Terraform AzAPI 提供程序概述

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

资源

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

资源名称 说明
azapi_resource 用于使用完整 CRUD 完全管理任何 Azure(控制平面)资源 (API)。
   示例用例:
      新预览服务
      现有服务中添加了新功能
      当前未涵盖的现有功能/服务
azapi_update_resource 用于管理没有完整 CRUD 的资源或部分资源
   示例用例:
      更新现有服务的新属性
      更新预先创建的子资源,例如 DNS SOA 记录。
azapi_resource_action 用于在不管理资源的生命周期的情况下对资源执行单个操作
   示例用例:
      关闭虚拟机
      向 Key Vault 添加机密
azapi_data_plane_resource 用于管理 Azure 数据平面资源的特定子集
   示例用例:
      KeyVault 证书联系人
      Synapse 工作区库

使用层次结构

总体而言,使用应遵循以下步骤:

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

资源配置示例

以下代码片段配置 AzureRM 提供程序中当前不存在的资源:

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"
        }
      }
    }
  }
}

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

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

使用 AzAPI 提供程序的好处

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

  • 支持所有 Azure 控制平面服务:
    • 预览服务和功能
    • 所有 API 版本
  • 完整 Terraform 状态文件保真度
    • 将属性和值保存到状态
  • 不依赖于 Swagger
  • 常见且一致的 Azure 身份验证
  • Robust VS Code 扩展

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

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

VS Code 扩展和语言服务器

AzAPI VS Code 扩展提供丰富的创作体验,具有以下优势:

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

AzAPI2AzureRM 迁移工具

AzureRM 提供程序为管理 Azure 资源提供了最集成的 Terraform 体验。 因此,AzAPI 和 AzureRM 提供程序的建议用法如下:

  1. 当服务或功能处于预览状态时,请使用 AzAPI 提供程序。
  2. 一旦服务正式发布,请使用 AzureRM 提供程序。

AzAPI2AzureRM 工具旨在帮助从 AzAPI 提供程序迁移到 AzureRM 提供程序。

AzAPI2AzureRM 是一种开源工具,可自动执行将 AzAPI 资源转换为 AzureRM 资源的过程。

AzAPI2AzureRM 有两种模式:规划和迁移:

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

AzAPI2AzureRM 确保在迁移后,Terraform 配置和状态与实际状态保持一致。 可以通过完成迁移后运行 terraform plan 来验证更新状态,以查看是否没有任何更改。

使用 AzAPI 提供程序

  1. 安装 VS Code 扩展

  2. 将 AzAPI 提供程序添加到 Terraform 配置。

    terraform {
      required_providers {
        azapi = {
          source  = "Azure/azapi"
        }
      }
    }
    
    provider "azapi" {
      # More information on the authentication methods supported by
      # the AzureRM Provider can be found here:
      # https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs
    
      # subscription_id = "..."
      # client_id       = "..."
      # client_secret   = "..."
      # tenant_id       = "..."
    }
    
  3. 声明一个或多个 AzAPI 资源,如以下示例代码所示:

    resource "azapi_resource" "example" {
      name = "example"
      parent_id = data.azurerm_machine_learning_workspace.existing.id
      type = "Microsoft.MachineLearningServices/workspaces/computes@2021-07-01"
    
      location = "eastus"
      body = {
        properties = {
          computeType      = "ComputeInstance"
          disableLocalAuth = true
          properties = {
            vmSize = "STANDARD_NC6"
          }
        }
      }
    }
    
    

后续步骤