aws-cdk 2.1118.4 → 2.1120.0

package/README.md

@@ -17,11 +17,13 @@ The AWS CDK Toolkit provides the `cdk` command-line interface that can be used t
 | [`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 diagnose`](#cdk-diagnose)             | Diagnose a failed stack's root cause                                              |
 | [`cdk diff`](#cdk-diff)                     | Diff stacks against current state                                                 |
 | [`cdk deploy`](#cdk-deploy)                 | Deploy a stack into an AWS account                                                |
 | [`cdk publish-assets`](#cdk-publish-assets) | Publish assets for stack(s) without deploying                                     |
 | [`cdk rollback`](#cdk-rollback)             | Roll back a failed deployment                                                     |
 | [`cdk import`](#cdk-import)                 | Import existing AWS resources into a CDK stack                                    |
+| [`cdk orphan`](#cdk-orphan)                 | Detach resources from a stack without deleting them                               |
 | [`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                                               |
@@ -158,6 +160,30 @@ The `quiet` option can be set in the `cdk.json` file.
 See the [AWS Documentation](https://docs.aws.amazon.com/cdk/latest/guide/apps.html#apps_cloud_assembly) to learn more about cloud assemblies.
 See the [CDK reference documentation](https://docs.aws.amazon.com/cdk/api/latest/docs/cloud-assembly-schema-readme.html) for details on the cloud assembly specification
 
+### `cdk diagnose`
+
+> [!CAUTION]
+> `cdk diagnose` is under development and therefore must be opted in via the
+> `--unstable` flag: `cdk --unstable=diagnose diagnose`. `--unstable` indicates
+> that the scope and API of feature might still change. Otherwise the feature
+> is generally production ready and fully supported.
+
+Looks at a failed stack deployment in CloudFormation, and prints the root cause
+reason with pointers to the CDK source code that caused the problem.
+
+This peforms the same diagnosis that `cdk deploy` does, but does it
+after-the-fact. This can be useful to refresh your memory, ask a colleague to
+help diagnose a deployment problem, or try to diagnose a deployment problem if
+your way of working dictates that you perform stack deployment via a CI/CD
+system instead of directly using the CDK CLI.
+
+```console
+# Diagnose all stacks found inside the application
+$ cdk --unstable=diagnose diagnose
+
+# Diagnose the failed deployment of a specific stack
+$ cdk --unstable=diagnose diagnose <MyStackName>
+```
 
 ### `cdk diff`
 
@@ -166,10 +192,10 @@ deployed application (or a user-specified CloudFormation template). If you need
 found you need to use the `--fail` command line option.
 
 ```console
-$ # Diff against the currently deployed stack
+# Diff against the currently deployed stack
 $ cdk diff --app='node bin/main.js' MyStackName
 
-$ # Diff against a specific template document
+# Diff against a specific template document
 $ cdk diff --app='node bin/main.js' MyStackName --template=path/to/template.yml
 ```
 
@@ -409,6 +435,11 @@ be deployed and then executes it. This behavior can be controlled with the
 - `--method=prepare-change-set`: create the change set but don't execute it.
   This is useful if you have external tools that will inspect the change set or
   you have an approval process for change sets.
+- `--method=execute-change-set`: execute a previously created change set. This
+  bypasses change set creation and asset publishing entirely. Requires exactly
+  one stack name. Defaults to the `cdk-deploy-change-set` change set name if
+  `--change-set-name` is not provided. This is useful for two-step deployment
+  workflows where you first review a change set and then execute it.
 - `--method=direct`: do not create a change set but apply the change immediately.
   This is typically a bit faster than creating a change set, but it loses
   the progress information.
@@ -428,8 +459,23 @@ set to make it easier to later execute:
 $ cdk deploy --method=prepare-change-set --change-set-name MyChangeSetName
 ```
 
-For more control over when stack changes are deployed, the CDK can generate a
-CloudFormation change set but not execute it.
+To review a change set before executing it, use a two-step workflow:
+
+```console
+$ # Step 1: Create the change set without executing it
+$ cdk deploy MyStack --method=prepare-change-set
+
+$ # Step 2: Review the change set (e.g., in the AWS Console or via CLI)
+
+$ # Step 3: Execute the change set
+$ cdk deploy MyStack --method=execute-change-set
+```
+
+A custom change set name can be provided with `--change-set-name` in both steps.
+
+When using `--method=execute-change-set`, the options `--force`, `--parameters`,
+`--import-existing-resources`, and `--revert-drift` cannot be used
+since the change set has already been created.
 
 #### Import existing resources
 
@@ -460,9 +506,9 @@ $ cdk deploy --import-existing-resources --exclusively StackName
 ```
 
 Only resources that have custom names can be imported using `--import-existing-resources`.
-For more information, see [name type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html). 
+For more information, see [name type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html).
 To import resources that do not accept custom names, such as EC2 instances,
-use the `cdk import` instead. 
+use the `cdk import` instead.
 Visit [Bringing existing resources into CloudFormation management](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import.html)
 for more details.
 
@@ -792,6 +838,73 @@ This feature currently has the following limitations:
   IAM permissions to the `deploy-role`.
 
 
+### `cdk orphan`
+
+> `cdk orphan` is currently experimental, meaning we reserve the right to change 
+> options and flag names in the future. Pass the `--unstable=orphan` flag when using
+> this command and be aware of this when using it in scripts.
+
+Safely detaches one or more resources from a CloudFormation stack without deleting them.
+This is useful when you need to migrate a resource from one construct type to another
+(for example, migrating a DynamoDB `Table` to `TableV2`) without any downtime or data loss.
+
+The orphan command works by:
+
+1. Resolving cross-resource references (`Ref`, `Fn::GetAtt`, `Fn::Sub`) to the orphaned resources, so that other resources in the stack that depend on them continue to work after the orphaned resources are removed
+2. Setting the `DeletionPolicy` to `Retain`, replacing all cross-resource references with literal values, and removing `DependsOn` entries to isolate the resources from the rest of the stack
+3. Removing the resources from the CloudFormation template (they continue to exist in your AWS account)
+
+After orphaning, you can update your CDK code and use `cdk import` to bring the resource back under management with the new construct type.
+
+All construct paths must reference the same stack. Wildcard patterns are not supported; paths are matched as exact prefixes.
+
+```console
+$ # Orphan a single resource
+$ cdk orphan --unstable=orphan MyStack/MyTable
+
+$ # Orphan multiple resources
+$ cdk orphan --unstable=orphan MyStack/MyTable MyStack/MyBucket
+```
+
+#### Example: Migrating DynamoDB Table to TableV2
+
+1. Deploy your stack with the original `Table` construct:
+
+    ```ts
+    const table = new dynamodb.Table(this, 'MyTable', {
+      tableName: 'my-table',
+      partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING },
+    });
+    ```
+
+2. Orphan the table from the stack:
+
+    ```console
+    $ cdk orphan --unstable=orphan MyStack/MyTable
+    ```
+
+    The command outputs next steps including a `cdk import` command with the resource mapping.
+
+3. Update your CDK code to use `TableV2`:
+
+    ```ts
+    const table = new dynamodb.TableV2(this, 'MyTable', {
+      tableName: 'my-table',
+      partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING },
+    });
+    ```
+
+4. Import the existing table into the new construct:
+
+    ```console
+    $ cdk import --resource-mapping-inline '{"MyTable794EDED1":{"TableName":"my-table"}}'
+    ```
+
+    The import command will show any pending drift and offer to run `cdk deploy` afterwards to reconcile it.
+
+The table remains available throughout the entire process with zero downtime.
+
+
 ### `cdk migrate`
 
 ⚠️**CAUTION**⚠️: CDK Migrate is currently experimental and may have breaking changes in the future.
@@ -1056,9 +1169,9 @@ cdk bootstrap --no-previous-parameters
 CDK Garbage Collection.
 
 > [!CAUTION]
-> CDK Garbage Collection is under development and therefore must be opted in via the 
->`--unstable` flag: `cdk gc --unstable=gc`. `--unstable` indicates that the scope and 
-> API of feature might still change. Otherwise the feature is generally production 
+> CDK Garbage Collection is under development and therefore must be opted in via the
+>`--unstable` flag: `cdk gc --unstable=gc`. `--unstable` indicates that the scope and
+> API of feature might still change. Otherwise the feature is generally production
 > ready and fully supported.
 
 `cdk gc` garbage collects unused assets from your bootstrap bucket via the following mechanism:
@@ -1171,12 +1284,12 @@ $ cdk doctor
 
 ### `cdk refactor`
 
-⚠️**CAUTION**⚠️: CDK Refactor is currently experimental and may have 
-breaking changes in the future. Make sure to use the `--unstable=refactor` flag 
+⚠️**CAUTION**⚠️: CDK Refactor is currently experimental and may have
+breaking changes in the future. Make sure to use the `--unstable=refactor` flag
 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 
+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). 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
@@ -1200,9 +1313,9 @@ The following resources were moved or renamed:
 └───────────────────────────────┴───────────────────────────────┴───────────────────────────────────┘
 ```
 
-Note the use of the `--dry-run` flag. When this flag is used, the CLI will 
-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 
+Note the use of the `--dry-run` flag. When this flag is used, the CLI will
+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 your application has more than one stack, and you want the `refactor`
@@ -1210,7 +1323,7 @@ command to consider only a subset of them, you can specify the stacks you
 want, both local and deployed:
 
 ```shell
-$ cdk refactor Test* ProdStack --unstable=refactor --dry-run 
+$ cdk refactor Test* ProdStack --unstable=refactor --dry-run
 ```
 
 This is useful if, for example, you have more than one CDK application deployed
@@ -1246,8 +1359,8 @@ Detected ambiguities:
 ```
 
 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: 
+`--override-file=<path>` CLI option. This file should contain a JSON object
+with the following structure:
 
 ```json
 {
@@ -1273,7 +1386,7 @@ that is not already occupied by any resource.
 
 To determine if a resource was moved or renamed, the CLI computes a digest
 for each resource, both in the deployed stacks and in the local stacks, and
-then compares the digests. 
+then compares the digests.
 
 Conceptually, the digest is computed as:
 
@@ -1281,19 +1394,19 @@ Conceptually, the digest is computed as:
 digest(resource) = hash(type + properties + dependencies.map(d))
 ```
 
-where hash is a cryptographic hash function. In other words, the digest of a 
-resource is computed from its type, its own properties (that is, excluding 
-properties that refer to other resources), and the digests of each of its 
-dependencies. The digest of a resource, defined recursively this way, remains 
-stable even if one or more of its dependencies gets renamed. Since the 
-resources in a CloudFormation template form a directed acyclic graph, this 
+where hash is a cryptographic hash function. In other words, the digest of a
+resource is computed from its type, its own properties (that is, excluding
+properties that refer to other resources), and the digests of each of its
+dependencies. The digest of a resource, defined recursively this way, remains
+stable even if one or more of its dependencies gets renamed. Since the
+resources in a CloudFormation template form a directed acyclic graph, this
 function is well-defined.
 
 Resources that have the same digest, but different locations, are considered to be
 the same resource, and therefore to have been moved or renamed.
 
 #### Limitations
-- A refactor cannot leave a stack empty. This is a CloudFormation API limitation, 
+- A refactor cannot leave a stack empty. This is a CloudFormation API limitation,
   that also applies to deployments.
 - Creation of new stacks during a refactor is not supported. If you need to
   create a new stack, do it in a separate deployment, previous to refactoring.
@@ -1318,7 +1431,7 @@ option.
 
 ```console
 $ # Detect drift against the currently-deployed stack with the verbose flag enabled
-$ cdk drift --verbose 
+$ cdk drift --verbose
 ```
 
 ### `cdk cli-telemetry`
@@ -1345,7 +1458,7 @@ that can be set in many different ways (such as `~/.cdk.json`).
 $ # Check the current status of telemetry
 $ cdk cli-telemetry --status
 ```
-### `cdk flags` 
+### `cdk flags`
 
 View and modify your feature flag configurations.
 
@@ -1369,7 +1482,7 @@ Alternatively, you can also run `cdk flags --all` to see a report of all feature
 3. flags that are not configured at all
 
 ```shell
-$ cdk flags --unstable=flags --all 
+$ cdk flags --unstable=flags --all
     Feature Flag                              Recommended                  User
     @aws-cdk/...                              true                         true
   * @aws-cdk/...                              true                         false
@@ -1394,7 +1507,7 @@ $ cdk flags --unstable=flags --set --recommended --all
     [~] AWS::S3::Bucket MyBucket
     └─ [~] Properties
         └─ [~] Encryption
-                ... 
+                ...
     Number of stacks with differences: 2
   Do you want to accept these changes? (y/n) y
   Resynthesizing...
@@ -1429,7 +1542,7 @@ $ cdk flags --unstable=flags --set --default --unconfigured
   * @aws-cdk/...                              true                         <unset>
   * @aws-cdk/...                              true                         <unset>
   Synthesizing...
-  
+
   Do you want to accept these changes? (y/n) y
   Resynthesizing...
 ```
@@ -1438,7 +1551,7 @@ $ cdk flags --unstable=flags --set --default --unconfigured
 
 #### View more information about a flag
 
-Besides running `cdk flags` and `cdk flags --all` to view your feature flag configuration, you can also utilize `cdk flags "#FLAGNAME#"` to inspect a specific feature flag and find out what a specific flag does. This can be helpful in cases where you want to understand a particular flag and its impact on your application. 
+Besides running `cdk flags` and `cdk flags --all` to view your feature flag configuration, you can also utilize `cdk flags "#FLAGNAME#"` to inspect a specific feature flag and find out what a specific flag does. This can be helpful in cases where you want to understand a particular flag and its impact on your application.
 
 ```shell
 $ cdk flags --unstable=flags "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021"
@@ -1449,7 +1562,7 @@ $ cdk flags --unstable=flags "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1
 
 #### Filter flags by substring
 
-You can also run `cdk flags #substring#` to view all matching feature flags. If there is only one feature flag that matches that substring, specific details will be displayed. 
+You can also run `cdk flags #substring#` to view all matching feature flags. If there is only one feature flag that matches that substring, specific details will be displayed.
 
 ```shell
 $ cdk flags --unstable=flags ebs
@@ -1486,7 +1599,7 @@ $ cdk flags --unstable=flags--set "@aws-cdk/aws-cloudfront:defaultSecurityPolicy
                     - ...
     Number of stacks with differences: 2
   Do you want to accept these changes? (y/n) y
-  Resynthesizing...   
+  Resynthesizing...
 ```
 
 ## Global Options