Deploy with dry-run, timeouts, pruning, and log/TUI output modes

Use deploy controls when the ordinary kix deploy <cluster> workflow needs a safer preview, different wait limits, orphan cleanup, or structured event logs. This guide assumes Kix can reach the target Kubernetes context.

Preview the apply

Add --dry-run to send the apply and delete requests to the Kubernetes API server without persisting them:

kix-examples/ live capture

❱ kix deploy how-to-application --dry-run --timeout 5m --prune --log-format line

Show outputHide output · 25 lines

Building cluster 'how-to-application'...
Cluster how-to-application: 16 manifests
Connecting to cluster...
Active activation: how-to-application-gb5d6ry45b5l (gb5d6ry4...)

  how-to-app
    ~ preview 1.0.0 (1 changed, 3 dep-affected)

  Plan: 1 updated, 2 unchanged
  Resources: 1 real content, 3 dep-affected

Dry run. No changes will be applied.
plan: 16 nodes
ConfigMap/preview@how-to-app> configured
ConfigMap/preview@how-to-app> ready
Deployment/preview@how-to-app> configured
Deployment/preview@how-to-app> ready
Service/preview@how-to-app> configured
Service/preview@how-to-app> ready
PackageInstance/preview@how-to-app> configured
PackageInstance/preview@how-to-app> ready
Activation/how-to-application-bhxsvmcwa9ij> created
Activation/how-to-application-bhxsvmcwa9ij> ready

Dry run complete: 1 created, 4 configured, 11 unchanged, 0 failed

kix deploy --dry-run runs kix plan with the same planning flags, so admission checks, permissions, and field conflicts are evaluated, and every refused write is listed. It does not ask for confirmation and does not create an activation record. It exits 2 when the deploy would change something and 3 when the deploy would stop.

A deploy without --dry-run runs the same dry run before it asks for confirmation. Under the default --on-error stop, a plan with a refused write stops the deploy before anything is applied.

Remove --dry-run when the plan is ready to apply. Keep --prune only when the orphaned resources shown in the plan should be deleted.

Set the readiness timeout

--timeout controls how long Kix waits for each resource to become ready. It accepts minutes, seconds, or a bare number of seconds:

kix-examples/

❱ kix deploy how-to-application --timeout 10m

❱ kix deploy how-to-application --timeout 300s

The default is three minutes. Increase it for resources whose normal startup takes longer, such as a database restore or a large image pull.

Kix also stops a deploy after ten minutes with no progress. To change that stall limit for one run, set KIX_STALL_TIMEOUT in seconds:

kix-examples/

❱ KIX_STALL_TIMEOUT=900 kix deploy how-to-application

Progress and readiness are separate: a resource can take longer than the stall limit without triggering it when its readiness checks continue to report activity.

Choose when to prune

By default, Kix reports resources that belonged to the previous activation but keeps them. Use --prune to delete those orphans after the new resources have been applied:

kix-examples/

❱ kix deploy how-to-application --prune

Pruning never deletes a Namespace or CustomResourceDefinition. It also keeps an orphan that another Kix cluster in the same Kubernetes cluster still deploys. The plan lists both as kept.

Use --prune-mode no to prevent deletion even if a surrounding script also passes --prune:

kix-examples/

❱ kix deploy how-to-application --prune --prune-mode no

Review stateful removals carefully. Kix requires a separate migration acknowledgement when a plan replaces a stateful resource in the same logical slot. This safeguard does not apply when a stateful resource is removed without a replacement. Kix treats it as an ordinary orphan, and --prune deletes it along with its PersistentVolumeClaim. The plan lists each orphan as “will be deleted” before asking for confirmation. The --yes flag skips that prompt.

Choose terminal or CI output

The default pretty format falls back to line-oriented output when stdin is not a terminal. Colour is a separate decision and is disabled when stdout is not a terminal. Select line explicitly for stable CI logs:

kix-examples/

❱ kix deploy how-to-application --log-format line

Use json when another program needs the deploy events. The plan is still plain text on the same stream, so filter valid JSON lines before treating the result as NDJSON. The last event is a summary object with the counts and succeeded:

kix-examples/

❱ kix deploy how-to-application --yes --log-format json | jq -R -c 'fromjson? // empty' > deploy-events.ndjson

For a live dependency view in an interactive terminal, use the TUI. This example groups resources by namespace and caps the live viewport at 20 rows:

kix-examples/

❱ kix deploy how-to-application --tui --group-by-ns --fold-height 20

On a non-interactive terminal, --tui falls back to line-oriented output. These output options change presentation only; they do not change deployment order.

Troubleshoot a first-deploy preview

A dry run persists nothing, so it cannot check an object whose Namespace or CRD the same deploy creates. The plan lists those objects under “Not checked by the dry run”, with their changes from comparing builds, and most of a cluster’s first deployment is in that list. Run kix check for validation before the first deploy, and review the listed objects in the plan.

Reference

See kix deploy for all deploy flags, defaults, and exit behavior.