Laboratório de Troubleshooting: Modify an existing Bicep file
Cenários de Diagnóstico
Cenário 1 — Causa Raiz
Um administrador herda um arquivo Bicep de um projeto anterior e executa o deploy sem modificações iniciais para validar o baseline. O deploy termina com sucesso. Em seguida, ele adiciona um novo parâmetro e uma nova Storage Account ao arquivo, salva e executa novamente:
az deployment group create \
--resource-group rg-prod-eastus \
--template-file main.bicep \
--parameters env=prod
O comando retorna o seguinte erro:
Error BCP037: The property 'accessTier' is not allowed on objects of type
'StorageAccountPropertiesCreateParameters'.
O administrador verifica que a versão da API declarada para a Storage Account é 2021-02-01, a mesma usada no recurso original que deployou com sucesso. O resource group está na região East US. A subscription tem uma policy que exige a tag costCenter em todos os recursos, e essa tag foi adicionada corretamente ao novo recurso.
Qual é a causa raiz do erro?
A) A policy de tags está bloqueando o deploy porque a validação da policy ocorre antes da validação do schema da API.
B) A propriedade accessTier não é válida para o kind de Storage Account configurado no novo recurso, mesmo que seja uma propriedade reconhecida pela versão da API.
C) A versão da API 2021-02-01 foi descontinuada e não aceita novos deployments, apenas leituras de recursos existentes.
D) O parâmetro env não está declarado no arquivo Bicep com o tipo correto, causando falha na resolução das propriedades do recurso.
Cenário 2 — Decisão de Ação
A causa do problema foi identificada: um arquivo Bicep que gerencia um App Service Plan e um App Service em produção está com a versão da API do App Service desatualizada. Uma propriedade necessária para habilitar o acesso por identidade gerenciada foi introduzida em uma versão posterior e não está disponível na versão atual declarada no arquivo.
O ambiente é de produção com SLA ativo. O App Service está recebendo tráfego. A atualização da versão da API no arquivo Bicep já foi testada em ambiente de desenvolvimento e o deploy funcionou corretamente. O modo de deployment configurado no pipeline é Incremental. A equipe de mudanças exige aprovação para qualquer alteração em produção fora da janela programada, que ocorre nas próximas 6 horas.
Qual é a ação correta a tomar neste momento?
A) Executar o deploy imediatamente em produção com a versão da API corrigida, pois o modo Incremental garante que apenas a propriedade nova será aplicada, sem risco de interrupção.
B) Atualizar a versão da API diretamente no portal do Azure via editor de templates ARM para contornar o processo de aprovação sem modificar o arquivo Bicep.
C) Aguardar a janela de mudança programada, submeter a alteração para aprovação com o resultado do teste em desenvolvimento como evidência e executar o deploy na janela autorizada.
D) Reverter o arquivo Bicep para a versão anterior e redeployar imediatamente para garantir consistência entre o repositório e o estado atual do recurso.
Cenário 3 — Causa Raiz
Um administrador modifica um arquivo Bicep para extrair valores repetidos para variáveis. Antes da modificação, o deploy funcionava. Após a modificação abaixo, o Bicep compila sem erro com az bicep build, mas o deploy falha:
var location = 'eastus'
var appName = 'myapp-${environment}'
resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
name: '${appName}-plan'
location: location
sku: {
name: 'B1'
tier: 'Basic'
}
}
resource appService 'Microsoft.Web/sites@2022-03-01' = {
name: appName
location: location
properties: {
serverFarmId: appServicePlan.id
}
}
O erro retornado pelo Azure Resource Manager é:
InvalidTemplate: Deployment template validation failed: 'The template variable
'location' is not valid: The language expression property 'location' cannot be
used within a deployment at scope 'resourceGroup'.
O parâmetro environment está declarado no arquivo. A subscription e o resource group existem e o administrador tem permissão de Contributor. O pipeline de CI usa az bicep build para validar o arquivo antes do deploy.
Qual é a causa raiz da falha?
A) A função resourceGroup().location deve ser usada para determinar a localização, pois o Azure não aceita strings literais no campo location de recursos dentro de um resource group.
B) A variável location entra em conflito com uma palavra reservada ou propriedade implícita do escopo de deployment no ARM, e o nome deve ser alterado para evitar a colisão.
C) O az bicep build não detecta conflitos de nomes com propriedades do escopo ARM porque valida apenas a sintaxe Bicep, não a resolução de expressões no ARM.
D) O campo location de um recurso não aceita referência a variável; deve receber um valor literal ou referência direta a um parâmetro.
Cenário 4 — Sequência de Diagnóstico
Um administrador recebe o seguinte relato: um arquivo Bicep que antes deployava com sucesso passou a falhar após uma modificação feita por outro membro da equipe. A mensagem de erro é genérica:
Error: Deployment failed. Check the activity log for details.
Os passos disponíveis para investigação são:
- Executar
az bicep build --file main.biceppara verificar erros de sintaxe e compilação. - Consultar o activity log do resource group no portal ou via CLI para obter a mensagem de erro detalhada do ARM.
- Comparar o arquivo Bicep atual com a versão anterior no histórico de controle de versão para identificar o que foi alterado.
- Executar um what-if deployment com
az deployment group what-ifpara visualizar as mudanças que seriam aplicadas. - Tentar executar o deploy em um resource group de teste isolado para confirmar se o erro é reproduzível.
Qual é a sequência correta de investigação?
A) 3, 1, 2, 4, 5
B) 1, 3, 2, 4, 5
C) 2, 1, 3, 4, 5
D) 5, 3, 1, 2, 4
Gabarito e Explicações
Gabarito — Cenário 1
Resposta: B
A propriedade accessTier é reconhecida pela versão da API 2021-02-01, mas é válida apenas para Storage Accounts do kind BlobStorage ou StorageV2. Se o novo recurso foi declarado com kind: 'Storage' (legado), a API rejeita a propriedade como inválida para aquele tipo, mesmo que a versão da API seja idêntica à do recurso que funcionou. A mensagem not allowed on objects of type indica incompatibilidade entre propriedade e tipo, não entre propriedade e versão.
A informação sobre a policy de tags é propositalmente irrelevante: a policy está satisfeita e não é a origem do erro. A alternativa A é um erro de diagnóstico comum que confunde rejeição de policy com erro de schema. A alternativa C é falsa: versões de API no ARM não são descontinuadas para deployments novos de forma silenciosa. A alternativa D desvia o foco para o parâmetro, que não tem relação com o erro de schema relatado. O distrator mais perigoso é A, pois poderia levar o administrador a investigar políticas e permissões em vez do tipo do recurso.
Gabarito — Cenário 2
Resposta: C
O processo de mudança da organização exige aprovação antes de alterações em produção. A janela está próxima (6 horas), o ambiente de desenvolvimento já validou a mudança, e o modo Incremental não elimina o risco de impacto em um recurso com tráfego ativo; ele apenas omite recursos ausentes do template. Agir fora do processo sem aprovação viola o controle de mudanças, independentemente da confiança técnica na solução.
A alternativa A ignora a restrição de processo e superestima a segurança do modo Incremental. A alternativa B contorna o controle de mudanças e cria uma divergência entre o estado do recurso no Azure e o arquivo Bicep no repositório, que é um risco operacional grave. A alternativa D não faz sentido no contexto: o arquivo atual no repositório não deployou em produção com o erro; não há divergência a corrigir. O distrator mais perigoso é A, pois usa um argumento técnico plausível para justificar contornar o processo.
Gabarito — Cenário 3
Resposta: B
A mensagem de erro do ARM indica diretamente que a propriedade location não pode ser usada como expressão no escopo de deployment de resource group. Isso ocorre porque location é uma propriedade implícita do objeto de escopo resourceGroup() no ARM, e ao declarar uma variável Bicep com esse nome, o compilador ARM interpreta a referência de forma ambígua ou conflitante durante a resolução de expressões. Renomear a variável para algo como deployLocation resolve o problema sem nenhuma outra alteração.
A pista confirmadora está na mensagem: The language expression property 'location' cannot be used within a deployment at scope 'resourceGroup', indicando colisão de nome com propriedade do escopo, não restrição sobre strings literais.
A alternativa A está incorreta: o Azure aceita strings literais em location. A alternativa D está incorreta: Bicep aceita variáveis como valor de location. A informação sobre permissões de Contributor e existência do resource group é irrelevante e foi incluída propositalmente. O fato de az bicep build não detectar o erro (alternativa C) é verdadeiro como observação, mas descreve uma limitação da ferramenta, não a causa raiz. O distrator mais perigoso é A, pois leva o administrador a substituir variáveis por resourceGroup().location sem entender que o problema é o nome da variável.
Gabarito — Cenário 4
Resposta: A
A sequência correta é 3, 1, 2, 4, 5 porque o raciocínio diagnóstico progressivo parte do contexto mais específico disponível.
O primeiro passo é identificar o que mudou (3), pois o problema surgiu após uma modificação conhecida. Em seguida, valida-se a sintaxe do arquivo modificado (1) para confirmar se a modificação introduziu erro estrutural. Depois, consulta-se o activity log (2) para obter a mensagem de erro detalhada do ARM, que é mais informativa que a mensagem genérica. Com a causa hipotética identificada, usa-se o what-if (4) para validar o comportamento esperado antes de re-executar. Por último, se ainda houver dúvida, testa-se em ambiente isolado (5).
A alternativa C (2, 1, 3, ...) inverte a lógica: consultar o log antes de saber o que mudou é possível, mas ineficiente quando o contexto da modificação já está disponível. A alternativa B (1, 3, ...) compila antes de ver o que mudou, o que pode levar a corrigir erros de sintaxe sem entender a intenção da mudança. A alternativa D começa pelo ambiente de teste isolado, o que introduz overhead desnecessário quando os passos 1 e 3 poderiam já apontar a causa.
Árvore de Troubleshooting: Modify an existing Bicep file
Legenda
| Cor | Tipo de nó |
|---|---|
| Azul escuro | Sintoma inicial (ponto de entrada) |
| Azul | Pergunta diagnóstica (decisão binária ou observável) |
| 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 o sintoma observado e responda cada pergunta com base no que você consegue verificar diretamente: saída do az bicep build, mensagem do activity log, ou comparação com o histórico de versão. Siga o caminho que corresponde ao que você observa, não ao que você supõe. Cada nó vermelho identifica uma causa específica que exige uma ação corretiva própria; cada nó laranja indica que o diagnóstico ainda precisa de confirmação antes de agir.