Zpracování rozdílů mezi prostředími pomocí parametrů Bicep

7 min

Už jste se dozvěděli o parametrech Bicep. Pomáhají určit hodnoty, které se můžou měnit mezi nasazeními souborů Bicep.

Parametry se běžně používají k podpoře rozdílů mezi prostředími. Například v neprodukčním prostředí často chcete nasadit levné skladové položky vašich prostředků Azure. V produkčním prostředí chcete nasadit skladové položky, které mají lepší výkon. A možná budete chtít pro prostředky v každém prostředí použít různé názvy.

Když nasadíte soubor Bicep, zadáte hodnoty pro každý parametr. Existuje několik možností, jak zadat hodnoty pro každý parametr z pracovního postupu a jak zadat samostatné hodnoty pro každé prostředí. V této lekci se dozvíte o přístupech k určení hodnot parametrů Bicep v pracovním postupu nasazení.

Soubory parametrů

Soubor parametrů je soubor ve formátu JSON, který obsahuje hodnoty parametrů, které chcete použít pro každé prostředí. Soubor parametrů odešlete do Azure Resource Manageru při odeslání nasazení.

Tady je ukázkový soubor parametrů:

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

Soubory parametrů je možné potvrdit do úložiště Git spolu se souborem Bicep. Potom můžete odkazovat na soubor parametrů v šabloně pracovního postupu, ve které provádíte nasazení.

Je vhodné vytvořit konzistentní strategii vytváření názvů prostředí pro soubory parametrů. Můžete například pojmenovat parametry souborů parametrů. ENVIRONMENT_NAME.json, například parametry. Production.json. Potom můžete použít vstup šablony pracovního postupu k automatickému výběru správného souboru parametrů na základě vstupní hodnoty.

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

Při použití souborů parametrů nemusí soubory YAML pracovního postupu obsahovat seznam parametrů, které je potřeba předat jednotlivým krokům nasazení. To je užitečné hlavně v případě, že máte velký počet parametrů.

Soubor parametrů uchovává hodnoty parametrů v jednom souboru JSON. Soubory parametrů jsou také součástí vašeho úložiště Git, takže se dají získat verze stejným způsobem jako všechny ostatní kódy.

Důležité

Soubory parametrů by se neměly používat pro zabezpečené hodnoty. Neexistuje způsob, jak chránit hodnoty tajných kódů v souborech parametrů a nikdy byste tajné kódy neměli ukládat do úložiště Git.

Proměnné pracovního postupu

GitHub Actions umožňuje ukládat proměnné pracovního postupu, které jsou užitečné pro hodnoty, které se můžou mezi prostředími lišit. Jsou také užitečné pro hodnoty, které chcete definovat pouze jednou, a pak je znovu použít v celém pracovním postupu.

Proměnné definované v souboru YAML

Můžete definovat proměnné a nastavit jejich hodnoty v souboru YAML. To je užitečné, když potřebujete opakovaně použít stejnou hodnotu. Proměnnou můžete definovat pro celý pracovní postup, úlohu nebo jeden krok:

env:
  MyVariable1: value1

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

Tajné kódy definované ve webovém rozhraní

Stejně jako soubory parametrů Bicep nejsou soubory YAML vhodné pro tajné kódy. Místo toho můžete tajné kódy definovat pomocí webového rozhraní GitHubu. Hodnoty proměnných můžete kdykoli změnit a pracovní postup přečte aktualizované hodnoty při příštím spuštění. GitHub Actions se pokusí skrýt hodnoty tajných kódů v protokolech pracovního postupu. To znamená, že můžete uložit hodnoty, které váš soubor Bicep pak přijme jako parametry s dekorátorem @secure() .

Upozorňující

Ve výchozím nastavení GitHub Actions obfuscuje hodnoty tajných proměnných v protokolech pracovního postupu, ale musíte postupovat i podle osvědčených postupů. Kroky pracovního postupu mají přístup k hodnotám tajných kódů. Pokud váš pracovní postup obsahuje krok, který nezpracuje tajný kód bezpečně, je možné, že se v protokolech pracovního postupu zobrazí hodnota tajného kódu. Vždy byste měli pečlivě zkontrolovat všechny změny definičního souboru pracovního postupu a ověřit, že tajné kódy nebudou chybně ošetřené.

Při vytváření tajného kódu vám GitHub umožňuje zvolit, jestli ho chcete vymezit na celé úložiště Git nebo na konkrétní prostředí. Tajné kódy v oboru prostředí dodržují pravidla ochrany nakonfigurovaná ve vašich prostředích, takže pokud nakonfigurujete požadované pravidlo revidujících, pracovní postup nemá přístup k hodnotám tajných kódů, dokud zadaný uživatel GitHubu neschválili váš kanál pro nasazení do tohoto prostředí.

Tajné kódy v rozsahu prostředí můžou být užitečné, ale s předběžným ověřením nebo operacemi citlivostní operace Azure Resource Manageru snadno nefungují. Tyto operace musí komunikovat s Azure, což znamená, že potřebují identitu úlohy. Obecně chcete po dokončení předběžných operací nebo operací citlivostní kontroly poskytnout schválení nasazení, abyste měli vysokou jistotu o změnách, které nasazujete. Pokud tedy používáte tajné kódy s oborem prostředí, proces kontroly člověka probíhá příliš brzy v pracovním postupu.

Z tohoto důvodu v cvičeních tohoto modulu nepoužíváte tajné kódy vymezené prostředím. Místo toho vytvoříte tajné kódy s oborem úložiště s předvídatelnými názvy, které zahrnují název prostředí. To umožňuje vašemu pracovnímu postupu identifikovat správný tajný kód, který se má použít pro každé prostředí. Ve vlastních pracovních postupech se můžete rozhodnout použít tajné kódy s vymezeným úložištěm, tajné kódy s oborem prostředí nebo dokonce kombinaci obojího.

Poznámka:

Tajné kódy můžete také vymezit na organizace GitHubu. I když toto není v oboru pro tento modul, propočítáme si další informace v souhrnu.

Použití proměnných v pracovním postupu

Způsob přístupu k hodnotě proměnné v pracovním postupu závisí na typu proměnné.

Typ	Syntaxe
Proměnné definované ve stejném souboru	`${{ env.VARIABLE_NAME }}`
Vstupy do volaný pracovní postup	`${{ inputs.INPUT_NAME }}`
Tajné kódy	`${{ secrets.SECRET_NAME }}`

Když například spustíte nasazení Bicep, můžete použít tajné kódy k určení identity úlohy Azure, která se má použít, označovaného jako vstup pracovního postupu pro zadání názvu skupiny prostředků a proměnné pro zadání hodnoty 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 }}

Jaký je nejlepší přístup?

Seznámili jste se s několika způsoby zpracování parametrů, které váš soubor Bicep potřebuje pro vaše nasazení. Je užitečné pochopit, kdy můžete použít jaký přístup.

Vyhněte se zbytečným parametrům

Parametry vám pomůžou opakovaně používat soubory Bicep, ale je snadné definovat příliš mnoho parametrů. Když nasadíte soubor Bicep, musíte zadat hodnotu pro každý parametr. V komplexních nasazeních v několika prostředích je obtížné spravovat velkou sadu hodnot jednotlivých parametrů.

Zvažte volitelné parametry, kde můžete, a použijte výchozí hodnoty, které platí pro většinu vašich prostředí. Pak se můžete vyhnout tomu, aby pracovní postupy předávaly hodnoty parametrů.

Mějte také na paměti, že parametry se často používají v Bicep, když se prostředky potřebují připojit k jiným prostředkům. Pokud máte například web, který se musí připojit k účtu úložiště, budete muset zadat název účtu úložiště a přístupový klíč. Klíče jsou zabezpečené hodnoty. Při nasazování této kombinace prostředků ale zvažte tyto další přístupy:

Pro přístup k účtu úložiště použijte spravovanou identitu webu. Když vytvoříte spravovanou identitu, Azure automaticky vygeneruje a spravuje její přihlašovací údaje. Tento přístup zjednodušuje nastavení připojení. Také to znamená, že nemusíte vůbec zpracovávat tajné kódy, takže je to nejbezpečnější možnost.
Nasaďte účet úložiště a web společně ve stejné šabloně Bicep. Pomocí modulů Bicep udržujte prostředky webu a úložiště pohromadě. Potom můžete automaticky vyhledat hodnoty pro název účtu úložiště a klíč v kódu Bicep místo předávání parametrů.
Přidejte podrobnosti účtu úložiště do trezoru klíčů jako tajný klíč. Kód webu pak načte přístupový klíč přímo z trezoru. Tento přístup zabraňuje nutnosti spravovat klíč v pracovním postupu vůbec.

Použití proměnných pracovního postupu pro malé sady parametrů

Pokud máte pro soubory Bicep jenom několik parametrů, zvažte definování proměnných v souboru YAML.

Použití souborů parametrů pro velké sady parametrů

Pokud máte pro soubory Bicep velkou sadu parametrů, zvažte použití souborů parametrů k zachování nezabezpečených hodnot pro každé prostředí. Pokaždé, když potřebujete změnit hodnoty, můžete aktualizovat soubor parametrů a potvrdit změnu.

Tento přístup zjednodušuje kroky pracovního postupu, protože nemusíte explicitně nastavovat hodnotu pro každý parametr.

Bezpečné ukládání tajných kódů

Použijte vhodný proces pro ukládání a zpracování tajných kódů. Tajné kódy GitHubu můžete použít k ukládání tajných kódů v úložišti GitHub nebo k ukládání tajných kódů v Azure pomocí služby Key Vault.

V případě zabezpečených parametrů nezapomeňte explicitně předat jednotlivé parametry do kroků nasazení.

GitHub může automaticky kontrolovat tajné kódy, které byly omylem potvrzeny, abyste mohli být upozorněni. Tajné kódy pak můžete odebrat a otočit. Odkazujeme na další informace o této funkci v souhrnu.

Kombinování přístupů

Ke zpracování parametrů je běžné kombinovat více přístupů. Většinu hodnot parametrů můžete například uložit do souborů parametrů a pak nastavit zabezpečené hodnoty pomocí tajného klíče. Následující příklad znázorňuje kombinaci:

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

Tip

Na konci tohoto příkladu parameters je hodnota poskytována jako víceřádkový řetězec YAML pomocí znaku > . To usnadňuje čtení souboru YAML. Je ekvivalentní zahrnutí celé hodnoty na jeden řádek.