Behandeln von Unterschieden zwischen Umgebungen mithilfe von Bicep-Parametern

  • 7 Minuten

Sie haben bereits Informationen zu Bicep-Parametern erhalten. Sie helfen Ihnen, Werte anzugeben, die sich zwischen Bereitstellungen Ihrer Bicep-Dateien ändern können.

Parameter werden häufig verwendet, um die Unterschiede zwischen Ihren Umgebungen zu unterstützen. Beispielsweise möchten Sie in Ihren Nicht-Produktionsumgebungen häufig kostengünstige SKUs Ihrer Azure-Ressourcen bereitstellen. In der Produktion möchten Sie SKUs bereitstellen, die eine bessere Leistung aufweisen. Möglicherweise möchten Sie in jeder Umgebung unterschiedliche Namen für Ressourcen verwenden.

Wenn Sie Ihre Bicep-Datei bereitstellen, geben Sie Werte für jeden Parameter an. Es gibt mehrere Optionen, wie Sie die Werte für die einzelnen Parameter im Workflow angeben und wie Sie separate Werte für die jeweilige Umgebung angeben. In dieser Lerneinheit erfahren Sie mehr über Verfahren zum Angeben von Bicep-Parameterwerten in einem Bereitstellungsworkflow.

Parameterdateien

Eine Parameterdatei ist eine Datei im JSON-Format, die die Parameterwerte auflistet, die Sie für jede Umgebung verwenden möchten. Sie übermitteln die Parameterdatei an Azure Resource Manager, wenn Sie die Bereitstellung übermitteln.

Hier sehen Sie eine Beispielparameterdatei:

{
  "$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"
    }
  }
}

Parameterdateien können zusammen mit Ihrer Bicep-Datei in Ihr Git-Repository übertragen werden. Sie können dann auf die Parameterdatei in Ihrer Workflowvorlage verweisen, in der Sie die Bereitstellung ausführen.

Es empfiehlt sich, eine konsistente Umgebungsbenennungsstrategie für Parameterdateien einzurichten. Beispielsweise könnten Sie Ihre Parameterdateien parameters.ENVIRONMENT_NAME.json benennen, wie parameters.Production.json. Anschließend können Sie eine Eingabe der Workflowvorlage verwenden, um basierend auf einem Eingabewert automatisch die richtige Parameterdatei auszuwählen.

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

Wenn Sie Parameterdateien verwenden, müssen Ihre YAML-Dateien für den Workflow keine Liste von Parametern enthalten, die einzeln an Ihre Bereitstellungsschritte übergeben werden müssen. Dies ist besonders hilfreich, wenn Sie über eine große Anzahl von Parametern verfügen.

Eine Parameterdatei hält die Parameterwerte in einer einzelnen JSON-Datei zusammen. Die Parameterdateien sind auch Teil Ihres Git-Repositorys, sodass sie auf die gleiche Weise wie der gesamte andere Code versioniert werden können.

Wichtig

Parameterdateien sollten nicht für sichere Werte verwendet werden. Es gibt keine Möglichkeit, die Werte der Geheimnisse in den Parameterdateien zu schützen, und Sie sollten niemals Geheimnisse in Ihr Git-Repository committen.

Workflow-Variablen

GitHub Actions bietet die Möglichkeit, Workflowvariablen zu speichern. Diese sind für Werte nützlich, die in Umgebungen verschieden sein können. Sie sind auch für Werte nützlich, die Sie nur einmal definieren und dann im gesamten Workflow wiederverwenden möchten.

In einer YAML-Datei definierte Variablen

Sie können in einer YAML-Datei Variablen definieren und deren Werte festlegen. Dies ist nützlich, wenn Sie denselben Wert mehrmals wiederverwenden müssen. Sie können eine Variable für einen ganzen Workflow, für einen Auftrag oder für einen einzelnen Schritt definieren:

env:
  MyVariable1: value1

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

In der Weboberfläche definierte Geheimnisse

YAML-Dateien sind ebenso wie Bicep-Parameterdateien nicht für Geheimnisse geeignet. Stattdessen können Sie Geheimnisse mithilfe der GitHub-Weboberfläche definieren. Sie können die Variablenwerte jederzeit ändern. Der Workflow verwendet die aktualisierten Werte bei der nächsten Ausführung. GitHub Actions versucht, die Werte der Geheimnisse in den Workflowprotokollen auszublenden. Dies bedeutet, dass Sie Werte speichern können, die Ihre Bicep-Datei dann als Parameter mit dem Decorator @secure() akzeptiert.

Warnung

GitHub Actions verschleiert standardmäßig Variablenwerte mit Geheimnissen in Workflowprotokollen, trotzdem sollten Sie darüber hinaus bewährte Methoden befolgen. Ihre Workflowschritte haben Zugriff auf die Werte von Geheimnissen. Wenn Ihr Workflow einen Schritt enthält, der ein Geheimnis nicht sicher verarbeitet, besteht die Möglichkeit, dass der Geheimniswert in den Workflowprotokollen angezeigt wird. Sie sollten sämtliche Änderungen an einer Workflowdefinitionsdatei immer sorgfältig überprüfen, um sicherzustellen, dass die Geheimnisse richtig behandelt werden.

Wenn Sie ein Geheimnis erstellen, bietet GitHub die Möglichkeit, auszuwählen, ob Sie es für das ganze Git-Repository oder für eine bestimmte Umgebung festlegen möchten. Umgebungsbezogene geheime Schlüssel berücksichtigen die Schutzregeln, die Sie in Ihren Umgebungen konfigurieren. Wenn Sie also eine erforderliche Prüferregel konfigurieren, kann ein Workflow erst auf die geheimen Werte zugreifen, wenn der angegebene GitHub-Benutzer Ihre Pipeline für die Bereitstellung in dieser Umgebung genehmigt hat.

Umgebungsspezifische Geheimnisse können hilfreich sein, aber sie lassen sich nicht einfach mit der Preflightüberprüfung von Azure Resource Manager oder mit Was-wäre-wenn-Vorgängen verwenden. Für diese Vorgänge ist eine Kommunikation mit Azure erforderlich, d. h. sie benötigen eine Workloadidentität. Im Allgemeinen sollten Sie die Bereitstellungsgenehmigung nach Abschluss der Preflightvalidierung oder der Was-wäre-wenn-Vorgänge vorsehen, sodass Sie den von Ihnen bereitgestellten Änderungen in hohem Maß vertrauen können. Wenn Sie also umgebungsbezogene Geheimnisse verwenden, wird der Überprüfungsprozess durch Benutzer in Ihrem Workflow zu früh ausgeführt.

Aus diesem Grund werden in den Übungen dieses Moduls keine umgebungsbezogenen Geheimnisse verwendet. Stattdessen erstellen Sie repositorybezogene Geheimnisse mit voraussehbaren Namen, die den Umgebungsnamen enthalten. Dadurch kann Ihr Workflow das richtige Geheimnis feststellen, das für die jeweilige Umgebung verwendet werden soll. In Ihren eigenen Workflows können Sie sich dafür entscheiden, repositorybezogene Geheimnisse, umgebungsbezogene Geheimnisse oder sogar eine Mischung aus beiden zu verwenden.

Hinweis

Sie können Geheimnisse auch auf GitHub-Organisationen beziehen. Obwohl dies für dieses Modul nicht relevant ist, finden Sie in der Zusammenfassung Links zu weiteren Informationen.

Verwenden von Variablen in Ihrem Workflow

Wie Sie auf den Wert einer Variablen in Ihrem Workflow zugreifen, hängt vom Typ der Variablen ab.

type Syntax
Variablen, die in derselben Datei definiert sind ${{ env.VARIABLE_NAME }}
Eingaben für einen aufgerufenen Workflow ${{ inputs.INPUT_NAME }}
Geheimnisse ${{ secrets.SECRET_NAME }}

Wenn Sie beispielsweise eine Bicep-Bereitstellung ausführen, können Sie ein Geheimnis zum Angeben der zu verwendenden Azure-Workloadidentität, eine Eingabe für den aufgerufene Workflow zum Angeben des Ressourcengruppennamens und eine Variable zum Angeben des Werts eines Parameters verwenden:

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 }}

Was ist der beste Ansatz?

Sie haben verschiedene Möglichkeiten kennengelernt, um die Parameter zu behandeln, die Ihre Bicep-Datei für Ihre Bereitstellung benötigt. Es ist hilfreich zu verstehen, wann Sie welchen Ansatz verwenden können.

Vermeiden unnötiger Parameter

Parameter helfen Ihnen dabei, Ihre Bicep-Dateien wiederverwendbar zu machen, aber es ist einfach, zu viele Parameter zu definieren. Wenn Sie eine Bicep-Datei bereitstellen, müssen Sie einen Wert für jeden Parameter angeben. Bei komplexen Bereitstellungen für mehrere Umgebungen ist es schwierig, eine große Gruppe einzelner Parameterwerte zu verwalten.

Erwägen Sie, Parameter optional zu machen, wo dies möglich ist, und verwenden Sie Standardwerte, die für die meisten Umgebungen gelten. Sie können so vermeiden, dass Ihre Workflows Werte für die Parameter übergeben müssen.

Beachten Sie außerdem, dass Parameter häufig in Bicep verwendet werden, wenn Ressourcen eine Verbindung mit anderen Ressourcen herstellen müssen. Wenn Sie beispielsweise über eine Website verfügen, die eine Verbindung mit einem Speicherkonto herstellen muss, müssen Sie den Namen des Speicherkontos und den Zugriffsschlüssel angeben. Schlüssel sind sichere Werte. Berücksichtigen Sie jedoch diese anderen Ansätze, wenn Sie diese Kombination von Ressourcen bereitstellen:

  • Verwenden Sie die verwaltete Identität der Website, um auf das Speicherkonto zuzugreifen. Wenn Sie eine verwaltete Identität erstellen, generiert und verwaltet Azure automatisch die zugehörigen Anmeldeinformationen. Dieser Ansatz vereinfacht die Verbindungseinstellungen. Dies bedeutet auch, dass Sie keine Geheimnisse verarbeiten müssen, daher ist dies die sicherste Option.
  • Stellen Sie das Speicherkonto und die Website zusammen in derselben Bicep-Vorlage bereit. Verwenden Sie Bicep-Module, um Website- und Speicherressourcen zusammenzuhalten. Anschließend können Sie automatisch die Werte für den Speicherkontonamen und den Schlüssel im Bicep-Code suchen, anstatt Parameter zu übergeben.
  • Fügen Sie die Details des Speicherkontos einem Schlüsseltresor als Geheimnis hinzu. Der Websitecode lädt dann den Zugriffsschlüssel direkt aus dem Tresor. Dieser Ansatz vermeidet die Notwendigkeit, den Schlüssel im Workflow überhaupt zu verwalten.

Verwenden von Workflowvariablen für kleine Parametersätze

Wenn Sie nur über wenige Parameter für Ihre Bicep-Dateien verfügen, sollten Sie Variablen in Ihrer YAML-Datei definieren.

Verwenden von Parameterdateien für große Parametersätze

Wenn Sie über einen großen Parametersatz für Ihre Bicep-Dateien verfügen, sollten Sie Parameterdateien verwenden, um die nicht sicheren Werte für jede Umgebung zusammenzuhalten. Wenn Sie dann die Werte ändern müssen, können Sie eine Parameterdatei aktualisieren und die Änderung committen.

Dieser Ansatz vereinfacht Ihre Workflowschritte, da Sie nicht explizit den Wert für jeden Parameter festlegen müssen.

Sicheres Speichern von Geheimnissen

Verwenden Sie einen geeigneten Prozess zum Speichern und Verarbeiten von Geheimnissen. Verwenden Sie GitHub-Geheimnisse, um Geheimnisse in Ihrem GitHub-Repository zu speichern, oder verwenden Sie Key Vault, um Geheimnisse in Azure zu speichern.

Denken Sie bei sicheren Parametern daran, jeden Parameter explizit an Ihre Bereitstellungsschritte zu übergeben.

GitHub kann Ihr Repository automatisch auf Geheimnisse überprüfen, die versehentlich committet wurden, sodass Sie benachrichtigt werden können. Anschließend können Sie die Geheimnisse entfernen und rotieren. In der Zusammenfassung finden Sie Links zu weitere Informationen für dieses Feature.

Kombinieren von Ansätzen

Es ist üblich, mehrere Ansätze zu kombinieren, um Ihre Parameter zu verarbeiten. Beispielsweise können Sie die meisten Ihrer Parameterwerte in Parameterdateien speichern und dann sichere Werte mithilfe eines Geheimnisses festlegen. Die Kombination wird im folgenden Beispiel veranschaulicht.

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 }}

Tipp

Am Ende dieses Beispiels wird der Wert parameters mithilfe des >-Zeichens als mehrzeilige YAML-Zeichenfolge bereitgestellt. Dadurch wird das Lesen der YAML-Datei erleichtert. Dies entspricht dem Einbetten des gesamten Werts in eine einzelne Zeile.