How to debug AKS pods
Start by identifying the pod state, then follow the appropriate debugging path:
- View logs
- Shell access
- Port-forward
# Follow logs for a specific pod
kubectl logs -n internal-platform <pod-name> -f
# Logs for all pods with a label
kubectl logs -n internal-platform -l app=astra-backend --tail=100
# Previous container logs (after crash)
kubectl logs -n internal-platform <pod-name> --previous
# Open a shell in a running pod
kubectl exec -n internal-platform -it <pod-name> -- /bin/sh
# Run a single command
kubectl exec -n internal-platform <pod-name> -- env | grep DATABASE
# Forward a service port to localhost
kubectl port-forward -n internal-platform svc/astra-backend 8081:8081
# Forward PostgreSQL
kubectl port-forward -n internal-platform svc/internal-pg 5433:5432
Common errors
Pod stuck in Pending
- Check:
kubectl describe pod -n <ns> <pod>— look for scheduling errors - Common cause: Insufficient resources on nodes
Pod in CrashLoopBackOff
- Check:
kubectl logs -n <ns> <pod> --previous— see crash output - Common cause: Missing environment variables or database connection failure
Pod in ImagePullBackOff
- Check:
kubectl describe pod -n <ns> <pod>— look for ACR auth errors - Fix:
az acr login --name aucertacr41e0x5
Pod running but returning errors
# Live log stream
kubectl logs -n <ns> <pod-name> -f
# Check environment variables are set correctly
kubectl exec -n <ns> <pod-name> -- env | sort
# Check if the pod can reach dependent services
kubectl exec -n <ns> <pod-name> -- curl -s http://localhost:8080/health
Quick reference
| Command | Purpose |
|---|---|
kubectl get pods -n <ns> | List pod status |
kubectl describe pod -n <ns> <pod> | Detailed pod info + events |
kubectl logs -n <ns> <pod> -f | Stream live logs |
kubectl logs -n <ns> <pod> --previous | Logs from crashed container |
kubectl exec -n <ns> -it <pod> -- /bin/sh | Shell into pod |
kubectl port-forward -n <ns> svc/<svc> <local>:<remote> | Forward port |
kubectl top pod -n <ns> | CPU/memory usage |
What's next
- How to deploy to dev — Deployment process
- How to update Helm charts — Configuration changes