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, send an email to: sdk-support@rackspace.com.