Artifact reclamation

This page shows how to reclaim artifacts in object storage that are no longer referenced.

For command IDs and expected revisions on write commands, see Command IDs and expected revisions.

Use kibo artifact to reclaim bytes in object storage that the catalog no longer references, or to exclude a Launch from reclamation:

kibo artifact reclaim plan                        # Only records a plan; deletes nothing
kibo artifact reclaim get arec-...                # Review a plan or the result of a run
kibo artifact retain sha256:... --until 2026-12-31T00:00:00Z
kibo artifact reclaim plan                        # Plan again after the retention takes effect
kibo artifact reclaim apply arec-...              # Run the whole plan; requires confirmation
kibo artifact reclaim list

What gets reclaimedCopy Anchor Link

The reclaimable set is derived only from the catalog:

• A Launch is kept in any of these cases: a Workspace that is not deleted is bound to it; it has a retention period that has not expired; neither its Template revision nor its Platform revision is withdrawn.
• A Template or Platform revision is kept when it is not withdrawn or when a kept Launch references it.
• All other manifests, and the blobs referenced only by those manifests, go into the reclamation plan.

The plan lists each entry's reason, withdrawal time, and exclusive byte count, and gives the size of the kept set.

plan and applyCopy Anchor Link

• reclaim plan writes a record with status PLANNED and returns the record ID. It deletes nothing.
• reclaim apply accepts only such a record and runs it as a whole. You cannot run only part of it. Each entry is recomputed before the run: entries that have been referenced again are skipped, written to skipped in the result, and not deleted.
• To keep an object, first keep its Launch with retain, then run plan again.
• apply is a destructive command. In a terminal, you confirm it by typing the record ID. A non-interactive terminal requires --yes.
• Replaying the same --command-id on the same record returns the original result. Using it on a different record returns already_exists. Only one run is allowed at a time, and a second apply returns failed_precondition.

retainCopy Anchor Link

• retain can only extend the retention period. A time earlier than the existing retention period is rejected.
• A Launch that has already been reclaimed cannot be retained.

Automatic reclamationCopy Anchor Link

Every 24 hours, ctrl reclaims automatically and deletes only objects withdrawn more than 7 days ago. Records of automatic reclamation appear in reclaim list together with apply records, with AUTOMATIC in the TRIGGER column. For the start time and required permissions, see Install ctrl.

The admission views of kibo platform list, kibo platform get, and kibo template carry a Reclaimed time: a reclaimed revision is still withdrawn, but object storage no longer holds its bytes.