Utilize o SDK do Azure para Go para operações de plano de gestão

Aprenda a provisionar, configurar e gerir recursos do Azure de forma programática utilizando as bibliotecas de gestão do SDK do Azure for Go. Fluxos de trabalho comuns no plano de controlo incluem a criação de grupos de recursos, a gestão da infraestrutura de armazenamento e rede, e a gestão de operações do ciclo de vida das máquinas virtuais (VM), como criar, iniciar, parar, redimensionar, atualizar e eliminar. Se quiseres uma introdução mais avançada sobre como as bibliotecas de gestão se enquadram no SDK do Azure do Go, começa com Visão geral das bibliotecas de gestão SDK do Azure para Go. Este artigo foca-se nos padrões do plano de controlo Go que reutiliza entre serviços, e liga-se à orientação do plano de dados quando o percurso de execução passa da gestão de recursos para o trabalho com dados de serviço.

O que é o plano de controlo do Azure?

O plano de controlo do Azure é o conjunto de APIs que controlam o ciclo de vida dos recursos do Azure – criando-os, atualizando-os, configurando-os e eliminando-os. Cada operação que realiza no portal Azure, CLI do Azure ou ferramenta de infraestrutura como código acaba por invocar estas APIs de plano de controlo.

O SDK do Azure para Go expõe o plano de controlo através de uma família de pacotes arm* sob github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/. Cada pacote corresponde a um fornecedor de recursos do Azure e segue um padrão consistente:

1. Autentique usando o azidentity pacote.
2. Crie um cliente com tipo definido para o recurso que deseja gerir.
3. Chamar métodos no cliente para criar, ler, atualizar ou eliminar recursos.
4. Gere operações de longa duração usando pollers.

Cenários comuns para a automação do plano de controlo Go incluem:

• Provisionamento da infraestrutura para pipelines de implementação
• Gerir operações do ciclo de vida da VM, como criar, atualizar, eliminar, iniciar, parar e redimensionar
• Construir CLIs e operadores personalizados para equipas de plataforma
• Implementação da reconciliação de infraestruturas ao estilo GitOps
• Automatização da auditoria de conformidade e deteção de desvios

Authentication

Todas as operações de gestão requerem uma credencial autenticada do pacote azidentity. O pacote fornece tipos de credenciais para todos os ambientes, incluindo desenvolvimento local, pipelines CI/CD e workloads de produção a executar no Azure. Todos os tipos de credenciais implementam a mesma azcore.TokenCredential interface, por isso podes trocá-las sem alterar o código do cliente.

Depois de obteres uma credencial, cria uma fábrica de clientes para o pacote e depois pede-lhe para o cliente tipado que precisas:

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

A documentação atual arm* do pacote normalmente mostra o padrão de fábrica do cliente porque centraliza a configuração partilhada para clientes relacionados. Muitos pacotes também expõem construtores diretos New<ResourceType>Client(subscriptionID, credential, options), mas NewClientFactory(...).New<ResourceType>Client() é o padrão que mais frequentemente encontrará no pkg.go.dev. Para desenvolvimento local, o DefaultAzureCredential normalmente deteta o seu início de sessão do CLI do Azure. Em CI/CD e cargas de trabalho implementadas, pode mudar para credenciais baseadas em ambiente ou identidade gerida sem alterar o resto do código do cliente.

Para um guia completo sobre tipos de credenciais e melhores práticas, consulte Autenticação com a SDK do Azure para Go e a documentação do pacote azidentity.

Pacotes de clientes e clientes tipados

Os pacotes de gestão estão sob github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/<service>/arm<service>. Instala o pacote de identidade e apenas os arm* pacotes que planeias usar. Por exemplo, se só estiver a gerir VMs e grupos de recursos, só precisa de armcompute e armresources. Cada pacote contém clientes para os recursos desse mesmo serviço. Por exemplo, armcompute tem clientes para máquinas virtuais, discos, imagens e recursos de computação relacionados.

Um único pacote de gestão frequentemente contém vários clientes, com cada cliente focado num tipo de recurso ou grupo de operações. Por exemplo, armcompute inclui clientes para máquinas virtuais, discos, imagens e recursos relacionados. Depois de escolheres o pacote para um serviço, cria uma fábrica de clientes e reutiliza-a para criar os clientes tipados que correspondam aos recursos que queres gerir.

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

Este pacote e padrão de fábrica cliente é consistente entre os resourcemanager módulos. É um atalho útil quando estás a analisar pkg.go.dev ou a pedir a um agente para encontrar o cliente certo para uma tarefa.

Operações de longa duração

Muitas operações de gestão, como criar clusters, eliminar grupos de recursos e atualizar infraestruturas, funcionam de forma assíncrona. Métodos com o prefixo Begin iniciam o trabalho do lado do servidor e retornam imediatamente um poller. O teu código pode decidir se espera ou continua a fazer outro trabalho:

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

Uma chamada Begin* bem-sucedida significa apenas Azure aceitou o pedido. A operação ainda pode falhar mais tarde, enquanto o poller está a funcionar. Por isso, tanto a chamada inicial como PollUntilDone necessitam de tratamento de erros. Usa PollUntilDone quando quiseres o fluxo mais simples. Use poller.Poll e poller.Done quando precise de lógica de espera personalizada ou relatórios de progresso.

Para mais detalhes sobre padrões, consulte o Padrões de uso comum em SDK do Azure para Go.

Tratamento de erros

Operações de gestão devolvem erros estruturados que pode inspecionar para códigos de erro específicos:

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

A maioria das CreateOrUpdate operações são idempotentes. Realizar chamadas a um recurso existente atualiza o recurso em vez de falhar.

Fornecer um exemplo de recurso

Este exemplo mostra o padrão comum do plano de controlo: autenticar, criar um recurso com tags e timeout, e verificar o resultado. Use este padrão como modelo para todas as operações de gestão porque o padrão de credencial, contexto e ID de subscrição aplica-se a todos os arm* clientes.

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

Grupos de recursos

O pacote armresources gere grupos de recursos – os contentores organizacionais fundamentais na Azure. Cada recurso do Azure existe dentro de um grupo de recursos, tornando este o ponto de partida para qualquer fluxo de trabalho de provisionamento.

Use-o para criar e atualizar grupos de recursos com localização e etiquetas, listar grupos numa subscrição e eliminar grupos juntamente com todos os recursos contidos. A criação de grupos de recursos é síncrona e idempotente. A deleção é assíncrona e permanente.

Listar grupos de recursos também introduz um padrão importante no plano de controlo: muitas operações de leitura usam pagers. Quando enumerar grupos de recursos ou outras grandes coleções ARM, crie um pager e itere até que pager.More() retorne 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)
	}
}

Exemplo de código de gestão de grupos de recursos.

Para um guia de iniciação, consulte a documentação do pacote armresources.

Máquinas virtuais

O pacote armcompute é um exemplo canónico de plano de controlo porque a gestão de VMs é maioritariamente trabalho de ciclo de vida: criar ou atualizar uma VM, iniciá-la ou pará-la, redimensioná-la e eliminá-la. No Go, estes fluxos de trabalho usam o mesmo DefaultAzureCredential, context.Context, e o padrão de fábrica cliente mostrado no exemplo do grupo de recursos, por isso, uma vez implementado esse padrão, pode aplicá-lo em operações de cálculo sem alterar a sua abordagem de autenticação.

Se precisares de um ponto de partida rápido, cria a fábrica do cliente de computação e depois pede-lhe o cliente VM tipado:

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

Para amostras completas de VM e orientações específicas para operações, consulte os exemplos existentes de gestão de máquinas virtual e a documentação do pacote armcompute. Use essas referências para modelos completos de pedidos e detalhes de operações de longa duração, em vez de duplicar grandes modelos de VM neste artigo.

Key Vault (cofre de chaves)

O pacote armkeyvault gere o ciclo de vida de Azure Key Vault instâncias. Este pacote gere o plano de controlo da infraestrutura do vault. Use os pacotes separados azsecrets, azkeys, e azcertificates plano de dados para ler e escrever segredos, chaves e certificados.

Use este pacote para provisionar cofres com as definições de SKU e segurança apropriadas, como proteção contra eliminação suave e purga. Também pode gerir políticas de acesso para utilizadores, configurar o acesso à rede e endpoints privados, e ativar os registos de diagnóstico. Pode integrar o provisionamento de cofres nos fluxos de trabalho de onboarding de aplicações.

Key Vault exemplo de código de gestão.

Para clientes do Key Vault durante a execução, consulte o uso do SDK do Azure para Go para operações no plano de dados.

Para um guia de iniciação, consulte a documentação do pacote armkeyvault.

Clusters do AKS

O pacote armcontainerservice gere Azure Kubernetes Service clusters ao longo de todo o seu ciclo de vida.

Use este pacote para criar clusters com rede configurável, versão Kubernetes e identidade gerida. Pode adicionar e escalar os pools de nós, atualizar o plano de controlo e as versões dos nós, ativar suplementos como o Azure Policy e as funcionalidades de monitorização, e consultar a saúde do cluster para os dashboards operacionais. Todas as operações de agrupamento são de longa duração e seguem o padrão do poller.

Exemplo de código de gestão AKS.

Para um guia de iniciação, consulte a documentação do pacote armcontainerservice.

RBAC e autorização

O pacote armauthorization gere Azure Role-Based Controlo de Acesso. Use-o para automatizar políticas de acesso de privilégio mínimo entre subscrições e grupos de recursos.

Utilize-o para listar e pesquisar funções incorporadas, atribuir funções aos principais (utilizadores, principais de serviço, identidades geridas ou grupos) em qualquer âmbito, criar definições de funções personalizadas com permissões detalhadas e auditar atribuições para relatórios de conformidade e deteção de desvios. Atribuir funções a grupos em vez de indivíduos e usar funções predefinidas sempre que possível.

Para um guia de introdução, consulte a documentação do pacote armauthorization.

Redes virtuais e segurança de redes

O pacote armnetwork gere Azure infraestrutura de rede virtual.

Utilize-o para criar redes e sub-redes virtuais, configurar grupos de segurança de rede com regras de entrada e saída, configurar endpoints privados para serviços PaaS, automatizar o peering de rede entre regiões e implementar topologias hub-and-spoke de forma programática.

exemplo de código de gestão de rede.

Para um guia de iniciação, consulte a documentação do pacote armnetwork.

Registro de Contêineres

O pacote armcontainerregistry gere Azure Container Registry instâncias.

Utilize-o para provisionar registos com o SKU e geo-replicação apropriados, configurar autenticação (administrador, principal de serviço ou identidade gerida), gerir webhooks para CI/CD, ativar a análise de vulnerabilidades e aplicar políticas de retenção às imagens. Costumas usar o Container Registry juntamente com o Azure Kubernetes Service. Primeiro, provisiona o registo e depois faz referência nele durante a criação do cluster.

Código de gestão do Registo de Contêineres.

Para consultar um guia de introdução, veja a documentação do pacote armcontainerregistry.

Contas de armazenamento

O pacote armstorage gere Armazenamento do Azure contas.

Use-o para criar contas de armazenamento com o nível de desempenho e redundância adequados, gerir chaves de acesso e assinaturas de acesso partilhadas, configurar políticas de ciclo de vida dos blobs e configurar registos de diagnóstico. As contas de armazenamento são uma dependência comum para muitas aplicações, pelo que automatizar o seu provisionamento e configuração é um cenário comum no plano de controlo.

Exemplo de código de gestão de conta de armazenamento.

Para um guia de iniciação, consulte a documentação do pacote armstorage.

Passos seguintes

• Visão geral das bibliotecas de gestão SDK do Azure para Go
• Use o SDK do Azure para Go para operações de plano de dados
• Autenticação do SDK do Azure para Go
• SDK do Azure para amostras de Go em GitHub