Installation using kubeadm

This guide describes deploying Cilium on a Kubernetes cluster created with kubeadm.

For installing kubeadm on your system, please refer to the official kubeadm documentation The official documentation also describes additional options of kubeadm which are not mentioned here.

If you are interested in using Cilium’s kube-proxy replacement, please follow the Kubernetes without kube-proxy guide and skip this one.

Create the cluster

Initialize the control plane via executing on it:

kubeadm init


If you want to use Cilium’s kube-proxy replacement, kubeadm needs to skip the kube-proxy deployment phase, so it has to be executed with the --skip-phases=addon/kube-proxy option:

kubeadm init --skip-phases=addon/kube-proxy

For more information please refer to the Kubernetes without kube-proxy guide.

Afterwards, join worker nodes by specifying the control-plane node IP address and the token returned by kubeadm init:

kubeadm join <..>

Deploy Cilium


First, make sure you have Helm 3 installed.

If you have (or planning to have) Helm 2 charts (and Tiller) in the same cluster, there should be no issue as both version are mutually compatible in order to support gradual migration. Cilium chart is targeting Helm 3 (v3.0.3 and above).

Download the Cilium release tarball and change to the kubernetes install directory:

curl -LO
tar xzf master.tar.gz
cd cilium-master/install/kubernetes

Deploy Cilium release via Helm:

helm install cilium |CHART_RELEASE| --namespace kube-system

Validate the Installation

You can monitor as Cilium and all required components are being installed:

kubectl -n kube-system get pods --watch
NAME                                    READY   STATUS              RESTARTS   AGE
cilium-operator-cb4578bc5-q52qk         0/1     Pending             0          8s
cilium-s8w5m                            0/1     PodInitializing     0          7s
coredns-86c58d9df4-4g7dd                0/1     ContainerCreating   0          8m57s
coredns-86c58d9df4-4l6b2                0/1     ContainerCreating   0          8m57s

It may take a couple of minutes for all components to come up:

cilium-operator-cb4578bc5-q52qk         1/1     Running   0          4m13s
cilium-s8w5m                            1/1     Running   0          4m12s
coredns-86c58d9df4-4g7dd                1/1     Running   0          13m
coredns-86c58d9df4-4l6b2                1/1     Running   0          13m

Deploy the connectivity test

You can deploy the “connectivity-check” to test connectivity between pods. It is recommended to create a separate namespace for this.

kubectl create ns cilium-test

Deploy the check with:

kubectl apply -n cilium-test -f

It will deploy a series of deployments which will use various connectivity paths to connect to each other. Connectivity paths include with and without service load-balancing and various network policy combinations. The pod name indicates the connectivity variant and the readiness and liveness gate indicates success or failure of the test:

$ kubectl get pods -n cilium-test
NAME                                                     READY   STATUS    RESTARTS   AGE
echo-a-76c5d9bd76-q8d99                                  1/1     Running   0          66s
echo-b-795c4b4f76-9wrrx                                  1/1     Running   0          66s
echo-b-host-6b7fc94b7c-xtsff                             1/1     Running   0          66s
host-to-b-multi-node-clusterip-85476cd779-bpg4b          1/1     Running   0          66s
host-to-b-multi-node-headless-dc6c44cb5-8jdz8            1/1     Running   0          65s
pod-to-a-79546bc469-rl2qq                                1/1     Running   0          66s
pod-to-a-allowed-cnp-58b7f7fb8f-lkq7p                    1/1     Running   0          66s
pod-to-a-denied-cnp-6967cb6f7f-7h9fn                     1/1     Running   0          66s
pod-to-b-intra-node-nodeport-9b487cf89-6ptrt             1/1     Running   0          65s
pod-to-b-multi-node-clusterip-7db5dfdcf7-jkjpw           1/1     Running   0          66s
pod-to-b-multi-node-headless-7d44b85d69-mtscc            1/1     Running   0          66s
pod-to-b-multi-node-nodeport-7ffc76db7c-rrw82            1/1     Running   0          65s
pod-to-external-1111-d56f47579-d79dz                     1/1     Running   0          66s
pod-to-external-fqdn-allow-google-cnp-78986f4bcf-btjn7   0/1     Running   0          66s


If you deploy the connectivity check to a single node cluster, pods that check multi-node functionalities will remain in the Pending state. This is expected since these pods need at least 2 nodes to be scheduled successfully.

Enable Hubble

Hubble is a fully distributed networking and security observability platform for cloud native workloads. It is built on top of Cilium and eBPF to enable deep visibility into the communication and behavior of services as well as the networking infrastructure in a completely transparent manner.

  • Hubble can be configured to be in distributed mode or local mode.

    In distributed mode, Hubble listens on a TCP port on the host network. This allows Hubble Relay to communicate with all the Hubble instances in the cluster. Hubble CLI and Hubble UI in turn connect to Hubble Relay to provide cluster-wide networking visibility.


    In Distributed mode, Hubble runs a gRPC service over HTTP on the host network. It is secured using mutual TLS (mTLS) by default to only allow access to Hubble Relay. Refer to Use custom TLS certificates in distributed mode to manually provide TLS certificates.

    helm upgrade cilium ./cilium \
       --namespace $CILIUM_NAMESPACE \
       --reuse-values \
       --set hubble.enabled=true \
       --set hubble.listenAddress=":4244" \
       --set hubble.metrics.enabled="{dns,drop,tcp,flow,port-distribution,icmp,http}" \
       --set hubble.relay.enabled=true \
       --set hubble.ui.enabled=true

    In local mode, Hubble listens on a UNIX domain socket. You can connect to a Hubble instance by running hubble command from inside the Cilium pod. This provides networking visibility for traffic observed by the local Cilium agent.

    helm upgrade cilium ./cilium \
       --namespace $CILIUM_NAMESPACE \
       --reuse-values \
       --set hubble.enabled=true \
       --set hubble.metrics.enabled="{dns,drop,tcp,flow,port-distribution,icmp,http}"
  • Restart the Cilium daemonset to allow Cilium agent to pick up the ConfigMap changes:

    kubectl rollout restart -n $CILIUM_NAMESPACE ds/cilium
  • To pick one Cilium instance and validate that Hubble is properly configured to listen on a UNIX domain socket:

    kubectl exec -n $CILIUM_NAMESPACE -t ds/cilium -- hubble observe
  • (Distributed mode only) To validate that Hubble Relay is running, install the hubble CLI:

    Download the latest hubble release:

    export HUBBLE_VERSION=$(curl -s
    curl -LO "$HUBBLE_VERSION/hubble-linux-amd64.tar.gz"
    curl -LO "$HUBBLE_VERSION/hubble-linux-amd64.tar.gz.sha256sum"
    sha256sum --check hubble-linux-amd64.tar.gz.sha256sum
    tar zxf hubble-linux-amd64.tar.gz

    and move the hubble CLI to a directory listed in the $PATH environment variable. For example:

    sudo mv hubble /usr/local/bin

    Download the latest hubble release:

    export HUBBLE_VERSION=$(curl -s
    curl -LO "$HUBBLE_VERSION/hubble-darwin-amd64.tar.gz"
    curl -LO "$HUBBLE_VERSION/hubble-darwin-amd64.tar.gz.sha256sum"
    shasum -a 256 -c hubble-darwin-amd64.tar.gz.sha256sum
    tar zxf hubble-darwin-amd64.tar.gz

    and move the hubble CLI to a directory listed in the $PATH environment variable. For example:

    sudo mv hubble /usr/local/bin

    Download the latest hubble release:

    curl -LO ""
    set /p HUBBLE_VERSION=<stable.txt
    curl -LO ""
    curl -LO ""
    certutil -hashfile hubble-windows-amd64.tar.gz SHA256
    type hubble-windows-amd64.tar.gz.sha256sum
    :: verify that the checksum from the two commands above match
    tar zxf hubble-windows-amd64.tar.gz

    and move the hubble.exe CLI to a directory listed in the %PATH% environment variable after extracting it from the tarball.

    Once the hubble CLI is installed, set up a port forwarding for hubble-relay service and run hubble observe command:

    kubectl port-forward -n $CILIUM_NAMESPACE svc/hubble-relay --address --address :: 4245:80
    hubble observe --server localhost:4245

    (For Linux / MacOS) For convenience, you may set and export the HUBBLE_DEFAULT_SOCKET_PATH environment variable:

    export HUBBLE_DEFAULT_SOCKET_PATH=localhost:4245

    This will allow you to use hubble status and hubble observe commands without having to specify the server address via the --server flag.

  • (Distributed mode only) To validate that Hubble UI is properly configured, set up a port forwarding for hubble-ui service:

    kubectl port-forward -n $CILIUM_NAMESPACE svc/hubble-ui --address --address :: 12000:80

    and then open http://localhost:12000/.