How-to guide Operate a cluster

Garbage-collect stale resources

Remove resources no longer present in the cluster definition and retire old rollback records.

Use kix gc to remove resources that an earlier Activation managed but the current cluster definition no longer contains. Every mode also applies the Activation retention policy.

Review the normal garbage-collection plan

Run gc with the cluster name:

kix-examples/

❱ kix gc how-to-application

The normal mode compares the previously deployed Activation with a fresh build of the cluster. It prints the resources found by that comparison and the Activation records it plans to delete, then asks for confirmation.

Soft gc can also find stale cluster-level resources that belong to no package. It currently deletes those after confirmation without listing them in the plan. Use hard mode when the confirmation plan must be a complete inventory of live garbage.

It also deletes orphans that a kix deploy without --prune listed and kept. That deploy records the builds they came from on its Activation, and the plan lists them under Orphans kept by earlier deploys.

Check the package, kind, namespace, and name of each resource before approving the plan. Kix deletes dependants before their dependencies.

A Namespace or CustomResourceDefinition that has left the build is listed under Kept and is not deleted, in soft and hard mode. Deleting a Namespace deletes everything in it, and deleting a CustomResourceDefinition deletes every custom resource of that kind on the cluster, including ones Kix does not manage. kix deploy --prune keeps the same kinds. When you do want one removed, delete it with kubectl delete after checking what it contains.

Run without a prompt

After reviewing the plan, pass --yes in automation:

kix-examples/

❱ kix gc how-to-application -y
Loading old activation...
Building cluster 'how-to-application'...

Garbage collection plan

  how-to-app
    - preview 1.0.0 (3 resources)

  Plan: 1 removed, 2 unchanged
  1 activation records kept
  - deleted PackageInstance/preview@how-to-app
  - deleted Service/preview@how-to-app
  - deleted Deployment/preview@how-to-app
  - deleted ConfigMap/preview@how-to-app

GC complete: 4 deleted, 0 failed, 0 activation record(s) retired, 1 kept

This performs the same comparison and deletion without asking for confirmation. The captured run follows an instance being renamed in the cluster definition, so the resources deployed under the old name are the ones Kix removes.

Scan the live cluster for orphans

Use --hard when the local activation cache is unavailable or you need to find Kix-managed resources outside the previous-to-current build comparison:

kix-examples/

❱ kix gc how-to-application --hard

Hard mode scans live resources carrying Kix ownership metadata and compares them with the expected resources in the current build.

When one Kubernetes cluster hosts more than one Kix cluster, hard mode judges only the named cluster’s resources. It finds them through the Activation records each resource names, skips the other clusters’ resources, and keeps a resource another cluster’s current build also contains. A resource that names no Activation record at all cannot be attributed to either cluster, so hard mode lists it under “Unattributed” and keeps it. Review those and pass --include-unattributed to judge them against the build too.

Resources carrying a Kix label but no kix.run/identity-hash are reported as unstamped and kept by default. Kix cannot establish that it originally applied them. Include them only after checking each reported resource:

kix-examples/

❱ kix gc how-to-application --hard --include-unstamped

Let the operator perform cleanup

For an operator-managed cluster, use operator mode:

kix-examples/

❱ kix gc how-to-application --operator

Kix deletes the Activation records selected by the retention policy. These are all Superseded records, so the operator only removes its finalizer from each one. It deletes no resources: the Active record owns them. The operator deletes resources only when an Active, Deploying or Degraded record is deleted, and even then it keeps every Namespace and CustomResourceDefinition.

Use the same --keep, --keep-max, and --keep-for flags in any mode. For example:

kix-examples/

❱ kix gc how-to-application --hard --keep 20 --keep-max 100 --keep-for 90d