Groupes de variables d'environnement partagées

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 groupe de variables d'environnement contient des valeurs que plusieurs projets Orbit doivent partager, comme une clé API partagée ou des identifiants de base de données, au même endroit. Liez le groupe aux projets qui en ont besoin et chacune de leurs compilations obtiendra ces variables, de sorte que la rotation d'une clé se fait en une modification plutôt que six.

Où vivent les groupes Env

Ouvrez Orbit et choisissez Env groups dans la navigation de niveau supérieur. La page s'intitule Shared env var groups et les décrit comme des groupes au niveau du compte partagés entre plusieurs projets Orbit.

Les groupes se situent au-dessus des projets. Les variables propres à un projet vivent toujours sur son onglet Env vars : consultez Environment Variables in Orbit.

Quand utiliser un groupe

Le test est simple : la même valeur est-elle collée dans plus d'un projet ?

Bons candidats :

Une clé d'analyse partagée ou de suivi des erreurs utilisée par chaque interface frontale.
Une chaîne de connexion de réplica de lecture utilisée par plusieurs outils internes.
Une clé API tierce pour un service avec lequel l'ensemble du compte communique.
Un jeton client de drapeau de fonctionnalité commun.

Mauvais candidats :

Tout ce qui est spécifique à un projet. Il appartient à ce projet.
Tout ce qui diffère entre la production et l'aperçu. Les groupes ne sont pas par environnement, donc une valeur qui change selon l'environnement appartient aux variables d'environnement du projet.

Créer un groupe

Cliquez sur New group.
Donnez-lui un Group name, jusqu'à 64 caractères. Nommez-le d'après ce qu'il contient, par exemple le service auquel appartiennent les identifiants.
Ajoutez une Description facultative.
Cliquez sur Create group.

Un compte peut contenir jusqu'à 20 groupes. Lorsque vous êtes à la limite, le bouton affiche (limit reached) et la création d'un autre est refusée.

La création, l'édition et la suppression d'un groupe nécessitent un rôle propriétaire ou administrateur sur le compte. Les développeurs et les spectateurs peuvent voir les groupes mais pas les modifier, c'est intentionnel : une édition de groupe change plusieurs projets à la fois.

Ajouter des variables

Ouvrez le groupe et utilisez la section Variables :

Cliquez sur Add variable.
Entrez la clé et la valeur.
Cochez Mark as secret pour tout ce qui est sensible.
Cliquez sur Save group.

Une variable marquée comme secrète est stockée chiffrée et sa valeur n'est pas renvoyée au panneau après. La liste affiche la clé et un indicateur Marked as secret (hidden) au lieu de la valeur. Les valeurs non secrètes restent visibles pour que vous puissiez les vérifier d'un coup d'œil.

Marquer une variable comme secrète signifie que vous ne pouvez pas la relire depuis le panneau. C'est le but, mais cela signifie aussi que le groupe n'est pas un gestionnaire de mots de passe. Conservez la copie faisant autorité où votre équipe garde déjà les identifiants, et traitez le groupe comme le mécanisme de distribution.

Pour modifier la valeur d'un secret, saisissez le nouveau et enregistrez. Pour supprimer une variable, cliquez sur Remove sur sa ligne et enregistrez.

Lier des projets

La section Linked projects répertorie tous les projets du compte. Cliquez sur un projet pour le lier ou le délier ; les projets liés sont mis en surbrillance. Enregistrez le groupe à appliquer.

Un groupe sans projets liés ne fait rien, et la section indique No projects yet jusqu'à ce que vous en liiez un.

Les variables de groupe sont injectées au moment de la compilation, de sorte que la liaison d'un projet affecte sa prochaine compilation, pas le déploiement actuellement en direct. Si vous avez besoin du changement maintenant, redéployez : consultez Deploying Your Project.

Priorité

La règle est énoncée sur la page : les variables de groupe sont injectées au moment de la compilation, et les variables au niveau du projet et au niveau de l'environnement ont priorité sur les variables de groupe.

En d'autres termes, le plus spécifique gagne :

Variables au niveau de l'environnement, priorité la plus élevée.
Variables au niveau du projet.
Variables de groupe, priorité la plus basse.

Cet ordre est utile plutôt que simplement une technicité. Définissez la valeur par défaut partagée dans le groupe, et remplacez-la sur le seul projet qui a besoin de quelque chose de différent, sans supprimer ce projet du groupe. Consultez Environment Variables Per Environment pour la couche d'environnement.

Cela explique également la confusion la plus courante avec les groupes : vous modifiez le groupe, redéployez, et rien ne change, parce que le projet a sa propre variable avec la même clé qui gagne silencieusement. Vérifiez d'abord l'onglet Env vars du projet lui-même lorsqu'une valeur de groupe semble être ignorée.

Rotation d'une identité partagée

C'est le flux pour lequel les groupes existent :

Créez la nouvelle identité chez le fournisseur en laissant l'ancienne active.
Modifiez la valeur dans le groupe et enregistrez.
Redéployez chaque projet lié, ou attendez son prochain déploiement.
Confirmez que chaque projet fonctionne avec la nouvelle identité.
Révoquez l'ancienne identité chez le fournisseur.

Faire l'étape 5 en premier vous donne une fenêtre où chaque projet lié est cassé à la fois, ce qui est précisément le risque qu'une identité partagée concentre.

Supprimer un groupe

Cliquez sur delete sur le groupe. La confirmation est spécifique sur la conséquence : les futures compilations perdront ces variables, et les compilations déjà terminées ne sont pas affectées.

La suppression délinkèrise aussi chaque projet. Cela signifie que les déploiements en cours continuent avec les valeurs avec lesquelles ils ont été compilés, et la prochaine compilation de chaque projet lié arrive sans elles. Si ces variables sont requises, cette compilation échouera ou l'application se comportera mal à l'exécution.

Avant la suppression, délinkèrisez les projets un à la fois et redéployez chacun, de sorte que vous découvriez lesquels dépendent réellement du groupe avant qu'ils ne le perdent tous.

Conseils pratiques

Gardez les groupes petits et ciblés. Un groupe par service externe vaut mieux qu'un groupe géant « partagé », car cela vous permet de lier exactement les projets qui ont besoin de chaque chose.

Nommez les clés de la même manière partout. Si un projet lit SENTRY_DSN et un autre lit SENTRY_KEY, un groupe partagé ne peut pas vous aider. Standardisez d'abord les noms.

Ne mettez pas les identifiants de production dans un groupe lié à des projets avec des aperçus publics. Les variables de groupe atteignent chaque compilation d'un projet lié, aperçus compris.

Dépannage

Une compilation ne voit pas la variable. Confirmez que le projet est lié et enregistré, et que la compilation a été exécutée après la liaison. Les variables de groupe s'appliquent à partir de la prochaine compilation.

La valeur est incorrecte à l'exécution. Une variable au niveau du projet ou au niveau de l'environnement avec la même clé la remplace. Vérifiez l'onglet Env vars du projet.

Create group est indisponible. Vous êtes à la limite de 20 groupes, ou votre rôle de compte n'est pas propriétaire ou administrateur.

La valeur d'un secret s'affiche en blanc. C'est correct. Les valeurs secrètes ne sont pas renvoyées au panneau après l'enregistrement.

Un projet s'est cassé après une édition de groupe. Restaurez la valeur dans le groupe et redéployez, puis déterminez quel projet était en désaccord. Rolling Back a Deployment remet le site en direct en santé pendant que vous le faites.

Où aller ensuite

Environment Variables in Orbit pour les variables au niveau du projet.
Environment Variables Per Environment pour la couche de remplacement.
Orbit Project Settings pour le reste de la configuration d'un projet.