# StageSet Controller

> ordered, gated, multi-stage delivery of Flux sources (Git, OCI, Bucket, ExternalArtifact)

Project home: https://stageset.projects.metio.wtf/ — full text for LLMs: https://stageset.projects.metio.wtf/llms-full.txt

## Installation

- [Configuration reference](https://stageset.projects.metio.wtf/installation/configuration/): Every stageset-controller command-line flag and its default.
- [Install on Kubernetes](https://stageset.projects.metio.wtf/installation/kubernetes/): Prerequisites and the Helm install that get the controller onto a cluster.
- [Operations](https://stageset.projects.metio.wtf/installation/operations/): Metrics, alerts, events, and runbooks for running the controller day to day.
- [Production](https://stageset.projects.metio.wtf/installation/production/): High availability, security hardening, and on-prem and EKS HA reference setups.

## Tutorials

- [From Jsonnet to a gated rollout](https://stageset.projects.metio.wtf/tutorials/jsonnet-to-rollout/): Write Jsonnet manifests, render them with JaaS, and roll them out with StageSet — end to end.
- [Parameterizing a rollout](https://stageset.projects.metio.wtf/tutorials/parameters/): Two layers of parameters — JaaS TLAs/extVars at render time, StageSet postBuild substitution at delivery.
- [Progressive delivery](https://stageset.projects.metio.wtf/tutorials/progressive-delivery/): Gate a Flagger or Argo Rollouts promotion on a StageSet stage, and gate a StageSet stage on a Rollout.
- [Quickstart](https://stageset.projects.metio.wtf/tutorials/quickstart/): Install the controller and roll out your first StageSet in a few steps.
- [Stage sources — Git, OCI, Bucket](https://stageset.projects.metio.wtf/tutorials/flux-sources/): Point a stage straight at a Git/OCI/Bucket source, or render manifests first into an ExternalArtifact.

## Usage

- [Actions](https://stageset.projects.metio.wtf/usage/actions/): Typed pre, post, and on-failure steps — jobs, HTTP gates, waits, patches, deletes, transient applies.
- [Conflict policies](https://stageset.projects.metio.wtf/usage/conflict-policies/): Resolve immutable-field and ownership conflicts per resource.
- [Multi-cluster and tenancy](https://stageset.projects.metio.wtf/usage/multi-cluster/): Impersonation, watch scoping, single-tenant cluster-admin, and remote clusters.
- [Producer-aware sources](https://stageset.projects.metio.wtf/usage/producer-aware-sources/): Reference a producer like JaaS and let the controller find its ExternalArtifact.
- [Ready checks](https://stageset.projects.metio.wtf/usage/ready-checks/): Gate a stage on health with kstatus and CEL expressions.
- [Rollback](https://stageset.projects.metio.wtf/usage/rollback/): Restore the last good artifact revision when a run fails.
- [Secrets encryption (SOPS)](https://stageset.projects.metio.wtf/usage/encryption/): Decrypt SOPS-encrypted files in a stage's source before they are applied.
- [Stages and sources](https://stageset.projects.metio.wtf/usage/stages-and-sources/): The core — ordered stages applying Flux sources, with path, prune, patches, and substitution.
- [Update windows](https://stageset.projects.metio.wtf/usage/update-windows/): Allow or deny rollouts on a schedule, without pausing reconciliation.
- [Versioned migrations](https://stageset.projects.metio.wtf/usage/versioned-migrations/): Run migrations once, when the deployed version crosses a release boundary.

## CLI

- [stagesetctl build](https://stageset.projects.metio.wtf/cli/build/): Render a StageSet's manifests to stdout, exactly as the controller would.
- [stagesetctl diff](https://stageset.projects.metio.wtf/cli/diff/): Preview what a StageSet would change in the cluster — usable as a CI gate.
- [stagesetctl get](https://stageset.projects.metio.wtf/cli/get/): Print human-readable StageSet status, or list StageSets.
- [stagesetctl reconcile](https://stageset.projects.metio.wtf/cli/reconcile/): Force an out-of-band reconcile, optionally waiting for it to be handled.

## API reference

- [StageInventory](https://stageset.projects.metio.wtf/api/stageinventory/): The controller-managed inventory of objects each stage applied.
- [StageSet](https://stageset.projects.metio.wtf/api/stageset/): Every field of the StageSet resource — the one you author.

## Comparisons

- [StageSet vs Argo Rollouts](https://stageset.projects.metio.wtf/comparisons/argo-rollouts/): Different layers — staged multi-artifact delivery versus single-workload traffic shifting.
- [StageSet vs Flux kustomize-controller](https://stageset.projects.metio.wtf/comparisons/flux/): Intra-release stages and gates versus per-Kustomization ordering.
- [StageSet vs Helm](https://stageset.projects.metio.wtf/comparisons/helm/): How StageSet relates to Helm's templating and hook ordering.
- [StageSet vs jsonnet-controller](https://stageset.projects.metio.wtf/comparisons/jsonnet-controller/): A jsonnet-native Flux applier versus a renderer-agnostic staged-delivery layer.
- [StageSet vs Kustomize](https://stageset.projects.metio.wtf/comparisons/kustomize/): Why StageSet delivers what Kustomize only builds.
- [StageSet vs Tanka and kubecfg](https://stageset.projects.metio.wtf/comparisons/tanka-kubecfg/): Reconciled, gated delivery versus CLI-driven Jsonnet apply.

## Runbooks

- [ArtifactNotFound](https://stageset.projects.metio.wtf/runbooks/artifactnotfound/): The referenced ExternalArtifact could not be found (transient; the controller requeues).
- [Controller pod down](https://stageset.projects.metio.wtf/runbooks/controller-pod-down/): A stageset-controller pod has been NotReady for the alert window.
- [DependencyNotReady](https://stageset.projects.metio.wtf/runbooks/dependencynotready/): A StageSet named in spec.dependsOn is not yet Ready.
- [DowngradeRequiresMigration](https://stageset.projects.metio.wtf/runbooks/downgraderequiresmigration/): The desired version is below the deployed version and a migration boundary blocks the downgrade.
- [InvalidSpec](https://stageset.projects.metio.wtf/runbooks/invalidspec/): The StageSet spec is invalid; the Message names the offending field or action.
- [InvalidVersion](https://stageset.projects.metio.wtf/runbooks/invalidversion/): A version source or value could not be parsed as semver.
- [PreviousRevisionUnavailable](https://stageset.projects.metio.wtf/runbooks/previousrevisionunavailable/): rollbackOnFailure is set but the last-good revisions could not be restored.
- [Reconcile latency high](https://stageset.projects.metio.wtf/runbooks/reconcile-latency/): Reconcile p99 latency for the StageSet controller is above threshold.
- [ResolveFailed](https://stageset.projects.metio.wtf/runbooks/resolvefailed/): A source reference could not be resolved to a ready ExternalArtifact.
- [SourceNotReady](https://stageset.projects.metio.wtf/runbooks/sourcenotready/): The source exists but has not published a ready artifact yet (transient).
- [StageFailed](https://stageset.projects.metio.wtf/runbooks/stagefailed/): A stage failed to fetch, build, apply, verify, or run an action; the run halts there.
- [Stalled](https://stageset.projects.metio.wtf/runbooks/stalled/): The run cannot make progress and will not retry until the spec changes.
- [Succeeded](https://stageset.projects.metio.wtf/runbooks/succeeded/): All stages applied and verified the healthy steady state.
- [Suspended](https://stageset.projects.metio.wtf/runbooks/suspended/): Reconciliation is paused via spec.suspend.
- [UpdateDeferred](https://stageset.projects.metio.wtf/runbooks/updatedeferred/): A new revision is held by a closed update window.
- [Webhook cert renewal failing](https://stageset.projects.metio.wtf/runbooks/webhook-cert-renewal/): The self-signed admission webhook certificate is not being rotated.
- [Workqueue saturation](https://stageset.projects.metio.wtf/runbooks/workqueue-saturation/): The controller cannot drain its reconcile queue fast enough.

## Contributing

- [Building and testing](https://stageset.projects.metio.wtf/contributing/building/): Build the controller, run the test suite, and pass the static-analysis gate.
- [CI and releases](https://stageset.projects.metio.wtf/contributing/ci-and-release/): The pull-request gates and the automated calendar-based release process.