7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
Overview of the Terraform AzAPI provider
11/11/2024
The AzAPI provider is a thin layer on top of the Azure ARM REST APIs. It enables you to
manage any Azure resource type using any API version, enabling you to utilize the latest
functionality within Azure. AzAPI is a first-class provider designed to be used on its own or in
tandem with the AzureRM provider.
Benefits of using the AzAPI provider
The AzAPI provider features the following benefits:
Supports all Azure control plane services:
Preview services and features
All API versions
Full Terraform state file fidelity
Properties and values are saved to state
No dependency on Swagger
Common and consistent Azure authentication
Built-in preflight validation
Granular control over infrastructure development
Robust VS Code Extension
Resources
To allow you to manage all Azure resources and features without requiring updates, the AzAPI
provider includes the following generic resources:
ﾉ Expand table
Resource Name Description
azapi_resource Used to fully manage any Azure (control plane) resource (API) with full
CRUD.
Example Use Cases:
New preview service
New feature added to existing service
Existing feature / service not currently covered
azapi_update_resource Used to manage resources or parts of resources that don't have full CRUD
Example Use Cases:
[Link] 1/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
Resource Name Description
Update new properties on an existing service
Update pre-created child resource - such as DNS SOA record.
azapi_resource_action Used to perform a single operation on a resource without managing the
lifecycle of it
Example Use Cases:
Shut down a Virtual Machine
Add a secret to a Key Vault
azapi_data_plane_resource Used to manage a specific subset of Azure data plane resources
Example Use Cases:
KeyVault Certificate Contacts
Synapse Workspace Libraries
Usage hierarchy
Overall, usage should follow these steps:
1. It's always recommended to start with performing as many operations as possible within
azapi_resource .
2. If the resource type doesn't exist within azapi_resource but does fall under one of the
types supported by azapi_data_plane_resource , use that instead.
3. If the resource already exists in AzureRM or has a property that can't be accessed within
azapi_resource , use azapi_update_resource to access these specific properties. Resources
that azapi_resource or azapi_data_plane_resource don't support can't be updated
through this resource.
4. If you're trying to perform an action that isn't based on an Azure CRUD-friendly resource,
azapi_resource_action is less straightforward than azapi_update_resource but more
flexible.
Resource configuration examples
The following code snippet configures a resource that doesn't currently exist in the AzureRM
provider:
Terraform
resource "azapi_resource" "publicip" {
type = "[Link]/Customipprefixes@2021-03-01"
name = "exfullrange"
parent_id = azurerm_resource_group.[Link]
location = "westus2"
[Link] 2/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
body = {
properties = {
cidr = "[Link]/24"
signedMessage = "Sample Message for WAN"
}
}
}
The following code snippet configures a preview property for an existing resource from
AzureRM:
Terraform
resource "azapi_update_resource" "test" {
type = "[Link]/registries@2020-11-01-preview"
resource_id = azurerm_container_registry.[Link]
body = {
properties = {
anonymousPullEnabled = var.bool_anonymous_pull
}
}
}
The following code snippet configures a resource action on an existing AzureRM resource:
Terraform
resource "azapi_resource_action" "vm_shutdown" {
type = "[Link]/virtualMachines@2023-07-01"
resource_id = azurerm_linux_virtual_machine.[Link]
action = "powerOff”
}
The following code snippet configures a resource that doesn't currently exist in the AzureRM
provider due to being provisioned on the data plane:
Terraform
resource "azapi_data_plane_resource" "dataset" {
type = "[Link]/workspaces/datasets@2020-12-01"
parent_id =
trimprefix(data.azurerm_synapse_workspace.example.connectivity_endpoints.dev,
"[Link]
name = "example-dataset"
body = {
properties = {
type = "AzureBlob",
typeProperties = {
[Link] 3/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
folderPath = {
value = "@dataset().MyFolderPath"
type = "Expression"
}
fileName = {
value = "@dataset().MyFileName"
type = "Expression"
}
format = {
type = "TextFormat"
}
}
parameters = {
MyFolderPath = {
type = "String"
}
MyFileName = {
type = "String"
}
}
}
}
}
Preflight usage example
The following code snippet errors during terraform plan due to AzAPI's built-in preflight
validation:
Terraform
provider "azapi" {
enable_preflight = true
}
resource "azapi_resource" "vnet" {
type = "[Link]/virtualNetworks@2024-01-01"
parent_id = azapi_resource.[Link]
name = "example-vnet"
location = "westus"
body = {
properties = {
addressSpace = {
addressPrefixes = [
"[Link]/160", # preflight will throw an error here
]
}
}
}
}
[Link] 4/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
Preflight is hidden behind a provider flag but will help throw errors in plan stage.
Data Sources
The AzAPI provider supports a variety of useful data sources:
ﾉ Expand table
Data Source Name Description
azapi_resource Used to read information from any Azure (control plane) resource (API).
Example Use Cases:
New preview service
New feature added to existing service
Existing feature / service not currently covered
azapi_client_config Access client information such as subscription ID and tenant ID.
azapi_resource_action Used to perform a single read operation on a resource without managing
the lifecycle of it
Example Use Cases:
List Keys
Read status of VM
azapi_data_plane_resource Used to access a specific subset of Azure data plane resources
Example Use Cases:
KeyVault Certificate Contacts
Synapse Workspace Libraries
azapi_resource_id Access a resource's resource ID, with the ability to output information
such as subscription ID, parent ID, resource group name, and resource
name.
azapi_resource_list List all resources under a given parent resource ID.
Example Use Cases:
Resources under a subscription / resource group
Subnets under a virtual network
Authentication using the AzAPI provider
The AzAPI provider enables the same authentication methods as the AzureRM provider. For
more information on authentication options, see Authenticate Terraform to Azure.
Experience and lifecycle of the AzAPI provider
[Link] 5/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
This section describes some tools to help you use the AzAPI provider.
VS Code extension and Language Server
The AzAPI VS Code extension provides a rich authoring experience with the following
benefits:
List all available resource types and API versions.
Auto-completion of the allowed properties and values for any resource.
Show hints when hovering over a property.
[Link] 6/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
Syntax validation
Auto-completion with code samples.
aztfmigrate migration tool
The aztfmigrate tool is designed to help migrate existing resources between the AzAPI and
AzureRM providers.
aztfmigrate has two modes: plan and migrate:
Plan displays the AzAPI resources that can be migrated.
Migrate migrates the AzAPI resources to AzureRM resources in both the HCL files and the
state.
aztfmigrate ensures after migration that your Terraform configuration and state are aligned
with your actual state. You can validate the update to state by running terraform plan after
completing the migration to see that nothing has changed.
Granular controls over infrastructure
[Link] 7/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
One major benefit of AzAPI is through its ability to fine-tune your configuration to match the
right design patterns. There are several ways in which you can do this:
Provider functions
AzAPI (v2.0 and newer) has a slew of provider functions :
ﾉ Expand table
Function Name Description
build_resource_id Constructs an Azure resource ID given the parent ID, resource type,
and resource name.
Useful for creating resource IDs for top-level and nested resources
within a specific scope.
extension_resource_id Constructs an Azure extension resource ID given the base resource
ID, resource type, and additional resource names.
management_group_resource_id Constructs an Azure management group scope resource ID given
the management group name, resource type, and resource names.
parse_resource_id This function takes an Azure resource ID and a resource type and
parses the ID into its individual components such as subscription ID,
resource group name, provider namespace, and other parts.
resource_group_resource_id Constructs an Azure resource group scope resource ID given the
subscription ID, resource group name, resource type, and resource
names.
subscription_resource_id Constructs an Azure subscription scope resource ID given the
subscription ID, resource type, and resource names.
tenant_resource_id Constructs an Azure tenant scope resource ID given the resource
type and resource names.
User-defined retriable errors with the retry block
The AzAPI provider can digest errors when expected through the retry block. For example, if
a resource may run into a create timeout issue, the following block of code may help:
Terraform
resource "azapi_resource" "example" {
# usual properties
retry {
interval_seconds = 5
randomization_factor = 0.5 # adds randomization to retry pattern
[Link] 8/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
multiplier = 2 # if try fails, multiplies time between next try
by this much
error_message_regex = ["ResourceNotFound"]
}
timeouts {
create = "10m"
}
Triggers for resource replacement
The AzAPI provider allows you to configure parameters for resource replacement:
replace_triggers_external_values
Replaces the resource if a value changes. For example, if the SKU or zones variables were to be
modified, this resource would be re-created:
Terraform
resource "azapi_resource" "example" {
name = [Link]
type = "[Link]/publicIPAddresses@2023-11-01"
parent_id = "/subscriptions/00000000-0000-0000-0000-
000000000000/resourceGroups/example"
body = properties = {
sku = [Link]
zones = [Link]
}
replace_triggers_external_values = [
[Link],
[Link],
]
}
This can work across a broad set of resources, i.e. a policy assignment when properties of the
definition changes.
replace_triggers_refs
Replaces the resource if the referenced value changes. For example, if the SKU name or tier
was modified, this resource would be re-created:
Terraform
resource "azapi_resource" "example" {
type = "[Link]/namespaces@2021-11-01"
[Link] 9/10
7/19/25, 9:27 AM Overview of the Terraform AzAPI provider | Microsoft Learn
parent_id = azurerm_resource_group.[Link]
name = "xxx"
location = "westus"
body = {
properties = {
}
sku = {
name = "Standard"
tier = "Standard"
}
}
replace_triggers_refs = ["sku"]
}
This would not trigger a replace if a different resource's SKU were to change.
Next steps
Deploy your first resource with the AzAPI provider
Deploy your first Update Resource with the AzAPI provider
Deploy your first resource action with the AzAPI provider
Visit the provider registry
[Link] 10/10