Używanie Azure SDK dla języka Go na potrzeby operacji płaszczyzny sterowania

Dowiedz się, jak programowo aprowizować i konfigurować zasoby Azure oraz zarządzać nimi przy użyciu bibliotek zarządzania Azure SDK dla języka Go. Typowe przepływy pracy płaszczyzny sterowania obejmują tworzenie grup zasobów, zarządzanie infrastrukturą magazynu i sieci oraz obsługę operacji cyklu życia maszyny wirtualnej, takich jak tworzenie, uruchamianie, zatrzymywanie, zmienianie rozmiaru, aktualizowanie i usuwanie. Jeśli chcesz uzyskać wyższy poziom wprowadzenia do tego, jak biblioteki zarządzania pasują do Azure SDK dla języka Go, zacznij od Przegląd bibliotek zarządzania Azure SDK dla języka Go. W tym artykule skupiono się na wzorcach płaszczyzny sterowania w Go, które są ponownie używane w usługach, i zawiera odnośniki do wskazówek dotyczących płaszczyzny danych w sytuacji, gdy ścieżka środowiska uruchomieniowego przechodzi od zarządzania zasobami do pracy z danymi usługi.

Jaka jest płaszczyzna sterowania Azure?

Płaszczyzna sterowania Azure to zestaw interfejsów API, które kontrolują cykl życia zasobów Azure – obejmują tworzenie, aktualizowanie, konfigurowanie i usuwanie. Każda operacja wykonywana w portalu Azure, Azure CLI lub narzędziu infrastruktura jako kod ostatecznie wywołuje te interfejsy API płaszczyzny sterowania.

Azure SDK dla języka Go uwidacznia płaszczyznę sterowania za pośrednictwem rodziny pakietów arm* w github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/. Każdy pakiet odwołuje się do dostawcy zasobów Azure i przestrzega spójnego wzorca:

1. Uwierzytelnianie przy użyciu azidentity pakietu.
2. Utwórz typizowanego klienta dla zasobu, którym chcesz zarządzać.
3. Wywołaj metody na kliencie, aby tworzyć, odczytywać, aktualizować lub usuwać zasoby.
4. Obsługa długotrwałych operacji przy użyciu sondatorów.

Typowe scenariusze automatyzacji płaszczyzny sterowania Go obejmują:

• Przygotowywanie infrastruktury dla procesów wdrożeniowych
• Zarządzanie operacjami cyklu życia maszyny wirtualnej, takimi jak tworzenie, aktualizowanie, usuwanie, uruchamianie, zatrzymywanie i zmienianie rozmiaru maszyny wirtualnej
• Tworzenie niestandardowych interfejsów CLI i operatorów dla zespołów platformy
• Implementowanie uzgodnień infrastruktury w stylu gitOps
• Automatyzowanie inspekcji zgodności i wykrywania dryfu

Uwierzytelnianie

Wszystkie operacje zarządzania wymagają uwierzytelnionego poświadczenia z pakietu azidentity. Pakiet udostępnia typy poświadczeń dla każdego środowiska, obejmując lokalne programowanie, CI/CD pipeline'y oraz obciążenia produkcyjne działające w Azure. Wszystkie typy poświadczeń implementują ten sam azcore.TokenCredential interfejs, dzięki czemu można je zamienić bez zmiany kodu klienta.

Po uzyskaniu poświadczenia, utwórz generowanie klienta dla pakietu, a następnie uzyskaj klienta określonego typu, którego potrzebujesz.

// Create credential that auto-discovers authentication (Azure CLI, env vars, managed identity)
cred, err := azidentity.NewDefaultAzureCredential(nil)

// Construct a client factory, then the typed client for management operations
clientFactory, err := armresources.NewClientFactory(subscriptionID, cred, nil)
rgClient := clientFactory.NewResourceGroupsClient()

Bieżące arm* dokumenty pakietów zwykle pokazują wzorzec fabryki klienta, ponieważ centralizuje konfigurację udostępnioną dla powiązanych klientów. Wiele pakietów udostępnia również konstruktory bezpośrednie New<ResourceType>Client(subscriptionID, credential, options) , ale NewClientFactory(...).New<ResourceType>Client() jest wzorcem, który najczęściej będzie widoczny w pkg.go.dev. W przypadku rozwoju lokalnego DefaultAzureCredential zwykle korzysta z logowania w Azure CLI. W przypadku obciążeń CI/CD i wdrożonych przepływów pracy można przełączyć się na poświadczenia środowiskowe lub tożsamość zarządzaną bez zmiany pozostałej części kodu klienta.

Aby zapoznać się z pełnym przewodnikiem dotyczącym typów poświadczeń i najlepszych rozwiązań, zobacz Authentication with the Azure SDK for Go and the azidentity package documentation(

Pakiety klientów i typizowani klienci

Pakiety zarządzania znajdują się w github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/<service>/arm<service>. Zainstaluj pakiet tożsamości oraz wyłącznie pakiety arm*, których planujesz użyć. Jeśli na przykład zarządzasz tylko maszynami wirtualnymi i grupami zasobów, wystarczy tylko elementy armcompute i armresources. Każdy pakiet zawiera klientów dla zasobów w tej usłudze. Na przykład armcompute ma klientów maszyn wirtualnych, dysków, obrazów i powiązanych zasobów obliczeniowych.

Pojedynczy pakiet zarządzania często zawiera kilku klientów, z których każdy klient koncentruje się na jednym typie zasobu lub grupie operacji. Na przykład armcompute obejmuje klientów maszyn wirtualnych, dysków, obrazów i powiązanych zasobów. Po wybraniu pakietu dla usługi utwórz jedną fabrykę klienta i użyj jej ponownie, aby utworzyć typowych klientów pasujących do zasobów, którymi chcesz zarządzać.

clientFactory, err := armcompute.NewClientFactory(subscriptionID, cred, nil)
if err != nil {
	return err
}
vmClient := clientFactory.NewVirtualMachinesClient()

Ten wzorzec pakietu i fabryki klienta jest spójny w modułach resourcemanager . Jest to przydatny skrót podczas skanowania pkg.go.dev lub proszenia agenta o znalezienie odpowiedniego klienta dla zadania.

Długotrwałe operacje

Wiele operacji zarządzania, takich jak tworzenie klastrów, usuwanie grup zasobów i uaktualnianie infrastruktury, są uruchamiane asynchronicznie. Metody poprzedzone Begin rozpoczynają pracę po stronie serwera i natychmiast zwracają poller. Twój kod może zdecydować, czy czekać, czy nadal wykonywać inne czynności:

// Start an asynchronous operation (returns immediately)
poller, err := client.BeginCreateOrUpdate(ctx, resourceGroupName, parameters, nil)
if err != nil {
	return err
}

// Block until the operation completes or fails
result, err := poller.PollUntilDone(ctx, nil)
if err != nil {
	return err
}

Pomyślne wywołanie Begin* oznacza tylko, że Azure zaakceptowało żądanie. Operacja nadal może zakończyć się niepowodzeniem później, gdy narzędzie poller zostanie uruchomione. Dlatego zarówno początkowe wywołanie, jak i PollUntilDone wymagają obsługi błędów. Użyj PollUntilDone jeśli chcesz uzyskać najprostszy przepływ. Użyj polecenia poller.Poll i poller.Done , gdy potrzebujesz niestandardowej logiki oczekiwania lub raportowania postępu.

Aby uzyskać więcej informacji na temat wzorców, zobacz wzorce użycia Common w Azure SDK dla języka Go.

Obsługa błędów

Operacje zarządzania zwracają ustrukturyzowane błędy, które można sprawdzić pod kątem określonych kodów błędów:

import "github.com/Azure/azure-sdk-for-go/sdk/azcore"

// Check if the error is an Azure service error with structured details
var respErr *azcore.ResponseError
if errors.As(err, &respErr) {
	fmt.Printf("Error code: %s\n", respErr.ErrorCode)
	fmt.Printf("Status code: %d\n", respErr.StatusCode)
}

Większość CreateOrUpdate operacji jest idempotentna. Użycie ich na istniejącym zasobie aktualizuje zasób zamiast zakończyć się niepowodzeniem.

Przykład aprowizacji zasobu

W tym przykładzie przedstawiono wspólny wzorzec płaszczyzny sterowania: uwierzytelnianie, tworzenie zasobu z tagami i przekroczeniem limitu czasu oraz sprawdzanie wyniku. Użyj tego wzorca jako szablonu dla wszystkich operacji zarządzania, ponieważ wzorzec poświadczeń, kontekstu i identyfikatora subskrypcji ma zastosowanie do wszystkich arm* klientów.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/resources/armresources"
)

func main() {
	// Read subscription ID from environment (avoid hardcoding)
	subscriptionID := os.Getenv("AZURE_SUBSCRIPTION_ID")
	if subscriptionID == "" {
		log.Fatal("AZURE_SUBSCRIPTION_ID not set")
	}

	// Create credential that auto-discovers authentication
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to create credential: %v", err)
	}

	// Set a timeout for the entire operation (prevents hanging indefinitely)
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
	defer cancel()

	// Create a client factory for this management package
	clientFactory, err := armresources.NewClientFactory(subscriptionID, cred, nil)
	if err != nil {
		log.Fatalf("failed to create client factory: %v", err)
	}

	// Create the typed client for resource groups
	rgClient := clientFactory.NewResourceGroupsClient()

	// Many ARM models use pointer fields for optional values.
	resp, err := rgClient.CreateOrUpdate(ctx, "example-rg", armresources.ResourceGroup{
		Location: to.Ptr("eastus"),
		Tags: map[string]*string{
			"env":  to.Ptr("dev"),
			"team": to.Ptr("platform"),
		},
	}, nil)
	if err != nil {
		log.Fatalf("failed to create or update resource group: %v", err)
	}

	fmt.Printf("resource group %s ready in %s\n", *resp.Name, *resp.Location)
}

Grupy zasobów

Pakiet armresources0 zarządza grupami zasobów — podstawowymi kontenerami organizacyjnymi w Azure. Każdy zasób Azure istnieje w grupie zasobów, dzięki czemu jest to punkt początkowy dla dowolnego przepływu pracy wdrażania.

Służy do tworzenia i aktualizowania grup zasobów za pomocą lokalizacji i tagów, wyświetlania listy grup w ramach subskrypcji oraz usuwania grup wraz ze wszystkimi zawartymi zasobami. Proces tworzenia grupy zasobów odbywa się synchronicznie i jest idempotentny. Usuwanie jest asynchroniczne i trwałe.

Wyświetlanie listy grup zasobów również wprowadza ważny wzorzec warstwy zarządzania: wiele operacji odczytu korzysta z pagerów. Podczas wyliczania grup zasobów lub innych dużych kolekcji usługi ARM utwórz pager i iteruj, aż pager.More() zwróci wartość false.

pager := rgClient.NewListPager(nil)
for pager.More() {
	page, err := pager.NextPage(ctx)
	if err != nil {
		return err
	}

	for _, group := range page.ResourceGroupListResult.Value {
		fmt.Println(*group.Name)
	}
}

Przykład kodu zarządzania grupą zasobów.

Aby zapoznać się z przewodnikiem wprowadzającym, zobacz dokumentację pakietu armresources.

Maszyny wirtualne

Pakiet armcompute jest kanonicznym przykładem płaszczyzny sterowania, ponieważ zarządzanie maszynami wirtualnymi działa głównie w cyklu życia: tworzenie lub aktualizowanie maszyny wirtualnej, uruchamianie lub zatrzymywanie jej, zmienianie jego rozmiaru i usuwanie. W języku Go te przepływy pracy używają tego samego DefaultAzureCredential wzorca, context.Context i fabryki klienta pokazanego w przykładzie grupy zasobów, więc po zastosowaniu tego wzorca można używać go w operacjach przetwarzania bez zmiany sposobu uwierzytelniania.

Jeśli potrzebujesz szybkiego punktu wyjścia, utwórz fabrykę klienta obliczeniowego, a następnie poproś go o typizowanego klienta maszyny wirtualnej:

clientFactory, err := armcompute.NewClientFactory(subscriptionID, cred, nil)
if err != nil {
	return err
}
vmClient := clientFactory.NewVirtualMachinesClient()

Aby uzyskać pełne przykłady maszyn wirtualnych i wskazówki specyficzne dla operacji, zobacz istniejące przykłady zarządzania maszynami wirtualnymi oraz dokumentację pakietu armcompute. Użyj tych odwołań do kompletnych modeli żądań i długotrwałych szczegółów operacji zamiast duplikowania dużych szablonów maszyn wirtualnych w tym artykule.

Key Vault

Pakiet armkeyvault zarządza cyklem życia wystąpień Azure Key Vault. Ten pakiet zarządza płaszczyzną kontrolną dla infrastruktury Vault. Użyj oddzielnych pakietów azsecrets, azkeys i azcertificates płaszczyzny danych, aby odczytywać i zapisywać sekrety, klucze i certyfikaty.

Użyj tego pakietu, aby aprowizować magazyny z odpowiednimi ustawieniami SKU i zabezpieczeń, takimi jak miękkie usunięcie i ochrona przed pełnym usunięciem. Można również zarządzać zasadami dostępu dla podmiotów, konfigurować dostęp do sieci i prywatne punkty końcowe oraz włączać logowanie diagnostyczne. Aprowizowanie magazynu danych można zintegrować z przepływami pracy wdrożenia aplikacji.

Key Vault przykład kodu zarządzania.

Aby uzyskać informacje o klientach Key Vault po stronie środowiska uruchomieniowego, zobacz Użyj Azure SDK dla operacji płaszczyzny danych.

Aby zapoznać się z przewodnikiem wprowadzającym, zobacz dokumentację pakietu armkeyvault.

Klastry AKS

Pakiet armcontainerservice zarządza klastrami Azure Kubernetes Service w całym cyklu życia.

Ten pakiet służy do tworzenia klastrów z konfigurowalną siecią, wersją kubernetes i tożsamością zarządzaną. Pule węzłów można dodawać i skalować, uaktualniać wersje płaszczyzny sterowania i węzłów, włączać dodatki, takie jak Azure Policy i monitorowanie, oraz wykonywać zapytania dotyczące kondycji klastra dla operacyjnych pulpitów nawigacyjnych. Wszystkie operacje klastra są długotrwałe i realizowane zgodnie z wzorcem działania typu "poller".

przykład kodu zarządzania AKS.

Aby zapoznać się z przewodnikiem wprowadzającym, zobacz dokumentację pakietu armcontainerservice.

RBAC i autoryzacja

Pakiet armauthorization zarządza kontrolą dostępu opartą na rolach Azure. Służy do automatyzowania zasad dostępu z najmniejszymi uprawnieniami w subskrypcjach i grupach zasobów.

Służy do wyświetlania listy i wyszukiwania wbudowanych ról, przypisywania ról do podmiotów zabezpieczeń (użytkowników, jednostek usługi, tożsamości zarządzanych lub grup) w dowolnym zakresie, tworzenia niestandardowych definicji ról z precyzyjnymi uprawnieniami i przypisań inspekcji na potrzeby raportowania zgodności i wykrywania dryfu. Przypisz role do grup, a nie osób, i używaj wbudowanych ról, jeśli to możliwe.

Aby zapoznać się z przewodnikiem wprowadzającym, zobacz dokumentację pakietu armauthorization.

Sieci wirtualne i zabezpieczenia sieci

Pakiet armnetwork zarządza infrastrukturą sieci wirtualnej Azure.

Służy do tworzenia sieci wirtualnych i podsieci, konfigurowania sieciowych grup zabezpieczeń przy użyciu reguł ruchu przychodzącego i wychodzącego, konfigurowania prywatnych punktów końcowych dla usług PaaS, automatyzowania komunikacji równorzędnej sieci między regionami i programowego implementowania topologii piasty i szprych.

przykład kodu zarządzania siecią Network.

Aby zapoznać się z przewodnikiem wprowadzającym, zobacz dokumentację pakietu armnetwork.

Rejestr kontenerów

Pakiet armcontainerregistry zarządza wystąpieniami Azure Container Registry.

Służy do tworzenia rejestrów z odpowiednim SKU i replikacją geograficzną, konfigurowania uwierzytelniania (administratora, jej jednostki usługowej lub tożsamości zarządzanej), zarządzania webhookami na potrzeby ciągłej integracji/ciągłego wdrażania, włączania skanowania luk w zabezpieczeniach i stosowania zasady przechowywania obrazów. Często używasz usługi Container Registry obok Azure Kubernetes Service. Najpierw należy aprowizować rejestr, a następnie odwoływać się do niego podczas tworzenia klastra.

Przykład kodu zarządzania rejestrem kontenerów.

Aby zapoznać się z przewodnikiem wprowadzającym, zobacz dokumentację pakietu armcontainerregistry package.

Konta magazynu

Pakiet armstorage0 zarządza kontami Azure Storage.

Służy do tworzenia kont magazynu z odpowiednią warstwą wydajności i nadmiarowością, zarządzanie kluczami dostępu i sygnaturami dostępu współdzielonego, konfigurowanie zasad cyklu życia obiektów blob i konfigurowanie rejestrowania diagnostycznego. Kontenery danych są częstą zależnością dla wielu aplikacji, dlatego automatyzacja ich utworzenia i konfiguracji jest typowym scenariuszem warstwy kontrolnej.

Przykładowy kod zarządzania kontem magazynowym Storage.

Aby zapoznać się z przewodnikiem wprowadzającym, zobacz dokumentację pakietu armstorage.

Następne kroki

• Przegląd bibliotek zarządzania Azure SDK dla języka Go
• Użyj Azure SDK do operacji na płaszczyźnie danych
• Azure SDK na potrzeby uwierzytelniania języka Go
• Przykłady Azure SDK dla Go na GitHub