Skip to content

feat(simulate): show health in simulate output and exit 4 when a resource is failing - #554

Draft
jcogilvie wants to merge 21 commits into
crossplane:mainfrom
jcogilvie:jco-simulate-health-render
Draft

jcogilvie wants to merge 21 commits into
crossplane:mainfrom
jcogilvie:jco-simulate-health-render

Conversation

@jcogilvie

@jcogilvie jcogilvie commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Note

Depends on #546 and contains its commits, since a fork's PR can't target another fork branch. Review only the commits from feat(simulate): mark unhealthy resources in plan output onward. Once #546 merges, this diff narrows to them.

Description of your changes

Second of three stacked PRs for #539. The previous PR put the live health of XRs and their composed resources into the -o json|yaml result. This one shows it in the text output and the exit status of crossplane {xr,composition,project} simulate, so a run against a broken XR no longer looks like a small, safe change.

  • Plan output (-o plan).
    • An unhealthy XR's header ends in ⚠ <tier> (<condition>, <reason>): <message>.
    • Each unhealthy resource in the plan gets an indented ⚠ line under its entry.
    • Unhealthy composed resources that have no change are listed under the XR in an Unhealthy resources without changes: block, with each resource that a nested XR composes nested under that XR.
    • A Health: line follows Plan:, naming only the non-zero counts, e.g. Health: 1 of 2 XRs unhealthy before apply; 12 resources failing (Synced=False), 2 not ready, 1 paused.
  • Diff output (-o diff). The same information appears under each === XR === header and on each resource's ~~~ line. An XR's own entry carries only its tier, so its message prints once.
  • Nested XRs. Each unhealthy resource is listed once, under the deepest XR that has an entry of its own. In composition simulate a nested XR can have its own entry (since Improve nested-XR output in simulate #541), so its unhealthy resources are listed there, not under its parent too. Plan and diff output share this rule (health.OwnedElsewhere). The Health: line counts only XRs with live health in its "N of M XRs", so plan and diff output report the same counts.
  • Healthy runs print exactly what they print today. No existing golden output changed.
  • --full-messages. By default a condition message is cut to one line (newlines collapsed, about 120 runes, with an ellipsis). --full-messages prints it in full, wrapped and indented. With -o json|yaml the flag is ignored and reported like the other ignored flags.
  • Exit status. The status is now a bitmask: 3 = changes, 4 = a failing (Synced=False) XR or resource before apply, 7 = both. Only failing sets 4. A resource that is only not ready, or is paused, doesn't set it. A failing resource the change would delete still does. Errors keep their precedence (130, then 1, then 2) over 3, 4 and 7. DetermineExitCode now composes the bits instead of choosing one rung of a ladder. help/exit.md is rewritten, since "the lowest of 1, 2 and 3 wins" no longer holds.
  • Tests.
    • There are integration cases for xr, composition and project simulate against fixtures with live failing, not-ready and paused status. They assert the text, the JSON health fields and exit codes 4 and 7.
    • The fixture loader now writes status through the status subresource. That's a no-op for every existing fixture.

Example (xr simulate -o diff, the XR failing with a change):

XR: XNopResource/default/test-resource ⚠ failing (Synced=False, ReconcileError): cannot compose resources: the vpc does not exist

~~~ XDownstreamResource/test-resource ⚠ not ready (Ready=False, Creating)
...
~~~ XNopResource/test-resource ⚠ failing
...
Summary: 2 modified

Health: 1 of 1 XR unhealthy before apply; 1 resource not ready.

This run exits 7.

Points for review:

Stack (#539):

  1. feat(simulate): report the live health of XRs and composed resources #546: health model, engine plumbing, JSON output.
  2. This PR: text and -o diff rendering, exit bit 4, --full-messages.
  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 (with and without the integration tag), go test ./..., golangci-lint run ./... (with and without the integration tag) and nix run .#integration-test instead, since nix.sh needs Docker.
  • Added or updated unit tests.
  • Linked a PR or a docs tracking issue to document this change. The simulate exit help (internal/simulate/help/exit.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 91.99372% with 51 lines in your changes missing coverage. Please review.
✅ Project coverage is 62.64%. Comparing base (cd703a0) to head (79ac845).
⚠️ Report is 23 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
jcogilvie force-pushed the jco-simulate-health-render branch from 7d519ec to adf79ca Compare November 19, 2026 19:03
jcogilvie and others added 19 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>
An unhealthy XR's header and a plan whose live resource is not healthy now
carry a one-line health description: the tier, the condition it was read
from with its reason, and its message cut to 120 runes. Under each XR an
"Unhealthy resources without changes:" block lists the composed resources
that are unhealthy and have no plan, nesting each under the nested XR that
composes it. A Health: line after Plan: summarizes the counts. Healthy runs
print what they did before.

--full-messages prints the messages in full, wrapped and indented, and is
ignored, with a warning, for -o json and -o yaml. The formatting lives in
internal/health so the diff renderer can share it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
-o diff now shows what plan output does. An XR's health heads its section,
or the output for a single XR. A diffed resource that is not healthy is
marked on its header. Each XR's unhealthy resources without changes are
listed after its diffs, or after "No changes.". A Health: line closes the
run. The composition diff marks each affected XR's line and lists those
resources after the impact analysis. Both use the formatting in
internal/health and honour --full-messages. Healthy runs print what they
did before.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
Without an error, a simulate run's exit status now adds 4 when a composite
resource, or a resource it composes, was failing (Synced=False) before
apply, including one the change would delete. So 4 means no changes and
something failing, and 7 means both. Errors still come first: 130 over 1
over 2. DetermineExitCode takes the failing state and composes the bits
in place of returning the first match. The exit help and the harness's
exit-code comment describe the new statuses.

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

Fixtures carry Synced=False, Ready=False and paused. The cases assert the
text output, the JSON health fields and summary.health, and exit codes 4
and 7. Under envtest no controller writes status, so the fixture loader
now writes a fixture's status through the status subresource.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
The paused fixture carried crossplane.io/paused under the Crossplane field
manager, so the dry-run apply removed it and the plan golden showed the
annotation being dropped. Apply it under kubectl instead, as a user would.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
When the XR's health line is printed for its group, the XR's own diff entry
carries only its tier marker, without the condition and message again.

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>
@jcogilvie
jcogilvie force-pushed the jco-simulate-health-render branch from adf79ca to 04878ef Compare November 19, 2026 20:39
jcogilvie and others added 2 commits November 19, 2026 16:21
… diff

A nested XR with its own impact and health listed what it composes, and
its parent listed the same resources again. Share the plan output's rule
as health.OwnedElsewhere, used by both the simulate assembler and the
composition diff renderer across every composition in the run: each
resource is listed under the most deeply nested composite entry that has
health of its own.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
tallyComposite counted an XR without health, as one not yet in the
cluster or whose entry errored or was filtered, as a healthy composite.
That inflated the XR count past plan output's, and hid a nested XR's
failure: added as a composite, it was then skipped as a resource, so a
run that exits 4 printed no Health: line. Count a composite only when it
has health, as simulate's healthTally does.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: Jonathan Ogilvie <jonathan.ogilvie@sumologic.com>
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