Delen via


Overzicht van de Terraform AzAPI-provider

De AzAPI-provider is een dunne laag boven op de Azure ARM REST API's. Hiermee kunt u elk Azure-resourcetype beheren met behulp van een API-versie, zodat u de nieuwste functionaliteit binnen Azure kunt gebruiken. AzAPI is een eersteklas provider die is ontworpen om zelfstandig of in combinatie met de AzureRM-provider te worden gebruikt.

Voordelen van het gebruik van de AzAPI-provider

De AzAPI-provider biedt de volgende voordelen:

  • Ondersteunt alle Azure-besturingsvlakservices:
    • Voorvertoning van services en functies
    • Alle API-versies
  • Volledige getrouwheid van het Terraform-statusbestand
    • Eigenschappen en waarden worden opgeslagen in status
  • Geen afhankelijkheid van Swagger
  • Algemene en consistente Azure-verificatie
  • Ingebouwde preflight-validatie
  • Gedetailleerde controle over infrastructuurontwikkeling
  • Robuuste VS Code-extensie

Hulpmiddelen

Om u in staat te stellen alle Azure-resources en -functies te beheren zonder dat er updates nodig zijn, bevat de AzAPI-provider de volgende algemene resources:

Resourcenaam Beschrijving
azapi_resource Wordt gebruikt voor het volledig beheren van elke Azure-resource (besturingsvlak) (API) met volledige CRUD.
   Voorbeelden van Gebruiksscenario's
      Nieuwe preview-service
      Nieuwe functie toegevoegd aan bestaande service
      Bestaande functie/service die momenteel niet wordt gedekt
azapi_update_resource Wordt gebruikt voor het beheren van resources of delen van resources die geen volledige CRUD hebben
   Voorbeelden van gebruik
      Nieuwe eigenschappen voor een bestaande service bijwerken
      Vooraf aangemaakte onderliggende resource bijwerken, zoals een DNS SOA-record.
azapi_resource_action Wordt gebruikt om één bewerking uit te voeren op een resource zonder de levenscyclus ervan te beheren
   Voorbeelden van gebruikstoepassingen
      Een virtuele machine afsluiten
      Een geheim toevoegen aan een Sleutelkluis
azapi_data_plane_resource Wordt gebruikt voor het beheren van een specifieke subset van Azure-gegevensvlak-resources
   Voorbeelden van gebruik:
      KeyVault-certificaatcontactpersonen
      Synapse-werkruimtebibliotheken

Gebruikshiërarchie

Over het algemeen moet het gebruik de volgende stappen volgen:

  1. Het wordt altijd aanbevolen om te beginnen met het uitvoeren van zoveel mogelijk bewerkingen binnen azapi_resource.
  2. Als het resourcetype niet bestaat binnen azapi_resource, maar wel valt onder een van de typen die worden ondersteund door azapi_data_plane_resource, gebruik dan dat in plaats daarvan.
  3. Als de resource al bestaat in AzureRM of een eigenschap heeft die niet kan worden geopend binnen azapi_resource, gebruik azapi_update_resource om toegang te krijgen tot deze specifieke eigenschappen. Resources die niet worden ondersteund door azapi_resource of azapi_data_plane_resource kunnen niet via deze resource worden bijgewerkt.
  4. Als u een actie probeert uit te voeren die niet is gebaseerd op een azure CRUD-vriendelijke resource, is dit azapi_resource_action minder eenvoudig dan azapi_update_resource maar flexibeler.

Voorbeelden van resourceconfiguratie

Met het volgende codefragment wordt een resource geconfigureerd die momenteel niet bestaat in de AzureRM-provider:

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

Met het volgende codefragment wordt een preview-eigenschap geconfigureerd voor een bestaande resource vanuit 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
    }
  }
}

Met het volgende codefragment wordt een resourceactie geconfigureerd voor een bestaande AzureRM-resource:

resource "azapi_resource_action" "vm_shutdown" {
  type = "Microsoft.Compute/virtualMachines@2023-07-01"
  resource_id = azurerm_linux_virtual_machine.example.id
  action = "powerOff”
}

Met het volgende codefragment wordt een resource geconfigureerd die momenteel niet bestaat in de AzureRM-provider omdat dit is ingericht op het gegevensvlak:

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

Voorbeeld van preflight-gebruik

De volgende codefragmentfouten tijdens terraform plan vanwege de ingebouwde preflight-validatie van 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
        ]
      }
    }
  }
}

Preflight is verborgen achter een providervlag, maar helpt fouten in de plan fase te genereren.

Gegevensbronnen

De AzAPI-provider ondersteunt diverse nuttige gegevensbronnen:

Naam van gegevensbron Beschrijving
azapi_resource Wordt gebruikt voor het lezen van informatie uit elke Azure-resource (besturingsvlak) (API).
   Voorbeelden van gebruikssituaties:
      Nieuwe preview-service
      Nieuwe functie toegevoegd aan bestaande service
      Bestaande functie/service die momenteel niet wordt gedekt
azapi_client_config Toegang tot clientgegevens, zoals abonnements-id en tenant-id.
azapi_resource_action Wordt gebruikt om één leesbewerking uit te voeren op een resource zonder de levenscyclus ervan te beheren
   Gebruikstoepassingen:
      Lijstsleutels
      Status lezen van VM
azapi_data_plane_resource Wordt gebruikt voor toegang tot een specifieke subset van Azure-gegevensvlakbronnen
   Voorbeelden van gebruikssituaties
      KeyVault-certificaatcontactpersonen
      Synapse-werkruimtebibliotheken
azapi_resource_id Open de resource-id van een resource, met de mogelijkheid om informatie uit te voeren, zoals abonnements-id, bovenliggende id, resourcegroepnaam en resourcenaam.
azapi_resource_list Alle resources onder een opgegeven bovenliggende resource-id tonen.
   Voorbeelden van gebruikscases:
      Resources onder een abonnement/resourcegroep
      Subnetten onder een virtueel netwerk

Verificatie met behulp van de AzAPI-provider

De AzAPI-provider maakt dezelfde verificatiemethoden mogelijk als de AzureRM-provider. Zie Terraform verifiëren bij Azure voor meer informatie over verificatieopties.

Ervaring en levenscyclus van de AzAPI-provider

In deze sectie worden enkele hulpprogramma's beschreven waarmee u de AzAPI-provider kunt gebruiken.

VS Code-extensie en taalserver

De AzAPI VS Code-extensie biedt een uitgebreide ontwerpervaring met de volgende voordelen:

  • Geef alle beschikbare resourcetypen en API-versies weer. Alle beschikbare resourcetypen weergeven
  • Automatisch aanvullen van de toegestane eigenschappen en waarden voor elke resource. Toegestane eigenschappen weergeven
  • Hints weergeven bij het aanwijzen van een eigenschap. Hint weergeven bij het aanwijzen van een eigenschap
  • Syntaxisvalidatie Syntaxisvalidatie
  • Automatisch aanvullen met codevoorbeelden. Automatisch aanvullen met codevoorbeelden

hulpprogramma voor aztfmigrate migratie

Het aztfmigrate hulpprogramma is ontworpen om bestaande resources te migreren tussen de AzAPI- en AzureRM-providers.

aztfmigrate heeft twee modi: plannen en migreren:

  • In het plan worden de AzAPI-resources weergegeven die kunnen worden gemigreerd.
  • Het migratieproces migreert de AzAPI-resources naar AzureRM-resources in zowel de HCL-bestanden als de huidige toestand.

aztfmigrate zorgt er na de migratie voor dat uw Terraform-configuratie en -status zijn afgestemd op uw werkelijke status. U kunt de update naar de status valideren door uit te voeren terraform plan nadat de migratie is voltooid om te zien dat er niets is gewijzigd.

Gedetailleerde regelingen voor infrastructuur

Een belangrijk voordeel van AzAPI is door de mogelijkheid om uw configuratie af te stemmen op de juiste ontwerppatronen. Er zijn verschillende manieren waarop u dit kunt doen:

Providerfuncties

AzAPI (v2.0 en hoger) heeft een aantal providerfuncties:

Functienaam Beschrijving
build_resource_id Maakt een Azure resource-ID aan op basis van de bovenliggende ID, het resourcetype en de resourcenaam.
Handig voor het maken van resource-id's voor resources op het hoogste niveau en geneste resources binnen een specifieke scope.
extension_resource_id Hiermee wordt een Azure resource-ID van de extensie samengesteld op basis van de resource-ID, het resourcetype en aanvullende resourcenamen.
management_group_resource_id Hiermee wordt een resource-id voor het bereik van een Azure-beheergroep samengesteld op basis van de naam, het resourcetype en de resourcenamen van de beheergroep.
parse_resource_id Deze functie gebruikt een Azure-resource-id en een resourcetype en parseert de id in de afzonderlijke onderdelen, zoals abonnements-id, resourcegroepnaam, providernaamruimte en andere onderdelen.
resource_group_resource_id Hiermee wordt een resource-id voor het bereik van een Azure-resourcegroep samengesteld op basis van de abonnements-id, de naam van de resourcegroep, het resourcetype en de resourcenamen.
subscription_resource_id Hiermee wordt een resource-id voor het Azure-abonnementsbereik samengesteld op basis van de abonnements-id, het resourcetype en de resourcenamen.
tenant_resource_id Hiermee wordt een resource-id van het Azure-tenantbereik samengesteld op basis van het resourcetype en de resourcenamen.

Door de gebruiker gedefinieerde ophaalfouten met het retry-blok

De AzAPI-provider kan fouten verwerken wanneer verwacht via het retry blok. Als een resource bijvoorbeeld een time-outprobleem kan tegenkomen bij het maken, kan het volgende codeblok helpen:

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

Triggers voor middelenvervanging

Met de AzAPI-provider kunt u parameters configureren voor resourcevervanging:

replace_triggers_external_values

Vervangt de resource als een waarde wordt gewijzigd. Als de SKU- of zonesvariabelen bijvoorbeeld moeten worden gewijzigd, wordt deze resource opnieuw gemaakt:

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

Dit kan werken voor een brede set resources, bijvoorbeeld een beleidstoewijzing wanneer de eigenschappen van de definitie worden gewijzigd.

replace_triggers_refs

Vervangt de resource als de waarde waarnaar wordt verwezen, verandert. Als de SKU-naam of -laag bijvoorbeeld is gewijzigd, wordt deze resource opnieuw gemaakt:

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

Hiermee wordt geen vervanging geactiveerd als de SKU van een andere resource zou worden gewijzigd.

Volgende stappen