Omówienie dostawcy narzędzia Terraform AzAPI

Dostawca AzAPI to cienka warstwa na szczycie Azure ARM REST APIs. Umożliwia ona zarządzanie dowolnym typem zasobów platformy Azure przy użyciu dowolnej wersji interfejsu API, co umożliwia korzystanie z najnowszych funkcji na platformie Azure. AzAPI to dostawca pierwszej klasy przeznaczony do użycia samodzielnie lub w połączeniu z dostawcą modułu AzureRM.

Korzyści wynikające z używania dostawcy AzAPI

Dostawca AzAPI oferuje następujące korzyści:

• Obsługuje wszystkie usługi płaszczyzny sterowania platformy Azure:
  • Usługi i funkcje w wersji zapoznawczej
  • Wszystkie wersje interfejsu API
• Pełna wierność pliku stanu Terraform
  • Właściwości i wartości są zapisywane w stanie
• Brak zależności od Swagger
• Typowe i spójne uwierzytelnianie platformy Azure
• Wbudowana weryfikacja wstępna
• Szczegółowa kontrola nad opracowywaniem infrastruktury
• Niezawodne rozszerzenie programu VS Code

Zasoby

Aby umożliwić zarządzanie wszystkimi zasobami i funkcjami platformy Azure bez konieczności aktualizowania, dostawca AzAPI obejmuje następujące zasoby ogólne:

Hierarchia użycia

Ogólnie rzecz biorąc, przebieg użytkowania powinien obejmować następujące kroki:

1. Zawsze zaleca się rozpoczęcie od wykonywania jak największej liczby operacji w programie azapi_resource.
2. Jeśli typ zasobu nie istnieje w azapi_resource, ale mieści się w jednym z typów obsługiwanych przez azapi_data_plane_resource, użyj go zamiast tego.
3. Jeśli zasób już istnieje w usłudze AzureRM lub ma właściwość, do którego nie można uzyskać dostępu w programie azapi_resource, użyj polecenia azapi_update_resource , aby uzyskać dostęp do tych określonych właściwości. Zasoby, które azapi_resource lub azapi_data_plane_resource nie obsługują, nie mogą być aktualizowane za pomocą tego zasobu.
4. Jeśli próbujesz wykonać akcję, która nie jest oparta na zasobie przyjaznym dla środowiska CRUD platformy Azure, azapi_resource_action jest mniej prosta niż azapi_update_resource tylko bardziej elastyczna.

Przykłady konfiguracji zasobów

Poniższy fragment kodu konfiguruje zasób, który nie istnieje obecnie u dostawcy modułu 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"
    }
  }
}

Poniższy fragment kodu konfiguruje właściwość podglądu dla istniejącego zasobu z modułu 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
    }
  }
}

Poniższy fragment kodu konfiguruje akcję zasobu dla istniejącego zasobu modułu AzureRM:

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

Poniższy fragment kodu konfiguruje zasób, który obecnie nie istnieje w dostawcy AzureRM z powodu udostępnienia na płaszczyźnie danych.

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

Przykład użycia przedlotowego

Podczas terraform plan występuje błąd w poniższym fragmencie kodu z powodu wbudowanej weryfikacji wstępnej przez 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
        ]
      }
    }
  }
}

Kontrola przed lotem jest ukryta za flagą dostawcy, ale pomoże zgłaszać błędy na etapie plan.

Źródła danych

Dostawca AzAPI obsługuje różne przydatne źródła danych:

Uwierzytelnianie przy użyciu dostawcy AzAPI

Dostawca AzAPI włącza te same metody uwierzytelniania co dostawca modułu AzureRM. Aby uzyskać więcej informacji na temat opcji uwierzytelniania, zobacz Uwierzytelnianie narzędzia Terraform na platformie Azure.

Doświadczenie i cykl życia dostawcy AzAPI

W tej sekcji opisano niektóre narzędzia ułatwiające korzystanie z dostawcy AzAPI.

Rozszerzenie programu VS Code i serwer językowy

Rozszerzenie AzAPI VS Code zapewnia bogate środowisko tworzenia z następującymi korzyściami:

• Wyświetl listę wszystkich dostępnych typów zasobów i wersji interfejsu API.
• Automatyczne uzupełnianie dozwolonych właściwości i wartości dla dowolnego zasobu.
• Pokaż wskazówki podczas najechania kursorem na właściwość.
• Walidacja składni
• Automatyczne uzupełnianie przy użyciu przykładów kodu.

narzędzie do migracji aztfmigrate

Narzędzie aztfmigrate zostało zaprojektowane w celu ułatwienia migracji istniejących zasobów między dostawcami azAPI i AzureRM.

aztfmigrate ma dwa tryby: planowanie i migracja:

• Plan wyświetla zasoby AzAPI, które można migrować.
• Migracja zasobów AzAPI do zasobów AzureRM odbywa się zarówno w plikach HCL, jak i w stanie.

aztfmigrate zapewnia, że po migracji konfiguracja i stan Terraform są zgodne z aktualnym stanem. Możesz zweryfikować aktualizację stanu, uruchamiając polecenie terraform plan po zakończeniu migracji, aby zobaczyć, że nic się nie zmieniło.

Szczegółowa kontrola nad infrastrukturą

Jedną z głównych zalet narzędzia AzAPI jest możliwość dostosowania konfiguracji do odpowiednich wzorców projektowych. Istnieje kilka sposobów, na które można to zrobić:

Funkcje dostawcy

Moduł AzAPI (wersja 2.0 i nowsze) posiada szereg funkcji dostawcy :

Błędy możliwe do ponownego przetworzenia zdefiniowane przez użytkownika z blokiem retry

Dostawca AzAPI może przetwarzać błędy, gdy jest to oczekiwane za pośrednictwem bloku retry. Jeśli na przykład zasób może napotkać problem z limitem czasu tworzenia, może pomóc następujący blok kodu:

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

Wyzwalacze wymiany zasobów

Dostawca AzAPI umożliwia skonfigurowanie parametrów do zastąpienia zasobów:

replace_triggers_external_values

Zamienia zasób, jeśli wartość ulegnie zmianie. Jeśli na przykład zmienna SKU lub strefy ma zostać zmodyfikowana, ten zasób zostanie utworzony ponownie:

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

Może to działać w szerokim zestawie zasobów, na przykład przy przypisaniu polityki, gdy właściwości definicji się zmienią.

replace_triggers_refs

Zamienia zasób, jeśli przywołyną wartość ulegnie zmianie. Na przykład jeśli nazwa lub warstwa jednostki SKU została zmodyfikowana, ten zasób zostanie utworzony ponownie:

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

Nie spowoduje to zamiany, jeśli SKU innego zasobu miałaby się zmienić.

Następne kroki

• Wdrażanie pierwszego zasobu za pomocą dostawcy AzAPI
• Wdrażanie pierwszego zasobu aktualizacji za pomocą dostawcy AzAPI
• Wdróż swoją pierwszą akcję zasobu za pomocą dostawcy AzAPI
• Odwiedź rejestr dostawców