Engineering-Report: kzero v1.1.1

kzero v1.1.1 Produkt-Infografik

kzero ist ein Go-CLI für Out-of-Band-Wartung in Kubernetes: geordnete down-, up- und reset-Pipelines aus YAML auf einem Bastion- oder Automatisierungshost. Kein In-Cluster-GitOps. Das GHCR-Image ist distroless; der Host braucht kubectl im PATH (und helm bei Shell-Pfad-release.*).

v1.1.1 (2026-09-02) ist ein Sicherheits-Patch (Go 1.26.6, kein Schema-Change). Funktionale Features beziehen sich auf v1.1.0.

Im Hermes-Operator-Stack orchestriert kzero die Wartung; groot (schreibgeschütztes Diagnose-Archiv) erfasst Cluster-Evidenz vor oder nach dem Fenster — komplementär, kein Ersatz. Siehe §8.

1. „Kranke API“ und Bastion-first

In-Cluster-Reconciler hängen von derselben API ab, die sie heilen sollen. deployment models.

2. Warum Ad-hoc-Bash scheitert

Keine native Idempotenz
Kein strukturiertes dry-run
Fragile Fehlerbehandlung bei API-Ausfällen
Schwache Audit-Spur, keine integrierten notify-Hooks

kzero doctor prüft den Shell-Interpreter bei Hooks.

3. Beispiel: imperatives Bash-Skript

#!/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 imperativ → deklarativ

Bash	kzero v1.1.x	Vorteil
`kubectl scale …`	`deployment.<ns>/<name>` in `pipelines.down`	Geordnete Schritte
CronJob suspend	`cronjob.<ns>/<name>`	Native suspend/resume
Job delete/apply/wait	`job.<ns>/<name>`	`manifest:` + `wait_for_complete`
`helm upgrade`	`release.<ns>/<name>`	Helm SDK v4 bei native/auto
Ad-hoc `kubectl logs` / Evidenz	`groot collect` (optional `hooks.pre-down`)	Schreibgeschütztes `.tar.gz` vor Mutation
Manuelle Checks	`doctor`, `analyze`	Preflight
Retry-Schleifen	Engine-Retry + api_watchdog	Abbruch bei API-Verlust

SPECIFICATIONS.md

5. Äquivalentes kzero-Profil

schema_version: "1.0"

cluster:
  name: production-maintenance
  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   # optional: groot collect vor Mutation
  on-error: ./hooks/groot-capture.sh   # optional: zweites Bundle bei Pipeline-Fehler

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

Beispiele: kzero-selfhosted/run/examples

6. Sicherer Wartungs-Workflow

Gates vor run.mode: live. Auf Produktions-Bastions zuerst Evidenz mit groot (oder via hooks.pre-down):

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

# Empfohlen: schreibgeschütztes Archiv solange der Cluster voll beobachtbar ist
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

Cron-Gate: kzero diff --config ./kzero.yaml --phase up || exit 2

Details: diff.md

Schritt	Zweck
`groot collect` (optional)	Schreibgeschützte Logs/Events/API → `.tar.gz` für RCA und Tickets
`doctor`	API, Binärpfade, RBAC-Hinweise, Shell-Interpreter
`analyze`	Statischer Plan + optionale Objektprüfungen
`diff`	Soll vs. Ist für `--phase up\|down`; Exit 2 bei Drift

7. Exit-Codes

Code	Bedeutung
0	Erfolg
1	Config
2	Kubernetes / diff-Drift
3	Executor-Abbruch
4	Notify-Fehler (`require_delivery`)

8. Hermes-Ökosystem: groot ergänzt kzero

kzero ändert Cluster-Zustand (Scale, Helm, Jobs, PVCs). groot ist schreibgeschützt: groot collect bündelt Pod-Logs, Events und API-Snapshots in ein .tar.gz für Incident Response, RCA und Compliance. Ersetzt kzero nicht — bewahrt wie der Cluster aussah, bevor down / up läuft.

Repo	Rolle
hrodrig/groot	CLI: `collect`, validate, inspect; optional S3/GCS/SFTP-Upload
groot-selfhosted	Bastion-Cron, Helm CronJob, Operator-Playbooks
groot-trigger	In-Cluster-HTTP → Job mit `groot collect` on demand
groot-share (gfs)	VPS-Katalog: Ingest, List, Download, Retention

Landing: groot.hermesrodriguez.com. Gleiche Familie wie pgwd (Postgres-Watchdog) und gghstats (GitHub-Traffic).

Exit-Codes 0–4 in kzero folgen dem Muster von groot exitcode.

9. v1.1.0 / v1.1.1

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

10. Vergleichsmatrix

Fähigkeit	kzero	GitOps	Ansible	Shell
Architektur	Out-of-band	In-cluster	Extern	Extern
Simulation	analyze/dry-run/diff	Preview	check-mode	Selten
API-Resilienz	api_watchdog	API-abhängig	Mittel	Niedrig

11. Links

kzero ist ein diskreter Wartungs-Orchestrator, kein Argo/Flux-Ersatz. Kombiniere mit groot, wenn du ein Evidenz-Bundle in derselben Wartungsfenster brauchst.

Ressource	Link
SPEC	SPECIFICATIONS.md
Beispiel-Config	kzero.sample.yml
Changelog	CHANGELOG.md
kzero (Wartung)	hrodrig/kzero · kzero-selfhosted
groot (Diagnose-Archiv)	hrodrig/groot · groot-selfhosted
groot Ökosystem	groot-trigger · groot-share
Operator	kzero-selfhosted/run/examples