Dela via


Ö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:

  1. Vi rekommenderar alltid att du börjar 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 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. Visa en lista över alla tillgängliga resurstyper
  • Automatisk slutförande av tillåtna egenskaper och värden för alla resurser. Lista tillåtna egenskaper
  • Visa tips när du håller muspekaren över en egenskap. Visa förklaring när du för muspekaren över en egenskap
  • Syntaxverifiering Syntaxverifiering
  • Automatisk komplettering med kodexempel. 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.

Nästa steg