Como criar e usar um módulo no Bicep: passo a passo

Repetir o mesmo bloco de código para cada Storage Account, rede virtual ou base de dados torna os ficheiros Bicep longos e difíceis de manter. Um módulo no Bicep resolve este problema: encapsula um ou mais recursos num ficheiro separado, que passa a ser reutilizável, mais fácil de ler e de testar de forma independente. É o mesmo princípio de uma função na programação: escreves uma vez e reutilizas onde precisares. A seguir vais criar um módulo, passar-lhe parâmetros e ler os seus outputs a partir de um ficheiro principal.

Pré-requisitos

• Uma subscrição do Azure e um Resource Group já criado (por exemplo, rg-demo).
• Azure CLI instalado e sessão iniciada com az login.
• Visual Studio Code com a extensão Bicep (recomendado, mas opcional).
• Conhecimentos básicos de parâmetros e recursos em Bicep.

Passo 1: Criar o módulo

Um módulo é apenas um ficheiro Bicep normal. Cria um ficheiro chamado storageAccount.bicep com os recursos que queres reutilizar. Presta atenção aos param de entrada e aos output de saída: são o contrato do módulo com quem o utiliza. Os decoradores @description() e @allowed() documentam e restringem os valores aceites, tornando o módulo mais seguro.

@description('Prefixo para o nome da Storage Account')
param storagePrefix string

@description('Localização dos recursos')
param location string = resourceGroup().location

@allowed([
  'Standard_LRS'
  'Standard_GRS'
])
param sku string = 'Standard_LRS'

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

resource storage 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageName
  location: location
  sku: {
    name: sku
  }
  kind: 'StorageV2'
}

output storageName string = storage.name
output storageId string = storage.id

A função uniqueString() gera um sufixo determinista que garante um nome único e válido: as Storage Accounts exigem nomes globais em minúsculas, e isto evita o erro de nome já existente.

Dica: mantém cada módulo focado num único objetivo (uma Storage Account, uma rede, uma base de dados). Módulos pequenos e específicos reutilizam-se muito melhor do que um módulo gigante que faz tudo.

Passo 2: Consumir o módulo no ficheiro principal

Cria agora o ficheiro main.bicep. Para chamar o módulo usas a palavra-chave module, seguida de um nome simbólico e do caminho para o ficheiro. Os valores em params correspondem aos param declarados no módulo.

@description('Localização dos recursos')
param location string = resourceGroup().location

module stg 'storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'dados'
    location: location
    sku: 'Standard_LRS'
  }
}

O nome simbólico (stg) serve para referenciar o módulo dentro do ficheiro. A propriedade name é o nome do deployment aninhado que aparece no Azure: é opcional, mas ajuda a identificar cada implementação. Repara que não precisas de passar todos os parâmetros: os que têm valor por omissão no módulo podem ficar de fora quando o valor por defeito serve.

Passo 3: Ler os outputs do módulo

Um módulo pode devolver valores ao ficheiro principal através dos seus output. Para os ler, usa o nome simbólico do módulo seguido de .outputs e do nome do output. Acrescenta ao fim do main.bicep:

output storageAccountName string = stg.outputs.storageName

Desta forma, o nome real da Storage Account criada pelo módulo fica disponível para reutilizar noutros recursos ou para consultar no final do deployment.

Passo 4: Validar e fazer o deploy

Antes de implementar, compila o ficheiro para confirmar que não há erros de sintaxe:

az bicep build --file main.bicep

Se não houver erros, faz o deploy para o teu Resource Group:

az deployment group create --resource-group rg-demo --template-file main.bicep

Verificar o resultado

Quando o comando terminar, confirma que o módulo correu bem consultando os outputs do deployment:

az deployment group show --resource-group rg-demo --name main --query properties.outputs

Deves ver o valor storageAccountName com o nome da Storage Account. No portal do Azure, dentro do Resource Group, encontrarás também um deployment chamado storageDeploy: é a execução do teu módulo registada como deployment aninhado.

Conclusão

Com um módulo, um recurso passa a ser um bloco reutilizável que podes chamar quantas vezes precisares, mudando apenas os parâmetros. O passo seguinte natural é usar um loop for sobre o módulo para criar vários ambientes (dev, teste e produção) a partir do mesmo ficheiro. Qual seria o primeiro recurso da tua infraestrutura a transformar em módulo?