Gérer les différences entre les environnements à l’aide des paramètres Bicep

7 minutes

Vous avez déjà fait connaissance avec les paramètres Bicep. Ils vous permettent de spécifier des valeurs qui peuvent changer selon les déploiements de vos fichiers Bicep.

Souvent, vous utilisez des paramètres pour prendre en charge les différences entre vos environnements. Par exemple, dans vos environnements hors production, vous voulez souvent déployer des références SKU abordables de vos ressources Azure. En production, vous voulez déployer des références SKU qui offrent de meilleures performances. Vous voulez peut-être aussi utiliser des noms différents pour les ressources dans chaque environnement.

Quand vous déployez votre fichier Bicep, vous fournissez des valeurs pour chaque paramètre. Vous avez plusieurs options pour spécifier les valeurs de chaque paramètre à partir de votre workflow et pour spécifier des valeurs distinctes pour chaque environnement. Dans cette unité, vous découvrez les approches qui permettent de spécifier les valeurs de paramètre Bicep dans un workflow de déploiement.

Fichiers de paramètres

Un fichier de paramètres est un fichier au format JSON qui liste les valeurs de paramètre à utiliser pour chaque environnement. Vous envoyez le fichier de paramètres à Azure Resource Manager quand vous envoyez le déploiement.

Voici un exemple de fichier de paramètres :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "reviewApiUrl": {
      "value": "https://sandbox.contoso.com/reviews"
    }
  }
}

Les fichiers de paramètres peuvent être validés dans votre dépôt Git en même temps que votre fichier Bicep. Vous pouvez ensuite référencer le fichier de paramètres dans le modèle de workflow où vous exécutez votre déploiement.

Pensez à établir une stratégie de nommage d’environnement cohérente pour les fichiers de paramètres. Par exemple, vous pouvez nommer vos fichiers de paramètres parameters.ENVIRONMENT_NAME.json, dans notre exemple : parameters.Production.json. Vous pouvez ensuite utiliser une entrée de modèle de workflow pour sélectionner automatiquement le fichier de paramètres approprié en fonction d’une valeur d’entrée.

on:
  workflow_call:
    inputs:
      environmentType:
        required: true
        type: string
      # ...

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    # ...
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json

Quand vous utilisez des fichiers de paramètres, vos fichiers YAML de workflow n’ont pas besoin de passer une liste de paramètres individuellement à vos étapes de déploiement. Ce qui est particulièrement utile quand vous avez un grand nombre de paramètres.

Un fichier de paramètres réunit les valeurs de paramètre dans un seul fichier JSON. Les fichiers de paramètres font également partie de votre dépôt Git et peuvent donc être versionnés de la même façon que le reste de votre code.

Important

Les fichiers de paramètres ne doivent pas être utilisés pour les valeurs sécurisées. Il n’y a aucun moyen de protéger les valeurs des secrets dans les fichiers de paramètres et vous ne devez jamais valider de secrets dans votre dépôt Git.

Variable de workflow

GitHub Actions vous permet de stocker des variables de workflow, qui sont utiles pour les valeurs qui peuvent différer d’un environnement à l’autre. Elles sont également utiles pour les valeurs que vous voulez définir une seule fois et réutiliser dans votre workflow.

Variables définies dans un fichier YAML

Vous pouvez définir des variables et leurs valeurs dans un fichier YAML. Cela vous permet de réutiliser la même valeur plusieurs fois. Vous pouvez définir une variable pour un workflow entier, pour un travail ou pour une seule étape :

env:
  MyVariable1: value1

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyVariable2: value2
    steps:
    - run: echo Hello world!
      env:
        MyVariable3: value3

Secrets définis dans l’interface web

Tout comme les fichiers de paramètres Bicep, les fichiers YAML ne conviennent pas pour les secrets. Définissez plutôt les secrets en utilisant l’interface web GitHub. Vous pouvez changer les valeurs de variable à tout moment et le workflow lit les valeurs mises à jour à sa prochaine exécution. GitHub Actions tente de masquer les valeurs des secrets dans les journaux de workflow. Vous pouvez donc stocker des valeurs que votre fichier Bicep accepte ensuite comme paramètres avec l’élément décoratif @secure().

Avertissement

Par défaut, GitHub Actions obfusque les valeurs des variables secrètes dans les journaux de workflow, mais vous devez également suivre les bonnes pratiques. Vos étapes de workflow ont accès aux valeurs des secrets. Si votre workflow inclut une étape qui ne gère pas de secret sécurisé, il est possible que la valeur de secret soit affichée dans les journaux de workflow. Vous devez toujours examiner attentivement les modifications apportées à un fichier de définition de workflow pour vérifier que les secrets ne seront pas mal gérés.

Quand vous créez un secret, GitHub vous permet de choisir s’il doit être étendu à l’ensemble de votre dépôt Git ou à un environnement spécifique. Les secrets délimités à l’environnement respectent les règles de protection que vous configurez sur vos environnements. Par conséquent, si vous configurez une règle de réviseur obligatoire, un flux de travail ne peut pas accéder aux valeurs des secrets tant que l’utilisateur GitHub spécifié n’a pas approuvé votre pipeline pour déployer dans cet environnement.

Les secrets au niveau de l’environnement peuvent être utiles, mais ils ne fonctionnent pas facilement avec la validation préalable d’Azure Resource Manager ou les opérations de simulation. Ces opérations doivent communiquer avec Azure et ont donc besoin d’une identité de charge de travail. En général, vous voulez fournir l’approbation du déploiement après la validation préalable ou les opérations de simulation, pour que les changements que vous déployez aient un niveau de confiance élevé. Par conséquent, si vous utilisez des secrets au niveau de l’environnement, le processus de révision humaine se produit trop tôt dans le workflow.

Pour cette raison, vous n’utilisez pas de secrets au niveau de l’environnement dans les exercices de ce module. À la place, vous créez des secrets au niveau du dépôt avec des noms prévisibles qui intègrent le nom de l’environnement. Cela permet à votre workflow d’identifier le secret à utiliser pour chaque environnement. Dans vos propres workflows, vous pouvez choisir d’utiliser des secrets au niveau du dépôt, au niveau de l’environnement ou même un mélange des deux.

Notes

Vous pouvez également étendre les secrets aux organisations GitHub. Bien que cela ne fasse pas partie des objectifs de ce module, nous proposons des liens vers plus d’informations dans le récapitulatif.

Utiliser des variables dans votre workflow

La façon dont vous accédez à la valeur d’une variable dans votre workflow dépend du type de variable.

Type	Syntaxe
Variables définies dans le même fichier	`${{ env.VARIABLE_NAME }}`
Entrées dans un workflow appelé	`${{ inputs.INPUT_NAME }}`
Secrets	`${{ secrets.SECRET_NAME }}`

Par exemple, quand vous exécutez un déploiement Bicep, vous pouvez utiliser des secrets pour spécifier l’identité de charge de travail Azure à utiliser, une entrée de workflow appelée pour spécifier le nom du groupe de ressources et une variable pour spécifier la valeur d’un paramètre :

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MyParameter: value-of-parameter
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: myParameter=${{ env.MyParameter }}

Quelle est la meilleure approche ?

Vous avez vu plusieurs façons de gérer les paramètres dont votre fichier Bicep a besoin pour votre déploiement. Vous devez comprendre quand utiliser l’une ou l’autre de ces approches.

Éviter les paramètres inutiles

Les paramètres vous aident à rendre vos fichiers Bicep réutilisables, mais le risque est d’en définir un trop grand nombre. Quand vous déployez un fichier Bicep, vous devez fournir une valeur pour chaque paramètre. Dans les déploiements complexes sur plusieurs environnements, le nombre de valeurs de paramètre individuelles devient difficile à gérer.

Rendez facultatifs les paramètres là où vous le pouvez et utilisez des valeurs par défaut qui s’appliquent à la plupart de vos environnements. Vous pouvez alors éviter à vos workflows de passer des valeurs pour les paramètres.

Par ailleurs, gardez à l’esprit que les paramètres sont souvent utilisés dans Bicep quand des ressources doivent se connecter à d’autres ressources. Par exemple, si vous avez un site web qui doit se connecter à un compte de stockage, vous devez fournir le nom et la clé d’accès du compte de stockage. Les clés sont des valeurs sécurisées. Toutefois, tenez compte de ces autres approches quand vous déployez cette combinaison de ressources :

Utilisez l’identité managée du site web pour accéder au compte de stockage. Quand vous créez une identité managée, Azure génère et gère automatiquement ses informations d’identification. Cette approche simplifie les paramètres de connexion. Cela signifie aussi que vous n’avez pas du tout besoin de gérer les secrets, c’est donc l’option la plus sécurisée.
Déployez le compte de stockage et le site web ensemble dans le même modèle Bicep. Utilisez des modules Bicep pour maintenir ensemble le site web et les ressources de stockage. Vous pouvez ensuite rechercher automatiquement les valeurs du nom et de la clé du compte de stockage dans le code Bicep au lieu de les passer dans des paramètres.
Ajoutez les détails du compte de stockage à un coffre de clés sous forme de secret. Le code du site web charge alors la clé d’accès directement à partir du coffre. Cette approche évite de gérer la clé dans le workflow.

Utiliser des variables de workflow pour les petits ensembles de paramètres

Si vous avez seulement quelques paramètres pour vos fichiers Bicep, définissez des variables dans votre fichier YAML.

Utiliser des fichiers de paramètres pour les grands ensembles de paramètres

Si vous avez un grand ensemble de paramètres pour vos fichiers Bicep, utilisez des fichiers de paramètres pour regrouper les valeurs non sécurisées pour chaque environnement. Ensuite, chaque fois que vous devez changer les valeurs, vous pouvez mettre à jour le fichier de paramètres et valider votre changement.

Cette approche permet de simplifier vos étapes de workflow, car vous n’avez pas besoin de définir explicitement la valeur de chaque paramètre.

Stocker les secrets de manière sécurisée

Utilisez un processus approprié pour stocker et gérer les secrets. Utilisez les secrets GitHub pour stocker des secrets dans votre dépôt GitHub ou utilisez Key Vault pour stocker des secrets dans Azure.

Pour les paramètres sécurisés, n’oubliez pas de les passer explicitement un par un dans vos étapes de déploiement.

GitHub peut rechercher automatiquement dans votre dépôt les secrets qui ont été accidentellement validés, afin que vous puissiez en être averti. Vous pouvez ensuite supprimer et faire pivoter les secrets. Nous ajoutons dans le récapitulatif des liens vers plus d’informations sur cette fonctionnalité.

Combiner les approches

Il est courant de combiner plusieurs approches pour gérer les paramètres. Par exemple, vous pouvez stocker la plupart de vos valeurs de paramètre dans des fichiers de paramètres, puis définir les valeurs sécurisées dans un secret. L’exemple suivant illustre la combinaison :

on:
  workflow_dispatch:
    inputs:
      environmentType:
        required: true
        type: string
      resourceGroupName:
        required: true
        type: string
    secrets:
      AZURE_CLIENT_ID:
        required: true
      AZURE_TENANT_ID:
        required: true
      AZURE_SUBSCRIPTION_ID:
        required: true
      MySecureParameter:
        required: true

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      with:
        failOnStdErr: false
        resourceGroupName: ${{ inputs.resourceGroupName }}
        template: ./deploy/main.bicep
        parameters: >
          ./deploy/azuredeploy.parameters.${{ inputs.environmentType }}.json
          mySecureParameter=${{ secrets.MySecureParameter }}

Conseil

À la fin de cet exemple, la valeur parameters est fournie sous la forme de chaîne multiligne YAML en utilisant le caractère >. Le fichier YAML est alors plus facile à lire. Cela équivaut à ajouter la valeur entière sur une seule ligne.