Moduły Bicep

Bicep umożliwia organizowanie wdrożeń w modułach. Moduł to plik Bicep (lub szablon JSON usługi Azure Resource Manager), który jest wdrażany z innego pliku Bicep. Dzięki modułom można poprawić czytelność plików Bicep, hermetyzując złożone szczegóły wdrożenia. Można również łatwo używać modułów dla różnych wdrożeń.

Aby udostępnić moduły innym osobom w organizacji, utwórz specyfikację szablonu lub rejestr prywatny. Specyfikacje szablonów i moduły w rejestrze są dostępne tylko dla użytkowników z odpowiednimi uprawnieniami.

Napiwek

Wybór między rejestrem modułów a specyfikacjami szablonów jest głównie kwestią preferencji. Istnieje kilka kwestii, które należy wziąć pod uwagę podczas wyboru między nimi:

• Rejestr modułów jest obsługiwany tylko przez Bicep. Jeśli jeszcze nie używasz Bicep, użyj specyfikacji szablonu.
• Zawartość rejestru modułów Bicep można wdrożyć tylko z innego pliku Bicep. Specyfikacje szablonów można wdrażać bezpośrednio z poziomu interfejsu API, programu Azure PowerShell, interfejsu wiersza polecenia platformy Azure i witryny Azure Portal. Możesz nawet użyć UiFormDefinition polecenia , aby dostosować środowisko wdrażania portalu.
• Bicep ma pewne ograniczone możliwości osadzania innych artefaktów projektu (w tym plików szablonów innych niż Bicep i innych niż ARM. Na przykład skrypty programu PowerShell, skrypty interfejsu wiersza polecenia i inne pliki binarne) przy użyciu loadTextContent funkcji i loadFileAsBase64 . Specyfikacje szablonu nie mogą spakować tych artefaktów.

Moduły Bicep są konwertowane na pojedynczy szablon usługi Azure Resource Manager z zagnieżdżonym szablonem. Aby uzyskać więcej informacji na temat sposobu rozpoznawania plików konfiguracji i sposobu scalania pliku konfiguracji zdefiniowanego przez użytkownika za pomocą domyślnego pliku konfiguracji, zobacz Proces rozpoznawania plików konfiguracji i Proces scalania plików konfiguracji.

Zasoby szkoleniowe

Jeśli wolisz dowiedzieć się więcej o modułach za pomocą szczegółowych wskazówek, zobacz Tworzenie plików Bicep z możliwością komponowania przy użyciu modułów.

Definiowanie modułów

Podstawowa składnia definiowania modułu to:

@<decorator>(<argument>)
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

W związku z tym prosty, rzeczywisty przykład wygląda następująco:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Możesz również użyć szablonu JSON usługi ARM jako modułu:

module stgModule '../storageAccount.json' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Użyj nazwy symbolicznej, aby odwołać się do modułu w innej części pliku Bicep. Na przykład możesz użyć nazwy symbolicznej, aby pobrać dane wyjściowe z modułu. Nazwa symboliczna może zawierać znaki a-z, A-Z, 0-9 i podkreślenie (_). Nazwa nie może zaczynać się od liczby. Moduł nie może mieć takiej samej nazwy jak parametr, zmienna lub zasób.

Ścieżka może być plikiem lokalnym lub plikiem w rejestrze. Plik lokalny może być plikiem Bicep lub szablonem JSON usługi ARM. Aby uzyskać więcej informacji, zobacz Ścieżka do modułu.

Właściwość name jest wymagana. Staje się nazwą zagnieżdżonego zasobu wdrożenia w wygenerowanym szablonie.

Jeśli moduł o nazwie statycznej jest wdrażany współbieżnie w tym samym zakresie, istnieje możliwość ingerowania w dane wyjściowe z drugiego wdrożenia. Jeśli na przykład dwa pliki Bicep używają tego samego modułu o tej samej nazwie statycznej (examplemodule) i docelowej dla tej samej grupy zasobów, jedno wdrożenie może wyświetlić nieprawidłowe dane wyjściowe. Jeśli martwisz się o współbieżne wdrożenia w tym samym zakresie, nadaj modułowi unikatową nazwę.

Poniższy przykład łączy nazwę wdrożenia z nazwą modułu. Jeśli podasz unikatową nazwę wdrożenia, nazwa modułu będzie również unikatowa.

module stgModule 'storageAccount.bicep' = {
  name: '${deployment().name}-storageDeploy'
  scope: resourceGroup('demoRG')
}

Jeśli musisz określić zakres inny niż zakres głównego pliku, dodaj właściwość zakresu. Aby uzyskać więcej informacji, zobacz Ustawianie zakresu modułu.

// deploy to different scope
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  scope: <scope-object>
  params: {
    <parameter-names-and-values>
  }
}

Aby warunkowo wdrożyć moduł, dodaj if wyrażenie. Użycie jest podobne do warunkowego wdrażania zasobu.

// conditional deployment
module <symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Aby wdrożyć więcej niż jedno wystąpienie modułu, dodaj for wyrażenie. Można użyć dekoratora batchSize , aby określić, czy wystąpienia są wdrażane szeregowo, czy równolegle. Aby uzyskać więcej informacji, zobacz Iteracyjne pętle w Bicep.

// iterative deployment
@batchSize(int) // optional decorator for serial deployment
module <symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

Podobnie jak zasoby, moduły są wdrażane równolegle, chyba że zależą one od innych modułów lub zasobów. Zazwyczaj nie trzeba ustawiać zależności, ponieważ są one określane niejawnie. Jeśli musisz ustawić jawną zależność, możesz dodać dependsOn do definicji modułu. Aby dowiedzieć się więcej na temat zależności, zobacz Zależności zasobów.

module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
  dependsOn: [
    <symbolic-names-to-deploy-before-this-item>
  ]
}

Ścieżka do modułu

Plik modułu może być plikiem lokalnym lub plikiem zewnętrznym. Plik zewnętrzny może znajdować się w specyfikacji szablonu lub rejestrze modułów Bicep.

Plik lokalny

Jeśli moduł jest plikiem lokalnym, podaj względną ścieżkę do tego pliku. Wszystkie ścieżki w Bicep muszą być określone przy użyciu separatora katalogu ukośnika (/), aby zapewnić spójną kompilację na różnych platformach. Znak ukośnika odwrotnego systemu Windows (\) jest nieobsługiwany. Ścieżki mogą zawierać spacje.

Aby na przykład wdrożyć plik, który znajduje się na jednym poziomie w katalogu z głównego pliku, użyj polecenia:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Plik w rejestrze

Rejestr modułów publicznych

Uwaga

Moduły inne niż AVM (moduły zweryfikowane platformy Azure) są wycofyzowane z publicznego rejestru modułów.

Moduły zweryfikowane platformy Azure to wstępnie utworzone, wstępnie przetestowane i wstępnie zweryfikowane moduły do wdrażania zasobów na platformie Azure. Utworzone i należące do pracowników firmy Microsoft moduły te zostały zaprojektowane tak, aby uprościć i przyspieszyć proces wdrażania dla typowych zasobów i konfiguracji platformy Azure, a jednocześnie dostosować je do najlepszych rozwiązań; takich jak dobrze zaprojektowana struktura.

Przejdź do indeksu Bicep zweryfikowanych modułów platformy Azure, aby wyświetlić listę dostępnych modułów, wybierz wyróżnione liczby na poniższym zrzucie ekranu, aby przejść bezpośrednio do tego filtrowanego widoku.

Lista modułów zawiera najnowszą wersję. Wybierz numer wersji, aby wyświetlić listę dostępnych wersji:

Aby połączyć się z publicznym modułem, określ ścieżkę modułu z następującą składnią:

module <symbolic-name> 'br/public:<file-path>:<tag>' = {}

• br/public to alias dla modułów publicznych. Ten alias można dostosować w pliku konfiguracji Bicep.
• Ścieżka pliku może zawierać segmenty, które mogą być oddzielone znakiem / .
• tag służy do określania wersji modułu.

Na przykład:

module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Uwaga

br/public to alias dla modułów publicznych. Można go również napisać jako:

module <symbolic-name> 'br:mcr.microsoft.com/bicep/<file-path>:<tag>' = {}

Rejestr modułów prywatnych

Jeśli moduł został opublikowany w rejestrze, możesz połączyć się z tym modułem. Podaj nazwę rejestru kontenerów platformy Azure i ścieżkę do modułu. Określ ścieżkę modułu z następującą składnią:

module <symbolic-name> 'br:<registry-name>.azurecr.io/<file-path>:<tag>' = {

• br to nazwa schematu rejestru Bicep.
• Ścieżka pliku jest wywoływana repository w usłudze Azure Container Registry. Ścieżka pliku może zawierać segmenty oddzielone znakiem/.
• tag służy do określania wersji modułu.

Na przykład:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Podczas odwołowania się do modułu w rejestrze rozszerzenie Bicep w programie Visual Studio Code automatycznie wywołuje funkcję przywracania bicep w celu skopiowania modułu zewnętrznego do lokalnej pamięci podręcznej. Przywrócenie modułu zewnętrznego trwa kilka minut. Jeśli funkcja IntelliSense dla modułu nie działa natychmiast, poczekaj na zakończenie przywracania.

Pełna ścieżka modułu w rejestrze może być długa. Zamiast dostarczać pełną ścieżkę za każdym razem, gdy chcesz użyć modułu, można skonfigurować aliasy w pliku bicepconfig.json. Aliasy ułatwiają odwołanie do modułu. Na przykład za pomocą aliasu można skrócić ścieżkę do:

module stgModule 'br/ContosoModules:storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Alias dla publicznego rejestru modułów został wstępnie zdefiniowany:

module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Alias publiczny można zastąpić w pliku bicepconfig.json.

Plik w specyfikacji szablonu

Po utworzeniu specyfikacji szablonu możesz utworzyć link do tej specyfikacji szablonu w module. Określ specyfikację szablonu w następującym formacie:

module <symbolic-name> 'ts:<sub-id>/<rg-name>/<template-spec-name>:<version>' = {

Można jednak uprościć plik Bicep, tworząc alias dla grupy zasobów zawierającej specyfikacje szablonu. Gdy używasz aliasu, składnia staje się następująca:

module <symbolic-name> 'ts/<alias>:<template-spec-name>:<version>' = {

Poniższy moduł wdraża specyfikację szablonu w celu utworzenia konta magazynu. Subskrypcja i grupa zasobów dla specyfikacji szablonu są definiowane w aliasie o nazwie ContosoSpecs.

module stgModule 'ts/ContosoSpecs:storageSpec:2.0' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Korzystanie z dekoratorów

Dekoratory są zapisywane w formacie @expression i umieszczane powyżej deklaracji modułów. W poniższej tabeli przedstawiono dostępne dekoratory dla modułów.

Dekorator	Argument	opis
batchSize	Brak	Konfigurowanie wystąpień w celu sekwencyjnego wdrażania.
opis	string	Podaj opisy modułu.

Dekoratory znajdują się w przestrzeni nazw systemu. Jeśli musisz odróżnić dekorator od innego elementu o tej samej nazwie, należy poprzeć dekorator za pomocą polecenia sys. Jeśli na przykład plik Bicep zawiera parametr o nazwie description, należy dodać przestrzeń nazw systemu podczas korzystania z dekoratora opisu .

BatchSize

Można stosować @batchSize() tylko do definicji zasobu lub modułu for , która używa wyrażenia.

Domyślnie moduły są wdrażane równolegle. Po dodaniu dekoratora @batchSize(int) wystąpienia są wdrażane szeregowo.

@batchSize(3)
module storage 'br/public:avm/res/storage/storage-account:0.11.1' = [for storageName in storageAccounts: {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}]

Aby uzyskać więcej informacji, zobacz Wdrażanie w partiach.

opis

Aby dodać wyjaśnienie, dodaj opis do deklaracji modułów. Na przykład:

@description('Create storage accounts referencing an AVM.')
module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Tekst w formacie markdown może służyć do tekstu opisu.

Parametry

Parametry podane w definicji modułu są zgodne z parametrami w pliku Bicep.

Poniższy przykład Bicep zawiera trzy parametry : storagePrefix, storageSKU i location. Parametr storageSKU ma wartość domyślną, więc nie trzeba podawać wartości dla tego parametru podczas wdrażania.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Aby użyć poprzedniego przykładu jako modułu, podaj wartości dla tych parametrów.

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Ustawianie zakresu modułu

Podczas deklarowania modułu można ustawić zakres modułu, który różni się od zakresu zawierającego plik Bicep. scope Użyj właściwości , aby ustawić zakres modułu. Gdy właściwość zakresu nie zostanie podana, moduł zostanie wdrożony w zakresie docelowym elementu nadrzędnego.

Poniższy plik Bicep tworzy grupę zasobów i konto magazynu w tej grupie zasobów. Plik jest wdrażany w subskrypcji, ale moduł jest w zakresie nowej grupy zasobów.

// set the target scope for this file
targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

param location string = deployment().location

var resourceGroupName = '${namePrefix}rg'

resource newRG 'Microsoft.Resources/resourceGroups@2024-03-01' = {
  name: resourceGroupName
  location: location
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: newRG
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

W następnym przykładzie są wdrażane konta magazynu w dwóch różnych grupach zasobów. Obie te grupy zasobów muszą już istnieć.

targetScope = 'subscription'

resource firstRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup2'
}

module storage1 '../create-storage-account/main.bicep' = {
  name: 'westusdeploy'
  scope: firstRG
  params: {
    storagePrefix: 'stg1'
    location: 'westus'
  }
}

module storage2 '../create-storage-account/main.bicep' = {
  name: 'eastusdeploy'
  scope: secondRG
  params: {
    storagePrefix: 'stg2'
    location: 'eastus'
  }
}

Ustaw właściwość zakresu na prawidłowy obiekt zakresu. Jeśli plik Bicep wdraża grupę zasobów, subskrypcję lub grupę zarządzania, możesz ustawić zakres modułu na nazwę symboliczną dla tego zasobu. Możesz też użyć funkcji zakresu, aby uzyskać prawidłowy zakres.

Te funkcje to:

• resourceGroup
• Subskrypcja
• managementGroup
• tenant

W poniższym przykładzie użyto managementGroup funkcji w celu ustawienia zakresu.

param managementGroupName string

module mgDeploy 'main.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupName)
}

Wyjście

Możesz pobrać wartości z modułu i użyć ich w głównym pliku Bicep. Aby uzyskać wartość wyjściową z modułu, użyj outputs właściwości w obiekcie modułu.

Pierwszy przykład tworzy konto magazynu i zwraca podstawowe punkty końcowe.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

W przypadku użycia jako modułu możesz uzyskać wartość wyjściową.

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Następne kroki

• Aby zapoznać się z samouczkiem, zobacz Wdrażanie zasobów platformy Azure przy użyciu szablonów Bicep.
• Aby przekazać wartość wrażliwą do modułu , użyj funkcji getSecret .