Rapport technique : kzero v1.1.1

kzero est un CLI Go pour la maintenance hors bande Kubernetes : pipelines down, up et reset depuis du YAML sur un bastion. Pas de GitOps in-cluster. Image GHCR distroless ; l’hôte requiert kubectl (et helm pour release.* en shell).

v1.1.1 (2026-09-02) : correctif sécurité Go 1.26.6, sans changement de schéma. Fonctions ci-dessous : v1.1.0.

Dans la stack opérateur Hermes, kzero orchestre la maintenance ; groot (archive diagnostique en lecture seule) capture l’évidence avant ou après la fenêtre — complémentaires, pas substituts. Voir §8.

1. API dégradée

Les réconciliateurs in-cluster dépendent de la même API. Voir deployment models.

2. Limites du Bash ad-hoc

• Pas d’idempotence native
• Pas de dry-run structuré
• Gestion d’erreurs fragile (coupures API)
• Audit faible, pas de notify intégré

kzero doctor vérifie l’interpréteur shell des hooks.

3. Exemple : script Bash

#!/bin/bash
set -eo pipefail

kubectl scale deployment/data-ingest --replicas=0 -n production
kubectl rollout status deployment/data-ingest -n production
kubectl patch cronjob/daily-reconcile -p '{"spec":{"suspend":true}}' -n production
kubectl delete job/storage-cleanup -n production --ignore-not-found
kubectl apply -f storage-cleanup-job.yaml
kubectl wait --for=condition=complete job/storage-cleanup --timeout=300s -n production
helm upgrade --install core-api ./charts/core-api --values prod-values.yaml -n production
kubectl scale deployment/data-ingest --replicas=3 -n production
kubectl patch cronjob/daily-reconcile -p '{"spec":{"suspend":false}}' -n production

4. Mapping impératif → déclaratif

Bash	kzero v1.1.x	Avantage
kubectl scale …	deployment.<ns>/<name>	Étapes ordonnées
suspend CronJob	cronjob.<ns>/<name>	suspend/resume natif
Job delete/apply	job.<ns>/<name>	manifest: + attente
helm upgrade	release.<ns>/<name>	Helm SDK v4
kubectl logs / preuves ad hoc	groot collect (option hooks.pre-down)	Archive .tar.gz en lecture seule avant mutation
Checks manuels	doctor, analyze	Preflight
Retries	moteur + api_watchdog	Annulation si API down

SPECIFICATIONS.md

5. Profil kzero équivalent

schema_version: "1.0"

cluster:
  name: maintenance-production
  environment: production

helm:
  workspace: ./helm-assets

notify:
  require_delivery: true
  webhook:
    enabled: true
    url: "https://hooks.slack.com/services/…"

hooks:
  pre-down: ./hooks/groot-capture.sh   # optionnel : groot collect avant mutation
  on-error: ./hooks/groot-capture.sh   # optionnel : second bundle si échec pipeline

run:
  mode: dry-run
  execution: native
  api_watchdog:
    enabled: true
    fail_after: 30s

pipelines:
  down:
    - deployment.production/data-ingest
    - cronjob.production/daily-reconcile
    - job.production/storage-cleanup
  up:
    - job.production/storage-cleanup:
        manifest: ./jobs/storage-cleanup.yaml
        wait_for_complete: true
        timeout: 5m
    - release.production/core-api
    - deployment.production/data-ingest:
        replicas: 3
        wait_for_ready: true
    - cronjob.production/daily-reconcile

Exemples : kzero-selfhosted/run/examples

6. Workflow sécurisé

Exécuter les portes avant run.mode: live. Sur bastion de prod, capturer l’évidence avec groot d’abord (ou via hooks.pre-down) :

curl -fsSL https://get.kzero.hermesrodriguez.com/install.sh | sh
kzero --print-sample-config > ./kzero.yaml

# Recommandé : archive lecture seule tant que le cluster est observable
groot collect -c ./groot.yaml -o ./evidence/pre-down-$(date +%Y%m%d-%H%M).tar.gz

kzero doctor -c ./kzero.yaml
kzero analyze -c ./kzero.yaml
kzero diff -c ./kzero.yaml --phase down
kzero down -c ./kzero.yaml
kzero up -c ./kzero.yaml
kzero diff -c ./kzero.yaml --phase up

Gate CI : kzero diff --config ./kzero.yaml --phase up || exit 2 — voir diff.md.

Étape	Rôle
groot collect (optionnel)	Logs/événements/snapshot API → .tar.gz pour RCA et tickets
doctor	API, binaires, indices RBAC, interpréteur shell

7. Codes de sortie

Code	Événement
0	Succès
1	Config
2	Kubernetes / drift diff
3	Abandon exécuteur
4	Échec notify

8. Écosystème Hermes : groot complète kzero

kzero modifie l’état du cluster (scale, Helm, Jobs, PVC). groot est lecture seule : groot collect regroupe logs de pods, événements et snapshots API en un .tar.gz pour incident, RCA et conformité. Ne remplace pas kzero — préserve l’état du cluster avant down / up.

Dépôt	Rôle
hrodrig/groot	CLI : collect, validate, inspect ; upload S3/GCS/SFTP optionnel
groot-selfhosted	Bastion, CronJob Helm, playbooks opérateur
groot-trigger	HTTP in-cluster → Job groot collect à la demande
groot-share (gfs)	Catalogue VPS : ingest, liste, téléchargement, rétention

Landing : groot.hermesrodriguez.com. Même famille que pgwd (watchdog Postgres) et gghstats (analytics GitHub).

Les codes 0–4 de kzero suivent le modèle de groot exitcode.

9. v1.1.0 / v1.1.1

v1.1.0 : diff, job/cronjob, Helm SDK v4, Cosign/SBOM.
v1.1.1 : Go 1.26.6 — ghcr.io/hrodrig/kzero:v1.1.1.

10. Matrice

Capacité	kzero	GitOps	Ansible	Shell
Architecture	Hors bande	In-cluster	Externe	Externe
Simulation	analyze/dry-run/diff	Preview	check-mode	Rare

11. Liens

kzero est un orchestrateur de maintenance discret, pas un remplaçant d’Argo/Flux. Associez groot pour un bundle d’évidence dans la même fenêtre.

Ressource	Lien
SPEC	SPECIFICATIONS.md
Config exemple	kzero.sample.yml
Changelog	CHANGELOG.md
kzero (maintenance)	hrodrig/kzero · kzero-selfhosted
groot (archive diagnostic)	hrodrig/groot · groot-selfhosted
groot écosystème	groot-trigger · groot-share
Opérateur	kzero-selfhosted/run/examples