openstack-heat

OpenStack Heat -- Orchestration Service

Introduction

Heat is OpenStack's native orchestration engine. It implements infrastructure-as-code through HOT (Heat Orchestration Template) files -- YAML documents that declaratively describe cloud resources and their relationships. Heat creates, updates, and deletes collections of resources (called "stacks") as atomic units, handling dependency ordering, rollback on failure, and lifecycle management automatically.

Heat is to OpenStack what CloudFormation is to AWS and Deployment Manager is to GCP. The critical difference: HOT templates are portable across any OpenStack deployment, and Heat's resource type registry is extensible -- operators can register custom resource types without modifying the core service. For users familiar with Terraform, Heat serves a similar role but is integrated directly into the OpenStack control plane, meaning it has native access to all OpenStack APIs without external provider configuration.

The stack lifecycle follows a state machine: CREATE_IN_PROGRESS, CREATE_COMPLETE, CREATE_FAILED, UPDATE_IN_PROGRESS, UPDATE_COMPLETE, UPDATE_FAILED, DELETE_IN_PROGRESS, DELETE_COMPLETE, DELETE_FAILED. Each state transition is atomic -- either all resources in a stack reach the target state or the stack rolls back to the previous known-good state.

Deploy

Heat deployment via Kolla-Ansible requires enabling the service in globals.yml:

# /etc/kolla/globals.yml
enable_heat: "yes"

After deployment, Heat runs as two containers: heat_api (handles REST API requests) and heat_engine (processes stack operations, manages resource lifecycle). Some deployments also include heat_api_cfn for CloudFormation API compatibility.

Verification commands:

# Verify Heat containers are running
docker ps --filter name=heat

# Verify service registration in Keystone catalog
openstack service list | grep orchestration

# Verify Heat API is responsive
openstack orchestration service list

# Check engine status
openstack orchestration service list --format json

The orchestration service should appear with type orchestration in the service catalog. The engine should report status up with a recent updated_at timestamp. If the engine shows down, check the heat_engine container logs: docker logs heat_engine.

Configure

Template Format (HOT)

HOT templates are YAML documents with four top-level sections:

heat_template_version: wallaby    # OpenStack release name or date (2021-04-16)

description: >
  Human-readable description of what this template creates.

parameters:
  instance_name:
    type: string
    default: my-server
    description: Name for the Nova instance
    constraints:
      - length: { min: 1, max: 64 }
  image_id:
    type: string
    description: Glance image ID to use
  flavor:
    type: string
    default: m1.small

resources:
  my_network:
    type: OS::Neutron::Net
    properties:
      name: template-network

  my_subnet:
    type: OS::Neutron::Subnet
    properties:
      network_id: { get_resource: my_network }
      cidr: 10.0.1.0/24
      dns_nameservers: [8.8.8.8]

  my_server:
    type: OS::Nova::Server
    properties:
      name: { get_param: instance_name }
      image: { get_param: image_id }
      flavor: { get_param: flavor }
      networks:
        - network: { get_resource: my_network }

outputs:
  server_ip:
    description: IP address of the created instance
    value: { get_attr: [my_server, first_address] }

Core Resource Types

| Resource Type | Service | Purpose | |--------------|---------|---------| | OS::Nova::Server | Nova | Compute instances | | OS::Neutron::Net | Neutron | Virtual networks | | OS::Neutron::Subnet | Neutron | Subnets with CIDR blocks | | OS::Neutron::Router | Neutron | Virtual routers | | OS::Neutron::FloatingIP | Neutron | Floating IP allocation | | OS::Neutron::SecurityGroup | Neutron | Security group rules | | OS::Cinder::Volume | Cinder | Block storage volumes | | OS::Cinder::VolumeAttachment | Cinder | Volume-to-instance attachment | | OS::Glance::Image | Glance | Image registration | | OS::Swift::Container | Swift | Object storage containers | | OS::Keystone::Project | Keystone | Project creation | | OS::Heat::AutoScalingGroup | Heat | Auto-scaling groups | | OS::Heat::ScalingPolicy | Heat | Scaling policies | | OS::Heat::SoftwareConfig | Heat | Software configuration scripts | | OS::Heat::SoftwareDeployment | Heat | Software deployment execution | | OS::Heat::WaitCondition | Heat | Wait for external signals |

Intrinsic Functions

| Function | Purpose | Example | |----------|---------|---------| | get_resource | Reference another resource in the template | { get_resource: my_network } | | get_attr | Get an attribute from a resource | { get_attr: [my_server, first_address] } | | get_param | Get a parameter value | { get_param: instance_name } | | str_replace | String substitution | { str_replace: { template: "host=$HOST", params: { $HOST: { get_attr: [srv, first_address] } } } } | | list_join | Join list elements | { list_join: [",", [a, b, c]] } | | if | Conditional value | { if: [condition, value_true, value_false] } | | repeat | Iterate over a list | { repeat: { for_each: { "%item%": [a, b] }, template: { ... } } } |

Environment Files

Environment files override parameter defaults and map custom resource types:

# env.yaml
parameters:
  image_id: cirros-0.5.2
  flavor: m1.tiny

resource_registry:
  "OS::Nova::Server::Custom": custom_server.yaml

Nested Stacks

Templates can include other templates using OS::Heat::Stack or type: file.yaml:

resources:
  web_tier:
    type: web-server.yaml
    properties:
      image: { get_param: image_id }
      count: 3

Auto-Scaling Groups

resources:
  asg:
    type: OS::Heat::AutoScalingGroup
    properties:
      min_size: 1
      max_size: 5
      desired_capacity: 2
      resource:
        type: OS::Nova::Server
        properties:
          image: { get_param: image_id }
          flavor: m1.small

  scale_up_policy:
    type: OS::Heat::ScalingPolicy
    properties:
      adjustment_type: change_in_capacity
      auto_scaling_group_id: { get_resource: asg }
      scaling_adjustment: 1

Operate

Stack CRUD

# Create a stack from a template
openstack stack create -t template.yaml -e env.yaml \
  --parameter "instance_name=prod-web" my-stack

# List all stacks
openstack stack list

# Show stack details
openstack stack show my-stack

# Show stack resources
openstack stack resource list my-stack

# Show specific resource details
openstack stack resource show my-stack my_server

# Show stack events (creation timeline)
openstack stack event list my-stack

# Show stack outputs
openstack stack output list my-stack
openstack stack output show my-stack server_ip

Stack Update

# Update with modified template (in-place where possible)
openstack stack update -t updated-template.yaml my-stack

# Update parameters only
openstack stack update --parameter "flavor=m1.large" my-stack

# Preview update before applying (shows what will change)
openstack stack update --dry-run -t updated-template.yaml my-stack

Update semantics: Heat determines whether each resource can be updated in-place or requires replacement. Replacement creates a new resource before deleting the old one. Use --dry-run to preview which resources will be replaced.

Template Validation

# Validate template syntax and resource types
openstack stack template validate -t template.yaml

# Validate with environment
openstack stack template validate -t template.yaml -e env.yaml

Stack Lifecycle

# Suspend all resources in a stack
openstack stack suspend my-stack

# Resume suspended stack
openstack stack resume my-stack

# Create stack snapshot
openstack stack snapshot create my-stack snap-before-upgrade