Using Heat ResourceGroup resources

This has come up a few times recently, so I wanted to share a howto showing how (and how not) to use the group resources in Heat, e.g OS::Heat::ResourceGroup and OS::Heat::AutoScalingGroup.

The key thing to remember when dealing with these resources is that they can multiply any number of resources (expressed as a heat stack), not just individual resources. This is a very cool feature when you get your head around it! :)

Lets go through a worked example, where we use ResourceGroup to create 5 identical servers, each with a cinder volume of the same size attached.

Resource group basics

To create one server with a volume attached, you define the server, a volume, and a volume attachment resource, like this:

Now, lets say you need 5 (or 500) of these identical servers with an attached volume.  What you do *not* want to do is create three groups of resources (Server, Volume and VolumeAttachment), and somehow try to connect them all together.  This is an anti-pattern which will cause you much pain and frustration! :)

Instead, you need to use ResourceGroup to scale out the combination of resources.  Fortunately, Heat makes this very easy to do.  Lets say you call the template above creating one server with attached volume server_with_volume.yaml, you can create 5 identical nested stacks, each containing one server, volume and volume attachment like this:

Note: currently templates referencing nested stack templates can only be launched via python-heatclient (not the Horizon dashboard, a known issue we're working on resolving).

Simply do heat stack-create my_group -f server_with_volume_group.yaml and Heat will create 5 identical servers, attached to 5 identical volumes!

A more complete example related to the fragments above is available here.

Resource groups and provider resources

What's that you say? You don't like the nested stack reference hard-coded template name? No problem! :) You can also make use of the environment to define a provider resource type alias.

Then specify the type alias instead of the template name in the ResourceGroup definition:

This can be lauched like thisheat stack-create my_group2 -f server_with_volume_group.yaml -e env_server_with_volume.yaml

The example will work exactly as before, only different versions of My::Server::WithVolume can easily be substituted, for example if you need a staging workflow where the resource alias is reused across a large number of templates, different versions of the nested template can easily be specified by changing it in one place (the environment).

That is all, for more information, please see the examples in the heat-templates, and this new example which shows how to attach several identical volumes to one server.