Habilitar a validação de pré-voo no provedor Terraform do AzAPI

O Terraform permite a definição, a visualização e a implantação da infraestrutura de nuvem. Usando o Terraform, você cria arquivos de configuração usando a sintaxe HCL. A sintaxe da HCL permite que você especifique o provedor de nuvem, como o Azure, e os elementos que compõem sua infraestrutura de nuvem. Depois de criar os arquivos de configuração, você cria um plano de execução que permite visualizar as alterações de infraestrutura antes de serem implantadas. Depois de verificar as alterações, você aplica o plano de execução para implantar a infraestrutura.

O provedor Terraform do AzAPI inclui a validação de pré-voo interna que valida a configuração dos recursos do Azure no esquema da API ARM durante terraform plan, antes que quaisquer recursos sejam criados ou modificados em Azure. A verificação prévia captura erros de configuração antecipadamente, como prefixos de endereço inválidos, combinações de propriedades não suportadas ou violações de cota, sem incorrer nos custos de uma implantação mal sucedida.

A validação de pré-voo é um dos principais diferenciadores da AzAPI e funciona nativamente com a arquitetura de API ARM direta do provedor. Você também pode executar o preflight da extensão Microsoft Terraform VS Code sem definir a flag do provedor diretamente.

Pré-requisitos

• Assinatura do Azure: Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• Configurar o Terraform: se você ainda não fez isso, configure o Terraform usando uma das seguintes opções:

  • Configurar o Terraform no Azure Cloud Shell com o Bash
  • Configurar o Terraform no Azure Cloud Shell com o PowerShell
  • Configure Terraform em Windows com Bash
  • Configurar o Terraform no Windows com o PowerShell

Quando você faz logon no portal do Azure com uma conta da Microsoft, a assinatura padrão do Azure para essa conta é usada.

O Terraform autentica automaticamente usando informações da assinatura padrão do Azure.

Execute az account show para verificar a conta atual da Microsoft e a assinatura do Azure.

az account show

Todas as alterações feitas por meio do Terraform estão na assinatura exibida do Azure. Se é isso que você quer, ignore o restante deste artigo.

Habilitar a validação de pré-vôo

Definir enable_preflight = true no provider "azapi" bloco:

provider "azapi" {
  enable_preflight = true
}

O pré-vôo é desabilitado por padrão para preservar a compatibilidade com versões anteriores. Habilite-o em ambientes em que você deseja validação antecipada, como pipelines de Integração Contínua (CI) e verificações de pull requests.

Exemplo: detectar um prefixo de endereço inválido no tempo de planejamento

A configuração a seguir cria uma rede virtual com um bloco CIDR (roteamento de Inter-Domain sem classe) inválido. Com o pré-vôo habilitado, o erro aparece durante terraform plan e não durante terraform apply:

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

provider "azapi" {
  enable_preflight = true
}

resource "azurerm_resource_group" "example" {
  name     = "rg-preflight-demo"
  location = "eastus"
}

resource "azapi_resource" "vnet" {
  type      = "Microsoft.Network/virtualNetworks@2024-01-01"
  parent_id = azurerm_resource_group.example.id
  name      = "vnet-example"
  location  = "eastus"

  body = {
    properties = {
      addressSpace = {
        addressPrefixes = [
          "10.0.0.0/160"  # Invalid prefix length — preflight catches this at plan time
        ]
      }
    }
  }
}

Quando você executa terraform plan com essa configuração, o pré-vôo retorna um erro semelhante a:

Error: preflight validation failed for resource "azapi_resource.vnet":
  The value '10.0.0.0/160' is not a valid CIDR block.

Corrigir o prefixo de endereço para um valor válido (por exemplo, 10.0.0.0/16) limpa o erro.

O que a checagem pré-voo valida

O preflight envia o corpo do recurso para o endpoint preflight da API ARM, que valida:

• Valores de propriedade em relação ao esquema de recursos do ARM (por exemplo, faixas CIDR (Roteamento entre Domínios Sem Classe) válidas, nomes de SKU permitidos, campos necessários).
• Restrições de cota e capacidade no nível da assinatura para os tipos de recursos com suporte.
• Conformidade de política para atribuições de Azure Policy que são executadas no modo de pré-vôo.

O pré-voo não valida:

• Dependências entre recursos ou sequenciamento.
• Recursos que não têm suporte ao ponto de extremidade de pré-vôo do ARM (o provedor ignora silenciosamente a validação para esses tipos de recursos).
• Falhas de autenticação ou autorização (IAM (Gerenciamento de Identidade e Acesso) – essas falhas são exibidas durante terraform apply.

Usar o pré-vôo em pipelines de CI

Adicionar preflight a um pipeline de integração contínua fornece uma etapa de validação rápida e não destrutiva que captura erros de configuração antes que o código seja integrado. Habilite enable_preflight = true no bloco do provedor da configuração do Terraform e execute terraform plan:

provider "azapi" {
  enable_preflight = true
}

Como a pré-verificação é executada durante terraform plan sem efeitos colaterais, é seguro executar fluxos de trabalho de solicitação de pull em assinaturas ativas do Azure.

Desabilitar o ruído de saída com ignore_no_op_changes

Se você executar planos repetidamente, a AzAPI poderá detectar pequenas diferenças de no-op entre a configuração e o estado do ARM (por exemplo, valores padrão normalizados retornados pela API). Para suprimir essas diferenças de tempo de plano e focar em alterações reais, defina ignore_no_op_changes = true no bloco do provedor:

provider "azapi" {
  enable_preflight      = true
  ignore_no_op_changes  = true
}

Próximas Etapas