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

This content is for the v0.1 version. Switch to the latest version for up-to-date documentation.

Use deploy controls when the ordinary kix deploy <cluster> workflow needs a safer preview, different wait limits, orphan cleanup, or machine-readable output. 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:

Run in kix-examples/

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

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

  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-4d9xmbm6rcc2> created
Activation/how-to-application-4d9xmbm6rcc2> ready

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

For an existing deployment, the preview uses server-side dry-run, so admission checks, permissions, and field conflicts are still evaluated. It does not ask for confirmation and does not create an activation record.

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:

Run in 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:

Run in 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:

Run in kix-examples/

❱ kix deploy how-to-application --prune

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

Run in 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 is colored for an interactive terminal and falls back to line-oriented output when stdout is not a terminal. Select line explicitly for stable CI logs:

Run in kix-examples/

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

Use json for newline-delimited JSON events that another program will read:

Run in kix-examples/

❱ kix deploy how-to-application --dry-run --log-format json > deploy.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:

Run in 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 server-side dry-run of a cluster’s first deployment can report that a Namespace or Kix CRD does not exist. The previewed prerequisite is not persisted for a later resource to use. Run kix check for validation and kix diff to review the initial change set before the first deploy.