Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 160 lines (110 sloc) 7.845 kb
ac346e9 @geemus fix logo url
geemus authored
1 http://geemus.s3.amazonaws.com/fog.png
f9a0610 @geemus Initial commit to fog.
geemus authored
2
f7631dd @geemus README cleanup/editing
geemus authored
3 fog is the Ruby cloud computing library, top to bottom:
abe95d2 @technicalpickles REAMDE improvements (formatting, example of finding what collections exi...
technicalpickles authored
4
d7c3167 @geemus cleanup/update README
geemus authored
5 * Collections provide a simplified interface, making clouds easier to work with and switch between.
101b08e overhaul readme
geemus (Wesley Beary) authored
6 * Requests allow power users to get the most out of the features of each individual cloud.
7 * Mocks make testing and integrating a breeze.
dc1a271 @geemus adding a first pass at a readme
geemus authored
8
f67ca08 more readme updating
Wesley Beary authored
9 == Getting Started
dc1a271 @geemus adding a first pass at a readme
geemus authored
10
101b08e overhaul readme
geemus (Wesley Beary) authored
11 sudo gem install fog
f67ca08 more readme updating
Wesley Beary authored
12
f7631dd @geemus README cleanup/editing
geemus authored
13 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:
f67ca08 more readme updating
Wesley Beary authored
14
101b08e overhaul readme
geemus (Wesley Beary) authored
15 >> server = AWS.servers.create
f67ca08 more readme updating
Wesley Beary authored
16 ArgumentError: image_id is required for this operation
f171505 @geemus cleanup/update README
geemus authored
17
101b08e overhaul readme
geemus (Wesley Beary) authored
18 >> server = AWS.servers.create(:image_id => 'ami-5ee70037')
19 <Fog::AWS::EC2::Server [...]>
f171505 @geemus cleanup/update README
geemus authored
20
101b08e overhaul readme
geemus (Wesley Beary) authored
21 >> server.destroy # cleanup after yourself or regret it, trust me
22 true
f67ca08 more readme updating
Wesley Beary authored
23
101b08e overhaul readme
geemus (Wesley Beary) authored
24 == Collections
f67ca08 more readme updating
Wesley Beary authored
25
f7631dd @geemus README cleanup/editing
geemus authored
26 A high level interface to each cloud is provided through collections, such as `images` and `servers`.
27 You can see a list of available collections by calling `collections` on the connection object. You can try it out using the `fog` command:
abe95d2 @technicalpickles REAMDE improvements (formatting, example of finding what collections exi...
technicalpickles authored
28
f7631dd @geemus README cleanup/editing
geemus authored
29 >> AWS.collections
abe95d2 @technicalpickles REAMDE improvements (formatting, example of finding what collections exi...
technicalpickles authored
30 [:addresses, :directories, :files, :flavors, :images, :key_pairs, :security_groups, :servers, :snapshots, :volumes]
e0650c1 continued readme work
Wesley Beary authored
31
f7631dd @geemus README cleanup/editing
geemus authored
32 Some collections are available across multiple providers. For example, compute providers have +flavors+, +images+ and +servers+, and storage providers have +directory+ and +file+.
abe95d2 @technicalpickles REAMDE improvements (formatting, example of finding what collections exi...
technicalpickles authored
33
f7631dd @geemus README cleanup/editing
geemus authored
34 Collections share basic CRUD type operations, such as:
f171505 @geemus cleanup/update README
geemus authored
35 * +all+ - fetch every object of that type from the provider.
f7631dd @geemus README cleanup/editing
geemus authored
36 * +create+ - initialize a new record locally and a remote resource with the provider.
37 * +get+ - fetch a single object by it's identity from the provider.
38 * +new+ - initialize a new record locally, but create a remote resource with the provider.
e0650c1 continued readme work
Wesley Beary authored
39
8446c10 @geemus tightening up README a bit
geemus authored
40 As an example, we'll try initializing and persisting a Rackspace Cloud server:
dc1a271 @geemus adding a first pass at a readme
geemus authored
41
42 require 'fog'
43
8446c10 @geemus tightening up README a bit
geemus authored
44 # initialize a connection to Rackspace Cloud Servers
7519f5f update README
Wesley Beary authored
45 connection = Fog::Rackspace::Servers.new(
46 :rackspace_api_key => key,
47 :rackspace_username => username
48 )
49
50 # boot a gentoo server (flavor 1 = 256, image 3 = gentoo 2008.0)
036d0e4 @geemus fix readme server creation
geemus authored
51 server = connection.servers.create(:flavor_id => 1, :image_id => 3, :name => 'my_server')
7519f5f update README
Wesley Beary authored
52
53 # wait for it to be ready to do stuff
54 server.wait_for { ready? }
55
56 # DO STUFF
57
58 # shutdown the server
59 server.destroy
60
101b08e overhaul readme
geemus (Wesley Beary) authored
61 == Models
7519f5f update README
Wesley Beary authored
62
f7631dd @geemus README cleanup/editing
geemus authored
63 Many of the collection methods return individual objects, which also provide common methods:
f171505 @geemus cleanup/update README
geemus authored
64 * +destroy+ - will destroy the persisted object from the provider
65 * +save+ - persist the object to the provider
66 * +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)
101b08e overhaul readme
geemus (Wesley Beary) authored
67
68 == Mocks
dc1a271 @geemus adding a first pass at a readme
geemus authored
69
f7631dd @geemus README cleanup/editing
geemus authored
70 As you might imagine, testing code using Fog can be slow and expensive, constantly turning on and and shutting down instances.
71 Mocking allows skipping this overhead by providing an in memory representation resources as you make requests.
72 Enabling mocking easy to use, before you run other commands, simply run:
101b08e overhaul readme
geemus (Wesley Beary) authored
73
74 Fog.mock!
75
f7631dd @geemus README cleanup/editing
geemus authored
76 Then proceed as usual, if you run into unimplemented mocks fog will raise an error and as always contributions are welcome!
101b08e overhaul readme
geemus (Wesley Beary) authored
77
78 == Requests
79
80 Requests allow you to dive deeper when the models just can't cut it.
d7c3167 @geemus cleanup/update README
geemus authored
81 You can see a list of available requests by calling #requests on the connection object.
f7631dd @geemus README cleanup/editing
geemus authored
82
83 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:
101b08e overhaul readme
geemus (Wesley Beary) authored
84
c540fba readme, cleanup/correct request example
geemus (Wesley Beary) authored
85 $ fog
86 >> AWS[:ec2].describe_reserved_instances
87 #<Excon::Response [...]>
dc1a271 @geemus adding a first pass at a readme
geemus authored
88
f7631dd @geemus README cleanup/editing
geemus authored
89 It will return an {excon}[http://github.com/geemus/excon] response, which has `body`, `headers` and `status`. Both return nice hashes.
dc1a271 @geemus adding a first pass at a readme
geemus authored
90
101b08e overhaul readme
geemus (Wesley Beary) authored
91 == Go forth and conquer
dc1a271 @geemus adding a first pass at a readme
geemus authored
92
432361b @geemus add example of non-cli connection creation to README
geemus authored
93 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.
94
95 # create a compute connection
96 compute = Fog::Compute.new(:provider => 'AWS', :aws_access_key_id => ACCESS_KEY_ID, :aws_secret_access_key => SECRET_ACCESS_KEY)
97 # compute operations go here
98
99 # create a storage connection
100 storage = Fog::Storage.new(:provider => 'AWS', :aws_access_key_id => ACCESS_KEY_ID, :aws_secret_access_key => SECRET_ACCESS_KEY)
101 # storage operations go here
102
103 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!"
dc1a271 @geemus adding a first pass at a readme
geemus authored
104
101b08e overhaul readme
geemus (Wesley Beary) authored
105 You should try out the (varying) support fog has for:
f8768f9 @geemus update readme to better map to compute/storage naming
geemus authored
106 * {AWS}[http://aws.amazon.com] [{Compute}[http://aws.amazon.com/ec2], {ELB}[http://aws.amazon.com/elasticloadbalancing], {Storage}[http://aws.amazon.com/s3], {SimpleDB}[http://aws.amazon.com/simpledb]]
107 * {Blue Box Group}[http://www.blueboxgrp.com] [{Compute}[http://www.blueboxgrp.com/blocks]]
0ec77fc @tokengeek [brightbox] Added support for Brightbox cloud API beta (http://beta.brig...
tokengeek authored
108 * {Brightbox}[http://www.brightbox.co.uk] [{Compute}[http://beta.brightbox.com/]]
cb1f9de @geemus add google storage to readme
geemus authored
109 * {Google}[http://www.google.com] [{Storage}[http://code.google.com/apis/storage]]
2ed751c @geemus README update services list
geemus authored
110 * Local [Storage]
f8768f9 @geemus update readme to better map to compute/storage naming
geemus authored
111 * {Rackspace}[http://www.rackspace.com] [{Compute}[http://www.rackspacecloud.com/cloud_hosting_products/servers], {Storage}[http://www.rackspacecloud.com/cloud_hosting_products/files]]
2ed751c @geemus README update services list
geemus authored
112 * {Slicehost}[http://www.slicehost.com] [{Compute}[http://www.slicehost.com], {DNS}[http://www.slicehost.com]]
4703971 @geemus also link the company that provides each set of services
geemus authored
113 * {Terremark}[http://www.terremark.com] [{vCloud Express}[http://vcloudexpress.terremark.com]]
aad7ff0 @geemus update README with stuff that has basic support
geemus authored
114
115 There are also the basics of these providers (that could use your love):
f8768f9 @geemus update readme to better map to compute/storage naming
geemus authored
116 * {GoGrid}[http://www.gogrid.com] [{Compute}[http://www.gogrid.com]]
2ed751c @geemus README update services list
geemus authored
117 * {Linode}[http://www.linode.com] [{Compute}[http://www.linode.com], {DNS}[http://www.linode.com]]
f8768f9 @geemus update readme to better map to compute/storage naming
geemus authored
118 * {New Servers}[http://www.newservers.com] [{Compute}[http://www.newservers.com]]
2ed751c @geemus README update services list
geemus authored
119 * {Zerigo}[http://www.zerigo.com] [{DNS}[http://www.zerigo.com/managed-dns]
dc1a271 @geemus adding a first pass at a readme
geemus authored
120
101b08e overhaul readme
geemus (Wesley Beary) authored
121 Enjoy, and let me know what I can do to continue improving fog!
dc1a271 @geemus adding a first pass at a readme
geemus authored
122
1ea7e2f @geemus update readme with @fog
geemus authored
123 * Follow {@fog}[http://twitter.com/fog] and/or {@geemus}[http://twitter.com/geemus] on Twitter
8c3c98e @geemus note in readme that mailing list has release notes
geemus authored
124 * Discuss in irc on the {#ruby-fog}[irc://irc.freenode.net/ruby-fog] channel on Freenode
125 * Discuss via email on the {mailing list}[http://groups.google.com/group/ruby-fog] (note: release notes appear on this list)
e61ea3c @geemus remove tracker reference from README
geemus authored
126 * Report bugs or find stuff to work on in {issues}[http://github.com/geemus/fog/issues]
35101ee @geemus update/fix contributor guide link in readme
geemus authored
127 * Learn about {contributing}[http://github.com/geemus/fog/wiki/contributor-guide] or find more info about the {Providers}[http://github.com/geemus/fog/wiki/Providers] (including some todo items)
1ea7e2f @geemus update readme with @fog
geemus authored
128 * See what already uses fog and add your own stuff to {the list}[http://wiki.github.com/geemus/fog/in-the-wild]
dc1a271 @geemus adding a first pass at a readme
geemus authored
129
f171505 @geemus cleanup/update README
geemus authored
130 == Sponsorship
131
132 http://www.engineyard.com/images/logo.png
133
134 All new work on fog is sponsored by {Engine Yard}[http://engineyard.com]
135
d993636 @geemus fix readme to give copyright its own heading
geemus authored
136 == Copyright
f9a0610 @geemus Initial commit to fog.
geemus authored
137
52b3199 @geemus consolidate readme/license
geemus authored
138 (The MIT License)
139
101b08e overhaul readme
geemus (Wesley Beary) authored
140 Copyright (c) 2010 {geemus (Wesley Beary)}[http://github.com/geemus]
52b3199 @geemus consolidate readme/license
geemus authored
141
142 Permission is hereby granted, free of charge, to any person obtaining
143 a copy of this software and associated documentation files (the
144 "Software"), to deal in the Software without restriction, including
145 without limitation the rights to use, copy, modify, merge, publish,
146 distribute, sublicense, and/or sell copies of the Software, and to
147 permit persons to whom the Software is furnished to do so, subject to
148 the following conditions:
149
150 The above copyright notice and this permission notice shall be
151 included in all copies or substantial portions of the Software.
152
153 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
154 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
155 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
156 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
157 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
158 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
159 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.