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
badRequest (400), unauthorized (401), conflict (409), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name plain xsd: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 will not become available for reuse until the deletion completes successfully.

template_url (Optional) plain xsd:string

A URI to the location containing the stack template on which to perform the 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 plain xsd:dict

The stack template on which to perform the 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 xsd:dict

A JSON environment for the stack.

files (Optional) plain xsd:dict

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 template_url address. Instead, use the template parameter to supply the template content as part of the request.

parameters (Optional) plain xsd:dict

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 xsd: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.

timeout_mins (Optional) plain xsd:int

The timeout for stack creation in minutes.

disable_rollback (Optional) plain xsd:boolean

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.

Response parameters
Parameter Style Type Description
stack plain xsd:dict

The stack object.

id plain csapi:UUID

The UUID of the system-assigned stack.

links plain xsd:list

A list of URLs for the stack. Each URL is a JSON object with an href key indicating the URL and a rel key indicating its relationship to the stack in question. There may be multiple links returned. The self relationship identifies the URL of the stack itself.

{
    "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/teststack/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
badRequest (400), unauthorized (401), conflict (409), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name plain xsd: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 will not become available for reuse until the deletion completes successfully.

environment (Optional) plain xsd:dict

A JSON environment for the stack.

files (Optional) plain xsd:dict

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 template_url address. Instead, use the template parameter to supply the template content as part of the request.

parameters (Optional) plain xsd:dict

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 xsd:int

The timeout for stack creation in minutes.

adopt_stack_data plain xsd:dict

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

disable_rollback (Optional) plain xsd:boolean

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.

Response parameters
Parameter Style Type Description
stack plain xsd:dict

The stack object.

id plain csapi:UUID

The UUID of the system-assigned stack.

links plain xsd:list

A list of URLs for the stack. Each URL is a JSON object with an href key indicating the URL and a rel key indicating its relationship to the stack in question. There may be multiple links returned. The self relationship identifies the URL of the stack itself.

{
    "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": {
            "heat_template_version": "2013-05-23",
            "resources": {
                "MyServer": {
                    "type": "OS::Trove::Instance",
                    "properties": {
                        "flavor": "m1.small",
                        "size": 10
                    }
                }
            }
        }
    },
    "stack_name": "{stack_name}",
    "timeout_mins": "{timeout_mins}"
}
{
    "stack": {
        "id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
        "links": [
            {
                "href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/teststack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
                "rel": "self"
            }
        ]
    }
}
GET
/v1/​{tenant_id}​/stacks
List stack data

Lists active stacks.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

id (Optional) query csapi:UUID

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

status (Optional) query xsd:string

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

name (Optional) query xsd:string

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

action (Optional) query xsd:string

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

tenant (Optional) query xsd:string

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

username (Optional) query xsd:string

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

owner_id (Optional) query csapi:UUID

Filters the stack list by an 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 page size of items. Returns a number of items up to a 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

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 xsd:boolean

Set to true to include deleted stacks in the list. Default is false, which excludes deleted stacks from the list.

show_nested (Optional) query xsd:boolean

Set to true to include nested stacks in the list. Default is false, which excludes nested stacks from the list.

sort_keys (Optional) query xsd:string

Sorts the stack list by stack_name, stack_status, creation_time, or updated_time key.

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

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

global_tenant (Optional) query xsd:boolean

Set to true to include stacks from all tenants in the stack list. Specify policy requirements in the Orchestration policy.json file. Default is false.

with_count (Optional) query xsd:boolean

Set to true 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.

Response parameters
Parameter Style Type Description
creation_time plain xsd:dateTime

The date and time when the software was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2016-03-30T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

description plain xsd:string

The description of the active stack.

id plain csapi:UUID

The UUID of the active stack.

links plain xsd:list

A list of URLs for the stack. Each URL is a JSON object with an href key indicating the URL and a rel key indicating its relationship to the stack in question. There may be multiple links returned. The self relationship identifies the URL of the stack itself.

stack_name plain xsd:string

The name of the active stack.

stack_status plain xsd:string

The status of the active stack.

stack_status_reason plain xsd:string

The reason for the current status of the stack.

updated_time plain xsd:dateTime

The date and time when the stack resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2016-03-30T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

If the updated_at date and time stamp is not set, its value is null.

tags plain xsd:string

The stack tags.

{
    "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
badRequest (400), unauthorized (401), conflict (409), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name plain xsd: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 will not become available for reuse until the deletion completes successfully.

template_url (Optional) plain xsd:string

A URI to the location containing the stack template on which to perform the 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 plain xsd:dict

The stack template on which to perform the 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 xsd:dict

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 template_url address. Instead, use the template parameter to supply the template content as part of the request.

parameters (Optional) plain xsd:dict

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
stack plain xsd:dict

The stack object.

parent plain csapi:UUID

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

id plain csapi:UUID

The UUID of the system-assigned stack.

links plain xsd:list

A list of URLs for the stack. Each URL is a JSON object with an href key indicating the URL and a rel key indicating its relationship to the stack in question. There may be multiple links returned. The self relationship identifies the URL of the stack itself.

stack_name plain xsd:string

The name of the stack.

description plain xsd:string

A description of the stack.

template_description plain xsd:string

A description of the template that defines the stack.

timeout_mins plain xsd:int

Time-lines for stack creation.

disable_rollback plain xsd:boolean

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 xsd:list

List of stack capabilities for stack.

creation_time plain xsd:dateTime

The date and time when the software was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

notification_topics plain xsd:list

List of notification topics for stack.

updated_time plain xsd:dateTime

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

stack_owner plain xsd:string

Stack owner name.

parameters plain xsd:dict

List of parameters defined for the stack.

resources plain xsd:list

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
    }
}
PUT
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/preview
Preview stack update

Previews an update for a stack.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

template_url (Optional) plain xsd:string

A URI to the location containing the stack template on which to perform the 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 xsd:dict

The stack template on which to perform the 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 xsd:dict

A JSON environment for the stack.

files (Optional) plain xsd:dict

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 template_url address. Instead, use the template parameter to supply the template content as part of the request.

tags (Optional) plain xsd: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 xsd:dict

Supplies updated arguments for parameters that are 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 xsd:int

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 stack.

 

Also works with verbs other than GET, so that you can perform PUT and DELETE operations on a current stack. Set your client to follow redirects. 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 response code because this behavior is ubiquitous in web browsers.

Normal response codes
302
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd: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 a resource list of a 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 csapi:UUID

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

stack_name URI xsd: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 stack.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

Response parameters
Parameter Style Type Description
stack plain xsd:dict

The stack object.

capabilities plain xsd:list

A list of stack capabilities.

creation_time plain xsd:dateTime

The date and time when the stack was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

description plain xsd:string

The description of the stack.

id plain csapi:UUID

The UUID of the stack.

links plain xsd:list

The share links.

links plain xsd:list

A list of stack links.

notification_topics plain xsd:list

A list of stack notifications.

outputs plain xsd:list

A list of stack outputs.

parameters plain xsd:dict

Key and value pairs that contain stack parameters.

stack_name plain xsd:string

The name of the stack.

stack_owner plain xsd:string

The owner of the stack.

stack_status plain xsd:string

The status of the stack.

stack_status_reason plain xsd:string

The reason for the current status of the stack.

template_description plain xsd:string

The description of the stack template.

stack_user_project_id plain csapi:UUID

The project UUID of the stack user.

timeout_mins plain xsd:string

The timeout, in minutes.

updated_time plain xsd:dateTime

The date and time when the stack was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

If the updated_at date and time stamp is not set, its value is null.

parent plain xsd:string

The parent of the stack.

tags plain xsd:string

The stack tags.

{
    "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 stack.

 
Normal response codes
202
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

template_url (Optional) plain xsd:string

A URI to the location containing the stack template on which to perform the 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 xsd:dict

The stack template on which to perform the 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 xsd:dict

A JSON environment for the stack.

files (Optional) plain xsd:dict

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 template_url address. Instead, use the template parameter to supply the template content as part of the request.

tags (Optional) plain xsd: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 xsd:dict

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 xsd:int

The timeout for stack creation in minutes.

disable_rollback (Optional) plain xsd:boolean

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.

{
    "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 stack and its snapshots.

 
Normal response codes
204
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

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 stack but leaves its resources intact, and returns data that describes the stack and its resources.

 

This method can be disabled from the server side. If it is disabled, this call throws an exception.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

{
    "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 resources in a stack. All snapshots are deleted when the stack is deleted.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

name plain xsd:string

The name of the snapshot.

Response parameters
Parameter Style Type Description
id plain csapi:UUID

The UUID of the snapshot.

name plain xsd:string

The name of the snapshot.

status plain xsd:string

The status of the snapshot.

status_reason plain xsd:string

The reason for the current snapshot status.

creation_time plain xsd:dateTime

The date and time when the snapshot was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

data plain xsd:dict

The snapshot data.

{
    "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 snapshots for a stack.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

Response parameters
Parameter Style Type Description
snapshots plain xsd:list

A list of snapshots and their properties.

id plain csapi:UUID

The UUID of the snapshot.

name plain xsd:string

The name of the snapshot.

status plain xsd:string

The status of the snapshot.

status_reason plain xsd:string

The reason for the current snapshot status.

creation_time plain xsd:dateTime

The date and time when the snapshot was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

data plain xsd:dict

The snapshot data.

{
    "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 snapshot.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

snapshot_id URI csapi:UUID

The UUID of the snapshot.

Response parameters
Parameter Style Type Description
snapshot plain xsd:dict

Key and value pairs that contain snapshot properties.

project_id plain csapi:UUID

The UUID of the project.

resources plain xsd:dict

The snapshot resources.

template plain xsd:dict

Information about the template.

id plain csapi:UUID

The UUID of the snapshot.

name plain xsd:string

The name of the snapshot.

status plain xsd:string

The status of the snapshot.

status_reason plain xsd:string

The reason for the current snapshot status.

creation_time plain xsd:dateTime

The date and time when the snapshot was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

data plain xsd:dict

The snapshot data.

{
    "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 csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

snapshot_id URI csapi:UUID

The UUID of the snapshot.

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. You must recreate deleted stacks.

Normal response codes
202
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

snapshot_id URI csapi:UUID

The UUID of the snapshot.

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

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

Lists outputs for a stack.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

Response parameters
Parameter Style Type Description
output_key plain xsd:string

The name of a stack output.

output_value plain xsd:string

The value of a stack output.

description plain xsd:string

The description of a stack output.

output_error plain xsd:string

The error in a stack output.

{
    "outputs": [
        {
            "output_key": "output name",
            "output_value": "output value",
            "description": "output description",
            "output_error": null
        }
    ]
}

This operation does not accept a request body.

GET
/v1/​{tenant_id}​/stacks/​{stack_name}​/​{stack_id}​/outputs/​{output_key}​
Show output

Shows details for a stack output.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

output_key URI xsd:string

The key of a stack output.

Response parameters
Parameter Style Type Description
output_key plain xsd:string

The name of a stack output.

output_value plain xsd:string

The value of a stack output.

description plain xsd:string

The description of a stack output.

output_error plain xsd:string

The error in a stack output.

{
    "output": {
        "output_key": "output_name",
        "output_value": "output_value",
        "description": "output description",
        "output_error": null
    }
}

This operation does not accept a request 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
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

suspend plain xsd: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
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

resume plain xsd: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
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

cancel_update plain xsd: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 a stack.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

check plain xsd: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
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

nested_depth (Optional) query xsd:int

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

with_detail (Optional) query xsd:boolean

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

Response parameters
Parameter Style Type Description
resources plain xsd:list

A list of resources and their properties.

creation_time plain xsd:dateTime

The date and time when the stack resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

description plain xsd:string

The description of the stack resource.

logical_resource_id plain xsd:string

The ID of the logical stack resource.

physical_resource_id plain xsd:string

The ID of the stack physical resource.

required_by plain xsd:list

The list of resources that require this stack resource.

resource_name plain xsd:string

The name of the resource.

resource_status plain xsd:string

The status of the resource.

resource_status_reason plain xsd:string

The reason for the current stack resource state.

resource_type plain xsd:string

The type of the resource.

updated_time plain xsd:dateTime

The date and time when the stack resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

If the updated_at date and time stamp is not set, its value is null.

{
    "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 resource.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

resource_name URI xsd:string

The name of a resource in the stack.

Response parameters
Parameter Style Type Description
resource plain xsd:dict

Key and value pairs that contain stack resource properties.

creation_time plain xsd:dateTime

The date and time when the stack resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

description plain xsd:string

The description of the stack resource.

logical_resource_id plain xsd:string

The ID of the logical stack resource.

physical_resource_id plain xsd:string

The ID of the stack physical resource.

required_by plain xsd:list

The list of resources that require this stack resource.

resource_name plain xsd:string

The name of the resource.

resource_status plain xsd:string

The status of the resource.

resource_status_reason plain xsd:string

The reason for the current stack resource state.

resource_type plain xsd:string

The type of the resource.

updated_time plain xsd:dateTime

The date and time when the stack resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

If the updated_at date and time stamp is not set, its value is null.

{
    "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 resource.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

resource_name URI xsd: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 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 csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

resource_name URI xsd: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 stack.

 
Normal response codes
302
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd: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 stack.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

resource_action (Optional) query xsd:string

Filters the event list by a 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 xsd:string

Filters the event list by a 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 xsd:string

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

resource_type (Optional) query xsd:string

Filters the event list by a 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 page size of items. Returns a number of items up to a 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

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 xsd:string

Sorts the list by the resource_type or created_at key.

sort_dir (Optional) query xsd: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 stack resource.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

resource_name URI xsd:string

The name of a resource in the stack.

resource_action (Optional) query xsd:string

Filters the event list by a 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 xsd:string

Filters the event list by a 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_type (Optional) query xsd:string

Filters the event list by a 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 page size of items. Returns a number of items up to a 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

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 xsd:string

Sorts the list by the resource_type or created_at key.

sort_dir (Optional) query xsd: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 an event.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

resource_name URI xsd:string

The name of a resource in the stack.

event_id URI csapi:UUID

The UUID of the event that is related to the resource in the stack.

{
    "event": {
        "event_time": "2015-06-25T14:59:53",
        "id": "8db23e2e-72b2-47a2-9ed9-b52417f56e50",
        "links": [
            {
                "href": "http://hostname/v1/1234/stacks/mystack/56789/resources/random_key_name/events/8db23e2e-72b2-47a2-9ed9-b52417f56e50",
                "rel": "self"
            },
            {
                "href": "http://hostname/v1/1234/stacks/mystack/56789/resources/random_key_name",
                "rel": "resource"
            },
            {
                "href": "http://hostname/v1/1234/stacks/mystack/56789",
                "rel": "stack"
            }
        ],
        "logical_resource_id": "random_key_name",
        "physical_resource_id": null,
        "resource_name": "random_key_name",
        "resource_properties": {
            "character_classes": null,
            "character_sequences": null,
            "length": 8,
            "salt": null,
            "sequence": null
        },
        "resource_status": "CREATE_IN_PROGRESS",
        "resource_status_reason": "state changed",
        "resource_type": "OS::Heat::RandomString"
    }
}

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 stack.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

stack_name URI xsd:string

The name of a stack.

stack_id URI csapi:UUID

The UUID of the stack.

Response parameters
Parameter Style Type Description
description plain xsd:string

The description of the stack template.

heat_template_version plain xsd:string

The version of the heat template.

outputs plain xsd:dict

Key and value pairs that contain output data.

parameters plain xsd:dict

Key and value pairs that contain template parameters.

resources plain xsd:dict

The required sources for creating the stack template.

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

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

{
    "template_versions": [
        {
            "version": "heat_template_version.2014-10-16",
            "type": "hot"
        },
        {
            "version": "heat_template_version.2015-04-30",
            "type": "hot"
        },
        {
            "version": "HeatTemplateFormatVersion.2012-12-12",
            "type": "cfn"
        },
        {
            "version": "heat_template_version.2015-10-15",
            "type": "hot"
        },
        {
            "version": "AWSTemplateFormatVersion.2010-09-09",
            "type": "cfn"
        },
        {
            "version": "heat_template_version.2013-05-23",
            "type": "hot"
        },
        {
            "version": "heat_template_version.2016-04-08",
            "type": "hot"
        }
    ]
}

This operation does not accept a request body.

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

Validates a template.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

template_url (Optional) plain xsd:string

A URI to the location containing the stack template on which to perform the 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 plain xsd:dict

The stack template on which to perform the 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 xsd:dict

A JSON environment for the stack.

Response parameters
Parameter Style Type Description
Description plain xsd:string

The description specified in the template.

Parameters plain xsd:dict

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

ParameterGroups (Optional) plain xsd: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 resource type.

 

The returned template contains a single resource 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
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

type_name URI xsd:string

The name of a resource type.

template_type (Optional) query xsd:string

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

Response parameters
Parameter Style Type Description
HeatTemplateFormatVersion plain xsd:string

The version of the heat template.

Outputs plain xsd:dict

Key and value pairs that contain output data.

Parameters plain xsd:dict

Key and value pairs that contain template parameters.

Resources plain xsd:dict

Contain KeyPair for resource template.

{
    "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 resource type.

 

A schema describes the properties that can be set on the resource, their types, constraints, descriptions, and default values. Additionally, the response shows the resource attributes and their descriptions.

Normal response codes
200
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

type_name URI xsd:string

The name of a resource type.

Response parameters
Parameter Style Type Description
attributes plain xsd:dict

Key and value pairs that contain resource attributes.

description plain xsd:string

The description of the resource attribute.

properties plain xsd:dict

The properties of the resource. Includes description, type, and so on.

required plain xsd:boolean

If set to true the attribute is required.

type plain xsd:string

The property type.

update_allowed plain xsd:boolean

If set to true, update is allowed.

resource_type plain xsd:string

The type of the resource.

support_status plain xsd:dict

Information about the current status.

{
    "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 all supported template resource types.

 
Normal response codes
200
Error response codes
badRequest (400), unauthorized (401)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

name (Optional) query xsd:string

Filters the response by a resource type name. You can set this value to a regular expression. Use this filter multiple times to filter by multiple names.

version (Optional) query xsd:string

Filters the response by resource types by heat version. For example, 2016.1 or 5.0.0. Use this filter multiple times to filter by multiple versions.

support_status (Optional) query xsd:string

Filters the response by resource types by a support status. Valid support status values are UNKNOWN, SUPPORTED, DEPRECATED, UNSUPPORTED, and HIDDEN. Use this filter multiple times to filter by multiple support statuses.

Response parameters
Parameter Style Type Description
template_versions plain xsd:list

A template_versions object.

version plain xsd:string

The version of the template.

type plain xsd:string

The template type. Currently hot and cfn are the available template types.

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

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 csapi:UUID

The UUID 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
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

config (Optional) plain xsd:string

Configuration script or manifest that defines which configuration is performed.

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

The name of the configuration to create.

inputs (Optional) plain xsd:list

Schema that represents the inputs that this software configuration expects.

outputs (Optional) plain xsd:list

Schema that represents the outputs that this software configuration produces.

options (Optional) plain xsd:string

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

Response parameters
Parameter Style Type Description
inputs plain xsd:list

A list of inputs to configure the software.

name plain xsd:string

The name of the software configuration.

outputs plain xsd:list

A list of software configuration output data.

creation_time plain xsd:dateTime

The date and time when the software was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

group plain xsd:string

The name of the group in which the software is configured.

config plain xsd:string

The configuration code.

options plain xsd:string

The options, if any, to include in the code. For example any dependent flags.

{
    "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
badRequest (400), unauthorized (401), itemNotFound (404)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

config_id URI csapi:UUID

The UUID of the configuration.

Response parameters
Parameter Style Type Description
inputs plain xsd:list

A list of inputs to configure the software.

name plain xsd:string

The name of the software configuration.

outputs plain xsd:list

A list of software configuration output data.

creation_time plain xsd:dateTime

The date and time when the software was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

group plain xsd:string

The name of the group in which the software is configured.

config plain xsd:string

The configuration code.

options plain xsd:string

The options, if any, to include in the code. For example any dependent flags.

{
    "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 csapi:UUID

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

config_id URI csapi:UUID

The UUID of the configuration.

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
badRequest (400), unauthorized (401), itemNotFound (404), internalServerError (500)
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the software deployment. The value is INPROGRESS or COMPLETE.

server_id plain csapi:UUID

The UUID of the server.

config_id plain csapi:UUID

The UUID of the configuration.

output_values plain xsd:list

A list of output data.

input_values plain xsd:list

A list of input data.

action plain xsd:string

The deployment action.

status_reason plain xsd:string

The debug information for the current status.

id plain csapi:UUID

The UUID of the software deployment.

creation_time plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

{
    "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 csapi:UUID

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

config_id plain csapi:UUID

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

server_id plain csapi:UUID

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

action plain xsd:string

The current stack action that triggers this deployment resource.

stack_user_project_id (Optional) plain csapi:UUID

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

status (Optional) plain xsd:string

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

status_reason (Optional) plain xsd:string

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

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the software deployment. The value is INPROGRESS or COMPLETE.

server_id plain csapi:UUID

The UUID of the server.

config_id plain csapi:UUID

The UUID of the configuration.

output_values plain xsd:list

A list of output data.

input_values plain xsd:list

A list of input data.

action plain xsd:string

The deployment action.

status_reason plain xsd:string

The debug information for the current status.

id plain csapi:UUID

The UUID of the software deployment.

creation_time plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

{
    "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 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 csapi:UUID

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

server_id URI csapi:UUID

The UUID 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 software deployment.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

deployment_id URI csapi:UUID

The UUID of the deployment.

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the software deployment. The value is INPROGRESS or COMPLETE.

server_id plain csapi:UUID

The UUID of the server.

config_id plain csapi:UUID

The UUID of the configuration.

output_values plain xsd:list

A list of output data.

input_values plain xsd:list

A list of input data.

action plain xsd:string

The deployment action.

status_reason plain xsd:string

The debug information for the current status.

id plain csapi:UUID

The UUID of the software deployment.

creation_time plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

{
    "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 software deployment.

 
Normal response codes
200
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

deployment_id URI csapi:UUID

The UUID of the deployment.

config_id plain csapi:UUID

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

action plain xsd:string

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

status (Optional) plain xsd:string

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

status_reason (Optional) plain xsd:string

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

output_values (Optional) plain xsd:dict

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

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the software deployment. The value is INPROGRESS or COMPLETE.

server_id plain csapi:UUID

The UUID of the server.

config_id plain csapi:UUID

The UUID of the configuration.

output_values plain xsd:list

A list of output data.

input_values plain xsd:list

A list of input data.

action plain xsd:string

The deployment action.

status_reason plain xsd:string

The debug information for the current status.

id plain csapi:UUID

The UUID of the software deployment.

creation_time plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

{
    "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 software deployment.

 
Normal response codes
204
Request parameters
Parameter Style Type Description
tenant_id URI csapi:UUID

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

deployment_id URI csapi:UUID

The UUID of the deployment.

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 csapi:UUID

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

Response parameters
Parameter Style Type Description
status plain xsd:string

The status of the heat engine.

binary plain xsd:string

The name of the binary form of the heat engine.

report_interval plain xsd:int

The polling interval, in seconds. The API reports events at this interval until heat engine creation completes.

created_at plain xsd:dateTime

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC.

hostname plain xsd:string

The name of the host for the service.

updated_at plain xsd:dateTime

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

If the updated_at date and time stamp is not set, its value is null.

topic plain xsd:string

The topic of the heat engine.

deleted_at plain xsd:dateTime

The date and time when the resource was deleted.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

id plain csapi:UUID

The UUID of the heat engine.

services plain xsd:list

A list of heat engines.

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