Update: Add documentation for 'cdk rollback' command

evzzk · evzzk · commit 006c940bcb32 · 2024-10-04T09:55:39.000-10:00
diff --git a/v2/bootstrapping-env.md b/v2/bootstrapping-env.md
@@ -260,7 +260,7 @@ This section contains a list of the changes made in each version\.
 | 20 | 2\.119\.0 | Add ssm:GetParameters action to the AWS CloudFormation deploy IAM role\. For more information, see [\#28336](https://github.com/aws/aws-cdk/pull/28336/files#diff-4fdac38426c4747aa17d515b01af4994d3d2f12c34f7b6655f24328259beb7bf)\. | 
 | 21 | 2\.149\.0 | Add condition to the file publishing role\. | 
 | 22 | 2\.160\.0 | Add sts:TagSession permissions to the trust policy of bootstrap IAM roles\. | 
-| 23 | 2\.161\.0 | Add cloudformation:RollbackStack and cloudformation:ContinueUpdateRollback permissions to the trust policy of the deploy IAM role\. | 
+| 23 | 2\.161\.0 | Add cloudformation:RollbackStack and cloudformation:ContinueUpdateRollback permissions to the trust policy of the deploy IAM role\. This provides permissions for the cdk rollback command\. | 
 
 ## Upgrade from legacy to modern bootstrap template<a name="bootstrapping-template"></a>
 
diff --git a/v2/hello_world.md b/v2/hello_world.md
@@ -891,7 +891,7 @@ func NewHelloCdkStack(scope constructs.Construct, id string, props *HelloCdkStac
 
 Let's take a closer look at the `Function` construct\. Like all constructs, the `Function` class takes three parameters:
 + **scope** – Defines your `Stack` instance as the parent of the `Function` construct\. All constructs that define AWS resources are created within the scope of a stack\. You can define constructs inside of constructs, creating a hierarchy \(tree\)\. Here, and in most cases, the scope is `this` \(`self` in Python\)\.
-+ **Id** – The logical ID of the `Function` within your AWS CDK app\. This ID, plus a hash based on the function's location within the stack, uniquely identifies the function during deployment\. The AWS CDK also references this ID when you update the construct in your app and re\-deploy to update the deployed resource\. Here, your logical ID is `HelloWorldFunction`\. Functions can also have a name, specified with the `functionName` property\. This is different from the logical ID\.
++ **Id** – The construct ID of the `Function` within your AWS CDK app\. This ID, plus a hash based on the function's location within the stack, uniquely identifies the function during deployment\. The AWS CDK also references this ID when you update the construct in your app and re\-deploy to update the deployed resource\. Here, your construct ID is `HelloWorldFunction`\. Functions can also have a name, specified with the `functionName` property\. This is different from the construct ID\.
 + **props** – A bundle of values that define properties of the function\. Here you define the `runtime`, `handler`, and `code` properties\.
 
   Props are represented differently in the languages supported by the AWS CDK\.
diff --git a/v2/index.md b/v2/index.md
@@ -89,6 +89,7 @@ sponsored by Amazon.
    + [cdk metadata](ref-cli-cmd-metadata.md)
    + [cdk migrate](ref-cli-cdk-migrate.md)
    + [cdk notices](ref-cli-cmd-notices.md)
+   + [cdk rollback](ref-cli-cmd-rollback.md)
    + [cdk synthesize](ref-cli-cmd-synth.md)
    + [cdk watch](ref-cli-cmd-watch.md)
 + [AWS CDK reference](reference.md)
diff --git a/v2/ref-cli-cmd-bootstrap.md b/v2/ref-cli-cmd-bootstrap.md
@@ -110,6 +110,7 @@ To learn more about termination protection, see [Protecting a stack from being d
 `--toolkit-stack-name STRING`  <a name="ref-cli-cmd-bootstrap-options-toolkit-stack-name"></a>
 The name of the bootstrap stack to create\.  
 By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment\. Use this option to provide a different name for your bootstrap stack\.  
+The CDK CLI uses this value to verify your bootstrap stack version\.  
 *Default value*: `CDKToolkit`  
 *Required*: Yes
 
diff --git a/v2/ref-cli-cmd-deploy.md b/v2/ref-cli-cmd-deploy.md
@@ -14,8 +14,8 @@ $ cdk deploy <arguments> <options>
 
 ## Arguments<a name="ref-cli-cmd-deploy-args"></a>
 
-**CDK stack logical ID**  <a name="ref-cli-cmd-deploy-args-stack-name"></a>
-The logical ID of the CDK stack from your app to deploy\.  
+**CDK stack ID**  <a name="ref-cli-cmd-deploy-args-stack-name"></a>
+The construct ID of the CDK stack from your app to deploy\.  
 *Type*: String  
 *Required*: No
 
@@ -163,16 +163,17 @@ Specify what security\-sensitive changes require manual approval\.
 *Valid values*: `any-change`, `broadening`, `never`  
 *Default value*: `broadening`
 
-`--rollback BOOLEAN`  <a name="ref-cli-cmd-deploy-options-rollback"></a>
+`--rollback` \| `--no-rollback`, `-R`  <a name="ref-cli-cmd-deploy-options-rollback"></a>
 During deployment, if a resource fails to be created or updated, the deployment will roll back to the latest stable state before the CDK CLI returns\. All changes made up to that point will be undone\. Resources that were created will be deleted and updates that were made will be rolled back\.  
-Specify `false` to deactivate this behavior\. If a resource fails to be created or updated, the CDK CLI will leave changes made up to that point in place and return\. This may be helpful in development environments where you are iterating quickly\.  
-For `--rollback=false`, you can use `--no-rollback` or `-R`\.  
-When `false`, deployments that cause resource replacements will always fail\. You can only use this option value for deployments that update or create new resources\.
-*Default value*: `true`
+Specify `--no-rollback` to turn off this behavior\. If a resource fails to be created or updated, the CDK CLI will leave changes made up to that point in place and return\. This will leave your deployment in a failed, paused state\. From here, you can update your code and try the deployment again\. This may be helpful in development environments where you are iterating quickly\.  
+If a deployment performed with `--no-rollback` fails, and you decide that you want to rollback the deployment, you can use the `cdk rollback` command\. For more information, see [cdk rollback](ref-cli-cmd-rollback.md)\.  
+With `--no-rollback`, deployments that cause resource replacements will always fail\. You can only use this option value for deployments that update or create new resources\.
+*Default value*: `--rollback`
 
 `--toolkit-stack-name STRING`  <a name="ref-cli-cmd-deploy-options-toolkit-stack-name"></a>
 The name of the existing CDK Toolkit stack\.  
-This option is only used for CDK apps using legacy synthesis\.
+By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment\. Use this option to provide a different name for your bootstrap stack\.  
+The CDK CLI uses this value to verify your bootstrap stack version\.
 
 `--watch BOOLEAN`  <a name="ref-cli-cmd-deploy-options-watch"></a>
 Continuously observe CDK project files, and deploy the specified stacks automatically when changes are detected\.  
diff --git a/v2/ref-cli-cmd-destroy.md b/v2/ref-cli-cmd-destroy.md
@@ -14,8 +14,8 @@ $ cdk destroy <arguments> <options>
 
 ## Arguments<a name="ref-cli-cmd-destroy-args"></a>
 
-**CDK stack logical ID**  <a name="ref-cli-cmd-destroy-args-stack-name"></a>
-The logical ID of the CDK stack from your app to delete\.  
+**CDK stack ID**  <a name="ref-cli-cmd-destroy-args-stack-name"></a>
+The construct ID of the CDK stack from your app to delete\.  
 *Type*: String  
 *Required*: No
 
diff --git a/v2/ref-cli-cmd-diff.md b/v2/ref-cli-cmd-diff.md
@@ -12,8 +12,8 @@ $ cdk diff <arguments> <options>
 
 ## Arguments<a name="ref-cli-cmd-diff-args"></a>
 
-**CDK stack logical ID**  <a name="ref-cli-cmd-diff-args-stack-name"></a>
-The logical ID of the CDK stack from your app to perform a diff\.  
+**CDK stack ID**  <a name="ref-cli-cmd-diff-args-stack-name"></a>
+The construct ID of the CDK stack from your app to perform a diff\.  
 *Type*: String  
 *Required*: No
 
diff --git a/v2/ref-cli-cmd-import.md b/v2/ref-cli-cmd-import.md
@@ -38,8 +38,8 @@ $ cdk import <arguments> <options>
 
 ## Arguments<a name="ref-cli-cmd-import-args"></a>
 
-**CDK stack logical ID**  <a name="ref-cli-cmd-import-args-stack-name"></a>
-The logical ID of the CDK stack from your app to import resources to\. This argument can be provided multiple times in a single command\.  
+**CDK stack ID**  <a name="ref-cli-cmd-import-args-stack-name"></a>
+The construct ID of the CDK stack from your app to import resources to\. This argument can be provided multiple times in a single command\.  
 *Type*: String  
 *Required*: No
 
@@ -74,4 +74,6 @@ Specify `false` to iterate more rapidly\. Deployments containing resource replac
 *Default value*: `true`
 
 `--toolkit-stack-name STRING`  <a name="ref-cli-cmd-import-options-toolkit-stack-name"></a>
-The name of the CDK Toolkit stack to create
+The name of the CDK Toolkit stack to create\.  
+By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment\. Use this option to provide a different name for your bootstrap stack\.  
+The CDK CLI uses this value to verify your bootstrap stack version\.
diff --git a/v2/ref-cli-cmd-list.md b/v2/ref-cli-cmd-list.md
@@ -10,8 +10,8 @@ $ cdk list <arguments> <options>
 
 ## Arguments<a name="ref-cli-cmd-list-args"></a>
 
-**CDK stack logical ID**  <a name="ref-cli-cmd-list-args-stack-name"></a>
-The logical ID of the CDK stack from your app to perform this command against\.  
+**CDK stack ID**  <a name="ref-cli-cmd-list-args-stack-name"></a>
+The construct ID of the CDK stack from your app to perform this command against\.  
 *Type*: String  
 *Required*: No
 
diff --git a/v2/ref-cli-cmd-metadata.md b/v2/ref-cli-cmd-metadata.md
@@ -10,8 +10,8 @@ $ cdk metadata <arguments> <options>
 
 ## Arguments<a name="ref-cli-cmd-metadata-args"></a>
 
-**CDK stack logical ID**  <a name="ref-cli-cmd-metadata-args-stack-name"></a>
-The logical ID of the CDK stack from your app to display metadata for\.  
+**CDK stack ID**  <a name="ref-cli-cmd-metadata-args-stack-name"></a>
+The construct ID of the CDK stack from your app to display metadata for\.  
 *Type*: String  
 *Required*: No
 
diff --git a/v2/ref-cli-cmd-rollback.md b/v2/ref-cli-cmd-rollback.md
@@ -0,0 +1,54 @@
+# cdk rollback<a name="ref-cli-cmd-rollback"></a>
+
+Use the AWS Cloud Development Kit \(AWS CDK\) Command Line Interface \(CLI\) `cdk rollback` command to rollback a failed or paused stack from an AWS CloudFormation deployment to its last stable state\.
+
+**Note**  
+To use this command, you must have v23 of the bootstrap template deployed to your environment\. For more information, see [Bootstrap template version history](bootstrapping-env.md#bootstrap-template-history)\.
+
+When you deploy using `cdk deploy`, the CDK CLI will rollback a failed deployment by default\. If you specify `--no-rollback` with `cdk deploy`, you can then use the `cdk rollback` command to manually rollback a failed deployment\. This will initiate a rollback to the last stable state of your stack\.
+
+## Usage<a name="ref-cli-cmd-rollback-usage"></a>
+
+```
+$ cdk rollback <arguments> <options>
+```
+
+## Arguments<a name="ref-cli-cmd-rollback-args"></a>
+
+**CDK stack ID**  <a name="ref-cli-cmd-rollback-args-stack-name"></a>
+The construct ID of the CDK stack from your app to rollback\.  
+*Type*: String  
+*Required*: No
+
+## Options<a name="ref-cli-cmd-rollback-options"></a>
+
+For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options)\.
+
+`--all BOOLEAN`  <a name="ref-cli-cmd-rollback-options-all"></a>
+Rollback all stacks in your CDK app\.  
+*Default value*: `false`
+
+`--force, -f BOOLEAN`  <a name="ref-cli-cmd-rollback-options-force"></a>
+When you use `cdk rollback`, some resources may fail to rollback\. Provide this option to force the rollback of all resources\. This is the same behavior as providing the `--orphan` option for each resource in your stack\.  
+*Default value*: `false`
+
+`--help, -h BOOLEAN`  <a name="ref-cli-cmd-rollback-options-help"></a>
+Show command reference information for the `cdk rollback` command\.
+
+`--orphan LogicalId`  <a name="ref-cli-cmd-rollback-options-orphan"></a>
+When you use `cdk rollback`, some resources may fail to rollback\. When this happens, you can try to force the rollback of a resource by using this option and providing the logical ID of the resource that failed to rollback\.  
+This option can be provided multiple times in a single command The following is an example:  
+
+```
+$ cdk rollback MyStack --orphan MyLambdaFunction --orphan MyLambdaFunction2
+```
+To force the rollback of all resources, use the `--force` option instead\.
+
+`--toolkit-stack-name STRING`  <a name="ref-cli-cmd-rollback-options-toolkit-stack-name"></a>
+The name of the existing CDK Toolkit stack that the environment is bootstrapped with\.  
+By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment\. Use this option to provide a different name for your bootstrap stack\.  
+The CDK CLI uses this value to verify your bootstrap stack version\.
+
+`--validate-bootstrap-version BOOLEAN`  <a name="ref-cli-cmd-rollback-options-validate-bootstrap-version"></a>
+Specify whether to validate the bootstrap stack version\. Provide `--validate-bootstrap-version=false` or `--no-validate-bootsrap-version` to turn off this behavior\.  
+*Default value*: `true`
diff --git a/v2/ref-cli-cmd-synth.md b/v2/ref-cli-cmd-synth.md
@@ -16,8 +16,8 @@ $ cdk synthesize <arguments> <options>
 
 ## Arguments<a name="ref-cli-cmd-synth-args"></a>
 
-**CDK stack logical ID**  <a name="ref-cli-cmd-synth-args-stack-name"></a>
-The logical ID of the CDK stack from your app to synthesize\.  
+**CDK stack ID**  <a name="ref-cli-cmd-synth-args-stack-name"></a>
+The construct ID of the CDK stack from your app to synthesize\.  
 *Type*: String  
 *Required*: No
 
diff --git a/v2/ref-cli-cmd-watch.md b/v2/ref-cli-cmd-watch.md
@@ -31,8 +31,8 @@ $ cdk watch <arguments> <options>
 
 ## Arguments<a name="ref-cli-cmd-watch-args"></a>
 
-**CDK stack logical ID**  <a name="ref-cli-cmd-watch-args-stack-name"></a>
-The logical ID of the CDK stack from your app to watch\.  
+**CDK stack ID**  <a name="ref-cli-cmd-watch-args-stack-name"></a>
+The construct ID of the CDK stack from your app to watch\.  
 *Type*: String  
 *Required*: No
 
@@ -96,7 +96,8 @@ When `false`, deployments that cause resource replacements will always fail\. Yo
 
 `--toolkit-stack-name STRING`  <a name="ref-cli-cmd-watch-options-toolkit-stack-name"></a>
 The name of the existing CDK Toolkit stack\.  
-This option is only used for CDK apps using legacy synthesis\.
+By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment\. Use this option to provide a different name for your bootstrap stack\.  
+The CDK CLI uses this value to verify your bootstrap stack version\.
 
 ## Examples<a name="ref-cli-cmd-watch-examples"></a>
 
