|
Packit |
63bb0d |
# Gophercloud: an OpenStack SDK for Go
|
|
Packit |
63bb0d |
[![Build Status](https://travis-ci.org/gophercloud/gophercloud.svg?branch=master)](https://travis-ci.org/gophercloud/gophercloud)
|
|
Packit |
63bb0d |
[![Coverage Status](https://coveralls.io/repos/github/gophercloud/gophercloud/badge.svg?branch=master)](https://coveralls.io/github/gophercloud/gophercloud?branch=master)
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
Gophercloud is an OpenStack Go SDK.
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
## Useful links
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
* [Reference documentation](http://godoc.org/github.com/gophercloud/gophercloud)
|
|
Packit |
63bb0d |
* [Effective Go](https://golang.org/doc/effective_go.html)
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
## How to install
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
Before installing, you need to ensure that your [GOPATH environment variable](https://golang.org/doc/code.html#GOPATH)
|
|
Packit |
63bb0d |
is pointing to an appropriate directory where you want to install Gophercloud:
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
```bash
|
|
Packit |
63bb0d |
mkdir $HOME/go
|
|
Packit |
63bb0d |
export GOPATH=$HOME/go
|
|
Packit |
63bb0d |
```
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
To protect yourself against changes in your dependencies, we highly recommend choosing a
|
|
Packit |
63bb0d |
[dependency management solution](https://github.com/golang/go/wiki/PackageManagementTools) for
|
|
Packit |
63bb0d |
your projects, such as [godep](https://github.com/tools/godep). Once this is set up, you can install
|
|
Packit |
63bb0d |
Gophercloud as a dependency like so:
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
```bash
|
|
Packit |
63bb0d |
go get github.com/gophercloud/gophercloud
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
# Edit your code to import relevant packages from "github.com/gophercloud/gophercloud"
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
godep save ./...
|
|
Packit |
63bb0d |
```
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
This will install all the source files you need into a `Godeps/_workspace` directory, which is
|
|
Packit |
63bb0d |
referenceable from your own source files when you use the `godep go` command.
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
## Getting started
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
### Credentials
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
Because you'll be hitting an API, you will need to retrieve your OpenStack
|
|
Packit |
63bb0d |
credentials and either store them as environment variables or in your local Go
|
|
Packit |
63bb0d |
files. The first method is recommended because it decouples credential
|
|
Packit |
63bb0d |
information from source code, allowing you to push the latter to your version
|
|
Packit |
63bb0d |
control system without any security risk.
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
You will need to retrieve the following:
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
* username
|
|
Packit |
63bb0d |
* password
|
|
Packit |
63bb0d |
* a valid Keystone identity URL
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
For users that have the OpenStack dashboard installed, there's a shortcut. If
|
|
Packit |
63bb0d |
you visit the `project/access_and_security` path in Horizon and click on the
|
|
Packit |
63bb0d |
"Download OpenStack RC File" button at the top right hand corner, you will
|
|
Packit |
63bb0d |
download a bash file that exports all of your access details to environment
|
|
Packit |
63bb0d |
variables. To execute the file, run `source admin-openrc.sh` and you will be
|
|
Packit |
63bb0d |
prompted for your password.
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
### Authentication
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
Once you have access to your credentials, you can begin plugging them into
|
|
Packit |
63bb0d |
Gophercloud. The next step is authentication, and this is handled by a base
|
|
Packit |
63bb0d |
"Provider" struct. To get one, you can either pass in your credentials
|
|
Packit |
63bb0d |
explicitly, or tell Gophercloud to use environment variables:
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
```go
|
|
Packit |
63bb0d |
import (
|
|
Packit |
63bb0d |
"github.com/gophercloud/gophercloud"
|
|
Packit |
63bb0d |
"github.com/gophercloud/gophercloud/openstack"
|
|
Packit |
63bb0d |
"github.com/gophercloud/gophercloud/openstack/utils"
|
|
Packit |
63bb0d |
)
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
// Option 1: Pass in the values yourself
|
|
Packit |
63bb0d |
opts := gophercloud.AuthOptions{
|
|
Packit |
63bb0d |
IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
|
|
Packit |
63bb0d |
Username: "{username}",
|
|
Packit |
63bb0d |
Password: "{password}",
|
|
Packit |
63bb0d |
}
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
// Option 2: Use a utility function to retrieve all your environment variables
|
|
Packit |
63bb0d |
opts, err := openstack.AuthOptionsFromEnv()
|
|
Packit |
63bb0d |
```
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
Once you have the `opts` variable, you can pass it in and get back a
|
|
Packit |
63bb0d |
`ProviderClient` struct:
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
```go
|
|
Packit |
63bb0d |
provider, err := openstack.AuthenticatedClient(opts)
|
|
Packit |
63bb0d |
```
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
The `ProviderClient` is the top-level client that all of your OpenStack services
|
|
Packit |
63bb0d |
derive from. The provider contains all of the authentication details that allow
|
|
Packit |
63bb0d |
your Go code to access the API - such as the base URL and token ID.
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
### Provision a server
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
Once we have a base Provider, we inject it as a dependency into each OpenStack
|
|
Packit |
63bb0d |
service. In order to work with the Compute API, we need a Compute service
|
|
Packit |
63bb0d |
client; which can be created like so:
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
```go
|
|
Packit |
63bb0d |
client, err := openstack.NewComputeV2(provider, gophercloud.EndpointOpts{
|
|
Packit |
63bb0d |
Region: os.Getenv("OS_REGION_NAME"),
|
|
Packit |
63bb0d |
})
|
|
Packit |
63bb0d |
```
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
We then use this `client` for any Compute API operation we want. In our case,
|
|
Packit |
63bb0d |
we want to provision a new server - so we invoke the `Create` method and pass
|
|
Packit |
63bb0d |
in the flavor ID (hardware specification) and image ID (operating system) we're
|
|
Packit |
63bb0d |
interested in:
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
```go
|
|
Packit |
63bb0d |
import "github.com/gophercloud/gophercloud/openstack/compute/v2/servers"
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
server, err := servers.Create(client, servers.CreateOpts{
|
|
Packit |
63bb0d |
Name: "My new server!",
|
|
Packit |
63bb0d |
FlavorRef: "flavor_id",
|
|
Packit |
63bb0d |
ImageRef: "image_id",
|
|
Packit |
63bb0d |
}).Extract()
|
|
Packit |
63bb0d |
```
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
The above code sample creates a new server with the parameters, and embodies the
|
|
Packit |
63bb0d |
new resource in the `server` variable (a
|
|
Packit |
63bb0d |
[`servers.Server`](http://godoc.org/github.com/gophercloud/gophercloud) struct).
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
## Advanced Usage
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
Have a look at the [FAQ](./docs/FAQ.md) for some tips on customizing the way Gophercloud works.
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
## Backwards-Compatibility Guarantees
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
None. Vendor it and write tests covering the parts you use.
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
## Contributing
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
See the [contributing guide](./.github/CONTRIBUTING.md).
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
## Help and feedback
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
If you're struggling with something or have spotted a potential bug, feel free
|
|
Packit |
63bb0d |
to submit an issue to our [bug tracker](https://github.com/gophercloud/gophercloud/issues).
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
## Thank You
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
We'd like to extend special thanks and appreciation to the following:
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
### OpenLab
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
OpenLab is providing a full CI environment to test each PR and merge for a variety of OpenStack releases.
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
### VEXXHOST
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
|
|
Packit |
63bb0d |
VEXXHOST is providing their services to assist with the development and testing of Gophercloud.
|