A Go SDK for OpenStack. IN FEATURE FREEZE. See Issue #592
Go
Latest commit e00690e Oct 14, 2016 @jrperritt jrperritt Merge pull request #614 from MatMaul/rename_test_file
Rename request_tests.go to request_test.go
Permalink
Failed to load latest commit information.
acceptance imageservice: Rename Put|GetImageData() methods Jun 21, 2016
openstack Rename request_tests.go to request_test.go Oct 13, 2016
pagination return from AllPages for SinglePageBase May 2, 2016
rackspace another errant AuthenticatedHeaders call May 23, 2016
script Don't assume -v for acceptance tests. Oct 24, 2014
testhelper [WIP] OpenStack Glance support Jun 21, 2016
.travis.yml remove 'exec' from 'script' attribute Feb 23, 2016
CONTRIBUTING.md Updated docs to provide information about tags needed to run tests. Feb 13, 2016
CONTRIBUTORS.md Removing ServerID as a parameter from volumeattach Feb 7, 2015
LICENSE Added missing license, contributors file Aug 13, 2013
README.md show coveralls badge Feb 23, 2016
UPGRADING.md replace sdk-support email address with url Mar 16, 2015
auth_options.go comment about limiting the number of re-auth attempts Apr 16, 2016
auth_results.go Clarify some more internal/deprecated docs. Oct 31, 2014
doc.go Comments and missing words. Oct 31, 2014
endpoint_search.go Comments and missing words. Oct 31, 2014
endpoint_search_test.go apply defaults method unit test Oct 10, 2014
params.go alter BuildQuery to handle slices Feb 12, 2015
params_test.go alter BuildQuery to handle slices Feb 12, 2015
provider_client.go factor out repeated RawBody/JSONBody logic Jun 21, 2016
provider_client_test.go Remove leading "v" from user-agent string Apr 7, 2015
results.go Fix time format used for cloud orchestration Sep 9, 2015
service_client.go Embed the ProviderClient struct in ServiceClient. Oct 22, 2014
service_client_test.go ServiceURL unit test Oct 10, 2014
util.go Linting and comments fixes Sep 22, 2015
util_test.go Add template and environment parsing to gophercloud Sep 17, 2015

README.md

Gophercloud: an OpenStack SDK for Go

Build Status Coverage Status

Gophercloud is a flexible SDK that allows you to consume and work with OpenStack clouds in a simple and idiomatic way using golang. Many services are supported, including Compute, Block Storage, Object Storage, Networking, and Identity. Each service API is backed with getting started guides, code samples, reference documentation, unit tests and acceptance tests.

Useful links

How to install

Before installing, you need to ensure that your GOPATH environment variable is pointing to an appropriate directory where you want to install Gophercloud:

mkdir $HOME/go
export GOPATH=$HOME/go

To protect yourself against changes in your dependencies, we highly recommend choosing a dependency management solution for your projects, such as godep. Once this is set up, you can install Gophercloud as a dependency like so:

go get github.com/rackspace/gophercloud

# Edit your code to import relevant packages from "github.com/rackspace/gophercloud"

godep save ./...

This will install all the source files you need into a Godeps/_workspace directory, which is referenceable from your own source files when you use the godep go command.

Getting started

Credentials

Because you'll be hitting an API, you will need to retrieve your OpenStack credentials and either store them 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:

  • username
  • password
  • tenant name or tenant ID
  • a valid Keystone identity URL

For users that have the OpenStack dashboard installed, there's a shortcut. If you visit the project/access_and_security path in Horizon and click on the "Download OpenStack RC File" button at the top right hand corner, you will download a bash file that exports all of your access details to environment variables. To execute the file, run source admin-openrc.sh and you will be prompted for your password.

Authentication

Once you have access to your credentials, you can begin plugging them into Gophercloud. The next step is authentication, and this is handled by a base "Provider" struct. To get one, you can either pass in your credentials explicitly, or tell Gophercloud to use environment variables:

import (
  "github.com/rackspace/gophercloud"
  "github.com/rackspace/gophercloud/openstack"
  "github.com/rackspace/gophercloud/openstack/utils"
)

// Option 1: Pass in the values yourself
opts := gophercloud.AuthOptions{
  IdentityEndpoint: "https://my-openstack.com:5000/v2.0",
  Username: "{username}",
  Password: "{password}",
  TenantID: "{tenant_id}",
}

// 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)

The ProviderClient is the top-level client that all of your OpenStack services 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.

Provision a server

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

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

We then use this client for any Compute API operation we want. In our case, we want to provision a new server - so 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/rackspace/gophercloud/openstack/compute/v2/servers"

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

If you are unsure about what images and flavors are, you can read our Compute Getting Started guide. The above code sample creates a new server with the parameters, and embodies the new resource in the server variable (a servers.Server struct).

Next steps

Cool! You've handled authentication, got your ProviderClient and provisioned a new server. You're now ready to use more OpenStack services.

Contributing

Engaging the community and lowering barriers for contributors is something we care a lot about. For this reason, we've taken the time to write a contributing guide for folks interested in getting involved in our project. If you're not sure how you can get involved, feel free to submit an issue or contact us. You don't need to be a Go expert - all members of the community are welcome!

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 or contact us directly.