[ aws . cloudformation ]
Returns the inputs for the change set and a list of changes that CloudFormation will make if you execute the change set. For more information, see Updating Stacks Using Change Sets in the CloudFormation User Guide.
See also: AWS API Documentation
describe-change-set
is a paginated operation. Multiple API calls may be issued in order to retrieve the entire data set of results. You can disable pagination by providing the --no-paginate
argument.
When using --output text
and the --query
argument on a paginated response, the --query
argument must extract data from the results of the following query expressions: Changes
describe-change-set
--change-set-name <value>
[--stack-name <value>]
[--cli-input-json | --cli-input-yaml]
[--starting-token <value>]
[--max-items <value>]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
--change-set-name
(string)
The name or Amazon Resource Name (ARN) of the change set that you want to describe.
--stack-name
(string)
If you specified the name of a change set, specify the stack name or ID (ARN) of the change set you want to describe.
--cli-input-json
| --cli-input-yaml
(string)
Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton
. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml
.
--starting-token
(string)
A token to specify where to start paginating. This is the
NextToken
from a previously truncated response.For usage examples, see Pagination in the AWS Command Line Interface User Guide .
--max-items
(integer)
The total number of items to return in the command’s output. If the total number of items available is more than the value specified, a
NextToken
is provided in the command’s output. To resume pagination, provide theNextToken
value in thestarting-token
argument of a subsequent command. Do not use theNextToken
response element directly outside of the AWS CLI.For usage examples, see Pagination in the AWS Command Line Interface User Guide .
--generate-cli-skeleton
(string)
Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input
, prints a sample input JSON that can be used as an argument for --cli-input-json
. Similarly, if provided yaml-input
it will print a sample input YAML that can be used with --cli-input-yaml
. If provided with the value output
, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.
--debug
(boolean)
Turn on debug logging.
--endpoint-url
(string)
Override command’s default URL with the given URL.
--no-verify-ssl
(boolean)
By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.
--no-paginate
(boolean)
Disable automatic pagination.
--output
(string)
The formatting style for command output.
json
text
table
yaml
yaml-stream
--query
(string)
A JMESPath query to use in filtering the response data.
--profile
(string)
Use a specific profile from your credential file.
--region
(string)
The region to use. Overrides config/env settings.
--version
(string)
Display the version of this tool.
--color
(string)
Turn on/off color output.
on
off
auto
--no-sign-request
(boolean)
Do not sign requests. Credentials will not be loaded if this argument is provided.
--ca-bundle
(string)
The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.
--cli-read-timeout
(int)
The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.
--cli-connect-timeout
(int)
The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.
--cli-binary-format
(string)
The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob fileb://
will always be treated as binary and use the file contents directly regardless of the cli-binary-format
setting. When using file://
the file contents will need to properly formatted for the configured cli-binary-format
.
base64
raw-in-base64-out
--no-cli-pager
(boolean)
Disable cli pager for output.
--cli-auto-prompt
(boolean)
Automatically prompt for CLI input parameters.
--no-cli-auto-prompt
(boolean)
Disable automatically prompt for CLI input parameters.
Note
To use the following examples, you must have the AWS CLI installed and configured. See the Getting started guide in the AWS CLI User Guide for more information.
Unless otherwise stated, all examples have unix-like quotation rules. These examples will need to be adapted to your terminal’s quoting rules. See Using quotation marks with strings in the AWS CLI User Guide .
To get information about a change set
The following describe-change-set
example displays the details of the change set specified by change set name and stack name.
aws cloudformation describe-change-set \
--change-set-name my-change-set \
--stack-name my-stack
The following describe-change-set
example displays the details of the change set specified by the full ARN of the change set:
aws cloudformation describe-change-set \
--change-set-name arn:aws:cloudformation:us-west-2:123456789012:changeSet/my-change-set/bc9555ba-a949-xmpl-bfb8-f41d04ec5784
Output:
{
"Changes": [
{
"Type": "Resource",
"ResourceChange": {
"Action": "Modify",
"LogicalResourceId": "function",
"PhysicalResourceId": "my-function-SEZV4XMPL4S5",
"ResourceType": "AWS::Lambda::Function",
"Replacement": "False",
"Scope": [
"Properties"
],
"Details": [
{
"Target": {
"Attribute": "Properties",
"Name": "Timeout",
"RequiresRecreation": "Never"
},
"Evaluation": "Static",
"ChangeSource": "DirectModification"
}
]
}
}
],
"ChangeSetName": "my-change-set",
"ChangeSetId": "arn:aws:cloudformation:us-west-2:123456789012:changeSet/my-change-set/4eca1a01-e285-xmpl-8026-9a1967bfb4b0",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack/d0a825a0-e4cd-xmpl-b9fb-061c69e99204",
"StackName": "my-stack",
"Description": null,
"Parameters": null,
"CreationTime": "2019-10-02T05:20:56.651Z",
"ExecutionStatus": "AVAILABLE",
"Status": "CREATE_COMPLETE",
"StatusReason": null,
"NotificationARNs": [],
"RollbackConfiguration": {},
"Capabilities": [
"CAPABILITY_IAM"
],
"Tags": null
}
ChangeSetName -> (string)
The name of the change set.
ChangeSetId -> (string)
The Amazon Resource Name (ARN) of the change set.
StackId -> (string)
The Amazon Resource Name (ARN) of the stack that’s associated with the change set.
StackName -> (string)
The name of the stack that’s associated with the change set.
Description -> (string)
Information about the change set.
Parameters -> (list)
A list of
Parameter
structures that describes the input parameters and their values used to create the change set. For more information, see the Parameter data type.(structure)
The Parameter data type.
ParameterKey -> (string)
The key associated with the parameter. If you don’t specify a key and value for a particular parameter, CloudFormation uses the default value that’s specified in your template.
ParameterValue -> (string)
The input value associated with the parameter.
UsePreviousValue -> (boolean)
During a stack update, use the existing parameter value that the stack is using for a given parameter key. If you specify
true
, do not specify a parameter value.ResolvedValue -> (string)
Read-only. The value that corresponds to a SSM parameter key. This field is returned only for `
SSM
https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#aws-ssm-parameter-types`__ parameter types in the template.
CreationTime -> (timestamp)
The start time when the change set was created, in UTC.
ExecutionStatus -> (string)
If the change set execution status is
AVAILABLE
, you can execute the change set. If you can’t execute the change set, the status indicates why. For example, a change set might be in anUNAVAILABLE
state because CloudFormation is still creating it or in anOBSOLETE
state because the stack was already updated.
Status -> (string)
The current status of the change set, such as
CREATE_IN_PROGRESS
,CREATE_COMPLETE
, orFAILED
.
StatusReason -> (string)
A description of the change set’s status. For example, if your attempt to create a change set failed, CloudFormation shows the error message.
NotificationARNs -> (list)
The ARNs of the Amazon Simple Notification Service (Amazon SNS) topics that will be associated with the stack if you execute the change set.
(string)
RollbackConfiguration -> (structure)
The rollback triggers for CloudFormation to monitor during stack creation and updating operations, and for the specified monitoring period afterwards.
RollbackTriggers -> (list)
The triggers to monitor during stack creation or update actions.
By default, CloudFormation saves the rollback triggers specified for a stack and applies them to any subsequent update operations for the stack, unless you specify otherwise. If you do specify rollback triggers for this parameter, those triggers replace any list of triggers previously specified for the stack. This means:
To use the rollback triggers previously specified for this stack, if any, don’t specify this parameter.
To specify new or updated rollback triggers, you must specify all the triggers that you want used for this stack, even triggers you’ve specified before (for example, when creating the stack or during a previous stack update). Any triggers that you don’t include in the updated list of triggers are no longer applied to the stack.
To remove all currently specified triggers, specify an empty list for this parameter.
If a specified trigger is missing, the entire stack operation fails and is rolled back.
(structure)
A rollback trigger CloudFormation monitors during creation and updating of stacks. If any of the alarms you specify goes to ALARM state during the stack operation or within the specified monitoring period afterwards, CloudFormation rolls back the entire stack operation.
Arn -> (string)
The Amazon Resource Name (ARN) of the rollback trigger.
If a specified trigger is missing, the entire stack operation fails and is rolled back.
Type -> (string)
The resource type of the rollback trigger. Specify either AWS::CloudWatch::Alarm or AWS::CloudWatch::CompositeAlarm resource types.
MonitoringTimeInMinutes -> (integer)
The amount of time, in minutes, during which CloudFormation should monitor all the rollback triggers after the stack creation or update operation deploys all necessary resources.
The default is 0 minutes.
If you specify a monitoring period but don’t specify any rollback triggers, CloudFormation still waits the specified period of time before cleaning up old resources after update operations. You can use this monitoring period to perform any manual stack validation desired, and manually cancel the stack creation or update (using CancelUpdateStack , for example) as necessary.
If you specify 0 for this parameter, CloudFormation still monitors the specified rollback triggers during stack creation and update operations. Then, for update operations, it begins disposing of old resources immediately once the operation completes.
Capabilities -> (list)
If you execute the change set, the list of capabilities that were explicitly acknowledged when the change set was created.
(string)
Tags -> (list)
If you execute the change set, the tags that will be associated with the stack.
(structure)
The Tag type enables you to specify a key-value pair that can be used to store information about an CloudFormation stack.
Key -> (string)
Required . A string used to identify this tag. You can specify a maximum of 128 characters for a tag key. Tags owned by Amazon Web Services (Amazon Web Services) have the reserved prefix:
aws:
.Value -> (string)
Required . A string containing the value for this tag. You can specify a maximum of 256 characters for a tag value.
Changes -> (list)
A list of
Change
structures that describes the resources CloudFormation changes if you execute the change set.(structure)
The
Change
structure describes the changes CloudFormation will perform if you execute the change set.Type -> (string)
The type of entity that CloudFormation changes. Currently, the only entity type is
Resource
.HookInvocationCount -> (integer)
Is either
null
, if no hooks invoke for the resource, or contains the number of hooks that will invoke for the resource.ResourceChange -> (structure)
A
ResourceChange
structure that describes the resource and action that CloudFormation will perform.Action -> (string)
The action that CloudFormation takes on the resource, such as
Add
(adds a new resource),Modify
(changes a resource),Remove
(deletes a resource),Import
(imports a resource), orDynamic
(exact action for the resource can’t be determined).LogicalResourceId -> (string)
The resource’s logical ID, which is defined in the stack’s template.
PhysicalResourceId -> (string)
The resource’s physical ID (resource name). Resources that you are adding don’t have physical IDs because they haven’t been created.
ResourceType -> (string)
The type of CloudFormation resource, such as
AWS::S3::Bucket
.Replacement -> (string)
For the
Modify
action, indicates whether CloudFormation will replace the resource by creating a new one and deleting the old one. This value depends on the value of theRequiresRecreation
property in theResourceTargetDefinition
structure. For example, if theRequiresRecreation
field isAlways
and theEvaluation
field isStatic
,Replacement
isTrue
. If theRequiresRecreation
field isAlways
and theEvaluation
field isDynamic
,Replacement
isConditionally
.If you have multiple changes with different
RequiresRecreation
values, theReplacement
value depends on the change with the most impact. ARequiresRecreation
value ofAlways
has the most impact, followed byConditionally
, and thenNever
.Scope -> (list)
For the
Modify
action, indicates which resource attribute is triggering this update, such as a change in the resource attribute’sMetadata
,Properties
, orTags
.(string)
Details -> (list)
For the
Modify
action, a list ofResourceChangeDetail
structures that describes the changes that CloudFormation will make to the resource.(structure)
For a resource with
Modify
as the action, theResourceChange
structure describes the changes CloudFormation will make to that resource.Target -> (structure)
A
ResourceTargetDefinition
structure that describes the field that CloudFormation will change and whether the resource will be recreated.Attribute -> (string)
Indicates which resource attribute is triggering this update, such as a change in the resource attribute’s
Metadata
,Properties
, orTags
.Name -> (string)
If the
Attribute
value isProperties
, the name of the property. For all other attributes, the value is null.RequiresRecreation -> (string)
If the
Attribute
value isProperties
, indicates whether a change to this property causes the resource to be recreated. The value can beNever
,Always
, orConditionally
. To determine the conditions for aConditionally
recreation, see the update behavior for that property in the CloudFormation User Guide.Evaluation -> (string)
Indicates whether CloudFormation can determine the target value, and whether the target value will change before you execute a change set.
For
Static
evaluations, CloudFormation can determine that the target value will change, and its value. For example, if you directly modify theInstanceType
property of an EC2 instance, CloudFormation knows that this property value will change, and its value, so this is aStatic
evaluation.For
Dynamic
evaluations, can’t determine the target value because it depends on the result of an intrinsic function, such as aRef
orFn::GetAtt
intrinsic function, when the stack is updated. For example, if your template includes a reference to a resource that’s conditionally recreated, the value of the reference (the physical ID of the resource) might change, depending on if the resource is recreated. If the resource is recreated, it will have a new physical ID, so all references to that resource will also be updated.ChangeSource -> (string)
The group to which the
CausingEntity
value belongs. There are five entity groups:
ResourceReference
entities areRef
intrinsic functions that refer to resources in the template, such as{ "Ref" : "MyEC2InstanceResource" }
.
ParameterReference
entities areRef
intrinsic functions that get template parameter values, such as{ "Ref" : "MyPasswordParameter" }
.
ResourceAttribute
entities areFn::GetAtt
intrinsic functions that get resource attribute values, such as{ "Fn::GetAtt" : [ "MyEC2InstanceResource", "PublicDnsName" ] }
.
DirectModification
entities are changes that are made directly to the template.
Automatic
entities areAWS::CloudFormation::Stack
resource types, which are also known as nested stacks. If you made no changes to theAWS::CloudFormation::Stack
resource, CloudFormation sets theChangeSource
toAutomatic
because the nested stack’s template might have changed. Changes to a nested stack’s template aren’t visible to CloudFormation until you run an update on the parent stack.CausingEntity -> (string)
The identity of the entity that triggered this change. This entity is a member of the group that’s specified by the
ChangeSource
field. For example, if you modified the value of theKeyPairName
parameter, theCausingEntity
is the name of the parameter (KeyPairName
).If the
ChangeSource
value isDirectModification
, no value is given forCausingEntity
.ChangeSetId -> (string)
The change set ID of the nested change set.
ModuleInfo -> (structure)
Contains information about the module from which the resource was created, if the resource was created from a module included in the stack template.
TypeHierarchy -> (string)
A concatenated list of the module type or types containing the resource. Module types are listed starting with the inner-most nested module, and separated by
/
.In the following example, the resource was created from a module of type
AWS::First::Example::MODULE
, that’s nested inside a parent module of typeAWS::Second::Example::MODULE
.
AWS::First::Example::MODULE/AWS::Second::Example::MODULE
LogicalIdHierarchy -> (string)
A concatenated list of the logical IDs of the module or modules containing the resource. Modules are listed starting with the inner-most nested module, and separated by
/
.In the following example, the resource was created from a module,
moduleA
, that’s nested inside a parent module,moduleB
.
moduleA/moduleB
For more information, see Referencing resources in a module in the CloudFormation User Guide .
NextToken -> (string)
If the output exceeds 1 MB, a string that identifies the next page of changes. If there is no additional page, this value is null.
IncludeNestedStacks -> (boolean)
Verifies if
IncludeNestedStacks
is set toTrue
.
ParentChangeSetId -> (string)
Specifies the change set ID of the parent change set in the current nested change set hierarchy.
RootChangeSetId -> (string)
Specifies the change set ID of the root change set in the current nested change set hierarchy.