mirror of
https://github.com/fog/fog.git
synced 2022-11-09 13:51:43 -05:00
9d92233102
I noticed some projects using Fog are setting very specific versioning constraint. For example, https://github.com/mitchellh/vagrant-rackspace/issues/34 happened because both vagrant-aws and vagrant-rackspace are using 3 digits of precision. The fog RELEASE.md says that Fog follows semantic versioning. Several other projects have put up notices suggesting to use 2 digits of precision for projects that follow semver. See https://github.com/intridea/multi_json, for example. I added a similar notice, but softened the language because I don't think there is a clear understanding on what semantic versioning means for a project like Fog, which has multiple providers backed by services that are all evolving at their own pace.
204 lines
8.6 KiB
Markdown
204 lines
8.6 KiB
Markdown
|
|
|
|
fog is the Ruby cloud services 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.
|
|
|
|
[](http://travis-ci.org/fog/fog)
|
|
[](http://badge.fury.io/rb/fog)
|
|
[](https://gemnasium.com/fog/fog)
|
|
[](https://codeclimate.com/github/fog/fog)
|
|
[](https://coveralls.io/r/fog/fog?branch=master)
|
|
|
|
## 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 = 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.destroy # cleanup after yourself or regret it, trust me
|
|
true
|
|
|
|
## Ruby 1.8.7
|
|
|
|
The maintainers of this project, in concert with the maintainers of Ruby,
|
|
**strongly** recommend using the latest patchlevel of Ruby 1.9.2 or later.
|
|
[As of July 1, 2013, Ruby 1.8.7 is no longer officially maintained.][retired]
|
|
This means fixes will no longer be provided, even for known security
|
|
vulnerabilities.
|
|
|
|
[retired]: http://www.ruby-lang.org/en/news/2013/06/30/we-retire-1-8-7/
|
|
|
|
With this caveat, if you wish to bundle `fog` into your application on Ruby
|
|
1.8.7, you must add the following line to your `Gemfile`.
|
|
|
|
gem 'nokogiri', '~>1.5.0'
|
|
|
|
Also, ensure that you are using LibXML version 2.8.0, since there is an
|
|
[issue with LibXML version 2.9.0][issue829] ([and 2.9.1][issue904]).
|
|
|
|
[issue829]: https://github.com/sparklemotion/nokogiri/issues/829
|
|
[issue904]: https://github.com/sparklemotion/nokogiri/issues/904
|
|
|
|
## 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:
|
|
|
|
>> 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`
|
|
|
|
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
|
|
>> 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.
|
|
|
|
## Go forth and conquer
|
|
|
|
Play around and use the console to explore or check out [fog.io](http://fog.io) and the [provider documentation](http://fog.io/about/provider_documentation.html)
|
|
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 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!"
|
|
|
|
## Versioning
|
|
|
|
Fog library aims to adhere to [Semantic Versioning 2.0.0][semver], although it does not
|
|
address challenges of multi-provider libraries. Semantic versioning is only guaranteed for
|
|
the common API, not any provider-specific extensions. You may also need to update your
|
|
configuration from time to time (even between Fog releases) as providers update or deprecate
|
|
services.
|
|
|
|
However, we still aim for forwards compatibility within Fog major versions. As a result of this policy, you can (and
|
|
should) specify a dependency on this gem using the [Pessimistic Version
|
|
Constraint][pvc] with two digits of precision. For example:
|
|
|
|
```ruby
|
|
spec.add_dependency 'fog', '~> 1.0'
|
|
```
|
|
|
|
This means your project is compatible with Fog 1.0 up until 2.0. You can also set a higher minimum version:
|
|
|
|
```ruby
|
|
spec.add_dependency 'fog', '~> 1.16'
|
|
```
|
|
|
|
[semver]: http://semver.org/
|
|
[pvc]: http://guides.rubygems.org/patterns/
|
|
|
|
## Contributing
|
|
|
|
* Find something you would like to work on.
|
|
* Look for anything you can help with in the [issue tracker](https://github.com/fog/fog/issues).
|
|
* Look at the [code quality metrics](https://codeclimate.com/github/fog/fog) for anything you can help clean up.
|
|
* Or anything else!
|
|
* Fork the project and do your work in a topic branch.
|
|
* Make sure your changes will work on both Ruby 1.8.7 and Ruby 1.9
|
|
* Add a config at `tests/.fog` for the component you want to test.
|
|
* Add shindo tests to prove your code works and run all the tests using `bundle exec rake`.
|
|
* Rebase your branch against `fog/fog` to make sure everything is up to date.
|
|
* Commit your changes and send a pull request.
|
|
|
|
## Additional Resources
|
|
|
|
* [fog.io](http://fog.io)
|
|
* [Provider Documentation](http://fog.io/about/provider_documentation.html)
|
|
|
|
## Copyright
|
|
|
|
(The MIT License)
|
|
|
|
Copyright (c) 2013 [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.
|