--- title: "How to Install Cilium CNI on Kubernetes with Hubble" description: "Install Cilium as the Kubernetes CNI with Helm, replace kube-proxy with eBPF, enforce L3 to L7 network policies and inspect dropped traffic with Hubble." category: "Kubernetes Ecosystem" language: en source: https://cubepath.com/docs/kubernetes-ecosystem/cilium-cni-installation-and-configuration updated: 2026-09-25 --- # How to Install Cilium CNI on Kubernetes with Hubble Cilium is a Container Network Interface (CNI) plugin for Kubernetes that uses eBPF in the Linux kernel to route pod traffic, load balance Services and enforce network policies, instead of long iptables chains. In this tutorial you will install Cilium with Helm on a kubeadm cluster running Ubuntu 24.04, let it replace kube-proxy, restrict traffic between pods with an HTTP-aware policy and use Hubble to see which flows are allowed and dropped. ## Prerequisites To follow this tutorial, you will need: - A Kubernetes cluster (1.30 or newer) built with kubeadm on Ubuntu 24.04 nodes, for example CubePath VPS instances with at least 2 vCPUs and 4 GB of RAM each. Ubuntu 24.04 ships kernel 6.8, which supports every feature used here. - The cluster initialized **without** a CNI and without kube-proxy. With kubeadm, pass `--skip-phases=addon/kube-proxy` to `kubeadm init`. Until a CNI is installed, nodes report `NotReady` and CoreDNS stays `Pending`, which is expected. - `kubectl` and Helm 3 installed on the machine you manage the cluster from, with a working kubeconfig. - The IP address and port of the Kubernetes API server (the address you passed as `--control-plane-endpoint` or the control plane node IP, port `6443`). This guide calls it `your_api_server_ip`. - If a host firewall runs on the nodes, these ports open between nodes: `8472/udp` (VXLAN), `4240/tcp` (health checks), `4244/tcp` (Hubble) and, for Step 6, `51871/udp` (WireGuard). ## Step 1 - Installing the Cilium CLI The `cilium` CLI checks the status of the installation, runs connectivity tests and manages Hubble. Download the latest stable release and verify its checksum: ```bash CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt) CLI_ARCH=amd64 if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi curl -L --fail --remote-name-all "https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz"{,.sha256sum} sha256sum --check "cilium-linux-${CLI_ARCH}.tar.gz.sha256sum" ``` ```output cilium-linux-amd64.tar.gz: OK ``` Extract the binary to `/usr/local/bin` and remove the archive: ```bash sudo tar xzvfC "cilium-linux-${CLI_ARCH}.tar.gz" /usr/local/bin rm "cilium-linux-${CLI_ARCH}.tar.gz"{,.sha256sum} ``` Confirm the CLI runs: ```bash cilium version --client ``` ```output cilium-cli: v0.18.x compiled with go1.24.x on linux/amd64 ``` ## Step 2 - Installing Cilium with Helm Add the official Helm repository: ```bash helm repo add cilium https://helm.cilium.io/ helm repo update ``` Because kube-proxy is not running, Cilium cannot reach the API server through the `kubernetes` Service ClusterIP during bootstrap. You give it the real address with `k8sServiceHost` and `k8sServicePort`, and set `kubeProxyReplacement=true` so Cilium implements Services in eBPF. Replace `your_api_server_ip` with your API server address: ```bash helm install cilium cilium/cilium \ --namespace kube-system \ --set kubeProxyReplacement=true \ --set k8sServiceHost=your_api_server_ip \ --set k8sServicePort=6443 \ --set hubble.relay.enabled=true \ --set hubble.ui.enabled=true ``` This installs the latest chart version. To pin a specific release, list them with `helm search repo cilium/cilium --versions` and add `--version` to the command. Wait until every component reports healthy: ```bash cilium status --wait ``` ```output Cilium: OK Operator: OK Envoy DaemonSet: OK Hubble Relay: OK ClusterMesh: disabled DaemonSet cilium Desired: 3, Ready: 3/3, Available: 3/3 Deployment cilium-operator Desired: 1, Ready: 1/1, Available: 1/1 Deployment hubble-relay Desired: 1, Ready: 1/1, Available: 1/1 Deployment hubble-ui Desired: 1, Ready: 1/1, Available: 1/1 ``` The nodes now switch to `Ready` and CoreDNS starts: ```bash kubectl get nodes kubectl -n kube-system get pods -l k8s-app=kube-dns ``` ```output NAME STATUS ROLES AGE VERSION k8s-cp1 Ready control-plane 25m v1.33.4 k8s-w1 Ready 22m v1.33.4 k8s-w2 Ready 22m v1.33.4 NAME READY STATUS RESTARTS AGE coredns-674b8bbfcf-8qv2x 1/1 Running 0 25m coredns-674b8bbfcf-rk7nz 1/1 Running 0 25m ``` Check that the kube-proxy replacement is active. Inside the agent pods, the debugging CLI is called `cilium-dbg`: ```bash kubectl -n kube-system exec ds/cilium -- cilium-dbg status | grep KubeProxyReplacement ``` ```output KubeProxyReplacement: True [eth0 203.0.113.10 fe80::be24:11ff:fe4a:1 (Direct Routing)] ``` ## Step 3 - Running the connectivity test The CLI ships an end-to-end test suite that deploys client and server pods and checks pod-to-pod, pod-to-Service, node port, DNS and policy behavior. It takes several minutes: ```bash cilium connectivity test ``` ```output [cilium-test-1] All 70 tests (620 actions) successful, 0 tests skipped, 0 scenarios skipped. ``` The number of tests varies between versions. When it finishes, delete the namespace the test created (list it with `kubectl get ns | grep cilium-test`): ```bash kubectl delete namespace cilium-test-1 ``` ## Step 4 - Enforcing L3, L4 and L7 network policies Cilium enforces standard Kubernetes `NetworkPolicy` objects and adds its own `CiliumNetworkPolicy`, which can also filter on HTTP methods and paths. Create a small test setup: an nginx backend and two client pods with different labels. ```bash kubectl create namespace demo kubectl -n demo create deployment backend --image=nginx kubectl -n demo expose deployment backend --port=80 kubectl -n demo run frontend --image=curlimages/curl --labels=app=frontend -- sleep infinity kubectl -n demo run other --image=curlimages/curl --labels=app=other -- sleep infinity ``` Wait for the pods to be ready, then confirm both clients can reach the backend before any policy exists: ```bash kubectl -n demo wait --for=condition=Ready pod --all --timeout=120s kubectl -n demo exec frontend -- curl -s -o /dev/null -w '%{http_code}\n' http://backend/ kubectl -n demo exec other -- curl -s -o /dev/null -w '%{http_code}\n' http://backend/ ``` ```output 200 200 ``` Now write a policy that selects the backend pods and only allows pods labeled `app=frontend` to send `GET /` on port 80. Once a pod is selected by a policy with an `ingress` section, all other ingress traffic to it is denied. ```bash nano backend-policy.yaml ``` ```yaml apiVersion: cilium.io/v2 kind: CiliumNetworkPolicy metadata: name: backend-allow-frontend namespace: demo spec: endpointSelector: matchLabels: app: backend ingress: - fromEndpoints: - matchLabels: app: frontend toPorts: - ports: - port: "80" protocol: TCP rules: http: - method: GET path: "/" ``` The `path` field is a regular expression matched against the full request path, so `"/"` allows only the root page. Apply the policy: ```bash kubectl apply -f backend-policy.yaml ``` Test the three cases. The frontend can still load `/`: ```bash kubectl -n demo exec frontend -- curl -s -o /dev/null -w '%{http_code}\n' http://backend/ ``` ```output 200 ``` Any other path from the frontend is rejected at L7 by Cilium's embedded Envoy proxy with `403 Forbidden`: ```bash kubectl -n demo exec frontend -- curl -s -o /dev/null -w '%{http_code}\n' http://backend/index.html ``` ```output 403 ``` The `other` pod is dropped at L3/L4, so its request times out: ```bash kubectl -n demo exec other -- curl -s --max-time 5 -o /dev/null -w '%{http_code}\n' http://backend/ ``` ```output 000 command terminated with exit code 28 ``` List the policies Cilium has imported with `kubectl get ciliumnetworkpolicies -n demo`. ## Step 5 - Observing traffic with Hubble Hubble records every flow that passes through Cilium, with the policy verdict. Install the Hubble CLI the same way as the Cilium CLI: ```bash HUBBLE_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/hubble/main/stable.txt) HUBBLE_ARCH=amd64 if [ "$(uname -m)" = "aarch64" ]; then HUBBLE_ARCH=arm64; fi curl -L --fail --remote-name-all "https://github.com/cilium/hubble/releases/download/${HUBBLE_VERSION}/hubble-linux-${HUBBLE_ARCH}.tar.gz"{,.sha256sum} sha256sum --check "hubble-linux-${HUBBLE_ARCH}.tar.gz.sha256sum" sudo tar xzvfC "hubble-linux-${HUBBLE_ARCH}.tar.gz" /usr/local/bin rm "hubble-linux-${HUBBLE_ARCH}.tar.gz"{,.sha256sum} ``` The Hubble Relay you enabled in Step 2 aggregates flows from all nodes. Forward it to `localhost:4245` in the background and check the connection: ```bash cilium hubble port-forward & hubble status ``` ```output Healthcheck (via localhost:4245): Ok Current/Max Flows: 12,285/12,285 (100.00%) Flows/s: 41.37 Connected Nodes: 3/3 ``` Repeat the blocked request from the `other` pod, then ask Hubble for dropped flows in the `demo` namespace: ```bash kubectl -n demo exec other -- curl -s --max-time 5 http://backend/ hubble observe --namespace demo --verdict DROPPED --last 5 ``` ```output Sep 25 10:14:02.118: demo/other:51720 (ID:23411) <> demo/backend-5d8c9f7b6-xk2lp:80 (ID:9102) policy-verdict:none INGRESS DENIED (TCP Flags: SYN) Sep 25 10:14:02.118: demo/other:51720 (ID:23411) <> demo/backend-5d8c9f7b6-xk2lp:80 (ID:9102) Policy denied DROPPED (TCP Flags: SYN) ``` To see the L7 decisions for the frontend, including the rejected `/index.html` request, filter by HTTP: ```bash hubble observe --namespace demo --protocol http --last 10 ``` For a graphical service map, open the Hubble UI. This command forwards it to `http://localhost:12000` and tries to open a browser: ```bash cilium hubble ui ``` If you manage the cluster over SSH, forward port `12000` from your workstation (`ssh -L 12000:localhost:12000 your_user@your_server_ip`) and open the URL locally. ## Step 6 - Encrypting pod traffic with WireGuard (optional) Traffic between pods on different nodes travels unencrypted by default. Cilium can encrypt it transparently with WireGuard, with no change to the applications. Enable it on the existing release: ```bash helm upgrade cilium cilium/cilium \ --namespace kube-system \ --reuse-values \ --set encryption.enabled=true \ --set encryption.type=wireguard kubectl -n kube-system rollout restart ds/cilium kubectl -n kube-system rollout status ds/cilium ``` Verify encryption is active on an agent: ```bash kubectl -n kube-system exec ds/cilium -- cilium-dbg encrypt status ``` ```output Encryption: Wireguard Interface: cilium_wg0 Public key: 9W8kW2yA...= Number of peers: 2 ``` The number of peers should be the number of nodes minus one. ## Troubleshooting **Nodes stay `NotReady` and Cilium pods crash with API server timeouts.** The `k8sServiceHost` value is wrong or unreachable from the nodes. Check the agent logs with `kubectl -n kube-system logs ds/cilium` and fix the value with `helm upgrade cilium cilium/cilium -n kube-system --reuse-values --set k8sServiceHost=correct_ip`. **Services work on some nodes but not others after installing.** kube-proxy is still running and its iptables rules conflict with Cilium. Check with `kubectl -n kube-system get ds kube-proxy`. Either remove it (`kubectl -n kube-system delete ds kube-proxy` and `kubectl -n kube-system delete cm kube-proxy`, then reboot or flush the `KUBE-*` iptables chains on each node) or reinstall Cilium with `kubeProxyReplacement=false`. **Pods lose DNS after applying an egress policy.** A `CiliumNetworkPolicy` with an `egress` section denies everything not listed, including DNS. Add an egress rule to `k8s-app: kube-dns` pods in `kube-system` on port `53/UDP`, and confirm with `hubble observe --namespace your_namespace --protocol dns`. **`hubble status` cannot connect.** The port-forward is not running or Relay is down. Check `kubectl -n kube-system get deploy hubble-relay` and restart it with `kubectl -n kube-system rollout restart deploy/hubble-relay`. ## Conclusion You installed Cilium as the CNI of a kubeadm cluster, replaced kube-proxy with eBPF load balancing, restricted access to a backend down to a single HTTP method and path, and traced allowed and denied flows with Hubble. From here you can enable Hubble metrics for Prometheus (`hubble.metrics.enabled`), use `toFQDNs` rules to control egress by DNS name, or connect several clusters with Cilium Cluster Mesh.