Visão geral do provedor do AzAPI do Terraform

O provedor do AzAPI é uma camada fina sobre as APIs REST do Azure ARM. Ele permite que você gerencie qualquer tipo de recurso Azure usando qualquer versão da API, permitindo que você use a funcionalidade mais recente em Azure. O AzAPI é um provedor de primeira classe desenvolvido para ser usado sozinho ou em conjunto com o provedor do AzureRM.

Benefícios de usar o provedor do AzAPI

O provedor do AzAPI apresenta os seguintes benefícios:

• Oferece suporte a todos os serviços do plano de controle do Azure:
  • Serviços e recursos de pré-visualização
  • Todas as versões da API
• Integridade total do arquivo de estado do Terraform
  • Propriedades e valores são salvos no estado
• Nenhuma dependência do Swagger
• Autenticação comum e consistente do Azure
• Validação de pré-vôo interna
• Controle granular sobre o desenvolvimento de infraestrutura
• Extensão do Microsoft Terraform para Visual Studio Code

Recursos

Para permitir gerenciar todos os recursos e funcionalidades do Azure sem precisar de atualizações, o provedor do AzAPI inclui os seguintes recursos genéricos:

Para obter uma explicação detalhada de como a estrutura do plano de dados funciona e como parent_id é diferente dos recursos do plano de controle, consulte Understand the AzAPI data plane framework.

Hierarquia de uso

No geral, o uso deve seguir estas etapas:

1. Comece com a execução do maior número possível de operações dentro azapi_resource.
2. Se o tipo de recurso não existir no azapi_resource mas se enquadrar em um dos tipos suportados pelo azapi_data_plane_resource, use-o.
3. Se o recurso já existir no AzureRM ou tiver uma propriedade que não possa ser acessada no azapi_resource, use azapi_update_resource para acessar essas propriedades específicas. Os recursos que azapi_resource ou azapi_data_plane_resource não oferecem suporte, não poderão ser atualizados por meio desse recurso.
4. Se você estiver tentando executar uma ação que não seja baseada em um recurso compatível com o CRUD do Azure, azapi_resource_action será menos simples que azapi_update_resource, mas mais flexível.

Exemplos de configuração de recursos

O snippet de código a seguir configura um recurso de Azure diretamente por meio da API do 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"
    }
  }
}

O seguinte trecho de código configura uma propriedade de visualização para um recurso existente do 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
    }
  }
}

O seguinte trecho de código configura uma ação de recurso em um recurso existente do AzureRM:

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

O seguinte trecho de código configura um recurso que não existe atualmente no provedor do AzureRM devido a ser aprovisionado no plano de dados:

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

Exemplo de uso de pré-voo

Os seguintes erros de trecho de código ocorrem durante terraform plan devido à pré-validação interna da 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
        ]
      }
    }
  }
}

Quando habilitado, o preflight detecta erros de configuração durante terraform plan, em vez de durante a aplicação.

Fontes de dados

O provedor AzAPI dá suporte a várias fontes de dados úteis:

Para obter um exemplo prático usando azapi_resource_list com filtragem JMESPath, consulte Listar os recursos do Azure com o provedor Terraform do AzAPI.

Ler um recurso existente com a fonte de dados azapi_resource

A fonte de dados azapi_resource lê o estado atual de qualquer recurso de Azure e expõe suas propriedades por meio do atributo output. Use-o quando precisar de uma propriedade que o provedor do AzureRM não exponha:

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
}

Usar response_export_values e JMESPath

response_export_values controla quais propriedades são extraídas da resposta bruta da API ARM e disponibilizadas no output atributo. Ele aceita uma lista ou um mapa:

• Lista: especifique caminhos de propriedade JSON a serem extraídos. Use ["*"] para exportar o corpo completo da resposta.
• Mapa: use expressões JMESPath para filtrar e remodelar a resposta. A chave é o nome do campo de saída; o valor é a consulta JMESPath.

O formulário de mapa é preferencial para respostas de lista e casos em que você precisa transformar a saída:

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

Para obter um passo a passo completo, consulte Listar recursos Azure com o provedor Terraform da AzAPI.

Autenticação usando o provedor do AzAPI

O provedor do AzAPI habilita os mesmos métodos de autenticação que o provedor do AzureRM. Para obter mais informações sobre as opções de autenticação, consulte Autenticar o Terraform no Azure.

Experiência e ciclo de vida do provedor do AzAPI

Esta seção descreve algumas ferramentas para ajudar você a usar o provedor do AzAPI.

Extensão do VS Code e Servidor de Linguagem

A extensão Microsoft Terraform VS Code fornece uma experiência de criação avançada para os provedores AzureRM e AzAPI, incluindo:

• Liste todos os tipos de recursos disponíveis e versões de API.
• Preenchimento automático das propriedades e valores permitidos para qualquer recurso.
• Mostre dicas ao passar o mouse sobre uma propriedade.
• Validação da sintaxe
• Preenchimento automático com exemplos de código.

A extensão também dá suporte a colar como AzAPI (converte ARM JSON em blocos azapi_resource), a exportação de recursos do Azure por meio de aztfexport, migração do AzureRM para AzAPI e validação pré-voo. Para obter um guia completo, consulte Use a extensão Microsoft Terraform VS Code.

aztfmigrate ferramenta de migração

A ferramenta aztfmigrate foi projetada para ajudar a migrar recursos existentes entre os provedores AzAPI e AzureRM.

aztfmigrate tem dois modos: planejar e migrar:

• O modo Planejar exibe os recursos do AzAPI que podem ser migrados.
• Migrar migra os recursos do AzAPI para recursos do AzureRM nos arquivos HCL e no arquivo de estado.

aztfmigrate garante, após a migração, que a configuração e o estado do Terraform estejam alinhados com seu estado real. Você pode validar a atualização para o estado executando terraform plan depois de concluir a migração para confirmar se nenhuma alteração ocorreu.

Para obter um passo a passo, consulte Migrar recursos da AzAPI para o AzureRM.

Importar recursos de Azure existentes

Para colocar um recurso de Azure existente no gerenciamento de AzAPI sem criá-lo novamente, use o bloco import (Terraform 1.5 e posterior) ou o comando terraform import. A ID do recurso deve incluir a versão da API como um parâmetro de consulta:

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

Para importar vários recursos ao mesmo tempo da infraestrutura Azure existente, use Azure Export for Terraform (aztfexport), que gera automaticamente a configuração de HCL e os blocos de importação.

Controles granulares sobre a infraestrutura

Um dos principais benefícios da AzAPI é por meio de sua capacidade de ajustar sua configuração para corresponder aos padrões de design corretos. Há várias maneiras de fazer isso:

Opções de configuração do provedor

O bloco do provedor AzAPI aceita várias configurações que se aplicam globalmente em todos os recursos na configuração:

Para obter uma lista completa das opções de configuração do provedor, consulte o esquema de provedor AzAPI.

Para obter um passo a passo da habilitação do pré-vôo, consulte Habilitar a validação de pré-vôo no provedor Terraform do AzAPI.

Funções de provedor

AzAPI v2.0 e posterior inclui várias funções de provedor:

Erros repetíveis definidos pelo usuário com o bloco retry

O provedor de AzAPI lida com os erros esperados por meio do bloco retry. Por exemplo, use a seguinte configuração para tentar novamente quando um recurso encontrar um tempo limite de criação:

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

O retry bloco aceita estes atributos:

Combine retry com o bloco timeouts para definir um limite máximo para a duração total de tentativas.

timeouts {
  create = "10m"
}

Recursos efêmeros e propriedades apenas para gravação

O AzAPI v2.x dá suporte a argumentos somente gravação (Terraform 1.11 e posterior) por meio do sensitive_body atributo em azapi_resource. As propriedades de somente escrita são enviadas para a ARM API, mas não são armazenadas no estado do Terraform, o que é útil para segredos e credenciais.

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

Use sensitive_body_version para controlar quando as propriedades somente gravação são reenviadas para a API (por exemplo, ao alterar credenciais).

Gatilhos para substituição de recursos

O AzAPI provedor permite que você configure parâmetros para substituição de recursos:

replace_triggers_external_values

Substituirá o recurso caso algum valor seja alterado. Por exemplo, se as variáveis de SKU ou zonas fossem modificadas, esse recurso seria recriado:

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,
  ]
}

Esse gatilho funciona em um amplo conjunto de recursos, por exemplo, uma atribuição de política quando as propriedades da definição são alteradas.

replace_triggers_refs

Substituirá o recurso se o valor referenciado mudar. Por exemplo, se o nome ou a camada de SKU tiver sido modificado, esse recurso será recriado:

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

Isso não dispararia uma substituição se a SKU de um recurso diferente fosse alterada.

Próximas etapas

• Escolha entre os provedores do Terraform, AzureRM e AzAPI
• Entender a estrutura do plano de dados do AzAPI
• Implantar seu primeiro recurso com o provedor do AzAPI
• Implantar seu primeiro recurso de atualização com o provedor do AzAPI
• Implantar sua primeira ação de recursos com o provedor AzAPI
• Executar ações de recurso com o provedor de AzAPI
• Gerencie recursos do plano de dados do Azure com a AzAPI
• Listar recursos Azure com o provedor AzAPI
• Habilitar a validação de pré-vôo
• Usar funções de provedor AzAPI
• Caminhos de migração entre Azure, AzureRM e AzAPI
• Visite o registro do provedor