Visão geral do provedor Terraform AzAPI

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

Benefícios de usar o provedor AzAPI

O provedor AzAPI apresenta os seguintes benefícios:

• Suporta todos os serviços de plano de controlo do Azure:
  • Pré-visualizar serviços e funcionalidades
  • Todas as versões da API
• Fidelidade total do ficheiro de estado do Terraform
  • As propriedades e os valores são guardados no estado
• Sem dependência do Swagger
• Autenticação comum e consistente do Azure
• Validação pré-verificação integrada
• Controle granular sobre o desenvolvimento da infraestrutura
• Extensão robusta do VS Code

Recursos

Para permitir que você gerencie todos os recursos e recursos do Azure sem exigir atualizações, o provedor AzAPI inclui os seguintes recursos genéricos:

Hierarquia de uso

No geral, o uso deve seguir estas etapas:

1. É sempre recomendável começar pela realização do maior número possível de operações dentro de azapi_resource.
2. Se o tipo de recurso não existir em azapi_resource, mas se enquadrar num dos tipos suportados por azapi_data_plane_resource, utilize esse tipo.
3. Se o recurso já existir no AzureRM ou tiver uma propriedade que não pode ser acessada no azapi_resource, use azapi_update_resource para acessar essas propriedades específicas. Recursos que azapi_resource ou azapi_data_plane_resource não suportam não podem ser atualizados através deste recurso.
4. Se estiveres a tentar executar uma ação que não se baseia num recurso compatível com CRUD do Azure, azapi_resource_action é menos simples, mas azapi_update_resource é mais flexível.

Exemplos de configuração de recursos

O trecho de código a seguir configura um recurso que não existe atualmente no provedor 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"
    }
  }
}

O trecho de código a seguir 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 trecho de código a seguir 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 trecho de código a seguir configura um recurso que não existe atualmente no provedor AzureRM devido a ser provisionado 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 no snippet de código ocorrem durante a fase terraform plan devido à validação interna prévia 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
        ]
      }
    }
  }
}

Pré-verificação está oculta atrás de um sinalizador do fornecedor, mas ajudará a gerar erros na fase plan.

Fontes de dados

O provedor AzAPI suporta uma variedade de fontes de dados úteis:

Autenticação usando o provedor AzAPI

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

Experiência e ciclo de vida do fornecedor AzAPI

Esta seção descreve algumas ferramentas para ajudá-lo a usar o provedor AzAPI.

Extensão VS Code e Language Server

A extensão AzAPI VS Code fornece uma rica experiência de criação com os seguintes benefícios:

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

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:

• Plan exibe os recursos AzAPI que podem ser migrados.
• Migrar migra os recursos AzAPI para recursos do AzureRM nos arquivos HCL e no estado.

aztfmigrate garante após a migração que a configuração e o estado do Terraform estejam alinhados com o seu estado real. Você pode validar a atualização para o estado executando terraform plan depois de concluir a migração para ver que nada mudou.

Controles granulares sobre a infraestrutura

Um grande benefício do AzAPI é através de sua capacidade de ajustar sua configuração para corresponder aos padrões de design certos. Há várias maneiras de fazer isso:

Funções do provedor

AzAPI (v2.0 e mais recente) tem uma série de funções de provedor de :

Erros recuperáveis definidos pelo usuário com o bloco retry

O fornecedor de AzAPI pode lidar com erros conforme esperado através do bloco retry. Por exemplo, se um recurso pode ter um problema de tempo limite de criação, o seguinte bloco de código pode ajudar:

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

Gatilhos para substituição de recursos

O provedor de AzAPI permite configurar parâmetros para substituição de recursos:

replace_triggers_external_values

Substitui o recurso caso um valor seja modificado. Por exemplo, se as variáveis SKU ou zones 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,
  ]
}

Isso pode funcionar em um amplo conjunto de recursos, ou seja, uma atribuição de política quando as propriedades da definição mudam.

replace_triggers_refs

Substitui o recurso se o valor referenciado mudar. Por exemplo, se o nome ou a camada da SKU fosse modificada, esse recurso seria 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 acionaria uma substituição se o SKU de um recurso diferente fosse alterado.

Próximos passos

• Implante seu primeiro recurso com o provedor AzAPI
• Implante seu primeiro recurso de atualização com o provedor AzAPI
• Implante sua primeira ação de recurso com o provedor AzAPI
• Visite o registro do provedor