AWS – Using mappings to specify regional AMI IDs

The mappings section is used to define a set of key/value pairs. If you require any kind of AWS region portability, perhaps for disaster recovery (DR) or availability purposes, or simply to get your application closer to your end user, you’ll almost certainly need to specify some mappings in your template. This is particularly necessary if you are referencing anything in your template that is region specific.

The canonical example would be to specify a map of EC2 AMI IDs in your template. This is because AMIs are a region-specific resource, so a reference to a valid Amazon Machine Image (AMI) ID in one region, will be invalid in another. In this recipe, you will create a CloudFormation stack that allows a user to choose between an instance with Linux or Windows.

How to do it…

Follow these steps to launch an EC2 instance with an AMI ID that matches your region:

  1. Go to the CloudFormation console, and click Create stack.
  2. Save the following code to a file on your filesystem:
AWSTemplateFormatVersion: "2010-09-09" 
Description: Demonstrate CloudFormation Mappings
Parameters:
  OperatingSystem: 
    Description: The operating system to run for the instance
    Type: String 
    Default: Linux 
    AllowedValues: 
      - Linux 
      - Windows 
    ConstraintDescription: Must be Linux or Windows
Mappings: 
  RegionMap: 
    us-east-1: 
      Linux: ami-035be7bafff33b6b6
      Windows: ami-0df43b4f8a07c7c14
    us-west-1: 
      Linux: ami-0799ad445b5727125 
      Windows: ami-06b499097655a3ab5
Resources:
  MyEC2Instance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: 
        !FindInMap 
          - RegionMap
          - !Ref "AWS::Region"
          - !Ref OperatingSystem 
      InstanceType: t2.micro

  1. Select  Upload a template to Amazon S3, and choose the file that you just created. Click  Next, and give the stack a name. 
  2. Click  Next, and then  Next on the following screen.
  3. Click  Create.
  4. Go to the EC2 dashboard to confirm the creation of the EC2 instance with the correct AMI.
  5. Delete the stack.

How it works…

Mappings are simply dictionaries of name-value pairs, which allow you to make decisions based on variables such as which region the stack is being created in, or whether the environment is in production or development. You use the Fn::FindInMap function to access the contents of the mapping. Mappings have two levels of keys; there is a first level that has keys according to a top-level item, such as regions, and then a second level that allows you to define multiple subkeys, such as the operating system type in our previous example.

There’s more…

This recipe creates a simple EC2 instance, but, by default, it does not configure an SSH key, or a security group that would allow you to log in remotely. We will cover these options in a later chapter, but if you are curious, go ahead and investigate the AWS::EC2::SecurityGroup resource type, and the KeyName property of the AWS::EC2::Instance resource. Another option for securely logging in to your EC2 instance is AWS Systems Manager Session Manager, a relatively new service that directly gives you a shell login to Linux instances via the AWS console.

See also

  • The Using StackSets to deploy resources to multiple regions recipe in this chapter, for one of the most common uses of mappings
  • See Chapter 4, AWS Compute, for a more detailed introduction to EC2 instances

Comments are closed.