Kubernetes Troubleshooting Guide: Diagnosing Pod, Service, and Ingress Issues

This article presents a systematic troubleshooting workflow for Kubernetes clusters, focusing on the three core resources — Pods, Services, and Ingresses — and offers concrete command‑line checks, explanations of typical failure states, and references to official documentation.

Key terminology : Pod (the smallest deployable unit), Port‑forward, Service (an abstraction for a set of Pods), Ingress (external HTTP/HTTPS routing), PersistentVolumeClaim (PVC), ResourceQuota, and related concepts.

Pod module checks :

Verify no Pods are in PENDING state with kubectl get pods.

Inspect resource limits via kubectl describe resourcequota -n <namespace> and adjust or expand resources if needed.

Check PVC status; if PENDING, consult the PersistentVolume documentation.

Confirm Pods are scheduled to a node using kubectl get pods -o wide.

Ensure Pods reach RUNNING and READY states; otherwise examine logs with kubectl logs <pod-name> or kubectl logs <pod-name> --previous.

Handle specific error states such as ImagePullBackOff, CrashLoopBackOff, and RunContainerError by checking image names, tags, registry credentials, Dockerfile CMD, and volume mounts.

Validate readiness probes and liveness configurations when Pods repeatedly restart.

[root@10-186-65-37 ~]# kubectl get pods
NAME                               READY   STATUS    RESTARTS   AGE
myapp-deploy-55b54d55b8-5msx8    1/1     Running   0          14d

Service module checks :

Describe the Service to verify its Endpoints and TargetPort using kubectl describe service <service-name>.

Match Service selectors with Pod labels to ensure correct routing.

Confirm Pods have assigned IPs; missing IPs indicate controller‑manager issues.

If TargetPort and container Port differ, correct the Service or Pod specification.

[root@10-186-65-37 ~]# kubectl describe service myapp
Name:              myapp
Namespace:         default
Type:              ClusterIP
IP:                10.96.109.76
Port:              http  80/TCP
TargetPort:        80/TCP
Endpoints:         10.244.2.10:80,10.244.3.9:80,10.244.4.10:80

Ingress module checks :

Describe the Ingress to verify backend services and TLS configuration with kubectl describe ingress <ingress-name>.

Ensure the Ingress ServiceName and ServicePort match the corresponding Service.

Test port‑forwarding to the Ingress pod and external access; if failing, investigate the Ingress controller documentation.

[root@10-186-65-37 ~]# kubectl describe ingress ingress-tomcat-tls
Name:             ingress-tomcat-tls
Namespace:        default
Rules:
  Host               Path  Backends
  tomcat.quan.com    /    tomcat:8080 (10.244.2.11:8080,10.244.4.11:8080)

Throughout the guide, each step includes example command outputs and links to official Kubernetes documentation for deeper investigation.