AWS CloudFormation
User Guide (API Version 2010-05-15)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

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 cannot base a mapping on a parameter, pseudo parameter, or intrinsic function.

Syntax

The Mappings section consists of the key name Mappings, followed by a single colon. Braces enclose all mapping declarations. If you declare multiple mappings, they are delimited by commas. The keys and values in mappings must be literal strings. For each mapping, you must declare a logical name in quotation marks followed by a colon and braces that enclose the sets of values to map. The following example shows a Mappings section containing a single mapping named Mapping01.

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

Within a mapping, each map is a key followed by a colon and a set of name-value pairs that are enclosed by braces. The key identifies each map, and it must be unique within the mapping. Within the braces, you can declare multiple name-value pairs.

Examples

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 the AMI ID for the 32-bit AMI in the region represented by the key.

"Mappings" : {
  "RegionMap" : {
    "us-east-1"      : { "32" : "ami-6411e20d"},
    "us-west-1"      : { "32" : "ami-c9c7978c"},
    "eu-west-1"      : { "32" : "ami-37c2f643"},
    "ap-southeast-1" : { "32" : "ami-66f28c34"},
    "ap-northeast-1" : { "32" : "ami-9c03a89d"}
  }
}

The name-value pairs have a name (32 in the example) and a value. By naming the values, you can map more than one set of values to a key. The following example has region keys that are mapped to two sets of values: one named 32 and the other 64.

"RegionMap" : {
  "us-east-1"      : { "32" : "ami-6411e20d", "64" : "ami-7a11e213" },
  "us-west-1"      : { "32" : "ami-c9c7978c", "64" : "ami-cfc7978a" },
  "eu-west-1"      : { "32" : "ami-37c2f643", "64" : "ami-31c2f645" },
  "ap-southeast-1" : { "32" : "ami-66f28c34", "64" : "ami-60f28c32" },
  "ap-northeast-1" : { "32" : "ami-9c03a89d", "64" : "ami-a003a8a1" }
}

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 32 as the name of the value to map to.

{
  "AWSTemplateFormatVersion" : "2010-09-09",

  "Mappings" : {
    "RegionMap" : {
      "us-east-1" : { "32" : "ami-6411e20d", "64" : "ami-7a11e213" },
      "us-west-1" : { "32" : "ami-c9c7978c", "64" : "ami-cfc7978a" },
      "eu-west-1" : { "32" : "ami-37c2f643", "64" : "ami-31c2f645" },
      "ap-southeast-1" : { "32" : "ami-66f28c34", "64" : "ami-60f28c32" },
      "ap-northeast-1" : { "32" : "ami-9c03a89d", "64" : "ami-a003a8a1" }
    }
  },

  "Resources" : {
    "myEC2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "ImageId" : { "Fn::FindInMap" : [ "RegionMap", { "Ref" : "AWS::Region" }, "32"]},
        "InstanceType" : "m1.small"
      }
    }
  }
}

The following example shows a Mappings section with a mapping that contains three keys that map to arrays that contain multiple string values. The keys represent three regions, and the mapped values are the list of Availability Zones used in each region. The AWS::ElasticLoadBalancing::LoadBalancer resource uses the FindInMap function and the Region2AZ map to specify the AvailabilityZones property.

{
  "AWSTemplateFormatVersion" : "2010-09-09",

  "Mappings" : {
    "Region2AZ" : {
      "us-west-1" : { "AZ" : ["us-west-1a", "us-west-1b"] },
      "us-east-1" : { "AZ" : ["us-east-1a", "us-east-1b", "us-east-1c"] },
      "eu-west-1" : { "AZ" : ["eu-west-1a", "eu-west-1b"] }
    }
  },

  "Resources" : {
    "MyELB" : {
      "Type" : "AWS::ElasticLoadBalancing::LoadBalancer",
      "Properties" : {
        "AvailabilityZones" : { "Fn::FindInMap" : [ "Region2AZ", { "Ref" : "AWS::Region" }, "AZ" ] },
        "Listeners" : [ {
          "LoadBalancerPort" : "8888" ,
          "InstancePort" : "8888" ,
          "Protocol" : "HTTP"
        } ],
        "HealthCheck" : {
          "Target" : { "Fn::Join" : [ "", ["HTTP:", "8888", "/"]]},
          "HealthyThreshold" : "5",
          "UnhealthyThreshold" : "2",
          "Interval" : "10",
          "Timeout" : "8"
        }
      }
    }
  }
}