Feature gates

etcd uses a Kubernetes-style feature-gate registry to roll out new behavior in alpha → beta → GA phases.

Where it lives

• Library: pkg/featuregate/feature_gate.go (the MutableFeatureGate implementation).
• Server registry: server/features/etcd_features.go lists every server-side gate with its default and stability level.
• Flag wiring: server/embed/config.go::ServerFeatureGateFlagName and the --feature-gates=Foo=true,Bar=false parsing.

Concepts

• A gate name is a stable identifier (e.g. StopGRPCServiceOnDefrag).
• Stability: Alpha (off by default, no compatibility guarantees), Beta (on by default), GA (always on; flag reserved for two releases then removed).
• Default: per-stability default unless explicitly overridden.
• PreRelease lifetime: gates progress through stability levels with each minor release.

Setting gates

Operators provide them via the flag:

etcd --feature-gates=DistributedTracing=true,InitialCorruptCheck=true

Internal code consults the gate via *featuregate.FeatureGate.Enabled(name). Most gates are checked at boot, so toggling them requires a restart.

Why a registry instead of --experimental-* flags

The --experimental-* flag pattern made it hard to deprecate features cleanly: removing the flag was a breaking change. With the registry, a gate can be promoted to GA, kept as a no-op flag for two releases, and then removed — operators get a clear deprecation window.

This was one of the deliberate v3.6 cleanups; see pkg/featuregate/ and the deprecation policy in Documentation/contributor-guide/.

Examples currently in tree

Browse server/features/etcd_features.go for the canonical list. At wiki time it includes gates like:

• StopGRPCServiceOnDefrag — temporarily stop the gRPC server while bbolt defragmentation is running.
• InitialCorruptCheck — run a peer-hash comparison at startup.
• LeaseCheckpoint, LeaseCheckpointPersist — durably persist remaining lease TTL.
• DistributedTracing — enables OTLP span emission.

(Counts and exact names move with the source; the file above is the source of truth.)

Cross-references

• reference/configuration — how --feature-gates interacts with other flags.
• pkg/ — the registry implementation.