This guide addresses “Docker Timeout Error” occurring during image pull on Kubernetes Pods.

---

Troubleshooting: Docker Timeout Error on Kubernetes Pod

1. The Root Cause

When a Kubernetes Pod is scheduled on a node, the Kubelet component attempts to pull the necessary container images. A “Docker Timeout Error” frequently arises when the Kubelet’s configured imagePullProgressDeadline is exceeded before an image download completes, often due to network latency, large image sizes, or slow registry response times.

2. Quick Fix (CLI)

This fix involves directly editing the Kubelet configuration on the problematic Kubernetes node to extend the image pull deadline.

1. SSH into the affected Kubernetes node:

   ssh user@your-kubernetes-node-ip

2. Locate the Kubelet configuration file: (Common paths include /etc/kubernetes/kubelet.conf or /var/lib/kubelet/config.yaml. To find the exact path specified in the Kubelet systemd service unit, run):

   systemctl cat kubelet | grep -E 'config|--config'

3. Edit the configuration file (e.g., using vi or nano, substitute with your actual path):

   sudo vi /var/lib/kubelet/config.yaml 

4. Add or modify imagePullProgressDeadline: Inside the YAML file, ensure imagePullProgressDeadline is set to a higher value. The default is 5 minutes (5m). For example, to set it to 10 minutes (10m):

   # ... other Kubelet configurations
   apiVersion: kubelet.config.k8s.io/v1beta1
   kind: KubeletConfiguration
   imagePullProgressDeadline: 10m # Increase to 10 minutes
   # ...

5. Restart the Kubelet service:

   sudo systemctl daemon-reload
   sudo systemctl restart kubelet

3. Configuration Check

The critical configuration to inspect and modify is within the Kubelet’s primary configuration file, typically located at /var/lib/kubelet/config.yaml or /etc/kubernetes/kubelet.conf. Ensure the imagePullProgressDeadline field is present and its value is set to a duration greater than the default 5 minutes (e.g., 10m, 15m) to accommodate slower image downloads. This change must be applied to all relevant nodes experiencing the issue.

4. Verification

After applying the fix and restarting the Kubelet service, monitor the problematic Pod’s status and events.

1. Check Pod events for successful image pull:

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

   Look for events indicating a successful Pulled or Created container image.
2. Monitor Pod status:

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

   Confirm the Pod transitions to Running or a healthy state.