Orchestration with Heat

This article introduces the virtual machine service orchestration using OpenStack Heat available for Pouta.

You can access this feature in the web user interface's left hand panel or using the OpenStack or Heat command line client. Orchestration provides an easy way to create the entire infrastructure based on a reusable and human-readable template file. The template can describe many components of the infrastructure, such as servers, volumes and floating IPs. In the same file, it can attach the volumes and IPs to specific instances. A template can also define multiple instances connected to specific networks, some of which have floating IPs and some a volume attached. The file can also be used to modify the existing infrastructure.

Orchestration via the web user interface

Info

You should use "2018-08-31" ("rocky") or older as the Heat template version. Features in newer template versions may not be supported.

These instructions provide a simple example on how to set up a stack via the web user interface. To create a Heat stack, click the "Stacks" link in the Orchestration menu. The opened view displays all existing stacks and provides the button "Launch Stack" to launch a new stack. In the window which was opened after clicking the "Launch Stack" button, you can upload an existing template that you created or you can start configuring your stack. Selecting a template is mandatory, and the template data can also be provided as direct input, as depicted in the picture below. Note that this picture contains a valid, yet simple example of a template which builds two instances and displays the IP address of the first instance.

Here is the example:

heat_template_version: rocky # As mentioned above, you can either use the date or the name

description: Simple template to deploy a single instance in cPouta

resources:
  instance0:
    type: OS::Nova::Server
    properties:
      image: Ubuntu-22.04
      flavor: standard.small
      key_name: my-key
      networks:
        - network: project_xxxxx

  instance1:
    type: OS::Nova::Server
    properties:
      image: Centos-7
      flavor: standard.small
      key_name: my-key
      networks:
        - network: project_xxxx

outputs:
  network0:
    description: Output the networks of instance0
    value: { get_attr: [instance0, networks] }
  network1:
    description: Output the network of instance1
    value: { get_attr: [instance1, networks]}

After choosing "Next", the web user interface asks for a stack name and your password. After this, you can launch the stack. When the stack is built, it can be managed from the orchestration's Stacks view. The items which were built as a part of the stack can be found in their corresponding menus. In this case, the two instances can be seen and managed in the instances menu. In the stack's Overview tab (Orchestration -> Stacks -> click the stack), you can also see the output defined by the "outputs" section in the picture's example. To delete all components created by the stack template, simply press "Delete Stack" on the Stacks page.

Using orchestration with the command line client

Info

Be sure that python-heatclient is installed. You can install it by typing the command pip install python-heatclient (https://pypi.org/project/python-heatclient/)

Heat can be operated with the OpenStack command line client, but currently you can still use the deprecated Heat command line client as well. Create a stack on the command line:

openstack stack create -t /path/to/my/stack.yml my-heat-stack

Show the details of the newly created stack among other existing stacks, type the command openstack stack list:

openstack stack list
+--------------------------------------+---------------+-----------------+----------------------+--------------+
| ID                                   | Stack Name    | Stack Status    | Creation Time        | Updated Time |
+--------------------------------------+---------------+-----------------+----------------------+--------------+
| 98077bd5-9d69-47c3-98db-b0e19a60b1fa | my-heat-stack | CREATE_COMPLETE | 2016-06-08T07:34:46Z | None         |
+--------------------------------------+---------------+-----------------+----------------------+--------------+

Explanations

A template is composed of two major sections:
- The version used (heat_template_version)
- The resource(s) (resources)

There are also optional sections like:
- The description (description)
- The parameter group(s) (parameter_groups)
- The parameter(s) (parameters)
- The output(s) (outputs)
- The condition(s) (conditions)

Here is a detail of each sections:

heat_template_version
     Indicates that the YAML document is a HOT (Heat Orchestration Template) template of the specified version.

description
     Allows for giving a description of the template.

parameter_groups
     Allows for specifying how the input parameter should be grouped and the order to provide the parameters.

parameters
     Allows for specifying input parameters that have to be provided when instantiating the template.

resources
     Contains the declaration of the single resources of the template.

outputs
     Allows for specifying output parameters available once the template has been instantiated.

conditions
     Includes statements which can be used to restrict when a resource is created or when a property is defined

Advanced example: create a template to build one or more instances

The plan here is:
- Create a parameter file for Openstack Heat.
- Create two Openstack Heat templates: one for the number of instance(s) (OS::Heat::ResourceGroup) and the other for the specification of the deployment.
- Create an ansible script to automate the deployment.

Info

The following tools must be installed:
- Ansible
- python-openstackclient (pip install python-openstackclient)
- python-heatclient (pip install python-heatclient)

First, you can create a heat_params.yaml that will contains different variables use for your instance. Use your own value:

parameter_defaults:
  ssh_key_name:
  vm_flavor:
  vm_image:
  vm_network:
  count:

Second, two Openstack Heat templates. For the first one, we'll take our previous examples with some modifications. We call it heat_stack_vm.yaml:

heat_template_version: rocky # As mentioned above, you can either use the date or the name

description: Simple template to deploy a single or several instance(s) in cPouta

parameters: # Since we created a heat_params.yaml, they will be retrieved from this file
  ssh_key_name:
    description: SSH key name
    type: string
  vm_name:
    description: Name for the VM
    type: string
  vm_flavor:
    description: Flavor for the VM
    type: string
  vm_image:
    description: Image for the VM
    type: string
  vm_network:
    description: Network for the VM
    type: string

resources:
  instance:
    type: OS::Nova::Server
    properties:
      name: { get_param: vm_name } # This value will be retrieved from servers_group.yaml file. See after.
      image: { get_param: vm_image }
      flavor: { get_param: vm_flavor }
      key_name: { get_param: ssh_key_name }
      networks:
        - network: { get_param: vm_network }

outputs:
  network:
    description: Output the networks of instance
    value: { get_attr: [instance, networks] }

Third, we'll create a file called servers_group.yaml, a ResourceGroup, which allows us to scale our instances:

heat_template_version: rocky

description: Resource Group to deploy one or several instance(s)

parameters: # Parameter retrieves from heat_params.yaml file.
  count:
    description: Number of resources
    type: string

resources:
  instances_group:
    type: OS::Heat::ResourceGroup
    properties:
      count: { get_param: count }
      resource_def:
        type: heat_stack_vm.yaml # We defined our previous template.
        properties:
          vm_name: test-stack-%index% # Value %index% will be increased if more than one vm is created.

outputs:
  print_out:
    value: { get_attr: [instances_group, network] }

And finally, we'll create an ansible script that will build and deploy our vm(s). Let's call it build-heat-stack.yaml:

- hosts: localhost
  gather_facts: false
  vars:
    heat_environment_file: "heat_params.yaml" # Be sure that the file is located at the same level as build-heat-stack.yaml

  tasks:
    - name: Build a Heat stack VM
      register: heat_stack
      os_stack:
        name: "{{ stack_name }}"
        state: present
        template: "servers_group.yaml" # Be sure that the file is located at the same level as build-heat-stack.yaml
        environment: 
          - "{{ heat_environment_file }}"

    - name: Print out network
      debug:
        var: heat_stack

Source your cPouta project (source project_xxxxx.sh) and run the command:

ansible-playbook -e stack_name="test-stack" build-heat-stack.yaml`

If everything went well, you can check that the stack was created, either using the web interface of cPouta or typing the command: openstack stack list.
You can also check the instance(s) created: openstack server list.

If you delete the stack, all the resources created from it will be deleted as well.

Heat guidelines and command references

For more information, visit the OpenStack Heat wiki. For a full reference to the OpenStack command line client, see the command line reference.
Here is an example on our GitHub to deploy one or several instances with nginx Read more about the GitHub repo

Do you find this page useful?

Yes

Thank you for your feedback!

No

Thank you! Your feedback is appreciated.

Please let us know how we could improve this page by contacting us or by creating an issue in GitHub. You can also edit this page yourself and contribute your improvements by creating a pull request.