View a markdown version of this page

Fn::FindInMap - AWS CloudFormation
DeclarationParametersReturn valueExamplesSupported functionsRelated resources

This is the new CloudFormation Template Reference Guide. Please update your bookmarks and links. For help getting started with CloudFormation, see the AWS CloudFormation User Guide.

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"] }

If you want to specify a fallback value for when a key isn't found in the mapping, include a DefaultValue:

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

YAML

Syntax for the full function name:

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

Syntax for the short form:

!FindInMap [ MapName, TopLevelKey, SecondLevelKey ]

If you want to specify a fallback value for when a key isn't found in the mapping, include a DefaultValue:

Syntax for the full function name:

Fn::FindInMap:
  - MapName
  - TopLevelKey
  - SecondLevelKey
  - DefaultValue: DefaultValue

Syntax for the short form:

!FindInMap
  - MapName
  - TopLevelKey
  - SecondLevelKey
  - DefaultValue: DefaultValue
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.

DefaultValue

The value that Fn::FindInMap returns if either the TopLevelKey or SecondLevelKey is not found in the specified mapping. This parameter is optional. If omitted, Fn::FindInMap raises an error when a key is not found.

The fourth parameter must be a map with the key DefaultValue. For example: {"DefaultValue": "us-east-1"}.

Return value

The value that's assigned to SecondLevelKey. If the TopLevelKey or SecondLevelKey is not found and a DefaultValue is specified, the DefaultValue is returned instead.

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 in a template that includes two mappings: AWSInstanceType2Arch and AWSRegionArch2AMI. It also includes an InstanceType parameter that allows you to choose between t3.micro and t4g.nano. The default is t3.micro, but this can be overridden during stack creation.

Fn::FindInMap first determines the architecture (HVM64 or ARM64) based on the selected instance type, and then looks up the correct AMI ID for that architecture in the current AWS Region.

Note

The AMI IDs shown in these examples are placeholders for demonstration purposes. Whenever possible, consider using dynamic references to AWS Systems Manager parameters as an alternative to the Mappings section. To avoid updating all your templates with a new ID each time the AMI that you want to use changes, use a AWS Systems Manager parameter to retrieve the latest AMI ID when the stack is created or updated. The latest versions of commonly used AMIs are also available as public parameters in Systems Manager. For more information, see Get values stored in other services using dynamic references.

JSON

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Parameters": {
    "InstanceType": {
      "Description": "The EC2 instance type",
      "Type": "String",
      "AllowedValues": [
        "t3.micro",
        "t4g.nano"
      ],
      "Default": "t3.micro"
    }
  },
  "Mappings": {
    "AWSInstanceType2Arch": {
      "t3.micro": {
        "Arch": "HVM64"
      },
      "t4g.nano": {
        "Arch": "ARM64"
      }
    },
    "AWSRegionArch2AMI": {
      "us-east-1" : { 
        "HVM64" : "ami-12345678901234567", "ARM64" : "ami-23456789012345678" 
      },
      "us-west-1" : { 
        "HVM64" : "ami-34567890123456789", "ARM64" : "ami-45678901234567890"
      },
      "eu-west-1" : { 
        "HVM64" : "ami-56789012345678901", "ARM64" : "ami-67890123456789012" 
      },
      "ap-southeast-1" : { 
        "HVM64" : "ami-78901234567890123", "ARM64" : "ami-89012345678901234" 
      },
      "ap-northeast-1" : { 
        "HVM64" : "ami-90123456789012345", "ARM64" : "ami-01234567890123456" 
      }
    }
  },
  "Resources" : {
    "MyEC2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "InstanceType" : { "Ref": "InstanceType" },
        "ImageId" : {
          "Fn::FindInMap" : [ "AWSRegionArch2AMI", { "Ref": "AWS::Region" }, { "Fn::FindInMap": [ "AWSInstanceType2Arch", { "Ref": "InstanceType" }, "Arch" ]}]
        }
      }
    }
  }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
Parameters:
  InstanceType:
    Description: The EC2 instance type
    Type: String
    AllowedValues:
      - t3.micro
      - t4g.nano
    Default: t3.micro
Mappings: 
  AWSInstanceType2Arch:
    t3.micro:
      Arch: HVM64
    t4g.nano:
      Arch: ARM64
  AWSRegionArch2AMI:
    us-east-1: 
      HVM64: ami-12345678901234567
      ARM64: ami-23456789012345678
    us-west-1: 
      HVM64: ami-34567890123456789
      ARM64: ami-45678901234567890
    eu-west-1: 
      HVM64: ami-56789012345678901
      ARM64: ami-67890123456789012
    ap-southeast-1: 
      HVM64: ami-78901234567890123
      ARM64: ami-89012345678901234
    ap-northeast-1: 
      HVM64: ami-90123456789012345
      ARM64: ami-01234567890123456
Resources: 
  myEC2Instance: 
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: !Ref InstanceType
      ImageId:
        Fn::FindInMap:
        - AWSRegionArch2AMI
        - Ref: AWS::Region
        - Fn::FindInMap:
          - AWSInstanceType2Arch
          - Ref: InstanceType
          - Arch

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-abcdef01 and sg-ghijkl23.

JSON

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "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": "{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}",
        "InstanceType": "t2.micro",
        "SecurityGroupIds":{
          "Fn::Split":[
            ",",
            {
              "Fn::FindInMap":[
                "SecurityGroups",
                {
                  "Ref":"EnvironmentType"
                },
                "SecurityGroupIds"
              ]
            }
          ]
        }
      }
    }
  }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
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: '{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}'
      InstanceType: t2.micro
      SecurityGroupIds:
        Fn::Split:
          - ","
          - Fn::FindInMap: [ SecurityGroups, !Ref EnvironmentType, SecurityGroupIds ]

Use Fn::FindInMap with a default value

The following example uses a DefaultValue to provide a fallback when a key is not found in the mapping. If the current AWS Region is not defined in the RegionMap mapping, Fn::FindInMap returns t3.micro instead of raising an error.

JSON

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Mappings": {
    "RegionMap": {
      "us-east-1": {
        "InstanceType": "t3.large"
      },
      "eu-west-1": {
        "InstanceType": "t3.medium"
      }
    }
  },
  "Resources": {
    "MyInstance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "ImageId": "{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}",
        "InstanceType": {
          "Fn::FindInMap": [
            "RegionMap",
            { "Ref": "AWS::Region" },
            "InstanceType",
            { "DefaultValue": "t3.micro" }
          ]
        }
      }
    }
  }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
Mappings:
  RegionMap:
    us-east-1:
      InstanceType: t3.large
    eu-west-1:
      InstanceType: t3.medium
Resources:
  MyInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: '{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}'
      InstanceType: !FindInMap
        - RegionMap
        - !Ref AWS::Region
        - InstanceType
        - DefaultValue: t3.micro

Supported functions

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

  • Fn::FindInMap

  • Ref

Related resources

To use intrinsic functions beyond Fn::FindInMap and Ref in the parameters of 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.