Heat is the native OpenStack orchestration tool. This section demonstrates how to create a first instance using Heat.

It is beyond the scope of this section to explain the syntax of writing Heat templates. A predefined example from the catalystcloud-orchestration git repository will be used here as a template. This example may also be used as the basis for new templates.

Tip

For more information on writing Heat templates, please consult the documentation at Orchestration.

Checkout the catalystcloud-orchestration repository. This includes the example Heat templates:

$ git clone https://github.com/catalyst/catalystcloud-orchestration.git && ORCHESTRATION_DIR="$(pwd)/catalystcloud-orchestration" && echo $ORCHESTRATION_DIR

To continue, we will need to have an SSH key for our instance. Heat does not support uploading an SSH key so this step must be performed manually.

When an instance is created, OpenStack passes an SSH key to the instance which can be used for shell access. By default, Ubuntu will install this key for the “ubuntu” user. Other operating systems have a different default user, as listed here: Types of images

Use openstack keypair create to upload your Public SSH key.

Tip

Name the key using information such as your username and the hostname on which the ssh key was generated. This makes the key easy to identify at a later stage.

$ openstack keypair create --public-key ~/.ssh/id_test.pub first-instance-key
+-------------+-------------------------------------------------+
| Field       | Value                                           |
+-------------+-------------------------------------------------+
| fingerprint | <SSH_KEY_FINGERPRINT>                           |
| name        | testkey                                         |
| user_id     | <USER_ID>                                       |
+-------------+-------------------------------------------------+

$ openstack keypair list
+------------+-------------------------------------------------+
| Name       | Fingerprint                                     |
+------------+-------------------------------------------------+
| testkey    | <SSH_KEY_FINGERPRINT>                           |
+------------+-------------------------------------------------+

Note

Keypairs must be created in each region being used.

Now that we have our SSH key, we can start to build our instance:

Select the following Heat template from the catalystcloud-orchestration repository cloned earlier. Before making use of a template, it is good practice to check that the template is valid:

$ openstack orchestration template validate -t $ORCHESTRATION_DIR/hot/ubuntu-18.04/first-instance/first-instance.yaml

This command will echo the yaml if it succeeds and will return an error if it does not. If the template validates, it may be used to build the stack:

$ openstack stack create -t $ORCHESTRATION_DIR/hot/ubuntu-18.04/first-instance/first-instance.yaml first-instance-stack
+---------------------+-------------------------------------------------------------------------------------------+
| Field               | Value                                                                                     |
+---------------------+-------------------------------------------------------------------------------------------+
| id                  | cb956f56-536a-4244-930d-xxxxxxxxxxxx                                                      |
| stack_name          | first-instance-stack                                                                      |
| description         | HOT template for building the first instance stack on the Catalyst Cloud nz-por-1 region. |
|                     |                                                                                           |
| creation_time       | 2016-08-18T22:39:25Z                                                                      |
| updated_time        | None                                                                                      |
| stack_status        | CREATE_IN_PROGRESS                                                                        |
| stack_status_reason | Stack CREATE started                                                                      |
+---------------------+-------------------------------------------------------------------------------------------+

The stack_status indicates that creation is in progress. Use the event list command to check on the stack’s orchestration progress:

$  openstack stack event list first-instance-stack

View the output of the stack show command for further details:

$  openstack stack show first-instance-stack
+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| Field                 | Value                                                                                                                                                   |
+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| id                    | cb956f56-536a-4244-930d-xxxxxxxxxxxx                                                                                                                    |
| stack_name            | first-instance-stack                                                                                                                                    |
| description           | HOT template for building the first instance stack on the Catalyst Cloud nz-por-1 region.                                                               |
|                       |                                                                                                                                                         |
| creation_time         | 2016-08-18T22:39:25Z                                                                                                                                    |
| updated_time          | None                                                                                                                                                    |
| stack_status          | CREATE_COMPLETE                                                                                                                                         |
| stack_status_reason   | Stack CREATE completed successfully                                                                                                                     |
| parameters            | OS::project_id: <PROJECT_ID>                                                                                                        |
|                       | OS::stack_id: cb956f56-536a-4244-930d-xxxxxxxxxxxx                                                                                                      |
|                       | OS::stack_name: first-instance-stack                                                                                                                    |
|                       | domain_name: localdomain                                                                                                                                |
|                       | host_name: first-instance                                                                                                                               |
|                       | image: ubuntu-18.04-x86_64                                                                                                                              |
|                       | key_name: first-instance-key                                                                                                                            |
|                       | private_net_cidr: 10.0.0.0/24                                                                                                                           |
|                       | private_net_dns_servers: 202.78.247.197,202.78.247.198,202.78.247.199                                                                                   |
|                       | private_net_gateway: 10.0.0.1                                                                                                                           |
|                       | private_net_name: private-net                                                                                                                           |
|                       | private_net_pool_end: 10.0.0.200                                                                                                                        |
|                       | private_net_pool_start: 10.0.0.10                                                                                                                       |
|                       | private_subnet_name: private-subnet                                                                                                                     |
|                       | public_net: public-net                                                                                                                                  |
|                       | public_net_id: 849ab1e9-7ac5-4618-8801-xxxxxxxxxxxx                                                                                                     |
|                       | router_name: border-router                                                                                                                              |
|                       | secgroup_name: first-instance-sg                                                                                                                        |
|                       | servers_flavor: c1.c1r1                                                                                                                                 |
|                       |                                                                                                                                                         |
| outputs               | []                                                                                                                                                      |
|                       |                                                                                                                                                         |
| links                 | - href: https://api.nz-por-1.catalystcloud.io:8004/v1/<PROJECT_ID>/stacks/first-instance-stack/cb956f56-536a-4244-930d-xxxxxxxxxxxx |
|                       |   rel: self                                                                                                                                             |
|                       |                                                                                                                                                         |
| parent                | None                                                                                                                                                    |
| disable_rollback      | True                                                                                                                                                    |
| stack_user_project_id | <PROJECT_ID>                                                                                                                        |
| stack_owner           | None                                                                                                                                                    |
| capabilities          | []                                                                                                                                                      |
| notification_topics   | []                                                                                                                                                      |
| timeout_mins          | None                                                                                                                                                    |
+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+

Once the stack status is CREATE_COMPLETE, it is possible to SSH to the Floating IP of the instance:

$ export CC_FLOATING_IP_ID=$( openstack stack resource show -f value -c physical_resource_id first-instance-stack first_instance_server_floating_ip )
$ export CC_PUBLIC_IP=$( openstack floating ip show -f value -c floating_ip_address $CC_FLOATING_IP_ID )
$ ssh ubuntu@$CC_PUBLIC_IP

Warning

If a stack has been orchestrated using Heat, it is generally a good idea to also use Heat to delete that stack’s resources. Deleting components of a Heat orchestrated stack manually, whether using the other command line tools or the web interface, can result in resources or stacks being left in an inconsistent state.

To delete the first-instance-stack created previously, proceed as follows:

$ openstack stack delete first-instance-stack
Are you sure you want to delete this stack(s) [y/N]? y

Check that the stack has been deleted properly using the openstack stack list command. If there is an error, or if deleting the stack is taking a long time, check the output of openstack stack event list first-instance-stack.