Configuration reference
The controller is configured entirely through command-line flags, grouped below by subsystem. When deployed via the Helm chart you never pass these directly — the chart sets them from your values and its own defaults. For the values that drive each flag, see Helm chart values . For the values worth tuning and the reasoning behind each, see Production ; for metrics and runbooks, Operations .
The flag tables below are generated from the binary’s own FlagSet, so they track the controller’s runtime contract rather than a hand-maintained copy.
Manager and leader election
| Flag | Default | Description |
|---|---|---|
--health-probe-bind-address | :8081 | The address the probe endpoint binds to. |
--leader-elect | false | Enable leader election. |
The leader-election lease name is fixed at stageset-controller.stages.metio.wtf
and is created in the namespace the controller pod runs in.
Watch scope
| Flag | Default | Description |
|---|---|---|
--watch-namespaces | (empty) | Comma-separated list of namespaces this controller watches. Empty (the default) means cluster-wide. When set, the manager's cache only observes StageSets and sources in these namespaces — the multi-tenant controller-instances pattern. Falls back to STAGESET_WATCH_NAMESPACES env when the flag is empty. |
Environment variable: STAGESET_WATCH_NAMESPACES — comma-separated
namespace list. When --watch-namespaces is non-empty the flag takes
precedence. When restricted, the chart pivots RBAC to per-namespace
RoleBindings instead of a cluster-wide ClusterRoleBinding.
Reconciliation defaults
| Flag | Default | Description |
|---|---|---|
--allowed-action-hosts | (empty) | Host glob allowed for http actions; repeatable. Loopback and link-local ranges are always denied unless explicitly listed. |
--default-interval | 10m0s | Reconcile cadence for StageSets that omit spec.interval. |
--image-verification-insecure-registry | (empty) | Registry host[:port] whose images are pulled over plain HTTP during image verification (an on-prem/in-cluster registry without TLS); repeatable. Only affects verification bundle fetches, not the kubelet's image pulls. |
--image-verification-trusted-root | (empty) | Path to an offline Sigstore trusted-root JSON for image verification (air-gapped clusters). Empty fetches the public Sigstore root over TUF on first use. |
--inventory-shard-cap | 5000 | Maximum entries per StageInventory shard. |
--max-teardown-wait | 1h0m0s | How long a deleting StageSet's finalizer holds while reverse-order teardown keeps failing before it is force-dropped. Past this bound the controller emits a Warning TeardownForced event and removes the finalizer anyway, so a permanently-unreachable target cannot wedge the StageSet in Terminating — at the cost of orphaning objects the failing stage could not delete. |
--no-cross-namespace-refs | false | Deny cross-namespace sourceRef and dependsOn references. |
--object-level-kms | false | Decrypt SOPS cloud KMS keys with each StageSet's serviceAccountName federated to a cloud identity, instead of the controller's ambient credentials. The tenant ServiceAccount must be federated (IRSA / Workload Identity) to a cloud identity granted KMS decrypt. Off by default (ambient credentials). |
--require-image-verification | false | Deny-by-default for the image-verification gate: hold a stage whose rendered container images match no ImageVerificationPolicy, instead of applying them ungoverned. When off, only images a policy governs are verified (an ungoverned image applies unchanged). Off by default; strongly recommended in production once policies cover every registry you deploy from. |
--require-pinned-migration-sources | false | Require a spec.migrationsSourceRef source to be pinned to an immutable revision (OCIRepository spec.ref.digest or GitRepository spec.ref.commit) before its destructive migration ladder runs, so a tag/branch overwrite can't auto-roll new destructive content. When off, a mutable-pinned source still runs but emits a Warning event. Off by default; recommended in production. |
--require-verified-migration-sources | false | Require a spec.migrationsSourceRef source to be signature-verified (status.conditions[SourceVerified]=True from the source's spec.verify cosign/notation config) before its destructive migration ladder runs. A source whose verification FAILED is always refused; this flag additionally refuses sources that configure no verification at all. Off by default; strongly recommended in production. |
Rollback store — filesystem
The rollback store preserves a copy of each stage’s last-applied artifact so
that a rollback can re-apply the previous revision without re-fetching from the
producer. The filesystem backend is appropriate for single-replica deployments or
multi-replica deployments backed by an RWX volume.
--rollback-store-path and --rollback-store-s3-endpoint are mutually
exclusive. Both empty disables the store; rollback falls back to re-fetching the
producer artifact.
| Flag | Default | Description |
|---|---|---|
--rollback-store-path | (empty) | Filesystem directory (e.g. an RWX PVC mount) for the optional rollback store. Use an RWX volume for HA replicas. Mutually exclusive with the S3 store. The store holds rendered output that can include decrypted Secret data, and this backend adds no encryption — use an encrypted volume (or the S3 store with --rollback-store-s3-sse) when secrets are in play. |
The file store writes rendered output — including Secret data — in the clear. The volume must provide encryption at rest (encrypted StorageClass, LUKS, or cloud-disk encryption).
Rollback store — S3
Active when --rollback-store-s3-endpoint and --rollback-store-s3-bucket are
both non-empty.
| Flag | Default | Description |
|---|---|---|
--rollback-store-s3-access-key | (empty) | Access key; empty engages minio-go's IAM/IRSA discovery chain. |
--rollback-store-s3-anonymous | false | Use anonymous (unsigned) requests for the rollback store. |
--rollback-store-s3-bucket | (empty) | Bucket for the rollback store. |
--rollback-store-s3-endpoint | (empty) | S3-compatible endpoint for the optional rollback store (host:port). Empty disables the store; rollback falls back to re-fetching the producer artifact. |
--rollback-store-s3-prefix | (empty) | Key prefix within the rollback-store bucket. |
--rollback-store-s3-region | (empty) | Region for the rollback-store bucket. |
--rollback-store-s3-secret-key | (empty) | Secret key for the rollback store. |
--rollback-store-s3-session-token | (empty) | Optional session token for the rollback store. |
--rollback-store-s3-sse | s3 | Server-side encryption at rest for stored objects: none, s3 (SSE-S3), or kms (SSE-KMS). The store holds rendered Secret data, so encryption is on by default; set none only for a bucket whose backend cannot honor an SSE header. |
--rollback-store-s3-sse-kms-key | (empty) | KMS key ARN/ID for --rollback-store-s3-sse=kms; empty uses the bucket's default KMS key. |
--rollback-store-s3-use-ssl | true | Use TLS for the rollback-store endpoint. |
Metrics and health
| Flag | Default | Description |
|---|---|---|
--metrics-bind-address | :8080 | The address the metric endpoint binds to. |
The metrics endpoint exposes standard controller_runtime_* and workqueue_*
series alongside the custom stageset_* metrics documented in
Operations
.
Tracing
The controller exports OpenTelemetry traces over OTLP gRPC when
--tracing-endpoint is set; it is off by default. See
Observability
for the collector wiring.
| Flag | Default | Description |
|---|---|---|
--tracing-endpoint | (empty) | OTLP gRPC collector host:port (e.g. otel-collector.observability.svc:4317). Empty disables tracing entirely. |
--tracing-insecure | false | Skip TLS when dialing the OTLP collector. Use only for in-cluster collectors that don't terminate TLS themselves. |
--tracing-sample-ratio | 1 | TraceID-ratio sampling (0.0..1.0). 1.0 samples every trace. |
Webhook and TLS provisioning
The validating admission webhook for StageSet is enabled by default. Two TLS
provisioning modes are supported: cert-manager (the chart renders a
Certificate CR and mounts the issued cert from a Secret) and self-signed
(the controller generates a CA and serving cert in-pod and patches the
ValidatingWebhookConfiguration caBundle).
| Flag | Default | Description |
|---|---|---|
--enable-webhook | true | Enable the validating admission webhook for StageSet. |
--webhook-cert-dir | /tmp/k8s-webhook-server/serving-certs | Directory holding the webhook tls.crt and tls.key. |
--webhook-cert-mode | cert-manager | How webhook TLS is provisioned: cert-manager (the chart renders a Certificate; cert mounted from a Secret), or self-signed (the controller generates a CA + serving cert in-pod and patches the ValidatingWebhookConfiguration caBundle). |
--webhook-cert-validity | 8760h0m0s | Validity of the self-signed serving cert; the renewer rotates at validity/3. Operators wanting short-lived material should use cert-manager. |
--webhook-port | 9443 | Port the validating webhook server binds to. |
--webhook-service-name | stageset-controller-webhook | Service the webhook is reachable through; builds cert SANs for self-signed mode. |
--webhook-service-namespace | (empty) | Namespace of the webhook Service; empty falls back to the in-cluster ServiceAccount namespace. |
--webhook-validating-config-name | (empty) | Name of the ValidatingWebhookConfiguration whose caBundle to patch. Required for self-signed mode. |
Gate endpoint
The gate endpoint exposes a read-only HTTP API for Flagger canary stage-gates.
GET /gate/{namespace}/{stageset}/{stage} returns 200 when the named stage is
ready to advance and 503 otherwise.
| Flag | Default | Description |
|---|---|---|
--gate-bind-address | :8082 | Address for the read-only Flagger stage-gate endpoint (GET /gate/{namespace}/{stageset}/{stage}). Empty disables it. |
Logging
The controller logs through log/slog. Set the verbosity with --log-level
(debug, info, warn, or error, default info) and the encoding with
--log-format (json or text, default json); controller-runtime’s own
logs flow through the same handler via a logr bridge. See
Logging
for reading and filtering the output.
| Flag | Default | Description |
|---|---|---|
--log-format | json | Log output format: json or text. |
--log-level | info | Log level: debug, info, warn, or error. |