Runner CLI¶

runner is the program inside every CAPTF Job. The manager does not run Terraform or OpenTofu itself: it creates a Job, and the runner in that Job prepares the working directory, runs the module’s runtime step by step, and writes a small JSON result that the manager reads back when the Job ends. The binary is part of the manager image (/runner).

You never start the runner by hand in normal use. The manager builds the Job so that:

1. An init container, from the manager image, runs /runner copy /captf/bin/runner. This puts a copy of the binary on a shared volume, so the module’s own image does not need to contain it.
2. The main container, from the module’s source image, runs /captf/bin/runner run with the flags for one operation.

Run it yourself only to reproduce a failed Job in a container you control, or to read its flags while debugging a Job spec. See the image contract for the paths the runner expects and Choosing the Operation for when the manager picks each operation.

Synopsis¶

runner [global flags] copy <dest>
runner [global flags] run --op=<op> [flags]
runner [global flags] version
runner --version[=raw]

A bare runner prints its usage to standard error and exits with code 2.

Global flags¶

Every subcommand accepts these. They are the logging and version flags that every Kubernetes component registers, so they behave as they do in kube-apiserver or kubectl.

Invalid logging flags fail with exit code 2. For run, they also write a result (see Result error kinds).

copy¶

runner copy <dest>

Copies the running binary to <dest> and sets it executable (mode 0755). <dest> is the one required argument and takes no flags. The Job’s init container uses it to place the runner at /captf/bin/runner.

/runner copy /captf/bin/runner

It exits 0 on success, 1 when it cannot read or write a file, and 2 when it does not get exactly one argument.

run¶

runner run --op=<op> [flags]

Runs one operation in the Job’s main container. It takes no arguments, only flags. --op is required, and takes one of these:

Every operation runs init first, with -backend-config values from --backend-config and the lock timeout from --lock-timeout. When --force-unlock is set, force-unlock runs right after init.

The result goes to --result when the run ends, whether it succeeded or not.

Paths and environment¶

Runtime behavior¶

Approval and plan checks¶

See The Destructive-Plan Guard and Manual Plan Approval for how the manager sets these.

Restore and events¶

Example¶

A plan Job for a cluster, as the manager would start it, trimmed to the flags that matter:

/captf/bin/runner run \
  --op=plan \
  --image=registry.example.com/acme/cluster:v1.2.0 \
  --inputs-hash=<inputs-hash>

• <inputs-hash> is the hash the manager computed for the inputs it rendered into --config.

The manager supplies the rest through the defaults above and the mounts it builds. A run that finishes writes its result to the container’s termination log, which the manager reads from the Pod status.

version¶

runner version

Prints the program name and its build information, then exits 0. runner --version=raw prints the full build information instead.

runner version

Exit codes¶

Result error kinds¶

runner run always writes a result document, to --result (the termination log by default). A successful run has error: null. A failed run carries an error object with a kind, the step that failed and a bounded tail that summarizes the failure. The kind is one of: