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

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:

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:

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

• 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
• Besök providerregistret