The Go ecosystem seems to lack a comprehensive cloud services API (at the time this README was first written). As both Go and cloud services are trending in many businesses, and with Go used increasingly in infrastructure, it seems like an odd omission. To fill this gap, Gophercloud provides a Go binding to OpenStack cloud APIs. Many providers offer many APIs that are compatible with OpenStack; thus, building your infrastructure automation projects around Openstack is a natural way to avoid vendor lock-in.
|
Warning
|
This library is still in the very early stages of development. Unless you want to contribute, it probably isn’t what you want. |
Gophercloud provides an Openstack-compatible SDK binding to the Go community. As such, to either use it or contribute code, you’ll need to have Go installed. Please refer to the Go installation instructions for detailed steps to install the latest stable release of Go.
To use or contribute to Gophercloud, you’ll need some passing familiarity with Go, and how it uses certain concepts. If you’ve never worked with Go before, I strongly encourage the interested reader to follow through the excellent online book titled Effective Go.
|
Important
|
Please do not just clone this repository expecting it to work like any other Python, Ruby, Java, or C/C++ repo. Go packages don’t work that way! (You did read Effective Go, right?) |
Assuming you have a project underway already and its $GOPATH environment variable holds the correct path, you can include the Gophercloud package in the usual manner using go get:
go get github.com/rackspace/gophercloud
The remainder of this document, and supporting materials, assumes a correct $GOPATH configuration, but further assumes that an environment variable $GOPHERCLOUD points to the Gophercloud installation directory as well. E.g.,
export GOPHERCLOUD=$GOPATH/src/github.com/rackspace/gophercloud
If you’re just starting out with Go, a convenience script exists which lets you create a new Go workspace preconfigured with Gophercloud for you.
You can execute the following command to create a brand new Go workspace that is minimally configured for use with Gophercloud. This should work for any reasonable POSIX-compatible environment. source <(curl "https://raw.github.com/rackspace/Gophercloud/master/scripts/create-env.sh")
This script will not only install the software, but also create a shell script env.sh which, when executed, restores both $GOPATH and $GOPHERCLOUD to their correct values. The project will be installed in $HOME/go/gophercloud.
You should follow these steps to make sure your local installation works as expected.
export SDK_USERNAME=jack_frost (1) export SDK_PROVIDER=santa-telecom (2) SDK_PASSWORD=c0ldnbr33zy $GOPHERCLOUD/scripts/test-all.sh (3)
-
Use your cloud provider’s API user name.
-
Use your provider’s unique Gophercloud identifier. This is how Gophercloud will know which API endpoints to use.
-
Do not export your password unless you don’t care that it may reside in memory after the tests have all run. You might want to remove it from your shell’s history file afterwards too.
If everything goes well, you should only see output indicating the Go commands for each of the acceptance tests being run. Errors can be caused by several factors:
-
Your provider diverges from established Openstack standards.
-
Gophercloud incorrectly implements the relevant Openstack standards.
-
Mistake in setting up the
SDK_*environment variables above.
If a problem occurs, we’d love to hear about it in the issue tracker!
Simply list Gophercloud in the import section of relevant source listings, and you will be able to issue cloud requests through Gophercloud. For examples, either refer to the detailed SDK documentation, or take a look at the acceptance-level tests in the acceptance subdirectory.
After using Gophercloud for a while, you might find that it lacks some useful feature, or that existing behavior seems buggy. We welcome contributions from our users for both missing functionality as well as for bug fixes.
After installing Gophercloud and after running its env.sh script (only needed once per shell session), you will find the source files in the $GOPHERCLOUD directory. Feel free to open your favorite editor inside that directory and poke around.
Features and bug-fixes must appear on their own feature branches, even if you fork the Gophercloud repository. The name of the branch should be fairly descriptive, but try to avoid verbosity for verbosity’s sake. Examples of good feature branch names include:
script-environment-setup server-creation issue-43-memory-leak-fix
Some examples of not-so-good branch names include:
cloud-server-api-server-creation-endpoint-support (1) tk (2) anything/with/slashes (3)
-
This branch name is lengthy without delivering much value.
-
This branch name is too short to be useful to anyone other than the submitter.
-
This branch name exacerbates some Git usability issues, where some commands separate origins from branch names using slashes and others do not. Thus, using these kinds of branch names increases chances for easily preventable errors.
For example, if you’re looking to fix a memory leak that is documented in, just to pick a number, issue 42, you might follow a sequence of commands such as the following:
cd $GOPHERCLOUD git checkout working git checkout -b issue-42-fix-memory-leak # edit edit edit ... # commits happen here ... git push -u origin issue-42-fix-memory-leak
At this point, you may now switch to the GitHub user interface, and open a pull-request for the feature branch. This pull request should be descriptive. Basically, you want to give a small code walkthrough in the pull request summary. You should be able to answer, at a minimum, four basic questions, as appropriate for the nature of the patch:
-
What is the problem?
-
Why is it a problem?
-
What is your solution?
-
How does your solution actually work?
Here’s a made-up example:
Fix memory leak detailed in issue #42. The Rackspace provider interface tended to leak memory every fifth Saturday of February. Over the course of several decades, we find we run out of memory. Killing and restarting the process periodically restores service, but is a burden on the ops team. This PR fixes this bug permanently. The barProvider structure found in provider/barisp.go defines a FooSet as a slice, as seen on line 314. Per services/auth/keystone2.go line 628, Keystone authentication only ever uses the first three elements of this FooSet. Line 42 shows where FooSet is initialized to an empty slice, but on line 512, we see a function that appends to this slice unconditionally. I'm not sure where the logic exists to determine where this function is called; so, I've adjusted the provider/barisp.go file to truncate this FooSet to only three items, maximum on behalf of the caller. This seems to solve the problem in my test cases. See included tests.
Obviously, please use common sense! In situations where these questions do not apply, please don’t make up filler information.
|
Note
|
All bug-fix PRs MUST reference at least one open issue. New feature PRs SHOULD reference at least one open issue. This convention helps track why certain code is written the way it is, and maintains historical context. Lengthy design discussions should be moved to the gophercloud-dev mailing list if they occur; links to appropriate discussions should be made in the issue, again to maintain context. |
|
Tip
|
You may elide answers to the questions above if the answers already appear in the referenced PR(s), issues, or mailing list discussions. We care that the answers exist and may be easily found, not so much about where the answers may be found. |
Many projects will happily let you create a feature branch off the master branch. However, Go environments place special significance on master branches of packages. Because the go get command is not intended to perform complete package management tasks, but merely serve as a convenience for establishing your Go work environment, it will always fetch from the master branch of any repository you specify. Therefore, the master branch MUST always represent a customer-installable package. Not only that, but interface changes must be backward compatible at all times.
To facilitate development efforts, then, we maintain a working branch. New features and bug fixes merge into the working branch, where it remains staged for some future release date. Ideally, every push to github and every merge to working should kick off a batch of tests to validate the product still works. Assuming that working tests all pass, and your features or bug-fixes are both code- and feature-complete, then and only then should working be merged into master.