Kubernetes

Kubernetes est la plateforme d'orchestration de conteneurs standard de l'industrie, maintenue par la CNCF et initialement développée par Google. Il automatise le déploiement, la mise à l'échelle et la gestion du cycle de vie des applications conteneurisées via un modèle déclaratif : on décrit l'état désiré en YAML, Kubernetes s'assure que le cluster y correspond en permanence.

Cette fiche couvre l'installation vanilla via kubeadm, qui donne un contrôle total sur la configuration. Pour des clusters prêts en 30 secondes, voir k3s ou k0s.

Informations essentielles

Origine : Google → CNCF  ·  Licence : Apache 2.0  ·  Architectures : x86_64, ARM64, ARM

Liens : Site officiel  ·  Documentation  ·  GitHub  ·  Releases

Support : Kubernetes maintient les 3 dernières versions mineures (~15 mois par version). Passer à la version N+1 avant la fin de support de la version courante - ne jamais sauter de version mineure.

Stack par défaut (kubeadm)

Composants du control plane

Sur chaque nœud (control plane et workers) : kubelet (agent qui pilote le runtime de conteneurs).

Prérequis

Ressources minimales

Système d'exploitation

• Ubuntu 22.04 / 24.04, Debian 11 / 12
• Rocky Linux 9, AlmaLinux 9, RHEL 9
• Tout Linux 64-bit avec glibc et kernel ≥ 4.19 (kernel 5.x+ recommandé)
• Alpine Linux non supporté (musl libc)

Désactiver le swap (obligatoire)

sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

Modules kernel requis

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

Paramètres sysctl requis

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

Ports à ouvrir

Control plane

Workers

Les CNI ajoutent leurs propres ports : Calico utilise 179/TCP (BGP) ou 4789/UDP (VXLAN), Cilium utilise 4240/TCP (health) et 8472/UDP (VXLAN).

Installation

1. Installer containerd

Kubernetes n'utilise pas Docker - il s'appuie directement sur containerd via l'interface CRI. Deux façons de l'installer selon la distribution :

Ubuntu 24.04+ / Debian 12+ - le paquet natif est suffisamment récent (1.7+) :

sudo apt-get update
sudo apt-get install -y containerd

Ubuntu 22.04 / Debian 11 - Ubuntu 22.04 a livré containerd 1.5.9 à sa sortie (2022), trop ancien pour Kubernetes 1.26+ (exige CRI v1, disponible depuis containerd 1.6+). Les dépôts officiels ont depuis été mis à jour vers 1.7.x - vérifier avec containerd --version avant d'agir. Si la version est inférieure à 1.6, utiliser les binaires officiels :

# Télécharger containerd depuis son projet GitHub (pas de Docker requis)
CTRD=2.3.0
curl -LO https://github.com/containerd/containerd/releases/download/v${CTRD}/containerd-${CTRD}-linux-amd64.tar.gz
sudo tar Czxvf /usr/local containerd-${CTRD}-linux-amd64.tar.gz

# Installer runc (exécuteur de conteneurs OCI)
curl -Lo /tmp/runc.amd64 \
  https://github.com/opencontainers/runc/releases/download/v1.4.2/runc.amd64
sudo install -m 755 /tmp/runc.amd64 /usr/local/sbin/runc

# Service systemd
sudo mkdir -p /usr/local/lib/systemd/system
sudo curl -Lo /usr/local/lib/systemd/system/containerd.service \
  https://raw.githubusercontent.com/containerd/containerd/main/containerd.service
sudo systemctl daemon-reload
sudo systemctl enable containerd

Rocky Linux 9 / AlmaLinux 9 / RHEL 9 - containerd est disponible via les dépôts Docker :

sudo dnf install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install -y containerd.io
sudo systemctl enable --now containerd

Configuration commune - activer le cgroup driver systemd (OBLIGATOIRE)

sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
sudo systemctl restart containerd

2. Installer kubeadm, kubelet, kubectl

# Dépôt officiel Kubernetes (pkgs.k8s.io)
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.36/deb/Release.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] \
  https://pkgs.k8s.io/core:/stable:/v1.36/deb/ /' | \
  sudo tee /etc/apt/sources.list.d/kubernetes.list

sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

apt-mark hold empêche une mise à jour accidentelle lors d'un apt upgrade.

Rocky Linux 9 / AlmaLinux 9 / RHEL 9

# SELinux en mode permissif (requis pour kubelet)
sudo setenforce 0
sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config

# Dépôt officiel Kubernetes
cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.36/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.36/rpm/repodata/repomd.xml.key
EOF

sudo dnf install -y kubelet kubeadm kubectl
sudo systemctl enable --now kubelet

3. Initialiser le control plane

sudo kubeadm init \
  --pod-network-cidr=192.168.0.0/16 \
  --control-plane-endpoint=<IP_OU_DNS>:6443 \
  --cri-socket unix:///run/containerd/containerd.sock

• --pod-network-cidr : doit correspondre au CNI choisi (192.168.0.0/16 = défaut Calico)
• --control-plane-endpoint : IP ou DNS stable - indispensable pour le HA ultérieur
• --cri-socket : à préciser si plusieurs runtimes sont installés

4. Configurer kubectl

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

5. Installer un CNI - Calico

# Opérateur Tigera (recommandé)
kubectl create -f https://raw.githubusercontent.com/projectcalico/calico/v3.32.0/manifests/tigera-operator.yaml

curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.32.0/manifests/custom-resources.yaml
# Vérifier que le CIDR correspond à --pod-network-cidr (192.168.0.0/16 par défaut)
kubectl create -f custom-resources.yaml

# Surveiller le déploiement
watch kubectl get tigerastatus

6. Vérifier

kubectl get nodes
kubectl get pods -A

Les nœuds restent en état NotReady tant que le CNI n'est pas installé.

7. Cluster single-node : autoriser les workloads sur le control plane

Par défaut, kubeadm pose un taint NoSchedule sur le control plane, empêchant les pods applicatifs d'y être schedulés. Pour un cluster de labo ou single-node, le retirer :

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

# Vérifier (la ligne Taints doit afficher "<none>")
kubectl describe node <nom> | grep -i taint

Ne pas appliquer en production sur un vrai control plane dédié.

Ajouter des workers

La commande kubeadm join est affichée à la fin de kubeadm init. Si elle n'a pas été conservée :

# Régénérer la commande de jointure complète
kubeadm token create --print-join-command

Sur chaque worker (après avoir effectué les étapes Prérequis + containerd + kubeadm/kubelet) :

sudo kubeadm join <control-plane>:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash>

metrics-server

kubectl top nodes et kubectl top pods nécessitent metrics-server, qui n'est pas installé par défaut :

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# Vérifier le déploiement
kubectl -n kube-system rollout status deployment/metrics-server
kubectl top nodes

Sur un cluster kubeadm avec certificats auto-signés, metrics-server peut échouer à valider les certificats kubelet. Ajouter --kubelet-insecure-tls dans les args du Deployment :

kubectl patch deployment metrics-server -n kube-system \
  --type=json \
  -p='[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'

Configuration via fichier (kubeadm-config.yaml)

Plutôt que les flags en ligne de commande, kubeadm accepte un fichier de configuration :

# Voir les valeurs par défaut
kubeadm config print init-defaults

# kubeadm-config.yaml
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
kubernetesVersion: v1.36.0
controlPlaneEndpoint: "192.168.1.100:6443"

networking:
  podSubnet: "192.168.0.0/16"
  serviceSubnet: "10.96.0.0/12"

apiServer:
  certSANs:
    - "192.168.1.100"
    - "api.moncluster.com"
  extraArgs:
    - name: audit-log-maxage
      value: "30"

sudo kubeadm init --config kubeadm-config.yaml

Depuis Kubernetes 1.31, extraArgs utilise des paires name/value (plus une map de strings).

RBAC (contrôle d'accès)

Kubernetes utilise le RBAC (Role-Based Access Control) pour contrôler qui peut faire quoi sur le cluster. Activé par défaut depuis Kubernetes 1.8.

Les sujets peuvent être : User, Group, ou ServiceAccount.

Exemple : accès lecture seule sur un namespace

# role-readonly.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: production
  name: readonly
rules:
- apiGroups: [""]
  resources: ["pods", "services", "configmaps"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: readonly-binding
  namespace: production
subjects:
- kind: User
  name: alice
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: readonly
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f role-readonly.yaml

# Vérifier les permissions d'un utilisateur
kubectl auth can-i list pods --namespace=production --as=alice

ServiceAccount pour une application

kubectl create serviceaccount mon-app -n production

# Associer un Role existant
kubectl create rolebinding mon-app-binding \
  --role=readonly \
  --serviceaccount=production:mon-app \
  -n production

Haute disponibilité (HA)

Prérequis : un load balancer TCP en frontal des control plane (port 6443).

Premier control plane

sudo kubeadm init \
  --control-plane-endpoint "lb.moncluster.com:6443" \
  --upload-certs \
  --pod-network-cidr=192.168.0.0/16

--upload-certs chiffre et dépose les certificats PKI dans un Secret kubeadm-certs (valide 2 heures).

Ajouter d'autres control plane

sudo kubeadm join lb.moncluster.com:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash> \
  --control-plane \
  --certificate-key <certificate-key>

Si le --certificate-key a expiré (> 2h), le régénérer sur le premier control plane :

sudo kubeadm init phase upload-certs --upload-certs

Utiliser un nombre impair de control plane (3 ou 5) pour le quorum etcd.

Ingress

Un Ingress expose des Services HTTP/HTTPS via un point d'entrée unique avec routage par nom d'hôte ou chemin. Il nécessite un Ingress controller (non inclus par défaut).

Installer ingress-nginx

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.12.0/deploy/static/provider/baremetal/deploy.yaml

# Vérifier
kubectl -n ingress-nginx rollout status deployment/ingress-nginx-controller
kubectl get svc -n ingress-nginx

Sur bare-metal, le Service est de type NodePort. Pour une IP externe stable, voir MetalLB.

Exemple de ressource Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mon-app
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: app.mondomaine.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: mon-service
            port:
              number: 80

Gateway API est le successeur officiel des Ingress (plus expressif, multi-tenant). À considérer pour les nouveaux clusters : gateway-api.sigs.k8s.io.

Stockage persistant (PVC / StorageClass)

Les PersistentVolumeClaim (PVC) permettent aux pods de demander du stockage persistant sans connaître l'infrastructure sous-jacente. Une StorageClass définit comment provisionner ce stockage dynamiquement.

StorageClass locale (labo / single-node)

local-path-provisioner est le provisioner le plus simple pour un cluster de développement :

kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml

# En faire la StorageClass par défaut
kubectl patch storageclass local-path \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

kubectl get storageclass

Exemple : PVC + Pod

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mon-volume
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: pod-avec-volume
spec:
  containers:
  - name: app
    image: nginx
    volumeMounts:
    - mountPath: /data
      name: data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: mon-volume

kubectl apply -f pvc-pod.yaml
kubectl get pvc
kubectl get pv

En production, utiliser un CSI driver adapté : Longhorn, Rook/Ceph, NFS CSI, AWS EBS CSI, etc.

NetworkPolicy

Par défaut, tous les pods peuvent communiquer entre eux sans restriction. Les NetworkPolicy permettent de filtrer le trafic réseau entre pods.

Les NetworkPolicy nécessitent un CNI qui les supporte : Calico ✓ Cilium ✓ Flannel ✗ (sans plugin additionnel).

Isoler un namespace (deny-all par défaut)

# deny-all.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: deny-all
  namespace: production
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  - Egress

Autoriser uniquement le frontend vers le backend

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-frontend
  namespace: production
spec:
  podSelector:
    matchLabels:
      app: backend
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          app: frontend
    ports:
    - protocol: TCP
      port: 8080

kubectl apply -f deny-all.yaml
kubectl get networkpolicy -n production

Certificats

Les certificats clients expirent après 1 an. Les CA expirent après 10 ans.

# Vérifier les dates d'expiration
kubeadm certs check-expiration

# Renouveler tous les certificats
sudo kubeadm certs renew all

# Renouveler un certificat spécifique
sudo kubeadm certs renew apiserver

# Redémarrer kubelet après renouvellement (relit les certs au démarrage)
sudo systemctl restart kubelet

Lors d'un kubeadm upgrade, les certificats expirant dans moins de 180 jours sont automatiquement renouvelés.

Mise à jour

Règle absolue : ne jamais sauter de version mineure. Mettre à jour de 1.35 → 1.36, jamais de 1.34 → 1.36 directement.

Control plane (premier nœud)

# 1. Mettre à jour kubeadm
sudo apt-mark unhold kubeadm
sudo apt-get install -y kubeadm='1.36.*'
sudo apt-mark hold kubeadm

# 2. Vérifier et planifier
kubeadm version
sudo kubeadm upgrade plan

# 3. Appliquer la mise à jour
sudo kubeadm upgrade apply v1.36.0

# 4. Drain du nœud
kubectl drain <nom-nœud-cp> --ignore-daemonsets

# 5. Mettre à jour kubelet et kubectl
sudo apt-mark unhold kubelet kubectl
sudo apt-get install -y kubelet='1.36.*' kubectl='1.36.*'
sudo apt-mark hold kubelet kubectl

# 6. Redémarrer kubelet
sudo systemctl daemon-reload && sudo systemctl restart kubelet

# 7. Remettre en service
kubectl uncordon <nom-nœud-cp>

Control plane supplémentaires

Remplacer l'étape 3 par sudo kubeadm upgrade node (pas upgrade apply).

Workers

# 1. Drain (depuis une machine avec kubectl)
kubectl drain <nom-worker> --ignore-daemonsets --delete-emptydir-data

# 2. Sur le worker : mettre à jour kubeadm + kubelet config
sudo apt-get install -y kubeadm='1.36.*'
sudo kubeadm upgrade node
sudo apt-get install -y kubelet='1.36.*' kubectl='1.36.*'
sudo systemctl daemon-reload && sudo systemctl restart kubelet

# 3. Remettre en service
kubectl uncordon <nom-worker>

Mettre à jour les addons

kubeadm upgrade apply met à jour automatiquement CoreDNS et kube-proxy. Les autres addons sont à mettre à jour manuellement :

# Vérifier les versions après upgrade
kubectl get pods -n kube-system | grep -E "coredns|kube-proxy"

# CNI Calico - appliquer le manifest de la nouvelle version
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.32.0/manifests/tigera-operator.yaml
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.32.0/manifests/custom-resources.yaml

# metrics-server (si installé)
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# ingress-nginx (si installé) - vérifier la matrice de compatibilité sur le projet GitHub
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.12.0/deploy/static/provider/baremetal/deploy.yaml

Chaque addon a son propre cycle de versions - vérifier la compatibilité avec la version Kubernetes cible avant de mettre à jour.

Sauvegarde etcd

# Sauvegarder
ETCDCTL_API=3 etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save /backup/etcd-$(date +%Y%m%d).db

# Vérifier le snapshot
ETCDCTL_API=3 etcdctl --write-out=table \
  snapshot status /backup/etcd-$(date +%Y%m%d).db

Restaurer un snapshot

# Arrêter le control plane
sudo systemctl stop kubelet
sudo mv /etc/kubernetes/manifests /etc/kubernetes/manifests.bak

# Restaurer (etcdutl - etcdctl restore est déprécié depuis etcd v3.5+)
sudo etcdutl snapshot restore /backup/etcd-20240115.db \
  --data-dir=/var/lib/etcd-restore

# Mettre à jour le manifest etcd pour pointer vers le nouveau data-dir
sudo sed -i 's|/var/lib/etcd|/var/lib/etcd-restore|g' \
  /etc/kubernetes/manifests.bak/etcd.yaml

# Redémarrer
sudo mv /etc/kubernetes/manifests.bak /etc/kubernetes/manifests
sudo systemctl start kubelet

Troubleshooting

Logs des composants du control plane

# Composants en static pods - logs via kubectl
kubectl logs -n kube-system kube-apiserver-<node>
kubectl logs -n kube-system kube-controller-manager-<node>
kubectl logs -n kube-system kube-scheduler-<node>
kubectl logs -n kube-system etcd-<node>

# Ou directement via journalctl (kubelet)
sudo journalctl -u kubelet -f
sudo journalctl -u kubelet --since "10 minutes ago"

Nœud NotReady

# Vérifier kubelet
sudo systemctl status kubelet
sudo journalctl -u kubelet -n 50

# Vérifier les modules kernel
lsmod | grep br_netfilter
lsmod | grep overlay

# Vérifier les sysctl
sysctl net.bridge.bridge-nf-call-iptables
sysctl net.ipv4.ip_forward

Pod bloqué en Pending

kubectl describe pod <nom> -n <namespace>
kubectl get events -n <namespace> --sort-by='.lastTimestamp'
kubectl top nodes

Pod bloqué en ContainerCreating

# Souvent un problème CNI ou de runtime
kubectl describe pod <nom> -n <namespace> | grep -A10 Events
sudo crictl ps -a        # Lister les conteneurs via containerd
sudo crictl logs <id>    # Logs du conteneur

Vérifier les préflights avant init

sudo kubeadm init --dry-run

Reset complet d'un nœud

sudo kubeadm reset
sudo apt-get purge -y kubeadm kubelet kubectl
sudo rm -rf /etc/kubernetes /var/lib/etcd ~/.kube
sudo iptables -F && sudo iptables -t nat -F

Commandes utiles

# Gestion des contextes (multi-cluster)
kubectl config get-contexts                                        # Lister les contextes disponibles
kubectl config current-context                                     # Contexte actif
kubectl config use-context <nom>                                   # Changer de cluster
kubectl config set-context --current --namespace=<ns>             # Namespace par défaut du contexte actif

# Fusionner plusieurs kubeconfig
KUBECONFIG=~/.kube/config:~/.kube/config-cluster2 kubectl config view --flatten > ~/.kube/config-merged

# État du cluster
kubectl get nodes -o wide
kubectl get pods -A
kubectl top nodes
kubectl top pods -A

# Événements récents
kubectl get events -A --sort-by='.lastTimestamp' | tail -20

# Détail d'un nœud
kubectl describe node <nom>

# Vérifier les certificats
kubeadm certs check-expiration

# Statut des composants
kubectl get componentstatuses   # deprecated mais encore lisible

# Inspecter un pod en erreur
kubectl describe pod <nom> -n <namespace>
kubectl logs <nom> -n <namespace> --previous

# Shell dans un pod de debug
kubectl run debug --image=busybox --rm -it --restart=Never -- sh

# Tester la résolution DNS interne
kubectl run dns-test --image=busybox --rm -it --restart=Never \
  -- nslookup kubernetes.default

# Dump de l'état d'un namespace
kubectl get all -n <namespace> -o yaml > dump.yaml

Ressources

• Installation kubeadm : https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/
• Créer un cluster : https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/
• Haute disponibilité : https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/high-availability/
• Mise à jour : https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-upgrade/
• Gestion des certificats : https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/
• Ports et protocoles : https://kubernetes.io/docs/reference/networking/ports-and-protocols/
• Runtimes de conteneurs : https://kubernetes.io/docs/setup/production-environment/container-runtimes/
• Documentation Calico : https://docs.tigera.io/calico/latest/
• GitHub : https://github.com/kubernetes/kubernetes