Maximize Organization of your Cloudformation Template Using the Mappings Section

Organize your Mappings Section into subsections of common purpose for smooth integration with multiple templates with a plus for better readability!

The mappings section of a cloudformation template allows specific values to be mapped into keys to be used at different parts of your template. This might not seem all too important but as soon as the template of your stack gets longer with more resources, and as your stack references other stack resources, then this becomes a deciding factor in your final template’s readability and adaptability to changes.

I will explain here my approach to utilizing the mappings section. This is by no means an “official best practices” guide, but this is simply how I would often utilize the mappings section to organize my template structure. I will be demonstrating this approach by explaining snippets in a sample template I prepared, together with the reasons and benefits of following the approach. You can check out the complete cloudformation template (00.format-and-style.yaml) I will be using in this article.

Let’s get down to it.

Organize your key-value pairs into sections of common purpose!

The above snippet shows the Mappings declarations into 4 main groups: Naming Prefix (Application Naming Construct), Settings, Stacks, and Tags. I explain how these groups differ from each other below.

a. Application Naming Construct

This is none other than the prefixes for naming the resources created in the stack. Since naming prefixes are repeated all throughout the physical names of resources in the template, then they are defined here in the Mappings Section as one group. A lambda, and a role, can then refer to these in their physical name definitions shown respectively below:

For the naming convention being adopted here, please refer to this. (Check here to go straight to the lambda naming convention. Check here to go straight to that for IAM resources.)

b. Settings

This is where settings of AWS resources would be put. In the template I made, I organized Kinesis-related lambda settings under “Kinesis”. Putting these in the Mappings section allows one to quickly see all of the settings being set in different parts of the template all in one place. Similarly, the Kinesis Trigger Events definition of the Lambda resource would also just simply refer to the Settings values as shown below:

You might even separate the settings per environment and have something like:

The values under Settings in the above example would then be mapped in accordance with Env, which in this case is assumed to be a parameter in the template in the Parameters section.

c. Stacks

This is where I group all of the external stacks that the stack template refers to via Cross-Stack referencing. In the template provided, there are three stacks (Kinesis, Network, and Queue) with their corresponding exported resource references under Exports. The exported Stream ARN for instance, would then be imported through the Mappings values as shown below:

d. Tags

Lastly, tags! This is where I put tags used for resource tagging. They might be the whole values, or possibly prefixes to be joined with some parameters. My template example sets these as constant values fully defined under Mappings.

There you have it! :)

This article explained how I organize definitions under the Mappings section of a cloudformation template. The approach allows the reader to immediately get a bird’s-eye view of the entire stack information which includes cross-stack references, and naming prefixes , among other things without checking every line of the template. Putting highly-repeated keywords in the Mappings section especially physical name prefixes, and tag key-value pairs, would also allow for quick and short changes when these values need to change.