Cozystack’s etcd-operator v1alpha2 Makes Cluster Membership the API

Cozystack has picked up the etcd-operator project at a moment when Kubernetes platform teams are asking a harder question about operators: do they understand the protocol they manage, or do they only wrap a StatefulSet with nicer defaults?

In a June 29 CNCF project post, Andrey Kolkov and Andrei Kvapil said the etcd-operator project has been donated to Cozystack and published with a new etcd-operator.cozystack.io/v1alpha2 API. The important detail is not only the donation. It is the design change: the operator stops treating etcd members as interchangeable StatefulSet replicas and instead drives etcd’s own membership model.

That makes this release useful beyond the immediate Cozystack audience. etcd is the consistency layer behind many Kubernetes environments, and any automation that adds, removes, pauses, or migrates etcd members has to preserve quorum, identity, and recovery boundaries. Cozystack’s v1alpha2 design is a reminder that stateful Kubernetes automation is safest when the API exposes the workload’s real invariants rather than hiding them behind generic replica math.

What Cozystack is taking over

The CNCF post says the project develops an operator for deploying and maintaining etcd clusters on Kubernetes. Alongside the donation to Cozystack, the team published a from-scratch v1alpha2 implementation that supersedes the old etcd.aenix.io/v1alpha1 API while preserving the previous codebase in a v1alpha1 branch.

The new API shape

The operator’s concepts document describes two custom resources. EtcdCluster is the user-facing object that captures cluster-wide intent such as replica count, etcd version, storage size, and progress deadline. EtcdMember is created by the controller for each etcd member and owns that member’s Pod and PVC.

That split is the core contract. Users express cluster intent at the EtcdCluster layer, while the operator tracks each member’s identity and readiness separately. The documentation explicitly says there is no StatefulSet, because each Pod and PVC is reconciled independently.

Why the API group change matters

Changing the API group from etcd.aenix.io to etcd-operator.cozystack.io is more than a namespace rename. It marks a new operational model. The CNCF post says v1alpha2 replaces separate StatefulSet-style member management with per-member EtcdMember resources, replaces the free-form spec.options map with typed parameters, renames EtcdBackup to EtcdSnapshot, moves validation into CEL rules in the CRD, and switches the cluster Service to headless mode for stable per-member DNS names.

Why removing the StatefulSet is the interesting part

StatefulSets are a good Kubernetes primitive, but they are not a full model for every distributed system. etcd membership is governed by a consensus protocol. A new member is not just a Pod that appears with a higher ordinal. It must be added to the cluster, catch up, and only then become a voting member.

Protocol-aware membership

The Cozystack concepts document says scale-up adds a member as a learner first and promotes it only after it has caught up. Scale-down runs MemberRemove through a finalizer before the Pod is reclaimed. Pod restarts reuse the existing data directory and rejoin with the same etcd-side member ID. The CNCF post summarizes the same flow as direct use of etcd’s native Membership API: MemberAdd, MemberPromote, and MemberRemove.

That is a stronger abstraction than “replicas equals desired Pod count.” It encodes the fact that etcd membership changes are staged operations. The upstream etcd learner design explains why learners exist: a learner joins as a non-voting member, receives data from the leader, and can be promoted only when it is safe to count it toward quorum.

The operator becomes a state-machine coordinator

For platform teams, the practical takeaway is that the operator is coordinating two state machines at once: Kubernetes objects and etcd membership. If the controller only reasons about Pods, it can accidentally compress a multi-step consensus operation into a single reconciliation loop. Cozystack’s design is explicit about the sequence.

Identity is not an implementation detail

The concepts document also explains why generated member names and cluster tokens are used to avoid stale identity collisions across cluster incarnations. That may look like internal hygiene, but it is exactly the kind of detail that decides whether a stateful recovery path is safe after deletion, recreation, or PVC reuse.

What v1alpha2 adds for day-two operations

The CNCF post lists a broad set of capabilities in v1alpha2. Some are expected from a production operator, including bootstrap, scale-out, scale-in, TLS configuration, snapshots, and restore. Others are notable because they expose day-two operational hooks directly in the Kubernetes API.

Pause, resume, and scale integration

One of the most distinctive features is pause and resume with spec.replicas: 0 while preserving cluster and member identifiers. The post also says v1alpha2 exposes the /scale subresource, allowing Kubernetes scale-aware tooling such as kubectl scale and VerticalPodAutoscaler references to work against the operator’s custom resource instead of against an underlying StatefulSet.

Validation and disruption controls

Moving validation from a webhook to CEL rules in the CRD reduces one operational dependency: a validating webhook and its certificate chain are no longer required for that part of the contract. The CNCF post also says the operator automatically creates a PodDisruptionBudget to prevent drain operations from breaking quorum. Those controls matter because etcd failures often happen during routine maintenance, not only during obvious outages.

Snapshots, TLS, and scheduling knobs

The new operator supports snapshots to S3 or PVC through EtcdSnapshot, restore at initial bootstrap, independent TLS configuration for client and peer connections, a metrics port on 2381, and pass-through scheduling controls such as affinity and topology spread constraints. Those are practical features, but they also increase the need for clear ownership: storage teams, security teams, and platform teams must know which knobs are safe to expose and which are part of the operator’s own logic.

Migration is the first production gate

The most consequential part of the release may be migration. Cozystack’s migration documentation says the etcd-migrate tool adopts legacy v1alpha1 clusters in place. The existing etcd Pods and PVCs remain where they are; ownership, labels, member annotations, and custom resources change; the new operator takes over the live data plane.

No data movement does not mean no risk

The migration document states that no data is moved, no Pod is restarted, and quorum is never touched. It also says clients connecting by DNS name keep working, while warning that one Service changes shape from ClusterIP to headless and that consumers need to satisfy endpoint-compatibility requirements before applying the migration.

That distinction matters. A migration can be in-place and still require careful readiness checks. DNS behavior, endpoint consumers, operator scaling, and auth credentials are all part of the rollout surface. The documentation’s dry-run-first workflow is the right default because it forces teams to inspect the live cluster and planned v1alpha2 manifests before ownership changes are applied.

The real migration checklist

Before adopting v1alpha2, platform teams should confirm that both legacy and new controllers can be quieted, all etcd Pods are Ready, backups are available, client DNS behavior has been tested against the headless Service model, and credential changes are understood. They should also decide how they will test rollback, because an ownership migration that leaves the data plane running can still create confusion if two controllers or two API versions appear to own the same cluster.

How it compares with the official etcd-operator roadmap

The CNCF post compares Cozystack’s implementation with the official etcd-io operator roadmap. That roadmap includes creating three- or five-member clusters, setting etcd version and cluster size, understanding health, scaling, TLS and certificate renewal, upgrades, member recovery, backups, and restore from backup.

Where Cozystack is ahead

According to the CNCF post, Cozystack’s v1alpha2 implementation covers most roadmap items and adds capabilities driven by Cozystack and Kamaji multi-tenant use cases: scale to zero while preserving identity, tmpfs storage with replacement behavior, CEL validation, automatic quorum-aware disruption budgeting, the /scale subresource, pass-through scheduling, an in-place migration tool, and a kubectl-etcd plugin for day-two operations.

Where the limits remain

The same comparison says not every recovery path is finished. Recovering a single failed member with quorum is only partially implemented when PVCs are broken, multiple-member quorum-loss recovery is not implemented, and periodic backups are deliberately out of scope because recurring snapshots are expected to be driven by a standard CronJob. Those limits are not fatal, but they should shape production expectations.

What platform teams should test next

The release is a strong signal that stateful operators are becoming more protocol-aware. It is also still an alpha API. The production question is not whether v1alpha2 has a long feature list; it is whether the operator behaves predictably when clusters are upgraded, paused, migrated, drained, restored, and partially failed.

Test the unhappy paths first

A safe evaluation should start with failure drills: learner promotion delays, member removal during maintenance, node drain with the generated PodDisruptionBudget, lost tmpfs-backed members, PVC-backed members with crash-looping data directories, snapshot restore at bootstrap, and dry-run migration from the legacy API. These are the paths that reveal whether an operator is really modeling the workload or only automating the happy path.

Watch the API contract, not just the controller

The most durable part of this release may be its API stance. By making EtcdCluster and EtcdMember visible concepts, Cozystack gives operators a vocabulary for intent, membership identity, and convergence. That is a useful direction for cloud-native infrastructure: the API should show the invariants that matter when automation is under stress.

Sources: CNCF’s June 29, 2026 project post on etcd-operator and Cozystack, the Cozystack etcd-operator repository, Cozystack’s concepts and migration docs, the official etcd-operator roadmap, and the etcd learner design.

Featured image: rear of a rack at the NERSC data center by Derrick Coetzee via Wikimedia Commons, dedicated to the public domain under CC0 1.0; cropped, resized, and converted to WebP.