Common Kubernetes Deployment Issues and How to Fix

This document refers to the most common Kubernetes deployment problems, their likely causes, and steps to fix them.

1. ImagePullBackOff / ErrImagePull

Problem:

The pod cannot pull the container image.

Possible Causes:

• Incorrect image name or tag
• Image is hosted in a private registry without authentication
• Rate limiting on public registries (e.g., DockerHub)

How to Fix:

• Check the image name and tag using kubectl describe pod <pod-name>
• If using a private registry, create and apply an imagePullSecret:

kubectl create secret docker-registry myregistrykey \
  --docker-username=<user> \
  --docker-password=<password> \
  --docker-server=<registry>

Add to your pod or deployment:

imagePullSecrets:
  - name: myregistrykey

2. CrashLoopBackOff

Problem:

The container is repeatedly crashing and restarting.

Possible Causes:

• The application inside the container is exiting unexpectedly
• Invalid configuration or environment variables
• Failing liveness or readiness probes

How to Fix:

• Retrieve logs with:

  kubectl logs <pod-name> --previous

• Verify entrypoint, startup scripts, and environment variables
• Use initContainers if dependencies need to be initialized first

3. Pending Pods

Problem:

• Pods remain in a Pending state and are not scheduled.

Possible Causes:

• Requested resources (CPU, memory, GPU) exceed what’s available
• Taints on nodes prevent scheduling
• Affinity or anti-affinity rules cannot be satisfied

How to Fix:

• Describe the pod:

  kubectl describe pod <pod-name>

• Adjust resource requests/limits or scale your cluster
• Add tolerations to your pod spec if needed:

  tolerations:
    - key: "example"
      operator: "Exists"
      effect: "NoSchedule"

4. Service Not Reachable

Problem:

A pod or service cannot connect to another service using its DNS name.

Possible Causes:

• Incorrect service selectors
• No matching pods (endpoints list is empty)
• DNS resolution issues

How to Fix:

• Check the service:

  kubectl describe svc <svc-name>

• Make sure the pods have labels that match the service selector
• Verify the service has active endpoints:

  kubectl get endpoints <svc-name>

5. ConfigMap or Secret Not Found

Problem:

Pod startup fails due to missing ConfigMap or Secret.

Possible Causes:

• The ConfigMap or Secret doesn't exist
• Typo in the resource name
• Resource exists in a different namespace

How to Fix:

• Ensure the ConfigMap or Secret is created in the correct namespace
• Validate the names and keys used in the pod spec

6. Liveness or Readiness Probe Failures

Problem:

Probes fail, causing the pod to restart or remain unready.

Possible Causes:

• Application takes time to become ready
• Incorrect path or port specified
• Probes are too aggressive

How to Fix:

• Add initialDelaySeconds and adjust probe intervals:

  initialDelaySeconds: 10
  periodSeconds: 5

• Validate the health endpoint inside the container is working

7. Deployment Not Updating

Problem:

Changes to the deployment do not result in new pods being created.

Possible Causes:

• No actual changes in the pod template
• Deployment rollout is paused

How to Fix:

• Ensure the pod spec changes (e.g., image tag, env var)
• Force a rollout if needed:

kubectl rollout restart deployment <deployment-name>

8. PVC Pending

Problem:

PersistentVolumeClaim (PVC) remains in Pending state.

Possible Causes:

• No available PersistentVolume (PV)
• StorageClass does not exist or does not match
• Mismatch in requested size or access mode

How to Fix:

• Check available PVs and StorageClasses:

  kubectl get pv
  kubectl get storageclass

• Ensure a PV with matching size, access mode, and storage class exists

9. Node Pressure (Disk/CPU/Memory)

Problem:

Pods are evicted or not scheduled due to node resource constraints.

Possible Causes:

• Node is under resource pressure
• Kubelet evicts pods when thresholds are breached

How to Fix:

• Inspect node status:

  kubectl describe node <node-name>

• Free up resources or reschedule workloads
• Tune kubelet eviction settings if necessary

10. RBAC Permission Denied

Problem:

Service account or user is denied permission for an action.

Possible Causes:

• Missing Role or ClusterRole
• No RoleBinding or ClusterRoleBinding assigned

How to Fix:

• Test access using:

  kubectl auth can-i get pods --as=system:serviceaccount:<namespace>:<service-account>

• Apply the appropriate Role or ClusterRole and bind it to the service account