Condividi tramite


Panoramica del provider AzAPI Terraform

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.

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 nello stato
  • Nessuna dipendenza da Swagger
  • Autenticazione di Azure comune e coerente
  • Convalida integrata prima del volo
  • Controllo granulare sullo sviluppo dell'infrastruttura
  • Estensione di VS Code affidabile

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 Utilizzato per gestire completamente qualsiasi risorsa di Azure (API del piano di controllo) con operazioni CRUD complete.
   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 proprietà nuove su 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:
      Spegnere una macchina virtuale
      Aggiungere un segreto a un Key Vault
azapi_data_plane_resource Usato per gestire un subset specifico di risorse del piano dati di Azure
   Casi d'uso di esempio:
      Contatti certificati KeyVault
      Librerie dell'area di lavoro di Synapse

Gerarchia di utilizzo

In generale, l'utilizzo deve seguire questa procedura:

  1. È sempre consigliabile iniziare con l'esecuzione del maggior numero possibile di operazioni all'interno di azapi_resource.
  2. 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.
  3. 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.
  4. Se si sta tentando di eseguire un'azione non basata su una risorsa CRUD di Azure, azapi_resource_action è meno semplice di azapi_update_resource ma è 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 = {
    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"
        }
      }
    }
  }
}

Esempio di utilizzo prevolo

Gli errori nel seguente frammento di codice si verificano durante terraform plan a causa della convalida predefinita preliminare di 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
        ]
      }
    }
  }
}

La verifica preliminare è nascosta dietro un indicatore del fornitore, ma consente di generare errori nella fase plan.

Origini dati

Il provider AzAPI supporta un'ampia gamma di origini dati utili:

Nome origine dei dati Descrizione
azapi_resource Usato per leggere le informazioni da qualsiasi risorsa di Azure (piano di controllo) (API).
   Casi d'uso di esempio:
      Nuovo servizio di anteprima
      Nuova funzionalità aggiunta al servizio esistente
      Funzionalità/servizio esistenti non attualmente coperti
azapi_client_config Accedere alle informazioni client, ad esempio ID sottoscrizione e ID tenant.
azapi_resource_action Usato per eseguire una singola operazione di lettura su una risorsa senza gestirne il ciclo di vita
   Casi d'uso di esempio:
      Elenca chiavi
      Stato di lettura della macchina virtuale
azapi_data_plane_resource Usato per accedere a un sottoinsieme specifico delle risorse del piano dati di Azure
   Casi d'uso di esempio:
      Contatti di certificati Key Vault
      Librerie dell'area di lavoro di Synapse
azapi_resource_id Accedere all'ID di una risorsa, con la possibilità di visualizzare informazioni come l'ID della sottoscrizione, l'ID del genitore, il nome del gruppo di risorse e il nome della risorsa.
azapi_resource_list Elenca tutte le risorse con un ID risorsa padre specificato.
   Casi d'uso di esempio:
      Risorse in una sottoscrizione/gruppo di risorse
      Sottoreti in una rete virtuale

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.

Esperienza e ciclo di vita del provider AzAPI

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

Estensione VS Code e Language Server

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. Elencare tutti i tipi di risorse disponibili
  • Completamento automatico delle proprietà e dei valori consentiti per qualsiasi risorsa. Elencare le proprietà consentite
  • Mostra suggerimenti quando si passa il puntatore del mouse su una proprietà. Mostra suggerimento quando si passa il puntatore del mouse su una proprietà
  • Convalida della sintassi Convalida della sintassi
  • Completamento automatico con esempi di codice. Completamento automatico con esempi di codice

strumento di migrazione aztfmigrate

Lo strumento aztfmigrate è progettato per facilitare la migrazione delle risorse esistenti tra i provider AzAPI e AzureRM.

aztfmigrate prevede due modalità: pianificare ed eseguire la migrazione:

  • Il piano visualizza le risorse AzAPI di cui è possibile eseguire la migrazione.
  • Le risorse AzAPI vengono migrate alle risorse AzureRM, sia nei file HCL sia nello stato.

aztfmigrate 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.

Controlli granulari sull'infrastruttura

Uno dei principali vantaggi di AzAPI è la possibilità di ottimizzare la configurazione in modo che corrisponda ai modelli di progettazione corretti. Esistono diversi modi in cui è possibile eseguire questa operazione:

Funzioni del provider

AzAPI (v2.0 e versioni successive) comprende una serie di funzioni del provider :

Nome funzione Descrizione
build_resource_id Costruisce un ID risorsa di Azure in base all'ID padre, al tipo di risorsa e al nome della risorsa.
Utile per la creazione di identificatori di risorse per le risorse di primo livello e annidate all'interno di un ambito specifico.
extension_resource_id Costruisce un ID risorsa dell'estensione di Azure in base all'ID risorsa di base, al tipo di risorsa e ai nomi di risorse aggiuntivi.
management_group_resource_id Costruisce un ID risorsa dell'ambito del gruppo di gestione di Azure in base al nome del gruppo di gestione, al tipo di risorsa e ai nomi delle risorse.
parse_resource_id Questa funzione accetta un ID risorsa di Azure e un tipo di risorsa e analizza l'ID nei singoli componenti, ad esempio ID della sottoscrizione, nome del gruppo di risorse, spazio dei nomi del fornitore e altre parti.
resource_group_resource_id Costruisce un ID risorsa di ambito del gruppo di risorse di Azure in base all'ID sottoscrizione, al nome del gruppo di risorse, al tipo di risorsa e ai nomi delle risorse.
subscription_resource_id Costruisce un ID risorsa dell'ambito della sottoscrizione di Azure in base all'ID sottoscrizione, al tipo di risorsa e ai nomi delle risorse.
tenant_resource_id Costruisce un ID risorsa dell'ambito del tenant di Azure in base al tipo di risorsa e ai nomi delle risorse.

Errori ritentabili definiti dall'utente con il blocco di retry

Il provider di AzAPI può riepilogare gli errori quando previsto tramite il blocco retry. Ad esempio, se una risorsa può incontrare un problema di timeout nella creazione, il blocco di codice seguente può risultare utile.

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

Trigger per la sostituzione delle risorse

Il provider di AzAPI consente di configurare i parametri per la sostituzione delle risorse:

replace_triggers_external_values

Sostituisce la risorsa se viene modificato un valore. Ad esempio, se le variabili sku o zone devono essere modificate, questa risorsa verrà ricreata:

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

Questa operazione può essere eseguita in un ampio set di risorse, ad esempio un'assegnazione di criteri quando cambiano le proprietà della definizione.

replace_triggers_refs

Sostituisce la risorsa se il valore a cui si fa riferimento cambia. Ad esempio, se il nome o il livello sku è stato modificato, questa risorsa verrà ricreata:

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

In questo modo non verrà attivata una sostituzione se lo SKU di una risorsa diversa dovesse cambiare.

Passaggi successivi