Criar e usar módulos Bicep

  • 10 minutos

Os módulos são arquivos Bicep independentes. Eles geralmente contêm conjuntos de recursos que são implantados juntos. Os módulos podem ser consumidos a partir de qualquer outro modelo Bicep.

Usando módulos, você pode reutilizar seu código Bicep, e você pode tornar seus arquivos Bicep mais legíveis e compreensíveis porque cada um deles está focado em um trabalho específico. Seus modelos principais compõem, então, vários módulos juntos.

Os benefícios dos módulos

Em sua empresa de brinquedos, você tem provisionado recursos de nuvem usando muitos arquivos Bicep individuais. Com o tempo, esses modelos crescem significativamente. Eventualmente, você acaba tendo um código monolítico que é difícil de ler e navegar, e ainda mais difícil de manter.

Essa abordagem também força você a duplicar partes do seu código quando quiser reutilizá-lo em outros modelos. Quando você altera algo, você precisa pesquisar e atualizar vários arquivos.

Os módulos Bicep ajudam você a enfrentar esses desafios, dividindo seu código em arquivos menores e mais gerenciáveis que vários modelos podem referenciar. Os módulos oferecem alguns benefícios importantes.

Reutilização

Depois de criar um módulo, você pode reutilizá-lo em vários arquivos Bicep, mesmo que os arquivos sejam para projetos ou cargas de trabalho diferentes. Por exemplo, ao criar uma solução, você pode criar módulos separados para os componentes do aplicativo, o banco de dados e os recursos relacionados à rede. Em seguida, quando você começar a trabalhar em outro projeto com requisitos de rede semelhantes, você pode reutilizar o módulo relevante.

Diagrama que mostra um modelo que faz referência a três módulos: aplicativo, banco de dados e rede. O módulo de rede é então reutilizado em outro modelo.

Pode até partilhar módulos dentro da sua equipa, na sua organização ou com a comunidade do Azure. Você aprenderá mais sobre como compartilhar módulos Bicep em um módulo futuro do Microsoft Learn.

Encapsulamento

Os módulos ajudam a manter as definições de recursos relacionadas juntas. Por exemplo, quando você define um aplicativo do Azure Functions, normalmente implanta o aplicativo, um plano de hospedagem para o aplicativo e uma conta de armazenamento para os metadados do aplicativo. Esses três componentes são definidos separadamente, mas representam um agrupamento lógico de recursos, então pode fazer sentido defini-los como um módulo.

Dessa forma, seu modelo principal não precisa estar ciente dos detalhes de como um aplicativo de função é implantado. Essa é a responsabilidade do módulo.

Capacidade de composição

Depois de criar um conjunto de módulos, você pode compô-los juntos. Por exemplo, você pode criar um módulo que implanta uma rede virtual e outro módulo que implanta uma máquina virtual. Você define parâmetros e saídas para cada módulo para que você possa pegar as informações importantes de um e enviá-las para o outro.

Diagrama que mostra um modelo referenciando dois módulos e passando a saída de um para o parâmetro de outro.

Gorjeta

É útil pensar nos módulos Bicep como blocos de construção que você pode combinar de diferentes maneiras para dar suporte às suas implantações.

Caraterística

Ocasionalmente, você pode precisar usar módulos para acessar determinadas funcionalidades. Por exemplo, você pode usar módulos e loops juntos para implantar vários conjuntos de recursos. Você também pode usar módulos para definir recursos em escopos diferentes em uma única implantação.

Criar um módulo

Um módulo é um arquivo Bicep normal. Você irá criá-lo como faz com qualquer outro arquivo Bicep.

Geralmente, não é uma boa prática criar um módulo para cada recurso implantado. Um bom módulo Bicep normalmente define vários recursos relacionados. No entanto, se você tiver um recurso complexo com muita configuração, talvez faça sentido criar um único módulo para encapsular a complexidade. Essa abordagem mantém seus modelos principais simples e organizados.

Dividir um modelo Bicep existente em módulos

Você pode criar um modelo Bicep grande e, em seguida, decidir que ele deve ser dividido em módulos. Às vezes, é óbvio como você deve dividir um arquivo Bicep grande. Você pode ter um conjunto de recursos que claramente pertencem juntos em um módulo. Outras vezes, não é tão simples determinar os recursos que devem ser agrupados em um módulo.

O visualizador Bicep pode ajudá-lo a colocar todo o seu arquivo Bicep em perspetiva. O visualizador está incluído na extensão Bicep para Visual Studio Code.

Para exibir o visualizador, abra o Visual Studio Code Explorer, selecione e segure (ou clique com o botão direito do mouse) o arquivo Bicep e, em seguida, selecione Abrir Bicep Visualizer. O visualizador mostra uma representação gráfica dos recursos no arquivo Bicep. Inclui linhas entre recursos para mostrar as dependências que o Bicep deteta.

Você pode usar o visualizador para ajudá-lo a dividir seus arquivos. Considere se a visualização ilustra quaisquer clusters de recursos. Pode fazer sentido mover esses clusters para um módulo juntos.

Por exemplo, considere a seguinte visualização para um arquivo Bicep. São definidos dois conjuntos distintos de recursos. Pode fazer sentido agrupá-los em módulos de banco de dados e de rede separados.

Módulos de aninhamento

Os módulos podem incluir outros módulos. Usando essa técnica de aninhamento, você pode criar alguns módulos que implantam pequenos conjuntos de recursos e, em seguida, compô-los em módulos maiores que definem topologias complexas de recursos. Um modelo combina essas peças em um artefato implantável.

Gorjeta

Embora seja possível aninhar várias camadas de módulos, isso pode se tornar complexo. Se você receber um erro ou algo der errado, é mais difícil descobrir o que você precisa corrigir quando você tem muitas camadas de aninhamento.

Para implantações complexas, às vezes faz sentido usar pipelines de implantação para implantar vários modelos em vez de criar um único modelo que faz tudo com aninhamento. Você aprenderá mais sobre pipelines de implantação em um módulo futuro do Microsoft Learn.

Escolha bons nomes de arquivo

Certifique-se de usar um nome de arquivo descritivo para cada módulo. O nome do arquivo torna-se efetivamente o identificador do módulo. É importante que seus colegas possam entender o propósito do módulo apenas olhando para o nome do arquivo.

Usar o módulo em um modelo Bicep

Você usará um módulo em um modelo Bicep usando a module palavra-chave, da seguinte forma:

module appModule 'modules/app.bicep' = {
  name: 'myApp'
  params: {
    location: location
    appServiceAppName: appServiceAppName
    environmentType: environmentType
  }
}

Uma definição de módulo inclui os seguintes componentes:

  • A palavra-chave module.
  • Um nome simbólico, como appModule. Este nome é usado dentro deste arquivo Bicep sempre que você quiser se referir ao módulo. O nome simbólico nunca aparece no Azure.
  • O caminho do módulo, como modules/app.bicep. Normalmente, esse é o caminho para um arquivo Bicep no sistema de arquivos local. Em um módulo futuro do Microsoft Learn, você aprenderá sobre como compartilhar módulos usando registros e especificações de modelo, que têm seus próprios formatos de caminho de módulo.

    Gorjeta

    Você também pode usar um modelo JSON Azure Resource Manager (modelo ARM) como um módulo. Essa capacidade pode ser útil se você tiver um conjunto de modelos que ainda não migrou para o Bicep.

  • A name propriedade, que especifica o nome da implantação. Você aprenderá mais sobre implantações na próxima seção.
  • A params propriedade, onde você pode especificar valores para os parâmetros que o módulo espera. Você aprenderá mais sobre os parâmetros do módulo na próxima unidade.

Como funcionam os módulos

Entender como os módulos funcionam não é necessário para usá-los, mas pode ajudá-lo a investigar problemas com suas implantações ou ajudar a explicar o comportamento inesperado.

Implementações

No Azure, uma implantação é um recurso especial que representa uma operação de implantação. As implantações são recursos do Azure que têm o tipo Microsoft.Resources/deploymentsde recurso . Ao enviar uma implantação do Bicep, você cria ou atualiza um recurso de implantação. Da mesma forma, quando você cria recursos no portal do Azure, o portal cria um recurso de implantação em seu nome.

No entanto, nem todas as alterações nos recursos do Azure criam ou usam implantações. Por exemplo, quando você usa o portal do Azure para modificar um recurso existente, ele geralmente não cria uma implantação para fazer a alteração. Quando você usa ferramentas de terceiros como o Terraform para implantar ou configurar seus recursos, eles podem não criar implantações.

Ao implantar um arquivo Bicep usando a CLI do Azure ou o Azure PowerShell, você pode, opcionalmente, especificar o nome da implantação. Se você não especificar um nome, a CLI do Azure ou o Azure PowerShell criará automaticamente um nome de implantação para você a partir do nome de arquivo do modelo. Por exemplo, se você implantar um arquivo chamado main.bicep, o nome de implantação padrão será main.

Quando você usa módulos, o Bicep cria uma implantação separada para cada módulo. A name propriedade especificada para o módulo torna-se o nome da implantação. Quando você implanta um arquivo Bicep que contém um módulo, vários recursos de implantação são criados: um para o modelo pai e um para cada módulo.

Por exemplo, suponha que você crie um arquivo Bicep chamado main.bicep. Ele define um módulo chamado myApp. Quando você implanta o arquivo main.bicep , duas implantações são criadas. O primeiro é chamado main, e cria outra implantação nomeada myApp que contém os recursos do aplicativo.

Diagrama que mostra dois arquivos Bicep, cada um dos quais tem um nome de implantação separado.

Você pode listar e exibir os detalhes dos recursos de implantação para monitorar o status de suas implantações do Bicep ou para exibir o histórico de implantações. No entanto, quando você reutiliza o mesmo nome para uma implantação, o Azure substitui a última implantação com o mesmo nome. Se você precisar manter o histórico de implantação, certifique-se de usar um nome exclusivo para cada implantação. Você pode incluir a data e a hora da implantação no nome para ajudar a torná-la exclusiva.

Modelos JSON ARM gerados

Quando você implanta um arquivo Bicep, o Bicep o converte em um modelo JSON ARM. Esta conversão também é chamada de transpilação. Os módulos que o modelo usa são incorporados no arquivo JSON. Independentemente de quantos módulos você incluir em seu modelo, apenas um único arquivo JSON será criado.

No exemplo discutido na seção anterior, o Bicep gera um único arquivo JSON mesmo que originalmente houvesse dois arquivos Bicep.

Diagrama que mostra dois arquivos Bicep, que são transempilhados em um único arquivo JSON.