Adicionar parâmetros e saídas aos módulos

  • 7 minutos

Cada módulo que você cria deve ter um propósito claro. Pense num módulo como tendo um contrato. Ele aceita um conjunto de parâmetros, cria um conjunto de recursos e pode fornecer algumas saídas de volta para o modelo pai. Quem usa o módulo não precisa se preocupar com como ele funciona, apenas que ele faz o que espera.

Ao planejar um módulo, considere:

  • O que você precisa saber para poder cumprir o propósito do módulo.
  • O que qualquer pessoa que consome seu módulo esperará fornecer.
  • O que qualquer pessoa que consome seu módulo esperará acessar como saídas.

Parâmetros do módulo

Pense nos parâmetros que seu módulo aceita e se cada parâmetro deve ser opcional ou obrigatório.

Quando você cria parâmetros para modelos, é uma boa prática adicionar parâmetros padrão onde for possível. Em módulos, nem sempre é tão importante adicionar parâmetros padrão, porque seu módulo será usado por um modelo pai que pode usar seus próprios parâmetros padrão. Se você tiver parâmetros semelhantes em ambos os arquivos, ambos com valores padrão, pode ser difícil para os usuários do seu modelo descobrir qual valor padrão será aplicado e impor consistência. Muitas vezes, é melhor deixar o valor padrão no modelo pai e removê-lo do módulo.

Você também deve pensar em como gerenciar parâmetros que controlam as SKUs para seus recursos e outras definições de configuração importantes. Quando você cria um modelo Bicep autônomo, é comum incorporar regras de negócios em seu modelo. Por exemplo: quando implanto um ambiente de produção, a conta de armazenamento deve usar a camada GRS. Mas os módulos às vezes apresentam preocupações diferentes.

Se você estiver criando um módulo que precisa ser reutilizável e flexível, lembre-se de que as regras de negócios para cada modelo pai podem ser diferentes, portanto, pode não fazer tanto sentido incorporar regras de negócios em módulos genéricos. Considere definir as regras de negócios em seu modelo pai e, em seguida, passe explicitamente a configuração do módulo pelos parâmetros.

No entanto, se você criar um módulo destinado a facilitar para sua própria organização a implantação de recursos que atendam às suas necessidades específicas, faz sentido incluir regras de negócios para simplificar os modelos pai.

Quaisquer que sejam os parâmetros incluídos no módulo, certifique-se de adicionar uma descrição significativa usando o @description atributo:

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

Condições de utilização

Um dos objetivos com a implantação de uma infraestrutura usando código como o Bicep é evitar a duplicação de esforços, ou até mesmo criar vários modelos para os mesmos fins ou semelhantes. Os recursos do Bíceps oferecem uma poderosa caixa de ferramentas para criar módulos reutilizáveis que funcionam para várias situações. Você pode combinar recursos como módulos, expressões, valores de parâmetros padrão e condições para criar código reutilizável que oferece a flexibilidade necessária.

Suponha que você esteja criando um módulo que implanta uma conta do Azure Cosmos DB. Quando ele é implantado em seu ambiente de produção, você precisa configurar a conta para enviar seus logs para um espaço de trabalho do Log Analytics. Para configurar logs a serem enviados para o Log Analytics, você definirá um recurso diagnosticSettings .

Você pode atingir seu requisito adicionando uma condição à definição de recurso e tornando o parâmetro ID do espaço de trabalho opcional adicionando um valor padrão:

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

Ao incluir esse módulo em um modelo Bicep, você pode configurá-lo facilmente para enviar os logs de conta do Azure Cosmos DB para o Log Analytics definindo uma ID de espaço de trabalho. Ou, se você não precisar de logs para o ambiente que está implantando, omita o parâmetro. Ele tem um valor padrão. O módulo encapsula a lógica necessária para fazer a coisa certa para suas necessidades.

Gorjeta

Lembre-se de testar se o seu modelo é válido para ambos os cenários; quando a if instrução é avaliada como ou true false.

Saídas do módulo

Os módulos podem definir saídas. É uma boa ideia criar uma saída para as informações que o modelo pai pode precisar usar. Por exemplo, se o módulo definir uma conta de armazenamento, considere criar uma saída para o nome da conta de armazenamento para que o modelo pai possa acessá-la.

Aviso

Não use saídas para valores secretos. As saídas são registradas como parte do histórico de implantação, portanto, não são apropriadas para valores seguros. Em vez disso, você pode considerar uma das seguintes opções:

  • Use uma saída para fornecer o nome do recurso. Em seguida, o modelo pai pode criar um existing recurso com esse nome e pode procurar o valor seguro dinamicamente.
  • Escreva o valor em um segredo do Cofre da Chave do Azure. Peça ao modelo pai que leia o segredo do cofre quando precisar.

Um modelo pai pode usar saídas de módulo em variáveis, pode usar propriedades para outras definições de recursos ou pode expor variáveis e propriedades como saídas propriamente ditas. Ao expor e usar saídas em todos os seus arquivos Bicep, você pode criar conjuntos reutilizáveis de módulos Bicep que podem ser compartilhados com sua equipe e reutilizados em várias implantações. Também é uma boa prática adicionar uma descrição significativa às saídas usando o @description atributo:

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

Gorjeta

Você também pode usar serviços dedicados para armazenar, gerenciar e acessar as configurações que seu modelo Bicep cria. O Key Vault foi projetado para armazenar valores seguros. A Configuração de Aplicativo do Azure foi projetada para armazenar outros valores (não seguros).

Encadear módulos juntos

É comum criar um arquivo Bicep pai que compõe vários módulos juntos. Por exemplo, imagine que você está criando um novo modelo Bicep para implantar máquinas virtuais que usam redes virtuais dedicadas. Você pode criar um módulo para definir uma rede virtual. Em seguida, você pode pegar o ID do recurso de sub-rede da rede virtual como uma saída desse módulo e usá-lo como uma entrada para o módulo da máquina virtual:

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

Neste exemplo, nomes simbólicos são usados para a referência entre os módulos. Esta referência ajuda o Bicep a compreender automaticamente as relações entre os módulos.

Como o Bicep entende que há uma dependência, ele implanta os módulos em sequência:

  1. O Bicep implanta tudo no virtualNetwork módulo.
  2. Se essa implantação for bem-sucedida, o Bicep acessará o valor de saída e o passará para o subnetResourceId virtualMachine módulo como um parâmetro.
  3. O Bicep implanta tudo no virtualMachine módulo.

Nota

Quando você depende de um módulo, o Bicep aguarda a conclusão de toda a implantação do módulo. É importante lembrar isso ao planejar seus módulos. Se você criar um módulo que define um recurso que leva muito tempo para ser implantado, quaisquer outros recursos que dependam desse módulo aguardarão a conclusão da implantação de todo o módulo.