Terraform AzAPI 提供程序概述

AzAPI 提供程序是 Azure ARM REST API 之上的一个薄层。 它使你能够使用任何 API 版本管理任何Azure资源类型，使你能够在Azure中使用最新功能。 AzAPI 是一流的提供程序，旨在单独使用或与 AzureRM 提供程序协同使用。

使用 AzAPI 提供程序的好处

AzAPI 提供程序具有以下优点：

• 支持所有 Azure 控制平面服务：
  • 预览服务和功能
  • 所有 API 版本
• 完整 Terraform 状态文件保真度
  • 将属性和值保存到状态
• 不依赖于 Swagger
• 常见且一致的 Azure 身份验证
• 内置预检验证
• 对基础设施开发的细粒度控制
• Microsoft Terraform Visual Studio Code 扩展

资源

为了允许你在不需要更新的情况下管理所有 Azure 资源和功能，AzAPI 提供程序包括以下通用资源：

有关数据平面框架的工作原理和 parent_id 与控制平面资源的不同之处的详细说明，请参阅 了解 AzAPI 数据平面框架。

使用层级结构

总体而言，使用应遵循以下步骤：

1. 首先，在azapi_resource内执行尽可能多的操作。
2. 如果资源类型不存在于 azapi_resource 中，但属于 azapi_data_plane_resource 支持的类型之一，请改用该类型。
3. 如果 AzureRM 中已存在该资源，或者该资源具有无法在 azapi_resource 内访问的属性，请使用 azapi_update_resource 访问这些特定属性。 不支持 azapi_resource 或 azapi_data_plane_resource 的资源无法通过此资源进行更新。
4. 如果尝试执行不基于 Azure CRUD 友好资源的操作，azapi_resource_action 不如 azapi_update_resource 简单，但更灵活。

资源配置示例

以下代码片段直接通过 ARM API 配置Azure资源：

resource "azapi_resource" "publicip" {
  type      = "Microsoft.Network/Customipprefixes@2021-03-01"
  name      = "exfullrange"
  parent_id = azurerm_resource_group.example.id
  location  = "westus2"

  body = {
    properties = {
      cidr          = "10.0.0.0/24"
      signedMessage = "Sample Message for WAN"
    }
  }
}

以下代码片段为 AzureRM 中的现有资源配置预览属性：

resource "azapi_update_resource" "test" {
  type        = "Microsoft.ContainerRegistry/registries@2020-11-01-preview"
  resource_id = azurerm_container_registry.acr.id

  body = {
    properties = {
      anonymousPullEnabled = var.bool_anonymous_pull
    }
  }
}

以下代码段配置了对现有 AzureRM 资源的资源操作：

resource "azapi_resource_action" "vm_shutdown" {
  type = "Microsoft.Compute/virtualMachines@2023-07-01"
  resource_id = azurerm_linux_virtual_machine.example.id
  action = "powerOff”
}

以下代码段配置了 AzureRM 提供程序中当前不存在的资源，因为该资源是在数据平面上配置的：

resource "azapi_data_plane_resource" "dataset" {
  type      = "Microsoft.Synapse/workspaces/datasets@2020-12-01"
  parent_id = trimprefix(data.azurerm_synapse_workspace.example.connectivity_endpoints.dev, "https://")
  name      = "example-dataset"
  body = {
    properties = {
      type = "AzureBlob",
      typeProperties = {
        folderPath = {
          value = "@dataset().MyFolderPath"
          type  = "Expression"
        }
        fileName = {
          value = "@dataset().MyFileName"
          type  = "Expression"
        }
        format = {
          type = "TextFormat"
        }
      }
      parameters = {
        MyFolderPath = {
          type = "String"
        }
        MyFileName = {
          type = "String"
        }
      }
    }
  }
}

预检使用示例

在 terraform plan 期间，由于 AzAPI 的内置预检验证，以下代码片段出现错误：

provider "azapi" {
  enable_preflight = true
}
resource "azapi_resource" "vnet" {
  type      = "Microsoft.Network/virtualNetworks@2024-01-01"
  parent_id = azapi_resource.resourceGroup.id
  name      = "example-vnet"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = [
          "10.0.0.0/160", # preflight will throw an error here
        ]
      }
    }
  }
}

启用后，预检会在 terraform plan 期间显示配置错误，而不是在应用时。

数据源

AzAPI 提供程序支持各种有用的数据源：

有关使用 azapi_resource_list 和 JMESPath 筛选进行操作的示例，请参阅 使用 AzAPI Terraform 提供程序列出 Azure 资源。

使用 azapi_resource 数据源读取现有资源

azapi_resource数据源读取任何Azure资源的当前状态，并通过 output 属性公开其属性。 如果需要 AzureRM 提供程序未公开的属性，请使用它：

data "azapi_resource" "aks" {
  type      = "Microsoft.ContainerService/managedClusters@2024-02-01"
  resource_id = azurerm_kubernetes_cluster.example.id

  # Extract the OIDC issuer URL, not exposed by azurerm_kubernetes_cluster
  response_export_values = ["properties.oidcIssuerProfile.issuerURL"]
}

output "oidc_issuer_url" {
  value = data.azapi_resource.aks.output.properties.oidcIssuerProfile.issuerURL
}

使用 response_export_values 和 JMESPath

response_export_values 控制从原始 ARM API 响应中提取哪些属性，并将其在 output 属性中提供。 它接受列表或地图：

• 列表：指定要提取的 JSON 属性路径。 用于 ["*"] 导出完整响应正文。
• 映射：使用 JMESPath 表达式筛选和重塑响应。 键是输出字段名称;该值为 JMESPath 查询。

首选使用映射形式来处理列表响应和需要转换输出的情况：

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

  response_export_values = {
    "names"     = "value[].name"
    "locations" = "value[].location"
  }
}

有关完整演练，请参阅 使用 AzAPI Terraform 提供程序列出 Azure 资源。

使用 AzAPI 提供程序进行身份验证

AzAPI 提供程序启用与 AzureRM 提供程序相同的身份验证方法。 有关身份验证选项的详细信息，请参阅向 Azure 验证 Terraform。

AzAPI 提供程序的体验和生命周期

本节介绍一些帮助你使用 AzAPI 提供程序的工具。

VS Code 扩展和语言服务器

Microsoft Terraform VS Code 扩展为 AzureRM 和 AzAPI 提供程序提供了丰富的创作体验，包括：

• 列出所有可用的资源类型和 API 版本。
• 自动补全任何资源允许的属性和值。
• 将鼠标悬停在某个属性上时，显示提示。
• 语法验证
• 使用代码示例自动完成。

该扩展还支持粘贴为 AzAPI（将 ARM JSON 转换为 azapi_resource 块）、通过 aztfexport 导出 Azure 资源、AzureRM 到 AzAPI 的迁移和预检验证。 有关完整指南，请参阅 使用 Microsoft Terraform VS Code 扩展。

aztfmigrate 迁移工具

aztfmigrate 工具旨在帮助在 AzAPI 和 AzureRM 提供程序之间迁移现有资源。

aztfmigrate 有两种模式：计划和迁移：

• “Plan” 显示可迁移的 AzAPI 资源。
• “迁移”将 AzAPI 资源迁移到 HCL 文件和状态中的 AzureRM 资源。

aztfmigrate 确保迁移后，Terraform 配置和状态与实际状态保持一致。 完成迁移后，可以通过运行 terraform plan 更新来验证状态，以确认未发生任何更改。

有关分步演练，请参阅 将资源从 AzAPI 迁移到 AzureRM。

导入现有Azure资源

若要在不重新创建 AzAPI 管理的情况下将现有Azure资源引入，请使用 import 块（Terraform 1.5 及更高版本）或 terraform import 命令。 资源 ID 必须包含 API 版本作为查询参数：

import {
  to = azapi_resource.example
  id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Network/virtualNetworks/example-vnet?api-version=2023-11-01"
}

resource "azapi_resource" "example" {
  type      = "Microsoft.Network/virtualNetworks@2023-11-01"
  name      = "example-vnet"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = ["10.0.0.0/16"]
      }
    }
  }
}

若要从现有Azure基础结构一次性导入多个资源，请使用 Azure Export for Terraform （aztfexport），这将自动生成 HCL 配置和导入块。

对基础结构的精细控制

AzAPI 的一个主要好处是能够微调配置以匹配正确的设计模式。 有若干方法可实现此操作：

提供程序配置选项

AzAPI 提供程序块接受多个设置，这些设置在配置中的所有资源中全局应用：

有关提供程序配置选项的完整列表，请参阅 AzAPI 提供程序架构。

有关启用预检的演练，请参阅 AzAPI Terraform 提供程序中的“启用预检验证”。

提供者函数

AzAPI v2.0 及更高版本包括多个 提供程序函数：

用户自定义的可重试错误使用块retry

AzAPI 提供程序通过 retry 块处理预期的错误。 例如，使用以下配置，在资源遇到创建超时时重试：

resource "azapi_resource" "example" {
    # usual properties
    retry {
        interval_seconds     = 5
        randomization_factor = 0.5 # adds randomization to retry pattern
        multiplier           = 2 # if try fails, multiplies time between next try by this much
        error_message_regex  = ["ResourceNotFound"]
    }
    timeouts {
        create = "10m"
}

块 retry 接受以下属性：

将retry与timeouts块结合使用，以设置总重试持续时间的上限：

timeouts {
  create = "10m"
}

临时资源和仅写属性

AzAPI v2.x 支持通过 sensitive_body 属性在 azapi_resource 中使用只写入参数（适用于 Terraform 1.11 及更高版本）。 只写属性会被发送到 ARM API，但不会存储在 Terraform 状态中，这对处理机密信息和凭证非常有用。

resource "azapi_resource" "example" {
  type      = "Microsoft.SomeService/resources@2024-01-01"
  name      = "example"
  parent_id = azurerm_resource_group.example.id

  body = {
    properties = {
      name = "example"
    }
  }

  # Write-only — not stored in state
  sensitive_body = {
    properties = {
      adminPassword = var.admin_password
    }
  }
}

使用 sensitive_body_version 控制何时将仅写属性重新发送到 API（例如在轮换凭据时）。

资源替换的触发器

提供者 AzAPI 允许您配置资源替换的参数：

replace_triggers_external_values

如果值发生更改，则替换资源。 例如，如果要修改 SKU 或区域变量，将重新创建此资源：

resource "azapi_resource" "example" {
  name      = var.name
  type      = "Microsoft.Network/publicIPAddresses@2023-11-01"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example"
  body      = properties = {
    sku   = var.sku
    zones = var.zones
  }
  replace_triggers_external_values = [
    var.sku,
    var.zones,
  ]
}

此触发器适用于一组广泛的资源，例如，定义属性发生更改时的策略分配。

replace_triggers_refs

如果引用的值发生更改，则替换资源。 例如，如果修改了 SKU 名称或层，则会重新创建此资源：

resource "azapi_resource" "example" {
  type      = "Microsoft.Relay/namespaces@2021-11-01"
  parent_id = azurerm_resource_group.example.id
  name      = "xxx"
  location  = "westus"
  body = {
    properties = {
    }
    sku = {
      name = "Standard"
      tier = "Standard"
    }
  }

  replace_triggers_refs = ["sku"]
}

如果其他资源的 SKU 发生更改，则不会触发替换。

后续步骤

• 在 AzureRM 和 AzAPI Terraform 提供程序之间进行选择
• 了解 AzAPI 数据平面框架
• 使用 AzAPI 提供者部署第一个资源
• 使用 AzAPI 提供程序部署第一个更新资源
• 使用 AzAPI 提供器部署您第一个资源操作
• 使用 AzAPI 提供程序执行资源操作
• 使用 AzAPI 管理 Azure 数据平面资源
• 使用 AzAPI 提供程序列出 Azure 资源
• 启用预检验证
• 使用 AzAPI 提供程序函数
• Azure、AzureRM 和 AzAPI 之间的迁移路径
• 访问提供商注册表