snapshot

kix snapshot saves what Kix currently manages in a cluster to a directory. The directory is the old side of a later kix diff --from, so a build can be compared with the cluster without cluster access.

This page is hand-maintained. Check cli/kix-cli/src/cli.rs and cli/kix-cli/src/commands/snapshot.rs when in doubt.

Subcommands

Subcommand	Purpose
save <CLUSTER> <DIR>	Fetch the named Kix cluster’s resources from the selected Kubernetes context and write them to <DIR>

kix snapshot save <CLUSTER> <DIR>

kix snapshot save <CLUSTER> <DIR> [--context <CONTEXT>] [--quiet]

Argument or flag	Meaning
<CLUSTER>	Kix cluster whose resources to save. Kix finds them through the cluster’s Activation records, so the name is the one those records carry in their kix.run/cluster label. The command fails when the cluster has no records while other Kix clusters do.
<DIR>	Directory to write. Kix stages the complete snapshot beside this path before replacing an existing directory. Paths containing .. are rejected.
--context <CONTEXT>	Kubeconfig context to read. Defaults to the current context.
-q, --quiet	Suppress the progress lines on stderr.

The command reads the cluster only. It does not evaluate a flake, so --flake and --no-cache have no effect.

What is saved

The save lists every resource carrying the Kix managed-by label, keeps the ones Kix applied for the named cluster, and writes each one as the fields Kix applied. A resource belongs to the cluster when its kix.run/activations annotation names one of that cluster’s Activation records. Resources of other Kix clusters on the same Kubernetes cluster are left out, and the save prints how many it skipped per cluster. A resource both clusters deploy is saved. Kubernetes records which tool set each field through server-side apply, and Kix reads that record to keep only its own fields. Server defaults, status, and fields written by controllers or by kubectl are left out.

Included:

• every namespaced and cluster-scoped resource Kix applied for the cluster, including PackageInstance records and the cluster’s Activation records;
• the Kix annotations that identify each resource’s package, identity hash, and dependencies.

Excluded:

• status and anything a controller wrote;
• server-side defaults Kix never sent;
• the bookkeeping annotations Kix writes after applying (activations and applied hash), which change on every deploy without being a content change;
• resources that only carry the label because a controller copied it, such as Pods and EndpointSlices.

A resource Kix manages can be a Secret. Its data is part of what Kix applied, so it is part of the snapshot. Store snapshots where you would store the rendered manifests.

Directory layout

<DIR>/
  README.md                       # timestamp, cluster, context, resource count
  <namespace>/<name>-<kind>.yaml  # one file per namespaced resource
  _cluster/<name>-<kind>.yaml     # one file per cluster-scoped resource

Kinds are lower-cased in file names, for example how-to-app/production-deployment.yaml.

Exit status

Code	Meaning
0	Snapshot written
1	The cluster could not be reached, API discovery failed, a listing failed, or the named cluster has no Activation records while other Kix clusters do

Using a snapshot

Pass the directory to kix diff:

❱ kix diff <CLUSTER> --from <DIR>

That comparison runs without Kubernetes access. Save a fresh snapshot after each deploy; a snapshot describes the cluster at the moment it was taken.

Reference

See kix diff for the other old-side sources and the output formats.

Use it in a task

See Use snapshots for offline or CI diffs for the day-to-day workflow, or Save and diff snapshots for offline CI to run the comparison in a pipeline without cluster credentials.