Condition functions - AWS CloudFormation

Condition functions

You can use intrinsic functions, such as Fn::If, Fn::Equals, and Fn::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 for Fn::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 either prod 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 Conditions.

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.

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 the NewVolume 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 to 10.

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 the Conditions 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 returns false 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 or false 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 value of any type 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

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

value_if_false

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

Examples

To view additional samples, see Sample templates.

Example 1

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

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 the CreateNewSecurityGroup 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 an Fn::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 the DBSnapshotIdentifier 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 the RollingUpdates 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 returns false 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 or false.

Example

The following EnvCondition condition evaluates to true if the value for the EnvironmentType 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 as Fn::Equals and Fn::Or:

  • Fn::FindInMap

  • Ref

  • Other condition functions