1. technology and computing

docs.rackspace.com/api
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Rackspace Cloud Orchestration Getting Started Guide
API v1.0 (2015-05-27)
©2015 Rackspace US, Inc.
The document is for informational purposes only and is provided “AS IS.”
RACKSPACE MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, AS TO THE ACCURACY OR COMPLETENESS OF THE CONTENTS OF THIS DOCUMENT AND RESERVES THE RIGHT TO MAKE CHANGES TO SPECIFICATIONS AND PRODUCT/SERVICES DESCRIPTION AT ANY TIME WITHOUT NOTICE. RACKSPACE SERVICES OFFERINGS ARE SUBJECT TO CHANGE WITHOUT NOTICE. USERS MUST TAKE FULL RESPONSIBILITY FOR APPLICATION OF ANY SERVICES MENTIONED HEREIN. EXCEPT AS SET
FORTH IN RACKSPACE GENERAL TERMS AND CONDITIONS AND/OR CLOUD TERMS OF SERVICE, RACKSPACE ASSUMES NO LIABILITY
WHATSOEVER, AND DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO ITS SERVICES INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
Except as expressly provided in any written license agreement from Rackspace, the furnishing of this document does not give you any
license to patents, trademarks, copyrights, or other intellectual property.
Rackspace®, Rackspace logo and Fanatical Support® are registered service marks of Rackspace US, Inc. All other product names and
trademarks used in this document are for identification purposes only and are property of their respective owners.
ii
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Table of Contents
Overview ......................................................................................................................... 1
What is a template and how is it used? .................................................................. 1
Choose a method for calling the API operations ...................................................... 1
Additional sources of information ........................................................................... 2
Prerequisites for running examples .......................................................................... 2
How the heat client commands work ...................................................................... 2
How cURL commands work .................................................................................... 3
Pricing and service level .......................................................................................... 4
Create your first cloud orchestration ............................................................................... 5
Step 1. Install the heat client ................................................................................... 5
Step 2. Send requests to the API using cURL, Firefox, or rest-client .......................... 11
Step 3. Generate an authentication token ............................................................. 14
Step 4. Choose service access/endpoints ................................................................ 22
Step 5. Export environment variables to run cURL commands ................................ 23
Step 6. Create a simple stack for a cloud server ..................................................... 23
Step 7. List stacks .................................................................................................. 27
Step 8. Show stack details ..................................................................................... 29
Step 9. Delete a stack ........................................................................................... 32
Step 10. Create a stack by using a resource group ................................................. 33
Step 11. Update a stack with a load balancer ........................................................ 36
Step 12. Delete a stack with a load balancer ......................................................... 43
Document change history .............................................................................................. 44
heat Client command summary ..................................................................................... 45
Stack operations .................................................................................................... 45
Stack resources ...................................................................................................... 48
Events ................................................................................................................... 49
Outputs ................................................................................................................. 50
Templates ............................................................................................................. 50
Miscellaneous ........................................................................................................ 52
iii
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
List of Tables
1.
2.
3.
4.
heat client prerequisite software ................................................................................. 5
heat client environment variables ................................................................................ 9
cURL command-line options ...................................................................................... 12
Regionalized service endpoints .................................................................................. 22
iv
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
List of Examples
1. cURL command example: JSON request ....................................................................... 3
2. Set environment variables example ............................................................................. 9
3. cURL authenticate request: JSON ............................................................................... 13
4. cURL authenticate request: XML ............................................................................... 15
5. cURL authenticate request: JSON ............................................................................... 16
6. Authenticate response: XML ...................................................................................... 16
7. Authenticate response: JSON ..................................................................................... 17
8. single_server.template Example hot template file ........................................... 23
9. cURL create stack: JSON request ................................................................................ 26
10. cURL create stack: JSON response ............................................................................ 26
11. cURL list stacks: JSON request .................................................................................. 28
12. List stacks: JSON response ....................................................................................... 28
13. outputs section for template single_server.template ................................................ 30
14. cURL show stack details: JSON request .................................................................... 31
15. Show stack details: JSON response ........................................................................... 31
16. outputs section for template single_server.template ................................................ 32
17. cURL delete stack: JSON request .............................................................................. 33
18. Delete stack: JSON response .................................................................................... 33
19. servers-with-lb.template Example ............................................................... 34
20. cURL create stack: JSON request .............................................................................. 36
21. Create stack: JSON response .................................................................................... 36
22. servers-with-lb-add.template with load balancer added example .............................. 36
23. cURL update stack with load balancer: JSON request ............................................... 41
24. Update stack with load balancer: JSON response ..................................................... 41
25. cURL show stack details: JSON request .................................................................... 42
26. Show stack details: JSON response ........................................................................... 42
v
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Overview
What is a template and how is it used? ..........................................................................
Choose a method for calling the API operations ..............................................................
Additional sources of information ...................................................................................
Prerequisites for running examples ..................................................................................
How the heat client commands work ..............................................................................
How cURL commands work ............................................................................................
Pricing and service level ..................................................................................................
1
1
2
2
2
3
4
Follow the steps described in this guide to use the Rackspace Cloud Orchestration API to
create and access your stacks.
The simple exercises in this guide help you get started with Orchestration by showing you
how to access the API through either heat client commands or cURL commands.
Notes
• If you are interested in learning how to get started with Orchestration using the Cloud Control Panel instead of the API, refer to the following article: http://www.rackspace.com/knowledge_center/article/quick-set-up-withrackspace-cloud-orchestration.
• If you are interested in learning how to get started with Orchestration using
one of our SDKs, refer to the following: https://developer.rackspace.com/sdks/.
What is a template and how is it used?
You will learn the basics about templates in this guide. A template is a basic building block
for Orchestration. A Cloud Orchestration template is a portable file, written in a user-readable language, that describes how a set of resources should be assembled and what software should be installed in order to produce a working deployment.
Based on a template, Heat orchestration engine creates an instantiated set of resources,
called a stack, to run the application framework or component specified in the template. A
stack is a running instance of a template. The result of creating a stack is a deployment of
the application framework or component.
Choose a method for calling the API operations
For each exercise in this guide, you choose one of the following methods to call API operations:
• heat client commands. The heat client provides easy command line access to the Cloud
Orchestration API operations. We recommend that you use the heat client to run simple
commands that call API operations. You can specify the --debug parameter on any heat
command to show the underlying cURL request for the API operation. This is a good way
to become familiar with the API requests. For details see the section called “How the heat
client commands work” [2].
1
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
• cURL commands. If you are familiar with or want to learn cURL commands, choose this
method. With cURL, you send HTTP requests with embedded API operations from the
command line. The cURL examples in this guide include request bodies in JSON format.
For details see the section called “How cURL commands work” [3].
If you like, you can use cURL in one example and then use heat client commands in the next
example. If you choose to use a cURL command for any example, you must export the environment variables required to run the cURL examples. For details see the section called
“Step 5. Export environment variables to run cURL commands” [23].
To use the API, it helps to be familiar with HTTP 1.1, RESTful web services, the Rackspace
Cloud Servers service, and JSON data serialization format.
Additional sources of information
For details about using the Cloud Orchestration API, see the Cloud Orchestration Developer
Guide at http://docs.rackspace.com/.
For information about understanding templates for the Cloud Orchestration API, see the
Cloud Orchestration Templates Developer Guide at http://docs.rackspace.com/.
You can find information about resources to use in your templates at http://
orchestration.rackspace.com/raxdox/index.html.
You can send issues and bug reports to your support team via ticket, chat, email, or phone.
Prerequisites for running examples
To run the examples in this guide, you must have the following prerequisites:
• Rackspace Cloud account
• Rackspace Cloud username and password, as specified during registration
How the heat client commands work
The heat client is an open-source Python client that you can use to run simple commands to
call API operations. This client is easy to learn and use. Each heat client command runs cURL
commands that embed API requests. You can run the heat client from a computer or a remote system, such as a cloud server.
You install the heat client on a Linux distribution or on Mac OS X. Instructions are provided
in the section called “Step 1. Install the heat client” [5].
To configure the heat client, you update your .bash_profile file (or .bashrc) to set and export heat environment variables.
Note
You can specify the --debug parameter on any heat command to show the
underlying API request for the command. This is a good way to become familiar
with the API requests.
2
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Rackspace does not maintain the heat client, which is considered to be software in development.
How cURL commands work
cURL is a command-line tool that you can use to interact with REST interfaces. cURL enables
you to transmit and receive HTTP requests and responses from the command line or a shell
script, which enables you to work with the API directly. It is available for Linux distributions,
Mac OS X, and Windows. For information about cURL, see http://curl.haxx.se/.
To run the cURL request examples shown in this guide, copy each example from the HTML
version of this guide directly to the command line or a script.
The following command is an example cURL command for a JSON request that provisions a
server with an isolated network.
Example 1. cURL command example: JSON request
$ curl https://dfw.servers.api.rackspacecloud.com/v2/$OS_TENANT_ID/servers \
-X POST \
-H "X-Auth-Project-Id: $OS_TENANT_ID" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Auth-Token: $OS_AUTH_TOKEN" \
-d '{"server": {"name": "my_server_with_network", "imageRef": "d42f821e-c2d1-4796-9f07af5ed7912d0e", "flavorRef": "2", "max_count": 1, "min_count": 1, "networks": [{"uuid":
"538a112a-34d1-47ff-bf1e-c40639e886e2"}, {"uuid": "00000000-0000-0000-0000-000000000000"}, {"uuid":
"11111111-1111-1111-1111-111111111111"}]}}' \
| python -m json.tool
Note
The carriage returns in the cURL request examples are escaped with a backslash (\) character. The escape character allows continuation of the command
across multiple lines. However, do not include the escape character in the JSON
or XML request body within the cURL command.
3
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Pricing and service level
Cloud Orchestration is part of the Rackspace Cloud. Although you will not be billed for using Cloud Orchestration, you are billed for the stack resources you create when using Cloud
Orchestration.
Cloud Orchestration is a Non-Standard Rackspace Service. Applicable SLAs for the underlying infrastructure apply for successfully launched cloud products.
4
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Create your first cloud orchestration
Step 1. Install the heat client ........................................................................................... 5
Step 2. Send requests to the API using cURL, Firefox, or rest-client ................................. 11
Step 3. Generate an authentication token ..................................................................... 14
Step 4. Choose service access/endpoints ........................................................................ 22
Step 5. Export environment variables to run cURL commands ........................................ 23
Step 6. Create a simple stack for a cloud server ............................................................. 23
Step 7. List stacks .......................................................................................................... 27
Step 8. Show stack details ............................................................................................. 29
Step 9. Delete a stack ................................................................................................... 32
Step 10. Create a stack by using a resource group ......................................................... 33
Step 11. Update a stack with a load balancer ................................................................ 36
Step 12. Delete a stack with a load balancer ................................................................. 43
Step 1. Install the heat client
To manage your stacks from the command line, you can use the open-source heat client application.
If you want to run the cURL examples instead, skip to the section called “Step 2. Send requests to the API using cURL, Firefox, or rest-client” [11].
To install the heat client, you first install the python-heatclient package.
Note
The heat client is not maintained by Rackspace and should be considered software in development.
You can submit issues with the client at https://bugs.launchpad.net/pythonheatclient.
Before you begin, install the following prerequisite software:
Table 1. heat client prerequisite software
Prerequisite
Description
Python 2.7 or later
Currently, the heat client is tested with Python 2.7.
To determine if Python 2.7 is installed on your
computer:
1.
Open a shell terminal (or a command prompt on Windows), type python,
and press Enter.
2.
If you see output similar to the following output, Python is installed. The
first line in the output shows the installed Python version:
Python 2.7.1 (r271:86832, Aug 5 2011, 03:30:24)
[GCC 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.
00)] on darwin
Type "help", "copyright", "credits" or "license" for more
information.
>>>
5
Rackspace Cloud Orchestration
Getting Started Guide
Prerequisite
May 27, 2015
Description
Note
To exit the Python interpreter prompt, type exit().
3.
If the version information displayed does not start with 2.7, you need to install Python 2.7. Use the following procedure to install it.
To install Python 2.7:
•
Run the following command following to install Python 2.7 on Ubuntu Linux:
sudo apt-get install python2.7-dev
Notes
• On Windows and Mac OS X, download the Python 2.7
installation file from https://www.python.org/download/releases/2.7 and install it. Be sure to choose the latest release available, as listed in a note near the top of
the web page.
• On Ubuntu, if the command preceding is not recognized,
you might need to first run apt-get update before
you run apt-get install.
setuptools package
Installed by default on Mac OS X.
Many Linux distributions provide packages to make setuptools easy to install.
Search your package manager for setuptools to find an installation package.
If you cannot find one, download the setuptools package directly from http://
pypi.python.org/pypi/setuptools.
pip package
To install the heat client on a Mac OS X or Linux system, use pip because it ensures that you get the latest version of the heat client from the Python Package
Index. Also, it lets you update the package later.
If pip is not installed, install it through the package manager for your system:
• Mac OS X
$ sudo easy_install pip
• Ubuntu
$ apt-get install python-pip
Note
On Ubuntu, if the command preceding is not recognized, you
might need to first run apt-get update before you run
apt-get install.
• Debian
$ aptitude install python-pip
• Fedora
$ yum install python-pip
• CentOS, or Red Hat Enterprise Linux (from EPEL or another third-party repository)
$ yum install python-pip
6
API v1.0
Rackspace Cloud Orchestration
Getting Started Guide
Prerequisite
May 27, 2015
Description
Note for Windows Users
If you installed python from http://www.activestate.com/activepython/downloads then setuptools and pip are already installed on your computer.
If you installed python from http://www.python.org/getit/, follow these instructions to set up your environment:
1. If python was not in your path, run the following command
to add it to the path set: PATH=%PATH%;c:\python27;c:
\python27\scripts. Here, c:\python27 is the python installation directory. If it is different on your computer, change it
to the correct directory.
2. Install the appropriate version of setuptools for python2.7
from http://www.lfd.uci.edu/~gohlke/pythonlibs/#setuptools. If you have installed the 32-bit version of python2.7, install setuptools-2.0.2.win32-py2.7.exe, and if you
have the installed 64-bit version of python2.7, then install
setuptools-2.0.2.win-amd64-py2.7.exe.
3. Install the appropriate version (win32/amd64) of the pip utility for python2.7 from http://www.lfd.uci.edu/~gohlke/
pythonlibs/#pip.
7
API v1.0
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
To install the heat client
1.
Install or update the heat client package
The python-heatclient package contains the heat client.
To install the python-heatclient package, run the following command for your
operating system:
For Ubuntu, Debian, or OS X:
$ sudo pip install python-heatclient
For Red Hat Enterprise Linux, CentOS, or Fedora:
$ sudo python-pip install python-heatclient
For Windows:
Start the command prompt as an administrator user and then run following command:
$ pip install python-heatclient
Note
If you previously installed the python-heatclient package, run the following command for your operating system to upgrade it:
For Ubuntu, Debian, or OS X:
$ sudo pip install --upgrade python-heatclient
Note
If the previous command does not work, make sure that gcc is
installed by executing the following commands:
apt-get update
apt-get install gcc python-dev
Then retry the --upgrade command.
For RHEL, CentOS, or Fedora:
$ sudo python-pip install --upgrade python-heatclient
For Windows, start the command prompt as an administrator user and
then run following command:
$ pip install --upgrade python-heatclient
2.
Set environment variables
Edit your .bash_profile file or .bashrc file (whichever is used in your environment) to add and set environment variables that enable the heat client to connect to
your Rackspace Cloud account. Use nano or a text editor of your choice to edit your
the file.
8
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
$ nano ~/.bash_profile
Add the following sets of lines to your bash profile and save the file. Information
about the environment variables is provided after the examples.
Example 2. Set environment variables example
export
export
export
export
export
OS_AUTH_URL=https://identity.api.rackspacecloud.com/v2.0/
OS_USERNAME=yourUserName
OS_TENANT_ID=yourTenantId
OS_REGION_NAME=yourRegionName
OS_PASSWORD=yourPassword
Note for Windows users
For Windows:
1. Run the following commands to set the required environment variables
in the current command prompt (these environment variables will be
lost after the command prompt is closed):
set
set
set
set
set
OS_AUTH_URL=https://identity.api.rackspacecloud.com/v2.0/
OS_USERNAME=yourUserName
OS_TENANT_ID=yourTenantId
OS_REGION_NAME=yourRegionName
OS_PASSWORD=yourPassword
2. To persist these settings, add them to system environment variables by
clicking Start, then right-clicking Computer, and selecting Properties.
Click Advanced System Settings. You might need to confirm a User Account Control prompt. Then click the Environment Variables button.
In the environment variables preceding, username, password, and tenant_id refer to your Rackspace cloud account username, password, and tenant_id, respectively. Edit the values for username, password, tenant_id to provide your information as appropriate. Also set the OS_REGION_NAME endpoint to the appropriate regional endpoint where you want to deploy resources, for example DFW. For details
see the section called “Step 4. Choose service access/endpoints” [22]. Remember
to source the file containing the environment variables after editing (for example:
source .bashrc) so that the new settings will take effect immediately.
The following table describes the environment variables:
Table 2. heat client environment variables
Environment Variable
Description
OS_AUTH_URL
The endpoint for the Rackspace Cloud Identity service, which the heat client uses for
authentication.
OS_USERNAME
Your Rackspace Cloud user name.
OS_TENANT_ID
Your Rackspace Cloud tenant ID (account number).
OS_REGION_NAME
The regional endpoint (for example DFW) where you want to deploy the Cloud Orchestration resources. For details, see the section called “Step 4. Choose service access/endpoints” [22].
OS_PASSWORD
Your Rackspace Cloud password.
9
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Edit the values for the placeholders in the examples for your .bash_profile file or
.bashrc file (whichever is used in your environment) to provide your information as
appropriate.
Note for Windows users
For Windows, steps 3 and 4 following are not applicable.
3.
Set permissions on the bash profile or .bashrc file
Because the bash profile (or .bashrc) contains a password, set permissions on it so other people cannot read it:
$ chmod 600 ~/.bash_profile
4.
Source the environment variables
You must source the variables to make them available in your current shell.
If you set your environment variables in the .bash_profile file, run the following
command:
$ source ~/.bash_profile
If you set your environment variables in the .bashrc file, run the following command:
$ source ~/.bashrc
5.
Test the heat client
To verify that you can talk to the API server, authenticate, and list stacks:
$ heat stack-list
6.
Get help for heat client commands
To get help for heat client commands, run the following command:
$ heat help
To get help for a specific command, type the command name after the help parameter, as follows:
$ heat help commandName
Note
To show and become familiar with the underlying API request for a command, specify the --debug parameter as the first parameter on any command. For example:
$ heat --debug stack-list
If you can run the heat commands successfully, skip the following Troubleshooting
step. Otherwise, continue to the Troubleshooting step.
10
Rackspace Cloud Orchestration
Getting Started Guide
7.
May 27, 2015
API v1.0
Troubleshoot issues
Rackspace does not maintain the heat client, which is considered to be software in development. However, if you experience issues with installing and running the client, try
the following steps:
• If you cannot run commands successfully, make sure that you entered your user
name, password, and tenant ID correctly in the .bash_profile or .bashrc file.
• Enter the heat --debug stack-list command and check the corresponding cURL
command that is displayed to confirm that your settings for user name, password,
and tenant ID are correct. If not, you need to correct the settings you saved to the
.bash_profile file or .bashrc file, source the file, and retry the command.
• If you need to change any environment variables, either log out and back in or
source your .bash_profile or .bashrc file.
• To override some environment variable settings, you can use the options that
are listed at the end of the heat help output. For example, you can override the
OS_PASSWORD setting in the .bash_profile by specifying a password on a heat
command, as follows:
$ heat --os-password password stack-list
password is your Rackspace Cloud password.
If you are using only the heat client commands and aren't using cURL commands, skip to
the section called “Step 6. Create a simple stack for a cloud server” [23].
Step 2. Send requests to the API using cURL, Firefox, or rest-client
You have several options for sending requests through an API:
• Developers and testers might prefer to use cURL, the command-line tool from http://
curl.haxx.se/.
With cURL you can send HTTP requests and receive responses back from the command
line.
• If you like to use a more graphical interface, the ReST client for Firefox also works well
for testing and trying out commands. See https://addons.mozilla.org/en-US/firefox/addon/restclient/.
• You can also download and install rest-client, a Java application for testing RESTful web
services, from http://code.google.com/p/rest-client/.
Send API requests by using cURL
cURL is a command-line tool that is available on most UNIX system-based and Mac OS X systems, and can be downloaded for Windows, to interact with REST interfaces. For more information about cURL, visit http://curl.haxx.se/.
11
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
cURL enables you to transmit and receive HTTP requests and responses from the command
line or from within a shell script. As a result, you can work with the REST API directly without using one of the client APIs.
The following cURL command-line options are used in this guide to run the examples.
Table 3. cURL command-line options
Option
Description
-d
Sends the specified data in a POST request
to the HTTP server. Use this option to send
a JSON or XML request body to the server.
-H
Specifies an extra HTTP header in the request. You can specify any number of extra
headers. Precede each header with the -H
option.
Common headers in Rackspace API requests are as follows:
• Content-Type. Required for operations with a request body.
Specifies the format of the request body.
The syntax for the Content-Type header is as follows:
Content-Type: application/format
format is either json or xml.
• X-Auth-Project-Id. Optional. Specifies the project ID, which can be your account number or another value.
• Accept. Optional.
Specifies the format of the response
body. The syntax for the Accept header
is as follows:
Accept: application/format
format is either json or xml. The default is json.
• X-Auth-Token. Required. Specifies the
authentication token.
-i
Includes the HTTP header in the output.
-s
Silent or quiet mode. Progress and error
messages are not shown, and cURL is mute.
-T
Transfers the specified local file to the remote URL.
-X
Specifies the request method to use when
communicating with the HTTP server. The
specified request is used instead of the default method, which is GET.
json.tool
For commands that return a response, you can append the following code to
the command to call the json.tool to pretty-print output:
| python -m json.tool
12
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
To use the json.tool, import the json module. For information about the
json.tool, see json — JSON encoder and decoder.
If you run a Python version earlier than 2.6, import the simplejson module and
use the simplejson.tool. For information about the simple.json tool, see simplejson — JSON encoder and decoder.
If you do not want to pretty-print JSON output, omit this code.
Copying and pasting cURL request examples into a terminal
window
To run the cURL request examples shown in this guide on Linux or Mac systems, perform
the following steps:
1. Select the example from the HTML version of this guide by clicking the Select Text icon
to the right of the example.
2. Copy the text.
3. Paste the text into an ASCII editor (for example, vi or TextEdit ).
4. Modify the example with your required account information and so on, as detailed in
this guide.
Note
The carriage returns in the cURL request examples that are part of the cURL
syntax are escaped with a backslash (\) to avoid prematurely terminating the
command. However you should not escape carriage returns inside the XML or
JSON message within the command.
Consider the following cURL authenticate request: JSON example that is described in detail
in the section called “Step 3. Generate an authentication token” [14]:
Example 3. cURL authenticate request: JSON
curl -s -d \
'{
"auth":
{
"RAX-KSKEY:apiKeyCredentials":
{
"username": "yourUserName",
"apiKey": "yourApiKey"}
}
}' \
-H 'Content-Type: application/json' \
'https://identity.api.rackspacecloud.com/v2.0/tokens' | python -m json.tool
Note that all the lines that are part of the cURL command syntax have been escaped with a
backslash (\) to indicate that the command continues on the next line:
curl -i -d \
13
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
(... lines within the JSON portion of the message are not shown in this
example)
(... the example only shows lines that are part of cURL syntax)
}' \
-H 'Content-Type: application/json' \
'https://identity.api.rackspacecloud.com/v2.0/tokens' | python -m json.tool
However the lines within the JSON portion of the message are not escaped with a backslash
('\') to avoid issues with the JSON processing:
'{
"auth":
{
"RAX-KSKEY:apiKeyCredentials":
{
"username": "yourUserName",
"apiKey": "yourApiKey"}
}
}' \
Note
The final line of the JSON message is escaped since the backslash lies outside the
JSON message and continues the cURL command to the next line.
5. After you are finished modifying the text for the cURL request example with your information (for example yourUserName and yourApiKey), paste the text into your terminal window.
6. Execute the cURL command by pressing Enter.
If you have trouble copying and pasting the examples as described, try typing the entire example on one long line, removing all the backslash line continuation characters.
Step 3. Generate an authentication token
If you use cURL, you need to generate an authentication token.
If you are using heat client, the authentication token is generated for you automatically, so
skip this section and go to the section called “Step 6. Create a simple stack for a cloud server” [23].
In order to use the REST API, you must first obtain an authentication token, which must be
passed in for each request using the X-Auth-Token header.
The following examples demonstrate how to use cURL to obtain the authentication token
and the account number. You must supply the authentication token and account number
when calling subsequent Cloud Orchestration API operations.
Remember to replace the names in the examples with their respective values:
• yourUserName — Your common Rackspace Cloud user name, as supplied during registration.
14
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
• yourApiKey — Your API access key.
To find your API key:
1. Log in to the Cloud Control Panel (https://mycloud.rackspace.com).
2. On the upper-right side of the top navigation pane, click the Account: yourUserName
menu.
3. From the menu, select Account Settings.
4. In the Login Details section of the Account Settings page, locate the API Key field and
click Show.
5. Copy the value of the API Key and paste it into a text editor of your choice.
6. Click Hide to hide the value of the API Key. You also need your cloud account ID number. In the documentation, the account ID is often referred to as your tenant name or tenant ID (technically, the ID is different from the
name, but at Rackspace, they are the same thing). Together, three components—your user name, your API Key, and your tenant ID or cloud account ID—form the authentication
credentials that are required to connect to the Rackspace Cloud. To find your tenant ID or cloud account number, click the Account: yourUserName menu
on the upper-right side of the top navigation pane in the Cloud Control Panel. The tenant ID or account ID is listed first in the menu.
Use the following endpoint to access the Cloud Identity Service:
• https://identity.api.rackspacecloud.com/v2.0/
Your account might be based in either the US or the UK; this is not determined by your
physical location but by the location of the Rackspace retail site which was used to create
your account:
• If your account was created via http://www.rackspacecloud.com, it is a US-based account.
• If your account was created via http://www.rackspace.co.uk, it is a UK-based account.
Note that the v2.0 component in the URL indicates that you are using version 2.0 of the
Cloud Identity API.
Example 4. cURL authenticate request: XML
curl -s -d \
'<?xml version="1.0" encoding="UTF-8"?>
<auth>
<apiKeyCredentials
xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
username="yourUserName"
apiKey="yourApiKey"/>
</auth>' \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \
'https://identity.api.rackspacecloud.com/v2.0/tokens'
15
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Example 5. cURL authenticate request: JSON
curl -s -d \
'{
"auth":
{
"RAX-KSKEY:apiKeyCredentials":
{
"username": "yourUserName",
"apiKey": "yourApiKey"}
}
}' \
-H 'Content-Type: application/json' \
'https://identity.api.rackspacecloud.com/v2.0/tokens' | python -m json.tool
The following examples show the authentication response, which includes the authentication token id along with an expires attribute that specifies when the token expires.
More information about the response is provided after the examples.
Example 6. Authenticate response: XML
HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:50:20 GMT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<access xmlns:os-ksadm="http://docs.openstack.org/identity/api/ext/OS-KSADM/
v1.0"
xmlns="http://docs.openstack.org/identity/api/v2.0"
xmlns:rax-kskey="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
xmlns:rax-ksqa="http://docs.rackspace.com/identity/api/ext/RAX-KSQA/v1.0"
xmlns:common="http://docs.openstack.org/common/api/v1.0"
xmlns:ksgrp="http://docs.rackspace.com/identity/api/ext/RAX-KSGRP/v1.0"
xmlns:rax-kscatalog="http://docs.openstack.org/identity/api/ext/OSKSCATALOG/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom">
<token id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" expires="2011-12-08T22:51:02.
000-06:00"/>
<user id="123456" name="jsmith" rax-auth:defaultRegion="DFW">
<roles>
<role id="identity:admin" name="identity:admin" description="Admin Role.
"/>
<role id="identity:default" name="identity:default" description="Default
Role."/>
</roles>
</user>
<serviceCatalog>
<service type="rax:database" name="cloudDatabases">
<endpoint region="DFW" tenantId="1100111" publicURL="https://dfw.
databases.api.rackspacecloud.com/v1.0/1100111"/>
<endpoint region="ORD" tenantId="1100111" publicURL="https://ord.
databases.api.rackspacecloud.com/v1.0/1100111"/>
</service>
<service type="rax:load-balancer" name="cloudLoadBalancers">
<endpoint region="DFW" tenantId="1100111" publicURL="https://dfw.
loadbalancers.api.rackspacecloud.com/v1.0/1100111"/>
<endpoint region="ORD" tenantId="1100111" publicURL="https://ord.
loadbalancers.api.rackspacecloud.com/v1.0/1100111"/>
</service>
16
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
<service type="compute" name="cloudServersOpenStack">
<endpoint region="DFW" tenantId="1100111"
publicURL="https://dfw.servers.api.rackspacecloud.com/v2/1100111">
<version id="2" info="https://dfw.servers.api.rackspacecloud.com/v2/"
list="https://dfw.servers.api.rackspacecloud.com/" />
</endpoint>
<endpoint region="ORD" tenantId="1100111"
publicURL="https://ord.servers.api.rackspacecloud.com/v2/1100111">
<version id="2" info="https://ord.servers.api.rackspacecloud.com/v2/"
list="https://ord.servers.api.rackspacecloud.com/" />
</endpoint>
</service>
<service type="compute" name="cloudServers">
<endpoint tenantId="1100111"
publicURL="https://servers.api.rackspacecloud.com/v1.0/1100111">
<version id="1.0"
info="https://servers.api.rackspacecloud.com/v1.0/"
list="https://servers.api.rackspacecloud.com/"/>
</endpoint>
</service>
<service type="object-store" name="cloudFiles">
<endpoint region="DFW"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
publicURL="https://storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
internalURL="https://snet-storage101.dfw1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"/>
<endpoint region="ORD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
publicURL="https://storage101.ord1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
internalURL="https://snet-storage101.ord1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"/>
</service>
<service type="rax:object-cdn" name="cloudFilesCDN">
<endpoint region="DFW"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
publicURL="https://cdn1.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeee"/>
<endpoint region="ORD"
tenantId="MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee"
publicURL="https://cdn2.clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbbcccc-dddd-eeeeeeee"/>
</service>
<service type="rax:dns" name="cloudDNS">
<endpoint tenantId="1100111"
publicURL="https://dns.api.rackspacecloud.com/v1.0/1100111"/>
</service>
</serviceCatalog>
</access>
Example 7. Authenticate response: JSON
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 477
Date: Thu, 12 Apr 2012 18:45:13 GMT
{
"access": {
17
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
"token": {
"expires": "2011-12-08T22:51:02.000-06:00",
"id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"user": {
"id": "123456",
"name": "jsmith",
"RAX-AUTH:defaultRegion": "DFW",
"roles": [
{
"description": "Admin Role.",
"id": "identity:admin",
"name": "identity:admin"
},
{
"description": "Default Role.",
"id": "identity:default",
"name": "identity:default"
}
]
},
"serviceCatalog": [
{
"endpoints": [
{
"publicURL": "https://dfw.databases.api.
rackspacecloud.com/v1.0/1100111",
"region": "DFW",
"tenantId": "1100111"
},
{
"publicURL": "https://ord.databases.api.
rackspacecloud.com/v1.0/1100111",
"region": "ORD",
"tenantId": "1100111"
}
],
"name": "cloudDatabases",
"type": "rax:database"
},
{
"endpoints": [
{
"publicURL": "https://dfw.loadbalancers.api.
rackspacecloud.com/v1.0/1100111",
"region": "DFW",
"tenantId": "1100111"
},
{
"publicURL": "https://ord.loadbalancers.api.
rackspacecloud.com/v1.0/1100111",
"region": "ORD",
"tenantId": "1100111"
}
],
"name": "cloudLoadBalancers",
"type": "rax:load-balancer"
},
{
18
API v1.0
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
"endpoints": [
{
"tenantId": "1100111",
"region": "DFW",
"publicURL": "https://dfw.servers.api.rackspacecloud.
com/v2/1100111",
"versionId": "2",
"versionInfo": "https://dfw.servers.api.
rackspacecloud.com/v2/",
"versionList": "https://dfw.servers.api.
rackspacecloud.com/"
},
{
"tenantId": "1100111",
"region": "ORD",
"publicURL": "https://ord.servers.api.rackspacecloud.
com/v2/1100111",
"versionId": "2",
"versionInfo": "https://ord.servers.api.
rackspacecloud.com/v2/",
"versionList": "https://ord.servers.api.
rackspacecloud.com/"
}
],
"name": "cloudServersOpenStack",
"type": "compute"
},
{
"endpoints": [
{
"tenantId": "1100111",
"publicURL": "https://servers.api.rackspacecloud.com/
v1.0/1100111",
"versionId": "1.0",
"versionInfo": "https://servers.api.rackspacecloud.
com/v1.0/",
"versionList": "https://servers.api.rackspacecloud.
com/"
}
],
"name": "cloudServers",
"type": "compute"
},
{
"endpoints": [
{
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeee",
"publicURL": "https://storage101.dfw1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"internalURL": "https://snet-storage101.dfw1.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"region": "DFW"
},
{
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeee",
"publicURL": "https://storage101.ord1.clouddrive.com/
v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
19
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
"internalURL": "https://snet-storage101.ord1.
clouddrive.com/v1/MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"region": "ORD"
}
],
"name": "cloudFiles",
"type": "object-store"
},
{
"endpoints": [
{
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeee",
"publicURL": "https://cdn1.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"region": "DFW"
},
{
"tenantId": "MossoCloudFS_aaaaaaaa-bbbb-cccc-ddddeeeeeeee",
"publicURL": "https://cdn2.clouddrive.com/v1/
MossoCloudFS_aaaaaaaa-bbbb-cccc-dddd-eeeeeeee",
"region": "ORD"
}
],
"name": "cloudFilesCDN",
"type": "rax:object-cdn"
},
{
"endpoints": [
{
"region": "SYD",
"tenantId": "1100111",
"publicURL": "https://syd.orchestration.api.
rackspacecloud.com/v1/1100111"
},
{
"region": "IAD",
"tenantId": "1100111",
"publicURL": "https://iad.orchestration.api.
rackspacecloud.com/v1/1100111"
},
{
"region": "ORD",
"tenantId": "1100111",
"publicURL": "https://ord.orchestration.api.
rackspacecloud.com/v1/1100111"
},
{
"region": "DFW",
"tenantId": "1100111",
"publicURL": "https://dfw.orchestration.api.
rackspacecloud.com/v1/1100111"
}
],
"name": "cloudOrchestration",
"type": "orchestration"
},
{
"endpoints": [
20
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
{
"tenantId": "1100111",
"publicURL": "https://dns.api.rackspacecloud.com/v1.0/
1100111"
}
],
"name": "cloudDNS",
"type": "rax:dns"
}
]
}
}
The authentication token id is returned along with an expires attribute that specifies
when the token expires.
Notes
• For all response examples in this guide, the field values that you receive in
your responses will vary from those shown here because they will be specific
to your account.
• The information shown in the authenticate response examples is for USbased accounts. If you authenticate using a UK-based account, you will see
the service catalog information for UK-based accounts.
• The id attribute in the authenticate response specifies the authentication token. Tokens are valid for a finite duration.
You will set an environment variable (token) to specify your authentication
token for the Cloud Orchestration API operations in the section called “Step
5. Export environment variables to run cURL commands” [23]
• The expires attribute denotes the time after which the token becomes automatically become invalid. A token might be manually revoked before the
time identified by the expires attribute; expires predicts a token's maximum possible lifespan but does not guarantee that it will reach that lifespan.
Clients are encouraged to cache a token until it expires.
• Applications should be designed to re-authenticate after receiving a 401
(Unauthorized) response from a service endpoint.
The publicURL endpoints for cloudOrchestration (for example https://
ord.orchestration.api.rackspacecloud.com/v1/1100111) are also returned in
the response.
You will find the actual account number after the final forwardslash (/) in the publicURL
field. In this example, you can see that the account number is 1100111. You will set an environment variable (account) to specify your account number for the Cloud Orchestration
API operations in the section called “Step 5. Export environment variables to run cURL commands” [23]
After authentication, you can use cURL to perform GET, DELETE, and POST requests for the
Cloud Orchestration API.
21
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Step 4. Choose service access/endpoints
If you are using cURL, the endpoints to use for your Cloud Orchestration API operations are
summarized in the following table. Choose the endpoint for the data center where your
Cloud resources are located.
If you are using heat client, the endpoints to use for your Cloud Orchestration API operations are set automatically via the OS_REGION_NAME environment variable, so you can
skip this section and go to the section called “Step 6. Create a simple stack for a cloud server” [23].
Tip
To help you decide which regionalized endpoint to use, read about special considerations for choosing a region at http://www.rackspace.com/
knowledge_center/article/about-regions.
Table 4. Regionalized service endpoints
Region
Endpoint
Chicago (ORD)
https://ord.orchestration.api.rackspacecloud.com/v1/1234/
Dallas/Ft. Worth (DFW)
https://dfw.orchestration.api.rackspacecloud.com/v1/1234/
Northern Virginia (IAD)
https://iad.orchestration.api.rackspacecloud.com/v1/1234/
London (LON)
https://lon.orchestration.api.rackspacecloud.com/v1/1234/
Sydney (SYD)
https://syd.orchestration.api.rackspacecloud.com/v1/1234/
Hong Kong (HKG)
https://hkg.orchestration.api.rackspacecloud.com/v1/1234/
Note
All examples in this guide assume that you are operating against the ORD data center. If you are using a different data center, be sure to use the associated
endpoint from the table instead.
Replace the sample account ID number, 1234, with your actual account ID, which is
returned as part of the authentication response. You will set an environment variable
(OS_TENANT_ID) to specify your account ID for the Cloud Orchestration API operations in
the section called “Step 5. Export environment variables to run cURL commands” [23].
Refer to the section called “Step 3. Generate an authentication token” [14] for more information about obtaining the account ID.
When calling a Cloud Orchestration API operation, place the endpoint at the beginning of the request URL, for example: https://
ord.orchestration.api.rackspacecloud.com/v1/$OS_TENANT_ID/, as shown
in the cURL Create Stack Request example in the section called “Create stack by using
cURL” [26].
22
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Step 5. Export environment variables to run cURL
commands
To run the cURL command examples in this guide, follow this procedure to export environment variables.
If you are using heat client commands, skip to the section called “Step 6. Create a simple
stack for a cloud server” [23].
Export your tenant ID and authentication token to environment variables. All cURL examples in this guide use these environment variables.
To export environment variables:
1.
Export your tenant ID to the OS_TENANT_ID environment variable:
$ export OS_TENANT_ID="tenantId"
tenantId is the value in the tenantId field in the authentication response.
2.
Export your authentication token to the OS_AUTH_TOKEN environment variable:
$ export OS_AUTH_TOKEN="id"
id is the authentication token value in the id field in the token element in the authentication response. For information about the token ID, see the section called “Step 3.
Generate an authentication token” [14].
Step 6. Create a simple stack for a cloud server
Assume that you want to create a simple stack that defines a single cloud server. Use a text
editor such as nano or vi to create the following heat orchestration template (HOT) file and
then save it as single_server.template:
Example 8. single_server.template Example hot template file
heat_template_version: 2014-10-16
resources:
compute_instance:
type: "OS::Nova::Server"
properties:
flavor: 1 GB General Purpose v1
image: CentOS 6 (PV)
name: Single Server Stack
outputs:
public_ip:
description: public IP address of the deployed compute instance
value: { get_attr: [compute_instance, accessIPv4] }
23
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Notes
• If you enter in the template example text manually, remember to use a twospace indent (not Tab) for each subsection of the template.
• If you copy the example rather than entering the text manually, select the example from the HTML version of this guide by clicking the Select Text icon to
the right of the example and copying the text. Then paste the text into your
text editor.
This template has a resources section that creates a single cloud server with a 1 GB General Purpose v1 flavor size (which identifies a particular combination of memory capacity
and priority for CPU time). It has CentOS 6 installed, and is called Single Server Stack.
Notes
• You can find the information for resource types either by looking it up or by
using the API.
• You can look up the names for the supported attributes for resources here:
http://orchestration.rackspace.com/raxdox/index.html.
• To find the various types of supported template resources, use the List resource types API operation (GET /resource_types). The cURL command for
this operation is as follows. Be sure to use the correct values for your XAuth-Token and tenant_id):
curl -i -X GET -H 'X-Auth-Token: xxxxxx' -H 'Content-Type:
application/json' -H 'Accept: application/json' https://dfw.
orchestration.rackspacecloud.com/v1/<tenant_id>/resource_types
• To find the properties for a resource type, use the show resource data API
operation.
This template also has an outputs section. Outputs are used to provide important information to users, such as the IP address for the server in this example. The output in this
example is named public_ip. Its value is set by calling the intrinsic function get_attr,
and passing it the name of the cloud server resource (compute_instance) and the
attribute whose value is needed (accessIPv4). You will see shortly how this public
IP address is displayed to the user. You can find out more about intrinsic functions at
http://docs.rackspace.com/orchestration/api/v1/orchestration-templates-devguide/content/Defining_Template_dle245.html#intrinsic_functions_d1e725.
Now, choose one of the following methods to create the stack:
• the section called “Create stack with the heat client” [25]
• the section called “Create stack by using cURL” [26]
24
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Create stack with the heat client
To create the stack with the heat client:
•
Issue the following command, which includes the name of the template file that you
just created:
heat stack-create Single-Server-Stack --template-file single_server.
template
You should get a list of your stacks, including one with a stack_name of Single-Server-Stack with a stack_status of CREATE_IN_PROGRESS. For example:
+--------------------------------------+---------------------+-------------------+----------------------+
| id
| stack_name
| stack_status
|
creation_time
|
+--------------------------------------+---------------------+-------------------+----------------------+
| 3bd2c230-b02a-45d8-9f16-88c9a9f64d2d | Single-Server-Stack | CREATE_IN_PROGRESS |
2014-01-24T20:12:47Z |
+--------------------------------------+---------------------+-------------------+----------------------+
25
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Create stack by using cURL
To create a stack by using cURL
1.
Use the create stack API operation (/stacks) in the cURL request, as shown in the following example.
Example 9. cURL create stack: JSON request
curl -i -X POST -H 'Accept: application/json' -H 'Content-Type:
application/json' -H "X-Auth-Token: $OS_AUTH_TOKEN" -d \
'{
"stack_name": "Single-Server-Stack",
"disable_rollback": true,
"parameters": {},
"template": "heat_template_version: 2014-10-16\n \nresources:\n
compute_instance: \n
type: \"OS::Nova::Server\"\n
properties:
\n
flavor: 1 GB General Purpose v1\n
image: CentOS 6 (PV)\n
name: Single Server Stack\n
\noutputs:\n public_ip:\n
description: public IP address of the deployed compute instance\n
value: { get_attr: [compute_instance, accessIPv4] }
\n\n\n",
"timeout_mins": 60
}' \
https://ord.orchestration.api.rackspacecloud.com/v1/$OS_TENANT_ID/stacks
We recommend that you produce the value for the template attribute by executing
the following heat client command:
$ heat --debug stack-create Single-Server-Stack --template-file
single_server.template
Copy the value for the template attribute from the cURL command that is shown in
the output from the preceding command.
Although you can manually produce the required value for the template attribute
from the template file, to do so you must replace every line break with \n, escape any
double quotation marks (for example type: \"OS::Nova::Server\"), and maintain correct spacing to indicate the correct nesting level for each block in the template.
So it is easier to use the template value in the generated cURL command from the -debug output.
Note that executing the stack-create heat client command actually creates the stack,
so you must delete that stack before you issue the cURL command to create a stack.
As an alternative, you can also just use the entire cURL command generated by the -debug output rather than the cURL command shown in the previous example.
2.
The following example shows the response.
Example 10. cURL create stack: JSON response
HTTP/1.1 201 Created
content-length: 192
via: 1.0 Repose (Repose/2.13.0)
server: nginx/1.2.1
26
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
connection: keep-alive
location: https://ord.orchestration.api.rackspacecloud.com/v1/1234/stacks/
Single-Server-Stack/3bd2c230-b02a-45d8-9f16-88c9a9f64d2d
date: Thu, 23 Jan 2014 19:38:09 GMT
content-type: application/json
{
"stack": {
"id": "3bd2c230-b02a-45d8-9f16-88c9a9f64d2d",
"links": [
{
"href": "http://ord.orchestration.api.rackspacecloud.com/v1/1234/
stacks/Single-Server-Stack/3bd2c230-b02a-45d8-9f16-88c9a9f64d2d",
"rel": "self"
}
]
}
}
The example shows that the stack was created and has the ID 3bd2c230b02a-45d8-9f16-88c9a9f64d2d.
Notice that there is a self link that contains a versioned link to the stack resource. Use
this link in cases where the link will be followed immediately.
Step 7. List stacks
Now you can list stacks and confirm that your stack was created.
Choose one of the following methods:
• the section called “List stacks by using the heat client” [27]
• the section called “List stacks by using cURL” [28]
List stacks by using the heat client
This example lists stacks using the heat client.
To list stacks using the heat client:
•
Issue the following command:
heat stack-list
The command returns the id, stack_name, stack_status, and creation_time
for each of your stacks, as shown in the following example:
+--------------------------------------+---------------------+----------------+----------------------+
| id
| stack_name
| stack_status
|
creation_time
|
27
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
+--------------------------------------+---------------------+----------------+----------------------+
| bd2c230-b02a-45d8-9f16-88c9a9f64d2d | Single-Server-Stack | CREATE_COMPLETE |
2014-01-23T19:41:05Z |
+--------------------------------------+---------------------+----------------+----------------------+
In this case, you have just the Single-Server-Stack and its stack_status is
CREATE_COMPLETE.
Note
If you issue the stack-list command before the operation of creating the stack is complete, you might see the stack_status value of
CREATE_IN_PROGRESS. If you wait a minute, and then reissue the command, you should see that the stack has been created.
List stacks by using cURL
To list stacks with cURL:
1.
Execute the cURL request for list stacks:
Example 11. cURL list stacks: JSON request
curl -s \
-H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/json" \
https://ord.orchestration.api.rackspacecloud.com/v1/$OS_TENANT_ID/stacks |
python -m json.tool
2.
The following example shows the response.
Example 12. List stacks: JSON response
{
"stacks": [
{
"description": "No description",
"links": [
{
"href": "https://ord.orchestration.api.rackspacecloud.com/v1/
1234/stacks/Single-Server-Stack/bd2c230-b02a-45d8-9f16-88c9a9f64d2d",
"rel": "self"
}
],
"stack_status_reason": "Stack CREATE completed successfully",
"stack_name": "Single-Server-Stack",
"creation_time": "2014-01-23T19:41:05Z",
"updated_time": null,
"stack_status": "CREATE_COMPLETE",
"id": "bd2c230-b02a-45d8-9f16-88c9a9f64d2d"
}
]
}
28
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
You can see that your stack named Single-Server-Stack with the id bd2c230b02a-45d8-9f16-88c9a9f64d2d was successfully created.
Note
If you issue the stack-list command before the operation of creating the stack is complete, you might see the stack_status value of
CREATE_IN_PROGRESS. If you wait a minute, and then reissue the command, you should see that the stack has been created.
Step 8. Show stack details
In this section you show the details for your stack.
Choose one of the following methods:
• the section called “Show stack details by using the heat client” [29]
• the section called “Show stack details by using cURL” [30]
Show stack details by using the heat client
To show details for your stack by using the heat client:
•
Show the details for your stack Single-Server-Stack by issuing the following command:
heat stack-show Single-Server-Stack
The command returns the details for the stack:
+---------------------+---------------------------------------------------------------------------------------------------+
| capabilities
| []
|
| creation_time
| 2014-01-24T20:12:47Z
|
| description
| No description
|
| disable_rollback
| True
|
| id
| 3bd2c230-b02a-45d8-9f16-88c9a9f64d2d
|
| links
| http://ord.orchestration.api.rackspacecloud.com/v1/1234/
stacks/Single-Server-Stack/3bd2c230-b02a-45d8-9f16-88c9a9f64d2d
|
| notification_topics | []
|
| outputs
| [
|
|
|
{
|
|
|
"output_value": "23.253.88.131",
|
29
Rackspace Cloud Orchestration
Getting Started Guide
|
May 27, 2015
|
API v1.0
"description": "public IP address of the deployed compute
|
"output_key": "public_ip"
|
instance",
|
|
|
|
|
| ]
| parameters
| {
|
|
|
|
|
| }
| stack_name
| Single-Server-Stack
| stack_status
| CREATE_COMPLETE
| stack_status_reason
| Stack CREATE completed successfully
}
|
|
|
"OS::stack_name": "Single-Server-Stack",
|
"OS::stack_id": "3bd2c230-b02a-45d8-9f16-88c9a9f64d2d"
|
|
|
|
|
| template_description | No description
|
| timeout_mins
| 60
| updated_time
| None
|
|
+---------------------+---------------------------------------------------------------------------------------------------+
Notice this is where you can see the information created by the output parameter that you
created in the following section of your template file in the section called “Step 6. Create a
simple stack for a cloud server” [23]:
Example 13. outputs section for template single_server.template
outputs:
public_ip:
description: public IP address of the deployed compute instance
value: { get_attr: [compute_instance, accessIPv4] }
Locate the outputs property in the table of information returned by the stack-show
heat client command and look at the output value for the output_key public_ip.
The output_value in the preceding example is 23.253.88.56. That value is the public IP address for the server that was created by the stack Single-Server-Stack. If the
output parameter public_ip had not been provided in the template, there would be no
easy way to access the new server (other than by using the Cloud Control Panel). Using output parameters provides a method for returning important information to API users.
Show stack details by using cURL
To show details for the specified stack using cURL:
1.
Show stack details by executing the following request.
30
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
This operation does not require a request body.
Example 14. cURL show stack details: JSON request
curl -s \
-H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/json" \
https://ord.orchestration.api.rackspacecloud.com/v1/$OS_TENANT_ID/
stacks/Single-Server-Stack/stack_id | python -m json.tool
Remember to replace the following example values with their actual values:
• Single-Server-Stack — If you used a different name for your stack, specify it (see the
example in the section called “Create stack by using cURL” [26]).
• stack_id — Specify the ID returned in your create stack response (see the example in
the section called “Create stack by using cURL” [26]).
2.
The following example shows the response.
Example 15. Show stack details: JSON response
{
"stack": {
"disable_rollback": true,
"description": "No description",
"parameters": {
"OS::stack_name": "Single-Server-Stack",
"OS::stack_id": "3bd2c230-b02a-45d8-9f16-88c9a9f64d2d"
},
"stack_status_reason": "Stack CREATE completed successfully",
"stack_name": "Single-Server-Stack",
"outputs": [
{
"output_value": "23.253.88.131",
"description": "public IP address of the deployed compute
instance",
"output_key": "public_ip"
}
],
"creation_time": "2014-01-24T20:12:47Z",
"links": [
{
"href": "http://ord.orchestration.api.rackspacecloud.com/v1/1234/
stacks/Single-Server-Stack/3bd2c230-b02a-45d8-9f16-88c9a9f64d2d",
"rel": "self"
}
],
"capabilities": [
],
"notification_topics": [
],
"timeout_mins": 60,
"stack_status": "CREATE_COMPLETE",
"updated_time": null,
31
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
"id": "3bd2c230-b02a-45d8-9f16-88c9a9f64d2d",
"template_description": "No description"
}
}
The response shows the information created by the output parameter that you created
in the outputs section of your template file in the section called “Step 6. Create a simple
stack for a cloud server” [23]:
Example 16. outputs section for template single_server.template
outputs:
public_ip:
description: public IP address of the deployed compute instance
value: { get_attr: [compute_instance, accessIPv4] }
Locate the outputs property in the response information and look at the output value for the output_key public_ip. The output_value in the preceding example is
23.253.88.56. That value is the public IP address for the server that was created by the
stack Single-Server-Stack. If the output parameter public_ip had not been provided in the template, there would be no easy way to access the new server (other than by using the Cloud Control Panel). Using output parameters provides a method for returning important information to API users.
Step 9. Delete a stack
Since you are done using the stack, you can delete it.
Choose one of the following methods:
• the section called “Delete a stack by using the heat client” [32]
• the section called “Delete a stack by using cURL” [33]
Delete a stack by using the heat client
To delete the stack with the specified name using the heat client:
•
Delete your stack Single-Server-Stack by issuing the following command:
heat stack-delete Single-Server-Stack
The command returns the following information for the stack:
+--------------------------------------+---------------------+-------------------+----------------------+
| id
| stack_name
| stack_status
|
creation_time
|
+--------------------------------------+---------------------+-------------------+----------------------+
| bd2c230-b02a-45d8-9f16-88c9a9f64d2d | Single-Server-Stack | DELETE_IN_PROGRESS |
2014-01-23T19:41:05Z |
32
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
+--------------------------------------+---------------------+-------------------+----------------------+
The stack_status value shows that the stack is in the process of being deleted. After
a minute or so, you can execute the list stacks operation (refer to the section called “List
stacks by using the heat client” [27]) and observe that the Single-Server-Stack
stack is not listed.
Delete a stack by using cURL
To delete the specified stack by using cURL:
1.
Delete your stack Single-Server-Stack by executing the following request.
This operation does not require a request body. This operation does not return a response body.
Example 17. cURL delete stack: JSON request
curl -i -X DELETE \
-H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/json" \
https://ord.orchestration.api.rackspacecloud.com/v1/$OS_TENANT_ID/
stacks/Single-Server-Stack/stack_id
Remember to replace the following example values with their actual respective values:
• Single-Server-Stack — If you used a different name for your stack, specify it (see the
example in the section called “Create stack by using cURL” [26])
• stack_id — Specify the ID returned in your create stack response (see the example in
the section called “Create stack by using cURL” [26])
2.
The following example shows the response.
Example 18. Delete stack: JSON response
HTTP/1.1 204 No Content
Server: nginx/1.2.1
Date: Fri, 31 Jan 2014 16:36:24 GMT
Content-Type: text/html;charset=UTF-8
Content-Length: 0
Connection: keep-alive
Via: 1.0 Repose (Repose/2.13.0)
After a minute or so, you can execute the list stacks operation (refer to the section called
“List stacks by using cURL” [28]) and observe that the Single-Server-Stack is not
listed.
Step 10. Create a stack by using a resource group
Assume that you would like to create a cloud load balancer to use with some cloud servers.
You begin working on this task by creating a resource group to hold the servers. The ad33
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
vantage of this technique is that you can create the entire set of servers by creating one resource group, rather than specifying each server resource separately.
First, use your text editor to create the following template and save it in a file named
servers-with-lb.template:
Example 19. servers-with-lb.template Example
heat_template_version: 2014-10-16
description: |
Heat Orchestration Template that spins up a
resource group with 2 cloud servers.
resources:
web_nodes:
type: OS::Heat::ResourceGroup
properties:
count: 2
resource_def:
type: OS::Nova::Server
properties:
flavor: 1 GB General Purpose v1
image: CentOS 6 (PV)
name: LB-Compute Web Nodes
In the preceding example, a description is provided for the template. It is good practice
to always provide a brief description for what a template does in order to inform potential
future users about the template.
The resources section contains a resource group named web_nodes of type
OS::Heat::ResourceGroup. In the properties section for the group, the attribute
count is set to 2, which means that two resources of the type OS::Nova::Server
(as defined in the resource definition resource_def) will be created in the group. The
properties section for the resource definition for each resource in the group specifies
the following values:
• 1 GB General Purpose v1 flavor
• CentOS 6 (PV) image
• the name LB-Compute Web Nodes
Note
The advantage of using a resource group to define your servers is the fact that
you can set the desired number of servers to create by simply setting the value
of count in the template. For example, to create three Cloud Servers instead of
two, you could modify the value of count as follows:
count: 3
This technique enables you to quickly create an entire set of identical servers.
Choose one of the following methods:
34
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
• the section called “Create a stack by using a resource group with the heat client” [35]
• the section called “Create a stack by using a resource group with cURL” [35]
Create a stack by using a resource group with the heat
client
To create a stack with a resource group of cloud servers using the heat client:
1.
Create the stack using the heat client.
Issue the following command, which includes the name of the template file that you
just created:
heat stack-create Servers-With-LB-Stack --template-file servers-with-lb.
template
The command returns the information about the stack, including its status
CREATE_IN_PROGRESS:
+--------------------------------------+-----------------------+-------------------+----------------------+
| id
| stack_name
| stack_status
|
creation_time
|
+--------------------------------------+-----------------------+-------------------+----------------------+
| e7b67698-3929-43af-8e59-9652d00b7250 | Servers-With-LB-Stack | CREATE_IN_PROGRESS |
2014-01-28T18:00:27Z |
+--------------------------------------+-----------------------+-------------------+----------------------+
2.
After a couple of minutes you can issue the list stacks command (see the section called
“List stacks by using the heat client” [27]) to confirm that your stack is now created:
+--------------------------------------+-----------------------+----------------+----------------------+
| id
| stack_name
| stack_status
|
creation_time
|
+--------------------------------------+-----------------------+----------------+----------------------+
| e7b67698-3929-43af-8e59-9652d00b7250 | Servers-With-LB-Stack | CREATE_COMPLETE |
2014-01-28T18:00:27Z |
+--------------------------------------+-----------------------+----------------+----------------------+
Create a stack by using a resource group with cURL
To create the stack with a resource group of cloud servers using cURL:
1.
Create the stack by executing the following request.
35
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Example 20. cURL create stack: JSON request
curl -i -X POST -H 'Accept: application/json' -H 'Content-Type:
application/json' -H "X-Auth-Token: $OS_AUTH_TOKEN" -d \
'{
"stack_name": "Servers-With-LB-Stack",
"disable_rollback": true,
"parameters": {},
"template": "heat_template_version: 2014-10-16\n\ndescription:
|
\n Heat Orchestration Template that spins up a\n resource
group with 2 cloud servers.\n\nresources:\n web_nodes:\n
type:
OS::Heat::ResourceGroup\n
properties:\n
count: 2\n
resource_def:\n
type: OS::Nova::Server\n
properties:\n
flavor: 1 GB General Purpose v1\n
image: CentOS 6 (PV)\n
name: LB-Compute Web Nodes \n\n\n",
"timeout_mins": 60
}' \
https://ord.orchestration.api.rackspacecloud.com/v1/$OS_TENANT_ID/stacks
2.
The following example shows the response.
Example 21. Create stack: JSON response
HTTP/1.1 201 Created
Server: nginx/1.2.1
Date: Fri, 31 Jan 2014 17:09:37 GMT
Content-Type: application/json
Content-Length: 192
Location: https://ord.orchestration.api.rackspacecloud.com/v1/1234/stacks/
Servers-With-LB-Stack/e7b67698-3929-43af-8e59-9652d00b7250
Connection: keep-alive
Via: 1.0 Repose (Repose/2.13.0)
{"stack": {"id": "e7b67698-3929-43af-8e59-9652d00b7250", "links":
[{"href": "http://ord.orchestration.api.rackspacecloud.com/v1/1234/
stacks/Servers-With-LB-Stack/e7b67698-3929-43af-8e59-9652d00b7250", "rel":
"self"}]}}
The stack Servers-With-LB-Stack was successfully created and has the id
e7b67698-3929-43af-8e59-9652d00b7250.
Step 11. Update a stack with a load balancer
In this section you update your stack by adding a load balancer to use with the two servers.
1. Make a copy of your servers-with-lb.template from the previous section and
name the copy servers-with-lb-add.template.
2. Add the load balancer to your servers-with-lb-add.template file by adding the
highlighted text in the following example.
Example 22. servers-with-lb-add.template with load balancer added example
heat_template_version: 2014-10-16
description: |
36
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Heat Orchestration Template that spins up a
resource group with 2 cloud servers
and a cloud load balancer.
resources:
web_nodes:
type: OS::Heat::ResourceGroup
properties:
count: 2
resource_def:
type: OS::Nova::Server
properties:
flavor: 1 GB General Purpose v1
image: CentOS 6 (PV)
name: LB-Compute Web Nodes
lb:
type: Rackspace::Cloud::LoadBalancer
properties:
name: LB-Compute load balancer
nodes:
- addresses: { get_attr: [web_nodes, accessIPv4]} # This is where the
# wiring magic happens
port: 80
condition: ENABLED
healthMonitor:
attemptsBeforeDeactivation: 3
delay: 10
timeout: 120
type: HTTP
path: "/"
statusRegex: "."
bodyRegex: "."
protocol: HTTP
port: 80
virtualIps:
- type: PUBLIC
ipVersion: IPV4
outputs:
lb_public_ip:
description: The public IP address of the load balancer
value: { get_attr: [lb, PublicIp]}
In the description section, you added the information that the template now also creates a load balancer.
For the lb resource (in the resources section), you added the information to create the
load balancer. The resource type is Rackspace::Cloud::LoadBalancer. The load balancer has the following properties:
• It is named LB-Compute load balancer.
• It defines a list of addresses for the back-end nodes by calling the get_attr intrinsic
function, passing it the name of the resource group (web_nodes) and the IP address for
37
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
each server resource (accessIPv4), as defined in the resource group. These back-end
nodes are the servers that you created in the section called “Step 10. Create a stack by using a resource group” [33]. Each node uses port 80, and all nodes are enabled.
• The load balancer protocol is HTTP and the service is defined on port 80.
• One public IPV4 virtual IP address should be added for the load balancer.
Note
To create a ServiceNet address for the load balancer instead of a public virtual IP address, use the following value for type instead:
- type: SERVICENET
You will also need to change the outputs as follows:
outputs:
lb_servicenet_ip:
description: The Servicenet IP address of the load balancer
value: { get_attr: [lb, virtualIps, 0, address ]}
Note that since virtualIps is an array, you need to request the address
in the first element of the array (array subscript 0) to get the Servicenet address.
• A health monitor is defined with the following attributes set:
• attemptsBeforeDeactivation – Number of attempts made before the node is removed from the rotation
• delay – Number of seconds to wait before executing the health monitor
• timeout – Number of seconds to wait for a connection to be made before timing out
• type – Type of the health monitor
• path – HTTP path used in the monitor request
• statusRegex – Regular expression used to evaluate the HTTP status code returned in
the response
• bodyRegex – Regular expression used to evaluate the contents of the body of the response
The outputs section defines a single output lb_public_ip, which is the public IP address for the load balancer. Its value is assigned to the result of calling the get_attr intrinsic function with the name of the resource (lb) and its attribute (PublicIp).
Choose one of the following methods:
• the section called “Update a stack with a load balancer by using the heat client” [39]
• the section called “Update a stack with a load balancer by using cURL” [40]
38
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Update a stack with a load balancer by using the heat client
To update the specified stack by using the heat client:
1.
Update the stack using the heat client.
Issue the following command:
heat stack-update Servers-With-LB-Stack --template-file servers-with-lbadd.template
The command returns the information about the stack, including its status
UPDATE_IN_PROGRESS:
+--------------------------------------+-----------------------+-------------------+----------------------+
| id
| stack_name
| stack_status
|
creation_time
|
+--------------------------------------+-----------------------+-------------------+----------------------+
| e7b67698-3929-43af-8e59-9652d00b7250 | Servers-With-LB-Stack | UPDATE_IN_PROGRESS |
2014-01-28T18:00:27Z |
+--------------------------------------+-----------------------+-------------------+----------------------+
2.
Wait a couple of minutes and then issue the following command:
$ heat stack-show Servers-With-LB-Stack
The command returns the details about the stack, including its stack_status
UPDATE_COMPLETE:
+---------------------+---------------------------------------------------------------------------------------------------+
| Property
| Value
|
+---------------------+---------------------------------------------------------------------------------------------------+
| capabilities
| []
|
| creation_time
| 2014-01-28T18:00:27Z
|
| description
| Heat Orchestration Template that spins up a resource
|
|
| group with 2 cloud servers and a Cloud Load
|
|
| Balancer.
|
| disable_rollback
| True
|
| id
| e7b67698-3929-43af-8e59-9652d00b7250
|
| links
| http://ord.orchestration.api.rackspacecloud.com/v1/1234/
stacks/Servers-With-LB-Stack/e7b67698-3929-43af-8e59-9652d00b7250
|
39
Rackspace Cloud Orchestration
Getting Started Guide
| notification_topics
| []
| outputs
| [
|
|
|
|
|
|
May 27, 2015
API v1.0
|
|
{
|
"output_value": "162.242.141.48",
|
"description": "The public IP address of the load
|
"output_key": "lb_public_ip"
|
balancer",
|
|
|
|
|
| ]
| parameters
| {
|
|
|
|
|
| }
| stack_name
| Servers-With-LB-Stack
| stack_status
| UPDATE_COMPLETE
| stack_status_reason
| Stack successfully updated
}
|
|
|
"OS::stack_name": "Servers-With-LB-Stack",
|
"OS::stack_id": "e7b67698-3929-43af-8e59-9652d00b7250"
|
|
|
|
|
| template_description | Heat Orchestration Template that spins up a resource
|
|
| group with 2 cloud servers and a Cloud Load
|
|
| Balancer.
|
| timeout_mins
| 60
|
| updated_time
| 2014-01-28T21:34:47Z
|
+---------------------+---------------------------------------------------------------------------------------------------+
The outputs property (set in the outputs section of the template), shows that the
public IP address of the new load balancer is 162.242.141.48.
Update a stack with a load balancer by using cURL
To update the specified stack with by using cURL:
1.
Update the stack by executing the following request.
Remember to replace the names in the example preceding with their actual respective
values:
• Servers-With-LB-Stack — The name of the stack, if you changed it
40
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
• stack_id — The ID of the stack, as returned in your create stack response (see the example in the section called “Create stack by using cURL” [26])
Example 23. cURL update stack with load balancer: JSON request
curl -i -X PUT -H 'Accept: application/json' -H 'Content-Type:
application/json' -H "X-Auth-Token: $OS_AUTH_TOKEN" -d \
'{
"stack_name": "Servers-With-LB-Stack",
"disable_rollback": true,
"parameters": {},
"template": "heat_template_version: 2014-10-16\n\ndescription: |
\n Heat Orchestration Template that spins up a\n resource group
with 2 cloud servers\n and a cloud load balancer.\n\nresources:\n
web_nodes:\n
type: OS::Heat::ResourceGroup\n
properties:\n
count: 2\n
resource_def:\n
type: OS::Nova::Server\n
properties:\n
flavor: 1 GB General Purpose v1\n
image: CentOS 6 (PV)\n
name: LB-Compute Web Nodes \n\n
lb:\n
type: Rackspace::Cloud::LoadBalancer\n
properties:\n
name: LB-Compute load balancer\n
nodes:\n
- addresses:
{ get_attr: [web_nodes, accessIPv4]} # This is where the\n
# wiring magic happens\n
port: 80\n
condition: ENABLED\n
healthMonitor:\n
attemptsBeforeDeactivation: 3\n
delay: 10\n
timeout:
120\n
type: HTTP\n
path: \"/\"\n
statusRegex: \".
\"\n
bodyRegex: \".\"\n
protocol: HTTP\n
port: 80\n
virtualIps:\n
- type: PUBLIC\n
ipVersion: IPV4\n\noutputs:
\n lb_public_ip:\n
description: The public IP address of the load
balancer\n
value: { get_attr: [lb, PublicIp]} \n\n",
"timeout_mins": 60
}' \
https://ord.orchestration.api.rackspacecloud.com/v1/$OS_TENANT_ID/
stacks/Servers-With-LB-Stack/stack_id
2.
The following example shows the response for update stack with load balancer:
Example 24. Update stack with load balancer: JSON response
HTTP/1.1 100 Continue
HTTP/1.1 202 Accepted
Server: nginx/1.2.1
Date: Fri, 31 Jan 2014 22:06:57 GMT
Content-Type: text/plain;charset=UTF-8
Content-Length: 58
Connection: keep-alive
Via: 1.0 Repose (Repose/2.13.0)
202 Accepted
The request is accepted for processing.
After a few minutes, you can execute the show stack details operation to ensure that
the update completed successfully:
Remember to replace the names in the example with their actual respective values:
41
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
• Servers-With-LB-Stack — If you used a different name for your stack, specify it (see
the example in the section called “Create a stack by using a resource group with
cURL” [35])
• stack_id — The stack ID, as returned in your create stack response (see the example
in the section called “Create stack by using cURL” [26])
Example 25. cURL show stack details: JSON request
curl -s \
-H "X-Auth-Token: $OS_AUTH_TOKEN" \
-H "Content-Type: application/json" \
https://ord.orchestration.api.rackspacecloud.com/v1/$OS_TENANT_ID/stacks/
Servers-With-LB-Stack/stack_id | python -m json.tool
The following example shows the response.
Example 26. Show stack details: JSON response
{
"stack": {
"capabilities": [],
"creation_time": "2014-01-31T22:02:46Z",
"description": "Heat Orchestration Template that spins up a\nresource
group with 2 cloud servers\nand a cloud load balancer.\n",
"disable_rollback": true,
"id": "6574e1b1-4c22-49f5-a06d-6d99eb8d87c6",
"links": [
{
"href": "http://ord.orchestration.api.rackspacecloud.com/v1/
1234/stacks/Servers-With-LB-Stack/6574e1b1-4c22-49f5-a06d-6d99eb8d87c6",
"rel": "self"
}
],
"notification_topics": [],
"outputs": [
{
"description": "The public IP address of the load balancer",
"output_key": "lb_public_ip",
"output_value": "184.106.100.140"
}
],
"parameters": {
"OS::stack_name": "Servers-With-LB-Stack",
"OS::stack_id": "6574e1b1-4c22-49f5-a06d-6d99eb8d87c6"
},
"stack_name": "Servers-With-LB-Stack",
"stack_status": "UPDATE_COMPLETE",
"stack_status_reason": "Stack successfully updated",
"template_description": "Heat Orchestration Template that spins up a\
nresource group with 2 cloud servers\nand a cloud load balancer.\n",
"timeout_mins": 60,
"updated_time": "2014-01-31T22:08:01Z"
}
}
42
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Step 12. Delete a stack with a load balancer
When you are finished using your stack, delete it by using the commands shown in the section called “Step 9. Delete a stack” [32]. Be sure to adjust the stack name (and for cURL,
the stack_id) as necessary to reflect the new Servers-With-LB-Stack that you are
deleting.
This concludes the Getting Started exercises.
See the following section for a summary of the heat client commands.
For more tutorials on using Cloud Orchestration, see the Heat Tutorial.
43
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Document change history
This version of the guide replaces and obsoletes all previous versions. The most recent
changes are described in the following table:
Revision Date
Summary of Changes
May 27, 2015
• Added reference to SDKs in Overview [1].
May 21, 2015
• Added introductory information in Overview [1].
April 16, 2015
• Added CLI output- commands in the section called “Outputs” [50].
April 6, 2015
• Added note for upgrading heat client on Ubuntu in the section called “Step 1. Install the
heat client” [5].
• Added reference to list of supported resources (http://orchestration.rackspace.com/raxdox/index.html).
February 16, 2015
• Edited the document throughout.
• Replaced the deprecated 1 GB Performance flavor with 1 GB General Purpose v1
flavor.
• Added information about creating a SERVICENET load balancer in the section called “Step
11. Update a stack with a load balancer” [36].
February 10, 2015
• Updated image names as needed.
• Removed London endpoint, since we now have one global endpoint for the Rackspace Authentication Service. See the section called “Step 3. Generate an authentication token” [14].
December 17, 2014
• Updated templates to have latest template version:
heat_template_version: 2014-10-16
November 24, 2014
• Updated environment variables for running cURL commands. See the section called “Step 5.
Export environment variables to run cURL commands” [23].
November 21, 2014
• Updated cURL examples for the section called “Create a stack by using a resource group
with cURL” [35] and the section called “Update a stack with a load balancer by using
cURL” [40].
October 28, 2014
• Updated the document to add OS_REGION_NAME environment variable and remove the
HEAT_URL for the heat client.
October 7, 2014
• Updated the document for initial Unlimited Availability (UA) release.
August 1, 2014
• Updated information about choosing which regionalized endpoint to use in the section
called “Step 4. Choose service access/endpoints” [22].
July 23, 2014
• Added information about choosing which regionalized endpoint to use in the section called
“Step 4. Choose service access/endpoints” [22].
May 8, 2014
• Updated the link to the Python installation for Windows and Mac users in the section called
“Step 1. Install the heat client” [5].
March 17, 2014
• Updated examples to use Performance instances for Cloud Servers.
March 14, 2014
• Updated examples for Show Stack Details in the section called “Step 8. Show stack details” [29] and the section called “Step 11. Update a stack with a load balancer” [36].
March 13, 2014
• Updated the section called “Stack resources” [48].
March 12, 2014
• Updated examples to use CentOS 6.5 (since CentOS 6.4 is no longer supported).
• Added note about copying template examples in the section called “Step 6. Create a simple
stack for a cloud server” [23].
March 11, 2014
• Initial release.
.
44
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
heat Client command summary
Table of Contents
Stack operations ............................................................................................................
Stack resources ..............................................................................................................
Events ...........................................................................................................................
Outputs .........................................................................................................................
Templates .....................................................................................................................
Miscellaneous ................................................................................................................
45
48
49
50
50
52
Use the following heat client commands to perform API operations:
Stack operations
Create stack
$ heat stack-create <STACK_NAME>
[-f <FILE>] [-e <FILE>] [-u <URL>] [-o <URL>]
[-c <TIMEOUT>] [-c <TIMEOUT>] [-r ] [-P <KEY1=
VALUE1;KEY2=VALUE2...>]
Positional arguments
• STACK_NAME. The name of the stack to create.
Optional arguments
• -f <FILE> , --template-file <FILE>. The
path to the template.
• -e <FILE> , --environment-file <FILE>.
The path to the environment.
• -u <URL> , --template-url <URL>. The URL
of the template.
• -o <URL> , --template-object <URL>. The
URL to retrieve the template object (for example
from Swift).
• -c <TIMEOUT> , --create-timeout <TIMEOUT>. The stack creation timeout in minutes. Default:
60. (DEPRECATED. Use -t instead)
• -t <TIMEOUT> , --timeout <TIMEOUT>. The
stack creation timeout in minutes. Default: 60.
• -r , --enable-rollback. Enable rollback on a
create or update failure.
45
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
• -P <KEY1=VALUE1;KEY2=VALUE2...> , --parameters <KEY1=VALUE1;KEY2=VALUE2...>.
Parameter values used to create the stack. This argument can be specified multiple times, or once with parameters separated by semicolon.
List stack data
$ heat stack-list
Get stack data
$ heat stack-show <NAME or ID>
NAME is the name of the stack, or ID is the ID of the
stack to show.
Delete stack
$ heat stack-delete <NAME or ID>
NAME is the name of the stack, or ID is the ID of the
stack to delete.
Abandon stack
$ heat stack-abandon <NAME or ID>
NAME is the name of the stack, or ID is the ID of the
stack to abandon. This command deletes a specified
stack, but leaves its resources intact, and returns data
describing the stack and its resources.
Cancel stack update
$ heat stack-cancel-update <NAME or ID>
NAME is the name of the stack, or ID is the ID of the
stack.
Preview stack
$ heat stack-preview <STACK_NAME>
[-f <FILE>] [-e <FILE>] [-u <URL>] [-o <URL>]
[-c <TIMEOUT>] [-t <TIMEOUT>][-r ] [-P <KEY1=
VALUE1;KEY2=VALUE2...>]
Positional arguments
• STACK_NAME. The name of the stack to preview.
Optional arguments
• -f <FILE> , --template-file <FILE>. The
path to the template.
• -e <FILE> , --environment-file <FILE>.
The path to the environment.
• -u <URL> , --template-url <URL>. The URL
of the template.
• -o <URL> , --template-object <URL>. The
URL to retrieve the template object (for example
from Swift).
46
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
• -c <TIMEOUT> , --create-timeout <TIMEOUT>. The stack creation timeout in minutes. Default:
60. (DEPRECATED. Use -t instead.)
• -t <TIMEOUT> , --timeout <TIMEOUT>. The
stack creation timeout in minutes. Default: 60.
• -r , --enable-rollback. Enable rollback on a
create or update failure.
• -P <KEY1=VALUE1;KEY2=VALUE2...> , --parameters <KEY1=VALUE1;KEY2=VALUE2...>.
Parameter values used to create the stack. This can be
specified multiple times, or once with parameters separated by semicolon.
Adopt stack
$ heat stack-adopt <STACK_NAME>
[-e <FILE>] [-c <TIMEOUT>] [-t <TIMEOUT>] [-a
<FILE>]
[-r ] [-P <KEY1=VALUE1;KEY2=VALUE2...>]
Positional argument
• STACK_NAME. The name of the stack to adopt. This
operation creates a stack from existing resources.
Optional arguments
• -e <FILE> , --environment-file <FILE>.
The path to the environment.
• -c <TIMEOUT> , --create-timeout <TIMEOUT>. The stack creation timeout in minutes. Default:
60. (DEPRECATED. Use -t instead.)
• -t <TIMEOUT> , --timeout <TIMEOUT>. The
stack creation timeout in minutes. Default: 60.
• -a <FILE> , --adopt-file <FILE>. The path
to the data file to adopt.
• -r , --enable-rollback. Enable rollback on create/update failure.
• -P <KEY1=VALUE1;KEY2=VALUE2...> , --parameters <KEY1=VALUE1;KEY2=VALUE2...>.
Parameter values used to create the stack. This can be
specified multiple times, or once with parameters separated by semicolon.
Update stack
$ heat stack-update <NAME or ID>
[-f <FILE>] [-e <FILE>] [-u <URL>] [-o <URL>]
[-P <KEY1=VALUE1;KEY2=VALUE2...>]
47
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
NAME is the name of the stack, or ID is the ID of the
stack to update.
Stack resources
List stack resources
$ heat resource-list <NAME or ID>
NAME is the name of the stack, or ID is the ID of the
stack for which to list resources.
List resource metadata
$ heat resource-metadata <NAME or ID> <RESOURCE>
NAME is the name of the stack, or ID is the ID of the
stack for which to show resource metadata.
RESOURCE is the name of the resource for which to
show metadata.
Show resource
$ heat resource-show <NAME or ID> <RESOURCE>
NAME is the name of the stack, or ID is the ID of the
stack for which to show the resource.
RESOURCE is the name of the resource for which to
show the details.
Generate template based on resource
$ heat resource-template [-F <FORMAT>]
<RESOURCE_TYPE>
DEPRECATED. Use resource-type-template instead
Positional arguments
• RESOURCE_TYPE is the type of resource for which to
generate a template.
Optional arguments
• -F <FORMAT>, --format <FORMAT>. The template output format: yaml or json.
List resource types
$ heat resource-type-list
Show resource type
$ heat resource-type-show <RESOURCE_TYPE>
RESOURCE_TYPE is the type of the resource to show.
Generate a template based on a
resource type
$ heat resource-type-template <RESOURCE_TYPE> -F
<FORMAT>
RESOURCE_TYPE is the type of the resource.
48
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Optional arguments
• -F <FORMAT> , --format <FORMAT>. The template output format: yaml or json.
Events
List events for a stack
$ heat event-list [-r <RESOURCE>] <NAME or ID>
Positional arguments
• <NAME or ID>. NAME is the name of the stack, or
ID is the ID of the stack for which to show the events.
Optional arguments
• -r <RESOURCE>, --resource <RESOURCE>. The
name of the resource by which to filter events.
Describe event
$ heat event-show <NAME or ID> <RESOURCE>
<EVENT>
Positional arguments
• <NAME or ID>. NAME is the name of the stack, or
ID is the ID of the stack for which to show the events.
• <RESOURCE>. The name of the resource to which the
event belongs.
• <EVENT>. The ID of the event for which to display details.
49
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Outputs
Show available outputs
$ heat output-list <NAME or ID>
Where NAME is the name of the stack, or ID is the ID of
the stack to list.
Show a specific stack output
$ heat output-show [-a] [-F <FORMAT>] <NAME or
ID> [<OUTPUT NAME>]
Positional arguments
• <NAME or ID>. NAME is the name of the stack, or
ID is the ID of the stack to query.
Optional arguments
• -a. Displays all stack outputs.
• -F <FORMAT>. The template output format: yaml or
json.
• <OUTPUT NAME>. The name of the output to display.
Templates
Get template for a stack
$ heat template-show <NAME or ID>
<NAME or ID> NAME is the name of the stack, or ID is
the ID of the stack for which to get the template.
Validate template with parameters
$ heat template-validate [-u <URL>] [-f <FILE>]
[-e <FILE>] [-o <URL>]
[-P <KEY1=
VALUE1;KEY2=VALUE2...>]
Optional arguments
• -u <URL>, --template-url <URL>. The URL of
the template.
• -f <FILE>, --template-file <FILE>. The path
to the template.
• -e <FILE>, --environment-file. The path to
the environment.
• -o <URL>, --template-object <URL>. The URL
from which to retrieve the template object (for example, from Swift).
• -P <KEY1=VALUE1;KEY2=VALUE2...>, --parameters <KEY1=VALUE1;KEY2=VALUE2...>.
50
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
The parameter values to validate. This argument can
be specified multiple times, or once with parameters
separated by semicolons.
51
Rackspace Cloud Orchestration
Getting Started Guide
May 27, 2015
API v1.0
Miscellaneous
Display help for heat client
$ heat help
Display help for heat client command
$ heat help <COMMAND>
Display build information for
heat client
$ heat build-info
Provide bash completion for
heat
$ heat bash-completion
COMMAND is the name of the command for which to display help.
Note
To provide bash completion for heat for the
current session, enter the following command:
$ complete -W "`heat bash-completion`" heat
52