Yandex Cloud GO SDK

Go SDK for Yandex Cloud services.

NOTE: SDK is under development, and may make backwards-incompatible changes.

Installation

go get github.com/yandex-cloud/go-sdk/v2

Example usages

Initializing SDK

sdk, err := ycsdk.Build(ctx,
    options..WithCredentials(credentials.IAMToken(os.Getenv("YCIAMTOKEN"))),
)
if err != nil {
    log.Fatal(err)
}

SDK Authorization

https://yandex.cloud/ru/docs/iam/concepts/authorization/

IAM Token (Prefered)

https://yandex.cloud/ru/docs/iam/concepts/authorization/iam-token

sdk, err := ycsdk.Build(ctx,
    options..WithCredentials(credentials.IAMToken(os.Getenv("YCIAMTOKEN"))),
)
if err != nil {
    log.Fatal(err)
}

Inside Yandex Cloud Virtual Machine (Prefered)

https://yandex.cloud/ru/docs/compute/operations/vm-connect/auth-inside-vm#auth-inside-vm

sdk, err := ycsdk.Build(ctx,
    options.WithCredentials(credentials.InstanceServiceAccount()),
)
if err != nil {
	log.Fatal(err)
}

IAM Authorized Key (Service Account)

https://yandex.cloud/ru/docs/iam/concepts/authorization/key

keyPath := "your-authorized-key-path"
creds, err := credentials.ServiceAccountKeyFile(keyPath)
if err != nil {
    log.Fatalf("failed to load credentials: %w", err)
}
sdk, err := ycsdk.Build(ctx,
    options.WithCredentials(creds),
)
if err != nil {
	log.Fatal(err)
}

Service Usage

import (
    "context"
    "fmt"
    "log"
    "os"
    
    "github.com/yandex-cloud/go-sdk/v2"
    "github.com/yandex-cloud/go-sdk/v2/credentials"
    "github.com/yandex-cloud/go-sdk/v2/pkg/options"
    
    computeapi "github.com/yandex-cloud/go-genproto/yandex/cloud/compute/v1"
    computesdk "github.com/yandex-cloud/go-sdk/services/compute/v1"
)
func main() {     // Create background context     ctx := context.Background()
// Initialize SDK with IAM token credentials from environment variable     sdk, err := ycsdk.Build(ctx,         options.WithCredentials(credentials.IAMToken(os.Getenv("YCIAMTOKEN")).     ))          if err != nil {         log.Fatalf("failed to build SDK: %v", err)     }
// Create image client instance     imageClient := computesdk.NewImageClient(sdk)
// Request latest image from Debian 9     resp, err := imageClient.GetLatestByFamily(ctx, &computeapi.GetImageLatestByFamilyRequest{         FolderId: os.Getenv("YCFOLDERID"), // Get folder ID from env variable         Family:   "debian-9", // Specify Debian 9 image family     })
if err != nil {         log.Fatalf("failed to get image: %v", err)     }
// Print response with image details     fmt.Println(resp) }

Retries

SDK provide built-in retry policy, that supports exponential backoff and jitter, and also retry budget. It's necessary to avoid retry amplification.

import (
    ...
    ycsdk "github.com/yandex-cloud/go-sdk/v2"
    "github.com/yandex-cloud/go-sdk/v2/credentials"
    "github.com/yandex-cloud/go-sdk/v2/pkg/options"
)
...
sdk, err := ycsdk.Build(     ctx,     options.WithCredentials(credentials.IAMToken(os.Getenv("YCIAMTOKEN"))),     options.WithDefaultRetryOptions(), )

SDK provide different modes for retry throttling policy:

persistent is suitable when you use SDK in any long-lived application, when SDK instance will live long enough for manage budget;
temporary is suitable when you use SDK in any short-lived application, e.g. scripts or CI/CD.

By default, SDK will use temporary mode, but you can change it through functional option.

SDK Resolvers

SDK resolvers allows you to find resource id by its name.

import (
    "context"
    "flag"
    "fmt"
    "log"
    "os"
    
    ycsdk "bb.yandex-team.ru/cloud/cloud-go/sdk-v2"
    "bb.yandex-team.ru/cloud/cloud-go/sdk-v2/credentials"
    "bb.yandex-team.ru/cloud/cloud-go/sdk-v2/pkg/options"
    "bb.yandex-team.ru/cloud/cloud-go/sdk-v2/pkg/sdkresolvers"
    computesdk "bb.yandex-team.ru/cloud/cloud-go/sdk-v2/sdkresolvers/compute/v1"
)
func main() { 	iamToken := flag.String("token", os.Getenv("YCIAMTOKEN"), "IAM token for Yandex.Cloud (env YCIAMTOKEN)") 	folderID := flag.String("folder-id", os.Getenv("YCFOLDERID"), "Yandex.Cloud Folder ID (env YCFOLDERID)")
ctx := context.Background() 	sdk, err := ycsdk.Build(ctx, 		options.WithCredentials(credentials.IAMToken(*iamToken)), 	) 	if err != nil { 		log.Fatal(err) 	}
name := "test_name" 	r := computesdk.DiskResolver(name, sdkresolvers.FolderID(*folderID)) 	if err = r.Run(ctx, sdk); err != nil { 		log.Fatal(err) 	} 	fmt.Printf("id of object %s is %s", name, r.ID()) }