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 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 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 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: AFog::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.
Key | Description |
---|---|
:connect_timeout | Connection timeout (default: 60 seconds) |
:read_timeout | Read timeout for connection (default: 60 seconds) |
:write_timeout | Write timeout for connection (default: 60 seconds) |
:proxy | Proxy for HTTP and HTTPS connections |
:ssl_ca_path | Path to SSL certificate authorities |
:ssl_ca_file | SSL certificate authority file |
:ssl_verify_peer | SSL 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. 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 volume types:
response = service.list_volume_types
This returns in the following Excon::Response
:
<Excon::Response:0x10a708fb8 @remote_ip="72.32.164.210", @body="{\"volume_types\": [{\"extra_specs\": {}, \"name\": \"SATA\", \"id\": 1}, {\"extra_specs\": {}, \"name\": \"SSD\", \"id\": 2}]}", @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"}, @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 of 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. To learn more about Excon refer to Excon GitHub repo.
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:
Method | Description |
---|---|
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. |
save | Saves 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. |
reload | Updates 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. |
attributes | Returns 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_for | This 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:
<Fog::Rackspace::BlockStorage::VolumeTypes [ <Fog::Rackspace::BlockStorage::VolumeType id=1, name="SATA", extra_specs={} >, <Fog::Rackspace::BlockStorage::VolumeType id=2, name="SSD", extra_specs={} > ]
>
List Volumes¶ ↑
To retrieve a list of volumes:
service.volumes
This returns a collection of Fog::Rackspace::BlockStorage::Volume
models:
<Fog::Rackspace::BlockStorage::Volumes [ <Fog::Rackspace::BlockStorage::Volume id="a53a532f-546c-4da3-8c2d-b26be1046630", created_at="2013-03-19T14:19:16.000000", state="available", display_name="fog-ssd", display_description=nil, size=100, attachments=[], volume_type="SSD", availability_zone="nova" >, <Fog::Rackspace::BlockStorage::Volume id="e2359473-9933-483f-90df-deb4a9fb25ae", created_at="2013-03-19T14:16:45.000000", state="available", display_name="fog-example", display_description=nil, size=100, attachments=[], volume_type="SATA", availability_zone="nova" > ]
>
Get Volume¶ ↑
To retrieve an individual volume:
service.volume.get "fog-example"
This returns a Fog::Rackspace::BlockStorage::Volume
:
<Fog::Rackspace::BlockStorage::Volume id="e2359473-9933-483f-90df-deb4a9fb25ae", created_at="2013-03-19T14:16:45.000000", state="available", display_name="fog-example", display_description=nil, size=100, attachments=[], volume_type="SATA", availability_zone="nova" >
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
:
<Fog::Rackspace::BlockStorage::Volume id="a53a532f-546c-4da3-8c2d-b26be1046630", created_at="2013-03-19T14:19:16.000000", state="available", display_name="fog-ssd", display_description=nil, size=100, attachments=[], volume_type="SSD", availability_zone="nova"
>
Note: The :size
parameter is the only required parameter and is in gigabytes. Volumes must be a minimum of 100 GB.
Additional Parameters¶ ↑
The create
method also supports the following key values:
Key | Description |
---|---|
:display_name | The name of the volume. |
:display_description | A description of the volume. |
:snapshot_id | The optional snapshot from which to create a volume. |
:volume_type | The type of volume to create. Refer to List Volume Types section for valid types. SATA is the default volume type. |
Attach Volume¶ ↑
Please refer to the Attach Volume section in the Next Generation Cloud Servers™ (compute_v2) documentation.
Detach Volume¶ ↑
Please refer to the Detach Volume section in the Next Generation Cloud Servers™ (compute_v2) documentation.
Delete Volume¶ ↑
To delete a volume:
volume.destroy
Note: You cannot delete a volume until all of its dependent snapshots have been deleted.
List Snapshots¶ ↑
To retrieve a list of 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 a volume. Each subsequent snapshot will be the difference between the previous snapshot and the current 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 unmounting any file systems on the volume or by detaching the volume.
Additional Parameters¶ ↑
The create_snapshot
method also supports the following key values:
Key | Description |
---|---|
:display_name | The name of the snapshot. |
:display_description | A description of the snapshot. |
:force | If set to true, snapshot will be taken even if volume is still mounted. |
Delete Snapshot¶ ↑
To delete a snapshot:
snapshot.destroy
Examples¶ ↑
Example code using Cloud Block Storage can be found here.
Additional Resources¶ ↑
Support and Feedback¶ ↑
Your feedback is appreciated! If you have specific issues with the fog SDK, you should file an issue via Github.
For general feedback and support requests, please visit: developer.rackspace.com/support.