Uso de Vault#

Conexión de Vault (interno y externo)#

El proyecto admite dos configuraciones:

• Vault interno: el contenedor orchestrator-vault en la configuración docker-compose actual.
• Vault externo: un servidor o clúster de Vault separado, fuera de compose.

La secuencia es la misma en ambos casos: configure env, inicie los servicios y después migre y verifique.

Requisitos comunes de .env#

Configure al menos los siguientes valores:

VAULT_ADDR=http://<vault-host>:8200
VAULT_TOKEN=<token-con-acceso-a-kv>
ORCHESTRATOR_ENCRYPTION_KEY=<su-clave-de-cifrado>

Requisitos:

• VAULT_ADDR debe ser accesible desde el contenedor orchestrator.
• VAULT_TOKEN debe tener permisos create/read/update/delete/list para kv/*.
• ORCHESTRATOR_ENCRYPTION_KEY es obligatorio para el rollback y el cifrado.
• El mount kv/ de Vault debe utilizar KV v2.

Opción 1: Vault interno (perfil de docker compose)#

1. Configure .env#

VAULT_ADDR=http://orchestrator-vault:8200
VAULT_TOKEN=root-token
ORCHESTRATOR_ENCRYPTION_KEY=change_me

2. Inicie los servicios con el perfil vault#

# MariaDB + Vault
docker compose --profile mariadb --profile vault up -d

# o PostgreSQL + Vault
docker compose --profile pg --profile vault up -d

3. Inicialice y desbloquee (unseal) Vault#

docker compose exec orchestrator-vault sh

# dentro del contenedor
vault operator init
vault operator unseal
exit

Si no se creó kv/, habilítelo manualmente como KV v2:

docker compose exec orchestrator-vault sh

# dentro del contenedor
export VAULT_TOKEN='su-token-root'
vault secrets list -detailed
vault secrets enable -path=kv -version=2 kv
vault secrets list -detailed
exit

4. Aplicación de la configuración al backend#

Después de modificar .env, es necesario volver a crear el contenedor orchestrator. Un reinicio normal no aplica las nuevas variables de entorno. Ejecute el comando desde el directorio de instalación durante una ventana de mantenimiento acordada: el backend dejará de estar disponible brevemente. Los servicios de base de datos y Vault deben estar en ejecución; --no-deps los deja sin cambios.

docker compose up -d --no-deps --force-recreate orchestrator

Opción 2: Vault externo (servidor o clúster separado)#

1. Configure .env#

VAULT_ADDR=https://vault.company.local:8200
VAULT_TOKEN=s.xxxxxxxx
ORCHESTRATOR_ENCRYPTION_KEY=change_me

2. Prepare el Vault externo (una sola vez)#

Vault debe estar initialized y unsealed.

Verifique o habilite kv/ como KV v2:

export VAULT_ADDR='https://vault.company.local:8200'
export VAULT_TOKEN='s.xxxxxxxx'

vault secrets list -detailed
vault secrets enable -path=kv -version=2 kv
vault secrets list -detailed

3. Inicio de Orchestrator y aplicación de la configuración#

Después de modificar .env, es necesario volver a crear el contenedor orchestrator. Un reinicio normal no aplica las nuevas variables de entorno. Ejecute el comando desde el directorio de instalación durante una ventana de mantenimiento acordada: el backend dejará de estar disponible brevemente. Los servicios de base de datos y Vault deben estar en ejecución; --no-deps los deja sin cambios.

docker compose up -d --no-deps --force-recreate orchestrator

Migración y verificación (ambas opciones)#

1. Revise los registros de Orchestrator#

docker compose logs -f orchestrator

No deben aparecer los siguientes errores:

• Vault is not available
• VAULT_TOKEN environment variable is required

2. Migre los secretos a Vault#

docker compose exec orchestrator php backend/bin/vault-migrate.php

Resultado esperado:

• las contraseñas de la BD se sustituyen por VAULT_MIGRATED;
• los secretos se escriben en Vault en la ruta kv/orchestrator/....

3. Realice un rollback de Vault a la BD (opcional)#

# Opción 1: directamente
docker compose exec orchestrator php backend/bin/vault-rollback.php

# Opción 2: mediante Makefile
make vault-rollback

El rollback restaura los valores de Vault en la BD y los cifra con ORCHESTRATOR_ENCRYPTION_KEY.

Problemas frecuentes#