diff --git a/lib/fog/rackspace/docs/block_storage.md b/lib/fog/rackspace/docs/block_storage.md new file mode 100644 index 000000000..0bc828fc2 --- /dev/null +++ b/lib/fog/rackspace/docs/block_storage.md @@ -0,0 +1,414 @@ +#Cloud Block Storage (BlockStorage) + +This document explains how to get started using Cloud Block Storage with Fog. It assumes you have read the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. + +## Starting irb console +Start by executing the following command: + + irb + +Once `irb` has launched you need to require the Fog library. + +If using Ruby 1.8.x execute: + + require 'rubygems' + require 'fog' + +If using Ruby 1.9.x execute: + + require 'fog' + +## Create Service + +Next, create a connection to Cloud Block Storage: + +Using a US based account: + + service = Fog::Rackspace::BlockStorage.new({ + :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username + :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key + :rackspace_region => :ord # Defaults to :dfw + :connection_options => {} # Optional + }) + +Using a UK based account: + + service = Fog::Rackspace::BlockStorage.new({ + :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username + :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key + :rackspace_auth_url => Fog::Rackspace::UK_AUTH_ENDPOINT + :rackspace_region => :lon + :connection_options => {} # Optional + }) + +To learn more about obtaining cloud credentials refer to the [Getting Started with Fog and the Rackspace Open Cloud](getting_started.md) document. + +By default `Fog::Rackspace::BlockStorage` will authenticate against the US authentication endpoint and connect to the DFW region. You can specify alternative authentication endpoints using the key `:rackspace_auth_url`. Please refer to [Alternate Authentication Endpoints](http://docs.rackspace.com/auth/api/v2.0/auth-client-devguide/content/Endpoints-d1e180.html) for a list of alternative Rackspace authentication endpoints. + +Alternative regions are specified using the key `:rackspace_region `. A list of regions available for Cloud Block Storage can be found by executing the following: + + identity_service = Fog::Identity({ + :provider => 'Rackspace', # Rackspace Fog provider + :rackspace_username => RACKSPACE_USER_NAME, # Your Rackspace Username + :rackspace_api_key => RACKSPACE_API, # Your Rackspace API key + :rackspace_auth_url => Fog::Rackspace::UK_AUTH_ENDPOINT # Not specified for US Cloud + }) + + identity_service.service_catalog.display_service_regions :cloudBlockStorage + +Rackspace Private Cloud installations can skip specifying a region and directly specify their custom service endpoints using the key `:rackspace_block_storage_url`. + +**Note**: A`Fog::Rackspace::BlockStorage` instance is needed for the desired region. + +### Optional Connection Parameters + +Fog supports passing additional connection parameters to its underlying HTTP library (Excon) using the `:connection_options` parameter. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescription
:connect_timeoutConnection timeout (default: 60 seconds)
:read_timeoutRead timeout for connection (default: 60 seconds)
:write_timeoutWrite timeout for connection (default: 60 seconds)
:proxyProxy for HTTP and HTTPS connections
:ssl_ca_pathPath to SSL certificate authorities
:ssl_ca_fileSSL certificate authority file
:ssl_verify_peerSSL verify peer (default: true)
+ + +## Fog Abstractions +Fog provides both a **model** and **request** abstraction. The request abstraction provides the most efficient interface and the model abstraction wraps the request abstraction to provide a convenient `ActiveModel` like interface. + +### Request Layer +The request abstraction maps directly to the [Cloud Block Storage API](http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/overview.html). It provides the most efficient interface to the Rackspace Open Cloud. + +To see a list of requests supported by the service: + + service.requests + +This returns: + + :create_volume, :delete_volume, :get_volume, :list_volumes, :get_volume_type, :list_volume_types, :create_snapshot, :delete_snapshot, :get_snapshot, :list_snapshots + + +#### Example Request + +To request a list of flavors: + + response = service.list_volume_types + +This returns in the following `Excon::Response`: + + "Mon, 18 Mar 2013 20:26:03 GMT", "Content-Length"=>"109", "Content-Type"=>"application/json", "X-Compute-Request-Id"=>"req-9c2093d4-8a41-4d8b-a069-114470d1a0dd"}, @data={:status=>200, :headers=>{"Date"=>"Mon, 18 Mar 2013 20:26:03 GMT", "Content-Length"=>"109", "Content-Type"=>"application/json", "X-Compute-Request-Id"=>"req-9c2093d4-8a41-4d8b-a069-114470d1a0dd"}, :remote_ip=>"72.32.164.210", :body=>{"volume_types"=>[{"name"=>"SATA", "id"=>1, "extra_specs"=>{}}, {"name"=>"SSD", "id"=>2, "extra_specs"=>{}}]}}> + +To view the status of the response: + + response.status + +**Note**: Fog is aware valid HTTP response statuses for each request type. If an unexpected HTTP response status occurs, Fog will raise an exception. + +To view response body: + + response.body + +This will return: + + {"volume_types"=>[{"name"=>"SATA", "id"=>1, "extra_specs"=>{}}, {"name"=>"SSD", "id"=>2, "extra_specs"=>{}}]} + + +To learn more about Cloud Block Storage request methods refer to [rdoc](http://rubydoc.info/gems/fog/Fog/Rackspace/BlockStorage/Real). To learn more about Excon refer to [Excon GitHub repo](https://github.com/geemus/excon). + +### Model Layer +Fog models behave in a manner similar to `ActiveModel`. Models will generally respond to `create`, `save`, `persisted?`, `destroy`, `reload` and `attributes` methods. Additionally, fog will automatically create attribute accessors. + +Here is a summary of common model methods: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
create + Accepts hash of attributes and creates object.
+ Note: creation is a non blocking call and you will be required to wait for a valid state before using resulting object. +
saveSaves object.
+ Note: not all objects support updating object.
persisted?Returns true if the object has been persisted.
destroy + Destroys object.
+ Note: this is a non blocking call and object deletion might not be instantaneous. +
reloadUpdates object with latest state from service.
ready?Returns true if object is in a ready state and able to perform actions. This method will raise an exception if object is in an error state.
attributesReturns a hash containing the list of model attributes and values.
identity + Returns the identity of the object.
+ Note: This might not always be equal to object.id. +
wait_forThis method periodically reloads model and then yields to specified block until block returns true or a timeout occurs.
+ +The remainder of this document details the model abstraction. + + +## List Volume Types + +To retrieve a list of volume types: + + service.volume_types + +This returns a collection of `Fog::Rackspace::BlockStorage::VolumeType` models: + + , + + ] + > + +## List Volumes + +To retrieve a list of volumes: + + service.volumes + +This returns a collection of `Fog::Rackspace::BlockStorage::Volume` models: + + , + + ] + > + +## Get Volume + +To retrieve an individual volume: + + service.volume.get "fog-example" + +This returns a `Fog::Rackspace::BlockStorage::Volume`: + + + +## Create Volume + +To create a volume: + + volume = service.volumes.create(:size => 100, :display_name => 'fog-ssd', :volume_type => 'SSD' ) + +This will return a `Fog::Rackspace::BlockStorage::Volume`: + + + +The `size` parameter is in gigabytes and it must be a minimum of 100 GB. The `size` parameter is the only required parameter. + +### Additional Parameters + +The `create` method also supports the following key values: + + + + + + + + + + + + + + + + + + + + + + +
KeyDescription
:display_nameThe name of the volume.
:display_descriptionA description of the volume.
:snapshot_idThe optional snapshot from which to create a volume.
:volume_typeThe type of volume to create. Refer to List Volume Types for valid types. If not defined, then the default, SATA, is used.
+ +## Attach Volume + +Refer the [Attach Volume](compute_v2.md#attach-volume) section in the [Next Generation Cloud Servers™ (compute_v2)](compute_v2.md) documentation. + +## Detach Volume + +Refer the [Detach Volume](compute_v2.md#detach-volume) section in the [Next Generation Cloud Servers™ (compute_v2)](compute_v2.md) documentation. + + +## Delete Volume + +To delete a volume: + + volume.destroy + +**Note**: You cannot delete a volume once you have created a snapshot from it. + +## List Snapshots + +To retrieve a list of all snapshots: + + service.snapshots + +To retrieve a list of snapshots for a given volume: + + volume.snapshots + +## Create Snapshot + +A snapshot is a point-in-time copy of the volume. Each subsequent will be the difference between the last snapshot and the current state of the volume. + +To create a snapshot of a given volume: + + volume.create_snapshot :display_name => 'initial-snapshot' + +**Note**: All writes to the volume should be flushed before creating the snapshot, either by un-mounting any file systems on the volume, or by detaching the volume before creating the snapshot. + +### Additional Parameters + +The `create_snapshot` method also supports the following key values: + + + + + + + + + + + + + + + + + + +
KeyDescription
:display_nameThe name of the snapshot.
:display_descriptionA description of the snapshot.
:forceIndicate whether to snapshot, even if the volume is attached.
+ + + +## Delete Snapshot + +To delete a snapshot: + + snapshot.destroy + +## Examples + +Example code using Cloud Block Storage can be found [here](https://github.com/fog/fog/tree/master/lib/fog/rackspace/examples). + +## Additional Resources + +* [fog.io](http://fog.io/) +* [Fog rdoc](http://rubydoc.info/gems/fog/) +* [Fog Github repo](https://github.com/fog/fog) +* [Fog Github Issues](https://github.com/fog/fog/issues) +* [Excon Github repo](https://github.com/geemus/excon) +* [Cloud Block Storage API](http://docs.rackspace.com/cbs/api/v1.0/cbs-devguide/content/index.html) + +## Support and Feedback + +Your feedback is appreciated! If you have specific issues with the **fog** SDK, you should file an [issue via Github](https://github.com/fog/fog/issues). + +For general feedback and support requests, send an email to: .