2026 — Runbook OpenClaw Gateway sur Kubernetes : déploiement et recette — versions figées, quotas Resource, bind=lan, port-forward et rollback OOM/NotReady typiques (FAQ + comparaison Mac physique distant nu)
Plateforme et SRE qui livrent OpenClaw Gateway sur Kubernetes bloquent souvent la recette sur la dérive d'image, les sondes et adresses d'écoute décalées, les tests port-forward qui ne reflètent pas le trafic réel, et la décision rollback vs retuning sur OOM/NotReady. Cet article propose une matrice Kubernetes vs Mac nu, un runbook en sept étapes, des seuils prêts pour ticket de changement et une FAQ par symptôme.
1. Introduction : pourquoi la recette sur Kubernetes exige des preuves réseau et cgroup
Sur bare metal, « le port est ouvert » équivaut souvent à une écoute réussie. Sur Kubernetes, la même ligne de journal traverse encore les endpoints Service, kube-proxy (ou votre datapath CNI), NetworkPolicy et la comptabilité mémoire cgroup. Si OpenClaw Gateway garde un modèle mental 127.0.0.1 hérité d'un portable, vous obtenez des faux négatifs : curl vers le Pod fonctionne alors que le trafic via Service échoue, ou readiness reste rouge alors que le processus vit.
Ce guide enchaîne des preuves signables : digest d'image et hash des values Helm, requests/limits alignés sur les événements OOM, bind=lan cohérent avec targetPort, et tests port-forward recoupés avec des sondes in-cluster. Pour le contraste avec Docker Compose et la santé sur Mac nu, voir aussi OpenClaw sur nœud Mac distant — Docker ou bare metal ? Sondes Compose et FAQ comme modèle « même version, deux pistes ».
2. Trois points de douleur : dérive de version, bind vs sondes, quotas et trafic bruyant
- Dérive de version et non-reproductibilité : la production utilise
:latestou des tags sans digest ; deux semaines plus tard le même tag reconstruit un comportement différent. Les rollbacks ne prouvent plus que l'ancien ReplicaSet correspond au binaire de l'incident. - Adresse d'écoute, Service et sondes en conflit : la passerelle écoute en loopback alors que la readiness frappe l'IP du Pod ; ou bind=lan est correct mais NetworkPolicy n'autorise que le CIDR Ingress et les sondes kubelet sont jetées — NotReady coexiste avec des coupures de trafic.
- Quotas Resource et coût caché : sans requests, le planificateur « réussit » jusqu'à ce que le nœud se remplisse et OOM différé ; des limites trop basses tuent le processus aux pics d'appels d'outils avec sortie 137 et peu de journaux — difficile de séparer fuites et pics sans métriques.
3. Matrice décisionnelle : Kubernetes vs Mac physique distant nu
Alignez « qui gagne sous quelle contrainte » pour ne pas coller les habitudes launchd telles quelles dans les Pods.
| Dimension | Kubernetes (Deployment + Service) | Mac physique distant / launchd |
|---|---|---|
| Écoute bind | Utiliser bind=lan (ou 0.0.0.0) pour que le Service joigne le Pod ; loopback seulement pour sidecars du même Pod |
Souvent 127.0.0.1 derrière nginx/Caddy en terminaison TLS |
| Figement de version | Digest d'image + version de chart + hash des values dans le dossier de changement | Somme de contrôle + fichiers de verrouillage + champs de version dans le plist launchd |
| Isolation | OOMKilled cgroup et throttle CPU sont auditables | Mémoire unifiée et politique de swap ; surveiller pression mémoire et throttling thermique |
| Recette ad hoc | kubectl port-forward pour fumée — pas un substitut aux chemins in-cluster |
curl local ou tunnels SSH ; chemin plus court, moins d'angles replicas |
| Rollback typique | kubectl rollout undo ou digest précédent épinglé |
Remplacer binaire/tag + launchctl kickstart -k ; attention aux verrous instance unique |
4. Runbook en sept étapes (bind=lan et port-forward)
- Figez les versions : la CI écrit l'image
repo@sha256:…, la version du chart Helm et le SHA git devalues.yamldans le ticket ; bloquez les pipelines prod sur tags flottants. - Déclarez les ressources : fixez
requests.memoryproche du working set résident P95 ;limits.memorycouvre appels d'outils et buffers JSON ; les requests CPU évitent le placement sur nœuds déjà saturés. - Alignez bind et ports : si le trafic entre via Service/Ingress, configurez
bind=lan(ou écoute dual-stack documentée) et vérifiezcontainerPort,targetPortet ports des sondes. - Configurez les sondes : la readiness utilise le même protocole/hôte/chemin que le trafic réel ; ajoutez
initialDelaySeconds/startupProbepour le cold start afin que le chargement des compétences ne bascule pas NotReady. - Test fumée port-forward : depuis un poste ops,
kubectl port-forward deploy/openclaw-gateway 18789:18789(adapter le port), santé minimale et un appel d'outil ; répétez une sonde in-cluster et notez si les deux chemins concordent. - Observez et alertez : reliez compteur de redémarrages, OOMKilled, durée readiness=false, 5xx et profondeur de file passerelle à un tableau de bord ; gardez 24 h avant/après changement.
- Contraste Mac nu pour signature : sur un Mac physique distant, répétez les signaux clés avec le même digest en installation native ou Compose et documentez les écarts — voir OpenClaw sous Windows et Linux : PowerShell, WSL2, proxy HTTPS d'entreprise et passerelle macOS distante (runbook reproductible) pour l'alignement client vers passerelle macOS.
5. Seuils et paramètres réutilisables
- Épinglage d'image : les tickets prod incluent digest et identifiant de build ; les rollbacks recoupent les horodatages d'incident.
- Marge mémoire : avec pics d'appels d'outils observés, gardez les limites au moins ~25–40 % au-dessus du résident P95 explicable ; préférez le throttle avant de doubler aveuglément.
- Démarrage des sondes : passerelles avec cold start > 30 s : startupProbe ou grâce ≥ 40–60 s, alignée sur le chargement workspace/skills OpenClaw.
- port-forward : fumée uniquement ; les SLO de signature doivent inclure DNS Service in-cluster et chemins Ingress/TLS.
6. FAQ : OOM, NotReady et rollback
bind=lan élargit-il l'exposition ?
Écouter dans le Pod sur une adresse non loopback n'équivaut pas à une exposition Internet publique ; la surface est définie par le type de Service, Ingress, NetworkPolicy et politique de sortie. Auditez séparément « bind du processus » et « qui peut router vers le Pod ».
Premier pas sur OOMKilled ?
Lisez kubectl describe pod (Last State), pression mémoire du nœud et sortie 137 ; corrélez avec appels d'outils concurrents et tailles de charge utile pour ne pas confondre pics et fuites.
NotReady alors que les journaux indiquent « listening » — quoi corriger en premier ?
Vérifiez URL/port/chemin de la sonde, startupProbe manquante, NetworkPolicy bloquant les sources kubelet, et si les routes HTTP ne montent qu'après ready.
Comment documenter le rollback pour la conformité ?
Conservez le digest précédent et la révision Helm ; après kubectl rollout undo, exécutez santé in-cluster et poignée métier minimale et joignez les preuves au ticket.
7. Pourquoi aligner la même version sur Mac mini est plus simple
Kubernetes couvre replicas, déploiements progressifs et audits de quotas ; les nœuds Mac physique distant — souvent Mac mini M4 — restent le défaut pratique pour la signature, Screen Sharing et l'écosystème Apple. Faire tourner le même digest sous launchd avant de promouvoir l'image cluster réduit les surprises tardives de bind et de sondes.
Sur macOS, Unix et SSH sont prêts à l'emploi ; la mémoire unifiée Apple Silicon stabilise les processus passerelle longue durée face à de nombreux petits PC, et une consommation idle d'environ 4 W rend les tests de contraste 7j/7 abordables. Gatekeeper, SIP et FileVault réduisent le risque malware par rapport à des images Windows typiques. Pour des signaux de santé équivalents cluster et bare metal, un Mac mini M4 silencieux et efficace est un nœud de référence solide.
Si vous êtes prêt à valider ce runbook sur du matériel réel, le Mac mini M4 offre un excellent rapport coût / standard pour tourner en parallèle des clusters de production.
Mac mini comme nœud de contraste « doré » hors cluster
Signez la même build passerelle sur macOS distant avant de promouvoir l'image Kubernetes — moins d'incidents de sondes et d'écoute.