Orchestration Service API v1

Orchestration Service API v1

Build info

GET
/v1/{tenant_id}/build_info

Show build information

Shows build information for an Orchestration deployment.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
api body object The orchestration API revsion information.
engine body object The orchestration engine revsion information.

Response Example

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

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.

Response Codes

Success

Code Reason
300 - Multiple Choices There are multiple choices for resources. The request has to be more specific to successfully retrieve one of these resources.

Request Parameters

This operation does not accept a request body.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
versions body array A list of all orchestration API versions. Each object in the list provides information about a supported API version such as id, status and links, among other fields.
id body string A common name for the version in question. Informative only, it has no real semantic meaning.
status body string

The status of this API version. This can be one of:

  • CURRENT: this is the preferred version of the API to use
  • SUPPORTED: this is an older, but still supported version of the API
  • DEPRECATED: a deprecated version of the API that is slated for removal
links body array 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.

Response Example

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

Stacks

POST
/v1/{tenant_id}/stacks

Create stack

Creates a stack.

Response Codes

Success

Code Reason
201 - Created Resource was created and is ready to use.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
409 - Conflict This operation conflicted with another operation on this resource.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
disable_rollback (Optional) body 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.
environment (Optional) body object A JSON environment for the stack.
files (Optional) body object

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) body object

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
}
stack_name body string

A name for the 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_.-]{0,254}$ regular expression.

When you delete or abandon a stack, its name will not become available for reuse until the deletion completes successfully.

tags (Optional) body 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.
template (Optional) body object

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.

template_url (Optional) body 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.
timeout_mins (Optional) body integer The timeout for stack creation in minutes.

Request Example

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

Response Parameters

Name In Type Description
location header string For asynchronous resource operations, the location header contains a URI that can be checked to track resource status changes.
X-Openstack-Reqeuest-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
stack body object The stack object.
id body string The UUID of the stack.
links body array 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.

Response Example

{
    "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/preview

Preview stack

Previews a stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
409 - Conflict This operation conflicted with another operation on this resource.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
disable_rollback (Optional) body 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.
environment (Optional) body object A JSON environment for the stack.
files (Optional) body object

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) body object

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
}
stack_name body string

A name for the 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_.-]{0,254}$ regular expression.

When you delete or abandon a stack, its name will not become available for reuse until the deletion completes successfully.

tags (Optional) body 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.
template (Optional) body object

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.

template_url (Optional) body 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.
timeout_mins (Optional) body integer The timeout for stack creation in minutes.

Request Example

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

Response Parameters

Name In Type Description
X-Openstack-Reqeuest-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
capabilities body array List of stack capabilities for stack.
creation_time body string

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.

deletion_time body string

The date and time when the resource was (soft-) 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.

description body string The description of the stack resource.
disable_rollback (Optional) body 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.
id body string The UUID of the stack.
links body array 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.
notification_topics body array List of notification topics for stack.
outputs body array A list of stack outputs.
parameters body object A group of key-value pairs where each key contains either a user-provided parameter name or a built-in parameter name (e.g. OS::project_id).
parent body string The stack ID of the parent stack, if this is a nested stack.
resources body array List of stack resources.
stack body object The stack object.
stack_name body string

A name for the 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_.-]{0,254}$ regular expression.

When you delete or abandon a stack, its name will not become available for reuse until the deletion completes successfully.

stack_owner body string The owner of the stack.
stack_user_project_id body string The project UUID of the stack user.
tags body array The stack tags.
template_description body string The description of the stack template.
timeout_mins body integer The timeout for stack creation in minutes.
updated_time body string

The date and time when the object 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.

Response Example

{
    "stack": {
        "capabilities": [],
        "creation_time": "2015-01-31T15:12:36Z",
        "deletion_time": null,
        "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": [],
        "outputs": [],
        "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": null,
        "tags": null,
        "template_description": "HOT template for Nova Server resource.\n",
        "timeout_mins": null,
        "updated_time": null
    }
}
GET
/v1/{tenant_id}/stacks

List stacks

Lists active stacks.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
id (Optional) query string Filters the stack list by a stack ID. Use this filter multiple times to filter by multiple IDs.
status (Optional) query string Filters the stack list by a status. Use this filter multiple times to filter by multiple statuses.
name (Optional) query string Filters the stack list by a name. Use this filter multiple times to filter by multiple names.
action (Optional) query string Filters the stack list by an action. Use this filter multiple times to filter by multiple actions.
tenant (Optional) query string Filters the stack list by a tenant. Use this filter multiple times to filter by multiple tenants.
username (Optional) query string Filters the stack list by a user name. Use this filter multiple times to filter by multiple user names.
owner_id (Optional) query string 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 integer 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 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 string Sorts the stack list by stack_name, stack_status, creation_time, or updated_time key.
sort_dir (Optional) query string The sort direction of the list. A valid value is asc (ascending) or desc (descending).
show_deleted (Optional) query boolean Set to true to include deleted stacks in the list.
show_nested (Optional) query boolean Set to true to include nested stacks in the list.
tags (Optional) query string Lists stacks that contain one or more simple string tags. To specify multiple tags, separate the tags with commas. For example, tag1,tag2. The boolean AND expression is used to combine multiple tags.
tags_any (Optional) query string Lists stacks that contain one or more simple string tags. To specify multiple tags, separate the tags with commas. For example, tag1,tag2. The boolean OR expression is used to combine multiple tags.
not_tags (Optional) query string Lists stacks that do not contain one or more simple string tags. To specify multiple tags, separate the tags with commas. For example, tag1,tag2. The boolean AND expression is used to combine multiple tags.
not_tags_any (Optional) query string Lists stacks that do not contain one or more simple string tags. To specify multiple tags, separate the tags with commas. For example, tag1,tag2. The boolean OR expression is used to combine multiple tags.
global_tenant (Optional) query boolean Set to true to include stacks from all tenants (projects) in the stack list. Specify policy requirements in the Orchestration policy.json file.
with_count (Optional) query 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.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
stacks body array A list of stack object.
creation_time body string

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.

deletion_time body string

The date and time when the resource was (soft-) 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.

description body string The description of the stack resource.
links body array 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.
parent body string The stack ID of the parent stack, if this is a nested stack.
stack_name body string

A name for the 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_.-]{0,254}$ regular expression.

When you delete or abandon a stack, its name will not become available for reuse until the deletion completes successfully.

stack_owner body string The owner of the stack.
stack_status body string The status of the stack.
stack_status_reason body string The reason for the current status of the stack.
tags body array The stack tags.
updated_time body string

The date and time when the object 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.

stack_user_project_id body string The project UUID of the stack user.

Response Example

{
    "stacks": [
        {
            "creation_time": "2014-06-03T20:59:46Z",
            "deletion_time": null,
            "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"
                }
            ],
            "parent": null,
            "stack_name": "simple_stack",
            "stack_owner": null,
            "stack_status": "CREATE_COMPLETE",
            "stack_status_reason": "Stack CREATE completed successfully",
            "stack_user_project_id": "71510cbd459a49ac989ca1055de7038b",
            "tags": null,
            "updated_time": null
        }
    ]
}
GET
/v1/{tenant_id}/stacks/{stack_identity}

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.

Response Codes

Success

Code Reason
302 - Found The response is about a redirection hint. The header of the response usually contains a ‘location’ value where requesters can check to track the real location of the resource.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_identity path string The UUID or the name of a stack.

Response Parameters

Name In Type Description
location header string For asynchronous resource operations, the location header contains a URI that can be checked to track resource status changes.
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
code body string The response code to a resource find request. e.g. 302 Found.
message body string The message in the response to a resource find request.
title body string The title of the response to a resource find request. e.g. Found.

Response Example

{
    "code": "302 Found",
    "message": "The resource was found at <a href=\"http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd\">http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd</a>;\nyou should be redirected automatically.\n\n",
    "title": "Found"
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}

Show stack details

Shows details for a stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resolve_outputs (Optional) query boolean A boolean indicating whether the outputs section of a stack should be resolved.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
stack body object The stack object.
capabilities body array List of stack capabilities for stack.
creation_time body string

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.

deletion_time body string

The date and time when the resource was (soft-) 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.

description body string The description of the stack resource.
disable_rollback body boolean Whether deletion of all stack resources when stack creation fails is enabled.
id body string The UUID of the stack.
links body array 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.
notification_topics body array List of notification topics for stack.
outputs body array A list of stack outputs.
parameters body object A group of key-value pairs where each key contains either a user-provided parameter name or a built-in parameter name (e.g. OS::project_id).
parent body string The stack ID of the parent stack, if this is a nested stack.
stack_name body string

A name for the 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_.-]{0,254}$ regular expression.

When you delete or abandon a stack, its name will not become available for reuse until the deletion completes successfully.

stack_owner body string The owner of the stack.
stack_status body string The status of the stack.
stack_status_reason body string The reason for the current status of the stack.
stack_user_project_id body string The project UUID of the stack user.
tags body array The stack tags.
template_description body string The description of the stack template.
timeout_mins body integer The timeout for stack creation in minutes.
updated_time body string

The date and time when the object 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.

Response Example

{
    "stack": {
        "capabilities": [],
        "creation_time": "2014-06-03T20:59:46Z",
        "deletion_time": null,
        "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"
        },
        "parent": null,
        "stack_name": "simple_stack",
        "stack_owner": "simple_username",
        "stack_status": "CREATE_COMPLETE",
        "stack_status_reason": "Stack CREATE completed successfully",
        "stack_user_project_id": "65728b74-cfe7-4f17-9c15-11d4f686e591",
        "tags": null,
        "template_description": "sample stack",
        "timeout_mins": null,
        "updated_time": null
    }
}
PUT
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}

Update stack

Updates a stack.

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
clear_parameters (Optional) body array A list of parameters, if specified, to be removed from the set of parameters of the current stack. The default values in the template will be used.
disable_rollback (Optional) body 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.
environment (Optional) body object A JSON environment for the stack.
environment_files (Optional) body object An ordered list of names for environment files found in the files dict.
existing (Optional) body boolean A boolean specifying whether the service is about to reuse the existing stack template, parameters and environment. If template parameter is not provided, the existing template is used. If template_files is not provided, the existing environment is used. Parameters specified in the parameters key will patch over the existing values in the current stack. Parameters omitted will keep the existing values.
files (Optional) body object

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) body object

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) body 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.
template (Optional) body object

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.

template_url (Optional) body 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.
timeout_mins (Optional) body integer The timeout for stack creation in minutes.
converge (Optional) body boolean Set to true to force the stack to observe the reality before update.

Request Example

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

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
code body string The response code to a resource find request. e.g. 302 Found.
message body string The message in the response to a resource find request.
title body string The title of the response to a resource find request. e.g. Found.

Response Example

{
    "code": "202 Accepted",
    "message": "The request is accepted for processing.<br /><br />\n\n\n",
    "title": "Accepted"
}
PATCH
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}

Update stack (PATCH)

Updates a stack using the PATCH verb. The logic is identical to stack update with a PUT verb except that the existing parameter is always set to True.

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
clear_parameters (Optional) body array A list of parameters, if specified, to be removed from the set of parameters of the current stack. The default values in the template will be used.
disable_rollback (Optional) body 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.
environment (Optional) body object A JSON environment for the stack.
environment_files (Optional) body object An ordered list of names for environment files found in the files dict.
existing (Optional) body boolean This parameter can be specified but it will be ignored. When using the PATCH verb to update a stack,the orchestration service will try reuse the existing stack template, parameters and environment. If template parameter is not provided, the existing template is used. If template_files is not provided, the existing environment is used. Parameters specified in the parameters key will patch over the existing values in the current stack. Parameters omitted will keep the existing values.
files (Optional) body object

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) body object

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) body 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.
template (Optional) body object

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.

template_url (Optional) body 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.
timeout_mins (Optional) body integer The timeout for stack creation in minutes.
converge (Optional) body boolean Set to true to force the stack to observe the reality before update.

Request Example

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

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
code body string The response code to a resource find request. e.g. 302 Found.
message body string The message in the response to a resource find request.
title body string The title of the response to a resource find request. e.g. Found.

Response Example

{
    "code": "202 Accepted",
    "message": "The request is accepted for processing.<br /><br />\n\n\n",
    "title": "Accepted"
}
PUT
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/preview

Preview stack update

Previews an update for a stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
clear_parameters (Optional) body array A list of parameters, if specified, to be removed from the set of parameters of the current stack. The default values in the template will be used.
disable_rollback (Optional) body 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.
environment (Optional) body object A JSON environment for the stack.
environment_files (Optional) body object An ordered list of names for environment files found in the files dict.
existing (Optional) body boolean A boolean specifying whether the service is about to reuse the existing stack template, parameters and environment. If template parameter is not provided, the existing template is used. If template_files is not provided, the existing environment is used. Parameters specified in the parameters key will patch over the existing values in the current stack. Parameters omitted will keep the existing values.
files (Optional) body object

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) body object

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
}
show_nested (Optional) body boolean Set to true to include nested stacks in the preview result.
tags (Optional) body 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.
template (Optional) body object

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.

template_url (Optional) body 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.
timeout_mins (Optional) body integer The timeout for stack creation in minutes.
converge (Optional) body boolean Set to true to force the stack to observe the reality before update.

Request Example

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

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
resource_changes body object An map that describes what resources will be added, deleted, replaced, updated or remain unchanged.
added body array A list of resource objects that will be added if a stack update is performed.
deleted body array A list of resource objects that will be deleted if a stack update is performed.
replaced body array A list of resource objects that will be replaced if a stack update is performed.
unchanged body array A list of resource objects that will remain unchanged if a stack update is performed.
updated body array A list of resource objects that will have their properties updated in place if a stack update is performed.

Response Example

{
    "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}"
        }
    ]
}
PATCH
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/preview

Preview stack update (PATCH)

Previews an update for a stack using the PATCH verb. The logic is the same as that of stack update preview with a PUT verb except that the existing parameter is always set to True.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
clear_parameters (Optional) body array A list of parameters, if specified, to be removed from the set of parameters of the current stack. The default values in the template will be used.
disable_rollback (Optional) body 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.
environment (Optional) body object A JSON environment for the stack.
environment_files (Optional) body object An ordered list of names for environment files found in the files dict.
existing (Optional) body boolean This parameter can be specified but it will be ignored. When using the PATCH verb to update a stack,the orchestration service will try reuse the existing stack template, parameters and environment. If template parameter is not provided, the existing template is used. If template_files is not provided, the existing environment is used. Parameters specified in the parameters key will patch over the existing values in the current stack. Parameters omitted will keep the existing values.
files (Optional) body object

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) body object

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
}
show_nested (Optional) body boolean Set to true to include nested stacks in the preview result.
tags (Optional) body 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.
template (Optional) body object

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.

template_url (Optional) body 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.
timeout_mins (Optional) body integer The timeout for stack creation in minutes.
converge (Optional) body boolean Set to true to force the stack to observe the reality before update.

Request Example

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

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
resource_changes body object An map that describes what resources will be added, deleted, replaced, updated or remain unchanged.
added body array A list of resource objects that will be added if a stack update is performed.
deleted body array A list of resource objects that will be deleted if a stack update is performed.
replaced body array A list of resource objects that will be replaced if a stack update is performed.
unchanged body array A list of resource objects that will remain unchanged if a stack update is performed.
updated body array A list of resource objects that will have their properties updated in place if a stack update is performed.

Response Example

{
    "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}"
        }
    ]
}
DELETE
/v1/{tenant_id}/stacks/{stack_identity}

Find stack for deletion

Find the canonical URL for a stack for deletion. This request returns a status code of 302 pointing to the location where a DELETE request can be sent to request a stack deletion.

Response Codes

Success

Code Reason
302 - Found The response is about a redirection hint. The header of the response usually contains a ‘location’ value where requesters can check to track the real location of the resource.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_identity path string The UUID or the name of a stack.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
location header string For asynchronous resource operations, the location header contains a URI that can be checked to track resource status changes.
code body string The response code to a resource find request. e.g. 302 Found.
message body string The message in the response to a resource find request.
title body string The title of the response to a resource find request. e.g. Found.

Response Example

{
    "code": "302 Found",
    "message": "The resource was found at <a href=\"http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s2/321c4eed-c87f-4cea-8288-9238f3b92e63\">http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s2/321c4eed-c87f-4cea-8288-9238f3b92e63</a>;\nyou should be redirected automatically.\n\n",
    "title": "Found"
}
DELETE
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}

Delete stack

Deletes a stack. If a stack has snapshots, those snapshots are deleted as well.

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.

Response Parameters

This request does not return anything in the 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 is a preview feature which has to be explicitly enabled by setting the following option in the heat.conf file:

[DEFAULT]
enable_stack_abandon = True

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.

Response Parameters

Name In Type Description
action body string The current action on the stack.
environment body object A JSON environment for the stack.
files body object A map containing the name and content of files used by the stack.
id body string The UUID of the stack.
stack_name body string

A name for the 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_.-]{0,254}$ regular expression.

When you delete or abandon a stack, its name will not become available for reuse until the deletion completes successfully.

project_id body string The UUID of the project.
resources body object The required sources for creating the stack template.
stack_user_project_id body string The project UUID of the stack user.
status body string The status of the stack.
tags body array The stack tags.
template body object The template used to create the stack.

Response Example

{
    "action": "CREATE",
    "environment": {},
    "files": {},
    "id": "16934ca3-40e0-4fb2-a289-a700662ec05a",
    "name": "g",
    "project_id": "369166a68a3a49b78b4e138531556e55",
    "resources": {
        "server": {
            "status": "COMPLETE",
            "name": "server",
            "resource_data": {},
            "resource_id": "39d5dad7-7d7a-4cc8-bd84-851e9e2ff4ea",
            "action": "CREATE",
            "type": "OS::Nova::Server",
            "metadata": {}
        }
    },
    "stack_user_project_id": "9bbd353467bc4f069a3692d223a48aac",
    "status": "COMPLETE",
    "tags": null,
    "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"
            }
        }
    }
}
POST
/v1/{tenant_id}/stacks

Adopt stack

Creates a stack from existing resources.

This is a preview feature which has to be explicitly enabled by setting the following option in the heat.conf file:

[DEFAULT]
enable_stack_adopt = True

Response Codes

Success

Code Reason
201 - Created Resource was created and is ready to use.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
409 - Conflict This operation conflicted with another operation on this resource.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
adopt_stack_data body object Existing resources data to adopt a stack. Data returned by abandon stack could be provided as adopt_stack_data.
disable_rollback (Optional) body 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.
environment (Optional) body object A JSON environment for the stack.
files (Optional) body object

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) body object

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
}
stack_name body string

A name for the 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_.-]{0,254}$ regular expression.

When you delete or abandon a stack, its name will not become available for reuse until the deletion completes successfully.

timeout_mins (Optional) body integer The timeout for stack creation in minutes.

Request Example

{
    "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": "new_stack",
    "timeout_mins": 30
}

Response Parameters

Name In Type Description
location header string For asynchronous resource operations, the location header contains a URI that can be checked to track resource status changes.
X-Openstack-Reqeuest-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
stack body object The stack object.
id body string The UUID of the stack.
links body array 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.

Response Example

{
    "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/{stack_name}/{stack_id}/export

Export stack

Gets the stack data in JSON format.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
409 - Conflict This operation conflicted with another operation on this resource.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.

Response Parameters

The body of the response contains a map of file names and file contents.

Name In Type Description
X-Openstack-Reqeuest-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
action body string The last action executed on the stack.
environment body object A JSON environment for the stack.
files body object A map containing the name and content of files used by the stack.
id body string The UUID of the stack.
name body string

A name for the 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_.-]{0,254}$ regular expression.

When you delete or abandon a stack, its name will not become available for reuse until the deletion completes successfully.

project_id body string The UUID of the project.
resources body array A map of resource names and their properties.
stack_user_project_id body string The project UUID of the stack user.
status body string The status of the stack.
tags body array The stack tags.
template body object The template used to create the stack.

Response Example

{
    "action": "SUSPEND",
    "environment": {
        "event_sinks": [],
        "parameter_defaults": {},
        "parameters": {},
        "resource_registry": {
            "resources": {}
        }
    },
    "files": {},
    "id": "da778f26-6d25-4634-9531-d438188e48fd",
    "name": "s1",
    "project_id": "369166a68a3a49b78b4e138531556e55",
    "resources": {
        "random": {
            "action": "SUSPEND",
            "metadata": {},
            "name": "random",
            "resource_data": {
                "value": "wCPWWoGJH5SZKtNFAgqGcbiWokCkRgam"
            },
            "resource_id": "s1-random-pzuzs6pbjhho",
            "status": "COMPLETE",
            "type": "OS::Heat::RandomString"
        }
    },
    "stack_user_project_id": "a4e6fd443f5b4d4694331ff441ad2397",
    "status": "COMPLETE",
    "tags": null,
    "template": {
        "heat_template_version": "2014-10-16",
        "outputs": {
            "result": {
                "value": {
                    "get_attr": [
                        "random",
                        "value"
                    ]
                }
            }
        },
        "parameters": {
            "str_length": {
                "default": 32,
                "type": "number"
            }
        },
        "resources": {
            "random": {
                "properties": {
                    "length": {
                        "get_param": "str_length"
                    }
                },
                "type": "OS::Heat::RandomString"
            }
        }
    }
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/template

Get stack template

Gets a template for a stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.

Response Parameters

Name In Type Description
X-Openstack-Reqeuest-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
heat_template_version body string The version of the orchestration HOT template.
outputs body object Key and value pairs that contain output data.
parameters body object Key and value pairs that contain the schemas of parameters acceptable by the template.
description body string The description of the stack template.
resources body object Key and value pairs that contain definition of resources in the template.

Response Example

{
    "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"
        }
    }
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/environment

Get stack environment

Gets the environment for a stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.

Response Parameters

Name In Type Description
X-Openstack-Reqeuest-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
encrypted_param_names body array A list of parameter names whose values are encrypted.
event_sinks body array A list of event sinks.
parameter_defaults body object A map of parameters and their default values defined for the stack.
parameters (Optional) body object

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
}
resource_registry body object A map containing customized resource definitions. This map contains at least a dict of resources registered for the stack.

Response Example

{
    "encrypted_param_names": [],
    "event_sinks": [],
    "parameter_defaults": {},
    "parameters": {},
    "resource_registry": {
        "resources": {}
    }
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/files

Get stack files

Gets the files associated with a stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.

Response Parameters

The body of the response contains a map of file names and file contents.

Name In Type Description
X-Openstack-Reqeuest-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Response Example

{
    "file:///home/username/hello.sh": "#!/bin/sh\necho hello\n"
}

Stack resources

GET
/v1/{tenant_id}/stacks/{stack_identity}/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

Response Codes

Success

Code Reason
302 - Found The response is about a redirection hint. The header of the response usually contains a ‘location’ value where requesters can check to track the real location of the resource.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_identity path string The UUID or the name of a stack.

Response Parameter

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
location header string For asynchronous resource operations, the location header contains a URI that can be checked to track resource status changes.

Response Example

{
    "code": "302 Found",
    "message": "The resource was found at <a href=\"http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd\">http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd</a>;\nyou should be redirected automatically.\n\n",
    "title": "Found"
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources

List stack resources

Lists resources in a stack based on filtering parameters like resource name, status, type, action, id and physical_resource_id. These parameters could be used multiple times.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
type (Optional) query string Stack resource type. Valid resource types include OS::Cinder::Volume, OS::Nova::Server, OS::Neutron::Port and so on. This parameter can be specified more than once to filter results by multiple resource types.
status (Optional) query string Stack resource status. Valid resource statuses are COMPLETE, FAILED and IN_PROGRESS. This can be specified more than once to filter the results by multiple resource statuses.
name (Optional) query string Filters the result list by a resource name. You can use this filter multiple times to filter by multiple resource names.
action (Optional) query string Stack resource action. Valid resource actions are ADOPT, CHECK, CREATE, DELETE, INIT, RESTORE, RESUME, ROLLBACK, SNAPSHOT, SUSPEND, and UPDATE.
id (Optional) query string Filters the resource list by the logical ID of stack resources. Use this filter multiple times to filter by multiple resource IDs.
physical_resource_id (Optional) query string Filters the resource list by the ID of physical resource represented by a stack resource. Use this filter multiple times to filter by multiple physical resource IDs.
nested_depth (Optional) query integer Includes resources from nested stacks up to the nested_depth levels of recursion.
with_detail (Optional) query boolean Enables detailed resource information for each resource in list of resources.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
resources body array A list of resource objects.
creation_time body string

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.

links body array 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.
logical_resource_id body string The ID of the logical stack resource.
physical_resource_id body string The ID of the stack physical resource.
required_by body array The list of resources that require this stack resource.
resource_name body string The name of the resource.
resource_status body string The status of the resource.
resource_status_reason body string The reason for the current stack resource state.
resource_type body string The type name of the resource.
updated_time body string

The date and time when the object 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.

Response Example

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

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resource_name path string The name of a resource in the stack.
with_attr (Optional) query boolean Includes detailed resource information for the resource.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
resource body object Key and value pairs that contain stack resource properties.
attributes body object Key and value pairs that contain resource attributes.
creation_time body string

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.

description body string The description of the stack resource.
links body array A list of URLs for the resource. Each URL is a JSON object with an href key indicating the URL and a rel key indicating its relationship to the resource in question. There may be multiple links returned. The self relationship identifies the URL of the resource itself.
logical_resource_id body string The ID of the logical stack resource.
physical_resource_id body string The ID of the stack physical resource.
required_by body array The list of resources that require this stack resource.
resource_name body string The name of the resource.
resource_status body string The status of the resource.
resource_status_reason body string The reason for the current stack resource state.
resource_type body string The type name of the resource.
updated_time body string

The date and time when the object 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.

Response Example

{
    "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"
    }
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/metadata

Show resource metadata

Shows metadata for a resource.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resource_name path string The name of a resource in the stack.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
metadata body object The metadata of a resource.

Response Example

{
    "metadata": {
        "some_key": "some_value",
        "some_other_key": "some_other_value"
    }
}
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.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request The target resource doesn’t support receiving a signal.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

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

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resource_name path string The name of a resource in the stack.

Response Example

This operation does not return a response body.

PATCH
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name_or_physical_id}

Mark a resource as unhealthy

Mark the specified resource in the stack as unhealthy.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resource_name_or_physical_id path string The name of a resource in the stack, or the ID of its underlying physical resource.
mark_unhealthy body boolean A boolean indicating whether the target resource should be marked as unhealthy.
resource_status_reason (Optional) body string The reason for the current stack resource state.

Response Example

This operation does not return a response body.

Stack Outputs

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

List outputs

Lists outputs for a stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
outputs body array A list of stack outputs.
output_key body string The name of a stack output.
description body string A textual description of a stack output.

Response Example

{
    "outputs": [
        {
            "output_key": "output name",
            "description": "output description"
        }
    ]
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/outputs/{output_key}

Show output

Shows details for a stack output.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
output_key path string The key of a stack output.

Response Parameters

Name In Type Description
X-Openstack-Reqeuest-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
output body object An output record for the specified key.
output_key body string The name of a stack output.
output_value body string The value of a stack output.
description body string A textual description of a stack output.
output_error (Optional) body string The error in a stack output. This key only appears when an output has problem in resolving its value.

Response Example

{
    "output": {
        "output_key": "output_name",
        "output_value": "output_value",
        "description": "output description",
        "output_error": "error message"
    }
}

Stack Snapshots

POST
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots

Snapshot a stack

Takes a snapshot of all resources in a stack. All snapshots are deleted when the stack is deleted.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
name body string The name of the snapshot.

Request Example

{
    "name": "vol_snapshot"
}

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
creation_time body string

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.

data body object The snapshot data.
id body string The UUID of the snapshot.
name body string The name of the snapshot.
status body string The status of the snapshot.
status_reason body string The reason for the current snapshot status.

Response Example

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

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
snapshots body array A list of snapshots and their properties.
creation_time body string

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.

data body object The snapshot data.
id body string The UUID of the snapshot.
name body string The name of the snapshot.
status body string The status of the snapshot.
status_reason body string The reason for the current snapshot status.

Response Example

{
    "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
        }
    ]
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}

Show snapshot

Shows details for a snapshot.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
snapshot_id path string The UUID of the snapshot.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
snapshot body object Key and value pairs that contain snapshot properties.
creation_time body string

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.

data body object The snapshot data.
id body string The UUID of the snapshot.
name body string The name of the snapshot.
status body string The status of the snapshot.
status_reason body string The reason for the current snapshot status.

Response Example

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

Response Codes

Success

Code Reason
202 - Accepted Request was accepted for processing, but the processing has not been completed. A ‘location’ header is included in the response which contains a link to check the progress of the request.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
snapshot_id path string The UUID of the snapshot.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
code body string HTTP status code for a restore request. Usually 202 Accepted.
message body string The message in the response to a stack restore request.
title body string The title of the response to a stack restore request. e.g. Accepted.

Response Example

{
    "code": "202 Accepted",
    "message": "The request is accepted for processing.<br /><br />\n\n\n",
    "title": "Accepted"
}
DELETE
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/snapshots/{snapshot_id}

Delete a snapshot

Deletes a stack snapshot.

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
snapshot_id path string The UUID of the snapshot.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Response Example

The response to this API does not have a 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.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
suspend body string Specify the suspend action in the request body.

Request Example

{
    "suspend": null
}

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Response Example

This operation does not return a response body.

POST
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/actions

Resume stack

Resumes a suspended stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resume body string Specify the resume action in the request body.

Request Example

{
    "resume": null
}

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Response Example

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.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
cancel_update body string Specify the cancel_update action in the request body.

Request Example

{
    "cancel_update": null
}

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Response Example

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.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
check body string Specify the check action in the request body.

Request Example

{
    "check": null
}

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.

Response Example

This operation does not return a response body.

Events

The orchestration service provides APIs to check the events occurred on a stack or a specific resource in a stack.

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

List stack events

Lists events for a stack.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resource_action (Optional) query string Stack resource action. Valid resource actions are ADOPT, CHECK, CREATE, DELETE, INIT, RESTORE, RESUME, ROLLBACK, SNAPSHOT, SUSPEND, and UPDATE.
resource_status (Optional) query string Stack resource status. Valid resource statuses are COMPLETE, FAILED and IN_PROGRESS. This can be specified more than once to filter the results by multiple resource statuses.
resource_name (Optional) query string Filters the result list by a resource name. You can use this filter multiple times to filter by multiple resource names.
resource_type (Optional) query string Stack resource type. Valid resource types include OS::Cinder::Volume, OS::Nova::Server, OS::Neutron::Port and so on. This parameter can be specified more than once to filter results by multiple resource types.
limit (Optional) query integer 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 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 string Sorts the result list by keys specified in this parameter.
sort_dir (Optional) query string The sort direction of the list. A valid value is asc (ascending) or desc (descending).
nested_depth (Optional) query integer Includes resources from nested stacks up to the nested_depth levels of recursion.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
event_time body string The date and time when the event was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss, for example, 2015-08-27T09:49:58.
id body string The UUID of the event object.
links body array A list of URLs for the event. Each URL is a JSON object with an href key indicating the URL and a rel key indicating its relationship to the event in question. There may be multiple links returned. The self relationship identifies the URL of the event itself.
logical_resource_id body string The ID of the logical stack resource.
physical_resource_id body string The ID of the stack physical resource.
resource_name body string The name of the resource.
resource_status body string The status of the resource.
resource_status_reason body string The reason for the current stack resource state.

Response Example

{
    "events": [
        {
            "event_time": "2014-07-23T08:14:47Z",
            "id": "474bfdf0-a450-46ec-a78a-0c7faa404073",
            "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",
            "physical_resource_id": null,
            "resource_name": "port",
            "resource_status": "CREATE_FAILED",
            "resource_status_reason": "NotFound: Subnet f8a699d0-3537-429e-87a5-6b5a8d0c2bf0 could not be found"
        },
        {
            "event_time": "2014-07-23T08:14:47Z",
            "id": "66fa95b6-e6f8-4f05-b1af-e828f5aba04c",
            "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",
            "physical_resource_id": null,
            "resource_name": "port",
            "resource_status": "CREATE_IN_PROGRESS",
            "resource_status_reason": "state changed"
        }
    ]
}
GET
/v1/{tenant_id}/stacks/{stack_name}/events

Find stack events

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

Response Codes

Success

Code Reason
302 - Found The response is about a redirection hint. The header of the response usually contains a ‘location’ value where requesters can check to track the real location of the resource.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
location header string For asynchronous resource operations, the location header contains a URI that can be checked to track resource status changes.
code body string The response code to a resource find request. e.g. 302 Found.
message body string The message in the response to a resource find request.
title body string The title of the response to a resource find request. e.g. Found.

Response Example

{
    "code": "302 Found",
    "message": "The resource was found at <a href=\"http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd/events?sort_dir=asc\">http://192.168.42.11:8004/v1/369166a68a3a49b78b4e138531556e55/stacks/s1/da778f26-6d25-4634-9531-d438188e48fd/events?sort_dir=asc</a>;\nyou should be redirected automatically.\n\n",
    "title": "Found"
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events

List resource events

Lists events for a stack resource.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resource_name path string The name of a resource in the stack.
resource_action (Optional) query string Stack resource action. Valid resource actions are ADOPT, CHECK, CREATE, DELETE, INIT, RESTORE, RESUME, ROLLBACK, SNAPSHOT, SUSPEND, and UPDATE.
resource_status (Optional) query string Stack resource status. Valid resource statuses are COMPLETE, FAILED and IN_PROGRESS. This can be specified more than once to filter the results by multiple resource statuses.
resource_name (Optional) query string Filters the result list by a resource name. You can use this filter multiple times to filter by multiple resource names.
resource_type (Optional) query string Stack resource type. Valid resource types include OS::Cinder::Volume, OS::Nova::Server, OS::Neutron::Port and so on. This parameter can be specified more than once to filter results by multiple resource types.
limit (Optional) query integer 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 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 string Sorts the result list by keys specified in this parameter.
sort_dir (Optional) query string The sort direction of the list. A valid value is asc (ascending) or desc (descending).
nested_depth (Optional) query integer Includes resources from nested stacks up to the nested_depth levels of recursion.

Response Example

{
    "events": [
        {
            "event_time": "2014-07-23T08:14:47Z",
            "id": "474bfdf0-a450-46ec-a78a-0c7faa404073",
            "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",
            "physical_resource_id": null,
            "resource_name": "port",
            "resource_status": "CREATE_FAILED",
            "resource_status_reason": "NotFound: Subnet f8a699d0-3537-429e-87a5-6b5a8d0c2bf0 could not be found"
        },
        {
            "event_time": "2014-07-23T08:14:47Z",
            "id": "66fa95b6-e6f8-4f05-b1af-e828f5aba04c",
            "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",
            "physical_resource_id": null,
            "resource_name": "port",
            "resource_status": "CREATE_IN_PROGRESS",
            "resource_status_reason": "state changed"
        }
    ]
}
GET
/v1/{tenant_id}/stacks/{stack_name}/{stack_id}/resources/{resource_name}/events/{event_id}

Show event details

Shows details for an event.

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
stack_name path string The name of a stack.
stack_id path string The UUID of the stack.
resource_name path string The name of a resource in the stack.
event_id path string The UUID of the event that is related to the resource in the stack.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
event body object An map containing the name and values of event properties.
event_time body string The date and time when the event was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss, for example, 2015-08-27T09:49:58.
id body string The UUID of the event object.
links body array A list of URLs for the event. Each URL is a JSON object with an href key indicating the URL and a rel key indicating its relationship to the event in question. There may be multiple links returned. The self relationship identifies the URL of the event itself.
logical_resource_id body string The ID of the logical stack resource.
physical_resource_id body string The ID of the stack physical resource.
resource_name body string The name of the resource.
resource_properties body object A map containing the properties of the resource associated with the event.
resource_status body string The status of the resource.
resource_status_reason body string The reason for the current stack resource state.
resource_type body string The type name of the resource.

Response Example

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

Templates

GET
/v1/{tenant_id}/template_versions

List template versions

Lists all available template versions.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.

Response Parameters

Name In Type Description
X-Openstack-Request_id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
template_versions body array A list of template version object each describes the type name and version information for a template version.
alias body array The alias of a template version. For newer template versions supported, the orchestration service is moving away from template versioning using release date (which is hard to remember). Newer versions are named after the OpenStack release code name. For example, heat_template_version.newton.
type body string The type of the template version which can be cfn or hot.
version body string The version string of the template format.

Response Example

{
    "template_versions": [
        {
            "aliases": [],
            "version": "AWSTemplateFormatVersion.2010-09-09",
            "type": "cfn"
        },
        {
            "aliases": [],
            "version": "HeatTemplateFormatVersion.2012-12-12",
            "type": "cfn"
        },
        {
            "aliases": [],
            "version": "heat_template_version.2013-05-23",
            "type": "hot"
        },
        {
            "aliases": [],
            "version": "heat_template_version.2014-10-16",
            "type": "hot"
        },
        {
            "aliases": [],
            "version": "heat_template_version.2015-04-30",
            "type": "hot"
        },
        {
            "aliases": [],
            "version": "heat_template_version.2015-10-15",
            "type": "hot"
        },
        {
            "aliases": [],
            "version": "heat_template_version.2016-04-08",
            "type": "hot"
        },
        {
            "aliases": ["heat_template_version.newton"],
            "version": "heat_template_version.2016-10-14",
            "type": "hot"
        },
        {
            "aliases": ["heat_template_version.ocata"],
            "version": "heat_template_version.2017-02-24",
            "type": "hot"
        }
    ]
}
GET
/v1/{tenant_id}/template_versions/{template_version}/functions

List template functions

Lists all available functions for a template version.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
template_version path string The version of the heat template.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
template_functions body array A list of template function descriptors.
description body string The textual description about the usage of the template function.
functions body string The name of a function supported by the specified template version.

Response Example

{
    "template_functions": [
        {
            "functions": "Fn::Select",
            "description": "A function for selecting an item from a list or map."
        },
        {
            "functions": "repeat",
            "description": "A function for iterating over a list of items."
        },
        {
            "functions": "resource_facade",
            "description": "A function for retrieving data in a parent provider template."
        },
        {
            "functions": "list_join",
            "description": "A function for joining strings."
        },
        {
            "functions": "str_replace",
            "description": "A function for performing string substitutions."
        },
        {
            "functions": "get_attr",
            "description": "A function for resolving resource attributes."
        },
        {
            "functions": "get_param",
            "description": "A function for resolving parameter references."
        },
        {
            "functions": "get_file",
            "description": "A function for including a file inline."
        },
        {
            "functions": "digest",
            "description": "A function for performing digest operations."
        },
        {
            "functions": "get_resource",
            "description": "A function for resolving resource references."
        }
    ]
}
POST
/v1/{tenant_id}/validate

Validate template

Validates a template.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
environment (Optional) body object A JSON environment for the stack.
environment_files (Optional) body object An ordered list of names for environment files found in the files dict.
files (Optional) body object

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.

ignore_errors (Optional) query string List of comma separated error codes to ignore.
show_nested (Optional) query boolean Set to true to include nested stacks in the list.
template (Optional) body object

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.

template_url (Optional) body 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.

Request Example

{
    "template_url": "/PATH_TO_HEAT_TEMPLATES/WordPress_Single_Instance.template"
}

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
Description body string The description specified in the template.
ParameterGroups (Optional) body array A list of parameter groups. Each group contains a list of parameter names.
Parameters body object Key and value pairs that contain CFN template parameters.

Response Example

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

Software configuration

POST
/v1/{tenant_id}/software_configs

Create configuration

Creates a software configuration.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
inputs (Optional) body array Schema that represents the inputs that this software configuration expects.
group (Optional) body 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 body string The name of the software configuration.
outputs (Optional) body array Schema that represents the outputs that this software configuration produces.
config (Optional) body string Configuration script or manifest that defines which configuration is performed.
options (Optional) body string Map that contains options that are specific to the configuration management tool that this resource uses.
tenant_id path string The UUID of the tenant. A tenant is also known as a project.

Request Example

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

Response Parameters

Name In Type Description
id body string The UUID of the configuration.
inputs (Optional) body array Schema that represents the inputs that this software configuration expects.
group (Optional) body 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 body string The name of the software configuration.
outputs (Optional) body array Schema that represents the outputs that this software configuration produces.
creation_time body string

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_time body string

The date and time when the object 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.

config (Optional) body string Configuration script or manifest that defines which configuration is performed.
options (Optional) body string Map that contains options that are specific to the configuration management tool that this resource uses.
software_config body object The software_config object.

Response Example

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

List configs

Lists all available software configurations.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
limit (Optional) query integer 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 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.

Response Parameters

Name In Type Description
creation_time body string

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.

group (Optional) body 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.
id body string The UUID of the configuration.
name body string The name of the software configuration.
software_configs body array A list of software_config objects.

Response Example

{
    "software_configs": [{
        "group": "script",
        "name": "a-config-we5zpvyu7b5o",
        "creation_time": "2015-01-31T15:12:36Z",
        "id": "ddee7aca-aa32-4335-8265-d436b20db4f1",
    }]
}
GET
/v1/{tenant_id}/software_configs/{config_id}

Show configuration details

Shows details for a software configuration.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
config_id path string The UUID of the configuration.

Response Parameters

Name In Type Description
config (Optional) body string Configuration script or manifest that defines which configuration is performed.
creation_time body string

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.

group (Optional) body 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.
id body string The UUID of the configuration.
inputs (Optional) body array Schema that represents the inputs that this software configuration expects.
name body string The name of the software configuration.
options (Optional) body string Map that contains options that are specific to the configuration management tool that this resource uses.
outputs (Optional) body array Schema that represents the outputs that this software configuration produces.
software_config body object The software_config object.

Response Example

{
    "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
    }
}
DELETE
/v1/{tenant_id}/software_configs/{config_id}

Delete config

Deletes a software configuration.

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
config_id path string The UUID of the configuration.
POST
/v1/{tenant_id}/software_deployments

Create deployment

Creates a software deployment.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
action (Optional) body string The stack action that triggers this deployment resource.
config_id body string The UUID of the software configuration resource that runs when applying to the server.
input_values (Optional) body object A dict comprises of input data as key-value pairs.
server_id body string The UUID of the compute server to which the configuration applies.
stack_user_project_id (Optional) body string Authentication project ID, which can also perform operations on this deployment.
status (Optional) body string Current status of the deployment. A valid value is COMPLETE, IN_PROGRESS, or FAILED.
status_reason (Optional) body string The reason for the current deployment status.

Request Example

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

Response Parameters

Name In Type Description
action (Optional) body string The stack action that triggers this deployment resource.
config_id body string The UUID of the software configuration resource that runs when applying to the server.
creation_time body string

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.

id body string The UUID of the software deployment.
input_values (Optional) body object A dict comprises of input data as key-value pairs.
output_values body object A dict comprised of the output data from a software deployment.
server_id body string The UUID of the compute server to which the configuration applies.
software_deployment body object The software_deployment object.
status (Optional) body string Current status of the deployment. A valid value is COMPLETE, IN_PROGRESS, or FAILED.
status_reason (Optional) body string The reason for the current deployment status.
updated_time (Optional) body string

The date and time when the software deployment 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.

Response Example

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

List deployments

Lists all available software deployments.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
server_id (Optional) query string The UUID of the target server.

Response Parameters

Name In Type Description
action (Optional) body string The stack action that triggers this deployment resource.
config_id body string The UUID of the software configuration resource that runs when applying to the server.
creation_time body string

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.

id body string The UUID of the software deployment.
input_values (Optional) body object A dict comprises of input data as key-value pairs.
output_values body object A dict comprised of the output data from a software deployment.
server_id body string The UUID of the compute server to which the configuration applies.
software_deployments body array A list of software_deployment objects.
status (Optional) body string Current status of the deployment. A valid value is COMPLETE, IN_PROGRESS, or FAILED.
status_reason (Optional) body string The reason for the current deployment status.
updated_time (Optional) body string

The date and time when the software deployment 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.

Response Example

{
    "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"
        }
    ]
}
GET
/v1/{tenant_id}/software_deployments/{deployment_id}

Show deployment details

Shows details for a software deployment.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
deployment_id path string The UUID of the deployment.

Response Parameters

Name In Type Description
action (Optional) body string The stack action that triggers this deployment resource.
config_id body string The UUID of the software configuration resource that runs when applying to the server.
creation_time body string

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.

id body string The UUID of the software deployment.
input_values (Optional) body object A dict comprises of input data as key-value pairs.
output_values body object A dict comprised of the output data from a software deployment.
server_id body string The UUID of the compute server to which the configuration applies.
software_deployment body object The software_deployment object.
status (Optional) body string Current status of the deployment. A valid value is COMPLETE, IN_PROGRESS, or FAILED.
status_reason (Optional) body string The reason for the current deployment status.
updated_time (Optional) body string

The date and time when the software deployment 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.

Response Example

{
    "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"
    }
}
PUT
/v1/{tenant_id}/software_deployments/{deployment_id}

Update deployment

Updates a software deployment.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
deployment_id path string The UUID of the deployment.
action (Optional) body string The stack action that triggers this deployment resource.
config_id body string The UUID of the software configuration resource that runs when applying to the server.
input_values (Optional) body object A dict comprises of input data as key-value pairs.
output_values body object A dict comprised of the output data from a software deployment.
status (Optional) body string Current status of the deployment. A valid value is COMPLETE, IN_PROGRESS, or FAILED.
status_reason (Optional) body string The reason for the current deployment status.

Request Example

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

Response Parameters

Name In Type Description
action (Optional) body string The stack action that triggers this deployment resource.
config_id body string The UUID of the software configuration resource that runs when applying to the server.
creation_time body string

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.

id body string The UUID of the software deployment.
input_values (Optional) body object A dict comprises of input data as key-value pairs.
output_values body object A dict comprised of the output data from a software deployment.
server_id body string The UUID of the compute server to which the configuration applies.
software_deployments body array A list of software_deployment objects.
status (Optional) body string Current status of the deployment. A valid value is COMPLETE, IN_PROGRESS, or FAILED.
status_reason (Optional) body string The reason for the current deployment status.
updated_time (Optional) body string

The date and time when the software deployment 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.

Response Example

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

Response Codes

Success

Code Reason
204 - No Content The server has fulfilled the request by deleting the resource.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
deployment_id path string The UUID of the deployment.
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
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.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.
500 - Internal Server Error Something went wrong inside the service. This should not happen usually. If it does happen, it means the server has experienced some serious problems.

Request Parameters

Name In Type Description
server_id path string The UUID of the server for which to fetch server configuration metadata.
tenant_id path string The UUID of the tenant. A tenant is also known as a project.

Response Parameters

Name In Type Description
config (Optional) body string Configuration script or manifest that defines which configuration is performed.
creation_time body string

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.

group (Optional) body 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.
id body string The UUID of the configuration.
inputs (Optional) body array Schema that represents the inputs that this software configuration expects.
metadata body array The metadata about a software deployment.
name body string The name of the software configuration.
options (Optional) body string Map that contains options that are specific to the configuration management tool that this resource uses.
outputs (Optional) body array Schema that represents the outputs that this software configuration produces.
updated_time body string

The date and time when the object 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.

Response Example

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

Resource Types

GET
/v1/{tenant_id}/resource_types

List resource types

Lists all supported template resource types.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
name (Optional) query 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.
support_status (Optional) query string Filters the response by resource types by a support status. Valid support status values are UNKNOWN, SUPPORTED, DEPRECATED, UNSUPPORTED, and HIDDEN.
version (Optional) query string Filters the list of resource types by heat version. For example, 2016.1 or 5.0.0.
with_description (Optional) query boolean Either display resource type’s description or not.

Response Parameters

Note that the format of the response from this API varies when different query parameters are specified. The default response has the following format:

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
resource_types body array A list of resource type names.

When with_description is specified, the response has the following format:

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
resource_types body array A list of objects each of which provides the resource type name and a textual description about the type.
resource_type body string The type name of the resource.
description body string The textual description of the resource type.

Response Example

The following is an example of the simple response:

{
    "resource_types": [
        "AWS::EC2::Instance",
        "OS::Heat::ScalingPolicy",
        "AWS::CloudFormation::Stack"
    ]
}

The following is an example of the response when with_description is specified:

{
    "resource_types": [
        {
            "description": "No description given",
            "resource_type": "AWS::EC2::Instance"
        },
        {
            "description": "Resource for defining which resources can be accessed by users.\n\nNOTE: Now this resource is actually associated with an AWS user resource,\nnot any OS:: resource though it is registered under the OS namespace below.\n\nResource for defining resources that users are allowed to access by the\nDescribeStackResource API.\n",
            "resource_type": "OS::Heat::AccessPolicy"
        },
        {
            "description": "A resource to manage scaling of `OS::Heat::AutoScalingGroup`.\n\n**Note** while it may incidentally support\n`AWS::AutoScaling::AutoScalingGroup` for now, please do not use it for that\npurpose and use `AWS::AutoScaling::ScalingPolicy` instead.\n\nResource to manage scaling for `OS::Heat::AutoScalingGroup`, i.e. define\nwhich metric should be scaled and scaling adjustment, set cooldown etc.\n",
            "resource_type": "OS::Heat::ScalingPolicy"
        },
        {
            "description": "Represents a child stack to allow composition of templates.",
            "resource_type": "AWS::CloudFormation::Stack"
        },
        {
            "description": "Heat Template Resource for Keystone Group.\n\nGroups are a container representing a collection of users. A group itself\nmust be owned by a specific domain, and hence all group names are not\nglobally unique, but only unique to their domain.\n",
            "resource_type": "OS::Keystone::Group"
        }
    ]
}
GET
/v1/{tenant_id}/resource_types/{type_name}/template

Show resource type 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.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
type_name path string The name of a resource type.
template_type (Optional) query string Specify the resource template type. The valid types are: cfn, hot.

Response Parameters

The format of the response varies when template_type is set to different values. When it is set to cfn or omitted, the response has the following format:

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
Description body string The description specified in the template.
Outputs body object Key and value pairs that contain output data for a CFN template.
HeatTemplateFormatVersion body string The version of the orchestration CFN template.
Parameters body object Key and value pairs that contain CFN template parameters.
Resources body object A map containging all resource definitions for the resource template.

When the template_type is explicitly set to hot, the response has the following format:

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
heat_template_version body string The version of the orchestration HOT template.
description body string The description of the stack template.
outputs body object Key and value pairs that contain output data.
parameters body object Key and value pairs that contain the schemas of parameters acceptable by the template.
resources body object Key and value pairs that contain definition of resources in the template.

Response Example

The following is a sample of the response when template_type is set to cfn or omitted:

{
    "Description": "Initial template of KeyPair",
    "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\"]}"
        },
        "show": {
            "Description": "Detailed information about resource.",
            "Value": "{\"Fn::GetAtt\": [\"KeyPair\", \"show\"]}"
        }
    },
    "Parameters": {
        "name": {
            "Description": "The name of the key pair.",
            "MaxLength": 255,
            "MinLength": 1,
            "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": "Boolean"
        }
    },
    "Resources": {
        "KeyPair": {
            "Properties": {
                "name": {
                    "Ref": "name"
                },
                "public_key": {
                    "Ref": "public_key"
                },
                "save_private_key": {
                    "Ref": "save_private_key"
                }
            },
            "Type": "OS::Nova::KeyPair"
        }
    }
}

The following is a sample of the response when template_type is explicitly set to hot:

{
    "description": "Initial template of KeyPair",
    "heat_template_version": "2016-10-14",
    "outputs": {
        "private_key": {
            "description": "The private key if it has been saved.",
            "value": "{\"get_attr\": [\"KeyPair\", \"private_key\"]}"
        },
        "public_key": {
            "description": "The public key.",
            "value": "{\"get_attr\": [\"KeyPair\", \"public_key\"]}"
        },
        "show": {
            "description": "Detailed information about resource.",
            "value": "{\"get_attr\": [\"KeyPair\", \"show\"]}"
        }
    },
    "parameters": {
        "name": {
            "constraints": [
                {
                    "length": {
                        "max": 255,
                        "min": 1
                    }
                }
            ],
            "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": {
            "default": false,
            "description": "True if the system should remember a generated private key; False otherwise.",
            "type": "boolean"
        }
    },
    "resources": {
        "KeyPair": {
            "properties": {
                "name": {
                    "get_param": "name"
                },
                "public_key": {
                    "get_param": "public_key"
                },
                "save_private_key": {
                    "get_param": "save_private_key"
                }
            },
            "type": "OS::Nova::KeyPair"
        }
    }
}
GET
/v1/{tenant_id}/resource_types/{type_name}

Show resource type 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.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
400 - Bad Request Some content in the request was invalid.
401 - Unauthorized User must authenticate before making a request.
404 - Not Found The requested resource could not be found.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.
type_name path string The name of a resource type.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
attributes body object Key and value pairs that contain resource attributes.
properties body object The properties of the resource. Includes description, type, and so on.
resource_type body string The type name of the resource.
support_status body object Information about the current support status of a resource type.

Response Example

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

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, binary, topic name, host, report interval, last updated time, health status, and host name.

Response Codes

Success

Code Reason
200 - OK Request was successful.

Error

Code Reason
403 - Forbidden Policy does not allow current user to do this operation.
503 - Service Unavailable Service is not available. This is mostly caused by service configuration errors which prevents the service from successful start up.

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.

Request Parameters

Name In Type Description
tenant_id path string The UUID of the tenant. A tenant is also known as a project.

Response Parameters

Name In Type Description
X-Openstack-Request-Id header string A unique ID for tracking service request. The request ID associated with the request by default appears in the service logs.
services body array A list of heat engines.
binary body string The name of the binary executable of the heat engine.
created_at body string The date and time when the service engine was created.
deleted_at body string The date and time when the service engine was deleted.
engine_id body string The UUID of the engine service.
host body string The host on which the service engine is or was running.
hostname body string The name of the host for the service engine.
id body string The UUID of the heat engine service record. Note that each service engine may have multiple records in the service registry.
report_interval body integer The polling interval, in seconds. The API reports events at this interval until heat engine creation completes.
status body string The status of the heat engine.
topic body string The messaging topic of the heat engine.
updated_at body string The date and time when the service engine was updated.

Response Example

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

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.