Lab 04: Mapping

Overview

This lab will introduce Mappings. A Mappings section is a top level section of a CloudFormation template. It is used to define maps, their keys and values which can be then referenced in your template.

A diagram of the structure of a mappings section

Here is a simplified example of a Mappings section. It contains one Map, AnExampleMapping.
AnExampleMapping contains three top level keys, Key01, Key02 and Key03.
Each top level key contains one or more Key: Value pairs.

Mappings:
  AnExampleMap:
    TopLevelKey01:
      Key01: Value01
      Key02: Value02

    TopLevelKey02:
      AnotherKey: AnExampleValue

    TopLevelKey03:
      AFinalKey: ADifferentValue

Topics Covered

In this Lab, you will:

  • Create a mapping for environment type such as Test or Prod. Each environment type will be mapped to different instance type.
  • Find the required value in mappings and reference it in properties section of the EC2 resource.

Start Lab

You will now add a Mappings section to your own template.

The templates for this lab can be found in code/20-cloudformation-features
The starting template is 05-lab04-Mapping.yaml
The final template is 06-lab04-Mapping-Solution.yaml

1. Let’s start with creating EnvironmentType parameter

This section will define two possible environments, Test and Prod. It will use a new parameter, EnvironmentType.

In the Parameters section of the template. Replace the InstanceType parameter with the code below (you will not need the InstanceType parameter anymore. You will use the mapping instead).

Parameters:
  EnvironmentType:
    Description: 'Specify the Environment type of the stack.'
    Type: String
    Default: Test
    AllowedValues:
      - Test
      - Prod
    ConstraintDescription: 'Specify either Test or Prod.'

Dont forget to remove InstanceType from the ParameterGroups and ParameterLabels sections of the template.

2. Next, create EnvironmentToInstanceType in the mapping section

The map contains two top level keys, one for each environment. Each top level key contains a single InstanceType second level key.

Mappings:
  EnvironmentToInstanceType: # Map Name
    Test: # Top level key
      InstanceType: t2.micro # Second level key
    Prod:
      InstanceType: t2.small

3. Next, modify the InstanceType property

Using the intrinsic function Fn::FindInMap, CloudFormation will lookup the value in the EnvironmentToInstanceType map and will return the value back to InstanceType property.

Resources:
  WebServerInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: !Ref AmiID
      InstanceType: !FindInMap
        - EnvironmentToInstanceType # Map Name
        - !Ref EnvironmentType # Top Level Key
        - InstanceType # Second Level Key

4. Next, update the Tags property

As you have deleted the InstanceType parameter, you will need to update the tag. Reference EnviromentType in the tag property.

Tags:
  - Key: Name
    Value: !Join [ '-', [ !Ref EnvironmentType, webserver ] ]

5. Finally, Deploy the solution

Now that you have added a Mappings section to your template, go to the AWS console and update your CloudFormation Stack.

  1. Open the AWS CloudFormation link in a new tab and log in to your AWS account.
  2. Click on the stack name, for example cfn-workshop-ec2.
  3. In the top right corner click on Update.
  4. In Prepare template, choose Replace current template.
  5. In Template source, choose Upload a template file.
  6. Click on Choose file button and navigate to your workshop directory.
  7. Select the file 05-lab04-Mapping.yaml and click Next.
  8. For Amazon Machine Image ID leave the default value in.
  9. For EnvironmentType select the environment from drop down list, for example Test and click Next.
  10. You can leave Configure stack options default, click Next.
  11. On the Review <stack_name> page, scroll down to the bottom and click on Update stack.
  12. You can click the refresh button a few times until you see in the status UPDATE_COMPLETE.

Challenge

Add another Environment, Dev, to your template. It will need to contain Dev key name, and name-value pair InstanceType: t2.nano.

Don’t forget to add Dev to the list of allowed values for the EnvironmentType parameter.

Need a hint?
Expand to see the solution

To test that your solution works, update the stack as you did in step 5. Finally, Deploy the solution and change the EnvironmentType to Dev.

Changing the instance type will cause some downtime as EC2 instance has to be stopped before changing the type.


Conclusion

Great work! You have now successfully learned how to use mappings to create more flexible CloudFormation templates.