Merge pull request #407 from ycombinator/bfv

Boot from volume support

Author: ycombinator

docs/userguide/Compute/Server.md

@@ -47,7 +47,9 @@ RAX-SI:image_schedule|If scheduled images enabled or not. If the value is TRUE,
 
 ## Create server
 
-There are a few parameter requirements when creating a server:
+### Using an image
+
+There are a few parameter requirements when creating a server using an image:
 
 * **name** - needs to be a string;
 - **flavor** - a `OpenCloud\Compute\Resource\Flavor` object, that is populated with the values of a real API flavor;
@@ -86,13 +88,52 @@ try {
 
 It's always best to be defensive when executing functionality over HTTP; you can achieve this best by wrapping calls in a try/catch block. It allows you to debug your failed operations in a graceful and efficient manner. 
 
+### Using a bootable volume
+
+There are a few parameter requirements when creating a server using a bootable volume:
+
+* **name** - needs to be a string;
+* **flavor** - a `OpenCloud\Compute\Resource\Flavor` object, that is populated with the values of a real API flavor;
+* **volume** - a `OpenCloud\Volume\Resource\Volume` object, that is populated with the values of a real API volume;
+
+Firstly we need to find our flavor and volume using their IDs.
+
+```php
+$volumeService = $client->volumeService();
+$bootableVolume = $volumeService->volume('<ID OF A BOOTABLE VOLUME>');
+$flavor = $compute->flavor('<ID OF A FLAVOR>');
+```
+
+Now we're ready to create our instance:
+
+```php
+use OpenCloud\Compute\Constants\Network;
+
+$server = $compute->server();
+
+try {
+    $response = $server->create(array(
+        'name'     => 'My lovely server',
+        'volume'   => $bootableVolume,
+        'flavor'   => $flavor
+    ));
+} catch (\Guzzle\Http\Exception\BadResponseException $e) {
+    // No! Something failed. Let's find out:
+    echo $e->getRequest() . PHP_EOL . PHP_EOL;
+    echo $e->getResponse();
+}
+```
+
+It's always best to be defensive when executing functionality over HTTP; you can achieve this best by wrapping calls in a try/catch block. It allows you to debug your failed operations in a graceful and efficient manner. 
+
 ### Create parameters
 
 Name|Description|Type|Required
 ---|---|---|---
 name|The server name. The name that you specify in a create request becomes the initial host name of the server. After the server is built, if you change the server name in the API or change the host name directly, the names are not kept in sync.|string|Yes
 flavor|A populated `OpenCloud\Compute\Resource\Flavor` object representing your chosen flavor|object|Yes
-image|A populated `OpenCloud\Compute\Resource\Image` object representing your chosen image|object|Yes
+image|A populated `OpenCloud\Compute\Resource\Image` object representing your chosen image|object|No, if volume is specified
+volume|A populated `OpenCloud\Volume\Resource\Volume` object representing your chosen bootable volume|object|No, if image is specified
 OS-DCF:diskConfig|The disk configuration value. You can use two options: `AUTO` or `MANUAL`. <br><br>`AUTO` means the server is built with a single partition the size of the target flavor disk. The file system is automatically adjusted to fit the entire partition. This keeps things simple and automated. `AUTO` is valid only for images and servers with a single partition that use the EXT3 file system. This is the default setting for applicable Rackspace base images.<br><br>`MANUAL` means the server is built using whatever partition scheme and file system is in the source image. If the target flavor disk is larger, the remaining disk space is left unpartitioned. This enables images to have non-EXT3 file systems, multiple partitions, and so on, and enables you to manage the disk configuration.|string|No
 networks|An array of populated `OpenCloud\Compute\Resource\Network` objects that indicate which networks your instance resides in.|array|No
 metadata|An array of arbitrary data (key-value pairs) that adds additional meaning to your server.|array|No

lib/OpenCloud/Compute/Resource/Server.php

@@ -76,6 +76,13 @@ class Server extends NovaResource implements HasPtrRecordsInterface
      */
     public $image;
 
+    /**
+     * The bootable volume for this server.
+     *
+     * @var Volume
+     */
+    public $volume;
+
     /**
      * The Flavor for this server.
      *
@@ -649,6 +656,17 @@ protected function createJson()
             $server->metadata = $this->metadata->toArray();
         }
 
+        // Boot from volume
+        if ($this->volume instanceof Volume) {
+            $server->block_device_mapping_v2 = array();
+            $server->block_device_mapping_v2[] = (object) array(
+                'source_type' => 'volume',
+                'destination_type' => 'volume',
+                'uuid' => $this->volume->id,
+                'boot_index' => 0
+            );
+        }
+
         // Networks
         if (is_array($this->networks) && count($this->networks)) {
 

lib/OpenCloud/Volume/Resource/Volume.php

@@ -38,10 +38,6 @@ class Volume extends PersistentResource
     public $attachments = array();
     public $created_at;
     public $source_volid;
-
-    /**
-     * OpenStack only
-     */
     public $imageRef;
     public $bootable;
 

samples/Compute/create_server_from_bootable_volume.php

@@ -0,0 +1,69 @@
+<?php
+
+/*
+ * Copyright 2014 Rackspace US, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Pre-requisites:
+ *
+ * Prior to running this script, you must setup the following environment variables:
+ * - RAX_USERNAME: Your Rackspace Cloud Account Username,
+ * - RAX_API_KEY:  Your Rackspace Cloud Account API Key,
+ * - RAX_REGION:   Rackspace Cloud region in which to create server; e.g.: DFW,
+ * - RAX_BOOTABLE_VOLUME_ID: ID of bootable volume in Rackspace Cloud region, and
+ * - RAX_FLAVOR_ID: ID of a compute flavor (performance or higher) in the Rackspace Cloud; e.g.: performance1-1.
+ *
+ * - You have an existing keypair. For this script, it will be called 'my_keypair'
+ * but this will change depending on what you called yours.
+ */
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+use OpenCloud\Rackspace;
+use Guzzle\Http\Exception\BadResponseException;
+
+// 1. Instantiate a Rackspace client.
+$client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
+    'username' => getenv('RAX_USERNAME'),
+    'apiKey'   => getenv('RAX_API_KEY')
+));
+
+// 2. Create Compute service
+$region = getenv('RAX_REGION');
+$computeService = $client->computeService(null, $region);
+$volumeService = $client->volumeService(null, $region);
+
+// 3. Get empty server
+$server = $computeService->server();
+
+// 4. Select bootable volume
+$bootableVolume = $volumeService->volume(getenv('RAX_BOOTABLE_VOLUME_ID'));
+
+// 5. Select a hardware flavor
+$flavor = $computeService->flavor(getenv('RAX_FLAVOR_ID'));
+
+// 6. Create
+try {
+    $response = $server->create(array(
+        'name'     => 'My server created from a bootable volume',
+        'volume'   => $bootableVolume,
+        'flavor'   => $flavor
+    ));
+} catch (BadResponseException $e) {
+    // No! Something failed. Let's find out:
+    echo $e->getRequest() . PHP_EOL . PHP_EOL;
+    echo $e->getResponse();
+}

samples/Compute/list_servers.php

@@ -0,0 +1,47 @@
+<?php
+/**
+ * Copyright 2012-2014 Rackspace US, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+//
+// Pre-requisites:
+// * Prior to running this script, you must setup the following environment variables:
+//   * RAX_USERNAME: Your Rackspace Cloud Account Username, and
+//   * RAX_API_KEY:  Your Rackspace Cloud Account API Key, and
+//
+
+require __DIR__ . '/../../vendor/autoload.php';
+use OpenCloud\Rackspace;
+
+// 1. Instantiate a Rackspace client.
+$client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
+    'username' => getenv('RAX_USERNAME'),
+    'apiKey'   => getenv('RAX_API_KEY')
+));
+
+// 2. Obtain a Compute service object from the client.
+$region = 'DFW';
+$computeService = $client->computeService(null, $region);
+
+// 3. Get the list of servers.
+$serverList = $computeService->serverList();
+
+foreach ($serverList as $server) {
+    echo str_repeat("-", 80) . PHP_EOL;
+    echo "ID: " . $server->id() . " | "
+        . "Name: " . $server->name() . " | "
+        . "Image ID: " . $server->image->id . PHP_EOL;
+    echo str_repeat("-", 80) . PHP_EOL;
+}

tests/OpenCloud/Tests/Compute/Resource/ServerTest.php

@@ -333,4 +333,18 @@ public function test_Create_Fails_Without_Correct_Networks()
             )
         ));
     }
+
+    public function test_Create_With_Bootable_Volume()
+    {
+        $new = new PublicServer($this->service);
+        $new->volume = new Volume($this->service, '5286e0c0-4906-11e4-916c-0800200c9a66');
+
+        $json = $new->createJson();
+        $obj = $json->server->block_device_mapping_v2[0];
+
+        $this->assertEquals('5286e0c0-4906-11e4-916c-0800200c9a66', $obj->uuid);
+        $this->assertEquals('volume', $obj->source_type);
+        $this->assertEquals('volume', $obj->destination_type);
+        $this->assertEquals(0, $obj->boot_index);
+    }
 }