Přidání parametrů a výstupů do modulů

  • 7 min

Každý modul, který vytvoříte, by měl mít jasný účel. Modul si můžete představit jako smlouvu. Přijímá sadu parametrů, vytvoří sadu prostředků a může poskytovat některé výstupy zpět do nadřazené šablony. Každý, kdo modul používá, by se neměl starat o to, jak to funguje, jen že dělá to, co očekává.

Při plánování modulu zvažte:

  • Co potřebujete vědět, abyste mohli splnit účel modulu.
  • Kdo bude modul využívat, očekává, že ho poskytne.
  • Každý, kdo váš modul využívá, očekává přístup jako výstup.

Parametry modulu

Zamyslete se nad parametry, které modul přijímá, a jestli by měl být každý parametr volitelný nebo povinný.

Při vytváření parametrů pro šablony je vhodné přidat výchozí parametry tam, kde je to možné. Vmodulech Pokud máte v obou souborech podobné parametry, a to jak s výchozími hodnotami, může být obtížné uživatelům šablony zjistit, která výchozí hodnota se použije, a vynutit konzistenci. Často je lepší ponechat výchozí hodnotu v nadřazené šabloně a odebrat ji z modulu.

Měli byste také přemýšlet o tom, jak spravovat parametry, které řídí skladové položky pro vaše prostředky a další důležitá nastavení konfigurace. Když vytvoříte samostatnou šablonu Bicep, je běžné vložit obchodní pravidla do šablony. Příklad: Když nasadím produkční prostředí, měl by účet úložiště používat úroveň GRS. Moduly ale někdy představují různé obavy.

Pokud vytváříte modul, který musí být opakovaně použitelný a flexibilní, mějte na paměti, že obchodní pravidla pro každou nadřazenou šablonu se můžou lišit, takže nemusí mít smysl vkládat obchodní pravidla do obecných modulů. Zvažte definování obchodních pravidel v nadřazené šabloně a pak explicitně předat konfiguraci modulu prostřednictvím parametrů.

Pokud ale vytvoříte modul, který má vaší organizaci usnadnit nasazení prostředků, které odpovídají vašim konkrétním potřebám, je vhodné zahrnout obchodní pravidla, která zjednodušují nadřazené šablony.

Bez ohledu na parametry, které do modulu zahrnete, nezapomeňte pomocí atributu @description přidat smysluplný popis:

@description('The name of the storage account to deploy.')
param storageAccountName string

Použití podmínek

Jedním z cílů nasazení infrastruktury pomocí kódu, jako je Bicep, je vyhnout se duplikování úsilí nebo dokonce vytvořit několik šablon pro stejný nebo podobný účel. Funkce Bicep poskytují výkonný panel nástrojů pro vytváření opakovaně použitelných modulů, které fungují v různých situacích. Pomocí kombinace funkcí, jako jsou moduly, výrazy, výchozí hodnoty parametrů a podmínky, můžete vytvořit opakovaně použitelný kód, který vám poskytne flexibilitu, kterou potřebujete.

Předpokládejme, že vytváříte modul, který nasazuje účet služby Azure Cosmos DB. Když je nasazená do produkčního prostředí, musíte účet nakonfigurovat tak, aby odesílal protokoly do pracovního prostoru služby Log Analytics. Pokud chcete nakonfigurovat, aby se protokoly odesílaly do Log Analytics, definujete prostředek diagnosticSettings .

Požadavek můžete dosáhnout tak, že do definice prostředku přidáte podmínku a nastavíte parametr ID pracovního prostoru jako volitelný přidáním výchozí hodnoty:

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

Pokud tento modul zahrnete do šablony Bicep, můžete ho snadno nakonfigurovat tak, aby odesílal protokoly účtu služby Azure Cosmos DB do Log Analytics nastavením ID pracovního prostoru. Nebo pokud nepotřebujete protokoly pro prostředí, které nasazujete, vynecháte parametr. Má výchozí hodnotu. Modul zapouzdřuje logiku potřebnou k tomu, aby pro vaše požadavky udělal správnou věc.

Tip

Nezapomeňte otestovat, že vaše šablona je platná pro oba scénáře; pokud je if příkaz vyhodnocen jako buď true nebo false.

Výstupy modulu

Moduly mohou definovat výstupy. Je vhodné vytvořit výstup pro informace, které může nadřazená šablona potřebovat použít. Pokud například modul definuje účet úložiště, zvažte vytvoření výstupu pro název účtu úložiště, aby k němu nadřazená šablona přistupovala.

Upozorňující

Nepoužívejte výstupy pro tajné hodnoty. Výstupy se protokolují jako součást historie nasazení, takže nejsou vhodné pro zabezpečené hodnoty. Místo toho můžete zvážit jednu z následujících možností:

  • Pomocí výstupu zadejte název prostředku. Nadřazená šablona pak může vytvořit existing prostředek s tímto názvem a dynamicky vyhledat zabezpečenou hodnotu.
  • Napište hodnotu do tajného kódu služby Azure Key Vault. Požádejte nadřazenou šablonu, aby přečetla tajný klíč z trezoru, když ho potřebuje.

Nadřazená šablona může používat výstupy modulu v proměnných, může používat vlastnosti pro jiné definice prostředků nebo může vystavit proměnné a vlastnosti jako výstupy samotné. Zveřejněním a použitím výstupů v souborech Bicep můžete vytvořit opakovaně použitelné sady modulů Bicep, které se dají sdílet s vaším týmem a opakovaně používat napříč několika nasazeními. Je také vhodné přidat smysluplný popis výstupu pomocí atributu @description :

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

Tip

K ukládání, správě a přístupu k nastavení, která vaše šablona Bicep vytvoří, můžete také použít vyhrazené služby. Key Vault je navržený tak, aby ukládaly zabezpečené hodnoty. Aplikace Azure Configuration je navržená tak, aby ukládaly jiné (nezabezpečené) hodnoty.

Zřetězení modulů

Je běžné vytvořit nadřazený soubor Bicep, který vytváří více modulů dohromady. Představte si například, že vytváříte novou šablonu Bicep pro nasazení virtuálních počítačů, které používají vyhrazené virtuální sítě. Můžete vytvořit modul pro definování virtuální sítě. Pak můžete jako výstup z daného modulu vzít ID prostředku podsítě virtuální sítě a použít ho jako vstup modulu virtuálního počítače:

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

V tomto příkladu se symbolické názvy používají pro odkaz mezi moduly. Tento odkaz pomáhá Bicep automaticky pochopit vztahy mezi moduly.

Vzhledem k tomu, že Bicep chápe, že existuje závislost, nasadí moduly postupně:

  1. Bicep nasadí všechno v virtualNetwork modulu.
  2. Pokud je nasazení úspěšné, Bicep přistupuje k subnetResourceId výstupní hodnotě a předá ho modulu virtualMachine jako parametr.
  3. Bicep nasadí všechno v virtualMachine modulu.

Poznámka:

Když závisíte na modulu, Bicep čeká na dokončení celého nasazení modulu. Při plánování modulů je důležité si to pamatovat. Pokud vytvoříte modul, který definuje prostředek, který trvá dlouhou dobu, než se nasadí, všechny ostatní prostředky, které závisí na daném modulu, počká na dokončení nasazení celého modulu.