Módulos do Bicep

Com o Bicep, você pode organizar implantações em módulos. Um módulo é apenas um arquivo Bicep implantado por outro arquivo Bicep. Um módulo também pode ser um modelo do ARM (modelo do Azure Resource Manager) para JSON. Ao usar módulos, você melhora um legibilidade de seu arquivos Bicep by encapsulando detalhes complexos de sua implantação. Você também pode facilmente reutilizar módulos em implantações diferentes.

Para compartilhar módulos com outras pessoas em sua organização, crie uma especificação de modelo ou registro privado. As especificações de modelo e os módulos no registro estão disponíveis apenas para usuários com as permissões corretas.

Os módulos do Bicep são convertidos em um só modelo do ARM com modelos aninhados. Para obter mais informações sobre como o Bicep resolve arquivos de configuração e como o Bicep mescla um arquivo de configuração definido pelo usuário com o arquivo de configuração padrão, consulte o processo de resolução de arquivos de configuração e o processo de mesclagem de arquivos de configuração.

Definir módulos

A sintaxe básica para definir um módulo é:

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

Um exemplo simples do mundo real se parece com:

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

Você também pode usar um modelo do ARM para JSON como um módulo:

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

Use o nome simbólico para fazer referência ao módulo em outra parte do arquivo Bicep. Por exemplo, você pode usar o nome simbólico para obter a saída de um módulo. O nome simbólico pode conter a-z, A-Z, 0-9 e sublinhado (_). O nome não pode começar com um número. Um módulo não pode ter o mesmo nome que um parâmetro, variável ou recurso.

O caminho pode ser um arquivo local ou um arquivo em um registro. O arquivo local pode ser um arquivo Bicep ou um modelo arm para JSON. Para mais informações, veja Caminho para um módulo.

A propriedade name é opcional. Ela se torna o nome do recurso de implantação aninhado no modelo gerado. Se nenhum nome for fornecido, um GUID será gerado como nome do recurso de implantação aninhado.

Se você implantar um módulo com um nome estático simultaneamente no mesmo escopo, uma implantação poderá interferir na saída da outra implantação. Por exemplo, se dois arquivos Bicep usarem o mesmo módulo com o mesmo nome estático (examplemodule) e forem direcionados para o mesmo grupo de recursos, uma implantação poderá mostrar a saída errada. Se você estiver preocupado com implantações simultâneas no mesmo escopo, dê um nome exclusivo ao módulo. Outra maneira de garantir nomes de módulo exclusivos é deixar de fora a name propriedade, um nome de módulo exclusivo é gerado automaticamente. o no-module-name regra do linter foi criada para impor this cleaner coding practice by flagging any module that still contains um explicit name propriedade.

O exemplo a seguir concatena o nome da implantação ao nome do módulo. Se você fornecer um nome exclusivo para a implantação, o nome do módulo também será exclusivo.

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

Não fornecer nenhum nome de módulo também é válido. Um GUID é gerado como o nome do módulo.

module stgModule 'storageAccount.bicep' = {
  scope: resourceGroup('demoRG')
}

Se você precisar especificar um escopo diferente do escopo do arquivo principal, adicione a propriedade de escopo. Para saber mais, confira Definir escopo do módulo.

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

Para implantar condicionalmente um módulo, adicione uma expressão if. Isso é semelhante à implantação condicional de um recurso.

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

Para implantar mais de uma instância de um módulo, adicione a expressão for. Use o decorador batchSize para especificar se as instâncias são implantadas em série ou em paralelo. Para obter mais informações, veja Loops iterativos no 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>
  }
}]

Assim como os recursos, os módulos são implantados em paralelo, a menos que eles dependam de outros módulos ou recursos. Normalmente, você não precisa definir dependências porque elas são determinadas implicitamente. Se você precisar definir uma dependência explícita, adicione dependsOn à definição do módulo. Para saber mais sobre dependências, consulte Dependências de recursos no Bicep.

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

Caminho para um módulo

Você pode usar um arquivo local ou um arquivo externo para o módulo. Você pode encontrar o arquivo externo em uma especificação de template ou em um registro de módulos do Bicep.

Arquivo local

Se o módulo for um arquivo local, forneça um caminho relativo para esse arquivo. No Bicep, você deve usar o barra (/) separador de diretório for todos os caminhos para garantir compilação consistente entre plataformas. Não há suporte para o caractere de barra invertida (\) do Windows. Os caminhos podem conter espaços.

Para implantar um arquivo que esteja um nível acima no diretório do arquivo principal, use o seguinte exemplo:

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

Arquivo no registro

Há registros de módulos públicos e privados.

Registro de módulo público

Os módulos verificados do Azure são módulos predefinidos, pré-criados e previados que podem ser usados para implantar recursos no Azure. Os funcionários da Microsoft criaram e possuem esses módulos. Eles simplificam e aceleram o processo de implantação para recursos e configurações comuns de Azure. Os módulos também se alinham às práticas recomendadas, como o Azure Well-Architected Framework.

Navegue pelos módulos do Bicep para ver a lista de módulos disponíveis. Selecione os números realçados na captura de tela a seguir para ir diretamente para essa exibição filtrada:

A lista de módulos mostra a versão mais recente. Selecione o número da versão para ver uma lista de versões disponíveis.

Para vincular a um módulo público, especifique o caminho do módulo com a seguinte sintaxe:

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

• br/public: esse é o alias para módulos públicos. Você pode personalizar esse alias no arquivo de configuração do Bicep.
• caminho do arquivo: isso pode conter segmentos separados com o / caractere.
• tag: especifica uma versão para o módulo.

Por exemplo:

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

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

Registro de módulo privado

Se você publicou um módulo em um registro, poderá vincular a esse módulo. Forneça o nome para o registro de contêiner do Azure e um caminho para o módulo. Especifique o caminho do módulo com a seguinte sintaxe:

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

• br: nome do esquema de um registro do Bicep.
• caminho do arquivo: isso é chamado repository no Registro de Contêiner do Azure. O caminho do arquivo pode conter segmentos separados pelo / caractere.
• tag: especifica uma versão para o módulo.

Por exemplo:

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

Quando você faz referência a um módulo em um registro, a extensão Bicep no Visual Studio Code chama bicep restore automaticamente para copiar o módulo externo para o cache local. A restauração do módulo externo demora alguns minutos. Se o IntelliSense para o módulo não funcionar imediatamente, aguarde a conclusão da restauração.

O caminho completo de um módulo em um registro pode ser longo. Em vez de fornecer o caminho completo sempre que você quiser usar o módulo, configure aliases no arquivo bicepconfig.json. Os aliases facilitam a referência do módulo. Por exemplo, com um alias, você pode encurtar o caminho para:

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

O registro de módulo público tem um alias predefinido:

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

Você pode substituir o alias público no arquivo bicepconfig.json .

Começando com Bicep CLI v0.43.1, o Bicep bloqueia explicitamente o uso de domínios personalizados ao referenciar ou restaurar módulos de um ACR (Registro de Contêiner do Azure). Essa proteção impede o uso de configurações sem suporte que, de outra forma, causariam problemas de conformidade.

Se você tentar fazer referência a um domínio personalizado, por moduleStore.myCompany.comexemplo, a CLI Bicep retornará o erro de diagnóstico BCP446. Por exemplo:

module foo 'br:moduleStore.myCompany.com/networking/hub:1.0.0' = { ... }

Bicep valida todos os nomes de host de registro com base em uma lista de permissões interna. Atualmente, somente os seguintes domínios são permitidos:

• *.azurecr.io
• *.azurecr.cn
• *.azurecr.us
• mcr.microsoft.com
• mcr.azure.cn
• ghcr.io

Se sua organização usar domínios personalizados, atualize seus arquivos Bicep para cumprir estas restrições:

• Voltar a usar nomes de host nativos: Atualize todas as referências de módulo do Bicep para usar o domínio nativo .azurecr.io (ou outro domínio específico da nuvem aplicável).
• Limpar o cache local: Depois de atualizar suas referências, talvez seja necessário limpar o cache do módulo local. Execute bicep restore novamente para efetuar pull dos módulos usando os nomes de host nativos corrigidos.

Arquivo na especificação de modelo

Depois de criar uma especificação de modelo, vincule-se a essa especificação de modelo em um módulo. Defina a especificação de modelo no seguinte formato:

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

Para simplificar o arquivo Bicep, crie um alias para o grupo de recursos que contém suas especificações de modelo. Ao usar um alias, a sintaxe será a seguinte:

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

O módulo a seguir implanta uma especificação de modelo para criar uma conta de armazenamento. o assinatura e grupo de recursos for o especificação de modelo são definidos in o alias chamado ContosoSpecs.

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

Usar decoradores

Escreva decoradores no formato @expression e coloque-os acima das declarações do módulo. A tabela a seguir mostra os decoradores disponíveis para módulos:

Os decoradores estão no namespace sys. Se você precisar diferenciar um decorador de outro item com o mesmo nome, prefixe o decorador com sys. Por exemplo, se o arquivo Bicep incluir um parâmetro chamado description, você deverá adicionar o sys namespace ao usar o description decorador.

BatchSize

Você pode aplicar @batchSize() somente a uma definição de recurso ou módulo que usa uma for expressão.

Por padrão, o mecanismo de implantação implanta módulos em paralelo. Ao adicionar o decorador @batchSize(int), você implanta as instâncias em série.

@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}'
  }
}]

Para saber mais, consulte Implantar em lotes.

Description

Para adicionar explicação, adicione uma descrição às declarações do módulo. Por exemplo:

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

Você pode usar o texto formatado por Markdown para o texto de descrição.

Parameters

Os parâmetros que você fornece na definição de módulo correspondem aos parâmetros no arquivo Bicep.

O exemplo Bicep a seguir tem três parâmetros: storagePrefix, storageSKUe location. O storageSKU parâmetro tem um valor padrão, portanto, você não precisa fornecer um valor para esse parâmetro durante a implantação.

@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@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Para usar o exemplo anterior como um módulo, forneça valores para esses parâmetros.

targetScope = 'subscription'

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

resource demoRG 'Microsoft.Resources/resourceGroups@2025-04-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

Definir escopo do módulo

Ao declarar um módulo, defina um escopo para o módulo diferente do escopo do arquivo Bicep que o contém. Use a propriedade scope para definir o escopo do módulo. Quando você não fornece o scope propriedade, o o módulo é implantado at o escopo de destino do pai.

O arquivo Bicep a seguir cria um grupo de recursos e uma conta de armazenamento nesse grupo de recursos. O arquivo é implantado em uma assinatura, mas o módulo está no escopo do novo grupo de recursos.

// 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@2025-04-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

O exemplo a seguir implanta contas de armazenamento em dois grupos de recursos diferentes. Os dois grupos de recursos precisam já existir.

targetScope = 'subscription'

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

resource secondRG 'Microsoft.Resources/resourceGroups@2025-04-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'
  }
}

Defina a scope propriedade como um objeto de escopo válido. Se o arquivo Bicep implantar um grupo de recursos, assinatura, ou grupo de gerenciamento, defina o escopo for um module para o nome simbólico for that recurso. Ou use as funções de escopo para obter um escopo válido.

Essas funções são:

• resourceGroup
• subscription
• managementGroup
• tenant

O exemplo a seguir usa a função managementGroup para definir o escopo.

param managementGroupName string

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

Output

Você pode obter valores de um módulo e usá-los no arquivo principal do Bicep. Para obter um valor de saída de um módulo, use a propriedade outputs no objeto do módulo.

O primeiro exemplo cria uma conta de armazenamento e retorna os pontos de extremidade primários:

@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@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Ao usar a propriedade como um módulo, você pode obter esse valor de saída:

targetScope = 'subscription'

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

resource demoRG 'Microsoft.Resources/resourceGroups@2025-04-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

Ao usar o Bicep versão 0.35.1 ou posterior, você pode aplicar o decorador @secure() às saídas do módulo para marcá-las como sigilosas, garantindo que seus valores não sejam expostos em logs ou no histórico de implantação. Essa abordagem é útil quando um módulo precisa retornar dados confidenciais, como uma chave gerada ou uma cadeia de conexão, ao arquivo Bicep pai sem correr o risco de exposição. Para obter mais informações, consulte Saídas seguras.

Identidade de módulo

A partir do Bicep versão 0.36.1, você pode atribuir uma identidade gerenciada atribuída pelo usuário a um módulo. Essa identidade está disponível no módulo , por exemplo, para acessar um Key Vault. No entanto, os serviços de back-end ainda não dão suporte a essa funcionalidade.

param identityId string

module mod './module.bicep' = {
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identityId}': {}
    }
  }
  name: 'mod'
  params: {
    keyVaultUri: 'keyVaultUri'
    identityId: identityId
  }
}

Conteúdo relacionado

• Para passar um valor confidencial para um módulo, use a getSecret função.