How to Use Mappings in CloudFormation Templates

In AWS CloudFormation, Mappings let you create fixed key-value pairs to customize your template based on input like region or environment. You define a Mappings section with keys and values, then use Fn::FindInMap to retrieve values during stack creation.

Syntax

The Mappings section defines a dictionary of keys and nested keys with values. You use Fn::FindInMap to get a value by specifying the map name, top-level key, and second-level key.

Parts explained:

• Mappings: The section where you define your map.
• MapName: The name of your mapping.
• TopLevelKey: The first key to select a group.
• SecondLevelKey: The key inside the group to get the value.
• Fn::FindInMap: The function to retrieve the value from the map.

yaml

Mappings:
  RegionMap:
    us-east-1:
      HVM64: "ami-0ff8a91507f77f867"
      HVMG2: "ami-0a584ac55a7631c0c"
    us-west-1:
      HVM64: "ami-0bdb828fd58c52235"
      HVMG2: "ami-066ee5fd4a9ef77f1"

Resources:
  MyInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !FindInMap [RegionMap, !Ref "AWS::Region", HVM64]
      InstanceType: t2.micro

Example

This example shows a CloudFormation template that uses a mapping to select an Amazon Machine Image (AMI) ID based on the AWS region. The Mappings section defines AMI IDs for two regions. The EC2 instance uses Fn::FindInMap to pick the right AMI for the region where the stack is deployed.

yaml

AWSTemplateFormatVersion: '2010-09-09'
Description: Simple EC2 instance with region-based AMI

Mappings:
  RegionMap:
    us-east-1:
      AMI: "ami-0ff8a91507f77f867"
    us-west-2:
      AMI: "ami-0b898040803850657"

Resources:
  EC2Instance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !FindInMap [RegionMap, !Ref "AWS::Region", AMI]
      InstanceType: t2.micro

Output

When deployed in us-east-1, the EC2 instance uses AMI ami-0ff8a91507f77f867; in us-west-2, it uses ami-0b898040803850657.

Common Pitfalls

• Forgetting to define the Mappings section before using Fn::FindInMap causes errors.
• Using keys in Fn::FindInMap that do not exist in the mapping leads to stack creation failure.
• Not matching the case exactly in keys (mapping keys are case-sensitive).
• Trying to use parameters or functions inside Mappings is not allowed; mappings must be static.

yaml

Wrong usage example:

Resources:
  MyInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !FindInMap [RegionMap, !Ref "AWS::Region", "NonExistentKey"]  # Key not in mapping

Correct usage example:

Mappings:
  RegionMap:
    us-east-1:
      AMI: "ami-0ff8a91507f77f867"

Resources:
  MyInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !FindInMap [RegionMap, !Ref "AWS::Region", AMI]

Quick Reference

Term	Description
Mappings	Static key-value pairs defined in the template
MapName	Name of the mapping section
TopLevelKey	First key to select a group in the map
SecondLevelKey	Second key to select the value inside the group
Fn::FindInMap	Function to retrieve a value from the mapping

Key Takeaways

Mappings let you define static key-value pairs to customize templates by region or environment.

Use Fn::FindInMap with three arguments: map name, top-level key, and second-level key to get values.

Mapping keys are case-sensitive and must be defined before use.

Mappings cannot contain dynamic values like parameters or functions.

Always verify keys exist in the mapping to avoid deployment errors.