fog 0.7.1 → 0.7.2

data/docs/_posts/2011-01-01-dns.markdown

@@ -0,0 +1,79 @@
+---
+layout: default
+title:  dns
+---
+
+The power and flexibility of the cloud are amazing. But sometimes it can be a pain to chase your resources around and keep everything up to date. This is especially true of keeping track of addresses for DNS, but thankfully more and more API driven options are available, allowing you to automate your DNS to keep up with your hardware changes.
+
+## Setup
+
+First, make sure you have fog installed:
+
+    gem install fog
+
+For this first example we will use Zerigo (see below for how to use other providers). You can signup for Zerigo DNS <a href="https://www.zerigo.com/signup/dns">here</a>. Gather up your new credentials to initialize a connection to the service:
+
+    require 'rubygems'
+    require 'fog'
+
+    # create a connection to the service
+    dns = Fog::DNS.new({
+      :provider     =&gt; 'Zerigo',
+      :zerigo_email =&gt; ZERIGO_EMAIL,
+      :zerigo_token =&gt; ZERIGO_TOKEN
+    }
+
+## Getting in the Zone
+
+The first thing you need to do to prepare for your DNS excursion is create a zone for your domain.  The zone will contain all of the more specific records that you will create later.  You will just need to specify the domain, which should be your url without the 'http' or 'www' parts, and an email address.  Then you can create the zone with your DNS connection:<!--more-->
+
+    zone = @dns.zones.create(
+      :domain =&gt; 'example.com',
+      :email  =&gt; 'admin@example.com'
+    )
+
+Now that you have a zone you will need to update your registrar to let them know what DNS servers are responsible for your domain.  You can ask the zone what values to use:
+
+    zone.nameservers
+
+## Spinning Records
+
+With your new zone in hand you can add records as needed.  First and foremost you will probably want the 'www' version of your site to point to whatever your ip might be:
+
+    record = @zone.records.create(
+      :ip   =&gt; '1.2.3.4',
+      :name =&gt; 'example.com',
+      :type =&gt; 'A'
+    )
+
+Adding other records is similarly easy, for instance if we want 'www.example.com' to go to the same place, we can use a cname record:
+
+    record = @zone.records.create(
+      :ip   =&gt; 'example.com',
+      :name =&gt; 'www',
+      :type =&gt; 'CNAME'
+    )
+
+Or, similarly you might want to have your blog elsewhere:
+
+    record = @zone.records.create(
+      :ip   =&gt; '4.3.2.1',
+      :name =&gt; 'blog.example.com',
+      :type =&gt; 'A'
+    )
+
+You can add more specifics if you need to, but reasonable defaults make it just that easy.  You can also add any other kind of DNS record you might need for mail or other purposes, you can find a nice overview of record options and types <a href="http://en.wikipedia.org/wiki/Domain_Name_System#DNS_resource_records">on Wikipedia</a>.
+
+## No Zerigo? No Problem
+
+If you already have an account with another service you can just as easily use this same code with different credentials. fog currently supports <a href="http://aws.amazon.com/route53/">AWS Route 53</a>, <a href="http://bluebox.net">Blue Box</a>, <a href="http://dnsimple.com">DNSimple</a>, <a href="http://www.linode.com">Linode</a>, <a href="http://www.slicehost.com">Slicehost</a> and <a href="http://www.zerigo.com/managed-dns">Zerigo</a>; so you can have your pick.  As an example you can connect to AWS instead of Zerigo:
+
+    dns = Fog::DNS.new(
+      :provider               =&gt; 'AWS',
+      :aws_access_key_id      =&gt; AWS_ACCESS_KEY_ID,
+      :aws_secret_access_key  =&gt; AWS_SECRET_ACCESS_KEY
+    )
+
+## Go Forth and Resolve
+
+You can see an example of reusing code like this in the <a href="https://github.com/geemus/fog/blob/master/examples/dns_tests.rb">examples folder</a>. Using this makes it easier to give yourself shortcuts to your cloud servers and manage how clients and users access them as well. It is great to have this flexibility so that you can modify your cloud infrastructure as needed while keeping everything ship shape. It also provides a nice way to create custom subdomains for users and just generally round out your cloud solution.

data/docs/_posts/2011-01-01-press.markdown

@@ -0,0 +1,32 @@
+---
+layout: default
+title:  Press
+---
+
+Mentions and blog posts from elsewhere in reverse chronological order by day (and alphasorted for same days).
+
+**March 9th, 2011**
+
+* [Offsite Backups with fog](http://www.engineyard.com/blog/2011/offsite-backups-with-fog/)
+
+**March 2nd, 2011**
+
+* [Better AWS Access Control with IAM and Fog](http://blog.zerosum.org/2011/03/02/better-aws-access-control-with-iam-and-fog.html)
+* [Using Amazon's CloudFormation, cloud-init, chef and fog to automate infrastructure](http://allanfeid.com/content/using-amazons-cloudformation-cloud-init-chef-and-fog-automate-infrastructure)
+
+**January 6th, 2011**
+
+* [Happy New Year (and 0.4.0) from fog!](http://www.engineyard.com/blog/2011/happy-new-year-and-0-4-0-from-fog/)
+
+**November 30th, 2010**
+
+* [Getting Hired: fog Edition](http://www.engineyard.com/blog/2010/getting-hired-fog-edition/)
+
+**October 13, 2010**
+
+* [Engine Yard Announces Formal Support for ‘fog’ to Ensure Application Portability in the Cloud](http://www.engineyard.com/company/press/2010-10-13-engine-yard-announces-formal-support-for-%E2%80%98fog%E2%80%99-to-ensure-application-portability-in-the-cloud)
+* [Wesley Beary and fog Promoted to the Engine Yard Open Source Program](http://www.engineyard.com/blog/2010/wesley-beary-and-fog-promoted-to-the-engine-yard-open-source-program/)
+
+**September 28, 2010**
+
+* [The Curious Tale of the Humble Micro](http://www.engineyard.com/blog/2010/the-curious-tale-of-the-humble-micro/)

data/docs/_posts/2011-01-01-start.markdown

@@ -0,0 +1,21 @@
+---
+layout: default
+title:  Getting Started
+---
+
+First off, install the gem:
+
+    $ gem install fog
+
+## Setting Up Local Storage
+
+We will be using local storage in the example, so first off make a local directory that things can go in.
+
+    $ mkdir ~/fog
+
+Now We can start building out our script to play with.  First thing is first, we will setup a storage connection.
+
+    Fog::Storage.new(
+      :local_root => '~/fog',
+      :provider   => 'Local',
+    )

data/docs/_posts/2011-01-01-storage.markdown

@@ -0,0 +1,145 @@
+---
+layout: default
+title:  storage
+---
+
+Having Ruby experience makes you hirable; but how can you stand out? You need to demonstrate your abilities. What better way than using Ruby and "the cloud" to store and serve your resume!
+
+In this blog post you will learn to use <a href="http://github.com/geemus/fog">fog</a> - the cloud computing library - to upload your resume to Amazon's <a href="http://aws.amazon.com/s3/">Simple Storage Service</a> (S3), Rackspace's <a href="http://www.rackspacecloud.com/cloud_hosting_products/files">CloudFiles</a> or Google's <a href="http://code.google.com/apis/storage/">Storage for Developers</a>.
+
+Here's my out of date resume stored on <a href="http://geemus.s3.amazonaws.com/resume.html">S3</a>, <a href="http://c0023559.cdn2.cloudfiles.rackspacecloud.com/resume.html">CloudFiles</a> and <a href="https://geemus.commondatastorage.googleapis.com/resume.html">Google Storage</a>; programmatically stored in the cloud using this tutorial. NOTE: my boss would like me to add that I'm not currently looking for a new gig ;)
+
+Check out those cloud-specific URLs! You could put all three in your job application, add the Ruby source for how you did it, and have your choice of Ruby jobs for being so awesome!
+
+How? The all-clouds-in-one library of choice is <a href="https://github.com/geemus/fog">fog</a>.
+
+## Installing fog
+
+fog is distributed as a RubyGem:
+
+    gem install fog
+
+Or add it in your application's Gemfile:
+
+    gem "fog"
+
+## Using Amazon S3 and fog
+
+Sign up for an account <a href="http://aws-portal.amazon.com/gp/aws/developer/subscription/index.html?productCode=AmazonS3">here</a> and copy down your secret access key and access key id from <a href="http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key">here</a>. We are about to get into the code samples, so be sure to fill in anything in ALL_CAPS with your own values!
+
+First, create a connection with your new account:
+
+    require 'rubygems'
+    require 'fog'
+
+    # create a connection
+    connection = Fog::Storage.new(
+      :provider                 =&gt; 'AWS',
+      :aws_secret_access_key    =&gt; YOUR_SECRET_ACCESS_KEY,
+      :aws_access_key_id =&gt; YOUR_SECRET_ACCESS_KEY_ID
+    )
+
+    # First, a place to contain the glorious details
+    directory = connection.directories.create(
+      :key    =&gt; "fog-demo-#{Time.now.to_i}", # globally unique name
+      :public =&gt; true
+    )
+
+    # list directories
+    p connection.directories
+
+    # upload that resume
+    file = directory.files.create(
+      :key    =&gt; 'resume.html',
+      :body   =&gt; File.open("/path/to/my/resume.html"),
+      :public =&gt; true
+    )
+
+If you are anything like me, you will continually tweak your resume. Pushing updates is easy:
+
+    file.body = File.open("/path/to/my/resume.html")
+    file.save
+
+As you can see, cloud storage files in fog are a lot like an ActiveRecord model. Attributes that can be changed and a `#save` method that creates or updates the stored file in the cloud.
+
+But if it took you longer to realize the mistake you might not still have file around, but you've got options.
+
+directory = connection.directories.get("proclamations1234567890")
+
+    # get the resume file
+    file = directory.files.get('resume.html')
+    file.body = File.open("/path/to/my/resume.html")
+    file.save
+
+    # also, create(attributes) is just new(attributes).save, so you can also do:
+    file = directory.files.new(
+      :key =&gt; 'resume.html',
+      :body =&gt; 'improvements',
+      :public =&gt; true
+    )
+    file.save
+
+Alright, so you (eventually) become satisfied enough to send it off, what is the URL endpoint to your resume?
+
+    puts file.public_url
+
+Pop that link in an email and you should be ready to cruise job ads and send your resume far and wide (Engine Yard is <a href="http://www.engineyard.com/company/careers/wanted-head-in-the-clouds-engineer">hiring</a>, so check us out!). Now you are set, unless you are interviewing for Google, or Rackspace... Both of these companies have their own cloud storage services, so using Amazon S3 might not be the foot in the door you hoped for.
+
+More clouds? How much extra stuff will you have to do for these services!?! Hardly anything needs to change, you just have to pass slightly different credentials in, but I'm getting ahead of myself.
+
+## Google Storage for Developers
+
+Sign up <a href="http://gs-signup-redirect.appspot.com/">here</a> and get your credentials <a href="https://sandbox.google.com/storage/m/">here</a>.
+
+    connection = Fog::Storage.new(
+      :provider =&gt; 'Google',
+      :google_storage_secret_access_key =&gt; YOUR_SECRET_ACCESS_KEY,
+      :google_storage_access_key_id =&gt; YOUR_SECRET_ACCESS_KEY_ID
+    )
+
+## Rackspace CloudFiles
+
+Rackspace has <a href="http://www.rackspacecloud.com/cloud_hosting_products/files">Cloud Files</a> and you can sign up <a href="https://www.rackspacecloud.com/signup">here</a> and get your credentials <a href="https://manage.rackspacecloud.com/APIAccess.do">here</a>.
+
+    connection = Fog::Storage.new(
+      :provider =&gt; 'Rackspace',
+      :rackspace_username =&gt; RACKSPACE_USERNAME,
+      :rackspace_api_key =&gt; RACKSPACE_API_KEY
+    )
+
+Then create, save, destroy as per fog-for-AWS. The `:public =&gt; true` option when creating directories (see above) is important for Rackspace; your folder and files won't be shared to Rackspace's CDN and hence your users without it.  Similarly the `:public =&gt; true` on files is important for AWS and Google or they will be private.
+
+## Local Storage
+
+While you are working out the kinks you might not want to do everything live though, ditto for while you are running tests, so you have a couple options to try before you buy.  First, you can use a local provider to store things in a directory on your machine.
+
+    connection = Fog::Storage.new(
+      :provider =&gt; 'Local',
+      :local_root =&gt; '~/fog'
+    )
+
+## Mocking out Cloud Storage
+
+Of course when you are testing or developing you can always just use the mocks (at least for AWS and Google, Rackspace still needs mocks implemented if you are looking for somewhere to contribute).  They emulate the behavior of the external systems without actually using them.  It is as simple as:
+
+    Fog.mock!
+    connection = Fog::Storage.new(config_hash)
+
+## Cleaning up
+
+Fog takes care of the rest so you can focus on your cover letter. And with the awesome cover letter and cloud delivered resume you are probably a shoe-in. So all that is left is to cleanup that leftover job hunt residue.
+
+    file.destroy
+    directory.destroy
+
+## Summary
+
+All done. Try out all the different options and let me know if you have any bugs or issues.  I also wrote up a more <a href="https://gist.github.com/710869">consolidated example as a script</a> that you can use for reference.
+
+Bonus, note the `Fog.mock!` command. In your tests you can easily mock out calls to cloud providers.
+
+Please let me know in the comments if you got a new Ruby job because you hosted your CV on 3 different Cloud Stores without getting your hands dirty.
+
+Have questions or comments?  Hop into <a href="irc://irc.freenode.net/">#ruby-fog</a> on freenode, ping <a href="http://twitter.com/fog">@fog</a> or <a href="http://twitter.com/geemus">@geemus</a>.
+
+And please always remember that I accept high fives and contributions!

data/docs/_posts/2011-01-01-structure.markdown

@@ -0,0 +1,78 @@
+---
+layout: default
+title:  Structure
+---
+
+fog is the Ruby cloud computing library, top to bottom:
+
+* Collections 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.
+                                               
+## Collections
+
+A high level interface to each cloud is provided through collections, such as `images` and `servers`.
+You can see a list of available collections by calling `collections` on the connection object. You can try it out using the `fog` command:
+
+    >> AWS.collections
+    [:addresses, :directories, ..., :volumes, :zones]
+
+Some collections are available across multiple providers:
+
+* compute providers have `flavors`, `images` and `servers`
+* dns providers have `zones` and `records`
+* storage providers have `directories` and `files`
+
+Collections share basic CRUD type operations, such as:
+* `all` - fetch every object of that type from the provider.
+* `create` - initialize a new record locally and a remote resource with the provider.
+* `get` - fetch a single object by it's identity from the provider.
+* `new` - initialize a new record locally, but do not create a remote resource with the provider.
+
+As an example, we'll try initializing and persisting a Rackspace Cloud server:
+
+    require 'fog'
+
+    compute = Fog::Compute.new(
+      :provider           => 'Rackspace',
+      :rackspace_api_key  => key,
+      :rackspace_username => username
+    )
+
+    # boot a gentoo server (flavor 1 = 256, image 3 = gentoo 2008.0)
+    server = compute.servers.create(:flavor_id => 1, :image_id => 3, :name => 'my_server')
+    server.wait_for { ready? } # give server time to boot
+
+    # DO STUFF
+
+    server.destroy # cleanup after yourself or regret it, trust me
+
+## Models
+
+Many of the collection methods return individual objects, which also provide common methods:
+* `destroy` - will destroy the persisted object from the provider
+* `save` - persist the object to the provider
+* `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)
+
+## Requests
+
+Requests allow you to dive deeper when the models just can't cut it.
+You can see a list of available requests by calling #requests on the connection object.
+
+For instance, ec2 provides methods related to reserved instances that don't have any models (yet). Here is how you can lookup your reserved instances:
+
+    $ fog
+    >> AWS[:ec2].describe_reserved_instances
+    #<Excon::Response [...]>
+
+It will return an [excon](http://github.com/geemus/excon) response, which has `body`, `headers` and `status`. Both return nice hashes.
+
+## Mocks
+
+As you might imagine, testing code using Fog can be slow and expensive, constantly turning on and and shutting down instances.
+Mocking allows skipping this overhead by providing an in memory representation resources as you make requests.
+Enabling mocking easy to use, before you run other commands, simply run:
+
+    Fog.mock!
+
+Then proceed as usual, if you run into unimplemented mocks fog will raise an error and as always contributions are welcome!

data/docs/_posts/2011-01-01-users.markdown

@@ -0,0 +1,33 @@
+---
+layout: default
+title:  Users
+---
+
+Here lies a listing of projects and products that are using fog.
+
+Please feel free to add your own, just please follow these rules for consistency and readability.
+
+1. Listings should be in alphabetical order and should have a link and list of services used.
+2. Projects that are open source should link to where the source code can be found.
+3. Products that are not open source should link to where more information about the product can be found.
+
+Thanks for following these rules to keep the quality high and and the content useful!
+
+## Projects
+
+* [carrierwave](http://github.com/jnicklas/carrierwave) = AWS => Storage
+* [chef](http://github.com/opscode/chef) = AWS => Compute, Slicehost => Compute, Terremark => vCloud, Rackspace => Compute
+* [deckard](http://github.com/joewilliams/deckard) = AWS => Compute
+* [gaff](http://github.com/joewilliams/gaff) = AWS => Compute, Slicehost => Compute
+* [gemcutter](http://github.com/rubygems/gemcutter) = AWS => Storage
+* [plover](http://github.com/railsmachine/plover) = AWS => Compute
+
+## Products
+
+* [DevStructure](http://devstructure.com/) = AWS => Compute, Rackspace => Compute, Slicehost => Compute
+* [Engine Yard AppCloud](http://www.engineyard.com/cloud) = AWS => \[Compute, Storage\]
+* [iSwifter](http://iswifter.youwebinc.com/) = BlueBox => Compute
+* [OpenFeint](http://openfeint.com) = BlueBox => Compute
+* [PHPFog](https://phpfog.com) = AWS => Compute
+* [RowFeeder](https://rowfeeder.com) = Blue Box Group => Compute
+* [Viximo](http://viximo.com) = AWS => Compute

data/docs/index.markdown

@@ -0,0 +1,94 @@
+---
+layout: default
+title:  The Ruby cloud services library
+---
+
+Whether you need compute, dns, storage, or a multitude of other services, fog provides an accessible entry point and facilitates cross service compatibility.
+
+Just getting started working with cloud resources? You are not alone, and having so many complicated options makes it hard to know where to start. fog delivers the knowledge of cloud experts to you, helping you to bootstrap your cloud usage and guiding you as your own expertise develops.
+
+By coding with fog from the start you avoid vendor lock-in and give yourself more flexibility to provide value. Whether you are writing a library, designing a software as a service product or just hacking on the weekend this flexibility is a huge boon.
+
+With a rapidly expanding community and codebase the advantages of fog just keep coming. Join us and together we will realize the future of cloud computing.
+
+## Getting Started
+
+    sudo gem install fog
+
+Now type 'fog' to try stuff, confident that fog will let you know what 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
+
+## Go forth and conquer
+
+Play around and use the console to explore or check out the [getting started guide](http://wiki.github.com/geemus/fog/getting-started-with-fog) for more details. Once you are reading to start scripting fog, here is a quick hint on how to make connections without the command line thing to help you.
+
+    # create a compute connection
+    compute = Fog::Compute.new(:provider => 'AWS', :aws_access_key_id => ACCESS_KEY_ID, :aws_secret_access_key => SECRET_ACCESS_KEY)
+    # compute operations go here
+
+    # create a storage connection
+    storage = Fog::Storage.new(:provider => 'AWS', :aws_access_key_id => ACCESS_KEY_ID, :aws_secret_access_key => SECRET_ACCESS_KEY)
+    # storage operations go here
+
+geemus says: "That should give you everything you need to get started, but let me know if there is anything I can do to help!"
+
+## Contributing
+
+* Find something you would like to work on. For suggestions look for the `easy`, `medium` and `hard` tags in the [issues](http://github.com/geemus/fog/issues)
+* Fork the project and do your work in a topic branch.
+* Add shindo tests to prove your code works and run all the tests using `bundle exec rake`.
+* Rebase your branch against geemus/fog to make sure everything is up to date.
+* Commit your changes and send a pull request.
+
+## T-Shirts
+
+Wonder how you can get a lovely fog shirt? Look no further!
+
+* Blue shirts go to people who have contributed indirectly, great examples are writing blog posts or giving lightning talks.
+* Grey shirts and a follow from @fog go to people who have made it on to the [contributors list](https://github.com/geemus/fog/contributors) by submitting code.
+* Black shirts go to people who have made it on to the [collaborators list](https://github.com/api/v2/json/repos/show/geemus/fog/collaborators) by coercing geemus into adding them (geemus is currently the only member of this list).
+
+## Resources
+
+Enjoy, and let me know what I can do to continue improving fog!
+
+* Stay up to date by following [@fog](http://twitter.com/fog) and/or [@geemus](http://twitter.com/geemus) on Twitter.
+* Get and give help on the [#ruby-fog](irc://irc.freenode.net/ruby-fog) irc channel on Freenode
+* Follow release notes and discussions on the [mailing list](http://groups.google.com/group/ruby-fog)
+* Report bugs or find tasks to help with in the [issues](http://github.com/geemus/fog/issues)
+* Learn about [contributing](http://github.com/geemus/fog/wiki/contributor-guide)
+* See where fog is used and let the world know how you use it [in the wild](http://wiki.github.com/geemus/fog/in-the-wild)
+* Check out blog posts and other mentions in the [press](http://wiki.github.com/geemus/fog/press)
+
+## 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.