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

./_k8s/platform-up.sh                # from either lab's root      (submodule layout)
./_k8s/install.sh platform           # same thing, via the entry point
./install.sh kubeadm platform        # from this repo's root       (sibling layout)

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

Both labs remain responsible for bootstrapping the cluster (VMs, OS, kubeadm init / talosctl bootstrap). This repository only 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. This repository is mounted there as the _k8s/ submodule.

# 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

💡 Nothing to declare, and that is the whole point. 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. LAB_DIR is no longer needed, and neither is the talos/kubeadm argument. KUBECONFIG is derived the same way (<lab>/kubeconfig); export it yourself only for your own kubectl calls, not for the scripts.

Passing the distribution explicitly still works, and still wins — useful to be sure of what you are running, or in the sibling layout below:

./_k8s/install.sh kubeadm platform

cd ../Vagrant-Talos    && ./talos/cluster-up.sh        # or
cd ../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

Every component is still runnable on its own, bare in the submodule layout:

./_k8s/longhorn/longhorn-up.sh               # from the lab root    (submodule layout)
./observability/observability-up.sh talos    # from this repo root  (sibling layout)

🎓 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.

🧩 Two layouts: submodule or sibling repositories#

Both labs mount this repository as a git submodule on _k8s/, at their root. That is the normal layout, the one every lab command assumes. Keeping the two repositories side by side — what existed before — still works, and stays documented here as the variant.

Installing and updating the submodule, from the lab:

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, and 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 single 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, not to the lab, and a git commit run inside _k8s/ commits here. The route is therefore: PR on this repository → merge → in the lab, git submodule update --remote _k8s, then commit the bumped pointer (git status shows modified: _k8s (new commits)). That commit is the application layer's version bump, and it is what keeps a lab reproducible.

📍 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 in _out/self-signed/, _out/vault-init.json…) live in the lab repository, with the kubeconfig right beside them at its root. 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 it is already exported, it becomes <lab dir>/kubeconfig.

ℹ️ Why the test is Vagrantfile, and why it comes before rule 4. 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 — where the parent is just some working directory. Ordering it before the "root of this repo" rule is deliberate: a leftover _out/ (or a lab.env dropped here for a one-off test) must never shadow the real lab sitting right above. Explicit LAB_DIR/LAB_ENV stays above everything, because an override that can be outvoted is not an override.

⚠️ This is exactly the failure the parent rule removes. Before it, the submodule layout resolved <root>/../Vagrant-KubeADM to Vagrant-KubeADM/Vagrant-KubeADM — a path that does not exist — and fell through to this repository itself, which carries neither lab.env nor _out/. Nothing failed loudly: the scripts ran on the profile defaults — <distro>.lab.example.io instead of your LAB_DOMAIN (hence a wildcard TLS Secret under a name no add-on would look for), CNI=cilium instead of the CNI you picked, guessed POD_CIDR / HOSTONLY_IF / KUBE_PROXY_REPLACEMENT instead of the ones cluster-up.sh detected, and a KUBECONFIG pointing at a file that does not exist. If you ever see that shape of symptom again, it is a resolution problem: read the summary line first.

💡 One signal does fire, 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)". Two readings: either the bootstrap really did not finish, or the lab was not the one resolved. The warning is non-blocking, and on Talos there is no equivalent (that lab has no cluster.env).

Every script prints its resolution before touching anything — one line, worth reading:

    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: the resolution missed the lab — force it with LAB_DIR.

Overriding it all by hand stays possible — useful for a lab kept somewhere else entirely, or to exercise this repository in isolation:

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
LAB_ENV=~/labs/my-lab/lab.env  KUBECONFIG=~/labs/my-lab/kubeconfig  ./install.sh talos platform

⚠️ Do not create a lab.env at this repo's root. Rule 4 accepts one, and it is there for exercising this repo without any lab — but a second lab.env is a second truth, drifting from the lab's the moment either changes. That is precisely 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(), four families of signals ordered by how early they become available:

ℹ️ Source 7 hard-codes the two names, on purpose. LAB_REPO_NAME would have been the natural way to name the neighbour, but the profile sets it — and the profile is what we are trying to choose. So the two candidates are tested directly. If both are present next door, nothing is decided and the scripts ask: guessing there would mean a one-in-two chance of deploying onto the wrong cluster. Pass talos/kubeadm in that case.

ℹ️ Why the probe is last. It needs a KUBECONFIG that is already correct — but KUBECONFIG is derived from the lab directory, which comes from the profile, which is loaded only once the distribution is known. By construction the probe is the least available signal at the exact moment it is needed, so it only ever answers for an ambient kubectl context. Sources 5 and 6 read the lab directly and have no such dependency.

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 that gets created while no pod ever starts, for instance.

ℹ️ 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 those three stay silent and source 7 takes over — which is why ./install.sh platform works bare from here too, as long as a single lab sits next door. Two labs side by side, or a renamed directory: pass the distribution, or export LAB_DIR. An explicit argument short-circuits the whole question and stays the surest way to know what you ran.

🧬 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.

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/ — ./_k8s/install.sh, ./_k8s/longhorn/longhorn-up.sh, and so on. Nothing else moves: 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, and what keeps a stray second lab.env from ever competing with the real one. See Where lab.env and _out/ are found.

🔗 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#

Alongside it, two more neutral markers. 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 — so from the lab root, whichever layout you are in:

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.

ℹ️ The commands below spell out <distro> to stay unambiguous, but it is optional in both layouts: ./_k8s/install.sh longhorn from a lab root, ./install.sh longhorn from here with a single lab next door.

🌐 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 → 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#

• Both labs cloned side by side, and no distribution argument. The neighbour signal then points two ways at once: the scripts stop and ask rather than pick. Say which one — ./install.sh talos … — 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: a Vagrant-KubeADM-v2/ next door is found by neither, and resolution falls back to this repo — silently, with the probe on whatever kubectl context happens to be ambient. LAB_DIR is the fix. In submodule layout the directory name is irrelevant.
• 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.
• A git pull in a lab does not move _k8s/. The submodule stays pinned to its previous commit: 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 announcement). With calico, flannel or none, platform-up.sh installs metallb/ right after the CNI, on the same range — so every CNI now 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

Both labs mount this repository as their _k8s/ submodule; each one documents its own bootstrap, its lab.env and its lifecycle. The relative paths that used to point at ../Vagrant-Talos/ and ../Vagrant-KubeADM/ are gone: they resolved to nothing on the published site, and to two different places depending on the layout.

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

./_k8s/platform-up.sh                # depuis la racine de l'un ou l'autre lab (sous-module)
./_k8s/install.sh platform           # la même chose, par le point d'entrée
./install.sh kubeadm platform        # depuis la racine de ce dépôt    (dépôts voisins)

📖 Documentation navigable : https://ops-nc.github.io/k8s-playground/ — une page unique et autonome, bilingue (EN/FR) avec thème sombre/clair, régénérée depuis ces mêmes README.md / LISEZ-MOI.md à chaque push sur main (make docs pour la construire en local).

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

⚡ Démarrage rapide#

On ne démarre jamais ici : on démarre dans un lab, là où vivent le cluster et son état. Ce dépôt y est monté en sous-module, sur _k8s/.

# 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, 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 → wildcard TLS

# 3. Les addons, à la carte
./_k8s/install.sh longhorn vault argocd
./_k8s/install.sh list               # le catalogue complet
./_k8s/install.sh all                # plateforme + tous les addons, dans le bon ordre

💡 Rien à déclarer, et c'est tout l'intérêt. 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. LAB_DIR n'est plus nécessaire, l'argument talos/kubeadm non plus. KUBECONFIG est dérivé de la même façon (<lab>/kubeconfig) ; ne l'exporte que pour tes propres appels kubectl, pas pour les scripts.

Passer la distribution explicitement reste possible, et reste prioritaire — utile pour être sûr de ce qu'on lance, ou en disposition voisine ci-dessous :

./_k8s/install.sh kubeadm platform

cd ../Vagrant-Talos    && ./talos/cluster-up.sh        # ou
cd ../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 facultatif ici aussi

Chaque composant reste lançable seul, nu en disposition sous-module :

./_k8s/longhorn/longhorn-up.sh               # depuis la racine du lab  (sous-module)
./observability/observability-up.sh talos    # depuis la racine d'ici   (dépôts voisins)

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

🧩 Deux dispositions : sous-module ou dépôts voisins#

Les deux labs montent ce dépôt en sous-module git, sur _k8s/, à leur racine. C'est la disposition normale, celle que supposent toutes les commandes des labs. Garder les deux dépôts côte à côte — ce qui existait avant — fonctionne toujours et reste documenté ici comme la variante.

Installer et mettre à jour le sous-module, depuis le lab :

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        # amène _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 l'on jouerait alors les commandes documentées contre une couche applicative plus ancienne. Enchaîne chaque pull avec git submodule update --init --recursive. Et un _k8s/ vide — ./_k8s/install.sh: No such file or directory — ne veut jamais dire qu'une chose : le sous-module n'a jamais été initialisé.

💡 Modifier cette couche, c'est modifier ici. Vu depuis un lab, _k8s/ est une copie de travail de ce dépôt sur un HEAD détaché : les fichiers qu'on y édite appartiennent à ce dépôt, pas au lab, et un git commit lancé dans _k8s/ committe ici. Le chemin est donc : PR sur ce dépôt → merge → dans le lab, git submodule update --remote _k8s, puis commit du pointeur bumpé (git status affiche modified: _k8s (new commits)). Ce commit est la montée de version de la couche applicative, et c'est lui qui garde le lab reproductible.

📍 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 dans _out/self-signed/, _out/vault-init.json…) vivent dans le dépôt du lab, avec le kubeconfig juste à côté, à sa racine. Il n'y a qu'une source de vérité pour la topologie, celle du lab — c'est pourquoi ce dépôt ne porte ni lab.env, ni modèle de lab.env. _resolve_lab_dir(), dans lib/common.sh, cherche ce dossier dans cet ordre :

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

ℹ️ Pourquoi le test porte sur Vagrantfile, et pourquoi il passe avant la règle 4. 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 en disposition voisine — où le parent n'est qu'un dossier de travail quelconque. L'ordonner avant la règle « racine de ce dépôt » est délibéré : un _out/ résiduel (ou un lab.env déposé ici pour un test ponctuel) ne doit jamais masquer le vrai lab qui se trouve juste au-dessus. LAB_DIR / LAB_ENV restent au-dessus de tout : une surcharge qu'on peut mettre en minorité n'est pas une surcharge.

⚠️ C'est exactement la panne que la règle du parent supprime. Avant elle, la disposition sous-module résolvait <racine>/../Vagrant-KubeADM en Vagrant-KubeADM/Vagrant-KubeADM — un chemin qui n'existe pas — et retombait sur ce dépôt lui-même, qui ne porte ni lab.env ni _out/. Rien ne cassait bruyamment : les scripts tournaient avec les défauts du profil — <distro>.lab.example.io au lieu de ton LAB_DOMAIN (donc un Secret TLS wildcard sous un nom qu'aucun addon n'irait chercher), CNI=cilium au lieu du CNI choisi, POD_CIDR / HOSTONLY_IF / KUBE_PROXY_REPLACEMENT DEVINÉS au lieu de ceux détectés par cluster-up.sh, et un KUBECONFIG pointant sur un fichier inexistant. Si tu revois cette forme de symptôme, c'est un problème de résolution : lis d'abord la ligne de résumé.

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

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

    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 pourtant un lab.env, ou un domaine qui n'est pas celui que tu as posé : la résolution a manqué le lab — force-la avec LAB_DIR.

Tout surcharger à la main reste possible — utile pour un lab rangé ailleurs, ou pour exercer ce dépôt isolément :

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
LAB_ENV=~/labs/mon-lab/lab.env  KUBECONFIG=~/labs/mon-lab/kubeconfig  ./install.sh talos platform

⚠️ Ne crée pas de lab.env à la racine de ce dépôt. La règle 4 en accepte un, et il est là pour exercer ce dépôt sans aucun lab — mais un second lab.env est une seconde vérité, qui diverge de celle du lab dès que l'une des deux bouge. C'est précisément 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(), quatre familles de signaux classées par la précocité avec laquelle elles deviennent disponibles :

ℹ️ La source 7 code les deux noms en dur, volontairement. LAB_REPO_NAME aurait été la façon naturelle de nommer le voisin, mais c'est le profil qui le pose — et le profil est précisément ce qu'on cherche à choisir. Les deux candidats sont donc testés directement. Si les deux sont présents à côté, rien n'est tranché et les scripts redemandent : deviner reviendrait à une chance sur deux de déployer sur le mauvais cluster. Dans ce cas, passe talos/kubeadm.

ℹ️ Pourquoi le sondage est en dernier. Il exige un KUBECONFIG déjà correct — or KUBECONFIG est dérivé du dossier du lab, qui vient du profil, qui n'est chargé qu'une fois la distribution connue. Par construction, le sondage est donc le signal le moins disponible à l'instant précis où on en a besoin : il ne répond jamais que pour un contexte kubectl ambiant. Les sources 5 et 6 lisent le lab directement et n'ont pas cette dépendance.

Sans aucune de ces sources, les scripts refusent de démarrer : appliquer un manifeste pensé pour Talos sur Debian (ou l'inverse) ne produit pas une erreur franche mais une panne silencieuse — un Deployment créé dont aucun pod ne démarre, par exemple.

ℹ️ Les sources 4 à 6 exigent que le lab soit localisé d'abord — et c'est là que la disposition compte. En sous-module, la règle du parent-Vagrantfile s'applique avant tout chargement de profil : les trois fonctionnent donc nues, et c'est ce qui rend ./_k8s/platform-up.sh autosuffisant. En dépôts voisins, aucun lab n'est localisé à cet instant (LAB_REPO_NAME vient du profil) : ces trois-là restent muettes et la source 7 prend le relais — c'est pourquoi ./install.sh platform marche nu depuis ici aussi, tant qu'il n'y a qu'un seul lab à côté. Deux labs côte à côte, ou un dossier renommé : passe la distribution, ou exporte LAB_DIR. Un argument explicite court-circuite toute la question et reste le moyen le plus sûr de savoir ce qu'on a lancé.

🧬 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 à coups de if dispersés, ils lisent des variables.

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 commun : résolution de la distro, lecture 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 la page unique depuis tous les README (make docs)
Makefile                    docs, docs-check, validate — tout ce qui tourne sans cluster

En sous-module, tout cet arbre est sous le _k8s/ du lab — ./_k8s/install.sh, ./_k8s/longhorn/longhorn-up.sh, etc. Rien d'autre ne bouge : les chemins internes à ce dépôt sont les mêmes dans les deux dispositions, et c'est pour ça que chaque pas-à-pas est écrit depuis la racine de ce dépôt.

Il n'y a ni Vagrantfile, ni _out/, ni lab.env ici, et c'est voulu : ce dépôt porte les manifestes, le lab porte le cluster et son état. Cette absence est structurante — c'est elle qui fait de « le parent porte un Vagrantfile » un repère non ambigu, et qui empêche un second lab.env de venir concurrencer le vrai. Cf. Où sont trouvés lab.env et _out/.

🔗 Chaîne de dépendances#

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

cluster bootstrapé  (lab Talos ou lab kubeadm — nodes NotReady, pas encore 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/ — UNIQUEMENT si le CNI n'est pas cilium, sur la MÊME plage
   │                      (sauté avec METALLB=false : plus aucune IP LoadBalancer)
   ├─ 2. envoy-gateway/   contrôleur Envoy + main-gateway (écouteurs :80 et :443)
   ├─ 3. metric-server    API metrics.k8s.io  (kubectl top, HPA)
   └─ 4. wildcard TLS     *.<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 en tirets>-tls) : aucun addon n'a jamais à savoir lequel a été choisi.

🌐 LAB_DOMAIN — le domaine des UI#

À ses côtés, deux autres marqueurs neutres. Le dépôt est public : aucun manifeste ne porte de vraie valeur. Trois marqueurs neutres sont substitués à la volée (fonction 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 — donc depuis la racine du lab, quelle que soit la disposition :

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

⚠️ Un domaine resté à <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 passer par un *-up.sh) ne bénéficient pas de la substitution : wordpress-example/wordpress-mariadb.yaml, vault-secret-operator/k8s/*.yaml, cert-manager/04-gateway-https-example.yaml. Passe-les dans le même sed :

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

📦 Versions épinglées#

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

ℹ️ Les images des démos (WordPress, MariaDB, nginx, alpine, busybox, PostgreSQL, MinIO) sont épinglées volontairement et ne font pas partie de cet audit : les mettre à jour n'a d'intérêt que si la démo casse.

🗺️ Le catalogue#

./install.sh list affiche la même liste, à jour.

ℹ️ Les commandes ci-dessous explicitent <distro> pour rester sans ambiguïté, mais il est facultatif dans les deux dispositions : ./_k8s/install.sh longhorn depuis la racine d'un lab, ./install.sh longhorn depuis ici avec un seul lab à côté.

🌐 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, pas routable telle quelle.

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

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

   Puis l'approuver dans la console Tailscale.

   ⚠️ Rester sur le /32 (ou l'encadrer par une ACL) : un /24 exposerait aussi l'API Kubernetes (:6443) et le SSH de chaque node.

2. Nom + TLS — 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. Le TLS est donc terminé par Envoy, pas par Cloudflare → la Gateway doit porter un certificat publiquement trusté (Let's Encrypt, cf. cert-manager/). Un certificat Cloudflare Origin CA serait refusé par les navigateurs.

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

⚠️ Pièges#

• Les deux labs clonés côte à côte, sans argument de distribution. Le signal « voisin » pointe alors dans les deux sens à la fois : les scripts s'arrêtent et redemandent plutôt que de choisir. Dis lequel — ./install.sh talos … — ou lance depuis le lab visé, en sous-module.
• Le dossier du lab renommé, en dépôts voisins. La recherche du lab (LAB_REPO_NAME) comme la détection par voisinage matchent ces deux noms au pied de la lettre : un Vagrant-KubeADM-v2/ à côté n'est trouvé par aucune des deux, et la résolution retombe sur ce dépôt — silencieusement, avec le sondage du contexte kubectl ambiant. LAB_DIR est le correctif. En sous-module, le nom du dossier n'a aucune importance.
• Lire 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 que prévu.
• Un git pull dans un lab ne déplace pas _k8s/. Le sous-module reste épinglé sur son commit précédent : 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 l'annotation is-default-class: "true". Les deux addons installés ⇒ un PVC sans storageClassName explicite atterrit sur la SC créée en dernier, de façon non déterministe. Nomme toujours ta SC.
• Cette couche a besoin d'un Service LoadBalancer qui obtienne réellement une IP, et Cilium est le seul CNI ici à en fournir une tout seul (annonce L2/ARP). Avec calico, flannel ou none, platform-up.sh installe metallb/ juste après le CNI, sur la même plage — tous les CNI aboutissent donc désormais à 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 en y laissant la loadBalancerClass Cilium.
• Jamais MetalLB et Cilium. Deux annonceurs sur une plage, ce sont deux nodes qui répondent à l'ARP pour .200 : le point d'entrée marche alors « une fois sur deux », sans qu'aucun log ne le dise. metallb-up.sh refuse de s'installer sur un cluster Cilium, et platform ne le choisit jamais là.
• Changer de CNI à chaud n'est pas supporté : remets le cluster à plat depuis le lab (./kubeadm/cluster-reset.sh, ou vagrant destroy), puis rebootstrape.
• Les policies Kyverno du dépôt sont violées par le dépôt lui-même (require-requests-limits exige un limits.cpu que les manifestes maison ne posent pas, volontairement). Le rapport est bruyant par construction — cf. kyverno/.
• Les émetteurs de métriques sont coupés par défaut (serviceMonitor/podMonitor à false dans trivy-operator, CloudNativePG, node-problem-detector) : Prometheus ne scrute rien tant que tu ne les rallumes pas après avoir installé observability.
• Ne descends jamais CP_MEM sous 3072 dans le lab.env du lab : empiler ces addons sur des control planes à 2 Go affame etcd. observability demande 4096.

📚 Références#

• OPS-NC/Vagrant-Talos — le lab Talos (de 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

Les deux labs montent ce dépôt en sous-module _k8s/ ; chacun documente son propre bootstrap, son lab.env et son cycle de vie. Les chemins relatifs qui pointaient vers ../Vagrant-Talos/ et ../Vagrant-KubeADM/ ont disparu : ils ne menaient nulle part sur le site publié, et vers deux endroits différents selon la disposition.

🐝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, handy for showing flows.

📋 Prerequisites#

⚡ Install#

🎓 Two paths, same result: the all-in-one script below, or the "Guided walkthrough" section further down — the same commands, one at a time, for training.

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: the pod CIDR is in the generated machine config
grep -A2 podSubnets ../Vagrant-Talos/_out/controlplane.yaml

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=false \
  --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? (kubeadm with KUBE_PROXY_REPLACEMENT=true)
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, not guesses;
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 there is no kube-proxy DaemonSet in kube-system, and that is the expected state — cilium-dbg status must report KubeProxyReplacement: True.

🌐 Hubble UI (not exposed)#

Hubble is enabled but no HTTPRoute exposes it: that is deliberate (the UI has no authentication). One-off access through a port-forward:

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. KUBE_PROXY_REPLACEMENT=true makes kubeadm/cluster-up.sh run kubeadm init --skip-phases=addon/kube-proxy; this script then reads the same value back from _out/cluster.env. Flipping only one of the two loses every Service in the cluster. Changing your mind means rebuilding: ./kubeadm/cluster-reset.sh then ./kubeadm/cluster-up.sh.
• 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é, pratique pour montrer les flux.

📋 Prérequis#

⚡ Installation#

🎓 Deux chemins, même résultat : le script tout-en-un ci-dessous, ou la section « Pas à pas guidé » plus bas — les mêmes commandes, une par une, pour une formation.

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 : le CIDR pod est dans la config machine générée
grep -A2 podSubnets ../Vagrant-Talos/_out/controlplane.yaml

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=false \
  --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é ? (kubeadm avec KUBE_PROXY_REPLACEMENT=true)
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, pas devinés ;
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 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 (non exposée)#

Hubble est activé mais aucune HTTPRoute ne l'expose : c'est volontaire (l'UI n'a pas d'authentification). Accès ponctuel par port-forward :

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. KUBE_PROXY_REPLACEMENT=true fait lancer à kubeadm/cluster-up.sh un kubeadm init --skip-phases=addon/kube-proxy ; ce script relit ensuite la même valeur dans _out/cluster.env. N'en changer qu'un des deux fait perdre TOUS les Services du cluster. Changer d'avis = reconstruire : ./kubeadm/cluster-reset.sh puis ./kubeadm/cluster-up.sh.
• 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#

🎓 Two paths, same result: the all-in-one script below, or the "Guided walkthrough" section further down — the same commands, one at a time, for training.

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), 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#

🎓 Deux chemins, même résultat : le script tout-en-un ci-dessous, ou la section « Pas à pas guidé » plus bas — les mêmes commandes, une par une, pour une formation.

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), 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#

What MetalLB does here#

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

The setup in one sentence#

metallb/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 DNS record points at.

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

When is it installed?#

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

📋 Prerequisites#

⚡ Install#

🎓 Two paths, same result: the all-in-one script below, or the "Guided walkthrough" section further down — the same commands, one at a time, for training.

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 training:

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

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

Chart metallb/metallb 0.16.1, read from lab.env (METALLB_VERSION) and 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. One thing genuinely differs, and it is admission.

ℹ️ No profile variable was added for this component: nothing here reads lib/profiles/<distro>.sh beyond DEFAULT_HOSTONLY_IF, which already existed. The PodSecurity divergence is carried by a namespace manifest applied in both cases — the repository rule: label the namespace everywhere, even where it unlocks nothing today.

🎓 Guided walkthrough (step by step)#

The same thing as the script, one command at a time. Set your variables first:

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. Check the starting point#

kubectl get nodes                         # all Ready — the CNI is already there
kubectl get ciliuml2announcementpolicies.cilium.io 2>/dev/null   # MUST be empty / no CRD
kubectl -n envoy-gateway-system get svc   # EXTERNAL-IP <pending>, if the Gateway is up

2. The namespace, before the chart#

kubectl apply -f metallb/namespace.yaml
kubectl get ns metallb-system --show-labels     # pod-security.kubernetes.io/enforce=privileged

3. Add the Helm repository#

helm repo add metallb https://metallb.github.io/metallb
helm repo update metallb

4. Install MetalLB — L2 only, no FRR#

helm upgrade --install metallb metallb/metallb \
  --namespace metallb-system \
  --version 0.16.1 \
  --set frrk8s.enabled=false \
  --set speaker.frr.enabled=false

5. Wait for the controller and the speakers#

kubectl -n metallb-system rollout status deploy/metallb-controller --timeout=300s
kubectl -n metallb-system rollout status daemonset/metallb-speaker --timeout=300s

6. Apply the pool + the L2 announcement#

# The versioned values are the lab defaults: substitute yours, exactly as the script does
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 -

⚠️ If this 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 exactly what the script's loop does.

7. 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

🔧 What the script does#

Files#