Skip to content
kix /docs
Install the CLI

How-to guide Operate a cluster

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

Section titled “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 · 26 lines 
Building cluster 'how-to-application'...
Cluster how-to-application: 17 manifests
Connecting to cluster...
Active activation: how-to-application-6rhi3wpk9iml (6rhi3wpk...)

  how-to-app
    ~ preview 1.0.0 (1 changed, 3 dep-affected)
      ~ ConfigMap/preview@how-to-app
          ~ $.data.index.html:
              --- old
              +++ new
              @@ -1 +1 @@
              -Hello from preview
              +Preview deploy controls
      ~ Deployment/preview@how-to-app (via dependency)
      ~ Service/preview@how-to-app (via dependency)
      ~ PackageInstance/preview@how-to-app (via dependency)

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

Not checked by any preview: whether Pods start, pull their images, and pass their probes.

Objects: 6 written, 0 deleted (sha256:b53211e72c52af5821fdd776fdbc47e4831bda22958d75fc3012a70b8ee00331)
  ↻ 1 written again unchanged: a build this cluster ran holds the same file
(exit code: 2)

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

Section titled “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.

Some failures do not wait for the timeout. A pod in ImagePullBackOff or CrashLoopBackOff, a Job that has used up its retries, or a custom resource whose controller rejects it (a Cilium policy with Valid=False) fails the resource as soon as Kix sees the state, with the controller’s message. The owning package declares which states mean that; see Declare readiness for custom resources.

Kix also checks objects it does not change. Before it deploys an object, it reads every unchanged object that the object depends on, directly or through other unchanged objects, and waits for it to be ready under the same timeout. An unchanged Deployment that is restarting is waited for like a changed one. An unchanged object that an earlier deploy or a change on the cluster left broken fails the deploy on that object, with its own status, and the error says that nothing in this deploy changed it. Fix the object and deploy again, or deploy with --on-error continue to deploy the objects that do not depend on it. Unchanged objects that nothing in the deploy depends on are not read, and a deploy with no changes reads nothing.

Every failure also says how many objects Kix did not deploy because they depend on the failed one.

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. Kix tells you about such a wait anyway: after 10 seconds it prints a waiting: line with the resource, what its last readiness check said, and how much of the readiness timeout has passed, and repeats it at 30, 60, and 120 seconds and then every minute.

Choose when to prune

Section titled “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 any Kix-owned resources that left the build (including a PersistentVolumeClaim declared directly as a Kix resource, though not claims that Kubernetes created from a StatefulSet’s volumeClaimTemplates). The plan lists each orphan as “will be deleted” before asking for confirmation. The --yes flag skips that prompt.

Choose terminal or CI output

Section titled “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. Stdout then holds only the events, one JSON object per line; the plan and the other text go to stderr. Every event carries schema_version, and the last is a summary object with the counts and succeeded:

kix-examples/ 
❱ kix deploy how-to-application --yes --log-format json > 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

Section titled “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.