Agrupar recursos relacionados usando módulos

Concluído

Você começou a usar modelos Bicep para alguns lançamentos recentes de produtos, e eles foram bem-sucedidos. Como você declarou seus recursos em um arquivo de modelo, pode implantar rapidamente os recursos para lançamentos de novos brinquedos sem precisar configurar manualmente os recursos no portal do Azure.

O gerente de TI pode ver que seu código Bicep está se tornando mais complexo e tem um número crescente de recursos definidos, então eles perguntaram se você pode tornar o código mais modularizado. Você pode criar arquivos Bicep individuais, chamados módulos, para diferentes partes de sua implantação. O modelo principal do Bíceps pode fazer referência a esses módulos. Nos bastidores, os módulos são transempilhados em um único modelo JSON para implantação.

Os módulos também são uma forma de tornar o código Bicep ainda mais reutilizável. Você pode ter um único módulo Bicep que muitos outros modelos Bicep usam.

Muitas vezes, você também precisará emitir saídas dos módulos e modelos do Bíceps. As saídas são uma maneira de seu código Bicep enviar dados de volta para quem ou o que quer que tenha iniciado a implantação. Vejamos primeiro as saídas.

Nota

Os comandos nesta unidade são mostrados para ilustrar conceitos. Não execute os comandos ainda. Você vai praticar o que você aprende aqui em breve.

Saídas

Um ser humano pode implantar manualmente modelos do Bicep, ou algum tipo de processo de liberação automatizado pode implantá-los. De qualquer forma, é comum ter alguns dados do modelo que você precisa enviar de volta para quem ou o que quer que esteja executando a implantação do modelo.

Aqui estão alguns exemplos de cenários em que você pode precisar obter informações da implantação do modelo:

• Você cria um modelo Bicep que implanta uma máquina virtual e precisa obter o endereço IP público para que possa SSH na máquina.
• Você cria um modelo Bicep que aceita um conjunto de parâmetros, como um nome de ambiente e um nome de aplicativo. O modelo usa uma expressão para nomear um aplicativo do Serviço de Aplicativo do Azure que ele implanta. Você precisa gerar o nome do aplicativo que o modelo implantou para poder usá-lo em um pipeline de implantação para publicar os binários do aplicativo.

Você pode usar saídas para esses cenários. Para definir uma saída em um modelo Bicep, use a output palavra-chave assim:

output appServiceAppName string = appServiceAppName

A definição de saída inclui algumas partes principais:

• A output palavra-chave diz ao Bicep que você está definindo uma saída.
• appServiceAppName é o nome da saída. Quando alguém implanta o modelo com êxito, os valores de saída incluem o nome especificado para que ele possa acessar os valores esperados.
• string é o tipo de saída. As saídas do bíceps suportam os mesmos tipos que os parâmetros.
• Um valor deve ser especificado para cada saída. Ao contrário dos parâmetros, as saídas sempre precisam ter valores. Os valores de saída podem ser expressões, referências a parâmetros ou variáveis ou propriedades de recursos implantados no arquivo.

Gorjeta

As saídas podem usar os mesmos nomes que variáveis e parâmetros. Essa convenção pode ser útil se você construir uma expressão complexa dentro de uma variável para usar dentro dos recursos do modelo, e também precisar expor o valor da variável como uma saída.

Aqui está outro exemplo de uma saída. Este terá seu valor definido como o nome de domínio totalmente qualificado (FQDN) de um recurso de endereço IP público.

output ipFqdn string = publicIPAddress.properties.dnsSettings.fqdn

Gorjeta

Tente usar propriedades de recursos como saídas em vez de fazer suposições sobre como os recursos se comportarão. Por exemplo, se você precisar ter uma saída para a URL do aplicativo do Serviço de Aplicativo, use a propriedade do defaultHostName aplicativo em vez de criar uma cadeia de caracteres para a URL por conta própria. Às vezes, essas suposições não são válidas em ambientes diferentes, ou a maneira como o recurso funciona muda, então é mais seguro que o recurso diga suas próprias propriedades.

Atenção

Não crie saídas para valores secretos, como cadeias de conexão ou chaves. Qualquer pessoa com acesso ao seu grupo de recursos pode ler saídas de modelos. Há outras abordagens que você pode usar para obter acesso a propriedades de recursos secretos, que abordaremos em um módulo posterior.

Definir um módulo

Os módulos Bicep permitem que você organize e reutilize seu código Bicep criando unidades menores que podem ser compostas em um modelo. Qualquer modelo Bicep pode ser usado como um módulo por outro modelo. Ao longo deste módulo de aprendizagem, você criou modelos de Bíceps. Isso significa que você já criou arquivos que podem ser usados como módulos Bicep!

Imagine que você tem um modelo Bicep que implanta recursos de aplicativo, banco de dados e rede para a solução A. Você pode dividir esse modelo em três módulos, cada um deles focado em seu próprio conjunto de recursos. Como bônus, agora você pode reutilizar os módulos em outros modelos para outras soluções também; portanto, ao desenvolver um modelo para a solução B, que tem requisitos de rede semelhantes aos da solução A, você pode reutilizar o módulo de rede.

Quando desejar que o modelo inclua uma referência a um arquivo de módulo, use a module palavra-chave. Uma definição de módulo é semelhante a uma declaração de recurso, mas em vez de incluir um tipo de recurso e uma versão da API, você usará o nome do arquivo do módulo:

module myModule 'modules/mymodule.bicep' = {
  name: 'MyModule'
  params: {
    location: location
  }
}

Vejamos de perto algumas partes-chave desta definição de módulo:

• A module palavra-chave diz ao Bicep que você está prestes a usar outro arquivo Bicep como um módulo.
• Assim como os recursos, os módulos precisam de um nome simbólico como myModule. Você usará o nome simbólico quando se referir às saídas do módulo em outras partes do modelo.
• modules/mymodule.bicep é o caminho para o arquivo de módulo, relativo ao arquivo de modelo. Lembre-se, um arquivo de módulo é apenas um arquivo Bicep regular.
• Assim como os recursos, a name propriedade é obrigatória. O Azure usa o nome do módulo porque cria uma implantação separada para cada módulo dentro do arquivo de modelo. Essas implantações têm nomes que você pode usar para identificá-las.
• Você pode especificar quaisquer parâmetros do módulo usando a params palavra-chave. Ao definir os valores de cada parâmetro dentro do modelo, você pode usar expressões, parâmetros de modelo, variáveis, propriedades de recursos implantados no modelo e saídas de outros módulos. O Bíceps compreenderá automaticamente as dependências entre os recursos.

Módulos e saídas

Assim como os modelos, os módulos Bicep podem definir saídas. É comum encadear módulos dentro de um modelo. Nesse caso, a saída de um módulo pode ser um parâmetro para outro módulo. Usando módulos e saídas juntos, você pode criar arquivos Bicep poderosos e reutilizáveis.

Projete seus módulos

Um bom módulo Bicep segue alguns princípios-chave:

• Um módulo deve ter uma finalidade clara. Você pode usar módulos para definir todos os recursos relacionados a uma parte específica da sua solução. Por exemplo, você pode criar um módulo que contenha todos os recursos usados para monitorar seu aplicativo. Você também pode usar um módulo para definir um conjunto de recursos que pertencem juntos, como todos os seus servidores de banco de dados e bancos de dados.

• Não coloque cada recurso em seu próprio módulo. Você não deve criar um módulo separado para cada recurso implantado. Se você tiver um recurso que tenha muitas propriedades complexas, pode fazer sentido colocar esse recurso em seu próprio módulo, mas, em geral, é melhor que os módulos combinem vários recursos.

• Um módulo deve ter parâmetros claros e saídas que façam sentido. Considere o objetivo do módulo. Pense se o módulo deve manipular valores de parâmetro ou se o modelo pai deve lidar com isso e, em seguida, passar um único valor para o módulo. Da mesma forma, pense nas saídas que um módulo deve retornar e certifique-se de que elas sejam úteis para os modelos que usarão o módulo.

• Um módulo deve ser o mais autónomo possível. Se um módulo precisar usar uma variável para definir uma parte de um módulo, a variável geralmente deve ser incluída no arquivo de módulo em vez de no modelo pai.

• Um módulo não deve gerar segredos. Assim como os modelos, não crie saídas de módulo para valores secretos, como cadeias de conexão ou chaves.