Validação Pré-voo de Implantação do Azure

Esta habilidade valida implantações Bicep antes da execução, suportando fluxos de trabalho do Azure CLI (az) e do Azure Developer CLI (azd).

Quando Usar Esta Habilidade

• Antes de implantar infraestrutura no Azure
• Ao preparar ou revisar arquivos Bicep
• Para pré-visualizar quais alterações uma implantação fará
• Para verificar se as permissões são suficientes para a implantação
• Antes de executar os comandos azd up, azd provision ou az deployment

Processo de Validação

Siga estas etapas em ordem. Continue para a próxima etapa mesmo que uma etapa anterior falhe — capture todos os problemas no relatório final.

Etapa 1: Detectar Tipo de Projeto

Determine o fluxo de trabalho de implantação verificando os indicadores do projeto:

1. Verificar projeto azd: Procure por azure.yaml na raiz do projeto

   • Se encontrado → Use fluxo de trabalho azd
   • Se não encontrado → Use fluxo de trabalho az CLI

2. Localizar arquivos Bicep: Encontre todos os arquivos .bicep para validar

   • Para projetos azd: Verifique primeiro o diretório infra/, depois a raiz do projeto
   • Para autônomo: Use o arquivo especificado pelo usuário ou pesquise locais comuns (infra/, deploy/, raiz do projeto)

3. Detectar automaticamente arquivos de parâmetros: Para cada arquivo Bicep, procure por arquivos de parâmetros correspondentes:

   • <filename>.bicepparam (parâmetros Bicep — preferencial)
   • <filename>.parameters.json (parâmetros JSON)
   • parameters.json ou parameters/<env>.json no mesmo diretório

Etapa 2: Validar Sintaxe Bicep

Execute o Bicep CLI para verificar a sintaxe do template antes de tentar a validação da implantação:

bicep build <bicep-file> --stdout

O que capturar:

• Erros de sintaxe com números de linha/coluna
• Mensagens de aviso
• Status de sucesso/falha da compilação

Se o Bicep CLI não estiver instalado:

• Anote o problema no relatório
• Continue para a Etapa 3 (o Azure validará a sintaxe durante o what-if)

Etapa 3: Executar Validação Pré-voo

Escolha a validação apropriada com base no tipo de projeto detectado na Etapa 1.

Para Projetos azd (azure.yaml existe)

Use azd provision --preview para validar a implantação:

azd provision --preview

Se um ambiente for especificado ou vários ambientes existirem:

azd provision --preview --environment <env-name>

Bicep Autônomo (sem azure.yaml)

Determine o escopo da implantação a partir da declaração targetScope do arquivo Bicep:

Execute primeiro com o nível de validação do Provedor:

# Resource Group scope (most common)
az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Subscription scope
az deployment sub what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Management Group scope
az deployment mg what-if \
  --location <location> \
  --management-group-id <mg-id> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Tenant scope
az deployment tenant what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

Estratégia de Fallback:

Se --validation-level Provider falhar com erros de permissão (RBAC), tente novamente com ProviderNoRbac:

az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --validation-level ProviderNoRbac

Anote o fallback no relatório — o usuário pode não ter permissões completas de implantação.

Etapa 4: Capturar Resultados do What-If

Analise a saída do what-if para categorizar as alterações de recursos:

Para recursos modificados, capture as alterações específicas de propriedade.

Etapa 5: Gerar Relatório

Crie um arquivo de relatório Markdown na raiz do projeto chamado:

• preflight-report.md

Use a estrutura de template de references/REPORT-TEMPLATE.md.

Seções do Relatório:

…