How to Enable Parallel Kubelet Image Pulling

Kubelet image pulls are serialized by default unless configured otherwise. During a new platform installation or an application version upgrade initiated through the Swimlane Admin Console (KOTS), pulling many large container images sequentially can extend the deployment window.

This procedure configures kubelet to allow concurrent image pulls by setting serializeImagePulls: false and limiting concurrency with maxParallelImagePulls: 5. This can reduce image download time when the registry, network, node resources, and container runtime can sustain parallel downloads.

Connect to the Kubernetes node using SSH and obtain root privileges, or use sudo.

Create a dated backup of the current kubelet configuration:

sudo cp /var/lib/kubelet/config.yaml /var/lib/kubelet/config.yaml.bak-$(date +%F)

Confirm that the backup exists before editing the original file:

sudo ls -l /var/lib/kubelet/config.yaml*

Open the kubelet configuration file:

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

Locate the cgroupDriver setting. Add the two image-pull settings at the same YAML indentation level as cgroupDriver. Do not add duplicate keys if either setting already exists; update the existing value instead.

The relevant section should look like this: cgroupDriver: systemd serializeImagePulls: false maxParallelImagePulls: 5 clusterDNS:

The example shows top-level keys. Preserve the indentation and structure used by the existing file. YAML indentation is significant; use spaces, not tabs. Do not change unrelated kubelet settings.

Save and exit vi:

:wq

Before restarting kubelet, review the edited section and check that the file contains only one occurrence of each setting:

sudo grep -nE '^(cgroupDriver|serializeImagePulls|maxParallelImagePulls):' /var/lib/kubelet/config.yaml

Kubelet validates its configuration when it starts. Restart kubelet to apply the updated settings:

sudo systemctl restart kubelet

Restarting containerd is not normally required for this kubelet configuration change. Avoid restarting the container runtime unless there is a separate operational reason or your platform-specific procedure explicitly requires it.

sudo systemctl status kubelet --no-pager

If kubelet fails to start, inspect the service logs:

sudo journalctl -u kubelet -xe --no-pager

Common causes include invalid YAML indentation, duplicate or misspelled keys, or a kubelet version that does not recognize the configured field. Correct the configuration and restart kubelet again.

kubectl get nodes

Confirm that the node returns to Ready. In a multi-node cluster, repeat the configuration and verification procedure on each applicable node, one node at a time.

During a deployment or image-pull operation, inspect recent cluster events:

kubectl get events -A --sort-by=.metadata.creationTimestamp | grep -i 'Pulling image'

The events can help identify image-pull activity, but they do not by themselves prove that downloads overlapped in time. To validate the behavior, compare timestamps and container runtime or kubelet logs for multiple image pulls on the same node. Also compare deployment duration before and after the change under similar conditions.

If parallel image pulling causes resource pressure or other operational issues, restore the previous configuration or explicitly return kubelet to serialized image pulling.

Use the dated backup created before the change. Replace the date below with the actual backup suffix on the node:

sudo cp /var/lib/kubelet/config.yaml.bak-YYYY-MM-DD /var/lib/kubelet/config.yaml

Alternatively, edit the file and set the values as follows:

serializeImagePulls: true

Remove maxParallelImagePulls if you are restoring the original sequential behavior, or follow the configuration requirements for the Kubernetes version in use.

sudo systemctl restart kubelet sudo systemctl status kubelet --no-pager kubectl get nodes

Confirm that kubelet is active and the node has returned to Ready before proceeding to another node.

With parallel image pulling enabled, kubelet can initiate multiple image pulls concurrently on a node, up to the configured limit and subject to available resources and runtime behavior. This can shorten application installation and upgrade times when image downloads are a significant part of the deployment process.