Troubleshooting
Diagnostic Commands
Gather diagnostic information before investigating issues:
# Platform status
butleradm status
# Controller logs
kubectl logs -n butler-system deploy/butler-controller --tail=100
# All Butler pods
kubectl get pods -n butler-system
# TenantCluster status and conditions
kubectl describe tenantcluster <name> -n <namespace>
# Recent events
kubectl get events -n <namespace> --sort-by='.lastTimestamp'
Issues by Area
| Area | Common Problems |
|---|---|
| Bootstrap | KIND cluster hangs, provider connectivity, VM provisioning failures |
| Cluster Provisioning | Stuck in Provisioning, workers not joining, control plane issues |
| Networking | MetalLB not assigning IPs, IPAM allocation failures, DNS issues |
| Addons | Cilium not starting, Helm chart failures, addon stuck in Installing |
Enable Debug Logging
kubectl set env deploy/butler-controller -n butler-system LOG_LEVEL=debug