Fn::FindInMap - Amazon CloudFormation
DeclarationParametersReturn valueExamplesSupported functionsRelated resources
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Fn::FindInMap

The intrinsic function Fn::FindInMap returns the value corresponding to keys in a two-level map that's declared in the Mappings section.

Declaration

JSON

{ "Fn::FindInMap" : [ "MapName", "TopLevelKey", "SecondLevelKey"] }

YAML

Syntax for the full function name:

Fn::FindInMap: [ MapName, TopLevelKey, SecondLevelKey ]

Syntax for the short form:

!FindInMap [ MapName, TopLevelKey, SecondLevelKey ]
Note

You can't nest two instances of two functions in short form.

Parameters

MapName

The logical name of a mapping declared in the Mappings section that contains the keys and values.

TopLevelKey

The top-level key name. Its value is a list of key-value pairs.

SecondLevelKey

The second-level key name, which is set to one of the keys from the list assigned to TopLevelKey.

Return value

The value that's assigned to SecondLevelKey.

Examples

The following examples demonstrate how to use the Fn::FindInMap function.

Use Fn::FindInMap with region-specific values

The following example shows how to use Fn::FindInMap for a template with a Mappings section that contains a single map, RegionMap, that associates AMIs with Amazon Regions.

  • The map has 5 top-level keys that correspond to various Amazon Regions.

  • Each top-level key is assigned a list with two second level keys, "HVM64" and "HVMG2", that correspond to the AMI's architecture.

  • Each of the second-level keys is assigned an appropriate AMI name.

The example template contains an AWS::EC2::Instance resource whose ImageId property is set by the FindInMap function.

MapName is set to the map of interest, "RegionMap" in this example. TopLevelKey is set to the Region where the stack is created, which is determined by using the "AWS::Region" pseudo parameter. SecondLevelKey is set to the desired architecture, "HVM64" for this example.

FindInMap returns the AMI assigned to FindInMap. For a HVM64 instance in us-east-1, FindInMap would return "ami-0ff8a91507f77f867".

Note

Consider Amazon Systems Manager AMI aliases as an alternative to the mapping section. To avoid updating all your templates with a new ID each time the AMI that you want to use changes, use the AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> parameter type to fetch the latest AMI ID when the stack is created or updated. The latest versions of commonly used AMIs are also available as public parameters. For examples of how to reference the AMI alias in your template, see SSM parameter types.

JSON

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

YAML

Mappings: 
  RegionMap: 
    us-east-1: 
      HVM64: "ami-0ff8a91507f77f867"
      HVMG2: "ami-0a584ac55a7631c0c"
    us-west-1: 
      HVM64: "ami-0bdb828fd58c52235"
      HVMG2: "ami-066ee5fd4a9ef77f1"
    eu-west-1: 
      HVM64: "ami-047bb4163c506cd98"
      HVMG2: "ami-0a7c483d527806435"
    ap-southeast-1: 
      HVM64: "ami-08569b978cc4dfa10"
      HVMG2: "ami-0be9df32ae9f92309"
    ap-northeast-1: 
      HVM64: "ami-06cd52961ce9f0d85"
      HVMG2: "ami-053cdd503598e4a9d"
Resources: 
  myEC2Instance: 
    Type: "AWS::EC2::Instance"
    Properties: 
      ImageId: !FindInMap
        - RegionMap
        - !Ref 'AWS::Region'
        - HVM64
      InstanceType: t2.micro

Use Fn::FindInMap for environment-specific configurations

The following example shows how to use Fn::FindInMap for a template with a Mappings section that contains a single map, SecurityGroups. It also contains an EnvironmentType parameter that allows you to specify whether the environment is Dev or Prod. It defaults to Dev but can be overridden during stack creation.

Fn::FindInMap returns the appropriate SecurityGroupIds based on the EnvironmentType parameter. Fn::Split then splits the comma-separated string of security group IDs into a list, which is the expected format for SecurityGroupIds.

If you deploy this stack with EnvironmentType set to Dev, the SecurityGroupIds for EC2Instance will be sg-12345678. If you set EnvironmentType to Prod, it will use sg-abcdef01and sg-ghijkl23.

JSON

{
  ...
  "Parameters":{
    "EnvironmentType":{
      "Description":"The environment type (Dev or Prod)",
      "Type":"String",
      "Default":"Dev",
      "AllowedValues":[
        "Dev",
        "Prod"
      ]
    }
  },
  "Mappings":{
    "SecurityGroups":{
      "Dev":{
        "SecurityGroupIds":"sg-12345678"
      },
      "Prod":{
        "SecurityGroupIds":"sg-abcdef01,sg-ghijkl23"
      }
    }
  },
  "Resources":{
    "Ec2Instance":{
      "Type":"AWS::EC2::Instance",
      "Properties":{
        "ImageId": "ami-0a70b9d193ae8a799",
        "InstanceType": "t2.micro",
        "SecurityGroupIds":{
          "Fn::Split":[
            ",",
            {
              "Fn::FindInMap":[
                "SecurityGroups",
                {
                  "Ref":"EnvironmentType"
                },
                "SecurityGroupIds"
              ]
            }
          ]
        }
      }
    }
  }
}

YAML

Parameters:
  EnvironmentType:
    Description: The environment type (Dev or Prod)
    Type: String
    Default: Dev
    AllowedValues:
      - Dev
      - Prod
Mappings:
  SecurityGroups:
    Dev:
      SecurityGroupIds: sg-12345678
    Prod:
      SecurityGroupIds: sg-abcdef01,sg-ghijkl23
Resources:
  Ec2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      ImageId: ami-0a70b9d193ae8a799
      InstanceType: t2.micro
      SecurityGroupIds:
        Fn::Split:
          - ","
          - Fn::FindInMap: [ SecurityGroups, !Ref EnvironmentType, SecurityGroupIds ]

Supported functions

You can use the following functions in a Fn::FindInMap function:

  • Fn::FindInMap

  • Ref

Related resources

To use other intrinsic functions or a default value in a Fn::FindInMap function, you must declare the AWS::LanguageExtensions transform within your template. For more information, see Fn::FindInMap enhancements.

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