Gruppi di Variabili di Ambiente Condivise

An environment variable group holds values that several Orbit projects need, such as a shared API key or a database credential, in one place. Link the group to the projects that need it and every…

Un gruppo di variabili di ambiente contiene valori che più progetti Orbit necessitano, come una chiave API condivisa o una credenziale di database, in un unico posto. Collega il gruppo ai progetti che ne hanno bisogno e ogni loro build riceverà quelle variabili, quindi ruotare una chiave è una modifica anziché sei.

Dove si trovano i gruppi di variabili di ambiente

Apri Orbit e scegli Env groups dalla navigazione di primo livello. La pagina si intitola Shared env var groups e li descrive come gruppi a livello di account condivisi tra più progetti Orbit.

I gruppi si trovano al di sopra dei progetti. Le variabili proprie di un progetto rimangono comunque nella sua scheda Env vars: vedi Environment Variables in Orbit.

Quando utilizzare un gruppo

Il test è semplice: lo stesso valore viene incollato in più di un progetto?

Buoni candidati:

Una chiave di analisi condivisa o di tracciamento degli errori utilizzata da ogni front end.
Una stringa di connessione della replica di lettura utilizzata da diversi strumenti interni.
Una chiave API di terze parti per un servizio con cui comunica l'intero account.
Un token client di feature flag comune.

Cattivi candidati:

Qualsiasi cosa specifica di un progetto. Appartiene a quel progetto.
Qualsiasi cosa che differisce tra production e preview. I gruppi non sono per ambiente, quindi un valore che cambia a seconda dell'ambiente appartiene alle variabili di ambiente proprie del progetto.

Creazione di un gruppo

Fai clic su New group.
Assegnagli un Group name, fino a 64 caratteri. Assegnagli un nome in base al contenuto, ad esempio il servizio a cui appartengono le credenziali.
Aggiungi una Description opzionale.
Fai clic su Create group.

Un account può contenere fino a 20 gruppi. Quando raggiungi il limite, il pulsante mostra (limit reached) e la creazione di un altro viene rifiutata.

La creazione, modifica e cancellazione di un gruppo richiede un ruolo owner o admin sull'account. Gli sviluppatori e i visualizzatori possono vedere i gruppi ma non modificarli, il che è intenzionale: una modifica del gruppo modifica più progetti contemporaneamente.

Aggiunta di variabili

Apri il gruppo e usa la sezione Variables:

Fai clic su Add variable.
Immetti la chiave e il valore.
Spunta Mark as secret per qualsiasi cosa sensibile.
Fai clic su Save group.

Una variabile contrassegnata come secret viene archiviata crittografata e il suo valore non viene restituito al panel in seguito. L'elenco mostra la chiave e un indicatore Marked as secret (hidden) al posto del valore. I valori non secret rimangono visibili così puoi verificarli a colpo d'occhio.

Contrassegnare una variabile come secret significa che non puoi leggerla dal panel. Questo è l'obiettivo, ma significa anche che il gruppo non è un password manager. Mantieni la copia autorevole dove il tuo team conserva già le credenziali e tratta il gruppo come il meccanismo di distribuzione.

Per modificare il valore di un secret, digita quello nuovo e salva. Per rimuovere una variabile, fai clic su Remove sulla sua riga e salva.

Collegamento dei progetti

La sezione Linked projects elenca ogni progetto nell'account. Fai clic su un progetto per collegarlo o scollegarlo; i progetti collegati sono evidenziati. Salva il gruppo per applicare.

Un gruppo senza progetti collegati non fa nulla e la sezione mostra No projects yet finché non colleghi uno.

Le variabili di gruppo vengono inserite al momento della build, quindi collegare un progetto influisce sulla sua prossima build, non sulla distribuzione attualmente live. Se hai bisogno della modifica ora, ridistribuisci: vedi Deploying Your Project.

Precedenza

La regola è stata dichiarata nella pagina: le variabili di gruppo vengono inserite al momento della build e le variabili a livello di progetto e a livello di ambiente hanno la precedenza sulle variabili di gruppo.

In altre parole, vince l'elemento più specifico:

Variabili a livello di ambiente, priorità più alta.
Variabili a livello di progetto.
Variabili di gruppo, priorità più bassa.

Questo ordine è utile e non solo una tecnicità. Imposta il valore predefinito condiviso nel gruppo e sovrascrivi su un progetto che necessita qualcosa di diverso, senza rimuovere quel progetto dal gruppo. Vedi Environment Variables Per Environment per il livello di ambiente.

Spiega anche la confusione più comune con i gruppi: modifichi il gruppo, ridistribuisci e nulla cambia, perché il progetto ha la sua variabile con la stessa chiave che vince silenziosamente. Controlla prima la scheda Env vars propria del progetto quando un valore di gruppo sembra essere ignorato.

Rotazione di una credenziale condivisa

Questo è il workflow per cui i gruppi esistono:

Crea la nuova credenziale dal provider, lasciando attiva quella vecchia.
Modifica il valore nel gruppo e salva.
Ridistribuisci ogni progetto collegato, o attendi il suo prossimo deploy.
Conferma che ogni progetto funziona con la nuova credenziale.
Revoca la credenziale vecchia dal provider.

Eseguire il passaggio 5 per primo ti dà una finestra in cui ogni progetto collegato è interrotto contemporaneamente, il che è esattamente il rischio che una credenziale condivisa concentra.

Eliminazione di un gruppo

Fai clic su delete nel gruppo. La conferma è specifica sulla conseguenza: i build futuri perderanno queste variabili e i build già completati non saranno interessati.

L'eliminazione scollega anche ogni progetto. Ciò significa che le distribuzioni in esecuzione continueranno con i valori con cui sono state costruite e il prossimo build di ogni progetto collegato verrà a mancare. Se quelle variabili sono necessarie, il build fallirà o l'app si comporterà male al runtime.

Prima di eliminare, scollega i progetti uno alla volta e ridistribuisci ognuno, così scoprirai quali dipendono effettivamente dal gruppo prima che tutti lo perdano.

Consigli pratici

Mantieni i gruppi piccoli e mirato. Un gruppo per servizio esterno batte un grande gruppo "condiviso", perché ti permette di collegare esattamente i progetti che necessitano di ogni cosa.

Assegna un nome alle chiavi nello stesso modo ovunque. Se un progetto legge SENTRY_DSN e un altro legge SENTRY_KEY, un gruppo condiviso non può aiutarti. Standardizza prima i nomi.

Non mettere credenziali production in un gruppo collegato a progetti con preview pubbliche. Le variabili di gruppo raggiungono ogni build di un progetto collegato, anteprime incluse.

Risoluzione dei problemi

Un build non vede la variabile. Conferma che il progetto è collegato e salvato e che il build è stato eseguito dopo il collegamento. Le variabili di gruppo si applicano dal prossimo build.

Il valore è sbagliato al runtime. Una variabile a livello di progetto o a livello di ambiente con la stessa chiave la sta sovrascrivendo. Controlla la scheda Env vars del progetto.

Create group non è disponibile. Hai raggiunto il limite di 20 gruppi, oppure il tuo ruolo di account non è owner o admin.

Il valore di un secret viene visualizzato come vuoto. Questo è corretto. I valori secret non vengono restituiti al panel dopo il salvataggio.

Un progetto si è interrotto dopo una modifica del gruppo. Rollback del valore nel gruppo e ridistribuisci, quindi scopri quale progetto era in disaccordo. Rolling Back a Deployment rende il sito in esecuzione sano mentre lo fai.

Dove andare dopo

Environment Variables in Orbit per le variabili a livello di progetto.
Environment Variables Per Environment per il livello di override.
Orbit Project Settings per il resto della configurazione di un progetto.