1.3.1. Basics for HOT creation

Here is an example of template:
heat_template_version: 2016-04-08

description: Sample template to deploy a single compute instance

resources:
  my_instance:
    type: ECL::Compute::Server
    properties:
      image: ad936ae4-2983-4f23-9187-e47e82cb2725
      flavor: 1CPU-4GB
      networks:
      - uuid: 252700fb-7907-434d-bf67-d67afbcbb276

Required keys for template are shown in below table:

Key Description
heat_template_version
Specify version of the template. 2016-04-08 is a common choice.
For the list of available version, please check About heat_template_version.
resources
Define the detailed resources for this stack. (e.g. instance, logic_network, etc.)
At least one resource should be defined.
Resources is the core component of template.
Detailed definition method of Resources can be found in Resources.

Note

In addition, following keys(optional) can also be specified in the template.
They will be explained in the second half of this page.

1.3.1.1. About heat_template_version

List of template version can be obtained by following command/API.

ecl command

% ecl dpm template version list
+----------------------------------+------+
| version                          | type |
+----------------------------------+------+
| heat_template_version.2016-04-08 | hot  |
+----------------------------------+------+

curl command

% curl -g -i -X GET http://{deployment_manager_url}/v1/{tenant_id}/template_versions -H "Accept: application/json" -H "X-Auth-Token: <token>"

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 343
X-Openstack-Request-Id: req-79751ec4-51ea-4486-a86b-0c5e988991ec
Date: Thu, 05 Jan 2017 10:43:53 GMT

{"template_versions": [{"version": "heat_template_version.2016-04-08", "type": "hot"}, {"version": "heat_template_version.2013-05-23", "type": "hot"}, {"version": "heat_template_version.2015-04-30", "type": "hot"}, {"version": "heat_template_version.2015-10-15", "type": "hot"}, {"version": "heat_template_version.2014-10-16", "type": "hot"}]}

Note

For your reference, official document of Openstack also lists Heat template versions: Heat Orchestration Template (HOT) specification:
However, 2016-10-14(OpenStack newton) and 2017-02-24(OpenStack ocata) are not supported in Enterprise Cloud 2.0.

1.3.1.2. Resources

How to define resources.

Resource name

heat_template_version: 2016-04-08

description: Sample template to deploy a single compute instance

resources:
  my_instance:
    type: ECL::Compute::Server
    properties:
      image: ad936ae4-2983-4f23-9187-e47e82cb2725
      flavor: 1CPU-4GB
      networks:
      - uuid: 252700fb-7907-434d-bf67-d67afbcbb276
The resources section is required to contain at least one resource definition.
Each resource definition begins from the resource name.
In above example, my_instance is just the resource name.

Please be careful that resource names can NOT be duplicate in one stack.

For every resource, we should specify its type value as well as properties.
Different type will lead to different properties requires.

Resource definition

For every resource, following contents should be defined.
key description
type
Describe resource type as well as the service this resource subjected to provided by Enterprise Cloud 2.0.
e.g.
ECL::Compute::Server represents instance resource from virtual server service.
ECL::Network::LogicalNetwork represents logical network resource from network service.

Available resource types can be checked from List of Resource Types.
properties
Describe parameters used to create the defined resource.
For above resource ECL::Compute::Server, following properties should be defined.

・ Specify ad936ae4-2983-4f23-9187-e47e82cb2725 for image(ID of the image for instance to boot with)
・ Specify 1CPU-4GB for flavor(Instance's CPU/RAM)
・ Specify 252700fb-7907-434d-bf67-d67afbcbb276 for networks(Logic network for instance to connect on. Could be multiple)

Properties items are various from different types. Check How to check property items for different resource types.
For different resource types, check Template Examples for the detailed property items.

How to check property items for different resource types

Check Detailed Information of Resource Type from control panel for the detailed property items.
Or we can use following methods.

ecl command

$ ecl dpm resource type show ECL::Compute::KeyPair
support_status:
  message: null
  previous_status: null
  status: SUPPORTED
  version: null
attributes:
  fingerprint:
    description: Fingerprint
    type: string
  id:
    description: Unique id
    type: string
  name:
    description: The name to associate with the keypair.
    type: string
  private_key:
    description: Private key if it has been saved.
    type: string
  public_key:
    description: Public key
    type: string
  save_private_key:
    description: True if the system should remember a generated private key; False
      otherwise.
    type: boolean
  show:
    description: Detailed information about resource.
    type: map
  user_id:
    description: Owner of instance
    type: string
properties:
  name:
    constraints:
    - length:
        max: 255
        min: 1
    description: The name to associate with the keypair.
    immutable: false
    required: true
    type: string
    update_allowed: false
  public_key:
    description: The public ssh key to import. If not provided, a key is generated.
    immutable: false
    required: false
    type: string
    update_allowed: false
  save_private_key:
    default: false
    description: True if the system should remember a generated private key; False
      otherwise.
    immutable: false
    required: false
    type: boolean
    update_allowed: false
resource_type: ECL::Compute::KeyPair

curl command

% curl -g -i -X GET "http://{deployment_manager_url}/v1/{tenant_id}/resource_types/ECL%3A%3ANetwork%3A%3ALogicalNetwork?with_description=False" -H "Accept: application/json" -H "X-Auth-Token: <token>"
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2005
X-Openstack-Request-Id: req-382a667f-e78e-4ba7-9873-fc67d4b8605b
Date: Fri, 06 Jan 2017 00:40:25 GMT

{"support_status": {"status": "SUPPORTED", "message": null, "version": null, "previous_status": null}, "attributes": {"status": {"type": "string", "description": "The network status."}, "subnets": {"type": "list", "description": "The associated subnets."}, "name": {"type": "string", "description": "Network name."}, "admin_state_up": {"type": "boolean", "description": "The administrative status of the network."}, "tenant_id": {"type": "string", "description": "The tenant owning this network."}, "tags": {"type": "map", "description": "Network tags."}, "plane": {"type": "string", "description": "Type of the traffic for which network will be used."}, "show": {"type": "map", "description": "Detailed information about resource."}, "shared": {"type": "integer", "description": "Indicates whether this network is shared across all tenants (not supported)"}, "id": {"type": "string", "description": "Network unique id."}, "description": {"type": "string", "description": "Network description."}}, "properties": {"description": {"update_allowed": true, "required": false, "type": "string", "description": "Network description.", "immutable": false}, "admin_state_up": {"description": "The administrative state of the network", "default": true, "required": false, "update_allowed": true, "type": "boolean", "immutable": false}, "tenant_id": {"update_allowed": false, "required": false, "type": "string", "description": "Tenant ID of the owner (UUID).", "immutable": false}, "tags": {"update_allowed": true, "required": false, "type": "map", "description": "Network tags.", "immutable": false}, "plane": {"description": "Type of the traffic for which network will be used.", "default": "data", "required": false, "update_allowed": false, "type": "string", "immutable": false, "constraints": [{"allowed_values": ["data", "storage"]}]}, "name": {"update_allowed": true, "required": false, "type": "string", "description": "Network name.", "immutable": false}}, "resource_type": "ECL::Network::LogicalNetwork"}

Define multiple resources in one stack

Here is an example:

heat_template_version: 2016-04-08

description: Sample Templ to create multiple keypairs.

resources:
  keypair1:
    type: ECL::Compute::KeyPair
    properties:
      name: key_pair01
  keypair2:
    type: ECL::Compute::KeyPair
    properties:
      name: key_pair02

Write down multiple resources in sequence under resources tag as the above example, and these resources will be created together when creating the stack.

Next is an example shows how to create resources when dependent relationship exists between two resources.
In the following template, one logic network and one subnet will be created together.
Here is the detailed process.
Step1. Create a logical network.
Step2. Create a subnet based on the created logical network.

Because the subnet we want to create in step2 needs to be created based on the logical network,
we need to specify logical network’s network_id to the subnet.
However, when writing down the template, we have on idea on the network_id of a not-yet-created logical network.

We can solve this problem by following template example.
heat_template_version: 2016-04-08

description: Sample template to deploy a single logical network with subnet

resources:
  private_net:
    type: ECL::Network::LogicalNetwork
    properties:
      name: stack_network_01
      plane: data

  private_subnet:
    type: ECL::Network::Subnet
    properties:
      network_id: { get_resource: private_net }
      cidr: 192.168.1.0/24
      gateway_ip: 192.168.1.1
      allocation_pools:
        - start: 192.168.1.100
          end: 192.168.1.200
In above template, resource private_net is for Step1. Create a logical network..
Also, resource private_subnet is for Step2. Create a subnet based on the created logical network.

Please pay attention to network_id property in resource private_subnet.
{ get_resource: private_net } is specified to property network_id.
Here key word get_resource is used to get resource id from specified resource.

In other word, after private_net‘s creating, its id will be got by get_resource and be used on creating private_subnet.

By this way we can create two resources with dependency relationship between each other.

Note

Functions which can be used in template like get_resource is called as Intrinsic function.
Check here for detailed information.

1.3.1.3. Parameters

Paremeters section allows for specifying input parameters that have to be provided when instantiating the template.
Following is two cases we can use parameters to simplify our template.

1. When creating multiple instances by the same flavor, use parameters to summarize the flavor id.
2. Only one property value in the template needs to be changed while other properties remaining unchanged.

Following is the detailed example on using parameters.
heat_template_version: 2016-04-08

description: Sample template to deploy a single logical network with params

parameters:
  network_name:
    type: string
    label: Network Name

resources:
  private_net:
    type: ECL::Network::LogicalNetwork
    properties:
      name: { get_param: network_name }
      plane: data
In the example template, key parameters is used.
We can find in parameters section, a parameter network_name is specified. By this way, network_name should be provided by user upon deployment.
Resource ECL::Network::LogicalNetwork‘s name property use get_param function to refer to the parameter network_name‘s value.

Note

Above template is one example of get_param and Intrinsic functions.
Check here for detailed information.
In above example, value of parameter network_name needs to be provided by user upon deployment.

Next section we will introduce how to provide this value for parameters.
Value NameFromParameters will be provided for parameter network_name in following examples.
(We assume the above template’s name is test-template.yaml.)

How to provide values for parameters

ecl command

% ecl dpm stack create -t test-template.yaml Test-Stack --parameter network_name=NameFromParameters

curl command

Specify KEY-VALUE pair to provide values for parameters in parameters tag, request body.
e.g. -d ‘{“files”: {}, “disable_rollback”: true, "parameters": {"network_name": "NameFromParameters"} ...
% curl -g -i -X POST -H 'X-Auth-Token: <token>' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"files": {}, "disable_rollback": true, "parameters": {"network_name": "NameFromParameters"}, "stack_name": "Test-Stack3", "environment": {}, "template": {"heat_template_version": "2016-04-08", "description": "Sample template to deploy a single logical network with params", "parameters": {"network_name": {"type": "string", "label": "Network Name"}}, "resources": {"private_net": {"type": "ECL::Network::LogicalNetwork", "properties": {"plane": "data", "name": {"get_param": "network_name"}}}}}}' http://{deployment_manager_url}/v1/{tenant_id}/stacks

control panel

Please refer to How to create a stack.

Set default values for parameters

Default value is used if the user doesn’t specify a value for parameter during deployment.
heat_template_version: 2016-04-08

description: Sample template to deploy a single logical network with params

parameters:
  network_name:
    type: string
    label: Network Name
    default: DefaultName

resources:
  private_net:
    type: ECL::Network::LogicalNetwork
    properties:
      name: { get_param: network_name }
      plane: data
After setting default value for parameter networkname, if the user doesn’t provide a value explicitly during deployment, default value DefaultName will be provided automatically.
If user provided a value explicitly for parameter, that value will be used even there is a default value.

1.3.1.4. Outputs

Deployment Manager will create resources automatically by using the API of each service when creating a stack.
Therefore, it is not possible to directly refer to the response of single resource’s creation API.
On the other hand, since the following information is included only in the response of resource create API, a mechanism to refer to these values is required.

* Baremetal server’s password
* Firewall’s password
* Loadbalancer’s password
* Keypair’s private key

By storing these values in the outputs attribute of a stack, it is possible to check it later as detailed information on the stack.
We can add outputs section in template to store the values in output attribute.
heat_template_version: 2016-04-08

description: Sample template to create loadbalancer.

resources:
  lb01:
    type: ECL::Network::LoadBalancer
    properties:
      name: test-lb01-via-template
      load_balancer_plan_id: 29da442c-9a06-4eb3-b3cd-b6b123198214

outputs:
  lb_admin_username:
    value: { get_attr: [lb01, admin_username] }
    description: Admin username
  lb_admin_password:
    value: { get_attr: [lb01, admin_password] }
    description: Admin password
  lb_user_username:
    value: { get_attr: [lb01, user_username] }
    description: User username
  lb_user_password:
    value: { get_attr: [lb01, user_password] }
    description: User password
  lb_interfaces:
    value: { get_attr: [lb01, interfaces] }
    description: LB interfaces
Creating ECL::Network::LoadBalancer by above template, parameters like username, admin password will be stored in output attribute.
Also results can be confirmed by using command ecl dpm stack show.
% ecl dpm stack show Test-Stack
+-----------------------+--------------------------------------------------------------------------------------------------------------------------+
| Property              | Value                                                                                                                    |
+-----------------------+--------------------------------------------------------------------------------------------------------------------------+
| id                    | d8a1092d-4f49-40f5-935d-3bde1596a914                                                                                     |
| stack_name            | Test-Stack                                                                                                               |
| description           | Sample template to create loadbalancer.                                                                             |
| creation_time         | 2017-01-06T02:30:24                                                                                                      |
| stack_status          | CREATE_IN_PROGRESS                                                                                                       |
| stack_status_reason   | Stack CREATE started                                                                                                     |
| parameters            | {                                                                                                                        |
|                       |   "OS::project_id": "c36bde1eafa8416b90232e00aab36080",                                                                  |
|                       |   "OS::stack_id": "d8a1092d-4f49-40f5-935d-3bde1596a914",                                                                |
|                       |   "OS::stack_name": "Test-Stack"                                                                                         |
|                       | }                                                                                                                        |
|                       |                                                                                                                          |
| outputs               | [                                                                                                                        |
|                       |   {                                                                                                                      |
|                       |     "output_value": "user-admin",                                                                                        |
|                       |     "output_key": "lb_admin_username",                                                                                   |
|                       |     "description": "Admin username"                                                                                      |
|                       |   },                                                                                                                     |
|                       |   {                                                                                                                      |
|                       |     "output_value": [                                                                                                    |
|                       |       {                                                                                                                  |
|                       |         "status": "PENDING_CREATE",                                                                                      |
|                       |         "virtual_ip_properties": null,                                                                                   |
|                       |         "name": "Interface 1/1",                                                                                         |
|                       |         "network_id": null,                                                                                              |
|                       |         "slot_number": 1,                                                                                                |
|                       |         "virtual_ip_address": null,                                                                                      |
|                       |         "ip_address": null,                                                                                              |
|                       |         "id": "f7bbaddc-8b4a-427c-91dd-7657e0ad95c7"                                                                     |
|                       |       },                                                                                                                 |
|                       |       {                                                                                                                  |
|                       |         "status": "PENDING_CREATE",                                                                                      |
|                       |         "virtual_ip_properties": null,                                                                                   |
|                       |         "name": "Interface 1/2",                                                                                         |
|                       |         "network_id": null,                                                                                              |
|                       |         "slot_number": 2,                                                                                                |
|                       |         "virtual_ip_address": null,                                                                                      |
|                       |         "ip_address": null,                                                                                              |
|                       |         "id": "1bbb3de1-e737-49cb-9986-b8c550945851"                                                                     |
|                       |       },                                                                                                                 |
|                       |       {                                                                                                                  |
|                       |         "status": "PENDING_CREATE",                                                                                      |
|                       |         "virtual_ip_properties": null,                                                                                   |
|                       |         "name": "Interface 1/3",                                                                                         |
|                       |         "network_id": null,                                                                                              |
|                       |         "slot_number": 3,                                                                                                |
|                       |         "virtual_ip_address": null,                                                                                      |
|                       |         "ip_address": null,                                                                                              |
|                       |         "id": "e19c21da-901b-4fa3-a3d0-8fdaa9a76cf8"                                                                     |
|                       |       },                                                                                                                 |
|                       |       {                                                                                                                  |
|                       |         "status": "PENDING_CREATE",                                                                                      |
|                       |         "virtual_ip_properties": null,                                                                                   |
|                       |         "name": "Interface 1/4",                                                                                         |
|                       |         "network_id": null,                                                                                              |
|                       |         "slot_number": 4,                                                                                                |
|                       |         "virtual_ip_address": null,                                                                                      |
|                       |         "ip_address": null,                                                                                              |
|                       |         "id": "2fa8487f-1b37-4d7a-834f-06b9ebc852ac"                                                                     |
|                       |       }                                                                                                                  |
|                       |     ],                                                                                                                   |
|                       |     "output_key": "lb_interfaces",                                                                                       |
|                       |     "description": "LB interfaces"                                                                                       |
|                       |   },                                                                                                                     |
|                       |   {                                                                                                                      |
|                       |     "output_value": "nw2azwiwoftf",                                                                                      |
|                       |     "output_key": "lb_admin_password",                                                                                   |
|                       |     "description": "Admin password"                                                                                      |
|                       |   },                                                                                                                     |
|                       |   {                                                                                                                      |
|                       |     "output_value": "fRVQsu8c99BV",                                                                                      |
|                       |     "output_key": "lb_user_password",                                                                                    |
|                       |     "description": "User password"                                                                                       |
|                       |   },                                                                                                                     |
|                       |   {                                                                                                                      |
|                       |     "output_value": "user-read",                                                                                         |
|                       |     "output_key": "lb_user_username",                                                                                    |
|                       |     "description": "User username"                                                                                       |
|                       |   }                                                                                                                      |
|                       | ]                                                                                                                        |
| links                 | http://{deployment_manager_url}/v1/c36bde1eafa8416b90232e00aab36080/stacks/Test-Stack/d8a1092d-4f49-40f5-935d-3bde1596a914 (self)      |
| disable_rollback      | True                                                                                                                     |
| parent                | None                                                                                                                     |
| tags                  | null                                                                                                                     |
| stack_user_project_id | c36bde1eafa8416b90232e00aab36080                                                                                         |
| notification_topics   | []                                                                                                                       |
| timeout_mins          | None                                                                                                                     |
| stack_owner           | ********************************                                                                                         |
+-----------------------+--------------------------------------------------------------------------------------------------------------------------+

1.3.1.5. description

Use following key to write a description for template itself.
key description
description
describe a template
Define a description in multiple lines is also allowed. See Define a description in multiple lines.

Define a description in multiple lines

description: >
  This is how you can provide a longer description
  of your template that goes over several lines.