OpenBao - guida DevOps
OpenBao – Guida rapida DevOps
Scopo
Questa procedura descrive le attività da eseguire in Semaphore quando:
- viene deployata una nuova VM che deve utilizzare OpenBao;
- viene aggiunto un nuovo progetto Docker Compose su una VM già configurata.
1. Nuova VM – Installazione OpenBao Agent
Per ogni nuova VM applicativa deve essere eseguito in Semaphore il playbook:
Install openbao agent
Il playbook:
- installa e configura OpenBao Agent;
- configura l'autenticazione AppRole;
- associa la VM al corretto gruppo e ambiente;
- prepara il filesystem utilizzato dall'Agent;
- abilita il servizio
openbao-agent.
Variabili richieste
Esempio:
{
"host": "v329",
"openbao_addr": "https://secretmanager.eagleprojects.cloud",
"group": "devops",
"env": "test",
"role_id": "<ROLE_ID>",
"secret_id": "<SECRET_ID>",
"vm_id": "329"
}
Significato dei parametri
| Variabile | Descrizione |
|---|---|
host |
Host Semaphore / inventory della VM |
openbao_addr |
Endpoint OpenBao raggiungibile tramite Caddy |
group |
Gruppo applicativo a cui appartiene la VM |
env |
Ambiente della VM, ad esempio dev, test, staging, prod |
role_id |
RoleID AppRole assegnato alla VM |
secret_id |
SecretID AppRole assegnato alla VM |
vm_id |
ID univoco della VM |
Attenzione alle credenziali AppRole
role_id e secret_id sono credenziali macchina.
In particolare il secret_id deve essere trattato come un secret:
- non inserirlo nella documentazione;
- non copiarlo nei ticket;
- non salvarlo in repository;
- non condividerlo in chat o canali non autorizzati;
- utilizzarlo esclusivamente durante il provisioning previsto.
2. Verifica dopo installazione Agent
Al termine del playbook verificare sulla VM:
systemctl status openbao-agent --no-pager
Il servizio deve risultare attivo.
Per controllare i log:
journalctl -u openbao-agent -n 100 --no-pager
Verificare inoltre che l'Agent riesca ad autenticarsi verso:
https://secretmanager.eagleprojects.cloud
3. Nuovo progetto Docker Compose
Quando viene aggiunto un nuovo progetto Docker Compose su una VM già configurata con OpenBao Agent, deve essere eseguito in Semaphore il playbook:
openbao-register-compose
Esempio:
{
"host": "v913",
"nome_univoco_progetto": "dwh_utility",
"group": "bi",
"env": "test"
}
Significato dei parametri
| Variabile | Descrizione |
|---|---|
host |
VM sulla quale è presente il Docker Compose |
nome_univoco_progetto |
Nome tecnico univoco del progetto |
group |
Gruppo proprietario del progetto |
env |
Ambiente della VM/progetto |
4. Regola fondamentale: nome univoco del progetto
La variabile:
nome_univoco_progetto
deve corrispondere esattamente al nome tecnico assegnato al progetto.
Deve essere identico lungo tutta la catena:
Repository
=
Registry
=
Ticket
=
OpenBao
=
nome_univoco_progetto
Esempio corretto:
Repository dwh_utility
Registry dwh_utility
Ticket dwh_utility
nome_univoco_progetto dwh_utility
OpenBao dwh_utility
Non utilizzare variazioni come:
dwh-utility
DWH Utility
dwhutility
dwh_utility_test
se il nome ufficiale del progetto è:
dwh_utility
Il nome non è una descrizione leggibile del progetto: è un identificativo tecnico utilizzato dalle automazioni.
5. Path OpenBao risultante
Il playbook associa il progetto al path:
kv/apps/<group>/<env>/<nome_univoco_progetto>
Con:
{
"nome_univoco_progetto": "dwh_utility",
"group": "bi",
"env": "test"
}
il secret corrispondente sarà:
kv/apps/bi/test/dwh_utility
Questo deve essere lo stesso path nel quale vengono gestite le variabili dalla Web UI OpenBao.
6. Flusso completo per una nuova VM
Creazione VM
↓
creazione policy/AppRole OpenBao
↓
ottenimento RoleID + SecretID
↓
Semaphore
↓
Install openbao agent
↓
OpenBao Agent attivo
Successivamente, per ogni Compose:
nuovo progetto
↓
verifica nome univoco
↓
openbao-register-compose
↓
registrazione template/configurazione
↓
OpenBao Agent
↓
.env generato
↓
Docker Compose
7. Flusso per un nuovo progetto su VM esistente
Se la VM ha già OpenBao Agent configurato, non deve essere rilanciato il playbook di installazione Agent.
È sufficiente:
Nuovo Docker Compose
↓
verifica Repository / Registry / Ticket
↓
recupero nome univoco progetto
↓
Semaphore
↓
openbao-register-compose
↓
OpenBao
↓
Agent
↓
Docker Compose
8. Checklist DevOps
Nuova VM
- VM presente nell'inventory Semaphore.
-
groupcorretto. -
envcorretto. -
vm_idcorretto. - AppRole creato per la VM.
-
role_iddisponibile. -
secret_iddisponibile. - Eseguito
Install openbao agent. -
openbao-agent.serviceattivo.
Nuovo progetto
- Docker Compose presente sulla VM.
- Nome univoco verificato sul ticket.
- Nome coerente con repository e registry.
-
groupcorretto. -
envcorretto. - Eseguito
openbao-register-compose. - Path OpenBao corretto.
-
.envgenerato correttamente dall'Agent.
9. Regola operativa sintetica
NUOVA VM
→ Install openbao agent
NUOVO DOCKER COMPOSE
→ openbao-register-compose
e in entrambi i casi verificare sempre:
group
env
nome/ID VM
nome univoco progetto
Per i progetti, la regola principale rimane:
Repository = Registry = Ticket = OpenBao = nome_univoco_progetto
10. Schema di funzionamento
┌──────────────────────────┐
│ OpenBao Server │
│ │
│ KV Secrets Engine │
│ kv/apps/<group>/<env>/* │
│ │
│ Policy RBAC │
│ AppRole Auth │
└─────────────┬────────────┘
│
│ TLS
│
Secret retrieval API
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ VM TARGET │
│ │
│ ┌──────────────────────┐ │
│ │ OpenBao Agent │ │
│ │ │ │
│ │ - AppRole Login │ │
│ │ - Token management │ │
│ │ - Secret rendering │ │
│ │ - Auto refresh │ │
│ └──────────┬───────────┘ │
│ │ │
│ │ 1. Authenticate │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ AppRole Authentication │ │
│ │ │ │
│ │ role_id │ │
│ │ secret_id │ │
│ └──────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ OpenBao Token │ │
│ │ │ │
│ │ associato alla policy │ │
│ │ agent-<group>-<env> │ │
│ └──────────┬────────────┘ │
│ │ │
│ │ 2. Read secrets │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ KV Secret Path │ │
│ │ │ │
│ │ kv/apps/prism/prod/* │ │
│ │ │ │
│ └──────────┬──────────────────┘ │
│ │ │
│ │ 3. Template rendering │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ /run/openbao-agent/ │ │
│ │ │ │
│ │ prism.env │ │
│ │ │ │
│ │ DB_PASSWORD=xxxxx │ │
│ │ API_KEY=xxxxx │ │
│ │ JWT_SECRET=xxxxx │ │
│ └──────────┬──────────────────┘ │
│ │ │
│ │ systemd PathChanged │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Reload Service │ │
│ │ │ │
│ │ openbao-compose-reload │ │
│ └──────────┬──────────────────┘ │
│ │ │
└──────────────┼─────────────────────────────────────────────────────┘
│
│ docker compose restart / reload
▼
┌──────────────────────────────┐
│ Docker Compose │
│ │
│ compose.yml │
│ │
│ services: │
│ app: │
│ env_file: │
│ - /run/openbao-agent/ │
│ prism.env │
│ │
└──────────────┬───────────────┘
│
▼
┌─────────────────┐
│ Docker Container │
│ │
│ Environment: │
│ │
│ DB_PASSWORD │
│ API_KEY │
│ JWT_SECRET │
└─────────────────┘
No comments to display
No comments to display