fog 1.18.0 → 1.19.0

data/lib/fog/hp/docs/connect.md

@@ -0,0 +1,152 @@
+# Connecting to HP Cloud Services using Ruby Fog Bindings
+
+The HP Cloud uses OpenStack as the platform and you can connect and set up your HP Cloud using Ruby Fog. To begin, connect using the following instructions:
+
+* [Initial Connection](#initial-connection)
+* [Availability Zones](#availability-zones)
+* [Optional Parameters](#optional-parameters)
+
+## Initial Connection
+
+To connect to the HP Cloud, follow these steps:
+
+1. Enter IRB
+
+        irb
+
+2. Require the Fog library and Rubygems:
+
+        require 'rubygems'
+        require 'fog'
+        
+    **Note**: If the `require 'rubygems'` command returns a value of `false`, enter IRB with the following command:
+    
+        irb -r 'rubygems'
+
+3. Establish a connection to the desired HP Cloud service
+
+        conn = Fog::<SERVICE-NAME>.new(
+               :provider      => "HP",
+               :hp_access_key  => "<your_ACCESS_KEY>",
+               :hp_secret_key => "<your_SECRET_KEY>",
+               :hp_auth_uri   => "<IDENTITY_ENDPOINT_URL>",
+               :hp_tenant_id => "<your_TENANT_ID>",
+               :hp_avl_zone => "<your_AVAILABILITY_ZONE>",
+               <other optional parameters>
+               )
+
+Where `SERVICE-NAME` can be [Compute](https://github.com/fog/fog/blob/master/lib/fog/hp/docs/compute.md), [Storage](https://github.com/fog/fog/blob/master/lib/fog/hp/docs/object_storage.md), [CDN](https://github.com/fog/fog/blob/master/lib/fog/hp/docs/cdn.md) or other services. Please surf on over to the [Block Storage](https://github.com/fog/fog/blob/master/lib/fog/hp/docs/block-storage.md) for the details on how to connect to that service.
+
+**Note**: You must use the `:hp_access_key` parameter rather than the now-deprecated `:hp_account_id` parameter you might have used in previous versions of the HP Cloud Services Extensions to Ruby Fog.
+
+You can find the values the access key, secret key, and other values by clicking the [`API Keys`](https://console.hpcloud.com/account/api_keys) button in the [Console Dashboard](https://console.hpcloud.com/dashboard).
+
+
+## Availability Zones
+
+You cannot specify an availability zone if you have not activated it.  To activate an availability zone, go to the [Management Console dashboard](https://console.hpcloud.com/) and click the `**Activate`** button.  You are required to set an availability zone to establish a connection; there is no default availability zone value.
+
+The current usable availability zones for the compute service:
+
+* `az-1.region-a.geo-1`
+* `az-2.region-a.geo-1`
+* `az-3.region-a.geo-1`
+
+The current usable availability zones for the storage service:
+
+* `region-a.geo-1`
+* `region-b.geo-1`
+
+The current usable availability zones for the CDN:
+
+* `region-a.geo-1`
+* `region-b.geo-1`
+
+The current usable availability zones for the block storage service:
+
+* `az-1.region-a.geo-1`
+* `az-2.region-a.geo-1`
+* `az-3.region-a.geo-1`
+
+## Optional Parameters
+
+This section describes the optional parameters that you can use when connecting to any of the HP Cloud services.  The examples below show the Compute service, but these optional parameters work with all of the HP Cloud services.
+
+The `user_agent` parameter allows you to specify a string to pass as a `user_agent` header for the connection.  You can use this to track the caller of the operations.  You can set the `user_agent` parameter as follows:
+
+        conn = Fog::Compute.new(
+               ...
+               ...
+               :user_agent => "MyApp/x.x.x")
+
+This inserts a `user_agent` string such as `hpfog/x.x.x (MyApp/x.x.x)` into the header.
+
+In addition to the `user_agent` parameter, there are several additional parameters you can set using the `connection_options` parameter.  These options are provided by the Excon library and allow you to modify the underlying connection to a service.  These options are [Instrumentation](#Instrumentation), [Timeouts](#Timeouts), [Proxy](#Proxy), and [HTTPS/SSL](#HTTPS).
+
+### Instrumentation
+
+Use this parameter for debugging purposes.  When you use the default instrumentor `Excon::StandardInstrumentor`, all events are output to `stderr`. You can also designate your own instrumentor. You can set the default instrumentor as follows:
+
+        conn = Fog::Compute.new(
+               ...
+               ...
+               :connection_options => {:instrumentor => Excon::StandardInstrumentor})
+
+For convenience of debugging HTTP requests, we have created a custom instrumentor `Excon::SimpleHttpInstrumentor`. This instrumentor shows the HTTP calls in afashion which is similar to a `curl` output. You can set the custom `SimpleHttpInstrumentor` as follows:
+
+        conn = Fog::Compute.new(
+               ...
+               ...
+               :connection_options => {:instrumentor => Excon::SimpleHttpInstrumentor, :instrumentor_name => 'SimpleHttp'})
+
+### Timeouts
+
+Use this parameter to set different timeout values.  You can set the timeouts parameter as follows:
+
+        conn = Fog::Compute.new(
+               ...
+               ...
+               :connection_options => {
+                      :connect_timeout => <time_in_secs>, 
+                      :read_timeout => <time_in_secs>, 
+                      :write_timeout => <time_in_secs>})
+
+### Proxy
+
+Use this parameter to specify a proxy URL for both  HTTP and HTTPS connections.  You can set the proxy parameter as follows:
+
+        conn = Fog::Compute.new(
+               ...
+               ...
+               :connection_options => {:proxy => 'http://myproxyurl:4444'})
+               
+### HTTPS/SSL
+
+By default, peer certificates are verified when you use secure socket layer (SSL) for HTTPS.  Sometimes this does not work due to configurations in different operating systems, causing connection errors. To help avoid this, you can set  HTTPS/SSL parameters.  To set the path to the certificates:
+
+        conn = Fog::Compute.new(
+               ...
+               ...
+               :connection_options => {:ssl_ca_path => "/path/to/certs"})
+             
+To set the path to a certificate file:
+
+        conn = Fog::Compute.new(
+               ...
+               ...
+               :connection_options => {:ssl_ca_file => "/path/to/certificate_file"})
+
+To set turn off peer verification:
+
+        conn = Fog::Compute.new(
+               ...
+               ...
+               :connection_options => {:ssl_verify_peer => false})
+
+**Note**: This makes your connection less secure.
+
+For further information on these options, please see [the Excon documentation](http://github.com/geemus/excon).
+
+
+---------
+[Documentation Home](https://github.com/fog/fog/blob/master/lib/fog/hp/README.md) | [Examples](https://github.com/fog/fog/blob/master/lib/fog/hp/examples/getting_started_examples.md)

data/lib/fog/hp/docs/install.md

@@ -0,0 +1,133 @@
+# Installing Ruby Fog Bindings for HP Cloud Services
+
+Before you can begin working with the Ruby Fog bindings, you have to install them (of course!). This page provides you with the installation information for the following operating systems:
+
+* [Ubuntu Installation](#ubuntu-installation)
+* [Mac OSX Installation](#mac-osx-installation)
+* [CentOS Installation](#centos-installation)
+* [Uninstalling](#uninstalling) 
+
+To install and use HP Cloud Ruby bindings for Fog, please install the [latest release](http://fog.io) of Fog.
+
+
+## Ubuntu Installation
+
+If you plan on using the Ruby Fog binding on Ubuntu, we recommend you use Ubuntu versions 12.04 or 12.10.  The Ruby Fog bindings may work on other versions, but are not supported. 
+
+To install the Ruby Fog bindings on the Ubuntu operating system, follow these steps while logged in as the root user:
+
+1. Install Ruby and Ruby-dev:
+
+        apt-get install ruby1.8 ruby-dev
+
+2. Install RubyGems:
+
+        apt-get install rubygems
+
+3. Install the dependent libraries:
+
+        apt-get install libxml2 libxml2-dev libxslt1-dev libxslt1.1 sgml-base xml-core
+
+4. Install the RDoc Ruby source documenation generator package:
+
+        gem install rdoc
+
+5. Install the Fog gem:
+
+        gem install fog
+
+
+See the [Connecting to the Service](https://github.com/fog/fog/blob/master/lib/fog/hp/docs/connect.md) page for details on how to connect.
+
+## MacOS X Installation
+
+Some Ruby packages require C/C++ compiler support.  On the MacOS, if you haven't already installed XCode, we recommend that you install it to provide the needed C/C++ compiler for your system.  
+
+To install the Ruby Fog bindings on MacOS X, follow these steps while logged in as the root user:
+
+1. Download and install Xcode.  You can [download the most recent version of XCode through the Mac App Store](https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12).  If you want to install an earlier version of Xcode, go to the [Apple Developer](https://developer.apple.com/downloads/index.action) site and search for "Xcode".  In the results list, select the version of Xcode that you want and install it.  (Note that you need to be signed up as an "Apple Developer" to access the download.  Sign-up is free.)
+
+2. To make your installation process easier we recommend that you install [Homebrew](http://wiki.github.com/mxcl/homebrew/installation).  Follow the instructions on the Homebrew page to install the package.  After you have downloaded Homebrew, the CLI command to install it is:
+
+        homebrew install - ruby -e "$(curl -fsSkL raw.github.com/mxcl/homebrew/go)"
+
+3. Add the Homebrew path to your $PATH environment variable.  You can either do this via the CLI command line:
+
+        export PATH=:/usr/local/sbin:$PATH
+        
+    (The default Homebrew installation location is the `/usr/local/sbin` directory.)  Or you can add the Homebrew path (`/usr/local/sbin`) to your $PATH environment variable in your local `.profile` file.
+    
+4. Install RVM on your system:
+
+        curl -L get.rvm.io | bash -s stable
+
+    **Note**: You can also install RVM using [Jewelry Box](https://unfiniti.com/software/mac/jewelrybox), a RVM graphical user interface (GUI) for Mac OSX.
+
+5. Install the packages required by RVM; the following command lists the required packages:
+    
+        source ~/.rvm/scripts/rvm
+        rvm requirements # install required packages
+        
+6. Install the required packages listed in Step 5:
+
+        brew install <packages>
+        
+    Where `<packages>` are the packages that you need to install.
+    
+7. Install the `libksba` library:
+
+        brew install libksba
+
+8. Install Ruby:
+
+        rvm user all
+        rvm install ruby-1.9.2 --with-gcc=clang
+        
+9. Use the Ruby version and make it the default:
+
+        rvm use 1.9.2 --default
+
+10. Install the Fog gem:
+
+        gem install fog
+
+
+See the [Connecting to the Service](https://github.com/fog/fog/blob/master/lib/fog/hp/docs/connect.md) page for details on how to connect.
+
+## CentOS Installation
+
+If you plan on using the Ruby Fog binding on CentOS, we recommend you use CentOS versions 6.2 or 6.3.  The Ruby Fog bindings may work on other versions, but are not supported. 
+
+To install the Ruby Fog bindings on CentOS, follow these steps while logged in as the root user:
+
+1. Install Ruby and Ruby Dev:
+
+        yum install -y ruby ruby-devel
+    
+2. Install Rubygems:
+
+        yum install -y rubygems
+
+3. Install the dependent libraries:
+
+        yum install -y gcc make libxml2 libxml2-devel libxslt libxslt-devel
+
+4. Install RDoc Ruby source documentation generator package:
+
+        gem install rdoc
+
+5. Install the Fog gem:
+
+        gem install fog
+
+
+See the [Connecting to the Service](https://github.com/fog/fog/blob/master/lib/fog/hp/docs/connect.md) page for details on how to connect.
+
+## Uninstalling
+
+Its recommended that you uninstall a previous version prior to upgrading. To uninstall, execute the followin command while logged in as the root user:
+
+        gem uninstall fog
+
+---------
+[Documentation Home](https://github.com/fog/fog/blob/master/lib/fog/hp/README.md) | [Examples](https://github.com/fog/fog/blob/master/lib/fog/hp/examples/getting_started_examples.md)

data/lib/fog/hp/examples/block_storage.md

@@ -0,0 +1,296 @@
+#Examples for working with HP Cloud Block Storage Service v12.12
+
+HP Cloud block storage provides support for volumes and snapshots. A volume can store boot images, user data or both. They provide customers with persistent and flexible permanent storage. You can think of it as list of USB devices, that can be plugged in anywhere at will. Volumes can be attached to server instances and mounted. 
+
+Snapshots are saved volume images at specific moments in time. You can take a snapshot of a volume and then use that snapshot to create a new volume.
+
+The block storage provider has two abstractions: a model layer and a request layer. Both layers are detailed below. The following code snippets can be executed from within a Ruby console (IRB):
+
+        irb
+
+This page discusses the following tasks:
+
+* [Connecting to the Service](#connecting-to-the-service)
+
+**Model Layer Examples**
+
+* [Model Volume Operations](#model-volume-operations)
+* [Model Snapshot Operations](#model-snapshot-operations)
+
+**Request Layer Examples**
+
+* [Request Volume Operations](#request-volume-operations)
+* [Request Snapshot Operations](#request-snapshot-operations)
+
+## Connecting to the Service
+
+To connect to the HP Cloud Block Storage Service, follow these steps:
+
+1. Enter IRB
+
+        irb
+
+2. Require the Fog library
+
+        require 'fog'
+
+3. Establish a connection to the HP Cloud BlockStorage service
+
+        conn = Fog::HP::BlockStorage.new(
+               :hp_access_key  => "<your_ACCESS_KEY>",
+               :hp_secret_key => "<your_SECRET_KEY>",
+               :hp_auth_uri   => "<IDENTITY_ENDPOINT_URL>",
+               :hp_tenant_id => "<your_TENANT_ID>",
+               :hp_avl_zone => "<your_AVAILABILITY_ZONE>",
+               <other optional parameters>
+               )
+
+**Note**: You must use the `:hp_access_key` parameter rather than the now-deprecated  `:hp_account_id` parameter you might have used in previous Ruby Fog versions.
+
+You can find the values the access key, secret key, and other values by clicking the [`API Keys`](https://console.hpcloud.com/account/api_keys) button in the [Console Dashboard](https://console.hpcloud.com/dashboard).
+
+## Model Volume Operations
+
+This section discusses the volume operations you can perform using the model abstraction.
+
+1. List all available volumes for an account
+
+        volumes = conn.volumes
+        volumes.size   # returns no. of volumes
+        # display volumes in a tabular format
+        volumes.table([:id, :name, :status, :created_at])
+
+2. Obtain the details of a particular volume
+
+        volume = conn.volumes.get(volume_id)
+        volume.name                         # returns name of the volume
+        volume.created_at                   # returns the date the volume was created
+        volume.status                        # returns the state of the volume e.g. available, in-use
+
+3. List all available bootable volumes for an account
+
+        bootable_volumes = conn.bootable_volumes
+        bootable_volumes.size   # returns no. of bootable volumes
+        # display bootable volumes in a tabular format
+        bootable_volumes.table([:id, :name, :state, :created_at])
+
+4. Obtain the details of a particular bootable volume
+
+        volume = conn.bootable_volumes.get(volume_id)
+        volume.name                         # returns name of the bootable volume
+        volume.created_at                  # returns the date the bootable volume was created
+        volume.status                        # returns the state of the bootable volume e.g. available, in-use
+
+5. Create a new volume
+
+        new_volume = conn.volumes.create(
+               :name => "TestVolume",
+               :description => "My Test Volume",
+               :size => 1)
+        new_volume.id       # returns the id of the volume
+        new_volume.name     # => "TestVolume"
+        new_volume.status    # returns the status of the volume e.g. creating, available
+ 
+6. Create a new volume from an existing snapshot
+
+        new_volume = conn.volumes.create(
+               :name => "TestVolume",
+               :description => "My Test Volume",
+               :snapshot_id => 1,
+               :size => 1)
+        new_volume.id       # returns the id of the volume
+        new_volume.snapshot_id       # returns the snapshot_id of the volume
+        new_volume.name     # => "TestVolume"
+        new_volume.status    # returns the status of the volume e.g. creating, available
+**Note**: The size of the volume you create from a snapshot is the same as that of the snapshot. The `:size` parameter has no effect in this case.
+
+7. Create a new bootable volume from an suitable single-part image
+
+        new_volume = conn.bootable_volumes.create(
+               :name => "BootVolume",
+               :description => "My Boot Volume",
+               :image_id => 11111,
+               :size => 10)
+        new_volume.id       # returns the id of the volume
+**Note**: You can use a bootable volume to create a persistent server instance.
+
+8. Attach an existing volume to an existing server
+
+        volume = conn.volumes.get(volume_id)
+        volume.attach(server_id, device)
+        # => true
+**Note**: The device parameter is the mount point on the server instance to which the volume is attached (for example, `/dev/sdf`).
+
+9. Detach an existing volume
+
+        volume = conn.volumes.get(volume_id)
+        volume.detach
+        # => true
+
+10. Delete an existing volume
+
+        volume = conn.volumes.get(volume_id)
+        volume.destroy
+        # => true
+
+## Model Snapshot Operations
+
+This section discusses the snapshot operations you can perform using the model abstraction.
+
+1. List all available snapshots for an account
+
+        snapshots = conn.snapshots
+        snapshots.size   # returns no. of snapshots
+        # display snapshots in a tabular format
+        conn.snapshots.table([:id, :name, :state, :created_at])
+
+2. Obtain the details of a particular snapshot
+
+        snapshot = conn.snapshots.get(snapshot_id)
+        snapshot.name                       # returns name of the volume
+        snapshot.created_at                   # returns the date the volume was created
+        snapshot.status                        # returns the state of the volume e.g. available
+
+3. Create a new snapshot
+
+        new_snapshot = conn.snapshots.create(
+               :name => "TestVolume",
+               :description => "My Test Volume",
+               :volume_id => 1)
+        new_snapshot.id       # returns the id of the volume
+        new_snapshot.name     # => "TestVolume"
+        new_snapshot.volume_id     # => 1
+        new_snapshot.status    # returns the status of the volume e.g. creating, available
+
+4. Delete an existing snapshot
+
+        snapshot = conn.snapshots.get(snapshot_id)
+        snapshot.destroy
+        # => true
+
+## Request Volume Operations
+
+This section discusses the volume operations you can perform using the request abstraction.
+
+1. List all available volumes for an account
+
+        response = conn.list_volumes
+        response.body['volumes']                    # returns an array of volume hashes
+        response.headers                            # returns the headers
+        response.body['volumes'][0]['displayName']         # returns the name of the volume
+
+2. Obtain the details of a particular volume
+
+        response = conn.get_volume_details(volume_id)
+        volume = response.body['volume']
+        volume['displayName']                  # returns the name of the volume
+        volume['size']                               # returns the size of the volume
+        volume['status']                            # returns the status of the volume e.g. available, in-use
+
+3. List all available bootable volumes for an account
+
+        response = conn.list_bootable_volumes
+        response.body['volumes']                    # returns an array of bootable volume hashes
+        response.headers                            # returns the headers
+        response.body['volumes'][0]['displayName']         # returns the name of the bootable volume
+
+4. Obtain the details of a particular bootable volume
+
+        response = conn.get_bootable_volume_details(volume_id)
+        volume = response.body['volume']
+        volume['displayName']                  # returns the name of the bootable volume
+        volume['size']                               # returns the size of the bootable volume
+        volume['status']                            # returns the status of the bootable volume e.g. available, in-use
+
+5. Create a new volume
+
+        response = conn.create_volume("demo-vol", "demo-vol-desc", 1)
+        volume = response.body['volume']
+        volume['id']                                # returns the id of the new volume
+        volume['displayName']                # => "demo-vol"
+        volume['size']                             # => 1
+        volume['status']                          # returns the status of the volume e.g. creating, available
+
+6. Create a new volume from an existing snapshot
+
+        response = conn.create_volume("demo-vol", "demo-vol-desc", 1, {'snapshot_id' => 1})
+        volume = response.body['volume']
+        volume['id']                                # returns the id of the new volume
+        volume['displayName']                # => "demo-vol"
+        volume['size']                             # => 1
+        volume['snapshot_id']                 # => 1
+        volume['status']                          # returns the status of the volume e.g. creating, available
+**Note**: The size of the volume you create from a snapshot is the same as that of the snapshot. The third parameter (the size) has no effect in this case.
+
+7. Create a new bootable volume from an suitable single-part image
+
+        new_volume = conn.create_volume("TestBootVol", 
+                                                        "My Test Boot Volume", 
+                                                        10, 
+                                                        {"imageRef" => "1111111"}
+                                                     )
+        new_volume.id       # returns the id of the volume
+**Note**: You can use a bootable volume to create a persistent server instance.
+
+8. Attach an existing volume to an existing server
+
+        response = conn.compute.attach_volume(server_id, volume_id, device)
+        volume_attachment = response.body['volumeAttachment']
+        volume_attachment['id']       # returns the id of the volume
+        volume_attachment['volumeId']  # returns the id of the volume
+**Note**: The device parameter is the mount point on the server instance to which the volume is attached (for example, `/dev/sdf`)
+
+9. List volumes attached to a server
+
+        response = conn.compute.list_server_volumes(server_id)
+        volume_attachments = response.body['volumeAttachments']
+        volume_attachment[0]['id']       # returns the id of the volume
+        volume_attachment[0]['volumeId']  # returns the id of the volume
+        volume_attachment[0]['device']  # returns the device of the volume
+
+10. Detach an existing volume
+
+        conn.detach_volume(server_id, volume_id)
+
+11. Delete an existing volume
+
+        conn.delete_volume(volume_id)
+
+## Request Snapshot Operations
+
+This section discusses the snapshot operations you can perform using the request abstraction.
+
+1. List all available snapshots for an account
+
+        response = conn.list_snapshots
+        response.body['snapshots']                    # returns an array of snapshot hashes
+        response.headers                            # returns the headers
+        response.body['snapshots'][0]['displayName']         # returns the name of the snapshot
+        response.body['snapshots'][0]['size']                       # returns the size of the snapshot
+        response.body['snapshots'][0]['volumeId']               # returns the volume id of the snapshot
+
+2. Obtain the details of a particular snapshot
+
+        response = conn.get_snapshot_details(snapshot_id)
+        snapshot = response.body['snapshot']
+        snapshot['displayName']                  # returns the name of the snapshot
+        snapshot['size']                               # returns the size of the snapshot
+        snapshot['volumeId']                        # returns the volume id of the snapshot
+        snapshot['status']                            # returns the status of the snapshot e.g. available, in-use
+
+3. Create a new snapshot
+
+        response = conn.create_snapshot("demo-snap", "demo-snap-desc", 1)
+        snapshot = response.body['snapshot']
+        snapshot['id']                                # returns the id of the new volume
+        snapshot['displayName']                # => "demo-vol"
+        snapshot['size']                             # => 1
+        snapshot['volumeId']                        # returns the volume id of the snapshot
+        snapshot['status']                          # returns the status of the snapshot e.g. creating, available
+
+4. Delete an existing snapshot
+
+        conn.delete_snapshot(snapshot_id)
+
+---------
+[Documentation Home](https://github.com/fog/fog/blob/master/lib/fog/hp/README.md) | [Examples](https://github.com/fog/fog/blob/master/lib/fog/hp/examples/getting_started_examples.md)