IRC on Freenode #rackspace developer forum
  • Sign Up
  • Log In
    • MyRackspace Portal
    • Cloud Control Panel
    • Rackspace Webmail Login
    • Email Admin Login
  • Rackspace Logo
  • Developer Home
  • Documentation & SDKs
  • Blog
SDK Quickstarts
  • Gophercloud Go
  • JClouds Java
  • OpenStack.NET.NET
  • pkgcloud Node.js
  • php-opencloud PHP
  • pyrax Python
  • fog Ruby
Cloud User Guides
  • Core Infrastructure
  • Cloud Servers
  • Cloud Images
  • Orchestration
Developer Community
  • Developer Blog
  • Knowledge Center
  • Developer Forum
  • Outreach & Events
Rackspace Cloud
  • Auto Scale
  • CDN
  • Cloud Block Storage
  • Cloud Databases
  • Cloud DNS
  • Cloud Files
  • Cloud Identity
  • Cloud Images
  • Cloud Load Balancers
  • Cloud Monitoring
  • Cloud Networks
  • Cloud Queues
  • Cloud Servers
  • Orchestration
Other Products
  • Airbrake
  • Mailgun
  • ObjectRocket
  • RedisToGo
Developer Community
  • Developer Blog
  • Knowledge Center
  • Developer Forum
  • Outreach & Events

Rackspace Developer Docs


Let’s Build Something Powerful Together!

Submit an issue
  • Cloud Orchestration 1.0
  • Getting started
    • Get your credentials
    • Send API requests to Orchestration
      • Using the heat client
      • Using cURL
    • Authenticate to the Rackspace Cloud
      • Authenticating by using the heat client
      • Authenticating by using cURL
    • Orchestration concepts
      • Template
      • Resource
      • Stack
    • Create and manage stacks
      • Creating a simple stack for a cloud server
      • Listing stacks
      • Showing stack details
      • Deleting a stack
      • Creating a stack by using a resource group
      • Updating a stack with a load balancer
      • Deleting a stack with a load balancer
  • General API information
    • Service access endpoints
    • Contract version
    • Request and response types
    • Date and time format
    • Paginated collections
    • HTTP status codes
      • Response body
      • 2xx (Success) status codes
      • 4xx (Client error) status codes
      • 5xx (Server error) status codes
    • Stack status
    • Role Based Access Control
      • Assigning roles to account users
      • Roles available for Cloud Orchestration
      • Multiproduct global roles and permissions
      • Resolving conflicts between RBAC multiproduct and product-specific roles
      • RBAC Permissions Cross-reference to Cloud Orchestration API Operations
  • API reference
    • Stack operations
      • Create stack
      • Adopt stack
      • List stack data
      • Find stack
      • Show stack details
      • Update stack
      • Delete stack
      • Preview stack
      • Abandon stack
    • Stack resources
      • Find stack resources
      • List resources
      • Show resource data
      • List resource types
      • Show resource schema
      • Show resource template
    • Stack events
      • Find stack events
      • List stack events
      • List resource events
      • Show event details
    • Templates
      • Get stack template
      • Validate template
    • Build info
      • Show build information
  • Release notes
    • API 1.0 release, October 7, 2014
      • What's new
      • Resolved issues
      • Known issues
  • Service updates
  • Additional resources
  • Disclaimer

Stack operations#

Use the stack operations to view and manage stacks for a Rackspace Cloud account.

Create stack#

POST /v1/{tenant_id}/stacks

Creates a stack.

This table shows the possible response codes for this operation:

Response Code Name Description
201 Created The request has been fulfilled and resulted in a new resource being created.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
409 Conflict The request could not be completed due to a conflict with the current state of the resource.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.

This table shows the body parameters for the request:

Name Type Description
stack_name String (Required) A name for the new stack. This value must be unique within a project. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens. Specifically, the name must match the ^[a-zA-Z][a-zA-Z0-9_.- ]*$ regular expression. When you delete or abandon a stack, its name might not be available for reuse for an unspecified period of time.
template_url String (Optional) A URI to the location containing the stack template on which to perform the specified operation. See the description of the template parameter for information about the expected template content located at the URI. This parameter is only required when you omit the template parameter. If you specify both parameters, this parameter is ignored.
template String (Optional) The stack template on which to perform the specified operation. This parameter is always provided as a string in the JSON request body. The content of the string is a JSON- or YAML-formatted Orchestration template. For example: "template": { "heat_template_version": "2013-05- 23", ...} This parameter is required only when you omit the template_url parameter. If you specify both parameters, this value overrides the template_url parameter value.
files Map (Optional) Supplies the contents of files referenced in the template or the environment. Stack templates and resource templates can explicitly reference files by using the get_file intrinsic function. In addition, the environment parameter can contain implicit references to files. The value is a JSON object, where each key is a relative or absolute URI which serves as the name of a file, and the associated value provides the contents of the file. The following code shows the general structure of this parameter. { ... "files": { "fileA.yaml": "Contents of the file", "file:///usr/fileB.template": "Contents of the file", "http://example.com/fileC.template": "Contents of the file" } ... } Additionally, some template authors encode their user data in a local file. The Orchestration client examines the template for the get_file intrinsic function and adds an entry to the files map with the path to the file as the name and the file contents as the value. So, a simple example looks like this: { "files": { "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" }, ..., "stack_name": "teststack", "template": { ..., "resources": { "my_server": { "type": "OS::Nova::Server", "properties": { ..., "user_data": { "get_file": "myfile" } } } } }, "timeout_mins": 60 } Do not use this parameter to provide the content of the template located at the address specified by template_url. Instead, use the template parameter to supply the template content as part of the request.
parameters Object (Optional) Supplies arguments for parameters defined in the stack template. The value is a JSON object, where each key is the name of a parameter defined in the template and the associated value is the argument to use for that parameter when instantiating the template. The following code shows the general structure of this parameter. In the example, a and b would be the names of two parameters defined in the template. { ... "parameters": { "a": "Value", "b": "3" } ... } While the service accepts JSON numbers for parameters with the type number and JSON objects for parameters with the type json, all parameter values are converted to their string representation for storage in the created Stack. Clients are encouraged to send all parameter values using their string representation for consistency between requests and responses from the Orchestration service. A value must be provided for each template parameter which does not specify a default value. However, this parameter is not allowed to contain JSON properties with names that do not match a parameter defined in the template. The files parameter maps logical file names to file contents. Both the get_file intrinsic function and provider template functionality use this mapping. When you want to use a provider template, for example, the Orchestration service adds an entry to the files map by using: * The URL of the provider template as the name. * The contents of that file as the value. Additionally, some template authors encode their user data in a local file. The Orchestration client examines the template for the get_file intrinsic function and adds an entry to the files map with the path to the file as the name and the file contents as the value. So, a simple example looks like this: { "files": { "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" }, ..., "stack_name": "teststack", "template": { ..., "resources": { "my_server": { "type": "OS::Nova::Server", "properties": { ..., "user_data": { "get_file": "myfile" } } } } }, "timeout_mins": 60 }
tags String (Optional) One or more simple string tags to associate with the stack. To associate multiple tags with a stack, separate the tags with commas. For example, tag1,tag2.
parameters.param_name-n String (Optional) User-defined parameter names to pass to the template.
parameters.param_value-n String (Optional) User-defined parameter values to pass to the template.

Example Create stack: JSON request

{
    "files": {},
    "disable_rollback": true,
    "parameters": {
        "flavor": "2 GB General Purpose v1"
    },
    "stack_name": "teststack",
    "template": {
        "heat_template_version": "2013-05-23",
        "description": "Simple template to test heat commands",
        "parameters": {
            "flavor": {
                "default": "1 GB General Purpose v1",
                "type": "string"
            }
        },
        "resources": {
            "hello_world": {
                "type": "OS::Nova::Server",
                "properties": {
                    "key_name": "heat_key",
                    "flavor": {
                        "get_param": "flavor"
                    },
                    "image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
                    "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
                }
            }
        }
    },
    "timeout_mins": 60
}

Response#

This table shows the body parameters for the response:

Name Type Description
stack_name String (Required) The name of the stack to create.
template_url String (Required) The URL of the template.
template String (Required) A JSON template.
environment String (Optional) A JSON environment for the stack.
files String (Optional) A map of file names to JSON template bodies. File names are provider resource templates, as referenced in the environment.
parameters.param_name- n String (Optional) User-defined parameter names to pass to the template.
parameters.param_value-n String (Optional) User-defined parameter values to pass to the template.
timeout_mins Integer (Optional) The timeout for stack creation in minutes.
disable_rollback String (Optional) Enables or disables deletion of all previously-created stack resources when stack creation fails. Set to True to keep all previously-created stack resources when stack creation fails. Set to False to delete all previously-created stack resources when stack creation fails. Default is True.
stack_id String (Required) The system-assigned ID for the stack.
links String (Required) A list of URLs for the stack.
rel String (Required) A reference to the stack's parent. If no parent, reference is self.

Example Create stack: JSON response

{
    "stack": {
        "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
        "links": [
            {
                "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
                "rel": "self"
            }
        ]
    }
}

Adopt stack#

POST /v1/{tenant_id}/stacks

Creates a stack from existing resources.

This table shows the possible response codes for this operation:

Response Code Name Description
201 Created The request has been fulfilled and resulted in a new resource being created.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
409 Conflict The request could not be completed due to a conflict with the current state of the resource.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.

This table shows the body parameters for the request:

Name Type Description
stack_name String (Required) A name for the new stack. The value must be unique within a project. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens. Specifically, the name must match the ^[a-zA-Z][a-zA-Z0-9_.- ]*$ regular expression. When you delete or abandon a stack, its name might not be available for reuse for an unspecified period of time.
template_url String (Optional) A URI to the location containing the stack template on which to perform the specified operation. See the description of the template parameter for information about the expected template content located at the URI. This parameter is only required when you omit the template parameter. If you specify both parameters, this parameter is ignored.
template String (Optional) The stack template on which to perform the specified operation. This parameter is always provided as a string in the JSON request body. The content of the string is a JSON- or YAML-formatted Orchestration template. For example: "template": { "heat_template_version": "2013-05- 23", ...} This parameter is required only when you omit the template_url parameter. If you specify both parameters, this value overrides the template_url parameter value.
environment String (Optional) A JSON environment for the stack.
files Map (Optional) Supplies the contents of files referenced in the template or the environment. Stack templates and resource templates can explicitly reference files by using the get_file intrinsic function. In addition, the environment parameter can contain implicit references to files. The value is a JSON object, where each key is a relative or absolute URI which serves as the name of a file, and the associated value provides the contents of the file. The following code shows the general structure of this parameter. { ... "files": { "fileA.yaml": "Contents of the file", "file:///usr/fileB.template": "Contents of the file", "http://example.com/fileC.template": "Contents of the file" } ... } Additionally, some template authors encode their user data in a local file. The Orchestration client examines the template for the get_file intrinsic function and adds an entry to the files map with the path to the file as the name and the file contents as the value. So, a simple example looks like this: { "files": { "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" }, ..., "stack_name": "teststack", "template": { ..., "resources": { "my_server": { "type": "OS::Nova::Server", "properties": { ..., "user_data": { "get_file": "myfile" } } } } }, "timeout_mins": 60 } Do not use this parameter to provide the content of the template located at the address specified by template_url. Instead, use the template parameter to supply the template content as part of the request.
parameters Object (Optional) Supplies arguments for parameters defined in the stack template. The value is a JSON object, where each key is the name of a parameter defined in the template and the associated value is the argument to use for that parameter when instantiating the template. The following code shows the general structure of this parameter. In the example, a and b would be the names of two parameters defined in the template. { ... "parameters": { "a": "Value", "b": "3" } ... } While the service accepts JSON numbers for parameters with the type number and JSON objects for parameters with the type json, all parameter values are converted to their string representation for storage in the created Stack. Clients are encouraged to send all parameter values using their string representation for consistency between requests and responses from the Orchestration service. A value must be provided for each template parameter which does not specify a default value. However, this parameter is not allowed to contain JSON properties with names that do not match a parameter defined in the template. The files parameter maps logical file names to file contents. Both the get_file intrinsic function and provider template functionality use this mapping. When you want to use a provider template, for example, the Orchestration service adds an entry to the files map by using: * The URL of the provider template as the name. * The contents of that file as the value. Additionally, some template authors encode their user data in a local file. The Orchestration client examines the template for the get_file intrinsic function and adds an entry to the files map with the path to the file as the name and the file contents as the value. So, a simple example looks like this: { "files": { "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" }, ..., "stack_name": "teststack", "template": { ..., "resources": { "my_server": { "type": "OS::Nova::Server", "properties": { ..., "user_data": { "get_file": "myfile" } } } } }, "timeout_mins": 60 }
timeout_mins String (Optional) The timeout for stack creation in minutes.
adopt_stack_data String (Required) Existing resources data to adopt a stack. Data returned by abandon stack could be provided as adopt_stack_data.
disable_rollback String (Optional) Enables or disables deletion of all stack resources when stack creation fails. Set to True to keep all resources when stack creation fails. Set to False to delete all resources when stack creation fails. Default is True.

Example Adopt stack: JSON request

{
    "adopt_stack_data": {
        "action": "CREATE",
        "id": "bxxxxx4-0xx2-4xx1-axx6-exxxxxxxc",
        "name": "teststack",
        "resources": {
            "MyServer": {
                "action": "CREATE",
                "metadata": {},
                "name": "MyServer",
                "resource_data": {},
                "resource_id": "cxxxx3-dxx3-4xx-bxx2-3xxxxxxxxa",
                "status": "COMPLETE",
                "type": "OS::Trove::Instance"
            }
        },
        "status": "COMPLETE",
        "template": {}
    },
    "stack_name": "{stack_name}",
    "template_url": "{template_url}",
    "timeout_mins": "{timeout_mins}"
}

Response#

Example Adopt stack: JSON response

{
    "action": "CREATE",
    "id": "46c927bb-671a-43db-a29c-16a2610865ca",
    "name": "trove",
    "resources": {
        "mysql_server": {
            "action": "CREATE",
            "metadata": {},
            "name": "mysql_server",
            "resource_data": {},
            "resource_id": "74c5be7e-3e62-41e7-b455-93d1c32d56e3",
            "status": "COMPLETE",
            "type": "OS::Trove::Instance"
        }
    },
    "status": "COMPLETE",
    "template": {
        "heat-template-version": "2013-05-23",
        "description": "MySQL server instance",
        "parameters": {
            "instance_name": {
                "description": "The database instance name",
                "type": "string"
            }
        },
        "resources": {
            "mysql_server": {
                "properties": {
                    "databases": [
                        {
                            "name": "testdbonetwo"
                        }
                    ],
                    "flavor": "1 GB General Purpose v1",
                    "name": "test-trove-db",
                    "size": 30,
                    "users": [
                        {
                            "databases": [
                                "testdbonetwo"
                            ],
                            "name": "testuser",
                            "password": "testpass123"
                        }
                    ]
                },
                "type": "OS::Trove::Instance"
            }
        }
    }
}

List stack data#

GET /v1/{tenant_id}/stacks

Lists active stacks.

This table shows the possible response codes for this operation:

Response Code Name Description
200 Success Request succeeded.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.

This table shows the query parameters for the request:

Name Type Description
id String (Optional) Filters the stack list by a specified stack ID. Use this filter multiple times to filter by multiple IDs.
status String (Optional) Filters the stack list by a specified status. Use this filter multiple times to filter by multiple statuses.
name String (Optional) Filters the stack list by a specified name. Use this filter multiple times to filter by multiple names.
action String (Optional) Filters the stack list by a specified action. Use this filter multiple times to filter by multiple actions.
tenant String (Optional) Filters the stack list by a specified tenant. Use this filter multiple times to filter by multiple tenants.
username String (Optional) Filters the stack list by a specified user name. Use this filter multiple times to filter by multiple user names.
owner_id String (Optional) Filters the stack list by a specified owner ID, which is the ID of the parent stack of listed stack. Use this filter multiple times to filter by multiple owner IDs.
limit Int (Optional) Requests a specified page size of returned items from the query. Returns a number of items up to the specified limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
marker String (Optional) Specifies the ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
show_deleted String (Optional) Specifies whether to include deleted stacks in the list. Default is False, which excludes deleted stacks from the list.
show_nested String (Optional) Specifies whether to include nested stacks in the list. Default is False, which excludes nested stacks from the list.
sort_keys String (Optional) Sorts the stack list by name, status, created_at, or updated_at key.
tags String (Optional) Lists stacks that contain one or more simple string tags. To specify multiple tags, separate the tags with commas. For example, tag1,tag2. The boolean AND expression is used to combine multiple tags.
tags_any String (Optional) Lists stacks that contain one or more simple string tags. To specify multiple tags, separate the tags with commas. For example, tag1,tag2. The boolean OR expression is used to combine multiple tags.
not_tags String (Optional) Lists stacks that do not contain one or more simple string tags. To specify multiple tags, separate the tags with commas. For example, tag1,tag2. The boolean AND expression is used to combine multiple tags.
not_tags_any String (Optional) Lists stacks that do not contain one or more simple string tags. To specify multiple tags, separate the tags with commas. For example, tag1,tag2. The boolean OR expression is used to combine multiple tags.
sort_dir String (Optional) The sort direction of the list. A valid value is asc (ascending) or desc (descending).
global_tenant String (Optional) Specifies whether to include stacks from all tenants in the stack list. Policy requirements are specified in the Orchestration policy.json file. Default is False.
with_count String (Optional) Specifies whether to include a count key in the response. The count key value is the number of stacks that match the query criteria. Default is False.

This operation does not accept a request body.

Response#

Example List stack data: JSON response

{
    "stacks": [
        {
            "creation_time": "2014-06-03T20:59:46Z",
            "description": "sample stack",
            "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
            "links": [
                {
                    "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
                    "rel": "self"
                }
            ],
            "stack_name": "simple_stack",
            "stack_status": "CREATE_COMPLETE",
            "stack_status_reason": "Stack CREATE completed successfully",
            "updated_time": "",
            "tags": ""
        }
    ]
}

Find stack#

GET /v1/{tenant_id}/stacks/{stack_name}

Finds the canonical URL for a specified stack.

Also works with verbs other than GET, so you can perform PUT and DELETE operations on a current stack. Set your client to follow redirects. Note that when redirecting, the request method should not change, as defined in RFC2626. However, in many clients the default behavior is to change the method to GET when you receive a 302 because this behavior is ubiquitous in web browsers.

This table shows the possible response codes for this operation:

Response Code Name Description
202 Accepted The request has been accepted for processing, but the processing has not been completed.
302 Found The requested resource resides temporarily under a different URI.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
404 Not Found The server has not found anything matching the Request-URI.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.
stack_name String (Required) The name of a stack.

This operation does not accept a request body.

Response#

Example Find stack: JSON response

{
    "stack": {
        "capabilities": [],
        "creation_time": "2014-06-04T20:36:12Z",
        "description": "sample stack",
        "disable_rollback": true,
        "id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7",
        "links": [
            {
                "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/5333af0c-cc26-47ee-ac3d-8784cefafbd7",
                "rel": "self"
            }
        ],
        "notification_topics": [],
        "outputs": [],
        "parameters": {
            "OS::stack_id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7",
            "OS::stack_name": "simple_stack"
        },
        "stack_name": "simple_stack",
        "stack_status": "CREATE_COMPLETE",
        "stack_status_reason": "Stack CREATE completed successfully",
        "template_description": "sample stack",
        "timeout_mins": null,
        "updated_time": null
    }
}

Show stack details#

GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}

Shows details for a specified stack.

This table shows the possible response codes for this operation:

Response Code Name Description
200 Success Request succeeded.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
404 Not Found The server has not found anything matching the Request-URI.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.
stack_name String (Required) The name of a stack.
{stack_id} String (Required) The stack ID.

This operation does not accept a request body.

Response#

Example Show stack details: JSON response

{
    "stack": {
        "capabilities": [],
        "creation_time": "2014-06-03T20:59:46Z",
        "description": "sample stack",
        "disable_rollback": "True",
        "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
        "links": [
            {
                "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
                "rel": "self"
            }
        ],
        "notification_topics": [],
        "outputs": [],
        "parameters": {
            "OS::stack_id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
            "OS::stack_name": "simple_stack"
        },
        "stack_name": "simple_stack",
        "stack_status": "CREATE_COMPLETE",
        "stack_status_reason": "Stack CREATE completed successfully",
        "template_description": "sample stack",
        "timeout_mins": "",
        "updated_time": "",
        "tags": ""
    }
}

Update stack#

PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id}

Updates a specified stack.

This table shows the possible response codes for this operation:

Response Code Name Description
202 Accepted The request has been accepted for processing, but the processing has not been completed.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
404 Not Found The server has not found anything matching the Request-URI.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.
stack_name String (Required) The name of a stack.
{stack_id} String (Required) The stack ID.

This table shows the body parameters for the request:

Name Type Description
template_url String (Optional) A URI to the location containing the stack template on which to perform the specified operation. See the description of the template parameter for information about the expected template content located at the URI. This parameter is only required when you omit the template parameter. If you specify both parameters, this parameter is ignored.
template String (Optional) The stack template on which to perform the specified operation. This parameter is always provided as a string in the JSON request body. The content of the string is a JSON- or YAML-formatted Orchestration template. For example: "template": { "heat_template_version": "2013-05- 23", ...} This parameter is required only when you omit the template_url parameter. If you specify both parameters, this value overrides the template_url parameter value.
environment String (Optional) A JSON environment for the stack.
files Map (Optional) Supplies the contents of files referenced in the template or the environment. Stack templates and resource templates can explicitly reference files by using the get_file intrinsic function. In addition, the environment parameter can contain implicit references to files. The value is a JSON object, where each key is a relative or absolute URI which serves as the name of a file, and the associated value provides the contents of the file. The following code shows the general structure of this parameter. { ... "files": { "fileA.yaml": "Contents of the file", "file:///usr/fileB.template": "Contents of the file", "http://example.com/fileC.template": "Contents of the file" } ... } Additionally, some template authors encode their user data in a local file. The Orchestration client examines the template for the get_file intrinsic function and adds an entry to the files map with the path to the file as the name and the file contents as the value. So, a simple example looks like this: { "files": { "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" }, ..., "stack_name": "teststack", "template": { ..., "resources": { "my_server": { "type": "OS::Nova::Server", "properties": { ..., "user_data": { "get_file": "myfile" } } } } }, "timeout_mins": 60 } Do not use this parameter to provide the content of the template located at the address specified by template_url. Instead, use the template parameter to supply the template content as part of the request.
tags String (Optional) One or more simple string tags to associate with the stack. To associate multiple tags with a stack, separate the tags with commas. For example, tag1,tag2.
parameters Object (Optional) This parameter supplies updated arguments for parameters defined in the stack template. The value is a JSON object, where each key is the name of a parameter defined in the template and the associated value is the argument to use for that parameter when instantiating the template. The following code shows the general structure of this parameter. In the example, a and b are the names of two parameters defined in the template. {... "parameters": { "a": "Value", "b": "3" }... } While the service accepts JSON numbers for parameters with the type number and JSON objects for parameters with the type json, all parameter values are converted to their string representation for storage in the created Stack. Clients are encouraged to send all parameter values using their string representation for consistency between requests and responses from the Orchestration service. You must specify a value for each template parameter that does not have a default value. However, this parameter cannot contain JSON properties with names that do not match a parameter that is defined in the template.
timeout_mins String (Optional) The timeout for stack creation in minutes.

Example Update stack: JSON request

{
    "template": {
        "heat_template_version": "2013-05-23",
        "description": "Create a simple stack",
        "parameters": {
            "flavor": {
                "default": "1 GB General Purpose v1",
                "type": "string"
            }
        },
        "resources": {
            "hello_world": {
                "type": "OS::Nova::Server",
                "properties": {
                    "key_name": "heat_key",
                    "flavor": {
                        "get_param": "flavor"
                    },
                    "image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
                    "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
                }
            }
        }
    },
    "parameters": {
        "flavor": "2 GB General Purpose v1"
    }
}

Response#

This operation does not return a response body.

Delete stack#

DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}

Deletes a specified stack and any snapshots of that stack.

This table shows the possible response codes for this operation:

Response Code Name Description
204 No Content The server has fulfilled the request but does not need to return an entity- body, and might want to return updated meta- information.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
404 Not Found The server has not found anything matching the Request-URI.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.
stack_name String (Required) The name of a stack.
{stack_id} String (Required) The stack ID.

This operation does not accept a request body.

Response#

This operation does not return a response body.

Preview stack#

POST /v1/{tenant_id}/stacks/preview

Previews a stack.

This table shows the possible response codes for this operation:

Response Code Name Description
200 Success Request succeeded.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
409 Conflict The request could not be completed due to a conflict with the current state of the resource.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.

This table shows the body parameters for the request:

Name Type Description
stack_name String (Required) A name for the new stack. The value must be unique within a project. The name must start with an ASCII letter and can contain ASCII letters, digits, underscores, periods, and hyphens. Specifically, the name must match the ^[a-zA-Z][a-zA-Z0-9_.- ]*$ regular expression. When you delete or abandon a stack, its name might not be available for reuse for an unspecified period of time.
template_url String (Optional) A URI to the location containing the stack template on which to perform the specified operation. See the description of the template parameter for information about the expected template content located at the URI. This parameter is only required when you omit the template parameter. If you specify both parameters, this parameter is ignored.
template String (Optional) The stack template on which to perform the specified operation. This parameter is always provided as a string in the JSON request body. The content of the string is a JSON- or YAML-formatted Orchestration template. For example: "template": { "heat_template_version": "2013-05- 23", ...} This parameter is required only when you omit the template_url parameter. If you specify both parameters, this value overrides the template_url parameter value.
files Map (Optional) Supplies the contents of files referenced in the template or the environment. Stack templates and resource templates can explicitly reference files by using the get_file intrinsic function. In addition, the environment parameter can contain implicit references to files. The value is a JSON object, where each key is a relative or absolute URI which serves as the name of a file, and the associated value provides the contents of the file. The following code shows the general structure of this parameter. { ... "files": { "fileA.yaml": "Contents of the file", "file:///usr/fileB.template": "Contents of the file", "http://example.com/fileC.template": "Contents of the file" } ... } Additionally, some template authors encode their user data in a local file. The Orchestration client examines the template for the get_file intrinsic function and adds an entry to the files map with the path to the file as the name and the file contents as the value. So, a simple example looks like this: { "files": { "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" }, ..., "stack_name": "teststack", "template": { ..., "resources": { "my_server": { "type": "OS::Nova::Server", "properties": { ..., "user_data": { "get_file": "myfile" } } } } }, "timeout_mins": 60 } Do not use this parameter to provide the content of the template located at the address specified by template_url. Instead, use the template parameter to supply the template content as part of the request.
parameters Object (Optional) Supplies arguments for parameters defined in the stack template. The value is a JSON object, where each key is the name of a parameter defined in the template and the associated value is the argument to use for that parameter when instantiating the template. The following code shows the general structure of this parameter. In the example, a and b would be the names of two parameters defined in the template. { ... "parameters": { "a": "Value", "b": "3" } ... } While the service accepts JSON numbers for parameters with the type number and JSON objects for parameters with the type json, all parameter values are converted to their string representation for storage in the created Stack. Clients are encouraged to send all parameter values using their string representation for consistency between requests and responses from the Orchestration service. A value must be provided for each template parameter which does not specify a default value. However, this parameter is not allowed to contain JSON properties with names that do not match a parameter defined in the template. The files parameter maps logical file names to file contents. Both the get_file intrinsic function and provider template functionality use this mapping. When you want to use a provider template, for example, the Orchestration service adds an entry to the files map by using: * The URL of the provider template as the name. * The contents of that file as the value. Additionally, some template authors encode their user data in a local file. The Orchestration client examines the template for the get_file intrinsic function and adds an entry to the files map with the path to the file as the name and the file contents as the value. So, a simple example looks like this: { "files": { "myfile": "#!/bin/bash\necho \"Hello world\" > /root/testfile.txt" }, ..., "stack_name": "teststack", "template": { ..., "resources": { "my_server": { "type": "OS::Nova::Server", "properties": { ..., "user_data": { "get_file": "myfile" } } } } }, "timeout_mins": 60 }

Example Preview stack: JSON request

{
    "files": {},
    "disable_rollback": true,
    "parameters": {
        "flavor": "2 GB General Purpose v1"
    },
    "stack_name": "teststack",
    "template": {
        "heat_template_version": "2013-05-23",
        "description": "Simple template to test heat commands",
        "parameters": {
            "flavor": {
                "default": "1 GB General Purpose v1",
                "type": "string"
            }
        },
        "resources": {
            "hello_world": {
                "type": "OS::Nova::Server",
                "properties": {
                    "key_name": "heat_key",
                    "flavor": {
                        "get_param": "flavor"
                    },
                    "image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
                    "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
                }
            }
        }
    },
    "timeout_mins": 60
}

Response#

This table shows the body parameters for the response:

Name Type Description
parent String (Required) The stack ID of the parent stack, if this is a nested stack.
id String (Required) The stack ID.
stack_name String (Required) The name of the stack.
description String (Required) A description of the stack.
template_description String (Required) A description of the template that defines the stack.
timeout_mins Integer (Required) Timelines for stack creation.
disable_rollback String (Required) Enables or disables stack rollback when stack creation fails. Set to True to rollback the stack when stack creation fails. Set to False to disable stack rollback when stack creation fails. Default is True.
capabilities String (Required) List of stack capabilities for stack.
notification_topics String (Required) List of notification topics for stack.
updated_time String (Required) Time of last stack update in the following format: YYYY-MM- DDThh:mm:ssTZD, where TZD is the time zone designator.
stack_owner String (Required) Stack owner name.
parameters String (Required) List of parameters defined for the stack.
resources String (Required) List of stack resources.

Example Preview stack: JSON response

{
    "stack": {
        "capabilities": [],
        "creation_time": "2015-01-31T15:12:36Z",
        "description": "HOT template for Nova Server resource.\n",
        "disable_rollback": true,
        "id": "None",
        "links": [
            {
                "href": "http://192.168.122.102:8004/v1/6e18cc2bdbeb48a5basad2dc499f6804/stacks/test_stack/None",
                "rel": "self"
            }
        ],
        "notification_topics": [],
        "parameters": {
            "OS::project_id": "6e18cc2bdbeb48a5basad2dc499f6804",
            "OS::stack_id": "None",
            "OS::stack_name": "teststack",
            "admin_user": "cloud-user",
            "flavor": "1 GB General Purpose v1",
            "image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
            "key_name": "heat_key",
            "server_name": "MyServer"
        },
        "parent": null,
        "resources": [
            {
                "attributes": {},
                "description": "",
                "metadata": {},
                "physical_resource_id": "",
                "properties": {
                    "description": "Ping and SSH",
                    "name": "the_sg",
                    "rules": [
                        {
                            "direction": "ingress",
                            "ethertype": "IPv4",
                            "port_range_max": null,
                            "port_range_min": null,
                            "protocol": "icmp",
                            "remote_group_id": null,
                            "remote_ip_prefix": null,
                            "remote_mode": "remote_ip_prefix"
                        },
                        {
                            "direction": "ingress",
                            "ethertype": "IPv4",
                            "port_range_max": 65535,
                            "port_range_min": 1,
                            "protocol": "tcp",
                            "remote_group_id": null,
                            "remote_ip_prefix": null,
                            "remote_mode": "remote_ip_prefix"
                        },
                        {
                            "direction": "ingress",
                            "ethertype": "IPv4",
                            "port_range_max": 65535,
                            "port_range_min": 1,
                            "protocol": "udp",
                            "remote_group_id": null,
                            "remote_ip_prefix": null,
                            "remote_mode": "remote_ip_prefix"
                        }
                    ]
                },
                "required_by": [
                    "server1"
                ],
                "resource_action": "INIT",
                "resource_identity": {
                    "path": "/resources/the_sg_res",
                    "stack_id": "None",
                    "stack_name": "teststack",
                    "tenant": "6e18cc2bdbeb48a5b3cad2dc499f6804"
                },
                "resource_name": "the_sg_res",
                "resource_status": "COMPLETE",
                "resource_status_reason": "",
                "resource_type": "OS::Neutron::SecurityGroup",
                "stack_identity": {
                    "path": "",
                    "stack_id": "None",
                    "stack_name": "teststack",
                    "tenant": "6e18cc2bdbeb48a5b3cad2dc499f6804"
                },
                "stack_name": "teststack",
                "updated_time": "2015-01-31T15:12:36Z"
            },
            {
                "attributes": {
                    "accessIPv4": "",
                    "accessIPv6": "",
                    "addresses": "",
                    "console_urls": "",
                    "first_address": "",
                    "instance_name": "",
                    "name": "MyServer",
                    "networks": "",
                    "show": ""
                },
                "description": "",
                "metadata": {},
                "physical_resource_id": "",
                "properties": {
                    "admin_pass": null,
                    "admin_user": "cloud-user",
                    "availability_zone": null,
                    "block_device_mapping": null,
                    "config_drive": null,
                    "diskConfig": null,
                    "flavor": "1 GB General Purpose v1",
                    "flavor_update_policy": "RESIZE",
                    "image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
                    "image_update_policy": "REPLACE",
                    "key_name": "heat_key",
                    "metadata": {
                        "ha_stack": "None"
                    },
                    "name": "MyServer",
                    "networks": [
                        {
                            "fixed_ip": null,
                            "network": "private",
                            "port": null,
                            "uuid": null
                        }
                    ],
                    "personality": {},
                    "reservation_id": null,
                    "scheduler_hints": null,
                    "security_groups": [
                        "None"
                    ],
                    "software_config_transport": "POLL_SERVER_CFN",
                    "user_data": "",
                    "user_data_format": "HEAT_CFNTOOLS"
                },
                "required_by": [],
                "resource_action": "INIT",
                "resource_identity": {
                    "path": "/resources/hello_world",
                    "stack_id": "None",
                    "stack_name": "teststack",
                    "tenant": "6e18cc2bdbeb48a3433cad2dc499sdf32234"
                },
                "resource_name": "hello_world",
                "resource_status": "COMPLETE",
                "resource_status_reason": "",
                "resource_type": "OS::Nova::Server",
                "stack_identity": {
                    "path": "",
                    "stack_id": "None",
                    "stack_name": "teststack",
                    "tenant": "6e18cc2bdbeb48a3433cad2dc499sdf32234"
                },
                "stack_name": "teststack",
                "updated_time": "2015-01-31T15:12:36Z"
            }
        ],
        "stack_name": "test_stack",
        "stack_owner": "admin",
        "template_description": "HOT template for Nova Server resource.\n",
        "timeout_mins": null,
        "updated_time": null
    }
}

Abandon stack#

DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/abandon

Deletes a specified stack but leaves its resources intact, and returns data describing the stack and its resources.

This table shows the possible response codes for this operation:

Response Code Name Description
200 Success Request succeeded.
400 Bad Request The request could not be understood by the server due to malformed syntax.
401 Unauthorized The request requires user authentication.
404 Not Found The server has not found anything matching the Request-URI.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

Request#

This table shows the URI parameters for the request:

Name Type Description
{tenant_id} String The ID of the tenant. A tenant is also known as an account or project.
stack_name String (Required) The name of a stack.
{stack_id} String (Required) The stack ID.

This operation does not accept a request body.

Response#

Example Abandon stack: JSON response

{
    "status": "COMPLETE",
    "name": "g",
    "dry_run": true,
    "template": {
        "outputs": {
            "instance_ip": {
                "value": {
                    "str_replace": {
                        "params": {
                            "username": "ec2-user",
                            "hostname": {
                                "get_attr": [
                                    "server",
                                    "first_address"
                                ]
                            }
                        },
                        "template": "ssh username@hostname"
                    }
                }
            }
        },
        "heat_template_version": "2013-05-23",
        "resources": {
            "server": {
                "type": "OS::Nova::Server",
                "properties": {
                    "key_name": {
                        "get_param": "key_name"
                    },
                    "image": {
                        "get_param": "image"
                    },
                    "flavor": {
                        "get_param": "flavor"
                    }
                }
            }
        },
        "parameters": {
            "key_name": {
                "default": "heat_key",
                "type": "string"
            },
            "image": {
                "default": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
                "type": "string"
            },
            "flavor": {
                "default": "1 GB General Purpose v1",
                "type": "string"
            }
        }
    },
    "action": "CREATE",
    "id": "16934ca3-40e0-4fb2-a289-a700662ec05a",
    "resources": {
        "server": {
            "status": "COMPLETE",
            "name": "server",
            "resource_data": {},
            "resource_id": "39d5dad7-7d7a-4cc8-bd84-851e9e2ff4ea",
            "action": "CREATE",
            "type": "OS::Nova::Server",
            "metadata": {}
        }
    }
}
Previous API reference
Next Stack resources
Docs
  • Cloud Backup
  • Cloud Block Storage
  • Cloud Databases
  • Cloud DNS
  • Cloud Files
  • Cloud Identity
  • Cloud Images
  • Cloud Load Balancers
  • Cloud Monitoring
  • Cloud Orchestration
  • Cloud Networks
  • Cloud Queues
  • Cloud Servers
  • Rackspace Auto Scale
  • Rackspace CDN
Sdks
  • Go
  • Java
  • .Net
  • Node
  • PHP
  • Python
  • Ruby
Partner Tools
  • Airbrake
  • Mailgun
  • ObjectRocket
  • RedisToGo
Community
  • Developer Blog
  • Events
©2018 Rackspace US, Inc.
  • ©2018 Rackspace US, Inc.
  • About Rackspace
  • Investors
  • Careers
  • Privacy Statement
  • Website Terms
  • Trademarks