Openstack Heat is an "orchestration tool" which is used to define a collection of virtual resources (Servers, networks, volumes, firewalls etc) which should be created in bulk. To define such a collection of resources you use text-files in a YAML format called the "Heat Orchestration Template", or HOT files. When a collection of resources is defined you can create one or more instances of that collection. A typical use-case can be to create a HOT-template describing a single lab-instance for a student-group, and then instantiate it multiple times to create multiple identical LAB scenarios.
Documentation
Heat is a large tool, with online documentation which is updated by the team developing Heat. The online documentation is found HERE, and it is recommended to familiarize yourself with it. It might be a bit overwhelming at first, so the guide on the following wiki-page might be a good starting-point to understand some of the Heat functionality.
Example-case
To demonstrate the use of heat we are going to create a virtual lab infrastructure consisting of two virtual servers connected to a single network. One of the servers should have an extra disk connected which it is going to share to the other using NFS, to demonstrate multiple bits of Heats functionality. We are going to create two Heat-templates for this example, one for some common resources needed by all the labs, and one for each server-pair. The following figure might help visualize the intended setup:
![](/wiki/download/attachments/260451153/HeatGuide.drawio.png?version=1&modificationDate=1660744044327&api=v2)
Common infrastructure
The common infrastructure is in this case a virtual network connected to a virtual switch. In addition we create a common firewall-group allowing traffic to/from our servers.
Base template structure
A heat-template is a YAML file, and the base structure looks something like so:
heat_template_version: 2018-08-31
description:
# a description of the template
parameters:
# declaration of input parameters
resources:
# declaration of template resources
outputs:
# declaration of output parameters
Basicly there is a block for inputs, a block for resources and a block for outputs.
Heat template for our common infrastructure
For our common infrastructure we do not need any inputs, but we would like to create som resources and give the ID of the created resources as output so that we can use them as inputs for other templates. This can result in a template looking like this:
heat_template_version: 2018-08-31
description: >
A template to create common base infrastructure for the heat-guide at
https://www.ntnu.no/wiki/display/skyhigh/Openstack+Heat
resources:
network:
type: OS::Neutron::Net
subnet_v4:
type: OS::Neutron::Subnet
properties:
network_id: { get_resource: network }
cidr: '192.168.0.0/24'
dns_nameservers: [ '129.241.0.200', '129.241.0.201' ]
ip_version: 4
router:
type: OS::Neutron::Router
properties:
external_gateway_info: { network: ntnu-internal }
router_interface_v4:
type: OS::Neutron::RouterInterface
properties:
router_id: { get_resource: router }
subnet: { get_resource: subnet_v4 }
secgroup_generic:
type: OS::Neutron::SecurityGroup
properties:
description: |
A security group allowing users connect to the VM's using ssh
rules:
- protocol: icmp
remote_ip_prefix: '0.0.0.0/0'
- protocol: tcp
port_range_min: 22
port_range_max: 22
remote_ip_prefix: '0.0.0.0/0'
- protocol: tcp
remote_ip_prefix: '192.168.0.0/24'
port_range_min: 111
port_range_max: 111
- protocol: udp
remote_ip_prefix: '192.168.0.0/24'
port_range_min: 111
port_range_max: 111
- protocol: tcp
remote_ip_prefix: '192.168.0.0/24'
port_range_min: 2049
port_range_max: 2049
- protocol: udp
remote_ip_prefix: '192.168.0.0/24'
port_range_min: 2049
port_range_max: 2049
- protocol: tcp
remote_ip_prefix: '192.168.0.0/24'
port_range_min: 32767
port_range_max: 32768
- protocol: udp
remote_ip_prefix: '192.168.0.0/24'
port_range_min: 32767
port_range_max: 32768
outputs:
network:
description: The network created by the template
value: { get_resource: network }
secgroup_generic:
description: The security-group allowing generiv VM access.
value: { get_resource: secgroup_generic }
Basically we are here telling heat to create a network for us (line 8-9) with a subnetwork connected to it (line 11-17). The subnetwork should use the address 192.168.0.0/24. Next up we create a router connected to the 'ntnu-internal' network, and attaching it to the newly created subnet. The final resource defined is a security-group allowing incoming ssh-connections from anywhere, incoming ICMP (ie: ping) from anywhere and incoming NFS-connections from any hosts at the supplied subnet.
The "get resource" functions used allows heat to reffer to resources it creates elsewhere in the template. For instance we reffer to the network "{ get_resource: network }" when creating the subnet, and that basicly means "use the ID from the network you are creating". As an alternative you could have given a network ID ther manually instead.
Actually create the resources defined in our template
When a template is defined it is possible to use it to create a "heat stack". A "stack" is the resources created based on a template, and you can create multiple stacks using the same template if you want to have multiple copies of the same infrastructure. Creating the stack can be done through both the webinterface and the commandline-client. Even though most of this article will use the commandline we will also show the creation of the first stack through the webclient.
Creating a Heat Stack in the webinterface
To create a Heat stack in the webinterface you should navigate to "Orchestration → Stacks" and click the "Launch Stack" button. There you can either select template-files from your computer, or you can paste the templates into text-fields.
![](/wiki/download/thumbnails/260451153/01-web-create.png?version=1&modificationDate=1661868237378&api=v2)
![](/wiki/download/thumbnails/260451153/02-web-create.png?version=1&modificationDate=1661868246237&api=v2)
![](/wiki/download/attachments/260451153/03-web-create.png?version=1&modificationDate=1661868250495&api=v2)
After a little bit of time the stack should be "Create Complete", and you can now browse the networks/routers/security group pages to see the newly created resources.
Creating a Heat Stack using the command line
Creating a heat-stack using the commandline is done through the use of a single "openstack stack create" command. The stacks can be listed afterwards using the "openstack stack list" command.
$ openstack stack create -t common.yaml Common-CLI
+---------------------+-------------------------------------------------------------------------------------------------------------------+
| Field | Value |
+---------------------+-------------------------------------------------------------------------------------------------------------------+
| id | 925313a9-be62-45ef-80f2-f811e57fe4fa |
| stack_name | Common-CLI |
| description | A template to create common base infrastructure for the heat-guide at |
| | https://www.ntnu.no/wiki/display/skyhigh/Openstack+Heat |
| | |
| creation_time | 2022-08-30T14:07:36Z |
| updated_time | None |
| stack_status | CREATE_IN_PROGRESS |
| stack_status_reason | Stack CREATE started |
+---------------------+-------------------------------------------------------------------------------------------------------------------+
$ openstack stack list
+--------------------------------------+------------+-----------------+----------------------+--------------+
| ID | Stack Name | Stack Status | Creation Time | Updated Time |
+--------------------------------------+------------+-----------------+----------------------+--------------+
| 925313a9-be62-45ef-80f2-f811e57fe4fa | Common-CLI | CREATE_COMPLETE | 2022-08-30T14:07:36Z | None |
+--------------------------------------+------------+-----------------+----------------------+--------------+
Displaying the status of the heat stack.
Navigating using the web-client lets us see the resources created and managed by the stack, and also the output from the stack. In this case the output is the ID of the created network and the ID of the created security group.
![](/wiki/download/attachments/260451153/04-web-verify.png?version=1&modificationDate=1661868619424&api=v2)
The same information is also available through the CLI:
$ openstack stack show Common
+-----------------------+-----------------------------------------------------------------------------------------------------------------+
| Field | Value |
+-----------------------+-----------------------------------------------------------------------------------------------------------------+
| id | 2abc3c47-044a-4075-a1f6-422ee49376d8 |
| stack_name | Common |
| description | A template to create common base infrastructure for the heat-guide at |
| | https://www.ntnu.no/wiki/display/skyhigh/Openstack+Heat |
| | |
| creation_time | 2022-08-30T13:51:20Z |
| updated_time | None |
| stack_status | CREATE_COMPLETE |
| stack_status_reason | Stack CREATE completed successfully |
| parameters | OS::project_id: 74729572aad24d93b9a4cac7301ef9d1 |
| | OS::stack_id: 2abc3c47-044a-4075-a1f6-422ee49376d8 |
| | OS::stack_name: Common |
| | |
| outputs | - description: The security-group allowing generiv VM access. |
| | output_key: secgroup_generic |
| | output_value: 30586c14-7bc1-4ef4-91dc-2089eb32ec23 |
| | - description: The network created by the template |
| | output_key: network |
| | output_value: db265ea1-1d85-47f1-ba3a-714174da114e |
| | |
| links | - href: https://api.stack.it.ntnu.no:8004/v1/74729572aad24d93b9a4cac7301ef9d1/stacks/Common/2abc3c47-044a-4075- |
| | a1f6-422ee49376d8 |
| | rel: self |
| | |
| deletion_time | None |
| notification_topics | [] |
| capabilities | [] |
| disable_rollback | True |
| timeout_mins | 60 |
| stack_owner | eigilo |
| parent | None |
| stack_user_project_id | 9865a03e9eb042bc9de03578a9eca6ed |
| tags | [] |
| | |
+-----------------------+-----------------------------------------------------------------------------------------------------------------+
Student Lab
The second template we are going to create two virual machies; one fileserver connected to an extra volume and one client connecting to this fileserver. This template should be possible to start multiple times to create multiple machines. It will also demonstrate how to configure machines using both cloud-config and shell-scripts.
Parameters
This template should be able to recieve parameters when it is created, to allow variations of the template being created. Parameters can in heat be defined like so:
parameters:
flavor:
type: string
label: Fileserver flavor
description: The flavor used to spawn the fileserver
constraints:
- custom_constraint: nova.flavor
ubuntu:
type: string
label: Fileserver image
description: The image used to spawn the fileserver
constraints:
- custom_constraint: glance.image
admin-ssh-key:
type: string
label: SSH Key admin
description: The SSH-key to inject in the fileserver for admin-purposes.
user-ssh-key:
type: string
label: SSH Key User
description: The SSH-key to inject in the fileserver for the user user.
secgroup_generic:
type: string
network:
type: string
volume_type:
type: string
label: Volume type
description: The cinder-type used to create the volume for the fileserver
default: 'HDD-300'
constraints:
- custom_constraint: cinder.vtype
volume_size:
type: number
label: Volume size
default: 2
description: The size of the exported volume from the fileserver
The parameters for this template would thus be:
- flavor: An openstack flavor defining the specifications for the two virtual machines we are going to make
- ubuntu: The ID of the openstack-image which we are using to create our VM's
- admin-ssh-key: An ssh-key to be injected into the "administrator" user of the machines
- user-ssh-key: An ssh-key to be injected into the "user" user of the machines
- secgroup_generic: The ID of the security-group to use
- network: The ID of the network to connect the machines to
- volume_type: The name of the Openstack volume type to use. This one defaults to "HDD-300", and you do not need to specify it unless you want another type.
- volume_size: The size og the volume attached to the fileserver. This one defaults to "2", an you do not need to specify it unless you want another size.