fog/README.rdoc

fog[http://github.com/geemus/fog/blob/master/fog.png]

fog helps you interact with cloud services.

The quick and dirty, top to bottom:
* Models provide a simplified interface, making clouds easier to work with and switch between.
* Requests allow power users to get the most out of the features of each individual cloud.
* Mocks make testing and integrating a breeze.

Put them together and you get a great cloud computing experience, but we are getting ahead of ourselves...

== Getting Started

  sudo gem install fog

Now just type 'fog' to trying stuff out, confident that fog should let you know what you need to do. Here is an example of wading through server creation for Amazon Elastic Compute Cloud:

  >> server = AWS.servers.create
  ArgumentError: image_id is required for this operation
  >> server = AWS.servers.create(:image_id => 'ami-5ee70037')
  <Fog::AWS::EC2::Server [...]>
  >> server.destroy # cleanup after yourself or regret it, trust me
  true

== Collections

Nouns like Images and Servers are collections, which form the interface to the cloud.
Collections provide all, create, get and new methods.
* all fetches every object of that type from the cloud.
* create initializes a new record locally and then persists it to the cloud.
* get fetches a single object by its identity.
* new initializes a new record locally.

Common compute nouns are flavors, images and servers.

Common storage nouns are directory and file.

As an example, we'll try initializing and persisting a rackspace server:

  require 'fog'

  # initialize a connection to Rackspace Servers
  connection = Fog::Rackspace::Servers.new(
    :rackspace_api_key => key,
    :rackspace_username => username
  )

  # boot a gentoo server (flavor 1 = 256, image 3 = gentoo 2008.0)
  server = connection.servers.new(:flavor_id => 1, :image_id => 3, :name => 'my_server')

  # wait for it to be ready to do stuff
  server.wait_for { ready? }

  # DO STUFF

  # shutdown the server
  server.destroy

== Models

Many of the collection methods return individual objects, which provide destroy, save and wait_for methods.
* destroy will destroy the persisted object from the cloud
* save will persist the object to the cloud
* wait_for takes a block and waits for either the block to return true for the object or for a timeout (defaults to 10 minutes)

== Mocks

Mocking provides an in memory representation of clouds as you make different requests.
This representation allows subsequent calls to mimic the behavior of the cloud while eliminating the cost and time needed to actually run tests against various providers.
Mocking is easy to use, just write any functions as you normally would and then in your tests ensure you call:

  Fog.mock!

Make sure you call it first (before you initialize any connections) and all your calls should now run in mock mode.
If you run into the edges of mock implementation it should let you know that they haven't been implemented yet.

== Requests

Requests allow you to dive deeper when the models just can't cut it.
For instance, ec2 provides methods related to reserved instances that don't have any models (yet anyway).
You can get a description of your reserved instances like this:

  $ fog
  >> AWS[:ec2].describe_reserved_instances
  #<Excon::Response [...]>

It will return an excon response, which has headers and body methods. Both give nice ruby hash representations of the result.

== Go forth and conquer

That should give you some stuff to try and places to look.

You should try out the (varying) support fog has for:
* AWS [EC2, S3, SimpleDB]
* Rackspace [Files, Servers]
* Slicehost
* Terremark vCloud Express

Enjoy, and let me know what I can do to continue improving fog!

* Follow {@geemus}[http://twitter.com/geemus] on Twitter.
* See upcoming work in the {tracker}[http://www.pivotaltracker.com/projects/54635].
* Report bugs in {issues}[http://github.com/geemus/fog/issues].

== Copyright

(The MIT License)

Copyright (c) 2010 {geemus (Wesley Beary)}[http://github.com/geemus]

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.