Gophercloud: an OpenStack SDK for Go

Gophercloud is a Go SDK for OpenStack.

Join us on kubernetes slack, on #gophercloud. Visit slack.k8s.io for an invitation.

Note This branch contains the current stable branch of Gophercloud: v2. The legacy stable version can be found in the v1 branch.

How to install

Reference a Gophercloud package in your code:

import "github.com/gophercloud/gophercloud/v2"

Then update your go.mod:

go mod tidy

Getting started

Credentials

Because you'll be hitting an API, you will need to retrieve your OpenStack credentials and either store them in a clouds.yaml file, as environment variables, or in your local Go files. The first method is recommended because it decouples credential information from source code, allowing you to push the latter to your version control system without any security risk.

You will need to retrieve the following:

A valid Keystone identity URL
Credentials. These can be a username/password combo, a set of Application Credentials, a pre-generated token, or any other supported authentication mechanism.

For users who have the OpenStack dashboard installed, there's a shortcut. If you visit the project/api_access path in Horizon and click on the "Download OpenStack RC File" button at the top right hand corner, you can download either a clouds.yaml file or an openrc bash file that exports all of your access details to environment variables. To use the clouds.yaml file, place it at ~/.config/openstack/clouds.yaml. To use the openrc file, run source openrc and you will be prompted for your password.

Gophercloud authentication

Gophercloud authentication is organized into two layered abstractions:

ProviderClient holds the authentication token and can be used to build a ServiceClient.
ServiceClient specializes against one specific OpenStack module and can directly be used to make API calls.

A provider client is a top-level client that all of your OpenStack service clients derive from. The provider contains all of the authentication details that allow your Go code to access the API - such as the base URL and token ID.

One single Provider client can be used to build as many Service clients as needed.

With clouds.yaml

package main

import (
	"context"

	"github.com/gophercloud/gophercloud/v2/openstack"
	"github.com/gophercloud/gophercloud/v2/openstack/config"
	"github.com/gophercloud/gophercloud/v2/openstack/config/clouds"
)

func main() {
	ctx := context.Background()

	// Fetch coordinates from a `cloud.yaml` in the current directory, or
	// in the well-known config directories (different for each operating
	// system).
	authOptions, endpointOptions, tlsConfig, err := clouds.Parse()
	if err != nil {
		panic(err)
	}

	// Call Keystone to get an authentication token, and use it to
	// construct a ProviderClient. All functions hitting the OpenStack API
	// accept a `context.Context` to enable tracing and cancellation.
	providerClient, err := config.NewProviderClient(ctx, authOptions, config.WithTLSConfig(tlsConfig))
	if err != nil {
		panic(err)
	}

	// Use the ProviderClient and the endpoint options fetched from
	// `clouds.yaml` to build a service client: a compute client in this
	// case. Note that the contructor does not accept a `context.Context`:
	// no further call to the OpenStack API is needed at this stage.
	computeClient, err := openstack.NewComputeV2(providerClient, endpointOptions)
	if err != nil {
		panic(err)
	}

	// use the computeClient
}

With environment variables (openrc)

Gophercloud can parse the environment variables set by running source openrc:

package main

import (
	"context"
	"os"

	"github.com/gophercloud/gophercloud/v2"
	"github.com/gophercloud/gophercloud/v2/openstack"
)

func main() {
	ctx := context.Background()

	opts, err := openstack.AuthOptionsFromEnv()
	if err != nil {
		panic(err)
	}

	providerClient, err := openstack.AuthenticatedClient(ctx, opts)
	if err != nil {
		panic(err)
	}

	computeClient, err := openstack.NewComputeV2(providerClient, gophercloud.EndpointOpts{
		Region: os.Getenv("OS_REGION_NAME"),
	})
	if err != nil {
		panic(err)
	}

	// use the computeClient
}

Manually

You can also generate a "Provider" by passing in your credentials explicitly:

package main

import (
	"context"

	"github.com/gophercloud/gophercloud/v2"
	"github.com/gophercloud/gophercloud/v2/openstack"
)

func main() {
	ctx := context.Background()

	providerClient, err := openstack.AuthenticatedClient(ctx, gophercloud.AuthOptions{
		IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
		Username:         "username",
		Password:         "password",
	})
	if err != nil {
		panic(err)
	}

	computeClient, err := openstack.NewComputeV2(providerClient, gophercloud.EndpointOpts{
		Region: "RegionName",
	})
	if err != nil {
		panic(err)
	}

	// use the computeClient
}

Provision a server

We can use the Compute service client generated above for any Compute API operation we want. In our case, we want to provision a new server. To do this, we invoke the Create method and pass in the flavor ID (hardware specification) and image ID (operating system) we're interested in:

import "github.com/gophercloud/gophercloud/v2/openstack/compute/v2/servers"

func main() {
    // [...]

    server, err := servers.Create(context.TODO(), computeClient, servers.CreateOpts{
        Name:      "My new server!",
        FlavorRef: "flavor_id",
        ImageRef:  "image_id",
    }).Extract()

    // [...]

The above code sample creates a new server with the parameters, and returns a servers.Server.

Advanced Usage

Have a look at the FAQ for some tips on customizing the way Gophercloud works.

Backwards-Compatibility Guarantees

Gophercloud versioning follows semver.

Before v1.0.0, there were no guarantees. Starting with v1, there will be no breaking changes within a major release.

See the Release instructions.

Contributing

See the contributing guide.

Help and feedback

If you're struggling with something or have spotted a potential bug, feel free to submit an issue to our bug tracker.

mahak/gophercloud