fog--fog/lib/fog/rackspace/docs/block_storage.md

#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 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"

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:

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 for valid types. If not defined, then the default, SATA, is used.

Attach Volume

Please refer the Attach Volume section in the Next Generation Cloud Servers™ (compute_v2) documentation.

Detach Volume

Please refer 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 snaphosts 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 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:

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

• fog.io
• Fog rdoc
• Fog Github repo
• Fog Github Issues
• Excon Github repo
• Cloud Block Storage API

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.