Gophercloud: an OpenStack SDK for Go
Branch: master
Clone or download
stbenjam and jtopjian Baremetal V1 API: Node management (#1450)
* Baremetal V1 API: Node management

* Addressed comments

* Add missing newline
Latest commit dcc6e84 Feb 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update PULL_REQUEST_TEMPLATE May 31, 2018
.zuul/playbooks Enable neutron trunk extension in integration tests Oct 30, 2018
acceptance Baremetal API: noauth support (#1449) Feb 15, 2019
docs Docs: Adding Microversion documentation (#1320) Jan 26, 2019
internal add NewLoadBalancerV2 service client (#591) Nov 3, 2017
openstack Baremetal V1 API: Node management (#1450) Feb 16, 2019
pagination Do not fetch twice the first page Jun 21, 2018
script Core: Reauth Concurrency fixes (#1435) Feb 4, 2019
testhelper Fix testhelper.deepDiffEqual (#374) Jun 11, 2017
testing Core: Reauth Concurrency fixes (#1435) Feb 4, 2019
.gitignore ignore .vscode May 4, 2018
.travis.yml Enable go modules (#1448) Feb 12, 2019
.zuul.yaml Support acceptance test against OpenStack Rocky release (#1238) Oct 30, 2018
CHANGELOG.md merge lbaasv2, portsbinding, volumes v2; remove 'rackspace' refs; upd… Jul 12, 2016
LICENSE Added missing license, contributors file Aug 13, 2013
README.md Update README.md (#1183) Aug 14, 2018
auth_options.go Auth: update application credential requirements logic (#1419) Jan 25, 2019
auth_result.go fix example code for type AuthResult (#1439) Feb 6, 2019
doc.go Amend example code (#1369) Dec 20, 2018
endpoint_search.go Docs: Top level doc updates (#450) Aug 11, 2017
errors.go Add support to authenticate with application credential Sep 17, 2018
go.mod Enable go modules (#1448) Feb 12, 2019
go.sum Enable go modules (#1448) Feb 12, 2019
params.go BuildRequestQuery to check slice of struct fields Oct 11, 2018
provider_client.go add gophercloud.AuthResult (#1226) Feb 6, 2019
results.go Core: Fix Unchecked Type Assertion (#1305) Oct 25, 2018
service_client.go Baremetal v1 API: Nodes (#1431) Feb 12, 2019
util.go Refactor WaitFor (#221) Feb 14, 2017

README.md

Gophercloud: an OpenStack SDK for Go

Build Status Coverage Status

Gophercloud is an OpenStack Go SDK.

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

# Edit your code to import relevant packages from "github.com/gophercloud/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
  • 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/gophercloud/gophercloud"
  "github.com/gophercloud/gophercloud/openstack"
  "github.com/gophercloud/gophercloud/openstack/utils"
)

// Option 1: Pass in the values yourself
opts := gophercloud.AuthOptions{
  IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
  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)

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/gophercloud/gophercloud/openstack/compute/v2/servers"

server, err := servers.Create(client, 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 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

None. Vendor it and write tests covering the parts you use.

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.

Thank You

We'd like to extend special thanks and appreciation to the following:

OpenLab

OpenLab is providing a full CI environment to test each PR and merge for a variety of OpenStack releases.

VEXXHOST

VEXXHOST is providing their services to assist with the development and testing of Gophercloud.