Huge news!Announcing our $20M Series A led by Andreessen Horowitz.Learn more
Log inDemoInstall

Package Overview
File Explorer

Package gophercloud provides a multi-vendor interface to OpenStack-compatible clouds. The library has a three-level hierarchy: providers, services, and resources. Provider structs represent the cloud providers that offer and manage a collection of services. You will generally want to create one Provider client per OpenStack cloud. Use your OpenStack credentials to create a Provider client. The IdentityEndpoint is typically refered to as "auth_url" or "OS_AUTH_URL" in information provided by the cloud operator. Additionally, the cloud may refer to TenantID or TenantName as project_id and project_name. Credentials are specified like so: You can authenticate with a token by doing: You may also use the openstack.AuthOptionsFromEnv() helper function. This function reads in standard environment variables frequently found in an OpenStack `openrc` file. Again note that Gophercloud currently uses "tenant" instead of "project". Service structs are specific to a provider and handle all of the logic and operations for a particular OpenStack service. Examples of services include: Compute, Object Storage, Block Storage. In order to define one, you need to pass in the parent provider, like so: Resource structs are the domain models that services make use of in order to work with and represent the state of API resources: Intermediate Result structs are returned for API operations, which allow generic access to the HTTP headers, response body, and any errors associated with the network transaction. To turn a result into a usable resource struct, you must call the Extract method which is chained to the response, or an Extract function from an applicable extension: All requests that enumerate a collection return a Pager struct that is used to iterate through the results one page at a time. Use the EachPage method on that Pager to handle each successive Page in a closure, then use the appropriate extraction method from that request's package to interpret that Page as a slice of results: If you want to obtain the entire collection of pages without doing any intermediary processing on each page, you can use the AllPages method: This top-level package contains utility functions and data types that are used throughout the provider and service packages. Of particular note for end users are the AuthOptions and EndpointOpts structs. An example retry backoff function, which respects the 429 HTTP response code and a "Retry-After" header:


Version published


Gophercloud: an OpenStack SDK for Go

Coverage Status

Gophercloud is an OpenStack Go SDK.

How to install

Reference a Gophercloud package in your code:

import ""

Then update your go.mod:

go mod tidy

Getting started


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.


Once you have access to your credentials, you can begin plugging them into Gophercloud. The next step is authentication, which is handled by a base "Provider" struct. There are number of ways to construct such a struct.

With gophercloud/utils

The library provides the clientconfig package to simplify authentication. It provides additional functionality, such as the ability to read clouds.yaml files. To generate a "Provider" struct using the clientconfig package:

import (

// You can also skip configuring this and instead set 'OS_CLOUD' in your
// environment
opts := new(clientconfig.ClientOpts)
opts.Cloud = "devstack-admin"

provider, err := clientconfig.AuthenticatedClient(opts)

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.

Once we have a base Provider, we inject it as a dependency into each OpenStack service. For example, in order to work with the Compute API, we need a Compute service client. This can be created like so:

client, err := clientconfig.NewServiceClient("compute", opts)

Without gophercloud/utils

Note gophercloud doesn't provide support for clouds.yaml file so you need to implement this functionality yourself if you don't wish to use gophercloud/utils.

You can also generate a "Provider" struct without using the clientconfig package from gophercloud/utils. To do this, you can either pass in your credentials explicitly or tell Gophercloud to use environment variables:

import (

// Option 1: Pass in the values yourself
opts := gophercloud.AuthOptions{
  IdentityEndpoint: "",
  Username: "{username}",
  Password: "{password}",

// Option 2: Use a utility function to retrieve all your environment variables
opts, err := openstack.AuthOptionsFromEnv()

Once you have the opts variable, you can pass it in and get back a ProviderClient struct:

provider, err := openstack.AuthenticatedClient(opts)

As above, you can then use this provider client to generate a service client for a particular OpenStack service:

client, err := openstack.NewComputeV2(provider, gophercloud.EndpointOpts{
	Region: os.Getenv("OS_REGION_NAME"),

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 ""

server, err := servers.Create(client, servers.CreateOpts{
	Name:      "My new server!",
	FlavorRef: "flavor_id",
	ImageRef:  "image_id",

The above code sample creates a new server with the parameters, and embodies the new resource in the server variable (a servers.Server struct).

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.


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.


Last updated on 30 Nov 2023

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

SocketSocket SOC 2 Logo


  • Package Issues
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc