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 AWS Regions.
-
The map has 5 top-level keys that correspond to various AWS 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 AWS 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 Systems Manager 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-abcdef01
and 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.