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...

Use Parameters and Mappings to Specify Values in Your Template

You can use an input parameter to refer to a specific value in a map by using the Fn::FindInMap function. For example, suppose you have a list of regions that map to a specific AMI. You can select the AMI that your stack uses by specifying a region parameter when you create the stack.

  1. Add one parameter to your Parameters section for every mapping you want to include. The parameter is how you pass in the desired mapping key.

  2. Create the mappings that contain the key options and key values.

  3. Use the Fn::FindInMap function as the value for the resource property or output you want to assign conditionally.

    Note

    You can set a default value for both parameters and mappings. You should set a default for at least one of these. If Fn::FindInMap cannot resolve a key and value at runtime, an error will prevent the stack from being created.

Consider this example. Suppose you want the aws cloudformation describe-stacks command to print the AMI name of the AMI you want to run based on a particular region. You could do this with the following:

{
  "AWSTemplateFormatVersion" : "2010-09-09",
  
  "Description" : "TemplateName - ShortMapExample.template",  
  
  "Parameters" : {
    "Region" : {
      "Default" : "us-east-1",
      "Description" : " 'us-east-1' | 'us-west-1' | 'eu-west-1' | 'ap-southeast-1' "
    }
  },
	
  "Mappings" : {
    "RegionMap" : {
      "us-east-1" : {
          "AMI" : "ami-76f0061f"
      },
      "us-west-1" : {
          "AMI" : "ami-655a0a20"
      },
      "eu-west-1" : {
          "AMI" : "ami-7fd4e10b"
      },
      "ap-southeast-1" : {
          "AMI" : "ami-72621c20"
      }
    }
  },

  "Resources" : {
  
   ...other resources...

    },
    
  "Outputs" : {
    "OutVal" : {
      "Description" : "Return the name of the AMI matching the RegionMap key",
      "Value" : { "Fn::FindInMap" : [ "RegionMap", { "Ref" : "Region" }, "AMI" ]}
    }
  }
  
}

The parameter Region accepts a string value, ideally one of the region identifiers in the template. The Mappings section declares the RegionMap mapping. Each mapping key assigns a value to the AMI attribute. The Outputs section declares the OutVal output, which gets its value based on the value returned from Fn:FindInMap.

The following shows the value assigned to OutVal based on the listed command:

Command LinesValue Assigned to OutVal
aws cloudformation create-stack --stack-name MyTestStack --template-body file:///home/local/test/ShortRegionExample.json
 --parameters ParameterKey=Region,ParameterValue=us-west-1
...
aws cloudformation describe-stacks --stack-name MyTestStack

ami-655a0a20

aws cloudformation create-stack --stack-name MyTestStack --template-body file:///home/local/test/ShortRegionExample.json
 --parameters ParameterKey=Region,ParameterValue=eu-west-1
...
aws cloudformation describe-stacks --stack-name MyTestStack

ami-7fd4e10b

aws cloudformation create-stack --stack-name MyTestStack --template-body file:///home/local/test/ShortRegionExample.json
...
aws cloudformation describe-stacks MyTestStack

ami-76f0061f

In the first two cases, the value specified as part of the --parameters option determines the value of OutVal. In the third example, a mapping key is not specified, so the default region, us-east-1, will be used.