Obsługa różnic między środowiskami przy użyciu parametrów Bicep

  • 7 min

Znasz już parametry Bicep. Ułatwiają one określanie wartości, które mogą ulec zmianie między wdrożeniami plików Bicep.

Parametry są często używane do obsługi różnic między środowiskami. Na przykład w środowiskach nieprodukcyjnych często chcesz wdrożyć niedrogie jednostki SKU zasobów platformy Azure. W środowisku produkcyjnym chcesz wdrożyć jednostki SKU o lepszej wydajności. Możesz też użyć różnych nazw zasobów w każdym środowisku.

Podczas wdrażania pliku Bicep należy podać wartości dla każdego parametru. Istnieje kilka opcji określania wartości dla każdego parametru z przepływu pracy oraz sposobu określania oddzielnych wartości dla każdego środowiska. W tej lekcji poznasz metody określania wartości parametrów Bicep w przepływie pracy wdrażania.

Pliki parametrów

Plik parametrów jest plikiem w formacie JSON, który zawiera listę wartości parametrów, które mają być używane dla każdego środowiska. Podczas przesyłania wdrożenia należy przesłać plik parametrów do usługi Azure Resource Manager.

Oto przykładowy plik parametrów:

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

Pliki parametrów mogą być zatwierdzane w repozytorium Git wraz z plikiem Bicep. Następnie możesz odwołać się do pliku parametrów w szablonie przepływu pracy, w którym jest wykonywane wdrożenie.

Dobrym pomysłem jest ustanowienie spójnej strategii nazewnictwa środowiska dla plików parametrów. Możesz na przykład nazwać parametry plików parametrów . ENVIRONMENT_NAME.json, na przykład parametry. Production.json. Następnie możesz użyć danych wejściowych szablonu przepływu pracy, aby automatycznie wybrać prawidłowy plik parametrów na podstawie wartości wejściowej.

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

W przypadku korzystania z plików parametrów pliki YAML przepływu pracy nie muszą zawierać listy parametrów, które należy przekazać indywidualnie do kroków wdrażania. Jest to szczególnie przydatne, gdy masz dużą liczbę parametrów.

Plik parametrów przechowuje wartości parametrów w jednym pliku JSON. Pliki parametrów są również częścią repozytorium Git, dzięki czemu mogą być wersjonowane w taki sam sposób, jak w przypadku wszystkich innych kodów.

Ważne

Pliki parametrów nie powinny być używane na potrzeby bezpiecznych wartości. Nie ma możliwości ochrony wartości wpisów tajnych w plikach parametrów i nigdy nie należy zatwierdzać wpisów tajnych w repozytorium Git.

Zmienne przepływu pracy

Funkcja GitHub Actions umożliwia przechowywanie zmiennych przepływu pracy, które są przydatne w przypadku wartości, które mogą się różnić między środowiskami. Są one również przydatne w przypadku wartości, które chcesz zdefiniować tylko raz, a następnie ponownie w całym przepływie pracy.

Zmienne zdefiniowane w pliku YAML

Zmienne można definiować i ustawiać ich wartości w pliku YAML. Jest to przydatne, gdy trzeba wielokrotnie używać tej samej wartości. Można zdefiniować zmienną dla całego przepływu pracy, zadania lub jednego kroku:

env:
  MyVariable1: value1

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

Wpisy tajne zdefiniowane w interfejsie internetowym

Podobnie jak pliki parametrów Bicep, pliki YAML nie są odpowiednie dla wpisów tajnych. Zamiast tego można zdefiniować wpisy tajne przy użyciu interfejsu internetowego usługi GitHub. Wartości zmiennych można zmienić w dowolnym momencie, a przepływ pracy odczytuje zaktualizowane wartości przy następnym uruchomieniu. Funkcja GitHub Actions próbuje ukryć wartości wpisów tajnych w dziennikach przepływu pracy. Oznacza to, że możesz przechowywać wartości, które plik Bicep następnie akceptuje jako parametry z dekoratorem @secure() .

Ostrzeżenie

Domyślnie funkcja GitHub Actions zaciemnia wartości zmiennych wpisów tajnych w dziennikach przepływu pracy, ale należy również postępować zgodnie z dobrymi rozwiązaniami. Kroki przepływu pracy mają dostęp do wartości wpisów tajnych. Jeśli przepływ pracy zawiera krok, który nie obsługuje wpisu tajnego bezpiecznie, istnieje prawdopodobieństwo, że wartość wpisu tajnego może zostać wyświetlona w dziennikach przepływu pracy. Zawsze należy dokładnie przejrzeć wszelkie zmiany w pliku definicji przepływu pracy, aby sprawdzić, czy wpisy tajne nie zostaną nieprawidłowo potraktowane.

Podczas tworzenia wpisu tajnego usługa GitHub umożliwia określenie zakresu go do całego repozytorium Git, czy do określonego środowiska. Wpisy tajne w zakresie środowiska przestrzegają reguł ochrony skonfigurowanych w środowiskach, więc jeśli skonfigurujesz wymaganą regułę recenzenta, przepływ pracy nie będzie mógł uzyskać dostępu do wartości wpisów tajnych, dopóki określony użytkownik usługi GitHub nie zatwierdzi potoku do wdrożenia w tym środowisku.

Wpisy tajne o zakresie środowiska mogą być przydatne, ale nie mogą łatwo pracować z weryfikacją wstępną usługi Azure Resource Manager ani operacjami warunkowymi. Te operacje muszą komunikować się z platformą Azure, co oznacza, że potrzebują tożsamości obciążenia. Zazwyczaj chcesz podać zatwierdzenie wdrożenia po zakończeniu walidacji wstępnej lub operacji analizy co-jeżeli, tak aby mieć wysoki stopień zaufania do wdrażanych zmian. Dlatego jeśli używasz wpisów tajnych o zakresie środowiska, proces przeglądu przez człowieka odbywa się zbyt wcześnie w przepływie pracy.

Z tego powodu w ćwiczeniach tego modułu nie używasz wpisów tajnych o zakresie środowiska. Zamiast tego tworzone są wpisy tajne o zakresie repozytorium z przewidywalnymi nazwami, które zawierają nazwę środowiska. Umożliwia to przepływowi pracy identyfikowanie prawidłowego wpisu tajnego do użycia dla każdego środowiska. We własnych przepływach pracy możesz użyć wpisów tajnych o zakresie repozytorium, wpisów tajnych o zakresie środowiska, a nawet kombinacji obu tych typów.

Uwaga

Możesz również określić zakres wpisów tajnych w organizacjach usługi GitHub. Chociaż nie ma to zakresu dla tego modułu, link do dodatkowych informacji znajduje się w podsumowaniu.

Używanie zmiennych w przepływie pracy

Sposób uzyskiwania dostępu do wartości zmiennej w przepływie pracy zależy od typu zmiennej.

Typ Składnia
Zmienne zdefiniowane w tym samym pliku ${{ env.VARIABLE_NAME }}
Dane wejściowe do wywoływanego przepływu pracy ${{ inputs.INPUT_NAME }}
Wpisy tajne ${{ secrets.SECRET_NAME }}

Na przykład podczas uruchamiania wdrożenia Bicep możesz użyć wpisów tajnych, aby określić tożsamość obciążenia platformy Azure do użycia, nazywane wejście przepływu pracy w celu określenia nazwy grupy zasobów i zmiennej w celu określenia wartości parametru:

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

Jakie jest najlepsze podejście?

Wiesz już o kilku sposobach obsługi parametrów, których potrzebuje plik Bicep dla danego wdrożenia. Warto zrozumieć, kiedy można użyć tego podejścia.

Unikaj niepotrzebnych parametrów

Parametry ułatwiają wielokrotne użycie plików Bicep, ale można łatwo zdefiniować zbyt wiele parametrów. Podczas wdrażania pliku Bicep należy podać wartość dla każdego parametru. W przypadku złożonych wdrożeń w wielu środowiskach trudno zarządzać dużym zestawem pojedynczych wartości parametrów.

Rozważ wprowadzenie parametrów opcjonalnych, w których można i użyj wartości domyślnych, które mają zastosowanie do większości środowisk. Następnie można uniknąć konieczności przekazywania wartości parametrów przez przepływy pracy.

Należy również pamiętać, że parametry są często używane w aplikacji Bicep, gdy zasoby muszą łączyć się z innymi zasobami. Jeśli na przykład masz witrynę internetową, która musi połączyć się z kontem magazynu, musisz podać nazwę konta magazynu i klucz dostępu. Klucze są bezpiecznymi wartościami. Należy jednak rozważyć te inne podejścia podczas wdrażania tej kombinacji zasobów:

  • Użyj tożsamości zarządzanej witryny internetowej, aby uzyskać dostęp do konta magazynu. Podczas tworzenia tożsamości zarządzanej platforma Azure automatycznie generuje poświadczenia i zarządza nimi. Takie podejście upraszcza ustawienia połączenia. Oznacza to również, że nie musisz w ogóle obsługiwać wpisów tajnych, więc jest to najbezpieczniejsza opcja.
  • Wdróż konto magazynu i witrynę internetową razem w tym samym szablonie Bicep. Użyj modułów Bicep, aby zachować razem zasoby witryny internetowej i magazynu. Następnie możesz automatycznie wyszukać wartości nazwy konta magazynu i klucza w kodzie Bicep, zamiast przekazywać parametry.
  • Dodaj szczegóły konta magazynu do magazynu kluczy jako wpis tajny. Następnie kod witryny internetowej ładuje klucz dostępu bezpośrednio z magazynu. Takie podejście pozwala uniknąć konieczności zarządzania kluczem w przepływie pracy.

Używanie zmiennych przepływu pracy dla małych zestawów parametrów

Jeśli masz tylko kilka parametrów dla plików Bicep, rozważ zdefiniowanie zmiennych w pliku YAML.

Używanie plików parametrów dla dużych zestawów parametrów

Jeśli masz duży zestaw parametrów dla plików Bicep, rozważ użycie plików parametrów, aby zachować wartości niezabezpieczenia dla każdego środowiska. Następnie za każdym razem, gdy trzeba zmienić wartości, możesz zaktualizować plik parametrów i zatwierdzić zmianę.

Takie podejście ułatwia kroki przepływu pracy, ponieważ nie trzeba jawnie ustawiać wartości dla każdego parametru.

Bezpieczne przechowywanie wpisów tajnych

Użyj odpowiedniego procesu do przechowywania i obsługi wpisów tajnych. Używanie wpisów tajnych usługi GitHub do przechowywania wpisów tajnych w repozytorium GitHub lub przechowywania wpisów tajnych na platformie Azure za pomocą usługi Key Vault.

W przypadku bezpiecznych parametrów pamiętaj, aby jawnie przekazać każdy parametr do kroków wdrażania.

Usługa GitHub może automatycznie skanować repozytorium pod kątem wpisów tajnych, które zostały przypadkowo zatwierdzone, aby można było otrzymywać powiadomienia. Następnie można usunąć i obrócić wpisy tajne. Link do dodatkowych informacji o tej funkcji znajduje się w podsumowaniu.

Łączenie podejść

Często łączy się wiele podejść do obsługi parametrów. Na przykład większość wartości parametrów można przechowywać w plikach parametrów, a następnie ustawiać bezpieczne wartości przy użyciu wpisu tajnego. Poniższy przykład ilustruje kombinację:

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

Napiwek

Na końcu tego przykładu parameters wartość jest dostarczana jako ciąg wielowierszowy YAML przy użyciu > znaku . Ułatwia to odczytywanie pliku YAML. Jest to równoważne z dołączeniem całej wartości w jednym wierszu.