Feature gates and component config

Every alpha and beta feature in Kubernetes is named, gated, and discoverable. This page covers the machinery and the conventions.

The machinery

staging/src/k8s.io/component-base/featuregate/ carries the feature-gate registry. Every component embeds the same MutableFeatureGate and registers its feature constants at boot:

const (
    // owner: @username
    // kep: https://kep.k8s.io/NNN
    MyFeature featuregate.Feature = "MyFeature"
)

var defaultKubernetesFeatureGates = map[featuregate.Feature]featuregate.FeatureSpec{
    MyFeature: {Default: false, PreRelease: featuregate.Alpha},
    ...
}

Three pre-release stages:

• Alpha — disabled by default; may break, may be removed.
• Beta — enabled by default (post-1.24); shape can still change with a deprecation cycle.
• GA (general availability) — gate is locked on; the constant remains for a few releases as a no-op for compatibility, then is removed.

The kube-feature catalog lives in pkg/features/kube_features.go. It is the single largest feature-gate file in the repo — by mid-2026 it has hundreds of gates spanning every subsystem.

The component-base catalog (staging/src/k8s.io/component-base/featuregate) carries gates that apply to all components. The apiserver module carries gates that apply only to apiserver-flavored binaries. Each binary's main composes the relevant catalogs at startup.

Querying a gate

In code:

import utilfeature "k8s.io/apiserver/pkg/util/feature"
import "k8s.io/kubernetes/pkg/features"

if utilfeature.DefaultFeatureGate.Enabled(features.MyFeature) {
    // new code path
}

The DefaultFeatureGate is process-global. Tests mutate it via featuregatetesting.SetFeatureGateDuringTest(t, gate, feature, true) (in staging/src/k8s.io/component-base/featuregate/testing/) to ensure each test runs with a known gate state.

Versioned feature gates

Recent work (the VersionedFeatureGate infrastructure) lets a gate's default and pre-release stage depend on the running emulation/binary version. Operators can run a 1.30 binary with --emulated-version=1.29 and have the gate state match 1.29's defaults. This makes downgrade paths safer.

Listing and changing gates

Every component accepts --feature-gates=Feature1=true,Feature2=false. Listing them:

kube-apiserver --help | grep -A 200 feature-gates

The schema is also discoverable at runtime:

kubectl get --raw /metrics | grep kubernetes_feature_enabled

Component config

Most components also accept a YAML config file alongside flags:

Component	Config kind	Schema
kube-apiserver	(no single config; structured --authentication-config, --authorization-config, --encryption-provider-config, --admission-control-config-file)	various
kube-controller-manager	KubeControllerManagerConfiguration (deprecated; flags only)	cmd/kube-controller-manager/app/options/
kube-scheduler	KubeSchedulerConfiguration	pkg/scheduler/apis/config/ (versioned in v1, v1beta3, …)
kubelet	KubeletConfiguration	pkg/kubelet/apis/config/ (versioned, supports drop-ins)
kube-proxy	KubeProxyConfiguration	pkg/proxy/apis/config/

The convention: declare an internal type, declare versioned external types, generate conversion. The component reads the config via the same scheme/codec as the apiserver does for API objects. This is why kubectl explain works on KubeletConfiguration.

Deprecation policy

• A flag is deprecated for at least 1 minor release, then hidden, then removed in a major release.
• A feature gate at GA stays in the registry for 1-2 minor releases (locked on) before being removed.
• A config field follows the same versioning as API objects: bump apiVersion, conversion preserves data.

Adding a feature gate

1. Pick a name. Must be camel-case, descriptive, unique.
2. Add a constant + spec to the appropriate catalog (pkg/features/kube_features.go for kube-apiserver/controller-manager/scheduler/kubelet, or a component-specific file).
3. Wrap your code path:

   if utilfeature.DefaultFeatureGate.Enabled(features.MyFeature) { ... }

4. Add tests that toggle the gate on and off.
5. File a KEP (kubernetes/enhancements) before the feature can graduate to beta.
6. At GA, lock the gate on and plan removal.

Key source files

File	Purpose
pkg/features/kube_features.go	The kube catalog of feature gates
staging/src/k8s.io/component-base/featuregate/feature_gate.go	Feature gate registry
staging/src/k8s.io/component-base/featuregate/testing/setter.go	Test helpers
staging/src/k8s.io/apiserver/pkg/features/kube_features.go	Apiserver-flavored gates
cmd/<binary>/app/options/feature_gate_options.go	Per-binary flag wiring