Skip to main content
In this lesson we’ll cover CloudFormation mappings: a simple, static lookup mechanism for configuration values that never change at stack runtime. Mappings are ideal for things like region-specific AMI IDs, environment labels, or account-specific constants that you want to keep in a single, predictable place.
Mappings are static. You cannot use intrinsic functions or parameter references inside the Mappings section; all mapping values must be literal constants.

​
Anatomy of a mapping

A CloudFormation mapping is a nested lookup table with three conceptual parts:
  • Mapping name — the top-level identifier (for example, DevMap).
  • Top-level key — the first-level entries inside the mapping (for example, Arno or Alice).
  • Second-level key — the nested label inside each top-level key (for example, Env).
  • Value — the literal constant associated with the second-level key (for example, Development).
Example YAML mapping: 
Mappings:
  DevMap:                # Mapping name
    Arno:                # Top-level key
      Env: Development   # Second-level key -> value
    Alice:
      Env: Production
Table: mapping anatomy at a glance
PartExampleDescription
Mapping nameDevMapTop-level label for the whole mapping
Top-level keyArno, AliceFirst-level lookup keys inside the mapping
Second-level keyEnvNested lookup label used in FindInMap calls
ValueDevelopment, ProductionLiteral constants returned by the lookup

​
Using a mapping (FindInMap)

To read values from a mapping, use the intrinsic function FindInMap (short form: !FindInMap or long form: Fn::FindInMap). The lookup requires three arguments:
  1. Mapping name
  2. Top-level key
  3. Second-level key
Important: The entries within the Mappings section must be literal values, but the three arguments passed to !FindInMap can be literal strings, references to Parameters, or pseudo-parameters (for example, AWS::Region). Short form example — referencing the mapping to set a Tag value: 
Resources:
  MyInstance:
    Type: AWS::EC2::Instance
    Properties:
      ImageId: ami-0abcdef1234567890
      Tags:
        - Key: Environment
          Value: !FindInMap [ DevMap, Arno, Env ]
Long form equivalent: 
Resources:
  MyInstance:
    Type: AWS::EC2::Instance
    Properties:
      Tags:
        - Key: Environment
          Value:
            Fn::FindInMap:
              - DevMap
              - Arno
              - Env
You can combine parameters or pseudo-parameters in the lookup keys. For example, using a parameter to pick the top-level key: 
Parameters:
  Tenant:
    Type: String
    Default: Arno

Resources:
  MyInstance:
    Type: AWS::EC2::Instance
    Properties:
      Tags:
        - Key: Environment
          Value: !FindInMap [ DevMap, !Ref Tenant, Env ]

​
When to use mappings

Mappings are best for static, template-time lookups with predictable, constant values. Use them when you need to:
Use caseWhy use a mapping
Region -> AMI IDDifferent AMIs per region, fixed per template
Account -> settingsAccount-specific values that don’t change at runtime
Environment labelsMap tenant or hostnames to environment names
Static configurationAny constant lookup not depending on runtime logic
Mappings are defined in the template and must contain literal values. Do not include intrinsic functions or parameter references inside the Mappings section — those values must be constants.

​
Best practices

  • Keep mapping entries small and focused (e.g., separate mappings for AMIs and environment labels).
  • Use clear, consistent top-level key names (for example, account IDs, tenant names, or region codes).
  • Prefer parameters or pseudo-parameters as arguments to !FindInMap when the actual lookup key needs to vary at template runtime.
  • Store large or frequently changing data (like many AMI IDs) outside the template (for example, in SSM Parameter Store or a configuration management system) if they change often.

​
Summary

  • Mappings are static, table-like sections in a CloudFormation template defined under the top-level Mappings key.
  • Use !FindInMap (short) or Fn::FindInMap (long) to look up values by mapping name, top-level key, and second-level key.
  • Mapping values must be literal constants—no intrinsic functions or parameter references inside the Mappings block.
  • Use mappings for predictable, template-time configuration such as region -> AMI mappings or account-specific settings.

Watch Video