Enable preflight validation in the AzAPI Terraform provider

Terraform enables the definition, preview, and deployment of cloud infrastructure. Using Terraform, you create configuration files using HCL syntax. The HCL syntax allows you to specify the cloud provider - such as Azure - and the elements that make up your cloud infrastructure. After you create your configuration files, you create an execution plan that allows you to preview your infrastructure changes before they're deployed. Once you verify the changes, you apply the execution plan to deploy the infrastructure.

The AzAPI Terraform provider includes built-in preflight validation that validates your Azure resource configuration against the ARM API schema during terraform plan, before any resources are created or modified in Azure. Preflight catches configuration errors early—such as invalid address prefixes, unsupported property combinations, or quota violations—without incurring the cost of a failed deployment.

Preflight validation is one of AzAPI's key differentiators and works natively with the provider's direct-to-ARM-API architecture. You can also run preflight from the Microsoft Terraform VS Code extension without setting the provider flag directly.

Prerequisites

• Azure subscription: If you don't have an Azure subscription, create a free account before you begin.

• Configure Terraform: If you haven't already done so, configure Terraform using one of the following options:

  • Configure Terraform in Azure Cloud Shell with Bash
  • Configure Terraform in Azure Cloud Shell with PowerShell
  • Configure Terraform in Windows with Bash
  • Configure Terraform in Windows with PowerShell

When you log in to the Azure portal with a Microsoft account, the default Azure subscription for that account is used.

Terraform automatically authenticates using information from the default Azure subscription.

Run az account show to verify the current Microsoft account and Azure subscription.

az account show

Any changes you make via Terraform are on the displayed Azure subscription. If that's what you want, skip the rest of this article.

Enable preflight validation

Set enable_preflight = true in the provider "azapi" block:

provider "azapi" {
  enable_preflight = true
}

Preflight is disabled by default to preserve backward compatibility. Enable it in environments where you want early validation, such as CI pipelines and pull request checks.

Example: Catch an invalid address prefix at plan time

The following configuration creates a virtual network with an invalid Classless Inter-Domain Routing (CIDR) block. With preflight enabled, the error surfaces during terraform plan rather than during 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
        ]
      }
    }
  }
}

When you run terraform plan with this configuration, preflight returns an error similar to:

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

Correcting the address prefix to a valid value (for example, 10.0.0.0/16) clears the error.

What preflight validates

Preflight sends the resource body to the ARM API's preflight endpoint, which validates:

• Property values against the ARM resource schema (for example, valid CIDR (Classless Inter-Domain Routing) ranges, allowed SKU names, required fields).
• Subscription-level quota and capacity constraints for supported resource types.
• Policy compliance for Azure Policy assignments that run in preflight mode.

Preflight does not validate:

• Cross-resource dependencies or sequencing.
• Resources that don't have ARM preflight endpoint support (the provider silently skips validation for those resource types).
• Authentication or authorization (Identity and Access Management (IAM)) failures—these failures surface during terraform apply.

Use preflight in CI pipelines

Adding preflight to a CI pipeline provides a fast, nondestructive validation step that catches configuration errors before code is merged. Enable enable_preflight = true in the provider block of your Terraform configuration, then run terraform plan:

provider "azapi" {
  enable_preflight = true
}

Because preflight runs during terraform plan with no side effects, it's safe to run in pull request workflows against live Azure subscriptions.

Disable output noise with ignore_no_op_changes

If you run plans repeatedly, AzAPI might detect minor no-op differences between the configuration and the ARM state (for example, normalized default values returned by the API). To suppress these plan-time differences and focus on real changes, set ignore_no_op_changes = true in the provider block:

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

Next steps