Lono Improvements v2.1.0

Recently, I’ve made some major improvements and updates to the lono tool. I thought it would be nice to provide a post detailing the changes for everyone.

Summary

  • Official http://lono.cloud/ documentation site. There’s an official documentation site now. 🎉

  • Much improved lono error stack traces. It will now show the exact line of code where the template ERB view error is instead of a scary and less useful backtrace to the internal lono code.

  • YAML as well as JSON is now supported. It took me a little bit of time but I think YAML is more concise and easier to read.

  • lono param file generation. You can specify CloudFormation parameters with simple formatted key=value env-like file and it generates the CloudFormation parameters for you. Example: http://lono.cloud/docs/scratch-params-build/

  • lono cfn lifecyle commands. The nice thing about the lono cfn lifecycle commands is that it will automatically call lono generate so you never forget.

  • Standalone installer: https://www.boltops.com/toolbelt — This handles installing all the dependencies for you like ruby. Gem installation is still available for those who prefer it.

Details

Let’s cover the updates in a little more detailed now.

Official documentation site

The old documentation was pretty much the README before. As lono’s features grew the README got quite long and became overwhelming for new users. Most of the documentation has now been moved to the official documentation site and the README provides a nice quick start summary for users. I hope the lono documentation site provides a useful resource for everyone!

Improved Error Stack Traces

I honestly have no idea how lono lived so long without this major improvement. Before when you made a syntax error in a lono ERB template, the stack trace would look something like this:

$ lono generate
/Users/tung/.rbenv/versions/2.4.1/lib/ruby/2.4.0/erb.rb:896:in `eval': (erb):5: syntax error, unexpected ':', expecting end-of-input (SyntaxError)
Parameters:
           ^
  from /Users/tung/.rbenv/versions/2.4.1/lib/ruby/2.4.0/erb.rb:896:in `result'
...
  from /Users/tung/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/lono-1.0.2/lib/lono/cli.rb:23:in `generate'
  from /Users/tung/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/thor-0.19.4/lib/thor/command.rb:27:in `run'
...
  from /Users/tung/.rbenv/versions/2.4.1/bin/lono:22:in `load'
  from /Users/tung/.rbenv/versions/2.4.1/bin/lono:22:in `<main>'
$

I know, that stack trace hurts the eyes so much that it possibly makes them painfully bleed, resulting in you rushing to call for an ambulance and getting professional medical help; that costs a small fortune. Fortunately, with the new version of lono you do not have to worry about this specific scenario with your eyes as much. Here’s an example stack trace with the same error:

The output is even colorizes so you can clearly where the error is 😁 Huge thanks to Matt Galloway for helping me implement this feature.

YAML Support

AWS CloudFormation officially introduced support for writing your template in YAML format in September 19, 2016. It sadly took me 8 months to add YAML support. Best reason I can give you: kids.

At first, I was actually not used to writing the templates in YAML but I’m getting fairly used to it now. I also use these commands to convert from JSON to YAML and vice versa.

From YAML to JSON:

ruby -ryaml -rjson -e 'puts JSON.pretty_generate(YAML.load(ARGF))' < /path/to/yaml/file

From JSON to YAML:

ruby -ryaml -rjson -e 'puts YAML.dump(JSON.load(ARGF))' < /path/to/json/file

Sometimes it is useful to go back to JSON so I can use Stephen’s lovely jq tool.

Lono Param Generation

Writing parameter files in AWS official format is a bit verbose. I can completely understand why AWS has chosen to use such a verbose format due to it’s flexibility, but for most cases a simpler format perfectly suffices. Here’s the concise format:

KeyName=tutorial
InstanceType=t2.micro

Verbose:

[
  {
    "ParameterKey": "InstanceType",
    "ParameterValue": "t2.micro"
  },
  {
    "ParameterKey": "KeyName",
    "ParameterValue": "tutorial"
  }
]

This simple key=value env file format is much easier on the eyes. And it similarly helps you escape from the ambulance scenario explained in the stack trace improvements above.

Lono Cfn Lifecycle Commands

Lono now has lono cfn lifecycle commands built in. A couple of folks asked about this in the past and now it’s here! You can create, update, delete and even preview stack updates!

$ lono cfn create mystack-$(date +%Y%m%d%H%M%S) --template mystack --params mystack
$ lono cfn create mystack-$(date +%Y%m%d%H%M%S) # shorthand if template and params file matches.
$ lono cfn diff mystack-1493859659
$ lono cfn preview mystack-1493859659
$ lono cfn update mystack-1493859659
$ lono cfn delete mystack-1493859659
$ lono cfn create -h # getting help

More details are available on the official docs: Creating the Stack.

Convenient Standalone Installer

Lono is dependent on a newer versions of a ruby installation on your system. This is an extra step for some folks and is a barrier to trying it out. Lono is included in the bolts toolbelt which allows you install lono without dealing with it’s dependencies. All it takes is a single command:

brew cask install boltopslabs/software/bolts

Of course, the RubyGems installation method still works just as good. Installation instructions are on the docs.

Thanks for Reading

I would absolutely love constructive feedback. It helps me learn and improve. 😁