Uso do Vault#

Conexão ao Vault (interno e externo)#

O projeto oferece duas configurações:

• Vault interno: o contêiner orchestrator-vault na configuração docker-compose atual.
• Vault externo: um servidor ou cluster do Vault separado, fora do compose.

A sequência é a mesma nos dois casos: configure env, inicie os serviços e depois migre e verifique.

Requisitos comuns de .env#

Configure pelo menos os seguintes valores:

VAULT_ADDR=http://<vault-host>:8200
VAULT_TOKEN=<token-com-acesso-ao-kv>
ORCHESTRATOR_ENCRYPTION_KEY=<sua-chave-de-criptografia>

Requisitos:

• VAULT_ADDR deve ser acessível a partir do contêiner orchestrator.
• VAULT_TOKEN deve ter permissões create/read/update/delete/list para kv/*.
• ORCHESTRATOR_ENCRYPTION_KEY é necessário para rollback e criptografia.
• O mount kv/ do Vault deve usar KV v2.

Opção 1: Vault interno (perfil do docker compose)#

1. Configure .env#

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

2. Inicie os serviços com o perfil vault#

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

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

3. Inicialize e desbloqueie (unseal) o Vault#

docker compose exec orchestrator-vault sh

# dentro do contêiner
vault operator init
vault operator unseal
exit

Se kv/ não foi criado, habilite-o manualmente como KV v2:

docker compose exec orchestrator-vault sh

# dentro do contêiner
export VAULT_TOKEN='seu-token-root'
vault secrets list -detailed
vault secrets enable -path=kv -version=2 kv
vault secrets list -detailed
exit

4. Aplicação das configurações ao backend#

Após alterar .env, é necessário recriar o contêiner orchestrator. Uma reinicialização comum não aplica as novas variáveis de ambiente. Execute o comando no diretório de instalação durante uma janela de manutenção acordada: o backend ficará brevemente indisponível. Os serviços de banco de dados e Vault já devem estar em execução; --no-deps os mantém inalterados.

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

Opção 2: Vault externo (servidor ou cluster separado)#

1. Configure .env#

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

2. Prepare o Vault externo (uma vez)#

O Vault deve estar initialized e unsealed.

Verifique ou 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. Inicialização do Orchestrator e aplicação das configurações#

Após alterar .env, é necessário recriar o contêiner orchestrator. Uma reinicialização comum não aplica as novas variáveis de ambiente. Execute o comando no diretório de instalação durante uma janela de manutenção acordada: o backend ficará brevemente indisponível. Os serviços de banco de dados e Vault já devem estar em execução; --no-deps os mantém inalterados.

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

Migração e verificação (ambas as opções)#

1. Verifique os logs do Orchestrator#

docker compose logs -f orchestrator

Os seguintes erros não devem aparecer:

• Vault is not available
• VAULT_TOKEN environment variable is required

2. Migre os segredos para o Vault#

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

Resultado esperado:

• as senhas no BD são substituídas por VAULT_MIGRATED;
• os segredos são gravados no Vault em kv/orchestrator/....

3. Faça rollback do Vault para o BD (opcional)#

# Opção 1: diretamente
docker compose exec orchestrator php backend/bin/vault-rollback.php

# Opção 2: pelo Makefile
make vault-rollback

O rollback restaura os valores do Vault no BD e os criptografa com ORCHESTRATOR_ENCRYPTION_KEY.

Problemas comuns#