# Garbage-collect stale resources

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:

<Command commands={["kix gc how-to-application"]} cwd="kix-examples/" />

The normal mode compares the previously deployed Activation with a fresh build
of the cluster. It prints every resource and Activation record it plans to
delete, then asks for confirmation.

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

## Run without a prompt

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

<Command {...gcPlan} />

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:

<Command commands={["kix gc how-to-application --hard"]} cwd="kix-examples/" />

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

:::caution[Hard mode is not limited to one cluster]
The scan covers every Kix-managed resource the context can see, and judges
each one against the build of the cluster you named. If one Kubernetes
cluster hosts more than one Kix cluster, hard mode treats the other clusters'
resources as garbage. Run it only where the named cluster owns everything Kix
manages, or check the reported plan before approving it.
:::

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:

<Command
  commands={["kix gc how-to-application --hard --include-unstamped"]}
  cwd="kix-examples/"
/>

## Let the operator perform cleanup

For an operator-managed cluster, use operator mode:

<Command commands={["kix gc how-to-application --operator"]} cwd="kix-examples/" />

Kix deletes the Activation records selected by the retention policy. The
operator's finalizers perform the associated resource cleanup.

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

<Command
  commands={[
    "kix gc how-to-application --hard --keep 20 --keep-max 100 --keep-for 90d",
  ]}
  cwd="kix-examples/"
/>

:::note[Configure the history window]
See [Configure Activation retention](/docs/how-to/operate-a-cluster/configure-activation-retention/)
for the retention rules and scheduling example.
:::

:::note[Reference]
See [`kix gc`](/docs/reference/cli/gc/) for all flags and mode behavior.
:::