fog-openstack 0.1.0

data/lib/fog/openstack/docs/getting_started.md

@@ -0,0 +1,81 @@
+# Getting Started with Fog and OpenStack
+
+This document explains how to get started using Fog with [OpenStack](http://openstack.org)
+
+## Requirements
+
+### Ruby
+
+Fog officially supports Ruby 2.0.0, 1.9.3, 1.9.2, and 1.8.7 (also known as Matz Ruby Interpreter or MRI). While not officially supported, fog has been known to work with Rubinus and JRuby.
+
+Ruby 2.0.0 is suggested for new projects. For information on installing Ruby please refer to the [Ruby download page](http://www.ruby-lang.org/en/downloads/).
+
+### RubyGems
+
+RubyGems is required to access the Fog gem. For information on installing RubyGems, please refer to [RubyGems download page](http://rubygems.org/pages/download).
+
+### Bundler (optional)
+
+Bundler helps manage gem dependencies and is recommended for new projects. For more information about bundler, please refer to the [bundler documentation](http://gembundler.com/).
+
+## Installation
+
+To install Fog via RubyGems run the following command:
+
+    $ gem install fog
+
+To install Fog via Bundler add `gem 'fog'` to your `Gemfile`. This is a sample `Gemfile` to install Fog:
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'fog'
+```
+
+After creating your `Gemfile` execute the following command to install the libraries:
+
+	bundle install	
+
+## Next Steps
+
+Now that you have installed Fog and obtained your credentials, you are ready to begin exploring the capabilities of the Rackspace Open Cloud and Fog using `irb`.
+
+Start by executing the following command:
+
+	irb
+	
+Once `irb` has launched you will need to require the Fog library.
+
+If using Ruby 1.8.x execute the following command:
+
+```ruby
+require 'rubygems'
+require 'fog'
+```
+
+If using Ruby 1.9.x execute the following command:
+
+```ruby
+require 'fog'
+```
+
+You should now be able to execute the following command to see a list of services Fog provides for the Rackspace Open Cloud:
+
+```ruby
+Fog::OpenStack.services
+```
+
+These services can be explored in further depth in the following documents:
+
+* [Compute](compute.md)
+* [Storage (Swift)](storage.md)
+
+## Additional Resources
+* [fog.io](http://fog.io)
+* [Fog rdoc](http://rubydoc.info/gems/fog)
+* [Fog Github repo](https://github.com/fog/fog)
+* [Release Notes](https://github.com/fog/fog/blob/master/changelog.txt)
+
+
+## Support and Feedback
+Your feedback is appreciated! If you have specific issues with the **fog** SDK, you should file an [issue via Github](https://github.com/fog/fog/issues).

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

@@ -0,0 +1,318 @@
+# 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)_
+
+# OpenStack Orchestration (Heat) Client
+
+[Full OpenStack Orchestration/Heat API Docs](http://developer.openstack.org/api-ref-orchestration-v1.html)
+
+## Orchestration Service
+Get a handle on the Orchestration service:
+
+```ruby
+service = Fog::Orchestration::OpenStack.new({
+  :openstack_auth_url  => 'http://KEYSTONE_HOST:KEYSTONE_PORT/v2.0/tokens', # OpenStack Keystone endpoint
+  :openstack_username  => OPEN_STACK_USER,                                  # Your OpenStack Username
+  :openstack_tenant    => OPEN_STACK_TENANT,                                # Your tenant id
+  :openstack_api_key   => OPEN_STACK_PASSWORD,                              # Your OpenStack Password
+  :connection_options  => {}                                                # Optional
+})
+```
+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
+service.stacks
+```
+This returns a list of stacks with minimum attributes, leaving other attributes empty
+```ruby
+=> <Fog::Orchestration::OpenStack::Stacks
+    [
+      <Fog::Orchestration::OpenStack::Stack
+        id="0b8e4060-419b-416b-a927-097d4afbf26d",
+        capabilities=nil,
+        description="Simple template to deploy a single compute instance",
+        disable_rollback=nil,
+        links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/stack4/0b8e4060-419b-416b-a927-097d4afbf26d", "rel"=>"self"}],
+        notification_topics=nil,
+        outputs=nil,
+        parameters=nil,
+        stack_name="stack4",
+        stack_status="UPDATE_COMPLETE",
+        stack_status_reason="Stack successfully updated",
+        template_description=nil,
+        timeout_mins=nil,
+        creation_time="2014-08-27T21:25:56Z",
+        updated_time="2015-01-30T20:10:43Z"
+      >,
+      ...
+```
+
+Create a new `stack` with a [Heat Template (HOT)](http://docs.openstack.org/developer/heat/template_guide/hot_guide.html) or an AWS CloudFormation Template (CFN):
+
+```ruby
+raw_template = File.read(TEMPLATE_FILE)
+service.stacks.new.save({
+  :stack_name => "a_name_for_stack",
+  :template   => raw_template,
+  :parameters => {"flavor" => "m1.small", "image" => "cirror"}
+})
+```
+This returns a JSON blob filled with information about our new stack:
+
+```ruby
+ {"id"=>"53b35fbe-34f7-4837-b0f8-8863b7263b7d",
+ "links"=>[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/a_name_for_stack/53b35fbe-34f7-4837-b0f8-8863b7263b7d",
+ "rel"=>"self"}]}
+ ```
+
+We can get a reference to the stack using its `stack_name` and `id`:
+
+```ruby
+stack = service.stacks.get("stack4", "0b8e4060-419b-416b-a927-097d4afbf26d")
+```
+This returns a stack with all attributes filled
+```ruby
+=>   <Fog::Orchestration::OpenStack::Stack
+    id="0b8e4060-419b-416b-a927-097d4afbf26d",
+    capabilities=[],
+    description="Simple template to deploy a single compute instance",
+    disable_rollback=true,
+    links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/stack4/0b8e4060-419b-416b-a927-097d4afbf26d", "rel"=>"self"}],
+    notification_topics=[],
+    outputs=[],
+    parameters={"AWS::StackId"=>"arn:openstack:heat::5d139d95546240748508b2a518aa5bef:stacks/stack4/0b8e4060-419b-416b-a927-097d4afbf26d", "AWS::Region"=>"ap-southeast-1", "AWS::StackName"=>"stack4"},
+    stack_name="stack4",
+    stack_status="UPDATE_COMPLETE",
+    stack_status_reason="Stack successfully updated",
+    template_description="Simple template to deploy a single compute instance",
+    timeout_mins=60,
+    creation_time="2014-08-27T21:25:56Z",
+    updated_time="2015-01-30T20:10:43Z"
+  >
+```
+It can be also obtained through the details method of a simple stack object
+```ruby
+stack.details
+```
+
+A stack knows about related `events`:
+
+```ruby
+stack.events
+=>   <Fog::Orchestration::OpenStack::Events
+    [
+      <Fog::Orchestration::OpenStack::Event
+        id="251",
+        resource_name="my_instance",
+        event_time="2015-01-21T20:08:51Z",
+        links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/a_name_for_stack/53b35fbe-34f7-4837-b0f8-8863b7263b7d/resources/my_instance/events/251", "rel"=>"self"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/a_name_for_stack/53b35fbe-34f7-4837-b0f8-8863b7263b7d/resources/my_instance", "rel"=>"resource"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/a_name_for_stack/53b35fbe-34f7-4837-b0f8-8863b7263b7d", "rel"=>"stack"}],
+        logical_resource_id="my_instance",
+        resource_status="CREATE_IN_PROGRESS",
+        resource_status_reason="state changed",
+        physical_resource_id=nil
+      >,
+```
+A stack knows about related `resources`:
+
+```ruby
+stack.resources
+=>   <Fog::Orchestration::OpenStack::Resources
+    [
+      <Fog::Orchestration::OpenStack::Resource
+        id=nil,
+        resource_name="my_instance",
+        description=nil,
+        links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9/resources/my_instance", "rel"=>"self"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9", "rel"=>"stack"}],
+        logical_resource_id="my_instance",
+        resource_status="CREATE_COMPLETE",
+        updated_time="2014-09-12T20:44:06Z",
+        required_by=[],
+        resource_status_reason="state changed",
+        resource_type="OS::Nova::Server"
+      >
+    ]
+  >
+```
+
+You can get a stack's `template`
+
+```ruby
+stack.template
+=>   <Fog::Orchestration::OpenStack::Template
+    format="HOT",
+    description="Simple template to deploy a single compute instance",
+    template_version="2013-05-23",
+    parameters=nil,
+    resources=...
+```
+
+You can just delete a stack. This deletes associated `resources` :
+
+```ruby
+stack.delete
+=> #<Excon::Response:0x007fe1066b2af8 @data={:body=>"", :headers=>{"Content-Type"=>"text/html; charset=UTF-8", "Content-Length"=>"0", "Date"=>"Wed, 21 Jan 2015 20:38:00 GMT"}, :status=>204, :reason_phrase=>"No Content", :remote_ip=>"10.8.96.4", :local_port=>59628, :local_address=>"10.17.68.186"}, @body="", @headers={"Content-Type"=>"text/html; charset=UTF-8", "Content-Length"=>"0", "Date"=>"Wed, 21 Jan 2015 20:38:00 GMT"}, @status=204, @remote_ip="10.8.96.4", @local_port=59628, @local_address="10.17.68.186">
+```
+
+Reload any object by calling `reload` on it:
+
+```ruby
+stacks.reload
+=>   <Fog::Orchestration::OpenStack::Stacks
+    [...]
+  >
+```
+
+## Events
+
+You can list `Events` of a `stack`:
+
+```ruby
+stack.events
+=>   <Fog::Orchestration::OpenStack::Events
+    [
+      <Fog::Orchestration::OpenStack::Event
+        id="15",
+        resource_name="my_instance",
+        event_time="2014-09-12T20:43:58Z",
+        links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9/resources/my_instance/events/15", "rel"=>"self"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9/resources/my_instance", "rel"=>"resource"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9", "rel"=>"stack"}],
+        logical_resource_id="my_instance",
+        resource_status="CREATE_IN_PROGRESS",
+        resource_status_reason="state changed",
+        physical_resource_id=nil
+      >,
+```
+
+`Event` can be got through corresponding `resource`
+
+```ruby
+event = service.events.get(stack, resource, event_id)
+=>   <Fog::Orchestration::OpenStack::Event
+    id="15",
+    resource_name="my_instance",
+    event_time="2014-09-12T20:43:58Z",
+    links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9/resources/my_instance/events/15", "rel"=>"self"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9/resources/my_instance", "rel"=>"resource"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9", "rel"=>"stack"}],
+    logical_resource_id="my_instance",
+    resource_status="CREATE_IN_PROGRESS",
+    resource_status_reason="state changed",
+    physical_resource_id=nil
+  >
+```
+
+An `event` knows about its associated `stack`:
+
+```ruby
+event.stack
+=>   <Fog::Orchestration::OpenStack::Stack
+    id="0c9ee370-ef64-4a80-a6cc-65d2277caeb9",
+    description="Simple template to deploy a single compute instance",
+    links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9", "rel"=>"self"}],
+    stack_status_reason="Stack create completed successfully",
+    stack_name="progenerated",
+    creation_time="2014-09-12T20:43:58Z",
+    updated_time="2014-09-12T20:44:06Z"
+  >
+```
+An  `event` has an associated `resource`:
+
+```ruby
+resource = event.resource
+=>   <Fog::Orchestration::OpenStack::Resource
+    id=nil,
+    resource_name="my_instance",
+    description="",
+    links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9/resources/my_instance", "rel"=>"self"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9", "rel"=>"stack"}],
+    logical_resource_id="my_instance",
+    resource_status="CREATE_COMPLETE",
+    updated_time="2014-09-12T20:44:06Z",
+    required_by=[],
+    resource_status_reason="state changed",
+    resource_type="OS::Nova::Server"
+  >
+```
+
+## Resource
+
+`resources` might be nested:
+
+```ruby
+service.resources.all(stack, {:nested_depth => 1})
+=>   <Fog::Orchestration::OpenStack::Resources
+    [
+      <Fog::Orchestration::OpenStack::Resource
+        id=nil,
+        resource_name="my_instance",
+        description=nil,
+        links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9/resources/my_instance", "rel"=>"self"}, {"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9", "rel"=>"stack"}],
+        logical_resource_id="my_instance",
+        resource_status="CREATE_COMPLETE",
+        updated_time="2014-09-12T20:44:06Z",
+        required_by=[],
+        resource_status_reason="state changed",
+        resource_type="OS::Nova::Server"
+      >
+    ]
+  >
+```
+
+A `resource` knows about its associated `stack`:
+
+```ruby
+resource.stack
+=>   <Fog::Orchestration::OpenStack::Stack
+    id="0c9ee370-ef64-4a80-a6cc-65d2277caeb9",
+    description="Simple template to deploy a single compute instance",
+    links=[{"href"=>"http://10.8.96.4:8004/v1/5d139d95546240748508b2a518aa5bef/stacks/progenerated/0c9ee370-ef64-4a80-a6cc-65d2277caeb9", "rel"=>"self"}],
+    stack_status_reason="Stack create completed successfully",
+    stack_name="progenerated",
+    creation_time="2014-09-12T20:43:58Z",
+    updated_time="2014-09-12T20:44:06Z"
+  >
+```
+
+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 template (either HOT or CFN) before using it:
+
+```ruby
+service.templates.validate(:template => content)
+=>   <Fog::Orchestration::OpenStack::Template
+    format=nil,
+    description="Simple template to deploy a single compute instance",
+    template_version=nil,
+    parameters={},
+    resources=nil,
+    content=nil
+  >
+```

data/lib/fog/openstack/docs/planning.md

@@ -0,0 +1,270 @@
+# Planning
+
+This document explains how to get started using OpenStack Tuskar with Fog.
+
+
+## Starting irb console
+
+Start by executing the following command:
+
+```bash
+irb
+```
+
+Once `irb` has launched you need to require the Fog library.
+
+If using Ruby 1.8.x execute:
+
+```ruby
+require 'rubygems'
+require 'fog'
+```
+
+If using Ruby 1.9.x execute:
+
+```ruby
+require 'fog'
+```
+
+## Create Service
+
+Next, create a connection to Tuskar:
+
+```ruby
+service = Fog::Openstack.new({
+  :service             => :planning,     # OpenStack Fog service
+  :openstack_username  => USERNAME,      # Your OpenStack Username
+  :openstack_api_key   => PASSWORD,      # Your OpenStack Password
+  :openstack_auth_url  => 'http://YOUR_OPENSTACK_ENDPOINT:PORT/v2.0/tokens'
+  :connection_options  => {}             # Optional
+})
+```
+
+### 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 `Fog::Openstack[:planning]` object supports a number of methods that wrap individual HTTP requests to the Tuskar API.
+
+To see a list of requests supported by the planning service:
+
+```ruby
+service.requests
+```
+
+This returns:
+
+```ruby
+[
+  :list_roles,
+  :list_plans,
+  :get_plan_templates,
+  :get_plan,
+  :patch_plan,
+  :create_plan,
+  :delete_plan,
+  :add_role_to_plan,
+  :remove_role_from_plan
+]
+
+```
+
+
+#### Example Request
+
+To request a list of plans:
+
+```ruby
+response = service.list_plans
+```
+
+This returns in the following `Excon::Response`:
+
+```ruby
+#<Excon::Response:0x007f141e045ab8
+@data=
+  {
+    :body=>
+    [
+      {
+	"created_at"=>"2014-09-26T20:23:14.222815",
+	"description"=>"Development testing cloud",
+	"name"=>"dev-cloud",
+	"parameters"=>
+	  [
+	  {
+	    "default"=>"guest",
+	    "description"=>"The password for RabbitMQ",
+	    "hidden"=>true,
+	    "label"=>nil,
+	    "name"=>"compute-1 => =>RabbitPassword",
+	    "value"=>"secret-password"
+	  },
+	  {
+	    "default"=>"default",
+	    "description"=>"description",
+	    "hidden"=>true,
+	    "label"=>nil,
+	    "name"=>"name",
+	    "value"=>"value"
+	  }
+	  ],
+	"roles"=>
+	  [
+	  {
+	    "description"=>"OpenStack hypervisor node. Can be wrapped in a ResourceGroup for scaling.\n",
+	    "name"=>"compute",
+	    "uuid"=>"b7b1583c-5c80-481f-a25b-708ed4a39734",
+	    "version"=>1
+	  }
+	  ],
+	"updated_at"=>nil,
+	"uuid"=>"53268a27-afc8-4b21-839f-90227dd7a001"
+      }
+    ],
+    :headers=>{},
+    :status=>200
+  },
+  @body="",
+  @headers={},
+  @status=nil,
+  @remote_ip=nil,
+  @local_port=nil,
+  @local_address=nil
+>
+```
+
+To view the status of the response:
+
+```ruby
+response.status
+```
+
+**Note**: Fog is aware of the valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception.
+
+To view response headers:
+
+```ruby
+response.headers
+```
+
+This will return hash similar to:
+
+```ruby
+{
+  "X-Account-Bytes-Used"=>"2563554",
+  "Date"=>"Thu, 21 Feb 2013 21:57:02 GMT",
+  "X-Account-Meta-Temp-Url-Key"=>"super_secret_key",
+  "X-Timestamp"=>"1354552916.82056",
+  "Content-Length"=>"0",
+  "Content-Type"=>"application/json; charset=utf-8",
+  "X-Trans-Id"=>"txe934924374a744c8a6c40dd8f29ab94a",
+  "Accept-Ranges"=>"bytes",
+  "X-Account-Container-Count"=>"7",
+  "X-Account-Object-Count"=>"5"
+}
+```
+
+[//]: # (TODO: Specify URL to rubydoc.info when OpenStack Planning service is part of release and pages are built)
+To learn more about `Fog::Openstack[:planning]` request methods refer to [rdoc](http://rubydoc.info/gems/fog/Fog). 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`,  `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>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>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>
+</table>
+
+The remainder of this document details the model abstraction.
+
+
+## Additional Resources
+
+* [fog.io](http://fog.io/)
+* [Fog rdoc](http://rubydoc.info/gems/fog/)
+* [Fog Github repo](https://github.com/fog/fog)
+* [Fog Github Issues](https://github.com/fog/fog/issues)
+* [Excon Github repo](https://github.com/geemus/excon)
+* [Tuskar API](http://docs.openstack.org/developer/tuskar/)
+
+## Support and Feedback
+
+Your feedback is appreciated! If you have specific issues with the **fog** SDK, you should file an [issue via Github](https://github.com/fog/fog/issues).
+