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": {}
        }
    }
}