AzAPI Provider for Terraform

Managed identities for Azure resources allow Azure resources to authenticate to services that support Azure Active Directory (Azure AD) without storing credentials on the resource.

There are two types:

1. System-assigned: The identity's lifecycle is tied to the resource. It is created when the resource is created and removed when the resource is deleted.
2. User-assigned: A standalone Azure resource that can be assigned to one or more Azure resources.

To use a managed identity, you must perform two steps:

1. Assign a role: Associate the identity with the subscription used to run Terraform to grant permission to access Azure Resource Manager (ARM) resources.
2. Configure access control: Set up permissions for specific Azure resources (e.g., Key Vault or Storage Account) that the identity needs to access.

Permissions required: To configure a resource with a managed identity and assign RBAC roles, your account must be an Owner or have both Contributor and User Access Administrator roles.

The AzAPI provider supports Azure Policy invoke policies (external evaluation policies). When a write request (PUT, POST, PATCH, or DELETE) is blocked because it lacks a required policy token, the provider can automatically handle the acquisition and retry process.

Reactive Acquisition (Default)

By default, the provider uses a reactive approach:

1. It sends the original write request.
2. If it receives a 403 Forbidden with the error code RequestDisallowedByPolicy and a PolicyViolation entry containing missingPolicyTokenDetails where shouldDeny is true, it triggers the acquisition flow.
3. The provider calls the Microsoft.Authorization/acquirePolicyToken API (api-version=2025-03-01) for the subscription.
4. If a token is returned, the provider attaches it via the x-ms-policy-external-evaluations header and retries the original request.

Note: GET requests are never affected by this feature.

Limitations

• Change references are not supported: If the policy denial indicates that a change reference is required (isChangeReferenceRequired is true), the provider will return an error instead of attempting to acquire a token.

The response_export_values attribute determines how data from the Azure API response is mapped to the output attribute of the ephemeral resource. It supports two modes:

1. List Mode

Provide a list of JMESPath paths to export. Setting it to ["*"] exports the full response body.

Example: If you set ["properties.loginServer", "properties.policies.quarantinePolicy.status"], the output will be:

{
  properties = {
    loginServer = "registry1.azurecr.io"
    policies = {
      quarantinePolicy = {
        status = "disabled"
      }
    }
  }
}

2. Map Mode

Provide a map where the key is your desired result name and the value is a JMESPath query string.

Example: If you set {"login_server": "properties.loginServer", "quarantine_status": "properties.policies.quarantinePolicy.status"}, the output will be:

{
  "login_server" = "registry1.azurecr.io"
  "quarantine_status" = "disabled"
}

# Example of using the output from an ephemeral resource
output "login_server" {
  value = ephemeral.azapi_resource_action.example.output.properties.loginServer
}

The azapi_data_plane_resource is used to manage resources that reside on the data plane of an Azure service rather than the control plane. Unlike standard azapi_resource calls which typically target the Azure Resource Manager (ARM) endpoint, data plane resources often target service-specific endpoints (e.g., service-name.azureiotcentral.com or service-name.search.windows.net).

Key characteristics:

• parent_id: Often requires the service's data plane endpoint (e.g., a URL) rather than an ARM resource ID.
• retry block: Allows configuring custom retry logic for specific error patterns common in data plane operations (like PermissionDenied or Unauthorized).
• depends_on: Frequently requires an explicit dependency on a control plane azapi_resource (like a Role Assignment) to ensure permissions are in place before the data plane call is made.

resource "azapi_data_plane_resource" "example" {
  type      = "Microsoft.AppConfiguration/configurationStores/keyValues@1.0"
  parent_id = replace(azapi_resource.appconf.output.endpoint, "https://", "")
  name      = "mykey"
  body = {
    content_type = ""
    value        = "myvalue"
  }

  retry = {
    error_message_regex  = ["PermissionDenied", "Unauthorized"]
    interval_seconds     = 30
    max_interval_seconds = 180
  }

  depends_on = [
    azapi_resource.roleAssignment,
  ]
}

You can capture data from the Azure API response using response_export_values (for standard data) or sensitive_response_export_values (for sensitive data). This allows you to use values returned by the action in other parts of your Terraform configuration.

Both attributes accept two formats:

1. List: A list of paths to export. Using ["*"] exports the entire response body.

   • Example: ["properties.loginServer"] creates an output object containing that specific path.

2. Map: A map where the key is your desired output name and the value is a JMESPath query string used to extract the data.

   • Example: {"login_server": "properties.loginServer"}

Accessing Outputs

Once exported, you can access the values via the .output or .sensitive_output attributes of the resource.

// Accessing standard output
output "login_server" {
  value = azapi_resource_action.example.output.properties.loginServer
}

// Accessing sensitive output
output "quarantine_policy" {
  value     = azapi_resource_action.example.sensitive_output.properties.policies.quarantinePolicy.status
  sensitive = true
}

resource "azapi_resource_action" "example" {
  type        = "Microsoft.ContainerRegistry/registries@2023-01-01"
  resource_id = azapi_container_registry.example.id
  action      = "regeneratePassword"
  
  response_export_values = {
    "login_server" = "properties.loginServer"
  }
}

output "login_server" {
  value = azapi_resource_action.example.output.login_server
}