🏠 🐧Vagrant-Talos

Talos has no SSH and no package manager: the OS is immutable and driven entirely through the talosctl API from the host. Vagrant therefore only creates and starts the VMs; all the cluster configuration goes through talosctl.

The whole path, in three commands:

vagrant up                      # creates the VMs, they boot into maintenance mode
./talos/cluster-up.sh           # config + etcd bootstrap + kubeconfig + health
./_k8s/platform-up.sh           # application layer (assumes CNI=cilium, the default, see §9)

🧰 1. Prerequisites (on the host)#

💡 Keep talosctl aligned with TALOS_VERSION. The binary version is what decides the generated configuration schema; a mismatch with the ISO produces obscure errors.

To pin talosctl to a specific version instead of taking the latest:

curl -Lo /tmp/talosctl https://github.com/siderolabs/talos/releases/download/v1.13.7/talosctl-linux-amd64
sudo install -m 0755 /tmp/talosctl /usr/local/bin/talosctl

ℹ️ The Talos ISO (metal-amd64.iso) is downloaded automatically on the first vagrant up, into iso/. No Vagrant box or plugin to install: the "dummy communicator" (no SSH) and the empty pace/empty box are handled by the Vagrantfile.

⚠️ VirtualBox and KVM cannot share VT-x. If the KVM module is loaded, vagrant up dies on VERR_VMX_IN_VMX_ROOT_MODE — unload it first: TROUBLESHOOTING.md.

🗺️ 2. IP plan (host-only network 192.168.56.0/24)#

The IPs are deterministic: each VM has a fixed MAC and a DHCP reservation on the VirtualBox host-only network, created automatically by the Vagrantfile.

Every VM has 2 NICs: NIC1 = VirtualBox NAT (Internet) and NIC2 = host-only 192.168.56.x (cluster and API network).

ℹ️ Interface naming: since Talos 1.5, NICs get predictable names (enp0s3, enp0s8…), not eth0/eth1. The host-only NIC is therefore enp0s8 (VirtualBox NIC2 = PCI bus 0000:00:08.0). The patches never target by name: the VIP is set through busPath and the node IP through the 192.168.56.0/24 subnet → robust whatever the naming scheme.

⚠️ The subnet is only half configurable. NETWORK drives the Vagrantfile and cluster-up.sh, but 192.168.56.x is hard-coded in talos/patch-all.yaml (validSubnets), talos/patch-cp.yaml (vip.ip, advertisedSubnets) and talos/cni-flannel.yaml (--iface-can-reach). Changing NETWORK without editing those three files produces a silently broken cluster.

⚙️ 3. Pick the topology — lab.env#

The topology lives in lab.env, the single source read by the Vagrantfile and by talos/cluster-up.sh. Start from the versioned template (lab.env is gitignored):

cp lab.env.example lab.env

Variables read by cluster-up.sh but missing from the template (all have a default): VIP ($NETWORK.5), CLUSTER_NAME (talos-lab), INSTALL_DISK (/dev/sda), OUT (_out), FORCE.

💡 Create lab.env anyway. Without it, the Vagrantfile and cluster-up.sh fall back to their internal defaults — both aligned on v1.13.7 and on CNI=cilium, but you lose the Image Factory installer image (iscsi extensions), and therefore Longhorn. Keep the CNI value in lab.env in sync with what you actually want: cluster-up.sh decides what Talos lays down, platform-up.sh decides what Helm installs afterwards, and two disagreeing values give you two competing CNIs — a broken pod network.

⚠️ Do not lower CP_MEM below 3072. 2 GB control planes starve etcd as soon as the _k8s/ addons stack up, and the cluster collapses under load — observability/ requires 4 GB explicitly. That is why the template ships 4096.

💰 What the default topology costs: 3 × 4 GB + 3 × 2 GB = 18 GB of RAM, 12 vCPU and ~6 × 20 GB of disk. A 16 GB host cannot run it — use the minimal lab below.

💡 Minimal lab (2 VMs, ~6 GB). Enough for Talos itself and the base platform (platform-up.sh); the data addons expect the default 3 workers (Longhorn replicates ×3, observability/ wants 4 GB control planes). Edit lab.env:

CONTROL_PLANES=1
WORKERS=1

⚠️ Edit the file, do not just export the variable. CONTROL_PLANES=1 vagrant up only affects vagrant: cluster-up.sh re-reads lab.env and would wait for control planes .20/.30 that were never created. To override on the fly, pass the variable to both commands: CONTROL_PLANES=1 vagrant up && CONTROL_PLANES=1 ./talos/cluster-up.sh.

🌐 LAB_DOMAIN: the repo is public, so its default is neutral (talos.lab.example.io). The _k8s/ manifests carry that domain; the *-up.sh scripts replace it on the fly with LAB_DOMAIN (sed), without ever rewriting the versioned files. Put your domain in lab.env (see _k8s/README.md).

The 1st control plane is always talos-cp1 (192.168.56.10). The VirtualBox/Vagrant VM name is identical to the Talos hostname (see §8).

🚀 4. Start the cluster#

vagrant up                      # the VMs boot from the ISO, in maintenance mode
./talos/cluster-up.sh           # everything else

cluster-up.sh chains: config generation → apply to the nodes (with deterministic hostnames) → etcd bootstrap → kubeconfig → health wait. It prints the exports you need and a final kubectl get nodes.

export TALOSCONFIG="$PWD/_out/talosconfig"
export KUBECONFIG="$PWD/kubeconfig"
kubectl get nodes -o wide

For another topology, edit lab.env or override on the spot:

CONTROL_PLANES=1 WORKERS=2 ./talos/cluster-up.sh     # single
CNI=flannel      ./talos/cluster-up.sh               # CNI laid down by Talos, no LB IPs

⚠️ NEVER re-run cluster-up.sh on an already-installed cluster. Its maintenance mode wait polls the nodes with --insecure; an already-installed node (secure mode) never answers. The wait is bounded (WAIT_MAINTENANCE, 300 s) and then fails with an explicit message — but it still wasted five minutes and applied nothing. To grow a running cluster, see §6.1.

⚠️ NEVER regenerate _out/ (nor FORCE=1) on a running cluster: gen config produces new secrets and new CAs, which breaks the existing cluster. Do it only after a vagrant destroy.

vagrant up

talosctl -n 192.168.56.10 get disks --insecure   # must list /dev/sda

set -a ; . ./lab.env ; set +a        # loads TALOS_VERSION, INSTALLER_IMAGE, CNI…

talosctl gen config talos-lab https://192.168.56.5:6443 \
  --install-disk /dev/sda \
  --install-image "$INSTALLER_IMAGE" \
  --additional-sans 192.168.56.5,192.168.56.10,192.168.56.20,192.168.56.30 \
  --config-patch               @talos/patch-all.yaml \
  --config-patch-control-plane @talos/patch-cp.yaml \
  --config-patch-control-plane "@talos/cni-${CNI:-cilium}.yaml" \
  --output-dir _out

export TALOSCONFIG="$PWD/_out/talosconfig"

# Control plane(s) — single: only .10; HA: .10, .20, .30
talosctl apply-config --insecure -n 192.168.56.10 --file _out/controlplane.yaml

# Workers (.101, .102, … — independent of the number of CPs)
talosctl apply-config --insecure -n 192.168.56.101 --file _out/worker.yaml
talosctl apply-config --insecure -n 192.168.56.102 --file _out/worker.yaml

talosctl config endpoint 192.168.56.10        # HA: add .20 .30
talosctl config node     192.168.56.10

talosctl bootstrap -n 192.168.56.10

talosctl kubeconfig -n 192.168.56.10 ./kubeconfig
export KUBECONFIG="$PWD/kubeconfig"

talosctl health --wait-timeout 10m -n 192.168.56.10 -e 192.168.56.10
talosctl -n 192.168.56.10 get members      # members seen by discovery
kubectl get nodes -o wide

📦 5. What comes next: the application layer#

A bare cluster does nothing useful. Everything else lives in _k8s/: Cilium, Envoy Gateway, cert-manager, Longhorn, Vault, PostgreSQL, Prometheus/Loki, Kyverno, Trivy, MinIO…

./talos/cluster-up.sh              # 1. cluster (CNI=cilium by default: Talos installs nothing)
./_k8s/platform-up.sh              # 2. Cilium → Envoy Gateway → metrics-server → wildcard TLS
./_k8s/argocd/argocd-up.sh         # 3. opt-in addons

After the bootstrap, the nodes stay NotReady until the CNI is installed — that is expected, platform-up.sh handles it. See _k8s/README.md for the full dependency chain and the list of addons.

⚠️ This layer requires CNI=cilium (the default). It relies on a LoadBalancer Service that actually gets an IP, which only Cilium's L2 announcement (ARP) provides here. With flannel, calico or none, the Gateway stays at EXTERNAL-IP <pending> and no UI is reachable. Details in §9.

5.1 DNS + TLS: the two manual prerequisites#

ℹ️ This whole subsection is for SELF_SIGNED=false only. With the default (SELF_SIGNED=true), platform-up.sh signs the wildcard itself with openssl under a local CA: no public DNS record and no Cloudflare token are needed, and the domain never has to exist outside your machine. All you do is make the name resolve locally — an /etc/hosts line pointing your subdomains at 192.168.56.200 — and, optionally, import _out/self-signed/ca.crt to silence the browser warning. See _k8s/self-signed/README.md. Read on only if you own a real domain and want a publicly trusted certificate.

This is the part everyone forgets, and nothing works without it. Two things to do once, outside the cluster.

a) A wildcard DNS record pointing at the Gateway IP.

Every lab UI is served through a single entry point — Envoy's LoadBalancer Service, which takes the first IP of LB_POOL_START (192.168.56.200 by default). One record is therefore enough for all the subdomains:

# the IP actually assigned (use this if you changed LB_POOL_START)
kubectl -n envoy-gateway-system get svc -o wide | grep LoadBalancer

# check resolution
dig +short argo.talos.lab.example.io      # must answer 192.168.56.200

⚠️ The Cloudflare proxy (orange cloud) cannot work here. It would have to reach your origin from the Internet, but 192.168.56.200 is a private, non-routable IP. In orange you would get a 522 error. Stay on DNS-only: Envoy terminates TLS, not Cloudflare — hence the need for a publicly trusted certificate (Let's Encrypt, see point b).

ℹ️ The lab is therefore only reachable from the host, or through access to the host-only network (Tailscale — see _k8s/README.md). A public wildcard pointing at a private IP carries no exploitation risk, but it does publish the existence of the lab and its IP plan: your call.

💡 With no DNS at all, you can test by short-circuiting resolution:

curl -sI --resolve argo.talos.lab.example.io:443:192.168.56.200 \
  https://argo.talos.lab.example.io/

b) A Cloudflare API token for the DNS-01 challenge.

A wildcard cannot be validated over HTTP-01 (Let's Encrypt cannot reach a private IP), so cert-manager uses DNS-01: it proves ownership by writing an _acme-challenge record, which takes a token scoped to Zone/DNS/Edit + Zone/Zone/Read on your zone only — an All zones token would let the lab rewrite the DNS of every domain you own. How to create it, and how the certificate is then issued: _k8s/cert-manager/README.md.

Then in lab.env (gitignored — never in lab.env.example):

SELF_SIGNED=false                      # leave the default (true) and none of this is read
LAB_DOMAIN=talos.lab.example.io        # your domain
LAB_DNS_ZONE=example.io                # the Cloudflare zone (derived if empty)
LAB_ACME_EMAIL=you@example.io          # Let's Encrypt expiry notices
LAB_ACME_ISSUER=staging                # staging (default) | prod — see the warning below
CLOUDFLARE_API_TOKEN=<your-token>

platform-up.sh creates the cloudflare-api-token Secret, substitutes the domain in the manifests and waits for the certificate. Follow it with kubectl -n envoy-gateway-system get certificate.

⚠️ prod costs a quota slot on every rebuild, and staging is the default on purpose. The wildcard lives only in etcd, so vagrant destroy burns it and the next platform-up.sh asks for a brand new one. Let's Encrypt production allows 5 certificates per week for the same *.<LAB_DOMAIN>: the 6th rebuild fails with 429 rateLimited and the lab stays without TLS until the 168 h window slides. Use prod on a stable lab, not while iterating — and back the wildcard up before a destroy:

kubectl -n envoy-gateway-system get secret wildcard-<your-domain-in-dashes>-tls \
  -o yaml > _out/wildcard-tls.backup.yaml     # contains the private key: _out/ is gitignored

♻️ 6. Lifecycle#

vagrant status                 # VM status
vagrant halt                   # power off
vagrant up                     # power back on
vagrant destroy -f             # delete everything (dedicated disks included)

⚠️ After a destroy, also delete the local Talos state before starting over: rm -rf _out kubeconfig.

⚠️ VirtualBox 7.x does not always clean up after a destroy, and the next up then fails on VERR_ALREADY_EXISTS. Purge the leftovers with ./talos/virtualbox-cleanup.sh — details and precautions in TROUBLESHOOTING.md.

6.1 Adding workers (live, without breaking the cluster)#

To grow an already running cluster, start the new VMs and apply the existing worker config to them (same secrets). Two rules:

• Do not regenerate _out/ (nor FORCE=1): new secrets would break the cluster.
• Do not re-run cluster-up.sh: it would wait for maintenance mode on already-installed nodes and hang.

Example — going from 3 to 5 workers (talos-w4=.104, talos-w5=.105):

1. Raise WORKERS in lab.env (here WORKERS=5).
2. Start only the new VMs:

   vagrant up talos-w4 talos-w5
   

3. Apply the existing worker config while pinning the hostname (Nth worker = talos-w<N>):

   export TALOSCONFIG="$PWD/_out/talosconfig"
   WK_IP_START=101 ; WK_IP_STEP=1              # same values as lab.env
   for n in 4 5; do
     ip="192.168.56.$(( WK_IP_START + (n - 1) * WK_IP_STEP ))"
     until talosctl -n "$ip" get disks --insecure >/dev/null 2>&1; do sleep 5; done
     talosctl apply-config --insecure -n "$ip" --file _out/worker.yaml \
       --config-patch "$(printf 'apiVersion: v1alpha1\nkind: HostnameConfig\nauto: "off"\nhostname: talos-w%s\n' "$n")"
   done
   

4. The workers join automatically (their config already points at the VIP). Check: kubectl get nodes -o wide → talos-w4/talos-w5 turn Ready.

💡 Removing a worker:

kubectl drain talos-w5 --ignore-daemonsets --delete-emptydir-data
vagrant destroy -f talos-w5
kubectl delete node talos-w5

then lower WORKERS in lab.env.

ℹ️ Adding control planes follows the same logic (VM + apply-config of controlplane.yaml, hostname talos-cp<N>); they join etcd through discovery, without re-running bootstrap.

🚑 7. Troubleshooting#

Symptoms and fixes have their own page, so this one stays about installing: TROUBLESHOOTING.md — host and VirtualBox (VT-x/KVM conflict, leftovers after a destroy), addressing and DHCP (stale leases, unreachable VIP), Talos nodes (--insecure silence, KUBERNETES: n/a), cluster and pods (the NAT-NIC DNS trap, nodes staying NotReady).

Addon-specific problems live in the ⚠️ pitfalls and 🚑 troubleshooting sections of each _k8s/<addon>/README.md — index in _k8s/README.md.

🔍 8. How it works (under the hood)#

• No SSH → a dummy communicator (in the Vagrantfile) reports "ready" immediately so that vagrant up does not hang.
• No Talos box → we start from the empty pace/empty box and boot the metal-amd64.iso ISO (SATA DVD drive, BIOS, boot disk then DVD).
• Deterministic IPs → fixed MAC per VM + host-only DHCP reservations (VBoxManage dhcpserver ... --fixed-address) created by a before :up trigger, stale leases purged → the node takes its reserved IP on the 1st DHCP.
• Deterministic hostnames → cluster-up.sh applies one HostnameConfig document per node (auto: "off" + fixed hostname:) instead of the auto-generated name (talos-xxxxx). The VirtualBox VMs carry the same name.
• VIP / HA → talos/patch-cp.yaml sets a VIP shared between control planes (election through etcd): the kube-apiserver endpoint stays stable even if a CP goes down.
• Online discovery → talos/patch-all.yaml enables the discovery.talos.dev service and disables the kubernetes registry, deprecated and incompatible with Kubernetes ≥ 1.32.
• Default route through the NAT → deliberate (Internet access). What must be host-only is the node's identity (kubelet nodeIP, etcd, VIP), not the default route.

References: Talos Linux · siderolabs/talos · rgl/talos-vagrant · bjwschaap/vagrant-empty-box

🌐 9. CNI: Cilium, Calico or Flannel#

Two ways to install a CNI, and a single variable#

CNI (in lab.env) expresses an intent, read in two places:

1. talos/cluster-up.sh applies the talos/cni-<CNI>.yaml patch, which fills in cluster.network.cni in the control plane config. Talos installs flannel itself, at bootstrap — without kubectl, by rendering an internal manifest.
2. _k8s/platform-up.sh installs the CNI in every other case, through Helm.

CNI=calico ./talos/cluster-up.sh && ./_k8s/platform-up.sh

Which one to choose?#

In practice: keep cilium. It is the only choice that makes the lab usable end to end. calico is there to compare CNIs and to work on NetworkPolicy; flannel for a bare cluster, if you just want to explore Talos.

The Cilium install (chart pinned to 1.19.6, L2 pool, --set devices=enp0s8) is documented and scripted in _k8s/cilium/README.md — that is the source of truth, platform-up.sh calls it for you.

⚠️ Calico does not announce LoadBalancer Service IPs. It can only do it over BGP, which assumes a peer router — non-existent on a VirtualBox host-only network. With CNI=calico you therefore have to install MetalLB (L2 mode) and adjust _k8s/envoy-gateway/Envoy-Proxy.yml, which pins loadBalancerClass: io.cilium/l2-announcer (platform-up.sh strips that line outside Cilium). Full procedure: _k8s/calico/README.md.

⚠️ Switching CNI on an existing cluster is not supported: vagrant destroy, then rebuild. Two coexisting CNIs fight over the pod network.

⚠️ The key point on the Cilium side is the same as for flannel: pin the host-only interface (enp0s8). Otherwise Cilium picks the default route NIC (the NAT) and the VTEPs are broken.

ℹ️ The kubelet.nodeIP.validSubnets fix (talos/patch-all.yaml) still holds with Cilium: the nodes' INTERNAL-IP, the source of the VTEPs, is already on 192.168.56.0/24.

🛠️ 10. Validating a change#

Everything can be validated without touching a cluster:

make validate       # script syntax + Vagrantfile + Talos config + doc links
make docs           # regenerates docs/index.html from every README (EN + FR)
make help           # lists the targets

make validate-talos generates the config in a temporary directory, then feeds it to talosctl validate --mode metal: no risk for _out/ nor for the cluster — unlike FORCE=1 ./talos/cluster-up.sh, which regenerates the secrets and breaks a running cluster. make validate-docs builds the docs into a throwaway directory and fails if a *.md link or a cross-page anchor no longer resolves. make validate-yaml parses every *.yaml / *.yml tracked by git.

On every pull request, the ci workflow re-runs three of these on a runner — shell syntax, YAML, and the Vagrantfile — by calling the very same make targets, so a check cannot pass in CI and fail on your machine. vagrant validate runs there with --ignore-provider, since a runner has no VirtualBox.

📄 11. License#

This project is licensed under the Apache License 2.0 — see LICENSE.

In short: use it, modify it, redistribute it, including commercially, as long as you keep the copyright notice and state your changes. It comes with no warranty: this is a lab, do not run it in production.

The license covers what this repo actually contains — the Vagrantfile, the talos/ and _k8s/ scripts, the manifests and the documentation. It does not extend to the third-party components those scripts download (Talos Linux, Cilium, Longhorn, Vault, Envoy Gateway, chaoskube…), each of which keeps its own license.

🏠 🐧Vagrant-Talos

Talos n'a ni SSH ni gestionnaire de paquets : l'OS est immuable et entièrement piloté par l'API talosctl depuis l'hôte. Vagrant ne sert donc qu'à créer et démarrer les VMs ; toute la configuration du cluster passe par talosctl.

Le parcours complet, en trois commandes :

vagrant up                      # crée les VMs, elles bootent en mode maintenance
./talos/cluster-up.sh           # config + bootstrap etcd + kubeconfig + santé
./_k8s/platform-up.sh           # couche applicative (suppose CNI=cilium, le défaut, cf. §9)

🧰 1. Prérequis (sur l'hôte)#

💡 Garde talosctl aligné sur TALOS_VERSION. C'est la version du binaire qui décide du schéma de configuration généré ; un écart avec l'ISO produit des erreurs obscures.

Pour épingler talosctl sur une version précise au lieu de prendre la dernière :

curl -Lo /tmp/talosctl https://github.com/siderolabs/talos/releases/download/v1.13.7/talosctl-linux-amd64
sudo install -m 0755 /tmp/talosctl /usr/local/bin/talosctl

ℹ️ L'ISO Talos (metal-amd64.iso) est téléchargée automatiquement au premier vagrant up, dans iso/. Aucune box ni plugin Vagrant à installer : le « dummy communicator » (pas de SSH) et la box vide pace/empty sont gérés par le Vagrantfile.

⚠️ VirtualBox et KVM ne peuvent pas partager VT-x. Si le module KVM est chargé, vagrant up meurt sur VERR_VMX_IN_VMX_ROOT_MODE — le décharger d'abord : DEPANNAGE.md.

🗺️ 2. Plan d'adressage (réseau host-only 192.168.56.0/24)#

Les IP sont déterministes : chaque VM a une MAC fixe et une réservation DHCP sur le réseau host-only de VirtualBox, posée automatiquement par le Vagrantfile.

Chaque VM possède 2 cartes : NIC1 = NAT VirtualBox (Internet) et NIC2 = host-only 192.168.56.x (réseau du cluster et de l'API).

ℹ️ Nommage des interfaces : depuis Talos 1.5, les cartes ont des noms prédictibles (enp0s3, enp0s8…), pas eth0/eth1. La carte host-only s'appelle donc enp0s8 (NIC2 VirtualBox = bus PCI 0000:00:08.0). Les patches ne ciblent jamais par nom : la VIP est posée via busPath et l'IP de node via le sous-réseau 192.168.56.0/24 → robuste quel que soit le nommage.

⚠️ Le sous-réseau n'est configurable qu'à moitié. NETWORK pilote le Vagrantfile et cluster-up.sh, mais 192.168.56.x est codé en dur dans talos/patch-all.yaml (validSubnets), talos/patch-cp.yaml (vip.ip, advertisedSubnets) et talos/cni-flannel.yaml (--iface-can-reach). Changer NETWORK sans éditer ces trois fichiers produit un cluster silencieusement cassé.

⚙️ 3. Choisir la topologie — lab.env#

La topologie vit dans lab.env, source unique lue par le Vagrantfile et talos/cluster-up.sh. Partir du modèle versionné (lab.env est gitignoré) :

cp lab.env.example lab.env

Variables lues par cluster-up.sh mais absentes du modèle (toutes ont un défaut) : VIP ($NETWORK.5), CLUSTER_NAME (talos-lab), INSTALL_DISK (/dev/sda), OUT (_out), FORCE.

💡 Crée quand même lab.env. Sans lui, le Vagrantfile et cluster-up.sh retombent sur leurs défauts internes — alignés tous les deux sur v1.13.7 et sur CNI=cilium, mais tu perds l'image d'installeur Image Factory (extensions iscsi), donc Longhorn. Garde la valeur de CNI dans lab.env cohérente avec ce que tu veux vraiment : cluster-up.sh décide de ce que pose Talos, platform-up.sh de ce qu'installe Helm ensuite, et deux valeurs divergentes donnent deux CNI concurrents — réseau pod cassé.

⚠️ Ne descends pas CP_MEM sous 3072. Des control planes à 2 Go affament etcd dès qu'on empile les addons _k8s/, et le cluster s'effondre sous charge — observability/ exige explicitement 4 Go. C'est pour ça que le modèle livre 4096.

💰 Ce que coûte la topologie par défaut : 3 × 4 Go + 3 × 2 Go = 18 Go de RAM, 12 vCPU et ~6 × 20 Go de disque. Un hôte à 16 Go ne peut pas la faire tourner — utilise le lab minimal ci-dessous.

💡 Lab minimal (2 VMs, ~6 Go). Suffisant pour Talos lui-même et la plateforme de base (platform-up.sh) ; les addons de données supposent les 3 workers par défaut (Longhorn réplique ×3, observability/ veut des CP à 4 Go). Éditer lab.env :

CONTROL_PLANES=1
WORKERS=1

⚠️ Éditer le fichier, pas seulement exporter la variable. CONTROL_PLANES=1 vagrant up n'agit que sur vagrant : cluster-up.sh relit lab.env et attendrait des control planes .20/.30 jamais créés. Pour surcharger à la volée, passer la variable aux deux commandes : CONTROL_PLANES=1 vagrant up && CONTROL_PLANES=1 ./talos/cluster-up.sh.

🌐 LAB_DOMAIN : le dépôt est public, donc son défaut est neutre (talos.lab.example.io). Les manifestes _k8s/ portent ce domaine ; les scripts *-up.sh le remplacent à la volée par LAB_DOMAIN (sed), sans jamais réécrire les fichiers versionnés. Mets ton domaine dans lab.env (cf. _k8s/LISEZ-MOI.md).

Le 1er control plane est toujours talos-cp1 (192.168.56.10). Le nom de VM VirtualBox/Vagrant est identique au hostname Talos (cf. §8).

🚀 4. Démarrer le cluster#

vagrant up                      # les VMs bootent sur l'ISO, en mode maintenance
./talos/cluster-up.sh           # tout le reste

cluster-up.sh enchaîne : génération de la config → application aux nodes (avec hostnames déterministes) → bootstrap etcd → kubeconfig → attente de santé. Il affiche les export à faire et un kubectl get nodes final.

export TALOSCONFIG="$PWD/_out/talosconfig"
export KUBECONFIG="$PWD/kubeconfig"
kubectl get nodes -o wide

Pour une autre topologie, éditer lab.env ou surcharger ponctuellement :

CONTROL_PLANES=1 WORKERS=2 ./talos/cluster-up.sh     # single
CNI=flannel      ./talos/cluster-up.sh               # CNI posé par Talos, pas d'IP LB

⚠️ cluster-up.sh ne se relance pas sur un cluster déjà installé. Son attente du mode maintenance interroge les nodes en --insecure ; un node déjà installé (mode sécurisé) ne répond jamais. L'attente est bornée (WAIT_MAINTENANCE, 300 s) puis échoue avec un message explicite — mais elle a quand même perdu cinq minutes sans rien appliquer. Pour agrandir un cluster en route, voir §6.1.

⚠️ Ne régénère jamais _out/ (ni FORCE=1) sur un cluster en route : gen config produit de nouveaux secrets et de nouvelles CA, ce qui casse le cluster existant. À faire uniquement après un vagrant destroy.

vagrant up

talosctl -n 192.168.56.10 get disks --insecure   # doit lister /dev/sda

set -a ; . ./lab.env ; set +a        # charge TALOS_VERSION, INSTALLER_IMAGE, CNI…

talosctl gen config talos-lab https://192.168.56.5:6443 \
  --install-disk /dev/sda \
  --install-image "$INSTALLER_IMAGE" \
  --additional-sans 192.168.56.5,192.168.56.10,192.168.56.20,192.168.56.30 \
  --config-patch               @talos/patch-all.yaml \
  --config-patch-control-plane @talos/patch-cp.yaml \
  --config-patch-control-plane "@talos/cni-${CNI:-cilium}.yaml" \
  --output-dir _out

export TALOSCONFIG="$PWD/_out/talosconfig"

# Control plane(s) — single : seulement .10 ; HA : .10, .20, .30
talosctl apply-config --insecure -n 192.168.56.10 --file _out/controlplane.yaml

# Workers (.101, .102, … — indépendant du nombre de CP)
talosctl apply-config --insecure -n 192.168.56.101 --file _out/worker.yaml
talosctl apply-config --insecure -n 192.168.56.102 --file _out/worker.yaml

talosctl config endpoint 192.168.56.10        # HA : ajouter .20 .30
talosctl config node     192.168.56.10

talosctl bootstrap -n 192.168.56.10

talosctl kubeconfig -n 192.168.56.10 ./kubeconfig
export KUBECONFIG="$PWD/kubeconfig"

talosctl health --wait-timeout 10m -n 192.168.56.10 -e 192.168.56.10
talosctl -n 192.168.56.10 get members      # membres vus par la discovery
kubectl get nodes -o wide

📦 5. Et après : la couche applicative#

Le cluster nu ne fait rien d'utile. Tout le reste vit dans _k8s/ : Cilium, Envoy Gateway, cert-manager, Longhorn, Vault, PostgreSQL, Prometheus/Loki, Kyverno, Trivy, MinIO…

./talos/cluster-up.sh              # 1. cluster (CNI=cilium par défaut : Talos ne pose rien)
./_k8s/platform-up.sh              # 2. Cilium → Envoy Gateway → metrics-server → wildcard TLS
./_k8s/argocd/argocd-up.sh         # 3. addons à la carte

Après le bootstrap, les nodes restent NotReady tant que le CNI n'est pas installé — c'est normal, platform-up.sh s'en charge. Voir _k8s/LISEZ-MOI.md pour la chaîne de dépendances complète et la liste des addons.

⚠️ Cette couche exige CNI=cilium (le défaut). Elle repose sur un Service LoadBalancer qui obtient réellement une IP, ce que seule l'annonce L2 (ARP) de Cilium fournit ici. Avec flannel, calico ou none, le Gateway reste en EXTERNAL-IP <pending> et aucune UI n'est joignable. Détail au §9.

5.1 DNS + TLS : les deux prérequis manuels#

ℹ️ Toute cette sous-section ne concerne que SELF_SIGNED=false. Avec le défaut (SELF_SIGNED=true), platform-up.sh signe lui-même le wildcard avec openssl sous une AC locale : ni enregistrement DNS public, ni token Cloudflare, et le domaine n'a jamais besoin d'exister hors de ta machine. Il te reste seulement à faire résoudre le nom en local — une ligne /etc/hosts pointant tes sous-domaines vers 192.168.56.200 — et, si tu veux, à importer _out/self-signed/ca.crt pour faire taire l'avertissement du navigateur. Voir _k8s/self-signed/LISEZ-MOI.md. Ne lis la suite que si tu possèdes un vrai domaine et que tu veux un certificat publiquement trusté.

C'est la partie qu'on oublie, et rien ne fonctionne sans elle. Deux choses à faire une seule fois, en dehors du cluster.

a) Un enregistrement DNS wildcard vers l'IP du Gateway.

Toutes les UI du lab sont servies par un seul point d'entrée — le Service LoadBalancer d'Envoy, qui prend la première IP de LB_POOL_START (192.168.56.200 par défaut). Un seul enregistrement suffit donc pour tous les sous-domaines :

# l'IP réellement attribuée (à utiliser si tu as changé LB_POOL_START)
kubectl -n envoy-gateway-system get svc -o wide | grep LoadBalancer

# vérifier la résolution
dig +short argo.talos.lab.example.io      # doit répondre 192.168.56.200

⚠️ Le proxy Cloudflare (nuage orange) ne peut pas fonctionner ici. Il devrait joindre ton origine depuis Internet, or 192.168.56.200 est une IP privée, non routable. En orange tu obtiendrais une erreur 522. Reste en DNS-only : c'est Envoy qui termine le TLS, pas Cloudflare — d'où la nécessité d'un certificat publiquement trusté (Let's Encrypt, cf. point b).

ℹ️ Le lab n'est donc joignable que depuis l'hôte, ou via un accès au réseau host-only (Tailscale — voir _k8s/LISEZ-MOI.md). Un wildcard public qui pointe vers une IP privée est sans risque d'exploitation, mais il publie l'existence du lab et son plan d'adressage : à toi de voir.

💡 Sans DNS du tout, tu peux tester en court-circuitant la résolution :

curl -sI --resolve argo.talos.lab.example.io:443:192.168.56.200 \
  https://argo.talos.lab.example.io/

b) Un token API Cloudflare pour le challenge DNS-01.

Un wildcard ne peut pas être validé par HTTP-01 (Let's Encrypt n'atteint pas une IP privée) : cert-manager passe donc par DNS-01, en prouvant la propriété du domaine via un enregistrement _acme-challenge. Ça demande un token restreint à Zone/DNS/Edit + Zone/Zone/Read sur ta seule zone — un token All zones laisserait le lab réécrire le DNS de tous tes domaines. Comment le créer, et comment le certificat est ensuite émis : _k8s/cert-manager/LISEZ-MOI.md.

Puis dans lab.env (gitignoré — jamais dans lab.env.example) :

SELF_SIGNED=false                      # en laissant le défaut (true), rien de tout ceci n'est lu
LAB_DOMAIN=talos.lab.example.io        # ton domaine
LAB_DNS_ZONE=example.io                # la zone Cloudflare (déduite si vide)
LAB_ACME_EMAIL=toi@example.io          # avis d'expiration Let's Encrypt
LAB_ACME_ISSUER=staging                # staging (défaut) | prod — voir l'avertissement plus bas
CLOUDFLARE_API_TOKEN=<ton-token>

platform-up.sh crée le Secret cloudflare-api-token, substitue le domaine dans les manifestes et attend le certificat. Suivi avec kubectl -n envoy-gateway-system get certificate.

⚠️ prod coûte un slot de quota à chaque rebuild, et staging est le défaut exprès. Le wildcard vit uniquement dans etcd : vagrant destroy le brûle, et le platform-up.sh suivant en redemande un neuf. La production Let's Encrypt plafonne à 5 certificats par semaine pour un même *.<LAB_DOMAIN> : le 6e rebuild échoue en 429 rateLimited et le lab reste sans TLS jusqu'à ce que la fenêtre de 168 h glisse. Utilise prod sur un lab stable, pas pendant que tu itères — et sauvegarde le wildcard avant un destroy :

kubectl -n envoy-gateway-system get secret wildcard-<ton-domaine-en-tirets>-tls \
  -o yaml > _out/wildcard-tls.backup.yaml     # contient la clé privée : _out/ est gitignoré

♻️ 6. Cycle de vie#

vagrant status                 # état des VMs
vagrant halt                   # éteindre
vagrant up                     # rallumer
vagrant destroy -f             # tout supprimer (et les disques dédiés)

⚠️ Après un destroy, supprime aussi l'état Talos local avant de recommencer : rm -rf _out kubeconfig.

⚠️ VirtualBox 7.x ne nettoie pas toujours après un destroy, et le up suivant échoue alors sur VERR_ALREADY_EXISTS. Purger les résidus avec ./talos/virtualbox-cleanup.sh — détails et précautions dans DEPANNAGE.md.

6.1 Ajouter des workers (à chaud, sans casser le cluster)#

Pour agrandir un cluster déjà en route, on démarre les nouvelles VMs et on leur applique la config worker existante (mêmes secrets). Deux règles :

• Ne pas régénérer _out/ (ni FORCE=1) : de nouveaux secrets casseraient le cluster.
• Ne pas relancer cluster-up.sh : il attendrait le mode maintenance sur des nodes déjà installés et bloquerait.

Exemple — passer de 3 à 5 workers (talos-w4=.104, talos-w5=.105) :

1. Augmenter WORKERS dans lab.env (ici WORKERS=5).
2. Démarrer uniquement les nouvelles VMs :

   vagrant up talos-w4 talos-w5
   

3. Appliquer la config worker existante en fixant le hostname (Nᵉ worker = talos-w<N>) :

   export TALOSCONFIG="$PWD/_out/talosconfig"
   WK_IP_START=101 ; WK_IP_STEP=1              # mêmes valeurs que lab.env
   for n in 4 5; do
     ip="192.168.56.$(( WK_IP_START + (n - 1) * WK_IP_STEP ))"
     until talosctl -n "$ip" get disks --insecure >/dev/null 2>&1; do sleep 5; done
     talosctl apply-config --insecure -n "$ip" --file _out/worker.yaml \
       --config-patch "$(printf 'apiVersion: v1alpha1\nkind: HostnameConfig\nauto: "off"\nhostname: talos-w%s\n' "$n")"
   done
   

4. Les workers rejoignent automatiquement (leur config pointe déjà sur la VIP). Vérifier : kubectl get nodes -o wide → talos-w4/talos-w5 passent Ready.

💡 Retirer un worker :

kubectl drain talos-w5 --ignore-daemonsets --delete-emptydir-data
vagrant destroy -f talos-w5
kubectl delete node talos-w5

puis réduire WORKERS dans lab.env.

ℹ️ Ajouter des control planes suit la même logique (VM + apply-config de controlplane.yaml, hostname talos-cp<N>) ; ils rejoignent etcd via la discovery, sans relancer bootstrap.

🚑 7. Dépannage#

Les symptômes et leurs correctifs ont leur propre page, pour que celle-ci reste consacrée à l'installation : DEPANNAGE.md — hôte et VirtualBox (conflit VT-x/KVM, résidus après un destroy), adressage et DHCP (baux périmés, VIP injoignable), nodes Talos (silence en --insecure, KUBERNETES: n/a), cluster et pods (le piège DNS de la carte NAT, nodes qui restent NotReady).

Les problèmes propres à un addon vivent dans les sections ⚠️ pièges et 🚑 dépannage de chaque _k8s/<addon>/LISEZ-MOI.md — index dans _k8s/LISEZ-MOI.md.

🔍 8. Comment ça marche (sous le capot)#

• Pas de SSH → un dummy communicator (dans le Vagrantfile) répond « prêt » immédiatement pour que vagrant up ne reste pas bloqué.
• Pas de box Talos → on part de la box vide pace/empty et on fait booter l'ISO metal-amd64.iso (lecteur DVD SATA, BIOS, boot disque puis DVD).
• IP déterministes → MAC fixe par VM + réservations DHCP host-only (VBoxManage dhcpserver ... --fixed-address) posées par un trigger before :up, baux périmés purgés → le node prend son IP réservée dès le 1er DHCP.
• Hostnames déterministes → cluster-up.sh applique un document HostnameConfig par node (auto: "off" + hostname: fixe) au lieu du nom auto-généré (talos-xxxxx). Les VMs VirtualBox portent le même nom.
• VIP / HA → talos/patch-cp.yaml pose une VIP partagée entre control planes (élection via etcd) : l'endpoint kube-apiserver reste stable même si un CP tombe.
• Discovery online → talos/patch-all.yaml active le service discovery.talos.dev et désactive le registre kubernetes, déprécié et incompatible avec Kubernetes ≥ 1.32.
• Route par défaut via le NAT → volontaire (accès Internet). Ce qui doit être host-only, c'est l'identité du node (kubelet nodeIP, etcd, VIP), pas la route par défaut.

Références : Talos Linux · siderolabs/talos · rgl/talos-vagrant · bjwschaap/vagrant-empty-box

🌐 9. CNI : Cilium, Calico ou Flannel#

Deux façons d'installer un CNI, et une seule variable#

CNI (dans lab.env) exprime une intention, lue à deux endroits :

1. talos/cluster-up.sh applique le patch talos/cni-<CNI>.yaml, qui renseigne cluster.network.cni de la config des control planes. C'est Talos qui installe flannel, lui-même, au bootstrap — sans kubectl, en rendant un manifeste interne.
2. _k8s/platform-up.sh installe le CNI dans tous les autres cas, par Helm.

CNI=calico ./talos/cluster-up.sh && ./_k8s/platform-up.sh

Lequel choisir ?#

En pratique : garde cilium. C'est le seul choix qui rend le lab utilisable de bout en bout. calico est là pour comparer les CNI et travailler les NetworkPolicy ; flannel pour un cluster nu, si tu veux juste explorer Talos.

L'installation de Cilium (chart épinglé 1.19.6, pool L2, --set devices=enp0s8) est documentée et scriptée dans _k8s/cilium/LISEZ-MOI.md — c'est la source de vérité, platform-up.sh l'appelle pour toi.

⚠️ Calico n'annonce pas les IP de Service LoadBalancer. Il ne sait le faire qu'en BGP, ce qui suppose un routeur pair — inexistant sur un réseau host-only VirtualBox. Avec CNI=calico il faut donc installer MetalLB (mode L2) et adapter _k8s/envoy-gateway/Envoy-Proxy.yml, qui épingle loadBalancerClass: io.cilium/l2-announcer (platform-up.sh retire cette ligne hors Cilium). Marche à suivre complète : _k8s/calico/LISEZ-MOI.md.

⚠️ Changer de CNI sur un cluster existant n'est pas supporté : vagrant destroy puis reconstruire. Deux CNI qui coexistent se disputent le réseau des pods.

⚠️ Le point clé côté Cilium est le même que pour flannel : épingler l'interface host-only (enp0s8). Sinon Cilium prend la carte de la route par défaut (le NAT) et les VTEP sont cassés.

ℹ️ Le correctif kubelet.nodeIP.validSubnets (talos/patch-all.yaml) reste valable avec Cilium : l'INTERNAL-IP des nodes, source des VTEP, est déjà sur 192.168.56.0/24.

🛠️ 10. Valider un changement#

Tout se valide sans toucher à un cluster :

make validate       # syntaxe des scripts + Vagrantfile + config Talos + liens de la doc
make docs           # régénère docs/index.html depuis tous les README (EN + FR)
make help           # liste les cibles

make validate-talos génère la config dans un dossier temporaire puis la passe à talosctl validate --mode metal : aucun risque pour _out/ ni pour le cluster — contrairement à FORCE=1 ./talos/cluster-up.sh, qui régénère les secrets et casse un cluster en route. make validate-docs construit la doc dans un dossier jetable et échoue si un lien *.md ou une ancre inter-pages ne résout plus. make validate-yaml parse tous les *.yaml / *.yml suivis par git.

À chaque pull request, le workflow ci rejoue trois de ces contrôles sur un runner — syntaxe shell, YAML et Vagrantfile — en appelant les mêmes cibles make, pour qu'un test ne puisse pas passer en CI et échouer sur ta machine. vagrant validate y tourne avec --ignore-provider, un runner n'ayant pas VirtualBox.

📄 11. Licence#

Ce projet est sous licence Apache 2.0 — cf. LICENSE.

En résumé : utilisation, modification et redistribution libres, y compris commerciales, à condition de conserver la notice de copyright et d'indiquer les modifications apportées. Le tout sans aucune garantie : c'est un lab, ne le passe pas en production.

La licence couvre ce que contient ce dépôt — le Vagrantfile, les scripts talos/ et _k8s/, les manifestes et la documentation. Elle ne s'étend pas aux composants tiers que ces scripts téléchargent (Talos Linux, Cilium, Longhorn, Vault, Envoy Gateway, chaoskube…), qui gardent chacun leur propre licence.

⬆️Upgrade Talos (and Kubernetes)

Reference at test time: Talos v1.13.7, Kubernetes v1.36.2, CNI=cilium, 3 CP + 5 workers. Adapt the IPs to your topology (lab.env); the repo ships 3 CP + 3 workers.

⚠️ talosctl must be ≥ the target version. Check before you start: talosctl version --client.

🎯 1. How Talos upgrades itself#

Talos has no SSH and no package manager: an upgrade replaces the system image on disk, it patches nothing in place.

talosctl -n <ip-node> upgrade --image ghcr.io/siderolabs/installer:<vX.Y.Z>

• A/B scheme: the new image is written to the inactive partition, the node reboots onto it. If the boot fails, Talos rolls back automatically. Manual rollback: talosctl -n <ip> rollback.
• The upgrade preserves etcd and the machine config. The EPHEMERAL partition (/var) is kept except without --preserve on a single-node. In HA you can wipe a node (etcd rebuilds from the quorum), but for a node that stores data (Longhorn → /var/lib/longhorn): always --preserve.

🔢 2. The version model in this lab#

Three version references coexist, and they do not move together:

⚠️ INSTALLER_IMAGE masks TALOS_VERSION. lab.env.example sets an Image Factory image whose tag carries its own version (factory.talos.dev/installer/<schematic>:v1.13.7). Bumping TALOS_VERSION alone then changes the ISO only: the disk would stay on the old version. Both lines must be updated together.

💡 The fallback defaults in the Vagrantfile and in cluster-up.sh are aligned (v1.13.7): on every bump, update both at the same time as lab.env, otherwise a lab brought up without lab.env would start again on the old version.

For an upgrade the ISO is irrelevant: you change the installer image of the already installed nodes (§3), then update lab.env for future rebuilds.

⚡ 3. Procedure (running cluster)#

Pre-flight — never start from an already degraded cluster:

export TALOSCONFIG=_out/talosconfig KUBECONFIG=./kubeconfig
talosctl -n 192.168.56.10 -e 192.168.56.10 health        # healthy cluster
talosctl -n 192.168.56.10 -e 192.168.56.10 etcd status   # 3 healthy members

Order: one node at a time, workers first, then the control planes.

⚠️ NEVER upgrade two CPs in parallel: the etcd quorum is 2/3, losing two of them breaks the cluster. The .5 VIP switches over to another CP on its own during the reboot.

NEW=v1.14.x                                    # target version
IMG=ghcr.io/siderolabs/installer:${NEW}        # ⚠️ see the "extensions" callout below

# a) Workers, one by one
for ip in 101 102 103 104 105; do
  talosctl -n 192.168.56.$ip -e 192.168.56.10 upgrade --image "$IMG" --preserve --wait
  kubectl wait --for=condition=Ready node/talos-w$((ip-100)) --timeout=5m
done

# b) Control planes, one by one, etcd checked BETWEEN each one
for ip in 10 20 30; do
  talosctl -n 192.168.56.$ip -e 192.168.56.20 upgrade --image "$IMG" --preserve --wait
  talosctl -n 192.168.56.10 -e 192.168.56.10 etcd status
done

⚠️ -e/--endpoints must never point at the target node. For a CP, aim at another CP (otherwise you lose access when it reboots); a worker serves no kubeconfig at all. Details in §7.

⚠️ On 2-3 GB VMs, let the disk/etcd load settle between two nodes: I/O starvation breaks the quorum.

☸️ 4. Upgrading Kubernetes#

Talos and Kubernetes upgrade independently.

talosctl -n 192.168.56.10 -e 192.168.56.10 upgrade-k8s --to 1.37.x

This orchestrates the static pods' apiserver / controller-manager / scheduler / kubelet, one component at a time. Check the supported Talos ↔ Kubernetes skew in the Talos release notes first.

🧩 5. Adding extensions = the same mechanism#

Adding iscsi-tools / util-linux-tools (required by Longhorn) is not a kubectl job: it is an upgrade to an Image Factory installer image that bakes them in.

SCHEMATIC_ID=$(curl -sX POST --data-binary @_k8s/longhorn/schematic.yaml \
  https://factory.talos.dev/schematics -H "Content-Type: application/yaml" | jq -r .id)

talosctl -n 192.168.56.101 -e 192.168.56.10 upgrade \
  --image factory.talos.dev/installer/${SCHEMATIC_ID}:v1.13.7 --preserve --wait

talosctl -n 192.168.56.101 get extensions      # iscsi-tools + util-linux-tools present

⚠️ NEVER upgrade a "factory" node to the classic ghcr.io installer: that strips the extensions and breaks Longhorn. The factory image tag must carry the target version, with the same schematic ID.

💡 For a fresh cluster it is simpler to add --config-patch @_k8s/longhorn/patch-longhorn.yaml to the gen config — see ../_k8s/longhorn/README.md.

✅ 6. After the upgrade#

talosctl -n 192.168.56.10 version
kubectl get nodes -o wide

• Bump TALOS_VERSION and INSTALLER_IMAGE in lab.env (and in the lab.env.example template) → future vagrant up / cluster-up.sh runs will start on the right version, ISO and installer.
• Bump the local talosctl binary to stay aligned.

📊 7. Real test: v1.13.5 → v1.13.7#

Run on 3 CP (3 GB / 3 vCPU) + 5 workers (2 GB / 2 vCPU), with Longhorn and Argo CD deployed, rolling one node at a time, with a probe hitting https://192.168.56.5:6443/livez every ~1 s.

talosctl --endpoints <A_CP_OTHER_THAN_THE_TARGET> --nodes 192.168.56.<x> \
  upgrade --image factory.talos.dev/installer/613e1592…:v1.13.7 --preserve --drain=false

Two pitfalls hit along the way#

1. Endpoint = the target node → failure. The drain done by talosctl upgrade fetches the kubeconfig through the endpoint; a worker serves none (Unimplemented: kubeconfig is only available on control plane nodes) → the upgrade errors out before the reboot even starts. Fix: point --endpoints at a control plane — and to upgrade a CP, at a CP other than the target. The talosconfig endpoints (the 3 CPs) are fine for the workers.

2. Drain stuck on Longhorn. The instance-manager PodDisruptionBudget blocks eviction: the drain runs until --drain-timeout (5 min). Lab fix: --drain=false (straight reboot; --preserve keeps /var/lib/longhorn, and Longhorn rebuilds the replicas when the node returns). In production: tune Longhorn's node drain policy.

Measured results#

API downtime: none. 1056 probes over ~17 min covering the 8 reboots (including the 3 CPs) → 100 % answered, 0 DOWN, longest outage = 0 s. The VIP switching between control planes is transparent at one-second granularity. etcd stayed at 3/3, Kubernetes unchanged (v1.36.2).

Extensions preserved: iscsi-tools + util-linux-tools still present after the upgrade, thanks to the factory image tagged :v1.13.7 (same schematic ID as :v1.13.5). Post-upgrade: Longhorn 5 nodes Ready, Argo CD and the Longhorn UI served over trusted HTTPS (200).

📚 References#

• Talos — Upgrading Talos Linux
• Talos — Upgrading Kubernetes
• Image Factory — extensions baked into the installer
• ../_k8s/longhorn/README.md — Longhorn's Talos prerequisites

⬆️Upgrade Talos (et Kubernetes)

Référence au moment du test : Talos v1.13.7, Kubernetes v1.36.2, CNI=cilium, 3 CP + 5 workers. Adapte les IP à ta topologie (lab.env) ; le dépôt livre 3 CP + 3 workers.

⚠️ talosctl doit être ≥ la version cible. Vérifie avant de commencer : talosctl version --client.

🎯 1. Comment Talos s'upgrade#

Talos n'a ni SSH ni gestionnaire de paquets : un upgrade remplace l'image système sur le disque, il ne patche rien en place.

talosctl -n <ip-node> upgrade --image ghcr.io/siderolabs/installer:<vX.Y.Z>

• Schéma A/B : la nouvelle image est écrite sur la partition inactive, le node reboote dessus. Si le démarrage échoue, Talos rollback automatiquement. Rollback manuel : talosctl -n <ip> rollback.
• L'upgrade préserve etcd et la config machine. La partition EPHEMERAL (/var) est conservée sauf sans --preserve sur un single-node. En HA on peut wiper un node (etcd se reconstruit depuis le quorum), mais pour un node qui stocke des données (Longhorn → /var/lib/longhorn) : toujours --preserve.

🔢 2. Le modèle de version dans ce lab#

Trois références de version coexistent, et elles ne bougent pas ensemble :

⚠️ INSTALLER_IMAGE masque TALOS_VERSION. lab.env.example définit une image Image Factory dont le tag porte sa propre version (factory.talos.dev/installer/<schematic>:v1.13.7). Bumper TALOS_VERSION seul ne change alors que l'ISO : le disque resterait sur l'ancienne version. Les deux lignes doivent être mises à jour ensemble.

💡 Les défauts de repli du Vagrantfile et de cluster-up.sh sont alignés (v1.13.7) : à chaque bump, mets les deux à jour en même temps que lab.env, sinon un lab monté sans lab.env repartirait sur l'ancienne version.

Pour un upgrade, l'ISO ne sert pas : on change l'image d'installeur des nodes déjà installés (§3), puis on met lab.env à jour pour les futurs rebuilds.

⚡ 3. Procédure (cluster en route)#

Pré-vol — ne jamais partir d'un cluster déjà dégradé :

export TALOSCONFIG=_out/talosconfig KUBECONFIG=./kubeconfig
talosctl -n 192.168.56.10 -e 192.168.56.10 health        # cluster sain
talosctl -n 192.168.56.10 -e 192.168.56.10 etcd status   # 3 membres sains

Ordre : un node à la fois, workers d'abord, puis control planes.

⚠️ Ne JAMAIS upgrader deux CP en parallèle : le quorum etcd est 2/3, en perdre deux casse le cluster. Le VIP .5 bascule seul vers un autre CP pendant le reboot.

NEW=v1.14.x                                    # version cible
IMG=ghcr.io/siderolabs/installer:${NEW}        # ⚠️ voir l'encart « extensions » ci-dessous

# a) Workers, un par un
for ip in 101 102 103 104 105; do
  talosctl -n 192.168.56.$ip -e 192.168.56.10 upgrade --image "$IMG" --preserve --wait
  kubectl wait --for=condition=Ready node/talos-w$((ip-100)) --timeout=5m
done

# b) Control planes, un par un, etcd vérifié ENTRE chaque
for ip in 10 20 30; do
  talosctl -n 192.168.56.$ip -e 192.168.56.20 upgrade --image "$IMG" --preserve --wait
  talosctl -n 192.168.56.10 -e 192.168.56.10 etcd status
done

⚠️ -e/--endpoints ne doit jamais désigner le node cible. Pour un CP, viser un autre CP (sinon on perd l'accès quand il reboote) ; un worker ne sert pas de kubeconfig du tout. Détail au §7.

⚠️ Sur des VM à 2-3 Go, laisser retomber la charge disque/etcd entre deux nodes : la famine I/O casse le quorum.

☸️ 4. Upgrade de Kubernetes#

Talos et Kubernetes s'upgradent indépendamment.

talosctl -n 192.168.56.10 -e 192.168.56.10 upgrade-k8s --to 1.37.x

Orchestre apiserver / controller-manager / scheduler / kubelet des static pods, un composant à la fois. Vérifier le skew Talos ↔ Kubernetes supporté dans les release notes Talos avant.

🧩 5. Ajouter des extensions = le même mécanisme#

Ajouter iscsi-tools / util-linux-tools (requis par Longhorn) n'est pas un kubectl : c'est un upgrade vers une image d'installeur Image Factory qui les bake.

SCHEMATIC_ID=$(curl -sX POST --data-binary @_k8s/longhorn/schematic.yaml \
  https://factory.talos.dev/schematics -H "Content-Type: application/yaml" | jq -r .id)

talosctl -n 192.168.56.101 -e 192.168.56.10 upgrade \
  --image factory.talos.dev/installer/${SCHEMATIC_ID}:v1.13.7 --preserve --wait

talosctl -n 192.168.56.101 get extensions      # iscsi-tools + util-linux-tools présents

⚠️ Ne JAMAIS upgrader un node « factory » vers l'installeur ghcr.io classic : cela retire les extensions et casse Longhorn. Le tag de l'image factory doit porter la version cible, avec le même schematic ID.

💡 Pour un cluster neuf, il est plus simple d'ajouter --config-patch @_k8s/longhorn/patch-longhorn.yaml au gen config — voir ../_k8s/longhorn/LISEZ-MOI.md.

✅ 6. Après l'upgrade#

talosctl -n 192.168.56.10 version
kubectl get nodes -o wide

• Bumper TALOS_VERSION et INSTALLER_IMAGE dans lab.env (et le modèle lab.env.example) → les futurs vagrant up / cluster-up.sh repartiront sur la bonne version, ISO et installeur.
• Bumper le binaire talosctl local pour rester aligné.

📊 7. Test réel : v1.13.5 → v1.13.7#

Déroulé sur 3 CP (3 Go / 3 vCPU) + 5 workers (2 Go / 2 vCPU), Longhorn et Argo CD déployés, en rolling un node à la fois, avec une sonde interrogeant https://192.168.56.5:6443/livez toutes les ~1 s.

talosctl --endpoints <UN_CP_DIFFERENT_DE_LA_CIBLE> --nodes 192.168.56.<x> \
  upgrade --image factory.talos.dev/installer/613e1592…:v1.13.7 --preserve --drain=false

Deux pièges rencontrés#

1. Endpoint = le node cible → échec. Le drain de talosctl upgrade récupère le kubeconfig via l'endpoint ; un worker n'en sert pas (Unimplemented: kubeconfig is only available on control plane nodes) → l'upgrade sort en erreur avant même le reboot. Parade : --endpoints pointe un control plane — et pour upgrader un CP, un CP autre que la cible. Les endpoints de la talosconfig (les 3 CP) conviennent pour les workers.

2. Drain bloqué par Longhorn. Le PodDisruptionBudget des instance-manager empêche l'éviction : le drain tourne jusqu'au --drain-timeout (5 min). Parade lab : --drain=false (reboot direct ; --preserve garde /var/lib/longhorn, Longhorn reconstruit les réplicas au retour). En production : régler la node drain policy de Longhorn.

Résultats mesurés#

Interruption API : aucune. 1056 sondes sur ~17 min couvrant les 8 reboots (dont les 3 CP) → 100 % de réponses, 0 DOWN, plus longue coupure = 0 s. La bascule du VIP entre control planes est transparente à la granularité d'une seconde. etcd est resté à 3/3, Kubernetes inchangé (v1.36.2).

Extensions préservées : iscsi-tools + util-linux-tools toujours présents après upgrade, grâce à l'image factory en :v1.13.7 (même schematic ID que :v1.13.5). Post-upgrade : Longhorn 5 nodes Ready, Argo CD et UI Longhorn servis en HTTPS trusté (200).

📚 Références#

• Talos — Upgrading Talos Linux
• Talos — Upgrading Kubernetes
• Image Factory — extensions bakées dans l'installeur
• ../_k8s/longhorn/LISEZ-MOI.md — prérequis Talos de Longhorn

🚑Troubleshooting

Each _k8s/<addon>/README.md carries its own ⚠️ pitfalls and 🚑 troubleshooting section for what is specific to it (Longhorn, Vault, Calico…). This page covers the lab itself: the host, VirtualBox, addressing and the Talos nodes.

🖥️ 1. Host and VirtualBox#

VT-x conflict: unload KVM before starting VirtualBox#

VirtualBox and KVM cannot use VT-x at the same time. If the KVM kernel module is loaded, vagrant up fails at boot:

VBoxManage: error: VT-x is being used by another hypervisor (VERR_VMX_IN_VMX_ROOT_MODE).
VBoxManage: error: VirtualBox can't operate in VMX root mode.

Check, then unload KVM (needs a real terminal: sudo asks for a password):

# 1. Is KVM loaded? (Intel: kvm_intel; AMD: kvm_amd)
lsmod | grep kvm

# 2. Unload (fails if a KVM/libvirt VM is still running — stop it first)
sudo modprobe -r kvm_intel kvm      # AMD: sudo modprobe -r kvm_amd kvm

💡 Persistence. KVM is reloaded on every boot. If this host is never used for KVM/libvirt, blacklist it once and for all:

echo -e "blacklist kvm_intel\nblacklist kvm" | sudo tee /etc/modprobe.d/disable-kvm.conf

To revert: delete that file and reboot (or sudo modprobe kvm_intel).

VirtualBox refuses the 192.168.56.0/24 network#

Allow the range in /etc/vbox/networks.conf:

* 192.168.56.0/21

vagrant up fails after a destroy (VirtualBox leftovers)#

VirtualBox 7.x (linked clones) does not always clean up after a destroy. Symptom on the next up:

The name of your virtual machine couldn't be set because VirtualBox
is reporting another VM with that name already exists.
VBoxManage: error: Could not rename the directory '.../temp_clone_...'
to '.../talos-cp1' ... (VERR_ALREADY_EXISTS)

Two layers of leftovers pile up: orphan directories ~/VirtualBox VMs/talos-*/ and dead entries in the media registry (talos-* disks still registered + accumulated inaccessible entries), which would then make the up fail on "medium already registered".

DRY_RUN=1 ./talos/virtualbox-cleanup.sh   # shows what would be deleted
./talos/virtualbox-cleanup.sh             # actually purges

⚠️ Run it AFTER vagrant destroy, never on a running cluster. The script targets the talos- prefix (PREFIX= variable) and the temp_clone_* VMs: if another Vagrant project is in the middle of a up on the same machine, its temporary clone would be deleted.

💡 A destroy that reports success can still leave those directories behind, each holding a small snapshot .vmdk. So run the cleanup after every destroy, not just after a visibly failed one. In dry-run the directories show up as "kept (contains files)": that is normal, the real run deletes the .vmdk first and then finds them empty.

vagrant up fails on storagectl ... --remove SAS#

The pace/empty box exposes its disk on a controller named SAS (replaced with SATA/AHCI). If a future version of the box changes that name, list it with VBoxManage showvminfo <vm> | grep -i "Storage Controller Name" and adjust the Vagrantfile.

⚠️ The Vagrantfile uses the existence of the disk as a provisioning sentinel. If a destroy fails and leaves .vagrant/talos-disks/<vm>.vdi behind, the next up creates a VM with no disk attached and the install dies with an obscure error. Clean up with ./talos/virtualbox-cleanup.sh.

🗺️ 2. Addressing and DHCP#

A node does not get its .x IP#

Talos retries DHCP in a loop: wait ~30 s. Otherwise vagrant reload <node> (the trigger re-arms the host-only DHCP with the reservations). To see a VM's real IP, open its console (vb.gui = false → true in the Vagrantfile): Talos prints its IP on screen.

A node takes an unexpected IP (stale DHCP leases)#

Symptom: talosctl -n <reserved-ip> ... --insecure returns no route to host while another IP answers. Cause: VirtualBox honours an already-acked DHCP lease before applying the MAC→IP reservations. An old lease (typically in the ~.100 range, inherited from vboxnet0's default DHCP server) overrides the reservation.

The before :up trigger creates the MAC→IP reservations and purges those leases before the VMs boot (dhcpd restarted empty), so that every node gets its reserved IP on its 1st DHCP DISCOVER. The after :destroy trigger purges them too.

To fix an already started cluster without destroying everything:

# 1. power off the nodes (maintenance mode => no data lost)
for v in talos-cp1 talos-cp2 talos-cp3; do VBoxManage controlvm "$v" poweroff; done

# 2. purge the host-only network lease file (adjust vboxnet0 if needed)
CFG="${VBOX_USER_HOME:-$HOME/.config/VirtualBox}"
rm -f "$CFG"/HostInterfaceNetworking-vboxnet0-Dhcpd.leases*
VBoxManage dhcpserver restart --network HostInterfaceNetworking-vboxnet0

# 3. power back on: the nodes redo a DHCP DISCOVER and get their reserved IP
vagrant up

Check: talosctl -n 192.168.56.10 version --insecure must answer NODE: 192.168.56.10.

The VIP 192.168.56.5 is unreachable#

The VIP only appears after etcd's bootstrap. Check that the host-only NIC really is 0000:00:08.0: talosctl -n 192.168.56.10 get links, then get addresses. If the interface differs, adjust busPath in talos/patch-cp.yaml.

🐧 3. Talos nodes#

talosctl ... --insecure does not answer#

The node is not in maintenance mode yet, or has no host-only IP. Check talosctl -n <ip> get disks --insecure and §2.

⚠️ An already installed node (secure mode) never answers --insecure: that is expected, not a fault. This is exactly why cluster-up.sh must not be re-run on a live cluster — to grow one, see §6.1 of the README.

The Talos console shows KUBERNETES: n/a#

Normal before apply-config. The dashboard derives that version from the kubelet image tag in the KubeletSpec resource, which only exists once the machine config has been applied. In maintenance mode no kubelet is configured → n/a. Nothing to fix: look at the console after applying the config. Check outside the console: talosctl -n <ip> get kubeletspec or kubectl get nodes.

The install disk is not /dev/sda#

Check with talosctl -n <ip> get disks --insecure and adjust INSTALL_DISK.

☸️ 4. Cluster and pods#

Pods can ping the Internet but have no DNS#

Symptom: ping 1.1.1.1 works from a pod, but nslookup/apk update fail (DNS: transient error).

Cause: flannel picks the public IP of its VXLAN tunnel on the default route interface = the NAT NIC (10.0.2.15, identical on every VM). All the VTEPs then point at an isolated NAT → cross-node pod traffic is broken. DNS fails because CoreDNS often runs on a different node than the client pod; Internet egress, on the other hand, leaves through the local NAT and works.

kubectl get nodes -o custom-columns='NODE:.metadata.name,FLANNEL-IP:.metadata.annotations.flannel\.alpha\.coreos\.com/public-ip'
# KO if FLANNEL-IP = 10.0.2.15 everywhere; OK if = 192.168.56.10/.20/.30

The fix already lives in talos/cni-flannel.yaml (--iface-can-reach=192.168.56.1). On a rebuild it is picked up at bootstrap time. On an already started cluster, Talos does not re-push the manifest update on its own → patch the DaemonSet:

kubectl -n kube-system patch ds kube-flannel --type=json \
  -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--iface-can-reach=192.168.56.1"}]'
kubectl -n kube-system rollout status ds/kube-flannel

ℹ️ Same root cause, same countermeasure for the other CNIs: Cilium pins devices=enp0s8, and Calico pins nodeAddressAutodetectionV4.cidrs. The NAT NIC being identical on every VM is the recurring trap of this lab — see README.md.

The nodes stay NotReady after the bootstrap#

Expected with CNI=cilium, calico or none: Talos installs no CNI, and a node without a pod network never reports Ready. ./_k8s/platform-up.sh installs it and unblocks them. Only flannel is laid down by Talos itself, at bootstrap time.

If they are still NotReady after the CNI install, look at the CNI pods first (kubectl -n kube-system get pods for Cilium, kubectl -n calico-system get pods for Calico), then the addon's own README.

🚑Dépannage

Chaque _k8s/<addon>/LISEZ-MOI.md porte ses propres sections ⚠️ pièges et 🚑 dépannage pour ce qui lui est spécifique (Longhorn, Vault, Calico…). Cette page couvre le lab lui-même : l'hôte, VirtualBox, l'adressage et les nodes Talos.

🖥️ 1. Hôte et VirtualBox#

Conflit VT-x : décharger KVM avant de lancer VirtualBox#

VirtualBox et KVM ne peuvent pas utiliser VT-x en même temps. Si le module noyau KVM est chargé, vagrant up échoue au démarrage :

VBoxManage: error: VT-x is being used by another hypervisor (VERR_VMX_IN_VMX_ROOT_MODE).
VBoxManage: error: VirtualBox can't operate in VMX root mode.

Vérifier, puis décharger KVM (demande un vrai terminal : sudo réclame un mot de passe) :

# 1. KVM est-il chargé ? (Intel : kvm_intel ; AMD : kvm_amd)
lsmod | grep kvm

# 2. Décharger (échoue si une VM KVM/libvirt tourne encore — l'arrêter d'abord)
sudo modprobe -r kvm_intel kvm      # AMD : sudo modprobe -r kvm_amd kvm

💡 Persistance. KVM est rechargé à chaque démarrage. Si cet hôte ne sert jamais à KVM/libvirt, blackliste-le une fois pour toutes :

echo -e "blacklist kvm_intel\nblacklist kvm" | sudo tee /etc/modprobe.d/disable-kvm.conf

Pour revenir en arrière : supprimer ce fichier et redémarrer (ou sudo modprobe kvm_intel).

VirtualBox refuse le réseau 192.168.56.0/24#

Autoriser la plage dans /etc/vbox/networks.conf :

* 192.168.56.0/21

vagrant up échoue après un destroy (résidus VirtualBox)#

VirtualBox 7.x (clones liés) ne nettoie pas toujours après un destroy. Symptôme au up suivant :

The name of your virtual machine couldn't be set because VirtualBox
is reporting another VM with that name already exists.
VBoxManage: error: Could not rename the directory '.../temp_clone_...'
to '.../talos-cp1' ... (VERR_ALREADY_EXISTS)

Deux couches de résidus s'accumulent : les dossiers orphelins ~/VirtualBox VMs/talos-*/ et des entrées mortes dans le registre de médias (disques talos-* encore enregistrés + entrées inaccessible accumulées), qui feraient ensuite échouer le up sur « medium already registered ».

DRY_RUN=1 ./talos/virtualbox-cleanup.sh   # montre ce qui serait supprimé
./talos/virtualbox-cleanup.sh             # purge réellement

⚠️ À lancer APRÈS vagrant destroy, jamais sur un cluster en route. Le script cible le préfixe talos- (variable PREFIX=) et les VMs temp_clone_* : si un autre projet Vagrant est en cours de up sur la même machine, son clone temporaire serait supprimé.

💡 Un destroy qui rapporte un succès peut tout de même laisser ces dossiers derrière lui, chacun contenant un petit snapshot .vmdk. Lance donc la purge après chaque destroy, pas seulement après un échec visible. En dry-run les dossiers apparaissent « CONSERVÉ (contient des fichiers) » : c'est normal, le vrai passage supprime d'abord le .vmdk puis les trouve vides.

vagrant up échoue sur storagectl ... --remove SAS#

La box pace/empty expose son disque sur un contrôleur nommé SAS (remplacé par SATA/AHCI). Si une future version de la box change ce nom, le lister avec VBoxManage showvminfo <vm> | grep -i "Storage Controller Name" et ajuster le Vagrantfile.

⚠️ Le Vagrantfile utilise l'existence du disque comme sentinelle de provisioning. Si un destroy échoue et laisse .vagrant/talos-disks/<vm>.vdi derrière lui, le up suivant crée une VM sans disque attaché et l'installation meurt sur une erreur obscure. Nettoyer avec ./talos/virtualbox-cleanup.sh.

🗺️ 2. Adressage et DHCP#

Un node n'obtient pas son IP .x#

Talos réessaie le DHCP en boucle : attendre ~30 s. Sinon vagrant reload <node> (le trigger réarme le DHCP host-only avec les réservations). Pour voir l'IP réelle d'une VM, ouvrir sa console (vb.gui = false → true dans le Vagrantfile) : Talos affiche son IP à l'écran.

Un node prend une IP inattendue (baux DHCP périmés)#

Symptôme : talosctl -n <ip-réservée> ... --insecure renvoie no route to host alors qu'une autre IP répond. Cause : VirtualBox honore un bail DHCP déjà acked avant d'appliquer les réservations MAC→IP. Un vieux bail (typiquement dans la plage ~.100, héritée du serveur DHCP par défaut de vboxnet0) prend le pas sur la réservation.

Le trigger before :up crée les réservations MAC→IP et purge ces baux avant le démarrage des VMs (dhcpd redémarré à vide), pour que chaque node obtienne son IP réservée dès son 1er DHCP DISCOVER. Le trigger after :destroy les purge aussi.

Pour réparer un cluster déjà démarré sans tout détruire :

# 1. éteindre les nodes (mode maintenance => aucune donnée perdue)
for v in talos-cp1 talos-cp2 talos-cp3; do VBoxManage controlvm "$v" poweroff; done

# 2. purger le fichier de baux du réseau host-only (adapter vboxnet0 si besoin)
CFG="${VBOX_USER_HOME:-$HOME/.config/VirtualBox}"
rm -f "$CFG"/HostInterfaceNetworking-vboxnet0-Dhcpd.leases*
VBoxManage dhcpserver restart --network HostInterfaceNetworking-vboxnet0

# 3. rallumer : les nodes refont un DHCP DISCOVER et obtiennent leur IP réservée
vagrant up

Vérification : talosctl -n 192.168.56.10 version --insecure doit répondre NODE: 192.168.56.10.

La VIP 192.168.56.5 est injoignable#

La VIP n'apparaît qu'après le bootstrap d'etcd. Vérifier que la carte host-only est bien 0000:00:08.0 : talosctl -n 192.168.56.10 get links, puis get addresses. Si l'interface diffère, ajuster busPath dans talos/patch-cp.yaml.

🐧 3. Nodes Talos#

talosctl ... --insecure ne répond pas#

Le node n'est pas encore en mode maintenance, ou n'a pas d'IP host-only. Vérifier talosctl -n <ip> get disks --insecure et le §2.

⚠️ Un node déjà installé (mode sécurisé) ne répond jamais en --insecure : c'est attendu, pas une panne. C'est exactement pour ça qu'il ne faut pas relancer cluster-up.sh sur un cluster en route — pour l'agrandir, voir §6.1 du LISEZ-MOI.

La console Talos affiche KUBERNETES: n/a#

Normal avant l'apply-config. Le dashboard déduit cette version du tag de l'image kubelet dans la ressource KubeletSpec, qui n'existe qu'une fois la configuration machine appliquée. En mode maintenance aucun kubelet n'est configuré → n/a. Rien à corriger : regarder la console après l'application de la config. Vérifier hors console : talosctl -n <ip> get kubeletspec ou kubectl get nodes.

Le disque d'installation n'est pas /dev/sda#

Vérifier avec talosctl -n <ip> get disks --insecure et ajuster INSTALL_DISK.

☸️ 4. Cluster et pods#

Les pods pingent Internet mais n'ont pas de DNS#

Symptôme : ping 1.1.1.1 fonctionne depuis un pod, mais nslookup/apk update échouent (DNS: transient error).

Cause : flannel choisit l'IP publique de son tunnel VXLAN sur l'interface de la route par défaut = la carte NAT (10.0.2.15, identique sur toutes les VMs). Tous les VTEP pointent alors vers un NAT isolé → le trafic pod cross-node est cassé. Le DNS échoue parce que CoreDNS tourne souvent sur un autre node que le pod client ; la sortie Internet, elle, part par le NAT local et fonctionne.

kubectl get nodes -o custom-columns='NODE:.metadata.name,FLANNEL-IP:.metadata.annotations.flannel\.alpha\.coreos\.com/public-ip'
# KO si FLANNEL-IP = 10.0.2.15 partout ; OK si = 192.168.56.10/.20/.30

Le correctif vit déjà dans talos/cni-flannel.yaml (--iface-can-reach=192.168.56.1). Sur un rebuild il est pris en compte au bootstrap. Sur un cluster déjà démarré, Talos ne repousse pas la mise à jour du manifeste de lui-même → patcher le DaemonSet :

kubectl -n kube-system patch ds kube-flannel --type=json \
  -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--iface-can-reach=192.168.56.1"}]'
kubectl -n kube-system rollout status ds/kube-flannel

ℹ️ Même cause racine, même parade pour les autres CNI : Cilium épingle devices=enp0s8, et Calico épingle nodeAddressAutodetectionV4.cidrs. La carte NAT identique sur toutes les VMs est LE piège récurrent de ce lab — cf. LISEZ-MOI.md.

Les nodes restent NotReady après le bootstrap#

Attendu avec CNI=cilium, calico ou none : Talos n'installe aucun CNI, et un node sans réseau pod ne passe jamais Ready. ./_k8s/platform-up.sh l'installe et les débloque. Seul flannel est posé par Talos lui-même, au bootstrap.

S'ils sont toujours NotReady après l'installation du CNI, regarder d'abord les pods du CNI (kubectl -n kube-system get pods pour Cilium, kubectl -n calico-system get pods pour Calico), puis le README de l'addon.

☸️_k8s/ — the lab's application layer

Read this directory in two passes: a base platform (4 components, a single script), then independent addons you add opt-in, each in its own directory with its own *-up.sh.

⚡ Quick start#

# 1. Bootstrap with CNI=cilium (the repo default): Talos installs no CNI, this layer does
CNI=cilium ./talos/cluster-up.sh

# 2. The base platform: Cilium → Envoy Gateway → metrics-server → wildcard TLS
./_k8s/platform-up.sh

# 3. The addons, opt-in
./_k8s/longhorn/longhorn-up.sh      # block storage (StorageClass longhorn)
./_k8s/vault-cluster/vault-up.sh    # Vault HA — needs longhorn-up.sh first
./_k8s/argocd/argocd-up.sh
./_k8s/chaos-kube/chaoskube-up.sh    # optional: chaos, deletes 1 pod/hour

⚠️ CNI=cilium is the only "everything on" choice. This layer needs a LoadBalancer Service that really gets an IP: that is exactly what Cilium's L2 announcement (ARP) does. With flannel, calico or none, the Gateway stays at EXTERNAL-IP <pending> and no UI is reachable.

🌐 Choosing the CNI#

CNI (in lab.env) is read in two places: talos/cluster-up.sh applies the talos/cni-<CNI>.yaml patch at bootstrap time, then platform-up.sh installs the CNI when Talos did not.

⚠️ Switching CNI on an existing cluster is not supported: vagrant destroy, then rebuild. Two CNIs at once fight over the pod network.

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

cluster Ready  (Talos has bootstrapped, CNI per lab.env)
   │
   ├─ 1. CNI              cilium/ (default, + L2 pool → LoadBalancer IP .200)
   │                      or calico/ (CNI only) or flannel (already there) or nothing
   ├─ 2. envoy-gateway/   Envoy controller + main-gateway (listeners :80 and :443)
   ├─ 3. metric-server    metrics.k8s.io API  (kubectl top, HPA)
   └─ 4. wildcard TLS     *.talos.lab.example.io — one of two modes, per SELF_SIGNED
              │             true  (default) → self-signed/   openssl, local CA, no cert-manager
              │             false           → cert-manager/  Let's Encrypt DNS-01 Cloudflare
              │
              └─ addons: storage → databases → secrets → observability → security

That is exactly the order of platform-up.sh ([1/4] → [4/4]): metrics-server before the certificate. Both TLS modes fill the same Secret (wildcard-<LAB_DOMAIN with dashes>-tls), so no addon ever has to know which one you picked — they all just attach an HTTPRoute to the https listener.

📋 Cross-cutting prerequisites#

💡 The StorageClasses are not interchangeable: longhorn-r1 (1 replica) is the base for apps that already replicate at the application level (PostgreSQL, Vault), longhorn (3 replicas) for everything else, local-path for anything ephemeral. See longhorn/ and local-path-storage/.

🌐 LAB_DOMAIN — the UI domain#

The repo is public: every versioned manifest carries a neutral domain, talos.lab.example.io. Put yours in lab.env (gitignored):

echo 'LAB_DOMAIN=talos.lab.my-domain.tld' >> lab.env

The *-up.sh scripts (platform-up.sh, argocd-up.sh, kyverno-up.sh, observability-up.sh, minio-up.sh, minio-cluster-up.sh, trivy-operator-up.sh, vault/00-secrets-engines.sh) read LAB_DOMAIN — environment variable first, then lab.env, then the neutral default — and substitute the domain on the fly:

sed "s/talos\.lab\.example\.io/${LAB_DOMAIN}/g" <manifest> | kubectl apply -f -

No versioned file is rewritten: git status stays clean.

⚠️ Manifests applied by hand (without a *-up.sh) get no such substitution: wordpress-example/wordpress-mariadb.yaml, longhorn/httproute.yaml, vault-cluster/httproute.yaml, vault-secret-operator/k8s/30-pki-tls.yaml. Either edit them, or pipe them through the same sed:

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

ℹ️ SELF_SIGNED decides how that domain gets its certificate (see lab.env.example). true — the default — signs a wildcard with openssl under a local CA (self-signed/): no real domain, no token, no quota, and the domain never has to resolve publicly. false switches to cert-manager/ + Let's Encrypt, and only then do the three ACME variables matter: LAB_DNS_ZONE (zone of the DNS-01 solver; default = the last 2 labels of LAB_DOMAIN), LAB_ACME_EMAIL (Let's Encrypt account; default admin@<zone>) and LAB_ACME_ISSUER — staging (default, untrusted cert) or prod (trusted, but capped at 5 certificates per week for the same wildcard, and every vagrant destroy burns one).

🧱 Base platform — platform-up.sh#

Installs only the 4 components above, idempotent (helm upgrade --install), re-runnable without breaking anything.

ℹ️ With the default SELF_SIGNED=true, step [4/4] runs self-signed/selfsigned-up.sh instead and cert-manager is never installed — no chart, no CRDs, no Cloudflare Secret.

ℹ️ metrics-server tuned for Talos: --kubelet-insecure-tls + secure port 10250, so it does not require a kubelet CSR approver. Check: kubectl top nodes.

🗂️ The addons#

Suggested order: storage first (everything else depends on it), then the databases, then the rest in any order.

💾 Storage#

🐘 Databases#

🔐 Secrets#

📈 Observability#

🛡️ Security#

🌐 Networking & TLS#

🧪 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 Talos (:50000) and Kubernetes (:6443) APIs.

2. Name + TLS — public Cloudflare wildcard *.talos.lab.example.io → 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.

⚠️ Pitfalls#

• Two default StorageClasses. longhorn/values.yaml sets persistence.defaultClass: true and local-path-storage.yaml sets the is-default-class: "true" annotation. With both addons installed ⇒ a PVC without an explicit storageClassName lands on the most recently created SC, non-deterministically. Always name your SC.
• The repo's own Kyverno policies are violated by the repo. require-requests-limits demands a limits.cpu that the in-house manifests never set (deliberate choice: no CPU throttling), and require-labels expects app.kubernetes.io/name where they use app:. The report is therefore 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. Stacking these addons on 2 GB control planes starves etcd. lab.env.example ships 4096, which is what observability/ requires.
• A git add -A can publish local addon secrets. _k8s/databasement/ is gitignored for that very reason — check git status before committing.

📚 References#

• ../README.md — the Talos/Vagrant lab, from vagrant up to a ready cluster
• ../talos/UPGRADE.md — upgrading Talos and Kubernetes
• Gateway API · Cilium · Envoy Gateway · cert-manager

☸️_k8s/ — la couche applicative du lab

Le dossier se lit en deux temps : une plateforme de base (4 briques, un seul script), puis des addons indépendants que tu ajoutes à la carte, chacun dans son dossier avec son *-up.sh.

⚡ Démarrage rapide#

# 1. Bootstrap en CNI=cilium (défaut du dépôt) : Talos ne pose aucun CNI, cette couche si
CNI=cilium ./talos/cluster-up.sh

# 2. La plateforme de base : Cilium → Envoy Gateway → metrics-server → wildcard TLS
./_k8s/platform-up.sh

# 3. Les addons, à la carte
./_k8s/longhorn/longhorn-up.sh      # stockage bloc (StorageClass longhorn)
./_k8s/vault-cluster/vault-up.sh    # Vault HA — exige longhorn-up.sh d'abord
./_k8s/argocd/argocd-up.sh
./_k8s/chaos-kube/chaoskube-up.sh    # optionnel : chaos, supprime 1 pod/heure

⚠️ CNI=cilium est le seul choix « tout allumé ». Cette couche a besoin d'un Service LoadBalancer qui obtienne réellement une IP : c'est ce que fait l'annonce L2 (ARP) de Cilium. Avec flannel, calico ou none, le Gateway reste en EXTERNAL-IP <pending> et aucune UI n'est joignable.

🌐 Le choix du CNI#

CNI (dans lab.env) est lu à deux endroits : talos/cluster-up.sh applique le patch talos/cni-<CNI>.yaml au bootstrap, puis platform-up.sh installe le CNI quand ce n'est pas Talos qui l'a fait.

⚠️ Changer de CNI sur un cluster existant n'est pas supporté : vagrant destroy puis reconstruire. Deux CNI simultanés se disputent le réseau des pods.

🔗 Chaîne de dépendances#

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

cluster Ready  (Talos a bootstrapé, CNI selon lab.env)
   │
   ├─ 1. CNI              cilium/ (défaut, + pool L2 → IP LoadBalancer .200)
   │                      ou calico/ (CNI seul) ou flannel (déjà posé) ou rien
   ├─ 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     *.talos.lab.example.io — deux modes, selon SELF_SIGNED
              │             true  (défaut) → self-signed/   openssl, AC locale, pas de cert-manager
              │             false          → cert-manager/  Let's Encrypt DNS-01 Cloudflare
              │
              └─ addons : stockage → bases → secrets → observabilité → sécurité

C'est exactement l'ordre de platform-up.sh ([1/4] → [4/4]) : metrics-server avant le certificat. Les deux modes TLS remplissent le même Secret (wildcard-<LAB_DOMAIN en tirets>-tls), donc aucun addon n'a jamais à savoir lequel tu as choisi — tous se contentent d'accrocher une HTTPRoute à l'écouteur https.

📋 Prérequis transverses#

💡 Les StorageClass ne sont pas interchangeables : longhorn-r1 (1 réplica) est le socle des applis qui répliquent déjà au niveau applicatif (PostgreSQL, Vault), longhorn (3 réplicas) pour le reste, local-path pour l'éphémère. Voir longhorn/ et local-path-storage/.

🌐 LAB_DOMAIN — le domaine des UI#

Le dépôt est public : tous les manifestes versionnés portent un domaine neutre, talos.lab.example.io. Mets le tien dans lab.env (gitignoré) :

echo 'LAB_DOMAIN=talos.lab.mon-domaine.tld' >> lab.env

Les scripts *-up.sh (platform-up.sh, argocd-up.sh, kyverno-up.sh, observability-up.sh, minio-up.sh, minio-cluster-up.sh, trivy-operator-up.sh, vault/00-secrets-engines.sh) lisent LAB_DOMAIN — variable d'environnement d'abord, sinon lab.env, sinon le défaut neutre — et substituent le domaine à la volée :

sed "s/talos\.lab\.example\.io/${LAB_DOMAIN}/g" <manifeste> | kubectl apply -f -

Aucun fichier versionné n'est réécrit : git status reste propre.

⚠️ Les manifestes appliqués à la main (sans *-up.sh) ne bénéficient pas de cette substitution : wordpress-example/wordpress-mariadb.yaml, longhorn/httproute.yaml, vault-cluster/httproute.yaml, vault-secret-operator/k8s/30-pki-tls.yaml. Soit tu les édites, soit tu passes par le même sed :

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

ℹ️ SELF_SIGNED décide comment ce domaine obtient son certificat (cf. lab.env.example). true — le défaut — signe un wildcard avec openssl sous une AC locale (self-signed/) : pas de domaine réel, pas de token, pas de quota, et le domaine n'a jamais besoin de résoudre publiquement. false bascule sur cert-manager/ + Let's Encrypt, et c'est seulement là que les trois variables ACME comptent : LAB_DNS_ZONE (zone du solveur DNS-01 ; défaut = les 2 derniers labels de LAB_DOMAIN), LAB_ACME_EMAIL (compte Let's Encrypt ; défaut admin@<zone>) et LAB_ACME_ISSUER — staging (défaut, cert non trusté) ou prod (trusté, mais plafonné à 5 certificats par semaine pour un même wildcard, et chaque vagrant destroy en brûle un).

🧱 Plateforme de base — platform-up.sh#

Installe uniquement les 4 briques ci-dessus, idempotent (helm upgrade --install), relançable sans casse.

ℹ️ Avec le défaut SELF_SIGNED=true, l'étape [4/4] lance self-signed/selfsigned-up.sh à la place et cert-manager n'est jamais installé — ni chart, ni CRD, ni Secret Cloudflare.

ℹ️ metrics-server adapté Talos : --kubelet-insecure-tls + port sécurisé 10250, pour ne pas exiger d'approbateur de CSR kubelet. Vérif : kubectl top nodes.

🗂️ Les addons#

Ordre conseillé : le stockage d'abord (tout le reste en dépend), puis les bases, puis le reste dans n'importe quel ordre.

💾 Stockage#

🐘 Bases de données#

🔐 Secrets#

📈 Observabilité#

🛡️ Sécurité#

🌐 Réseau & TLS#

🧪 Démos#

🌍 Accès distant (Tailscale + Cloudflare)#

Le 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 approuver dans la console Tailscale.

   ⚠️ Reste sur le /32 (ou cadre par ACL) : un /24 exposerait aussi les API Talos (:50000) et Kubernetes (:6443).

2. Nom + TLS — wildcard Cloudflare public *.talos.lab.example.io → 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 → le Gateway doit porter un certificat publiquement trusté (Let's Encrypt, cf. cert-manager/). Un certificat Cloudflare Origin CA serait rejeté par les navigateurs.

⚠️ Pièges#

• 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 la plus récemment créée, de façon non déterministe. Nomme toujours ta SC.
• Les policies Kyverno du dépôt sont violées par le dépôt. require-requests-limits exige limits.cpu que les manifestes maison ne posent jamais (choix délibéré : pas de throttling CPU), et require-labels attend app.kubernetes.io/name là où ils utilisent app:. Le rapport est donc bruyant par construction — voir kyverno/.
• Les émetteurs de métriques sont coupés par défaut. serviceMonitor/podMonitor sont à false chez trivy-operator, CloudNativePG et node-problem-detector : Prometheus ne collecte rien d'eux tant que tu ne les as pas basculés après l'install d'observability.
• Ne descends jamais CP_MEM sous 3072. Empiler ces addons sur des control planes à 2 Go affame etcd. lab.env.example livre 4096, ce qu'observability/ exige.
• Un git add -A peut publier des secrets d'addons locaux. _k8s/databasement/ est désormais gitignoré pour cette raison — vérifie git status avant de commiter.

📚 Références#

• ../LISEZ-MOI.md — le lab Talos/Vagrant, du vagrant up au cluster prêt
• ../talos/MISE-A-JOUR.md — mise à jour Talos et Kubernetes
• Gateway API · Cilium · Envoy Gateway · cert-manager

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

./_k8s/cilium/cilium-up.sh

Chart cilium/cilium 1.19.6, pinned in the script via CILIUM_VERSION (overridable: CILIUM_VERSION=1.19.7 ./_k8s/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.

🔧 What the script does#

1. Installs Cilium with Helm in kube-system, with the Talos-specific + L2 values;
2. waits for condition=Ready on every node (300 s max) — the CNI is what unblocks them;
3. applies cilium-l2.yml: LoadBalancer IP pool + ARP announcement policy.

The --set flags that matter#

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.
• enp0s8 interface: the host-only NIC, the only address through which the host can reach the VMs (adapt the ^enp0s8$ regex if your NICs have other names).
• 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

🌐 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 takes two consistent changes: proxy.disabled: true in talos/cni-none.yaml and kubeProxyReplacement=true + k8sServiceHost=192.168.56.5 k8sServicePort=6443 on the Helm side. Done halfway, the cluster loses its Services.
• 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.
• Alpha API: CiliumL2AnnouncementPolicy only exists as cilium.io/v2alpha1 on 1.19.6 (the pool itself moved to v2 — v2alpha1 is marked deprecated there). Re-check on a major version bump: kubectl get crd ciliuml2announcementpolicies.cilium.io -o yaml.

📚 References#

• Talos — Deploying Cilium
• Cilium — LoadBalancer IPAM
• Cilium — L2 Announcements
• ../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#

./_k8s/cilium/cilium-up.sh

Chart cilium/cilium 1.19.6, épinglé dans le script via CILIUM_VERSION (surchargeable : CILIUM_VERSION=1.19.7 ./_k8s/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.

🔧 Ce que fait le script#

1. Installe Cilium en Helm dans kube-system avec les valeurs spécifiques Talos + L2 ;
2. attend condition=Ready sur tous les nodes (300 s max) — c'est le CNI qui les débloque ;
3. applique cilium-l2.yml : pool d'IP LoadBalancer + politique d'annonce ARP.

Les --set qui comptent#

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 enp0s8 : la carte host-only, seule adresse par laquelle l'hôte peut joindre les VMs (le regex ^enp0s8$ est à adapter si tes cartes ont d'autres noms).
• 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

🌐 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.
• Remplacer kube-proxy demande deux changements cohérents : proxy.disabled: true dans talos/cni-none.yaml et kubeProxyReplacement=true + k8sServiceHost=192.168.56.5 k8sServicePort=6443 côté Helm. À moitié fait, le cluster perd ses Services.
• 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.
• API alpha : CiliumL2AnnouncementPolicy n'existe qu'en cilium.io/v2alpha1 sur 1.19.6 (le pool, lui, est passé en v2 — v2alpha1 y est marqué déprécié). À revérifier lors d'une montée de version majeure : kubectl get crd ciliuml2announcementpolicies.cilium.io -o yaml.

📚 Références#

• Talos — Deploying Cilium
• Cilium — LoadBalancer IPAM
• Cilium — L2 Announcements
• ../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/ layer of the lab depends on that VIP. See 🌐 Making the UIs reachable for the procedure.

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#

./_k8s/calico/calico-up.sh

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:

🔧 What the script does#

1. Guardrails: binaries, /readyz, refusal if another CNI is already there, and refusal if POD_CIDR diverges from the podSubnets read in _out/controlplane.yaml.
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, and Talos's baseline default rejects the operator pod (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: installing an L2 announcer is on you. This directory does not do it. Two things to do, in this order.

1. Install MetalLB in L2 mode on the same range Cilium uses (192.168.56.200 → 192.168.56.230, with the first IP going to main-gateway):

helm repo add metallb https://metallb.github.io/metallb
helm upgrade --install metallb metallb/metallb --version 0.16.1 \
  -n metallb-system --create-namespace

Then an IPAddressPool + an L2Advertisement (metallb.io/v1beta1) covering the range.

ℹ️ PodSecurity: the MetalLB speaker runs in hostNetwork with NET_RAW. The Talos default is baseline, which rejects such pods. So you have to set pod-security.kubernetes.io/enforce: privileged on the metallb-system namespace — same recipe as ../observability/namespace.yaml.

2. Remove the Cilium-specific loadBalancerClass. ../envoy-gateway/Envoy-Proxy.yml currently pins, on line 13:

        loadBalancerClass: io.cilium/l2-announcer

⚠️ As long as that line is there, MetalLB will not serve the Service. A loadBalancerClass tells Kubernetes "only this controller may handle this Service": MetalLB will ignore it and the IP will stay <pending> even with a valid pool. You have to delete the line (any announcer then takes over) or replace it with the class of the announcer you chose.

Once both points are done:

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

⚠️ 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=enp0s8 (Cilium).
• PodSecurity baseline 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; Talos enforces baseline by default, which rejects both. helm --create-namespace sets no PSS label, so without namespace.yaml the Deployment is created but 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 ≠ Talos podSubnets = silently broken pod network. The script refuses to continue if it detects the mismatch in _out/controlplane.yaml, 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: vagrant destroy → CNI=calico in lab.env → vagrant up → ./talos/cluster-up.sh → ./_k8s/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 installing MetalLB.
• eBPF dataplane: tempting, ruled out. The Sidero guide recommends it, but it requires bpfNetworkBootstrap: Enabled, kubeProxyManagement: Enabled and a FelixConfiguration with cgroupV2Path: /sys/fs/cgroup (Talos has no usable /var for that) — and it is broken on some Talos versions (BPF program load failed on calico_sendmsg_v46, see siderolabs/talos#12221). Too many moving parts for the lab's "comparison" CNI.
• 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 (vagrant destroy → CNI=cilium → cluster-up.sh → _k8s/platform-up.sh).

📚 References#

• Sidero — Deploy Calico CNI (Talos)
• Calico — Installation API (operator.tigera.io/v1)
• Calico — Configure BGP peering / advertise service IPs
• Calico — Get started with NetworkPolicy
• MetalLB — Layer 2 configuration
• ../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/ du lab dépend de ce VIP. Voir 🌐 Rendre les UI joignables pour la marche à suivre.

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#

./_k8s/calico/calico-up.sh

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 :

🔧 Ce que fait le script#

1. Garde-fous : binaires, /readyz, refus si un autre CNI est déjà là, et refus si POD_CIDR diverge du podSubnets lu dans _out/controlplane.yaml.
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, et le défaut baseline de Talos refuse le pod de l'opérateur (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