Usar el SDK de Azure para Go para las operaciones del plano de control

Obtenga información sobre cómo aprovisionar, configurar y administrar recursos de Azure mediante programación mediante el uso de las bibliotecas de administración de SDK de Azure para Go. Los flujos de trabajo comunes del plano de control incluyen la creación de grupos de recursos, la administración de la infraestructura de almacenamiento y redes, y el control de las operaciones del ciclo de vida de la máquina virtual (VM), como crear, iniciar, detener, cambiar el tamaño, actualizar y eliminar. Si desea la introducción de nivel superior sobre cómo encajan las bibliotecas de administración en la SDK de Azure para Go, comience con Overview de la SDK de Azure para las bibliotecas de administración de Go. Este artículo se centra en los patrones de control de Go que reutiliza en los servicios y proporciona enlaces a la guía del plano de datos cuando la trayectoria en tiempo de ejecución cambia de la gestión de recursos a la interacción con los datos del servicio.

¿Cuál es el plano de control de Azure?

El Azure plano de control es el conjunto de API que controlan el ciclo de vida de los recursos de Azure: crear, actualizar, configurar y eliminarlos. Cada operación que realice en el portal de Azure, CLI de Azure o herramienta de infraestructura como código llama finalmente a estas API del plano de control.

SDK de Azure para Go expone el plano de control a través de una familia de paquetes en arm* bajo github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/. Cada paquete se asigna a un proveedor de recursos de Azure y sigue un patrón coherente:

1. Autentíquese mediante el azidentity paquete.
2. Cree un cliente tipado para el recurso que desea administrar.
3. Ejecute métodos del cliente para crear, leer, actualizar o eliminar recursos.
4. Controle las operaciones de larga duración utilizando encuestadores.

Entre los escenarios comunes para la automatización del plano de control de Go se incluyen:

• Infraestructura de aprovisionamiento para canalizaciones de implementación
• Administración de operaciones de ciclo de vida de máquinas virtuales, como crear, actualizar, eliminar, iniciar, detener y cambiar el tamaño
• Creación de CLIs y operadores personalizados para equipos de plataforma
• Implementación de la reconciliación de la infraestructura al estilo GitOps
• Automatización de la auditoría de cumplimiento y la detección de desfase

Autenticación

Todas las operaciones de administración requieren una credencial autenticada del paquete azidentity. El paquete proporciona tipos de credenciales para todos los entornos, incluidos el desarrollo local, las canalizaciones de CI/CD y las cargas de trabajo de producción que se ejecutan en Azure. Todos los tipos de credenciales implementan la misma azcore.TokenCredential interfaz, por lo que puede intercambiarlos sin cambiar el código de cliente.

Después de obtener una credencial, cree un generador de cliente para el paquete y después pídele el cliente con tipo que necesita:

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

Los documentos de paquetes actuales arm* suelen mostrar el patrón de fábrica de cliente porque centraliza la configuración compartida para los clientes relacionados. Muchos paquetes también exponen constructores directos New<ResourceType>Client(subscriptionID, credential, options) , pero NewClientFactory(...).New<ResourceType>Client() es el patrón que verá con más frecuencia en pkg.go.dev. Para el desarrollo local, DefaultAzureCredential normalmente detecta automáticamente el inicio de sesión de CLI de Azure. En CI/CD y cargas de trabajo implementadas, puede cambiar a credenciales basadas en entorno o identidad administrada sin cambiar el resto del código de cliente.

Para obtener una guía completa sobre los tipos de credenciales y los procedimientos recomendados, consulte Authentication con la SDK de Azure para Go y la documentación del paquete azidentity.

Paquetes de cliente y clientes tipados

Los paquetes de administración están en github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/<service>/arm<service>. Instale el paquete de identidad y solo los arm* paquetes que planea usar. Por ejemplo, si solo administra máquinas virtuales y grupos de recursos, solo necesita armcompute y armresources. Cada paquete contiene clientes para los recursos de ese servicio. Por ejemplo, armcompute tiene clientes para máquinas virtuales, discos, imágenes y recursos de proceso relacionados.

Un único paquete de administración suele contener varios clientes, con cada cliente centrado en un tipo de recurso o grupo de operaciones. Por ejemplo, armcompute incluye clientes para máquinas virtuales, discos, imágenes y recursos relacionados. Después de elegir el paquete de un servicio, cree un generador de cliente y reutilítelo para crear los clientes con tipo que coincidan con los recursos que desea administrar.

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

Este patrón de fábrica de cliente y paquete es coherente en todos los resourcemanager módulos. Es un acceso directo útil al examinar pkg.go.dev o pedir a un agente que encuentre el cliente adecuado para una tarea.

Operaciones de larga duración

Muchas operaciones de administración, como la creación de clústeres, la eliminación de grupos de recursos y la actualización de la infraestructura, se ejecutan de forma asincrónica. Los métodos que tienen como prefijo Begin inician el trabajo del lado del servidor y devuelven un sondeo inmediatamente. El código puede decidir si desea esperar o seguir realizando otro trabajo:

// 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 llamada correcta Begin* solo significa Azure aceptó la solicitud. La operación todavía puede producir un error más adelante mientras se ejecuta el sondeo. Es por eso que tanto la llamada inicial como PollUntilDone necesitan el control de errores. Use PollUntilDone cuando desee el flujo más sencillo. Use poller.Poll y poller.Done cuando necesite una lógica de espera personalizada o informes de progreso.

Para obtener más información sobre los patrones, consulte los patrones de uso de Common en SDK de Azure para Go.

Gestión de errores

Las operaciones de administración devuelven errores estructurados que puede inspeccionar para ver códigos de error 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)
}

La mayoría CreateOrUpdate de las operaciones son idempotentes. Llamarlos en un recurso existente actualiza el recurso en lugar de generar errores.

Aprovisionar un ejemplo de recurso

En este ejemplo se muestra el patrón común del plano de control: autenticar, crear un recurso con etiquetas y tiempo de espera y comprobar el resultado. Use este patrón como plantilla para todas las operaciones de administración porque el patrón de credenciales, contexto e identificador de suscripción se aplica a todos los 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

El paquete armresources administra los grupos de recursos: los contenedores organizativos fundamentales de Azure. Cada Azure recurso existe dentro de un grupo de recursos, lo que hace que sea el punto de partida para cualquier flujo de trabajo de aprovisionamiento.

Úselo para crear y actualizar grupos de recursos con ubicación y etiquetas, enumerar grupos en una suscripción y eliminar grupos junto con todos los recursos contenidos. La creación de un grupo de recursos informáticos es sincrónica e idempotente. La eliminación es asincrónica y permanente.

Listar grupos de recursos también presenta un patrón importante del plano de control: muchas operaciones de lectura usan mecanismos de paginación. Al enumerar grupos de recursos u otras colecciones de ARM grandes, cree un paginador e iterar hasta que pager.More() devuelva 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)
	}
}

Ejemplo de código de gestión de grupos de recursos.

Para obtener una guía de introducción, consulte la documentación del paquete armresources.

Máquinas virtuales

El paquete armcompute es un ejemplo de plano de control canónico porque la administración de máquinas virtuales funciona principalmente en el ciclo de vida: crear o actualizar una máquina virtual, iniciarla o detenerla, cambiar su tamaño y eliminarla. En Go, estos flujos de trabajo usan el mismo patrón factory de clientes y DefaultAzureCredential, context.Context tal como se muestra en el ejemplo del grupo de recursos, por lo que una vez implementado ese patrón, puede aplicarlo en operaciones de cómputo sin cambiar el enfoque de autenticación.

Si necesita un punto de partida rápido, cree la fábrica de clientes de cómputo y luego pídale el cliente de máquina virtual tipado.

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

Para obtener ejemplos completos de máquinas virtuales e instrucciones específicas de la operación, consulte las muestras de gestión de máquinas virtuales existentes y la documentación del paquete armcompute. Use esas referencias para los modelos de solicitud completos y los detalles de las operaciones de ejecución prolongada en lugar de duplicar plantillas de máquina virtual de gran tamaño en este artículo.

Key Vault

El paquete armkeyvault administra el ciclo de vida de las instancias de Azure Key Vault. Este paquete gestiona el plano de control de la infraestructura de bóveda. Utiliza los paquetes independientes del plano de datos azsecrets, azkeys y azcertificates para leer y escribir secretos, claves y certificados.

Utilice este paquete para aprovisionar bóvedas con la SKU y con las configuraciones de seguridad apropiadas, como la eliminación suave y la protección contra purga. También puede gestionar las políticas de acceso para principales, configurar el acceso a la red y los puntos de conexión privados, y habilitar el registro de diagnósticos. Puede integrar el aprovisionamiento de bóvedas en procesos de incorporación de aplicaciones.

Key Vault ejemplo de código de administración.

Para los clientes de Key Vault en el lado de ejecución, utilice el SDK de Azure para Go para operaciones del plano de control de datos.

Para obtener una guía de introducción, consulte la documentación del paquete armkeyvault.

Clústeres de AKS

El paquete armcontainerservice administra Azure Kubernetes Service clústeres en su ciclo de vida completo.

Use este paquete para crear clústeres con redes configurables, versión de Kubernetes e identidad administrada. Puede agregar y escalar grupos de nodos, actualizar el plano de control y las versiones de nodo, habilitar complementos como Azure Policy y supervisión, y consultar el estado del clúster para los paneles operativos. Todas las operaciones de clúster son de larga duración y siguen el patrón de encuesta.

ejemplo de código de administración AKS.

Para obtener una guía de introducción, consulte la documentación del paquete armcontainerservice.

RBAC y autorización

El paquete armauthorization administra Azure Role-Based Access Control. Úselo para automatizar las directivas de acceso con privilegios mínimos en suscripciones y grupos de recursos.

Úselo para enumerar y buscar roles integrados, asignar roles a entidades principales (usuarios, entidades de servicio, identidades administradas o grupos) en cualquier ámbito, crear definiciones de roles personalizadas con permisos detallados y auditar las asignaciones para la elaboración de informes de cumplimiento y la detección de desviaciones. Asigne roles a grupos en lugar de individuos y use roles integrados siempre que sea posible.

Para obtener una guía de introducción, consulte la documentación del paquete armauthorization.

Redes virtuales y seguridad de red

El paquete armnetwork administra Azure infraestructura de red virtual.

Úselo para crear redes virtuales y subredes, configurar grupos de seguridad de red con reglas de entrada y salida, configurar puntos de conexión privados para servicios PaaS, automatizar el emparejamiento de red entre regiones e implementar topologías en estrella tipo hub-and-spoke mediante programación.

ejemplo de código de administración de Network.

Para obtener una guía de introducción, consulte la documentación del paquete armnetwork.

Registro de contenedor

El paquete armcontainerregistry administra instancias de Azure Container Registry.

Úselo para aprovisionar registros con la SKU y la replicación geográfica adecuadas, configurar la autenticación (administrador, entidad de servicio o identidad administrada), administrar webhooks para CI/CD, habilitar el examen de vulnerabilidades y aplicar directivas de retención a imágenes. A menudo se usa Container Registry junto con Azure Kubernetes Service. En primer lugar, aprovisione el registro y, a continuación, haga referencia a él durante la creación del clúster.

Ejemplo de código de administración del Registro de Contenedores.

Para obtener una guía de introducción, consulte la documentación del paquete armcontainerregistry.

cuentas de almacenamiento

El paquete armstorage administra cuentas de Azure Storage.

Úselo para crear cuentas de almacenamiento con el nivel de rendimiento adecuado y redundancia, administrar claves de acceso y firmas de acceso compartido, configurar directivas de ciclo de vida de blobs y configurar el registro de diagnóstico. Las cuentas de almacenamiento son una dependencia común para muchas aplicaciones, por lo que automatizar su aprovisionamiento y configuración es un escenario común del plano de control.

ejemplo de código de administración de cuentas de Storage.

Para obtener una guía de introducción, consulte la documentación del paquete armstorage.

Pasos siguientes

• Información general de la SDK de Azure para las bibliotecas de administración de Go
• Utiliza el SDK de Azure para Go en las operaciones del plano de datos
• SDK de Azure para Go Authentication
• SDK de Azure para ejemplos de Go en GitHub