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 development version of Gophercloud (
v3). Backward-compatible changes are backported to the current stable branchv2. The legacy stable version can be found in thev1branch.
Reference a Gophercloud package in your code:
import "github.com/gophercloud/gophercloud/v2"
Then update your go.mod:
go mod tidy
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 is organized into two layered abstractions:
ProviderClientholds the authentication token and can be used to build aServiceClient.ServiceClientspecializes 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. The constructor accepts a `context.Context` for endpoint // resolution, cancellation, and tracing. computeClient, err := openstack.NewComputeV2(ctx, 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(ctx, 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/v3", Username: "username", Password: "password", }) if err != nil { panic(err) } computeClient, err := openstack.NewComputeV2(ctx, providerClient, gophercloud.EndpointOpts{ Region: "RegionName", }) if err != nil { panic(err) } // use the computeClient }
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", }, nil).Extract() // [...]
The above code sample creates a new server with the parameters, and returns a
servers.Server.
| Service | Name | Module | 1.x | 2.x |
|---|---|---|---|---|
| Baremetal | Ironic | openstack/baremetal |
✔ | ✔ |
| Baremetal Introspection | Ironic Inspector | openstack/baremetalintrospection |
✔ | ✔ |
| Block Storage | Cinder | openstack/blockstorage |
✔ | ✔ |
| Clustering | Senlin | openstack/clustering |
✔ | ✘ |
| Compute | Nova | openstack/compute |
✔ | ✔ |
| Container | Zun | openstack/container |
✔ | ✔ |
| Container Infrastructure | Magnum | openstack/containerinfra |
✔ | ✔ |
| Database | Trove | openstack/db |
✔ | ✔ |
| DNS | Designate | openstack/dns |
✔ | ✔ |
| Identity | Keystone | openstack/identity |
✔ | ✔ |
| Image | Glance | openstack/image |
✔ | ✔ |
| Key Management | Barbican | openstack/keymanager |
✔ | ✔ |
| Load Balancing | Octavia | openstack/loadbalancer |
✔ | ✔ |
| Messaging | Zaqar | openstack/messaging |
✔ | ✔ |
| Metric | Aetos | openstack/metric |
✘ | ✔ |
| Networking | Neutron | openstack/networking |
✔ | ✔ |
| Object Storage | Swift | openstack/objectstorage |
✔ | ✔ |
| Orchestration | Heat | openstack/orchestration |
✔ | ✔ |
| Placement | Placement | openstack/placement |
✔ | ✔ |
| Shared File Systems | Manila | openstack/sharedfilesystems |
✔ | ✔ |
| Workflow | Mistral | openstack/workflow |
✔ | ✔ |
Have a look at the FAQ for some tips on customizing the way Gophercloud works.
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.
If you're struggling with something or have spotted a potential bug, feel free to submit an issue to our bug tracker.