Översikt över Terraform AzAPI-providern
AzAPI-providern är ett tunt lager ovanpå Azure ARM REST-API:erna. Det gör att du kan hantera alla Azure-resurstyper med valfri API-version, så att du kan använda de senaste funktionerna i Azure. AzAPI är en förstklassig leverantör som är utformad för att användas på egen hand eller tillsammans med AzureRM-providern.
Fördelar med att använda AzAPI-providern
AzAPI-providern har följande fördelar:
- Stöder alla Azure-kontrollplanstjänster:
- Förhandsgranska tjänster och funktioner
- Alla API-versioner
- Fullständig noggrannhet för Terraform-tillståndsfilen
- Egenskaper och värden sparas i tillståndet
- Inget beroende av Swagger
- Vanlig och konsekvent Azure-autentisering
- Inbyggd preflight-validering
- Detaljerad kontroll över infrastrukturutveckling
- Robust VS Code-tillägg
Resurser
För att du ska kunna hantera alla Azure-resurser och funktioner utan att kräva uppdateringar innehåller AzAPI-providern följande allmänna resurser:
Resursnamn | beskrivning |
---|---|
azapi_resource |
Används för att helt och hållet hantera alla Azure-resurser inom kontrollplanen (API) med fullständig CRUD. Exempel på användningsfall: Ny förhandsversionstjänst Ny funktion har lagts till i befintlig tjänst Befintlig funktion/tjänst omfattas inte för närvarande |
azapi_update_resource |
Används för att hantera resurser eller delar av resurser som inte har fullständig CRUD Exempel på användningsfall: Uppdatera nya egenskaper för en befintlig tjänst Uppdatera förskapad delresurs – till exempel DNS SOA-post. |
azapi_resource_action |
Används för att utföra en enda åtgärd på en resurs utan att hantera livscykeln för den Exempel på användningsfall: Stäng av en virtuell dator Lägga till en hemlighet i ett Key Vault |
azapi_data_plane_resource |
Används för att hantera en specifik delmängd av Azure-dataplansresurser Exempel på användningsfall: KeyVault-certifikatkontakter Synapse-arbetsytebibliotek |
Användningshierarki
Sammantaget bör användningen följa dessa steg:
- Vi rekommenderar alltid att du börjar med att utföra så många åtgärder som möjligt inom
azapi_resource
. - Om resurstypen inte finns inom
azapi_resource
men hamnar under någon av de typer som stöds avazapi_data_plane_resource
använder du den i stället. - Om resursen redan finns i AzureRM eller har en egenskap som inte kan nås inom
azapi_resource
använder duazapi_update_resource
för att komma åt dessa specifika egenskaper. Resurser somazapi_resource
ellerazapi_data_plane_resource
inte stöder kan inte uppdateras via den här resursen. - Om du försöker utföra en åtgärd som inte baseras på en Azure CRUD-vänlig resurs är
azapi_resource_action
det mindre enkelt änazapi_update_resource
men mer flexibelt.
Exempel på resurskonfiguration
Följande kodfragment konfigurerar en resurs som för närvarande inte finns i AzureRM-providern:
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"
}
}
}
Följande kodfragment konfigurerar en förhandsgranskningsegenskap för en befintlig resurs från 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
}
}
}
Följande kodfragment konfigurerar en resursåtgärd på en befintlig AzureRM-resurs:
resource "azapi_resource_action" "vm_shutdown" {
type = "Microsoft.Compute/virtualMachines@2023-07-01"
resource_id = azurerm_linux_virtual_machine.example.id
action = "powerOff”
}
Följande kodfragment konfigurerar en resurs som för närvarande inte finns i AzureRM-providern på grund av att den etableras på dataplanet:
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"
}
}
}
}
}
Exempel på preflight-användning
Följande kodfragmentfel under terraform plan
på grund av AzAPI:s inbyggda preflight-validering:
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
]
}
}
}
}
Preflight är dolt bakom en providerflagga men hjälper till att utlösa fel i plan
fas.
Datakällor
AzAPI-providern stöder en mängd användbara datakällor:
Namn på datakälla | beskrivning |
---|---|
azapi_resource |
Används för att läsa information från alla Azure-resurser (kontrollplan) (API). Exempel på användningsfall: Ny förhandsversionstjänst Ny funktion har lagts till i befintlig tjänst Befintlig funktion/tjänst omfattas inte för närvarande |
azapi_client_config |
Få åtkomst till klientinformation som prenumerations-ID och klient-ID. |
azapi_resource_action |
Används för att utföra en enda läsåtgärd på en resurs utan att hantera livscykeln för den Exempel på användningsfall: Lista nycklar Lässtatus för virtuell dator |
azapi_data_plane_resource |
Används för att komma åt en specifik delmängd av Azure-dataplansresurser Exempel på användningsfall: KeyVault-certifikatkontakter Synapse-arbetsytebibliotek |
azapi_resource_id |
Få åtkomst till resursens resurs-ID med möjlighet att mata ut information som prenumerations-ID, överordnat ID, resursgruppsnamn och resursnamn. |
azapi_resource_list |
Visa en lista över alla resurser under ett angivet överordnat resurs-ID. Exempel på användningsfall: Resurser under en prenumeration eller resursgrupp Undernät under ett virtuellt nätverk |
Autentisering med AzAPI-providern
AzAPI-providern aktiverar samma autentiseringsmetoder som AzureRM-providern. Mer information om autentiseringsalternativ finns i Autentisera Terraform till Azure.
Erfarenhet och livscykel för AzAPI-providern
I det här avsnittet beskrivs några verktyg som hjälper dig att använda AzAPI-providern.
VS Code-tillägget och språkservern
Tillägget AzAPI VS Code ger en omfattande redigeringsupplevelse med följande fördelar:
- Visa en lista över alla tillgängliga resurstyper och API-versioner.
- Automatisk slutförande av tillåtna egenskaper och värden för alla resurser.
- Visa tips när du håller muspekaren över en egenskap.
- Syntaxverifiering
- Automatisk komplettering med kodexempel.
aztfmigrate
migreringsverktyg
Verktyget aztfmigrate
är utformat för att migrera befintliga resurser mellan AzAPI- och AzureRM-leverantörerna.
aztfmigrate
har två lägen: planera och migrera:
- Planen visar de AzAPI-resurser som kan migreras.
- Migrera migrerar AzAPI-resurserna till AzureRM-resurser i både HCL-filerna och tillståndet.
aztfmigrate
säkerställer efter migreringen att din Terraform-konfiguration och ditt tillstånd är i linje med ditt faktiska tillstånd. Du kan verifiera uppdateringen till tillståndet genom att köra terraform plan
efter att ha slutfört migreringen för att se att ingenting har ändrats.
Detaljerade kontroller över infrastrukturen
En stor fördel med AzAPI är att den kan finjustera konfigurationen så att den matchar rätt designmönster. Det finns flera sätt att göra detta på:
Providerfunktioner
AzAPI (v2.0 och senare) har en mängd providerfunktioner:
Funktionsnamn | beskrivning |
---|---|
build_resource_id |
Skapar ett Azure-resurs-ID med det överordnade ID:t, resurstypen och resursnamnet. Användbart för att skapa resurs-ID:er för toppnivå och kapslade resurser inom ett specifikt omfång. |
extension_resource_id |
Konstruerar ett resurs-ID för Azure-tillägget baserat på basresurs-ID, resurstyp och ytterligare resursnamn. |
management_group_resource_id |
Skapar ett resurs-ID för Azure-hanteringsgruppens omfång med tanke på hanteringsgruppens namn, resurstyp och resursnamn. |
parse_resource_id |
Den här funktionen tar ett Azure-resurs-ID och en resurstyp och parsar ID:t i sina enskilda komponenter, till exempel prenumerations-ID, resursgruppsnamn, providernamnområde och andra delar. |
resource_group_resource_id |
Skapar ett resurs-ID för Azure-resursgruppsomfång med tanke på prenumerations-ID, resursgruppsnamn, resurstyp och resursnamn. |
subscription_resource_id |
Skapar ett resurs-ID för Azure-prenumerationsomfång med tanke på prenumerations-ID, resurstyp och resursnamn. |
tenant_resource_id |
Konstruerar ett resurs-ID för Azure-klientomfånget med tanke på resurstypen och resursnamnen. |
Användardefinierade återförsökningsbara fel med retry
-blocket
AzAPI
-providern kan sammanfatta fel när det förväntas via retry
-blocket. Om en resurs till exempel kan stöta på ett problem med att skapa timeout kan följande kodblock hjälpa:
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"
}
Utlösare för resursutbyte
Med AzAPI
-providern kan du konfigurera parametrar för ersättning av resurser.
replace_triggers_external_values
Ersätter resursen om ett värde ändras. Om till exempel SKU:n eller zonvariablerna skulle ändras skapas den här resursen igen:
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,
]
}
Detta kan fungera över en bred uppsättning resurser, t.ex. en principtilldelning när definitionens egenskaper ändras.
replace_triggers_refs
Ersätter resursen om det refererade värdet ändras. Om till exempel SKU-namnet eller nivån ändrades skapas den här resursen igen:
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"]
}
Detta skulle inte utlösa en ersättning om en annan resurs SKU skulle ändras.