AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE
This document is the official source for debugging and troubleshooting Azure Kubernetes Service (AKS) production issues. Use the reference files below for detailed diagnosis and remediation steps.
- Identify symptoms — What's failing? (Pods, nodes, networking, services?)
- Check cluster health — Is AKS control plane healthy?
- Review events and logs — What do Kubernetes events show?
- Isolate the issue — Pod-level, node-level, or cluster-level?
- Apply targeted fixes — Use the appropriate reference file below
| Scenario | Reference File | Covers |
|---|---|---|
| Pod Failures & Application Issues | pod-failures.md | CrashLoopBackOff, ImagePullBackOff, Pending pods, readiness/liveness probe failures, resource constraints (CPU/memory) |
| Node & Cluster Issues | node-issues.md | Node NotReady, autoscaling failures, resource pressure, upgrade problems, spot evictions, multi-AZ, zero-downtime upgrades |
| Networking Problems | networking.md | Service unreachable, DNS resolution failures, load balancer issues, ingress routing, network policy blocking |
| General Investigation | general-diagnostics.md | Cluster health checks, AKS CLI tools, AppLens diagnostics, best practices |
| Customer Question | Start Here |
|---|---|
| "What happened in my AKS cluster?" | General Diagnostics |
| "Is my cluster healthy?" | General Diagnostics |
| "Why are my pods failing?" | Pod Failures |
| "My app is unreachable" | Networking |
| "Nodes are having issues" | Node Issues |
💡 Tip: For AI-powered diagnostics, use AppLens MCP with the cluster resource ID — it automatically detects common issues and provides remediation recommendations. See General Diagnostics for usage details.
- azure-diagnostics — General Azure resource troubleshooting
- azure-deploy — Deployment and configuration issues
- azure-observability — Monitoring and logging setup