Relatório técnico: kzero v1.1.1

Infográfico de produto kzero v1.1.1

kzero é um CLI Go para manutenção out-of-band em Kubernetes: pipelines down, up e reset a partir de YAML num bastion. Não é GitOps in-cluster. Imagem GHCR distroless; o host precisa de kubectl (e helm para release.* por shell).

v1.1.1 (2026-09-02): patch de segurança Go 1.26.6, sem alteração de esquema. Capacidades abaixo: v1.1.0.

Na stack operador Hermes, kzero orquestra a manutenção; groot (arquivo de diagnóstico só leitura) captura evidência antes ou depois da janela — complementares, não substitutos. Ver §8.

1. API degradada

Reconciliadores in-cluster dependem da mesma API. Ver deployment models.

2. Por que Bash ad-hoc falha

  • Sem idempotência nativa
  • Sem dry-run estruturado
  • Tratamento frágil de falhas de API
  • Auditoria fraca, sem notify integrado

kzero doctor verifica o interpretador shell dos hooks.

3. Exemplo: 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. Mapeamento imperativo → declarativo

Bash kzero v1.1.x Benefício
kubectl scale … deployment.<ns>/<name> Passos ordenados
suspend CronJob cronjob.<ns>/<name> suspend/resume nativo
Job delete/apply job.<ns>/<name> manifest: + espera
helm upgrade release.<ns>/<name> Helm SDK v4
kubectl logs / evidência ad hoc groot collect (opcional hooks.pre-down) Arquivo .tar.gz só leitura antes de mutar
Checks manuais doctor, analyze Preflight
Retries motor + api_watchdog Cancela se API cair

SPECIFICATIONS.md

5. Perfil kzero equivalente

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   # opcional: groot collect antes de mutar
  on-error: ./hooks/groot-capture.sh   # opcional: segundo bundle se o pipeline falhar

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

Exemplos: kzero-selfhosted/run/examples

6. Fluxo seguro

Execute as portas antes de run.mode: live. Em bastion de produção, capture evidência com groot primeiro (ou via hooks.pre-down):

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

# Recomendado: arquivo só leitura enquanto o cluster ainda é observável
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 — diff.md

Passo Propósito
groot collect (opcional) Logs/eventos/snapshot API → .tar.gz para RCA e tickets
doctor API, binários, dicas RBAC, interpretador shell

7. Exit codes

Código Significado
0 Sucesso
1 Config
2 Kubernetes / drift diff
3 Aborto do executor
4 Falha notify

8. Ecossistema Hermes: groot complementa kzero

kzero altera o estado do cluster (scale, Helm, Jobs, PVCs). groot é só leitura: groot collect empacota logs de pods, eventos e snapshots de API num .tar.gz para incidentes, RCA e conformidade. Não substitui kzero — preserva como estava o cluster antes de down / up.

Repositório Papel
hrodrig/groot CLI: collect, validate, inspect; upload S3/GCS/SFTP opcional
groot-selfhosted Bastion, CronJob Helm, playbooks operador
groot-trigger HTTP in-cluster → Job com groot collect sob demanda
groot-share (gfs) Catálogo VPS: ingest, listagem, download, retenção

Landing: groot.hermesrodriguez.com. Mesma família que pgwd (watchdog Postgres) e gghstats (analytics GitHub).

Os exit codes 0–4 de kzero seguem o padrão 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. Matriz

Capacidade kzero GitOps Ansible Shell
Arquitetura Out-of-band In-cluster Externa Externa
Simulação analyze/dry-run/diff Preview check-mode Rara

kzero é um orquestrador de manutenção discreto, não substituto de Argo/Flux. Combine com groot quando precisar de um bundle de evidência na mesma janela.

Recurso Link
SPEC SPECIFICATIONS.md
Config exemplo kzero.sample.yml
Changelog CHANGELOG.md
kzero (manutenção) hrodrig/kzero · kzero-selfhosted
groot (arquivo diagnóstico) hrodrig/groot · groot-selfhosted
groot ecossistema groot-trigger · groot-share
Operador kzero-selfhosted/run/examples