OUTSCALE Go SDK

The OUTSCALE Go SDK enables you to interact with OUTSCALE Cloud resources using Go. It provides a typed Go client for OUTSCALE APIs, JSON serialization, authentication, and error handling.

To use this SDK, you must have:

  • An OUTSCALE account

  • Valid API credentials

  • Network access to OUTSCALE API endpoints.

Installation

Before you begin: Ensure that you have Go 1.24 or later installed.

The SDK is available as a Go module. To install it, run the following command:

$ go get github.com/outscale/osc-sdk-go/v3

This command adds the SDK dependency to your go.mod file.

API Access Configuration

To use the OUTSCALE Go SDK, you first need to configure it so it can connect to the OUTSCALE API.

You must specify:

  • The credentials used to authenticate your requests.

  • The API endpoint or Region where requests are sent.

You can also configure optional HTTP settings, such as a custom HTTP client or timeout, depending on your requirements.

Authentication

You must provide valid credentials to access the API. Without valid credentials, API requests will fail.

The SDK allows you to authenticate using access keys:

  • In your code (recommended)

  • In the environment variables

  • In the credentials file

Environment variables have precedence over the credentials file. If access keys are set in the environment variables, the values set in the credentials file will be overridden.

Using Go Code

In your go file, use the following syntax:

cfg.SetAccessKey("YOUR_ACCESS_KEY")
cfg.SetSecretKey("YOUR_SECRET_KEY")

Using the Environnement Variables

Set your access key and your secret key in the environment variables, using the following commands:

$ export OSC_ACCESS_KEY=xxx
$ export OSC_SECRET_KEY=yyy

The SDK will automatically authenticate requests using the OSC_ACCESS_KEY and OSC_SECRET_KEY environment variables.

Using the Credentials File

You can set as many profiles as needed in the ~/.osc/config.json file, using the following syntax:

{
  "default": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>"
  },
  "profile_1": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>"
  },
  "profile_2": {
    "access_key": "<ACCESS_KEY>",
    "secret_key": "<SECRET_KEY>"
  }
}

By default, the SDK uses the default profile.

To use another profile from the same credentials file, you can set the OSC_PROFILE environment variable before running your Go application.

The following example runs the application using the profile_1 profile:

$ export OSC_PROFILE=profile_1
$ go run main.go

The SDK will then load the credentials associated with profile_1 instead of the default profile.

You can also select the profile directly in your Go code when creating the client, using the following syntax:

config, err := osc.LoadDefaultConfig(
    context.TODO(),
    osc.WithProfile("profile_1"),
)
if err != nil {
    log.Fatal(err)
}

client := osc.NewFromConfig(config)

This allows you to choose which profile should be used without changing the credentials file.

Endpoint and Region

You must specify the API endpoint or Region you will use.

The following example configures the endpoint for the eu-west-2 Region:

cfg := osc.NewConfiguration()
cfg.SetHost("https://api.eu-west-2.outscale.com/api/v1")

Initialization

To work with the OUTSCALE Go SDK, you must create a new API client from a pre-made configuration at initialization.

The following example initializes an API client that you can use to access the generated services:

cfg := osc.NewConfiguration()
client := osc.NewAPIClient(cfg)

Refer to the GoDoc reference and the examples directory for detailed configuration patterns and authentication methods.

After creating the API client, you can perform your first API call by using the following syntax in your file:

package main

import (
    "fmt"
    osc "github.com/outscale/osc-sdk-go/v3"
)

func main() {
    cfg := osc.NewConfiguration()
    client := osc.NewAPIClient(cfg)

// API Call: Read VMs
    resp, _, err := client.VmApi.ReadVms(nil)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(resp)
}

Once initialized, the client can be used to interact with OUTSCALE services.

Examples

The OUTSCALE Go SDK GitHub repository includes an examples/ directory. We recommend starting from these examples and adapting them to your own use case.

Listing VMs

The following sample shows how to read virtual machines (VMs).

package examples_test

import (
	"testing"

	"github.com/outscale/osc-sdk-go/v3/pkg/osc"
	"github.com/stretchr/testify/require"
)

func TestReadVms(t *testing.T) {
	client := newOSCClient(t)

// 1. Read the list of VMs.
	read, err := client.ReadVms(t.Context(), osc.ReadVmsRequest{Filters: nil})
// 2. Validate the returned VM collection.
	require.NoError(t, err)
	require.NotNil(t, read.Vms)
// 3. Log each VM ID and image ID.
	for i, vm := range *read.Vms {
		t.Logf("[%d] Id: %s; ImageId: %s", i, vm.VmId, vm.ImageId)
	}
}

Managing Keypairs

The following sample shows how to manage SSH keypairs, including their creation and deletion.

package examples_test

import (
	"testing"
	"time"

	"github.com/outscale/osc-sdk-go/v3/pkg/options"
	"github.com/outscale/osc-sdk-go/v3/pkg/osc"
	"github.com/stretchr/testify/require"
)

func TestKeypair(t *testing.T) {
	client := newOSCClient(t)

	ctx := t.Context()

	keypairName := "osc-sdk-go-test-" + RandomString(10)
	faux := false
// 1. Create a keypair.
	resp, err := client.CreateKeypair(ctx, osc.CreateKeypairRequest{
		DryRun:      &faux,
		KeypairName: keypairName,
	}, options.WithRetryTimeout(time.Minute*10))
	require.NoError(t, err)

	deleted := false
	defer func() {
		if deleted {
			return
		}

		if resp.Keypair == nil || resp.Keypair.KeypairId == nil {
			return
		}

		_, _ = client.DeleteKeypair(ctx, osc.DeleteKeypairRequest{
			KeypairId: resp.Keypair.KeypairId,
		})
	}()
// 2. Validate the keypair data returned by the API.
	require.NotNil(t, resp.Keypair)
	require.NotNil(t, resp.Keypair.KeypairId)

	t.Logf("Keypair created: %s", *resp.Keypair.KeypairId)
// 3. Delete the keypair.
	_, err = client.DeleteKeypair(ctx, osc.DeleteKeypairRequest{
		KeypairId: resp.Keypair.KeypairId,
	})
	require.NoError(t, err)
	deleted = true
}

Related Pages

Export to PDF