Mappings - AWS CloudFormation
SyntaxExamplesRelated resources

Mappings

The optional Mappings section matches a key to a corresponding set of named values. For example, if you want to set values based on a region, you can create a mapping that uses the region name as a key and contains the values you want to specify for each specific region. You use the Fn::FindInMap intrinsic function to retrieve values in a map.

You can't include parameters, pseudo parameters, or intrinsic functions in the Mappings section.

Syntax

The Mappings section consists of the key name Mappings. The keys in mappings must be literal strings. The values can be String or List types. The following example shows a Mappings section containing a single mapping named Mapping01 (the logical name).

Within a mapping, each map is a key followed by another mapping. The key must be a map of name-value pairs and unique within the mapping.

JSON

"Mappings" : {
  "Mapping01" : {
    "Key01" : {
      "Name" : "Value01"
    },
    "Key02" : {
      "Name" : "Value02"
    },
    "Key03" : {
      "Name" : "Value03"
    }
  }
}

YAML

Mappings: 
  Mapping01: 
    Key01: 
      Name: Value01
    Key02: 
      Name: Value02
    Key03: 
      Name: Value03

Examples

Basic mapping

The following example shows a Mappings section with a map RegionMap, which contains five keys that map to name-value pairs containing single string values. The keys are region names. Each name-value pair is an instance type from the T family that's available in the region represented by the key.

The name-value pairs have a name (InstanceType in the example) and a value. By naming the values, you can map more than one set of values to a key.

JSON

"Mappings" : {
  "RegionMap" : {
    "us-east-1"      : {"InstanceType": "t2.micro"},
    "us-west-1"      : {"InstanceType": "t2.micro"},
    "eu-west-1"      : {"InstanceType": "t2.micro"},
    "eu-north-1"     : {"InstanceType": "t3.micro"},
    "me-south-1"     : {"InstanceType": "t3.micro"}
  }
}

YAML

Mappings:
  RegionMap:
    us-east-1:
      InstanceType: t2.micro
    us-west-1:
      InstanceType: t2.micro
    eu-west-1:
      InstanceType: t2.micro
    eu-north-1:
      InstanceType: t3.micro
    me-south-1:
      InstanceType: t3.micro

Mapping with multiple values

The following example has region keys that are mapped to two sets of values: one named MyAMI1 and the other MyAMI2.

JSON

    "AMIIDMap" : {
      "us-east-1"        : {"MyAMI1" : "ami-0ff8a91507f77f867", "MyAMI2" : "ami-0a584ac55a7631c0c"},
      "us-west-1"        : {"MyAMI1" : "ami-0bdb828fd58c52235", "MyAMI2" : "ami-066ee5fd4a9ef77f1"},
      "eu-west-1"        : {"MyAMI1" : "ami-047bb4163c506cd98", "MyAMI2" : "ami-0a7c483d527806435"},
      "ap-southeast-1"   : {"MyAMI1" : "ami-08569b978cc4dfa10", "MyAMI2" : "ami-0be9df32ae9f92309"},
      "ap-northeast-1"   : {"MyAMI1" : "ami-06cd52961ce9f0d85", "MyAMI2" : "ami-053cdd503598e4a9d"}
    }

YAML

AMIIDMap: 
    us-east-1:
      MyAMI1: ami-0ff8a91507f77f867
      MyAMI2: ami-0a584ac55a7631c0c
    us-west-1:
      MyAMI1: ami-0bdb828fd58c52235
      MyAMI2: ami-066ee5fd4a9ef77f1
    eu-west-1:
      MyAMI1: ami-047bb4163c506cd98
      MyAMI2: ami-0a7c483d527806435
    ap-southeast-1:
      MyAMI1: ami-08569b978cc4dfa10
      MyAMI2: ami-0be9df32ae9f92309
    ap-northeast-1:
      MyAMI1: ami-06cd52961ce9f0d85
      MyAMI2: ami-053cdd503598e4a9d

Return a value from a mapping

You can use the Fn::FindInMap function to return a named value based on a specified key. The following example template contains an Amazon EC2 resource whose ImageId property is assigned by the FindInMap function. The FindInMap function specifies key as the region where the stack is created (using the AWS::Region pseudo parameter) and MyAMI1 as the name of the value to map to. For more information about pseudo parameters, see Pseudo parameters reference.

JSON

{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Mappings" : {
    "AMIIDMap" : {
      "us-east-1"        : {"MyAMI1" : "ami-0ff8a91507f77f867", "MyAMI2" : "ami-0a584ac55a7631c0c"},
      "us-west-1"        : {"MyAMI1" : "ami-0bdb828fd58c52235", "MyAMI2" : "ami-066ee5fd4a9ef77f1"},
      "eu-west-1"        : {"MyAMI1" : "ami-047bb4163c506cd98", "MyAMI2" : "ami-0a7c483d527806435"},
      "ap-northeast-1"   : {"MyAMI1" : "ami-06cd52961ce9f0d85", "MyAMI2" : "ami-053cdd503598e4a9d"},
      "ap-southeast-1"   : {"MyAMI1" : "ami-08569b978cc4dfa10", "MyAMI2" : "ami-0be9df32ae9f92309"}
    }
  },
  "Resources" : {
    "myEC2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "ImageId" : { "Fn::FindInMap" : [ "AMIIDMap", { "Ref" : "AWS::Region" }, "MyAMI1" ]},
        "InstanceType" : "t2.micro"
      }
    }
  }
}

YAML

AWSTemplateFormatVersion: "2010-09-09"
Mappings: 
  AMIIDMap: 
    us-east-1:
      MyAMI1: ami-0ff8a91507f77f867
      MyAMI2: ami-0a584ac55a7631c0c
    us-west-1:
      MyAMI1: ami-0bdb828fd58c52235
      MyAMI2: ami-066ee5fd4a9ef77f1
    eu-west-1:
      MyAMI1: ami-047bb4163c506cd98
      MyAMI2: ami-0a7c483d527806435
    ap-northeast-1:
      MyAMI1: ami-06cd52961ce9f0d85
      MyAMI2: ami-053cdd503598e4a9d
    ap-southeast-1:
      MyAMI1: ami-08569b978cc4dfa10
      MyAMI2: ami-0be9df32ae9f92309
Resources: 
  myEC2Instance: 
    Type: "AWS::EC2::Instance"
    Properties: 
      ImageId: !FindInMap [AMIIDMap, !Ref "AWS::Region", MyAMI1]
      InstanceType: t2.micro

Input parameter and Fn::FindInMap

You can use an input parameter with the Fn::FindInMap function to refer to a specific value in a map. For example, suppose you have a list of regions and environment types that map to a specific security group ID. You can select the security group ID that your stack uses by using an input parameter (EnvironmentType). To determine the region, use the AWS::Region pseudo parameter, which gets the in which you create the stack.

JSON

{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Parameters":{
    "EnvironmentType":{
      "Description":"The environment type (Dev or Prod)",
      "Type":"String",
      "Default":"Dev",
      "AllowedValues":[
        "Dev",
        "Prod"
      ]
    }
  },
  "Mappings":{
    "SecurityGroupMap":{
      "us-east-1": {
        "Dev": "sg-12345678",
        "Prod": "sg-abcdef01"
      },
      "us-west-2" : {
        "Dev" : "sg-ghijkl23",
        "Prod" : "sg-45678abc"
      }
    }
  },
  "Resources":{
    "Ec2Instance":{
      "Type":"AWS::EC2::Instance",
      "Properties":{
        "ImageId": "ami-0a70b9d193ae8a799",
        "InstanceType": "t2.micro",
        "SecurityGroupIds": [{ "Fn::FindInMap" : [ "SecurityGroupMap", { "Ref" : "AWS::Region" }, { "Ref" : "EnvironmentType" } ]}]
      }
    }
  }
}

YAML

AWSTemplateFormatVersion: "2010-09-09"
Parameters: 
  EnvironmentType: 
    Description: The environment type (Dev or Prod)
    Type: String
    Default: Dev
    AllowedValues: 
      - Dev
      - Prod
Mappings: 
  SecurityGroupMap: 
    us-east-1: 
      Dev: "sg-12345678"
      Prod: "sg-abcdef01"
    us-west-2: 
      Dev: "sg-ghijkl23"
      Prod: "sg-45678abc"
Resources:
  Ec2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      ImageId: ami-0a70b9d193ae8a799
      InstanceType: t2.micro
      SecurityGroupIds:
        - !FindInMap [SecurityGroupMap, !Ref "AWS::Region", !Ref EnvironmentType]

These related topics can be helpful as you develop templates that use the Fn::FindInMap function.