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:

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:

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.
• 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 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 :

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

• Effettua il deployment della prima risorsa con il provider AzAPI
• Distribuire la prima risorsa di aggiornamento con il provider AzAPI
• Esegui la tua prima azione su una risorsa con il provider AzAPI
• Visitare il registro del provider