aws-cdk 2.1020.2 → 2.1022.0

package/README.md

@@ -11,26 +11,27 @@
 
 The AWS CDK Toolkit provides the `cdk` command-line interface that can be used to work with AWS CDK applications. This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
 
-| Command                               | Description                                                                       |
-| ------------------------------------- | --------------------------------------------------------------------------------- |
-| [`cdk docs`](#cdk-docs)               | Access the online documentation                                                   |
-| [`cdk init`](#cdk-init)               | Start a new CDK project (app or library)                                          |
-| [`cdk list`](#cdk-list)               | List stacks and their dependencies in an application                              |
-| [`cdk synth`](#cdk-synth)             | Synthesize a CDK app to CloudFormation template(s)                                |
-| [`cdk diff`](#cdk-diff)               | Diff stacks against current state                                                 |
-| [`cdk deploy`](#cdk-deploy)           | Deploy a stack into an AWS account                                                |
-| [`cdk rollback`](#cdk-rollback)       | Roll back a failed deployment                                                     |
-| [`cdk import`](#cdk-import)           | Import existing AWS resources into a CDK stack                                    |
-| [`cdk migrate`](#cdk-migrate)         | Migrate AWS resources, CloudFormation stacks, and CloudFormation templates to CDK |
-| [`cdk watch`](#cdk-watch)             | Watches a CDK app for deployable and hotswappable changes                         |
-| [`cdk destroy`](#cdk-destroy)         | Deletes a stack from an AWS account                                               |
-| [`cdk bootstrap`](#cdk-bootstrap)     | Deploy a toolkit stack to support deploying large stacks & artifacts              |
-| [`cdk gc`](#cdk-gc)                   | Garbage collect assets associated with the bootstrapped stack                     |
-| [`cdk doctor`](#cdk-doctor)           | Inspect the environment and produce information useful for troubleshooting        |
-| [`cdk acknowledge`](#cdk-acknowledge) | Acknowledge (and hide) a notice by issue number                                   |
-| [`cdk notices`](#cdk-notices)         | List all relevant notices for the application                                     |
-| [`cdk refactor`](#cdk-refactor)       | Moves resources between stacks or within the same stack                           |
-| [`cdk drift`](#cdk-drift)             | Detect drifts in the given CloudFormation stack(s)                                |
+| Command                                  | Description                                                                       |
+| ---------------------------------------- | --------------------------------------------------------------------------------- |
+| [`cdk docs`](#cdk-docs)                  | Access the online documentation                                                   |
+| [`cdk init`](#cdk-init)                  | Start a new CDK project (app or library)                                          |
+| [`cdk list`](#cdk-list)                  | List stacks and their dependencies in an application                              |
+| [`cdk synth`](#cdk-synth)                | Synthesize a CDK app to CloudFormation template(s)                                |
+| [`cdk diff`](#cdk-diff)                  | Diff stacks against current state                                                 |
+| [`cdk deploy`](#cdk-deploy)              | Deploy a stack into an AWS account                                                |
+| [`cdk rollback`](#cdk-rollback)          | Roll back a failed deployment                                                     |
+| [`cdk import`](#cdk-import)              | Import existing AWS resources into a CDK stack                                    |
+| [`cdk migrate`](#cdk-migrate)            | Migrate AWS resources, CloudFormation stacks, and CloudFormation templates to CDK |
+| [`cdk watch`](#cdk-watch)                | Watches a CDK app for deployable and hotswappable changes                         |
+| [`cdk destroy`](#cdk-destroy)            | Deletes a stack from an AWS account                                               |
+| [`cdk bootstrap`](#cdk-bootstrap)        | Deploy a toolkit stack to support deploying large stacks & artifacts              |
+| [`cdk gc`](#cdk-gc)                      | Garbage collect assets associated with the bootstrapped stack                     |
+| [`cdk doctor`](#cdk-doctor)              | Inspect the environment and produce information useful for troubleshooting        |
+| [`cdk acknowledge`](#cdk-acknowledge)    | Acknowledge (and hide) a notice by issue number                                   |
+| [`cdk notices`](#cdk-notices)            | List all relevant notices for the application                                     |
+| [`cdk refactor`](#cdk-refactor)          | Moves resources between stacks or within the same stack                           |
+| [`cdk drift`](#cdk-drift)                | Detect drifts in the given CloudFormation stack(s)                                |
+| [`cdk cli-telemetry](#cdk-cli-telemetry) | Enable or disable cli telemetry collection                                        |
 
 ## Common topics
 
@@ -1101,8 +1102,12 @@ when using this command.
 
 Compares the infrastructure specified in the current state of the CDK app with 
 the currently deployed application, to determine if any resource was moved 
-(to a different stack or to a different logical ID, or both). The CLI will 
-show the correspondence between the old and new locations in a table:
+(to a different stack or to a different logical ID, or both). In keeping with
+the CloudFormation API, you are not allowed to modify the set of resources
+as part of a refactor. In other words, adding, deleting or updating resources
+is considered an error.
+
+The CLI will show the correspondence between the old and new locations in a table:
 
 ```
 $ cdk refactor --unstable=refactor --dry-run
@@ -1125,41 +1130,45 @@ show this table and exit. Eventually, the CLI will also be able to automatically
 apply the refactor on your CloudFormation stacks. But for now, only the dry-run 
 mode is supported.
 
-If you want to exclude some resources from the refactor, you can pass an 
-exclude file, containing a list of destination locations to exclude. A 
-location can be either the stack name + logical ID, or the construct path. For  
-example, if you don't want to include the bucket and the distribution from 
-the table above in the refactor, you can create a file called 
-`exclude.txt` with the following content (destination locations separated by 
-newlines): 
+If your application has more than one stack, and you want the `refactor`
+command to consider only a subset of them, you can pass a list of stack
+patterns as a parameter:
 
+```shell
+$ cdk refactor Web* --unstable=refactor --dry-run 
 ```
-Web/Website/Origin/Resource
-Web/Website/Distribution/Resource
-```
 
-and pass it to the CLI via the `--exclude-file` flag:
+The pattern language is the same as the one used in the `cdk deploy` command.
+However, unlike `cdk deploy`, in the absence of this parameter, all stacks are
+considered.
+
+The CLI's default behavior is to include in the comparison only the deployed
+stacks that have a counterpart (stack with the same name) locally. If you want
+to include additional deployed stacks in the comparison, pass their names using
+the `--additional-stack-name` option:
 
 ```shell
-$ cdk refactor --exclude-file exclude.txt --unstable=refactor --dry-run
+$ cdk refactor --unstable=refactor --dry-run --additional-stack-name=Foo --additional-stack-name=Bar
 ```
 
-If your application has more than one stack, and you want the refactor 
-command to consider only a subset of them, you can pass a list of stack 
-patterns as a parameter:
+In case of ambiguities, the CLI will display a table like this:
 
-```shell
-$ cdk refactor Web* --unstable=refactor --dry-run 
+```
+Detected ambiguities:
+┌───┬──────────────────────┐
+│   │ Resource             │
+├───┼──────────────────────┤
+│ - │ Stack2/DLQ/Resource  │
+│   │ Stack2/DLQ2/Resource │
+├───┼──────────────────────┤
+│ + │ Stack1/DLQ/Resource  │
+│   │ Stack1/DLQ2/Resource │
+└───┴──────────────────────┘
 ```
 
-The pattern language is the same as the one used in the `cdk deploy` command. 
-However, unlike `cdk deploy`, in the absence of this parameter, all stacks are 
-considered.
-
-If, instead of letting the CLI decide which resources to move, you want to 
-provide your own mapping of old to new locations, you can do so by passing a
-mapping file to the CLI via the `--mapping-file` flag. This file should 
-contain a JSON object with the following format: 
+You can resolve this ambiguity manually, by passing an override file via the
+`--override-file=<path>` CLI option. This file should contain a JSON object 
+with the following structure: 
 
 ```json
 {
@@ -1168,22 +1177,19 @@ contain a JSON object with the following format:
       "account": "123456789012",
       "region": "us-east-1",
       "resources": {
-        "Foo.OldName": "Bar.NewName"
+        "Stack2.OldName": "Stack2.NewName"
       }
     }
   ]
 }
 ```
 
-where `resources` is a mapping of resources from source to destination 
-locations for a given environment. Resource locations are in the format 
-`StackName.LogicalId`.The source must refer to a location where there is a 
-resource currently deployed, while the destination must refer to a location 
+where `resources` is a mapping of resources from source to destination
+locations for a given environment. Resource locations are in the format
+`StackName.LogicalId`.The source must refer to a location where there is a
+resource currently deployed, while the destination must refer to a location
 that is not already occupied by any resource.
 
-If you want to undo a refactor, you can use the `--revert` option in 
-conjunction with the `--mapping-file` option. It will apply the mapping in 
-reverse order (source becomes destination and vice versa).
 
 ### `cdk drift`
 
@@ -1208,6 +1214,31 @@ $ # Detect drift against the currently-deployed stack with the verbose flag enab
 $ cdk drift --verbose 
 ```
 
+### `cdk cli-telemetry`
+
+Enables or disables cli telemetry collection for your local CDK App. Records your
+choice in `cdk.context.json`. You can also set your preference manually under the `context` key in your
+`~/.cdk.json` file or `<app-root>/cdk.json` file.
+
+```bash
+$ # Disable telemetry
+$ cdk cli-telemetry --disable
+
+$ # Enable telemetry
+$ cdk cli-telemetry --enable
+```
+
+You can also check the current status on whether your CDK App is opted in or out of
+cli telemetry collection. Note that this takes into account all methods of disabling
+cli telemetry, including environment variables and
+[context values](https://docs.aws.amazon.com/cdk/v2/guide/context.html)
+that can be set in many different ways (such as `~/.cdk.json`).
+
+```bash
+$ # Check the current status of telemetry
+$ cdk cli-telemetry --status
+```
+
 ## Global Options
 
 ### `unstable`
@@ -1223,6 +1254,20 @@ cdk gc --unstable=gc
 The command will fail if `--unstable=gc` is not passed in, which acknowledges that the user
 is aware of the caveats in place for the feature.
 
+### `telemetry-file`
+
+Send your telemetry data to a local file (note that `--telemetry-file` is unstable, and must
+be passed in conjunction with `--unstable=telemetry`).
+
+```bash
+cdk list --telemetry-file=my/file/path --unstable=telemetry
+```
+
+The supplied path must be a non existing file. If the file exists, it will fail to log telemetry
+data but the command itself will continue uninterrupted.
+
+> Note: The file will be written to regardless of your opt-out status.
+
 ## Notices
 
 CDK Notices are important messages regarding security vulnerabilities, regressions, and usage of unsupported