Skip to content

feat(simulate): report the live health of XRs and composed resources - #546

Open
jcogilvie wants to merge 11 commits into
crossplane:mainfrom
jcogilvie:jco-simulate-health-model
Open

jcogilvie wants to merge 11 commits into
crossplane:mainfrom
jcogilvie:jco-simulate-health-model

Conversation

@jcogilvie

@jcogilvie jcogilvie commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Description of your changes

First of three stacked PRs for #539: crossplane {xr,composition,project} simulate showed only the spec diff, so an XR whose composed resources were all failing looked like a harmless small change. This PR reads the current health of the XR and its composed resources from the live objects simulate already fetches, and adds it to the -o json|yaml result. Text and -o diff output and the exit codes are unchanged here; they come in the next PR.

  • feat(health). A new leaf package, internal/health, classifies a live object from its conditions:

    • paused: carries crossplane.io/paused: "true", whatever its conditions.
    • failing: Synced=False.
    • notReady: Ready=False.
    • healthy: anything else, including objects with no Synced or Ready condition, such as a ConfigMap.

    It has no dependency on internal/diff, internal/plan or internal/simulate, so all three can use it, and so can resource simulate later.

  • feat(diff) / fix(diff). XRDiffGroup and XRImpact carry a CompositeHealth: the XR's health, plus the health of every composed resource in the observed set the engine already fetches, unchanged ones included. There are no new cluster reads.

    • A claim reports its backing XR's health. The claim's own Synced condition doesn't reflect a composition error.
    • Nested XRs are merged once: what a nested XR composes records it as Via.
    • Health is read from the live objects. It is never read from the Ready state --eventual-state synthesizes between renders.
    • DiffSingleResource now returns the RenderedResources instead of the bare unchanged map.
    • On the composition path, XRDiffResult keeps only the unchanged map and the health, not the observed objects.
  • feat(simulate). The structured result gains:

    • health (state plus the synced and ready conditions) on each plan and each composite.
    • composites[].unhealthy[], listing non-healthy composed resources that have no plan of their own. Each is listed once, with via naming the nested XR that composes it.
    • summary.health (unhealthyComposites, failing, notReady, paused).

    formatVersion goes from 0.1 to 0.2, and help/output.md documents the new fields.

Points for review:

  • The JSON shape is the contract the next two PRs and any CI consumers build on. The enum values are camelCase (notReady) to match the other machine-output enums (webhookUnavailable, manualPolicy, missingSchema).
  • Each unhealthy resource is listed once, under the deepest composite entry that has health of its own. In xr simulate a nested XR has no entry of its own, so it and what it composes are listed under its top-level composite, with via. In composition simulate a nested XR can have its own entry (since Improve nested-XR output in simulate #541), and then it carries its own health and unhealthy list, and counts in unhealthyComposites. A nested XR whose entry has no health (it errored, or was skipped or deferred) stays under its parent and counts as a resource.

Stack (#539):

  1. This PR: health model, engine plumbing, JSON output.
  2. feat(simulate): show health in simulate output and exit 4 when a resource is failing #554: text and -o diff rendering, the always-on exit bit 4 for failing resources (exit 3 = changes, 4 = failing, 7 = both) and --full-messages, for xr/composition/project simulate.
  3. feat(resource): report live health in resource simulate #566: the same for crossplane resource simulate.

I have:

  • Read and followed Crossplane's contribution process.
  • Read and followed Crossplane's AI policy and confirmed a human stands behind this PR.
  • Run ./nix.sh flake check to ensure this PR is ready for review. Ran go build, go vet, go test ./internal/... ./cmd/... (with envtest) and golangci-lint run ./... (with and without the integration tag) instead.
  • Added or updated unit tests.
  • Linked a PR or a docs tracking issue to document this change. The output help (internal/simulate/help/output.md) is updated in this PR.
  • Added backport release-x.y labels to auto-backport this PR. Not a backport candidate.

Need help with this checklist? See the cheat sheet.

🤖 Generated with Claude Code

@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.70968% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.18%. Comparing base (cd703a0) to head (a1a5d40).
⚠️ Report is 36 commits behind head on main.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

jcogilvie and others added 11 commits November 19, 2026 14:49
Add a leaf package that maps a live object to a health tier: paused (the
crossplane.io/paused annotation, overriding conditions), failing
(Synced=False), notReady (Ready=False) or healthy, carrying the Synced and
Ready conditions it was classified from.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Record the health of each XR's live object and of the composed resources
the diff engine already fetched to render it, on XRDiffGroup and XRImpact.
No new cluster reads: the XR comes from the resolved composite's cluster
copy, and composed resources from the observed resources render consumes,
before --eventual-state synthesizes any Ready condition. A nested XR's
observed resources merge into its parent's once, keyed by identity.

DiffSingleResource now returns the RenderedResources it built, so the
composition path gets health along with the unchanged renderings.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Each plan with a live object carries its health; each composite carries
the health of its live XR and lists the not-healthy composed resources
that have no plan of their own. The summary counts unhealthy composites
and failing, notReady and paused resources, each once. Bump the result
format version to 0.2 and document the new fields.

Text and diff output are unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
…health once

A claim mirrors only part of its backing XR's conditions, so the composite
health of a claim input is now its backing XR's.

RenderedResources classifies health as it records the live objects instead
of retaining them. Merge now records each nested composite's health, with
the nested composite as the via of what it composes directly, so every
composed resource is listed once with the composite that composes it. That
also covers a nested XR found by name rather than in its parent's observed
set, which previously lost its health when it had no plan.

The comp path stores each XR's computed health rather than its render.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
…ummary health

Each unhealthy entry names the nested composite that composes it under
via. The health counts move under summary.health, and a composite in two
entries is counted once. The help documents via, summary.health, a claim's
health, and that a composite that was not simulated has no health.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
PR 1 reports each composite's live health, so the project simulate
integration cases now see Health: healthy on every composite.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
A composition run gives a nested composite of the diffed composition's type
an entry of its own, now marked composedBy. Its parent's health also lists
it and what it composes, so each of those appeared in two unhealthy lists.

A nested composite with an entry and health of its own now shows its health
there and lists what it composes itself; its parent lists neither. One whose
entry has no health, because it wasn't simulated, stays listed under its
parent and counts there as a resource.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
@jcogilvie
jcogilvie force-pushed the jco-simulate-health-model branch 2 times, most recently from 355e2c8 to a1a5d40 Compare November 19, 2026 20:18
@jcogilvie
jcogilvie marked this pull request as ready for review November 19, 2026 22:41
@jcogilvie
jcogilvie requested review from a team and tampakrap as code owners November 19, 2026 22:41
@jcogilvie
jcogilvie requested review from haarchri and removed request for a team November 19, 2026 22:41
@coderabbitai

coderabbitai Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The change adds live health classification for Kubernetes objects and carries that health through diff processing into structured simulate results. Output includes health on plans and composites, unhealthy composed-resource details, and aggregate health counts. The result format version changes from 0.1 to 0.2.

Changes: Live health reporting

Layer / File(s) Summary
Health classification and resource capture
internal/health/*, internal/diff/types/*
The new health model classifies objects as paused, failing, not ready, or healthy. RenderedResources records health for composites and composed resources, including nested-resource attribution.
Health propagation through diff processing
internal/diff/result/*, internal/diff/diffprocessor/*, internal/diff/testutils/mocks.go
DiffSingleResource returns rendered resources with health. Diff groups and changed or unchanged composite impacts carry health; validator-rejected groups have their health cleared.
Health assembly in simulate reports
internal/plan/*, internal/simulate/report.go, internal/simulate/report_test.go
Report conversion adds health to composites and plans, and associates unplanned unhealthy resources with their deepest owning composite.
Health summaries and output format
internal/simulate/result*, internal/simulate/help/output.md, cmd/crossplane/project/*_test.go
Structured results include composite health, unhealthy-resource details, and aggregate counts under summary.health. The plan result format version changes to 0.2. Tests and output documentation cover these fields.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant DiffProcessor
  participant XRImpact
  participant ReportAssembler
  participant Result
  DiffProcessor->>XRImpact: Provide composite and composed-resource health
  XRImpact->>ReportAssembler: Supply health during report conversion
  ReportAssembler->>Result: Add composite, plan, and unhealthy-resource health
  Result->>Result: Include health counts in summary.health
Loading

Possibly related issues

  • crossplane/cli#539: The PR adds live health and unhealthy composed-resource details to structured simulate output, but does not add the text output requested by the issue.
Merge Risk: Minimal · up to a1a5d

This change adds live health to the structured JSON and YAML simulate results and bumps the result format to 0.2. The text and diff outputs and exit codes are unchanged. Nothing concrete blocks merging.

Pre-merge checks: Passed 6

Check name Status Explanation
Title check Passed The title "feat(simulate): report the live health of XRs and composed resources" is 68 characters, under the 72-character limit. It names the main change: simulate output now reports live health of XR…
Description check Passed The description states the PR is the first of three stacked PRs for #539. It explains that simulate now reads live health of XRs and composed resources and adds it to the -o json|yaml result. It also …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Breaking Changes Passed Summary: The check applies to files under apis/** or cmd/**. The pull request changes no files under apis/**. It changes two files under cmd/**, and both are test files. Evidence: - Th…
Feature Gate Requirement Passed The check fails only for new experimental features that affect apis/** or significantly change behavior, and that lack a feature flag. This PR does not meet that condition. Evidence: - No `apis/…
Full details: Title check

Explanation

The title "feat(simulate): report the live health of XRs and composed resources" is 68 characters, under the 72-character limit. It names the main change: simulate output now reports live health of XRs and composed resources, which the changeset adds to the JSON/YAML results.

Full details: Description check

Explanation

The description states the PR is the first of three stacked PRs for #539. It explains that simulate now reads live health of XRs and composed resources and adds it to the -o json|yaml result. It also lists the health states, the new internal/health package, the DiffSingleResource change, the formatVersion bump to 0.2, and the documentation update. This matches the changeset.

Full details: Breaking Changes

Explanation

Summary: The check applies to files under apis/** or cmd/**. The pull request changes no files under apis/**. It changes two files under cmd/**, and both are test files. Evidence: - The changed-file inventory (git diff --name-status against refs/coderabbit/pre-merge-check/base and head) lists 22 files. Only cmd/crossplane/project/integration_plan_output_test.go and cmd/crossplane/project/integration_project_test.go match cmd/**. No file matches apis/**. - The cmd/** diff only adds the internal/health import and sets Health: healthy (&amp;health.Health{State: health.Healthy}) on expected simulate.CompositeResult values. It does not rename or remove any field, flag, or behavior. It also adds no required public field or flag. - All production logic (internal/health, internal/diff, internal/plan, internal/simulate) lies outside the check's path scope. Out-of-scope observations (not part of this verdict): - internal/plan/output.go bumps ResultFormatVersion from 0.1 to 0.2. This bump is the deliberate versioning signal for the JSON output change. The raw summary also says that summary.health is added and that deferred and destroy counts now sit in a nested summary object. That is a machine-readable output contract change. A reviewer should confirm it is intended, but it falls outside apis/** and cmd/**, so it does not trigger this check. - The breaking-change label state is not visible in the supplied metadata. It is not needed here because no in-scope trigger applies. Thank you to the contributor for the clear stack plan and the explicit test updates. Those updates make the new output expectations easy to follow.

Full details: Feature Gate Requirement

Explanation

The check fails only for new experimental features that affect apis/** or significantly change behavior, and that lack a feature flag. This PR does not meet that condition. Evidence: - No apis/** changes. The changed-file list has no paths under apis/. - Feature gating already applies. The changed code sits inside simulate commands that the CLI already gates as alpha. cmd/crossplane/xr/xr.go:24, cmd/crossplane/composition/composition.go:30, cmd/crossplane/project/project.go:26 and cmd/crossplane/resource/resource.go:28 all carry maturity:"alpha". Alpha commands are hidden unless features.enableAlpha is set (cmd/crossplane/main.go:155-160, pkg/cli/cli.go:136-139). The new health fields therefore inherit the existing flag. - Behavior change is additive. The PR adds health, unhealthy and summary.health to the -o json|yaml output. The PR description states that text output, -o diff output and exit codes are unchanged. Existing fields are not removed or renamed. - Versioned output. ResultFormatVersion moves from 0.1 to 0.2 (internal/plan/output.go:90). This signals the schema change to consumers. The schema documentation is updated in internal/simulate/help/output.md. Residual note: the PR does not state that the output is experimental. The format bump and the alpha command gate are the controls the repository already uses. If maintainers want the new JSON fields gated separately, that would be a design choice. The check does not require it. Thanks to the author for the clear stacking plan and the notes on the JSON contract. A question for the author: should the 0.2 schema be documented as alpha in the release notes, since the enclosing commands are alpha?

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between b0b62c0 and a1a5d40.

Files selected for processing: 20

  • cmd/crossplane/project/integration_plan_output_test.go
  • cmd/crossplane/project/integration_project_test.go
  • internal/diff/diffprocessor/comp_processor.go
  • internal/diff/diffprocessor/comp_processor_test.go
  • internal/diff/diffprocessor/diff_processor.go
  • internal/diff/diffprocessor/diff_processor_test.go
  • internal/diff/result/comp.go
  • internal/diff/result/types.go
  • internal/diff/testutils/mocks.go
  • internal/diff/types/types.go
  • internal/diff/types/types_test.go
  • internal/health/health.go
  • internal/health/health_test.go
  • internal/plan/output.go
  • internal/plan/types.go
  • internal/simulate/help/output.md
  • internal/simulate/report.go
  • internal/simulate/report_test.go
  • internal/simulate/result.go
  • internal/simulate/result_test.go

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@jcogilvie

Copy link
Copy Markdown
Collaborator Author

@coderabbitai Thanks for the review. Two follow-ups on the Breaking Changes and Feature Gate notes:

  • Summary layout. The deferred and destroy counts don't move. summary.create, update, destroy, replace, noop, approximate, errored and deferred stay flat at the same paths as in 0.1. The only addition is a new summary.health object (unhealthyComposites, failing, notReady, paused), so a 0.1 consumer that ignores unknown fields reads the same values as before. The change is additive, and the formatVersion bump to 0.2 marks it.
  • Alpha status of 0.2. The new fields inherit the alpha gate of the simulate commands, as you noted, and there's no separate gate for them. Whether the release notes call the schema alpha is for the maintainers to decide when they cut the release; this PR doesn't change the release notes.

Posted by an AI agent (Claude Code) acting on behalf of @jcogilvie.

@coderabbitai

coderabbitai Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Tip

For best results, initiate chat on the files or code changes.

Analysis chain

Script executed:

#!/bin/bash
set -u
echo '--- Current result outline ---'
ast-grep outline internal/simulate/result.go --items all --match 'Summary|Marshal|Result|Health' --view expanded
echo '--- Current summary serialization and fields ---'
rg -n -C 5 'summary|Summary|MarshalJSON|json:"(create|update|destroy|replace|noop|approximate|errored|deferred|health)' internal/simulate/result.go
echo '--- Base revision summary serialization and fields ---'
git show refs/coderabbit/pre-merge-check/base:internal/simulate/result.go | rg -n -C 5 'summary|Summary|MarshalJSON|json:"(create|update|destroy|replace|noop|approximate|errored|deferred|health)' || echo 'Base revision unavailable or no matching fields.'
echo '--- Version constant and output documentation ---'
rg -n -C 3 'ResultFormatVersion|summary\.health|summary\.deferred|summary\.destroy|formatVersion' internal/plan/output.go internal/simulate/help/output.md

Length of output: 11546


Script executed:

#!/bin/bash
set -u
echo '--- Summary definition ---'
ast-grep outline internal/plan/output.go --items all --match 'Summary' --view expanded
cat -n internal/plan/output.go | sed -n '20,110p'
echo '--- PR patch for result serialization ---'
gh api repos/crossplane/cli/pulls/546/files --paginate --jq '.[] | select(.filename == "internal/simulate/result.go") | .patch'

Length of output: 9449


@jcogilvie Thanks for the correction. I was wrong to say the deferred and destroy counts moved. They remain flat under summary; the new summary field is summary.health. The formatVersion changes to 0.2.

Consumers that ignore the new fields must also accept the 0.2 version to read the result.

The alpha status is consistent with the existing command-maturity guidance. The schema is also described as alpha in internal/plan/output.go, Line 87. I agree that release-note wording is a maintainer decision.


Learnings added

Learnt from: jcogilvie
URL: https://github.com/crossplane/cli/pull/546

Timestamp: 2026-11-19T23:55:52.640Z
Learning: Within repository "crossplane/cli", only for files matching one of ["internal/simulate/result.go"]: For the simulate JSON/YAML result transition from formatVersion `0.1` to `0.2`, the existing summary counts, including `summary.destroy` and `summary.deferred`, remain at their original flat paths. The summary change adds `summary.health`; do not claim that the existing counts moved. Compatibility also depends on the consumer accepting the new format version and added fields.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.


Learnings used

Learnt from: CR
Repo: crossplane/cli PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2026-10-31T03:07:34.054Z
Learning: Source excerpt:
# Contributing to the Crossplane CLI

## Command Maturity Levels

Alpha and beta commands are marked as such using a custom kong struct tag,
`maturity:"alpha"` or `maturity:"beta"`. These struct tags control two things:

1. Alpha commands are hidden from the help output by default. Users must enable
   showing alpha commands in their CLI configuration file.
2. Alpha and beta commands automatically have notes added to their help text
   indicating the maturity level and what it means.
Learnt from: adamwg
Repo: crossplane/cli PR: 10
File: cmd/crossplane/dependency/dependency.go:21-25
Timestamp: 2026-05-13T18:59:40.564Z
Learning: The Crossplane CLI (crossplane/cli) does not use programmatic feature flags for experimental features. Instead, it uses the `maturity` struct tag (e.g., `maturity:"beta"`) on kong command registrations to signal experimental/beta status. This tag is applied at the parent command level (e.g., the `Dependency`, `Project`, `XRD`, etc. top-level Cmd fields in cmd/crossplane/main.go), so subcommands like `dependency add`, `dependency update-cache`, and `dependency clean-cache` are already gated under the parent's maturity annotation. Do not flag missing feature flags or suggest wrapping command registration behind a feature gate function; the maturity tag is the correct and sufficient mechanism.
Learnt from: CR
Repo: crossplane/cli PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2026-10-31T03:07:34.054Z
Learning: Source excerpt:
# Contributing to the Crossplane CLI

## Command Maturity Levels

If a command is not tagged with a maturity level, it will inherit from its
parent in the command tree. This means that if you're introducing a whole tree
of commands into beta, only the parent needs to be tagged. Commands without a
maturity level anywhere in their tree are considered GA.

You are interacting with an AI system.

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.

1 participant