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

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

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

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

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

Ресурсы

Чтобы разрешить управлять всеми ресурсами и функциями 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, но более гибким.

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

Следующий фрагмент кода настраивает ресурс Azure непосредственно через API ARM:

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 см. в разделе Список ресурсов Azure с поставщиком AzAPI Terraform.

Прочитайте существующий ресурс с 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 определяет, какие свойства извлекаются из необработанного ответа API ARM и становятся доступными в атрибуте 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"
  }
}

Полное руководство см. в List Azure resources with the AzAPI Terraform provider.

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

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

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

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

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

Расширение VS Code Microsoft Terraform VS Code предоставляет широкий интерфейс разработки для поставщиков AzureRM и AzAPI, в том числе:

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

Расширение также поддерживает вставку как AzAPI (преобразует JSON ARM в блоки azapi_resource), экспорт ресурсов Azure с помощью aztfexport, миграцию AzureRM-to-AzAPI и предварительную проверку. Полное руководство см. в разделе Использование расширения MICROSOFT Terraform VS Code.

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

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

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

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

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

Пошаговое руководство см. в статье "Миграция ресурсов из AzAPI в AzureRM".

Импорт существующих ресурсов Azure

Чтобы перенести существующий ресурс Azure в управление AzAPI без повторного создания, используйте блок import (Terraform 1.5 и более поздней версии) или команду terraform import. Идентификатор ресурса должен включать версию 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 Экспорт для Terraform (aztfexport), который создает конфигурацию HCL и блоки импорта автоматически.

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

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

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

Блок поставщика AzAPI принимает несколько параметров, которые применяются глобально ко всем ресурсам в конфигурации:

Для получения полного списка параметров конфигурации поставщика см. схему поставщика AzAPI.

Пошаговое руководство по включению предварительной проверки см. в разделе "Включение предварительной проверки в поставщике AzAPI Terraform".

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

AzAPI версии 2.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 версии 2.x поддерживает аргументы только для записи (Terraform 1.11 и более поздние версии) с помощью атрибута sensitive_body на azapi_resource. Свойства, доступные только для записи, отправляются в API ARM, но не хранятся в состоянии 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
• Управляйте ресурсами плоскости данных Azure с помощью AzAPI
• Перечислите ресурсы Azure с поставщиком AzAPI
• Включить предварительную проверку
• Использование функций поставщика AzAPI
• Пути миграции между Azure, AzureRM и AzAPI
• Перейдите к реестру поставщиков