Informe técnico: kzero v1.1.1

kzero es un CLI en Go para mantenimiento fuera de banda en Kubernetes: pipelines ordenados down, up y reset desde YAML en un bastión o host de automatización. No es GitOps in-cluster. La imagen GHCR es distroless (solo el binario); el host sigue necesitando kubectl en el PATH (y helm cuando el perfil usa pasos release.* por shell).

v1.1.1 (2026-09-02) es un parche de seguridad sobre la línea 1.1.x (Go 1.26.6, sin cambios de esquema). Las capacidades funcionales descritas abajo corresponden sobre todo a v1.1.0.

En el stack operador Hermes, kzero orquesta el mantenimiento; groot (archivo de diagnóstico solo lectura) captura evidencia antes o después de la ventana — complementarios, no sustitutos. Ver §8.

1. Mantenimiento crítico y la «API enferma»

Cuando etcd, webhooks o el scheduler degradan la API, la automatización in-cluster (Argo CD, Flux) puede quedar paralizada. Una herramienta fuera de banda mantiene un camino de control independiente. Ver modelos de despliegue.

2. Por qué migrar desde Bash ad-hoc

Los scripts imperativos suelen fallar en producción por:

• Falta de idempotencia — re-ejecutar tras un fallo parcial es arriesgado.
• Sin dry-run nativo — simular impacto exige lógica custom por comando.
• Errores frágiles — pérdidas transitorias de API abortan el script o se ignoran.
• Auditoría débil — sin log estructurado por paso ni notify integrado.

kzero doctor comprueba el intérprete de shell cuando hay hooks (/bin/sh vs bash).

3. Ejemplo: script Bash típico

Ventana habitual: escalar ingesta a cero, suspender CronJob, Job de limpieza, upgrade Helm, restaurar servicios.

#!/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

Si kubectl wait falla por un corte transitorio, el clúster puede quedar a medias sin reanudación limpia.

4. Mapeo imperativo → declarativo

Bash / kubectl	kzero v1.1.x	Ventaja
kubectl scale deployment … --replicas=0	deployment.<ns>/<name> en pipelines.down	Orden de pasos; hooks post para esperar drenado
kubectl patch cronjob … suspend	cronjob.<ns>/<name>	Suspend en down, resume en up
delete job + apply + wait	job.<ns>/<name>	Borrado en down; manifest: + wait_for_complete en up
helm upgrade --install …	release.<ns>/<name>	Helm SDK v4 con run.execution: native/auto
kubectl logs / evidencia ad hoc	groot collect (opcional hooks.pre-down)	Archivo .tar.gz solo lectura antes de mutar
Comprobaciones manuales	kzero doctor, kzero analyze	Preflight antes de mutar
Reintentos a mano	Retry del motor + run.api_watchdog	Cancela si la API no responde tras fail_after
curl a Slack	notify.*	Exit 4 con notify.require_delivery

Contrato: SPECIFICATIONS.md.

5. Perfil kzero equivalente (YAML válido)

Mismo escenario que §3, con referencias compactas del esquema real:

schema_version: "1.0"

cluster:
  name: maintenance-production
  environment: production

helm:
  workspace: ./helm-assets   # core-api.yaml para Helm SDK nativo

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 si falla el 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

En down, los workloads escalan a 0 automáticamente. Más patrones: pvc-statefulset-data-strategy.md.

Ejemplos operador: kzero-selfhosted/run/examples.

6. Flujo de trabajo seguro

Ejecuta las compuertas antes de run.mode: live. En bastión de producción, captura evidencia con groot primero (o vía hooks.pre-down):

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

# Recomendado: archivo solo lectura mientras el clúster sigue 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
# … ventana de mantenimiento …
kzero up -c ./kzero.yaml
kzero diff -c ./kzero.yaml --phase up

Comando	Propósito
groot collect (opcional)	Logs/eventos/snapshot API → .tar.gz para RCA y tickets
doctor	API, rutas de binarios, pistas RBAC, shell
analyze	Plan estático + comprobaciones de objetos
diff	Deseado vs live; exit 2 si hay drift
down / up / reset	Ejecución live; api_watchdog cancela si la API cae

Wrapper para cron/CI:

kzero diff --config ./kzero.yaml --phase up || exit 2
kzero reset --config ./kzero.yaml

Cookbook: diff.md.

7. Códigos de salida

Código	Significado	Acción típica
0	Éxito	Continuar
1	Config / validación	Fallar CI; corregir YAML
2	Error Kubernetes o drift en diff	Parar; revisar clúster
3	Aborto del ejecutor / hooks	On-call; estado posiblemente parcial
4	Fallo de notify	Con notify.require_delivery: true

8. Ecosistema Hermes: groot complementa a kzero

kzero muta el clúster (escala, Helm, Jobs, PVCs). groot es solo lectura: groot collect empaqueta logs de pods, eventos y snapshots de API en un .tar.gz para incidentes, RCA y cumplimiento. No sustituye a kzero — preserva cómo estaba el clúster antes del down / up.

Repo	Rol
hrodrig/groot	CLI: collect, validate, inspect; upload S3/GCS/SFTP opcional
groot-selfhosted	Bastión, CronJob Helm, playbooks operador
groot-trigger	HTTP in-cluster → Job con groot collect bajo demanda
groot-share (gfs)	Catálogo VPS: ingest, listado, descarga, retención

Landing: groot.hermesrodriguez.com. Misma familia que pgwd (watchdog Postgres) y gghstats (analítica GitHub).

Los exit codes 0–4 de kzero siguen el patrón de groot exitcode.

9. Capacidades v1.1.0 (sin cambios en v1.1.1)

• kzero diff, pasos nativos job/cronjob, Helm SDK v4, Cosign + SBOM.

v1.1.1: solo Go 1.26.6 — usar ghcr.io/hrodrig/kzero:v1.1.1.

10. Matriz comparativa

Capacidad	kzero v1.1.1	GitOps	Ansible	Scripts shell
Arquitectura	Fuera de banda	In-cluster	SSH externo	Externo
Mantenimiento	Pipelines YAML	Reconciliación	Playbooks	Imperativo
Resiliencia API	api_watchdog	Depende de API	Media	Baja
Simulación	analyze, dry-run, diff	Preview sync	check-mode	Inexistente

11. Alcance y enlaces

kzero es un orquestador de mantenimiento discreto, no sustituto de Argo/Flux. Combínalo con groot cuando necesites un bundle de evidencia en la misma ventana.

Recurso	Enlace
SPEC	SPECIFICATIONS.md
Config de ejemplo	kzero.sample.yml
Changelog	CHANGELOG.md
kzero (mantenimiento)	hrodrig/kzero · kzero-selfhosted
groot (archivo diagnóstico)	hrodrig/groot · groot-selfhosted
groot ecosistema	groot-trigger · groot-share
Operador	kzero-selfhosted/run/examples