mirror of
https://github.com/fog/fog.git
synced 2022-11-09 13:51:43 -05:00
As discussed in #991, this converts the readme from SimpleMarkup to Markdown
This commit is contained in:
Mike Fiedler
parent
2c100b9064
commit
df3a0680a9
3 changed files with 68 additions and 63 deletions
|
|
@ -1,3 +1,3 @@
|
|||
README.rdoc
|
||||
README.md
|
||||
lib/**/*.rb
|
||||
bin/*
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
http://geemus.s3.amazonaws.com/fog.png
|
||||
|
||||
|
||||
fog is the Ruby cloud computing library, top to bottom:
|
||||
|
||||
|
|
@ -6,104 +6,109 @@ fog is the Ruby cloud computing library, top to bottom:
|
|||
* 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
|
||||
## Getting Started
|
||||
|
||||
sudo gem install fog
|
||||
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:
|
||||
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 = Compute[:aws].servers.create
|
||||
ArgumentError: image_id is required for this operation
|
||||
>> server = Compute[:aws].servers.create
|
||||
ArgumentError: image_id is required for this operation
|
||||
|
||||
>> server = Compute[:aws].servers.create(:image_id => 'ami-5ee70037')
|
||||
<Fog::AWS::EC2::Server [...]>
|
||||
>> server = Compute[:aws].servers.create(:image_id => 'ami-5ee70037')
|
||||
<Fog::AWS::EC2::Server [...]>
|
||||
|
||||
>> server.destroy # cleanup after yourself or regret it, trust me
|
||||
true
|
||||
>> server.destroy # cleanup after yourself or regret it, trust me
|
||||
true
|
||||
|
||||
== Collections
|
||||
## 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:
|
||||
You can see a list of available collections by calling `collections` on the connection object.
|
||||
You can try it out using the `fog` command:
|
||||
|
||||
>> Compute[:aws].collections
|
||||
[:addresses, :directories, ..., :volumes, :zones]
|
||||
>> Compute[: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+
|
||||
* 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.
|
||||
|
||||
* `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'
|
||||
require 'fog'
|
||||
|
||||
compute = Fog::Compute.new(
|
||||
:provider => 'Rackspace',
|
||||
:rackspace_api_key => key,
|
||||
:rackspace_username => username
|
||||
)
|
||||
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
|
||||
# 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
|
||||
# DO STUFF
|
||||
|
||||
server.destroy # cleanup after yourself or regret it, trust me
|
||||
server.destroy # cleanup after yourself or regret it, trust me
|
||||
|
||||
== Models
|
||||
## 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
|
||||
* `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!
|
||||
Fog.mock!
|
||||
|
||||
Then proceed as usual, if you run into unimplemented mocks fog will raise an error and as always contributions are welcome!
|
||||
Then proceed as usual, if you run into unimplemented mocks, fog will raise an error and as always contributions are welcome!
|
||||
|
||||
== Requests
|
||||
## 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.
|
||||
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
|
||||
>> Compute[:aws].describe_reserved_instances
|
||||
#<Excon::Response [...]>
|
||||
$ fog
|
||||
>> Compute[:aws].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.
|
||||
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
|
||||
## Go forth and conquer
|
||||
|
||||
Play around and use the console to explore or check out {fog.io}[http://fog.io] for more details and examples. Once you are ready to start scripting fog, here is a quick hint on how to make connections without the command line thing to help you.
|
||||
Play around and use the console to explore or check out [fog.io](http://fog.io) for more details and examples.
|
||||
Once you are ready 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 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
|
||||
# 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
|
||||
## 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/fog/fog/issues]
|
||||
* Fork the project and do your work in a topic branch.
|
||||
|
|
@ -111,21 +116,21 @@ geemus says: "That should give you everything you need to get started, but let m
|
|||
* Rebase your branch against fog/fog to make sure everything is up to date.
|
||||
* Commit your changes and send a pull request.
|
||||
|
||||
== Additional Resources
|
||||
## Additional Resources
|
||||
|
||||
{fog.io}[http://fog.io]
|
||||
[fog.io](http://fog.io)
|
||||
|
||||
== Sponsorship
|
||||
## Sponsorship
|
||||
|
||||
http://www.engineyard.com/images/logo.png
|
||||
|
||||
|
||||
All new work on fog is sponsored by {Engine Yard}[http://engineyard.com]
|
||||
All new work on fog is sponsored by [Engine Yard](http://engineyard.com)
|
||||
|
||||
== Copyright
|
||||
## Copyright
|
||||
|
||||
(The MIT License)
|
||||
|
||||
Copyright (c) 2010 {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
|
||||
|
|
@ -37,7 +37,7 @@ Gem::Specification.new do |s|
|
|||
## Specify any RDoc options here. You'll want to add your README and
|
||||
## LICENSE files to the extra_rdoc_files list.
|
||||
s.rdoc_options = ["--charset=UTF-8"]
|
||||
s.extra_rdoc_files = %w[README.rdoc]
|
||||
s.extra_rdoc_files = %w[README.md]
|
||||
|
||||
## List your runtime dependencies here. Runtime dependencies are those
|
||||
## that are needed for an end user to actually USE your code.
|
||||
|
|
|
|||
Loading…
Reference in a new issue