This is the beginning of a series of posts on AWS Cloudformation.
Infrastructure as code is a rather game changing development in the tech world. Cloudformation being the major IaC format for AWS.
AWS documentation leave a lot to be desired to the novice. They are written in an extremely technical fashion and not the most fun or even clear to an expert at best…and actually missing information, outdated, or unclear at their worst. Not blaming AWS or anything, they do an amazing job with the massive amount of docs they have to have, I just want to help them out.
My goal is to document all of learning as I go from noob to pro and write the docs I wish I had. If there are any issues or places that I can update these guides to make things clearer, please leave a comment or email and let me know how I can improve these docs.
Section 1 – The Template Format
The basic framework for CF templates is actually pretty simple. It’s a single file, called a template, that you use to build up an entire set of AWS resources, called a stack. A single template could define a single server in the stack or a template could define an entire infrastructure stack, with everything needed to make a complex enterprise system from various AWS offerings, including load balancers, autoscalers, lambdas, and more.
The templates can be defined in either JSON or YML format and the syntactic sugar is different but the content is the same. I’m going to use JSON in these guides because I prefer it, but either is perfectly acceptable and the ideas should translate seamlessly between the two.
The basic CF template can be broken up into several subsections.
{
"AWSTemplateFormatVersion" : "2010-09-09",
"Description" : "JSON string",
"Parameters" : {
set of parameters
},
"Mappings" : {
set of mappings
},
"Conditions" : {
set of conditions
},
"Resources" : {
set of resources
},
"Outputs" : {
set of outputs
}
}
We shall get to all of these sections as we go along, but a brief breakdown is as follows.
AWS template version: this is not a custom date that you define. This is a specific versioning of AWS template represented by a date. It defines the capabilities of the template. The funny part, after reading the docs, is that the only allowable value for this section is: “2010-09-09”
- Template versioning info: Link
Description: A custom description of your template/stack. Put whatever you want here.
Parameters: Define values that you pass to your templates at runtime. You can pass in IP address ranges, names of things, and a lot more. Using these properly will go a long way to making your templates super reusable. We will explore this more as we go(WWETMAWG).
Mappings: A series of key/value pairs you can use within your templates. As you’ll see, these can be, and are often, nested so that you can have multiple levels of key/value pairings. (WWETMAWG)
Conditions: a set of conditions you can use to test against, for example, when creating different environments you can define conditions that creates smaller servers for development and larger servers for production.(WWETMAWG)
Resources: The actual AWS offerings are defined in this section.(WWETMAWG…majorly.) This is where all of the magic happens.
Outputs: Values that you return after running your template. Glorified return expression.
Note: There’s another section not included called Transforms used for specialty templates when creating serverless applications with the SAM DSL. Will explore SAM in detail down the road.
Section 2 – the keywords
This is the actual language that you use to build your cloud formation templates. This can be compared to the syntax of programming languages i.e. the reserved words you use to write your code.
The entire template reference is located here: Link
The two keyword types you will be using the most are:
- Resources
- These are all of the built in AWS offerings you find in the console control panel.
- Examples are: EC2, Kinesis, SNS, etc
- There are quite a few. The entire list is located here: Link. Bookmark it because you will be using it ALOT.
- Intrinsic Functions
- These are helper functions.
- These are utility functions to be used within the template itself.
- They do things like access parameters or test conditionals or format text.
- The full list is located here: Link
Section 3-running the template
Once you have finished writing your templates, there are two ways to run the templates to create your stack within AWS.
- Cloudformation tool inside of the AWS console
- AWS CLI.
You should definitely get acquainted with both because they both offer useful tools to develop and troubleshoot your templates.
AWS CLI
Poke around the docs here to figure out how to set up the AWS CLI: Link
- Note a significant gotcha when setting up the CLI is to be sure you set the output to JSON not TEXT!
Useful commands for CRUD inside of the AWS CLI are:
- aws cloudformation create-stack
- aws cloudformation delete-stack
- aws cloudformation update-stack
- aws cloudformation validate-template
- Note: validate-template simply does a cursory validation of the template, more of a JSON linting than an in depth validation that your template configuration is correct. (This needs more research as to what exactly it does.)
- Use it to find general formatting errors.
- For more info, see: Here
Useful command for describing and troubleshooting stacks are:
- aws cloudformation list-stacks
- aws cloudformation describe-stack-events
- aws cloudformation describe-stacks
Cloudformation Console
There’s a lot of tools in the CF console to work with CF templates. I’ve only used the CLI so far to create templates, but it looks pretty straightforward to create a stack by uploading a template to the CF console.
What I’ve found to be very useful is using the console to troubleshoot, once I’ve created my stack from the CLI. After running a create from the CLI you will see the stack appear in the console, and if there’s errors during the creation of the stack, you can click on that stack, and drill down into an stack trace of what went wrong during stack creation. Super useful and we’ll revisit this.
Fini
The goal of this first post was to set the foundation of the basic tools that will be used in future posts and describe the basic anatomy of CF templates. From here on out hopefully will just be actually hands on creation of templates. Thanks for reading. Tune in next time for creating our first template!
