Editing Heat Templates in Atom

Posted on Thu 18 August 2016 in articles

Now that you’re more acquainted with writing Heat templates, you might be wondering if there’s a way to make writing them easier. YAML is easy to use as a template language, but as you start to write longer and more complex templates (especially if you use Flame) you might be encountering situations that make you feel like this:

Samir

Fortunately, there are tools to make it a little easier.

One of my favorite tools, for more than just editing Heat templates, is a text editor called Atom. Yes, a text editor. “But Garett, I already have Notepad”, or “I have Wordpad with rich text editing”, or maybe even, “I’ll use Microsoft Word, I already use it for all my reports, graphic design, and even screenshots!”. As amazing and misused as those tools are, there are actually tools made just for editing code like YAML. Take a look.

Install Atom

Go to Atom.io and hit the big “Download for xxxxx” button. After the file is finished downloading, launch it and install Atom. You should be able to accept whatever defaults it prompts you for. After installation is done, launch Atom, and there should be a blank file sitting there, waiting for your next wonderful creation.

Make Atom a YAML Machine

Atom comes with built-in support for YAML, which means you get syntax highlighting out of the box. If you’ve never experienced syntax highlighting before, here’s a side by side comparison a simple heat template. The one on the left has syntax highlighting turned off, the one on the right has it turned on.

better with colors

That is so much easier to read. Next, let’s add a package to Atom that will catch a lot of syntax errors that usually cause problems in larger YAML files. Press Ctrl+, on Windows, or Cmd+, on Mac, which will pull up the Settings tab. On the left side of the tab, click on “Install” button, then in the search box type linter-js-yaml and hit enter. The first result that comes up should be a package called, fittingly, “linter-js-yaml”. Hit the install button, then wait for it complete. When it’s done, copy the below code (which is the same used in the image above, with some mines laid out for you):

### Heat Template ###
description: yaml demo in Atom
heat_template_version 2013-05-23

parameters:
  my_flavor:
    type:string
    description: VM instance flavor

resources:
  enigma:
  properties:
      diskConfig: AUTO
      flavor: { get_param|my_flavor }
      image: HAL_bae
      key_name: garettkey
      name: enigma
      networks:
      - network: skynet
    type: OS::Nova::Server

If you plug this into a file in Atom and name the file anything.yaml (that is, name it whatever you want, just add the .yaml extension) and your new-fangled linter should pop should show some errors. Look near the bottom of the screen and you’ll see something similar to the following:

errors!

Click on the text that says “# Issue” and a little box will pop up giving you a clue as to what is wrong.

tell me what's wrong baby

What does that mean? Well, thanks to syntax highlighting, if we look at the text above, we can see that pattern of colors is broken up by that plain, boring grey color. This should give you a clue as to what’s wrong. A lot of YAML consists of defining parameters in a key: value layout. What we’re missing on the line above is a colon! Add that colon, then wait a second to see if the linter finds anything else. You’ll find that as you correct one issue, the linter might find another. Just as in real life, it might feel like you’re going down a rabbit-hole of your own mistakes, but don’t worry, it’s just a YAML file. No one will judge you for it (unless you go ahead and run your Heat template knowing that there are errors in it, then your boss might be upset). Just keep correcting errors until you’re not seeing anymore errors. And then to be safe, you can do a dry-run:

heat stack-preview -f anything.yaml newstack

Or if you’re using the new unified command line tool (Oslo):

openstack stack create -t anything.yaml --dry-run newstack

The End

I hope you’ll find Atom useful both in writing Heat templates, and any other coding work. Leave a comment if there’s any other guide you’d like to see for Atom.