ADR 0004: Gestión de secretos del cluster — Vaultwarden + VKS¶
Fecha: 2026-09-07 Estado: aceptado
Contexto¶
Los secretos del cluster se gestionan hoy con Vaultwarden como fuente de
verdad (colección Homelab de la org Familia) y
Vaultwarden Kubernetes Secrets (VKS)
como puente que los materializa en Secrets de k8s. Sealed Secrets queda
reservado solo para bootstrap (DB de Vaultwarden, credenciales de VKS,
ADMIN_TOKEN, SMTP).
Se plantea la duda de si sustituir este approach por HashiCorp Vault + External Secrets Operator (ESO), el patrón "de referencia" para secretos en Kubernetes. Vaultwarden se mantendrá en cualquier caso como gestor de contraseñas personal de la familia.
Decisión¶
Se mantiene Vaultwarden + VKS. No se introduce HashiCorp Vault ni ESO.
Comparación que justifica la decisión:
| Dimensión | Vaultwarden + VKS | Vault + ESO |
|---|---|---|
| Servicios extra | 0 (VKS ya operativo) | +2 (Vault + ESO) |
| Madurez | VKS nicho (single-maintainer) | Vault/ESO estándar de facto |
| Modelo de secretos | Estáticos (Login / Secure Note) | Estáticos + dynamic secrets + leases/TTL + PKI |
| Rotación | Manual (VKS re-sincroniza ≤5 min) | Nativa (TTL, renovación automática) |
| Auditoría / ACL | Colecciones (grueso) | Audit devices + policies finos |
| Bootstrap | Bajo (DB CNPG + ADMIN_TOKEN) |
Alto (storage + unseal + root token) |
| HA | Pod Recreate + CNPG |
3 nodos Raft/Consul + unseal por reinicio |
| Huella | 1 contenedor + emptyDir |
Storage persistente + operador ESO |
| UX familiar | UI de gestor de contraseñas (ya en uso) | Sin UI amigable |
| Encaje | Un solo sistema; VKS es solo un puente | Dos sistemas de secretos que se solapan |
Consecuencias¶
- No se añade Vault: se evita un servicio extra y, sobre todo, el coste operativo del unseal/bootstrap y de mantener dos fuentes de verdad.
- El umbral para reevaluar es la necesidad real de dynamic secrets, auditoría o ACL fino. Hoy no se alcanza:
- Las credenciales de Postgres ya las rota CloudNativePG (operador).
- El TLS lo cubre cert-manager + Let's Encrypt, no hace falta Vault PKI.
- Riesgo asumido: VKS es un proyecto pequeño (bus-factor). Se mitiga porque
su alcance es mínimo (poll + materializar
Secrets) y es re-desplegable desde Git; el estado real vive en Vaultwarden. - Vaultwarden + VKS ya es el patrón "External Secrets" de facto: un
Secretde k8s materializado desde una fuente externa. ESO no aporta nada aquí porque no tiene provider nativo para Vaultwarden.