mirror of
https://github.com/fog/fog.git
synced 2022-11-09 13:51:43 -05:00
pull/convert info from README for index
This commit is contained in:
geemus
parent
07b49be6fb
commit
d935a6106a
1 changed files with 160 additions and 1 deletions
161
docs/index.md
161
docs/index.md
|
|
@ -13,9 +13,168 @@ By coding with fog from the start you avoid vendor lock-in and give yourself mor
|
|||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
## Getting Started
|
||||
|
||||
fog.io is very much a work in progress. In the meantime there are some great details available in the <a href="https://github.com/geemus/fog/blob/master/README.rdoc">README</a>.
|
||||
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
|
||||
|
||||
## 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)
|
||||
|
||||
## 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!
|
||||
|
||||
## 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.
|
||||
|
||||
## 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)
|
||||
|
||||
## Sponsorship
|
||||
|
||||
http://www.engineyard.com/images/logo.png
|
||||
|
||||
All new work on fog is sponsored by [Engine Yard](http://engineyard.com)
|
||||
|
||||
## 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.
|
||||
|
||||
## See Also:
|
||||
{% for post in site.posts %}
|
||||
|
|
|
|||
Loading…
Reference in a new issue