Orchestration API v1 (CURRENT)

Uses a template language to orchestrate OpenStack services.

General API information

Authenticated calls that target a known URI but that use an HTTP method that the implementation does not support return a 405 Method Not Allowed error code. In addition, the HTTP OPTIONS method is supported for each known URI. In both cases, the Allow response header indicates the HTTP methods that are supported for the resource.

API versions

GET
/
List versions

Lists all Orchestration API versions.

 
Normal response codes
200
{
    "versions": [
        {
            "status": "CURRENT",
            "id": "v1.0",
            "links": [
                {
                    "href": "http://23.253.228.211:8000/v1/",
                    "rel": "self"
                }
            ]
        }
    ]
}

This operation does not accept a request body.

Stacks

POST
/v1/​{tenant_id}​/stacks
Create stack

Creates a stack.

 
Normal response codes
201
Error response codes
400, 401, 409, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name plain String

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 (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

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.

Response parameters
Parameter Style Type Description
stack_name plain String

The name of the stack to create.

template_url plain String

The URL of the template.

template plain String

A JSON template.

environment (Optional) plain String

A JSON environment for the stack.

files (Optional) plain String

A map of file names to JSON template bodies. File names are provider resource templates, as referenced in the environment.

param_name-n (Optional) plain String

User-defined parameter names to pass to the template.

param_value-n (Optional) plain String

User-defined parameter values to pass to the template.

timeout_mins (Optional) plain String

The timeout for stack creation in minutes.

disable_rollback (Optional) plain String

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 plain String

The system-assigned ID for the stack.

links plain String

A list of URLs for the stack.

rel plain String

A reference to the stack's parent. If no parent, reference is self.

{
    "files": {},
    "disable_rollback": true,
    "parameters": {
        "flavor": "m1.heat"
    },
    "stack_name": "teststack",
    "template": {
        "heat_template_version": "2013-05-23",
        "description": "Simple template to test heat commands",
        "parameters": {
            "flavor": {
                "default": "m1.tiny",
                "type": "string"
            }
        },
        "resources": {
            "hello_world": {
                "type": "OS::Nova::Server",
                "properties": {
                    "key_name": "heat_key",
                    "flavor": {
                        "get_param": "flavor"
                    },
                    "image": "40be8d1a-3eb9-40de-8abd-43237517384f",
                    "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
                }
            }
        }
    },
    "timeout_mins": 60
}
{
    "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"
            }
        ]
    }
}
POST
/v1/​{tenant_id}​/stacks
Adopt stack

Creates a stack from existing resources.

 
Normal response codes
201
Error response codes
400, 401, 409, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name plain String

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 (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

A JSON environment for the stack.

files (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

The timeout for stack creation in minutes.

adopt_stack_data plain String

Existing resources data to adopt a stack. Data returned by abandon stack could be provided as adopt_stack_data.

disable_rollback (Optional) plain String

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.

{
    "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}"
}
{
    "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": "m1.medium",
                    "name": "test-trove-db",
                    "size": 30,
                    "users": [
                        {
                            "databases": [
                                "testdbonetwo"
                            ],
                            "name": "testuser",
                            "password": "testpass123"
                        }
                    ]
                },
                "type": "OS::Trove::Instance"
            }
        }
    }
}
GET
/v1/​{tenant_id}​/stacks
List stack data

Lists active stacks.

 
Normal response codes
200
Error response codes
400, 401, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

id (Optional) query String

Filters the stack list by a specified stack ID. Use this filter multiple times to filter by multiple IDs.

status (Optional) query String

Filters the stack list by a specified status. Use this filter multiple times to filter by multiple statuses.

name (Optional) query String

Filters the stack list by a specified name. Use this filter multiple times to filter by multiple names.

action (Optional) query String

Filters the stack list by a specified action. Use this filter multiple times to filter by multiple actions.

tenant (Optional) query String

Filters the stack list by a specified tenant. Use this filter multiple times to filter by multiple tenants.

username (Optional) query String

Filters the stack list by a specified user name. Use this filter multiple times to filter by multiple user names.

owner_id (Optional) query String

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 (Optional) query xsd:int

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 (Optional) query xsd:string

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 (Optional) query String

Specifies whether to include deleted stacks in the list. Default is False, which excludes deleted stacks from the list.

show_nested (Optional) query String

Specifies whether to include nested stacks in the list. Default is False, which excludes nested stacks from the list.

sort_keys (Optional) query String

Sorts the stack list by name, status, created_at, or updated_at key.

tags (Optional) query String

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 (Optional) query String

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 (Optional) query String

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 (Optional) query String

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 (Optional) query String

The sort direction of the list. A valid value is asc (ascending) or desc (descending).

global_tenant (Optional) query String

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 (Optional) query String

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.

{
    "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": ""
        }
    ]
}
POST
/v1/​{tenant_id}​/stacks/preview
Preview stack

Previews a stack.

 
Normal response codes
200
Error response codes
400, 401, 409, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name plain String

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 (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

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
}
Response parameters
Parameter Style Type Description
parent plain String

The stack ID of the parent stack, if this is a nested stack.

id plain String

The stack ID.

stack_name plain String

The name of the stack.

description plain String

A description of the stack.

template_description plain String

A description of the template that defines the stack.

timeout_mins plain String

Time-lines for stack creation.

disable_rollback plain String

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 plain String

List of stack capabilities for stack.

notification_topics plain String

List of notification topics for stack.

updated_time plain String

Time of last stack update in the following format: YYYY-MM-DDThh:mm:ssTZD, where TZD is the time zone designator.

stack_owner plain String

Stack owner name.

parameters plain String

List of parameters defined for the stack.

resources plain String

List of stack resources.

{
    "files": {},
    "disable_rollback": true,
    "parameters": {
        "flavor": "m1.heat"
    },
    "stack_name": "teststack",
    "template": {
        "heat_template_version": "2013-05-23",
        "description": "Simple template to test heat commands",
        "parameters": {
            "flavor": {
                "default": "m1.tiny",
                "type": "string"
            }
        },
        "resources": {
            "hello_world": {
                "type": "OS::Nova::Server",
                "properties": {
                    "key_name": "heat_key",
                    "flavor": {
                        "get_param": "flavor"
                    },
                    "image": "40be8d1a-3eb9-40de-8abd-43237517384f",
                    "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
                }
            }
        }
    },
    "timeout_mins": 60
}
{
    "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": "m1.small",
            "image": "F20-cfg",
            "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": "m1.small",
                    "flavor_update_policy": "RESIZE",
                    "image": "F20-cfg",
                    "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
    }
}
POST
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/preview
Preview stack update

Preview an update for a specified stack

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

template_url (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

A JSON environment for the stack.

files (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

The timeout for stack creation in minutes.

{
    "template": {
        "heat_template_version": "2013-05-23",
        "description": "Create a simple stack",
        "parameters": {
            "flavor": {
                "default": "m1.tiny",
                "type": "string"
            }
        },
        "resources": {
            "hello_world": {
                "type": "OS::Nova::Server",
                "properties": {
                    "key_name": "heat_key",
                    "flavor": {
                        "get_param": "flavor"
                    },
                    "image": "40be8d1a-3eb9-40de-8abd-43237517384f",
                    "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
                }
            }
        }
    },
    "parameters": {
        "flavor": "m1.small"
    }
}
{
    "unchanged": [
        {
            "updated_time": "datetime",
            "resource_name": "",
            "physical_resource_id": "{resource id or ''}",
            "resource_action": "CREATE",
            "resource_status": "COMPLETE",
            "resource_status_reason": "",
            "resource_type": "restype",
            "stack_identity": "{stack_id}",
            "stack_name": "{stack_name}"
        }
    ],
    "updated": [
        {
            "updated_time": "datetime",
            "resource_name": "",
            "physical_resource_id": "{resource id or ''}",
            "resource_action": "CREATE",
            "resource_status": "COMPLETE",
            "resource_status_reason": "",
            "resource_type": "restype",
            "stack_identity": "{stack_id}",
            "stack_name": "{stack_name}"
        }
    ],
    "replaced": [
        {
            "updated_time": "datetime",
            "resource_name": "",
            "physical_resource_id": "{resource id or ''}",
            "resource_action": "CREATE",
            "resource_status": "COMPLETE",
            "resource_status_reason": "",
            "resource_type": "restype",
            "stack_identity": "{stack_id}",
            "stack_name": "{stack_name}"
        }
    ],
    "added": [
        {
            "updated_time": "datetime",
            "resource_name": "",
            "physical_resource_id": "{resource id or ''}",
            "resource_action": "CREATE",
            "resource_status": "COMPLETE",
            "resource_status_reason": "",
            "resource_type": "restype",
            "stack_identity": "{stack_id}",
            "stack_name": "{stack_name}"
        }
    ],
    "deleted": [
        {
            "updated_time": "datetime",
            "resource_name": "",
            "physical_resource_id": "{resource id or ''}",
            "resource_action": "CREATE",
            "resource_status": "COMPLETE",
            "resource_status_reason": "",
            "resource_type": "restype",
            "stack_identity": "{stack_id}",
            "stack_name": "{stack_name}"
        }
    ]
}
GET
/v1/​{tenant_id}​/stacks/​{stack_name}​
Find stack

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.

Normal response codes
302
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

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

This operation does not accept a request body and does not return a response body.

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/resources
Find stack resources

Finds the canonical URL for the resource list of a specified stack.

 

The canonical URL is returned for only non-deleted stacks. To fetch the resource list for deleted stacks, use the following endpoint:

/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources
Normal response codes
302
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

This operation does not accept a request body and does not return a response body.

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​
Show stack details

Shows details for a specified stack.

 
Normal response codes
200
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

{
    "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::project_id": "3ab5b02f-a01f-4f95-afa1-e254afc4a435",
            "OS::stack_id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
            "OS::stack_name": "simple_stack"
        },
        "stack_name": "simple_stack",
        "stack_owner": "simple_username",
        "stack_status": "CREATE_COMPLETE",
        "stack_status_reason": "Stack CREATE completed successfully",
        "template_description": "sample stack",
        "stack_user_project_id": "65728b74-cfe7-4f17-9c15-11d4f686e591",
        "timeout_mins": "",
        "updated_time": "",
        "parent": "",
        "tags": ""
    }
}

This operation does not accept a request body.

PUT
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​
Update stack

Updates a specified stack.

 
Normal response codes
202
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

template_url (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

A JSON environment for the stack.

files (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

The timeout for stack creation in minutes.

{
    "template": {
        "heat_template_version": "2013-05-23",
        "description": "Create a simple stack",
        "parameters": {
            "flavor": {
                "default": "m1.tiny",
                "type": "string"
            }
        },
        "resources": {
            "hello_world": {
                "type": "OS::Nova::Server",
                "properties": {
                    "key_name": "heat_key",
                    "flavor": {
                        "get_param": "flavor"
                    },
                    "image": "40be8d1a-3eb9-40de-8abd-43237517384f",
                    "user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
                }
            }
        }
    },
    "parameters": {
        "flavor": "m1.small"
    }
}

This operation does not return a response body.

DELETE
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​
Delete stack

Deletes a specified stack and any snapshots of that stack.

 
Normal response codes
204
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

This operation does not accept a request body and does not return a response body.

DELETE
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/abandon
Abandon stack

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

 
Normal response codes
200
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

{
    "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": "fedora-amd64",
                "type": "string"
            },
            "flavor": {
                "default": "m1.small",
                "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": {}
        }
    }
}

This operation does not accept a request body.

POST
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/snapshots
Snapshot stack

Takes a snapshot of all the resources in the stack. All snapshots are deleted upon deletion of the stack.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

name plain String

The name of the snapshot.

{
    "name": "vol_snapshot"
}
{
    "id": "13c3a4b5-0585-440e-85a4-6f96b20e7a78",
    "name": "vol_snapshot",
    "status": "IN_PROGRESS",
    "status_reason": null,
    "data": null,
    "creation_time": "2015-09-01T20:57:55Z"
}
GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/snapshots
List snapshots

Lists the stack snapshots.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

{
    "snapshots": [
        {
            "id": "7c4e1ef4-bf1b-41ab-a0c8-ce01f4ffdfa1",
            "name": "vol_snapshot",
            "status": "IN_PROGRESS",
            "status_reason": null,
            "creation_time": "2015-08-04T20:57:55Z",
            "data": null
        }
    ]
}

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/snapshots/​{snapshot_id}​
Show snapshot

Shows details for a specified snapshot.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

snapshot_id URI String

The snapshot ID.

{
    "snapshot": {
        "id": "7c4e1ef4-bf1b-41ab-a0c8-ce01f4ffdfa1",
        "name": "vol_snapshot",
        "status": "COMPLETE",
        "status_reason": "Stack SNAPSHOT completed successfully",
        "creation_time": "2015-08-04T20:57:55Z",
        "data": {
            "status": "COMPLETE",
            "name": "stack_vol1",
            "stack_user_project_id": "fffa11067b1c48129ddfb78fba2bf09f",
            "environment": {
                "parameters": {},
                "resource_registry": {
                    "resources": {}
                }
            },
            "template": {
                "heat_template_version": "2013-05-23",
                "resources": {
                    "volume": {
                        "type": "OS::Cinder::Volume",
                        "properties": {
                            "size": 1
                        }
                    }
                }
            },
            "action": "SNAPSHOT",
            "project_id": "ecdb08032cd042179692a1b148f6565e",
            "id": "656452c2-e151-40da-8704-c844e69b485c",
            "resources": {
                "volume": {
                    "status": "COMPLETE",
                    "name": "volume",
                    "resource_data": {
                        "backup_id": "99108cf8-398f-461b-a043-bdceb7c9f572"
                    },
                    "resource_id": "3ab8cf79-807b-4c40-b743-0655f91e072f",
                    "action": "SNAPSHOT",
                    "type": "OS::Cinder::Volume",
                    "metadata": {}
                }
            }
        }
    }
}

This operation does not accept a request body.

DELETE
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/snapshots/​{snapshot_id}​
Delete snapshot

Deletes a stack snapshot.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

snapshot_id URI String

The snapshot ID.

This operation does not accept a request body and does not return a response body.

POST
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/snapshots/​{snapshot_id}​/restore
Restore snapshot

Restores a stack snapshot. You can restore only active stacks from a snapshot. Deleted stacks must be recreated.

 
Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

snapshot_id URI String

The snapshot ID.

This operation does not accept a request body and does not return a response body.

Stack actions

Performs non-lifecycle operations on the stack. Specify the action in the request body.

POST
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/actions
Suspend stack

Suspends a stack.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

suspend plain String

Specify the suspend action in the request body.

{
    "suspend": null
}

This operation does not return a response body.

POST
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/actions
Resume stack

Resumes a suspended stack.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

resume plain String

Specify the resume action in the request body.

{
    "resume": null
}

This operation does not return a response body.

POST
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/actions
Cancel stack update

Cancels a currently running update of a stack.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

cancel_update plain String

Specify the cancel_update action in the request body.

{
    "cancel_update": null
}

This operation does not return a response body.

POST
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/actions
Check stack resources

Checks whether the resources are in expected states for the specified stack.

 
Normal response codes
201
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

check plain String

Specify the check action in the request body.

{
    "check": null
}

This operation does not return a response body.

Stack resources

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/resources
List resources

Lists resources in a stack.

 
Normal response codes
200
Error response codes
400, 401, 404
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

nested_depth (Optional) query String

Includes resources from nested stacks up to the nested_depth levels of recursion.

with_detail (Optional) query String

Enables detailed resource information for each resource in list of resources.

{
    "resources": [
        {
            "creation_time": "2015-06-25T14:59:53",
            "links": [
                {
                    "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c/resources/random_key_name",
                    "rel": "self"
                },
                {
                    "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c",
                    "rel": "stack"
                }
            ],
            "logical_resource_id": "random_key_name",
            "physical_resource_id": "mystack-random_key_name-pmjmy5pks735",
            "required_by": [],
            "resource_name": "random_key_name",
            "resource_status": "CREATE_COMPLETE",
            "resource_status_reason": "state changed",
            "resource_type": "OS::Heat::RandomString",
            "updated_time": "2015-06-25T14:59:53"
        }
    ]
}
GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/resources/​{resource_name}​
Show resource data

Shows data for a specified resource.

 
Normal response codes
200
Error response codes
400, 401, 404
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

resource_name URI String

The name of a resource in the stack.

{
    "resource": {
        "attributes": {
            "value": "I9S20uIp"
        },
        "creation_time": "2015-06-25T14:59:53",
        "description": "",
        "links": [
            {
                "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c/resources/random_key_name",
                "rel": "self"
            },
            {
                "href": "http://hostname/v1/1234/stacks/mystack/629a32d0-ac4f-4f63-b58d-f0d047b1ba4c",
                "rel": "stack"
            }
        ],
        "logical_resource_id": "random_key_name",
        "physical_resource_id": "mystack-random_key_name-pmjmy5pks735",
        "required_by": [],
        "resource_name": "random_key_name",
        "resource_status": "CREATE_COMPLETE",
        "resource_status_reason": "state changed",
        "resource_type": "OS::Heat::RandomString",
        "updated_time": "2015-06-25T14:59:53"
    }
}

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/resources/​{resource_name}​/metadata
Show resource metadata

Shows metadata for a specified resource.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

resource_name URI String

The name of a resource in the stack.

{
    "metadata": {
        "some_key": "some_value",
        "some_other_key": "some_other_value"
    }
}

This operation does not accept a request body.

POST
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/resources/​{resource_name}​/signal
Send a signal to a resource

Sends a signal to a specified resource.

 

The contents of the request body depends on the resource to which you send a signal.

Some resources cannot receive signals. If you send them a signal, they return a 400 error code.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

resource_name URI String

The name of a resource in the stack.

This operation does not accept a request body and does not return a response body.

Stack events

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/events
Find stack events

Finds the canonical URL for the event list of a specified stack.

 
Normal response codes
302
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

This operation does not accept a request body and does not return a response body.

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/events
List stack events

Lists events for a specified stack.

 
Normal response codes
200
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

resource_action (Optional) query String

Filters the event list by a specified resource action. You can use this filter multiple times to filter by multiple resource actions. Valid resource actions are ADOPT, CHECK, CREATE, DELETE, INIT, RESTORE, RESUME, ROLLBACK, SNAPSHOT, SUSPEND, and UPDATE.

resource_status (Optional) query String

Filters the event list by a specified resource status. You can use this filter multiple times to filter by multiple resource statuses. Valid resource statuses are COMPLETE, FAILED, and IN_PROGRESS.

resource_name (Optional) query String

Filters the event list by a specified resource name. You can use this filter multiple times to filter by multiple resource names.

resource_type (Optional) query String

Filters the event list by a specified resource type. You can use this filter multiple times to filter by multiple resource types. Valid resource types include OS::Cinder::Volume, OS::Nova::Server, OS::Neutron::Port, and so on.

limit (Optional) query xsd:int

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 (Optional) query xsd:string

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.

sort_keys (Optional) query String

Sorts the list by the resource_type or created_at key.

sort_dir (Optional) query String

The sort direction of the list. A valid value is asc (ascending) or desc (descending).

{
    "events": [
        {
            "resource_name": "port",
            "event_time": "2014-07-23T08:14:47Z",
            "links": [{
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/474bfdf0-a450-46ec-a78a-0c7faa404073",
                "rel": "self"
            },
            {
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port",
                "rel": "resource"
            },
            {
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5",
                "rel": "stack"
            }],
            "logical_resource_id": "port",
            "resource_status": "CREATE_FAILED",
            "resource_status_reason": "NotFound: Subnet f8a699d0-3537-429e-87a5-6b5a8d0c2bf0 could not be found",
            "physical_resource_id": null,
            "id": "474bfdf0-a450-46ec-a78a-0c7faa404073"
        },
        {
            "resource_name": "port",
            "event_time": "2014-07-23T08:14:47Z",
            "links": [{
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/66fa95b6-e6f8-4f05-b1af-e828f5aba04c",
                "rel": "self"
            },
            {
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port",
                "rel": "resource"
            },
            {
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5",
                "rel": "stack"
            }],
            "logical_resource_id": "port",
            "resource_status": "CREATE_IN_PROGRESS",
            "resource_status_reason": "state changed",
            "physical_resource_id": null,
            "id": "66fa95b6-e6f8-4f05-b1af-e828f5aba04c"
        }
    ]
}
GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/resources/​{resource_name}​/events
List resource events

Lists events for a specified stack resource.

 
Normal response codes
200
Error response codes
400, 401, 404
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

resource_name URI String

The name of a resource in the stack.

resource_action (Optional) query String

Filters the event list by a specified resource action. You can use this filter multiple times to filter by multiple resource actions. Valid resource actions are ADOPT, CHECK, CREATE, DELETE, INIT, RESTORE, RESUME, ROLLBACK, SNAPSHOT, SUSPEND, and UPDATE.

resource_status (Optional) query String

Filters the event list by a specified resource status. You can use this filter multiple times to filter by multiple resource statuses. Valid resource statuses are COMPLETE, FAILED, and IN_PROGRESS.

resource_name (Optional) query String

Filters the event list by a specified resource name. You can use this filter multiple times to filter by multiple resource names.

resource_type (Optional) query String

Filters the event list by a specified resource type. You can use this filter multiple times to filter by multiple resource types. Valid resource types include OS::Cinder::Volume, OS::Nova::Server, OS::Neutron::Port, and so on.

limit (Optional) query xsd:int

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 (Optional) query xsd:string

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.

sort_keys (Optional) query String

Sorts the list by the resource_type or created_at key.

sort_dir (Optional) query String

The sort direction of the list. A valid value is asc (ascending) or desc (descending).

{
    "events": [
        {
            "resource_name": "port",
            "event_time": "2014-07-23T08:14:47Z",
            "links": [{
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/474bfdf0-a450-46ec-a78a-0c7faa404073",
                "rel": "self"
            },
            {
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port",
                "rel": "resource"
            },
            {
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5",
                "rel": "stack"
            }],
            "logical_resource_id": "port",
            "resource_status": "CREATE_FAILED",
            "resource_status_reason": "NotFound: Subnet f8a699d0-3537-429e-87a5-6b5a8d0c2bf0 could not be found",
            "physical_resource_id": null,
            "id": "474bfdf0-a450-46ec-a78a-0c7faa404073"
        },
        {
            "resource_name": "port",
            "event_time": "2014-07-23T08:14:47Z",
            "links": [{
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port/events/66fa95b6-e6f8-4f05-b1af-e828f5aba04c",
                "rel": "self"
            },
            {
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5/resources/port",
                "rel": "resource"
            },
            {
                "href": "http://192.168.123.200:8004/v1/dc4b074874244f7693dd65583733a758/stacks/aws_port/db467ed1-50b5-4a3e-aeb1-396ff1d151c5",
                "rel": "stack"
            }],
            "logical_resource_id": "port",
            "resource_status": "CREATE_IN_PROGRESS",
            "resource_status_reason": "state changed",
            "physical_resource_id": null,
            "id": "66fa95b6-e6f8-4f05-b1af-e828f5aba04c"
        }
    ]
}
GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/resources/​{resource_name}​/events/​{event_id}​
Show event details

Shows details for a specified event.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

resource_name URI String

The name of a resource in the stack.

event_id URI String

The ID of an event related to the resource in the stack.

This operation does not accept a request body.

Templates

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/template
Get stack template

Gets a template for a specified stack.

 
Normal response codes
200
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

stack_name URI String

The name of a stack.

stack_id URI String

The stack ID.

{
    "description": "Hello world HOT template that just defines a single server. Contains just base features to verify base HOT support.\n",
    "heat_template_version": "2013-05-23",
    "outputs": {
        "foo": {
            "description": "Show foo parameter value",
            "value": {
                "get_param": "foo"
            }
        }
    },
    "parameters": {
        "foo": {
            "default": "secret",
            "description": "Name of an existing key pair to use for the server",
            "hidden": true,
            "type": "string"
        }
    },
    "resources": {
        "random_key_name": {
            "properties": {
                "length": 8
            },
            "type": "OS::Heat::RandomString"
        }
    }
}

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/template_versions
List template versions

Lists all available template versions.

 
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

This operation does not accept a request body and does not return a response body.

POST
/v1/​{tenant_id}​/validate
Validate template

Validates a specified template.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

template_url (Optional) plain String

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 (Optional) plain String

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 (Optional) plain String

A JSON environment for the stack.

Response parameters
Parameter Style Type Description
Description plain String

The description specified in the template.

Parameters plain object

An object that defines all input parameters that are defined in the template. Indexed by parameter name.

ParameterGroups (Optional) plain list

A list of parameter groups. Each group contains a list of parameter names.

{
    "template_url": "/PATH_TO_HEAT_TEMPLATES/WordPress_Single_Instance.template"
}
{
    "Description": "A template that provides a single server instance.",
    "Parameters": {
        "server-size": {
            "default": "1GB Standard Instance",
            "description": "Server size",
            "type": "String",
            "constraints": [
                {
                    "allowed_values": [
                        "512MB Standard Instance",
                        "1GB Standard Instance",
                        "4GB Standard Instance",
                        "8GB Standard Instance"
                    ],
                    "description": "Must be a valid server size."
                }
            ]
        },
        "key_name": {
            "description": "Keypair name for SSH access to the server",
            "required": true,
            "type": "String"
        },
        "server_name": {
            "default": "My server",
            "description": "My server",
            "type": "String"
        }
    },
    "ParameterGroups": [
        {
            "label": "Parameter groups",
            "description": "My parameter groups",
            "parameters": [
                "param_name-1",
                "param_name-2"
            ]
        }
    ]
}
GET
/v1/​{tenant_id}​/resource_types/​{type_name}​/template
Show resource template

Shows the template representation for a specified resource type.

 

The returned template contains a single resource of the specified type. Each resource property is mapped to a template parameter and each resource attribute is mapped to a template output.

You can use these templates as a starting place for creating customized, template-based resources or as examples of using the particular resource in another template.

Use the template_type query parameter to specify the resource template type. Default type is cfn. The hot template type is supported. For example:

/v1/{tenant_id}/resource_types/{type_name}/template?template_type=cfn
Normal response codes
200
Error response codes
400, 401, 404
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

type_name URI String

The name of a resource type.

template_type (Optional) query String

The resource template type. Default type is cfn. The hot template type is supported.

{
    "HeatTemplateFormatVersion": "2012-12-12",
    "Outputs": {
        "private_key": {
            "Description": "The private key if it has been saved.",
            "Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"private_key\"]}"
        },
        "public_key": {
            "Description": "The public key.",
            "Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"public_key\"]}"
        }
    },
    "Parameters": {
        "name": {
            "Description": "The name of the key pair.",
            "Type": "String"
        },
        "public_key": {
            "Description": "The optional public key. This allows users to supply the public key from a pre-existing key pair. If not supplied, a new key pair will be generated.",
            "Type": "String"
        },
        "save_private_key": {
            "AllowedValues": [
                "True",
                "true",
                "False",
                "false"
            ],
            "Default": false,
            "Description": "True if the system should remember a generated private key; False otherwise.",
            "Type": "String"
        }
    },
    "Resources": {
        "KeyPair": {
            "Properties": {
                "name": {
                    "Ref": "name"
                },
                "public_key": {
                    "Ref": "public_key"
                },
                "save_private_key": {
                    "Ref": "save_private_key"
                }
            },
            "Type": "OS::Nova::KeyPair"
        }
    }
}

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/resource_types/​{type_name}​
Show resource schema

Shows the interface schema for a specified resource type. This schema describes the properties that can be set on the resource, their types, constraints, descriptions, and default values. Additionally, the resource attributes and their descriptions are provided.

 
Normal response codes
200
Error response codes
400, 401
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

type_name URI String

The name of a resource type.

{
    "attributes": {
        "an_attribute": {
            "description": "A runtime value of the resource."
        }
    },
    "properties": {
        "a_property": {
            "constraints": [
                {
                    "description": "Must be between 1 and 255 characters",
                    "length": {
                        "max": 255,
                        "min": 1
                    }
                }
            ],
            "description": "A resource description.",
            "required": true,
            "type": "string",
            "update_allowed": false
        }
    },
    "resource_type": "OS::Heat::AResourceName",
    "support_status": {
        "message": "A status message",
        "status": "SUPPORTED",
        "version": "2014.1"
    }
}

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/resource_types
List resource types

Lists the supported template resource types.

 
Normal response codes
200
Error response codes
400, 401
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

{
    "resource_types": [
        "AWS::EC2::Instance",
        "OS::Heat::ScalingPolicy",
        "AWS::CloudFormation::Stack",
        "OS::Keystone::Group",
        "OS::Glance::Image",
        "AWS::EC2::Volume",
        "OS::Heat::SoftwareDeployment",
        "AWS::AutoScaling::ScalingPolicy",
        "AWS::EC2::InternetGateway",
        "OS::Heat::SoftwareDeployments",
        "AWS::EC2::VolumeAttachment",
        "AWS::CloudFormation::WaitConditionHandle",
        "OS::Cinder::VolumeAttachment",
        "OS::Cinder::EncryptedVolumeType",
        "OS::Heat::AutoScalingGroup",
        "OS::Nova::FloatingIP",
        "OS::Heat::HARestarter",
        "OS::Keystone::Project",
        "OS::Keystone::Endpoint",
        "OS::Heat::InstanceGroup",
        "AWS::CloudWatch::Alarm",
        "AWS::AutoScaling::AutoScalingGroup",
        "OS::Heat::CloudConfig",
        "OS::Heat::SoftwareComponent",
        "OS::Cinder::Volume",
        "OS::Keystone::Service",
        "OS::Heat::WaitConditionHandle",
        "OS::Heat::SoftwareConfig",
        "AWS::CloudFormation::WaitCondition",
        "OS::Heat::StructuredDeploymentGroup",
        "OS::Heat::RandomString",
        "OS::Heat::SoftwareDeploymentGroup",
        "OS::Nova::KeyPair",
        "OS::Heat::MultipartMime",
        "OS::Heat::UpdateWaitConditionHandle",
        "OS::Nova::Server",
        "AWS::IAM::AccessKey",
        "AWS::EC2::SecurityGroup",
        "AWS::EC2::EIPAssociation",
        "AWS::EC2::EIP",
        "OS::Heat::AccessPolicy",
        "AWS::IAM::User",
        "OS::Heat::WaitCondition",
        "OS::Heat::StructuredDeployment",
        "AWS::RDS::DBInstance",
        "AWS::AutoScaling::LaunchConfiguration",
        "OS::Heat::Stack",
        "OS::Nova::FloatingIPAssociation",
        "OS::Heat::ResourceGroup",
        "OS::Heat::StructuredConfig",
        "OS::Nova::ServerGroup",
        "OS::Heat::StructuredDeployments",
        "OS::Keystone::Role",
        "OS::Keystone::User",
        "AWS::ElasticLoadBalancing::LoadBalancer",
        "OS::Nova::Flavor",
        "OS::Cinder::VolumeType"
    ]
}

This operation does not accept a request body.

Build info

GET
/v1/​{tenant_id}​/build_info
Show build information

Shows build information for an Orchestration deployment.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

{
    "api": {
        "revision": "{api_build_revision}"
    },
    "engine": {
        "revision": "{engine_build_revision}"
    }
}

This operation does not accept a request body.

Software configuration

POST
/v1/​{tenant_id}​/software_configs
Create configuration

Creates a software configuration.

 
Normal response codes
200
Error response codes
400, 401, 404
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

config (Optional) plain String

Configuration script or manifest that defines which configuration is performed.

group (Optional) plain String

Namespace that groups this software configuration by when it is delivered to a server. This setting might simply define which configuration tool performs the configuration.

name (Optional) plain String

The name of the configuration to create.

inputs (Optional) plain String

Schema that represents the inputs that this software configuration expects.

outputs (Optional) plain String

Schema that represents the outputs that this software configuration produces.

options (Optional) plain String

Map that contains options that are specific to the configuration management tool that this resource uses.

{
    "inputs": [
        {
            "default": null,
            "type": "String",
            "name": "foo",
            "description": null
        },
        {
            "default": null,
            "type": "String",
            "name": "bar",
            "description": null
        }
    ],
    "group": "script",
    "name": "a-config-we5zpvyu7b5o",
    "outputs": [
        {
            "type": "String",
            "name": "result",
            "error_output": false,
            "description": null
        }
    ],
    "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
    "options": null
}
{
    "software_config": {
        "creation_time": "2015-01-31T15:12:36Z",
        "inputs": [
            {
                "default": null,
                "type": "String",
                "name": "foo",
                "description": null
            },
            {
                "default": null,
                "type": "String",
                "name": "bar",
                "description": null
            }
        ],
        "group": "script",
        "name": "a-config-we5zpvyu7b5o",
        "outputs": [
            {
                "type": "String",
                "name": "result",
                "error_output": false,
                "description": null
            }
        ],
        "options": null,
        "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
        "id": "ddee7aca-aa32-4335-8265-d436b20db4f1"
    }
}
GET
/v1/​{tenant_id}​/software_configs/​{config_id}​
Show configuration details

Shows details for a software configuration.

 
Normal response codes
200
Error response codes
400, 401, 404
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

config_id URI String

The configuration ID.

{
    "software_config": {
        "inputs": [
            {
                "default": null,
                "type": "String",
                "name": "foo",
                "description": null
            },
            {
                "default": null,
                "type": "String",
                "name": "bar",
                "description": null
            }
        ],
        "group": "script",
        "name": "a-config-we5zpvyu7b5o",
        "outputs": [
            {
                "type": "String",
                "name": "result",
                "error_output": false,
                "description": null
            }
        ],
        "creation_time": "2015-01-31T15:12:36Z",
        "id": "ddee7aca-aa32-4335-8265-d436b20db4f1",
        "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
        "options": null
    }
}

This operation does not accept a request body.

DELETE
/v1/​{tenant_id}​/software_configs/​{config_id}​
Delete config

Deletes a software configuration.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

config_id URI String

The configuration ID.

This operation does not accept a request body and does not return a response body.

GET
/v1/​{tenant_id}​/software_deployments
List deployments

Lists all available software deployments.

 
Normal response codes
200
Error response codes
400, 401, 404, 500
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

{
    "software_deployments": [
        {
            "status": "COMPLETE",
            "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
            "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd",
            "output_values": {
                "deploy_stdout": "Writing to /tmp/barmy\nWritten to /tmp/barmy\n",
                "deploy_stderr": "+ echo Writing to /tmp/barmy\n+ echo fu\n+ cat /tmp/barmy\n+ echo -n The file /tmp/barmy contains fu for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/barmy\n+ echo Output to stderr\nOutput to stderr\n",
                "deploy_status_code": 0,
                "result": "The file /tmp/barmy contains fu for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE"
            },
            "input_values": null,
            "action": "CREATE",
            "status_reason": "Outputs received",
            "id": "ef422fa5-719a-419e-a10c-72e3a367b0b8",
            "creation_time": "2015-01-31T15:12:36Z",
            "updated_time": "2015-01-31T15:18:21Z"
        }
    ]
}

This operation does not accept a request body.

POST
/v1/​{tenant_id}​/software_deployments
Create deployment

Creates a software deployment.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

config_id plain String

The ID of the software configuration resource that runs when applying to the server.

server_id plain String

The ID of the compute server to which the configuration applies.

action plain String

The current stack action that triggers this deployment resource.

stack_user_project_id (Optional) plain String

Authentication project ID, which can also perform operations on this deployment.

status (Optional) plain String

Current status of the deployment. A valid value is COMPLETE, IN_PROGRESS, or FAILED.

status_reason (Optional) plain String

Error description for the last status change, which is FAILED status.

{
    "status": "IN_PROGRESS",
    "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
    "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd",
    "stack_user_project_id": "c024bfada67845ddb17d2b0c0be8cd79",
    "action": "CREATE",
    "status_reason": "Deploy data available"
}
{
    "software_deployment": {
        "status": "IN_PROGRESS",
        "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
        "config_id": "8da95794-2ad9-4979-8ae5-739ce314c5cd",
        "output_values": null,
        "input_values": null,
        "action": "CREATE",
        "status_reason": "Deploy data available",
        "id": "ef422fa5-719a-419e-a10c-72e3a367b0b8",
        "creation_time": "2015-01-31T15:12:36Z",
        "updated_time": "2015-01-31T15:18:21Z"
    }
}
GET
/v1/​{tenant_id}​/software_deployments/metadata/​{server_id}​
Show server configuration metadata

Shows the deployment configuration metadata for a specified server.

 

Use the group property to specify the configuration hook to which the pass the metadata item.

Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

server_id URI String

The ID of the server for which to fetch configuration metadata.

{
    "metadata": [
        {
            "inputs": [
                {
                    "default": null,
                    "type": "String",
                    "name": "foo",
                    "value": "fooooo",
                    "description": null
                },
                {
                    "default": null,
                    "type": "String",
                    "name": "bar",
                    "value": "baaaaa",
                    "description": null
                },
                {
                    "type": "String",
                    "name": "deploy_server_id",
                    "value": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
                    "description": "ID of the server being deployed to"
                },
                {
                    "type": "String",
                    "name": "deploy_action",
                    "value": "CREATE",
                    "description": "Name of the current action being deployed"
                },
                {
                    "type": "String",
                    "name": "deploy_stack_id",
                    "value": "a/9bd57090-8954-48ab-bab9-adf9e1ac70fc",
                    "description": "ID of the stack this deployment belongs to"
                },
                {
                    "type": "String",
                    "name": "deploy_resource_name",
                    "value": "deployment",
                    "description": "Name of this deployment resource in the stack"
                },
                {
                    "type": "String",
                    "name": "deploy_signal_id",
                    "value": "http://192.168.20.103:8000/v1/signal/arn%3Aopenstack%3Aheat%3A%3Ae2a84fbdaeb047ae8da4b503f3b69f1f%3Astacks%2Fa%2F9bd57090-8954-48ab-bab9-adf9e1ac70fc%2Fresources%2Fdeployment?Timestamp=2014-03-19T20%3A30%3A59Z&SignatureMethod=HmacSHA256&AWSAccessKeyId=ca3571413e4a49998d580215517b3685&SignatureVersion=2&Signature=w6Iu%2BNbg86mqwSOUf1GLuKPO7KaD82PiGpL4ig9Q1l4%3D",
                    "description": "ID of signal to use for signalling output values"
                }
            ],
            "group": "script",
            "name": "a-config-we5zpvyu7b5o",
            "outputs": [
                {
                    "type": "String",
                    "name": "result",
                    "error_output": false,
                    "description": null
                }
            ],
            "options": null,
            "creation_time": "2015-01-31T15:12:36Z",
            "updated_time": "2015-01-31T15:18:21Z",
            "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
            "id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434"
        },
        {
            "inputs": [
                {
                    "default": null,
                    "type": "String",
                    "name": "foo",
                    "value": "fu",
                    "description": null
                },
                {
                    "default": null,
                    "type": "String",
                    "name": "bar",
                    "value": "barmy",
                    "description": null
                },
                {
                    "type": "String",
                    "name": "deploy_server_id",
                    "value": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
                    "description": "ID of the server being deployed to"
                },
                {
                    "type": "String",
                    "name": "deploy_action",
                    "value": "CREATE",
                    "description": "Name of the current action being deployed"
                },
                {
                    "type": "String",
                    "name": "deploy_stack_id",
                    "value": "a/9bd57090-8954-48ab-bab9-adf9e1ac70fc",
                    "description": "ID of the stack this deployment belongs to"
                },
                {
                    "type": "String",
                    "name": "deploy_resource_name",
                    "value": "other_deployment",
                    "description": "Name of this deployment resource in the stack"
                },
                {
                    "type": "String",
                    "name": "deploy_signal_id",
                    "value": "http://192.168.20.103:8000/v1/signal/arn%3Aopenstack%3Aheat%3A%3Ae2a84fbdaeb047ae8da4b503f3b69f1f%3Astacks%2Fa%2F9bd57090-8954-48ab-bab9-adf9e1ac70fc%2Fresources%2Fother_deployment?Timestamp=2014-03-19T20%3A30%3A59Z&SignatureMethod=HmacSHA256&AWSAccessKeyId=7b761482f8254946bcd3d5ccb36fe939&SignatureVersion=2&Signature=giMfv%2BhrAw6y%2FCMKQIQz2IhO5PkAj5%2BfP5YsL6rul3o%3D",
                    "description": "ID of signal to use for signalling output values"
                }
            ],
            "group": "script",
            "name": "a-config-we5zpvyu7b5o",
            "outputs": [
                {
                    "type": "String",
                    "name": "result",
                    "error_output": false,
                    "description": null
                }
            ],
            "options": null,
            "creation_time": "2015-01-31T16:14:13Z",
            "updated_time": "2015-01-31T16:18:19Z",
            "config": "#!/bin/sh -x\necho \"Writing to /tmp/$bar\"\necho $foo > /tmp/$bar\necho -n \"The file /tmp/$bar contains `cat /tmp/$bar` for server $deploy_server_id during $deploy_action\" > $heat_outputs_path.result\necho \"Written to /tmp/$bar\"\necho \"Output to stderr\" 1>&2",
            "id": "8da95794-2ad9-4979-8ae5-739ce314c5cd"
        }
    ]
}

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/software_deployments/​{deployment_id}​
Show deployment details

Shows details for a specified software deployment.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

deployment_id URI String

The deployment ID.

{
    "software_deployment": {
        "status": "IN_PROGRESS",
        "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
        "config_id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434",
        "output_values": null,
        "input_values": null,
        "action": "CREATE",
        "status_reason": "Deploy data available",
        "id": "06e87bcc-33a2-4bce-aebd-533e698282d3",
        "creation_time": "2015-01-31T15:12:36Z",
        "updated_time": "2015-01-31T15:18:21Z"
    }
}

This operation does not accept a request body.

PUT
/v1/​{tenant_id}​/software_deployments/​{deployment_id}​
Update deployment

Updates a specified software deployment.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

deployment_id URI String

The deployment ID.

config_id plain String

ID of the software configuration resource to run when applying to the server. This ID might not be the same configuration ID with which the deployment was created because ephemeral configurations are created throughout the life cycle of the deployment.

action plain String

Current stack action in which this deployment resource is being triggered.

status (Optional) plain String

Current status of the deployment. Value is IN_PROGRESS, COMPLETE, or FAILED.

status_reason (Optional) plain String

Error description for the last status change, which is FAILED status.

output_values (Optional) plain String

Map of output values for the deployment, as signaled from the server.

{
    "status": "COMPLETE",
    "output_values": {
        "deploy_stdout": "Writing to /tmp/baaaaa\nWritten to /tmp/baaaaa\n",
        "deploy_stderr": "+ echo Writing to /tmp/baaaaa\n+ echo fooooo\n+ cat /tmp/baaaaa\n+ echo -n The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/baaaaa\n+ echo Output to stderr\nOutput to stderr\n",
        "deploy_status_code": 0,
        "result": "The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE"
    },
    "status_reason": "Outputs received"
}
{
    "software_deployment": {
        "status": "COMPLETE",
        "server_id": "ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5",
        "config_id": "3d5ec2a8-7004-43b6-a7f6-542bdbe9d434",
        "output_values": {
            "deploy_stdout": "Writing to /tmp/baaaaa\nWritten to /tmp/baaaaa\n",
            "deploy_stderr": "+ echo Writing to /tmp/baaaaa\n+ echo fooooo\n+ cat /tmp/baaaaa\n+ echo -n The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE\n+ echo Written to /tmp/baaaaa\n+ echo Output to stderr\nOutput to stderr\n",
            "deploy_status_code": 0,
            "result": "The file /tmp/baaaaa contains fooooo for server ec14c864-096e-4e27-bb8a-2c2b4dc6f3f5 during CREATE"
        },
        "input_values": null,
        "action": "CREATE",
        "status_reason": "Outputs received",
        "id": "06e87bcc-33a2-4bce-aebd-533e698282d3",
        "creation_time": "2015-01-31T15:12:36Z",
        "updated_time": "2015-01-31T15:18:21Z"
    }
}
DELETE
/v1/​{tenant_id}​/software_deployments/​{deployment_id}​
Delete deployment

Deletes a specified software deployment.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

deployment_id URI String

The deployment ID.

This operation does not accept a request body and does not return a response body.

Manage service

GET
/v1/​{tenant_id}​/services
Show orchestration engine status

Enables administrative users to view details for all orchestration engines.

 

Orchestration engine details include engine_id, topic name, last updated time, health status, and host name.

Troubleshooting

  • A 503 error code indicates that the heat engines are not operational. Run the heat-manage service list command or contact your cloud provider to determine why the heat engines are not operational.

Normal response codes
200
Error response codes
503, 403
Request parameters
Parameter Style Type Description
tenant_id URI String

The ID of the tenant. A tenant is also known as an account or project.

{
    "services": [
        {
            "status": "up",
            "binary": "heat-engine",
            "report_interval": 60,
            "engine_id": "9d9242c3-4b9e-45e1-9e74-7615fbf20e5d",
            "created_at": "2015-02-03T05:55:59.000000",
            "hostname": "mrkanag",
            "updated_at": "2015-02-03T05:57:59.000000",
            "topic": "engine",
            "host": "engine-1",
            "deleted_at": null,
            "id": "e1908f44-42f9-483f-b778-bc814072c33d"
        },
        {
            "status": "down",
            "binary": "heat-engine",
            "report_interval": 60,
            "engine_id": "2d2434bf-adb6-4453-9c6b-b22fb8bd2306",
            "created_at": "2015-02-03T06:03:14.000000",
            "hostname": "mrkanag",
            "updated_at": "2015-02-03T06:09:55.000000",
            "topic": "engine",
            "host": "engine",
            "deleted_at": null,
            "id": "582b5657-6db7-48ad-8483-0096350faa21"
        }
    ]
}

This operation does not accept a request body.