Gerar os modelos de Bicep com o GitHub Copilot

  • 12 minutos

Dica

Consulte a guia Texto e imagens para obter mais detalhes!

Bicep é a linguagem específica do domínio de Microsoft para implantar recursos de Azure. Ele é compilado em modelos JSON do Azure Resource Manager, mas é mais legível e conciso. O Bicep elimina o código repetitivo do Azure Resource Manager, mantendo o modelo declarativo.

Uma definição básica de recurso do Bicep tem a seguinte forma:

param location string = 'eastus'
param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
    supportsHttpsTrafficOnly: true
    minimumTlsVersion: 'TLS1_2'
  }
}

Três coisas a observar: o @ símbolo separa o tipo de recurso da versão da API, os parâmetros são declarados na parte superior e as referências de recurso usam nomes simbólicos em vez de IDs de recurso. Esses padrões são importantes ao revisar a saída do Copilot.

Esta unidade tem como foco o uso do Copilot para gerar, estender e otimizar modelos de Bicep. Para obter uma introdução completa ao Bicep, consulte Introdução ao Bicep.

Gerando templates a partir de prompts em linguagem natural

Por padrão, o Copilot gera código Bicep com base em seus dados de treinamento. Nenhuma ferramenta externa nem dados de esquema em tempo real são utilizados. Para tipos de recursos comuns com requisitos específicos, isso já produz uma saída confiável.

Gerando um modelo simples

Comece com um prompt focado em um único recurso para ver o que o Copilot gera. Um prompt bem restrito como este fornece Copilot tudo o que precisa:

Generate a Bicep template for an Azure Storage Account with these requirements:
- Standard_LRS SKU
- StorageV2 kind
- HTTPS-only access enforced
- Minimum TLS version: TLS 1.2
- Blob soft delete enabled with 7-day retention
- Public blob access disabled
- Parameters for: storageAccountName, location (default: eastus),
  environment, owner, costCenter
- Apply tags using a tags object built from the environment, owner,
  and costCenter parameters
- Output the storage account's primary blob endpoint

Você deve obter um arquivo Bicep completo com parâmetros, um bloco de recursos e uma saída. Valide-o imediatamente com az bicep build antes de fazer qualquer outra coisa.

Gerando um modelo de vários recursos

A complexidade aumenta quando vários recursos dependem uns dos outros. Referências de recurso, em que o nome simbólico de um recurso aparece dentro das propriedades de outro recurso, são onde Copilot às vezes precisa de correção.

Experimente este prompt para gerar um conjunto conectado de recursos:

Generate a Bicep template that deploys the following resources:
- An App Service Plan (Standard S1 SKU) on Linux
- An App Service (Web App) using Node 20 on the App Service Plan
- A Key Vault with RBAC authorization enabled and soft delete (90 days)
- A Role Assignment giving the Web App's system-assigned managed identity
  the "Key Vault Secrets User" role on the Key Vault
- Application settings on the Web App pointing to the Key Vault URI

Parameters: appName, location, environment, owner, costCenter
Use symbolic name references for all cross-resource dependencies.
Do not use hardcoded resource IDs.

Verifique se há três problemas comuns neste nível:

  • Dependências circulares: se dois recursos se referirem um ao outro, o Bicep não compila. Verifique o grafo de dependência.
  • Role assignment scope: o recurso roleAssignment precisa do Key Vault como seu escopo, não do grupo de recursos. Verifique a propriedade scope:.
  • Referência de identidade: webApp.identity.principalId é a maneira correta de referenciar a identidade gerenciada. Confirme que o Copilot usa o nome simbólico, e não um valor fixo.

Modularizando um modelo

À medida que os modelos crescem, eles se tornam mais difíceis de manter. Os módulos do Bicep permitem dividir um modelo extenso em componentes reutilizáveis. Copilot pode fazer essa divisão para você.

Refactor this Bicep template into modules. Create:
- A module for the App Service Plan and Web App (modules/webapp.bicep)
- A module for the Key Vault and Role Assignment (modules/keyvault.bicep)
- A main.bicep that calls both modules and passes parameters between them

Show me the content of all three files. Ensure the output of the Key Vault
module (the Key Vault URI) is passed to the Web App module as an input.

Copilot gera os arquivos do módulo e o arquivo de orquestração principal. O mais importante é verificar se os valores output de um módulo estão corretamente conectados como entradas param para outro. Essa conexão entre módulos é o erro mais comum ao dividir modelos.

Bicep MCP: geração sensível ao contexto

O que é MCP?

O PROTOCOLO MCP (Model Context Protocol) é um padrão aberto que permite que os modelos de IA se conectem a ferramentas externas e APIs. Em vez de depender apenas de dados de treinamento, um Copilot habilitado para MCP pode consultar fontes de dados dinâmicas em tempo real.

O servidor MCP do Bicep conecta o GitHub Copilot ao registro de tipos do Bicep em tempo real. Graças a essa conexão, GitHub Copilot obtém acesso a:

  • Versões de API atuais para cada tipo de recurso de Azure
  • O esquema de propriedade completo para cada tipo de recurso
  • Regras de validação que sinalizam configurações incorretas antes de executar bicep build
  • Avisos de descontinuação quando uma versão da API está sendo descontinuada

Sem o MCP, o Copilot gera o Bicep com base em padrões extraídos de seus dados de treinamento. Esses dados têm uma data de corte de conhecimento e as versões da API do Azure evoluem continuamente. O resultado pode ser modelos que usam versões de API desatualizadas, perdem as propriedades necessárias adicionadas recentemente ou incluem parâmetros preteridos. Com o MCP ativo, Copilot consulta o registro dinâmico antes de gerar cada bloco de recursos.

Habilitando o servidor MCP Bicep

  1. No VS Code, abra a Paleta de Comandos (Ctrl+Shift+P).
  2. Pesquisar MCP: Ativar o servidor Bicep.
  3. Confirme se o servidor é mostrado como ativo na barra de status Copilot.

Depois de ser habilitado, o Copilot Chat usa automaticamente o servidor MCP do Bicep quando você trabalha com arquivos .bicep ou faz perguntas sobre recursos do Bicep.

O que muda com o MCP ativo

O mesmo prompt executado com e sem MCP produz uma saída visivelmente diferente em três áreas.

Versões da API

Sem o MCP, Copilot pode gerar:

resource firewall 'Microsoft.Network/azureFirewalls@2022-07-01' = {

Com o MCP, Copilot consulta o registro e gera a versão estável atual:

resource firewall 'Microsoft.Network/azureFirewalls@2024-03-01' = {

As versões de API mais recentes geralmente incluem melhorias de segurança, novas propriedades necessárias e correções de bug.

Propriedades obrigatórias

Alguns tipos de recurso ganharam propriedades necessárias em versões de API mais recentes. Sem o MCP, Copilot pode produzir um modelo que é compilado localmente, mas falha durante a implantação quando Azure valida a solicitação. Com o MCP, Copilot sabe sobre esses requisitos e os inclui.

Validação durante a geração

Com o MCP ativo, Copilot pode sinalizar problemas antes de executar bicep build. Se você escrever um nome de propriedade que não existe no esquema, Copilot poderá identificá-lo imediatamente, semelhante ao IntelliSense para um idioma tipado.

Exemplo: rede hub-spoke com MCP

Use este prompt com o MCP ativo para gerar uma topologia de hub-spoke completa:

Generate a Bicep template for a hub-spoke VNet topology:
- Hub VNet: 10.0.0.0/16 with AzureFirewallSubnet (/26) and GatewaySubnet (/27)
- Spoke VNet: 10.1.0.0/16 with an application subnet (/24)
- VNet peering between hub and spoke (both directions)
- Azure Firewall Standard tier in the hub
- Azure Firewall Policy linked to the firewall
- Public IP for the firewall
- NSG on the application subnet blocking inbound SSH and RDP from internet
- Log Analytics Workspace for diagnostic logging
- Diagnostic settings on the firewall sending logs to the workspace
Parameters: location, environment, owner, costCenter
Use latest stable API versions.

Com o MCP ativo, Copilot usa versões de API atuais, vincula corretamente o recurso firewallPolicy ao recurso AzureFirewall, gera o recurso diagnosticSettings com o formato de matriz logs e metrics correto e usa dependsOn somente em que referências simbólicas não são suficientes.

Validação e práticas recomendadas

Sempre executar az bicep build

Após cada geração do Copilot, execute:

az bicep build --file main.bicep

Esse comando compila Bicep para Azure Resource Manager JSON e captura erros de sintaxe, propriedades necessárias ausentes e referências inválidas. É uma etapa de validação rápida que captura muitos problemas antes da implantação.

Use what-if antes de cada implantação

O comando what-if mostra exatamente o que Azure cria, modifica ou exclui, sem fazer alterações:

az deployment group what-if \
  --resource-group rg-iaclab \
  --template-file main.bicep \
  --parameters @params.json

Revise o resultado antes de cada implantação. Procure recursos sendo excluídos que você não pretendia remover, modificações que parecem inesperadas e uma contagem de recursos que corresponde ao seu design.

Usar arquivos de parâmetro para valores específicos do ambiente

Copilot pode gerar arquivos de parâmetro de seus modelos:

Generate a Bicep parameters file (bicepparam format) for the template above.
Create values appropriate for a staging environment.
Include comments explaining what each parameter controls.

Esse tipo de prompt produz um arquivo .bicepparam que você pode versionar junto com o template, com um arquivo para cada ambiente.

Peça ao Copilot para documentar o resultado

Add @description() decorators to every parameter and output in this template.
The descriptions should be clear enough for someone who has never seen the template
to understand what each parameter controls and what constraints apply.

Este exemplo de prompt torna o template autodocumentado e melhora a saída what-if, que exibe descrições dos parâmetros.

Corrigindo problemas comuns com Copilot

Referência de recurso inválida

Sintoma: bicep build falha com "The referenced resource could not be found."

This Bicep template has an invalid resource reference at line [X].
The resource [name] references [other resource] but uses a hardcoded string
instead of the symbolic name. Fix all cross-resource references to use
symbolic names.

Dependência circular

Sintoma: bicep build falha com "A cycle was detected in the template."

This Bicep template has a circular dependency between [resource A] and
[resource B]. Restructure the template to break the cycle. One approach
is to use an existing() reference for one of the resources.

Versão da API desatualizada

Sintoma: a implantação falha com "The resource type [X] was not found in the namespace."

The resource type [Microsoft.Network/azureFirewalls@2021-02-01] appears to
use an outdated API version. Update it to the current stable API version
and adjust any properties that have changed.