Condividi tramite

Usare l'Azure SDK per Go per le operazioni del piano di controllo

Informazioni su come effettuare il provisioning, configurare e gestire le risorse Azure a livello di codice usando le librerie di gestione di Azure SDK per Go. I flussi di lavoro comuni del piano di controllo includono la creazione di gruppi di risorse, la gestione dell'infrastruttura di archiviazione e di rete e la gestione delle operazioni del ciclo di vita delle macchine virtuali (VM), ad esempio creazione, avvio, arresto, ridimensionamento, aggiornamento ed eliminazione. Per un'introduzione di livello superiore al modo in cui le librerie di gestione rientrano nel Azure SDK per Go, iniziare con Panoramica delle librerie di gestione di Azure SDK Go. Questo articolo è incentrato sui modelli del piano di controllo Go che vengono riutilizzati tra i servizi e collegamenti alle linee guida del piano dati quando il percorso di runtime passa dalla gestione delle risorse all'uso dei dati del servizio.

Che cos'è il piano di controllo Azure?

Il piano di controllo Azure è il set di API che controllano il ciclo di vita delle risorse Azure, ovvero la creazione, l'aggiornamento, la configurazione e l'eliminazione. Ogni operazione eseguita nel portale di Azure, interfaccia della riga di comando di Azure o nello strumento di infrastruttura come codice chiama infine queste API del piano di controllo.

Il Azure SDK per Go espone il piano di controllo tramite una famiglia di pacchetti arm* in github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/. Ogni pacchetto esegue il mapping a un provider di risorse Azure e segue un modello coerente:

  1. Eseguire l'autenticazione usando il azidentity pacchetto.
  2. Creare un client tipizzato per la risorsa che si vuole gestire.
  3. Chiamare i metodi sul client per creare, leggere, aggiornare o eliminare risorse.
  4. Gestire le operazioni a esecuzione prolungata usando i poller.

Gli scenari comuni per l'automazione del piano di controllo Go includono:

  • Provisionamento dell'infrastruttura per le pipeline di distribuzione
  • Gestione delle operazioni del ciclo di vita delle macchine virtuali, ad esempio creazione, aggiornamento, eliminazione, avvio, arresto e ridimensionamento
  • Creazione di cli e operatori personalizzati per i team della piattaforma
  • Implementazione della riconciliazione dell'infrastruttura in stile GitOps
  • Automazione del controllo della conformità e rilevamento della deriva

Autenticazione

Tutte le operazioni di gestione richiedono credenziali autenticate dal pacchetto azidentity. Il pacchetto fornisce tipi di credenziali per ogni ambiente, inclusi lo sviluppo locale, le pipeline CI/CD e i carichi di lavoro di produzione in esecuzione in Azure. Tutti i tipi di credenziali implementano la stessa azcore.TokenCredential interfaccia, in modo da poterli scambiare senza modificare il codice client.

Dopo aver ottenuto una credenziale, crea una factory di client per il pacchetto e quindi richiedi il client tipizzato necessario.

// 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()

La documentazione del pacchetto corrente arm* mostra in genere il modello factory client perché centralizza la configurazione condivisa per i client correlati. Molti pacchetti espongono anche costruttori diretti New<ResourceType>Client(subscriptionID, credential, options) , ma NewClientFactory(...).New<ResourceType>Client() è il modello più spesso visualizzato in pkg.go.dev. Per lo sviluppo locale, DefaultAzureCredential di solito utilizza il tuo accesso a interfaccia della riga di comando di Azure. Nei carichi di lavoro CI/CD e distribuiti è possibile passare alle credenziali basate sull'ambiente o all'identità gestita senza modificare il resto del codice client.

Per una guida completa sui tipi di credenziali e sulle procedure consigliate, vedere Authentication with the Azure SDK for Go and the azidentity package documentation.

Pacchetti client e client tipizzato

I pacchetti di gestione si trovano in github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/<service>/arm<service>. Installare il pacchetto di identità e solo i arm* pacchetti che si intende utilizzare. Ad esempio, se si gestiscono solo macchine virtuali e gruppi di risorse, sono necessari armcompute solo e armresources. Ogni pacchetto contiene i client per le risorse in tale servizio. Ad esempio, armcompute include client per macchine virtuali, dischi, immagini e risorse di calcolo correlate.

Un singolo pacchetto di gestione contiene spesso diversi client, con ogni client incentrato su un tipo di risorsa o un gruppo di operazioni. Ad esempio, armcompute include client per macchine virtuali, dischi, immagini e risorse correlate. Dopo aver scelto il pacchetto per un servizio, creare una fabbrica di client e riutilizzarla per creare i client tipizzati che corrispondono alle risorse da gestire.

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

Questo pacchetto e il modello factory client sono coerenti tra i resourcemanager moduli. È un collegamento utile quando si analizza pkg.go.dev o si chiede a un agente di trovare il client giusto per un'attività.

Operazioni a esecuzione prolungata

Molte operazioni di gestione, ad esempio la creazione di cluster, l'eliminazione di gruppi di risorse e l'aggiornamento dell'infrastruttura, vengono eseguite in modo asincrono. I metodi con il prefisso Begin avviano il processo lato server e restituiscono immediatamente un poller. Il codice può decidere se attendere o continuare a eseguire altre operazioni:

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

Una chiamata Begin* riuscita significa solo che Azure ha accettato la richiesta. L'operazione può comunque fallire successivamente durante l'esecuzione del poller. Ecco perché sia la chiamata iniziale che PollUntilDone necessitano della gestione degli errori. Usare PollUntilDone quando si vuole il flusso più semplice. Usare poller.Poll e poller.Done quando è necessaria la logica di attesa personalizzata o la creazione di report sullo stato.

Per ulteriori dettagli sui modelli di utilizzo comuni, vedere Common usage patterns in Azure SDK for Go.

Gestione degli errori

Le operazioni di gestione restituiscono errori strutturati che è possibile esaminare per individuare codici di errore specifici:

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

La maggior parte delle operazioni CreateOrUpdate sono idempotenti. Se le si chiama su una risorsa esistente, la risorsa viene aggiornata invece di dare errore.

Eseguire il provisioning di un esempio di risorsa

Questo esempio mostra il modello comune del piano di controllo: autenticare, creare una risorsa con tag e timeout e controllare il risultato. Usare questo modello come modello per tutte le operazioni di gestione perché il modello di credenziali, contesto e ID sottoscrizione si applica a tutti i arm* client.

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

Gruppi di risorse

Il pacchetto armresources gestisce i gruppi di risorse, ovvero i contenitori organizzativi fondamentali in Azure. Ogni risorsa Azure esiste all'interno di un gruppo di risorse, rendendo questo il punto di partenza per qualsiasi flusso di lavoro di provisioning.

Usarlo per creare e aggiornare gruppi di risorse con località e tag, gruppi di elenchi in una sottoscrizione ed eliminare gruppi insieme a tutte le risorse contenute. La creazione del gruppo di risorse è sincrona e idempotente. L'eliminazione è asincrona e permanente.

L'elenco dei gruppi di risorse introduce anche un importante modello del piano di controllo: molte operazioni di lettura usano i pager. Quando si enumerano gruppi di risorse o altre raccolte ARM di grandi dimensioni, creare un paginatore e scorrere fino a pager.More() quando non restituisce 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)
	}
}

Codice di esempio per la gestione del gruppo di risorse.

Per una guida introduttiva, vedere la documentazione del pacchetto armresources.

Macchine virtuali

Il pacchetto armcompute è un esempio canonico del piano di controllo perché la gestione delle macchine virtuali è per lo più lavoro del ciclo di vita: creare o aggiornare una macchina virtuale, avviarla o arrestarla, ridimensionarla ed eliminarla. In Go, questi flussi di lavoro utilizzano lo stesso modello di factory client DefaultAzureCredential, context.Context illustrato nell'esempio del gruppo di risorse, quindi una volta che tale modello è disponibile, è possibile applicarlo alle operazioni di calcolo senza modificare l'approccio di autenticazione.

Se è necessario un punto di avvio rapido, creare la factory client di calcolo e quindi richiederla per il client di macchine virtuali tipizzato:

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

Per esempi completi di macchine virtuali e indicazioni specifiche per le operazioni, vedere gli esempi di gestione di macchine virtuali esistenti e la documentazione del pacchetto armcompute. Usare questi riferimenti per i modelli di richiesta completi e i dettagli delle operazioni a esecuzione prolungata anziché duplicare modelli di macchine virtuali di grandi dimensioni in questo articolo.

Key Vault

Il pacchetto armkeyvault gestisce il ciclo di vita delle istanze di Azure Key Vault. Questo pacchetto gestisce il piano di controllo per l'infrastruttura del vault. Usare i pacchetti separati azsecretsdel piano dati , azkeyse azcertificates per leggere e scrivere segreti, chiavi e certificati.

Usare questo pacchetto per provvedere al provisioning di cassaforti con le impostazioni di sicurezza e SKU appropriate, come l'eliminazione temporanea e la protezione dall'eliminazione definitiva. Puoi anche gestire i criteri di accesso per i principali, configurare l'accesso alla rete e gli endpoint privati e abilitare la registrazione diagnostica. È possibile integrare il provisioning del vault nei flussi di lavoro per l'onboarding delle applicazioni.

esempio di codice di gestione Key Vault.

Per i client di Key Vault sul lato runtime, vedere Utilizzare l'SDK Azure per Go per le operazioni del piano dati.

Per una guida introduttiva, vedere la documentazione del pacchetto armkeyvault.

Cluster AKS

Il pacchetto armcontainerservice gestisce i cluster servizio Azure Kubernetes nel ciclo di vita completo.

Usare questo pacchetto per creare cluster con rete configurabile, versione di Kubernetes e identità gestita. È possibile aggiungere e ridimensionare pool di nodi, aggiornare il piano di controllo e le versioni dei nodi, abilitare componenti aggiuntivi come Criteri di Azure e monitoraggio e eseguire query sull'integrità del cluster per i dashboard operativi. Tutte le operazioni del cluster sono a esecuzione prolungata e seguono il modello di poller.

esempio di codice di gestione AKS.

Per una guida introduttiva, vedere la documentazione del pacchetto armcontainerservice.

RBAC e autorizzazione

Il pacchetto armauthorization gestisce Azure Role-Based Controllo di accesso. Usarlo per automatizzare i criteri di accesso con privilegi minimi tra sottoscrizioni e gruppi di risorse.

Usarlo per elencare e cercare ruoli predefiniti, assegnare ruoli alle entità (utenti, entità servizio, identità gestite o gruppi) in qualsiasi ambito, creare definizioni di ruolo personalizzate con autorizzazioni specifiche e controllare le assegnazioni per la creazione di report di conformità e il rilevamento della deviazione. Assegnare ruoli a gruppi anziché a singoli utenti e usare i ruoli predefiniti laddove possibile.

Per una guida introduttiva, vedere la documentazione del pacchetto armauthorization.

Reti virtuali e sicurezza di rete

Il pacchetto armnetwork gestisce Azure'infrastruttura di rete virtuale.

Usarlo per creare reti virtuali e subnet, configurare gruppi di sicurezza di rete con regole in ingresso e in uscita, configurare endpoint privati per i servizi PaaS, automatizzare il peering di rete tra aree e implementare topologie hub-spoke a livello di codice.

esempio di codice di gestione Rete.

Per una guida introduttiva, vedere la documentazione del pacchetto armnetwork.

Registro dei container

Il pacchetto armcontainerregistry gestisce le istanze di Registro Azure Container.

Usarlo per effettuare il provisioning dei registri con lo SKU e la replica geografica appropriati, configurare l'autenticazione (amministratore, entità servizio o identità gestita), gestire i webhook per CI/CD, abilitare l'analisi delle vulnerabilità e applicare criteri di conservazione alle immagini. Spesso si usa Registro Container insieme a servizio Azure Kubernetes. Eseguire prima di tutto il provisioning del registro e quindi referenziarlo durante la creazione del cluster.

Esempio di codice di gestione del Registro di sistema Container.

Per una guida introduttiva, vedere la documentazione del pacchetto armcontainerregistry.

Account di archiviazione

Il pacchetto armstorage gestisce gli account Archiviazione di Azure.

Usarlo per creare account di archiviazione con il livello di prestazioni e la ridondanza corretti, gestire le chiavi di accesso e le firme di accesso condiviso, configurare i criteri del ciclo di vita dei BLOB e configurare la registrazione diagnostica. Gli account di archiviazione sono una dipendenza comune per molte applicazioni, quindi l'automazione del provisioning e della configurazione è uno scenario comune del piano di gestione.

esempio di codice di gestione degli account Storage.

Per una guida introduttiva, vedere la documentazione del pacchetto armstorage.

Passaggi successivi

  • Last updated on