1# Gophercloud: an OpenStack SDK for Go 2[![Build Status](https://travis-ci.org/gophercloud/gophercloud.svg?branch=master)](https://travis-ci.org/gophercloud/gophercloud) 3[![Coverage Status](https://coveralls.io/repos/github/gophercloud/gophercloud/badge.svg?branch=master)](https://coveralls.io/github/gophercloud/gophercloud?branch=master) 4 5Gophercloud is an OpenStack Go SDK. 6 7## Useful links 8 9* [Reference documentation](http://godoc.org/github.com/gophercloud/gophercloud) 10* [Effective Go](https://golang.org/doc/effective_go.html) 11 12## How to install 13 14Before installing, you need to ensure that your [GOPATH environment variable](https://golang.org/doc/code.html#GOPATH) 15is pointing to an appropriate directory where you want to install Gophercloud: 16 17```bash 18mkdir $HOME/go 19export GOPATH=$HOME/go 20``` 21 22To protect yourself against changes in your dependencies, we highly recommend choosing a 23[dependency management solution](https://github.com/golang/go/wiki/PackageManagementTools) for 24your projects, such as [godep](https://github.com/tools/godep). Once this is set up, you can install 25Gophercloud as a dependency like so: 26 27```bash 28go get github.com/gophercloud/gophercloud 29 30# Edit your code to import relevant packages from "github.com/gophercloud/gophercloud" 31 32godep save ./... 33``` 34 35This will install all the source files you need into a `Godeps/_workspace` directory, which is 36referenceable from your own source files when you use the `godep go` command. 37 38## Getting started 39 40### Credentials 41 42Because you'll be hitting an API, you will need to retrieve your OpenStack 43credentials and either store them as environment variables or in your local Go 44files. The first method is recommended because it decouples credential 45information from source code, allowing you to push the latter to your version 46control system without any security risk. 47 48You will need to retrieve the following: 49 50* username 51* password 52* a valid Keystone identity URL 53 54For users that have the OpenStack dashboard installed, there's a shortcut. If 55you visit the `project/access_and_security` path in Horizon and click on the 56"Download OpenStack RC File" button at the top right hand corner, you will 57download a bash file that exports all of your access details to environment 58variables. To execute the file, run `source admin-openrc.sh` and you will be 59prompted for your password. 60 61### Authentication 62 63> NOTE: It is now recommended to use the `clientconfig` package found at 64> https://github.com/gophercloud/utils/tree/master/openstack/clientconfig 65> for all authentication purposes. 66> 67> The below documentation is still relevant. clientconfig simply implements 68> the below and presents it in an easier and more flexible way. 69 70Once you have access to your credentials, you can begin plugging them into 71Gophercloud. The next step is authentication, and this is handled by a base 72"Provider" struct. To get one, you can either pass in your credentials 73explicitly, or tell Gophercloud to use environment variables: 74 75```go 76import ( 77 "github.com/gophercloud/gophercloud" 78 "github.com/gophercloud/gophercloud/openstack" 79 "github.com/gophercloud/gophercloud/openstack/utils" 80) 81 82// Option 1: Pass in the values yourself 83opts := gophercloud.AuthOptions{ 84 IdentityEndpoint: "https://openstack.example.com:5000/v2.0", 85 Username: "{username}", 86 Password: "{password}", 87} 88 89// Option 2: Use a utility function to retrieve all your environment variables 90opts, err := openstack.AuthOptionsFromEnv() 91``` 92 93Once you have the `opts` variable, you can pass it in and get back a 94`ProviderClient` struct: 95 96```go 97provider, err := openstack.AuthenticatedClient(opts) 98``` 99 100The `ProviderClient` is the top-level client that all of your OpenStack services 101derive from. The provider contains all of the authentication details that allow 102your Go code to access the API - such as the base URL and token ID. 103 104### Provision a server 105 106Once we have a base Provider, we inject it as a dependency into each OpenStack 107service. In order to work with the Compute API, we need a Compute service 108client; which can be created like so: 109 110```go 111client, err := openstack.NewComputeV2(provider, gophercloud.EndpointOpts{ 112 Region: os.Getenv("OS_REGION_NAME"), 113}) 114``` 115 116We then use this `client` for any Compute API operation we want. In our case, 117we want to provision a new server - so we invoke the `Create` method and pass 118in the flavor ID (hardware specification) and image ID (operating system) we're 119interested in: 120 121```go 122import "github.com/gophercloud/gophercloud/openstack/compute/v2/servers" 123 124server, err := servers.Create(client, servers.CreateOpts{ 125 Name: "My new server!", 126 FlavorRef: "flavor_id", 127 ImageRef: "image_id", 128}).Extract() 129``` 130 131The above code sample creates a new server with the parameters, and embodies the 132new resource in the `server` variable (a 133[`servers.Server`](http://godoc.org/github.com/gophercloud/gophercloud) struct). 134 135## Advanced Usage 136 137Have a look at the [FAQ](./docs/FAQ.md) for some tips on customizing the way Gophercloud works. 138 139## Backwards-Compatibility Guarantees 140 141None. Vendor it and write tests covering the parts you use. 142 143## Contributing 144 145See the [contributing guide](./.github/CONTRIBUTING.md). 146 147## Help and feedback 148 149If you're struggling with something or have spotted a potential bug, feel free 150to submit an issue to our [bug tracker](https://github.com/gophercloud/gophercloud/issues). 151 152## Thank You 153 154We'd like to extend special thanks and appreciation to the following: 155 156### OpenLab 157 158<a href="http://openlabtesting.org/"><img src="./docs/assets/openlab.png" width="600px"></a> 159 160OpenLab is providing a full CI environment to test each PR and merge for a variety of OpenStack releases. 161 162### VEXXHOST 163 164<a href="https://vexxhost.com/"><img src="./docs/assets/vexxhost.png" width="600px"></a> 165 166VEXXHOST is providing their services to assist with the development and testing of Gophercloud. 167