Problema

Los administradores de Proxmox suelen combinar scripts ad‑hoc, llamadas API y herramientas de terceros para tareas repetitivas: despliegues, backups, migraciones o cambios de firewall. En entornos con varios nodos y cientos de máquinas virtuales, esa fragmentación genera tres problemas recurrentes:

  1. Falta de trazabilidad – Cada cambio se ejecuta de forma aislada, sin un registro central que permita auditar quién hizo qué y cuándo.
  2. Riesgo de cambios destructivos – Operaciones como borrar un pool no vacío o eliminar una regla HA pueden ejecutarse sin una revisión previa, provocando interrupciones inesperadas.
  3. Ausencia de control humano en pipelines – Los CI/CD despliegan sin intervención, lo que dificulta validar cambios críticos que requieren aprobación manual.

El patrón es claro: la automatización avanza, pero la seguridad y la observabilidad quedan rezagadas, lo que lleva a incidentes difíciles de diagnosticar y a una sobrecarga de trabajo para revertir errores.

Causa

Varias causas subyacen a este escenario:

  • Herramientas dispares: Cada función (backup, firewall, HA) tiene su propio cliente o script, lo que impide una visión unificada del estado del clúster.
  • Falta de políticas de pre‑flight: Los comandos de API no incluyen validaciones de riesgo por defecto; el operador confía en que la sintaxis es correcta.
  • Ausencia de integración con control de versiones: El estado del clúster no se versiona, por lo que no hay “fuente de verdad” para comparar antes y después de una operación.
  • Gestión manual de incidentes: Cuando se detecta un problema, los equipos suelen bloquear individualmente nodos o máquinas, sin un mecanismo centralizado que impida nuevas mutaciones.

Estas causas aparecen con frecuencia en laboratorios domésticos que escalan a producción y en entornos corporativos donde varios equipos comparten el mismo clúster.

Solución

Una estrategia unificada basada en Proxxx aborda los tres ejes problemáticos:

  1. GitOps nativo – proxxx state export genera un TOML estable que describe pools, ACL, storage, backups, firewall y HA. El archivo se versiona en Git, lo que permite comparar (proxxx state diff) y aplicar cambios (proxxx state apply) de forma declarativa.
  2. Risk gates y pre‑flight – Al ejecutar cualquier mutación, Proxxx evalúa reglas de riesgo (p. ej., borrado de pool no vacío, eliminación de ACL raíz). Si la operación supera el umbral, el comando falla a menos que se añada --allow-risk o se active --interactive para confirmar cada riesgo.
  3. Human‑in‑the‑Loop (HITL) – La opción --hitl telegram envía una solicitud de aprobación a un bot de Telegram. Si no se recibe respuesta en 120 s, la acción se niega automáticamente. La política se puede afinar por etiqueta, VMID o comodín.
  4. Incident freeze – proxxx incident freeze --reason "patch rollout" bloquea todas las mutaciones POST/PUT/DELETE en todo el clúster durante el TTL especificado. Los lectores siguen funcionando, lo que permite investigar sin que nuevas operaciones empeoren la situación.
  5. Observabilidad integrada – Comandos como proxxx heatmap, proxxx anomaly y proxxx accounting entregan métricas de latencia API, outliers y consumo de recursos por VM, facilitando la detección temprana de cuellos de botella.
  6. Manejo de perfiles de solo‑lectura – Definir read_only = true en un perfil impide cualquier mutación desde el cliente, ideal para entornos de producción donde solo se permite escritura en un clúster de pruebas.

Flujo típico

  1. Exportar estado: proxxx state export > cluster-state.toml.
  2. Modificar en Git: Cambiar la regla de firewall o añadir un backup job.
  3. Revisar diff: proxxx state diff --base cluster-state.toml --target HEAD.
  4. Aplicar con validación: proxxx state apply --allow-risk --interactive.
  5. Aprobación HITL (si corresponde): El bot de Telegram solicita confirmación antes de ejecutar cambios críticos.
  6. Bloquear mutaciones durante mantenimiento: proxxx incident freeze --reason "upgrade" --ttl 2h.
  7. Desbloquear: proxxx incident thaw.

Este enfoque mantiene la automatización, pero introduce puntos de control que evitan errores catastróficos y proporcionan una pista de auditoría completa.

Cuándo aplicar esta solución

  • Entornos con múltiples nodos y >50 VMs donde los cambios se orquestan desde pipelines CI/CD.
  • Equipos distribuidos que requieren aprobaciones humanas para operaciones de alto riesgo.
  • Procedimientos de actualización que necesitan bloquear mutaciones mientras se verifica la compatibilidad.
  • Laboratorios que migran a producción y quieren introducir GitOps sin cambiar la arquitectura existente.

No es necesario cuando el clúster es monolítico, con pocos recursos y sin requisitos de auditoría; en esos casos, los scripts simples pueden seguir siendo suficientes.

Código

# Exportar estado completo del clúster
proxxx state export > cluster-state.toml

# Ver diff entre el estado actual y la rama git
git checkout feature/firewall-change
proxxx state diff --base cluster-state.toml --target HEAD

# Aplicar cambios con riesgo controlado y aprobación interactiva
proxxx state apply --allow-risk --interactive

# Ejecutar una migración con confirmación HITL vía Telegram
proxxx migrate 102 --stream --hitl telegram

# Iniciar un freeze de incidentes por 3 horas
proxxx incident freeze --reason "kernel upgrade" --ttl 3h

# Ver métricas de latencia API por nodo
proxxx heatmap --output json | jq .

Verificación

  1. Confirmar export: ls -l cluster-state.toml y revisar que el archivo contiene secciones [pools], [acl], [storage].
  2. Validar diff: El comando proxxx state diff debe listar únicamente los recursos modificados; si aparecen cambios inesperados, revierte el commit.
  3. Comprobar aprobación HITL: Después de lanzar proxxx migrate, verifica en Telegram que el mensaje de aprobación llegó y que la respuesta ✅ ejecutó la migración.
  4. Verificar freeze: Ejecuta proxxx ls nodes (debe funcionar) y luego intenta crear una VM: proxxx create vm 200. El comando debe terminar con código de salida 8 y mensaje “mutation blocked by incident freeze”.
  5. Revisar métricas: proxxx heatmap --output json debe mostrar latencias <200 ms en nodos sanos; valores superiores indican problemas de red o carga.

Notas adicionales

  • Firma y SBOM: Cada release de Proxxx incluye SHA‑256, firma cosign y un SBOM CycloneDX. Verifica con cosign verify-blob --key cosign.pub proxxx.tar.gz y escanea con grype proxxx.tar.gz antes de desplegar en producción.
  • Perfiles read‑only: Combínalos con tokens de auditoría (PVEAuditor) para reforzar la política del lado del servidor; así, incluso si un cliente omite la bandera --allow-risk, el API rechazará la mutación.
  • Escalado a múltiples clústeres: Usa proxxx fleet para obtener una vista consolidada. El comando permite filtrar por health status y lanzar acciones específicas a un clúster sin cambiar de perfil manualmente.
  • Backup verification: Después de restaurar con proxxx backup-verify, revisa los logs de proxmox-backup-client para confirmar que los metadatos coinciden; una discrepancia suele indicar corrupción en el almacenamiento compartido.
  • Actualizaciones de Proxmox: Ejecuta proxxx upgrade-check --target 9.x antes de cualquier salto de versión. El exit code 1 indica hallazgos bloqueantes que deben resolverse en CI antes de aprobar la actualización.

Con este enfoque, los equipos pueden seguir beneficiándose de la velocidad de los pipelines automatizados sin sacrificar la seguridad ni la visibilidad del estado del clúster. Proxxx actúa como un “capa de control” que unifica lectura, escritura y auditoría en un único binario, simplificando la gestión de entornos Proxmox complejos.