Preview changes with `kix diff`

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

Use kix diff to preview how the rendered cluster differs from the resources currently running in Kubernetes. The command reads live state but does not apply changes.

Compare desired and live resources

Start from a cluster that matches what is deployed. Kix compares only the fields it applied, so an unchanged cluster reports nothing and exits 0:

Run in kix-examples/

❱ kix diff how-to-application
⠁ Fetching live cluster state...                                                Discovering API resources...
Fetching managed resources (60 resource types)...
Fetched 16 resources across 60 resource types
3 packages: 3 unchanged, 0 changed, 0 added, 0 removed
No differences found.

Now change the production message in the cluster definition and run the same command:

Run in kix-examples/

❱ kix diff how-to-application
⠁ Fetching live cluster state...                                                Discovering API resources...
Fetching managed resources (60 resource types)...
Fetched 16 resources across 60 resource types
3 packages: 2 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-aq1zdgf9gsnb -> how-to-application-h9nqwqrpw48l
(exit code: 2)

The report names the ConfigMap you edited and shows the changed value. The resources marked “via dependency” have no content change of their own. Their identity hash moves because they depend on the ConfigMap, so Kix will re-stamp them on the next deploy.

Read the diff

The report is grouped by package, and each line tells you something different:

A package marked added or removed appears on only one side.
A resource marked ~ has a content change, shown as a diff of the fields that differ.
A resource marked “via dependency” has no content change of its own. Only its identity hash moved, because something it depends on changed.
A cluster-level group collects resources that belong to no package, such as namespaces and custom resource definitions.
An activation line names the deployment record this change would create.

Read the packages you edited first, then the dependent resources, which tell you how far the rollout reaches. A non-empty diff exits with status 2, which lets CI tell a change from a clean comparison.

Select the flake and context

By default, Kix evaluates the current directory and reads the current kubectl context. Set either input explicitly when needed:

❱ kix diff how-to-application --flake ./infrastructure --context kind-kix-demo

The flake supplies the desired manifests. The Kubernetes context supplies the live manifests being compared.

Produce review-friendly output

Select Markdown output when attaching the result to a pull request or change review:

Run in kix-examples/

❱ kix diff how-to-application --output markdown Show output

⠁ Fetching live cluster state...                                                Discovering API resources...
Fetching managed resources (60 resource types)...
Fetched 16 resources across 60 resource types
### kix diff

**Plan:** 1 updated, 0 added, 0 removed, 2 unchanged
**Resources:** 1 with real content changes, 4 dep-affected (hash bump only)

#### Changed packages

<details>
<summary><code>how-to-app/production</code> 1.0.0 (1 changed, 4 dep-affected)</summary>

**Modified resources:**

- `ConfigMap/production@how-to-app` (1 diffs)

**Dep-affected (hash bump only, no content change):**

- `Deployment/production@how-to-app`
- `Job/production-health@how-to-app`
- `PackageInstance/production@how-to-app`
- `Service/production@how-to-app`

</details>

**Activation:** `how-to-application-aq1zdgf9gsnb` → `how-to-application-h9nqwqrpw48l`
(exit code: 2)

Redirect it into a file for the job to publish:

Run in kix-examples/

❱ kix diff how-to-application --output markdown > kix-diff.md

Use JSON when another program will process the result:

Run in kix-examples/

❱ kix diff how-to-application --output json > kix-diff.json

Confirm a clean result

After deploying the intended change, run the command again. A clean result confirms that Kix does not currently plan another content change.

kix diff compares the fields Kix applied. Use kix drift when you need to know who else owns a field and what they changed.