From 46150eca5ee33d00ccbfac7ef672e954bd17348f Mon Sep 17 00:00:00 2001 From: Adam Wolfe Gordon Date: Wed, 18 Nov 2026 16:38:37 -0600 Subject: [PATCH] Document CompositionRevision garbage collection Describe the new `--enable-composition-revision-gc` alpha feature and how the `unusedRevisionHistoryLimit` field works on Compositions. Fixes #1159 Signed-off-by: Adam Wolfe Gordon --- .../composition/composition-revisions.md | 62 +++++++++++++++++++ content/master/get-started/install.md | 1 + 2 files changed, 63 insertions(+) diff --git a/content/master/composition/composition-revisions.md b/content/master/composition/composition-revisions.md index b9695f6f5..9566eafef 100644 --- a/content/master/composition/composition-revisions.md +++ b/content/master/composition/composition-revisions.md @@ -123,6 +123,68 @@ spec: name: example-18pdg ``` +## Garbage collect unused revisions + +{{}} +Composition revision garbage collection is an alpha feature. Enable it by +setting the `--enable-composition-revision-gc` feature flag. +{{< /hint >}} + +Crossplane creates a new `CompositionRevision` every time you edit a +`Composition`, and by default never deletes them. A `Composition` that changes +often can build up a long list of revisions that no XR uses. + +With garbage collection enabled, Crossplane deletes unused revisions each time +it reconciles a `Composition`. The `unusedRevisionHistoryLimit` field in the +`Composition` spec sets the number of unused revisions to keep. The default is +`1`. Set it to `0` to keep every revision. + +```yaml {copy-lines="none"} +apiVersion: apiextensions.crossplane.io/v1 +kind: Composition +metadata: + name: example +spec: + compositeTypeRef: + apiVersion: example.org/v1alpha1 + kind: PlatformDB + # Keep up to 3 unused revisions. + unusedRevisionHistoryLimit: 3 + mode: Pipeline + pipeline: + # Removed for brevity +``` + +Crossplane never deletes: + +* The latest revision of the `Composition`. +* Any revision an XR references in its `compositionRevisionRef`. +* The newest revision that matches any XR's `compositionRevisionSelector`. +* The newest revision that matches the XRD's + `defaultCompositionRevisionSelector`. + +These revisions don't count toward the `unusedRevisionHistoryLimit`. With the +default limit of `1`, Crossplane keeps the latest revision, every revision in +use, and the newest unused revision. + +Crossplane keeps the newest unused revisions and deletes the oldest ones. This +means Crossplane can delete a newer revision while an older one remains. For +example, consider a `Composition` with revisions `1` through `5` and a `Manual` +XR using revision `1`. With the default limit of `1`, Crossplane keeps revision +`1` because the XR uses it, revision `5` because it's the latest, and revision +`4` because it's the newest unused revision. Crossplane deletes revisions `2` +and `3`. + +Changing a Composition's `unusedRevisionHistoryLimit` doesn't create a new +`CompositionRevision`. + +{{}} +After you upgrade Crossplane, every existing `Composition` gets the default +`unusedRevisionHistoryLimit` of `1`. If you want to keep more revisions, set +`unusedRevisionHistoryLimit` on your compositions before you enable the +`--enable-composition-revision-gc` flag. +{{< /hint >}} + ## Complete example This tutorial discusses how CompositionRevisions work and how they manage Composite Resource diff --git a/content/master/get-started/install.md b/content/master/get-started/install.md index ddea92d70..df5f5fd6e 100644 --- a/content/master/get-started/install.md +++ b/content/master/get-started/install.md @@ -110,6 +110,7 @@ at the table below. | Beta | `--enable-realtime-compositions` | Enable support for real time compositions. | | Beta | `--enable-ssa-claims` | Enable support for using server-side apply to sync claims with XRs. | | Beta | `--enable-usages` | Enable support for Usages. | +| Alpha | `--enable-composition-revision-gc` | Enable garbage collection of unused CompositionRevisions. | | Alpha | `--enable-dependency-version-downgrades` | Enable automatic version downgrades of dependencies when updating packages. | | Alpha | `--enable-dependency-version-upgrades` | Enable automatic version upgrades of dependencies when updating packages. | | Alpha | `--enable-function-response-cache` | Enable caching of composition function responses to improve performance. |