gc

kix gc removes what a cluster’s build no longer contains. It has three modes: soft (the default) compares the last deployed build with a fresh one, --hard scans every Kix-managed resource of the named cluster, and --operator deletes Activation records and lets the Kix operator clean up after them. Every mode also retires old Superseded Activation records.

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

Synopsis

kix gc <CLUSTER> [-y] [--hard [--include-unstamped] [--include-unattributed]] [--operator]
       [--keep <N>] [--keep-max <N>] [--keep-for <DURATION>]
       [--flake <FLAKE>] [--context <CONTEXT>]

Argument or flag	Meaning
<CLUSTER>	Cluster name to build from the flake.
-y, --yes	Skip the confirmation prompt. Required when stdin is not a terminal.
--hard	Scan the named cluster’s resources carrying the Kix managed-by label and delete those whose identity hash is not in the fresh build.
--include-unstamped	With --hard, also delete resources that carry the label but no kix.run/identity-hash. Kix never applied these, so by default they are only listed.
--include-unattributed	With --hard (required), also judge resources that name no Activation record on the cluster. When another Kix cluster has records on the same Kubernetes cluster, Kix cannot tell whose these are, so by default they are only listed.
--operator	Delete the retired Activation records only; the operator’s finalizer removes their resources.
--keep <N>	Always keep at least the N newest Superseded records, whatever their age. Default 10. 0 keeps none.
--keep-max <N>	Never keep more than N Superseded records. Default 50. A value below --keep is raised to it.
--keep-for <DURATION>	Beyond --keep, retire records older than this: 30d, 12h, 45m, 30s, or a bare number of days. 0 or off disables the age rule. Default 30d.
--flake, --context	See Global flags. -o has no effect.

Modes

Mode	Old side	What is deleted
Soft	The build the cluster’s Active record names, from this machine’s cache of the last kix deploy or kix rollback when that is the same build, else from the local Nix store; and the builds the Active record lists under status.orphansKeptFrom	Resources whose kind, namespace and name are absent from the fresh build. Exits with a message if the cluster has no Active record or its build is not on this machine. A cached build of another context’s cluster of the same name is set aside with a warning.
--hard	Every Kix-managed resource of the named cluster	Resources whose identity hash is not in the fresh build
--operator	Activation records	Retired records; the operator deletes their resources

Soft gc can omit cluster-level garbage from its plan

Soft gc currently deletes stale resources that belong to no package, but its confirmation plan does not list them. Use --hard when you need the plan to inventory those resources before deletion.

--hard judges the resources of the cluster you name. Each resource Kix deploys lists, in its kix.run/activations annotation, the Activation records whose builds contain it, and each record carries a kix.run/cluster label. When one Kubernetes cluster hosts several Kix clusters, hard mode reads those records to decide whose each resource is:

• A resource that names only another cluster’s records is skipped, and the run prints how many it skipped per cluster.
• A resource that another cluster’s current build also contains is kept and listed as kept ..., still deployed by Kix cluster <name>.
• A resource that names no record on the cluster (its records were retired, or it predates the annotation) is listed under “Unattributed” and kept unless you pass --include-unattributed. With only one Kix cluster on the Kubernetes cluster, such a resource is judged like any other.

Soft gc, kix deploy --prune and kix rollback --prune apply the same rule to a resource both clusters deploy: when the named cluster’s build drops it and another cluster’s current build still contains it, the plan lists it as kept.

Every delete checks again just before it happens: gc reads the resource, then the Activation records, and deletes it only if no other cluster’s current record names it and it has not changed since that read. A resource left for either reason is printed as = prune: kept ... and is not a failure.

Resources are deleted dependents first. Namespaces and CustomResourceDefinitions are skipped. A resource that is already gone when gc deletes it is reported, not counted as a failure.

A deploy without --prune keeps its orphans and lists the builds they came from on the new Activation, under status.orphansKeptFrom. Soft gc deletes those orphans too, listed under “Orphans kept by earlier deploys”. When soft or hard gc deletes without failures and the fresh build is the one the Active record describes, it removes the list. Soft gc leaves the list if this machine could not read one of the builds, and hard gc leaves it if it was forbidden to list some kinds. Deploying with --prune every time keeps the list empty, so soft gc has no kept orphans to find; see deploy.

Retiring a record removes it as a rollback target. Each record kept adds one entry to the kix.run/activations annotation on every managed resource, which is why the count is capped. A record is deleted only if it has not changed since it was listed.

Examples

❱ kix gc demo

❱ kix gc demo --hard --yes

❱ kix gc demo --keep 5 --keep-for 14d

Exit status

Code	Meaning
0	Nothing to collect, everything planned was deleted, or the prompt was declined
1	A deletion failed; confirmation was needed on a non-interactive terminal; or a build or cluster error

Use it in a task

See Garbage-collect stale resources for choosing a mode, and Configure activation retention for the retention flags.