Skip to content

feat(featuregate): version-keyed feature gates with readiness-gated alpha opt-ins (#1275) - #1482

Open
leninmehedy wants to merge 1 commit into
mainfrom
01275-feature-gate-system
Open

leninmehedy wants to merge 1 commit into
mainfrom
01275-feature-gate-system

Conversation

@leninmehedy

@leninmehedy leninmehedy commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

What this introduces

Solo-provisioner's feature-gate system — a thin adapter over github.com/automa-saga/gatekit that lets a behaviour or contract change land behind an off-by-default gate instead of forcing every change to stay backward-compatible. This is Layer 1 of epic #1275 (gate + maturity).

This PR replaces the stacked PRs #1393 / #1396 / #1397 / #1437. Those evolved the --experimental opt-in three times as the design converged; reviewing them in sequence meant reading code that later PRs rewrote. This is the same work squashed into one clean diff against main, so --experimental appears only in its final form and there is no churn to wade through.

The model

A gate sits on one axis and carries two independent labels — keep them separate:

  • Axis — activation version (ActiveFrom): a coordination counter, not a per-feature counter. You don't bump it to add a feature — development gates all live at the current version. Only a compatibility gate ever advances it, so it may stay at 1 forever.
  • Label 1 — Maturity (Alpha / Beta / GA / Deprecated): how ready for users. Alpha needs an opt-in; Beta/GA ride the version axis.
  • Label 2 — Gate kind: how it rolls out, decided by one question — does turning it on require the whole fleet to flip together? No → development gate (lives at the current version, never bumps it — the common case). Yes → compatibility gate (new spec at current+1, bump the activation version later via finalize, Layer 2).

Maturity and gate kind are orthogonal. For an Alpha spec, Default is the readiness switch:

Default State Who can turn it on
false dormant (unfinished) nobody — safe home for incremental code
true ready (dogfood) --experimental or the env var

An opt-in enables an alpha only when it's ready. A dormant Alpha, Default: false feature is unreachable by any opt-in, yet gate.Enabled(f) still compiles and returns false — so a feature merges incrementally with no risk of exposing a half-done path. This adopts gatekit's native WithExperimental semantics (which honour Default) while keeping the opt-in command-scoped and sharing one gate between a command and its business code.

Deciding how to define a feature

I want to… ActiveFrom Maturity Default Who can turn it on
Merge unfinished code, reachable by no one current (1) Alpha false nobody
Let testers dogfood it current (1) Alpha true --experimental / env
Offer an opt-in beta for feedback current (1) Beta true --experimental / env
Ship to everyone (no fleet coordination) current (1) GA true everyone (on)
Make a breaking change safe across a rolling upgrade current + 1 Alpha→GA per stage after the activation-version bump (finalize, Layer 2)
Retire a superseded path later version Deprecated — contract step — delete the else branch

The full decision tree is in docs/dev/feature-gates.md.

Feature lifecycle — define and promote

Stage Spec in registry.go Who can turn it on How you get here
Not in main commented placeholder nobody code not merged yet
Dormant (unfinished) {ActiveFrom: 1, Default: false, Maturity: Alpha} nobody land the feature + its code; gate.Enabled(f) returns false
Ready (dogfood) {ActiveFrom: 1, Default: true, Maturity: Alpha} --experimental / env flip Default: false → true
GA (on for all) {ActiveFrom: 1, Default: true, Maturity: GA} everyone graduate Alpha → GA in place
Removed delete the spec + the else branch — contract step; mark any superseded model Deprecated

Example — define a dormant feature

features.go:

KubeClusterUpgrade gatekit.Feature = "KubeClusterUpgrade"

registry.go:

KubeClusterUpgrade: {
    Description: "Upgrade the Kubernetes cluster along the k8s/Cilium ladder (`kube cluster upgrade`).",
    Specs: gatekit.VersionedSpecs{
        {ActiveFrom: 1, Default: false, Maturity: gatekit.Alpha}, // dormant
    },
},

business code:

if gate.Enabled(featuregate.KubeClusterUpgrade) { // compiles; returns false while dormant
    // new path
}

Example — promote it

1. Ready to dogfood — flip Default:

- {ActiveFrom: 1, Default: false, Maturity: gatekit.Alpha},
+ {ActiveFrom: 1, Default: true,  Maturity: gatekit.Alpha},

Now kube cluster upgrade --experimental (or SOLO_PROVISIONER_ENABLE_KUBE_CLUSTER_UPGRADE=1) runs it.

2. GA — graduate the maturity in place:

- {ActiveFrom: 1, Default: true, Maturity: gatekit.Alpha},
+ {ActiveFrom: 1, Default: true, Maturity: gatekit.GA},

Now it's on for everyone; drop the command's --experimental gate.

For a true compatibility change that must flip the whole fleet together, add a new spec at the next activation version instead (a compat gate — Layer 2), rather than bumping an existing one.

What's in the PR

  • internal/featuregate/ — the catalog (registry.go), the two-axis gate (gate.go), readiness-aware env opt-ins (env.go), feature constants + CurrentActivationVersion + SupportWindow (features.go).
  • solo-provisioner feature list (cmd/cli/commands/feature/) — inspects the catalog (maturity, ActiveFrom, enabled, opt-in env var) with filters; read-only, runs unprivileged.
  • Command / flag gating (cmd/cli/commands/common/feature_gate.go) — GateFeature / GateFeatureFlag hide and label by maturity and refuse unless opted in; a persistent flag is gated on PersistentPreRunE so inheriting subcommands are covered. GateExperimental (bespoke) is removed.
  • Golden --help surface test — pins the visible command/flag surface so accidental exposure of an alpha can't merge silently.
  • kube cluster upgrade — moved onto the KubeClusterUpgrade alpha gate.
  • Lints (lint_test.go) — removal lint, baseline lint (vs testdata/baseline_registry.json), dev-gate-window warning. Pure-Go, run in ordinary CI.
  • docs/dev/feature-gates.md — the full dev guide.
  • gatekit v0.7.0 — go.mod / go.sum bump.

Opt-in surfaces (all readiness-aware)

  • --experimental — hidden, command-scoped flag; enables that command's ready feature. Preferred under sudo, which strips env vars.
  • SOLO_PROVISIONER_ENABLE_<FEATURE>=1 — per-feature env var; the exact name is printed by feature list.
  • Options.Overrides — internal raw seam for tests / programmatic forcing; bypasses readiness. Not an operator surface.

What to review

  • Opt-in semantics — requireFeatureEnabled + ExperimentalReady (gate.go, feature_gate.go): a ready alpha is enabled by an opt-in; a dormant one is refused with a distinct message.
  • One shared gate — the command installs the resolved gate on its context; business code reads it via featuregate.Gate(ctx) (not its own NewDefault()).
  • Env validation — envFeatureRequests keeps gatekit's strict unknown/malformed behaviour.
  • Lints — the baseline snapshot matches the catalog; regenerate only at release.

Testing

go test ./internal/featuregate/... ./cmd/cli/commands/... and task lint pass. These paths are pure-Go (no Linux-only deps), so they run in normal CI; the full suite still needs the UTM VM per repo rules.

Out of scope

…lpha opt-ins (#1275)

Introduce solo-provisioner's feature-gate system, a thin adapter over
github.com/automa-saga/gatekit that lets a behaviour or contract change land
behind an off-by-default gate instead of forcing every change to stay
backward-compatible. Layer 1 of epic #1275 (gate + maturity); Layer 2 (finalize,
state-backed activation axis, gated migrations) is out of scope.

Core model (internal/featuregate)
- A registry keys every gated behaviour by an activation version (ActiveFrom) and
  tags it with a maturity (Alpha/Beta/GA). CurrentActivationVersion is the in-force
  version (1, the GA floor); SupportWindow is the single source of the window W.
- Two axes: a feature is on when the last spec with ActiveFrom <= current resolves
  on; Alpha needs an operator opt-in, Beta/GA follow the version axis alone.

Readiness-gated opt-ins
- An operator opt-in (--experimental or SOLO_PROVISIONER_ENABLE_<FEATURE>) enables an
  alpha only when its spec is ready (Default:true). An unfinished Alpha,Default:false
  feature is dormant: no opt-in can turn it on, yet gate.Enabled(f) still compiles and
  returns false, so a feature can be merged incrementally with no risk of exposing a
  half-done path. --experimental is command-scoped and shares one gate with business
  code, so command availability and in-code behaviour are one decision.

CLI
- `solo-provisioner feature list` inspects the catalog (maturity, ActiveFrom, enabled,
  opt-in env var) with filters; read-only, runs unprivileged.
- common.GateFeature / GateFeatureFlag gate a command or a single flag by maturity: an
  alpha is hidden from --help and refused unless opted in; a persistent flag is gated
  on PersistentPreRunE so inheriting subcommands are covered too. A golden --help
  surface test pins the visible command/flag surface so accidental exposure can't merge.
- `kube cluster upgrade` moved onto the KubeClusterUpgrade alpha gate.

Lints (ordinary CI, pure-Go)
- Removal lint, baseline lint (against testdata/baseline_registry.json, regenerated
  only at release with -update-baseline), and a dev-gate-window warning.

Docs
- docs/dev/feature-gates.md: the model, defining and promoting a feature, the opt-in
  surfaces, development vs compatibility gates, and the lints.

Replaces the bespoke --experimental command gate (GateExperimental) and moves the
whole system onto gatekit v0.7.0.

Signed-off-by: Lenin Mehedy <lenin.mehedy@hashgraph.com>
@leninmehedy
leninmehedy force-pushed the 01275-feature-gate-system branch from 7619e92 to 095027e Compare November 21, 2026 01:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant