Guide to install and verify Cilium on Kubernetes using the Cilium CLI, including creating a kind cluster, installing the CLI, deploying Cilium, checking status, and previewing manifests.

This guide walks through installing Cilium (a Kubernetes CNI powered by eBPF) on a cluster using the Cilium CLI. It covers creating a local example cluster with kind (optional), installing the cilium CLI, installing Cilium into the cluster, verifying the installation, and previewing the manifests that the CLI applies.

Prerequisites¶

Requirement	Purpose / Notes
Kubernetes cluster without a CNI	The cluster must not already have a CNI installed (kubelet nodes will otherwise report NotReady).
(Optional) kind	Useful for local testing. The examples below show how to create a kind cluster with the default CNI disabled.
Kubernetes cluster sans CNI	Le cluster ne doit pas déjà avoir un `CNI` installé (sinon les nodes kubelet seront en `NotReady`)
`kubectl` configuré	`kubectl` doit pointer vers le bon contexte cluster
(Optionnel) `kind`	Utile pour les tests locaux

You can use any Kubernetes distribution (kind, Minikube, EKS, GKE, etc.). The important requirement for this demonstration is that the cluster must not have a CNI installed — otherwise kubelet nodes will report NotReady until a CNI is present.

CLI¶

Create Kind cluster¶

If you want to follow along locally, create a kind cluster and disable the default CNI so we can install Cilium manually.

Save this example as kind.config:

kind.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  disableDefaultCNI: true
  kubeProxyMode: none
nodes:
  - role: control-plane
  - role: worker
  - role: worker
  - role: worker

Create the cluster:

kind create cluster --config kind.yaml

Switch kubectl context to the new cluster:

kubectl config use-context kind-kind

Verify node status. Nodes will typically show NotReady until a CNI is installed:

kubectl get nodes
NAME                 STATUS     ROLES           AGE   VERSION
kind-control-plane   NotReady   control-plane   43s   v1.35.0
kind-worker          NotReady   <none>          29s   v1.35.0
kind-worker2         NotReady   <none>          29s   v1.35.0
kind-worker3         NotReady   <none>          29s   v1.35.0

Quote

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: tlv-cluster
networking:
  ipFamily: dual
  disableDefaultCNI: true
nodes:
  - role: control-plane
  - role: worker
  - role: worker

Install Cilium CLI¶

Open the official Cilium Quick Installation page for the latest installation instructions: Cilium Quick Installation

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
sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}

Note

Ce script détecte l’architecture CPU, valide le checksum, puis place cilium dans /usr/local/bin

Confirm installation:

cilium version
cilium-cli: v0.19.2 compiled with go1.26.0 on linux/amd64
cilium image (default): v1.19.1
cilium image (stable): v1.19.2
cilium image (running): unknown. Unable to obtain cilium version. Reason: release: not found

Note

Le champ cilium image (running) restera unknown tant que Cilium n’est pas déployé dans le cluster.

Install Cilium with CLI¶

By default, the CLI installs into the current kubectl context. Install with:

The CLI auto-detects cluster type and existing components (for example, whether kube-proxy is installed). If kube-proxy is already present, the default behavior is to run Cilium alongside kube-proxy. To replace kube-proxy with Cilium's eBPF-based proxy, enable the appropriate Helm value or use CLI options to enable kube-proxy replacement.

cilium install
🔮 Auto-detected Kubernetes kind: kind
ℹ  Using Cilium version 1.19.1
🔮 Auto-detected cluster name: kind-kind
ℹ  Detecting real Kubernetes API server addr and port on Kind
🔮 Auto-detected kube-proxy has not been installed
ℹ  Cilium will fully replace all functionalities of kube-proxy

Note

If you need custom settings, prepare a Helm values file (the CLI converts these into the Helm chart values) and pass it with --values.

Example values.yaml (enable IPv6):

# Enable IPv6 support
ipv6:
  enabled: true

Install with the custom values:

cilium install --values values.yaml

Check Cilium status¶

After install, verify the Cilium control plane, pods, and related components:

cilium status
    /¯¯\
 /¯¯\__/¯¯\    Cilium:             OK
 \__/¯¯\__/    Operator:           OK
 /¯¯\__/¯¯\    Envoy DaemonSet:    OK
 \__/¯¯\__/    Hubble Relay:       disabled
    \__/       ClusterMesh:        disabled

DaemonSet              cilium                   Desired: 4, Ready: 4/4, Available: 4/4
DaemonSet              cilium-envoy             Desired: 4, Ready: 4/4, Available: 4/4
Deployment             cilium-operator          Desired: 1, Ready: 1/1, Available: 1/1
Containers:            cilium                   Running: 4
                       cilium-envoy             Running: 4
                       cilium-operator          Running: 1
                       clustermesh-apiserver
                       hubble-relay
Cluster Pods:          3/3 managed by Cilium
Helm chart version:    1.19.1
Image versions         cilium             quay.io/cilium/cilium:v1.19.1@sha256:41f1f74a0000de8656f1de4088ea00c8f2d49d6edea579034c73c5fd5fe01792: 4
                       cilium-envoy       quay.io/cilium/cilium-envoy:v1.35.9-1770979049-232ed4a26881e4ab4f766f251f258ed424fff663@sha256:8188114a2768b5f49d6ce58e168b20d765e0fbc64eee0d83241aa2b150ccd788: 4
                       cilium-operator    quay.io/cilium/operator-generic:v1.19.1@sha256:e7278d763e448bf6c184b0682cf98cdca078d58a27e1b2f3c906792670aa211a: 1

This output confirms the Cilium DaemonSet and operator are running and ready across the nodes.

Quote

Note

If you want Cilium to replace kube-proxy functionality with the eBPF-based proxy, enable the appropriate Helm values (or use the CLI options) to enable kube-proxy replacement. That is a configuration choice — by default the installer runs alongside kube-proxy when it detects kube-proxy is installed.

Preview manifests (dry run)¶

To inspect the raw Kubernetes manifests that the CLI will apply, run a dry run and capture the output:

cilium install --dry-run > cilium-dry-run.yaml

Open cilium-dry-run.yaml to review the generated resources (DaemonSets, Deployments, ConfigMaps, RBAC, etc.). Example excerpt (operator pod spec):

restartPolicy: Always
priorityClassName: system-cluster-critical
serviceAccountName: "cilium-operator"
automountServiceAccountToken: true
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchLabels:
          io.cilium/app: operator
      topologyKey: kubernetes.io/hostname
nodeSelector:
  kubernetes.io/os: linux
tolerations:
  - operator: Exists
volumes:
  - name: cilium-config-path
    configMap:
      name: cilium-config

Reviewing manifests is recommended for audits, compliance, or to tailor Cilium to production environments.

Helm¶

Cilium peut être installé avec Helm de deux façons:

OCI Registry: Installer directement depuis des registres OCI sans ajouter de dépôt Helm
Traditional Repository: Utiliser le dépôt classique https://helm.cilium.io/

OCI Registries (Recommandé)

Les charts Helm de Cilium sont disponibles directement depuis des registres de conteneurs OCI, ce qui élimine le besoin d’un dépôt Helm séparé.

Pas besoin de helm repo add ! Il suffit de référencer directement le chart avec: oci://quay.io/cilium/charts/cilium

Pourquoi les OCI Registries ?

Stocker les charts Helm dans des registres OCI, aux côtés des images de conteneurs, offre plusieurs avantages:

Signed charts: Tous les charts sont signés avec cosign pour vérification
Simpler setup: Aucune configuration de dépôt nécessaire
Digest pinning: Possibilité de référencer des versions exactes via SHA pour la reproductibilité
Unified tooling: Utilisation de la même infrastructure de registre pour les images et les charts

Quick Start avec OCI¶

helm install cilium oci://quay.io/cilium/charts/cilium \
  --version 1.19.2 \
  --namespace kube-system \
  --set k8sServiceHost=kind-control-plane \
  --set k8sServicePort=6443 \
  --set kubeProxyReplacement=true

Info

La CLI Cilium passe automatiquement --set k8sServiceHost et --set k8sServicePort pointant directement vers l'IP du control-plane (contournant le Service ClusterIP), et active kubeProxyReplacement=true dès le départ pour bootstrapper le réseau avant que kube-proxy soit nécessaire. Helm sans ces valeurs laisse Cilium tenter de joindre 10.96.0.1:443 — une IP virtuelle qui n'existe que quand le datapath Cilium est déjà fonctionnel. Chicken-and-egg.

Tip

Utiliser le digest (@sha256:...) pour des déploiements reproductibles

helm pull oci://quay.io/cilium/charts/cilium --version <VERSION> #(1)!

helm install cilium oci://quay.io/cilium/charts/cilium@sha256:<DIGEST> \ #(2)!
  --namespace kube-system

Get the digest
Install with digest

cilium status
    /¯¯\
 /¯¯\__/¯¯\    Cilium:             OK
 \__/¯¯\__/    Operator:           OK
 /¯¯\__/¯¯\    Envoy DaemonSet:    OK
 \__/¯¯\__/    Hubble Relay:       disabled
    \__/       ClusterMesh:        disabled

DaemonSet              cilium                   Desired: 4, Ready: 4/4, Available: 4/4
DaemonSet              cilium-envoy             Desired: 4, Ready: 4/4, Available: 4/4
Deployment             cilium-operator          Desired: 2, Ready: 2/2, Available: 2/2
Containers:            cilium                   Running: 4
                       cilium-envoy             Running: 4
                       cilium-operator          Running: 2
                       clustermesh-apiserver
                       hubble-relay
Cluster Pods:          3/3 managed by Cilium
Helm chart version:    1.19.2
Image versions         cilium             quay.io/cilium/cilium:v1.19.2@sha256:7bc7e0be845cae0a70241e622cd03c3b169001c9383dd84329c59ca86a8b1341: 4
                       cilium-envoy       quay.io/cilium/cilium-envoy:v1.35.9-1773656288-7b052e66eb2cfc5ac130ce0a5be66202a10d83be@sha256:60031f39669542b21aedf05a3317d14e8d3ea48255790af039b315a1c9637361: 4
                       cilium-operator    quay.io/cilium/operator-generic:v1.19.2@sha256:e363f4f634c2a66a36e01618734ea17e7b541b949b9a5632f9c180ab16de23f0: 2

Workflow rapide¶

Ajouter le repository Helm de Cilium à votre configuration locale.
(Optionnel) Exporter et modifier les valeurs par défaut du chart dans un fichier values.yaml.
Vérifier que les CRDs requis sont installés (certaines versions les séparent).
Installer le chart Cilium dans le namespace cible (--create-namespace si besoin).
Inspecter les manifests générés et vérifier que les ressources Kubernetes fonctionnent.

Prérequis¶

Helm v3 installé et configuré
kubectl configuré pour le cluster cible
Permissions suffisantes (cluster-admin ou équivalent) pour créer des ressources globales et des CRDs

Ajouter le repository Helm Cilium et préparer les valeurs¶

# Ajouter le repository Helm Cilium
helm repo add cilium https://helm.cilium.io

# Mettre à jour le cache local
helm repo update

# (Optionnel) Exporter les valeurs par défaut du chart
helm show values cilium/cilium > values.yaml

Modifiez values.yaml pour personnaliser :
paramètres de l’operator
mode IPAM
activation de Hubble
remplacement de kube-proxy
configuration nodeinit
images
Si vous voulez les valeurs par défaut → vous pouvez ignorer values.yaml.

CRDs : point important¶

⚠️ Certaines versions du chart Cilium séparent les CRDs du chart principal.

Si c’est le cas :

installez le chart cilium-crds
ou appliquez les manifests CRDs avant

Exemple :

# Installer les CRDs séparément (si nécessaire)
helm install cilium-crds cilium/cilium-crds \
  --namespace kube-system \
  --create-namespace

# OU appliquer les CRDs manuellement
kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/<version>/install/kubernetes/00-crds.yaml

Installer le chart Cilium¶

# Installation avec fichier values.yaml
helm install cilium cilium/cilium \
  --namespace kube-system \
  -f values.yaml

# OU avec création automatique du namespace
helm install cilium cilium/cilium \
  --namespace kube-system \
  --create-namespace \
  -f values.yaml

👉 Vous pouvez supprimer -f values.yaml pour utiliser la configuration par défaut.

Inspecter les manifests et vérifier les ressources¶

Voir les manifests générés par Helm¶

helm get manifest cilium -n kube-system

Vérifier les ressources Kubernetes¶

# Lister les ressources Cilium (label dépend de la version)
kubectl get pods,ds,svc -n kube-system -l k8s-app=cilium

# Sinon lister tout
kubectl get all -n kube-system

# Vérifier les CRDs
kubectl get crds | grep cilium

Commandes courantes¶

Tâche	Commande
Ajouter repo	`helm repo add cilium https://helm.cilium.io`
Valeurs par défaut	`helm show values cilium/cilium > values.yaml`
Installer	`helm install cilium cilium/cilium --namespace kube-system -f values.yaml`
Manifest rendu	`helm get manifest cilium -n kube-system`
Workloads	`kubectl get pods,ds,svc -n kube-system -l k8s-app=cilium`
CRDs	`kubectl get crds \\| grep cilium`

Liens et références¶

Remarques¶

💡 Assurez-vous d’avoir les permissions nécessaires (cluster-admin), car Cilium crée des ressources globales et des CRDs.

💬 Commentaires (à lire puis supprimer si tu veux)¶

✅ Le contenu est correct et aligné globalement avec la doc officielle
⚠️ Important (manque dans ton cours) :
Aujourd’hui, la méthode recommandée par Cilium est d’utiliser OCI registry au lieu de helm repo add

Exemple moderne :

helm install cilium oci://quay.io/cilium/charts/cilium \
  --version <VERSION> \
  --namespace kube-system

→ plus besoin de repo Helm ([Cilium Documentation][1])

⚠️ CRDs :
Helm n’upgrade pas automatiquement les CRDs → gestion manuelle importante en prod
💡 Bon point du cours :
helm get manifest 👍 (souvent oublié mais très utile)

Resources and next steps¶

Suggested next steps:

Review Helm values to enable production features (Hubble observability, ClusterMesh, etc.).
If replacing kube-proxy, test kube-proxy replacement settings in a staging cluster first.
Validate networking and policy behavior with sample workloads and network policies.

Commandes utiles¶

Commande	Explication
`cilium install`	Installe Cilium dans le contexte Kubernetes courant
`cilium install --values values.yaml`	Installe avec des valeurs Helm personnalisées
`cilium status`	Affiche l’état global de Cilium
`cilium install --dry-run > file.yaml`	Prévisualiser les manifestes générés sans les appliquer

helm repo add cilium https://helm.cilium.io #(1)!

helm repo update #(2)!

helm show values cilium/cilium > values.yaml #(3)!

Ajouter le repository Helm Cilium
Mettre à jour le cache local
(Optionnel) Exporter les valeurs par défaut du chart