Edit

Quickstart: List Azure resources with 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.

In this article, you use the azapi_resource_list data source to list Azure resources and filter results with JMESPath expressions. You create two storage accounts, then use azapi_resource_list to list and extract their properties.

  • Create a resource group and two storage accounts with the AzureRM provider
  • Use azapi_resource_list to list the storage accounts and extract their names and locations using JMESPath

Prerequisites

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

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.

Understand response_export_values

The response_export_values attribute controls which properties are extracted from the API response and made available in the output attribute of the data source. It accepts either a list or a map:

  • List: Specifies JSON paths to extract. Use ["*"] to export the full response body.
  • Map: Uses JMESPath expressions to filter and reshape the response. The key is the name of the result, and the value is the JMESPath expression.

The map form is preferred when you need to extract specific fields or transform list responses, because it produces cleaner, more usable output values.

Implement the Terraform code

  1. Create a directory in which to test the sample Terraform code and make it the current directory.

  2. Create a file named providers.tf and insert the following code:

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

provider "azurerm" {
  features {}
}

provider "azapi" {}

  3. Create a file named variables.tf and insert the following code:

    variable "resource_group_location" {
  type        = string
  default     = "eastus"
  description = "Location of the resource group."
}

variable "resource_group_name_prefix" {
  type        = string
  default     = "rg"
  description = "Prefix of the resource group name that's combined with a random value to create a unique name."
}

  4. Create a file named main.tf and insert the following code:

    resource "random_pet" "rg_name" {
  prefix = var.resource_group_name_prefix
}

resource "random_string" "storage_suffix" {
  length  = 8
  upper   = false
  special = false
}

resource "azurerm_resource_group" "example" {
  location = var.resource_group_location
  name     = random_pet.rg_name.id
}

resource "azurerm_storage_account" "example" {
  count                    = 2
  name                     = "st${random_string.storage_suffix.result}${count.index}"
  resource_group_name      = azurerm_resource_group.example.name
  location                 = azurerm_resource_group.example.location
  account_tier             = "Standard"
  account_replication_type = "LRS"
}

Run terraform init to initialize the Terraform deployment. This command downloads the Azure provider required to manage your Azure resources.

terraform init -upgrade

Key points:

  • The -upgrade parameter upgrades the necessary provider plugins to the newest version that complies with the configuration's version constraints.

Run terraform plan to create an execution plan.

terraform plan -out main.tfplan

Key points:

  • The terraform plan command creates an execution plan, but doesn't execute it. Instead, it determines what actions are necessary to create the configuration specified in your configuration files. This pattern allows you to verify whether the execution plan matches your expectations before making any changes to actual resources.
  • The optional -out parameter allows you to specify an output file for the plan. Using the -out parameter ensures that the plan you reviewed is exactly what is applied.

Run terraform apply to apply the execution plan to your cloud infrastructure.

terraform apply main.tfplan

Key points:

  • The example terraform apply command assumes you previously ran terraform plan -out main.tfplan.
  • If you specified a different filename for the -out parameter, use that same filename in the call to terraform apply.
  • If you didn't use the -out parameter, call terraform apply without any parameters.

List resources with azapi_resource_list

Now that the storage accounts are created, add a data source to list them and extract properties using JMESPath.

  1. Create a file named list_resources.tf and insert the following code:

    data "azapi_resource_list" "storage_accounts" {
  type      = "Microsoft.Storage/storageAccounts@2023-01-01"
  parent_id = azurerm_resource_group.example.id

  # Use JMESPath expressions to extract specific fields from the response.
  # The API returns a list of resources in a top-level "value" array.
  response_export_values = {
    "names"     = "value[].name"
    "locations" = "value[].location"
    "skus"      = "value[].sku.name"
  }
}

  2. Create a file named outputs.tf and insert the following code:

    output "resource_group_name" {
  value = azurerm_resource_group.example.name
}

output "storage_account_names" {
  value = data.azapi_resource_list.storage_accounts.output.names
}

output "storage_account_locations" {
  value = data.azapi_resource_list.storage_accounts.output.locations
}

output "storage_account_skus" {
  value = data.azapi_resource_list.storage_accounts.output.skus
}

  3. Run terraform apply again to create the data source and extract the outputs:

    terraform apply

Key points about azapi_resource_list

  • The type field identifies the resource type and API version to list.
  • The parent_id field sets the scope: a resource group ID to list within a resource group, a subscription ID to list across a subscription, or a parent resource ID to list child resources (for example, subnets under a VNet).
  • The map form of response_export_values uses JMESPath expressions against the raw API response. The storage account list API returns results in a top-level value array, so expressions start with value[].

List resources at different scopes

The parent_id determines the listing scope. Examples:

# List all storage accounts in a subscription
data "azapi_resource_list" "all_storage" {
  type      = "Microsoft.Storage/storageAccounts@2023-01-01"
  parent_id = "/subscriptions/${var.subscription_id}"
  response_export_values = {
    "names" = "value[].name"
  }
}

# List subnets in a virtual network (child resource listing)
data "azapi_resource_list" "subnets" {
  type      = "Microsoft.Network/virtualNetworks/subnets@2023-11-01"
  parent_id = azurerm_virtual_network.example.id
  response_export_values = ["*"]
}

Clean up resources

When you no longer need the resources created via Terraform, do the following steps:

  1. Run terraform plan and specify the destroy flag.

    terraform plan -destroy -out main.destroy.tfplan

    Key points:

    • The terraform plan command creates an execution plan, but doesn't execute it. Instead, it determines what actions are necessary to create the configuration specified in your configuration files. This pattern allows you to verify whether the execution plan matches your expectations before making any changes to actual resources.
    • The optional -out parameter allows you to specify an output file for the plan. Using the -out parameter ensures that the plan you reviewed is exactly what is applied.

  2. Run terraform apply to apply the execution plan.

    terraform apply main.destroy.tfplan

Troubleshoot Terraform on Azure

Troubleshoot common problems when using Terraform on Azure

Next steps

Terraform AzAPI provider overview

Use provider functions in the AzAPI Terraform provider

  • Last updated on