Laboratório de Troubleshooting: Export a deployment as an Azure Resource Manager template or convert an Azure Resource Manager template to a Bicep file
Cenários de Diagnóstico
Cenário 1 — Causa Raiz
Um administrador exportou o template ARM de um grupo de recursos contendo uma conta de armazenamento, um plano de App Service e uma Web App. O grupo de recursos foi criado há dois anos e nunca teve seus recursos recriados. A assinatura está ativa, o administrador possui a role Contributor no grupo de recursos e a exportação foi concluída sem mensagem de erro no portal.
Ao tentar reimplantar o template em um novo grupo de recursos na mesma região, a implantação falha imediatamente na validação, antes de criar qualquer recurso.
A saída do comando de implantação é a seguinte:
$ az deployment group create \
--resource-group rg-destino \
--template-file exported-template.json \
--parameters @exported-parameters.json
ERROR: {"code": "InvalidRequestContent",
"message": "The request content was invalid and could not be deserialized:
'Required property 'properties' not found in JSON.
Path 'resources[2]', line 48, position 5.'"}
O administrador verifica que o arquivo possui 3 recursos declarados e que os dois primeiros passam na validação. O terceiro recurso no arquivo corresponde à Web App. A conta de armazenamento foi criada recentemente como parte de um teste separado e não tem relação com a Web App.
Qual é a causa raiz da falha de validação?
A) O arquivo de parâmetros exportado está referenciando valores de uma assinatura diferente, causando incompatibilidade de IDs de recurso.
B) O template exportado incluiu propriedades de runtime da Web App que não são válidas como entrada no schema ARM, e o bloco properties resultante ficou incompleto ou malformado.
C) A role Contributor não possui permissão suficiente para reimplantar Web Apps a partir de templates ARM exportados.
D) A conta de armazenamento declarada no template está em conflito com a Web App porque ambas compartilham o mesmo namespace de nome na região de destino.
Cenário 2 — Decisão de Ação
A equipe de infraestrutura identificou que um template ARM em JSON armazenado no repositório da empresa contém um loop copy para criar múltiplas instâncias de uma NIC. Após executar az bicep decompile, o arquivo .bicep gerado apresenta o seguinte aviso inline:
// WARNING: The following 'copy' loop could not be fully decompiled.
// Review and fix manually before deploying.
resource nic 'Microsoft.Network/networkInterfaces@2022-07-01' = [for i in range(0, nicCount): {
name: 'nic-${i}'
location: location
properties: {
// FIXME: ipConfigurations could not be resolved
}
}]
A causa já foi identificada: a sintaxe do loop copy em JSON não teve mapeamento completo para Bicep durante a decompilação. O time precisa que o arquivo Bicep esteja pronto para implantação em no máximo duas horas. O ambiente de produção está operacional e não há janela de manutenção ativa. O repositório usa revisão obrigatória por pull request antes de qualquer merge.
Qual é a ação correta a tomar neste momento?
A) Reexecutar az bicep decompile com a flag --force para forçar a resolução automática do loop e gerar um arquivo sem avisos.
B) Abrir o arquivo .bicep gerado, preencher manualmente o bloco ipConfigurations com a sintaxe correta de Bicep para o loop, validar com az bicep build e submeter via pull request.
C) Reverter para o template JSON original e implantá-lo diretamente, descartando a conversão para Bicep até que uma janela de manutenção esteja disponível.
D) Executar az deployment group validate no arquivo .bicep com o aviso presente para verificar se o ARM aceita a implantação mesmo com o bloco incompleto.
Cenário 3 — Causa Raiz
Uma engenheira exportou com sucesso o template ARM de um grupo de recursos pelo portal do Azure. Ao abrir o arquivo template.json no VS Code com a extensão Bicep instalada, ela executa o seguinte comando para converter o arquivo:
$ az bicep build --file template.json
O comando é concluído sem erros e gera um arquivo chamado template.json.bicep no mesmo diretório. Ao abrir esse arquivo, a engenheira percebe que o conteúdo é idêntico ao JSON original, não contendo nenhuma sintaxe Bicep.
O ambiente possui a versão mais recente da Azure CLI instalada. A extensão Bicep está na versão 0.24.24. O VS Code não exibe nenhum alerta de erro.
Qual é a causa raiz do comportamento observado?
A) A versão da extensão Bicep instalada no VS Code é incompatível com o comando az bicep build, fazendo com que o output seja gerado no formato errado.
B) O comando az bicep build compila arquivos .bicep para JSON e não realiza a conversão inversa. A engenheira usou o comando oposto ao necessário para a operação desejada.
C) O arquivo template.json exportado pelo portal contém uma propriedade $schema que impede a ferramenta Bicep de processá-lo corretamente, forçando a saída em JSON.
D) O comando az bicep build requer que o arquivo de entrada tenha a extensão .bicep. Por ter recebido um .json, a ferramenta copiou o arquivo sem processamento.
Cenário 4 — Sequência de Diagnóstico
Um administrador relata que, após exportar o template ARM de um grupo de recursos e tentar reimplantá-lo em outra região, a implantação falha. Ele não sabe em qual etapa do processo o problema foi introduzido.
Os seguintes passos de investigação estão disponíveis, mas foram listados fora de ordem:
- Executar
az deployment group validateno template e no arquivo de parâmetros para identificar erros de schema antes de uma nova tentativa de implantação. - Abrir o arquivo
template.jsonexportado e inspecionar manualmente se existem valores de região fixos no lugar de parâmetros ou variáveis. - Verificar a mensagem de erro retornada pela implantação com falha para determinar em qual recurso e propriedade a validação falhou.
- Comparar o template exportado com um template de referência funcional para a mesma topologia, identificando propriedades ausentes ou extras.
- Corrigir os valores problemáticos identificados e executar uma reimplantação em modo incremental para validar a correção.
Qual é a sequência correta de investigação?
A) 1 -> 2 -> 3 -> 4 -> 5
B) 3 -> 2 -> 4 -> 1 -> 5
C) 2 -> 4 -> 1 -> 3 -> 5
D) 3 -> 1 -> 2 -> 4 -> 5
Gabarito e Explicações
Gabarito — Cenário 1
Resposta: B
Explique:
- A mensagem de erro indica que o ARM não encontrou a propriedade
propertiesobrigatória no terceiro recurso do template, que corresponde à Web App. Esse comportamento é característico de exportações que capturam atributos de runtime ou estados computados do serviço, resultando em um blocopropertiesmalformado ou incompleto quando inserido como entrada em uma nova implantação. - A pista central no enunciado é que "o grupo de recursos foi criado há dois anos e nunca teve seus recursos recriados". Recursos com longa vida acumulam propriedades de runtime que o ARM registra no estado mas não aceita de volta como parâmetros de criação.
- A informação sobre a conta de armazenamento criada recentemente é propositalmente irrelevante. O erro aponta explicitamente para
resources[2], o terceiro recurso, que é a Web App, e a conta de armazenamento não tem relação com ela. - A alternativa A é um erro de diagnóstico clássico: confundir problemas de IDs de assinatura com erros de schema. A alternativa C é falsa porque a role Contributor é suficiente para implantações. Agir com base na alternativa D levaria o administrador a procurar conflitos de nome inexistentes, perdendo tempo enquanto o problema real permanece no template.
Gabarito — Cenário 2
Resposta: B
Explique:
- A causa já está identificada no enunciado: o loop
copynão foi decompilado corretamente. A ação correta é corrigir manualmente o bloco problemático, validar a compilação comaz bicep builde seguir o fluxo obrigatório de pull request. Essa abordagem respeita todas as restrições: o prazo de duas horas é viável para uma correção pontual, o ambiente de produção não é tocado e o processo de revisão é mantido. - A alternativa A é tecnicamente incorreta: a flag
--forcenão existe no comandoaz bicep decompilee não resolveria um problema de mapeamento de sintaxe. - A alternativa C ignora a restrição de tempo e abandona o objetivo da conversão sem justificativa técnica. A alternativa D é a mais perigosa: submeter ao ARM um arquivo com bloco
propertiesvazio resultaria em falha de implantação em produção, violando a premissa de que o ambiente está operacional. O aviso inline é uma indicação explícita de que o arquivo não está pronto para implantação.
Gabarito — Cenário 3
Resposta: B
Explique:
- O comando
az bicep buildtem uma função específica e unidirecional: compilar um arquivo.biceppara JSON ARM. Ao receber um arquivo.jsoncomo entrada, o comportamento documentado é gerar um arquivo de saída com o mesmo conteúdo JSON, pois nenhuma transformação de decompilação é realizada por esse comando. O comando correto para a operação desejada, converter JSON para Bicep, éaz bicep decompile. - A pista mais direta no enunciado é o nome do arquivo gerado:
template.json.bicep. Esse padrão de nomenclatura é exatamente o queaz bicep buildproduz ao receber um.json: ele adiciona.bicepcomo sufixo sem transformar o conteúdo. - As informações sobre a versão da CLI e da extensão Bicep são propositalmente irrelevantes. O comportamento descrito é o comportamento esperado e documentado do comando, não um bug de versão.
- A alternativa D é plausível mas incorreta:
az bicep buildaceita arquivos.jsoncomo entrada sem erro, apenas sem realizar decompilação. Agir com base na alternativa C levaria a investigações desnecessárias no conteúdo do template exportado, desviando do problema real, que é o uso do comando incorreto.
Gabarito — Cenário 4
Resposta: B
Explique:
- A sequência correta começa pelo sintoma concreto disponível: a mensagem de erro da implantação com falha (passo 3). Essa mensagem indica o recurso e a propriedade problemática, guiando a investigação. Com essa informação, o próximo passo é inspecionar o template exportado para identificar valores fixos de região ou propriedades malformadas (passo 2). Em seguida, comparar com um template de referência funcional ajuda a confirmar quais propriedades estão fora do esperado (passo 4). Antes de reimplantar, a validação via
az deployment group validate(passo 1) evita nova falha em produção. Por fim, a correção e reimplantação incremental (passo 5) fecha o ciclo. - A alternativa A comete o erro de começar pela validação antes de ler a mensagem de erro original, perdendo a informação diagnóstica mais direta disponível. A alternativa C ignora completamente a mensagem de erro existente, que é o ponto de partida mais eficiente. A alternativa D divide a leitura da mensagem de erro e a validação em etapas não contíguas, introduzindo uma inspeção manual no meio sem base na mensagem que ainda não foi lida por completo.
- A disciplina de partir sempre do erro concreto antes de inspecionar o template é o diferencial entre um diagnóstico eficiente e um processo de tentativa e erro.
Árvore de Troubleshooting: Export a deployment as an Azure Resource Manager template or convert an Azure Resource Manager template to a Bicep file
Legenda:
| Cor | Tipo de nó |
|---|---|
| Azul escuro | Sintoma inicial ou falha reportada |
| Azul médio | Pergunta diagnóstica |
| Vermelho | Causa identificada |
| Verde | Ação recomendada ou resolução |
| Laranja | Validação ou verificação intermediária |
Para usar esta árvore diante de um problema real, comece pelo nó raiz descrevendo a falha observada e responda cada pergunta de diagnóstico com base no que você pode verificar diretamente no terminal, no portal ou no arquivo. Siga o caminho que corresponde ao seu cenário até chegar a um nó de causa identificada, depois execute a ação recomendada correspondente e confirme a correção no nó de validação antes de considerar o problema resolvido.