Ö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
• Microsoft Terraform Visual Studio 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:

En detaljerad förklaring av hur dataplansramverket fungerar och hur parent_id skiljer sig från kontrollplansresurser finns i Förstå AzAPI-dataplansramverket.

Användningshierarki

Sammantaget bör användningen följa dessa steg:

1. Börja med att utföra så många åtgärder som möjligt inom azapi_resource.
2. Om resurstypen inte finns inom azapi_resource men hamnar under någon av de typer som stöds av azapi_data_plane_resourceanvänder du den i stället.
3. Om resursen redan finns i AzureRM eller har en egenskap som inte kan nås inom azapi_resourceanvänder du azapi_update_resource för att komma åt dessa specifika egenskaper. Resurser som azapi_resource eller azapi_data_plane_resource inte stöder kan inte uppdateras via den här resursen.
4. 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 än azapi_update_resource men mer flexibelt.

Exempel på resurskonfiguration

Följande kodfragment konfigurerar en Azure resurs direkt via ARM-API:et:

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

När det är aktiverat visas konfigurationsfel i förväg under terraform plan istället för vid användning.

Datakällor

AzAPI-providern stöder olika användbara datakällor:

Ett praktiskt exempel med azapi_resource_list med JMESPath-filtrering finns i Lista Azure resurser med AzAPI Terraform-providern.

Läsa en befintlig resurs med azapi_resource datakälla

Datakällan azapi_resource läser det aktuella tillståndet för alla Azure resurser och exponerar dess egenskaper via attributet output. Använd den när du behöver en egenskap som AzureRM-providern inte exponerar:

data "azapi_resource" "aks" {
  type      = "Microsoft.ContainerService/managedClusters@2024-02-01"
  resource_id = azurerm_kubernetes_cluster.example.id

  # Extract the OIDC issuer URL, not exposed by azurerm_kubernetes_cluster
  response_export_values = ["properties.oidcIssuerProfile.issuerURL"]
}

output "oidc_issuer_url" {
  value = data.azapi_resource.aks.output.properties.oidcIssuerProfile.issuerURL
}

Använda response_export_values och JMESPath

response_export_values kontrollerar vilka egenskaper som extraheras från arm-API-råsvaret och görs tillgängliga i attributet output . Den accepterar en lista eller en karta:

• Lista: Ange JSON-egenskapssökvägar som ska extraheras. Använd ["*"] för att exportera hela svarstexten.
• Karta: Använd JMESPath-uttryck för att filtrera och omforma svaret. Nyckeln är namnet på utdatafältet. värdet är JMESPath-frågan.

Kartformuläret föredras för listsvar och fall där du behöver transformera utdata:

data "azapi_resource_list" "storage_accounts" {
  type      = "Microsoft.Storage/storageAccounts@2023-01-01"
  parent_id = azurerm_resource_group.example.id

  response_export_values = {
    "names"     = "value[].name"
    "locations" = "value[].location"
  }
}

En fullständig genomgång finns i Listning av Azure-resurser med AzAPI Terraform-provider.

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 Microsoft Terraform VS Code ger en omfattande redigeringsupplevelse för både AzureRM- och AzAPI-leverantörerna, inklusive:

• Visa en lista över alla tillgängliga resurstyper och API-versioner.
• Automatisk komplettering av tillåtna egenskaper och värden för alla resurser.
• Visa tips när du håller muspekaren över en egenskap.
• Syntaxverifiering
• Komplettera automatiskt med kodexempel.

Tillägget stöder även paste-as-AzAPI (konverterar ARM JSON till azapi_resource block), Azure resursexport via aztfexport, AzureRM-to-AzAPI-migrering och förhandsvalidering. En fullständig guide finns i Använd tillägget Microsoft Terraform VS Code.

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 genom att köra terraform plan efter migreringen för att bekräfta att inga ändringar har gjorts.

En stegvis genomgång finns i Migrera resurser från AzAPI till AzureRM.

Importera befintliga Azure resurser

Använd import-blocket (Terraform 1.5 och senare) eller kommandot terraform import för att ta med en befintlig Azure resurs under AzAPI-hanteringen utan att skapa den igen. Resurs-ID:t måste innehålla API-versionen som en frågeparameter:

import {
  to = azapi_resource.example
  id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Network/virtualNetworks/example-vnet?api-version=2023-11-01"
}

resource "azapi_resource" "example" {
  type      = "Microsoft.Network/virtualNetworks@2023-11-01"
  name      = "example-vnet"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = ["10.0.0.0/16"]
      }
    }
  }
}

Om du vill importera flera resurser samtidigt från befintlig Azure infrastruktur använder du Azure Export for Terraform (aztfexport), som genererar både HCL-konfigurationen och importblocken automatiskt.

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:

Konfigurationsalternativ för leverantör

AzAPI-providerblocket accepterar flera inställningar som gäller globalt för alla resurser i konfigurationen:

En fullständig lista över konfigurationsalternativ för provider finns i AzAPI-providerschema.

En genomgång av hur du aktiverar preflight finns i Aktivera preflight-validering i AzAPI Terraform-providern.

Providerfunktioner

AzAPI v2.0 och senare innehåller flera providerfunktioner:

Användardefinierade återförsöksbara fel med retry blocket

AzAPI-providern hanterar förväntade fel via retry blocket. Använd till exempel följande konfiguration för att försöka igen när en resurs stöter på en tidsgräns för att skapa:

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

Blocket retry accepterar följande attribut:

Kombinera retry med timeouts blocket för att ange en övre gräns för total varaktighet för återförsök:

timeouts {
  create = "10m"
}

Tillfälliga resurser och endast skrivbara egenskaper

AzAPI v2.x stöder skrivskyddade argument (Terraform 1.11 och senare) via attributet på sensitive_bodyazapi_resource. Skrivskyddade egenskaper skickas till ARM-API:et men lagras inte i Terraform-tillstånd, vilket är användbart för hemligheter och autentiseringsuppgifter:

resource "azapi_resource" "example" {
  type      = "Microsoft.SomeService/resources@2024-01-01"
  name      = "example"
  parent_id = azurerm_resource_group.example.id

  body = {
    properties = {
      name = "example"
    }
  }

  # Write-only — not stored in state
  sensitive_body = {
    properties = {
      adminPassword = var.admin_password
    }
  }
}

Använd sensitive_body_version för att styra när skrivskyddade egenskaper skickas tillbaka till API:et (till exempel vid rotation av autentiseringsuppgifter).

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

Den här utlösaren fungerar i en bred uppsättning resurser, till exempel en principtilldelning när definitionsegenskaperna ä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 resurss SKU ändras.

Nästa steg

• Välj mellan AzureRM- och AzAPI Terraform-leverantörer
• Förstå Ramverket för AzAPI-dataplan
• Distribuera din första resurs med AzAPI-providern
• Distribuera din första uppdateringsresurs med AzAPI-providern
• Distribuera din första resursåtgärd med AzAPI-providern
• Utföra resursåtgärder med AzAPI-providern
• Hantera Azure dataplansresurser med AzAPI
• Lista Azure resurser med AzAPI-providern
• Aktivera preflight-validering
• Använda AzAPI-providerfunktioner
• Migrationssökvägar mellan Azure, AzureRM och AzAPI
• Besök providerregistret