kanzifucius/crossplane-debug
Overview
This skill debugs Crossplane Compositions, Functions (KCL, Go templates, patch-and-transform, auto-ready), and managed resources. It guides you through extracting composition artifacts from a remote cluster, running local renders, tracing resource relationships, and inspecting provider and function logs. Use it to isolate rendering errors, function failures, resource creation problems, and claim/XR status issues.
How this skill works
The skill inspects composition YAML, function definitions, and a sample XR/claim to reproduce rendering with crossplane beta render. When sources are not local, it provides extraction steps and a helper script to pull composition, functions, and sample XR from the cluster. It also walks through cluster-side diagnostics: crossplane beta trace, kubectl describe/events, function and provider pod logs, and managed resource status fields to pinpoint causes.
When to use it
- Troubleshooting composition rendering errors or missing resources
- Investigating function failures (KCL, Go templates, patch-and-transform, auto-ready)
- Diagnosing managed resource creation failures, Synced/Ready conditions, or provider errors
- Debugging claim/XR status, connection secrets, and propagation issues
- When composition files are deployed only in a remote cluster and local reproduction is needed
Best practices
- Extract composition, functions, and a cleaned sample XR for local render before changing live resources
- Use crossplane beta render with a functions.yaml that matches cluster runtime (Default) or development targets (Development)
- Run functions locally (Docker) when iterating on KCL or custom logic to shorten feedback loop
- Trace from claim/XR (crossplane beta trace) to see full composed resource tree and quick status summary
- Inspect managed resource Status.AtProvider and provider logs for cloud-side errors; events often contain actionable messages
Example use cases
- Extract a deployed composition and sample XR from a cluster, run crossplane beta render to reproduce wrong resource values
- Run a local KCL function server and render to diagnose KCL syntax or logic errors that produce empty output
- Use crossplane beta trace to find which composed resource is failing to become Ready and inspect its provider logs
- Inspect XR and claim status to find missing connectionDetails or failing conditions after applying a composition change
- Debug auto-ready pipeline issues by validating function order and checking events for readiness propagation
FAQ
Extract the composition, build a functions.yaml that sets the function runtime to Default to use the cluster-side implementation, then run crossplane beta render locally. Also check function pods and logs in the cluster for errors.
Managed resource shows Synced=False. What next?
Describe the managed resource and check Conditions, Events, and Status.AtProvider. View provider pod logs for API errors or rate limiting. Confirm provider credentials and permissions, and retry after addressing any provider-side issues.
