Compartilhar via

Use o SDK do Azure para Go para operações de plano de controle

Saiba como provisionar, configurar e gerenciar recursos Azure programaticamente usando as bibliotecas de gerenciamento do SDK do Azure for Go. Os fluxos de trabalho comuns do plano de controle incluem a criação de grupos de recursos, o gerenciamento de infraestrutura de armazenamento e rede e o tratamento de operações de ciclo de vida de VM (máquina virtual), como criar, iniciar, parar, redimensionar, atualizar e excluir. Se você quiser a introdução de nível superior sobre como as bibliotecas de gerenciamento se encaixam no SDK do Azure para Go, comece com Overview das bibliotecas de gerenciamento do SDK do Azure for Go. Este artigo se concentra nos padrões do plano de controle Go que você reutiliza nos serviços e vincula-se às diretrizes do plano de dados quando o caminho do runtime passa do gerenciamento de recursos para trabalhar com dados de serviço.

Qual é o plano de controle do Azure?

O plano de controle Azure é o conjunto de APIs que controlam o ciclo de vida dos recursos de Azure – criando, atualizando, configurando e excluindo-os. Cada operação que você executa no portal do Azure, CLI do Azure, ou em ferramentas de infraestrutura como código, por fim, faz chamadas para essas APIs do plano de controle.

O SDK do Azure para Go expõe o plano de controle por meio de uma família de pacotes arm* em github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/. Cada pacote é mapeado para um provedor de recursos Azure e segue um padrão consistente:

  1. Autentique usando o azidentity pacote.
  2. Crie um cliente tipado para o recurso que você deseja gerenciar.
  3. Chame métodos no cliente para criar, ler, atualizar ou excluir recursos.
  4. Lidar com operações de execução longa usando sondadores.

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

  • Provisionamento de infraestrutura para pipelines de implantação
  • Gerenciando operações de ciclo de vida de VM, como criar, atualizar, excluir, iniciar, parar e redimensionar
  • Criando CLIs e operadores personalizados para equipes de plataforma
  • Implementando a reconciliação de infraestrutura no estilo GitOps
  • Automatizando a auditoria de conformidade e a detecção de descompasso

Autenticação

Todas as operações de gerenciamento exigem uma credencial autenticada do pacote azidentity. O pacote fornece tipos de credenciais para todos os ambientes, incluindo desenvolvimento local, pipelines de CI/CD e workloads de produção em execução no Azure. Todos os tipos de credencial implementam a mesma azcore.TokenCredential interface, para que você possa trocá-los sem alterar o código do cliente.

Depois de obter uma credencial, crie uma fábrica de clientes para o pacote e solicite o cliente digitado de que você precisa:

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

Os documentos do pacote atual arm* geralmente mostram o padrão de fábrica do cliente porque centraliza a configuração compartilhada 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 você verá com mais frequência em pkg.go.dev. Para o desenvolvimento local, DefaultAzureCredential geralmente detecta seu login no CLI do Azure. Em CI/CD e cargas de trabalho implantadas, você pode alternar para credenciais baseadas em ambiente ou identidade gerenciada sem alterar o restante do código do cliente.

Para obter um guia completo sobre tipos de credenciais e práticas recomendadas, consulte Authentication com o SDK do Azure for Go e a documentação do pacote azidentity.

Pacotes de cliente e clientes tipados

Os pacotes de gerenciamento estão em github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/<service>/arm<service>. Instale o pacote de identidade e apenas os arm* pacotes que você planeja usar. Por exemplo, se você estiver gerenciando apenas VMs e grupos de recursos, você só precisará armcompute e armresources. Cada pacote contém clientes para os recursos nesse serviço. Por exemplo, armcompute tem clientes para máquinas virtuais, discos, imagens e recursos de computação relacionados.

Um único pacote de gerenciamento geralmente contém vários clientes, com cada cliente focado em um tipo de recurso ou grupo de operações. Por exemplo, armcompute inclui clientes para máquinas virtuais, discos, imagens e recursos relacionados. Depois de escolher o pacote para um serviço, crie uma fábrica de clientes e reutilize-a para criar os clientes tipados que correspondem aos recursos que você deseja gerenciar.

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

Esse padrão de fábrica de cliente e pacote é consistente entre os resourcemanager módulos. É um atalho útil quando você está verificando pkg.go.dev ou solicitando que um agente encontre o cliente certo para uma tarefa.

Operações de longa duração

Muitas operações de gerenciamento, como a criação de clusters, a exclusão de grupos de recursos e a atualização da infraestrutura, são executadas de forma assíncrona. Métodos prefixados com Begin iniciam o trabalho do lado do servidor e retornam um poller imediatamente. Seu código pode decidir se deseja esperar ou continuar fazendo 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 de Begin* bem-sucedida significa apenas que o Azure aceitou a solicitação. A operação ainda pode falhar mais tarde enquanto o sondador é executado. É por isso que tanto a chamada inicial quanto PollUntilDone precisam de manipulação de erros. Use PollUntilDone quando quiser o fluxo mais simples. Use poller.Poll e poller.Done quando precisar de uma lógica de espera personalizada ou relatórios de progresso.

Para obter mais detalhes sobre padrões, consulte os padrões de uso Common no SDK do Azure for Go.

Tratamento de erros

As operações de gerenciamento retornam erros estruturados que você pode inspecionar para obter 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 operações CreateOrUpdate são idempotentes. Chamá-los em um recurso existente atualiza o recurso ao invés de provocar uma falha.

Provisionar um exemplo de recurso

Este exemplo mostra o padrão comum do plano de controle: autenticar, criar um recurso com marcas e tempo limite e verificar o resultado. Use esse padrão como um modelo para todas as operações de gerenciamento porque o padrão de credencial, contexto e ID de assinatura se aplica 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 gerencia grupos de recursos – os contêineres organizacionais fundamentais em Azure. Cada recurso Azure existe em um grupo de recursos, tornando-o o ponto de partida para qualquer fluxo de trabalho de provisionamento.

Use-o para criar e atualizar grupos de recursos com localização e marcas, listar grupos em uma assinatura e excluir grupos, juntamente com todos os recursos contidos. A criação do grupo de recursos é síncrona e idempotente. A exclusão é assíncrona e permanente.

Listar grupos de recursos também apresenta um padrão de plano de controle importante: muitas operações de leitura usam pagers. Quando enumerar grupos de recursos ou outras grandes coleções ARM, crie um pager e itere até pager.More() retornar 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 gerenciamento de grupo Resource.

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

Máquinas virtuais

O pacote armcompute é um exemplo de plano de controle canônico porque o gerenciamento de VM é principalmente um trabalho de ciclo de vida: criar ou atualizar uma VM, iniciá-la ou pará-la, redimensioná-la e excluí-la. Em Go, esses fluxos de trabalho usam o mesmo padrão de fábrica de clientes com DefaultAzureCredential e context.Context mostrado no exemplo do grupo de recursos, portanto, depois que esse padrão estiver em vigor, você poderá aplicá-lo em operações de computação sem alterar sua abordagem de autenticação.

Se você precisar de um ponto de partida rápido, crie a fábrica de clientes de computação e solicite o cliente de VM tipado:

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

Para obter exemplos completos de VM e diretrizes específicas da operação, consulte os exemplos de gerenciamento de máquinas virtual e a documentação do pacote armcompute. Use essas referências para modelos de solicitação completos e detalhes de operação de execução longa em vez de duplicar modelos de VM grandes neste artigo.

Key Vault (cofre de chaves)

O pacote armkeyvault gerencia o ciclo de vida de instâncias de Azure Key Vault. Esse pacote manipula o plano de controle para a infraestrutura do Vault. Use os pacotes separados de plano de dados azsecrets, azkeys e azcertificates para ler e gravar segredos, chaves e certificados.

Utilize este pacote para provisionar cofres com as configurações de segurança e SKU apropriadas, como exclusão suave e proteção contra limpeza. Você também pode gerenciar políticas de acesso para principais, configurar o acesso à rede e pontos de extremidade privados e habilitar o registro de diagnóstico. Você pode integrar o provisionamento de cofre em fluxos de trabalho de integração de aplicativos.

Key Vault exemplo de código de gerenciamento.

Para os clientes de Key Vault no runtime, consulte Use o SDK do Azure for Go para operações do plano de dados.

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

Clusters do AKS

O pacote armcontainerservice gerencia Serviço de Kubernetes do Azure clusters em todo o ciclo de vida.

Use esse pacote para criar clusters com rede configurável, versão do Kubernetes e identidade gerenciada. Você pode adicionar e dimensionar pools de nós, atualizar as versões do plano de gerenciamento e do nó, habilitar complementos como Azure Policy e monitoramento e consultar a saúde do cluster para visibilidade em painéis operacionais. Todas as operações de cluster são de execução prolongada e seguem o padrão de polling.

exemplo de código de gerenciamento AKS.

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

RBAC e autorização

O pacote armauthorization gerencia Azure Role-Based Controle de Acesso. Use-o para automatizar políticas de acesso com privilégios mínimos entre assinaturas e grupos de recursos.

Use-o para listar e pesquisar funções internas, atribuir funções a principais (usuários, entidades de serviço, identidades gerenciadas ou grupos) em qualquer escopo, criar definições de função personalizadas com permissões refinadas e auditar atribuições para relatórios de conformidade e detecção de desvios. Atribua funções a grupos em vez de indivíduos e use funções internas sempre que possível.

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

Redes virtuais e segurança de rede

O pacote armnetwork gerencia Azure infraestrutura de rede virtual.

Use-o para criar redes virtuais e sub-redes, configurar grupos de segurança de rede com regras de entrada e saída, configurar pontos de extremidade privados para serviços de PaaS, automatizar o emparelhamento de rede entre regiões e implementar topologias hub-and-spoke programaticamente.

Exemplo de código de gerenciamento de rede.

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

Registro de contêiner

O pacote armcontainerregistry gerencia Registro de Contêiner do Azure instâncias.

Use-o para provisionar registros com a SKU e a replicação geográfica apropriadas, configurar a autenticação (administrador, entidade de serviço ou identidade gerenciada), gerenciar webhooks para CI/CD, habilitar a verificação de vulnerabilidades e aplicar políticas de retenção a imagens. Geralmente, você usa o Registro de Contêiner junto com Serviço de Kubernetes do Azure. Primeiro, provisione o registro e, em seguida, faça referência a ele durante a criação do cluster.

Exemplo de código de gerenciamento do Registro de Contêiner.

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

Contas de armazenamento

O pacote armstorage gerencia contas Armazenamento do Azure.

Use-o para criar contas de armazenamento com a camada de desempenho e redundância corretas, gerenciar chaves de acesso e assinaturas de acesso compartilhado, configurar políticas de ciclo de vida do blob e configurar o log de diagnóstico. As contas de armazenamento são uma dependência comum para muitos aplicativos, portanto, automatizar seu provisionamento e configuração é um cenário comum de plano de controle.

Exemplo de código de gerenciamento de conta de armazenamento.

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

Próximas Etapas 

  • Last updated on