AWS AWSCloudFormation documentation change
Summary
Restructured conditions documentation with updated explanations of intrinsic functions, added sample templates section, and removed detailed implementation examples in favor of more concise guidance
Security assessment
Added documentation about using NoEcho parameter to mask sensitive values in parameters, which is a security best practice. However, there's no evidence of addressing a specific security vulnerability.
Diff
diff --git a/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-conditions.md b/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-conditions.md index cf08bca0f..0d2b857f5 100644 --- a//AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-conditions.md +++ b//AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-conditions.md @@ -3 +3 @@ -Associating a conditionFn::AndFn::EqualsFn::IfFn::NotFn::OrSupported functions +Fn::AndFn::EqualsFn::IfFn::NotFn::OrSupported functionsSample templates @@ -9 +9 @@ This is the new _AWS CloudFormation Template Reference Guide_. Please update you -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 can use intrinsic functions, such as `Fn::If` or `Fn::Equals`, to create and configure stack resources based on conditional logic. These conditions evaluate during stack creation or updates. After you define all your conditions, you can associate them with resources or resource properties in the `Resources` and `Outputs` sections of a template. @@ -11 +11 @@ You can use intrinsic functions, such as `Fn::If`, `Fn::Equals`, and `Fn::Not`, -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. +For advanced scenarios, you can combine conditions using `Fn::And` or `Fn::Or` functions, or use `Fn::Not` to negate a condition's value. You can also nest conditions to create more complex conditional logic. @@ -13,3 +13 @@ You define all conditions in the `Conditions` section of a template except for ` -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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html) in the _AWS CloudFormation User Guide_. +If you're new to using conditions in your templates, we recommend you first review the [CloudFormation template Conditions syntax](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html) topic in the _AWS CloudFormation User Guide_. @@ -19 +17 @@ For more information about the `Conditions` section, see [Conditions](https://do -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. +You must 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, `UpdatePolicy` attribute, and property values within the `Resources` and `Outputs` sections. @@ -23,2 +20,0 @@ You can only reference other conditions and values from the `Parameters` and `Ma - * Associating a condition - @@ -37,91 +33 @@ You can only reference other conditions and values from the `Parameters` and `Ma - * [Sample templates](./conditions-sample-templates.html) - - * [Condition](./intrinsic-function-reference-condition.html) - - - - -## 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. 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"} - ] - } + * Sample templates @@ -129 +34,0 @@ You can also use conditions inside other conditions. The following snippet is fr -##### YAML @@ -132,3 +36,0 @@ You can also use conditions inside other conditions. The following snippet is fr - MyAndCondition: !And - - !Equals ["sg-mysggroup", !Ref "ASecurityGroup"] - - !Condition SomeOtherCondition @@ -161 +63 @@ Syntax for the short form: -`condition` +condition @@ -166 +68 @@ A condition that evaluates to `true` or `false`. -### Examples +### `Fn::And` usage examples @@ -212 +114 @@ Syntax for the short form: -`value` +value @@ -217 +119 @@ A string value that you want to compare. -### Examples +### `Fn::Equals` usage examples @@ -219 +121 @@ A string value that you want to compare. -The following `UseProdCondition` condition evaluates to true if the value for the `EnvironmentType` parameter is equal to `prod`: +The following `IsProduction` condition evaluates to true if the value for the `EnvironmentType` parameter is equal to `prod`: @@ -224 +126 @@ The following `UseProdCondition` condition evaluates to true if the value for th - "UseProdCondition" : { + "IsProduction" : { @@ -234 +136 @@ The following `UseProdCondition` condition evaluates to true if the value for th - UseProdCondition: + IsProduction: @@ -262 +164 @@ Syntax for the short form: -`condition_name` +condition_name @@ -267 +169 @@ A reference to a condition in the Conditions section. Use the condition's name t -`value_if_true` +value_if_true @@ -270 +172 @@ A reference to a condition in the Conditions section. Use the condition's name t -A value to be returned if the specified condition evaluates to `true`. +A value to be returned if the specified condition evaluates to true. @@ -272 +174 @@ A value to be returned if the specified condition evaluates to `true`. -`value_if_false` +value_if_false @@ -277 +179,5 @@ A value to be returned if the specified condition evaluates to `false`. -### Examples +### `Fn::If` usage examples + +###### Topics + + * Conditionally choosing a resource @@ -279 +185 @@ A value to be returned if the specified condition evaluates to `false`. -To view additional samples, see [Sample templates](./conditions-sample-templates.html). + * Conditional outputs @@ -281 +187 @@ To view additional samples, see [Sample templates](./conditions-sample-templates -#### Example 1 + * Conditional array values @@ -283 +189,10 @@ To view additional samples, see [Sample templates](./conditions-sample-templates -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`. + * Conditional properties and property values + + * Conditional update policies + + + + +#### Conditionally choosing a resource + +The following example uses an `Fn::If` function in an Amazon EC2 resource definition to determine which security group resource to associate with the instance. If the `CreateNewSecurityGroup` condition evaluates to true, CloudFormation uses the referenced value of `NewSecurityGroup` (a security group created elsewhere in the template) to specify the `SecurityGroupIds` property. If `CreateNewSecurityGroup` is false, CloudFormation uses the referenced value of `ExistingSecurityGroupId` (a parameter that references an existing security group). @@ -288 +203,7 @@ The following snippet uses an `Fn::If` function in the `SecurityGroups` property - "SecurityGroups" : [{ + "Resources": { + "EC2Instance": { + "Type": "AWS::EC2::Instance", + "Properties": { + "ImageId": "ami-0abcdef1234567890", + "InstanceType": "t3.micro", + "SecurityGroupIds": { @@ -291,2 +212,2 @@ The following snippet uses an `Fn::If` function in the `SecurityGroups` property - {"Ref" : "NewSecurityGroup"}, - {"Ref" : "ExistingSecurityGroup"} + [{"Ref": "NewSecurityGroup"}], + [{"Ref": "ExistingSecurityGroupId"}] @@ -294,0 +216,3 @@ The following snippet uses an `Fn::If` function in the `SecurityGroups` property + } + } + } @@ -299,2 +223,10 @@ The following snippet uses an `Fn::If` function in the `SecurityGroups` property