From 184377af0358b148081f277b4c42cdb286896d4a Mon Sep 17 00:00:00 2001 From: Mark Maglana Date: Sun, 22 Sep 2013 01:51:38 -0700 Subject: [PATCH] Update README, homepage spec, and remove extraneous file --- README.md | 205 +-------------------------------------------- README.md.orig | 217 ------------------------------------------------ aviator.gemspec | 2 +- 3 files changed, 2 insertions(+), 422 deletions(-) delete mode 100644 README.md.orig diff --git a/README.md b/README.md index 6d0d9dc..360e904 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ ![Aviator](https://raw.github.com/aviator/www/gh-pages/images/logo-small.png)
A lightweight library for communicating with the OpenStack API. -## Project Stats - [![Build Status](https://travis-ci.org/aviator/aviator.png?branch=master)](https://travis-ci.org/aviator/aviator) [![Coverage Status](https://coveralls.io/repos/aviator/aviator/badge.png?branch=master)](https://coveralls.io/r/aviator/aviator?branch=master) [![Code Climate](https://codeclimate.com/github/aviator/aviator.png)](https://codeclimate.com/github/aviator/aviator) @@ -10,205 +8,4 @@ [![Dependency Status](https://gemnasium.com/aviator/aviator.png)](https://gemnasium.com/aviator/aviator) -## Installation - -Add this line to your application's Gemfile: - - gem 'aviator' - -Or if you want to live on the edge: - - gem 'aviator', :git => 'git@github.com:aviator/aviator.git', :branch => 'develop' - -And then execute: - - $ bundle - -Or install it yourself as: - - $ gem install aviator - -## Usage - -```ruby -require 'aviator' - -# Create a new session. See 'Configuration' below for the config file format. -session = Aviator::Session.new( - config_file: 'path/to/aviator.yml', - environment: :production, - log_file: 'path/to/aviator.log' - ) - -# Authenticate against the auth service specified in :config_file. If no -# credentials are available in the config file, this line will throw an error. -session.authenticate - -# You can re-authenticate anytime. Note that this creates a new token in the -# underlying environment while the old token is discarded by the Session object. -# Be aware of this fact as it might unnecessarily generate too many tokens. -# -# Notice how you can override the credentials in the config file. Also note that -# the keys used below (:username, :password, :tenantName) match the name as -# indicated in the official OpenStack documentation. -session.authenticate do |credentials| - credentials[:username] = myusername - credentials[:password] = mypassword - credentials[:tenantName] = tenantName -end - -# Serialize the session information for caching. The output is in plaintext JSON which -# contains sensitive information. You are responsible for securing that. -str = session.dump - -# Create a new Session object from a session dump. This DOES NOT create a new token. -# If you employed any form of encryption on the string, make sure to decrypt it first! -session = Aviator::Session.load(str) - -# In some instances, Session::load is inefficient because it creates a new session object -# each time. In a web app environment, for instance, having to destroy and recreate the -# session object can take its toll on performance. In such a scenario, use Session#load -# (instance method, as opposed to class method). This will 'infect' an already existing -# session object with the supplied session dump and return itself instead of creating -# a brand new session object. -session.load(other_session_dump) - -# Depending on how old the loaded session dump is, its session data may already be expired. -# Check if it's still current by calling Session#validate and reauthenticate as needed. -# -# IMPORTANT: The validator must be defined in the config file and it must refer to the -# name of a request that is known to Aviator. See 'Configuration' below for examples -session.authenticate unless session.validate - -# If you want the newly created session to log its output, make sure to indicate it on load -session = Aviator::Session.load(str, log_file: 'path/to/aviator.log') - -# Get a handle to the Identity Service. -keystone = session.identity_service - -# Create a new tenant -response = keystone.request(:create_tenant) do |params| - params[:name] = 'Project' - params[:description] = 'My Project' - params[:enabled] = true -end - -# Aviator uses parameter names as defined in the official OpenStack API doc. You can -# also access the params via dot notation (e.g. params.description) or by using a string -# for a hash key (e.g. params['description']). However, keep in mind that OpenStack -# parameters that have dashes and other characters that are not valid for method names -# and symbols can only be expressed as strings. E.g. params['changes-since'] - - -# Be explicit about the endpoint type. Useful in those rare instances when -# the same request name means differently depending on the endpoint type. -# For example, in OpenStack, :list_tenants will return only the tenants the -# user is a member of in the public endpoint whereas the admin endpoint will -# return all tenants in the system. -response = keystone.request(:list_tenants, endpoint_type: 'admin') -``` - -## Configuration - -The configuration file is a simple YAML file that can have one or more environment definitions. - -``` -production: - provider: openstack - auth_service: - name: identity - host_uri: http://my.openstackenv.org:5000 - request: create_token - validator: list_tenants # Request to make for validating the session - api_version: v2 # Optional if version is indicated in host_uri - auth_credentials: - username: admin - password: mypassword - tenantName: myproject - -development_1: - provider: openstack - auth_service: - name: identity - host_uri: http://devstack:5000/v2.0 - request: create_token - validator: list_tenants - auth_credentials: - tokenId: 2c963f5512d067b24fdc312707c80c7a6d3d261b - tenantName: admin - -development_2: - provider: openstack - auth_service: - name: identity - host_uri: http://devstack:5000/v2.0 - request: create_token - validator: list_tenants - auth_credentials: - username: admin - password: mypassword - tenantName: myproject -``` - -A note on the validator: it can be any request as long as - -1. It is defined in Aviator -1. Does not require any parameters -1. It returns an HTTP status 200 or 203 to indicate auth info validity. -1. It returns any other HTTP status to indicate that the auth info is invalid. - -## CLI tools - -List available providers. Includes only OpenStack for now. - -```bash -$ aviator describe -``` - -List available services for OpenStack. - -```bash -$ aviator describe openstack -``` - -List available requests for Keystone - -```bash -$ aviator describe openstack identity -``` - -Describe Keystone's create_tenant request - -```bash -$ aviator describe openstack identity v2 admin create_tenant -``` - -The last command above will display: - -```bash -Request: create_tenant - -Parameters: - (required) description - (required) enabled - (required) name - -Sample Code: - session.identity_service.request(:create_tenant, endpoint_type: 'admin') do |params| - params['name'] = value - params['description'] = value - params['enabled'] = value - end - -Links: - documentation: - http://docs.openstack.org/api/openstack-identity-service/2.0/content/ -``` - -## Contributing - -1. Fork it -2. Create your feature branch (`git checkout -b my-new-feature`) -3. Commit your changes (`git commit -am 'Add some feature'`) -4. Push to the branch (`git push origin my-new-feature`) -5. Create new Pull Request +Usage and Installation \ No newline at end of file diff --git a/README.md.orig b/README.md.orig deleted file mode 100644 index fee8b1c..0000000 --- a/README.md.orig +++ /dev/null @@ -1,217 +0,0 @@ -# Aviator - -[![Build Status](https://travis-ci.org/aviator/aviator.png?branch=master)](https://travis-ci.org/aviator/aviator) -[![Coverage Status](https://coveralls.io/repos/aviator/aviator/badge.png?branch=master)](https://coveralls.io/r/aviator/aviator?branch=master) -[![Code Climate](https://codeclimate.com/github/aviator/aviator.png)](https://codeclimate.com/github/aviator/aviator) -[![Gem Version](https://badge.fury.io/rb/aviator.png)](http://badge.fury.io/rb/aviator) -[![Dependency Status](https://gemnasium.com/aviator/aviator.png)](https://gemnasium.com/aviator/aviator) -<<<<<<< HEAD - -======= ->>>>>>> develop - -A lightweight library for communicating with the OpenStack API. - - -## Installation - -Add this line to your application's Gemfile: - - gem 'aviator' - -Or if you want to live on the edge: - - gem 'aviator', :git => 'git@github.com:aviator/aviator.git', :branch => 'develop' - -And then execute: - - $ bundle - -Or install it yourself as: - - $ gem install aviator - -## Usage - -```ruby -require 'aviator' - -# Create a new session. See 'Configuration' below for the config file format. -session = Aviator::Session.new( - config_file: 'path/to/aviator.yml', - environment: :production, - log_file: 'path/to/aviator.log' - ) - -# Authenticate against the auth service specified in :config_file. If no -# credentials are available in the config file, this line will throw an error. -session.authenticate - -# You can re-authenticate anytime. Note that this creates a new token in the -# underlying environment while the old token is discarded by the Session object. -# Be aware of this fact as it might unnecessarily generate too many tokens. -# -# Notice how you can override the credentials in the config file. Also note that -# the keys used below (:username, :password, :tenantName) match the name as -# indicated in the official OpenStack documentation. -session.authenticate do |credentials| - credentials[:username] = myusername - credentials[:password] = mypassword - credentials[:tenantName] = tenantName -end - -# Serialize the session information for caching. The output is in plaintext JSON which -# contains sensitive information. You are responsible for securing that. -str = session.dump - -# Create a new Session object from a session dump. This DOES NOT create a new token. -# If you employed any form of encryption on the string, make sure to decrypt it first! -session = Aviator::Session.load(str) - -# In some instances, Session::load is inefficient because it creates a new session object -# each time. In a web app environment, for instance, having to destroy and recreate the -# session object can take its toll on performance. In such a scenario, use Session#load -# (instance method, as opposed to class method). This will 'infect' an already existing -# session object with the supplied session dump and return itself instead of creating -# a brand new session object. -session.load(other_session_dump) - -# Depending on how old the loaded session dump is, its session data may already be expired. -# Check if it's still current by calling Session#validate and reauthenticate as needed. -# -# IMPORTANT: The validator must be defined in the config file and it must refer to the -# name of a request that is known to Aviator. See 'Configuration' below for examples -session.authenticate unless session.validate - -# If you want the newly created session to log its output, make sure to indicate it on load -session = Aviator::Session.load(str, log_file: 'path/to/aviator.log') - -# Get a handle to the Identity Service. -keystone = session.identity_service - -# Create a new tenant -response = keystone.request(:create_tenant) do |params| - params[:name] = 'Project' - params[:description] = 'My Project' - params[:enabled] = true -end - -# Aviator uses parameter names as defined in the official OpenStack API doc. You can -# also access the params via dot notation (e.g. params.description) or by using a string -# for a hash key (e.g. params['description']). However, keep in mind that OpenStack -# parameters that have dashes and other characters that are not valid for method names -# and symbols can only be expressed as strings. E.g. params['changes-since'] - - -# Be explicit about the endpoint type. Useful in those rare instances when -# the same request name means differently depending on the endpoint type. -# For example, in OpenStack, :list_tenants will return only the tenants the -# user is a member of in the public endpoint whereas the admin endpoint will -# return all tenants in the system. -response = keystone.request(:list_tenants, endpoint_type: 'admin') -``` - -## Configuration - -The configuration file is a simple YAML file that can have one or more environment definitions. - -``` -production: - provider: openstack - auth_service: - name: identity - host_uri: http://my.openstackenv.org:5000 - request: create_token - validator: list_tenants # Request to make for validating the session - api_version: v2 # Optional if version is indicated in host_uri - auth_credentials: - username: admin - password: mypassword - tenantName: myproject - -development_1: - provider: openstack - auth_service: - name: identity - host_uri: http://devstack:5000/v2.0 - request: create_token - validator: list_tenants - auth_credentials: - tokenId: 2c963f5512d067b24fdc312707c80c7a6d3d261b - tenantName: admin - -development_2: - provider: openstack - auth_service: - name: identity - host_uri: http://devstack:5000/v2.0 - request: create_token - validator: list_tenants - auth_credentials: - username: admin - password: mypassword - tenantName: myproject -``` - -A note on the validator: it can be any request as long as - -1. It is defined in Aviator -1. Does not require any parameters -1. It returns an HTTP status 200 or 203 to indicate auth info validity. -1. It returns any other HTTP status to indicate that the auth info is invalid. - -## CLI tools - -List available providers. Includes only OpenStack for now. - -```bash -$ aviator describe -``` - -List available services for OpenStack. - -```bash -$ aviator describe openstack -``` - -List available requests for Keystone - -```bash -$ aviator describe openstack identity -``` - -Describe Keystone's create_tenant request - -```bash -$ aviator describe openstack identity v2 admin create_tenant -``` - -The last command above will display: - -```bash -Request: create_tenant - -Parameters: - (required) description - (required) enabled - (required) name - -Sample Code: - session.identity_service.request(:create_tenant, endpoint_type: 'admin') do |params| - params['name'] = value - params['description'] = value - params['enabled'] = value - end - -Links: - documentation: - http://docs.openstack.org/api/openstack-identity-service/2.0/content/ -``` - -## Contributing - -1. Fork it -2. Create your feature branch (`git checkout -b my-new-feature`) -3. Commit your changes (`git commit -am 'Add some feature'`) -4. Push to the branch (`git push origin my-new-feature`) -5. Create new Pull Request diff --git a/aviator.gemspec b/aviator.gemspec index ed3f15e..bf7718d 100644 --- a/aviator.gemspec +++ b/aviator.gemspec @@ -10,7 +10,7 @@ Gem::Specification.new do |spec| spec.email = ["mmaglana@gmail.com"] spec.description = %q{ A lightweight Ruby library for the OpenStack API } spec.summary = %q{ A lightweight Ruby library for the OpenStack API } - spec.homepage = "https://github.com/aviator/aviator" + spec.homepage = "http://aviator.github.io/www/" spec.license = "MIT" spec.files = `git ls-files`.split($/)