How-to guide Operate a cluster

Use snapshots for offline or CI diffs

Use a snapshot when you want kix diff without a connection to the cluster: on a laptop off the VPN, in a CI job that holds no cluster credentials, or when several people need the same old side for a review.

kix snapshot save writes the fields Kix applied to each resource of the named cluster. kix diff --from then compares a build with that directory the same way it compares with the live cluster, so the two reports match.

This guide assumes the cluster has been deployed at least once and that you can reach it when saving. The examples use the how-to-application cluster from kix-examples.

Save a snapshot after deploying

Take the snapshot right after a successful deploy, while the cluster and the source agree:

kix-examples/

❱ kix snapshot save how-to-application ./snapshots/how-to-application
Discovering API resources...
Fetching managed resources (60 resource types)...
Fetched 17 resources
Saved 17 resources to ./snapshots/how-to-application/

Pass --context when the cluster is not the current kubectl context. The command reports how many resources it fetched and wrote. The directory holds one YAML file per resource, grouped by namespace, plus a README.md with the timestamp, cluster and context. Resources of other Kix clusters deployed to the same Kubernetes cluster are left out.

Diff a build against the snapshot

Compare the current source with the snapshot. No cluster access is needed:

kix-examples/

❱ kix diff how-to-application --from ./snapshots/how-to-application
4 packages: 4 unchanged, 0 changed, 0 added, 0 removed
No differences found.

Drift not checked: the deployed build is not on this machine, so changes are not labelled as the commit's or as drift.

Straight after the save this reports no differences and exits with status 0.

Preview a change

Edit the source, then run the same command again. Changing the production message in the example cluster gives a report like this:

kix-examples/

❱ kix diff how-to-application --from ./snapshots/how-to-application
4 packages: 3 unchanged, 1 changed, 0 added, 0 removed

  how-to-app
    ~ production 1.0.0 (1 changed, 4 dep-affected)
      ~ ConfigMap/production@how-to-app
          ~ $.data.index.html:
              --- old
              +++ new
              @@ -1 +1 @@
              -Hello from production
              +Updated production message
      ~ Deployment/production@how-to-app (via dependency)
      ~ Job/production-health@how-to-app (via dependency)
      ~ PackageInstance/production@how-to-app (via dependency)
      ~ Service/production@how-to-app (via dependency)

  Activation: how-to-application-6rhi3wpk9iml -> how-to-application-vwynqsd34657


Drift not checked: the deployed build is not on this machine, so changes are not labelled as the commit's or as drift.

Not checked: admission webhooks, field ownership conflicts, and what the deploy itself refuses. `kix plan` checks them with a server-side dry run.
(exit code: 2)

The ConfigMap is the resource you edited. The four resources marked “via dependency” have no content change of their own; their identity hash moves because they depend on the ConfigMap, and Kix will re-stamp them on the next deploy. The command exits with status 2 whenever it finds a difference.

Keep the snapshot current

A snapshot describes the cluster at the moment it was taken. Once you deploy, save again, or the next diff will keep showing the change you already shipped. A simple rule: every command that deploys is followed by a save of the same context.

When you can reach the cluster, run kix diff how-to-application without --from. It reads the same fields from the live resources and needs no saved copy.

Compare with a previous build instead

A bundled build works as the old side too. Package the cluster from the old revision with kix bundle, build a second bundle from the current revision, and compare the two:

kix-examples/

❱ kix bundle how-to-application before.kixbundle

❱ kix bundle how-to-application after.kixbundle

❱ kix diff how-to-application --bundle after.kixbundle --from-bundle before.kixbundle

You can also export the old revision with kix export --for audit --out ./before and pass --from ./before. Both approaches compare two builds of the source without contacting a cluster. Use them to check what a branch changes relative to main.

Troubleshooting

Every resource shows as removed or cluster-level. The directory was written by kix export in its default mode, which strips the annotations the comparison needs. Save a snapshot instead, or export with --for audit.

The diff reports changes you did not make. The snapshot is older than the last deploy. Save a fresh one and compare again.