Anterior

Avançar

Criar e usar módulos do Bicep

Concluído

Os módulos são arquivos do Bicep independentes. Normalmente, eles contêm conjuntos de recursos que são implantados juntos. Os módulos podem ser consumidos de qualquer outro modelo do Bicep.

Com os módulos, você pode reutilizar o código do Bicep facilmente e tornar seus arquivos mais legíveis e compreensíveis, pois eles têm como foco um trabalho específico. Os modelos principais compõem vários módulos juntos.

Os benefícios dos módulos

Em sua empresa de brinquedos, você está provisionando recursos de nuvem usando muitos arquivos do Bicep individuais. Ao longo do 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 quer reutilizá-lo em outros modelos. Quando você altera algo, precisa pesquisar vários arquivos e atualizá-los.

Os módulos do Bicep ajudam a resolver 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.

Capacidade de reutilização

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

Você pode até mesmo compartilhar módulos dentro de sua equipe, em sua organização ou com a comunidade do Azure. Você aprenderá mais sobre o compartilhamento de módulos do Bicep em um futuro módulo do Microsoft Learn.

Encapsulamento

Os módulos ajudam você 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. Portanto, pode fazer sentido defini-los como um módulo.

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

Modularidade

Depois de criar um conjunto de módulos, você poderá redigi-los. 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 os parâmetros e as saídas de cada módulo para poder obter informações importantes de um e enviá-las para o outro.

Dica

É útil considerar os módulos do Bicep como blocos de construção que você pode combinar de maneiras diferentes para dar suporte a suas implantações.

Funcionalidade

Ocasionalmente, talvez seja necessário 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 normal do Bicep. Você o criará exatamente como faz com qualquer outro arquivo do Bicep.

Em geral, não é uma boa prática criar um módulo para cada recurso que você implantar. Um bom módulo do 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 existente do Bicep em módulos

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

O visualizador do Bicep pode ajudar você a colocar todo o arquivo do Bicep em perspectiva. O visualizador está incluído na extensão do 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) no arquivo do Bicep e, em seguida, selecione Abrir Visualizador do Bicep. O visualizador mostra uma representação gráfica dos recursos em seu arquivo do Bicep. Ele inclui linhas entre recursos para mostrar as dependências detectadas pelo Bicep.

Você pode usar o visualizador para ajudar na divisão de seus arquivos. Considere se a visualização ilustra qualquer cluster de recursos. Pode fazer sentido mover esses clusters para um mesmo módulo.

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

Visualizador

Agrupamento

Aninhar módulos

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, compor isso em módulos maiores que definem topologias complexas de recursos. Um modelo combina essas partes em um artefato implantável.

Dica

Embora seja possível aninhar várias camadas de módulos, isso pode se tornar complexo. Se você receber um erro ou se algo der errado, será mais difícil descobrir o que você precisa corrigir quando tiver 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.

Escolher bons nomes de arquivo

Use um nome de arquivo descritivo para cada módulo. O nome do arquivo efetivamente se torna o identificador do módulo. É importante que seus colegas entendam a finalidade do módulo apenas observando o nome do arquivo.

Usar o módulo em um modelo do Bicep

Você usará um módulo em um modelo do Bicep usando a palavra-chave module, desta 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. Esse nome é usado dentro desse arquivo do Bicep sempre que você deseja consultar o 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 do Bicep em seu sistema de arquivos local. Em um módulo futuro do Microsoft Learn, você aprenderá como compartilhar módulos usando registros e especificações de modelo, que têm seus próprios formatos de caminho de módulo.

  Dica

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

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

Como os módulos funcionam

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

Implantaçõ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 de recurso Microsoft.Resources/deployments. 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, elas podem não criar implantações.

Ao implantar um arquivo do Bicep usando a CLI do Azure ou o Azure PowerShell, opcionalmente, você pode 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ê com base no nome do arquivo do modelo. Por exemplo, se você implantar um arquivo chamado main.bicep, o nome da implantação padrão será main.

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

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

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, use 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 do ARM JSON gerados

Quando você implanta um arquivo do Bicep, o Bicep o converte em um modelo do ARM JSON. Essa conversão também é chamada de transpilação. Os módulos que o modelo usa são inseridos 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, embora houvesse originalmente dois arquivos do Bicep.

Continuar