Usar funções de provedor no provedor Terraform do AzAPI

O Terraform permite a definição, a visualização e a implantação da infraestrutura de nuvem. Usando o Terraform, você cria arquivos de configuração usando a sintaxe HCL. A sintaxe da HCL permite que você especifique o provedor de nuvem, como o Azure, e os elementos que compõem sua infraestrutura de nuvem. Depois de criar os arquivos de configuração, você cria um plano de execução que permite visualizar as alterações de infraestrutura antes de serem implantadas. Depois de verificar as alterações, você aplica o plano de execução para implantar a infraestrutura.

O AzAPI v2.0 e posterior inclui um conjunto de funções provider para construir e analisar IDs de recursos Azure. As funções do provedor são executadas durante a elaboração do plano dentro da configuração do Terraform e não requerem consultar uma fonte de dados ou realizar uma chamada de rede. Eles reduzem a complexidade do código quando sua configuração precisa construir ou decompor IDs de recursos.

Funções de provedor disponíveis

Pré-requisitos

• Assinatura do Azure: Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• Configurar o Terraform: se você ainda não fez isso, configure o Terraform usando uma das seguintes opções:

  • Configurar o Terraform no Azure Cloud Shell com o Bash
  • Configurar o Terraform no Azure Cloud Shell com o PowerShell
  • Configure Terraform em Windows com Bash
  • Configurar o Terraform no Windows com o PowerShell

Verifique se a configuração declara a AzAPI v2.0 ou posterior e o Terraform 1.8 ou posterior:

terraform {
  required_version = ">= 1.8"
  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {}
}

provider "azapi" {}

Interpretar um identificador de recurso com parse_resource_id

Use parse_resource_id para decompor uma ID de recurso Azure existente em seus componentes individuais. A função é útil quando você precisa da ID da assinatura, do nome do grupo de recursos ou do nome do recurso de um recurso gerenciado em outro lugar em sua configuração ou passado como uma variável.

locals {
  storage_id_parts = provider::azapi::parse_resource_id(
    "Microsoft.Storage/storageAccounts",
    azurerm_storage_account.example.id
  )
}

output "subscription_id" {
  value = local.storage_id_parts.subscription_id
}

output "resource_group_name" {
  value = local.storage_id_parts.resource_group_name
}

output "storage_account_name" {
  value = local.storage_id_parts.name
}

A função retorna um objeto com estes campos:

• id — a ID completa do recurso
• name — o nome do recurso
• parent_id — o ID do recurso pai
• parts — um mapa de todos os segmentos de ID de recurso
• provider_namespace (por exemplo, Microsoft.Storage)
• resource_group_name
• resource_group_id
• subscription_id
• type (por exemplo, Microsoft.Storage/storageAccounts)

Construa uma ID com escopo de grupo de recursos usando resource_group_resource_id

Use resource_group_resource_id quando precisar referenciar uma ID de recurso para um recurso que você não gerencia no Terraform (por exemplo, um recurso existente passado como uma variável) ou quando quiser construir uma ID previsível antes da criação do recurso.

variable "subscription_id" {
  type = string
}

variable "existing_resource_group" {
  type = string
}

variable "existing_storage_account" {
  type = string
}

locals {
  storage_account_id = provider::azapi::resource_group_resource_id(
    var.subscription_id,
    var.existing_resource_group,
    "Microsoft.Storage/storageAccounts",
    [var.existing_storage_account]
  )
}

# Reference the pre-existing storage account without a data source lookup
resource "azapi_resource_action" "regenerate_key" {
  type        = "Microsoft.Storage/storageAccounts@2023-01-01"
  resource_id = local.storage_account_id
  action      = "regenerateKey"
  method      = "POST"

  body = {
    keyName = "key1"
  }
}

O parâmetro de nomes de recurso aceita uma lista para dar suporte a tipos de recursos aninhados. Por exemplo, para construir uma ID de sub-rede:

locals {
  subnet_id = provider::azapi::resource_group_resource_id(
    var.subscription_id,
    var.resource_group_name,
    "Microsoft.Network/virtualNetworks/subnets",
    [var.vnet_name, var.subnet_name]
  )
}

Construir uma ID com escopo de assinatura com subscription_resource_id

Use subscription_resource_id para recursos com escopo no nível da assinatura, como grupos de recursos ou atribuições de política:

locals {
  resource_group_id = provider::azapi::subscription_resource_id(
    var.subscription_id,
    "Microsoft.Resources/resourceGroups",
    [var.resource_group_name]
  )
}

Criar uma ID com escopo no grupo de gerenciamento com management_group_resource_id

Use management_group_resource_id para recursos com escopo de grupo de gerenciamento, como atribuições de política e atribuições de função:

locals {
  mg_policy_id = provider::azapi::management_group_resource_id(
    var.management_group_name,
    "Microsoft.Authorization/policyAssignments",
    [var.policy_assignment_name]
  )
}

Construir um ID de recurso de extensão com extension_resource_id

Use extension_resource_id para recursos de extensão anexados a outro recurso, como bloqueios ou atribuições de função em um recurso específico:

locals {
  lock_id = provider::azapi::extension_resource_id(
    azurerm_storage_account.example.id,
    "Microsoft.Authorization/locks",
    [var.lock_name]
  )
}

Criar uma ID de recurso com build_resource_id

Use build_resource_id quando uma ID de recurso pai determinar o escopo e você não precisar especificar a assinatura ou o grupo de recursos separadamente. Essa função infere o escopo a partir do ID pai:

locals {
  subnet_id = provider::azapi::build_resource_id(
    azurerm_virtual_network.example.id,
    "Microsoft.Network/virtualNetworks/subnets",
    var.subnet_name
  )
}

Comparar com abordagens de fonte de dados

As funções de provedor são preferíveis em vez de fontes de dados para construção e análise de ID porque:

• Executa inteiramente em tempo de planejamento sem chamadas de rede.
• Não adicione recursos ao estado do Terraform.
• São determinísticos e não exigem depends_on ordenamento.

Utilize azapi_resource como fonte de dados quando precisar ler as propriedades ao vivo de um recurso, não apenas construir ou processar seu ID.

Próximas Etapas