Utilisateur de la CLI, le fait de donner tout pouvoir à un outil tel que Claude ne me plaisait pas trop, et j'ai donc naturellement commencé à utiliser Docker Sandbox (sbx) qui me permet, entre autres, d'avoir :

• Une isolation du filesystem (sbx n'a accès qu'au dossier courant, et il ne "pourrit" pas mon système hôte)
• Pas d'accès à toutes mes variables d'environnement
• Un contrôle sur les flux réseau sortants

Mais le problème, c'est qu'une sandbox sbx, c'est une micro-vm qui peut être éphémère. Une fois la session Claude terminée, vous pouvez la supprimer avec sbx rm, son historique et sa mémoire avec.

⚠️ Ce que j'ai mis en place à date (été 2026) peut avoir évolué depuis, les projets sont très actifs !

Les problèmes

La mémoire

Claude Code stocke la mémoire et l'historique de chaque session dans ~/.claude/projects/<slug>/. Oui, vous pouvez vérifier chez vous, vous aurez un dossier dont le nom dérive du chemin du workspace pour chaque dossier où vous avez lancé une session Claude. Dans une sandbox, ce dossier vit sur un volume Docker lié au cycle de vie de la sandbox. Lorsqu'on supprime la sandbox (sbx rm), on perd tout : la mémoire accumulée au fil des sessions, les transcripts .jsonl, la config perso.

Et donc vous voyez venir la tuile : au prochain sbx run alors que la sandbox a été détruite, tout est oublié 🫤.

La config custom

Autre problème, j'utilise Claude à ma façon, et j'aimerais bien avoir ma façon aussi dans la sandbox, comme par exemple :

• Mon propre CLAUDE.md
• Ma config propre (thème clair, en français, pas de télémétrie)
• Mes hooks activés (RTK)

Avec sbx run claude, Claude Code est lancé en mode YOLO, mais pas plus. Il va falloir trouver un moyen de copier depuis l'hôte.

TL;DR : Vous pouvez retrouver mon kit ici si vous avez la flemme de lire la suite 🫠.

Une solution : les kits mixin

Docker sbx permet d'étendre les fonctionnalités de base avec des kits, notamment les kits mixin. C'est donc cela que je vais utiliser pour résoudre mes 2 problèmes !

J'utilise la spec v2 des kits, livrée avec sbx 0.38.0, sortie le jour même de cet article.

Sauver la mémoire sur l'hôte

Un kit sbx ne peut pas monter un dossier arbitraire de l'hôte. Les seuls chemins réellement persistants côté hôte dans une sandbox sont le workspace lui-même et les skills (au moins en version v0.38). Tout le reste (~/.claude/projects, sessions, todos) est un volume déclaré par l'agent de base, donc lié à la sandbox.

Ce qu'on va alors faire, c'est simplement de remplacer ~/.claude/projects/<slug> par un lien symbolique pointant vers .claude-project/ à la racine du workspace : lorsque ma sandbox sera créée, un dossier .claude-project/ sera créé à la racine du workspace, et le lien symbolique sera mis en place.

Côté kit, cela se fait via un script exécuté à chaque démarrage de sandbox dans le fichier spec.yaml.

1startup:
2  - description: Links ~/.claude/projects/<slug> to the workspace, excludes it from git
3    user: "1000"
4    command:
5      - sh
6      - -c
7      - |
8        # Mon super code généré par Claude pour faire un symlink

Ce script tourne à chaque démarrage de sandbox, mémoire et transcripts atterrissent alors physiquement sur mon Mac, visibles dans le Finder, survivent à sbx rm.

J'ai défini un dossier .claude-project/, qui est exclu localement via .git/info/exclude, cela est aussi géré au niveau du kit :

1# Ignore local to the clone, without touching the versioned .gitignore.
2# --git-common-dir (not --git-dir): in a linked worktree, --git-dir
3# points to .git/worktrees/<name>, where info/exclude is not read by git.
4GITDIR=$(git -C "$WS" rev-parse --git-common-dir 2>/dev/null) || exit 0
5case "$GITDIR" in /*) ;; *) GITDIR="$WS/$GITDIR" ;; esac
6mkdir -p "$GITDIR/info"
7grep -qxF '/.claude-project/' "$GITDIR/info/exclude" 2>/dev/null \
8  || echo '/.claude-project/' >> "$GITDIR/info/exclude"

Autre point important, avec agentInstructions je vais passer des instructions spécifiques pour que Claude Code gère bien ce dossier .claude-project/.

1agentInstructions:
2  content: |
3    ## Host-persisted project directory

Avec cela, lorsque la sandbox est arrêtée, supprimée, relancée, le dossier .claude-project/ persiste avec ce qu'il faut ! Fini la perte de mémoire en environnement cloisonné 🧠 !

Récupérer ma config perso

Le symlink règle la mémoire, mais chaque sbx run repart aussi avec un settings.json vierge. Même mécanique ici, un script qui merge un fichier JSON custom avec celui par défaut à chaque démarrage grâce à jq.

Voici mon fichier settings.custom.json (extrait) qui sera fusionné :

 1{
 2  "theme": "light-ansi",
 3  "statusLine": {
 4    "type": "command",
 5    "command": "~/.claude/statusline.sh"
 6  },
 7  "env": {
 8    "CLAUDE_CODE_ENABLE_TELEMETRY": "0"
 9  },
10  "language": "French"
11}

Et toujours pareil, le merge sera effectué au démarrage de la sandbox, défini ici dans le spec.yaml :

1jq --arg dir "$TARGET" --slurpfile kit "$CUSTOMSETTINGS" \
2   '. * {autoMemoryDirectory: $dir} * $kit[0]' "$SETTINGS" > "$TMP"

Ajouter mes hooks (RTK surtout)

On continue, cette fois-ci avec les hooks. Vous avez compris le principe maintenant, du bon script shell dans le spec.yaml qui installe le binaire et enregistre son hook, mais au setup cette fois, pour éviter d'installer RTK à chaque (re)démarrage de la sandbox !

J'aurais pu utiliser ici les templates pour inclure tous les tools / binaires nécessaires par défaut dans l'image de la sandbox, mais là ça m'évite de devoir gérer une image personnalisée.

Alors pour le moment c'est un peu sale, car on a "pin" la version de RTK à installer, pour éviter un curl | sh :

1setup:
2  install:
3    - description: Installs rtk (pinned binary, checksum verified) and its Bash hook
4      user: "1000" # Le user n'est pas root, mais 1000 par défaut
5      command: |
6        # Ma super installation de RTK

Le hook RTK a besoin de définir des ordres dans le fichier CLAUDE.md, on voit ça juste après.

Mon CLAUDE.md

Au fur et à mesure de mon utilisation de Claude, j'ai créé mon propre CLAUDE.md pour que l'outil me réponde selon mes préférences, et j'aimerais bien le retrouver dans mes sandboxes.

Cette fois-ci, pas la peine de scripter, le kit permet de copier simplement des fichiers depuis le répertoire files/home/.claude vers le répertoire ~/.claude/ de la sandbox.

"Sauf que", mon fichier à moi CLAUDE.md est personnel (profil, stack de référence, décisions actées, conventions de travail), pas forcément lié au projet ou à la sandbox. J'ai donc décidé :

• de le nommer PERSONA.md, et de faire une inclusion via @-import.
• d'avoir ce PERSONA.md placeholder dans le kit mis à disposition.
• d'avoir mon PERSONA.md synchronisé avec mise run claude via une task personnalisée (voir plus bas).

J'ai ensuite un @RTK.md : rtk en a besoin. Ce qui nous donne au final un fichier assez sommaire :

1<!-- PERSONA, mes infos "persos" -->
2@PERSONA.md
3
4<!-- Hook RTK (https://github.com/rtk-ai/rtk) -->
5@RTK.md

Synchro de mon PERSONA.md

Pour utiliser mon vrai ~/.claude/PERSONA.md, je le synchronise avec mise run claude, dont voici la task correspondante. Au moins si besoin d'être utilisée ailleurs, elle n'est pas exclusive au kit :

 1#!/usr/bin/env bash
 2#MISE description="Sandbox claude-project-host : new if absent, resume + attach if present"
 3#MISE dir="{{cwd}}"
 4#MISE tools={ "github:docker/sbx-releases" = "prefix:0.38" }
 5#USAGE arg "<workspace>" help="Chemin du workspace a monter" default="."
 6
 7# Copy PERSONA.md to the kit directory
 8kit_dir="$HOME/.config/sbx/claude-project-host"
 9cp "$HOME/.claude/PERSONA.md" "$kit_dir/files/home/.claude/PERSONA.md"
10
11ws="$(cd "${usage_workspace}" && pwd)" || { echo "Workspace not found: '${usage_workspace}'" >&2; exit 1; }
12name="claude-$(basename "$ws")"
13
14# Check if the sandbox is already present, reattach if so
15if sbx ls | awk '{print $1}' | grep -Fqx "$name"; then
16  echo "Sandbox '$name' present, reattaching..."
17  sbx run "$name"
18# Otherwise, create a new sandbox with the toolkit
19else
20  echo "Sandbox '$name' absent, creating..."
21  sbx run --name "$name" --kit "$kit_dir" claude "$ws"
22fi

En plus

Quelques bonus

Tant qu'à faire, je rajoute des instructions spécifiques dans mon kit :

• Faire des "Session summaries" : écrire un résumé après chaque choix / débat important, au format Markdown Obsidian pour que je puisse l'intégrer facilement dans mon coffre de notes.
• Pour le moment pas beaucoup plus 😅

Distribution du kit

Le mixin a été pensé pour mon usage perso, en français. Pour le publier, j'ai séparé le mécanisme (générique, à partager) du contenu (personnel, à ne pas partager).

Deux fichiers concentraient le problème :

• PERSONA.md — on l'a vu plus haut, le kit publié embarque désormais un placeholder (les sections à remplir, sans contenu), et mon vrai PERSONA.md reste local, resynchronisé par une tâche mise run claude qui vit hors du repo.
• "language": "French" dans les préférences répliquées — un défaut personnel que je garde pour mon propre usage, à charge pour quiconque fork le kit de le changer pour le sien.

Et pour celles et ceux qui ont lu jusque-là, je remets le lien du dépôt : https://github.com/rverchere/sbx-kit-claude-project-host

Amusez-vous bien avec Docker Sandbox et Claude Code !

Liens

• Spec des kits sbx : SPEC-v2.md
• Kits communautaires : sbx-kits-contrib
• Hook RTK : rtk-ai/rtk

Lorsque j'ai migré depuis Ingress NGINX, j'ai été un peu dérouté avec la notion de HTTPRoutes, Gateways, etc. Et j'ai remarqué que pour chaque Gateway définie dans le cluster, Envoy Gateway génère son propre déploiement Envoy et son propre Service de type LoadBalancer. Si sur le principe c'est cohérent avec la spec, j'aimerais un moyen de mutualiser les LoadBalancers entre les Gateways du cluster, pour notamment économiser des coûts de cloud (et les IPs publiques).

La problématique : un LoadBalancer par Gateway

En théorie, les équipes devs n'ont pas à gérer les Gateways, seulement les Routes, c'est aux ops de gérer cette partie. Mais parfois on peut donner de l'autonomie aux équipes, et qu'elles gèrent leurs propres Gateways avec leur policies. Sans mergeGateways, le schéma est le suivant : chaque équipe qui déploie une Gateway pour son application se retrouve avec son propre LB provisionné côté cloud, sa propre IP.

1Gateway "eg" (envoy-gateway-system)      → Service LB → IP 203.0.113.10
2Gateway "app1-gw"                        → Service LB → IP 203.0.113.11
3Gateway "app2-gw"                        → Service LB → IP 203.0.113.12
4Gateway "monitoring-gw" (monitoring)     → Service LB → IP 203.0.113.13
5[...]

Ce comportement est différent d'avant avec les ingress, où j'avais 1 seul LB pour toutes mes ressources. On va voir comment retrouver cette façon de faire.

La solution : mergeGateways

Envoy Gateway propose via la ressource EnvoyProxy un paramètre mergeGateways. Quand il est à true, toutes les Gateway utilisant la même GatewayClass partagent un seul déploiement Envoy et un seul Service LoadBalancer.

La ressource EnvoyProxy

C'est ici qu'on active la fusion des Gateways, et qu'on configure le Service LB partagé :

 1# envoyproxy-custom-proxy-config.yaml
 2apiVersion: gateway.envoyproxy.io/v1alpha1
 3kind: EnvoyProxy
 4metadata:
 5  name: custom-proxy-config
 6  namespace: envoy-gateway-system
 7spec:
 8  mergeGateways: true # <-- là
 9  provider:
10    type: Kubernetes
11    kubernetes:
12      envoyService:
13        type: LoadBalancer
14      envoyDeployment:
15        [...]

Le GatewayClass qui référence l'EnvoyProxy

La GatewayClass fait le lien entre les Gateway et notre configuration EnvoyProxy, via parametersRef :

 1# gatewayclass-eg.yaml
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: GatewayClass
 4metadata:
 5  name: eg
 6spec:
 7  controllerName: gateway.envoyproxy.io/gatewayclass-controller
 8  parametersRef:
 9    group: gateway.envoyproxy.io
10    kind: EnvoyProxy
11    name: custom-proxy-config # <-- mergeGateways: true
12    namespace: envoy-gateway-system

Toute Gateway déclarée avec gatewayClassName: eg bénéficiera automatiquement du merge.

La Gateway principale

La gateway "centrale" reste dans envoy-gateway-system, avec ses listeners HTTP/HTTPS habituels :

 1# gateway-eg.yaml
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: Gateway
 4metadata:
 5  name: eg
 6  namespace: envoy-gateway-system
 7spec:
 8  gatewayClassName: eg
 9  listeners:
10    - name: http
11      protocol: HTTP
12      port: 80
13      allowedRoutes:
14        namespaces:
15          from: All
16    - name: https
17      protocol: HTTPS
18      port: 443
19      tls:
20        mode: Terminate
21        certificateRefs:
22          - kind: Secret
23            name: ip-cert-tls # Voir article précédent
24      allowedRoutes:
25        namespaces:
26          from: All

Exemple : App1 avec sa propre Gateway

Avec mergeGateways, chaque application peut avoir sa propre Gateway dans son propre namespace.

La Gateway applicative

App1 déclare sa Gateway dans son namespace app1, avec son listener HTTPS et son certificat Let's Encrypt géré par cert-manager via l'annotation :

 1# app1-gateway.yaml
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: Gateway
 4metadata:
 5  name: app1-gateway
 6  namespace: app1
 7  annotations:
 8    cert-manager.io/cluster-issuer: letsencrypt-prod-eg
 9spec:
10  gatewayClassName: eg
11  listeners:
12    - name: https
13      protocol: HTTPS
14      hostname: app1.gravitek.io
15      port: 443
16      tls:
17        mode: Terminate
18        certificateRefs:
19          - kind: Secret
20            name: app1.gravitek.io-tls
21      allowedRoutes:
22        namespaces:
23          from: Same

La HTTPRoute

 1# app1-httproute.yaml
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: HTTPRoute
 4metadata:
 5  name: app1
 6  namespace: app1
 7spec:
 8  parentRefs:
 9    - group: gateway.networking.k8s.io
10      kind: Gateway
11      name: app1-gateway
12      namespace: app1
13      sectionName: https
14  hostnames:
15    - app1.gravitek.io
16  rules:
17    - matches:
18        - path:
19            type: PathPrefix
20            value: /
21      backendRefs:
22        - kind: Service
23          name: app1
24          port: 8080
25          weight: 1

Résultat : App1 est accessible via la même IP publique que toutes les autres applications, sans LB supplémentaire, avec son propre certificat géré de façon autonome dans son namespace.

Remarques

• Si besoin particulier, chaque application peut maintenant gérer des règles différentes sur les ClientTrafficPolicy, BackendTrafficPolicy & co.

• ⚠️ Pour la gestion TLS, dans mon cas d'usage toutes les applis ont des routes HTTPS, pas HTTP. La redirection HTTP vers HTTPS est gérée par la Gateway par défaut, avec un redirect permanent. Cela m'a posé soucis avec cert-manager, et cette configuration marche bien chez moi.

Alternative : ListenerSets

Gateway API v1.3 propose une approche alternative avec les ListenerSets : une Gateway principale expose des listeners de base, et des ListenerSet permettent d'en ajouter depuis d'autres namespaces.

C'est séduisant car c'est natif Gateway API (pas une extension Envoy), avec un modèle de permissions plus granulaire sur les listeners. Mais il y a des limites importantes à date :

• Seule HTTPRoute supportée : si vous utilisez des GRPCRoute, TCPRoute, elles ne peuvent pas référencer des listeners issus d'un ListenerSet.
• Encore expérimental : la feature est en alpha dans Gateway API, le support varie selon les implémentations.

Pour l'instant, mergeGateways reste la solution que j'ai choisie, à vous de voir laquelle vous préférez.

Conclusion

Avec mergeGateways, on passe d'un modèle "un LB par Gateway" à "un LB pour tout le cluster", retrouvant à peu près la configuration que j'avais avec Ingress NGINX :

• 💰 Un seul LoadBalancer partagé entre toutes les Gateways
• 🌐 Une seule IP publique → gestion DNS simplifiée
• 🧩 Autonomie conservée : chaque application gère sa propre Gateway dans son namespace, avec ses propres certificats et listeners

Bien sûr, rien ne vous empêche d'avoir plusieurs Gateways quand même, avec ou sans mergeGateways, cela dépend de votre besoin et architecture !

Ressources

• Envoy Gateway - mergeGateways : https://gateway.envoyproxy.io/docs/tasks/operations/deployment-mode/#merged-gateways-onto-a-single-envoyproxy-fleet
• Gateway API - ListenerSets (GEP-1713) : gateway-api.sigs.k8s.io/geps/gep-1713
• Envoy Gateway - EnvoyProxy API : gateway.envoyproxy.io/docs/api/extension_types/#envoyproxy

Imaginons une Envoy Gateway exposée sur l'IP publique 203.0.113.14, et une application maintenance (le service maintenance dans le namespace maintenance, sur le port 8080) qui sert une simple page "site en maintenance". On va voir comment servir cette page par défaut, en HTTPS sur l'IP publique elle-même.

⚠️ Je ne détaille pas l'installation d'Envoy Gateway ni de cert-manager (tous deux via Helm), ni non plus le déploiement de l'app de maintenance (simple page statique), qu'on suppose déjà en place. Nous allons nous concentrer sur le routing par défaut et le certificat sur IP.

Une réponse HTTP(S) par défaut "moche"

Quand on déclare des HTTPRoute avec des hostnames bien précis (app1.gravitek.io, app2.gravitek.io, etc.), tout le reste, qui ne correspond à aucune route (typiquement un curl https://203.0.113.14/, un scan, ou un DNS pas encore basculé) tombe dans le vide. Avec en prime une erreur de certificat TLS.

 1$ curl https://203.0.113.14/
 2curl: (60) SSL certificate problem: unable to get local issuer certificate
 3More details here: https://curl.se/docs/sslcerts.html
 4
 5curl failed to verify the legitimacy of the server and therefore could not
 6establish a secure connection to it. To learn more about this situation and
 7how to fix it, please visit the web page mentioned above.
 8
 9$ curl -k https://203.0.113.14/
10404 page not found

On va voir ci-après comment résoudre 2 problèmes d'un coup :

1. Un backend par défaut : tout ce qui ne matche aucune route applicative atterrit sur une page de maintenance propre.
2. Du HTTPS même sur l'IP : plus de gros warning de certificat invalide quand on accède à l'IP directement. Historiquement, impossible avec Let's Encrypt (que des domaines)... mais ça a changé 🎉.

Pour le point 2, ça résoud notamment un "problème" quand le mail du RSSI arrive : "Bonjour, votre IP 203.0.113.14 présente un certificat invalide, merci de corriger 🙏". Jusqu'à présent je lui répondais qu'on ne pouvait pas avoir un certificat sur une IP, mais c'est maintenant possible 😅.

Pré-requis : configuration des composants

Pour activer le support de la Gateway API & du Backend par défaut, deux paramètres doivent être activés dans les values des différents charts (si vous utilisez Helm, sinon je vous laisse chercher les équivalents niveau configuration) :

cert-manager : support de la Gateway API

cert-manager doit savoir résoudre un challenge ACME via une HTTPRoute (et non un Ingress). C'est l'option enableGatewayAPI :

1# custom-values-cert-manager.yaml
2cert-manager:
3  # CRDs
4  crds:
5    enabled: true
6
7  # Enable Gateway API Support
8  config:
9    enableGatewayAPI: true

Sans ça, le solver http01 de type gatewayHTTPRoute (qu'on verra plus bas) est tout simplement ignoré.

Envoy Gateway : activer l'API Backend

Pour router vers un endpoint qui n'est pas un Service Kubernetes (ici une app dans un autre namespace, qu'on veut joindre par son FQDN interne), Envoy Gateway propose une ressource Backend. C'est une extension API, on l'active :

1# custom-values-envoy.yaml
2# https://gateway.envoyproxy.io/v1.7/install/install-helm/#enable-backend-api
3config:
4  envoyGateway:
5    extensionApis:
6      enableBackend: true

La Gateway et son IP publique

Côté GatewayClass, rien de particulier : une classe standard rattachée au contrôleur Envoy Gateway.

1# gatewayclass-eg.yaml
2apiVersion: gateway.networking.k8s.io/v1
3kind: GatewayClass
4metadata:
5  name: eg
6spec:
7  controllerName: gateway.envoyproxy.io/gatewayclass-controller

La Gateway elle-même expose deux listeners, HTTP et HTTPS, ce dernier terminant le TLS avec le secret ip-cert-tls, qu'on va générer juste après :

 1# gateway-eg.yaml
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: Gateway
 4metadata:
 5  name: eg
 6  namespace: envoy-gateway-system
 7spec:
 8  gatewayClassName: eg
 9  listeners:
10    - name: http
11      protocol: HTTP
12      port: 80
13      allowedRoutes:
14        namespaces:
15          from: All
16    - name: https
17      protocol: HTTPS
18      port: 443
19      tls:
20        mode: Terminate
21        certificateRefs:
22          - group: ""
23            kind: Secret
24            name: ip-cert-tls # Certificat IP
25      allowedRoutes:
26        namespaces:
27          from: All

Un certificat Let's Encrypt sur une IP

Pendant des années, Let's Encrypt ne signait que des noms de domaine. Taper https://203.0.113.14/ donnait un certificat invalide. Depuis l'annonce de Let's Encrypt sur les certificats pour adresses IP, c'est devenu possible (c'est désormais en GA (janvier 2026)) avec une contrainte : ces certificats ne sont délivrés que via le profil shortlived, des certificats à durée de vie très courte (~6 jours).

Le ClusterIssuer en profil shortlived

cert-manager supporte la sélection de ce profil ACME via le champ profile. On déclare un ClusterIssuer dédié, qui résout le challenge HTTP-01 via une HTTPRoute rattachée à notre gateway :

 1# clusterissuer-letsencrypt-prod-eg-shortlived.yaml
 2apiVersion: cert-manager.io/v1
 3kind: ClusterIssuer
 4metadata:
 5  name: letsencrypt-prod-shortlived
 6spec:
 7  acme:
 8    email: remi@gravitek.io
 9    server: https://acme-v02.api.letsencrypt.org/directory
10    privateKeySecretRef:
11      name: letsencrypt-prod-shortlived
12    profile: shortlived # Profil ACME
13    solvers:
14      - http01:
15          gatewayHTTPRoute: # Ref à ma Gateway
16            parentRefs:
17              - name: eg
18                namespace: envoy-gateway-system
19                group: gateway.networking.k8s.io
20                kind: Gateway

Deux points à noter :

• profile: shortlived : c'est obligatoire pour obtenir un certificat sur IP. Un profil classique refusera la demande.
• solvers.http01.gatewayHTTPRoute : cert-manager crée automatiquement une HTTPRoute temporaire sur la gateway eg le temps de résoudre le challenge /.well-known/acme-challenge/.... Pour un cert sur IP, seul HTTP-01 est possible : pas de DNS-01 (pas de zone DNS pour une IP, CQFD 🤷).

Le Certificate qui demande l'IP

Maintenant qu'on a notre Gateway, Route et ClusterIssuer, on peut déclarer notre certificat. Il ressemble à n'importe quel autre, sauf qu'on remplace dnsNames par ipAddresses :

 1# certificate-ip.yaml
 2apiVersion: cert-manager.io/v1
 3kind: Certificate
 4metadata:
 5  name: ip-cert
 6  namespace: envoy-gateway-system
 7spec:
 8  secretName: ip-cert-tls
 9  secretTemplate:
10    labels:
11      x509-certificate-exporter/exclude: "true"
12  issuerRef:
13    name: letsencrypt-prod-shortlived
14    kind: ClusterIssuer
15  ipAddresses:
16    - 203.0.113.14

L'IP doit être l'IP publique de la gateway (celle exposée par le Service LoadBalancer d'Envoy chez moi), et le secretName doit correspondre au certificateRefs du listener HTTPS.

💡 Pourquoi Le label x509-certificate-exporter/exclude: "true" ? Si vous monitorez l'expiration de vos certificats avec x509-certificate-exporter, un certificat qui expire tous les ~6 jours va générer une alerte en permanence. Je décide de le dégager de la supervision.

⚠️ Les certificats shortlived durent quelques jours seulement : cert-manager les renouvelle très fréquemment, attention au rate-limit Let's Encrypt et au solver HTTP-01.

Une fois le certificat émis :

1$ kubectl -n envoy-gateway-system get certificate ip-cert
2NAME         READY   SECRET           AGE
3ip-cert      True    ip-cert-tls      2m

Et curl https://203.0.113.14/ ne hurle plus au certificat invalide 🎉.

Le backend par défaut, mais avec la page de maintenance

On a maintenant un certificat valide pour l'IP, mais on a toujours une page par défaut moche. On va améliorer cela avec un backend par défaut.

La ressource Backend

L'app de maintenance vit dans son propre namespace maintenance. Plutôt que de jouer avec un Service cross-namespace et une ReferenceGrant, on déclare un Backend Envoy Gateway qui pointe vers le FQDN interne du service :

 1# backend-maintenance.yaml
 2apiVersion: gateway.envoyproxy.io/v1alpha1
 3kind: Backend
 4metadata:
 5  name: maintenance
 6  namespace: envoy-gateway-system
 7spec:
 8  endpoints:
 9    - fqdn:
10        hostname: maintenance.maintenance.svc.cluster.local
11        port: 8080

C'est exactement le cas d'usage de l'API Backend qu'on a activée plus haut : un endpoint arbitraire (FQDN, IP...) consommable depuis une HTTPRoute, dans le namespace de la gateway.

La HTTPRoute par défaut (catch-all)

Le "backend par défaut" est simplement une HTTPRoute sans hostnames. Sans hostname déclaré, elle matche tout le trafic du listener HTTPS qui n'est pas capté par une route applicative plus spécifique :

 1# httproute-default-backend.yaml
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: HTTPRoute
 4metadata:
 5  name: default-backend
 6  namespace: envoy-gateway-system
 7spec:
 8  parentRefs:
 9    - group: gateway.networking.k8s.io
10      kind: Gateway
11      name: eg
12      sectionName: https
13  rules:
14    - backendRefs:
15        - group: gateway.envoyproxy.io
16          kind: Backend
17          name: maintenance
18          weight: 1
19      matches:
20        - path:
21            type: PathPrefix
22            value: /

Le backendRefs ne pointe pas un Service mais bien un kind: Backend du groupe gateway.envoyproxy.io. Les HTTPRoute applicatives, elles, ont des hostnames précis et sont donc plus spécifiques : Gateway API les fait gagner sur le catch-all. Notre default-backend ne capte donc que le reste IP directe, host inconnu, DNS pas encore basculé.

⚠️ Je vous invite à lire la doc Envoy Gateway, quelques warnings & restrictions existent.

Redirection "IP" HTTP vers HTTPS

Tant qu'on y est, on évite de servir la maintenance en clair sur le port 80 : on redirige tout HTTP vers HTTPS, là aussi via une route catch-all (sans hostname) attachée au listener http :

 1# httproute-https-redirect.yaml
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: HTTPRoute
 4metadata:
 5  name: http-to-https-redirect
 6  namespace: envoy-gateway-system
 7spec:
 8  parentRefs:
 9    - group: gateway.networking.k8s.io
10      kind: Gateway
11      name: eg
12      sectionName: http
13  rules:
14    - filters:
15        - type: RequestRedirect
16          requestRedirect:
17            scheme: https
18            statusCode: 301
19      matches:
20        - path:
21            type: PathPrefix
22            value: /

⚠️ Attention à l'ordre des opérations avec le challenge ACME : le solver HTTP-01 a besoin de répondre en HTTP sur /.well-known/acme-challenge/. La HTTPRoute temporaire créée par cert-manager est plus spécifique (elle matche ce path précis) que notre redirect catch-all /, donc le challenge passe avant la redirection, mais faites attention on sait jamais.

Le résultat

Au final, n'importe quel accès qui ne tombe pas sur une app connue :

1# Accès direct par IP, en HTTP → redirigé en HTTPS
2$ curl -IL http://203.0.113.14/
3HTTP/1.1 301 Moved Permanently
4location: https://203.0.113.14/
5
6# ... puis servi par la page de maintenance, certificat valide
7$ curl https://203.0.113.14/
8<html><body><h1>Page non trouvée.</h1></body></html>

Plus de 404 page not found moche, plus de warning de certificat : un point d'entrée propre, en HTTPS, même sur l'IP nue.

Voici "en joli" ce que ça peut donner:

Conclusion

En assemblant quelques ressources, on obtient un comportement par défaut soigné sur la gateway :

• 🧭 Un backend par défaut via une HTTPRoute sans hostname + une ressource Backend Envoy Gateway, qui rattrape tout le trafic non routé.
• 🔒 Du HTTPS valide sur l'IP elle-même, grâce aux certificats Let's Encrypt sur adresse IP et au profil shortlived.
• 🤖 Le tout auto-renouvelé par cert-manager en solver HTTP-01, même si le certificat est court.

Avec tout ça, notre RSSI est content 😎. Ah, et pour les curieux, je n'ai pas testé en IPv6 !

Ressources

• Let's Encrypt - Premier certificat sur adresse IP : letsencrypt.org/2025/07/01/issuing-our-first-ip-address-certificate
• Let's Encrypt - Certificats short-lived : letsencrypt.org/2025/02/20/first-short-lived-cert-issued
• Let's Encrypt - Disponibilité générale (6 jours & IP) : letsencrypt.org/2026/01/15/6day-and-ip-general-availability
• cert-manager - ACME profiles : cert-manager.io/docs/configuration/acme/#acme-profiles
• Envoy Gateway - Backend : gateway.envoyproxy.io/docs/tasks/traffic/backend

Pour l'exemple, on va imaginer une app mysecureapp dans le namespace mysecurens, accessible sur mysecureapp.gravitek.io, et un Keycloak sur sso.gravitek.io.

💡 J'ai profité de cet article pour tester ma démo sur l'environnement Clever Cloud avec un cluster Kubernetes CKE et un add-on Keycloak. Je ne détaille pas le setup ici, peut-être dans un autre article 😉.

⚠️ Je n'explique pas non plus comment configurer Keycloak, ni comment exposer l'app via Gateway API, on suppose que vous avez déjà à disposition ces éléments.

Contexte : exposer l'app via Gateway API

La route applicative /

La HTTPRoute de base est classique : on route tout le trafic de mysecureapp.gravitek.io vers le service applicatif.

 1apiVersion: gateway.networking.k8s.io/v1
 2kind: HTTPRoute
 3metadata:
 4  name: mysecureapp
 5  namespace: mysecurens
 6spec:
 7  parentRefs:
 8    - kind: Gateway
 9      name: eg
10      namespace: mysecurens
11      sectionName: mysecureapp-https
12  hostnames:
13    - mysecureapp.gravitek.io
14  rules:
15    - matches:
16        - path:
17            type: PathPrefix
18            value: /
19      backendRefs:
20        - name: mysecureapp
21          port: 8080

La route /oauth2 pour le callback OIDC

Pour que l'authentification OIDC fonctionne, la redirectURL et le logoutPath de la SecurityPolicy (qu'on verra juste après) doivent matcher une règle de la HTTPRoute. C'est mentionné dans la doc Envoy Gateway, en particulier la section "OIDC Authentication for a HTTPRoute" → "Create a SecurityPolicy". C'est aussi valable pour une policy attachée à une Gateway.

Ici, la route / ci-dessus couvre déjà /oauth2/callback — donc en théorie une règle dédiée n'est pas obligatoire. Mais dès qu'on remplace ce / par des préfixes spécifiques (ex: /myapp, /metrics), aucun ne couvre /oauth2 et la règle devient indispensable. Pour ne pas se mélanger les pinceaux, autant la déclarer explicitement dès le départ :

1  # Endpoint interne du filtre OAuth2
2  rules:
3    - matches:
4        - path:
5            type: PathPrefix
6            value: /oauth2

Pas besoin de backendRefs ici : ce path est entièrement géré en interne par le filtre OIDC d'Envoy (callback, échange de token, logout). Il faut juste que la HTTPRoute accepte de le router.

OIDC avec SecurityPolicy

Avant, avec ingress-nginx, ce type d'app tournait avec un oauth2-proxy déployé à côté, avec ses propres Ingress, sa conf, et son Deployment à maintenir. Avec Envoy Gateway, la SecurityPolicy fait exactement le même travail, sans déploiement supplémentaire :

 1# SecurityPolicy
 2apiVersion: gateway.envoyproxy.io/v1alpha1
 3kind: SecurityPolicy
 4metadata:
 5  name: mysecureapp-oidc
 6  namespace: mysecurens
 7spec:
 8  targetRefs:
 9    - group: gateway.networking.k8s.io
10      kind: HTTPRoute
11      name: mysecureapp
12  oidc:
13    provider:
14      issuer: https://sso.gravitek.io/realms/myrealm
15    clientID: mysecureapp
16    clientSecret:
17      name: mysecureapp-client-secret   # Secret K8s contenant le client_secret
18    redirectURL: https://mysecureapp.gravitek.io/oauth2/callback
19    logoutPath: /oauth2/logout
20    scopes:
21      - openid
22      - groups  # On se basera plus tard la-dessus pour l'authz
23    cookieNames:
24      idToken: "IdTokenMySecureApp"

Le targetRefs pointe sur la HTTPRoute. Envoy intercepte toutes les requêtes, lance le flow OAuth2/OIDC si l'utilisateur n'est pas authentifié, et pose le cookie IdTokenMySecureApp avec l'id_token JWT une fois connecté.

➡️ Résultat : toute personne avec un compte valide dans le realm peut accéder à l'app. C'est déjà pas mal... mais on peut mieux faire !

💡 Pourquoi fixer cookieNames.idToken ? Ce champ est optionnel : sans lui, Envoy nomme le cookie IdToken mais y ajoute un suffixe de hash dérivé du domaine (ex: IdToken-5671b67c), donc imprévisible. Or le filtre JWT relira ce cookie plus tard via extractFrom.cookies et a besoin d'un nom stable. On l'épingle donc explicitement.

Authn ≠ Authz

L'OIDC, c'est de l'authentification : il vérifie qui vous êtes. Il ne dit rien sur ce que vous avez le droit de faire. Avec la SecurityPolicy ci-dessus, n'importe quel compte du realm peut se connecter 🙈.

Il faut alors de l'autorisation : restreindre ici l'accès aux membres d'un groupe spécifique. Envoy Gateway résout ça avec deux blocs supplémentaires dans la même SecurityPolicy :

• jwt : pour extraire et valider le token depuis le cookie posé par le filtre OIDC
• authorization : pour définir les règles d'accès à partir des claims du token

L'ordre des filtres générés par Envoy Gateway est oauth2 (OIDC) → jwt → authorization, le filtre OIDC s'exécute en premier. Une requête non authentifiée est donc interceptée et redirigée vers Keycloak avant que le filtre JWT ne soit évalué : ce dernier ne voit que des requêtes déjà authentifiées, qui portent l'id_token dans le cookie.

Filtrage par groupe avec JWT et authorization

Pour pouvoir vérifier les groupes d'un utilisateur, on va d'abord configurer le filtre JWT pour lire le cookie IdTokenMySecureApp et en extraire le claim groups :

 1# SecurityPolicy
 2  jwt:
 3    providers:
 4      - name: keycloak
 5        issuer: "https://sso.gravitek.io/realms/myrealm"
 6        remoteJWKS:
 7          cacheDuration: 300s
 8          uri: "https://sso.gravitek.io/realms/myrealm/protocol/openid-connect/certs"
 9        extractFrom:
10          cookies:
11            - IdTokenMySecureApp

Ensuite, on configure le bloc authorization où par défaut tout est refusé, et on autorise uniquement les membres du groupe /admins :

 1  authorization:
 2    defaultAction: Deny
 3    rules:
 4      - name: allow-admin-group
 5        action: Allow
 6        principal:
 7          jwt:
 8            provider: keycloak
 9            claims:
10              - name: groups
11                valueType: StringArray
12                values: ["/admins"]

Le claim groups est un tableau dans Keycloak, d'où le valueType: StringArray. Envoy vérifie que /admins est présent dans ce tableau — si oui, la requête passe. Sinon, 403.

Groupes Keycloak

Pour que le claim groups reflète l'appartenance aux groupes, il faut un mapper de type Group Membership sur le client scope.

Avec l'option Full group path activée sur le mapper Group Membership, le claim vaut /admins (avec le slash initial) ; désactivée, il vaut admins. Envoy fait une comparaison exacte : values: ["/admins"] ne matchera jamais un claim admins, et inversement. Un simple / de différence = 403. Choisissez une convention et gardez la même des deux côtés (le mapper Keycloak et le bloc authorization).

SecurityPolicy complète

En assemblant le tout, un seul objet qui fait l'authn et l'authz :

 1apiVersion: gateway.envoyproxy.io/v1alpha1
 2kind: SecurityPolicy
 3metadata:
 4  name: mysecureapp-oidc
 5  namespace: mysecurens
 6spec:
 7  targetRefs:
 8    - group: gateway.networking.k8s.io
 9      kind: HTTPRoute
10      name: mysecureapp
11
12  oidc:
13    provider:
14      issuer: https://sso.gravitek.io/realms/myrealm
15    clientID: mysecureapp
16    clientSecret:
17      name: mysecureapp-client-secret
18    redirectURL: https://mysecureapp.gravitek.io/oauth2/callback
19    logoutPath: /oauth2/logout
20    scopes:
21      - openid
22      - groups
23    cookieNames:
24      idToken: "IdTokenMySecureApp"
25
26  jwt:
27    providers:
28      - name: keycloak
29        issuer: "https://sso.gravitek.io/realms/myrealm"
30        remoteJWKS:
31          cacheDuration: 300s
32          uri: "https://sso.gravitek.io/realms/myrealm/protocol/openid-connect/certs"
33        extractFrom:
34          cookies:
35            - IdTokenMySecureApp
36
37  authorization:
38    defaultAction: Deny
39    rules:
40      - name: allow-admin-group
41        action: Allow
42        principal:
43          jwt:
44            provider: keycloak
45            claims:
46              - name: groups
47                valueType: StringArray
48                values: ["/admins"]

Le diagramme ci-dessous résume le flux complet :

Et donc, après tout ce paramétrage, vous aurez un beau message si vous n'avez pas les droits nécessaires 😕 :

1RBAC: access denied

Sinon, si vous êtes dans le bon groupe, vous pourrez accéder à votre application 🥳 !

Allons plus loin : passer l'identité à l'application

Tout ce qu'on a vu jusqu'ici se passe dans la gateway : la décision authn/authz est prise par Envoy, et le backend mysecureapp ne voit jamais le token ni les groupes. C'est suffisant pour protéger l'accès, mais parfois l'app a elle-même besoin de savoir qui est connecté (afficher le nom de l'utilisateur, adapter l'UI selon les groupes, appeler une autre API en son nom...).

Deux champs optionnels permettent de transmettre cette info au backend.

forwardAccessToken — l'access token vers le backend

Dans le bloc oidc, forwardAccessToken: true demande à Envoy de transmettre l'access token OIDC au backend (dans le header Authorization) :

1  oidc:
2    # ...
3    forwardAccessToken: true

claimToHeaders — un claim dans un header

Dans le bloc jwt, claimToHeaders injecte la valeur d'un claim du token dans un header HTTP transmis au backend :

1  jwt:
2    providers:
3      - name: keycloak
4        # ...
5        claimToHeaders:
6          - claim: groups
7            header: x-user-groups

Le nom du header (x-user-groups) est ici libre : ce n'est ni un standard ni une convention Keycloak. L'app lira alors les groupes dans ce header sans avoir à décoder le JWT elle-même.

Valider le flux avec un backend "echo"

Pour vérifier concrètement ce qu'Envoy injecte (cookie, Authorization, headers custom), on peut s'appuyer sur l'application mendhak/http-https-echo. Avec la variable JWT_HEADER, il décode le JWT d'un header donné et l'ajoute, claims lisibles, dans sa réponse JSON.

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4  name: mysecureapp
 5  namespace: mysecurens
 6spec:
 7  replicas: 1
 8  selector: 
 9    matchLabels:
10      app: mysecureapp
11  template:
12    metadata: 
13      labels:
14        app: mysecureapp
15    spec:
16      containers:
17        - name: echo
18          image: mendhak/http-https-echo
19          env:
20            - name: JWT_HEADER
21              value: "Authorization"   # décode l'access token
22          ports: 
23            - containerPort: 8080
24---
25apiVersion: v1
26kind: Service
27metadata:
28  name: mysecureapp
29  namespace: mysecurens
30spec:
31  selector: 
32    app: mysecureapp
33  ports: 
34    - port: 8080
35      targetPort: 8080

• L'id_token est dans le cookie IdTokenMySecureApp → l'echo l'affiche brut, non décodé (à passer dans jwt.io à la main, ou via jwt decode).
• L'access token n'arrive dans Authorization: Bearer … que si forwardAccessToken: true → là JWT_HEADER=Authorization le décode automatiquement. C'est le cas d'usage idéal pour valider forwardAccessToken.

Une fois authentifié en tant que membre du groupe autorisé — et avec les deux options activées (forwardAccessToken: true, claimToHeaders) — l'echo renvoie ceci :

 1{
 2  "path": "/",
 3  "headers": {
 4    "host": "mysecureapp.gravitek.io",
 5    "x-forwarded-proto": "https",
 6    "x-request-id": "02d9c605-3391-48d7-ba70-9b7f95f0c0c2",
 7    // forwardAccessToken: true → l'access token en Bearer
 8    "authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI…",
 9    // posés par le filtre OIDC : access token + id_token
10    "cookie": "AccessToken-10c7e844=eyJhbGc…; IdTokenMySecureApp=eyJhbGc…",
11    // claimToHeaders : valeur du claim `groups`, encodée en base64
12    "x-user-groups": "WyIvYWRtaW5zIl0="
13  },
14  "method": "GET",
15  // JWT_HEADER=Authorization → l'access token décodé par l'echo
16  "jwt": {
17    "payload": {
18      "iss": "https://sso.gravitek.io/realms/myrealm",
19      "aud": "account",
20      "azp": "mysecureapp",
21      "scope": "openid groups",
22      "groups": [
23        "/admins"
24      ]
25    }
26  }
27}

Les trois mécanismes vus plus haut sont visibles d'un coup d'œil :

• authorization: Bearer … → c'est forwardAccessToken: true qui l'a ajouté ; sans lui, ce header est absent.
• x-user-groups: WyIvYWRtaW5zIl0= → c'est claimToHeaders ; la valeur est le base64 du tableau JSON du claim (echo WyIvYWRtaW5zIl0= | base64 -d → ["/admins"]). Envoy n'envoie pas la valeur brute mais la représentation JSON encodée.
• jwt.payload.groups → l'echo a décodé l'access token (grâce à JWT_HEADER=Authorization) ; on y retrouve groups, c'est exactement le claim sur lequel la règle authorization a statué pour laisser passer la requête.

Le cookie IdTokenMySecureApp, lui, contient l'id_token : c'est lui que le filtre JWT relit (via extractFrom.cookies) pour appliquer l'authorization, indépendamment de ce qui est transmis au backend.

Conclusion

Maintenant, avec une seule SecurityPolicy, on peut gérer l'authn OIDC, l'extraction JWT, l'authorization par claim, colocalisé avec la HTTPRoute. Plus de déploiement oauth2-proxy, plus de conf éparpillée. Plus simple, plus clair, j'aime bien !

Une fois le pattern en place, protéger une nouvelle app par groupe devient simple = un bloc oidc, un bloc jwt, une règle authorization, et go ! 🎉

Rendez-vous bientôt pour un prochain article autour d'Envoy Gateway et les Gateway API !

Ressources

• Envoy Gateway - OIDC : gateway.envoyproxy.io/docs/tasks/security/oidc — inclut le warning sur le matching redirectURL / HTTPRoute
• Envoy Gateway - JWT Authentication : gateway.envoyproxy.io/docs/tasks/security/jwt-authentication
• Envoy Gateway - JWT Claim-Based Authorization : gateway.envoyproxy.io/docs/tasks/security/jwt-claim-authorization — exemples avec StringArray et filtrage par claim

Pour l'exemple, on va imaginer une app mysecureapp dans le namespace mysecurens, qui expose son service mysecureapp sur le port 8443 en HTTPS, avec un certificat auto-signé.

Avant : ingress-nginx & annotations

Côté ingress-nginx, c'était assez direct. Une ressource Ingress avec une seule annotation, et go :

 1apiVersion: networking.k8s.io/v1
 2kind: Ingress
 3metadata:
 4  name: mysecureapp
 5  namespace: mysecurens
 6  annotations:
 7    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
 8    [...]
 9spec:
10  ingressClassName: nginx
11  rules:
12    - host: mysecureapp.gravitek.io
13      http:
14        paths:
15          - path: /
16            pathType: Prefix
17            backend:
18              service:
19                name: mysecureapp
20                port:
21                  number: 8443
22  tls:
23    - hosts:
24        - mysecureapp.gravitek.io
25      secretName: mysecureapp.gravitek.io-tls # Certificat public Let's Encrypt

L'annotation backend-protocol: "HTTPS" est claire, elle indique à nginx de parler en TLS au backend. Et c'est tout. Par défaut, ingress-nginx ne vérifie pas le certificat du backend 🙈. Tant qu'on ne lui demande pas explicitement (proxy-ssl-verify: "on" + proxy-ssl-secret), il chiffre mais ne valide rien.

Après : Gateway API & BackendTLSPolicy

En Gateway API (j'utilise Envoy Gateway, mais le principe est le même côté API), la route HTTP devient une HTTPRoute, et le TLS vers le backend se déclare avec une BackendTLSPolicy :

 1# HTTPRoute
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: HTTPRoute
 4metadata:
 5  name: mysecureapp
 6  namespace: mysecurens
 7spec:
 8  hostnames:
 9    - mysecureapp.gravitek.io
10  parentRefs:
11    - kind: Gateway
12      name: eg # Nom de ma gateway
13      namespace: mysecurens # Pour l'exemple on a la GW dans le même NS que l'appli
14      sectionName: mysecureapp-https # Section de Gateway qui écoute en HTTPS
15  rules:
16    - backendRefs:
17        - kind: Service
18          name: mysecureapp
19          port: 8443
20      matches:
21        - path:
22            type: PathPrefix
23            value: /

 1# BackendTLSPolicy
 2apiVersion: gateway.networking.k8s.io/v1
 3kind: BackendTLSPolicy
 4metadata:
 5  name: mysecureapp-backend-tls
 6  namespace: mysecurens
 7spec:
 8  targetRefs:
 9    - kind: Service
10      name: mysecureapp
11  validation:
12    hostname: mysecureapp.mysecurens.svc.cluster.local
13    caCertificateRefs:
14      - kind: ConfigMap
15        name: internal-ca # on va voir cela après ;)

Côté flux, ça donne :

C'est propre, c'est déclaratif, c'est versionné dans un objet bien identifié... mais 💥, contrairement à nginx, il n'y a pas de mode verify: off. La spec impose soit une caCertificateRefs, soit un wellKnownCACertificates: System. Impossible de faire du SkipVerify (et c'est tant mieux).

Sauf que : mon backend a un certificat auto-signé, donc pas de CA "publique" à pointer. Et il faut bien matérialiser cette CA dans un ConfigMap du namespace mysecurens pour que la BackendTLSPolicy puisse la référencer. Comment faire ça proprement ? 🤔

BackendTLSPolicy : deux modes de validation

Avant d'aller plus loin, un mot sur les options possibles côté Gateway API pour parler en TLS au backend. La spec BackendTLSPolicy définit deux modes de validation, mutuellement exclusifs :

• wellKnownCACertificates: System : le gateway utilise le bundle de CA du système (Let's Encrypt, DigiCert et autres autorités publiques). Si mon backend expose un certificat signé par une CA publique — typiquement un service managé ou un endpoint SaaS — c'est l'option la plus simple : rien à gérer, rien à distribuer.
• caCertificateRefs : le gateway charge la (ou les) CA depuis un ConfigMap que je fournis dans le namespace de la BackendTLSPolicy. C'est le mode obligatoire dès qu'on a une CA privée : certificat auto-signé, PKI maison, etc.

C'est ce deuxième cas qui motive cet article : un service interne avec certificat auto-signé, qu'on veut consommer en TLS validé. Si le backend utilise un certificat public, wellKnownCACertificates: System et c'est plié — pas besoin de trust-manager.

caCertificateRefs : Secret ou ConfigMap ?

Avec Envoy Gateway, on pourrait très bien utiliser un Secret comme caCertificateRefs, et donc éviter en partie la suite de cet article (merci @Shinro pour la remarque, cf issue #2777). Mais c'est un support Implementation-Specific au sens de la spec Gateway API — Envoy Gateway le permet, d'autres implémentations non.

Cependant, ça ne résoudrait pas un problème de rotation de ca.crt, par exemple. Continuons alors la lecture ! 😉

Trois tentatives pour définir la CA dans un ConfigMap

Parmi mes expérimentations, j'ai noté 3 possibilités permettant d'avoir la CA du certificat auto-signé de mon application.

1. La recopie manuelle du ca.crt

La méthode "quick & dirty" : récupérer le ca.crt du Secret source, et le re-créer en ConfigMap à la main :

1$ kubectl -n mysecurens get secret mysecureapp-internal-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
2$ kubectl -n mysecurens create configmap mysecureapp-ca --from-file=ca.crt

Ça marche... jusqu'à la première rotation de la CA : il faut repasser à la main, régénérer, recommiter, rolling-restart. Et si on oublie, c'est BackendTLSPolicy rouge et erreur 503 à la clé. ❌

Cette solution simple ne faisait que décaler le problème pour mon moi futur 😬.

2. Synchro automatique avec Kyverno

Pour automatiser, j'ai pensé à Kyverno avec une GeneratingPolicy qui prend le Secret source et génère le ConfigMap cible :

 1apiVersion: policies.kyverno.io/v1alpha1
 2kind: GeneratingPolicy
 3metadata:
 4  name: sync-ca-to-configmap
 5spec:
 6  matchConstraints:
 7    resourceRules:
 8      - apiGroups: [""]
 9        apiVersions: ["v1"]
10        resources: ["secrets"]
11        operations: ["CREATE", "UPDATE"]
12        resourceNames: ["mysecureapp-internal-tls"]
13  generate:
14    - expression: |
15        [...]

Sur le papier, ça paraît simple : le mode synchronisé était censé garder le ConfigMap aligné sur le Secret à chaque update. En vrai, chaque UPDATE du secret source supprimait le ConfigMap au lieu de le mettre à jour, avant de le recréer. Concrètement : une BackendTLSPolicy qui flappe à chaque renouvellement, donc pire qu'avant. ❌

Étant sur une version de kyverno assez "vieille" (1.15) avec une CR v1alpha1, je suspecte un problème de stabilité / maturité, sur les dernières versions en v1 j'espère que ça devrait aller mieux.

Et donc comme pour le point précédent, ça pourrait le faire pour mon moi du futur qui fera la maj kyverno 😅.

3. trust-manager : le bon outil qui juste marche

Et puis je suis tombé sur trust-manager, l'outil officiel de l'écosystème cert-manager, dont le seul boulot est exactement ce qu'on cherche : prendre une CA en source et la distribuer sous forme de ConfigMap dans les namespaces ciblés, avec sync automatique en cas de rotation.

C'est cette troisième approche qu'on va retenir pour la suite.

La solution : cert-manager + trust-manager

L'idée : émettre tous les certificats internes du cluster avec une CA interne gérée par cert-manager, et distribuer le ca.crt dans les namespaces qui en ont besoin avec trust-manager.

Plutôt qu'une CA par appli (chacune dans son ns, à répliquer cross-namespace), on part sur une CA unique au niveau du cluster, qui signe tous les certificats feuilles internes. C'est un pattern PKI privée classique : une seule racine de confiance pour tout le trafic interne du cluster.

1. Une CA interne avec cert-manager

On bootstrap avec un ClusterIssuer self-signed, qui ne sert qu'à générer la CA racine, puis on déclare un ClusterIssuer qui signera tous les certificats feuilles :

1# ClusterIssuer self-signed
2apiVersion: cert-manager.io/v1
3kind: ClusterIssuer
4metadata:
5  name: selfsigned
6spec:
7  selfSigned: {}

 1# CA Interne
 2apiVersion: cert-manager.io/v1
 3kind: Certificate
 4metadata:
 5  name: internal-ca
 6  namespace: cert-manager
 7spec:
 8  isCA: true # On définit comme CA interne / privée
 9  commonName: internal-ca
10  secretName: internal-ca-tls
11  duration: 87600h0m0s # 10 ans
12  renewBefore: 2160h0m0s # 90 jours
13  privateKey:
14    algorithm: ECDSA
15    size: 256
16    rotationPolicy: Always
17  issuerRef:
18    name: selfsigned
19    kind: ClusterIssuer

1# ClusterIssuer utilisant la CA interne
2apiVersion: cert-manager.io/v1
3kind: ClusterIssuer
4metadata:
5  name: internal-ca-issuer
6spec:
7  ca:
8    secretName: internal-ca-tls

À partir de là, internal-ca-issuer peut signer le certificat feuille de mysecureapp (et de tous les autres services internes du cluster). Côté mysecureapp, on remplace donc le certificat auto-signé par un certificat signé par cette CA interne :

 1apiVersion: cert-manager.io/v1
 2kind: Certificate
 3metadata:
 4  name: mysecureapp-internal-tls
 5  namespace: mysecurens
 6spec:
 7  secretName: mysecureapp-internal-tls
 8  duration: 2160h0m0s # 90 jours
 9  renewBefore: 360h0m0s # 15 jours
10  privateKey:
11    algorithm: ECDSA
12    size: 256
13    rotationPolicy: Always
14  dnsNames:
15    # Nom DNS interne pour joindre le service
16    - mysecureapp.mysecurens.svc.cluster.local
17    - mysecureapp.mysecurens.svc
18    - mysecureapp
19  issuerRef:
20    name: internal-ca-issuer
21    kind: ClusterIssuer

⚠️ Point d'attention : le dnsNames doit contenir le hostname validé par la BackendTLSPolicy (ici mysecureapp.mysecurens.svc.cluster.local). Sinon Envoy rejette le certificat avec une erreur de SAN, même si la chaîne de confiance est parfaitement valide.

2. Distribuer le ca.crt avec trust-manager

trust-manager s'installe via Helm, dans le même namespace que cert-manager par défaut :

1$ helm upgrade --install trust-manager jetstack/trust-manager \
2    --namespace cert-manager \
3    --wait

⚠️ Remarque : trust-manager lit ses sources dans un seul namespace, défini par --app.trust.namespace (par défaut cert-manager, donc pas besoin de le spécifier). C'est pour ça qu'on a émis internal-ca directement dans cert-manager plutôt que de chercher à répliquer le secret depuis ailleurs.

Une fois trust-manager en place, on déclare un Bundle : il prend une source (notre secret internal-ca-tls) et synchronise un ConfigMap cible dans tous les namespaces qui matchent un selector :

 1apiVersion: trust.cert-manager.io/v1alpha1
 2kind: Bundle
 3metadata:
 4  name: internal-ca
 5spec:
 6  sources:
 7    - secret:
 8        name: internal-ca-tls
 9        key: ca.crt
10  target:
11    configMap:
12      key: ca.crt
13    namespaceSelector:
14      matchLabels:
15        trust-ca: "true"

Pour qu'un namespace récupère la CA, il suffit de le tagger :

1$ kubectl label namespace mysecurens trust-ca=true

Et c'est tout. Le ConfigMap internal-ca (clé ca.crt) apparaît automatiquement dans mysecurens :

1$ kubectl -n mysecurens get cm internal-ca
2NAME          DATA   AGE
3internal-ca   1      42m

Ce ConfigMap est ensuite référencé par la BackendTLSPolicy (cf. plus haut). Le jour où la CA tourne, trust-manager propage le nouveau ca.crt dans tous les namespaces consommateurs, sans rien à toucher.

3. Bonus : un ConfigMap qui ne bouge pas, et c'est tant mieux 🎉

Un effet de bord plutôt sympa de cette archi : tant que la CA ne tourne pas (soit dans 10 ans 😅), le ConfigMap internal-ca est strictement immuable. Les certificats feuilles de chaque appli, eux, peuvent tourner toutes les 90 jours sans que la BackendTLSPolicy ni le ConfigMap ne bougent — la chaîne de confiance reste valide tant que la racine ne change pas.

Conclusion

Avec la migration Gateway API, et malgré la perte du SkipVerify, on y gagne au final sur plusieurs plans :

• 🔒 Du TLS de bout en bout, avec validation de la chaîne, pas du verify: off qui traîne dans une annotation
• 🧹 Une CA centralisée, des certificats feuilles auto-renouvelés, et un ca.crt qui se diffuse tout seul
• 📦 Tout en déclaratif Kubernetes, versionné, sans vieilles annotations 🙈 (on prend goût à ne plus gérer d'annotations tordues)

Le ticket d'entrée est juste un poil plus élevé qu'une annotation nginx, mais le résultat est nettement plus solide. Et une fois la PKI interne en place, ajouter un nouveau backend HTTPS interne devient très simple : un Certificate, un label sur le namespace, une BackendTLSPolicy, et zou !

Ressources

• Gateway API - BackendTLSPolicy : gateway-api.sigs.k8s.io/api-types/backendtlspolicy
• cert-manager : cert-manager.io
• trust-manager : cert-manager.io/docs/trust/trust-manager
• Envoy Gateway : gateway.envoyproxy.io

Si vous souhaitez une introduction plus complète vous pourrez bientôt voir la vidéo youtube, sinon les slides sont dispos ici.

Le problème : jongler entre contextes

Je suis consultant Cloud Native Infra, et je gère au quotidien plus d'une dizaine de projets avec chacun leurs clusters Kubernetes en dev et en prod, hébergés sur des zones différentes. Chaque projet a ses propres versions d'outils, ses variables d'environnement, ses secrets, ses scripts...

Au quotidien, ça donne grosso modo ça :

 1## Projet A - Dev - Helium ☕
 2$ java --version  # openjdk 25.x
 3$ python --version  # 3.14.x
 4$ kubectl version  # v1.35.x
 5$ export KUBECONFIG=~/.kube/helium
 6$ export ANSIBLE_INVENTORY=inventories/helium/dev
 7
 8## Projet B - Prod - Lithium ⚓
 9$ java --version  # openjdk 17.x
10$ python --version  # 3.11.x
11$ kubectl version  # v1.33.x
12$ export KUBECONFIG=~/.kube/lithium
13$ export ANSIBLE_INVENTORY=inventories/lithium/prod

Concrètement :

• 🔄 Versions d'outils différentes selon les projets
• 🌍 Variables d'environnement spécifiques à chaque contexte
• 📜 Scripts custom à maintenir
• ⚠️ Oublier de switcher = bugs, erreurs, frustration (😱 le terraform plan sur le mauvais projet qui demande de redéployer un cluster, c'est arrivé ^^)

Avant, je faisais tout cela avec un mix d'outils :

Ça marchait, mais c'était perfectible. Et puis j'ai (re)découvert Mise, un outil créé par @jdx en 2023, écrit en Rust (donc vachement rapide), qui agrège dans un seul binaire asdf + direnv + un task runner, avec une activation automatique par répertoire, le tout configurable simplement avec des fichiers au format TOML.

Pour l'installation, c'est un simple curl https://mise.run | sh puis eval "$(mise activate zsh)" dans le shell. Je ne vais pas refaire la doc ici, vous trouverez tout sur mise.jdx.dev, je préfère vous montrer mon vrai setup.

Mon setup : Un dizaine de projets & clusters Kubernetes

J'ai une arborescence du genre :

 1projects-kubernetes-clusters/
 2├── calcium/              # Projet A
 3│   ├── calcium-dev/
 4│   └── calcium-prod/
 5├── lithium/              # Projet B
 6│   ├── lithium-dev/
 7│   └── lithium-prod/
 8├── helium/               # Projet C
 9│   ├── helium-dev/
10│   │   └── ansible/
11│   └── helium-prod/
12└── ...                   # 10+ projets identiques

Et la magie de Mise, c'est que la configuration est hiérarchique sur 3 niveaux :

1. Global (~/.config/mise/config.toml) : ce qui s'applique partout (proxy WireGuard par exemple)
2. Projet parent (calcium/mise.toml) : variables OVH, endpoints, project name
3. Environnement spécifique (calcium/calcium-dev/mise.toml) : nom du cluster, kubeconfig

Niveau global

Au niveau de mon home, j'ai juste de quoi sourcer mon proxy WireGuard quand je suis chez un client :

1# ~/.config/mise.toml
2[env]
3# WireGuard Proxy
4_.source = ["~/.config/mise/proxy.sh"]

Niveau projet parent

Au niveau du projet parent, je définis les variables communes à tous les environnements (dev + prod), et j'active fnox pour les secrets :

 1# calcium/mise.toml
 2[env]
 3OS_REGION_NAME = "GRA7"
 4OVH_ENDPOINT = "ovh-eu"
 5OS_AUTH_URL = "https://auth.cloud.ovh.net/v3/"
 6
 7VAULT_ADDR = "https://vault.gravitek.io"
 8VAULT_OVH_PROJECT = "calcium"
 9TF_VAR_project_name = "{{env.VAULT_OVH_PROJECT}}"
10
11# fnox pour les secrets
12_.fnox-env = { tools = true }
13
14[plugins]
15fnox-env = "https://github.com/jdx/mise-env-fnox"

Les secrets sont gérés via fnox, l'outil compagnon de Mise. Chez moi, j'utilise principalement HashiCorp Vault pour ce qui est partagé. La conf tient dans un fnox.toml au niveau du projet :

 1# calcium/fnox.toml
 2[providers.vault-ovh-project-api]
 3type = "vault"
 4address = "https://vault.gravitek.io"
 5path = "secret/myorg/ovh/calcium"
 6
 7[providers.vault-ovh-project-openstack]
 8type = "vault"
 9address = "https://vault.gravitek.io"
10path = "secret/myorg/ovh/calcium/openstack"
11
12[secrets]
13OVH_APPLICATION_KEY = { provider = "vault-ovh-project-api", value = "API_CREDENTIALS/OVH_APPLICATION_KEY" }
14OVH_APPLICATION_SECRET = { provider = "vault-ovh-project-api", value = "API_CREDENTIALS/OVH_APPLICATION_SECRET" }
15OS_USERNAME = { provider = "vault-ovh-project-openstack", value = "admin/OS_USERNAME" }
16OS_PASSWORD = { provider = "vault-ovh-project-openstack", value = "admin/OS_PASSWORD" }

Et pour le VAULT_TOKEN lui-même, je le stocke dans le Keychain macOS, ce qui m'évite de l'avoir en clair quelque part :

1[providers.keychain]
2type = "keychain"
3service = "fnox"
4
5[secrets]
6VAULT_TOKEN = { provider = "keychain", value = "VAULT_TOKEN" }

Niveau environnement spécifique

Au niveau de l'environnement spécifique, j'ajoute le nom du cluster, l'URL, et surtout un hook qui auto-switch le contexte kubectl à l'entrée du répertoire :

 1# calcium/calcium-dev/mise.toml
 2[env]
 3CLUSTER_NAME = "calcium-dev"
 4CLUSTER_URL = "https://xxx.k8s.ovh.net"
 5
 6[hooks]   # mode expérimental
 7enter = """
 8if [ -n "$CLUSTER_NAME" ] && kubectl config get-contexts "$CLUSTER_NAME" &>/dev/null; then
 9  kubectl config use-context "$CLUSTER_NAME"
10fi
11"""

Plus de kubectx à la main, plus de risque de terraform plan sur le mauvais cluster 🙏.

Bonus : sous-répertoire Ansible avec venv Python

Pour mes répertoires Ansible, j'ajoute encore un niveau de configuration avec un venv Python dédié grâce à uv, et des tâches pour installer les dépendances :

 1# helium/helium-dev/ansible/mise.toml
 2[tools]
 3python = "3.14"
 4
 5[env]
 6_.python.venv = { path = ".venv", create = true, python = "3.14", uv_create_args = ['--seed'] }
 7
 8[tasks.install]
 9description = "Installer les dépendances et les rôles Ansible"
10run = ["uv pip install ansible ansible-lint python-gitlab",
11       "ansible-galaxy install -r roles/requirements.yml -p roles --force"]

Le résultat au quotidien

Concrètement, en switchant de répertoire :

 1$ cd projects/calcium/calcium-dev/
 2🔑 [MISE] Environnement CALCIUM détecté.
 3$ echo $PROJECT_NAME
 4calcium
 5$ kubectl config current-context
 6calcium-dev
 7$ echo $OVH_APPLICATION_SECRET
 8s3cr3t_p4ssw0rd      # résolu depuis Vault automatiquement
 9
10$ cd ../../lithium/lithium-prod/
11🔑 [MISE] Environnement LITHIUM détecté.
12$ echo $PROJECT_NAME
13lithium
14$ kubectl config current-context
15lithium-prod

Je cd dans un répertoire, tout est automatiquement chargé : versions d'outils, variables d'env, secrets résolus depuis Vault ou le Keychain, contexte kubectl switché. Zéro friction, zéro oubli.

Au final, Mise a remplacé chez moi : asdf, direnv, mes scripts shell custom, et même les virtualenvs python. C'est devenu le point d'entrée de mes projets.

Ressources

• Documentation : mise.jdx.dev & fnox.jdx.dev
• GitHub : jdx/mise & jdx/fnox
• Slides Devoxx France 2026 : presentations.verchere.fr/Mise_Devoxxfr_2026
• Dépôt de démo : github.com/gravitek-io/mise-demo
• Blog Julien Wittouck : Adieu direnv, bonjour mise
• Blog Stéphane Robert : Mise

Préambule

Dans cet article on va causer réseau, avec des IPs pour joindre les divers nodes, qu'on devra définir. Voici un récapitulatif pour mon setup :

Aussi, vous trouverez les scripts pour automatiser tout ce que je détaille dans l'article ici, utilisé pour ma conférence sur ArgoCD multi-clusters : dépôt git.

On aura besoin de la cli talosctl. Pour information je suis en v1.11.5 au moment de la publication de l'article :

1$ talosctl version  
2Client:
3        Tag:         v1.11.5
4        SHA:         undefined
5        Built:       2025-11-06T12:35:51Z
6        Go version:  go1.25.4
7        OS/Arch:     darwin/arm64

Création de plusieurs clusters Talos

Commençons doucement : je veux créer deux clusters Talos locaux qui doivent communiquer entre eux pour tester ArgoCD en mode multi-clusters. Docker permet de créer 1 cluster Kind avec Docker Desktop, mais ici j'en ai besoin de plusieurs, autant m'amuser avec Talos.

La création de clusters est très simple si l'on suit la documentation. Chaque cluster devra alors avoir son propre nom et propre CIDR :

• Nom : cluster-1
• CIDR : 10.5.10.0/24
• Version : v1.33.4

 1$ talosctl cluster create --name cluster-1 --kubernetes-version v1.33.4 --cidr 10.5.10.0/24
 2validating CIDR and reserving IPs
 3generating PKI and tokens
 4creating state directory in "/path/to/talos/clusters/cluster-1"
 5creating network cluster-1
 6creating controlplane nodes
 7creating worker nodes
 8waiting for API
 9bootstrapping cluster
10waiting for etcd to be healthy: OK
11waiting for etcd members to be consistent across nodes: OK
12waiting for etcd members to be control plane nodes: OK
13waiting for apid to be ready: OK
14waiting for [...]: OK
15waiting for coredns to report ready: OK
16waiting for all k8s nodes to report schedulable: OK
17
18merging kubeconfig into "/path/to/kubeconfig"
19PROVISIONER           docker
20NAME                  cluster-1
21NETWORK NAME          cluster-1
22NETWORK CIDR          10.5.10.0/24
23NETWORK GATEWAY       10.5.10.1
24NETWORK MTU           1500
25KUBERNETES ENDPOINT   https://127.0.0.1:62233
26
27NODES:
28
29NAME                        TYPE           IP          CPU    RAM      DISK
30/cluster-1-controlplane-1   controlplane   10.5.10.2   2.00   2.1 GB   -
31/cluster-1-worker-1         worker         10.5.10.3   2.00   2.1 GB   -

1$ talosctl cluster create --name cluster-2 --kubernetes-version v1.33.4 --cidr 10.5.20.0/24
2[...]

Après quelques minutes, j'ai mes deux clusters opérationnels :

1$ kubectl config get-contexts
2CURRENT   NAME              CLUSTER     AUTHINFO          NAMESPACE
3          admin@cluster-1   cluster-1   admin@cluster-1   default
4*         admin@cluster-2   cluster-2   admin@cluster-2   default
5
6$ NAME                       STATUS   ROLES           AGE     VERSION
7cluster-1-controlplane-1   Ready    control-plane   4m54s   v1.33.4
8cluster-1-worker-1         Ready    <none>          4m54s   v1.33.4

Parfait ! Maintenant, essayons de faire communiquer les deux clusters.

Visibilité inter-clusters

Lorsqu'on a créé les clusters, on a défini pour chacun un CIDR : 10.5.10.0/24 et 10.5.20.0/24, ce qui correspond à 2 networks Docker :

 1$ docker network ls
 2NETWORK ID     NAME                    DRIVER    SCOPE
 3f2c1d59b61f2   cluster-1               bridge    local
 4c31015d9e6d3   cluster-2               bridge    local
 5
 6$ docker network inspect cluster-1 -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}'
 710.5.10.0/24
 8
 9$ docker network inspect cluster-2 -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}'
1010.5.20.0/24

Le problème est que chaque cluster a son propre réseau Docker isolé. Les conteneurs du cluster-1 ne peuvent pas joindre le réseau du cluster-2.

Création d'un réseau partagé

Pour permettre la communication entre ces 2 clusters, il faut créer un réseau Docker commun et y connecter les nœuds de chaque cluster.

Créons d'abord un réseau partagé talos-shared :

1$ docker network create --driver bridge --subnet=172.30.0.0/24 talos-shared
23e1f0e92331f7078ee72cd0cfa99a01bf35c9f012efc52e34b10fc3563e3d795
3
4$ docker network ls
5f2c1d59b61f2   cluster-1               bridge    local
6c31015d9e6d3   cluster-2               bridge    local
73e1f0e92331f   talos-shared            bridge    local

Maintenant, connectons les nœuds du cluster-1 à ce réseau :

1$ docker network connect --ip 172.30.0.11 talos-shared cluster-1-controlplane-1
2$ docker network connect --ip 172.30.0.12 talos-shared cluster-1-worker-1

Et ceux du cluster-2 :

1$ docker network connect --ip 172.30.0.21 talos-shared cluster-2-controlplane-1
2$ docker network connect --ip 172.30.0.22 talos-shared cluster-2-worker-1

Testons la connectivité réseau avec kubectl debug depuis le cluster 1 vers le 2 :

1kubectl --context admin@cluster-1 debug -n kube-system -it --image alpine node/cluster-1-worker-1 -- ping -c 2 172.30.0.21
264 bytes from 172.30.0.21: seq=1 ttl=64 time=0.529 ms
3
4--- 172.30.0.21 ping statistics ---
52 packets transmitted, 2 packets received, 0% packet loss
6round-trip min/avg/max = 0.092/0.310/0.529 ms

Excellent ! Les nœuds se voient maintenant.

Maintenant, tentons de nous connecter à l'API server du cluster-2 depuis le cluster-1. On va récupérer son IP :

1$ kubectl --context admin@cluster-2 config view --minify -o jsonpath='{.clusters[0].cluster.server}'
2https://127.0.0.1:62406

Bon, ça démarre mal... 127.0.0.1 est l'IP locale, pas sûr que ça fonctionne. En effet, lors de la création des clusters Talos + Docker, on passe par le host local pour accéder à l'API Server. Bon, on va quand même tenter avec l'IP du réseau partagé 172.30.0.21 !

Accédons à cette IP depuis un pod du cluster-1 sur le port par défaut de l'api-server, port 6443 :

 1kubectl --context admin@cluster-1 debug -n kube-system -it --image alpine node/cluster-1-worker-1 -- /bin/sh
 2/ # apk add curl
 3/ # curl -k https://172.30.0.21:6443
 4{
 5  "kind": "Status",
 6  "apiVersion": "v1",
 7  "metadata": {},
 8  "status": "Failure",
 9  "message": "Unauthorized",
10  "reason": "Unauthorized",
11  "code": 401
12}/ #

Ok, on arrive à joindre l'API Server du cluster-2 depuis le cluster-1, on a une erreur 401 mais au moins ça répond !

Maintenant allons plus loin avec une commande kubectl. On édite le kubeconfig pour que le serveur soit bien server: https://172.30.0.21:6443, puis on exécute une commande depuis un conteneur dans le même sous-réseau pour valider l'accès à l'api-server :

1$ docker run --network talos-shared -v ${PWD}:/tmp alpine/k8s:1.33.4 kubectl --kubeconfig=/tmp/kubeconfig --context admin@cluster-2 get nodes
2pod:/# kubectl get nodes               
3NAME                       STATUS   ROLES           AGE   VERSION
4cluster-2-controlplane-1   Ready    control-plane   73m   v1.33.4
5cluster-2-worker-1         Ready    <none>          74m   v1.33.4

Ok, ça marche !

Bon 🤔... quand j'avais testé pour ma démo avec ArgoCD, j'avais une erreur sur les Subject Alternative Names (certSANs), car Talos a généré un certificat seulement avec les 2 IPs initiales : celle en 10.5.20.2 et 127.0.0.1. Si vous avez une erreur d'IP, alors on va recréer les clusters avec les bonnes SANs.

Validité du certificat de l'API Server

Le certificat de l'API server de Talos ne contient que les IPs du réseau dédié (10.5.20.2) et localhost. Il faut ajouter l'IP du réseau partagé (172.30.0.21 par exemple pour le cluster-2) dans les Subject Alternative Names (SANs) du certificat.

On voit en effet par défaut qu'elle ne fait pas partie des certSANs :

1$ talosctl --context cluster-1 -n 127.0.0.1 get mc -o yaml | yq '.spec | fromyaml | .cluster.apiServer.certSANs'
2- 10.5.20.2
3- 127.0.0.1

On va alors recréer les clusters avec un patch de configuration :

 1# Suppression des clusters existants
 2$ talosctl cluster destroy --name cluster-1
 3$ talosctl cluster destroy --name cluster-2
 4
 5# Recréation avec patch des certSANs
 6$ talosctl cluster create \
 7    --name cluster-1 \
 8    --kubernetes-version v1.33.4 \
 9    --cidr 10.5.10.0/24 \
10    --config-patch-control-plane '[{"op": "replace", "path": "/cluster/apiServer/certSANs", "value": ["172.30.0.11", "10.5.10.2", "127.0.0.1"]}]'
11
12$ talosctl cluster create \
13    --name cluster-2 \
14    --kubernetes-version v1.33.4 \
15    --cidr 10.5.20.0/24 \
16    --config-patch-control-plane '[{"op": "replace", "path": "/cluster/apiServer/certSANs", "value": ["172.30.0.21", "10.5.20.2", "127.0.0.1"]}]'

On reconnecte ensuite les nœuds au réseau partagé :

1$ docker network connect --ip 172.30.0.11 talos-shared cluster-1-controlplane-1
2$ docker network connect --ip 172.30.0.12 talos-shared cluster-1-worker-1
3$ docker network connect --ip 172.30.0.21 talos-shared cluster-2-controlplane-1
4$ docker network connect --ip 172.30.0.22 talos-shared cluster-2-worker-1

Vérifions le certSANs :

1$ talosctl --context cluster-1 -n 127.0.0.1 get mc -o yaml | yq '.spec | fromyaml | .cluster.apiServer.certSANs'
2- 172.30.0.11
3- 10.5.10.2
4- 127.0.0.1

On a maintenant un certSANs valide, des nodes accessibles depuis n'importe quel autre node partageant le réseau, impeccable !

Upgrade Kubernetes inside Docker

Maintenant que j'ai mes clusters locaux qui peuvent discuter entre eux, je souhaite les mettre à jour. La documentation dit que non, mais je suis joueur !

1$ talosctl --context cluster-1 -n 127.0.0.1 upgrade-k8s --to 1.34.0
2error detecting the lowest Kubernetes version Get "https://10.5.10.2:6443/api/v1/namespaces/kube-system/pods": dial tcp 10.5.10.2:6443: i/o timeout

Ah ! En effet, ça ne fonctionne pas... Le problème est que talosctl essaie de communiquer avec le control plane via 10.5.10.2:6443, mais depuis l'hôte Docker, on doit joindre le control plane du conteneur via localhost (ce qui est défini dans notre KUBECONFIG).

Si on regarde la configuration de la machine, l'endpoint du control plane pointe vers https://10.5.10.2:6443 :

1$ talosctl -n 127.0.0.1 get mc -o yaml | yq '.spec | fromyaml | .cluster.controlPlane.endpoint'
2https://10.5.10.2:6443

Patcher temporairement l'endpoint

Pour faire l'upgrade, on va temporairement changer l'endpoint du control plane pour qu'il pointe vers l'IP du réseau local, faire l'upgrade, puis remettre la configuration d'origine. Voici comment faire pour le cluster-1 :

1. Récupérer l'URL du serveur depuis le kubeconfig

   1$ SERVER_URL=$(kubectl config view --context admin@cluster-1 --minify \
   2    -o jsonpath='{.clusters[0].cluster.server}')
   3$ echo $SERVER_URL
   4https://127.0.0.1:51189
   

2. Sauvegarder l'ancien endpoint sur le réseau dédié au cluster (10.5.10.2)

   1$ OLD_URL=$(talosctl --context cluster-1 -n 127.0.0.1 get mc -o yaml | \
   2    yq '.spec | fromyaml | .cluster.controlPlane.endpoint' | grep '^https' | head -n1)
   3$ echo $OLD_URL
   4https://10.5.10.2:6443
   

3. Patcher l'endpoint pour utiliser l'IP du réseau localhost avec $SERVER_URL

   1$ talosctl --context cluster-1 -n 127.0.0.1 patch mc \
   2    --patch '[{"op": "replace", "path": "/cluster/controlPlane/endpoint", "value": "https://127.0.0.1:51189"}]'
   3patched MachineConfigs.config.talos.dev/v1alpha1 at the node 127.0.0.1
   4Applied configuration without a reboot
   

4. Lancer l'upgrade Kubernetes depuis notre laptop !

    1$ talosctl --context cluster-1 -n 127.0.0.1 upgrade-k8s --to 1.34.0
    2automatically detected the lowest Kubernetes version 1.33.4
    3discovered controlplane nodes ["10.5.20.2"]
    4discovered worker nodes ["10.5.20.3"]
    5> "10.5.20.2": Talos version 1.11.5 is compatible with Kubernetes version 1.34.0
    6> "10.5.20.3": Talos version 1.11.5 is compatible with Kubernetes version 1.34.0
    7checking for removed Kubernetes component flags
    8checking for removed Kubernetes API resource versions
    9> "10.5.20.2": pre-pulling registry.k8s.io/kube-apiserver:v1.34.0
   10> "10.5.20.2": pre-pulling registry.k8s.io/kube-controller-manager:v1.34.0
   11> "10.5.20.2": pre-pulling registry.k8s.io/kube-scheduler:v1.34.0
   12> "10.5.20.2": pre-pulling ghcr.io/siderolabs/kubelet:v1.34.0
   13> "10.5.20.3": pre-pulling ghcr.io/siderolabs/kubelet:v1.34.0
   14updating "kube-apiserver" to version "1.34.0"
   15> "10.5.20.2": starting update
   16[...]
   

5. Une fois terminé, remettre l'endpoint d'origine ($OLD_URL)

   1$ talosctl --context cluster-1 -n 127.0.0.1 patch mc \
   2    --patch '[{"op": "replace", "path": "/cluster/controlPlane/endpoint", "value": "https://10.5.10.2:6443"}]'
   

6. Redémarrer les conteneurs pour appliquer la configuration

   1$ docker container restart cluster-1-controlplane-1 cluster-1-worker-1
   

Vérifions que l'upgrade a bien fonctionné :

1$ kubectl --context admin@cluster-1 get nodes
2NAME                       STATUS     ROLES           AGE   VERSION
3cluster-1-controlplane-1   Ready      control-plane   18m   v1.34.0
4cluster-1-worker-1         Ready      <none>          18m   v1.34.0

Parfait ! L'upgrade Kubernetes a réussi 🎉, même si la doc officielle nous dit que c'est impossible 😜. Le redémarrage des conteneurs permet de s'assurer que la configuration d'origine (avec l'endpoint localhost) est bien appliquée.

Conclusion

Créer plusieurs clusters Talos locaux avec Docker est simple, mais permettre leur communication nécessite quelques ajustements :

1. Créer un réseau Docker partagé pour que les nœuds puissent communiquer
2. Patcher les certSANs lors de la création pour inclure l'IP du réseau partagé dans le certificat TLS
3. Patcher temporairement le controlPlane endpoint lors des upgrades Kubernetes pour utiliser l'IP du host

Avec cette approche, on peut s'amuser à gérer tout plein de clusters localement avec Docker, faut-il encore avoir une machine qui supporte autant de nodes 🤯 !

Ressources

Quelques ressources utiles pour aller plus loin :

• Documentation officielle Talos
• Talos Docker Mode
• Machine Config Patches
• ArgoCD Multi-Clusters
• Scripts utilisés pour la démo ArgoCD

GenAI

Je me suis aidé de Claude Code pour rédiger l'article, même si au final j'ai ré-écrit plus de 80% de l'article après beaucoup de discussions pour valider les commandes et corriger ce que je voulais vraiment présenter. Il m'a été très utile cependant pour la création des images SVG.

J'ai cherché alors comment revenir sur du Bluetooth LE (Low Energy). Voici un court article sur le sujet.

Tout d'abord, j'utilise Home Assistant depuis quelques années, mais je n'ai pas grand chose dessus. Je l'utilise principalement pour centraliser le suivi de température de mon logement. Pour cela, j'ai opté pour des thermomètres Xiaomi Mijia LYWSD03MMC, avec un très bon rapport qualité/prix, facile à utiliser & flasher pour l'intégrer dans Home Assistant.

J'avais d'abord paramétré les thermomètres avec le protocole Xiaomi BLE, puis basculé certains en Zigbee grâce notamment au firmware z03mmc. Vous trouverez suffisamment de tutos sur Internet si vous souhaitez basculer en zigbee.

Cependant, dans l'article de Denis il parle de BTHome v2, option que je n'avais pas avant (seulement Xiaomi BLE). J'ai donc décidé de tout migré sur ce protocole qui me semble plus standard et mieux supporté.

Ci-après vous trouverez alors la procédure pour revenir de Zigbee à Bluetooth BLE, moins courrant que l'inverse 🙂

Home Assistant ZHA & OTA

Mon setup utilise Zigbee Home Automation, pour contrôler mes équipements Zigbee, et donc certains de mes thermomètres jusqu'à présent. J'ai pu voir d'autres setups utilisant du MQTT avec Zigbee2MQTT & Mosquito, ce n'est pas mon cas.

ZHA toolkit

Pour pouvoir flasher à nouveau les devices, il va falloir alors que je passe par de l'OTA (over-the-air). ZHA le supporte nativement. Cependant, pour accélérer le processus, on peut installer ZHA Toolkit :

1. Installer Home Assistant Community Store
2. Installer ZHA Toolkit

Je ne sais pas si cela est vraiment utile, mais "chezmoiçamarche".

Settings pour OTA

On va maintenant définir dans ZHA où le thermomètre devra aller récupérer le firmware. Une longue liste est disponible sur le dépôt GitHub de pvvx.

On édite le fichier /homeassitant/configuration.yaml (peut dépendre de votre installation) pour :

1. Activer ZHA Toolkit
2. Spécifier l'URL de la liste des firmwares à récupérer (pour moi : index_v55.json du dépôt GIT)

1zha_toolkit:
2
3zha:
4  zigpy_config:
5    ota:
6      enabled: true
7      z2m_remote_index: https://raw.githubusercontent.com/pvvx/ATC_MiThermometer/ef4b5a713d16acfe3f3183d72b7706c9fc697c86/zigbee_ota/index_v55.json

Puis on redémarre HomeAssistant pour la prise en compte.

Flash

Tout est prêt, reste maintenant à flasher ! 2 options possibles, soit vous forcez l'OTA avec la notification zha_toolkit, soit vous attendez...

Pour "trigger" un OTA, on va dans les "Outils de développement", puis "Actions", on sélectionne zha_toolkit.ota_notify et on choisit le thermomètre que l'on souhaite mettre à jour :

Après quelques instants, HomeAssitant propose une mise à jour !

Note: on voit ici un "Entity not found", c'est parce que le screenshot a été pris après que j'ai supprimé le device, ne pas en tenir compte.

On lance l'upgrade, et on attend que ça se termine.

Configuration Bluetooth

A partir de ce moment, on peut suivre la procédure de Denis sur son blog, en utilisant le flasher en ligne TelinkMiFlasher.

Intégration Home Assistant

Après la reconfiguration, le device sera détecté par HomeAssistant, reste plus qu'à le rajouter !

Suppression & Historique

Attention (c'est bien de lire jusqu'ici), si vous souhaitez conserver l'historique des températures, humidité & co, pensez à bien noter les identités de l'ancien device zigbee avant de le supprimer, et modifiez celles du nouveau device, pour mon cas :

• temperature_humidity_sensor_1bbb_battery
• temperature_humidity_sensor_1bbb_humidity
• temperature_humidity_sensor_1bbb_temperature
• temperature_humidity_sensor_1bbb_voltage

Sources

Comme je disais en début d'article, beaucoup de ressources pour basculer de bluetooth à zigbee, mais peu pour l'inverse. Ce qui m'a permis d'y arriver est surtout ce commentaire GitHub :

• https://github.com/pvvx/ZigbeeTLc/issues/151#issuecomment-2645922817

Maintenant vous pouvez utiliser correctement vos thermomètres en Bluetooth BLE !

Et tant qu'à migrer, pourquoi ne pas changer un peu de theme du blog ? Ah, vous pensiez à autre chose ? Désolé de vous décevoir 😄

En effet, le thème utilisé jusqu'à présent était hugo-clarity, basé sur le design system Clarity de VMware. Il était alors tant d'aller voir ailleurs... Après quelques recherches, j'ai choisi simplement un des thèmes les plus connus Hugo : PaperMod. Je recherchais quelque chose de simple et épuré, bien supporté. Et ce thème correspond à tous mes critères, donc feu !

Changement du thème

Pour changer de thème, quelques adaptations à faire, mais la doc est assez simple à suivre :

1. Installation du thème à coup de git submodule
2. Modification des pages pour mieux intégrer les images de cover (thumbnail vers cover)
3. Gestion de la table des matières
4. Gestion d'asciinema

Exemple de changements :

 1diff --git a/content/posts/2021/2021-09-09-marp-gitpod.md b/content/posts/2021/2021-09-09-marp-gitpod.md
 2index a74584f..22cd983 100644
 3--- a/content/posts/2021/2021-09-09-marp-gitpod.md
 4+++ b/content/posts/2021/2021-09-09-marp-gitpod.md
 5@@ -1,14 +1,16 @@
 6 ---
 7 title: "Créer des slides depuis n'importe où avec Marp, GitLab Pages et Gitpod"
 8 date: 2021-09-09T12:00:00Z
 9-thumbnail: /2021/09/2021-09-09-marp.png
10+cover:
11+  image: /2021/09/2021-09-09-marp.png
12+  alt: "Logo Marp - outil de création de présentations en Markdown"
13+  relative: false
14 categories:
15   - Divers
16 tags:
17   - GitLab
18   - Markdown
19 description: Créer des slides depuis n'importe où avec Marp, GitLab Pages et Gitpod.
20-toc: true

Améliorations

Basculer de thème m'a permis de corriger quelques trucs qui ne fonctionnaient pas avant, ou ne me convenaient pas :

• L'affichage des tags / catégories & co dont je me fiche, je voulais quelque chose de minimaliste
• Mise en place des permalinks plus propres (déso pour les flux RSS, j'ai l'impression que ça a regénéré de nouveaux articles)
• Nettoyage des catégories et tags
• La recherche sur les articles ici

Le design, merci Claude

Tant qu'a changer, autant faire les choses jusqu'au bout, j'ai demandé à Claude de me faire un css sur mesure, aux couleurs de ma société Gravitek.

Après quelques heures de discussions, d'essais, j'arrive à un résultat pas trop mal :

• Couleurs qui me plaisent, avec theme ligth/dark
• Gestion des images / code correct
• Gestion du format mobile

Au départ c'était mal barré !

Bon, Claude est gentil par contre il est très verbeux, la CSS custom fait pas moins de 1000 lignes ! Si vous avez lu jusque là, que vous êtes experts CSS et que vous voulez améliorer ça, n'hésitez pas à faire une Merge Request 😇

Egalement, si vous trouvez des bugs d'affichage n'hésitez pas à m'en faire part !

La suite

Est-ce qu'avec ce nouveau site je vais écrire de nouveaux articles ? Probable ! On verra ces prochaines semaines ! 😉