☸️k8s-playground — the Kubernetes layer for the Talos and kubeadm labs

./_k8s/platform-up.sh                # from either lab's root
./_k8s/install.sh longhorn vault      # add-ons, opt-in

📖 Browsable documentation: https://ops-nc.github.io/k8s-playground/ — one self-contained page, bilingual (EN/FR), dark/light, rebuilt from these README.md / LISEZ-MOI.md files on every push to main (make docs builds it locally).

Both labs remain responsible for bootstrapping the cluster (VMs, OS, kubeadm init / talosctl bootstrap). This repository covers what comes after, with kubectl and helm from the host — including the CNI, because neither bootstrap leaves a usable pod network behind.

⚡ Quick start#

You never start here: you start in a lab, which is where the cluster and its state live.

# 1. The lab — its submodule included (Talos twin: OPS-NC/Vagrant-Talos)
git clone --recurse-submodules https://github.com/OPS-NC/Vagrant-kubeadm.git
cd Vagrant-kubeadm
cp lab.env.example lab.env               # the LAB's model: topology, domain, TLS mode, CNI
vagrant up && ./kubeadm/cluster-up.sh    # nodes are NotReady: no CNI yet

# 2. Lay down the base platform — nothing to declare
./_k8s/platform-up.sh                # CNI → Envoy Gateway → metrics-server → wildcard TLS

# 3. Add-ons, opt-in
./_k8s/install.sh longhorn vault argocd
./_k8s/install.sh list               # the full catalogue
./_k8s/install.sh all                # platform + every add-on, in dependency order

From the lab root this repository is <lab>/_k8s: the lab is its parent, recognised by its Vagrantfile, and the distribution is read off that lab's own structure — kubeadm/cluster-up.sh here, talos/cluster-up.sh in the Talos twin. KUBECONFIG is derived the same way (<lab>/kubeconfig); export it yourself only for your own kubectl calls. Passing the distribution explicitly still works and still wins, which is the surest way to know what you ran: ./_k8s/install.sh kubeadm platform.

Every component is also runnable on its own:

./_k8s/longhorn/longhorn-up.sh

🎓 Training mode. Every directory ships a README.md (EN) / LISEZ-MOI.md (FR) with a "Guided walkthrough" section: the same installation, command by command, with what to observe at each step and the per-distribution variants. The all-in-one script and the walkthrough do exactly the same thing.

cd ../Vagrant-Talos && ./talos/cluster-up.sh    # or ../Vagrant-KubeADM && ./kubeadm/cluster-up.sh

cd ../k8s-playground                 # this repo, sibling of the lab
./install.sh talos platform          # one lab next door ⇒ the argument is optional here too

git clone --recurse-submodules https://github.com/OPS-NC/Vagrant-kubeadm.git
git submodule update --init --recursive   # fills _k8s/ on a clone already made
git submodule update --remote _k8s        # moves _k8s/ onto the latest commit of this repo

⚠️ git pull in the lab does NOT update the submodule. It moves the lab repository only; _k8s/ stays on the commit pinned before, so you would be running the documented commands against an older application layer. Follow every pull with git submodule update --init --recursive. And an empty _k8s/ — ./_k8s/install.sh: No such file or directory — always means one thing: the submodule was never initialised.

💡 Changing this layer is a change made here. Seen from a lab, _k8s/ is a checkout of this repository on a detached HEAD: files edited in it belong to this repo, and a git commit run inside _k8s/ commits here. The route is PR on this repository → merge → in the lab, git submodule update --remote _k8s, then commit the bumped pointer. That commit is the application layer's version bump.

📍 Where lab.env and _out/ are found#

The scripts store nothing. lab.env (the intent: domain, TLS mode, CNI, VM sizes) and _out/ (the facts: talosconfig, cluster.env, the local CA, vault-init.json…) live in the lab repository, with the kubeconfig beside them. There is exactly one source of truth for the topology and it is the lab's — which is why this repository ships no lab.env and no model for one. _resolve_lab_dir(), in lib/common.sh, looks for that directory in this order:

KUBECONFIG follows the same directory: unless already exported, it becomes <lab dir>/kubeconfig.

A Vagrantfile is the one unambiguous mark of a lab: it is there from the clone, before any vagrant up, and it never appears above this repo in the sibling layout. Rule 2 deliberately comes before rule 4, so a leftover _out/ (or a lab.env dropped here for a one-off test) can never shadow the real lab sitting right above.

Every script prints its resolution before touching anything, on one line:

    profil kubeadm (Debian 13 + kubeadm) · domaine *.kubeadm.lab.example.io · lab.env absent (défauts)

lab.env absent (défauts) on a lab that does have a lab.env, or a domaine that is not the one you set, means the resolution missed the lab. Force it:

LAB_DIR=~/labs/my-lab          ./install.sh talos platform   # lab.env + _out/ + kubeconfig, all there
LAB_ENV=~/labs/my-lab/lab.env  ./install.sh talos platform   # its directory becomes the lab dir

💡 One more signal fires, on kubeadm only: platform-up.sh warns when _out/cluster.env is missing — "./kubeadm/cluster-up.sh has not been run (or not to the end)". Either the bootstrap really did not finish, or the lab was not the one resolved. The warning is non-blocking, and Talos has no equivalent (that lab has no cluster.env).

⚠️ Do not create a lab.env at this repo's root. Rule 4 accepts one, for exercising this repo without any lab, but a second lab.env is a second truth that drifts from the lab's the moment either changes. That is why there is no lab.env.example here: the model to copy lives in the lab.

🎯 How the distribution is selected#

In priority order:

Sources 5 to 8 are _detect_distro(), ordered by how early each signal becomes available: structure works from the git clone, before any vagrant up; artefacts cover a lab whose directories were renamed; neighbours run the same test on ../Vagrant-Talos and ../Vagrant-KubeADM, and refuse to decide when both are there — guessing would be a one-in-two chance of deploying onto the wrong cluster; the probe comes last because it needs a KUBECONFIG that is already correct, which is derived from the lab directory, which comes from the profile, which is what we are trying to choose.

With none of the above, the scripts refuse to run: applying a Talos-shaped manifest on Debian (or the reverse) does not produce a clean error but a silent failure — a Deployment created while no pod ever starts.

ℹ️ Sources 4 to 6 need the lab to be located first, which is where layout matters. In submodule layout the parent-Vagrantfile rule fires before any profile is loaded, so all three work bare — that is what makes ./_k8s/platform-up.sh self-sufficient. In sibling layout no lab is located at that point (LAB_REPO_NAME comes from the profile), so source 7 takes over, and ./install.sh platform works bare from here too as long as a single lab sits next door.

🧬 What actually differs between the two labs#

Everything is concentrated in lib/profiles/talos.sh and lib/profiles/kubeadm.sh: the install scripts never test the distribution through scattered ifs, they read variables.

ℹ️ kube-proxy: same outcome, two mechanisms. Both labs default to KUBE_PROXY_REPLACEMENT=true, so on both the reference cluster runs with no kube-proxy at all and Cilium serves the Services in eBPF. Only the way the bootstrap drops it differs. The value is decided at bootstrap — not a runtime toggle — and it requires CNI=cilium on both, since nothing else here replaces kube-proxy.

Everything else — Argo CD, Kyverno, MinIO, CloudNativePG, Vault, Envoy Gateway, cert-manager, chaoskube, node-problem-detector, WordPress — is strictly identical on both distributions.

🗂️ Repository layout#

install.sh                  entry point: ./install.sh [talos|kubeadm] <component...>
platform-up.sh              the base platform (CNI → Gateway → metrics → TLS)
metric-server.yaml          metrics-server (applied by platform-up.sh)
lib/
  common.sh                 shared core: distro resolution, lab.env reading, helpers
  profiles/talos.sh         EVERYTHING specific to Talos
  profiles/kubeadm.sh       EVERYTHING specific to kubeadm/Debian
<component>/
  <component>-up.sh         the all-in-one install
  values.yaml / *.yaml      manifests and values (NEUTRAL values, substituted on the fly)
  README.md / LISEZ-MOI.md  EN/FR docs + guided walkthrough
docs/build.py               builds the single-page site from every README (make docs)
Makefile                    docs, docs-check, validate — everything that runs without a cluster

In submodule layout that whole tree hangs under the lab's _k8s/. Paths inside this repository are the same either way, which is why every walkthrough is written from this repository's root.

There is no Vagrantfile, no _out/ and no lab.env here, by design: this repo owns the manifests, the lab owns the cluster and its state. That absence is load-bearing — it is what makes "the parent holds a Vagrantfile" an unambiguous way to spot the lab.

🔗 Dependency chain#

Every link assumes the previous one: no LoadBalancer IP without an L2 announcer, no HTTPS without the Gateway, no UI without a certificate on the :443 listener.

bootstrapped cluster  (Talos lab or kubeadm lab — nodes NotReady, no CNI yet)
   │
   ├─ 1. CNI              cilium/ (default, + L2 pool → LoadBalancer IP .200)
   │                      or calico/ (CNI only) or flannel (CNI only) or nothing
   │     + L2 announcer   metallb/ — ONLY when the CNI is not cilium, on the SAME range
   │                      (skipped with METALLB=false: no LoadBalancer IP at all)
   ├─ 2. envoy-gateway/   Envoy controller + main-gateway (listeners :80 and :443)
   ├─ 3. metric-server    metrics.k8s.io API  (kubectl top, HPA)
   └─ 4. wildcard TLS     *.<LAB_DOMAIN> — two modes, per SELF_SIGNED
              │             true (default) → self-signed/   openssl, local CA
              │             false          → cert-manager/  Let's Encrypt DNS-01 Cloudflare
              │
              └─ add-ons: storage → backup → databases → identity → secrets → observability
                          → security

That is exactly the order of platform-up.sh ([1/4] → [4/4]). Both TLS modes fill the same Secret (wildcard-<LAB_DOMAIN with dashes>-tls), so no add-on ever has to know which one you picked.

🌐 LAB_DOMAIN — the UI domain#

The repository is public: no manifest carries a real value. Three neutral markers are substituted on the fly (the render helper in lib/common.sh), never rewriting a versioned file — git status stays clean:

LAB_DOMAIN is set in the lab's lab.env, never here:

echo 'LAB_DOMAIN=k8s.my-domain.tld' >> lab.env      # in Vagrant-Talos/ or Vagrant-KubeADM/

⚠️ A domain that stays at <distro>.lab.example.io while lab.env says otherwise is the first symptom of a lab.env that was never found: check which lab got resolved (the summary line) before suspecting the substitution.

⚠️ Manifests applied by hand (without a *-up.sh) get no substitution: wordpress-example/wordpress-mariadb.yaml, vault-secret-operator/k8s/*.yaml, cert-manager/04-gateway-https-example.yaml. Pipe them through the same sed:

sed 's/lab\.example\.io/k8s.my-domain.tld/g' <file> | kubectl apply -f -

📦 Pinned versions#

Audited on 1 August 2026: everything is on the latest stable release published at that date (helm search repo <chart> --versions). Every version is overridable by environment variable.

ℹ️ Demo images (WordPress, MariaDB, nginx, alpine, busybox, PostgreSQL, MinIO) are pinned on purpose and are not part of this audit: bumping them only matters when a demo breaks.

🗺️ The catalogue#

./install.sh list prints the same list, always up to date. <distro> is spelled out below to stay unambiguous, but it is optional in both layouts.

🌐 Networking & TLS#

💾 Storage#

🗃️ Backup#

🐘 Databases#

🪪 Identity#

🔐 Secrets#

📈 Observability#

🛡️ Security#

🧪 Demos#

🌍 Remote access (Tailscale + Cloudflare)#

The .200 VIP is a host-only IP announced over ARP: reachable from the host, not routable as-is.

1. L3 — the host advertises the route:

   sudo tailscale up --advertise-routes=192.168.56.200/32
   

   Then approve it in the Tailscale console.

   ⚠️ Stay on the /32 (or fence it with an ACL): a /24 would also expose the Kubernetes API (:6443) and SSH on every node.

2. Name + TLS — a public Cloudflare wildcard *.<LAB_DOMAIN> → 192.168.56.200, in DNS-only (grey cloud): the Cloudflare proxy cannot reach a private 192.168.56.x IP. TLS is therefore terminated by Envoy, not by Cloudflare, so the Gateway must carry a publicly trusted certificate (Let's Encrypt, see cert-manager/). A Cloudflare Origin CA certificate would be rejected by browsers.

💡 With the default SELF_SIGNED=true, none of this is needed: an /etc/hosts line pointing at 192.168.56.200 is enough, and the domain never has to resolve publicly.

⚠️ Pitfalls#

• Read the summary line, every time. One line per script, printed before anything is touched: profile, domain, and whether a lab.env was found. It is the cheapest way to catch a resolution that went somewhere unexpected.
• Both labs cloned side by side, and no distribution argument. The neighbour signal points two ways at once, so the scripts stop and ask rather than pick. Say which one, or run from the lab you mean, in submodule layout.
• The lab directory renamed, in sibling layout. Both the lab lookup (LAB_REPO_NAME) and the neighbour detection match those two names literally, so a Vagrant-KubeADM-v2/ next door is found by neither and resolution falls back to this repo — silently. LAB_DIR is the fix. In submodule layout the directory name is irrelevant.
• A git pull in a lab does not move _k8s/: git submodule update --init --recursive after every pull.
• Two default StorageClasses. longhorn/values.yaml sets persistence.defaultClass: true and local-path-storage.yaml sets the is-default-class: "true" annotation. With both add-ons installed, a PVC without an explicit storageClassName lands on the most recently created SC, non-deterministically. Always name your SC.
• This layer needs a LoadBalancer Service that really gets an IP, and Cilium is the only CNI here that provides one on its own (L2/ARP). With calico, flannel or none, platform-up.sh installs metallb/ right after the CNI on the same range, so every CNI ends up with a reachable .200. Two things still leave the Gateway at EXTERNAL-IP <pending>: METALLB=false in lab.env, and applying envoy-gateway/Envoy-Proxy.yml by hand with its Cilium loadBalancerClass left in.
• Never MetalLB and Cilium. Two announcers on one range means two nodes answering ARP for .200: the entry point then works "one time in two", with nothing in any log to say so. metallb-up.sh refuses to install on a Cilium cluster, and platform never picks it there.
• Switching CNI on a live cluster is not supported: flatten the cluster from the lab (./kubeadm/cluster-reset.sh, or vagrant destroy), then re-bootstrap.
• The repo's own Kyverno policies are violated by the repo (require-requests-limits demands a limits.cpu the in-house manifests deliberately never set). The report is noisy by construction — see kyverno/.
• Metric emitters are off by default (serviceMonitor/podMonitor are false in trivy-operator, CloudNativePG and node-problem-detector): Prometheus scrapes nothing from them until you flip them on after installing observability.
• Never lower CP_MEM below 3072 in the lab's lab.env: stacking these add-ons on 2 GB control planes starves etcd. observability needs 4096.

📚 References#

• OPS-NC/Vagrant-Talos — the Talos lab, from vagrant up to a ready cluster · browsable docs
• OPS-NC/Vagrant-kubeadm — the Debian 13 + kubeadm lab · browsable docs
• Gateway API · Cilium · Envoy Gateway · cert-manager · Talos Linux · kubeadm

☸️k8s-playground — les ressources Kubernetes des labs Talos et kubeadm

./_k8s/platform-up.sh                # depuis la racine de l'un ou l'autre lab
./_k8s/install.sh longhorn vault      # addons, opt-in

📖 Documentation navigable : https://ops-nc.github.io/k8s-playground/ — une page autonome, bilingue (EN/FR), thème clair/sombre, reconstruite depuis ces fichiers README.md / LISEZ-MOI.md à chaque push sur main (make docs la construit en local).

Les deux labs restent responsables du bootstrap du cluster (VM, OS, kubeadm init / talosctl bootstrap). Ce dépôt couvre ce qui vient après, avec kubectl et helm depuis l'hôte — le CNI compris, parce qu'aucun des deux bootstraps ne laisse un réseau de pods utilisable.

⚡ Démarrage rapide#

On ne commence jamais ici : on commence dans un lab, là où vivent le cluster et son état.

# 1. Le lab — sous-module compris (jumeau Talos : OPS-NC/Vagrant-Talos)
git clone --recurse-submodules https://github.com/OPS-NC/Vagrant-kubeadm.git
cd Vagrant-kubeadm
cp lab.env.example lab.env               # le modèle du LAB : topologie, domaine, mode TLS, CNI
vagrant up && ./kubeadm/cluster-up.sh    # les nodes sont NotReady : pas encore de CNI

# 2. Poser la plateforme de base — rien à déclarer
./_k8s/platform-up.sh                # CNI → Envoy Gateway → metrics-server → TLS wildcard

# 3. Les addons, opt-in
./_k8s/install.sh longhorn vault argocd
./_k8s/install.sh list               # le catalogue complet
./_k8s/install.sh all                # plateforme + tous les addons, dans l'ordre des dépendances

Depuis la racine du lab, ce dépôt est <lab>/_k8s : le lab est son parent, reconnu à son Vagrantfile, et la distribution se lit sur la structure de ce lab — kubeadm/cluster-up.sh ici, talos/cluster-up.sh chez le jumeau Talos. KUBECONFIG est déduit de la même façon (<lab>/kubeconfig) ; ne l'exporte que pour tes propres appels kubectl. Passer la distribution explicitement fonctionne toujours et gagne toujours, ce qui reste le moyen le plus sûr de savoir ce qu'on a lancé : ./_k8s/install.sh kubeadm platform.

Chaque composant s'exécute aussi tout seul :

./_k8s/longhorn/longhorn-up.sh

🎓 Mode apprentissage. Chaque dossier livre un README.md (EN) / LISEZ-MOI.md (FR) avec une section « Pas à pas guidé » : la même installation, commande par commande, avec ce qu'il faut observer à chaque étape et les variantes par distribution. Le script tout-en-un et le pas à pas font exactement la même chose.

cd ../Vagrant-Talos && ./talos/cluster-up.sh    # ou ../Vagrant-KubeADM && ./kubeadm/cluster-up.sh

cd ../k8s-playground                 # ce dépôt, voisin du lab
./install.sh talos platform          # un seul lab à côté ⇒ l'argument est optionnel ici aussi

git clone --recurse-submodules https://github.com/OPS-NC/Vagrant-kubeadm.git
git submodule update --init --recursive   # remplit _k8s/ sur un clone déjà fait
git submodule update --remote _k8s        # déplace _k8s/ sur le dernier commit de ce dépôt

⚠️ Un git pull dans le lab ne met PAS le sous-module à jour. Il ne déplace que le dépôt du lab ; _k8s/ reste sur le commit épinglé avant, et tu exécuterais les commandes documentées contre une couche applicative plus ancienne. Fais suivre chaque pull de git submodule update --init --recursive. Et un _k8s/ vide — ./_k8s/install.sh: No such file or directory — signifie toujours une seule chose : le sous-module n'a jamais été initialisé.

💡 Modifier cette couche est une modification faite ici. Vu depuis un lab, _k8s/ est un checkout de ce dépôt sur un HEAD détaché : les fichiers qu'on y édite appartiennent à ce dépôt, et un git commit lancé dans _k8s/ commite ici. Le chemin est donc : PR sur ce dépôt → merge → dans le lab, git submodule update --remote _k8s, puis commit du pointeur déplacé. Ce commit est la montée de version de la couche applicative.

📍 Où sont trouvés lab.env et _out/#

Les scripts ne stockent rien. lab.env (l'intention : domaine, mode TLS, CNI, taille des VM) et _out/ (les faits : talosconfig, cluster.env, l'AC locale, vault-init.json…) vivent dans le dépôt du lab, avec le kubeconfig à côté. Il y a exactement une source de vérité pour la topologie, et c'est celle du lab — d'où l'absence de lab.env et de modèle de lab.env ici. _resolve_lab_dir(), dans lib/common.sh, cherche ce dossier dans cet ordre :

KUBECONFIG suit le même dossier : sauf s'il est déjà exporté, il devient <dossier lab>/kubeconfig.

Un Vagrantfile est la marque non ambiguë d'un lab : il est là dès le clone, avant tout vagrant up, et il n'apparaît jamais au-dessus de ce dépôt dans la disposition voisine. La règle 2 passe volontairement avant la règle 4, pour qu'un _out/ résiduel (ou un lab.env déposé ici pour un test) ne puisse jamais masquer le vrai lab situé juste au-dessus.

Chaque script affiche sa résolution avant de toucher à quoi que ce soit, sur une ligne :

    profil kubeadm (Debian 13 + kubeadm) · domaine *.kubeadm.lab.example.io · lab.env absent (défauts)

lab.env absent (défauts) sur un lab qui a un lab.env, ou un domaine qui n'est pas celui que tu as posé, signifie que la résolution a raté le lab. Force-la :

LAB_DIR=~/labs/mon-lab          ./install.sh talos platform   # lab.env + _out/ + kubeconfig, tout est là
LAB_ENV=~/labs/mon-lab/lab.env  ./install.sh talos platform   # son dossier devient le dossier du lab

💡 Un signal de plus se déclenche, sur kubeadm seulement : platform-up.sh avertit quand _out/cluster.env manque — « ./kubeadm/cluster-up.sh n'a pas été lancé (ou pas jusqu'au bout) ». Soit le bootstrap n'est vraiment pas allé au bout, soit le lab résolu n'était pas le bon. L'avertissement est non bloquant, et Talos n'a pas d'équivalent (ce lab n'a pas de cluster.env).

⚠️ Ne crée pas de lab.env à la racine de ce dépôt. La règle 4 en accepte un, pour exercer ce dépôt sans lab, mais un second lab.env est une seconde vérité qui dérive de celle du lab dès que l'une des deux change. C'est pour ça qu'il n'y a pas de lab.env.example ici : le modèle à copier vit dans le lab.

🎯 Comment la distribution est choisie#

Par ordre de priorité :

Les sources 5 à 8 sont _detect_distro(), ordonnées par la précocité du signal : la structure fonctionne dès le git clone, avant tout vagrant up ; les artefacts couvrent un lab dont les dossiers ont été renommés ; les voisins rejouent le même test sur ../Vagrant-Talos et ../Vagrant-KubeADM, et refusent de décider quand les deux sont là — deviner serait une chance sur deux de déployer sur le mauvais cluster ; le sondage vient en dernier parce qu'il a besoin d'un KUBECONFIG déjà correct, lequel est déduit du dossier du lab, lequel vient du profil, qui est justement ce qu'on cherche à choisir.

Sans aucune de ces sources, les scripts refusent de tourner : appliquer un manifeste taillé pour Talos sur Debian (ou l'inverse) ne produit pas une erreur propre mais une panne silencieuse — un Deployment créé alors qu'aucun pod ne démarre jamais.

ℹ️ Les sources 4 à 6 ont besoin que le lab soit localisé d'abord, et c'est là que la disposition compte. En sous-module, la règle du Vagrantfile parent se déclenche avant tout chargement de profil, donc les trois fonctionnent nues — c'est ce qui rend ./_k8s/platform-up.sh autonome. En disposition voisine, aucun lab n'est localisé à ce moment-là (LAB_REPO_NAME vient du profil) : la source 7 prend le relais, et ./install.sh platform fonctionne nu depuis ici aussi tant qu'un seul lab est à côté.

🧬 Ce qui diffère vraiment entre les deux labs#

Tout est concentré dans lib/profiles/talos.sh et lib/profiles/kubeadm.sh : les scripts d'installation ne testent jamais la distribution par des if éparpillés, ils lisent des variables.

ℹ️ kube-proxy : même résultat, deux mécanismes. Les deux labs ont KUBE_PROXY_REPLACEMENT=true par défaut, donc sur les deux le cluster de référence tourne sans aucun kube-proxy et Cilium sert les Services en eBPF. Seule la façon dont le bootstrap s'en débarrasse diffère. La valeur se décide au bootstrap — ce n'est pas un interrupteur à chaud — et elle exige CNI=cilium des deux côtés, puisque rien d'autre ici ne remplace kube-proxy.

Tout le reste — Argo CD, Kyverno, MinIO, CloudNativePG, Vault, Envoy Gateway, cert-manager, chaoskube, node-problem-detector, WordPress — est strictement identique sur les deux distributions.

🗂️ Organisation du dépôt#

install.sh                  point d'entrée : ./install.sh [talos|kubeadm] <composant...>
platform-up.sh              la plateforme de base (CNI → Gateway → metrics → TLS)
metric-server.yaml          metrics-server (appliqué par platform-up.sh)
lib/
  common.sh                 socle partagé : résolution de distro, lecture de lab.env, helpers
  profiles/talos.sh         TOUT ce qui est propre à Talos
  profiles/kubeadm.sh       TOUT ce qui est propre à kubeadm/Debian
<composant>/
  <composant>-up.sh         l'installation tout-en-un
  values.yaml / *.yaml      manifestes et values (valeurs NEUTRES, substituées à la volée)
  README.md / LISEZ-MOI.md  doc EN/FR + pas à pas guidé
docs/build.py               construit le site en une page depuis tous les README (make docs)
Makefile                    docs, docs-check, validate — tout ce qui tourne sans cluster

En disposition sous-module, toute cette arborescence pend sous le _k8s/ du lab. Les chemins internes à ce dépôt sont les mêmes dans les deux cas, ce qui explique que chaque pas à pas soit écrit depuis la racine de ce dépôt.

Il n'y a ni Vagrantfile, ni _out/, ni lab.env ici, par construction : ce dépôt possède les manifestes, le lab possède le cluster et son état. Cette absence porte quelque chose — c'est elle qui fait de « le parent contient un Vagrantfile » un moyen non ambigu de repérer le lab.

🔗 Chaîne de dépendances#

Chaque maillon suppose le précédent : pas d'IP de LoadBalancer sans annonceur L2, pas de HTTPS sans le Gateway, pas d'UI sans certificat sur le listener :443.

cluster bootstrapé  (lab Talos ou lab kubeadm — nodes NotReady, pas de CNI)
   │
   ├─ 1. CNI              cilium/ (défaut, + pool L2 → IP LoadBalancer .200)
   │                      ou calico/ (CNI seul) ou flannel (CNI seul) ou rien
   │     + annonceur L2   metallb/ — SEULEMENT si le CNI n'est pas cilium, sur la MÊME plage
   │                      (ignoré avec METALLB=false : aucune IP de LoadBalancer)
   ├─ 2. envoy-gateway/   contrôleur Envoy + main-gateway (listeners :80 et :443)
   ├─ 3. metric-server    API metrics.k8s.io  (kubectl top, HPA)
   └─ 4. TLS wildcard     *.<LAB_DOMAIN> — deux modes, selon SELF_SIGNED
              │             true (défaut) → self-signed/   openssl, AC locale
              │             false         → cert-manager/  Let's Encrypt DNS-01 Cloudflare
              │
              └─ addons : stockage → sauvegarde → bases → identité → secrets → observabilité
                          → sécurité

C'est exactement l'ordre de platform-up.sh ([1/4] → [4/4]). Les deux modes TLS remplissent le même Secret (wildcard-<LAB_DOMAIN avec tirets>-tls), donc aucun addon n'a à savoir lequel tu as choisi.

🌐 LAB_DOMAIN — le domaine des UI#

Le dépôt est public : aucun manifeste ne porte de vraie valeur. Trois marqueurs neutres sont substitués à la volée (le helper render de lib/common.sh), sans jamais réécrire un fichier versionné — git status reste propre :

LAB_DOMAIN se pose dans le lab.env du lab, jamais ici :

echo 'LAB_DOMAIN=k8s.mon-domaine.tld' >> lab.env      # dans Vagrant-Talos/ ou Vagrant-KubeADM/

⚠️ Un domaine qui reste à <distro>.lab.example.io alors que lab.env dit autre chose est le premier symptôme d'un lab.env jamais trouvé : vérifie quel lab a été résolu (la ligne de résumé) avant de soupçonner la substitution.

⚠️ Les manifestes appliqués à la main (sans *-up.sh) ne reçoivent aucune substitution : wordpress-example/wordpress-mariadb.yaml, vault-secret-operator/k8s/*.yaml, cert-manager/04-gateway-https-example.yaml. Passe-les par le même sed :

sed 's/lab\.example\.io/k8s.mon-domaine.tld/g' <fichier> | kubectl apply -f -

📦 Versions épinglées#

Auditées le 1er août 2026 : tout est sur la dernière version stable publiée à cette date (helm search repo <chart> --versions). Chaque version est surchargeable par variable d'environnement.

ℹ️ Les images de démo (WordPress, MariaDB, nginx, alpine, busybox, PostgreSQL, MinIO) sont épinglées à dessein et ne font pas partie de cet audit : les monter n'a d'intérêt que quand une démo casse.

🗺️ Le catalogue#

./install.sh list affiche la même liste, toujours à jour. <distro> est écrit ci-dessous pour lever toute ambiguïté, mais il est optionnel dans les deux dispositions.

🌐 Réseau & TLS#

💾 Stockage#

🗃️ Sauvegarde#

🐘 Bases de données#

🪪 Identité#

🔐 Secrets#

📈 Observabilité#

🛡️ Sécurité#

🧪 Démos#

🌍 Accès distant (Tailscale + Cloudflare)#

La VIP .200 est une IP host-only annoncée en ARP : joignable depuis l'hôte, non routable telle quelle.

1. L3 — l'hôte annonce la route :

   sudo tailscale up --advertise-routes=192.168.56.200/32
   

   Puis approuve-la dans la console Tailscale.

   ⚠️ Reste sur le /32 (ou barrière par ACL) : un /24 exposerait aussi l'API Kubernetes (:6443) et SSH sur tous les nodes.

2. Nom + TLS — un wildcard Cloudflare public *.<LAB_DOMAIN> → 192.168.56.200, en DNS-only (nuage gris) : le proxy Cloudflare ne peut pas joindre une IP privée 192.168.56.x. TLS est donc terminé par Envoy, pas par Cloudflare, donc le Gateway doit porter un certificat reconnu publiquement (Let's Encrypt, voir cert-manager/). Un certificat Cloudflare Origin CA serait rejeté par les navigateurs.

💡 Avec le défaut SELF_SIGNED=true, rien de tout ça n'est nécessaire : une ligne /etc/hosts pointant 192.168.56.200 suffit, et le domaine n'a jamais à résoudre publiquement.

⚠️ Pièges#

• Lis la ligne de résumé, à chaque fois. Une ligne par script, affichée avant de toucher à quoi que ce soit : profil, domaine, et si un lab.env a été trouvé. C'est le moyen le moins cher d'attraper une résolution partie ailleurs.
• Les deux labs clonés côte à côte, sans argument de distribution. Le signal du voisin pointe dans deux directions à la fois : les scripts s'arrêtent et demandent plutôt que de choisir. Dis lequel, ou lance depuis le lab visé, en disposition sous-module.
• Le dossier du lab renommé, en disposition voisine. La recherche du lab (LAB_REPO_NAME) et la détection du voisin correspondent à ces deux noms littéralement : un Vagrant-KubeADM-v2/ à côté n'est trouvé par aucun des deux, et la résolution retombe sur ce dépôt — en silence. LAB_DIR est le remède. En sous-module, le nom du dossier n'a aucune importance.
• Un git pull dans un lab ne déplace pas _k8s/ : git submodule update --init --recursive après chaque pull.
• Deux StorageClass par défaut. longhorn/values.yaml pose persistence.defaultClass: true et local-path-storage.yaml pose l'annotation is-default-class: "true". Les deux addons installés, un PVC sans storageClassName explicite atterrit sur la SC créée le plus récemment, de façon non déterministe. Nomme toujours ta SC.
• Cette couche a besoin d'un Service LoadBalancer qui obtienne vraiment une IP, et Cilium est le seul CNI ici à en fournir une tout seul (L2/ARP). Avec calico, flannel ou none, platform-up.sh installe metallb/ juste après le CNI, sur la même plage, pour que tous les CNI finissent avec un .200 joignable. Deux choses laissent encore le Gateway en EXTERNAL-IP <pending> : METALLB=false dans lab.env, et appliquer envoy-gateway/Envoy-Proxy.yml à la main avec son loadBalancerClass Cilium dedans.
• Jamais MetalLB et Cilium. Deux annonceurs sur une plage, c'est deux nodes qui répondent à l'ARP pour .200 : le point d'entrée fonctionne alors « une fois sur deux », sans rien dans aucun log. metallb-up.sh refuse de s'installer sur un cluster Cilium, et platform ne le choisit jamais là.
• Changer de CNI sur un cluster vivant n'est pas supporté : rase le cluster depuis le lab (./kubeadm/cluster-reset.sh, ou vagrant destroy), puis re-bootstrape.
• Les politiques Kyverno du dépôt sont violées par le dépôt (require-requests-limits exige un limits.cpu que les manifestes maison ne posent volontairement jamais). Le rapport est bruyant par construction — voir kyverno/.
• Les émetteurs de métriques sont désactivés par défaut (serviceMonitor/podMonitor à false dans trivy-operator, CloudNativePG et node-problem-detector) : Prometheus ne scrape rien chez eux avant que tu ne les actives, après l'installation d'observability.
• Ne descends jamais CP_MEM sous 3072 dans le lab.env du lab : empiler ces addons sur des control planes de 2 Go affame etcd. observability demande 4096.

📚 Références#

• OPS-NC/Vagrant-Talos — le lab Talos, du vagrant up au cluster prêt · doc navigable
• OPS-NC/Vagrant-kubeadm — le lab Debian 13 + kubeadm · doc navigable
• Gateway API · Cilium · Envoy Gateway · cert-manager · Talos Linux · kubeadm

🐝cilium/ — CNI, LoadBalancer IPs and L2 announcement (ARP)

🎯 Purpose#

• CNI in VXLAN tunnel mode, pinned to the host-only interface (see ⚠️ Pitfalls).
• LoadBalancer IPs: a .200-.230 pool stands in for the missing cloud provider.
• L2 announcement (ARP): the IP becomes reachable from the host, hence over Tailscale (see ../README.md, "Remote access" section).
• Network observability: Hubble (relay + UI) is enabled and the UI is exposed at hubble.<LAB_DOMAIN> — handy for showing flows, and with no authentication.

📋 Prerequisites#

⚡ Install#

Through the repository entry point:

./install.sh <distro> cilium     # <distro> = talos | kubeadm

./cilium/cilium-up.sh <distro>

Chart cilium/cilium 1.20.0, read from lab.env (CILIUM_VERSION) and overridable per run (CILIUM_VERSION=1.20.1 ./cilium/cilium-up.sh). Idempotent (helm upgrade --install + kubectl apply). ../platform-up.sh calls it as step [1/4] — so there is nothing to run here if you go through the full platform.

⚠️ Do not take §9 of the root README as the installation reference. It shows the "manual" helm upgrade to explain who installs the CNI, but without --version (you get the latest published release, not the one validated here) and without applying cilium-l2.yml — so without an IP pool: the Gateway would stay at EXTERNAL-IP <pending>. The source of truth is cilium-up.sh.

🧬 Talos vs kubeadm#

This is the most distribution-dependent component in the whole repository.

Source: lib/profiles/<distro>.sh (CILIUM_IPAM_MODE, cilium_specific_sets(), KUBE_PROXY_REPLACEABLE, DEFAULT_HOSTONLY_IF).

🎓 Guided walkthrough (step by step)#

The commands below are exactly what the all-in-one script does, in order. Set up your shell first (once per session):

export KUBECONFIG=../Vagrant-Talos/kubeconfig        # or ../Vagrant-KubeADM/kubeconfig
export LAB_DOMAIN=talos.lab.example.io               # or your own (see the lab's lab.env)

1. Check the starting point#

kubectl get nodes                 # NotReady everywhere: that is EXPECTED, there is no CNI yet
kubectl get ds -A | grep -Ei 'cilium|flannel|calico'   # must be EMPTY (one CNI per cluster)

2. Collect the lab parameters#

# kubeadm: the FACTS live in _out/cluster.env (written by cluster-up.sh)
grep -E 'HOSTONLY_IF|POD_CIDR|KUBE_PROXY_REPLACEMENT' ../Vagrant-KubeADM/_out/cluster.env
# Talos: no cluster.env — lab.env is the source, and the machine config is the ground truth
grep -A2 podSubnets ../Vagrant-Talos/_out/controlplane.yaml
grep -A2 '^    proxy:' ../Vagrant-Talos/_out/controlplane.yaml   # disabled: true => no kube-proxy

3. Add the Helm repository#

helm repo add cilium https://helm.cilium.io/ && helm repo update cilium
helm search repo cilium/cilium --versions | head -3      # check the latest stable

4. Install Cilium — the command differs per distribution#

helm upgrade --install cilium cilium/cilium -n kube-system --create-namespace \
  --version 1.20.0 \
  --set envoy.enabled=false \
  --set kubeProxyReplacement=true \
  --set k8sServiceHost=192.168.56.5 --set k8sServicePort=6443 \
  --set routingMode=tunnel --set tunnelProtocol=vxlan \
  --set ipam.mode=kubernetes \
  --set l2announcements.enabled=true --set externalIPs.enabled=true \
  --set hubble.enabled=true --set hubble.relay.enabled=true --set hubble.ui.enabled=true \
  --set bandwidthManager.enabled=true \
  --set devices=enp0s8 \
  --set cgroup.autoMount.enabled=false --set cgroup.hostRoot=/sys/fs/cgroup \
  --set securityContext.capabilities.ciliumAgent="{CHOWN,KILL,NET_ADMIN,NET_RAW,IPC_LOCK,SYS_ADMIN,SYS_RESOURCE,DAC_OVERRIDE,FOWNER,SETGID,SETUID}" \
  --set securityContext.capabilities.cleanCiliumState="{NET_ADMIN,SYS_ADMIN,SYS_RESOURCE}"

helm upgrade --install cilium cilium/cilium -n kube-system --create-namespace \
  --version 1.20.0 \
  --set envoy.enabled=false \
  --set kubeProxyReplacement=true \
  --set k8sServiceHost=192.168.56.5 --set k8sServicePort=6443 \
  --set routingMode=tunnel --set tunnelProtocol=vxlan \
  --set ipam.mode=cluster-pool \
  --set ipam.operator.clusterPoolIPv4PodCIDRList='{10.244.0.0/16}' \
  --set ipam.operator.clusterPoolIPv4MaskSize=24 \
  --set l2announcements.enabled=true --set externalIPs.enabled=true \
  --set hubble.enabled=true --set hubble.relay.enabled=true --set hubble.ui.enabled=true \
  --set bandwidthManager.enabled=true \
  --set devices=eth1        # ⚠️ use the value DETECTED in _out/cluster.env

5. Wait for the CNI to unblock the nodes#

kubectl wait --for=condition=Ready nodes --all --timeout=300s
kubectl -n kube-system get pods -l k8s-app=cilium -o wide

6. Apply the LoadBalancer IP pool + L2 (ARP) announcement#

This is what gives the Gateway Service a real IP (the lab's "cloud provider").

sed -e 's/192\.168\.56\.200/192.168.56.200/' \
    -e 's/enp0s8/eth1/' \
    cilium/cilium-l2.yml | kubectl apply -f -     # on Talos: keep enp0s8
kubectl get ciliumloadbalancerippool
kubectl get ciliuml2announcementpolicy

7. Verify#

kubectl -n kube-system exec ds/cilium -- cilium-dbg status --verbose | head -30
# kube-proxy replaced? (either lab with KUBE_PROXY_REPLACEMENT=true: NotFound is expected)
kubectl -n kube-system get ds kube-proxy 2>&1 | tail -1

🔧 What the script does#

1. Reads _out/cluster.env (then lab.env as a fallback): HOSTONLY_IF, POD_CIDR, VIP, KUBE_PROXY_REPLACEMENT — detected facts on kubeadm, lab.env intents on Talos, which has no cluster.env;
2. installs Cilium with Helm in kube-system with the values below;
3. waits for condition=Ready on every node (300 s max) — the CNI is what unblocks them;
4. applies cilium-l2.yml: LoadBalancer IP pool + ARP announcement policy, with the pool range and the interface name substituted in.

The --set flags that matter#

⚠️ What is deliberately absent. The Cilium docs' Talos page recommends cgroup.autoMount.enabled=false, cgroup.hostRoot=/sys/fs/cgroup and explicit securityContext.capabilities.* lists. Those are Talos workarounds and they are actively harmful on Debian: the chart mounts cgroup2 itself and computes the capabilities the agent needs. Do not copy them back in.

cilium-l2.yml — two objects#

Why these choices:

• .200-.230 range: clear of the node IPs (CP .10/.20/.30, workers .101+), of the API VIP .5 and of the gateway .1. Keep it aligned if you change the IP plan in lab.env.
• Host-only interface: the only NIC through which the host can reach the VMs. The manifest ships ^enp0s8$ as the default; cilium-up.sh rewrites it from HOSTONLY_IF in _out/cluster.env, so a box that names it eth1 works with no edit.
• Workers only: keeps a control plane from answering ARP for the VIP. On a single-node topology (no worker), you have to drop the nodeSelector, otherwise nobody announces anything.

✅ Verify#

kubectl -n kube-system get pods -l k8s-app=cilium              # one agent per node, Running
kubectl get nodes                                              # all Ready
kubectl get ciliumloadbalancerippool                           # lb-pool-56, DISABLED=false, IPS AVAILABLE
kubectl get ciliuml2announcementpolicy                         # l2-lb-workers
kubectl -n envoy-gateway-system get svc                        # EXTERNAL-IP = 192.168.56.200
ping -c1 192.168.56.200                                        # from the host: ARP must answer

# Agent-side diagnostics. ⚠️ the in-pod binary was RENAMED `cilium` -> `cilium-dbg` in
# v1.15: `... -- cilium status` no longer exists.
kubectl -n kube-system exec ds/cilium -- cilium-dbg status --verbose
kubectl -n kube-system exec ds/cilium -- cilium-dbg service list   # empty => no eBPF Services

With KUBE_PROXY_REPLACEMENT=true — the default of both labs — there is no kube-proxy DaemonSet in kube-system, and that is the expected state: cilium-dbg status must report KubeProxyReplacement: True.

🌐 Hubble UI#

Hubble (relay + UI) is enabled, and cilium-up.sh exposes it through the Gateway API at https://hubble.<LAB_DOMAIN> — the hubble HTTPRoute of httproute.yaml, in kube-system, attached to the https listener of main-gateway. TLS is the *.<LAB_DOMAIN> wildcard the listener already carries: nothing else to issue.

kubectl -n kube-system get httproute hubble
curl -sk -o /dev/null -w '%{http_code}\n' "https://hubble.$LAB_DOMAIN/"   # 200

⚠️ The Hubble UI has no authentication, and it shows the flows of every namespace. Behind this Gateway it is reachable by anyone who can reach the VIP. On a lab that is the point; anywhere else, put an Envoy Gateway SecurityPolicy (Basic Auth / OIDC) in front of it, or delete the route: kubectl -n kube-system delete httproute hubble.

Ordering, if you are reading the scripts: platform-up.sh calls cilium-up.sh at step [1/4], and it is step [2/4] that installs Envoy Gateway — so on a fresh install the Gateway API CRDs do not exist yet when Cilium goes in. cilium-up.sh therefore only applies the route when it finds the httproutes CRD, and platform-up.sh applies it itself right after main-gateway is up. Either way the route exists at the end of platform-up.sh.

Without exposure at all (or before the platform layer is up), the port-forward still works:

kubectl -n kube-system port-forward svc/hubble-ui 12000:80     # then http://localhost:12000

⚠️ Pitfalls#

• Service stuck at EXTERNAL-IP: <pending> → missing pool (cilium-l2.yml not applied), exhausted range, or l2announcements not enabled at install time (the typical case when you followed §9 of the root README instead of cilium-up.sh).
• VIP that answers ping from the host but not from a Tailscale peer → expected: ARP does not cross a router. You need --advertise-routes on the host (see ../README.md).
• --set autoDirectNodeRoutes=true (or ipv4NativeRoutingCIDR) is forbidden here: those are native routing options, incompatible with tunnel mode. The agent exits fatal ("auto-direct-node-routes cannot be used with tunneling") and loops in CrashLoopBackOff.
• Replacing kube-proxy is decided at bootstrap, not here — on both labs. KUBE_PROXY_REPLACEMENT=true makes kubeadm/cluster-up.sh run kubeadm init --skip-phases=addon/kube-proxy, and talos/cluster-up.sh add talos/patch-no-kube-proxy.yaml (cluster.proxy.disabled: true) to the generated machine config. This script then reads the same value back — from _out/cluster.env on kubeadm, from lab.env on Talos, where nothing detects it. Flipping only one of the two loses every Service in the cluster. Changing your mind means rebuilding the cluster, not re-running this script.
• k8sServiceHost is not optional without kube-proxy. Nothing provisions the 10.96.0.1 apiserver ClusterIP any more, so an agent that only knows kubernetes.default never connects and stays in CrashLoopBackOff on Unable to contact k8s api-server.
• Pod CIDR mismatch. ipam.mode=cluster-pool defaults to 10.0.0.0/8 regardless of the podSubnet given to kubeadm. Symptom: pods get 10.0.x.x addresses while kubectl get node -o jsonpath='{.spec.podCIDR}' says 10.244.x.0/24. Always pass POD_CIDR back (the script does).
• Do not re-run the script to "refresh" a cluster that is running a demo without reading the Helm diff: changing routingMode or devices cuts traffic while the agents redeploy.
• The two objects do NOT share an apiVersion, and that asymmetry is deliberate — verified against the Cilium 1.20.0 docs: CiliumLoadBalancerIPPool is cilium.io/v2, while CiliumL2AnnouncementPolicy is still cilium.io/v2alpha1. Aligning them "for consistency" is the mistake to avoid: the pool silently stops being served on v2alpha1, and the Gateway goes back to <pending>. If a future Cilium promotes the policy to v2, the symptom is an apiVersion rejection at kubectl apply — check with kubectl get crd ciliuml2announcementpolicies.cilium.io -o jsonpath='{.spec.versions[*].name}'.

📚 References#

• Cilium — kube-proxy replacement
• Cilium — IPAM cluster-pool
• Cilium — LoadBalancer IPAM
• Cilium — L2 Announcements
• ../metallb/README.md — the same announcement, for the other CNIs (never alongside this one: two announcers on one range is an ARP conflict)
• ../envoy-gateway/README.md — the consumer of the .200 VIP

🐝cilium/ — CNI, IP LoadBalancer et annonce L2 (ARP)

🎯 À quoi ça sert#

• CNI en mode tunnel VXLAN, épinglé sur l'interface host-only (cf. ⚠️ Pièges).
• IP LoadBalancer : un pool .200-.230 remplace le cloud provider absent.
• Annonce L2 (ARP) : l'IP devient joignable depuis l'hôte, donc via Tailscale (cf. ../LISEZ-MOI.md, section « Accès distant »).
• Observabilité réseau : Hubble (relay + UI) est activé et l'UI est exposée sur hubble.<LAB_DOMAIN> — pratique pour montrer les flux, et sans aucune authentification.

📋 Prérequis#

⚡ Installation#

Via le point d'entrée du dépôt :

./install.sh <distro> cilium     # <distro> = talos | kubeadm

./cilium/cilium-up.sh <distro>

Chart cilium/cilium 1.20.0, lu dans lab.env (CILIUM_VERSION) et surchargeable au coup par coup (CILIUM_VERSION=1.20.1 ./cilium/cilium-up.sh). Idempotent (helm upgrade --install + kubectl apply). ../platform-up.sh l'appelle en étape [1/4] — tu n'as donc rien à lancer ici si tu déroules la plateforme complète.

⚠️ Ne prends pas le §9 du README racine comme référence d'installation. Il montre le helm upgrade « à la main » pour expliquer qui installe le CNI, mais sans --version (tu prends la dernière release publiée, pas celle validée ici) et sans appliquer cilium-l2.yml — donc sans pool d'IP : la Gateway resterait en EXTERNAL-IP <pending>. La source de vérité, c'est cilium-up.sh.

🧬 Talos vs kubeadm#

C'est le composant le plus dépendant de la distribution de tout le dépôt.

Source : lib/profiles/<distro>.sh (CILIUM_IPAM_MODE, cilium_specific_sets(), KUBE_PROXY_REPLACEABLE, DEFAULT_HOSTONLY_IF).

🎓 Pas à pas guidé (formation)#

Les commandes ci-dessous sont exactement ce que fait le script tout-en-un, dans l'ordre. Prépare d'abord l'environnement (une fois par session) :

export KUBECONFIG=../Vagrant-Talos/kubeconfig        # ou ../Vagrant-KubeADM/kubeconfig
export LAB_DOMAIN=talos.lab.example.io               # ou ton domaine (cf. lab.env du lab)

1. Vérifier le point de départ#

kubectl get nodes                 # NotReady partout : c'est NORMAL, il n'y a pas de CNI
kubectl get ds -A | grep -Ei 'cilium|flannel|calico'   # doit être VIDE (un seul CNI par cluster)

2. Relever les paramètres du lab#

# kubeadm : les FAITS sont dans _out/cluster.env (écrit par cluster-up.sh)
grep -E 'HOSTONLY_IF|POD_CIDR|KUBE_PROXY_REPLACEMENT' ../Vagrant-KubeADM/_out/cluster.env
# Talos : pas de cluster.env — lab.env est la source, et la config machine est la vérité
grep -A2 podSubnets ../Vagrant-Talos/_out/controlplane.yaml
grep -A2 '^    proxy:' ../Vagrant-Talos/_out/controlplane.yaml   # disabled: true => pas de kube-proxy

3. Ajouter le dépôt Helm#

helm repo add cilium https://helm.cilium.io/ && helm repo update cilium
helm search repo cilium/cilium --versions | head -3      # vérifier la dernière stable

4. Installer Cilium — la commande diffère selon la distribution#

helm upgrade --install cilium cilium/cilium -n kube-system --create-namespace \
  --version 1.20.0 \
  --set envoy.enabled=false \
  --set kubeProxyReplacement=true \
  --set k8sServiceHost=192.168.56.5 --set k8sServicePort=6443 \
  --set routingMode=tunnel --set tunnelProtocol=vxlan \
  --set ipam.mode=kubernetes \
  --set l2announcements.enabled=true --set externalIPs.enabled=true \
  --set hubble.enabled=true --set hubble.relay.enabled=true --set hubble.ui.enabled=true \
  --set bandwidthManager.enabled=true \
  --set devices=enp0s8 \
  --set cgroup.autoMount.enabled=false --set cgroup.hostRoot=/sys/fs/cgroup \
  --set securityContext.capabilities.ciliumAgent="{CHOWN,KILL,NET_ADMIN,NET_RAW,IPC_LOCK,SYS_ADMIN,SYS_RESOURCE,DAC_OVERRIDE,FOWNER,SETGID,SETUID}" \
  --set securityContext.capabilities.cleanCiliumState="{NET_ADMIN,SYS_ADMIN,SYS_RESOURCE}"

helm upgrade --install cilium cilium/cilium -n kube-system --create-namespace \
  --version 1.20.0 \
  --set envoy.enabled=false \
  --set kubeProxyReplacement=true \
  --set k8sServiceHost=192.168.56.5 --set k8sServicePort=6443 \
  --set routingMode=tunnel --set tunnelProtocol=vxlan \
  --set ipam.mode=cluster-pool \
  --set ipam.operator.clusterPoolIPv4PodCIDRList='{10.244.0.0/16}' \
  --set ipam.operator.clusterPoolIPv4MaskSize=24 \
  --set l2announcements.enabled=true --set externalIPs.enabled=true \
  --set hubble.enabled=true --set hubble.relay.enabled=true --set hubble.ui.enabled=true \
  --set bandwidthManager.enabled=true \
  --set devices=eth1        # ⚠️ la valeur DÉTECTÉE dans _out/cluster.env

5. Attendre que le CNI débloque les nodes#

kubectl wait --for=condition=Ready nodes --all --timeout=300s
kubectl -n kube-system get pods -l k8s-app=cilium -o wide

6. Poser le pool d'IP LoadBalancer + l'annonce L2 (ARP)#

C'est ce qui donne une vraie IP au Service du Gateway (le « cloud provider » du lab).

sed -e 's/192\.168\.56\.200/192.168.56.200/' \
    -e 's/enp0s8/eth1/' \
    cilium/cilium-l2.yml | kubectl apply -f -     # sur Talos : laisser enp0s8
kubectl get ciliumloadbalancerippool
kubectl get ciliuml2announcementpolicy

7. Vérifier#

kubectl -n kube-system exec ds/cilium -- cilium-dbg status --verbose | head -30
# kube-proxy remplacé ? (les deux labs avec KUBE_PROXY_REPLACEMENT=true : NotFound est normal)
kubectl -n kube-system get ds kube-proxy 2>&1 | tail -1

🔧 Ce que fait le script#

1. Lit _out/cluster.env (puis lab.env en repli) : HOSTONLY_IF, POD_CIDR, VIP, KUBE_PROXY_REPLACEMENT — des faits détectés sur kubeadm, des intentions de lab.env sur Talos, qui n'a pas de cluster.env ;
2. installe Cilium en Helm dans kube-system avec les valeurs ci-dessous ;
3. attend condition=Ready sur tous les nodes (300 s max) — c'est le CNI qui les débloque ;
4. applique cilium-l2.yml : pool d'IP LoadBalancer + politique d'annonce ARP, avec la plage et le nom de l'interface substitués.

Les --set qui comptent#

⚠️ Ce qui est volontairement absent. La page « Talos » de la doc Cilium recommande cgroup.autoMount.enabled=false, cgroup.hostRoot=/sys/fs/cgroup et des listes explicites de securityContext.capabilities.*. Ce sont des contournements Talos, activement nuisibles sur Debian : le chart monte lui-même le cgroup2 et calcule les capabilities dont l'agent a besoin. Ne les remets pas.

cilium-l2.yml — deux objets#

Pourquoi ces choix :

• Plage .200-.230 : hors des IP de nodes (CP .10/.20/.30, workers .101+), de la VIP d'API .5 et de la passerelle .1. À garder alignée si tu changes le plan d'adressage de lab.env.
• Interface host-only : la seule carte par laquelle l'hôte peut joindre les VMs. Le manifeste porte ^enp0s8$ comme défaut ; cilium-up.sh le réécrit depuis HOSTONLY_IF de _out/cluster.env, donc une box qui la nomme eth1 marche sans rien éditer.
• Workers seulement : évite qu'un control plane réponde à l'ARP du VIP. Sur une topologie single node (aucun worker), il faut retirer le nodeSelector, sinon plus personne n'annonce.

✅ Vérifier#

kubectl -n kube-system get pods -l k8s-app=cilium              # un agent par node, Running
kubectl get nodes                                              # tous Ready
kubectl get ciliumloadbalancerippool                           # lb-pool-56, DISABLED=false, IPS AVAILABLE
kubectl get ciliuml2announcementpolicy                         # l2-lb-workers
kubectl -n envoy-gateway-system get svc                        # EXTERNAL-IP = 192.168.56.200
ping -c1 192.168.56.200                                        # depuis l'hôte : l'ARP doit répondre

# Diagnostic côté agent. ⚠️ le binaire dans le pod a été RENOMMÉ `cilium` -> `cilium-dbg`
# en v1.15 : `... -- cilium status` n'existe plus.
kubectl -n kube-system exec ds/cilium -- cilium-dbg status --verbose
kubectl -n kube-system exec ds/cilium -- cilium-dbg service list   # vide => aucun Service eBPF

Avec KUBE_PROXY_REPLACEMENT=true — le défaut des deux labs — il n'y a aucun DaemonSet kube-proxy dans kube-system, et c'est l'état attendu : cilium-dbg status doit afficher KubeProxyReplacement: True.

🌐 Hubble UI#

Hubble (relay + UI) est activé, et cilium-up.sh l'expose via la Gateway API sur https://hubble.<LAB_DOMAIN> — l'HTTPRoute hubble de httproute.yaml, dans kube-system, rattachée au listener https de main-gateway. Le TLS est le wildcard *.<LAB_DOMAIN> que le listener porte déjà : rien d'autre à émettre.

kubectl -n kube-system get httproute hubble
curl -sk -o /dev/null -w '%{http_code}\n' "https://hubble.$LAB_DOMAIN/"   # 200

⚠️ L'UI Hubble n'a aucune authentification, et elle montre les flux de tous les namespaces. Derrière cette Gateway, elle est joignable par quiconque atteint la VIP. Sur un lab c'est justement l'intérêt ; ailleurs, mets une SecurityPolicy Envoy Gateway (Basic Auth / OIDC) devant, ou supprime la route : kubectl -n kube-system delete httproute hubble.

L'ordre, si tu lis les scripts : platform-up.sh appelle cilium-up.sh à l'étape [1/4], et c'est l'étape [2/4] qui installe Envoy Gateway — donc sur une install neuve, les CRD de la Gateway API n'existent pas encore quand Cilium est posé. cilium-up.sh n'applique donc la route que s'il trouve la CRD httproutes, et platform-up.sh l'applique lui-même juste après que main-gateway soit debout. Dans les deux cas la route existe à la fin de platform-up.sh.

Sans exposition du tout (ou avant que la couche platform soit debout), le port-forward marche toujours :

kubectl -n kube-system port-forward svc/hubble-ui 12000:80     # puis http://localhost:12000

⚠️ Pièges#

• Service coincé en EXTERNAL-IP: <pending> → pool absent (cilium-l2.yml non appliqué), plage épuisée, ou l2announcements non activé à l'install (cas typique quand on a suivi le §9 du README racine au lieu de cilium-up.sh).
• VIP qui répond au ping depuis l'hôte mais pas depuis un peer Tailscale → normal : l'ARP ne traverse pas un routeur. Il faut --advertise-routes sur l'hôte (cf. ../LISEZ-MOI.md).
• --set autoDirectNodeRoutes=true (ou ipv4NativeRoutingCIDR) est interdit ici : ce sont des options de routage natif, incompatibles avec le mode tunnel. L'agent sort en fatal (« auto-direct-node-routes cannot be used with tunneling ») et boucle en CrashLoopBackOff.
• Le remplacement de kube-proxy se décide au bootstrap, pas ici — sur les deux labs. KUBE_PROXY_REPLACEMENT=true fait lancer à kubeadm/cluster-up.sh un kubeadm init --skip-phases=addon/kube-proxy, et fait ajouter à talos/cluster-up.sh le patch talos/patch-no-kube-proxy.yaml (cluster.proxy.disabled: true) dans la config machine générée. Ce script relit ensuite la même valeur — dans _out/cluster.env sur kubeadm, dans lab.env sur Talos, où rien ne la détecte. N'en changer qu'un des deux fait perdre TOUS les Services du cluster. Changer d'avis = reconstruire le cluster, pas relancer ce script.
• k8sServiceHost n'est pas optionnel sans kube-proxy. Plus rien ne provisionne la ClusterIP 10.96.0.1 de l'apiserver : un agent qui ne connaît que kubernetes.default ne se connecte jamais et boucle en CrashLoopBackOff sur Unable to contact k8s api-server.
• CIDR pod divergent. ipam.mode=cluster-pool part par défaut sur 10.0.0.0/8, quoi qu'on ait déclaré à kubeadm. Symptôme : les pods prennent des adresses 10.0.x.x alors que kubectl get node -o jsonpath='{.spec.podCIDR}' annonce 10.244.x.0/24. Il faut toujours repasser POD_CIDR (le script le fait).
• Ne relance pas le script pour « rafraîchir » un cluster en production de démo sans lire le diff Helm : un changement de routingMode ou de devices coupe le trafic le temps du redéploiement des agents.
• Les deux objets ne partagent PAS la même apiVersion, et cette asymétrie est voulue — vérifiée sur la documentation Cilium 1.20.0 : CiliumLoadBalancerIPPool est en cilium.io/v2, tandis que CiliumL2AnnouncementPolicy est toujours en cilium.io/v2alpha1. Les aligner « par cohérence » est justement l'erreur à ne pas faire : le pool cesse silencieusement d'être servi en v2alpha1, et le Gateway repasse en <pending>. Si une future version de Cilium promeut la policy en v2, le symptôme est un rejet d'apiVersion au kubectl apply — à vérifier avec kubectl get crd ciliuml2announcementpolicies.cilium.io -o jsonpath='{.spec.versions[*].name}'.

📚 Références#

• Cilium — kube-proxy replacement
• Cilium — IPAM cluster-pool
• Cilium — LoadBalancer IPAM
• Cilium — L2 Announcements
• ../metallb/LISEZ-MOI.md — la même annonce, pour les autres CNI (jamais à côté de celle-ci : deux annonceurs sur une plage, c'est un conflit ARP)
• ../envoy-gateway/LISEZ-MOI.md — le consommateur du VIP .200

🐆calico/ — alternative CNI: pod network + NetworkPolicy, no LoadBalancer IPs

🎯 Purpose#

What Calico does here#

• CNI: pod network over VXLAN on 10.244.0.0/16, natOutgoing to reach the Internet. It is what takes the nodes from NotReady to Ready.
• NetworkPolicy: the standard networking.k8s.io/v1 ones and the NetworkPolicy/GlobalNetworkPolicy of projectcalico.org/v3 (order, tiers, explicit deny, HostEndpoint…). That is the real reason this directory exists: working on micro-segmentation with the reference implementation.
• projectcalico.org/v3 API: the calico-apiserver is enabled, so Calico objects are read and written with kubectl, without installing calicoctl.

What Calico does not do — and why that blocks you#

⚠️ Calico does NOT announce LoadBalancer Service IPs on this lab. It can only do it over BGP (serviceLoadBalancerIPs in a BGPConfiguration), which requires a peer router to establish a session with. On a VirtualBox host-only network, that router does not exist. And Calico has no equivalent of Cilium's L2/ARP announcement (CiliumLoadBalancerIPPool + CiliumL2AnnouncementPolicy). That is why installation.yaml sets bgp: Disabled: it is not an oversight, it is a fact.

Concrete, not theoretical consequence: with CNI=calico and nothing else,

In other words: the whole k8s-playground/ layer of the lab depends on that VIP. So ../platform-up.sh no longer leaves you there: as soon as CNI != cilium it installs MetalLB right after this script, on the very same range and the same interface Cilium would have used. See 🌐 Making the UIs reachable.

Cilium or Calico?#

💡 Recommendation: keep Cilium as the lab default. Calico is here to compare CNIs and to work on NetworkPolicy, not to light up a complete lab without extra work.

📋 Prerequisites#

⚡ Install#

Through the repository entry point:

./install.sh <distro> calico     # <distro> = talos | kubeadm

./calico/calico-up.sh <distro>

Chart projectcalico/tigera-operator v3.32.1 (repo https://docs.tigera.io/calico/charts), pinned in the script via CALICO_VERSION. Idempotent (helm upgrade --install + kubectl apply), safe to re-run.

Overridable variables:

🧬 Talos vs kubeadm#

The installation.yaml manifest is shared, but two of its settings do not have the same status on both distributions:

Calico's eBPF dataplane stays off on both: it needs bpfNetworkBootstrap + FelixConfiguration, and it is broken on some Talos releases (siderolabs/talos#12221). For eBPF in this lab: use Cilium.

🎓 Guided walkthrough (step by step)#

The commands below are exactly what the all-in-one script does, in order. Set up your shell first (once per session):

export KUBECONFIG=../Vagrant-Talos/kubeconfig        # or ../Vagrant-KubeADM/kubeconfig
export LAB_DOMAIN=talos.lab.example.io               # or your own (see the lab's lab.env)

1. Guardrails (what the script checks before touching the cluster)#

kubectl get nodes                                        # NotReady: expected, no CNI yet
kubectl get ds -A | grep -Ei 'cilium|flannel'            # must be EMPTY
kubectl -n kube-system get ds kube-proxy                 # MUST exist (Calico won't replace it)

2. Operator namespace (PodSecurity labels)#

kubectl apply -f calico/namespace.yaml
kubectl get ns tigera-operator --show-labels

3. Tigera operator chart — all 4 chart CRs disabled#

The chart ships no crds/ directory: the operator creates the operator.tigera.io CRDs when it starts. Any CR rendered by Helm would therefore fail on a fresh cluster ("no matches for kind").

helm repo add projectcalico https://docs.tigera.io/calico/charts && helm repo update projectcalico
helm upgrade --install calico projectcalico/tigera-operator \
  --namespace tigera-operator --create-namespace \
  --version v3.32.1 \
  --set installation.enabled=false --set apiServer.enabled=false \
  --set goldmane.enabled=false --set whisker.enabled=false
kubectl -n tigera-operator rollout status deploy/tigera-operator --timeout=300s

4. Wait for the operator-created CRDs#

kubectl wait --for=condition=Established crd/installations.operator.tigera.io --timeout=60s
kubectl wait --for=condition=Established crd/apiservers.operator.tigera.io  --timeout=60s

5. Apply the Installation + APIServer CRs#

# The versioned CIDRs are the lab defaults: adjust if your lab.env differs
sed -e 's#192\.168\.56\.0/24#192.168.56.0/24#g' \
    -e 's#10\.244\.0\.0/16#10.244.0.0/16#g' \
    calico/installation.yaml | kubectl apply -f -
kubectl apply -f calico/apiserver.yaml

6. Wait for calico-node, then for the nodes#

kubectl -n calico-system rollout status daemonset/calico-node --timeout=600s
kubectl wait --for=condition=Ready nodes --all --timeout=300s
kubectl get tigerastatus

7. Verify — and understand what is MISSING#

kubectl get ippools.projectcalico.org         # through the calico-apiserver, no calicoctl
kubectl -n envoy-gateway-system get svc       # EXTERNAL-IP <pending>: EXPECTED with Calico

⚠️ Calico announces no LoadBalancer Service IP (BGP only). <pending> at this exact point is therefore normal: it is ../metallb/, installed by platform-up.sh right after this script, that fills the address in — see the 🌐 section.

🔧 What the script does#

1. Guardrails: binaries, /readyz, refusal if another CNI is already there, refusal if kube-proxy is missing (KUBE_PROXY_REPLACEMENT=true, the default of both labs), and refusal if POD_CIDR diverges from the POD_CIDR recorded in _out/cluster.env.
2. namespace.yaml — the tigera-operator namespace, created before the chart because it carries the PodSecurity privileged labels. Helm's --create-namespace sets no label. kubeadm enforces nothing cluster-wide by default, so this is insurance rather than a hard requirement — but it is what keeps the operator working on a hardened cluster (see ⚠️ Pitfalls).
3. tigera-operator chart in that namespace. The operator runs in hostNetwork: it starts without a CNI, which is what makes bootstrapping possible.
4. Waits for the operator.tigera.io CRDs: the operator is started with -manage-crds=true, so it is the one creating installations and apiservers.operator.tigera.io. Applying a CR before that fails with "no matches for kind …".
5. kubectl apply of installation.yaml, with both CIDRs substituted on the fly (same mechanism as LAB_DOMAIN in ../platform-up.sh), then of apiserver.yaml which deploys the calico-apiserver.
6. Bounded waits: the calico-system/calico-node DaemonSet created, rollout status (600 s, the time of the first pull on 8 VMs), then all nodes Ready (300 s). Each one fails with an error carrying the diagnostic command to run — no || true anywhere.
7. Summary + a yellow reminder of the two steps still missing for the lab UIs.

The Helm settings that matter#

The chart renders four custom resources (Installation, APIServer, Goldmane, Whisker) and ships no crds/ directory — the CRDs are created by the operator at runtime (-manage-crds=true). So every one of them has to be disabled at install time, otherwise Helm fails before it even creates the namespace:

Error: unable to build kubernetes objects from release manifest: resource mapping not found
for name: "default" ... no matches for kind "APIServer" in version "operator.tigera.io/v1"
ensure CRDs are installed first

The installation.yaml fields that matter#

✅ Verify#

kubectl -n tigera-operator get pods                       # tigera-operator Running
kubectl get tigerastatus                                  # calico / apiserver: AVAILABLE=True
kubectl -n calico-system get pods -o wide                 # one calico-node per node + typha
kubectl get nodes                                         # all Ready
kubectl get installation default -o yaml                  # the CR as the operator completed it
kubectl get ippools.projectcalico.org default-ipv4-ippool -o yaml   # cidr + vxlanMode Always

The check that really matters: the address picked by each node must be in 192.168.56.x, never 10.0.2.15.

COLS='NODE:.metadata.name'
COLS="$COLS,ADDR:.metadata.annotations.projectcalico\.org/IPv4Address"
COLS="$COLS,VXLAN:.metadata.annotations.projectcalico\.org/IPv4VXLANTunnelAddr"
kubectl get nodes -o "custom-columns=$COLS"

Then a cross-node traffic test (this is where the NAT NIC pitfall shows up):

kubectl run t1 --image=busybox --restart=Never --command -- sleep 3600
kubectl run t2 --image=busybox --restart=Never --command -- sleep 3600
kubectl get pods -o wide                                  # check they are on 2 different nodes
kubectl exec t1 -- ping -c3 "$(kubectl get pod t2 -o jsonpath='{.status.podIP}')"
kubectl exec t1 -- nslookup kubernetes.default            # DNS = CoreDNS, often on another node
kubectl delete pod t1 t2

🌐 Making the lab UIs reachable (MetalLB)#

Calico provides no LoadBalancer IP — but you no longer have to do anything about it. Both steps that used to be manual are now handled by ../platform-up.sh at step [1/4], right after this script, as soon as CNI != cilium:

1. MetalLB is installed in L2 mode, by ../metallb/metallb-up.sh, on the same range Cilium uses (192.168.56.200 → 192.168.56.230, with the first IP going to main-gateway), on the same host-only interface and from the workers only. It reads the same LB_POOL_START / LB_POOL_END / HOSTONLY_IF keys of lab.env, so the wildcard DNS record keeps pointing at the same address whichever CNI you picked.

2. The Cilium-specific loadBalancerClass is removed. ../envoy-gateway/Envoy-Proxy.yml pins, on line 13:

        loadBalancerClass: io.cilium/l2-announcer

platform-up.sh strips that line before applying the manifest when CNI != cilium.

⚠️ It matters, and it is the #1 false lead here. A loadBalancerClass tells Kubernetes "only this controller may handle this Service": left in place, MetalLB ignores the Service and the IP stays <pending> even with a perfectly valid pool. If you apply Envoy-Proxy.yml by hand rather than through platform-up.sh, delete the line yourself.

Result, with no extra step:

./platform-up.sh <distro>                                 # CNI=calico → Calico + MetalLB
kubectl -n envoy-gateway-system get svc                   # EXTERNAL-IP = 192.168.56.200
kubectl get servicel2status -A -o wide                    # which worker announces it

Installing it on its own — for a repair, or if you had opted out with METALLB=false:

./install.sh <distro> metallb

⚠️ Never on a Cilium cluster. Two announcers on one range means two nodes answering ARP for .200. metallb-up.sh refuses outright — see ../metallb/README.md.

⚠️ Pitfalls#

• NAT NIC elected for the tunnels — the house pitfall, see CLAUDE.md. Every VM has enp0s3 (NAT, 10.0.2.15, the same IP on all VMs, and the one carrying the default route) and enp0s8 (host-only, 192.168.56.x). Calico's default autodetection (firstFound) follows the default route ⇒ every node declares itself as 10.0.2.15, every VXLAN VTEP points at an isolated NAT, and cross-node pod traffic + DNS are broken. Hence nodeAddressAutodetectionV4.cidrs: ["192.168.56.0/24"]. Same problem, same countermeasure as --iface-can-reach (flannel) and devices=<host-only> (Cilium).
• A baseline PodSecurity level blocks the operator, and it fails SILENTLY. The operator needs hostNetwork (that is what lets it start with no CNI at all) and a /var/lib/calico hostPath. kubeadm enforces nothing cluster-wide, so this does not bite out of the box — but it does on any cluster with a hardened default. helm --create-namespace sets no PSS label, so without namespace.yaml the Deployment would be created while the ReplicaSet cannot create a single pod. The trap is the symptom: kubectl -n tigera-operator get pods returns nothing at all — not a failing pod, zero pods — and the script dies on the rollout status timeout. The cause is only visible in the ReplicaSet events: kubectl -n tigera-operator describe rs. Same recipe as ../observability/namespace.yaml.

  💡 If you already hit the failure, fixing the labels is not enough: the ReplicaSet is in exponential backoff and can idle past the 300 s timeout. Kick it with kubectl -n tigera-operator rollout restart deploy/tigera-operator, then re-run the script.

• IPPool CIDR ≠ kubeadm podSubnet = silently broken pod network. The script refuses to continue if it detects the mismatch in _out/cluster.env, but if you change one, change the other.
• Changing CNI is NOT a live switch. Going from Cilium to Calico (or the other way round) on a live cluster leaves contradictory routes, iptables/eBPF rules and /etc/cni/net.d files. The procedure is: ./kubeadm/cluster-reset.sh (or vagrant destroy) → CNI=calico in lab.env → ./kubeadm/cluster-up.sh → ./calico/calico-up.sh. The script's guardrail is there to stop you doing it by mistake, not to make the operation possible.
• No Cilium loadBalancerClass: see the 🌐 section above. It is the #1 cause of an EXTERNAL-IP <pending> that persists after MetalLB is installed — and it only bites when Envoy-Proxy.yml was applied by hand, since platform-up.sh strips the line for you.
• eBPF dataplane: tempting, ruled out. It would require bpfNetworkBootstrap: Enabled, kubeProxyManagement: Enabled and a FelixConfiguration (cgroupV2Path), and it would take over kube-proxy — exactly what KUBE_PROXY_REPLACEMENT=false says is not happening here. Too many moving parts for the lab's "comparison" CNI: if you want eBPF, take Cilium.
• kubectl delete -f installation.yaml does not cleanly uninstall Calico: the operator deletes calico-node and every node drops to NotReady at once, pods included. Use helm uninstall (see 🧹) or, better, destroy the lab.
• MetalLB L2: a single node answers ARP per IP. Like the CiliumL2AnnouncementPolicy, this is not load balancing: one speaker is elected per address, all the VIP traffic enters through that node, then kube-proxy spreads it. A speaker failover takes a few seconds (the time to re-ARP) — expected, not an incident.

🚑 Troubleshooting#

🧹 Uninstall#

The chart ships a pre-delete hook (Job tigera-operator-uninstall) that cleans up the CR before removing the operator:

helm uninstall calico -n tigera-operator

⚠️ This cuts the CNI: every node goes back to NotReady and the pod network disappears. Do not do it "just to see" on a lab that hosts anything. To get back to Cilium, destroy and rebuild the cluster (./kubeadm/cluster-reset.sh → CNI=cilium → ./kubeadm/cluster-up.sh → ./platform-up.sh).

📚 References#

• Calico — Installation API (operator.tigera.io/v1)
• Calico — Configure BGP peering / advertise service IPs
• Calico — Get started with NetworkPolicy
• MetalLB — Layer 2 configuration
• ../metallb/README.md — the L2 announcer installed alongside Calico
• ../cilium/README.md — the lab's default CNI, and its L2 announcement
• ../envoy-gateway/README.md — the consumer of the .200 VIP

🐆calico/ — CNI alternatif : réseau pod + NetworkPolicy, sans IP LoadBalancer

🎯 À quoi ça sert#

Ce que Calico fait ici#

• CNI : réseau pod en VXLAN sur 10.244.0.0/16, natOutgoing pour sortir vers Internet. C'est lui qui fait passer les nodes de NotReady à Ready.
• NetworkPolicy : les networking.k8s.io/v1 standard et les NetworkPolicy/GlobalNetworkPolicy de projectcalico.org/v3 (ordre, tiers, deny explicite, HostEndpoint…). C'est la vraie raison d'être de ce dossier : travailler la micro-segmentation avec l'implémentation de référence.
• API projectcalico.org/v3 : le calico-apiserver est activé, donc les objets Calico se lisent et s'écrivent au kubectl, sans installer calicoctl.

Ce que Calico ne fait pas — et pourquoi c'est bloquant#

⚠️ Calico n'annonce PAS les IP de Service LoadBalancer sur ce lab. Il ne sait le faire qu'en BGP (serviceLoadBalancerIPs d'une BGPConfiguration), ce qui suppose un routeur pair avec qui établir une session. Sur un réseau host-only VirtualBox, ce routeur n'existe pas. Et Calico n'a aucun équivalent de l'annonce L2/ARP de Cilium (CiliumLoadBalancerIPPool + CiliumL2AnnouncementPolicy). C'est pour ça que installation.yaml pose bgp: Disabled : ce n'est pas un oubli, c'est un constat.

Conséquence concrète, pas théorique : avec CNI=calico et rien d'autre,

Autrement dit : toute la couche k8s-playground/ du lab dépend de ce VIP. Aussi ../platform-up.sh ne te laisse plus là : dès que CNI != cilium, il installe MetalLB juste après ce script, sur exactement la même plage et la même interface que Cilium aurait utilisées. Voir 🌐 Rendre les UI joignables.

Cilium ou Calico ?#

💡 Recommandation : garde Cilium comme défaut du lab. Calico est là pour comparer les CNI et pour travailler les NetworkPolicy, pas pour allumer un lab complet sans travail supplémentaire.

📋 Prérequis#

⚡ Installation#

Via le point d'entrée du dépôt :

./install.sh <distro> calico     # <distro> = talos | kubeadm

./calico/calico-up.sh <distro>

Chart projectcalico/tigera-operator v3.32.1 (repo https://docs.tigera.io/calico/charts), épinglé dans le script via CALICO_VERSION. Idempotent (helm upgrade --install + kubectl apply), relançable sans casse.

Variables surchargeables :

🧬 Talos vs kubeadm#

Le manifeste installation.yaml est commun, mais deux de ses réglages n'ont pas le même statut selon la distribution :

Le dataplane eBPF de Calico reste coupé sur les deux : il exige bpfNetworkBootstrap + FelixConfiguration, et il est cassé sur certaines versions de Talos (siderolabs/talos#12221). Pour de l'eBPF dans ce lab : Cilium.

🎓 Pas à pas guidé (formation)#

Les commandes ci-dessous sont exactement ce que fait le script tout-en-un, dans l'ordre. Prépare d'abord l'environnement (une fois par session) :

export KUBECONFIG=../Vagrant-Talos/kubeconfig        # ou ../Vagrant-KubeADM/kubeconfig
export LAB_DOMAIN=talos.lab.example.io               # ou ton domaine (cf. lab.env du lab)

1. Garde-fous (ce que le script vérifie avant de toucher au cluster)#

kubectl get nodes                                        # NotReady : normal, pas de CNI
kubectl get ds -A | grep -Ei 'cilium|flannel'            # doit être VIDE
kubectl -n kube-system get ds kube-proxy                 # DOIT exister (Calico ne le remplace pas)

2. Namespace de l'opérateur (labels PodSecurity)#

kubectl apply -f calico/namespace.yaml
kubectl get ns tigera-operator --show-labels

3. Chart de l'opérateur Tigera — les 4 CR du chart sont coupées#

Le chart ne livre pas de dossier crds/ : c'est l'opérateur qui crée les CRD operator.tigera.io à son démarrage. Toute CR rendue par Helm échouerait donc sur un cluster neuf (« no matches for kind »).

helm repo add projectcalico https://docs.tigera.io/calico/charts && helm repo update projectcalico
helm upgrade --install calico projectcalico/tigera-operator \
  --namespace tigera-operator --create-namespace \
  --version v3.32.1 \
  --set installation.enabled=false --set apiServer.enabled=false \
  --set goldmane.enabled=false --set whisker.enabled=false
kubectl -n tigera-operator rollout status deploy/tigera-operator --timeout=300s

4. Attendre les CRD créées par l'opérateur#

kubectl wait --for=condition=Established crd/installations.operator.tigera.io --timeout=60s
kubectl wait --for=condition=Established crd/apiservers.operator.tigera.io  --timeout=60s

5. Appliquer les CR Installation + APIServer#

# Les CIDR versionnés sont les défauts du lab : adapte-les si ton lab.env diffère
sed -e 's#192\.168\.56\.0/24#192.168.56.0/24#g' \
    -e 's#10\.244\.0\.0/16#10.244.0.0/16#g' \
    calico/installation.yaml | kubectl apply -f -
kubectl apply -f calico/apiserver.yaml

6. Attendre calico-node puis les nodes Ready#

kubectl -n calico-system rollout status daemonset/calico-node --timeout=600s
kubectl wait --for=condition=Ready nodes --all --timeout=300s
kubectl get tigerastatus

7. Vérifier — et comprendre ce qui MANQUE#

kubectl get ippools.projectcalico.org         # via le calico-apiserver, sans calicoctl
kubectl -n envoy-gateway-system get svc       # EXTERNAL-IP <pending> : ATTENDU avec Calico

⚠️ Calico n'annonce aucune IP de Service LoadBalancer (BGP uniquement). Un <pending> à cet endroit précis est donc normal : c'est ../metallb/, installé par platform-up.sh juste après ce script, qui remplit l'adresse — cf. la section 🌐.

🔧 Ce que fait le script#

1. Garde-fous : binaires, /readyz, refus si un autre CNI est déjà là, refus si kube-proxy est absent (KUBE_PROXY_REPLACEMENT=true, le défaut des deux labs), et refus si POD_CIDR diverge du POD_CIDR enregistré dans _out/cluster.env.
2. namespace.yaml — le namespace tigera-operator, créé avant le chart parce qu'il porte les labels PodSecurity privileged. Le --create-namespace de Helm ne pose aucun label. Sur kubeadm rien n'est appliqué au niveau cluster par défaut : c'est donc une assurance plutôt qu'une obligation — mais c'est elle qui garde l'opérateur fonctionnel sur un cluster durci (cf. ⚠️ Pièges).
3. Chart tigera-operator dans ce namespace. L'opérateur tourne en hostNetwork : il démarre sans CNI, c'est ce qui rend l'amorçage possible.
4. Attente des CRD operator.tigera.io : l'opérateur est lancé avec -manage-crds=true, c'est donc lui qui crée installations et apiservers.operator.tigera.io. Appliquer une CR avant ça échoue sur « no matches for kind … ».
5. kubectl apply de installation.yaml, avec les deux CIDR substitués à la volée (même mécanique que LAB_DOMAIN dans ../platform-up.sh), puis de apiserver.yaml qui déploie le calico-apiserver.
6. Attentes bornées : DaemonSet calico-system/calico-node créé, rollout status (600 s, le temps du premier pull sur 8 VM), puis tous les nodes Ready (300 s). Chacune échoue en erreur avec la commande de diagnostic à lancer — aucun || true.
7. Résumé + rappel en jaune des deux étapes manquantes pour les UI du lab.

Les réglages Helm qui comptent#

Le chart rend quatre custom resources (Installation, APIServer, Goldmane, Whisker) et ne livre aucun dossier crds/ — les CRD sont créées par l'opérateur à l'exécution (-manage-crds=true). Les quatre doivent donc être coupées à l'installation, sinon Helm échoue avant même de créer le namespace :

Error: unable to build kubernetes objects from release manifest: resource mapping not found
for name: "default" ... no matches for kind "APIServer" in version "operator.tigera.io/v1"
ensure CRDs are installed first

Les champs de installation.yaml qui comptent#

✅ Vérifier#

kubectl -n tigera-operator get pods                       # tigera-operator Running
kubectl get tigerastatus                                  # calico / apiserver : AVAILABLE=True
kubectl -n calico-system get pods -o wide                 # un calico-node par node + typha
kubectl get nodes                                         # tous Ready
kubectl get installation default -o yaml                  # la CR telle que l'opérateur l'a complétée
kubectl get ippools.projectcalico.org default-ipv4-ippool -o yaml   # cidr + vxlanMode Always

Le contrôle qui compte vraiment : l'adresse retenue par chaque node doit être en 192.168.56.x, jamais 10.0.2.15.

COLS='NODE:.metadata.name'
COLS="$COLS,ADDR:.metadata.annotations.projectcalico\.org/IPv4Address"
COLS="$COLS,VXLAN:.metadata.annotations.projectcalico\.org/IPv4VXLANTunnelAddr"
kubectl get nodes -o "custom-columns=$COLS"

Puis un test de trafic cross-node (c'est là que se voit le piège de la carte NAT) :

kubectl run t1 --image=busybox --restart=Never --command -- sleep 3600
kubectl run t2 --image=busybox --restart=Never --command -- sleep 3600
kubectl get pods -o wide                                  # vérifie qu'ils sont sur 2 nodes différents
kubectl exec t1 -- ping -c3 "$(kubectl get pod t2 -o jsonpath='{.status.podIP}')"
kubectl exec t1 -- nslookup kubernetes.default            # DNS = CoreDNS, souvent sur un autre node
kubectl delete pod t1 t2

🌐 Rendre les UI du lab joignables (MetalLB)#

Calico ne fournit pas d'IP de LoadBalancer — mais tu n'as plus rien à faire pour autant. Les deux étapes autrefois manuelles sont désormais prises en charge par ../platform-up.sh à l'étape [1/4], juste après ce script, dès que CNI != cilium :

1. MetalLB est installé en mode L2, par ../metallb/metallb-up.sh, sur la même plage que celle qu'utilise Cilium (192.168.56.200 → 192.168.56.230, la première IP revenant à main-gateway), sur la même interface host-only et depuis les workers uniquement. Il lit les mêmes clés LB_POOL_START / LB_POOL_END / HOSTONLY_IF de lab.env : l'enregistrement DNS wildcard continue donc de pointer vers la même adresse, quel que soit le CNI retenu.

2. La loadBalancerClass spécifique à Cilium est retirée. ../envoy-gateway/Envoy-Proxy.yml épingle, ligne 13 :

        loadBalancerClass: io.cilium/l2-announcer

platform-up.sh supprime cette ligne avant d'appliquer le manifeste quand CNI != cilium.

⚠️ Ça compte, et c'est la fausse piste n°1 ici. Une loadBalancerClass dit à Kubernetes « seul ce contrôleur a le droit de traiter ce Service » : laissée en place, MetalLB ignore le Service et l'IP reste <pending> même avec un pool parfaitement valide. Si tu appliques Envoy-Proxy.yml à la main plutôt que via platform-up.sh, retire la ligne toi-même.

Résultat, sans étape supplémentaire :

./platform-up.sh <distro>                                 # CNI=calico → Calico + MetalLB
kubectl -n envoy-gateway-system get svc                   # EXTERNAL-IP = 192.168.56.200
kubectl get servicel2status -A -o wide                    # quel worker l'annonce

L'installer seul — pour une réparation, ou si tu t'étais exclu avec METALLB=false :

./install.sh <distro> metallb

⚠️ Jamais sur un cluster Cilium. Deux annonceurs sur une plage, ce sont deux nodes qui répondent à l'ARP pour .200. metallb-up.sh refuse net — cf. ../metallb/LISEZ-MOI.md.

⚠️ Pièges#

• Carte NAT élue pour les tunnels — le piège maison, cf. CLAUDE.md. Chaque VM a enp0s3 (NAT, 10.0.2.15, la même IP sur toutes les VMs, et c'est elle qui porte la route par défaut) et enp0s8 (host-only, 192.168.56.x). L'autodétection par défaut de Calico (firstFound) suit la route par défaut ⇒ tous les nodes se déclarent en 10.0.2.15, tous les VTEP VXLAN pointent vers un NAT isolé, et le trafic pod cross-node
  • le DNS sont cassés. D'où nodeAddressAutodetectionV4.cidrs: ["192.168.56.0/24"]. Même problème, même parade que --iface-can-reach (flannel) et devices=<host-only> (Cilium).
• Un niveau PodSecurity baseline bloque l'opérateur, et ça échoue SILENCIEUSEMENT. L'opérateur a besoin du hostNetwork (c'est ce qui lui permet de démarrer sans aucun CNI) et d'un hostPath /var/lib/calico. kubeadm n'applique rien au niveau cluster : ça ne mord donc pas d'origine — mais ça mord sur tout cluster au défaut durci. Le helm --create-namespace ne pose aucun label PSS : sans namespace.yaml, le Deployment serait bien créé mais le ReplicaSet n'arriverait à créer aucun pod. Le piège, c'est le symptôme : kubectl -n tigera-operator get pods ne renvoie rien du tout — pas un pod en erreur, zéro pod — et le script meurt sur le timeout du rollout status. La cause n'est visible que dans les events du ReplicaSet : kubectl -n tigera-operator describe rs. Même recette que ../observability/namespace.yaml.

  💡 Si tu as déjà rencontré l'échec, corriger les labels ne suffit pas : le ReplicaSet est en backoff exponentiel et peut rester inactif au-delà des 300 s de timeout. Relance-le avec kubectl -n tigera-operator rollout restart deploy/tigera-operator, puis rejoue le script.

• CIDR de l'IPPool ≠ podSubnet de kubeadm = réseau pod silencieusement cassé. Le script refuse de continuer s'il détecte l'écart dans _out/cluster.env, mais si tu changes l'un, change l'autre.
• Changer de CNI n'est PAS une bascule à chaud. Passer de Cilium à Calico (ou l'inverse) sur un cluster vivant laisse des routes, des règles iptables/eBPF et des /etc/cni/net.d contradictoires. La procédure est : ./kubeadm/cluster-reset.sh (Talos : vagrant destroy) → CNI=calico dans lab.env → ./kubeadm/cluster-up.sh (ou ./talos/cluster-up.sh) → ./calico/calico-up.sh. Le garde-fou du script est là pour t'empêcher de le faire par erreur, pas pour rendre l'opération possible.
• Pas de loadBalancerClass Cilium : cf. la section 🌐 ci-dessus. C'est la cause n°1 d'un EXTERNAL-IP <pending> qui persiste après l'installation de MetalLB — et ça ne mord que si Envoy-Proxy.yml a été appliqué à la main, puisque platform-up.sh retire la ligne pour toi.
• Dataplane eBPF : tentant, écarté. Il exigerait bpfNetworkBootstrap: Enabled, kubeProxyManagement: Enabled et une FelixConfiguration (cgroupV2Path), et il prendrait la main sur kube-proxy — exactement ce que KUBE_PROXY_REPLACEMENT=false dit qu'on ne fait pas ici. Trop de pièces mobiles pour le CNI « de comparaison » du lab : si on veut de l'eBPF, on prend Cilium.
• kubectl delete -f installation.yaml ne désinstalle pas proprement Calico : l'opérateur supprime calico-node et tous les nodes retombent NotReady d'un coup, pods compris. Utilise helm uninstall (cf. 🧹) ou, mieux, détruis le lab.
• MetalLB L2 : une seule node répond à l'ARP par IP. Comme la CiliumL2AnnouncementPolicy, ce n'est pas de l'équilibrage : un speaker est élu par adresse, tout le trafic du VIP entre par ce node, puis kube-proxy répartit. Une bascule de speaker prend quelques secondes (le temps du ré-ARP) — normal, pas un incident.

🚑 Dépannage#

🧹 Désinstaller#

Le chart embarque un hook pre-delete (Job tigera-operator-uninstall) qui nettoie la CR avant de retirer l'opérateur :

helm uninstall calico -n tigera-operator

⚠️ Ça coupe le CNI : tous les nodes repassent NotReady et le réseau pod disparaît. Ne le fais pas « pour voir » sur un lab qui héberge quelque chose. Pour revenir à Cilium, détruis et reconstruis le cluster (./kubeadm/cluster-reset.sh → CNI=cilium → ./kubeadm/cluster-up.sh → ./platform-up.sh).

📚 Références#

• Calico — Installation API (operator.tigera.io/v1)
• Calico — Configure BGP peering / advertise service IPs
• Calico — Get started with NetworkPolicy
• MetalLB — Layer 2 configuration
• ../metallb/LISEZ-MOI.md — l'annonceur L2 installé à côté de Calico
• ../cilium/LISEZ-MOI.md — le CNI par défaut du lab, et son annonce L2
• ../envoy-gateway/LISEZ-MOI.md — le consommateur du VIP .200

📢metallb/ — LoadBalancer IPs and L2 announcement, when the CNI is not Cilium

🎯 Purpose#

MetalLB allocates an IP from the host-only range 192.168.56.200-230 to every type: LoadBalancer Service (the controller Deployment) and announces it over ARP from a worker node, so the host (and anything routed to it, Tailscale included) can reach it (the speaker DaemonSet). Nothing else: MetalLB is not a CNI, it needs a working pod network to run.

metallb-up.sh reads the same lab.env keys as Cilium and lays down the same two objects, translated into MetalLB's API, so switching CNI changes the CNI, not the address the *.<LAB_DOMAIN> wildcard points at.

The first IP of the range goes to main-gateway in both cases: 192.168.56.200.

../platform-up.sh decides at step [1/4], right after the CNI:

📋 Prerequisites#

kube-proxy is present by construction: KUBE_PROXY_REPLACEMENT=true implies CNI=cilium, which rules MetalLB out, so MetalLB always finds a kube-proxy in front of it, on both labs.

⚡ Install#

In practice you do not run this by hand: ../platform-up.sh calls it at step [1/4] as soon as CNI != cilium. The direct call is there for a repair, or for the walkthrough below:

./install.sh <distro> metallb      # <distro> = talos | kubeadm
./metallb/metallb-up.sh <distro>   # the same thing, directly

Chart metallb/metallb 0.16.1, overridable per run (METALLB_VERSION=0.16.0 ./metallb/metallb-up.sh). Idempotent (helm upgrade --install + kubectl apply).

ℹ️ metallb is deliberately excluded from ./install.sh <distro> all: on the default CNI=cilium it refuses to install, and an unconditional all would always stop right there. platform installs it when, and only when, the CNI calls for it.

🧬 Talos vs kubeadm#

The announcement itself is identical: same chart, same pool, same interface, same node selection. Two things differ, and only the first one matters.

🎓 Guided walkthrough (step by step)#

The same thing as the script, one command at a time.

export KUBECONFIG="$PWD/kubeconfig"           # from the lab root
LB_POOL_START=$(sed -n 's/^LB_POOL_START=//p' lab.env | head -1 | tr -d ' "')
LB_POOL_END=$(sed -n 's/^LB_POOL_END=//p'     lab.env | head -1 | tr -d ' "')
HOSTONLY_IF=$(sed -n 's/^HOSTONLY_IF=//p' _out/cluster.env | head -1)   # kubeadm
HOSTONLY_IF=${HOSTONLY_IF:-enp0s8}                                      # Talos
echo "$LB_POOL_START-$LB_POOL_END on $HOSTONLY_IF"

# 1. Starting point: nodes Ready (the CNI is there), and nothing else announcing
kubectl get nodes
kubectl get ciliuml2announcementpolicies.cilium.io 2>/dev/null   # MUST be empty / no CRD
kubectl -n envoy-gateway-system get svc                          # EXTERNAL-IP <pending>

# 2. The namespace, BEFORE the chart (see ⚠️ Pitfalls)
kubectl apply -f metallb/namespace.yaml
kubectl get ns metallb-system --show-labels     # pod-security.kubernetes.io/enforce=privileged

# 3. The chart — L2 only, no FRR
helm repo add metallb https://metallb.github.io/metallb && helm repo update metallb
helm upgrade --install metallb metallb/metallb \
  --namespace metallb-system --version 0.16.1 \
  --set frrk8s.enabled=false --set speaker.frr.enabled=false

# 4. Controller AND speakers — the controller allocates, the speakers announce
kubectl -n metallb-system rollout status deploy/metallb-controller --timeout=300s
kubectl -n metallb-system rollout status daemonset/metallb-speaker --timeout=300s

# 5. The pool + the L2 announcement, with your values substituted in
sed -e "s/192\.168\.56\.200/${LB_POOL_START}/g" \
    -e "s/192\.168\.56\.230/${LB_POOL_END}/g" \
    -e "s/enp0s8/${HOSTONLY_IF}/g" \
    metallb/metallb-l2.yml | kubectl apply -f -

# 6. Verify
kubectl -n metallb-system get ipaddresspool,l2advertisement
kubectl -n envoy-gateway-system get svc          # EXTERNAL-IP = 192.168.56.200
kubectl get servicel2status -A -o wide           # which node announces which IP

⚠️ If step 5 fails with connection refused or an x509 error on metallb-webhook-service, you are simply early: the controller injects its own certificate into the ValidatingWebhookConfiguration, which takes a few seconds after the rollout. Retry; that is what the script's loop (150 s) does.

🔧 How it works#

The script adds guard rails to what would otherwise be a helm install: it refuses if Cilium announces or if CNI=cilium (two ARP announcers on one range is the hardest failure of this lab to read), and it refuses if no node is Ready (MetalLB on a CNI-less cluster hangs Pending for five minutes before saying anything).

Two --set flags matter, and both disable the same thing two ways:

Everything else stays at the chart default, speaker.tolerateMaster=true included, which runs a speaker on the control planes too. Harmless: what decides who announces is the nodeSelectors of the L2Advertisement, exactly like the Cilium policy. In metallb-l2.yml, autoAssign: true on the pool means the Gateway asks for no particular address and gets the first free one, and ipAddressPools names the pool explicitly; without it the advertisement would cover every pool.

✅ Verify#

kubectl -n metallb-system get pods                      # 1 controller + 1 speaker per node
kubectl -n metallb-system get ipaddresspool -o wide
kubectl -n metallb-system get l2advertisement -o yaml | grep -A4 interfaces
kubectl -n envoy-gateway-system get svc                 # the Gateway took the FIRST IP of the pool
kubectl get servicel2status -A -o wide                  # who announces what

And above all, the IP must answer, which no kubectl get proves:

GWIP=$(kubectl -n envoy-gateway-system get svc \
  -o jsonpath='{.items[?(@.spec.type=="LoadBalancer")].status.loadBalancer.ingress[0].ip}')
curl -s -o /dev/null -w '%{http_code}\n' "http://$GWIP/"   # 404 = Envoy answers (no route yet)
ip neigh show "$GWIP"                                      # ARP resolved = L2 announcement OK

⚠️ Never test that IP with ping. No interface really carries the address: the elected speaker only answers ARP to attract the traffic, then the node forwards it. ICMP to the VIP therefore gets nothing, while ping on a node (.101) works, a very convincing false negative. The proof of the announcement is the ARP entry resolving to a worker's MAC:

ip neigh flush "$GWIP"; curl -s -o /dev/null --max-time 5 "http://$GWIP/"
ip neigh show "$GWIP"     # lladdr = MAC of the elected worker

🧪 Scenario — speaker failover#

The demo that justifies the component: the announcement survives losing a node.

kubectl get servicel2status -A -o wide          # note the announcing node, e.g. k8s-w2
ip neigh show "$GWIP"                           # note the MAC

kubectl -n metallb-system delete pod -l app.kubernetes.io/component=speaker \
  --field-selector spec.nodeName=k8s-w2

# A few seconds later, another worker has taken over
kubectl get servicel2status -A -o wide
ip neigh flush "$GWIP"; curl -s -o /dev/null -w '%{http_code}\n' "http://$GWIP/"
ip neigh show "$GWIP"                           # a DIFFERENT MAC — same IP

The few seconds of downtime are the re-ARP: expected, not an incident.

🚑 Troubleshooting#

⚠️ Pitfalls#

• Never MetalLB and Cilium's L2 announcement. Two speakers answering ARP for 192.168.56.200 make the host's ARP cache flap between two MACs: the entry point works "one time in two", and nothing in any log says so. The script refuses on two independent signals (the live cilium.io objects, and CNI resolving to cilium): the right move is to pick one CNI.
• interfaces: is a list of plain names, not regexes. Cilium's policy takes ^enp0s8$; MetalLB takes enp0s8. Copying the Cilium syntax across matches no interface and the announcement is dropped in silence: pool valid, IP assigned, ARP mute.
• loadBalancerClass beats any pool. As long as ../envoy-gateway/Envoy-Proxy.yml pins loadBalancerClass: io.cilium/l2-announcer, MetalLB ignores the Service, and a loadBalancerClass means "only this controller may serve it". platform-up.sh removes the line when CNI != cilium; applying that manifest by hand does not.
• The privileged labels are not cosmetic, and their absence lies to you. The controller is not privileged: it starts, allocates, and writes a perfectly normal EXTERNAL-IP into the Service. Only the speaker is refused, so you get an address that looks assigned and answers nothing. Always cross-check get svc with get pods.
• WORKERS=0 leaves nobody to announce. The nodeSelectors keep control planes out on purpose. On a lab with no worker, remove them from metallb-l2.yml.
• One node per IP, not load balancing. Like CiliumL2AnnouncementPolicy, L2 mode elects a single speaker per address: all the VIP traffic enters through that node, then kube-proxy spreads it across the endpoints.
• kube-proxy in IPVS mode needs strictARP: true. Neither lab uses IPVS, so this does not bite here, but it is the first thing to check if you take this component to another cluster: in IPVS mode without strictARP, every node answers ARP for the VIP.
• Changing CNI is not a live switch. Going from Cilium to Calico means a rebuilt cluster (./kubeadm/cluster-reset.sh, or vagrant destroy), not a helm uninstall.