Laboratório de Troubleshooting: Modify an existing Azure Resource Manager template
Cenários de Diagnóstico
Cenário 1 — Causa Raiz
Uma equipe de infraestrutura modifica um template ARM existente para adicionar um segundo disco gerenciado a uma VM de produção. O template original funcionava corretamente. Após a modificação, a implantação é submetida via Azure CLI e falha imediatamente com a seguinte saída:
$ az deployment group create \
--resource-group rg-prod-eastus \
--template-file vm-template.json \
--parameters @vm-params.json
{
"error": {
"code": "InvalidTemplate",
"message": "Deployment template validation failed: 'The template resource 'osdisk-prod-01' at line '47' and column '9' is not valid: The language expression property 'parameters' doesn't exist, please see https://aka.ms/arm-template-expressions for usage details.'",
"target": "osdisk-prod-01"
}
}
O engenheiro responsável informa que o parâmetro diskSizeGB foi adicionado corretamente na seção parameters do template. Ele também menciona que alterou a apiVersion do recurso Microsoft.Compute/disks de 2022-07-02 para 2023-04-02 para usar funcionalidades mais recentes. O trecho relevante do template modificado é:
"diskSizeGB": {
"type": "int",
"defaultValue": 128
},
{
"type": "Microsoft.Compute/disks",
"apiVersion": "2023-04-02",
"name": "osdisk-prod-01",
"location": "[resourceGroup().location]",
"properties": {
"diskSizeGB": "[parameter('diskSizeGB')]",
"creationData": {
"createOption": "Empty"
}
}
}
O template tem 3 outros recursos que foram implantados com sucesso anteriormente e não foram alterados.
Qual é a causa raiz da falha?
A) A apiVersion 2023-04-02 não é compatível com o tipo Microsoft.Compute/disks, causando rejeição do schema.
B) A função de template está com o nome incorreto: parameter em vez de parameters, tornando a expressão inválida.
C) O parâmetro diskSizeGB foi declarado como int, mas o campo diskSizeGB em properties exige uma string.
D) O campo creationData.createOption está incompatível com a propriedade diskSizeGB quando ambos são declarados simultaneamente.
Cenário 2 — Decisão de Ação
A causa do problema foi identificada: um template ARM de produção referencia um recurso de rede via dependsOn usando um nome literal desatualizado. O nome do recurso de rede foi renomeado em uma modificação anterior do template, mas a entrada em dependsOn não foi atualizada. Como resultado, todas as novas implantações do ambiente falham com erro de recurso não encontrado na dependência.
O ambiente possui as seguintes restrições:
- A implantação afetada é executada por um pipeline de CI/CD que roda a cada commit no branch principal
- O arquivo de template está versionado em um repositório Git com política de branch protegido: toda alteração exige pull request aprovado por dois revisores
- A equipe tem apenas um revisor disponível no momento
- O pipeline pode ser pausado manualmente pelo líder técnico sem impacto nos recursos já provisionados
- Existe um ambiente de homologação com template idêntico onde a correção pode ser testada
Qual é a ação correta a tomar neste momento?
A) Editar o arquivo de template diretamente no branch principal via interface do repositório para corrigir o dependsOn imediatamente, evitando mais falhas no pipeline.
B) Pausar o pipeline, abrir um pull request com a correção no dependsOn, testar em homologação e aguardar aprovação conforme a política de branch.
C) Remover a entrada incorreta de dependsOn temporariamente para desbloquear o pipeline e adicionar a versão correta em um segundo pull request posterior.
D) Reverter o template para a versão anterior ao renomeamento do recurso de rede para restaurar a consistência entre o nome declarado e a dependência.
Cenário 3 — Causa Raiz
Um administrador modifica um template ARM para provisionar três contas de armazenamento usando um loop copy. O template é validado sem erros pelo comando az deployment group validate, mas ao executar a implantação real, apenas duas contas são criadas. Nenhum erro é retornado na saída do comando.
O ambiente usa a região brazilsouth. As contas criadas anteriormente no mesmo resource group estão operacionais. O trecho do loop no template é:
"copy": {
"name": "storageCopy",
"count": "[parameters('storageCount')]"
},
"name": "[concat('stprod', copyIndex())]"
O arquivo de parâmetros usado na implantação contém:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"storageCount": {
"value": 2
}
}
}
O administrador afirma ter intenção de criar três contas e acredita que o template está configurado para isso. Ele também menciona que testou o template na semana anterior com storageCount igual a 5 e todas as contas foram criadas corretamente.
Qual é a causa raiz do comportamento observado?
A) A função copyIndex() inicia em 0, gerando nomes como stprod0, stprod1, o que causa conflito com contas existentes e impede a criação da terceira.
B) O parâmetro storageCount no arquivo de parâmetros está com valor 2, e o ARM criou exatamente o número de recursos declarado nesse arquivo.
C) A região brazilsouth tem uma limitação de duas contas de armazenamento por resource group em implantações via loop copy.
D) O comando az deployment group validate não executa o loop copy completamente, mascarando o erro de contagem durante a validação.
Cenário 4 — Sequência de Diagnóstico
Um time recebe o seguinte relatório de um operador:
"Tentei reimplantar o template ARM do ambiente de staging. A implantação foi submetida mas ficou presa no estado
Runningpor mais de quarenta minutos. Cancelei manualmente. Agora, ao tentar reimplantar, recebo um erro diferente do original."
O novo erro observado após o cancelamento é:
{
"error": {
"code": "DeploymentOperationFailed",
"message": "Resource 'vnet-staging-01' failed with error: Another operation (PUT) is in progress on resource 'vnet-staging-01'. Please retry later."
}
}
Os passos de investigação disponíveis estão listados abaixo fora de ordem:
- Verificar o estado atual do recurso
vnet-staging-01no portal ou viaaz network vnet show - Identificar se há outra operação ativa no resource group via
az deployment operation group list - Aguardar a conclusão ou expiração da operação travada antes de reimplantar
- Confirmar que o template não contém referência circular entre
vnet-staging-01e outros recursos - Verificar o histórico de implantações do resource group para identificar a operação cancelada
Qual é a sequência correta de investigação?
A) 4 → 1 → 5 → 2 → 3
B) 5 → 2 → 1 → 3 → 4
C) 1 → 4 → 2 → 5 → 3
D) 2 → 5 → 1 → 4 → 3
Gabarito e Explicações
Gabarito — Cenário 1
Resposta: B
A mensagem de erro é explícita: "The language expression property 'parameters' doesn't exist". Isso ocorre porque a expressão no template usa "[parameter('diskSizeGB')]" em vez de "[parameters('diskSizeGB')]" com o s final. O ARM não reconhece parameter como uma função válida de template e rejeita a expressão durante a validação, antes mesmo de tentar provisionar qualquer recurso.
A pista decisiva está na mensagem de erro, que aponta para a expressão de linguagem, não para o tipo de recurso nem para a combinação de propriedades.
A informação sobre a mudança de apiVersion é propositalmente irrelevante: ela não causa o erro descrito e serve para desviar o diagnóstico para a alternativa A. A versão de API afeta o conjunto de propriedades disponíveis, mas não gera a mensagem específica observada.
A alternativa C representa um erro de raciocínio sobre tipos: o ARM aceita inteiros em campos numéricos do schema sem conversão manual. A alternativa D descreve uma incompatibilidade inexistente: creationData e diskSizeGB coexistem normalmente no schema do recurso.
O distrator mais perigoso é A, pois leva o operador a investigar compatibilidade de apiVersion, o que é uma causa legítima em outros contextos mas não explica a mensagem de erro específica deste cenário.
Gabarito — Cenário 2
Resposta: B
A restrição crítica do cenário é a política de branch protegido com exigência de dois revisores. Editar diretamente o branch principal, como propõe a alternativa A, viola essa política e pode ser bloqueado pelo próprio repositório ou introduzir riscos adicionais sem revisão.
A ação correta é pausar o pipeline para interromper as falhas contínuas sem impactar os recursos já provisionados, depois seguir o processo estabelecido: abrir pull request, validar em homologação e aguardar aprovação. O enunciado confirma que pausar o pipeline é uma operação disponível e sem impacto.
A alternativa C representa uma solução tecnicamente funcional, mas divide a correção em dois pull requests sem necessidade, criando uma janela em que o template ficaria sem a dependência declarada, o que pode causar condições de corrida durante implantações paralelas.
A alternativa D seria regressiva: reverter para a versão anterior restauraria o nome antigo do recurso de rede, mas desfaria quaisquer outras modificações feitas desde então, potencialmente causando novos problemas no ambiente.
O erro de raciocínio central dos distratores A e C é priorizar a velocidade de correção acima do processo, ignorando a restrição de governança explicitamente declarada no cenário.
Gabarito — Cenário 3
Resposta: B
O comportamento é exatamente o esperado. O arquivo de parâmetros declara "storageCount": 2, e o ARM cria precisamente dois recursos, que é o valor fornecido em tempo de execução. O template em si pode estar "configurado para três" na intenção do administrador, mas a fonte de verdade para a implantação é o arquivo de parâmetros, e ele diz dois.
A pista decisiva está na presença do arquivo de parâmetros com valor explícito 2. O enunciado menciona que testes anteriores com storageCount: 5 funcionaram corretamente, o que elimina qualquer hipótese de bug no loop ou na função copyIndex().
A informação sobre a região brazilsouth é propositalmente irrelevante e serve para induzir o leitor a investigar limitações regionais inexistentes para esse tipo de recurso.
A alternativa A descreve um comportamento real de copyIndex() que inicia em 0, mas isso não causa o problema descrito: nomes como stprod0 e stprod1 são válidos e não conflitam entre si. A alternativa D descreve uma limitação real do comando validate em relação a algumas verificações de runtime, mas o loop copy é processado corretamente durante a validação e não é a causa aqui.
O distrator mais perigoso é A, pois direciona a investigação para o comportamento de copyIndex(), que é tecnicamente correto mas completamente irrelevante para o sintoma observado.
Gabarito — Cenário 4
Resposta: B
A sequência correta é: 5 → 2 → 1 → 3 → 4.
O raciocínio diagnóstico progressivo exige partir do que é conhecido para o que precisa ser descoberto:
O passo 5 (histórico de implantações) estabelece o contexto: a operação cancelada manualmente pode ter deixado o recurso em estado inconsistente. Esse é o ponto de entrada do diagnóstico.
O passo 2 (listar operações ativas) confirma se ainda existe uma operação em execução no resource group, o que é diretamente indicado pela mensagem de erro recebida.
O passo 1 (verificar estado atual do recurso) determina se o recurso vnet-staging-01 está em estado provisório, o que orienta a decisão seguinte.
O passo 3 (aguardar ou expirar a operação) é a ação corretiva adequada uma vez que o diagnóstico está completo.
O passo 4 (verificar referência circular) é o único passo que investiga uma causa estrutural do template, e não uma condição de estado do ambiente. Ele é relevante em outros contextos de falha de deploy, mas não é a causa da mensagem específica observada aqui, que aponta claramente para uma operação concorrente. Por isso, ele é o último a ser executado, apenas para descartar hipóteses residuais.
A alternativa A começa pelo passo de referência circular, que é uma causa improvável dado o erro explícito de operação concorrente, demonstrando raciocínio invertido. A alternativa C começa pelo estado atual do recurso sem antes entender o histórico, perdendo o contexto necessário para interpretar o que o estado significa.
Árvore de Troubleshooting: Modify an existing Azure Resource Manager template
Legenda de cores:
| Cor | Tipo de nó |
|---|---|
| Azul escuro | Sintoma inicial (ponto de entrada) |
| Azul | 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 e responda cada pergunta com base no que foi observado diretamente no ambiente. O primeiro passo é sempre classificar se a falha ocorre em validação ou em execução, pois isso define qual ramo investigar. Siga as ramificações respondendo apenas o que pode ser verificado naquele momento, sem pular etapas. Ao chegar em um nó de causa identificada, aplique a ação correspondente e retorne ao nó de validação para confirmar a correção antes de encerrar o diagnóstico.