Azure SDK for Go Documentation

Getting Started

Welcome to the Azure SDK for Go documentation. This guide will help you get started with building cloud-native applications on Azure using Go.

The Azure SDK for Go provides a set of idiomatic, idiomatic, and robust libraries for interacting with Azure services from your Go applications. It follows the Go community's best practices for package management, error handling, and concurrency.

Prerequisites

  • Go installed (version 1.18 or later recommended).
  • An Azure subscription.
  • Azure CLI installed and configured (optional, but recommended for authentication).

Installation

You can install the Azure SDK for Go modules using Go modules:

go get -u github.com/Azure/azure-sdk-for-go/...

Basic Example

Here's a simple example of how to list storage accounts in your Azure subscription:

package main

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

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storage/armstorage"
)

func main() {
	subscriptionID := os.Getenv("AZURE_SUBSCRIPTION_ID")
	if subscriptionID == "" {
		log.Fatal("AZURE_SUBSCRIPTION_ID environment variable not set")
	}

	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}

	ctx := context.Background()

	clientFactory, err := armstorage.NewClientFactory(subscriptionID, cred, nil)
	if err != nil {
		log.Fatalf("failed to create client factory: %v", err)
	}

	storageAccountsClient := clientFactory.NewStorageAccountsClient()

	pager := storageAccountsClient.NewListPager(nil)
	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			log.Fatalf("failed to advance page: %v", err)
		}
		for _, account := range page.Value {
			fmt.Printf("Storage Account Name: %s, Location: %s\n", *account.Name, *account.Location)
		}
	}
}

Core Concepts

Understanding these core concepts will help you leverage the Azure SDK for Go effectively.

Authentication

The SDK supports various authentication methods. The recommended approach is to use azidentity, which automatically handles credential discovery based on the environment.

  • azidentity.NewDefaultAzureCredential: Attempts multiple credential types in order (environment variables, managed identity, Azure CLI, etc.).
  • azidentity.NewInteractiveBrowserCredential: For local development, opens a browser for interactive login.
  • azidentity.NewClientSecretCredential: For service principals.

Clients

Each Azure service is represented by one or more client types (e.g., StorageAccountsClient, BlobClient). You create a client factory for a specific service and then instantiate the required clients from the factory.

clientFactory, err := armstorage.NewClientFactory(...)
storageClient := clientFactory.NewStorageAccountsClient()

Operations

Clients expose methods for performing operations on Azure resources (e.g., Create, Get, List, Delete). These methods typically return a response and an error.

Models

Request and response payloads are defined as Go structs. Pointers are used extensively to distinguish between zero values and unset fields.

Paging

For operations that return lists of resources, the SDK uses a Pager pattern. You repeatedly call NextPage to iterate through all results.

pager := client.NewListPager(...)
for pager.More() {
    page, err := pager.NextPage(ctx)
    // Process page.Value
}

Long-Running Operations (LROs)

Some Azure operations take time to complete. The SDK provides a consistent way to handle these using *poller.Poller. You start an LRO and then poll it until it's complete.

// Example of starting an LRO
poller, err := client.BeginCreate(ctx, ..., nil)
if err != nil {
    log.Fatalf("failed to start operation: %v", err)
}
resp, err := poller.PollUntilDone(ctx, nil)
if err != nil {
    log.Fatalf("operation did not complete: %v", err)
}
// Use resp. (The actual resource)

Azure Services

The Azure SDK for Go supports a wide range of Azure services. Here are some common categories:

Storage

Compute

Databases

Networking

AI + ML

API Reference

For detailed information on all available packages, types, and functions, please refer to the official Go documentation:

pkg.go.dev/github.com/Azure/azure-sdk-for-go

Example: Storage Accounts Client

Method Description Package
NewClientFactory Creates a factory for Storage resource management clients. sdk/resourcemanager/storage/armstorage
NewStorageAccountsClient Instantiates a client for managing Storage Accounts. sdk/resourcemanager/storage/armstorage
NewListPager Creates a pager to list all storage accounts in a subscription. sdk/resourcemanager/storage/armstorage
BeginCreate Starts the creation of a new storage account. (LRO) sdk/resourcemanager/storage/armstorage

Contributing

The Azure SDK for Go is an open-source project. We welcome contributions from the community! Please see our CONTRIBUTING.md file on GitHub for guidelines on how to contribute.

You can report issues, suggest features, or submit pull requests through the GitHub Issues page.