Runner CLI
runner is the Job entrypoint the manager copies into every source image’s init container and runs as the main container’s command (copy, then run); it is not a tool operators invoke directly. See Image Contract for how the image and the runner fit together.
Global flags
Every subcommand inherits these (component-base logging and version flags, as every Kubernetes component registers them).
| Flag | Type | Default | Description |
|---|---|---|---|
--feature-gates | mapStringBool | A set of key=value pairs that describe feature gates for alpha/experimental features. Options are: AllAlpha=true|false (ALPHA - default=false) AllBeta=true|false (BETA - default=false) ContextualLogging=true|false (BETA - default=true) LoggingAlphaOptions=true|false (ALPHA - default=false) LoggingBetaOptions=true|false (BETA - default=true) | |
--log-flush-frequency | duration | 5s | Maximum number of seconds between log flushes |
--log-json-info-buffer-size | quantity | 0 | [Alpha] In JSON format with split output streams, the info messages can be buffered for a while to increase performance. The default value of zero bytes disables buffering. The size can be specified as number of bytes (512), multiples of 1000 (1K), multiples of 1024 (2Ki), or powers of those (3M, 4G, 5Mi, 6Gi). Enable the LoggingAlphaOptions feature gate to use this. |
--log-json-split-stream | bool | false | [Alpha] In JSON format, write error messages to stderr and info messages to stdout. The default is to write a single stream to stdout. Enable the LoggingAlphaOptions feature gate to use this. |
--log-text-info-buffer-size | quantity | 0 | [Alpha] In text format with split output streams, the info messages can be buffered for a while to increase performance. The default value of zero bytes disables buffering. The size can be specified as number of bytes (512), multiples of 1000 (1K), multiples of 1024 (2Ki), or powers of those (3M, 4G, 5Mi, 6Gi). Enable the LoggingAlphaOptions feature gate to use this. |
--log-text-split-stream | bool | false | [Alpha] In text format, write error messages to stderr and info messages to stdout. The default is to write a single stream to stdout. Enable the LoggingAlphaOptions feature gate to use this. |
--logging-format | string | text | Sets the log format. Permitted formats: “json” (gated by LoggingBetaOptions), “text”. |
-v, --v | Level | 0 | number for the log level verbosity |
--version | version | false | –version, –version=raw prints version information and quits; –version=vX.Y.Z… sets the reported version |
--vmodule | pattern=N,... | comma-separated list of pattern=N settings for file-filtered logging (only works for text log format) |
copy <dest>
Copy this binary to <dest> (init container).
run
Run one operation in the Job’s main container.
| Flag | Type | Default | Description |
|---|---|---|---|
--allow-deletes-hash | string | inputs hash approved for a destructive plan | |
--backend-config | stringArray | [] | init -backend-config value (repeatable) |
--bin | stringArray | [] | runtime command, one flag per element (default /captf/runtime) |
--config | string | /captf/config | directory holding the rendered root module and tfvars (the per-run Secret’s mount) |
--event-object | string | emit progress events about <apiVersion>/<kind>/<namespace>/<name>/<uid> (none when unset) | |
--expect-plan | string | apply: the approved plan hash; stop with error kind plan-changed unless the plan’s hash is this one | |
--force-unlock | string | stale lock to force-unlock after init | |
--guard-deletes | bool | false | apply: stop before a plan that deletes or replaces a resource unless –allow-deletes-hash is –inputs-hash |
--image | string | source image reference, echoed in the result | |
--inputs-hash | string | hash of the inputs the Job renders | |
--job-name | string | the Job the events relate to | |
--lock-timeout | duration | 5m0s | state lock timeout |
--module | string | /captf/module | module directory |
--op | string | operation: apply, destroy, refresh, drift, restore or plan | |
--providers | string | /captf/providers | provider mirror directory (optional) |
--restore-chunks | int | 0 | restore: the number of backup chunks under <config>/restore |
--restore-resources | int | 0 | restore: the backup’s managed resource count; state list must show one when it is not 0 |
--result | string | /dev/termination-log | where to write the result |
--stop-timeout | duration | 1m0s | time an interrupted step gets to stop before SIGKILL |
--workdir | string | /captf/work | writable work directory |
version
Print the version and exit.
Exit codes
| Code | Name | Meaning |
|---|---|---|
0 | ExitOK | Every step succeeded, or an apply’s plan had no changes to apply. |
1 | ExitFailure | A step failed, was interrupted, stopped before a destructive plan (blocked), or found its approved plan had changed; or preflight/prepare itself failed. max(runtime exit, 1) when the failing step’s own exit code is not already at least 1. |
2 | ExitUsage | Bad input: an –op Steps does not recognize, a bad flag, unexpected arguments, or invalid logging flags. |
Result error kinds
runner run always writes a result document (--result, the termination log by default); a failed run’s error.kind is one of:
| Kind | Meaning |
|---|---|
image-layout | The image does not follow the image contract (a Preflight check failed): the module or runtime is not where the contract puts it. |
step | A runtime step (init, plan, apply, …) failed, or the runner’s own setup (Prepare, a restore assembly) failed. |
interrupted | The run’s context was canceled (a drain, eviction or deletion) while a step was running; counts toward no retry backoff. |
blocked | A guarded apply stopped before a plan that deletes or replaces resources, without an approval for its inputs hash. It changed nothing and is not retried until the inputs or the approval change. |
plan-changed | An apply approved for one plan (–expect-plan) found its plan is now another. It changed nothing, carries the new plan, and waits for its approval. |