Hello, Gophercloud

I’ve been playing around with Gophercloud over the past few days. While it’s nowhere near as complete as openstacksdk (which, coincidentally, recently hit the big 1.0.0 milestone 🎉) or legacy Python-based service clients yet, it is clearly a great tool to have in your arsenal and is the library underlying the Terraform OpenStack Provider, OpenStack platform support in openshift-install, and various OpenStack-specific Kubernetes components, among others.

In the interests of easing ramp-up for anyone else trying to get started with Gophercloud, here’s an simple “hello, world” example - listing servers - using both Gophercloud and openstacksdk.

Gophercloud (Go)

Create a new directory containing a single file, main.go, and add the following to it.

package main

import (
	"context"
	"fmt"

	"github.com/gophercloud/gophercloud/v2/openstack/compute/v2/servers"
	"github.com/gophercloud/utils/v2/openstack/clientconfig"
)

func main() {
	opts := new(clientconfig.ClientOpts)
	// We could configure the cloud manually but we don't. Instead we'll leave it unset causing gophercloud to load the
	// cloud from the 'OS_CLOUD' environment variable. We could also simplify this further and pass 'nil' below instead
	// of generating and passing a 'ClientOpts' object but this shows how you _could_ configure things if you so chose.
	// opts.Cloud = "devstack-admin"

	client, err := clientconfig.NewServiceClient(context.TODO(), "compute", opts)
	if err != nil {
		fmt.Println(err)
		return
	}

	pager, err := servers.List(client, nil).AllPages(context.TODO())
	if err != nil {
		fmt.Println(err)
		return
	}

	servers, err := servers.ExtractServers(pager)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println("servers:")
	for i, server := range servers {
		fmt.Printf("  server %d: id=%s\n", i, server.ID)
	}
}

Now generate the go.mod file.

❯ go mod init gophercloud-hello-world
❯ go mod tidy

Finally, you can run the command.

❯ export OS_CLOUD=devstack-admin  # or another entry from your local 'clouds.yaml'
❯ go run .

This should dump something like the following.

servers:
  server 0: id=395b60b4-73be-4ba4-a8a8-fdaa3fce57d5

This example also makes use of the gophercloud/utils library, to simplify authentication and the creation of clients. gophercloud itself also provides support for clouds.yaml files, but its slightly more verbose. If you wanted to skip utils, you could rewrite this like so:

package main

import (
	"context"
	"fmt"

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

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

	ao, eo, tlsConfig, err := clouds.Parse()
	if err != nil {
		fmt.Println(err)
		return
	}

	providerClient, err := config.NewProviderClient(ctx, ao, config.WithTLSConfig(tlsConfig))
	if err != nil {
		fmt.Println(err)
		return
	}

	client, err := openstack.NewComputeV2(ctx, providerClient, eo)

	// rest of code here ...
}

If you are working on Gophercloud itself, it can be helpful to use scripts like this to test your changes. If doing this, you can rely on the replace directive in go.mod to ensure your local clone of Gophercloud is used.

replace (
	github.com/gophercloud/gophercloud/v2 => /home/user/code/gophercloud
	github.com/gophercloud/utils/v2 => /home/user/code/utils
)

More information here.

openstacksdk (Python)

Create a new directory containing a single file, main.py, and add the following to it.

import openstack

def main():
    # We could configure the cloud manually but we don't. Instead we'll leave it unset causing openstacksdk to load the
    # cloud from the 'OS_CLOUD' environment variable.
    # conn = openstack.connect(cloud='devstack-admin')
    conn = openstack.connect()

    servers = conn.compute.servers()

    print('servers:')
    for i, server in enumerate(servers):
        print(f'  server {i}: id={server.id}')

if __name__ == '__main__':
    main()

Now create a virtual environment and install the dependencies.

❯ virtualenv .venv
❯ source .venv/bin/activate
❯ pip install openstacksdk

Finally, you can run the command.

❯ export OS_CLOUD=devstack-admin  # or another entry from your local 'clouds.yaml'
❯ python main.py

This should dump identical output to the Go-based script.

servers:
  server 0: id=395b60b4-73be-4ba4-a8a8-fdaa3fce57d5