Skip to content

Commit 04624df

Browse files
author
awstools
committed
feat(client-cloudformation): New CloudFormation DescribeEvents API with operation ID tracking and failure filtering capabilities to quickly identify root causes of deployment failures. Also, a DeploymentMode parameter for the CreateChangeSet API that enables creation of drift-aware change sets for safe drift management.
1 parent 12ad701 commit 04624df

30 files changed

+5817
-4121
lines changed

‎clients/client-cloudformation/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,14 @@ DescribeChangeSetHooks
390390

391391
[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudformation/command/DescribeChangeSetHooksCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudformation/Interface/DescribeChangeSetHooksCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudformation/Interface/DescribeChangeSetHooksCommandOutput/)
392392

393+
</details>
394+
<details>
395+
<summary>
396+
DescribeEvents
397+
</summary>
398+
399+
[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cloudformation/command/DescribeEventsCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudformation/Interface/DescribeEventsCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-cloudformation/Interface/DescribeEventsCommandOutput/)
400+
393401
</details>
394402
<details>
395403
<summary>

‎clients/client-cloudformation/src/CloudFormation.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,11 @@ import {
105105
DescribeChangeSetHooksCommandInput,
106106
DescribeChangeSetHooksCommandOutput,
107107
} from "./commands/DescribeChangeSetHooksCommand";
108+
import {
109+
DescribeEventsCommand,
110+
DescribeEventsCommandInput,
111+
DescribeEventsCommandOutput,
112+
} from "./commands/DescribeEventsCommand";
108113
import {
109114
DescribeGeneratedTemplateCommand,
110115
DescribeGeneratedTemplateCommandInput,
@@ -432,6 +437,7 @@ const commands = {
432437
DescribeAccountLimitsCommand,
433438
DescribeChangeSetCommand,
434439
DescribeChangeSetHooksCommand,
440+
DescribeEventsCommand,
435441
DescribeGeneratedTemplateCommand,
436442
DescribeOrganizationsAccessCommand,
437443
DescribePublisherCommand,
@@ -846,6 +852,21 @@ export interface CloudFormation {
846852
cb: (err: any, data?: DescribeChangeSetHooksCommandOutput) => void
847853
): void;
848854

855+
/**
856+
* @see {@link DescribeEventsCommand}
857+
*/
858+
describeEvents(): Promise<DescribeEventsCommandOutput>;
859+
describeEvents(
860+
args: DescribeEventsCommandInput,
861+
options?: __HttpHandlerOptions
862+
): Promise<DescribeEventsCommandOutput>;
863+
describeEvents(args: DescribeEventsCommandInput, cb: (err: any, data?: DescribeEventsCommandOutput) => void): void;
864+
describeEvents(
865+
args: DescribeEventsCommandInput,
866+
options: __HttpHandlerOptions,
867+
cb: (err: any, data?: DescribeEventsCommandOutput) => void
868+
): void;
869+
849870
/**
850871
* @see {@link DescribeGeneratedTemplateCommand}
851872
*/

‎clients/client-cloudformation/src/CloudFormationClient.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ import {
112112
DescribeChangeSetHooksCommandInput,
113113
DescribeChangeSetHooksCommandOutput,
114114
} from "./commands/DescribeChangeSetHooksCommand";
115+
import { DescribeEventsCommandInput, DescribeEventsCommandOutput } from "./commands/DescribeEventsCommand";
115116
import {
116117
DescribeGeneratedTemplateCommandInput,
117118
DescribeGeneratedTemplateCommandOutput,
@@ -318,6 +319,7 @@ export type ServiceInputTypes =
318319
| DescribeAccountLimitsCommandInput
319320
| DescribeChangeSetCommandInput
320321
| DescribeChangeSetHooksCommandInput
322+
| DescribeEventsCommandInput
321323
| DescribeGeneratedTemplateCommandInput
322324
| DescribeOrganizationsAccessCommandInput
323325
| DescribePublisherCommandInput
@@ -412,6 +414,7 @@ export type ServiceOutputTypes =
412414
| DescribeAccountLimitsCommandOutput
413415
| DescribeChangeSetCommandOutput
414416
| DescribeChangeSetHooksCommandOutput
417+
| DescribeEventsCommandOutput
415418
| DescribeGeneratedTemplateCommandOutput
416419
| DescribeOrganizationsAccessCommandOutput
417420
| DescribePublisherCommandOutput

‎clients/client-cloudformation/src/commands/CreateChangeSetCommand.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ export interface CreateChangeSetCommandOutput extends CreateChangeSetOutput, __M
108108
* IncludeNestedStacks: true || false,
109109
* OnStackFailure: "DO_NOTHING" || "ROLLBACK" || "DELETE",
110110
* ImportExistingResources: true || false,
111+
* DeploymentMode: "REVERT_DRIFT",
111112
* };
112113
* const command = new CreateChangeSetCommand(input);
113114
* const response = await client.send(command);

‎clients/client-cloudformation/src/commands/CreateStackCommand.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ export interface CreateStackCommandOutput extends CreateStackOutput, __MetadataB
9090
* const response = await client.send(command);
9191
* // { // CreateStackOutput
9292
* // StackId: "STRING_VALUE",
93+
* // OperationId: "STRING_VALUE",
9394
* // };
9495
*
9596
* ```

‎clients/client-cloudformation/src/commands/DescribeChangeSetCommand.ts‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ export interface DescribeChangeSetCommandOutput extends DescribeChangeSetOutput,
6565
* // ExecutionStatus: "UNAVAILABLE" || "AVAILABLE" || "EXECUTE_IN_PROGRESS" || "EXECUTE_COMPLETE" || "EXECUTE_FAILED" || "OBSOLETE",
6666
* // Status: "CREATE_PENDING" || "CREATE_IN_PROGRESS" || "CREATE_COMPLETE" || "DELETE_PENDING" || "DELETE_IN_PROGRESS" || "DELETE_COMPLETE" || "DELETE_FAILED" || "FAILED",
6767
* // StatusReason: "STRING_VALUE",
68+
* // StackDriftStatus: "DRIFTED" || "IN_SYNC" || "UNKNOWN" || "NOT_CHECKED",
6869
* // NotificationARNs: [ // NotificationARNs
6970
* // "STRING_VALUE",
7071
* // ],
@@ -92,14 +93,21 @@ export interface DescribeChangeSetCommandOutput extends DescribeChangeSetOutput,
9293
* // HookInvocationCount: Number("int"),
9394
* // ResourceChange: { // ResourceChange
9495
* // PolicyAction: "Delete" || "Retain" || "Snapshot" || "ReplaceAndDelete" || "ReplaceAndRetain" || "ReplaceAndSnapshot",
95-
* // Action: "Add" || "Modify" || "Remove" || "Import" || "Dynamic",
96+
* // Action: "Add" || "Modify" || "Remove" || "Import" || "Dynamic" || "SyncWithActual",
9697
* // LogicalResourceId: "STRING_VALUE",
9798
* // PhysicalResourceId: "STRING_VALUE",
9899
* // ResourceType: "STRING_VALUE",
99100
* // Replacement: "True" || "False" || "Conditional",
100101
* // Scope: [ // Scope
101102
* // "Properties" || "Metadata" || "CreationPolicy" || "UpdatePolicy" || "DeletionPolicy" || "UpdateReplacePolicy" || "Tags",
102103
* // ],
104+
* // ResourceDriftStatus: "IN_SYNC" || "MODIFIED" || "DELETED" || "NOT_CHECKED" || "UNKNOWN" || "UNSUPPORTED",
105+
* // ResourceDriftIgnoredAttributes: [ // ResourceDriftIgnoredAttributes
106+
* // { // ResourceDriftIgnoredAttribute
107+
* // Path: "STRING_VALUE",
108+
* // Reason: "MANAGED_BY_AWS" || "WRITE_ONLY_PROPERTY",
109+
* // },
110+
* // ],
103111
* // Details: [ // ResourceChangeDetails
104112
* // { // ResourceChangeDetail
105113
* // Target: { // ResourceTargetDefinition
@@ -109,10 +117,17 @@ export interface DescribeChangeSetCommandOutput extends DescribeChangeSetOutput,
109117
* // Path: "STRING_VALUE",
110118
* // BeforeValue: "STRING_VALUE",
111119
* // AfterValue: "STRING_VALUE",
112-
* // AttributeChangeType: "Add" || "Remove" || "Modify",
120+
* // BeforeValueFrom: "PREVIOUS_DEPLOYMENT_STATE" || "ACTUAL_STATE",
121+
* // AfterValueFrom: "TEMPLATE",
122+
* // Drift: { // LiveResourceDrift
123+
* // PreviousValue: "STRING_VALUE",
124+
* // ActualValue: "STRING_VALUE",
125+
* // DriftDetectionTimestamp: new Date("TIMESTAMP"),
126+
* // },
127+
* // AttributeChangeType: "Add" || "Remove" || "Modify" || "SyncWithActual",
113128
* // },
114129
* // Evaluation: "Static" || "Dynamic",
115-
* // ChangeSource: "ResourceReference" || "ParameterReference" || "ResourceAttribute" || "DirectModification" || "Automatic",
130+
* // ChangeSource: "ResourceReference" || "ParameterReference" || "ResourceAttribute" || "DirectModification" || "Automatic" || "NoModification",
116131
* // CausingEntity: "STRING_VALUE",
117132
* // },
118133
* // ],
@@ -123,6 +138,7 @@ export interface DescribeChangeSetCommandOutput extends DescribeChangeSetOutput,
123138
* // },
124139
* // BeforeContext: "STRING_VALUE",
125140
* // AfterContext: "STRING_VALUE",
141+
* // PreviousDeploymentContext: "STRING_VALUE",
126142
* // },
127143
* // },
128144
* // ],
@@ -132,6 +148,7 @@ export interface DescribeChangeSetCommandOutput extends DescribeChangeSetOutput,
132148
* // RootChangeSetId: "STRING_VALUE",
133149
* // OnStackFailure: "DO_NOTHING" || "ROLLBACK" || "DELETE",
134150
* // ImportExistingResources: true || false,
151+
* // DeploymentMode: "REVERT_DRIFT",
135152
* // };
136153
*
137154
* ```

‎clients/client-cloudformation/src/commands/DescribeChangeSetHooksCommand.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ export interface DescribeChangeSetHooksCommandOutput extends DescribeChangeSetHo
6060
* // ResourceTargetDetails: { // ChangeSetHookResourceTargetDetails
6161
* // LogicalResourceId: "STRING_VALUE",
6262
* // ResourceType: "STRING_VALUE",
63-
* // ResourceAction: "Add" || "Modify" || "Remove" || "Import" || "Dynamic",
63+
* // ResourceAction: "Add" || "Modify" || "Remove" || "Import" || "Dynamic" || "SyncWithActual",
6464
* // },
6565
* // },
6666
* // },

‎clients/client-cloudformation/src/commands/DescribeEventsCommand.ts‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
// smithy-typescript generated code
2+
import { getEndpointPlugin } from "@smithy/middleware-endpoint";
3+
import { Command as $Command } from "@smithy/smithy-client";
4+
import { MetadataBearer as __MetadataBearer } from "@smithy/types";
5+
6+
import { CloudFormationClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../CloudFormationClient";
7+
import { commonParams } from "../endpoint/EndpointParameters";
8+
import { DescribeEventsInput, DescribeEventsOutput } from "../models/models_0";
9+
import { DescribeEvents } from "../schemas/schemas_0";
10+
11+
/**
12+
* @public
13+
*/
14+
export type { __MetadataBearer };
15+
export { $Command };
16+
/**
17+
* @public
18+
*
19+
* The input for {@link DescribeEventsCommand}.
20+
*/
21+
export interface DescribeEventsCommandInput extends DescribeEventsInput {}
22+
/**
23+
* @public
24+
*
25+
* The output of {@link DescribeEventsCommand}.
26+
*/
27+
export interface DescribeEventsCommandOutput extends DescribeEventsOutput, __MetadataBearer {}
28+
29+
/**
30+
* <p>Returns CloudFormation events based on flexible query criteria. Groups events by operation ID,
31+
* enabling you to focus on individual stack operations during deployment.</p>
32+
* <p>An operation is any action performed on a stack, including stack lifecycle actions
33+
* (Create, Update, Delete, Rollback), change set creation, nested stack creation, and automatic
34+
* rollbacks triggered by failures. Each operation has a unique identifier (Operation ID) and
35+
* represents a discrete change attempt on the stack.</p>
36+
* <p>Returns different types of events including:</p>
37+
* <ul>
38+
* <li>
39+
* <p>
40+
* <b>Progress events</b> - Status updates during stack operation
41+
* execution.</p>
42+
* </li>
43+
* <li>
44+
* <p>
45+
* <b>Validation errors</b> - Failures from CloudFormation Early
46+
* Validations.</p>
47+
* </li>
48+
* <li>
49+
* <p>
50+
* <b>Provisioning errors</b> - Resource creation and update
51+
* failures.</p>
52+
* </li>
53+
* <li>
54+
* <p>
55+
* <b>Hook invocation errors</b> - Failures from CloudFormation
56+
* Hook during stack operations.</p>
57+
* </li>
58+
* </ul>
59+
* <note>
60+
* <p>One of <code>ChangeSetName</code>, <code>OperationId</code> or <code>StackName</code>
61+
* must be specified as input.</p>
62+
* </note>
63+
* @example
64+
* Use a bare-bones client and the command you need to make an API call.
65+
* ```javascript
66+
* import { CloudFormationClient, DescribeEventsCommand } from "@aws-sdk/client-cloudformation"; // ES Modules import
67+
* // const { CloudFormationClient, DescribeEventsCommand } = require("@aws-sdk/client-cloudformation"); // CommonJS import
68+
* // import type { CloudFormationClientConfig } from "@aws-sdk/client-cloudformation";
69+
* const config = {}; // type is CloudFormationClientConfig
70+
* const client = new CloudFormationClient(config);
71+
* const input = { // DescribeEventsInput
72+
* StackName: "STRING_VALUE",
73+
* ChangeSetName: "STRING_VALUE",
74+
* OperationId: "STRING_VALUE",
75+
* Filters: { // EventFilter
76+
* FailedEvents: true || false,
77+
* },
78+
* NextToken: "STRING_VALUE",
79+
* };
80+
* const command = new DescribeEventsCommand(input);
81+
* const response = await client.send(command);
82+
* // { // DescribeEventsOutput
83+
* // OperationEvents: [ // OperationEvents
84+
* // { // OperationEvent
85+
* // EventId: "STRING_VALUE",
86+
* // StackId: "STRING_VALUE",
87+
* // OperationId: "STRING_VALUE",
88+
* // OperationType: "CREATE_STACK" || "UPDATE_STACK" || "DELETE_STACK" || "CONTINUE_ROLLBACK" || "ROLLBACK" || "CREATE_CHANGESET",
89+
* // OperationStatus: "IN_PROGRESS" || "SUCCEEDED" || "FAILED",
90+
* // EventType: "STACK_EVENT" || "PROGRESS_EVENT" || "VALIDATION_ERROR" || "PROVISIONING_ERROR" || "HOOK_INVOCATION_ERROR",
91+
* // LogicalResourceId: "STRING_VALUE",
92+
* // PhysicalResourceId: "STRING_VALUE",
93+
* // ResourceType: "STRING_VALUE",
94+
* // Timestamp: new Date("TIMESTAMP"),
95+
* // StartTime: new Date("TIMESTAMP"),
96+
* // EndTime: new Date("TIMESTAMP"),
97+
* // ResourceStatus: "CREATE_IN_PROGRESS" || "CREATE_FAILED" || "CREATE_COMPLETE" || "DELETE_IN_PROGRESS" || "DELETE_FAILED" || "DELETE_COMPLETE" || "DELETE_SKIPPED" || "UPDATE_IN_PROGRESS" || "UPDATE_FAILED" || "UPDATE_COMPLETE" || "IMPORT_FAILED" || "IMPORT_COMPLETE" || "IMPORT_IN_PROGRESS" || "IMPORT_ROLLBACK_IN_PROGRESS" || "IMPORT_ROLLBACK_FAILED" || "IMPORT_ROLLBACK_COMPLETE" || "EXPORT_FAILED" || "EXPORT_COMPLETE" || "EXPORT_IN_PROGRESS" || "EXPORT_ROLLBACK_IN_PROGRESS" || "EXPORT_ROLLBACK_FAILED" || "EXPORT_ROLLBACK_COMPLETE" || "UPDATE_ROLLBACK_IN_PROGRESS" || "UPDATE_ROLLBACK_COMPLETE" || "UPDATE_ROLLBACK_FAILED" || "ROLLBACK_IN_PROGRESS" || "ROLLBACK_COMPLETE" || "ROLLBACK_FAILED",
98+
* // ResourceStatusReason: "STRING_VALUE",
99+
* // ResourceProperties: "STRING_VALUE",
100+
* // ClientRequestToken: "STRING_VALUE",
101+
* // HookType: "STRING_VALUE",
102+
* // HookStatus: "HOOK_IN_PROGRESS" || "HOOK_COMPLETE_SUCCEEDED" || "HOOK_COMPLETE_FAILED" || "HOOK_FAILED",
103+
* // HookStatusReason: "STRING_VALUE",
104+
* // HookInvocationPoint: "PRE_PROVISION",
105+
* // HookFailureMode: "FAIL" || "WARN",
106+
* // DetailedStatus: "CONFIGURATION_COMPLETE" || "VALIDATION_FAILED",
107+
* // ValidationFailureMode: "FAIL" || "WARN",
108+
* // ValidationName: "STRING_VALUE",
109+
* // ValidationStatus: "FAILED" || "SKIPPED",
110+
* // ValidationStatusReason: "STRING_VALUE",
111+
* // ValidationPath: "STRING_VALUE",
112+
* // },
113+
* // ],
114+
* // NextToken: "STRING_VALUE",
115+
* // };
116+
*
117+
* ```
118+
*
119+
* @param DescribeEventsCommandInput - {@link DescribeEventsCommandInput}
120+
* @returns {@link DescribeEventsCommandOutput}
121+
* @see {@link DescribeEventsCommandInput} for command's `input` shape.
122+
* @see {@link DescribeEventsCommandOutput} for command's `response` shape.
123+
* @see {@link CloudFormationClientResolvedConfig | config} for CloudFormationClient's `config` shape.
124+
*
125+
* @throws {@link CloudFormationServiceException}
126+
* <p>Base exception class for all service exceptions from CloudFormation service.</p>
127+
*
128+
*
129+
* @public
130+
*/
131+
export class DescribeEventsCommand extends $Command
132+
.classBuilder<
133+
DescribeEventsCommandInput,
134+
DescribeEventsCommandOutput,
135+
CloudFormationClientResolvedConfig,
136+
ServiceInputTypes,
137+
ServiceOutputTypes
138+
>()
139+
.ep(commonParams)
140+
.m(function (this: any, Command: any, cs: any, config: CloudFormationClientResolvedConfig, o: any) {
141+
return [getEndpointPlugin(config, Command.getEndpointParameterInstructions())];
142+
})
143+
.s("CloudFormation", "DescribeEvents", {})
144+
.n("CloudFormationClient", "DescribeEventsCommand")
145+
.sc(DescribeEvents)
146+
.build() {
147+
/** @internal type navigation helper, not in runtime. */
148+
protected declare static __types: {
149+
api: {
150+
input: DescribeEventsInput;
151+
output: DescribeEventsOutput;
152+
};
153+
sdk: {
154+
input: DescribeEventsCommandInput;
155+
output: DescribeEventsCommandOutput;
156+
};
157+
};
158+
}

‎clients/client-cloudformation/src/commands/DescribeStackEventsCommand.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ export interface DescribeStackEventsCommandOutput extends DescribeStackEventsOut
5454
* // StackId: "STRING_VALUE", // required
5555
* // EventId: "STRING_VALUE", // required
5656
* // StackName: "STRING_VALUE", // required
57+
* // OperationId: "STRING_VALUE",
5758
* // LogicalResourceId: "STRING_VALUE",
5859
* // PhysicalResourceId: "STRING_VALUE",
5960
* // ResourceType: "STRING_VALUE",

‎clients/client-cloudformation/src/commands/DescribeStackResourceCommand.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ export interface DescribeStackResourceCommandOutput extends DescribeStackResourc
5757
* // Description: "STRING_VALUE",
5858
* // Metadata: "STRING_VALUE",
5959
* // DriftInformation: { // StackResourceDriftInformation
60-
* // StackResourceDriftStatus: "IN_SYNC" || "MODIFIED" || "DELETED" || "NOT_CHECKED" || "UNKNOWN", // required
60+
* // StackResourceDriftStatus: "IN_SYNC" || "MODIFIED" || "DELETED" || "NOT_CHECKED" || "UNKNOWN" || "UNSUPPORTED", // required
6161
* // LastCheckTimestamp: new Date("TIMESTAMP"),
6262
* // },
6363
* // ModuleInfo: { // ModuleInfo

0 commit comments

Comments
 (0)