Přehled provideru Terraform AzAPI

Zprostředkovatel AzAPI je tenká vrstva nad REST API Azure ARM. Umožňuje spravovat jakýkoli typ prostředku Azure pomocí libovolné verze rozhraní API, což vám umožní využívat nejnovější funkce v Rámci Azure. AzAPI je prvotřídní poskytovatel navržený tak, aby se používal samostatně nebo společně s poskytovatelem AzureRM.

Výhody použití poskytovatele AzAPI

Poskytovatel AzAPI má následující výhody:

Podporuje všechny služby řídicí vrstvy Azure:
- Služby a funkce ve verzi Preview
- Všechny verze rozhraní API
Úplná přesnost souboru stavu Terraformu
- Vlastnosti a hodnoty se ukládají do stavu.
Bez závislosti na Swaggeru
Běžné a konzistentní ověřování Azure
Vestavěná kontrola před spuštěním
Podrobná kontrola vývoje infrastruktury
Robustní rozšíření VS Code

Zdroje informací

Aby bylo možné spravovat všechny prostředky a funkce Azure bez nutnosti aktualizací, poskytovatel AzAPI obsahuje následující obecné prostředky:

Název prostředku	Popis
`azapi_resource`	Slouží k úplné správě jakéhokoli prostředku v Azure (řídicí rovina, API) s úplným CRUD. Příklady případů použití: Nová služba Preview Nová funkce přidaná do existující služby Stávající funkce nebo služba, které nejsou aktuálně pokryté
`azapi_update_resource`	Slouží ke správě prostředků nebo částí prostředků, které nemají úplné CRUD. Příklady případů použití: Aktualizace existující služby o nové vlastnosti Aktualizace již vytvořeného podřízeného prostředku – například záznam DNS SOA.
`azapi_resource_action`	Slouží k provedení jedné operace s prostředkem bez správy životního cyklu prostředku. Příklady případů použití: Vypnutí virtuálního počítače Přidání tajného kódu do služby Key Vault
`azapi_data_plane_resource`	Slouží ke správě konkrétní podmnožinu prostředků roviny dat Azure. Příklady případů použití: Kontakty certifikátu služby KeyVault Knihovny pracovních prostorů Synapse

Hierarchie využití

Celkově by využití mělo postupovat takto:

Vždy se doporučuje začít s prováděním co největšího počtu operací v rámci azapi_resource.
Pokud typ prostředku neexistuje v rámci azapi_resource, ale spadá pod jeden z typů podporovaných azapi_data_plane_resource, použijte ho.
Pokud prostředek již existuje v AzureRM nebo má vlastnost, ke které se nedá přistupovat uvnitř azapi_resource, použijte azapi_update_resource pro přístup k těmto konkrétním vlastnostem. Prostředky, které azapi_resource nebo azapi_data_plane_resource nepodporují, se nedají prostřednictvím tohoto prostředku aktualizovat.
Pokud se pokoušíte provést akci, která není založená na prostředku Azure přátelském pro CRUD, použití azapi_resource_action je méně přímé než použití azapi_update_resource, ale více flexibilní.

Příklady konfigurace prostředků

Následující fragment kódu konfiguruje prostředek, který aktuálně neexistuje ve zprostředkovateli AzureRM:

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

Následující fragment kódu nakonfiguruje vlastnost Preview pro existující prostředek z 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
    }
  }
}

Následující fragment kódu konfiguruje akci prostředku u existujícího prostředku AzureRM:

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

Následující fragment kódu konfiguruje prostředek, který v zprostředkovateli AzureRM aktuálně neexistuje, protože je zřízený v rovině dat:

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

Příklad předběžného využití

Následující fragment kódu obsahuje chybu kvůli integrovanému předběžnému ověření AzAPI během terraform plan.

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 je skrytý za příznakem poskytovatele, ale pomůže odhalit chyby v plan fázi.

Zdroje dat

Poskytovatel AzAPI podporuje celou řadu užitečných zdrojů dat:

Název zdroje dat	Popis
`azapi_resource`	Používá se ke čtení informací z libovolného prostředku Azure (řídicí roviny) (API). Příklady případů použití: Nová služba Preview Nová funkce přidaná do existující služby Stávající funkce nebo služba, které nejsou aktuálně pokryté
`azapi_client_config`	Přístup k informacím o klientovi, jako je ID předplatného a ID tenanta
`azapi_resource_action`	Slouží k provedení jedné operace čtení u prostředku bez správy jeho životního cyklu. Příklady případů použití: Výpis klíčů Stav virtuálního počítače
`azapi_data_plane_resource`	Používá se pro přístup k konkrétní podmnožině prostředků roviny dat Azure. Příklady případů použití: Kontakty certifikátu služby KeyVault Knihovny pracovních prostorů Synapse
`azapi_resource_id`	Získejte přístup k ID prostředku s možností výstupu informací, jako je ID předplatného, nadřazené ID, název skupiny prostředků a název prostředku.
`azapi_resource_list`	Seznamuje všechny prostředky podle daného ID nadřazeného prostředku. Příklady případů použití: Prostředky v rámci předplatného nebo skupiny prostředků Podsítě ve virtuální síti

Ověřování pomocí zprostředkovatele AzAPI

Zprostředkovatel AzAPI umožňuje stejné metody ověřování jako poskytovatel AzureRM. Další informace o možnostech ověřování najdete v tématu Ověřování Terraformu v Azure.

Zkušenosti a životní cyklus poskytovatele AzAPI

Tato část popisuje některé nástroje, které vám pomůžou používat poskytovatele AzAPI.

Rozšíření VS Code a jazykový server

Rozšíření AzAPI VS Code poskytuje bohaté prostředí pro vytváření obsahu s následujícími výhodami:

Zobrazí seznam všech dostupných typů prostředků a verzí rozhraní API.
Automatické dokončování povolených vlastností a hodnot pro libovolný prostředek
Zobrazit nápovědy při najetí myší na vlastnost
Ověření syntaxe
Automatické dokončování pomocí ukázek kódu

nástroj pro migraci `aztfmigrate`

Nástroj aztfmigrate je navržený tak, aby pomohl migrovat existující prostředky mezi poskytovateli AzAPI a AzureRM.

aztfmigrate má dva režimy: plánování a migrace:

Plán zobrazí prostředky AzAPI, které je možné migrovat.
Přenáší prostředky AzAPI do prostředků AzureRM jak v souborech HCL, tak ve stavu.

aztfmigrate po migraci zajistíte, že konfigurace a stav Terraformu odpovídají vašemu skutečnému stavu. Aktualizaci stavu můžete ověřit spuštěním terraform plan po dokončení migrace a zjistit, že se nic nezměnilo.

Podrobné kontroly nad infrastrukturou

Jednou z hlavních výhod AzAPI je možnost doladit konfiguraci tak, aby odpovídala správným vzorům návrhu. Můžete to udělat několika způsoby:

Funkce zprostředkovatele

AzAPI (v2.0 a novější) má mnoho funkcí poskytovatele :

Název funkce	Popis
`build_resource_id`	Konstruuje ID prostředku Azure na základě nadřazeného ID, typu prostředku a názvu prostředku. Užitečné při vytváření ID prostředků pro prostředky nejvyšší úrovně a vnořené prostředky v rámci určitého oboru.
`extension_resource_id`	Vytvoří ID prostředku rozšíření Azure na základě ID základního prostředku, typu prostředku a dalších názvů prostředků.
`management_group_resource_id`	Vytvoří ID prostředku v rozsahu management skupiny Azure uvedením názvu skupiny, typu prostředku a názvů prostředků.
`parse_resource_id`	Tato funkce přebírá ID prostředku Azure a typ prostředku a rozloží ID na jednotlivé komponenty, jako jsou ID předplatného, název skupiny prostředků, obor názvů poskytovatele a další části.
`resource_group_resource_id`	Vytvoří ID prostředku pro obor působnosti skupiny prostředků Azure na základě zadaného ID předplatného, názvu skupiny prostředků, typu prostředku a názvů prostředků.
`subscription_resource_id`	Vytvoří ID prostředku na úrovni předplatného Azure na základě ID předplatného, typu prostředku a názvů prostředků.
`tenant_resource_id`	Vytvoří ID prostředku prostředí tenanta Azure na základě typu prostředku a názvů prostředků.

Uživatelem definované chyby opakovatelné s blokem `retry`

Poskytovatel AzAPI může zpracovat chyby, pokud se očekávají, v rámci bloku retry. Pokud by například prostředek mohl narazit na problém s vypršením časového limitu pro vytvoření, mohl by vám pomoct tento blok kódu:

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

Spouštěče pro výměnu zdrojů

Poskytovatel AzAPI umožňuje konfigurovat parametry nahrazování zdrojů.

`replace_triggers_external_values`

Nahradí prostředek, pokud se hodnota změní. Pokud by se například změnily proměnné skladové položky nebo zóny, tento prostředek by se znovu vytvořil:

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

To může fungovat v široké sadě prostředků, tj. přiřazení zásad při změně vlastností definice.

`replace_triggers_refs`

Nahradí prostředek, pokud se odkazovaná hodnota změní. Pokud se například změnil název skladové položky nebo úroveň, tento prostředek by se znovu vytvořil:

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

To by neaktivovalo nahrazení, pokud by došlo ke změně skladové položky jiného prostředku.

Další kroky

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-03-09