cmd/bpa-operator/vendor/github.com/gophercloud/gophercloud/README.md

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