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:
- È 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 daazapi_data_plane_resource
, usarlo invece. - Se la risorsa esiste già in AzureRM o ha una proprietà a cui non è possibile accedere all'interno
azapi_resource
di , usareazapi_update_resource
per accedere a queste proprietà specifiche. Le risorse cheazapi_resource
oazapi_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 diazapi_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.
- 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 :
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.