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.

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.

files_container (Optional)

body

string

Name of the container in swift that has child templates and environment files.

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

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.

environment_files (Optional)

body

object

An ordered list of names for environment files found in the files dict.

files_container (Optional)

body

string

Name of the container in swift that has child templates and environment files.

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

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

files_container (Optional)

body

string

Name of the container in swift that has child templates and environment files.

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.

files_container (Optional)

body

string

Name of the container in swift that has child templates and environment files.

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.

files_container (Optional)

body

string

Name of the container in swift that has child templates and environment files.

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.

files_container (Optional)

body

string

Name of the container in swift that has child templates and environment files.

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

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

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

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

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

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

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

Cancel stack create/update without rollback

Cancels a currently running create/update of a stack without rollback.

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_without_rollback

body

string

Specify the cancel_without_rollback action in the request body..

Request Example

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

Parameter schema in CFN format.

Environment (Optional)

body

object

Environment for the stack, where multiple environment files are provided this will be the merged result.

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"
            ]
        }
    ],
    "Environment": {
        "event_sinks": [],
        "parameter_defaults": {},
        "parameters": {},
        "resource_registry": {
            "resources": {}
        }
    }
}

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

Parameter schema in CFN format.

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:

{
    "HeatTemplateFormatVersion": "2012-12-12",
    "Description": "Initial template of KeyPair",
    "Parameters": {
        "public_key": {
            "Type": "String",
            "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."
        },
        "save_private_key": {
            "Default": false,
            "Type": "Boolean",
            "Description": "True if the system should remember a generated private key; False otherwise.",
            "AllowedValues": [
                "True",
                "true",
                "False",
                "false"
            ]
        },
        "type": {
            "Type": "String",
            "Description": "Keypair type. Supported since Nova api version 2.2.",
            "AllowedValues": [
                "ssh",
                "x509"
            ]
        },
        "user": {
            "Type": "String",
            "Description": "ID or name of user to whom to add key-pair. The usage of this property is limited to being used by administrators only. Supported since Nova api version 2.10."
        },
        "name": {
            "MinLength": 1,
            "Type": "String",
            "Description": "The name of the key pair.",
            "MaxLength": 255
        }
    },
    "Resources": {
        "KeyPair": {
            "Type": "OS::Nova::KeyPair",
            "Properties": {
                "public_key": {
                    "Ref": "public_key"
                },
                "save_private_key": {
                    "Ref": "save_private_key"
                },
                "type": {
                    "Ref": "type"
                },
                "user": {
                    "Ref": "user"
                },
                "name": {
                    "Ref": "name"
                }
            }
        }
    },
    "Outputs": {
        "public_key": {
            "Description": "The public key.",
            "Value": {
                "Fn::GetAtt": [
                    "KeyPair",
                    "public_key"
                ]
            }
        },
        "private_key": {
            "Description": "The private key if it has been saved.",
            "Value": {
                "Fn::GetAtt": [
                    "KeyPair",
                    "private_key"
                ]
            }
        },
        "OS::stack_id": {
            "Value": {
                "Ref": "KeyPair"
            }
        },
        "show": {
            "Description": "Detailed information about resource.",
            "Value": {
                "Fn::GetAtt": [
                    "KeyPair",
                    "show"
                ]
            }
        }
    }
}

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

{
    "heat_template_version": "2016-10-14",
    "description": "Initial template of KeyPair",
    "parameters": {
        "public_key": {
            "type": "string",
            "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."
        },
        "save_private_key": {
            "default": false,
            "type": "boolean",
            "description": "True if the system should remember a generated private key; False otherwise."
        },
        "type": {
            "type": "string",
            "description": "Keypair type. Supported since Nova api version 2.2.",
            "constraints": [
                {
                    "allowed_values": [
                        "ssh",
                        "x509"
                    ]
                }
            ]
        },
        "user": {
            "type": "string",
            "description": "ID or name of user to whom to add key-pair. The usage of this property is limited to being used by administrators only. Supported since Nova api version 2.10.",
            "constraints": [
                {}
            ]
        },
        "name": {
            "type": "string",
            "description": "The name of the key pair.",
            "constraints": [
                {
                    "length": {
                        "max": 255,
                        "min": 1
                    }
                }
            ]
        }
    },
    "resources": {
        "KeyPair": {
            "type": "OS::Nova::KeyPair",
            "properties": {
                "public_key": {
                    "get_param": "public_key"
                },
                "save_private_key": {
                    "get_param": "save_private_key"
                },
                "type": {
                    "get_param": "type"
                },
                "user": {
                    "get_param": "user"
                },
                "name": {
                    "get_param": "name"
                }
            }
        }
    },
    "outputs": {
        "public_key": {
            "description": "The public key.",
            "value": {
                "get_attr": [
                    "KeyPair",
                    "public_key"
                ]
            }
        },
        "private_key": {
            "description": "The private key if it has been saved.",
            "value": {
                "get_attr": [
                    "KeyPair",
                    "private_key"
                ]
            }
        },
        "OS::stack_id": {
            "value": {
                "get_resource": "KeyPair"
            }
        },
        "show": {
            "description": "Detailed information about resource.",
            "value": {
                "get_attr": [
                    "KeyPair",
                    "show"
                ]
            }
        }
    }
}
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.",
            "type": "string"
        }
    },
    "properties": {
        "a_property": {
            "constraints": [
                {
                    "description": "Must be between 1 and 255 characters",
                    "length": {
                        "max": 255,
                        "min": 1
                    }
                }
            ],
            "description": "A resource property description.",
            "required": true,
            "type": "string",
            "update_allowed": false,
            "immutable": false
        }
    },
    "resource_type": "OS::Heat::AResourceName",
    "support_status": {
        "message": "A status message",
        "status": "SUPPORTED",
        "version": "10.0.0"
    }
}

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