Xnode::Keystone

xnode-keystone provides methods that allow you to interact with the Keystone Identity service provided by an OpenStack cloud. It covers your authentication, as well as retrieving other OpenStack API endpoints exposed by your cloud administrators.

Installation

Add this line to your application's Gemfile:

gem 'xnode-keystone'

And then execute:

$ bundle

Or install it yourself as:

$ gem install xnode-keystone

Usage

Basic usage is as follows. You need to have an openrc file somewhere that looks something like this:

export OS_USERNAME=demo
export OS_PASSWORD=supas33krit
export OS_TENANT_NAME=Demo
export OS_AUTH_URL=https://controller:5000/v2.0
export OS_AUTH_URL=https://controller:5000/v3

Source it with . openrc.sh to load the environment variables. xnode-keystone needs these to find your creds.

There are modules for both v2.0 and v3 of the Keystone Identity service. These are called as follows:

For v2.0:

Xnode::Keystone::V2::Authenticate.new

and for v3:

Xnode::Keystone::V3::Authenticate.new

Below is an example that is for V2:

require 'xnode/keystone'

# Initialise a new instance of the base class
auth = Xnode::Keystone::V2::Authenticate.new

# Send an authentication request, and get a JSON response back that's been decoded bash into a Hash
request = auth.request

# To extract a token from the request...
token = auth.get_token(request)

# And to get the public compute API endpoint back...
endpoints = auth.catalog(request)
compute = endpoints['compute']['public']

# If you want a list of tenants...
keystone = endpoints['identity']['public']
tenants = auth.tenants(keystone, token)

And finally, an example for V3:

require 'xnode/keystone'

# Initialise a new instance of the base class
auth = Xnode::Keystone::V3::Authenticate.new

# Send an authentication request, and get a JSON response back that's been decoded bash into a Hash
request = auth.request

# To extract a token from the request...
token = auth.get_token

# And to get the public compute API endpoint back...
endpoints = auth.catalog(request)
compute = endpoints['compute']['public']

# If you want a list of tenants...
keystone = endpoints['identity']['public']
tenants = auth.tenants(keystone, token)

Both are almost syntactically identical, but require some tweaks internally to manipulate the way that the data needed is returned to the user. The major difference is in the get_token method. In V2, you need to pass in the response body, as the token is contained within the JSON response returned by the API. In V3, you just need to call the method without any parameters, as the token is actually returned as a header in the form of X-Subject-Token, which I just write to an instance variable, which is accessed by get_token when called.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/xnoder/xnode-keystone.

License

The gem is available as open source under the terms of the MIT License.