From 101b08e3cc6efd7f173e880a6f0c8034f6033b3c Mon Sep 17 00:00:00 2001 From: "geemus (Wesley Beary)" Date: Mon, 22 Mar 2010 22:32:01 -0700 Subject: [PATCH] overhaul readme --- README.rdoc | 127 ++++++++++++++++++++++++---------------------------- 1 file changed, 59 insertions(+), 68 deletions(-) diff --git a/README.rdoc b/README.rdoc index fca464e9a..798b37f53 100644 --- a/README.rdoc +++ b/README.rdoc @@ -1,64 +1,46 @@ = fog -fog helps you interact with cloud services. fog is a work in progress. +fog helps you interact with cloud services. -== Install +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. - sudo gem install fog +Put them together and you get a great cloud computing experience, but we are getting ahead of ourselves... == Getting Started -You can start stumbling around as soon as you install with the fog command line tool. -After installing, just type 'fog' to get started. -If you don't have credentials setup it will let you know what to do. + sudo gem install fog -Then just start playing around, fog should let you know if you are forget things. +Now just type 'fog' to trying stuff out, confident that fog should let you know what you need to do. -For example if you try to create a server but leave out stuff: - - server = AWS.servers.create - -You'll get reminded that things are missing. +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') + + >> server.destroy # cleanup after yourself or regret it, trust me + true -So just add the missing stuff and you are off to the races: +== Collections - server = AWS.servers.create(:image_id => 'ami-5ee70037') +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. -But don't forget to cleanup or you'll regret it when you get the bill: +Common compute nouns are flavors, images and servers. - server.destroy +Common storage nouns are directory and file. -Rinse, repeat, enjoy! - -== Working with Servers - -Lets boot up a server on EC2 +As an example, we'll try initializing and persisting a rackspace server: require 'fog' - # initialize a connection to Amazon Elastic Compute Cloud - connection = Fog::AWS::EC2.new( - :aws_access_key_id => id, - :aws_secret_access_key => key - ) - - # boot a gentoo server - server = connection.servers.new(:image_id => 'ami-5ee70037') - # you might also want to add the server to security groups, which goes like this: - # AWS.servers.create(:image_id => 'ami-5ee70037', :groups => ['web', 'db']) - - # wait for it to be ready to do stuff - server.wait_for { ready? } - - # DO STUFF - - # shutdown the server - server.destroy - -Now we will try again, but with Rackspace - # initialize a connection to Rackspace Servers connection = Fog::Rackspace::Servers.new( :rackspace_api_key => key, @@ -76,53 +58,62 @@ Now we will try again, but with Rackspace # shutdown the server server.destroy -== Working with Directories and Files +== Models - require 'fog' +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) - # initialize a connection to Amazon Simple Storage Solution - connection = Fog::AWS::S3.new( +== 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: + + connection = Fog::AWS::EC2.new( :aws_access_key_id => id, :aws_secret_access_key => key ) - # create a directory - directory = connection.directory.create(:name => 'directoryname') + connection.describe_reserved_instances - # create a new file in your directory - directory.files.create(:key => 'filename', :body => 'filebody') +It will return a nice ruby hash that you can get whatever data you might need from. - # connect to your directory - directory = connection.directories.get('directoryname') +== Go forth and conquer - # get your file - file = directory.files.get('filename') +That should give you some stuff to try and places to look. - # delete the file - file.destroy +You should try out the (varying) support fog has for: +* AWS [EC2, S3, SimpleDB] +* Rackspace [Files, Servers] +* Slicehost +* Terremark vCloud Express - # delete the directory - directory.destroy +{Let me know}[http://github.com/geemus/fog/issues] what I may have missed or should add. -== More info +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]. -== Supports - -* AWS EC2 -* AWS S3 -* AWS SimpleDB (no models yet) -* Rackspace Files (no models yet, just getting started on requests) -* Rackspace Servers (some requests, server model, just getting started) - == Copyright (The MIT License) -Copyright (c) 2009 {geemus (Wesley Beary)}[http://github.com/geemus] +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