Managing K8S Crossplane Deep

Crossplane Deep-Dive Skill

Advanced analysis of Crossplane compositions, provider internals, and infrastructure reconciliation.

MANDATORY: Discovery-First Pattern

Always check provider health and installed XRDs before deep-diving into resources.

Phase 1: Discovery

#!/bin/bash

echo "=== Crossplane Core ==="
kubectl get deployment crossplane -n crossplane-system -o custom-columns='NAME:.metadata.name,READY:.status.readyReplicas,IMAGE:.spec.template.spec.containers[0].image' 2>/dev/null

echo ""
echo "=== RBAC Manager ==="
kubectl get deployment crossplane-rbac-manager -n crossplane-system -o custom-columns='NAME:.metadata.name,READY:.status.readyReplicas' 2>/dev/null

echo ""
echo "=== Provider Health ==="
kubectl get providers.pkg.crossplane.io -o custom-columns='NAME:.metadata.name,INSTALLED:.status.conditions[?(@.type=="Installed")].status,HEALTHY:.status.conditions[?(@.type=="Healthy")].status,PACKAGE:.spec.package,REVISION:.status.currentRevision' 2>/dev/null

echo ""
echo "=== Functions ==="
kubectl get functions.pkg.crossplane.io -o custom-columns='NAME:.metadata.name,INSTALLED:.status.conditions[?(@.type=="Installed")].status,HEALTHY:.status.conditions[?(@.type=="Healthy")].status,PACKAGE:.spec.package' 2>/dev/null

echo ""
echo "=== XRDs ==="
kubectl get xrd -o custom-columns='NAME:.metadata.name,ESTABLISHED:.status.conditions[?(@.type=="Established")].status,OFFERED:.status.conditions[?(@.type=="Offered")].status,GROUP:.spec.group' 2>/dev/null

echo ""
echo "=== Compositions ==="
kubectl get compositions -o custom-columns='NAME:.metadata.name,XR-KIND:.spec.compositeTypeRef.kind,RESOURCES:.spec.resources' 2>/dev/null | head -15

Phase 2: Analysis

#!/bin/bash

echo "=== Managed Resources Not Ready ==="
kubectl get managed -o json 2>/dev/null | jq -r '
  .items[] |
  select(.status.conditions[]? | select(.type == "Ready" and .status != "True")) |
  "\(.kind)/\(.metadata.name)\tReady:\(.status.conditions[] | select(.type == "Ready") | "\(.status) \(.reason)")\tSynced:\(.status.conditions[] | select(.type == "Synced") | .status)"
' | head -20

echo ""
echo "=== Stale Resources (Synced=False) ==="
kubectl get managed -o json 2>/dev/null | jq -r '
  .items[] |
  select(.status.conditions[]? | select(.type == "Synced" and .status != "True")) |
  "\(.kind)/\(.metadata.name)\t\(.status.conditions[] | select(.type == "Synced") | .reason): \(.message // "no message")[0:80]"
' | head -15

echo ""
echo "=== Composite Resources ==="
for xrd in $(kubectl get xrd -o jsonpath='{.items[*].metadata.name}' 2>/dev/null); do
  KIND=$(kubectl get xrd "$xrd" -o jsonpath='{.spec.names.kind}' 2>/dev/null)
  kubectl get "$KIND" -o custom-columns="KIND:.kind,NAME:.metadata.name,READY:.status.conditions[?(@.type==\"Ready\")].status,COMPOSITION:.spec.compositionRef.name" 2>/dev/null | tail -n +2
done | head -15

echo ""
echo "=== Claims (all namespaces) ==="
kubectl get claim --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,KIND:.kind,NAME:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status' 2>/dev/null | head -15

echo ""
echo "=== Provider Config Health ==="
for provider in $(kubectl get providers.pkg.crossplane.io -o jsonpath='{.items[*].metadata.name}' 2>/dev/null); do
  kubectl get providerconfigs -l pkg.crossplane.io/package="$provider" 2>/dev/null | head -5
done

echo ""
echo "=== EnvironmentConfigs ==="
kubectl get environmentconfigs -o custom-columns='NAME:.metadata.name,AGE:.metadata.creationTimestamp' 2>/dev/null

echo ""
echo "=== Usages (dependency tracking) ==="
kubectl get usages -o custom-columns='NAME:.metadata.name,OF:.spec.of.kind,BY:.spec.by.kind' 2>/dev/null | head -10

echo ""
echo "=== Provider Pod Errors ==="
for pod in $(kubectl get pods -n crossplane-system -l pkg.crossplane.io/revision -o name 2>/dev/null); do
  echo "--- $pod ---"
  kubectl logs "$pod" -n crossplane-system --tail=5 2>/dev/null | grep -i "error\|cannot\|fail" | head -3
done

Output Format

• Target ≤50 lines per output
• Use -o custom-columns and jq for CRD field extraction
• Show Ready/Synced conditions prominently for all resources
• Group managed resources by provider/kind when many exist
• Never dump full composition YAML -- show compositeTypeRef and resource count

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Provider vs ProviderConfig: Provider is the package; ProviderConfig holds credentials -- both must be healthy
• Composition selection: Multiple compositions can match an XR -- use compositionSelector or compositionRef for determinism
• Patch types: FromCompositeFieldPath, ToCompositeFieldPath, CombineFromComposite -- wrong patch type causes silent failures
• Finalizer blocking: Deleting XRs deletes all composed resources -- stuck finalizers indicate provider issues
• Management policies: ObserveOnly, OrphanOnDelete -- understand lifecycle implications before changing
• Functions pipeline: Crossplane Functions (v1.14+) replace patch-and-transform -- check if compositions use pipeline mode
• DeploymentRuntimeConfig: Controls provider pod resources, replicas, and node selectors
• Dependency ordering: Use readinessChecks and Usages to handle resource dependencies