k8s | aks debug

This is a fast, practical cheat sheet for debugging basics in Kubernetes and AKS. It includes core concepts plus a strict, ordered flow to isolate issues quickly.

---

Quick Concepts (Cluster, Namespace, Pod, Service, Ingress)

• Cluster: The full Kubernetes environment. Think of it as the logical “datacenter” where all resources live. In AKS, each cluster is its own managed control plane.
• Namespace: A logical partition inside a cluster. Use it to separate environments (dev, qa, prod), teams, or apps. A single cluster can host multiple namespaces.
• Pod: The smallest execution unit. A pod can run one or more containers that deploy and scale together.
• Deployment: Manages pod replicas and rolling updates. If a pod dies, the deployment creates a new one.
• Service: Exposes a stable endpoint for a set of pods and load‑balances traffic to them.
• Ingress: HTTP/HTTPS routing rules. Maps domains and paths to services.

---

1. Check which cluster you are connected to

Show current context:

kubectl config current-context

List all contexts:

kubectl config get-contexts

Switch to another cluster/context:

kubectl config use-context <context-name>

---

2. Connect to an AKS cluster (if context does not exist)

Check current subscription:

az account show

Switch subscription:

az account set --subscription "<subscription-id-or-name>"

Download cluster credentials:

az aks get-credentials \
  -g <resource-group> \
  -n <cluster-name> \
  --overwrite-existing

---

3. Work with namespaces

List namespaces:

kubectl get ns

List pods in a namespace:

kubectl get pods -n <namespace>

Tip: If you always work in a specific namespace, set it on the current context:

kubectl config set-context --current --namespace=<namespace>

---

4. Inspect pods

List pods:

kubectl get pods -n <namespace>

Describe a pod:

kubectl describe pod <pod-name> -n <namespace>

---

5. View logs

Stream logs from a pod:

kubectl logs -f <pod-name> -n <namespace>

Stream logs from a deployment:

kubectl logs -f deployment/<deployment-name> -n <namespace>

If a pod has multiple containers:

kubectl logs -f <pod-name> -c <container-name> -n <namespace>

---

6. Check services

List services:

kubectl get svc -n <namespace>

Check endpoints (which pods a service points to):

kubectl get endpoints -n <namespace>

---

7. Check ingress rules (important for APIs)

List ingress:

kubectl get ingress -n <namespace>

Show ingress routing details:

kubectl describe ingress -n <namespace>

Look for:

• Paths
• Backend services
• Rewrite rules

These determine the real API URLs.

---

8. View ingress controller logs

Useful when requests are not reaching the backend:

kubectl logs -f <ingress-pod-name> -n <namespace>

---

9. Test a backend directly (very useful)

Forward a port from a pod:

kubectl port-forward pod/<pod-name> <local-port>:<container-port> -n <namespace>

Then test locally:

curl http://127.0.0.1:<local-port>

This bypasses ingress and networking issues.

---

10. Quick troubleshooting checklist

When something is not working, debug in this order:

1. Am I connected to the correct cluster?
2. Am I using the correct namespace?
3. Is the pod in Running state?
4. Does the service point to the pod?
5. Does ingress have the correct path?
6. Does the request reach ingress?
7. Does the request reach the backend?

---

11. Quick rule for debugging requests

If no logs appear:

• Not in ingress logs → request never reached the cluster.
• In ingress logs but not backend → routing issue.
• In backend logs → application issue.

This helps isolate problems quickly.