azure-validate

Visão geral

O que é azure-validate?

azure-validate é uma skill de validação de implantação criada para executar verificações profundas de pré-flight na sua aplicação e infraestrutura Azure antes da implantação. Ela lê o plano de implantação aprovado criado por azure-prepare e, em seguida, valida configuração, infraestrutura como código (Bicep ou Terraform), fluxos de trabalho Azure Developer CLI (azd), scripts Azure CLI (azcli), políticas, regiões e permissões necessárias.

A skill faz parte da fase de implantação do seu fluxo de trabalho, mas se comporta como uma suíte de testes automatizados para o seu ambiente Azure. Ela ajuda a confirmar que o plano é seguro para ser executado e que sua aplicação está realmente pronta para ser implantada.

Quando usar essa skill?

Use azure-validate sempre que quiser:

• Verificar se sua aplicação e infraestrutura estão prontas para implantação
• Validar azure.yaml ou templates Bicep antes de executar azd provision ou azd deploy
• Executar verificações de pré-implantação para Terraform ou scripts Azure CLI diretos
• Confirmar escolhas de assinatura, região e cotas do Azure
• Validar conformidade com Azure Policy para os recursos planejados
• Detectar cedo erros comuns de validação do Azure CLI e de IaC
• Solucionar falhas recorrentes de implantação em pipelines de CI/CD

Ela se encaixa melhor nesta sequência:

azure-prepare → azure-validate → azure-deploy

Para quem é o azure-validate?

azure-validate é voltado para:

• Desenvolvedores backend e de nuvem que criam apps no Azure
• Engenheiros de DevOps e de plataforma responsáveis por implantações confiáveis
• Times que padronizaram em Bicep, Terraform, azd ou azcli para infraestrutura
• Responsáveis por CI/CD que precisam de verificações de pré-implantação consistentes e automatizadas

Se você gerencia com frequência implantações em múltiplos ambientes (dev/test/prod) ou precisa seguir políticas corporativas e regras de região, essa skill oferece uma camada de validação repetível.

Quais problemas ela resolve?

azure-validate ajuda a reduzir implantações com falha ou parciais ao detectar problemas como:

• Configuração ausente ou inválida em azure.yaml ou arquivos de IaC
• Regiões Azure mal configuradas ou não suportadas para determinados serviços
• Violações de Azure Policy que bloqueiam a implantação
• Problemas de autenticação e permissão (por exemplo, papéis ausentes)
• Erros comuns de validação do Azure CLI para Bicep e templates
• Receitas de infraestrutura desalinhadas entre azd, azcli, Bicep e Terraform

Em vez de descobrir esses problemas em produção ou tardiamente no pipeline, você os identifica na etapa de validação, com referências e receitas claras para corrigi-los.

Quando o azure-validate não é uma boa opção?

Esta skill não se destina a:

• Implantações fora do Azure (outros clouds ou apenas on-premises)
• Monitoramento pós-implantação, health checks ou observabilidade
• Suítes de testes de aplicação (unitários, integração ou UI)
• Implantações manuais pontuais sem um plano gerado por azure-prepare

Se você não usa infraestrutura como código ou um arquivo de plano estruturado (como .azure/plan.md criado por azure-prepare), não obterá o benefício completo do azure-validate.

Como usar

1. Instalação e configuração

Adicionar azure-validate às suas skills

Instale a skill a partir do repositório microsoft/azure-skills:

npx skills add https://github.com/microsoft/azure-skills --skill azure-validate

Isso torna o fluxo de trabalho do azure-validate disponível para seu agente ou ambiente de ferramentas.

Ordem obrigatória do fluxo

Antes de executar azure-validate, você precisa ter:

• Executado azure-prepare com sucesso, e
• Um arquivo .azure/plan.md presente com status Approved ou posterior

O fluxo de trabalho suportado é estritamente:

azure-prepare → azure-validate → azure-deploy

Se .azure/plan.md não existir ou não estiver aprovado, pare e execute azure-prepare primeiro.

2. Entender gatilhos e regras centrais

Principais gatilhos

Use azure-validate quando precisar:

• Confirmar que uma aplicação está pronta para implantação
• Validar azure.yaml ou templates Bicep
• Executar verificações de pré-flight antes de provisionar recursos
• Solucionar erros de implantação do Azure originados de etapas de IaC ou CLI

Regras centrais a seguir

Com base nas orientações da skill e na referência compartilhada global-rules:

1. Execute azure-validate somente depois de azure-prepare e antes de qualquer implantação real.
2. Trate falhas de validação como bloqueadoras. Não prossiga com azure-deploy até que os problemas sejam resolvidos.
3. Para qualquer ação destrutiva ou de alto impacto (deleção, sobrescrita, mudança relevante de custo ou segurança), sempre solicite confirmação do usuário usando ask_user, conforme descrito em references/global-rules.md.
4. Nunca presuma assinatura ou região do Azure; elas devem ser confirmadas com o usuário quando forem relevantes.

3. Seguir receitas de validação específicas de infraestrutura

A skill inclui receitas direcionadas em references/recipes/ para validar diferentes abordagens de infraestrutura.

Para projetos Azure Developer CLI (azd)

• Comece em references/recipes/azd/README.md.
• Use references/recipes/azd/environment.md para verificar a configuração de ambiente.
• Use references/recipes/azd/errors.md para interpretar e corrigir problemas comuns de validação e implantação do azd.
• Para projetos baseados em .NET Aspire, consulte references/recipes/azd/aspire.md para verificações adicionais.

Esses guias ajudam a confirmar que azure.yaml, a ligação da aplicação e a configuração de ambiente estão válidos antes de provisionar com azd.

Para fluxos de trabalho Azure CLI (azcli) + Bicep

• Comece em references/recipes/azcli/README.md para um checklist completo de validação AZCLI, incluindo:
  • Verificar a instalação do Azure CLI (az version)
  • Fazer login e definir a assinatura
  • Compilar Bicep (az bicep build)
  • Executar validação de template e pré-visualizações what-if
• Use references/recipes/azcli/errors.md para correções rápidas de mensagens de erro comuns do az (problemas de token, MFA, autorização, falhas de validação de template).

Essa combinação oferece um passo a passo concreto para validar implantações baseadas em Bicep acionadas pelo Azure CLI.

Para infraestrutura focada em Bicep

• Veja references/recipes/bicep/README.md para fluxos de validação específicos de Bicep.
• Use references/recipes/bicep/errors.md para orientação sobre problemas típicos de validação Bicep e como resolvê-los.

Você pode integrar essas verificações ao seu fluxo de trabalho local ou pipeline de CI para garantir que templates e parâmetros estejam válidos antes de executar uma implantação completa.

Para implantações baseadas em Terraform

• Use references/recipes/terraform/README.md para alinhar azure-validate com os passos de plan e apply do Terraform.
• Consulte references/recipes/terraform/errors.md para erros comuns de validação do Terraform e de autorização no Azure, com suas soluções.

Essas receitas ajudam a validar a infraestrutura Terraform e a configuração da conta Azure antes de executar terraform apply em qualquer ambiente.

4. Validar prontidão de políticas, regiões e cotas

Validação de Azure Policy

Use references/policy-validation.md como guia para garantir que a implantação planejada respeita as atribuições de Azure Policy na assinatura.

Fluxo típico:

1. Obter o ID da assinatura atual:

   az account show --query id -o tsv
   

2. Usar a integração Azure policy MCP para listar e revisar as políticas dessa assinatura, conforme mostrado na referência.

3. Resolver violações de política (SKUs não permitidos, tags ausentes, tipos de recurso restritos, bloqueios de localização, regras de segurança de rede) antes de prosseguir.

Só continue para a implantação depois de confirmar a conformidade com as políticas.

Verificações de disponibilidade de região e cotas

Use references/region-availability.md para conferir se todos os serviços da sua arquitetura são compatíveis com as regiões solicitadas e se as cotas são suficientes.

Isso é especialmente crítico para serviços com disponibilidade limitada por região, como:

• Azure Static Web Apps
• Azure OpenAI (com diferenças de região por modelo)

Siga as orientações da referência e quaisquer MCP tools listadas (para cotas e disponibilidade de região) para evitar falhas causadas por regiões não suportadas ou capacidade insuficiente.

5. Exemplos de validação de app e functions

Armazenamento de secrets para Aspire + Azure Functions

Se você estiver usando .NET Aspire com Azure Functions, consulte references/aspire-functions-secrets.md:

• Detectar se o host do app inclui AddAzureFunctionsProject com storage baseado em identidade.
• Garantir que AzureWebJobsSecretStorageType esteja configurado corretamente.
• Aplicar a correção recomendada (incluindo .WithEnvironment("AzureWebJobsSecretStorageType", "Files") onde indicado) antes do provisionamento.

Executar essa validação antes de azd provision evita problemas comuns de armazenamento de secrets das functions que podem bloquear implantações serverless.

6. Usar azure-validate em pipelines de CI/CD

Embora azure-validate seja escrita como uma skill de agente, seus passos e referências se encaixam bem em pipelines automatizados:

• Use as receitas como estágios do pipeline (por exemplo, execute validação Bicep e what-if antes dos jobs de deploy).
• Faça o pipeline falhar em qualquer erro de validação exposto pelas receitas ou verificações de política.
• Exiba links ou trechos dos arquivos em references/* nos logs do pipeline para orientar desenvolvedores na correção dos problemas.

Isso transforma o azure-validate em um gate de pré-implantação consistente para todos os ambientes.

7. Arquivos para revisar para customização avançada

Para adaptar azure-validate ao seu fluxo de trabalho, abra estes arquivos principais no repositório:

• SKILL.md – Instruções oficiais, gatilhos, regras e passos ordenados da skill.
• references/global-rules.md – Regras globais obrigatórias para ações destrutivas e tratamento de assinatura e região.
• references/policy-validation.md – Uso detalhado de validação de políticas.
• references/region-availability.md – Orientações de região e cota para serviços com restrições.
• references/aspire-functions-secrets.md – Validação de storage de secrets para Aspire + Azure Functions.
• references/recipes/README.md – Índice das receitas de validação para azd, azcli, Bicep e Terraform.

Use esses arquivos como blocos de construção em vez de copiar todo o fluxo de trabalho cegamente.

FAQ

azure-validate é obrigatório ou posso implantar sem ele?

A skill foi projetada para ser executada entre azure-prepare e azure-deploy. Embora tecnicamente você possa implantar sem rodar azure-validate, as diretrizes oficiais recomendam tratá-lo como um gate obrigatório. Ignorá-lo aumenta o risco de falhas de implantação, bloqueios por políticas ou problemas de região/permissão.

Preciso executar azure-prepare primeiro?

Sim. azure-validate parte do pressuposto de que azure-prepare já foi executado e que .azure/plan.md existe com status Approved ou posterior. Se esse arquivo estiver ausente ou não aprovado, você deve parar e executar azure-prepare antes de usar azure-validate.

Quais ferramentas de infraestrutura o azure-validate suporta?

azure-validate fornece receitas e orientações para:

• Azure Developer CLI (azd)
• Azure CLI (azcli) com templates Bicep
• Infraestrutura baseada em Bicep
• Terraform

Você pode escolher a receita que corresponde ao seu stack em references/recipes/.

Posso usar azure-validate com pipelines de CI/CD?

Sim. Embora seja escrita como uma skill de agente, suas etapas de validação, guias de erros e verificações de política/região são adequadas para CI/CD. Você pode espelhar as receitas e verificações no seu pipeline (por exemplo, GitHub Actions, Azure DevOps), de forma que as implantações só prossigam quando a validação for bem-sucedida.

azure-validate faz alterações nos meus recursos Azure?

azure-validate é focado em validação e verificações de pré-flight. As orientações enfatizam que qualquer ação destrutiva ou de alto impacto deve ser explicitamente confirmada com o usuário (via ask_user e o arquivo global-rules). No uso típico, você utiliza essa skill para inspecionar, validar e planejar — não para executar mudanças irreversíveis.

Como azure-validate ajuda com Azure Policy e governança?

A skill inclui references/policy-validation.md, que mostra como inspecionar políticas de uma assinatura e revisar a conformidade antes da implantação. Seguindo essas orientações, você consegue detectar antecipadamente tipos de recurso, SKUs, tags ou regiões não permitidos e alinhar sua implantação às regras da organização.

Como ele lida com serviços específicos de região, como Azure Static Web Apps ou Azure OpenAI?

references/region-availability.md lista serviços com suporte limitado por região e aponta para documentação oficial do Azure e MCP tools para verificar cotas e disponibilidade. azure-validate pressupõe que você consulte essa referência e só ofereça ou use regiões em que todos os serviços necessários sejam suportados.

azure-validate é adequado para ambientes de desenvolvimento local?

Sim, desde que você planeje implantar no Azure e use azure-prepare para gerar um plano, você pode executar azure-validate em ambientes de dev e teste. Essa é uma boa forma de detectar problemas cedo, antes de promover para staging ou produção.

Por onde começar ao instalar azure-validate pela primeira vez?

Depois de adicionar a skill, comece por SKILL.md para entender as regras e a sequência, e depois revise references/recipes/README.md para escolher a receita que corresponde à sua ferramenta de infraestrutura (azd, azcli, Bicep, Terraform). A partir daí, siga a receita relevante junto com as orientações de política e região para integrar azure-validate ao seu fluxo de trabalho.