Complete User Guide for the Orchestration Service¶

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:

  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:

  use OpenCloud\Rackspace;
  
  $client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
      'username' => '<YOUR RACKSPACE CLOUD ACCOUNT USERNAME>',
      'apiKey'   => '<YOUR RACKSPACE CLOUD ACCOUNT API KEY>'
  ));
  

Orchestration service¶

All Orchestration operations are done via an orchestration service object. To instantiate this object, call the orchestrationService method on the $client object. This method takes two arguments:

$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.

Validate template¶

Before you use a template to create a stack, you might want to validate it.

use OpenCloud\Common\Exceptions\InvalidTemplateError;

try {
    $orchestrationService->validateTemplate(array(
        'template' => file_get_contents(__DIR__ . '/lamp.yaml')
    ));
} catch (InvalidTemplateError $e) {
    // Use $e->getMessage() for explanation of why template is invalid
}

use OpenCloud\Common\Exceptions\InvalidTemplateError;

try {
    $orchestrationService->validateTemplate(array(
        'templateUrl' => 'https://raw.githubusercontent.com/rackspace-orchestration-templates/lamp/master/lamp.yaml'
    ));
} catch (InvalidTemplateError $e) {
    // Use $e->getMessage() for explanation of why template is invalid
}

Preview stack¶

Before you create a stack from a template, you might want to see what that stack will look like. This is called previewing the stack.

This operation takes one parameter, an associative array, with the following keys:

$stack = $orchestrationService->previewStack(array(
    'name'         => 'simple-lamp-setup',
    'template'     => file_get_contents(__DIR__ . '/lamp.yml'),
    'parameters'   => array(
        'server_hostname' => 'web01',
        'image'           => 'Ubuntu 14.04 LTS (Trusty Tahr) (PVHVM)'
    )
));
/** @var $stack OpenCloud\Orchestration\Resource\Stack **/

$stack = $orchestrationService->previewStack(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)'
    )
));
/** @var $stack OpenCloud\Orchestration\Resource\Stack **/

Create stack¶

You can create a stack from a template.

This operation takes one parameter, an associative array, with the following keys:

$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
));
/** @var $stack OpenCloud\Orchestration\Resource\Stack **/

$stack = $orchestrationService->stack();
$stack->create(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
));

List stacks¶

You can list all the stacks that you have created as shown in the following example:

$stacks = $orchestrationService->listStacks();
foreach ($stacks as $stack) {
    /** @var $stack OpenCloud\Orchestration\Resource\Stack **/
}

[ Get the executable PHP script for this example ]

Get stack¶

You can retrieve a specific stack using its name, as shown in the following example:

$stack = $orchestrationService->getStack('simple-lamp-setup');
/** @var $stack OpenCloud\Orchestration\Resource\Stack **/

[ Get the executable PHP script for this example ]

Get stack template¶

You can retrieve the template used to create a stack. Note that a JSON string is returned, regardless of whether a JSON or YAML template was used to create the stack.

$stackTemplate = $stack->getTemplate();
/** @var $stackTemplate string **/

[ Get the executable PHP script for this example ]

Update stack¶

You can update a running stack.

This operation takes one parameter, an associative array, with the following keys:

$stack->update(array(
    'template'      => file_get_contents(__DIR__ . '/lamp-updated.yml'),
    'parameters'    => array(
        'server_hostname' => 'web01',
        'image'           => 'Ubuntu 14.04 LTS (Trusty Tahr) (PVHVM)'
    ),
    'timeoutMins'   => 5
));
/** @var $stack OpenCloud\Orchestration\Resource\Stack **/

$stack->update(array(
    'templateUrl'   => 'https://raw.githubusercontent.com/rackspace-orchestration-templates/lamp/master/lamp-updated.yaml',
    'parameters'    => array(
        'server_hostname' => 'web01',
        'image'           => 'Ubuntu 14.04 LTS (Trusty Tahr) (PVHVM)'
    ),
    'timeoutMins'   => 5
));
/** @var $stack OpenCloud\Orchestration\Resource\Stack **/

Delete stack¶

If you no longer need a stack and all its resources, you can delete the stack and the resources as shown in the following example:

$stack->delete();

[ Get the executable PHP script for this example ]

Abandon Stack¶

If you want to delete a stack but preserve all its resources, you can abandon the stack as shown in the following example:

$abandonStackData = $stack->abandon();
/** @var $abandonStackData string **/

file_put_contents(__DIR__ . '/sample_adopt_stack_data.json', $abandonStackData);

[ Get the executable PHP script for this example ]

Note that this operation returns data about the abandoned stack as a string. You can use this data to recreate the stack by using the adopt stack operation.

Adopt stack¶

If you have data from an abandoned stack, you can re-create the stack as shown in the following example:

$stack = $orchestrationService->adoptStack(array(
    'name'           => 'simple-lamp-setup',
    'template'       => file_get_contents(__DIR__ . '/lamp.yml'),
    'adoptStackData' => $abandonStackData,
    'timeoutMins'    => 5
));
/** @var $stack OpenCloud\Orchestration\Resource\Stack **/

[ Get the executable PHP script for this example ]

List stack resources¶

You can list all the resources for a stack as shown in the following example:

$resources = $stack->listResources();
foreach ($resources as $resource) {
    /** @var $resource OpenCloud\Orchestration\Resource\Resource **/
}

[ Get the executable PHP script for this example ]

Get stack resource¶

You can retrieve a specific resource in a stack bt using that resource’s name, as shown in the following example:

$resource = $stack->getResource('load-balancer');
/** @var $resource OpenCloud\Orchestration\Resource\Resource **/

[ Get the executable PHP script for this example ]

Get stack resource metadata¶

You can retrieve the metadata for a specific resource in a stack as shown in the following example:

$resourceMetadata = $resource->getMetadata();
/** @var $resourceMetadata \stdClass **/

[ Get the executable PHP script for this example ]

List stack events¶

You can list all of the events for all of the resources in a stack as shown in the following example:

$stackEvents = $stack->listEvents();
foreach ($stackEvents as $stackEvent) {
    /** @var $stackEvent OpenCloud\Orchestration\Resource\Event **/
}

[ Get the executable PHP script for this example ]

List stack resource events¶

You can list all of the events for a specific resource in a stack as shown in the following example:

$resourceEvents = $resource->listEvents();
foreach ($resourceEvents as $resourceEvent) {
    /** @var $resourceEvent OpenCloud\Orchestration\Resource\Event **/
}

[ Get the executable PHP script for this example ]

Get stack resource event¶

You can retrieve a specific event for a specific resource in a stack, by using the resource event’s ID, as shown in the following example:

$resourceEvent = $resource->getEvent('c1342a0a-59e6-4413-9af5-07c9cae7d729');
/** @var $resourceEvent OpenCloud\Orchestration\Resource\Event **/

[ Get the executable PHP script for this example ]

List resource types¶

You can list all supported resource types as shown in the following example:

$resourceTypes = $orchestrationService->listResourceTypes();
foreach ($resourceTypes as $resourceType) {
    /** @var $resourceType OpenCloud\Orchestration\Resource\ResourceType **/
}

[ Get the executable PHP script for this example ]

Get resource type¶

You can retrieve a specific resource type’s schema as shown in the following example:

$resourceType = $orchestrationService->getResourceType('OS::Nova::Server');
/** @var $resourceType OpenCloud\Orchestration\Resource\ResourceType **/

[ Get the executable PHP script for this example ]

Get resource type template¶

You can retrieve a specific resource type’s representation as it would appear in a template, as shown in the following example:

$resourceTypeTemplate = $resourceType->getTemplate();
/** @var $resourceTypeTemplate string **/

[ Get the executable PHP script for this example ]

Get build info¶

You can retrieve information about the current Orchestration service build as shown in the following example:

$buildInfo = $orchestrationService->getBuildInfo();
/** @var $resourceType OpenCloud\Orchestration\Resource\BuildInfo **/

[ Get the executable PHP script for this example ]