nebius/gosdk

nebius/gosdk

Description: Nebius AI Cloud SDK for Go

Language: Go

License: MIT

Stars: 14

Forks: 0

Open issues: 0

Created: 2024-10-31T11:05:00Z

Pushed: 2026-06-09T08:13:49Z

Default branch: main

Fork: no

Archived: no

README:

Nebius AI Cloud SDK for Go

[![go minimal version][go-img]][go-url] [![go tested version][go-latest-img]][go-latest-url] [![CI][ci-img]][ci-url] [![License][license-img]][license-url] [![Go Reference][godoc-img]][godoc-url]

The Nebius AI Cloud SDK for Go is a comprehensive client library for interacting with nebius.com services. Built on gRPC, it supports all APIs defined in the Nebius API repository. This SDK simplifies resource management, authorization, and communication with Nebius services, making it a valuable tool for developers.

Installation

Add the SDK to your Go project with the following command:

go get github.com/nebius/gosdk

To update to the latest version:

go get -u github.com/nebius/gosdk

Supported Go Versions

• Minimum Supported Version: Go 1.24
• The SDK is regularly tested against the latest Go release.
• New SDK versions include several breaking changes in the underlying libraries and work with go>=1.24.
• If you need the older version, pin to `~v0.1, Skip ahead to the [Complete Example](#complete-example) or explore [Advanced Scenarios](SCENARIOS.md).

SDK Initialization

Initialize the SDK with appropriate options:

import "github.com/nebius/gosdk"

sdk, err := gosdk.New(ctx /*, option1, option2, option3 */)
if err != nil {
return fmt.Errorf("create gosdk: %w", err)
}
defer sdk.Close()

The gosdk.New constructor initializes the SDK. However, authorization is required for functionality. Use the gosdk.WithCredentials option to provide credentials.

To clean up resources properly, ensure you call Close when finished.

Find all available options in [options.go](options.go) (reference).

Authorization and Credentials

Authorization is handled by passing credentials via the gosdk.WithCredentials option. Commonly used credentials include gosdk.IAMToken and gosdk.ServiceAccountReader.

Find all available credentials in [credentials.go](credentials.go) (reference).

Using an IAM Token

The gosdk.IAMToken credentials allow you to use an IAM token directly for authorization. This approach is ideal for testing or tools used by end-users with their own credentials.

Here's an example of initializing the SDK with an IAM token stored in an environment variable:

token := os.Getenv("IAM_TOKEN")
sdk, err := gosdk.New(
ctx,
gosdk.WithCredentials(
gosdk.IAMToken(token),
),
)

Important:

• The SDK does not automatically manage IAM token creation or refresh for user accounts.
• Use the nebius CLI (documentation) to obtain an IAM token manually:

IAM_TOKEN=$(nebius iam get-access-token)

• Since tokens expire, this method requires manual token refreshes, making it less suitable for production environments.

Using a Service Account (Recommended)

Service account authorization is recommended for server-to-server communication and production use cases. This method eliminates the need for manual token management by securely handling IAM tokens in the background.

To authorize with a service account, provide the service account ID, public key ID, and RSA private key. The SDK uses these details to generate a JWT and exchange it for an IAM token. The token is automatically refreshed in the background to ensure continuous validity.

Use gosdk.ServiceAccount or gosdk.ServiceAccountReader with functions from [auth/service_account.go](auth/service_account.go).

Here are common approaches:

1. Using a JSON Credentials File:

import "github.com/nebius/gosdk/auth"

sdk, err := gosdk.New(
ctx,
gosdk.WithCredentials(
gosdk.ServiceAccountReader(
auth.NewServiceAccountCredentialsFileParser(
nil, // nil to use the real file system
"~/path/to/service_account.json",
),
),
),
)

File format:

{
"subject-credentials": {
"alg": "RS256",
"private-key": "PKCS#8 PEM with new lines escaped as \n",
"kid": "public-key-id",
"iss": "service-account-id",
"sub": "service-account-id"
}
}

2. Using a PEM-Encoded Private Key File:

auth.NewPrivateKeyFileParser(
nil, // nil to use the real file system
"~/path/to/private_key.pem",
"public-key-id",
"service-account-id",
)

3. Providing Key Content Directly:

privateKey, _ := os.ReadFile("path/to/private_key.pem")
auth.NewPrivateKeyParser(
privateKey,
"public-key-id",
"service-account-id",
)

Resources and Operations

Nebius AI Cloud communicates via gRPC, with read operations such as Get and List returning protobuf messages that describe resources. Mutating operations like Create, Update, and Delete return an Operation object.

Operations can be either synchronous or asynchronous. Synchronous operations are completed immediately, while asynchronous operations may take time to finish. To ensure an operation is fully completed, use the Wait method, which polls the operation status until it is done.

> ℹ️ Note: If the operation fails, Wait will return an error.

Create Resource

The following example demonstrates how to create a compute instance and use Wait to verify the operation's success.

import common "github.com/nebius/gosdk/proto/nebius/common/v1"
import compute "github.com/nebius/gosdk/proto/nebius/compute/v1"

instanceService := sdk.Services().Compute().V1().Instance()

operation, err := instanceService.Create(ctx, &compute.CreateInstanceRequest{
Metadata: &common.ResourceMetadata{
ParentId: "my-project-id",
Name: "my-instance",
},
Spec: &compute.InstanceSpec{
// instance configuration
},
})
if err != nil {
return fmt.Errorf("create instance: %w", err)
}

operation, err = operation.Wait(ctx)
if err != nil {
return fmt.Errorf("wait for instance create: %w", err)
}

instanceID := operation.ResourceID()

Get Resource

The operation doesn't contain the current state of the resource. Once it completes, fetch the resource.

instance, err := instanceService.Get(ctx, &compute.GetInstanceRequest{
Id: instanceID,
})
if err != nil {
return fmt.Errorf("get instance: %w", err)
}

Get Resource by Name

Most resources can also...