Ativar a validação pré-voo no fornecedor AzAPI Terraform

Terraform permite a definição, visualização e implantação de infraestrutura em nuvem. Usando Terraform, você cria arquivos de configuração usando a sintaxe HCL. A sintaxe HCL permite especificar o provedor de nuvem - como o Azure - e os elementos que compõem sua infraestrutura de nuvem. Depois de criares os ficheiros de configuração, crias um plano de execução que te permite pré-visualizar as alterações da infraestrutura antes de serem implementadas. Depois de verificares as alterações, aplicas o plano de execução para implementar a infraestrutura.

O fornecedor AzAPI Terraform inclui validação pré-voo incorporada que valida a configuração do seu recurso de Azure contra o esquema da API ARM durante terraform plan, antes de quaisquer recursos serem criados ou modificados em Azure. A pré-verificação detecta erros de configuração precocemente — como prefixos de endereço inválidos, combinações de propriedades não suportadas ou violações de quotas — evitando assim os custos associados a uma implementação falhada.

A validação pré-voo é um dos principais diferenciadores do AzAPI e funciona nativamente com a arquitetura direct-to-ARM-API do fornecedor. Também pode correr a verificação preliminar a partir da extensão Microsoft Terraform VS Code sem ter de definir diretamente a flag do fornecedor.

Pré-requisitos

• Subscrição do Azure: Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

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

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

Quando inicia sessão no portal do Azure com uma conta Microsoft, é utilizada a subscrição predefinida do Azure para essa conta.

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

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

az account show

As alterações que fizer através do Terraform serão aplicadas à subscrição do Azure exibida. Se é isso que você quer, pule o resto deste artigo.

Ativar a validação pré-voo

Definir enable_preflight = true no bloco provider "azapi":

provider "azapi" {
  enable_preflight = true
}

O pré-voo está desativado por defeito para preservar a compatibilidade retroativa. Ative-a em ambientes onde se pretende validação antecipada, como pipelines de CI e verificações de pull request.

Exemplo: Detetar um prefixo de endereço inválido durante a fase de planeamento

A configuração seguinte cria uma rede virtual com um bloco CIDR (Classless Inter-Domain Routeing) inválido. Com o pré-voo ativado, o erro surge durante terraform plan em vez de 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
        ]
      }
    }
  }
}

Ao executar terraform plan com esta configuração, o preflight devolve 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) elimina o erro.

O que valida o pré-voo

O pré-voo envia o corpo do recurso para o endpoint pré-voo da API ARM, que valida:

• Valores de propriedades em relação ao esquema de recursos ARM (por exemplo, intervalos válidos de CIDR (Classless Inter-Domain Routing), nomes de SKU permitidos, campos requeridos).
• Quotas ao nível da subscrição e restrições de capacidade para tipos de recursos suportados.
• Conformidade de políticas para atribuições do Azure Policy que correm em modo preflight.

O Preflight não valida:

• Dependências entre recursos ou sequenciação.
• Recursos que não têm suporte para endpoints ARM preflight (o fornecedor ignora silenciosamente a validação desses tipos de recursos).
• Falhas de autenticação ou autorização (Gestão de Identidade e Acesso (IAM))—estas falhas surgem durante terraform apply.

Utilização de pré-voo em pipelines de CI

Adicionar pré-verificação a um pipeline de CI proporciona um passo rápido e não destrutivo de validação que deteta erros de configuração antes de o código ser integrado. Ative enable_preflight = true no bloco de provedor da sua configuração Terraform e depois execute terraform plan:

provider "azapi" {
  enable_preflight = true
}

Como a pré-execução corre durante terraform plan sem efeitos secundários, é seguro correr em fluxos de trabalho de pedidos de pull contra subscrições ativas do Azure.

Desativar o ruído de saída com ignore_no_op_changes

Se executares planos repetidamente, o AzAPI pode detetar pequenas diferenças no-op entre a configuração e o estado ARM (por exemplo, valores padrão normalizados devolvidos pela API). Para suprimir estas diferenças de tempo de planeamento e focar em mudanças reais, defina ignore_no_op_changes = true no bloco de fornecedores:

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

Passos seguintes