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 potoku oraz sposobu określania oddzielnych wartości dla każdego środowiska. W tej lekcji poznasz metody określania wartości parametrów Bicep w potoku 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 potoku, 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ć parametru szablonu potoku, aby automatycznie wybrać prawidłowy plik parametrów.

parameters: 
- name: environmentType
  type: string
- name: serviceConnectionName
  type: string
- name: resourceGroupName
  type: string

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: ${{parameters.serviceConnectionName}}
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group ${{parameters.resourceGroupName}} \
                    --template-file deploy/main.bicep \
                    --parameters deploy/azuredeploy.parameters.${{parameters.environmentType}}.json

W przypadku korzystania z plików parametrów pliki YAML potoku nie muszą zawierać listy parametrów, które należy przekazać indywidualnie do kroków wdrażania. Jest to 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 potoku

Usługa Azure Pipelines umożliwia przechowywanie zmiennych potoku, które są przydatne w przypadku wartości, które mogą różnić się 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 potoku. Usługa Azure Pipelines obsługuje kilka sposobów definiowania zmiennych.

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. Jednak, podobnie jak pliki parametrów Bicep, pliki YAML nie są odpowiednie dla wpisów tajnych.

Zmienne zdefiniowane w interfejsie internetowym

Zmienne można definiować przy użyciu interfejsu internetowego usługi Azure DevOps. Wartości zmiennych można zmienić w dowolnym momencie, a potok odczytuje zaktualizowane wartości przy następnym uruchomieniu.

Zmienne zdefiniowane za pośrednictwem interfejsu internetowego można oznaczyć jako wpis tajny, co informuje usługę Azure Pipelines o próbie ukrycia wartości zmiennych w dziennikach potoku. Oznacza to, że możesz przechowywać wartości, które plik Bicep następnie akceptuje jako parametry z dekoratorem @secure() .

Ostrzeżenie

Domyślnie usługa Azure Pipelines zaciemnia wartości zmiennych wpisów tajnych w dziennikach potoku, ale należy również postępować zgodnie z dobrymi rozwiązaniami. Kroki potoku mają dostęp do wszystkich wartości zmiennych, w tym wpisów tajnych. Jeśli potok zawiera krok, który nie obsługuje bezpiecznej zmiennej, istnieje prawdopodobieństwo, że zmienna wpisu tajnego może być wyświetlana w dziennikach potoku.

Grupy zmiennych

Można również zdefiniować grupy zmiennych, które są zestawami zmiennych. Podobnie jak zmienne, te grupy definiuje się przy użyciu interfejsu internetowego usługi Azure DevOps. Można również używać grup zmiennych do bezpiecznego przechowywania wpisów tajnych. Grupy zmiennych mogą być nawet używane w wielu potokach w tym samym projekcie usługi Azure DevOps.

W przeciwieństwie do innych zmiennych należy jawnie zaimportować grupę zmiennych do potoku przy użyciu group słowa kluczowego variables w sekcji, w następujący sposób:

variables:
- group: MyVariableGroup

Podczas pracy z szablonami potoków można nazwać grupy zmiennych, aby można było je łatwo załadować przy użyciu parametru szablonu. Załóżmy na przykład, że potok jest wdrażany w dwóch środowiskach i musisz zdefiniować zestaw zmiennych dla każdego środowiska. Grupy zmiennych można nazwać dołączonymi nazwami środowisk, w następujący sposób:

Nazwa środowiska	Nazwa grupy zmiennych
Testowanie	`ToyWebsiteTest`
Produkcyjne	`ToyWebsiteProduction`

W każdej z tych grup zmiennych można dodawać zmienne o tych samych nazwach, ale z różnymi wartościami dla każdego środowiska.

Plik szablonu potoku używa makra {{ parameters.PARAMETER_NAME }} do wybrania odpowiedniej grupy zmiennych do zaimportowania:

parameters: 
- name: environmentType
  type: string
  default: 'Test'

variables: 
- group: ToyWebsite${{ parameters.environmentType }}

Grupy zmiennych usługi Key Vault

Możesz połączyć grupy zmiennych z usługą Azure Key Vault. Wpisy tajne w magazynie kluczy są udostępniane jako zmienne w grupie zmiennych. Wpisy tajne mogą być następnie używane w potokach tak, jakby były normalnymi zmiennymi.

Usługa Key Vault sprawia, że zarządzanie wpisami tajnymi jest bezpieczniejsze. Umożliwia również zarządzanie tymi wartościami przez zespół ds. zabezpieczeń oraz oddzielenie dostępu do potoków od używanych przez nią wpisów tajnych.

Aby połączyć grupę zmiennych z magazynem kluczy, wymagane są dalsze kroki. Te kroki obejmują utworzenie połączenia z usługą, które ma uprawnienia do odczytywania wpisów tajnych z magazynu kluczy. W lekcji podsumowania udostępniamy link do dodatkowych szczegółów dotyczących sposobu konfigurowania grup zmiennych usługi Key Vault.

Używanie zmiennych w potoku

Niezależnie od sposobu definiowania zmiennej uzyskujesz dostęp do jej wartości w potoku $(VariableName) przy użyciu składni . Na przykład po uruchomieniu wdrożenia Bicep można użyć zmiennej do określenia wartości parametru:

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: MyServiceConnection
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group $(ResourceGroupName) \
                    --template-file deploy/main.bicep \
                    --parameters environmentType=$(EnvironmentType)

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 potoki.

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 potoku w ogóle.

Używanie grup zmiennych dla małych zestawów parametrów

Jeśli masz tylko kilka parametrów dla plików Bicep, rozważ użycie grupy zmiennych. Wartości wpisów tajnych i innych niż tajne można przechowywać w grupach zmiennych.

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 sprawia, że kroki potoku są prostsze, 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. Jeśli masz tylko kilka wpisów tajnych do zarządzania, zmienne i grupy zmiennych usługi Azure Pipelines często działają dobrze. Jednak może istnieć bardziej złożone wymagania, takie jak duża liczba wpisów tajnych, wiele różnych środowisk lub ograniczenia kontroli dostępu. W takich sytuacjach rozważ przechowywanie wpisów tajnych dla każdego środowiska w oddzielnych magazynach kluczy. Użyj grup zmiennych, aby połączyć magazyny z potokiem.

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

Łą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 grupy zmiennych. Poniższy przykład ilustruje kombinację:

variables:
- group: MyVariableGroup # This group imports a parameter named MySecureParameter.

stages:

- stage: Deploy
  jobs:
  - deployment: DeployWebsite
    displayName: Deploy Website
    environment: Website
    strategy:
      runOnce:
        deploy:
          steps:
            - checkout: self
            - task: AzureCLI@2
              name: DeployBicepFile
              displayName: Deploy Bicep file
              inputs:
                azureSubscription: MyServiceConnection
                scriptType: 'bash'
                scriptLocation: 'inlineScript'
                inlineScript: |
                  az deployment group create \
                    --resource-group ${{parameters.resourceGroupName}} \
                    --template-file deploy/main.bicep \
                    --parameters deploy/azuredeploy.parameters.${{parameters.environmentName}}.json \
                                 mySecureParameter=$(MySecureParameter)

Istnieją specjalne reguły dotyczące sposobu określenia nazw połączeń z usługą. Te reguły mogą mieć wpływ na sposób używania nazw w potokach wdrażanych w wielu środowiskach. Na przykład nie można użyć zmiennej zdefiniowanej w grupie zmiennych w celu określenia nazwy połączenia usługi. Możesz użyć parametrów szablonu potoku, aby określić nazwę połączenia usługi do użycia.