| commit | 4eb3f964933f90707da2cbfbbcb0ad67f4d6ac2f | [log] [tgz] |
|---|---|---|
| author | Jamie Hannaford <jamie.hannaford@rackspace.com> | Tue Oct 07 11:50:00 2014 +0200 |
| committer | Jamie Hannaford <jamie.hannaford@rackspace.com> | Tue Oct 07 11:50:00 2014 +0200 |
| tree | 8b3d6360e63344853c24ac51f3233ec9928eb191 | |
| parent | 6b3ac761e1e79c47fe09ee73cf8ee98cac53d278 [diff] |
Spring cleaning our README - adding relevant sections and community info
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 documentation, code samples, unit tests and acceptance tests.
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
Once this is set up, you can install the gophercloud package like so:
go get github.com/rackspace/gophercloud
This will install all the source files you need into a pkg directory, which is referenceable from your own source files.
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:
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.
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:
// 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 import "github.com/rackspace/gophercloud/openstack/utils" opts, err := utils.AuthOptions()
Once you have the opts variable, you can pass it in and get back a ProviderClient struct:
import "github.com/rackspace/gophercloud/openstack"
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.
Cool! You've handled authentication and got your ProviderClient. You're now ready to use an OpenStack service.
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 the project. If you're not sure what you can do to get involved, feel free to submit an issue or ping us an e-mail! You don't need to be a Go expert - all members of the community are welcome.
If you're struggling with something or have spotted a potential bug, feel free to submit an issue to our bug tracker or e-mail us directly at sdk-support@rackspace.com.