OpenBao - guida utente

OpenBao – Guida utente alla gestione dei Secret

Scopo

OpenBao è il sistema centralizzato utilizzato per gestire le variabili di configurazione e i secret delle applicazioni.

Gli utenti autorizzati possono utilizzare direttamente la Web UI di OpenBao per:

visualizzare i secret;

aggiungere nuovi secret;

aggiungere nuove variabili a un progetto;

modificare valori esistenti;

consultare le versioni precedenti.

Non è necessario accedere via SSH alle VM applicative per modificare le variabili.

1. Regola fondamentale: il nome del progetto deve essere univoco

Il nome del progetto deve essere definito una sola volta e mantenuto identico in tutta la catena applicativa.

Il nome del progetto non deve essere modificato, abbreviato, tradotto o reinterpretato nei diversi sistemi.

La stessa identificazione deve essere utilizzata in:

Repository
    ↓
Registry
    ↓
Ticket
    ↓
OpenBao

Esempio corretto

Supponiamo che il nome univoco assegnato al progetto sia:

customer-portal

La stessa stringa deve essere utilizzata coerentemente:

Sistema	Esempio
Repository	`customer-portal`
Registry	`customer-portal`
Ticket	`customer-portal`
OpenBao	`kv/apps/<gruppo>/<ambiente>/customer-portal`

Quindi:

Repository → customer-portal
Registry   → customer-portal
Ticket     → customer-portal
OpenBao    → customer-portal

Esempio errato

Repository → customer-portal
Registry   → customerportal
Ticket     → Customer Portal
OpenBao    → customer_portal

Anche se per una persona questi nomi possono sembrare equivalenti, per i sistemi sono progetti differenti.

2. Perché è così importante

OpenBao non deve essere considerato un sistema isolato.

Il percorso utilizzato per recuperare i secret viene costruito sulla base dell'identificazione del progetto.

La struttura è:

kv/apps/<gruppo>/<ambiente>/<progetto>

Ad esempio:

kv/apps/rpa/prod/customer-portal

La parte:

customer-portal

deve corrispondere al nome univoco utilizzato nel resto della catena.

Se viene creato accidentalmente:

kv/apps/rpa/prod/customer_portal

mentre il progetto registrato è:

customer-portal

OpenBao considera i due path completamente differenti.

Il risultato può essere che:

l'utente modifica correttamente dei valori nella Web UI;

OpenBao salva correttamente il secret;

l'applicazione continua però a utilizzare i valori precedenti, perché l'Agent sta leggendo un altro path.

Per questo motivo:

Prima di creare un nuovo path in OpenBao, verificare sempre il nome univoco del progetto nel ticket.

Il ticket rappresenta il riferimento operativo da utilizzare per evitare ambiguità.

3. Accesso a OpenBao

Aprire:

https://secretmanager.eagleprojects.cloud

Selezionare l'autenticazione tramite:

OIDC

Verrà effettuato il redirect verso Authentik.

Accedere con il proprio account aziendale.

Una volta autenticati, i permessi disponibili dipendono dai gruppi Authentik di appartenenza.

4. Permessi

Il modello standard prevede due livelli.

Utente standard

Esempio:

RPA

Ha accesso Read Only al proprio namespace.

Può:

navigare nei secret;

visualizzare i valori;

consultare le informazioni disponibili.

Non può:

creare nuovi secret;

modificare valori;

cancellare secret.

Utente Senior

Esempio:

RPA-senior

Ha accesso Read / Write / Delete al proprio namespace.

Può:

visualizzare i secret;

creare nuovi secret;

aggiungere variabili;

modificare valori;

effettuare il normale delete previsto da KV v2.

Le operazioni distruttive definitive rimangono comunque escluse.

5. Struttura dei Secret

Tutti i secret applicativi si trovano sotto:

kv/apps/

La struttura standard è:

kv
└── apps
    └── <gruppo>
        └── <ambiente>
            └── <progetto>

Ad esempio:

kv
└── apps
    └── rpa
        ├── dev
        │   └── customer-portal
        │
        ├── staging
        │   └── customer-portal
        │
        └── prod
            └── customer-portal

Lo stesso progetto può quindi esistere nei diversi ambienti:

kv/apps/rpa/dev/customer-portal
kv/apps/rpa/staging/customer-portal
kv/apps/rpa/prod/customer-portal

ma il nome:

customer-portal

deve rimanere invariato.

6. Creare i Secret di un nuovo progetto

Prima di procedere recuperare dal ticket almeno:

Gruppo
Ambiente
Nome univoco progetto

Esempio:

Gruppo:     RPA
Ambiente:   PROD
Progetto:   customer-portal

Il path OpenBao sarà quindi:

kv/apps/rpa/prod/customer-portal

Procedura

Dalla Web UI OpenBao:

entrare in Secrets;

aprire il secret engine kv;

entrare in apps;

selezionare il proprio gruppo;

selezionare l'ambiente corretto;

creare il nuovo secret utilizzando esattamente il nome progetto indicato nel ticket.

Prima di premere Save, fermarsi e verificare:

Repository = Registry = Ticket = OpenBao

Se uno dei nomi non coincide, non creare il secret finché l'identificazione del progetto non è stata chiarita.

7. Inserire le variabili

All'interno del secret del progetto vengono inserite le coppie:

KEY = VALUE

Ad esempio:

DB_HOST       = database.internal
DB_PORT       = 5432
DB_NAME       = customer_portal
DB_USER       = customer_portal
DB_PASSWORD   = ********
REDIS_HOST    = redis.internal
LOG_LEVEL     = INFO

Ogni chiave rappresenta normalmente una environment variable che verrà resa disponibile all'applicazione.

Regole consigliate

Utilizzare nomi di variabile chiari e coerenti:

DB_HOST
DB_PORT
DB_USER
DB_PASSWORD
API_KEY
SMTP_HOST
SMTP_PORT
LOG_LEVEL

Evitare varianti non necessarie come:

DbHost
db_host
DATABASEHOST

se l'applicazione si aspetta:

DB_HOST

Anche il nome della variabile è case-sensitive dal punto di vista dell'applicazione.

8. Modificare un Secret esistente

Per modificare una variabile:

entrare in Secrets;

aprire kv;

entrare in apps;

selezionare il proprio gruppo;

selezionare l'ambiente;

aprire il progetto;

selezionare la modifica del secret;

modificare esclusivamente i valori necessari;

salvare.

Esempio:

prima:

API_URL=https://old-api.example.local

dopo:

API_URL=https://new-api.example.local

Non è necessario ricreare il progetto o creare un nuovo path.

9. Non rinominare il progetto per modificare un Secret

Una modifica di configurazione non deve mai essere effettuata creando un nuovo nome progetto.

Esempio sbagliato:

customer-portal

diventa:

customer-portal-new

oppure:

customer-portal-v2

solo perché sono cambiate alcune variabili.

Il progetto rimane:

customer-portal

e viene modificato il contenuto del secret esistente.

Un nuovo nome deve essere utilizzato solamente quando è stato effettivamente definito un nuovo identificativo di progetto lungo tutta la catena:

Repository
Registry
Ticket
OpenBao

10. Attenzione all'ambiente

Prima di modificare un secret verificare sempre l'ambiente.

Ad esempio:

kv/apps/rpa/dev/customer-portal

kv/apps/rpa/prod/customer-portal

sono due configurazioni completamente differenti.

Una modifica effettuata su:

dev

non modifica:

prod

e viceversa.

Prima del salvataggio verificare sempre:

GRUPPO
AMBIENTE
PROGETTO

Esempio:

RPA
↓
PROD
↓
customer-portal

11. Cosa succede dopo il salvataggio

Quando viene salvata una modifica:

Utente
   ↓
Web UI OpenBao
   ↓
KV v2
   ↓
nuova versione del Secret
   ↓
OpenBao Agent
   ↓
aggiornamento .env sulla VM
   ↓
applicazione della nuova configurazione

L'utente non deve collegarsi alla VM via SSH per modificare manualmente il file .env.

Il file distribuito sulla VM è gestito automaticamente dal sistema.

12. Non modificare manualmente i file generati sulla VM

I file:

/run/openbao-agent/*.env

sono generati automaticamente da OpenBao Agent.

Non devono essere utilizzati come sorgente principale di configurazione e non devono essere modificati manualmente.

Una modifica manuale:

OpenBao        VALUE=A
VM .env        VALUE=B

crea una configurazione incoerente e, alla successiva sincronizzazione, OpenBao Agent può sovrascrivere nuovamente il file con:

VALUE=A

La sorgente autorevole è sempre:

OpenBao

13. Versionamento

OpenBao utilizza KV v2.

Quando viene modificato un secret, OpenBao crea una nuova versione.

Concettualmente:

Version 1
DB_HOST=db01

Version 2
DB_HOST=db02

Version 3
DB_HOST=db03

Questo consente di mantenere la cronologia delle modifiche.

Per questo motivo, quando è necessario cambiare una configurazione, bisogna modificare il secret esistente, non creare copie con nomi differenti.

14. Aggiungere una nuova variabile a un progetto esistente

Supponiamo che il progetto:

customer-portal

contenga:

DB_HOST
DB_USER
DB_PASSWORD

e che sia necessario aggiungere:

REDIS_HOST

Aprire:

kv/apps/<gruppo>/<ambiente>/customer-portal

modificare il secret e aggiungere:

REDIS_HOST=redis.internal

Il risultato sarà:

DB_HOST
DB_USER
DB_PASSWORD
REDIS_HOST

Non creare:

customer-portal-redis

o un altro secret separato, a meno che questo non faccia parte esplicitamente dell'architettura del progetto.

15. Modificare una variabile

Per modificare:

LOG_LEVEL=INFO

in:

LOG_LEVEL=DEBUG

aprire il secret esistente e cambiare esclusivamente il valore:

LOG_LEVEL

da:

INFO

DEBUG

Non cambiare il nome della chiave.

16. Eliminare una variabile

La rimozione di una chiave deve essere effettuata con maggiore attenzione rispetto alla modifica del suo valore.

Rimuovere:

API_KEY

dal secret significa che, alla successiva applicazione della configurazione, quella variabile potrebbe non essere più disponibile all'applicazione.

Prima di eliminare una variabile verificare quindi che:

l'applicazione non la utilizzi più;

la modifica sia prevista dal ticket;

la configurazione sia coerente con il repository e il deployment corrente.

17. Checklist prima di salvare

Prima di qualsiasi modifica verificare:

Sto lavorando sul gruppo corretto.

Sto lavorando sull'ambiente corretto.

Il nome progetto corrisponde esattamente al ticket.

Il nome progetto è coerente con il repository.

Il nome progetto è coerente con il registry.

Non sto creando accidentalmente un nuovo path.

Le chiavi delle variabili sono corrette.

Sto modificando solamente i valori previsti dal ticket.

La verifica più importante rimane:

Repository
    =
Registry
    =
Ticket
    =
OpenBao

18. Regola di naming

Il nome progetto è un identificativo tecnico

Deve essere trattato come una chiave univoca, non come un titolo.

Quindi:

customer-portal

non equivale a:

Customer Portal
customer_portal
customerportal
customer-portal-prod
customer-portal-new

Se il progetto è stato registrato come:

customer-portal

deve essere utilizzato:

customer-portal

ovunque.

19. In caso di dubbio

Se non è chiaro quale nome utilizzare, non creare un nuovo secret.

Verificare prima il ticket e la corrispondenza con:

Repository
Registry
Ticket

e solo successivamente creare o modificare:

OpenBao

È preferibile fermare una modifica per verificare il naming piuttosto che creare un secondo path che rappresenta accidentalmente lo stesso progetto.

20. Riepilogo operativo

Per creare una nuova configurazione:

Controlla ticket
      ↓
verifica nome progetto
      ↓
verifica Repository / Registry
      ↓
entra in OpenBao
      ↓
kv/apps/<gruppo>/<ambiente>/<progetto>
      ↓
inserisci KEY=VALUE
      ↓
Save

Per modificare una configurazione:

Ticket
   ↓
identifica progetto e ambiente
   ↓
apri il path ESISTENTE
   ↓
modifica KEY/VALUE
   ↓
Save
   ↓
OpenBao Agent distribuisce la modifica

Regola finale

Un progetto deve avere un solo nome tecnico. Quel nome deve accompagnarlo senza variazioni dal repository al registry, dal ticket fino a OpenBao.

ONE PROJECT
    ↓
ONE UNIQUE NAME
    ↓
Repository
    ↓
Registry
    ↓
Ticket
    ↓
OpenBao

Questa coerenza è necessaria affinché automazioni, deployment e distribuzione dei secret possano identificare senza ambiguità la stessa applicazione.