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:
- Het wordt altijd aanbevolen om te beginnen met het uitvoeren van zoveel mogelijk bewerkingen binnen
azapi_resource
. - Als het resourcetype niet bestaat binnen
azapi_resource
, maar wel valt onder een van de typen die worden ondersteund doorazapi_data_plane_resource
, gebruik dan dat in plaats daarvan. - Als de resource al bestaat in AzureRM of een eigenschap heeft die niet kan worden geopend binnen
azapi_resource
, gebruikazapi_update_resource
om toegang te krijgen tot deze specifieke eigenschappen. Resources die niet worden ondersteund doorazapi_resource
ofazapi_data_plane_resource
kunnen niet via deze resource worden bijgewerkt. - 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 danazapi_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.
- Automatisch aanvullen van de toegestane eigenschappen en waarden voor elke resource.
- Hints weergeven bij het aanwijzen van een eigenschap.
- Syntaxisvalidatie
- 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.