CloudFormation Examples on GitHub

Another post from The Department of Quick Wins; How to search for CloudFormation examples on GitHub.

I'm a big fan of the AWS Documentation in general. I also know first-hand (many times over) that it's not perfect; and realistically there's a limit to how much the service teams can provide.

As someone who likes to get their hands dirty when learning a new service, I quickly jump to the quick starts and samples, but I often find that these examples - while they're good enough for a "hello world" kind of experience - don't go far enough.

Luckily, finding crowed sourced examples is not that hard; CloudFormation lends itself well to this because it has such a clearly defined language - I'd argue it's one of its selling points! Combine that with GitHub Search's prefix-based code search syntax, and you can quickly find real examples that can supplement the official examples.

Examples

In this example I'm looking for inline examples of CodePipeline's pipeline stages syntax, as I'm always forgetting it and the CloudFormation docs are a bit light-on with detailed examples.

Resource Types

When you're working with a specific CloudFormation Resource, the Resource and Property Types Reference is your friend. By searching for the specific resource Type that you're implementing, you can see what's working for other people:

"type aws codepipeline"

I deliberately haven't included the ":" as GitHub Search ignores them anyway. You'd think adding the full resource type (i.e. aws codepipeline pipeline) would work better, but GitHub doesn't seem to like it when your quoted string gets too long, and starts ignore the end.

Templates

If you're getting a bunch of non-template results, force the search to show you only CloudFormation templates with:

"AWSTemplateFormatVersion"

Filetype

Now that you're seeing templates, narrow it down to YAML results with:

 extension:yaml extension:yml

The key to note here is that these two search terms are combined as a logical "OR" (as opposed to an "AND" which is how many other terms work together); a file obviously cannot have an extension of yaml AND yml. This means you get results with both.

Searching with the extension: prefix also has the benefit of switching your results to the "Code" results, rather than showing you repositories, issues, etc.

I guess if you wanted to you could also search for JSON templates; my experience is that YAML templates on GitHub are generally more recent than JSON templates, so you'll get better-quality results with YAML; plus, it just looks nicer 😝

All Together Now

Here's what the final example looks like:

"type aws codepipeline" "AWSTemplateFormatVersion"  extension:yaml extension:yml

This search gives me a few results that I can reference, which is usually enough to get me productive, quickly:

Serverless Application Model

While there are a lot of good examples in the SAM repo, I often find myself looking for more examples of SAM templates.

You can limit your searches to SAM templates by searching for the transform definition:

"Transform: AWS::Serverless-2016-10-31"

Again, the ":" is ignored, but there's no harm including it.

Caveat Scrutator

Note that none of this is a guarantee of quality or security. Please please don't just download some templates from the Internet and launch them in your account, it's just not a Good Idea.

Other Code

Obviously this technique for searching GitHub is not unique to CloudFormation, and can be quickly and easily applied to other languages. The reason why it works so well for CloudFormation because it has such a clearly defined language; User-determined variable names (aka. resource identifiers), are such a small part of a template, that you can still easily find what you're looking for on GitHub. Compare this to actual programming languages, where variable/method naming makes up a majority of the content.

Another AWS-relevant example that works well is when looking for the usage of specific AWS SDK calls. Given the names are consistent (within a language, at least) then you can search for them with some similar parameters.

Photo by Anthony Martino on Unsplash