fog-rackspace 0.1.0

data/lib/fog/rackspace/docs/orchestration.md

@@ -0,0 +1,356 @@
+# OpenStack Orchestration
+The mission of the OpenStack Orchestration program is to create a human- and machine-accessible service for managing the entire lifecycle of infrastructure and applications within OpenStack clouds.
+
+## Heat
+Heat is the main project in the OpenStack Orchestration program. It implements an orchestration engine to launch multiple composite cloud applications based on templates in the form of text files that can be treated like code. A native Heat template format is evolving, but Heat also endeavours to provide compatibility with the AWS CloudFormation template format, so that many existing CloudFormation templates can be launched on OpenStack. Heat provides both an OpenStack-native ReST API and a CloudFormation-compatible Query API.
+
+*Why ‘Heat’? It makes the clouds rise!*
+
+**How it works**
+
+* A Heat template describes the infrastructure for a cloud application in a text file that is readable and writable by humans, and can be checked into version control, diffed, &c.
+* Infrastructure resources that can be described include: servers, floating ips, volumes, security groups, users, etc.
+* Heat also provides an autoscaling service that integrates with Ceilometer, so you can include a scaling group as a resource in a template.
+* Templates can also specify the relationships between resources (e.g. this volume is connected to this server). This enables Heat to call out to the OpenStack APIs to create all of your infrastructure in the correct order to completely launch your application.
+* Heat manages the whole lifecycle of the application - when you need to change your infrastructure, simply modify the template and use it to update your existing stack. Heat knows how to make the necessary changes. It will delete all of the resources when you are finished with the application, too.
+* Heat primarily manages infrastructure, but the templates integrate well with software configuration management tools such as Puppet and Chef. The Heat team is working on providing even better integration between infrastructure and software.
+
+_Source: [OpenStack Wiki](https://wiki.openstack.org/wiki/Heat)_
+
+# Rackspace Orchestration (Heat) Client
+
+[Full Rackspace Orchestration/Heat API Docs](http://docs.rackspace.com/orchestration/api/v1/orchestration-devguide/content/API_Operations_dle7023.html)
+
+## Orchestration Service
+Get a handle on the Orchestration service:
+
+```ruby
+irb: service = Fog::Rackspace::Orchestration.new({
+	:rackspace_username => username,
+	:rackspace_api_key  => api_key,
+  	:rackspace_region   => :iad #:ord, :dfw, :syd
+})
+===> #<Fog::Rackspace::Orchestration::Real:2168274880 ...
+```
+We will use this `service` to interact with the Orchestration resources, `stack`, `event`,  `resource`, and `template`
+
+## Stacks
+
+Get a list of stacks you own:
+
+```ruby
+irb: service.stacks
+===>   <Fog::Rackspace::Orchestration::Stacks
+    []
+  >
+```
+
+Create a new `stack` with a [Heat Template (HOT)](http://docs.openstack.org/developer/heat/template_guide/hot_guide.html). Here we are using Rackspace's HOT for [a single redis server]("https://github.com/rackspace-orchestration-templates/redis-single/blob/master/redis-single.yaml"):
+
+```ruby
+redis_template = File.read("spec/support/redis_template.yml")
+===> "heat_template_version: 2013-05-23\n\ndescription: ....
+
+irb:  service.stacks.new.save({
+		:stack_name => "a_redis_stack",
+		:template   => redis_template
+	})
+```
+
+We get back a JSON blob filled with info about our new stack:
+
+```ruby
+===> {"id"=>"73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "links"=>[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"self"}]}
+```
+
+Now that we have the `id` of our new stack, we can get a reference to it using the stack's `name` and `id`:
+
+
+```ruby
+irb: stack = service.stacks.get("a_redis_stack", "73e0f38a-a9fb-4a4e-8196-2b63039ef31f")
+===>   <Fog::Rackspace::Orchestration::Stack
+    id="73e0f38a-a9fb-4a4e-8196-2b63039ef31f",
+    description="This is a Heat template to deploy a standalone redis server on\nRackspace Cloud Servers\n",
+    links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"self"}],
+    stack_status_reason="Stack CREATE started",
+    stack_name="a_redis_stack",
+    creation_time="2014-11-13T16:21:02Z",
+    updated_time=nil
+  >
+```
+A stack knows about related `events`:
+
+```ruby
+irb: stack.events
+===>   <Fog::Rackspace::Orchestration::Events
+    [
+      <Fog::Rackspace::Orchestration::Event
+        id="7b1830a3-5d7b-43b2-bc1b-cffbb25c8b3e",
+        resource_name="redis_server_config",
+        event_time="2014-11-13T16:21:45Z",
+        links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f/resources/redis_server_config/events/7b1830a3-5d7b-43b2-bc1b-cffbb25c8b3e", "rel"=>"self"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f/resources/redis_server_config", "rel"=>"resource"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"stack"}],
+        logical_resource_id="redis_server_config",
+        resource_status="CREATE_IN_PROGRESS",
+        resource_status_reason="state changed",
+        physical_resource_id=nil
+      >,
+```
+A stack knows about related `resources`:
+
+```ruby
+irb: stack.resources
+===>   <Fog::Rackspace::Orchestration::Resources
+    [
+      <Fog::Rackspace::Orchestration::Resource
+        id=nil,
+        resource_name="redis_server",
+        description=nil,
+        links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f/resources/redis_server", "rel"=>"self"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"stack"}],
+        logical_resource_id="redis_server",
+        resource_status="CREATE_COMPLETE",
+        updated_time="2014-11-13T16:21:04Z",
+        required_by=["redis_server_config"],
+        resource_status_reason="state changed",
+        resource_type="Rackspace::Cloud::Server"
+      >,
+```
+
+You can list, limit, sort stacks based on certain keywords:
+
+** Available keywords:**
+
+* status
+* ​name
+* ​limit
+* ​marker
+* ​sort_keys
+* sort_dir
+
+```ruby
+irb:  stacks = service.stacks.all(sort_key: "stack_name", sort_dir: "asc")
+===>   <Fog::Rackspace::Orchestration::Stacks
+    [
+      <Fog::Rackspace::Orchestration::Stack
+        id="73e0f38a-a9fb-4a4e-8196-2b63039ef31f",
+        description="This is a Heat template to deploy a standalone redis server on\nRackspace Cloud Servers\n",
+        links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"self"}],
+        stack_status_reason="Stack CREATE started",
+        stack_name="a_redis_stack",
+        creation_time="2014-11-13T16:21:02Z",
+        updated_time=nil
+      >
+    ]
+  >
+```
+You can get a stack's `template`
+
+```ruby
+irb: stack.template
+===>   <Fog::Rackspace::Orchestration::Template
+    description="This is a Heat template to deploy a standalone redis server on\nRackspace Cloud Servers\n",
+    heat_template_version="2013-05-23",
+    ....
+```
+You can abandon a stack -- essentially, it will delete the stack, but keep the resources around for potential further use:
+
+```ruby
+irb: stack.abandon
+===> #<Excon::Response:0x00000104d6b870 @data={:body=>{"status"=>"IN_PROGRESS", "name"=>"a_redis_stack", "stack_user_project_id"=>"930035", "environment"=>{"parameters"=>{}, "resource_registry"=>{"resources"=>{}}}, "template"=>{"parameter_groups"=>[{"parameters"=>["flavor", "image"], "label"=>"Server Settings"}, {"parameters"=>["redis_port"], "label"=>"Redis Settings"}, {"parameters"=>["redis_version", "redis_hostname", "kitchen", "chef_version"], "label"=>"rax-dev-params"}], "heat_template_version"=>"2013-05-23", "description"=>"This is a Heat te
+```
+
+You can preview a stack:
+
+```ruby
+irb: service.stacks.preview({
+		:stack_name => "a_redis_template",
+		:template   => redis_template
+	})
+===>   <Fog::Rackspace::Orchestration::Stack
+    id="None",
+    description="This is a Heat template to deploy a standalone redis server on\nRackspace Cloud Servers\n",
+    links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_template/None", "rel"=>"self"}],
+    stack_status_reason=nil,
+    stack_name="a_redis_template",
+    creation_time="2014-11-13T16:33:50Z",
+    updated_time=nil
+  >
+```
+
+Of course, you can just delete a stack. This deletes associated `resources` (as opposed to `abandon`):
+
+```ruby
+irb: stack.delete
+===> #<Excon::Response:0x0000010198b000 @data={:body=>"", :headers=>{"Server"=>"nginx/1.2.1", "Date"=>"Thu, 13 Nov 2014 16:28:38 GMT", "Content-Type"=>"text/html; charset=UTF-8", "Connection"=>"keep-alive", "Via"=>"1.0 Repose (Repose/6.0.2)"}, :status=>204, :reason_phrase=>"No Content", :remote_ip=>"23.253.147.138", :local_port=>54721, :local_address=>"192.168.1.65"}, @body="", @headers={"Server"=>"nginx/1.2.1", "Date"=>"Thu, 13 Nov 2014 16:28:38 GMT", "Content-Type"=>"text/html; charset=UTF-8", "Connection"=>"keep-alive", "Via"=>"1.0 Repose (Repose/6.0.2)"}, @status=204, @remote_ip="23.253.147.138", @local_port=54721, @local_address="192.168.1.65">
+```
+
+Reload any object by calling `reload` on it:
+
+```ruby
+irb: stacks.reload
+===>   <Fog::Rackspace::Orchestration::Stacks
+    []
+  >
+```
+You can get build information:
+
+```ruby
+irb: service.stacks.build_info
+===> {"engine"=>{"revision"=>"2014.k1-20141027-1178"}, "fusion-api"=>{"revision"=>"j1-20140915-10d9ee4-98"}, "api"=>{"revision"=>"2014.k1-20141027-1178"}}
+```
+
+## Events
+
+`Events` are indexable and can be scoped by `stack`:
+
+```ruby
+irb: event = stack.events.first
+===>   <Fog::Rackspace::Orchestration::Event
+    id="7b1830a3-5d7b-43b2-bc1b-cffbb25c8b3e",
+    resource_name="redis_server_config",
+    event_time="2014-11-13T16:21:45Z",
+    links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f/resources/redis_server_config/events/7b1830a3-5d7b-43b2-bc1b-cffbb25c8b3e", "rel"=>"self"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f/resources/redis_server_config", "rel"=>"resource"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"stack"}],
+    logical_resource_id="redis_server_config",
+    resource_status="CREATE_IN_PROGRESS",
+    resource_status_reason="state changed",
+    physical_resource_id=nil
+  >
+```
+
+`Events` can be sorted, limited, etc by passing an hash like so:
+`service.events.all(stack, limit: 1)`
+
+** Available keys: **
+
+* resource_action
+* resource_status
+* resource_name
+* ​resource_type
+* ​limit
+* ​marker
+* sort_keys
+* ​sort_dir
+
+They are getable:
+
+```ruby
+irb: event = service.events.get(stack, resource, event_id)
+===>   <Fog::Rackspace::Orchestration::Event
+    id="7b1830a3-5d7b-43b2-bc1b-cffbb25c8b3e",
+    resource_name="redis_server_config",
+    event_time="2014-11-13T16:21:45Z",
+    links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f/resources/redis_server_config/events/7b1830a3-5d7b-43b2-bc1b-cffbb25c8b3e", "rel"=>"self"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f/resources/redis_server_config", "rel"=>"resource"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"stack"}],
+    logical_resource_id="redis_server_config",
+    resource_status="CREATE_IN_PROGRESS",
+    resource_status_reason="state changed",
+    physical_resource_id=nil
+  >
+```
+
+An `event` knows about its associated `stack`:
+
+```ruby
+irb: event.stack
+===>   <Fog::Rackspace::Orchestration::Stack
+    id="73e0f38a-a9fb-4a4e-8196-2b63039ef31f",
+    description="This is a Heat template to deploy a standalone redis server on\nRackspace Cloud Servers\n",
+    links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"self"}],
+    stack_status_reason="Stack CREATE completed successfully",
+    stack_name="a_redis_stack",
+    creation_time="2014-11-13T16:21:02Z",
+    updated_time=nil
+  >
+```
+
+You can list, limit, sort events based on certain keywords:
+
+```ruby
+irb: events = stack.events.all(stack, sort_key: "resource_name", sort_dir: "desc", limit: 3)
+===>   <Fog::Rackspace::Orchestration::Events
+    [
+      <Fog::Rackspace::Orchestration::Event
+        id="9cdae7d7-f44e-4dbb-bc0b-61ea6da9cf81",
+        resource_name="redis_server_config",
+        event_time="2014-11-13T16:24:07Z",
+        ....
+```
+
+An  `event` has an associated `resource`:
+
+```ruby
+irb: resource = event.resource
+===>   <Fog::Rackspace::Orchestration::Resource
+    id=nil,
+    resource_name="redis_server_config",
+    description="",
+    links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f/resources/redis_server_config", "rel"=>"self"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"stack"}],
+    logical_resource_id="redis_server_config",
+    resource_status="CREATE_COMPLETE",
+    updated_time="2014-11-13T16:21:45Z",
+    required_by=[],
+    resource_status_reason="state changed",
+    resource_type="OS::Heat::ChefSolo"
+  >
+```
+
+## Resource
+
+`resources` are indexable:
+
+```ruby
+irb: service.resources.all(stack, {nested_depth: 1})
+===>   <Fog::Rackspace::Orchestration::Resources
+    [
+      <Fog::Rackspace::Orchestration::Resource
+        id=nil,
+        resource_name="redis_server",
+        description=nil,
+        links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/ee648a3b-14a3-4df8-aa58-620a9d67e3e5/resources/redis_server", "rel"=>"self"}, {"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/ee648a3b-14a3-4df8-aa58-620a9d67e3e5", "rel"=>"stack"}],
+        logical_resource_id="redis_server",
+        resource_status="CREATE_COMPLETE",
+        updated_time="2014-11-13T16:32:30Z",
+        required_by=["redis_server_config"],
+        resource_status_reason="state changed",
+        resource_type="Rackspace::Cloud::Server"
+      >,
+      ...
+```
+
+A `resource` knows about its associated `stack`:
+
+```ruby
+irb: resource.stack
+===>   <Fog::Rackspace::Orchestration::Stack
+    id="73e0f38a-a9fb-4a4e-8196-2b63039ef31f",
+    description="This is a Heat template to deploy a standalone redis server on\nRackspace Cloud Servers\n",
+    links=[{"href"=>"https://iad.orchestration.api.rackspacecloud.com/v1/930035/stacks/a_redis_stack/73e0f38a-a9fb-4a4e-8196-2b63039ef31f", "rel"=>"self"}],
+    stack_status_reason="Stack CREATE completed successfully",
+    stack_name="a_redis_stack",
+    creation_time="2014-11-13T16:21:02Z",
+    updated_time=nil
+  >
+```
+
+Resource metadata is visible:
+
+```ruby
+irb: resource.metadata
+===> {}
+```
+
+A `resource's` template is visible (if one exists)
+
+```ruby
+irb: resource.template
+===> nil
+```
+
+## Validation
+You can validate a Heat template (HOT) before using it:
+
+```ruby
+irb: service.templates.validate({:template => redis_template})
+===>   <Fog::Rackspace::Orchestration::Template
+    description="This is a Heat template to deploy a standalone redis server on\nRackspace Cloud Servers\n",
+    heat_template_version=nil,
+    ...
+```

data/lib/fog/rackspace/docs/queues.md

@@ -0,0 +1,312 @@
+#Cloud Queues (queues)
+
+This document explains how to get started using queues with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document.
+
+## Basic Concepts
+
+Cloud Queues is an open source, scalable, and highly available message and notifications service, based on the OpenStack Marconi project. Users of this service can create and manage a producer-consumer or a publisher-subscriber model. Unlimited queues and messages give users the flexibility they need to create powerful web applications in the cloud.
+
+It consists of a few basic components: queues, messages, claims, and statistics. In the producer-consumer model, users create queues in which producers, or servers, can post messages. Workers, or consumers, can then claim those messages and delete them after they complete the actions associated with the messages. A single claim can contain multiple messages, and administrators can query claims for status.
+
+In the publisher-subscriber model, messages are posted to a queue as in the producer-consumer model, but messages are never claimed. Instead, subscribers, or watchers, send GET requests to pull all messages that have been posted since their last request. In this model, a message remains in the queue, unclaimed, until the message's time to live (TTL) has expired.
+
+In both of these models, administrators can get queue statistics that display the most recent and oldest messages, the number of unclaimed messages, and more.
+
+## Starting irb console
+
+Start by executing the following command:
+
+	irb
+
+Once `irb` has launched you need to require the Fog library as follows:
+
+	require 'fog'
+
+## Create Service
+
+Next, create a connection to queue service:
+
+Using a US-based account:
+
+	service = Fog::Rackspace::Queues.new(
+		:rackspace_username  => RACKSPACE_USER_NAME,   # Your Rackspace Username
+		:rackspace_api_key   => RACKSPACE_API,         # Your Rackspace API key
+		:rackspace_region    => :ord,                  # Your desired region
+		:rackspace_queues_client_id => CLIENT_ID,      # Your client ID
+		:connection_options  => {}                     # Optional connection options
+	)
+
+Using a UK-based account:
+
+	service = Fog::Rackspace::Queues.new(
+		:rackspace_username  => RACKSPACE_USER_NAME,        # Your Rackspace Username
+		:rackspace_api_key   => RACKSPACE_API,              # Your Rackspace API key
+		:rackspace_auth_url  => Fog::Rackspace::UK_AUTH_ENDPOINT,
+		:rackspace_region    => :lon,                       # Your desired region
+		:rackspace_queues_client_id =>  CLIENT_ID',         # Your client ID
+		:connection_options  => {}                          # Optional connection options
+	)
+
+To learn more about obtaining cloud credentials refer to the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document.
+
+### Authentication Endpoint
+
+By default `Fog::Rackspace::Queues` will authenticate against the US authentication endpoint. You can specify alternative authentication endpoints using the key `:rackspace_auth_url`. Please refer to [Alternate Authentication Endpoints](http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Endpoints-d1e180.html) for a list of alternative Rackspace authentication endpoints.
+
+### Regions
+
+Alternative regions are specified using the key `:rackspace_region `. A list of regions available for cloud queues can be found by executing the following:
+
+	identity_service = Fog::Identity({
+		:provider            => 'Rackspace',                     # Rackspace Fog provider
+		:rackspace_username  => RACKSPACE_USER_NAME,             # Your Rackspace Username
+		:rackspace_api_key   => RACKSPACE_API,                   # Your Rackspace API key
+		:rackspace_auth_url  => Fog::Rackspace::UK_AUTH_ENDPOINT # Not specified for US Cloud
+	})
+
+	identity_service.service_catalog.display_service_regions :queues
+
+### Private Cloud
+
+Rackspace Private Cloud installations can skip specifying a region and directly specify their custom service endpoints using the key `:rackspace_queues_url`.
+
+**Note**: A`Fog::Rackspace::Queues` instance is needed for the desired region.
+
+### Client ID
+
+The Rackspace Queue service requires that every client define a client id to help identify messages and claims specific to the client. This client id should take the form of a UUID and can be generated using fog as follows:
+
+    Fog::UUID.uuid
+
+If the client id is omitted fog will generate one for you.
+
+### Optional Connection Parameters
+
+Fog supports passing additional connection parameters to its underlying HTTP library (Excon) using the `:connection_options` parameter.
+
+<table>
+	<tr>
+		<th>Key</th>
+		<th>Description</th>
+	</tr>
+	<tr>
+		<td>:connect_timeout</td>
+		<td>Connection timeout (default: 60 seconds)</td>
+	</tr>
+	<tr>
+		<td>:read_timeout</td>
+		<td>Read timeout for connection (default: 60 seconds)</td>	</tr>
+	<tr>
+		<td>:write_timeout</td>
+		<td>Write timeout for connection (default: 60 seconds)</td>
+	</tr>
+	<tr>
+		<td>:proxy</td>
+		<td>Proxy for HTTP and HTTPS connections</td>
+	</tr>
+	<tr>
+		<td>:ssl_ca_path</td>
+		<td>Path to SSL certificate authorities</td>
+	</tr>
+	<tr>
+		<td>:ssl_ca_file</td>
+		<td>SSL certificate authority file</td>
+	</tr>
+	<tr>
+		<td>:ssl_verify_peer</td>
+		<td>SSL verify peer (default: true)</td>
+	</tr>
+</table>
+
+
+## Fog Abstractions
+
+Fog provides both a **model** and **request** abstraction. The request abstraction provides the most efficient interface and the model abstraction wraps the request abstraction to provide a convenient `ActiveModel`-like interface.
+
+### Request Layer
+
+The request abstraction maps directly to the [Queue API](http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/overview.html). It provides the most efficient interface to the Rackspace Open Cloud.
+
+To see a list of requests supported by the service:
+
+	service.requests
+
+This returns:
+
+	    :list_queues, :get_queue, :create_queue, :delete_queue, :get_queue_stats, :list_messages, :get_message, :create_message, :delete_message, :create_claim, :get_claim, :update_claim, :delete_claim
+
+
+#### Example Request
+
+To request a list of queues:
+
+	response = service.list_queues
+
+This returns in the following `Excon::Response`:
+
+	#<Excon::Response:0x007feddda06e00 @data={:body=>{"queues"=>[{"href"=>"/v1/queues/demo-queue", "name"=>"demo-queue"}], "links"=>[{"href"=>"/v1/queues?marker=demo-queue", "rel"=>"next"}]}, :headers=>{"Content-Length"=>"119", "Content-Type"=>"application/json; charset=utf-8", "Content-Location"=>"/v1/queues", "X-Project-ID"=>"5551212"}, :status=>200, :remote_ip=>"10.10.0.1"}, @body="{\"queues\": [{\"href\": \"/v1/queues/demo-queue\", \"name\": \"demo-queue\"}], \"links\": [{\"href\": \"/v1/queues?marker=demo-queue\", \"rel\": \"next\"}]}", @headers={"Content-Length"=>"119", "Content-Type"=>"application/json; charset=utf-8", "Content-Location"=>"/v1/queues", "X-Project-ID"=>"5551212"}, @status=200, @remote_ip="10.10.0.1">
+
+To view the status of the response:
+
+	response.status
+
+**Note**: Fog is aware of valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.
+
+To view response body:
+
+	response.body
+
+This returns:
+
+	{"queues"=>[{"href"=>"/v1/queues/demo-queue", "name"=>"demo-queue"}], "links"=>[{"href"=>"/v1/queues?marker=demo-queue", "rel"=>"next"}]}
+
+
+To learn more about queue request methods refer to [rdoc](http://rubydoc.info/gems/fog/Fog/Rackspace/Queues/Real). To learn more about Excon refer to [Excon GitHub repo](https://github.com/geemus/excon).
+
+### Model Layer
+
+Fog models behave in a manner similar to `ActiveModel`. Models will generally respond to `create`, `save`,  `persisted?`, `destroy`, `reload` and `attributes` methods. Additionally, fog will automatically create attribute accessors.
+
+Here is a summary of common model methods:
+
+<table>
+	<tr>
+		<th>Method</th>
+		<th>Description</th>
+	</tr>
+	<tr>
+		<td>create</td>
+		<td>
+			Accepts hash of attributes and creates object.<br>
+			Note: creation is a non-blocking call and you will be required to wait for a valid state before using resulting object.
+		</td>
+	</tr>
+	<tr>
+		<td>save</td>
+		<td>Saves object.<br>
+		Note: not all objects support updating object.</td>
+	</tr>
+	<tr>
+		<td>persisted?</td>
+		<td>Returns true if the object has been persisted.</td>
+	</tr>
+	<tr>
+		<td>destroy</td>
+		<td>
+			Destroys object.<br>
+			Note: this is a non-blocking call and object deletion might not be instantaneous.
+		</td>
+	<tr>
+		<td>reload</td>
+		<td>Updates object with latest state from service.</td>
+	<tr>
+		<td>ready?</td>
+		<td>Returns true if object is in a ready state and able to perform actions. This method will raise an exception if object is in an error state.</td>
+	</tr>
+	<tr>
+		<td>attributes</td>
+		<td>Returns a hash containing the list of model attributes and values.</td>
+	</tr>
+		<td>identity</td>
+		<td>
+			Returns the identity of the object.<br>
+			Note: This might not always be equal to object.id.
+		</td>
+	</tr>
+	<tr>
+		<td>wait_for</td>
+		<td>This method periodically reloads model and then yields to specified block until block returns true or a timeout occurs.</td>
+	</tr>
+</table>
+
+The remainder of this document details the model abstraction.
+
+## Create Queue
+
+Queues require a unique name. If you try to create a queue with a name that already exists, fog will throw a `Fog::Rackspace::Queues::ServiceError` exception with a 204 status code.
+
+To create a queue named demo-queue
+
+    begin
+      queue = service.queues.create :name => 'demo-queue'
+    rescue Fog::Rackspace::Queues::ServiceError => e
+      if e.status_code == 204
+        # duplicate queue exists
+      end
+    end
+
+## Posting a Message to a Queue
+
+Messages can be any type of data, as long as they do not exceed 256 KB in length. Typical message bodies range from simple values, to a chunk of XML, or a list of JSON values. Fog handles the JSON-encoding required to post the message.
+
+You can post a message a message to your queue as follows:
+
+    queue.messages.create :body => 'The laces were out!', :ttl => 360
+
+You must supply both a body and a value for `ttl`. The value of `ttl` must be between 60 and 1209600 seconds (one minute to 14 days).
+
+## Listing Messages in a Queue
+
+To list messages:
+
+    queue.messages
+
+You can change the behavior by setting the follow attributes on the messages collection:
+
+Parameter | Default | Effect
+---- | ---- | ----
+**echo** | `true` | When `true`, your own messages are included.
+**include_claimed** | `false` | By default, only unclaimed messages are returned. Pass this as `true` to get all messages, claimed or not.
+**marker** | `nil` | Used for pagination.
+**limit** | `10` | The maximum number of messages to return. Note that you may receive fewer than the specified limit if there aren't that many available messages in the queue.
+
+For example, to include claimed messages:
+
+    queue.messages.include_claimed = true
+    queue.messages
+
+## Claiming Messages in a Queue
+
+Claiming messages is how workers processing a queue mark messages as being handled by that worker, avoiding having two workers process the same message.
+
+Messages can be claimed and processed as follows:
+
+    claims = queue.claims.create :ttl => 300, :grace => 100, :limit => 10
+
+The parameters for this call are described in the following table:
+
+Parameter | Default | Notes
+---- | ---- | ----
+**ttl** |  | The ttl attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
+**grace** |  | The grace attribute specifies the message grace period in seconds. The value of the grace period must be between 60 and 43200 seconds (12 hours). To deal with workers that have stopped responding (for up to 1209600 seconds or 14 days, including claim lifetime), the server extends the lifetime of claimed messages to be at least as long as the lifetime of the claim itself, plus the specified grace period. If a claimed message would normally live longer than the grace period, its expiration is not adjusted.
+**limit** | 10 | The number of messages to claim. The maximum number of messages you may claim at once is 20.
+
+If the claim is successful it will return a `Fog::Rackspace::Queues::Claims` object; if there are not any available messages it will return `false`.
+
+To iterate through the claimed messages:
+
+    claim.messages.each do |message|
+      # process message here
+      message.destroy
+    end
+
+**Note:** You will want to call the `destroy` method on the message after processing to insure it is not processed more than once.
+
+## Renewing a Claim
+
+Once a claim has been made, if the TTL and grace period expire, the claim is automatically released and the messages are made available for others to claim. If you have a long-running process and want to ensure that this does not happen in the middle of the process, you should update the claim with one or both of a TTL or grace period. Updating resets the age of the claim, restarting the TTL for the claim. To update a claim, call:
+
+    claim.ttl = 360
+    claim.grace = 360
+    claim.save
+
+## Refreshing a Claim
+
+If you have a `Fog::Rackspace::Queues::claims` object, keep in mind that it is not a live window into the status of the claim; rather, it is a snapshot of the claim at the time the object was created. To refresh it with the latest information, call its `reload` method. This refreshes all of its attributes with the most current status of the claim.
+
+
+## Releasing a Claim
+
+If you have a claim on several messages and must abandon processing of those messages for any reason, you should release the claim so that those messages can be processed by other workers as soon as possible, instead of waiting for the claim's TTL to expire. When you release a claim, the claimed messages are immediately made available in the queue for other workers to claim. To release a claim, call:
+
+    claim.destroy