Omówienie dostawcy narzędzia Terraform AzAPI

Artykuł
08/16/2024

Dostawca AzAPI to cienka warstwa na szczycie interfejsów API REST usługi Azure ARM. 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.

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:

Nazwa zasobu	opis
azapi_resource	Służy do pełnego zarządzania dowolnym zasobem platformy Azure (płaszczyzną sterowania) (API) za pomocą pełnej operacji CRUD. Przykładowe przypadki użycia: Nowa usługa w wersji zapoznawczej Nowa funkcja dodana do istniejącej usługi Istniejąca funkcja/usługa nie jest obecnie objęta
azapi_update_resource	Służy do zarządzania zasobami lub częściami zasobów, które nie mają pełnej operacji CRUD Przykładowe przypadki użycia: Aktualizowanie nowych właściwości istniejącej usługi Zaktualizuj wstępnie utworzony zasób podrzędny — taki jak rekord SOA DNS.
azapi_resource_action	Służy do wykonywania pojedynczej operacji na zasobie bez zarządzania cyklem życia Przykładowe przypadki użycia: Zamykanie maszyny wirtualnej Dodawanie wpisu tajnego do usługi Key Vault
azapi_data_plane_resource	Służy do zarządzania określonym podzbiorem zasobów płaszczyzny danych platformy Azure Przykładowe przypadki użycia: Kontakty certyfikatów usługi KeyVault Biblioteki obszarów roboczych usługi Synapse

Hierarchia użycia

Ogólnie rzecz biorąc, użycie powinno wykonać następujące kroki:

Zawsze zaleca się rozpoczęcie od wykonywania jak największej liczby operacji w programie azapi_resource.
Jeśli typ zasobu nie istnieje, azapi_resource ale mieści się w jednym z typów obsługiwanych przez azapi_data_plane_resourceprogram , użyj tego polecenia.
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.
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 u dostawcy modułu AzureRM z powodu aprowizacji 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"
        }
      }
    }
  }
}

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.

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 narzędzia Terraform
- Właściwości i wartości są zapisywane w stanie
Brak zależności od struktury Swagger
Typowe i spójne uwierzytelnianie platformy Azure
Niezawodne rozszerzenie programu VS Code

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 umieszczania wskaźnika myszy na właściwości.
Walidacja składni
Automatyczne uzupełnianie przy użyciu przykładów kodu.

Narzędzie do migracji azAPI2AzureRM

Dostawca modułu AzureRM zapewnia najbardziej zintegrowane środowisko narzędzia Terraform do zarządzania zasobami platformy Azure. W związku z tym zalecane użycie dostawców AzAPI i AzureRM jest następujące:

Gdy usługa lub funkcja jest w wersji zapoznawczej, użyj dostawcy AzAPI.
gdy usługa zostanie oficjalnie wydana, użyj dostawcy modułu AzureRM.

Narzędzie AzAPI2AzureRM zostało zaprojektowane w celu ułatwienia migracji z dostawcy AzAPI do dostawcy modułu AzureRM.

AzAPI2AzureRM to narzędzie typu open source, które automatyzuje proces konwertowania zasobów AzAPI na zasoby modułu AzureRM.

Moduł AzAPI2AzureRM ma dwa tryby: planowanie i migracja:

Plan wyświetla zasoby AzAPI, które można migrować.
Migrowanie zasobów AzAPI do zasobów modułu AzureRM zarówno w plikach HCL, jak i w stanie.

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

Korzystanie z dostawcy AzAPI

Instalowanie rozszerzenia programu VS Code

Dodaj dostawcę AzAPI do konfiguracji narzędzia Terraform.

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
    }
  }
}

provider "azapi" {
  # More information on the authentication methods supported by
  # the AzureRM Provider can be found here:
  # https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs

  # subscription_id = "..."
  # client_id       = "..."
  # client_secret   = "..."
  # tenant_id       = "..."
}

Zadeklaruj co najmniej jeden zasób AzAPI, jak pokazano w poniższym przykładowym kodzie:

resource "azapi_resource" "example" {
  name = "example"
  parent_id = data.azurerm_machine_learning_workspace.existing.id
  type = "Microsoft.MachineLearningServices/workspaces/computes@2021-07-01"

  location = "eastus"
  body = {
    properties = {
      computeType      = "ComputeInstance"
      disableLocalAuth = true
      properties = {
        vmSize = "STANDARD_NC6"
      }
    }
  }
}

Udostępnij za pośrednictwem