Introduction

Installing a kubeadm-based Kubernetes cluster behind a proxy is mostly an environment-configuration problem. kubeadm, the container runtime, kubelet, the OS package manager, and sometimes image pulls all need consistent proxy settings, while internal cluster traffic must bypass the proxy through a carefully built NO_PROXY list.

That last part is where most installations fail. If pod CIDRs, service CIDRs, node IPs, or internal hostnames are missing from NO_PROXY, cluster components may try to talk to each other through the proxy and break in confusing ways.

Set the Proxy Variables Consistently

At a minimum, you usually need:

• 'HTTP_PROXY'
• 'HTTPS_PROXY'
• 'NO_PROXY'

A typical shape looks like this:

export HTTP_PROXY=http://proxy.example.com:3128
export HTTPS_PROXY=http://proxy.example.com:3128
export NO_PROXY=127.0.0.1,localhost,10.96.0.0/12,10.244.0.0/16,192.168.0.0/16,.cluster.local

The exact CIDRs and hostnames depend on your cluster design, but NO_PROXY usually needs to include:

• localhost entries
• node IP ranges
• service CIDR
• pod CIDR
• cluster DNS suffix such as .cluster.local

Configure the Container Runtime

The container runtime must be able to pull images through the proxy. For example, with containerd you typically set proxy environment variables in its systemd service configuration.

A common pattern is a systemd drop-in:

1[Service]
2Environment="HTTP_PROXY=http://proxy.example.com:3128"
3Environment="HTTPS_PROXY=http://proxy.example.com:3128"
4Environment="NO_PROXY=127.0.0.1,localhost,10.96.0.0/12,10.244.0.0/16,192.168.0.0/16,.cluster.local"

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart containerd

If the runtime cannot reach registries through the proxy, kubeadm init will fail when pulling images.

Configure kubelet Too

kubelet may also need the same proxy variables. A similar systemd drop-in can be used for the kubelet service so it behaves consistently with the runtime.

Even if image pulls succeed, cluster bootstrap can still fail later if kubelet or node-level components route internal traffic incorrectly.

Prepare the Host Before Running kubeadm

Make sure the machine can:

• install packages through the proxy
• resolve DNS through the network path you expect
• pull the required Kubernetes images
• bypass the proxy for internal cluster addresses

It is often useful to test image pulling explicitly before bootstrap instead of discovering proxy issues deep inside kubeadm logs.

Run kubeadm init with Matching Network Settings

When you initialize the control plane, use pod-network settings that match the CNI you plan to install, and make sure those CIDRs are already reflected in NO_PROXY.

Example:

sudo kubeadm init --pod-network-cidr=10.244.0.0/16

If your chosen CNI uses a different pod CIDR, update both the kubeadm command and NO_PROXY accordingly.

The Most Common Failure Mode

The classic failure pattern is:

• external registry access works through the proxy
• internal cluster communication accidentally also goes through the proxy
• control plane or DNS components fail in strange ways

That happens because the proxy configuration is only half-right. The cluster needs both external proxy routing and strong internal bypass rules.

Common Pitfalls

• Setting HTTP_PROXY and HTTPS_PROXY but leaving NO_PROXY incomplete.
• Forgetting to configure the container runtime and configuring only the shell environment.
• Using pod or service CIDRs in kubeadm that do not match the values excluded from the proxy.
• Debugging kubeadm itself when the real problem is image pull or internal routing behavior at the host level.

Summary

• Installing kubeadm behind a proxy is mainly about consistent host and service proxy configuration.
• Configure the package manager, container runtime, and kubelet, not just your login shell.
• Build NO_PROXY carefully with localhost, node IPs, service CIDR, pod CIDR, and cluster-local names.
• Make sure your chosen pod network settings match the addresses excluded from the proxy.
• Most failures come from incomplete proxy bypass rules, not from kubeadm itself.