Panoramica del provider AzAPI terraform

Articolo
08/16/2024

Il provider AzAPI è un livello sottile sopra le API REST arm di Azure. Consente di gestire qualsiasi tipo di risorsa di Azure usando qualsiasi versione dell'API, consentendo di usare le funzionalità più recenti all'interno di Azure. AzAPI è un provider di prima classe progettato per essere usato autonomamente o in combinazione con il provider AzureRM.

Risorse

Per consentire di gestire tutte le risorse e le funzionalità di Azure senza richiedere aggiornamenti, il provider AzAPI include le risorse generiche seguenti:

Nome della risorsa	Descrizione
azapi_resource	Usato per gestire completamente qualsiasi risorsa di Azure (piano di controllo) con CRUD completo. Casi d'uso di esempio: Nuovo servizio di anteprima Nuova funzionalità aggiunta al servizio esistente Funzionalità/servizio esistenti non attualmente coperti
azapi_update_resource	Usato per gestire risorse o parti di risorse che non dispongono di CRUD completo Casi d'uso di esempio: Aggiornare le nuove proprietà in un servizio esistente Aggiornare la risorsa figlio creata in modo preliminare, ad esempio il record SOA DNS.
azapi_resource_action	Usato per eseguire una singola operazione su una risorsa senza gestirlo Casi d'uso di esempio: Arrestare una macchina virtuale Aggiungere un segreto a un insieme di credenziali delle chiavi
azapi_data_plane_resource	Usato per gestire un subset specifico di risorse del piano dati di Azure Casi d'uso di esempio: Contatti certificato KeyVault Librerie dell'area di lavoro di Synapse

Gerarchia di utilizzo

In generale, l'utilizzo deve seguire questa procedura:

È sempre consigliabile iniziare con l'esecuzione del maggior numero possibile di operazioni all'interno di azapi_resource.
Se il tipo di risorsa non esiste all'interno azapi_resource di ma rientra in uno dei tipi supportati da azapi_data_plane_resource, usarlo invece.
Se la risorsa esiste già in AzureRM o ha una proprietà a cui non è possibile accedere all'interno azapi_resourcedi , usare azapi_update_resource per accedere a queste proprietà specifiche. Le risorse che azapi_resource o azapi_data_plane_resource non supportano non possono essere aggiornate tramite questa risorsa.
Se si sta tentando di eseguire un'azione non basata su una risorsa crud di Azure, azapi_resource_action è meno semplice ma azapi_update_resource più flessibile.

Esempi di configurazione delle risorse

Il frammento di codice seguente configura una risorsa che non esiste attualmente nel provider 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"
    }
  }
}

Il frammento di codice seguente configura una proprietà di anteprima per una risorsa esistente da AzureRM:

resource "azapi_update_resource" "test" {
  type        = "Microsoft.ContainerRegistry/registries@2020-11-01-preview"
  resource_id = azurerm_container_registry.acr.id

  body = jsonencode{
    properties = {
      anonymousPullEnabled = var.bool_anonymous_pull
    }
  }
}

Il frammento di codice seguente configura un'azione della risorsa in una risorsa AzureRM esistente:

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

Il frammento di codice seguente configura una risorsa che non esiste attualmente nel provider AzureRM a causa del provisioning nel piano dati:

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

Autenticazione con il provider AzAPI

Il provider AzAPI abilita gli stessi metodi di autenticazione del provider AzureRM. Per altre informazioni sulle opzioni di autenticazione, vedere Autenticare Terraform in Azure.

Vantaggi dell'uso del provider AzAPI

Il provider AzAPI offre i vantaggi seguenti:

Supporta tutti i servizi del piano di controllo di Azure:
- Funzionalità e servizi di anteprima
- Tutte le versioni dell'API
Fedeltà completa dei file di stato terraform
- Le proprietà e i valori vengono salvati in stato
Nessuna dipendenza da Swagger
Autenticazione di Azure comune e coerente
Estensione di VS Code affidabile

Esperienza e ciclo di vita del provider AzAPI

Questa sezione descrive alcuni strumenti che consentono di usare il provider AzAPI.

Estensione vs Code e server di linguaggio

L'estensione AzAPI VS Code offre un'esperienza di creazione avanzata con i vantaggi seguenti:

Elencare tutti i tipi di risorse disponibili e le versioni dell'API.
Completamento automatico delle proprietà e dei valori consentiti per qualsiasi risorsa.
Mostra suggerimenti quando si passa il puntatore del mouse su una proprietà.
Convalida della sintassi
Completamento automatico con esempi di codice.

Strumento di migrazione AzAPI2AzureRM

Il provider AzureRM offre l'esperienza Terraform più integrata per la gestione delle risorse di Azure. Di conseguenza, l'utilizzo consigliato dei provider AzAPI e AzureRM è il seguente:

Mentre il servizio o la funzionalità è in anteprima, usare il provider AzAPI.
dopo il rilascio ufficiale del servizio, usare il provider AzureRM.

Lo strumento AzAPI2AzureRM è progettato per facilitare la migrazione dal provider AzAPI al provider AzureRM.

AzAPI2AzureRM è uno strumento open source che automatizza il processo di conversione delle risorse AzAPI in risorse di AzureRM.

AzAPI2AzureRM ha due modalità: pianificare ed eseguire la migrazione:

Il piano visualizza le risorse AzAPI di cui è possibile eseguire la migrazione.
Esegue la migrazione delle risorse AzAPI alle risorse di AzureRM sia nei file HCL che nello stato.

AzAPI2AzureRM garantisce che dopo la migrazione la configurazione e lo stato di Terraform siano allineati allo stato effettivo. È possibile convalidare l'aggiornamento allo stato eseguendo terraform plan dopo aver completato la migrazione per verificare che non sia stato modificato nulla.

Uso del provider AzAPI

Installare l'estensione VS Code

Aggiungere il provider AzAPI alla configurazione di 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       = "..."
}

Dichiarare una o più risorse AzAPI come illustrato nel codice di esempio seguente:

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 = jsonencode({
    properties = {
      computeType      = "ComputeInstance"
      disableLocalAuth = true
      properties = {
        vmSize = "STANDARD_NC6"
      }
    }
  })
}

Condividi tramite