Skip to content

Conversation

jcogilvie
Copy link
Collaborator

@jcogilvie jcogilvie commented Oct 14, 2025

Description of your changes

This PR adds support for Crossplane's composition revision system and automatic/manual update policies in
crossplane-diff, ensuring diffs accurately reflect how Crossplane will render XRs based on their configured
update strategy.

Composition Revision Resolution

When diffing XRs, crossplane-diff now intelligently resolves which composition version to use based on the
XR's compositionUpdatePolicy and compositionRevisionRef fields:

  • Automatic Update Policy: XRs with compositionUpdatePolicy: Automatic (the default) always use the latest
    CompositionRevision for their composition. This mirrors Crossplane's behavior where automatic XRs are
    continuously upgraded to the newest composition version.

  • Manual Update Policy: XRs with compositionUpdatePolicy: Manual use the specific CompositionRevision
    referenced in their spec.crossplane.compositionRevisionRef field. This allows users to see diffs for XRs that
    are pinned to a specific composition version.

  • Fallback Behavior: If composition revisions cannot be found (e.g., for newly created compositions),
    crossplane-diff falls back to using the Composition resource directly.

New CLI Flag: --include-manual

The comp command now includes an --include-manual flag that controls which XRs are included in the diff
output:

  • Default behavior (--include-manual=false): Only shows diffs for XRs with Automatic update policy,
    since these are the XRs that will actually be affected by composition changes.

  • With --include-manual: Includes XRs with Manual update policy in the diff output, allowing users to
    see the potential impact if they were to upgrade these manually-pinned XRs.

This filtering ensures users see relevant results by default, while still allowing inspection of
manually-managed XRs when needed.

Implementation Details

  • Added CompositionRevisionClient to handle fetching and resolving CompositionRevision resources
  • Enhanced CompositionClient.FindMatchingComposition() to use revision-based resolution via
    resolveCompositionFromRevisions()
  • Added update policy filtering in CompDiffProcessor.filterXRsByUpdatePolicy()
  • The XR schema validator now strips the compositionRevisionRef field before validation, as it's set by
    Crossplane controllers and may not be present in all XRD schemas

Fixes #71.

I have:

Need help with this checklist? See the cheat sheet.

Signed-off-by: Jonathan Ogilvie <[email protected]>
Signed-off-by: Jonathan Ogilvie <[email protected]>
@jcogilvie jcogilvie changed the title Composition revisions feat: support composition revisions Oct 14, 2025
Signed-off-by: Jonathan Ogilvie <[email protected]>
Signed-off-by: Jonathan Ogilvie <[email protected]>
@jcogilvie jcogilvie self-assigned this Oct 15, 2025
@jcogilvie jcogilvie marked this pull request as ready for review October 15, 2025 20:20
@jcogilvie jcogilvie merged commit 24c23e3 into main Oct 15, 2025
11 checks passed
@jcogilvie jcogilvie deleted the composition-revisions branch October 15, 2025 20:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Ensure composition revision ref and update/delete policies are respected

1 participant