When to Use azurerm vs azapi

Now that you understand what the azurerm and azapi Terraform providers do, the next question is: when should you use each? This guide focuses on practical decision-making to help you choose the right provider for the task—rather than relying on habit or guessing. Use this guidance to reduce risk, improve maintainability, and keep your Terraform code aligned with Azure features and lifecycle practices.

​

Quick decision summary

• Prefer azurerm for standard, well-supported Azure resources where stability, validation, and long-term maintainability matter.
• Use azapi as an escape hatch when azurerm does not yet support a resource or property (including preview APIs), or when you need immediate access to specific ARM features.
• Mix both providers in the same configuration when appropriate: azurerm for most resources, azapi only where necessary.

​

High-level comparison

Below is a concise comparison of the most important criteria to consider when choosing between azurerm and azapi.

​

Detailed guidance

Resource schema and validation

• azurerm is strongly typed: the provider exposes documented arguments and types for each resource. This enables provider-side validation, clearer error messages, and better editor autocompletion.
• azapi treats the ARM resource body as a payload. Terraform (via azapi) performs minimal schema validation for ARM properties and forwards the JSON to Azure Resource Manager (ARM). This gives flexibility but removes many safety nets.

Validation behavior:

• azurerm: many mistakes are caught in terraform plan before modifications reach Azure.
• azapi: you are more likely to encounter validation errors at terraform apply (or later), so authors must validate ARM properties and API version choices carefully.

Feature availability and release cadence

• azurerm: waits for provider maintainers to model new Azure features. There can be a delay between the ARM API release and azurerm support.
• azapi: can target the ARM API version you need and access new or preview functionality immediately.

Ease of use and author experience

• azurerm: better for most teams—well-documented, consistent patterns, and lower cognitive load.
• azapi: better for advanced scenarios where direct ARM control is required. Expect to author JSON blocks, choose API versions explicitly, and handle raw ARM property shapes.

Stability and production risk

• azurerm: generally the safer choice for production workloads.
• azapi: powerful but riskier when used with preview APIs or unstable ARM endpoints. Use with caution and document intent.

​

Combining providers (recommended pattern)

You do not need to pick one provider for everything. A pragmatic pattern:

1. Use azurerm for the majority of resources—those that are supported, stable, and commonly managed.
2. Introduce azapi only for:
   • Resources not yet implemented in azurerm.
   • Features only exposed in preview APIs.
   • Cases where you need to set ARM properties that azurerm does not expose.

This hybrid approach keeps your configuration readable and safer while still enabling access to the latest Azure capabilities.

​

Best practices

• Prefer azurerm by default to reduce complexity and operational risk.
• Restrict azapi usage to well-justified exceptions. Keep such usages minimal and isolated.
• Document every azapi resource with:
  • The exact ARM resource type (e.g., Microsoft.Service/resourceType).
  • The targeted ARM API version.
  • The concrete reason azurerm couldn’t be used.
• Validate azapi configurations against the ARM API reference and test in non-production environments.
• Use version control and code reviews to ensure azapi payloads remain maintainable.
• Periodically review azapi resources—migrate them to azurerm if/when provider support becomes available.

​

When to choose which provider — short checklist

• Choose azurerm when:
  • The resource is supported by the provider.
  • You want provider-side validation and safer plan behavior.
  • You need stability and maintainability for production workloads.
• Choose azapi when:
  • The resource or property is not yet supported in azurerm.
  • You must use a preview or very recent ARM API.
  • You require direct access to ARM properties not surfaced by azurerm.

In summary: azurerm is the default, stable choice. azapi is a powerful tool to access recent or unsupported ARM features, but it requires additional care. Use them together strategically to keep Terraform aligned with Azure’s pace of innovation without sacrificing reliability.

​

Links and references

• azurerm provider (Terraform Registry)
• azapi provider (Terraform Registry)
• Azure Resource Manager REST API reference
• Terraform documentation