Learn Cilium - Setup & Installation

#Introduction

This is the moment for your first real action: installing Cilium in your cluster. In episode 3 we will use two installation paths — the Cilium CLI for speed and the Helm chart for full control — then verify the installation with cilium status and cilium connectivity test.

In addition, we will discuss an architectural decision that matters from the start: tunnel vs direct routing. This choice affects how packets move between nodes and should ideally be decided before workloads run. This episode also covers how Cilium integrates with container runtimes such as containerd and CRI-O.

One important note before starting: make sure no other CNI is installed in your cluster. If your cluster was created with kind or k3s, they may already have a built-in CNI installed (k3s uses flannel by default). Disable that CNI first so there is no conflict when Cilium takes over network management.

#Installing with the Cilium CLI

The easiest way to get started is with the Cilium CLI. Make sure your cluster is ready (episode 0) and no other CNI is installed, then run:

Install Cilium with the CLI

cilium install --version v1.20.0

cilium install --version v1.20.0 applies Cilium to the cluster with safe default settings: it will automatically detect the container runtime, IPAM mode, and datapath settings suitable for your local cluster. If no version is specified, the CLI uses the latest compatible version.

The Cilium CLI essentially wraps the Helm chart — everything the CLI does can also be done manually with Helm. This is important to understand because in production you will almost certainly use Helm or a GitOps tool (episode 18) instead of the CLI.

#Installing with the Helm Chart

For full control over the configuration, use Helm. Add the official repository then install the chart:

Install Cilium with Helm

helm repo add cilium https://helm.cilium.io/
helm repo update
helm install cilium cilium/cilium \
  --namespace kube-system \
  --version 1.20.0 \
  --set kubeProxyReplacement=strict

helm install cilium cilium/cilium installs the official chart into the kube-system namespace. The kubeProxyReplacement=strict option tells Cilium to fully replace kube-proxy — a topic we will dissect in episode 8.

#Verifying the Installation

After the installation finishes, verify the Cilium status:

Check Cilium status

cilium status

cilium status shows a summary: whether the agent and operator are running, whether the control plane is connected, and the detected kernel version. All components must show OK status before continuing.

A deeper verification is the connectivity test, which creates temporary workloads and tests various traffic paths between pods and services:

Run the connectivity test

cilium connectivity test

cilium connectivity test runs a series of scenarios: pod-to-pod, pod-to-service, ingress and egress, even with policies attached. All scenarios must pass. This test will also be used later in episode 21 as a quality gate in the CI/CD pipeline.

If a scenario fails, pay attention to the scenario name shown by the test. A failing pod-to-pod test usually points to a data plane problem, while a failing pod-to-service test could point to a load balancing or DNS problem. Stop and fix it before continuing, because all subsequent episodes assume a healthy installation underneath.

#Datapath Mode: Tunnel vs Direct Routing

The datapath mode determines how packets are sent between nodes:

Tunnel (default in many setups): packets are encapsulated with VXLAN or Geneve before being sent between nodes. The advantage is simplicity and independence from the physical network topology. Suitable for local clusters and cloud networks that cannot be routed directly.
Direct routing: packets are sent directly to the destination node's IP without encapsulation. Faster because there is no tunnel header overhead, but it requires a physical network capable of routing pod IPs between nodes. Suitable for properly configured VPCs.

To change the mode, set it at install time. For example with the CLI:

Install with direct routing

cilium install --set routing-mode=direct

The choice between the two does not mean one is always better than the other. For production on public clouds, direct routing is often chosen for performance, while tunnel provides flexibility on complex networks.

#Integration with the Container Runtime

Cilium integrates with the container runtime through CNI. Cilium provides a cilium-cni binary plugin and a CNI configuration file on every node. When containerd or CRI-O creates a pod, the runtime calls this plugin according to the CNI spec, and Cilium takes over the pod's network setup.

Verify that the CNI plugin is properly installed:

Check the CNI plugin

kubectl exec -n kube-system -it ds/cilium -- cilium-dbg status

cilium-dbg status run inside the agent pod shows the CNI Chained line and the active CNI configuration. If this line shows a configuration, it means Cilium is ready to be called by the runtime for every new pod.

#Updating and Removing the Installation

Installation is not a one-time operation. When you want to change configuration values or test again from scratch, there are two commands you must master:

Update the installation with Helm

helm upgrade cilium cilium/cilium \
  --namespace kube-system \
  --version 1.20.0 \
  --set ipam.mode=cluster-pool

helm upgrade cilium cilium/cilium applies new values without deleting the cluster. All --set options must be repeated every time you upgrade — Helm does not persist values between commands. A safer way is to write all values into a values.yaml file and then use -f values.yaml, because recorded values are easier to audit (episode 18).

To test from scratch or switch CNIs, remove the installation first:

Remove the Cilium installation

cilium uninstall

cilium uninstall cleans up the DaemonSet, operator, and Cilium resources from the cluster. After uninstalling, remember that the cluster will lose Cilium's networking capabilities — make sure no important workload depends on Cilium when this command is run. In a lab environment, the usual sequence is uninstall then reinstall to simulate a fresh cluster.

Reinstall and wait until ready

cilium install --version v1.20.0
cilium status --wait

cilium status --wait blocks until all Cilium components are ready — practical for scripts and pipelines because a success status means the installation is truly complete, not merely submitted.

Info

The Cilium CLI and Helm produce the same configuration. Use Helm if you need auditability and reproducibility, use the Cilium CLI if you want to start experimenting quickly. In production, helm values should be stored in a repository (episode 18).

#Closing

Key takeaways:

cilium install is a shortcut that wraps the Helm chart.
helm install cilium cilium/cilium gives full control over the configuration.
cilium status and cilium connectivity test are mandatory verification gates.
Tunnel uses encapsulation and is flexible; direct routing is faster but requires supporting networks.
Cilium integrates with containerd and CRI-O through the CNI plugin.

In the next episode 4, we will discuss basic networking: pod-to-pod and service — how Cilium allocates IP addresses, flows packets within and across nodes, handles masquerading, and replicates the ClusterIP, NodePort, and LoadBalancer Services directly in eBPF. This will be the foundation for all the subsequent security episodes.