Merge pull request #421 from rackspace/working

Merging working -> master in preparation for minor release

Author: ycombinator

CONTRIBUTING.md

@@ -34,3 +34,13 @@ phpunit
 1. Make sure your [variables-order](http://www.php.net/manual/en/ini.core.php#ini.variables-order) is set to "EGCRS"
 2. Set your *PHP_OpenCloud_USERNAME* and *PHP_OpenCloud_API_KEY* variables
 3. Run: ```php tests/OpenCloud/Smoke/Runner.php```
+
+## Conventions
+
+* When working on a `Service` class (e.g. [`OpenCloud\Image\Service`](/lib/OpenCloud/Image/Service.php), name methods like so:
+
+  * Methods that return a single resource, say `Foo`, should be named `getFoo`. For example, [`getImage`](/lib/OpenCloud/Image/Service.php#L67).
+  * Methods that return a collection of resources, say `Foo`, should be named `listFoos`. For example, [`listImages`](/lib/OpenCloud/Image/Service.php#L53).
+  * Methods that create a new resource, say `Foo`, should be named `createFoo`. For example, [`createEntity`](/lib/OpenCloud/CloudMonitoring/Service.php#L105).
+
+* When validating arguments to a method, please throw `\InvalidArgumentException` when an invalid argument is found. For example, see [here](/lib/OpenCloud/LoadBalancer/Resource/LoadBalancer.php#L212-L215).

README.md

@@ -67,4 +67,4 @@ You can also find assistance via IRC on #rackspace at freenode.net.
 Contributing
 ------------
 If you'd like to contribute to the project, or require help running the unit/acceptance tests, please view the
-[contributing guidelines](https://github.com/rackspace/php-opencloud/blob/master/CONTRIBUTING.md).
+[contributing guidelines](https://github.com/rackspace/php-opencloud/blob/master/CONTRIBUTING.md).

composer.json

@@ -3,7 +3,7 @@
     "description": "PHP SDK for Rackspace/OpenStack APIs",
     "keywords": ["rackspace", "openstack", "opencloud", "swift", "nova"],
     "type": "library",
-    "license": "MIT",
+    "license": "Apache-2.0",
     "authors": [
         {
             "name": "Jamie Hannaford",
@@ -22,11 +22,11 @@
     },
     "require": {
         "php" : ">=5.3.3",
-        "guzzle/http" : "~3.8"
+        "guzzle/http" : "~3.8",
+        "psr/log": "~1.0"
     },
     "require-dev" : {
         "guzzle/guzzle": "~3.8",
-        "psr/log": "~1.0",
         "satooshi/php-coveralls": "0.6.*@dev"
     }
 }

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,53 @@ 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
+volumeDeleteOnTermination|`true` if the bootable volume should be deleted when the server is terminated; `false`, otherwise|boolean|No; default = `false`
 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

docs/userguide/DNS/Domains.md

@@ -27,7 +27,7 @@ $domains = $service->domainList();
 $domains = $service->domainList(true);
 ```
 
-Please consult the [iterator documentation](docs/userguide/Iterators.md) for more information about iterators.
+Please consult the [iterator documentation](/docs/userguide/Iterators.md) for more information about iterators.
 
 ### Filter parameters
 
@@ -214,7 +214,7 @@ $asyncResponse = $service->import($bind9Data);
 
 ## Modify domain
 
-This call modifies DNS domain(s) attributes only. Only the TTL, email address and comment attributes of a domain can be modified. Records cannot be added, modified, or removed through this API operation - you will need to use the [add records](https://github.com/jamiehannaford/php-opencloud/blob/dns-docs/docs/userguide/DNS/Records.md#add-record), [modify records](https://github.com/jamiehannaford/php-opencloud/blob/dns-docs/docs/userguide/DNS/Records.md#modify-record) or [remove records](https://github.com/jamiehannaford/php-opencloud/blob/dns-docs/docs/userguide/DNS/Records.md#delete-record) operations respectively.
+This call modifies DNS domain(s) attributes only. Only the TTL, email address and comment attributes of a domain can be modified. Records cannot be added, modified, or removed through this API operation - you will need to use the [add records](/docs/userguide/DNS/Records.md#add-record), [modify records](/docs/userguide/DNS/Records.md#modify-record) or [remove records](/docs/userguide/DNS/Records.md#delete-record) operations respectively.
 
 ```php
 $domain->update(array(

docs/userguide/ObjectStore/USERGUIDE.md

@@ -356,7 +356,7 @@ $options = array(
 
 $objects = $container->objectList($options);
 ```
-[ [Get the executable PHP script for this example](/samples/ObjectStore/list-objects-with-params.php) ]
+[ [Get the executable PHP script for this example](/samples/ObjectStore/list-objects-with-prefix.php) ]
 
 In general, the `objectList()` method described above takes an optional parameter (`$options` in the example above). This parameter is an associative array of various options. Here is a complete listing of keys that can be specified in the `$options` array:
 

docs/userguide/Orchestration/README.md

@@ -0,0 +1,81 @@
+# Orchestration
+
+**Orchestration** is a service that can be used to create and manage cloud 
+resources. Examples of such resources are databases, load balancers,
+servers and software installed on them.
+
+## Concepts
+
+To use the Orchestration service effectively, you should understand several
+key concepts:
+
+* **Template**: An Orchestration template is a JSON or YAML document that
+describes how a set of resources should be assembled to produce a working
+deployment. The template specifies what resources should be used, what
+attributes of these resources are parameterized and what information is
+output to the user when a template is instantiated.
+
+* **Resource**: A resource is a template artifact that represents some component of your desired architecture (a Cloud Server, a group of scaled Cloud Servers, a load balancer, some configuration management system, and so forth).
+
+* **Stack**: A stack is a running instance of a template. When a stack is created,
+the resources specified in the template are created.
+
+## Getting started
+
+### 1. Instantiate an OpenStack or Rackspace client.
+
+To use the Orchestration service, you must first instantiate a `OpenStack` or `Rackspace` client object.
+
+* If you are working with an OpenStack cloud, instantiate an `OpenCloud\OpenStack` client as follows:
+
+    ```php
+    use OpenCloud\OpenStack;
+
+    $client = new OpenStack('<OPENSTACK CLOUD IDENTITY ENDPOINT URL>', array(
+        'username' => '<YOUR OPENSTACK CLOUD ACCOUNT USERNAME>',
+        'password' => '<YOUR OPENSTACK CLOUD ACCOUNT PASSWORD>'
+    ));
+    ```
+
+* If you are working with the Rackspace cloud, instantiate a `OpenCloud\Rackspace` client as follows:
+
+    ```php
+    use OpenCloud\Rackspace;
+
+    $client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
+        'username' => '<YOUR RACKSPACE CLOUD ACCOUNT USERNAME>',
+        'apiKey'   => '<YOUR RACKSPACE CLOUD ACCOUNT API KEY>'
+     ));
+    ```
+
+### 2. Obtain an Orchestration service object from the client.
+All Orchestration operations are done via an _orchestration service object_. To
+instantiate this object, call the `orchestrationService` method on the `$client`
+object as shown in the following example:
+
+```php
+$region = '<CLOUD REGION NAME>';
+$orchestrationService = $client->orchestrationService(null, $region);
+```
+
+Any stacks and resources created with this `$orchestrationService` instance will
+be stored in the cloud region specified by `$region`.
+
+### 3. Create a stack from a template.
+```php
+$stack = $orchestrationService->createStack(array(
+    'name'         => 'simple-lamp-setup',
+    'templateUrl'  => 'https://raw.githubusercontent.com/rackspace-orchestration-templates/lamp/master/lamp.yaml',
+    'parameters'   => array(
+        'server_hostname' => 'web01',
+        'image'           => 'Ubuntu 14.04 LTS (Trusty Tahr) (PVHVM)'
+    ),
+    'timeoutMins'  => 5
+));
+```
+
+[ [Get the executable PHP script for this example](/samples/Orchestration/quickstart.php) ]
+
+## Next steps
+
+Once you have created a stack, there is more you can do with it. See [complete user guide for orchestration](USERGUIDE.md).