Stack operations#
Use the stack operations to view and manage stacks for a Rackspace Cloud account.
Create stack#
POST /v1/{tenant_id}/stacks
Creates a stack.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 201 | Created | The request has been fulfilled and resulted in a new resource being created. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
This table shows the body parameters for the request:
| Name | Type | Description |
|---|---|---|
| stack_name | String (Required) | A name for the new stack. This value
must be unique within a project. The
name must start with an ASCII letter
and can contain ASCII letters,
digits, underscores, periods, and
hyphens. Specifically, the name must
match the ^[a-zA-Z][a-zA-Z0-9_.-
]*$ regular expression. When you
delete or abandon a stack, its name
might not be available for reuse for
an unspecified period of time. |
| template_url | String (Optional) | A URI to the location containing the
stack template on which to perform
the specified operation. See the
description of the template
parameter for information about the
expected template content located at
the URI. This parameter is only
required when you omit the
template parameter. If you
specify both parameters, this
parameter is ignored. |
| template | String (Optional) | The stack template on which to
perform the specified operation. This
parameter is always provided as a
string in the JSON request body.
The content of the string is a JSON-
or YAML-formatted Orchestration
template. For example: "template":
{ "heat_template_version": "2013-05-
23", ...} This parameter is
required only when you omit the
template_url parameter. If you
specify both parameters, this value
overrides the template_url
parameter value. |
| files | Map (Optional) | Supplies the contents of files
referenced in the template or the
environment. Stack templates and
resource templates can explicitly
reference files by using the
get_file intrinsic function. In
addition, the environment
parameter can contain implicit
references to files. The value is a
JSON object, where each key is a
relative or absolute URI which serves
as the name of a file, and the
associated value provides the
contents of the file. The following
code shows the general structure of
this parameter. { ... "files": {
"fileA.yaml": "Contents of the file",
"file:///usr/fileB.template":
"Contents of the file",
"http://example.com/fileC.template":
"Contents of the file" } ... }
Additionally, some template authors
encode their user data in a local
file. The Orchestration client
examines the template for the
get_file intrinsic function and
adds an entry to the files map
with the path to the file as the name
and the file contents as the value.
So, a simple example looks like this:
{ "files": { "myfile":
"#!/bin/bash\necho \"Hello world\" >
/root/testfile.txt" }, ...,
"stack_name": "teststack",
"template": { ..., "resources": {
"my_server": { "type":
"OS::Nova::Server", "properties": {
..., "user_data": { "get_file":
"myfile" } } } } }, "timeout_mins":
60 } Do not use this parameter to
provide the content of the template
located at the address specified by
template_url. Instead, use the
template parameter to supply the
template content as part of the
request. |
| parameters | Object (Optional) | Supplies arguments for parameters
defined in the stack template. The
value is a JSON object, where each
key is the name of a parameter
defined in the template and the
associated value is the argument to
use for that parameter when
instantiating the template. The
following code shows the general
structure of this parameter. In the
example, a and b would be the
names of two parameters defined in
the template. { ... "parameters": {
"a": "Value", "b": "3" } ... }
While the service accepts JSON
numbers for parameters with the type
number and JSON objects for
parameters with the type json,
all parameter values are converted to
their string representation for
storage in the created Stack. Clients
are encouraged to send all parameter
values using their string
representation for consistency
between requests and responses from
the Orchestration service. A value
must be provided for each template
parameter which does not specify a
default value. However, this
parameter is not allowed to contain
JSON properties with names that do
not match a parameter defined in the
template. The files parameter
maps logical file names to file
contents. Both the get_file
intrinsic function and provider
template functionality use this
mapping. When you want to use a
provider template, for example, the
Orchestration service adds an entry
to the files map by using: * The
URL of the provider template as the
name. * The contents of that file as
the value. Additionally, some
template authors encode their user
data in a local file. The
Orchestration client examines the
template for the get_file
intrinsic function and adds an entry
to the files map with the path to
the file as the name and the file
contents as the value. So, a simple
example looks like this: { "files":
{ "myfile": "#!/bin/bash\necho
\"Hello world\" > /root/testfile.txt"
}, ..., "stack_name": "teststack",
"template": { ..., "resources": {
"my_server": { "type":
"OS::Nova::Server", "properties": {
..., "user_data": { "get_file":
"myfile" } } } } }, "timeout_mins":
60 } |
| tags | String (Optional) | One or more simple string tags to
associate with the stack. To
associate multiple tags with a stack,
separate the tags with commas. For
example, tag1,tag2. |
| parameters.param_name-n | String (Optional) | User-defined parameter names to pass to the template. |
| parameters.param_value-n | String (Optional) | User-defined parameter values to pass to the template. |
Example Create stack: JSON request
{
"files": {},
"disable_rollback": true,
"parameters": {
"flavor": "2 GB General Purpose v1"
},
"stack_name": "teststack",
"template": {
"heat_template_version": "2013-05-23",
"description": "Simple template to test heat commands",
"parameters": {
"flavor": {
"default": "1 GB General Purpose v1",
"type": "string"
}
},
"resources": {
"hello_world": {
"type": "OS::Nova::Server",
"properties": {
"key_name": "heat_key",
"flavor": {
"get_param": "flavor"
},
"image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
"user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
}
}
}
},
"timeout_mins": 60
}
Response#
This table shows the body parameters for the response:
| Name | Type | Description |
|---|---|---|
| stack_name | String (Required) | The name of the stack to create. |
| template_url | String (Required) | The URL of the template. |
| template | String (Required) | A JSON template. |
| environment | String (Optional) | A JSON environment for the stack. |
| files | String (Optional) | A map of file names to JSON template bodies. File names are provider resource templates, as referenced in the environment. |
| parameters.param_name- n | String (Optional) | User-defined parameter names to pass to the template. |
| parameters.param_value-n | String (Optional) | User-defined parameter values to pass to the template. |
| timeout_mins | Integer (Optional) | The timeout for stack creation in minutes. |
| disable_rollback | String (Optional) | Enables or disables
deletion of all
previously-created stack
resources when stack
creation fails. Set to
True to keep all
previously-created stack
resources when stack
creation fails. Set to
False to delete all
previously-created stack
resources when stack
creation fails. Default
is True. |
| stack_id | String (Required) | The system-assigned ID for the stack. |
| links | String (Required) | A list of URLs for the stack. |
| rel | String (Required) | A reference to the
stack's parent. If no
parent, reference is
self. |
Example Create stack: JSON response
{
"stack": {
"id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"links": [
{
"href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"rel": "self"
}
]
}
}
Adopt stack#
POST /v1/{tenant_id}/stacks
Creates a stack from existing resources.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 201 | Created | The request has been fulfilled and resulted in a new resource being created. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
This table shows the body parameters for the request:
| Name | Type | Description |
|---|---|---|
| stack_name | String (Required) | A name for the new stack. The value
must be unique within a project. The
name must start with an ASCII letter
and can contain ASCII letters,
digits, underscores, periods, and
hyphens. Specifically, the name must
match the ^[a-zA-Z][a-zA-Z0-9_.-
]*$ regular expression. When you
delete or abandon a stack, its name
might not be available for reuse for
an unspecified period of time. |
| template_url | String (Optional) | A URI to the location containing the
stack template on which to perform
the specified operation. See the
description of the template
parameter for information about the
expected template content located at
the URI. This parameter is only
required when you omit the
template parameter. If you
specify both parameters, this
parameter is ignored. |
| template | String (Optional) | The stack template on which to
perform the specified operation. This
parameter is always provided as a
string in the JSON request body.
The content of the string is a JSON-
or YAML-formatted Orchestration
template. For example: "template":
{ "heat_template_version": "2013-05-
23", ...} This parameter is
required only when you omit the
template_url parameter. If you
specify both parameters, this value
overrides the template_url
parameter value. |
| environment | String (Optional) | A JSON environment for the stack. |
| files | Map (Optional) | Supplies the contents of files
referenced in the template or the
environment. Stack templates and
resource templates can explicitly
reference files by using the
get_file intrinsic function. In
addition, the environment
parameter can contain implicit
references to files. The value is a
JSON object, where each key is a
relative or absolute URI which serves
as the name of a file, and the
associated value provides the
contents of the file. The following
code shows the general structure of
this parameter. { ... "files": {
"fileA.yaml": "Contents of the file",
"file:///usr/fileB.template":
"Contents of the file",
"http://example.com/fileC.template":
"Contents of the file" } ... }
Additionally, some template authors
encode their user data in a local
file. The Orchestration client
examines the template for the
get_file intrinsic function and
adds an entry to the files map
with the path to the file as the name
and the file contents as the value.
So, a simple example looks like this:
{ "files": { "myfile":
"#!/bin/bash\necho \"Hello world\" >
/root/testfile.txt" }, ...,
"stack_name": "teststack",
"template": { ..., "resources": {
"my_server": { "type":
"OS::Nova::Server", "properties": {
..., "user_data": { "get_file":
"myfile" } } } } }, "timeout_mins":
60 } Do not use this parameter to
provide the content of the template
located at the address specified by
template_url. Instead, use the
template parameter to supply the
template content as part of the
request. |
| parameters | Object (Optional) | Supplies arguments for parameters
defined in the stack template. The
value is a JSON object, where each
key is the name of a parameter
defined in the template and the
associated value is the argument to
use for that parameter when
instantiating the template. The
following code shows the general
structure of this parameter. In the
example, a and b would be the
names of two parameters defined in
the template. { ... "parameters": {
"a": "Value", "b": "3" } ... }
While the service accepts JSON
numbers for parameters with the type
number and JSON objects for
parameters with the type json,
all parameter values are converted to
their string representation for
storage in the created Stack. Clients
are encouraged to send all parameter
values using their string
representation for consistency
between requests and responses from
the Orchestration service. A value
must be provided for each template
parameter which does not specify a
default value. However, this
parameter is not allowed to contain
JSON properties with names that do
not match a parameter defined in the
template. The files parameter
maps logical file names to file
contents. Both the get_file
intrinsic function and provider
template functionality use this
mapping. When you want to use a
provider template, for example, the
Orchestration service adds an entry
to the files map by using: * The
URL of the provider template as the
name. * The contents of that file as
the value. Additionally, some
template authors encode their user
data in a local file. The
Orchestration client examines the
template for the get_file
intrinsic function and adds an entry
to the files map with the path to
the file as the name and the file
contents as the value. So, a simple
example looks like this: { "files":
{ "myfile": "#!/bin/bash\necho
\"Hello world\" > /root/testfile.txt"
}, ..., "stack_name": "teststack",
"template": { ..., "resources": {
"my_server": { "type":
"OS::Nova::Server", "properties": {
..., "user_data": { "get_file":
"myfile" } } } } }, "timeout_mins":
60 } |
| timeout_mins | String (Optional) | The timeout for stack creation in minutes. |
| adopt_stack_data | String (Required) | Existing resources data to adopt a
stack. Data returned by abandon stack
could be provided as
adopt_stack_data. |
| disable_rollback | String (Optional) | Enables or disables deletion of all
stack resources when stack creation
fails. Set to True to keep all
resources when stack creation fails.
Set to False to delete all
resources when stack creation fails.
Default is True. |
Example Adopt stack: JSON request
{
"adopt_stack_data": {
"action": "CREATE",
"id": "bxxxxx4-0xx2-4xx1-axx6-exxxxxxxc",
"name": "teststack",
"resources": {
"MyServer": {
"action": "CREATE",
"metadata": {},
"name": "MyServer",
"resource_data": {},
"resource_id": "cxxxx3-dxx3-4xx-bxx2-3xxxxxxxxa",
"status": "COMPLETE",
"type": "OS::Trove::Instance"
}
},
"status": "COMPLETE",
"template": {}
},
"stack_name": "{stack_name}",
"template_url": "{template_url}",
"timeout_mins": "{timeout_mins}"
}
Response#
Example Adopt stack: JSON response
{
"action": "CREATE",
"id": "46c927bb-671a-43db-a29c-16a2610865ca",
"name": "trove",
"resources": {
"mysql_server": {
"action": "CREATE",
"metadata": {},
"name": "mysql_server",
"resource_data": {},
"resource_id": "74c5be7e-3e62-41e7-b455-93d1c32d56e3",
"status": "COMPLETE",
"type": "OS::Trove::Instance"
}
},
"status": "COMPLETE",
"template": {
"heat-template-version": "2013-05-23",
"description": "MySQL server instance",
"parameters": {
"instance_name": {
"description": "The database instance name",
"type": "string"
}
},
"resources": {
"mysql_server": {
"properties": {
"databases": [
{
"name": "testdbonetwo"
}
],
"flavor": "1 GB General Purpose v1",
"name": "test-trove-db",
"size": 30,
"users": [
{
"databases": [
"testdbonetwo"
],
"name": "testuser",
"password": "testpass123"
}
]
},
"type": "OS::Trove::Instance"
}
}
}
}
List stack data#
GET /v1/{tenant_id}/stacks
Lists active stacks.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 200 | Success | Request succeeded. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
This table shows the query parameters for the request:
| Name | Type | Description |
|---|---|---|
| id | String (Optional) | Filters the stack list by a specified stack ID. Use this filter multiple times to filter by multiple IDs. |
| status | String (Optional) | Filters the stack list by a specified status. Use this filter multiple times to filter by multiple statuses. |
| name | String (Optional) | Filters the stack list by a specified name. Use this filter multiple times to filter by multiple names. |
| action | String (Optional) | Filters the stack list by a specified action. Use this filter multiple times to filter by multiple actions. |
| tenant | String (Optional) | Filters the stack list by a specified tenant. Use this filter multiple times to filter by multiple tenants. |
| username | String (Optional) | Filters the stack list by a specified user name. Use this filter multiple times to filter by multiple user names. |
| owner_id | String (Optional) | Filters the stack list by a specified owner ID, which is the ID of the parent stack of listed stack. Use this filter multiple times to filter by multiple owner IDs. |
| limit | Int (Optional) | Requests a specified
page size of returned
items from the query.
Returns a number of
items up to the
specified limit value.
Use the limit
parameter to make an
initial limited request
and use the ID of the
last-seen item from the
response as the
marker parameter
value in a subsequent
limited request. |
| marker | String (Optional) | Specifies the ID of the
last-seen item. Use the
limit parameter to
make an initial limited
request and use the ID
of the last-seen item
from the response as the
marker parameter
value in a subsequent
limited request. |
| show_deleted | String (Optional) | Specifies whether to
include deleted stacks
in the list. Default is
False, which
excludes deleted stacks
from the list. |
| show_nested | String (Optional) | Specifies whether to
include nested stacks in
the list. Default is
False, which
excludes nested stacks
from the list. |
| sort_keys | String (Optional) | Sorts the stack list by
name, status,
created_at, or
updated_at key. |
| tags | String (Optional) | Lists stacks that
contain one or more
simple string tags. To
specify multiple tags,
separate the tags with
commas. For example,
tag1,tag2. The
boolean AND expression
is used to combine
multiple tags. |
| tags_any | String (Optional) | Lists stacks that
contain one or more
simple string tags. To
specify multiple tags,
separate the tags with
commas. For example,
tag1,tag2. The
boolean OR expression is
used to combine multiple
tags. |
| not_tags | String (Optional) | Lists stacks that do not
contain one or more
simple string tags. To
specify multiple tags,
separate the tags with
commas. For example,
tag1,tag2. The
boolean AND expression
is used to combine
multiple tags. |
| not_tags_any | String (Optional) | Lists stacks that do not
contain one or more
simple string tags. To
specify multiple tags,
separate the tags with
commas. For example,
tag1,tag2. The
boolean OR expression is
used to combine multiple
tags. |
| sort_dir | String (Optional) | The sort direction of
the list. A valid value
is asc (ascending)
or desc (descending). |
| global_tenant | String (Optional) | Specifies whether to
include stacks from all
tenants in the stack
list. Policy
requirements are
specified in the
Orchestration
policy.json file.
Default is False. |
| with_count | String (Optional) | Specifies whether to
include a count key in
the response. The count
key value is the number
of stacks that match the
query criteria. Default
is False. |
This operation does not accept a request body.
Response#
Example List stack data: JSON response
{
"stacks": [
{
"creation_time": "2014-06-03T20:59:46Z",
"description": "sample stack",
"id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"links": [
{
"href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"rel": "self"
}
],
"stack_name": "simple_stack",
"stack_status": "CREATE_COMPLETE",
"stack_status_reason": "Stack CREATE completed successfully",
"updated_time": "",
"tags": ""
}
]
}
Find stack#
GET /v1/{tenant_id}/stacks/{stack_name}
Finds the canonical URL for a specified stack.
Also works with verbs other than GET, so you can perform PUT and DELETE operations on a current stack. Set your client to follow redirects. Note that when redirecting, the request method should not change, as defined in RFC2626. However, in many clients the default behavior is to change the method to GET when you receive a 302 because this behavior is ubiquitous in web browsers.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 202 | Accepted | The request has been accepted for processing, but the processing has not been completed. |
| 302 | Found | The requested resource resides temporarily under a different URI. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 404 | Not Found | The server has not found anything matching the Request-URI. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
| stack_name | String (Required) | The name of a stack. |
This operation does not accept a request body.
Response#
Example Find stack: JSON response
{
"stack": {
"capabilities": [],
"creation_time": "2014-06-04T20:36:12Z",
"description": "sample stack",
"disable_rollback": true,
"id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7",
"links": [
{
"href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/5333af0c-cc26-47ee-ac3d-8784cefafbd7",
"rel": "self"
}
],
"notification_topics": [],
"outputs": [],
"parameters": {
"OS::stack_id": "5333af0c-cc26-47ee-ac3d-8784cefafbd7",
"OS::stack_name": "simple_stack"
},
"stack_name": "simple_stack",
"stack_status": "CREATE_COMPLETE",
"stack_status_reason": "Stack CREATE completed successfully",
"template_description": "sample stack",
"timeout_mins": null,
"updated_time": null
}
}
Show stack details#
GET /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
Shows details for a specified stack.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 200 | Success | Request succeeded. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 404 | Not Found | The server has not found anything matching the Request-URI. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
| stack_name | String (Required) | The name of a stack. |
| {stack_id} | String (Required) | The stack ID. |
This operation does not accept a request body.
Response#
Example Show stack details: JSON response
{
"stack": {
"capabilities": [],
"creation_time": "2014-06-03T20:59:46Z",
"description": "sample stack",
"disable_rollback": "True",
"id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"links": [
{
"href": "http://192.168.123.200:8004/v1/eb1c63a4f77141548385f113a28f0f52/stacks/simple_stack/3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"rel": "self"
}
],
"notification_topics": [],
"outputs": [],
"parameters": {
"OS::stack_id": "3095aefc-09fb-4bc7-b1f0-f21a304e864c",
"OS::stack_name": "simple_stack"
},
"stack_name": "simple_stack",
"stack_status": "CREATE_COMPLETE",
"stack_status_reason": "Stack CREATE completed successfully",
"template_description": "sample stack",
"timeout_mins": "",
"updated_time": "",
"tags": ""
}
}
Update stack#
PUT /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
Updates a specified stack.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 202 | Accepted | The request has been accepted for processing, but the processing has not been completed. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 404 | Not Found | The server has not found anything matching the Request-URI. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
| stack_name | String (Required) | The name of a stack. |
| {stack_id} | String (Required) | The stack ID. |
This table shows the body parameters for the request:
| Name | Type | Description |
|---|---|---|
| template_url | String (Optional) | A URI to the location containing the
stack template on which to perform
the specified operation. See the
description of the template
parameter for information about the
expected template content located at
the URI. This parameter is only
required when you omit the
template parameter. If you
specify both parameters, this
parameter is ignored. |
| template | String (Optional) | The stack template on which to
perform the specified operation. This
parameter is always provided as a
string in the JSON request body.
The content of the string is a JSON-
or YAML-formatted Orchestration
template. For example: "template":
{ "heat_template_version": "2013-05-
23", ...} This parameter is
required only when you omit the
template_url parameter. If you
specify both parameters, this value
overrides the template_url
parameter value. |
| environment | String (Optional) | A JSON environment for the stack. |
| files | Map (Optional) | Supplies the contents of files
referenced in the template or the
environment. Stack templates and
resource templates can explicitly
reference files by using the
get_file intrinsic function. In
addition, the environment
parameter can contain implicit
references to files. The value is a
JSON object, where each key is a
relative or absolute URI which serves
as the name of a file, and the
associated value provides the
contents of the file. The following
code shows the general structure of
this parameter. { ... "files": {
"fileA.yaml": "Contents of the file",
"file:///usr/fileB.template":
"Contents of the file",
"http://example.com/fileC.template":
"Contents of the file" } ... }
Additionally, some template authors
encode their user data in a local
file. The Orchestration client
examines the template for the
get_file intrinsic function and
adds an entry to the files map
with the path to the file as the name
and the file contents as the value.
So, a simple example looks like this:
{ "files": { "myfile":
"#!/bin/bash\necho \"Hello world\" >
/root/testfile.txt" }, ...,
"stack_name": "teststack",
"template": { ..., "resources": {
"my_server": { "type":
"OS::Nova::Server", "properties": {
..., "user_data": { "get_file":
"myfile" } } } } }, "timeout_mins":
60 } Do not use this parameter to
provide the content of the template
located at the address specified by
template_url. Instead, use the
template parameter to supply the
template content as part of the
request. |
| tags | String (Optional) | One or more simple string tags to
associate with the stack. To
associate multiple tags with a stack,
separate the tags with commas. For
example, tag1,tag2. |
| parameters | Object (Optional) | This parameter supplies updated
arguments for parameters defined in
the stack template. The value is a
JSON object, where each key is the
name of a parameter defined in the
template and the associated value is
the argument to use for that
parameter when instantiating the
template. The following code shows
the general structure of this
parameter. In the example, a and
b are the names of two parameters
defined in the template. {...
"parameters": { "a": "Value", "b":
"3" }... } While the service
accepts JSON numbers for parameters
with the type number and JSON
objects for parameters with the type
json, all parameter values are
converted to their string
representation for storage in the
created Stack. Clients are encouraged
to send all parameter values using
their string representation for
consistency between requests and
responses from the Orchestration
service. You must specify a value for
each template parameter that does not
have a default value. However, this
parameter cannot contain JSON
properties with names that do not
match a parameter that is defined in
the template. |
| timeout_mins | String (Optional) | The timeout for stack creation in minutes. |
Example Update stack: JSON request
{
"template": {
"heat_template_version": "2013-05-23",
"description": "Create a simple stack",
"parameters": {
"flavor": {
"default": "1 GB General Purpose v1",
"type": "string"
}
},
"resources": {
"hello_world": {
"type": "OS::Nova::Server",
"properties": {
"key_name": "heat_key",
"flavor": {
"get_param": "flavor"
},
"image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
"user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
}
}
}
},
"parameters": {
"flavor": "2 GB General Purpose v1"
}
}
Response#
This operation does not return a response body.
Delete stack#
DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}
Deletes a specified stack and any snapshots of that stack.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 204 | No Content | The server has fulfilled the request but does not need to return an entity- body, and might want to return updated meta- information. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 404 | Not Found | The server has not found anything matching the Request-URI. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
| stack_name | String (Required) | The name of a stack. |
| {stack_id} | String (Required) | The stack ID. |
This operation does not accept a request body.
Response#
This operation does not return a response body.
Preview stack#
POST /v1/{tenant_id}/stacks/preview
Previews a stack.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 200 | Success | Request succeeded. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
This table shows the body parameters for the request:
| Name | Type | Description |
|---|---|---|
| stack_name | String (Required) | A name for the new stack. The value
must be unique within a project. The
name must start with an ASCII letter
and can contain ASCII letters,
digits, underscores, periods, and
hyphens. Specifically, the name must
match the ^[a-zA-Z][a-zA-Z0-9_.-
]*$ regular expression. When you
delete or abandon a stack, its name
might not be available for reuse for
an unspecified period of time. |
| template_url | String (Optional) | A URI to the location containing the
stack template on which to perform
the specified operation. See the
description of the template
parameter for information about the
expected template content located at
the URI. This parameter is only
required when you omit the
template parameter. If you
specify both parameters, this
parameter is ignored. |
| template | String (Optional) | The stack template on which to
perform the specified operation. This
parameter is always provided as a
string in the JSON request body.
The content of the string is a JSON-
or YAML-formatted Orchestration
template. For example: "template":
{ "heat_template_version": "2013-05-
23", ...} This parameter is
required only when you omit the
template_url parameter. If you
specify both parameters, this value
overrides the template_url
parameter value. |
| files | Map (Optional) | Supplies the contents of files
referenced in the template or the
environment. Stack templates and
resource templates can explicitly
reference files by using the
get_file intrinsic function. In
addition, the environment
parameter can contain implicit
references to files. The value is a
JSON object, where each key is a
relative or absolute URI which serves
as the name of a file, and the
associated value provides the
contents of the file. The following
code shows the general structure of
this parameter. { ... "files": {
"fileA.yaml": "Contents of the file",
"file:///usr/fileB.template":
"Contents of the file",
"http://example.com/fileC.template":
"Contents of the file" } ... }
Additionally, some template authors
encode their user data in a local
file. The Orchestration client
examines the template for the
get_file intrinsic function and
adds an entry to the files map
with the path to the file as the name
and the file contents as the value.
So, a simple example looks like this:
{ "files": { "myfile":
"#!/bin/bash\necho \"Hello world\" >
/root/testfile.txt" }, ...,
"stack_name": "teststack",
"template": { ..., "resources": {
"my_server": { "type":
"OS::Nova::Server", "properties": {
..., "user_data": { "get_file":
"myfile" } } } } }, "timeout_mins":
60 } Do not use this parameter to
provide the content of the template
located at the address specified by
template_url. Instead, use the
template parameter to supply the
template content as part of the
request. |
| parameters | Object (Optional) | Supplies arguments for parameters
defined in the stack template. The
value is a JSON object, where each
key is the name of a parameter
defined in the template and the
associated value is the argument to
use for that parameter when
instantiating the template. The
following code shows the general
structure of this parameter. In the
example, a and b would be the
names of two parameters defined in
the template. { ... "parameters": {
"a": "Value", "b": "3" } ... }
While the service accepts JSON
numbers for parameters with the type
number and JSON objects for
parameters with the type json,
all parameter values are converted to
their string representation for
storage in the created Stack. Clients
are encouraged to send all parameter
values using their string
representation for consistency
between requests and responses from
the Orchestration service. A value
must be provided for each template
parameter which does not specify a
default value. However, this
parameter is not allowed to contain
JSON properties with names that do
not match a parameter defined in the
template. The files parameter
maps logical file names to file
contents. Both the get_file
intrinsic function and provider
template functionality use this
mapping. When you want to use a
provider template, for example, the
Orchestration service adds an entry
to the files map by using: * The
URL of the provider template as the
name. * The contents of that file as
the value. Additionally, some
template authors encode their user
data in a local file. The
Orchestration client examines the
template for the get_file
intrinsic function and adds an entry
to the files map with the path to
the file as the name and the file
contents as the value. So, a simple
example looks like this: { "files":
{ "myfile": "#!/bin/bash\necho
\"Hello world\" > /root/testfile.txt"
}, ..., "stack_name": "teststack",
"template": { ..., "resources": {
"my_server": { "type":
"OS::Nova::Server", "properties": {
..., "user_data": { "get_file":
"myfile" } } } } }, "timeout_mins":
60 } |
Example Preview stack: JSON request
{
"files": {},
"disable_rollback": true,
"parameters": {
"flavor": "2 GB General Purpose v1"
},
"stack_name": "teststack",
"template": {
"heat_template_version": "2013-05-23",
"description": "Simple template to test heat commands",
"parameters": {
"flavor": {
"default": "1 GB General Purpose v1",
"type": "string"
}
},
"resources": {
"hello_world": {
"type": "OS::Nova::Server",
"properties": {
"key_name": "heat_key",
"flavor": {
"get_param": "flavor"
},
"image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
"user_data": "#!/bin/bash -xv\necho \"hello world\" > /root/hello-world.txt\n"
}
}
}
},
"timeout_mins": 60
}
Response#
This table shows the body parameters for the response:
| Name | Type | Description |
|---|---|---|
| parent | String (Required) | The stack ID of the parent stack, if this is a nested stack. |
| id | String (Required) | The stack ID. |
| stack_name | String (Required) | The name of the stack. |
| description | String (Required) | A description of the stack. |
| template_description | String (Required) | A description of the template that defines the stack. |
| timeout_mins | Integer (Required) | Timelines for stack creation. |
| disable_rollback | String (Required) | Enables or disables
stack rollback when
stack creation fails.
Set to True to
rollback the stack when
stack creation fails.
Set to False to
disable stack rollback
when stack creation
fails. Default is
True. |
| capabilities | String (Required) | List of stack capabilities for stack. |
| notification_topics | String (Required) | List of notification topics for stack. |
| updated_time | String (Required) | Time of last stack
update in the following
format: YYYY-MM-
DDThh:mm:ssTZD, where
TZD is the time zone
designator. |
| stack_owner | String (Required) | Stack owner name. |
| parameters | String (Required) | List of parameters defined for the stack. |
| resources | String (Required) | List of stack resources. |
Example Preview stack: JSON response
{
"stack": {
"capabilities": [],
"creation_time": "2015-01-31T15:12:36Z",
"description": "HOT template for Nova Server resource.\n",
"disable_rollback": true,
"id": "None",
"links": [
{
"href": "http://192.168.122.102:8004/v1/6e18cc2bdbeb48a5basad2dc499f6804/stacks/test_stack/None",
"rel": "self"
}
],
"notification_topics": [],
"parameters": {
"OS::project_id": "6e18cc2bdbeb48a5basad2dc499f6804",
"OS::stack_id": "None",
"OS::stack_name": "teststack",
"admin_user": "cloud-user",
"flavor": "1 GB General Purpose v1",
"image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
"key_name": "heat_key",
"server_name": "MyServer"
},
"parent": null,
"resources": [
{
"attributes": {},
"description": "",
"metadata": {},
"physical_resource_id": "",
"properties": {
"description": "Ping and SSH",
"name": "the_sg",
"rules": [
{
"direction": "ingress",
"ethertype": "IPv4",
"port_range_max": null,
"port_range_min": null,
"protocol": "icmp",
"remote_group_id": null,
"remote_ip_prefix": null,
"remote_mode": "remote_ip_prefix"
},
{
"direction": "ingress",
"ethertype": "IPv4",
"port_range_max": 65535,
"port_range_min": 1,
"protocol": "tcp",
"remote_group_id": null,
"remote_ip_prefix": null,
"remote_mode": "remote_ip_prefix"
},
{
"direction": "ingress",
"ethertype": "IPv4",
"port_range_max": 65535,
"port_range_min": 1,
"protocol": "udp",
"remote_group_id": null,
"remote_ip_prefix": null,
"remote_mode": "remote_ip_prefix"
}
]
},
"required_by": [
"server1"
],
"resource_action": "INIT",
"resource_identity": {
"path": "/resources/the_sg_res",
"stack_id": "None",
"stack_name": "teststack",
"tenant": "6e18cc2bdbeb48a5b3cad2dc499f6804"
},
"resource_name": "the_sg_res",
"resource_status": "COMPLETE",
"resource_status_reason": "",
"resource_type": "OS::Neutron::SecurityGroup",
"stack_identity": {
"path": "",
"stack_id": "None",
"stack_name": "teststack",
"tenant": "6e18cc2bdbeb48a5b3cad2dc499f6804"
},
"stack_name": "teststack",
"updated_time": "2015-01-31T15:12:36Z"
},
{
"attributes": {
"accessIPv4": "",
"accessIPv6": "",
"addresses": "",
"console_urls": "",
"first_address": "",
"instance_name": "",
"name": "MyServer",
"networks": "",
"show": ""
},
"description": "",
"metadata": {},
"physical_resource_id": "",
"properties": {
"admin_pass": null,
"admin_user": "cloud-user",
"availability_zone": null,
"block_device_mapping": null,
"config_drive": null,
"diskConfig": null,
"flavor": "1 GB General Purpose v1",
"flavor_update_policy": "RESIZE",
"image": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
"image_update_policy": "REPLACE",
"key_name": "heat_key",
"metadata": {
"ha_stack": "None"
},
"name": "MyServer",
"networks": [
{
"fixed_ip": null,
"network": "private",
"port": null,
"uuid": null
}
],
"personality": {},
"reservation_id": null,
"scheduler_hints": null,
"security_groups": [
"None"
],
"software_config_transport": "POLL_SERVER_CFN",
"user_data": "",
"user_data_format": "HEAT_CFNTOOLS"
},
"required_by": [],
"resource_action": "INIT",
"resource_identity": {
"path": "/resources/hello_world",
"stack_id": "None",
"stack_name": "teststack",
"tenant": "6e18cc2bdbeb48a3433cad2dc499sdf32234"
},
"resource_name": "hello_world",
"resource_status": "COMPLETE",
"resource_status_reason": "",
"resource_type": "OS::Nova::Server",
"stack_identity": {
"path": "",
"stack_id": "None",
"stack_name": "teststack",
"tenant": "6e18cc2bdbeb48a3433cad2dc499sdf32234"
},
"stack_name": "teststack",
"updated_time": "2015-01-31T15:12:36Z"
}
],
"stack_name": "test_stack",
"stack_owner": "admin",
"template_description": "HOT template for Nova Server resource.\n",
"timeout_mins": null,
"updated_time": null
}
}
Abandon stack#
DELETE /v1/{tenant_id}/stacks/{stack_name}/{stack_id}/abandon
Deletes a specified stack but leaves its resources intact, and returns data describing the stack and its resources.
This table shows the possible response codes for this operation:
| Response Code | Name | Description |
|---|---|---|
| 200 | Success | Request succeeded. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized | The request requires user authentication. |
| 404 | Not Found | The server has not found anything matching the Request-URI. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
Request#
This table shows the URI parameters for the request:
| Name | Type | Description |
|---|---|---|
| {tenant_id} | String | The ID of the tenant. A tenant is also known as an account or project. |
| stack_name | String (Required) | The name of a stack. |
| {stack_id} | String (Required) | The stack ID. |
This operation does not accept a request body.
Response#
Example Abandon stack: JSON response
{
"status": "COMPLETE",
"name": "g",
"dry_run": true,
"template": {
"outputs": {
"instance_ip": {
"value": {
"str_replace": {
"params": {
"username": "ec2-user",
"hostname": {
"get_attr": [
"server",
"first_address"
]
}
},
"template": "ssh username@hostname"
}
}
}
},
"heat_template_version": "2013-05-23",
"resources": {
"server": {
"type": "OS::Nova::Server",
"properties": {
"key_name": {
"get_param": "key_name"
},
"image": {
"get_param": "image"
},
"flavor": {
"get_param": "flavor"
}
}
}
},
"parameters": {
"key_name": {
"default": "heat_key",
"type": "string"
},
"image": {
"default": "Ubuntu 12.04 LTS (Precise Pangolin) (PV)",
"type": "string"
},
"flavor": {
"default": "1 GB General Purpose v1",
"type": "string"
}
}
},
"action": "CREATE",
"id": "16934ca3-40e0-4fb2-a289-a700662ec05a",
"resources": {
"server": {
"status": "COMPLETE",
"name": "server",
"resource_data": {},
"resource_id": "39d5dad7-7d7a-4cc8-bd84-851e9e2ff4ea",
"action": "CREATE",
"type": "OS::Nova::Server",
"metadata": {}
}
}
}