mirror of
https://github.com/fog/fog.git
synced 2022-11-09 13:51:43 -05:00
[rackspace|block_storage] initial document checkin.
This commit is contained in:
Kyle Rames
parent
1e8a74a4d5
commit
45eec54eda
1 changed files with 414 additions and 0 deletions
414
lib/fog/rackspace/docs/block_storage.md
Normal file
414
lib/fog/rackspace/docs/block_storage.md
Normal file
|
|
@ -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.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Key</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:connect_timeout</td>
|
||||
<td>Connection timeout (default: 60 seconds)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:read_timeout</td>
|
||||
<td>Read timeout for connection (default: 60 seconds)</td> </tr>
|
||||
<tr>
|
||||
<td>:write_timeout</td>
|
||||
<td>Write timeout for connection (default: 60 seconds)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:proxy</td>
|
||||
<td>Proxy for HTTP and HTTPS connections</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:ssl_ca_path</td>
|
||||
<td>Path to SSL certificate authorities</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:ssl_ca_file</td>
|
||||
<td>SSL certificate authority file</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:ssl_verify_peer</td>
|
||||
<td>SSL verify peer (default: true)</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
## 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`:
|
||||
|
||||
<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](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:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Method</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>create</td>
|
||||
<td>
|
||||
Accepts hash of attributes and creates object.<br>
|
||||
Note: creation is a non blocking call and you will be required to wait for a valid state before using resulting object.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>save</td>
|
||||
<td>Saves object.<br>
|
||||
Note: not all objects support updating object.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>persisted?</td>
|
||||
<td>Returns true if the object has been persisted.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>destroy</td>
|
||||
<td>
|
||||
Destroys object.<br>
|
||||
Note: this is a non blocking call and object deletion might not be instantaneous.
|
||||
</td>
|
||||
<tr>
|
||||
<td>reload</td>
|
||||
<td>Updates object with latest state from service.</td>
|
||||
<tr>
|
||||
<td>ready?</td>
|
||||
<td>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.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>attributes</td>
|
||||
<td>Returns a hash containing the list of model attributes and values.</td>
|
||||
</tr>
|
||||
<td>identity</td>
|
||||
<td>
|
||||
Returns the identity of the object.<br>
|
||||
Note: This might not always be equal to object.id.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>wait_for</td>
|
||||
<td>This method periodically reloads model and then yields to specified block until block returns true or a timeout occurs.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
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",
|
||||
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:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Key</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:display_name</td>
|
||||
<td>The name of the volume.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:display_description</td>
|
||||
<td>A description of the volume.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:snapshot_id</td>
|
||||
<td>The optional snapshot from which to create a volume.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:volume_type</td>
|
||||
<td>The type of volume to create. Refer to <a href="list-volume-types">List Volume Types</a> for valid types. If not defined, then the default, SATA, is used.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 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:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Key</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:display_name</td>
|
||||
<td>The name of the snapshot.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:display_description</td>
|
||||
<td>A description of the snapshot.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>:force</td>
|
||||
<td>Indicate whether to snapshot, even if the volume is attached.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
## 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: <sdk-support@rackspace.com>.
|
||||
Loading…
Reference in a new issue