AWS CloudFormation Mappings : How and where to use.

AWS Cloud Formation Mappings.

Mappings is one of the section under AWS Cloudformation templates, which matches a key to it's corresponding set of named values

Basic mapping template.

Mappings:
  MyFirstMapping:
    Key1:
      Name: Value1
    Key2:
      Name: Value2

  MySecondMapping:
    dev:
      Name: Server1
    prod:
      Name: Server2

So from above example few things to note:

• There can be multiple mappings under mapping section.
• First/Top level key name must be different, from above template ( Key1, Key2, dev, prod)
• Second level key must be same, from above template ( Name )

Where can we use mappings.

• For example, if we want to set a instance type based upon environment or instance AMI id based on environment, we can use it to mappings.

So our Key will be environment name and Instance type and AMI id as values for specific second level key.

• We can use Fn::FindInMap intrinsic function to retrieve values in map.

So we will use the same example within our Cloud Formation script and understand it's section.

AWSTemplateFormatVersion: 2010-09-09
Description: |
  CFN Script to demonstrate Cloudformation Mappings section.

Parameters:
  EnvironmentName:
    Description: Select the environment.
    Type: String
    Default: dev
    AllowedValues:
      - dev
      - prd
  EC2KeyName:
    Description: Select your Key name from List.
    Type: AWS::EC2::KeyPair::KeyName
  EC2SecurityGroup:
    Description: Select your security group from List.
    Type: AWS::EC2::SecurityGroup::Id
  EC2Subnet:
    Description: Select your Subnet from List.
    Type: AWS::EC2::Subnet::Id

Mappings:
  InstanceTypeMap:
    dev:
      defaultInstanceType: t2.micro
    prd:
      defaultInstanceType: t2.small
  ImageIdMap:
    dev:
      defaultAMI: ami-0732b62d310b80e97
    prd:
      defaultAMI: ami-0732b62d310b80e97
  
Resources:
  CreateEC2Instance:
    Type: "AWS::EC2::Instance"
    Properties:
      ImageId: !FindInMap
      - ImageIdMap
      - !Ref EnvironmentName
      - defaultAMI
      InstanceType: !FindInMap
        - InstanceTypeMap
        - !Ref EnvironmentName
        - defaultInstanceType
      KeyName: !Ref EC2KeyName
      SubnetId: !Ref EC2Subnet
      SecurityGroupIds: 
       - !Ref EC2SecurityGroup

So from above template, 

• We can launch a basic EC2 instance and here mappings is used to decide which AMI ID and Instance Type based upon environment dev or prod.
• Parameters section has the EnvironmentName parameter, from which an user can select his/her environment name which can be prod or dev.

Mappings section : We have created two maps as

• InstanceTypeMap : 
• First/Top level keys : dev and prod
• Second Level key : defaultInstanceType.
• Second level values : t2.micro and t2.small
• ImageIdMap:
• First/Top level keys : dev and prod
• Second Level key : defaultAMI
• Second level values : ami-0732b62d3 andami-0732b6223

How to Use/Call mapping values within our resource section using intrinsic function FindInMap.

Our above template has two mappings and we will know how it has been referenced under resource section.

EC2 Instance creation resource has a requirement of ImageId through which we can declare our AMI Id.

So we can use the below template as base template.

ImageId: !FindInMap
      - MappingLogicalId
      - !Ref ParameterLogicalId
      - SecondLevelKey

With above base template can be replaced with our values as.

• Mapping Logical Id : ImageIdMap
• Top/First Level Key : We have used Parameter to grab it as user input.
• Second Level Key : defaultAMI

ImageId: !FindInMap
      - ImageIdMap
      - !Ref EnvironmentName
      - defaultAMI

Thus Same way, we have called mapping values under InstanceType's value.

InstanceType: !FindInMap
        - InstanceTypeMap
        - !Ref EnvironmentName
        - defaultInstanceType

Within next post i will cover mappings with Mappings with Pseudo parameters.

Read more ...