How to Debug Kubernetes Deployments, Services, and Ingress Step‑by‑Step

This guide explains how to troubleshoot a Kubernetes Deployment by examining the three core resources – Deployment, Service, and Ingress – and how they interconnect through labels and ports.

Core Components

Deployment : declares the desired number of Pod replicas and updates them.

Service : provides a stable virtual IP and selects Pods via label selectors; it forwards traffic to the Pods' containerPort using targetPort.

Ingress : defines external HTTP(S) routing rules that point to a Service by name and port.

Example YAML for a Hello‑World Application

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  labels:
    track: canary
spec:
  selector:
    matchLabels:
      any-name: my-app
  template:
    metadata:
      labels:
        any-name: my-app
    spec:
      containers:
        - name: cont1
          image: learnk8s/app:1.0.0
          ports:
            - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  ports:
    - port: 80          # Service port exposed to clients
      targetPort: 8080  # Must match containerPort
  selector:
    any-name: my-app
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

Connecting Deployment and Service

There is no direct link between a Deployment and a Service. The Service selects Pods directly using its selector. Ensure that:

The Service selector matches at least one Pod label.

The Service targetPort equals the Pod container's containerPort.

Service port can be any number because each Service has its own ClusterIP.

Testing Service Connectivity

kubectl get pods --show-labels

Filter by a specific label:

kubectl get pods --selector any-name=my-app --show-labels

Port‑forward to the Service to verify traffic flow: kubectl port-forward service/my-service 3000:80 In this command, 3000 is the local port, 80 is the Service port, and my-service is the Service name.

Connecting Service and Ingress

The Ingress must reference the Service by name and by the Service port. Both must match exactly.

Three‑Step Debugging Process

Confirm that Pods are running and ready.

Verify that the Service correctly routes to those Pods (labels, ports, Endpoints).

Check that the Ingress configuration points to the correct Service name and port.

Pod Debugging Commands

kubectl get pods

kubectl logs <pod-name>

– view container logs. kubectl describe pod <pod-name> – see events, status, and detailed spec. kubectl get pod <pod-name> -o yaml – retrieve the full Pod definition. kubectl exec -ti <pod-name> -- /bin/bash – open an interactive shell inside the container.

Common Pod Errors and Quick Fixes

ImagePullBackOff – check image name, tag, and registry credentials (add a Secret for private registries).

CrashLoopBackOff – inspect logs; use kubectl logs <pod> --previous if the container restarts quickly.

RunContainerError – verify volume mounts, ConfigMaps, and Secrets.

Pending – ensure sufficient cluster resources, no ResourceQuota violations, and that any PVCs are bound.

NotReady – investigate failing readiness probes via kubectl describe pod.

Service Debugging

kubectl describe service my-service

If the Endpoints list is empty, either the Pods lack the matching label or the Service selector is misspelled. Use the same kubectl port-forward command to test connectivity.

Ingress Debugging

kubectl describe ingress my-ingress

Typical problems include mismatched service.name or service.port, or the Ingress controller not running. Retrieve the Ingress controller pod and forward a local port to it:

kubectl get pods --all-namespaces | grep ingress
kubectl describe pod nginx-ingress-controller-6fc5bcc --namespace kube-system | grep Ports
kubectl port-forward nginx-ingress-controller-6fc5bcc 3000:80 --namespace kube-system

For Nginx‑Ingress, the official kubectl plugin provides additional checks: kubectl ingress-nginx lint – validates the generated nginx.conf. kubectl ingress-nginx backend – inspects backend configuration. kubectl ingress-nginx logs – shows controller logs.

Port and Label Matching Summary

Service selector must match at least one Pod label.

Service targetPort must equal the Pod containerPort.

Service port can be any number; multiple Services may reuse the same port because they have distinct ClusterIPs.

Ingress service.name must equal the Service name.

Ingress service.port must equal the Service port.

Extending the Approach

The same three‑step methodology (Pod → Service → Ingress) applies to other workload types such as Jobs, CronJobs, StatefulSets, and DaemonSets.