Quickstart for Cloud Orchestration#

Rackspace Cloud Orchestration is the name of the Rackspace orchestration and application architecture management service. Cloud Orchestration provides a software API to create and manipulate stacks of resources (for example load balancers, web servers, and databases) and software that operates as part of those stacks (for example Apache, PHP, MySQL, and Wordpress). Cloud Orchestration is an engine that understands cloud topologies; in this way, it is unlike Chef or Puppet, which are concerned with software on servers. Where applicable, Cloud Orchestration leverages software configuration management tools such as Chef. Using simple template syntax, you can define a cloud stack, deploy the stack, scale the stack (for example, add or remove resources), delete the stack, clone the stack, and more.

Concepts#

To use this service effectively, you should understand how these key ideas are used in this context:

resource

A template artifact that represents some component of your desired architecture.

stack

A running instance of a template. The result of creating a stack is a deployment of the application framework or component.

template

A file that describes how a set of resources should be assembled and what software should be installed to produce a working deployment.

Authentication#

To use this service you have to authenticate first. To do this, you will need your Rackspace username and API key. Your username is the one you use to login to the Cloud Control Panel at http://mycloud.rackspace.com/.

To find your API key, use the instructions in View and reset your API key.

You can specify a default region. Here is a list of available regions:

  • DFW (Dallas-Fort Worth, TX, US)

  • HKG (Hong Kong, China)

  • IAD (Blacksburg, VA, US)

  • LON (London, England)

  • SYD (Sydney, Australia)

Some users have access to another region in ORD (Chicago, IL). New users will not have this region.

Once you have these pieces of information, you can pass them into the SDK by replacing {username}, {apiKey}, and {region} with your info:

// Not currently supported by this SDK

import (
  "github.com/rackspace/gophercloud"
  osStacks "github.com/rackspace/gophercloud/openstack/orchestration/v1/stacks"
  "github.com/rackspace/gophercloud/pagination"
  "github.com/rackspace/gophercloud/rackspace/orchestration/v1/stacks"
)

ao := gophercloud.AuthOptions{
  Username: "{username}",
  APIKey: "{apiKey}",
}
provider, err := rackspace.AuthenticatedClient(ao)

serviceClient, err := rackspace.NewOrchestrationV1(provider, gophercloud.EndpointOpts{
  Region: "{region}",
})

// Not currently supported by this SDK

pkgcloud = require('pkgcloud');

// Each client is bound to a specific service and provider.
var client = pkgcloud.orchestration.createClient({
  provider: 'rackspace',
  username: '{username}',
  apiKey: '{apiKey}',
  region: '{region}'
});

require 'vendor/autoload.php';

use OpenCloud\Rackspace;

$client = new Rackspace(Rackspace::US_IDENTITY_ENDPOINT, array(
    'username' => '{username}',
    'apiKey'   => '{apiKey}'
));

# Not currently supported by this SDK

require 'fog'

@client = Fog::Rackspace::Orchestration.new(
  :rackspace_username => '{username}',
  :rackspace_api_key => '{apiKey}',
  :rackspace_region => '{region}'
)

# {username}, {apiKey} below are placeholders, do not enclose '{}' when you replace them with actual credentials.

curl -s https://identity.api.rackspacecloud.com/v2.0/tokens -X 'POST' \
   -d '{"auth":{"RAX-KSKEY:apiKeyCredentials":{"username":"{username}", "apiKey":"{apiKey}"}}}' \
   -H "Content-Type: application/json" | python -m json.tool

# From the resulting json, set three environment variables: tenant, TOKEN and endpoint

export TENANT="{tenantId}"
export TOKEN="{tokenId}"
export ENDPOINT="{publicUrl}" # For Orchestration service

Use the API#

Some of the basic operations you can perform with this API are described below.

Create stack#

After you have created your stack template, you can create the stack in the Rackspace cloud:

// Not currently supported by this SDK

createOpts := osStacks.CreateOpts{
  Name: "a_redis_stack",
  TemplateURL: "redis_hot_template",
}
aRedisStack, err =: stacks.Create(serviceClient, createOpts).Extract()

// Not currently supported by this SDK

client.createStack({
  name: 'a_redis_stack',
  templateUrl: 'redis_hot_template'
}, function(err, stack) {
  if (err) {
    // TODO handle as appropriate
    return;
  }

  // TODO use your stack here
});

$orchestrationService = $client->orchestrationService(null, '{region}');

$stack = $orchestrationService->createStack(array(
    'name'         => 'a_redis_stack',
    'templateUrl'  => 'redis_hot_template',
));

# Not currently supported by this SDK

@stack = @client.stacks.new.save(
  :stack_name => "a_redis_stack",
  :template   => redis_hot_template
)

$ curl -X POST -d \
  '{
  "stack_name": "{stackName}",
  "template": "{jsonOrchestrationTemplate}",
  "parameters": {
      "param_name-1": "{paramValue1}",
      "param_name-2": "{paramValue2}"
    },
  "timeout_mins": "{timeoutMins}"
  }' \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  $ENDPOINT/stacks | python -m json.tool

List stacks#

To see the stacks you have already deployed in a given region:

// Not currently supported by this SDK

err = stacks.List(serviceClient, nil).EachPage(func(page pagination.Page) (bool, error) {
  stackList, err := osStacks.ExtractStacks(page)
  if err != nil {
    // handle error...
  }
  return true, nil
})

// Not currently supported by this SDK

client.getStacks(function (err, stacks) {
  if (err) {
    // TODO handle as appropriate
    return;
  }

  // TODO use your stacks here
});

$stacks = $orchestrationService->listStacks();

# Not currently supported by this SDK

@client.stacks

$ curl -X GET $ENDPOINT/stacks \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json" | python -m json.tool

Get stack data#

To inspect a single stack’s detail data:

// Not currently supported by this SDK

stack, err := stacks.Get(serviceClient, {stackName}, {stackId}).Extract()

// Not currently supported by this SDK

var stack = new pkgcloud.providers.openstack.orchestration.Stack(client, {
  id: '{stackId}',
  name: '{stackName}'
});

client.getStack(stack, function (err, stack) {
  if (err) {
    // TODO handle as appropriate
    return;
  }

  // TODO use your stack here
});

$stack = $orchestrationService->getStack('{stackName}');

# Not currently supported by this SDK

@client.stacks.get(@stack.name, @stack.id)

$ curl -X GET $ENDPOINT/stacks/{stack_name}/{stack_id} \
  -H "X-Auth-Token: $TOKEN" \
  -H "Accept: application/json" | python -m json.tool

Update stack#

To update or modify an existing stack:

// Not currently supported by this SDK

updateOpts := osStacks.UpdateOpts{
  Timeout:  60,
}
err = stacks.Update(client, {stackName}, {stackId}, updateOpts).ExtractErr()

// Not currently supported by this SDK

stack.timeout = 60; // 1 hour

client.updateStack(stack, function(err, stack) {
  if (err) {
    // TODO handle as appropriate
    return;
  }

  // TODO use your stack here
});

$stack->update(array(
    'timeoutMins' => 60
));

# Not currently supported by this SDK

@stack.stack_name = "New Stack Name"
@stack.save

$ curl -X PUT -d \
  '{
  "template": "{updatedJSONOrchestrationTemplate}",
  "parameters": {
      "param_name-1": "{updatedParamValue1}",
      "param_name-2": "{updatedParamValue2}"
    },
  "timeout_mins": "{timeoutMins}"
  }' \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  $ENDPOINT/stacks/{stack_name}/{stack_id} | python -m json.tool

Delete stack#

To delete a stack and destroy all resources the stack has provisioned:

// Not currently supported by this SDK

err := stacks.Delete(serviceClient, "a_redis_stack", aRedisStack.ID).ExtractErr()

// Not currently supported by this SDK

client.deleteStack('a_redis_stack', function(err) {
  if (err) {
    // TODO handle as appropriate
    return;
  }
});

$stack->delete();

# Not currently supported by this SDK

@stack.delete

$ curl -X DELETE $ENDPOINT/stacks/{stack_name}/{stack_id} \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json"

More information#

This quickstart is intentionally brief, demonstrating only a few basic operations. To learn more about interacting with Rackspace cloud services, explore the following sites: