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 show READY: 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 |
1---2# dotbabel:generated projection=sha256:f0e7c91a4a4b115b4f0c02f86ff8d81d704405df0076984c0d4e82fd9ba5c228 source=skills/crossplane-specialist/SKILL.md — do not edit directly3allowed-tools: Read Grep Glob Bash4argument-hint: <XRD name, Claim name, or problem description>5description: |6 Deep-dive Crossplane platform review: XRD design, Composition correctness, provider config audit, managed resource health, and GitOps integration. Use for structured investigations of stuck Claims, composition pipeline bugs, and credential injection patterns. Triggers on: "Crossplane audit", "XRD review", "Composition debug", "stuck Claim", "managed resource stuck", "provider config review", "Crossplane GitOps".7name: crossplane-specialist-38metadata:9 source: https://skillmd.com/skills/kaiohenricunha/crossplane-specialist-310---1112# Crossplane Specialist1314Structured investigation for Crossplane-based infrastructure platforms. Five phases:15gather context, diagnose, design, recommend, verify.1617## Arguments1819- `$0` — XRD name, Claim name, or problem description. Required.2021---2223## Phase 1: Context Gathering24251. List installed providers and packages:26 ```bash27 kubectl get providers28 kubectl get configurations29 kubectl get functions30 ```312. List XRDs and their ready status:32 ```bash33 kubectl get xrd34 ```353. List Claims and Composites:36 ```bash37 kubectl get composite --all-namespaces38 kubectl get claim --all-namespaces39 ```404. Glob for Crossplane manifests in the working directory:41 ```bash42 find . -name "*.yaml" | xargs grep -l "apiVersion: apiextensions.crossplane.io" | sort43 ```4445---4647## Phase 2: Diagnosis4849**Stuck Claim / Composite trace:**5051```bash52kubectl describe claim <name> -n <namespace>53kubectl describe composite <name>54kubectl get managed --all-namespaces | grep -v "True"55kubectl describe <managed-resource-kind> <name>56```5758**Provider health:**5960```bash61kubectl describe provider <name>62kubectl get providerconfig63kubectl describe providerconfig <name>64```6566**Composition pipeline:**6768```bash69kubectl get composition <name> -o yaml70kubectl get function --all-namespaces71```7273---7475## Phase 3: Design / Root-Cause Analysis7677Map symptoms to causes:7879| Symptom | Common Causes | Check |80| --------------------------- | ----------------------------------------------------- | ---------------------------------------------- |81| Claim stuck `Waiting` | Composite not ready, no matching Composition | `kubectl describe composite` → events |82| Managed resource `NotFound` | Wrong external-name annotation, ID mismatch | Provider docs for external-name format |83| Provider `Unhealthy` | Bad credentials, missing `ProviderConfig` | `kubectl describe provider` events |84| Composition patch fails | Wrong `fromFieldPath`, type mismatch | `kubectl get composite -o yaml` patched fields |85| Function pipeline error | Function pod crash, malformed `FunctionIO` | `kubectl logs -n crossplane-system` function |86| Deletion stuck (finalizer) | Managed resource `Delete` policy, cloud resource busy | Check deletion policy + cloud console |8788Cite `kind:name` or `file:line` for every finding.8990---9192## Phase 4: Recommendations9394Output findings in priority order:9596```97[CRITICAL] <title>98Resource: <kind:name or file:line>99Issue: <one sentence>100Evidence: <kubectl output or config snippet>101Fix: <specific change, with YAML diff if applicable>102Trade-off: <alternative and its downside, if meaningful>103```104105Order: CRITICAL → WARNING → INFO.106107---108109## Phase 5: Verification110111After fixes are applied:1121131. `kubectl get composite <name>` — `READY: True`, `SYNCED: True`.1142. `kubectl get managed` — all managed resources show `READY: True`.1153. `kubectl describe claim <name>` — no error events.1164. `kubectl apply --dry-run=server -f composition.yaml` — no schema errors.1175. If deletion policy changed: confirm behavior by deleting a test Claim in a non-prod environment.118119---120121## Reference Docs122123| File | When to use |124| ----------------------- | --------------------------------------------------------- |125| `xrd-design.md` | XRD schema design, versioning, validation rules |126| `compositions.md` | Composition patch-and-transform, pipeline mode, Functions |127| `provider-configs.md` | Credential injection, `ProviderConfig` patterns |128| `managed-resources.md` | External-name, deletion policy, resource lifecycle |129| `gitops-integration.md` | Argo CD / Flux health checks, package management |