Обзор поставщика Terraform AzAPI

Статья
03/09/2025

Поставщик AzAPI — это тонкий слой поверх REST API Azure ARM. Он позволяет управлять любым типом ресурсов Azure с помощью любой версии API, что позволяет использовать последние функциональные возможности в Azure. AzAPI — это поставщик первого класса, предназначенный для использования самостоятельно или в тандеме с поставщиком AzureRM.

Преимущества использования поставщика AzAPI

Поставщик AzAPI имеет следующие преимущества:

Поддерживает все службы контрольной плоскости Azure:
- Предварительные версии служб и функций
- Все версии API
Полная целостность файла состояния Terraform
- Свойства и значения сохраняются в состоянии
Нет зависимости от Swagger
Общая и согласованная проверка подлинности Azure
Встроенная предварительная проверка готовности
Детальный контроль над разработкой инфраструктуры
Надежное расширение VS Code

Ресурсы

Чтобы разрешить управлять всеми ресурсами и функциями Azure без необходимости обновления, поставщик AzAPI включает следующие универсальные ресурсы:

Имя ресурса	Описание
`azapi_resource`	Используется для полного управления любым ресурсом Azure контрольной плоскости (API) с полным CRUD. Примеры вариантов использования: Новая предварительная версия службы Новая функция, добавленная в существующую службу Существующие функции или службы, которые в настоящее время не рассматриваются
`azapi_update_resource`	Используется для управления ресурсами или частями ресурсов, которые не имеют полного CRUD Примеры вариантов использования: Обновление новых свойств существующей службы Обновите предварительно созданный дочерний ресурс, например запись SOA DNS.
`azapi_resource_action`	Используется для выполнения одной операции с ресурсом без управления жизненным циклом ресурса. Примеры вариантов использования: Завершение работы виртуальной машины Добавление секрета в Key Vault
`azapi_data_plane_resource`	Используется для управления определенным подмножеством ресурсов плоскости данных Azure Примеры вариантов использования: Контакты сертификатов KeyVault Библиотеки рабочей области Synapse

Иерархия использования

В целом процесс использования должен следовать следующим шагам.

Всегда рекомендуется начать с выполнения как можно больше операций в пределах azapi_resource.
Если тип ресурса не существует в пределах azapi_resource , но не соответствует одному из типов, поддерживаемых azapi_data_plane_resource, используйте это.
Если ресурс уже существует в AzureRM или имеет свойство, к которому не удается получить доступ azapi_resource, используйте azapi_update_resource для доступа к этим конкретным свойствам. Ресурсы, которые azapi_resource или azapi_data_plane_resource не поддерживаются, не могут быть обновлены с помощью этого ресурса.
Если вы пытаетесь выполнить действие, которое не основано на ресурсе 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"
        }
      }
    }
  }
}

Пример использования предварительной проверки

Ошибки в следующем фрагменте кода возникают во время этапа 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
        ]
      }
    }
  }
}

Предварительная проверка скрыта за флагом поставщика, но поможет выявлять ошибки на этапе plan.

Источники данных

Поставщик AzAPI поддерживает различные полезные источники данных:

Имя источника данных	Описание
`azapi_resource`	Используется для чтения сведений из любого ресурса Azure (уровня управления) (API). Примеры вариантов использования: Новая предварительная версия службы Новая функция, добавленная в существующую службу Существующие функции или службы, которые в настоящее время не рассматриваются
`azapi_client_config`	Доступ к данным клиента, таким как идентификатор подписки и идентификатор клиента.
`azapi_resource_action`	Используется для выполнения одной операции чтения в ресурсе без управления жизненным циклом. Примеры вариантов использования: Список ключей Состояние чтения виртуальной машины
`azapi_data_plane_resource`	Используется для доступа к определенному подмножеству ресурсов плоскости данных Azure Примеры вариантов использования: Контакты сертификатов KeyVault Библиотеки рабочей области Synapse
`azapi_resource_id`	Доступ к идентификатору ресурса с возможностью вывода таких сведений, как идентификатор подписки, родительский идентификатор, имя группы ресурсов и имя ресурса.
`azapi_resource_list`	Перечислите все ресурсы, связанные с указанным идентификатором родительского ресурса. Примеры вариантов использования: Ресурсы в подписке или группе ресурсов Подсети в виртуальной сети

Проверка подлинности с помощью поставщика AzAPI

Поставщик AzAPI включает те же методы проверки подлинности, что и поставщик AzureRM. Дополнительные сведения о параметрах проверки подлинности см. в статье "Аутентификация Terraform" в Azure.

Опыт и жизненный цикл поставщика AzAPI

В этом разделе описаны некоторые инструменты для использования поставщика AzAPI.

Расширение VS Code и сервер языка

Расширение AZAPI VS Code обеспечивает широкий опыт разработки со следующими преимуществами:

Список всех доступных типов ресурсов и версий API.
Автоматическое завершение допустимых свойств и значений для любого ресурса.
Отображение подсказок при наведении указателя мыши на свойство.
Проверка синтаксиса
Автозавершение с примерами кода.

средство миграции `aztfmigrate`

Средство aztfmigrate предназначено для переноса существующих ресурсов между поставщиками AzAPI и AzureRM.

aztfmigrate имеет два режима: планирование и миграция:

План отображает ресурсы AzAPI, которые можно перенести.
Миграция переносит ресурсы AzAPI в ресурсы AzureRM как в файлах HCL, так и в состоянии.

aztfmigrate гарантирует, что после миграции конфигурация Terraform и состояние соответствуют фактическому состоянию. Обновление можно проверить, выполнив terraform plan после завершения миграции, чтобы увидеть, что ничего не изменилось.

Детализированное управление инфраструктурой

Одним из основных преимуществ AzAPI является возможность точно настроить конфигурацию, чтобы соответствовать правильным шаблонам дизайна. Это можно сделать несколькими способами.

Функции поставщика

AzAPI (версии 2.0 и более поздней версии) имеет множество функций поставщика :

Имя функции	Описание
`build_resource_id`	Создает идентификатор ресурса Azure с учетом родительского идентификатора, типа ресурса и имени ресурса. Полезно для создания идентификаторов ресурсов верхнего уровня и вложенных ресурсов в рамках определённой области.
`extension_resource_id`	Создает идентификатор ресурса расширения Azure с учетом базового идентификатора ресурса, типа ресурса и дополнительных имен ресурсов.
`management_group_resource_id`	Создает идентификатор ресурса области группы управления Azure с учетом имени группы управления, типа ресурса и имен ресурсов.
`parse_resource_id`	Эта функция принимает идентификатор ресурса Azure и тип ресурса, а затем анализирует идентификатор на отдельные компоненты, такие как идентификатор подписки, имя группы ресурсов, пространство имен поставщика и другие части.
`resource_group_resource_id`	Создает идентификатор ресурса области группы ресурсов Azure с идентификатором подписки, именем группы ресурсов, типом ресурсов и именами ресурсов.
`subscription_resource_id`	Создает идентификатор ресурса области подписки Azure с идентификатором подписки, типом ресурсов и именами ресурсов.
`tenant_resource_id`	Создает идентификатор ресурса области клиента Azure с учетом типа ресурса и имен ресурсов.

Ошибки, определяемые пользователем и повторяемые с блоком `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"
}

Триггеры для замены ресурсов

Поставщик 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 другого ресурса изменится.

Поделиться через

Обзор поставщика Terraform AzAPI

Преимущества использования поставщика AzAPI

Ресурсы

Иерархия использования

Примеры конфигурации ресурсов

Пример использования предварительной проверки

Источники данных

Проверка подлинности с помощью поставщика AzAPI

Опыт и жизненный цикл поставщика AzAPI

Расширение VS Code и сервер языка

средство миграции `aztfmigrate`

Детализированное управление инфраструктурой

Функции поставщика

Ошибки, определяемые пользователем и повторяемые с блоком `retry`

Триггеры для замены ресурсов

`replace_triggers_external_values`

`replace_triggers_refs`

Следующие шаги

Обратная связь

Дополнительные ресурсы

Поделиться через

Обзор поставщика Terraform AzAPI

Преимущества использования поставщика AzAPI

Ресурсы

Иерархия использования

Примеры конфигурации ресурсов

Пример использования предварительной проверки

Источники данных

Проверка подлинности с помощью поставщика AzAPI

Опыт и жизненный цикл поставщика AzAPI

Расширение VS Code и сервер языка

средство миграции aztfmigrate

Детализированное управление инфраструктурой

Функции поставщика

Ошибки, определяемые пользователем и повторяемые с блоком retry

Триггеры для замены ресурсов

replace_triggers_external_values

replace_triggers_refs

Следующие шаги

Обратная связь

Дополнительные ресурсы

средство миграции `aztfmigrate`

Ошибки, определяемые пользователем и повторяемые с блоком `retry`

`replace_triggers_external_values`

`replace_triggers_refs`