kaiohenricunha Crossplane Specialist
Structured investigation for Crossplane-based infrastructure platforms. Five phases: gather context, diagnose, design, recommend, verify.
Arguments
$0— XRD name, Claim name, or problem description. Required.
Phase 1: Context Gathering
- List installed providers and packages:
kubectl get providers kubectl get configurations kubectl get functions - List XRDs and their ready status:
kubectl get xrd - List Claims and Composites:
kubectl get composite --all-namespaces kubectl get claim --all-namespaces - Glob for Crossplane manifests in the working directory:
find . -name "*.yaml" | xargs grep -l "apiVersion: apiextensions.crossplane.io" | sort
Phase 2: Diagnosis
Stuck Claim / Composite trace:
kubectl describe claim <name> -n <namespace>
kubectl describe composite <name>
kubectl get managed --all-namespaces | grep -v "True"
kubectl describe <managed-resource-kind> <name>
Provider health:
kubectl describe provider <name>
kubectl get providerconfig
kubectl describe providerconfig <name>
Composition pipeline:
kubectl get composition <name> -o yaml
kubectl get function --all-namespaces
Phase 3: Design / Root-Cause Analysis
Map symptoms to causes:
| Symptom | Common Causes | Check |
|---|---|---|
Claim stuck Waiting |
Composite not ready, no matching Composition | kubectl describe composite → events |
Managed resource NotFound |
Wrong external-name annotation, ID mismatch | Provider docs for external-name format |
Provider Unhealthy |
Bad credentials, missing ProviderConfig |
kubectl describe provider events |
| Composition patch fails | Wrong fromFieldPath, type mismatch |
kubectl get composite -o yaml patched fields |
| Function pipeline error | Function pod crash, malformed FunctionIO |
kubectl logs -n crossplane-system function |
| Deletion stuck (finalizer) | Managed resource Delete policy, cloud resource busy |
Check deletion policy + cloud console |
Cite kind:name or file:line for every finding.
Phase 4: Recommendations
Output findings in priority order:
[CRITICAL] <title>
Resource: <kind:name or file:line>
Issue: <one sentence>
Evidence: <kubectl output or config snippet>
Fix: <specific change, with YAML diff if applicable>
Trade-off: <alternative and its downside, if meaningful>
Order: CRITICAL → WARNING → INFO.
Phase 5: Verification
After fixes are applied:
kubectl get composite <name>—READY: True,SYNCED: True.kubectl get managed— all managed resources showREADY: True.kubectl describe claim <name>— no error events.kubectl apply --dry-run=server -f composition.yaml— no schema errors.- If deletion policy changed: confirm behavior by deleting a test Claim in a non-prod environment.
Reference Docs
| File | When to use |
|---|---|
xrd-design.md |
XRD schema design, versioning, validation rules |
compositions.md |
Composition patch-and-transform, pipeline mode, Functions |
provider-configs.md |
Credential injection, ProviderConfig patterns |
managed-resources.md |
External-name, deletion policy, resource lifecycle |
gitops-integration.md |
Argo CD / Flux health checks, package management |