Compartilhar via

Visão geral do provedor do AzAPI do Terraform

  • Artigo

O provedor do 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 de API, possibilitando usar a funcionalidade mais recente do Azure. O AzAPI é um provedor de primeira classe desenvolvido para ser usado sozinho ou em conjunto com o provedor do AzureRM.

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:

Nome do recurso Descrição
azapi_resource Usado para gerenciar de forma abrangente qualquer recurso (API) do Azure (plano de controle) com CRUD completo.
   Exemplos de casos de uso:
      Novo serviço de versão prévia
      Novo recurso adicionado ao serviço existente
      Recurso/serviço existente não coberto atualmente
azapi_update_resource Usado para gerenciar recursos ou partes de recursos que não têm CRUD completo
   Exemplos de casos de uso:
      Atualizar novas propriedades em um serviço existente
      Atualize o recurso filho pré-criado, como o registro SOA DNS.
azapi_resource_action Usado para executar uma operação única em um recurso sem gerenciar seu ciclo de vida
   Exemplos de casos de uso:
      Desligar uma máquina virtual
      Adicionar um segredo a um Key Vault
azapi_data_plane_resource Usado para gerenciar um subconjunto específico de recursos do plano de dados do Azure
   Exemplos de casos de uso:
      Contatos do certificado do KeyVault
      Bibliotecas de workspace do Synapse

Hierarquia de uso

No geral, o uso deve seguir estas etapas:

  1. É sempre recomendável começar executando o maior número possível de operações no 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 seguinte trecho de código configura um recurso que não existe atualmente no provedor do 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 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"
        }
      }
    }
  }
}

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.

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
  • Fidelidade 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
  • Extensão robusta do VS Code

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 AzAPI VS Code oferece uma experiência de criação rica com os seguintes benefícios:

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

Ferramenta de migração AzAPI2AzureRM

O provedor do AzureRM fornece a experiência do Terraform mais integrada para gerenciar recursos do Azure. Portanto, o uso recomendado dos provedores do AzAPI e do AzureRM é o seguinte:

  1. Enquanto o serviço ou recurso estiver em versão prévia, use o provedor do AzAPI.
  2. depois que o serviço for lançado oficialmente, use o provedor do AzureRM.

A ferramenta AzAPI2AzureRM tool foi desenvolvida para ajudar a migrar do provedor do AzAPI para o provedor do AzureRM.

AzAPI2AzureRM é uma ferramenta de código aberto que automatiza o processo de conversão de recursos AzAPI em recursos AzureRM.

O AzAPI2AzureRM tem dois modos: planejar e migrar:

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

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

Usar o provedor do AzAPI

  1. Instalar a extensão VS Code

  2. Adicione o provedor do AzAPI à configuração do Terraform.

    terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
    }
  }
}

provider "azapi" {
  # More information on the authentication methods supported by
  # the AzureRM Provider can be found here:
  # https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs

  # subscription_id = "..."
  # client_id       = "..."
  # client_secret   = "..."
  # tenant_id       = "..."
}

  3. Declare um ou mais recursos do AzAPI conforme mostrado no seguinte código de exemplo:

    resource "azapi_resource" "example" {
  name = "example"
  parent_id = data.azurerm_machine_learning_workspace.existing.id
  type = "Microsoft.MachineLearningServices/workspaces/computes@2021-07-01"

  location = "eastus"
  body = {
    properties = {
      computeType      = "ComputeInstance"
      disableLocalAuth = true
      properties = {
        vmSize = "STANDARD_NC6"
      }
    }
  }
}

Próximas etapas