Condition functions - AWS CloudFormation (original) (raw)

You can use intrinsic functions, such as Fn::If, Fn::Equals, andFn::Not, to conditionally create stack resources. These conditions are evaluated based on input parameters that you declare when you create or update a stack. After you define all your conditions, you can associate them with resources or resource properties in the Resources and Outputs sections of a template.

You define all conditions in the Conditions section of a template except forFn::If conditions. You can use the Fn::If condition in the metadata attribute, update policy attribute, and property values in the Resources section and Outputs sections of a template.

You might use conditions when you want to reuse a template that can create resources in different contexts, such as a test environment versus a production environment. In your template, you can add an EnvironmentType input parameter, which accepts eitherprod or test as inputs. For the production environment, you might include Amazon EC2 instances with certain capabilities; however, for the test environment, you want to use less capabilities to save costs. With conditions, you can define which resources are created and how they're configured for each environment type.

For more information about the Conditions section, see CloudFormation template Conditions syntax.

Note

You can only reference other conditions and values from the Parameters and Mappings sections of a template. For example, you can reference a value from an input parameter, but you can't reference the logical ID of a resource in a condition.

Topics

• Associating a condition
• Fn::And
• Fn::Equals
• Fn::If
• Fn::Not
• Fn::Or
• Supported functions
• Sample templates
• Condition

Associating a condition

To conditionally create resources, resource properties, or outputs, you must associate a condition with them. Add the Condition: key and the logical ID of the condition as an attribute to associate a condition, as shown in the following snippet. AWS CloudFormation creates theNewVolume resource only when the CreateProdResources condition evaluates to true.

JSON

"NewVolume" : {
  "Type" : "AWS::EC2::Volume",
  "Condition" : "CreateProdResources",
  "Properties" : {
     "Size" : "100",
     "AvailabilityZone" : { "Fn::GetAtt" : [ "EC2Instance", "AvailabilityZone" ]}
}

YAML

NewVolume:
  Type: "AWS::EC2::Volume"
  Condition: CreateProdResources
  Properties: 
    Size: 100
    AvailabilityZone: !GetAtt EC2Instance.AvailabilityZone

Fn::If

For the Fn::If function, you only need to specify the condition name. The following snippet shows how to use Fn::If to conditionally specify a resource property. If the CreateLargeSize condition is true, CloudFormation sets the volume size to 100. If the condition is false, CloudFormation sets the volume size to10.

JSON

{
    "NewVolume": {
        "Type": "AWS::EC2::Volume",
        "Properties": {
            "Size": {
                "Fn::If": [
                    "CreateLargeSize",
                    "100",
                    "10"
                ]
            },
            "AvailabilityZone": {
                "Fn::GetAtt": [
                    "Ec2Instance",
                    "AvailabilityZone"
                ]
            }
        },
        "DeletionPolicy": "Snapshot"
    }
}

YAML

NewVolume:
  Type: 'AWS::EC2::Volume'
  Properties:
    Size:
      'Fn::If':
        - CreateLargeSize
        - '100'
        - '10'
    AvailabilityZone:
      'Fn::GetAtt':
        - Ec2Instance
        - AvailabilityZone
  DeletionPolicy: Snapshot

Nested conditions

You can also use conditions inside other conditions. The following snippet is from theConditions section of a template. The MyAndCondition condition includes the SomeOtherCondition condition:

JSON

"MyAndCondition": {
   "Fn::And": [
      {"Fn::Equals": ["sg-mysggroup", {"Ref": "ASecurityGroup"}]},
      {"Condition": "SomeOtherCondition"}
   ]
}

YAML

MyAndCondition: !And
  - !Equals ["sg-mysggroup", !Ref "ASecurityGroup"]
  - !Condition SomeOtherCondition

Fn::And

Returns true if all the specified conditions evaluate to true, or returnsfalse if any one of the conditions evaluates to false. Fn::And acts as an AND operator. The minimum number of conditions that you can include is 2, and the maximum is 10.

Declaration

JSON

"Fn::And": [{condition}, {...}]

YAML

Syntax for the full function name:

Fn::And: [condition]

Syntax for the short form:

!And [condition]

Parameters

condition

A condition that evaluates to true or false.

Example

The following MyAndCondition evaluates to true if the referenced security group name is equal to sg-mysggroup and if SomeOtherCondition evaluates to true:

JSON

"MyAndCondition": {
   "Fn::And": [
      {"Fn::Equals": ["sg-mysggroup", {"Ref": "ASecurityGroup"}]},
      {"Condition": "SomeOtherCondition"}
   ]
}

YAML

MyAndCondition: !And
  - !Equals ["sg-mysggroup", !Ref ASecurityGroup]
  - !Condition SomeOtherCondition

Fn::Equals

Compares if two values are equal. Returns true if the two values are equal orfalse if they aren't.

Declaration

JSON

"Fn::Equals" : ["value_1", "value_2"]

YAML

Syntax for the full function name:

Fn::Equals: [value_1, value_2]

Syntax for the short form:

!Equals [value_1, value_2]

Parameters

value

A string value that you want to compare.

Example

The following UseProdCondition condition evaluates to true if the value for the EnvironmentType parameter is equal to prod:

JSON

"UseProdCondition" : {
   "Fn::Equals": [
      {"Ref": "EnvironmentType"},
      "prod"
   ]
}

YAML

UseProdCondition:
  !Equals [!Ref EnvironmentType, prod]

Fn::If

Returns one value if the specified condition evaluates to true and another value if the specified condition evaluates to false. Currently, CloudFormation supports the Fn::If intrinsic function in the metadata attribute, update policy attribute, and property values in the Resources section and Outputs sections of a template. You can use the AWS::NoValue pseudo parameter as a return value to remove the corresponding property.

Declaration

JSON

"Fn::If": [condition_name, value_if_true, value_if_false]

YAML

Syntax for the full function name:

Fn::If: [condition_name, value_if_true, value_if_false]

Syntax for the short form:

!If [condition_name, value_if_true, value_if_false]

Parameters

condition_name

A reference to a condition in the Conditions section. Use the condition's name to reference it.

value_if_true

A value to be returned if the specified condition evaluates totrue.

value_if_false

A value to be returned if the specified condition evaluates tofalse.

Examples

To view additional samples, see Sample templates.

Example 1

The following snippet uses an Fn::If function in theSecurityGroups property for an Amazon EC2 resource. If theCreateNewSecurityGroup condition evaluates to true, CloudFormation uses the referenced value of NewSecurityGroup to specify theSecurityGroups property; otherwise, CloudFormation uses the referenced value ofExistingSecurityGroup.

JSON

"SecurityGroups" : [{
  "Fn::If" : [
    "CreateNewSecurityGroup",
    {"Ref" : "NewSecurityGroup"},
    {"Ref" : "ExistingSecurityGroup"}
  ]
}]

YAML

SecurityGroups:
  - !If [CreateNewSecurityGroup, !Ref NewSecurityGroup, !Ref ExistingSecurityGroup]

Example 2

In the Output section of a template, you can use the Fn::If function to conditionally output information. In the following snippet, if theCreateNewSecurityGroup condition evaluates to true, CloudFormation outputs the security group ID of the NewSecurityGroup resource. If the condition is false, CloudFormation outputs the security group ID of the ExistingSecurityGroup resource.

JSON

"Outputs" : {
  "SecurityGroupId" : {
    "Description" : "Group ID of the security group used.",
    "Value" : {
      "Fn::If" : [
        "CreateNewSecurityGroup",
        {"Ref" : "NewSecurityGroup"},
        {"Ref" : "ExistingSecurityGroup"}
      ]
    }
  }
}

YAML

Outputs:
  SecurityGroupId: 
    Description: Group ID of the security group used.
    Value: !If [CreateNewSecurityGroup, !Ref NewSecurityGroup, !Ref ExistingSecurityGroup]

Example 3

The following snippet uses the AWS::NoValue pseudo parameter in anFn::If function. The condition uses a snapshot for an Amazon RDS DB instance only if a snapshot ID is provided. If the UseDBSnapshot condition evaluates to true, CloudFormation uses the DBSnapshotName parameter value for theDBSnapshotIdentifier property. If the condition evaluates to false, CloudFormation removes the DBSnapshotIdentifier property.

JSON

"MyDB" : {
  "Type" : "AWS::RDS::DBInstance",
  "Properties" : {
    "AllocatedStorage" : "5",
    "DBInstanceClass" : "db.t2.small",
    "Engine" : "MySQL",
    "EngineVersion" : "5.5",
    "MasterUsername" : { "Ref" : "DBUser" },
    "MasterUserPassword" : { "Ref" : "DBPassword" },
    "DBParameterGroupName" : { "Ref" : "MyRDSParamGroup" },
    "DBSnapshotIdentifier" : {
      "Fn::If" : [
        "UseDBSnapshot",
        {"Ref" : "DBSnapshotName"},
        {"Ref" : "AWS::NoValue"}
      ]
    }
  }
}

YAML

MyDB:
  Type: "AWS::RDS::DBInstance"
  Properties: 
    AllocatedStorage: 5
    DBInstanceClass: db.t2.small
    Engine: MySQL
    EngineVersion: 5.5
    MasterUsername: !Ref DBUser
    MasterUserPassword: !Ref DBPassword
    DBParameterGroupName: !Ref MyRDSParamGroup
    DBSnapshotIdentifier:
      !If [UseDBSnapshot, !Ref DBSnapshotName, !Ref "AWS::NoValue"]

Example 4

The following snippet provides an Auto Scaling update policy only if theRollingUpdates condition evaluates to true. If the condition evaluates to false, CloudFormation removes the AutoScalingRollingUpdate update policy.

JSON

"UpdatePolicy": {
  "AutoScalingRollingUpdate": {
    "Fn::If": [
      "RollingUpdates",
      {
        "MaxBatchSize": "2",
        "MinInstancesInService": "2",
        "PauseTime": "PT0M30S"
      },
      {
        "Ref" : "AWS::NoValue"
      }
    ]
  }
}

YAML

UpdatePolicy:
  AutoScalingRollingUpdate:
    !If 
      - RollingUpdates
      -
        MaxBatchSize: 2
        MinInstancesInService: 2
        PauseTime: PT0M30S
      - !Ref "AWS::NoValue"

Fn::Not

Returns true for a condition that evaluates to false or returnsfalse for a condition that evaluates to true. Fn::Not acts as a NOT operator.

Declaration

JSON

"Fn::Not": [{condition}]

YAML

Syntax for the full function name:

Fn::Not: [condition]

Syntax for the short form:

!Not [condition]

Parameters

condition

A condition such as Fn::Equals that evaluates to true orfalse.

Example

The following EnvCondition condition evaluates to true if the value for theEnvironmentType parameter isn't equal to prod:

JSON

"MyNotCondition" : {
   "Fn::Not" : [{
      "Fn::Equals" : [
         {"Ref" : "EnvironmentType"},
         "prod"
      ]
   }]
}

YAML

MyNotCondition:
  !Not [!Equals [!Ref EnvironmentType, prod]]

Fn::Or

Returns true if any one of the specified conditions evaluate to true, or returns false if all the conditions evaluates to false. Fn::Or acts as an OR operator. The minimum number of conditions that you can include is 2, and the maximum is 10.

Declaration

JSON

"Fn::Or": [{condition}, {...}]

YAML

Syntax for the full function name:

Fn::Or: [condition, ...]

Syntax for the short form:

!Or [condition, ...]

Parameters

condition

A condition that evaluates to true or false.

Example

The following MyOrCondition evaluates to true if the referenced security group name is equal to sg-mysggroup or if SomeOtherCondition evaluates to true:

JSON

"MyOrCondition" : {
   "Fn::Or" : [
      {"Fn::Equals" : ["sg-mysggroup", {"Ref" : "ASecurityGroup"}]},
      {"Condition" : "SomeOtherCondition"}
   ]
}

YAML

MyOrCondition:
  !Or [!Equals [sg-mysggroup, !Ref ASecurityGroup], Condition: SomeOtherCondition]

Supported functions

You can use the following functions in the Fn::If condition:

• Fn::Base64
• Fn::FindInMap
• Fn::GetAtt
• Fn::GetAZs
• Fn::If
• Fn::Join
• Fn::Select
• Fn::Sub
• Ref

You can use the following functions in all other condition functions, such asFn::Equals and Fn::Or:

• Fn::FindInMap
• Ref
• Other condition functions