fix(toolkit-lib): remove deprecated DeployOptions.force in favor of more specific options (#315)

- Rename `force` option to more descriptive `forceDeployment` for
clarity
- Add new `forceAssetPublishing` option to control asset publishing
separately
- Add `orphanFailedResourcesDuringRollback` option for better rollback
control
- Rename `removePublishedAssets` to `removePublishedAssetsFromWorkGraph`
for clarity
- Update tests and implementation to use the new parameter names
- Improve documentation for deployment options

BREAKING CHANGE: The deprecated `force` option on `DeployOptions` has
been removed. The removed option originally caused multiple different
"force" actions. Each action now has a more targeted alternative. To
force a deployment even if the CDK Toolkit has not detected any changes,
use `forceDeployment`. To force re-publishing of previously published
assets, use `forceAssetPublishing`. To force failing resource being
orphaned during a rollback, use `orphanFailedResourcesDuringRollback`.
To implement interactive confirmation of rollbacks during a deployment,
react to the message request with code `CDK_TOOLKIT_I5050` in your
`IoHost`.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Author: mrgrain

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/private/deploy-options.ts

@@ -16,12 +16,11 @@ export interface BaseDeployOptions {
   readonly roleArn?: string;
 
   /**
-   * Always deploy, even if templates are identical.
+   * Deploy even if the deployed template is identical to the one we are about to deploy.
    *
    * @default false
-   * @deprecated the options currently covers multiple different functionalities and will be split out in future
    */
-  readonly force?: boolean;
+  readonly forceDeployment?: boolean;
 
   /**
    * Deployment method
@@ -44,6 +43,21 @@ export interface BaseDeployOptions {
    */
   readonly rollback?: boolean;
 
+  /**
+   * Automatically orphan resources that failed during rollback
+   *
+   * Has no effect if `rollback` is `false`.
+   *
+   * @default false
+   */
+  readonly orphanFailedResourcesDuringRollback?: boolean;
+
+  /**
+   * Force asset publishing even if the assets have not changed
+   * @default false
+   */
+  readonly forceAssetPublishing?: boolean;
+
   /**
    * Reuse the assets with the given asset IDs
    */

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/private/helpers.ts

@@ -27,7 +27,7 @@ export function buildParameterMap(parameters?: Map<string, string | undefined>):
 /**
  * Remove the asset publishing and building from the work graph for assets that are already in place
  */
-export async function removePublishedAssets(graph: WorkGraph, deployments: Deployments, options: DeployOptions) {
+export async function removePublishedAssetsFromWorkGraph(graph: WorkGraph, deployments: Deployments, options: DeployOptions) {
   await graph.removeUnnecessaryAssets(assetNode => deployments.isSingleAssetPublished(assetNode.assetManifest, assetNode.asset, {
     stack: assetNode.parentStack,
     roleArn: options.roleArn,

packages/@aws-cdk/toolkit-lib/lib/toolkit/toolkit.ts

@@ -10,7 +10,7 @@ import { assemblyFromSource } from './private';
 import type { BootstrapEnvironments, BootstrapOptions, BootstrapResult, EnvironmentBootstrapResult } from '../actions/bootstrap';
 import { BootstrapSource } from '../actions/bootstrap';
 import { AssetBuildTime, type DeployOptions } from '../actions/deploy';
-import { type ExtendedDeployOptions, buildParameterMap, createHotswapPropertyOverrides, removePublishedAssets } from '../actions/deploy/private';
+import { type ExtendedDeployOptions, buildParameterMap, createHotswapPropertyOverrides, removePublishedAssetsFromWorkGraph } from '../actions/deploy/private';
 import { type DestroyOptions } from '../actions/destroy';
 import type { ChangeSetDiffOptions, DiffOptions, LocalFileDiffOptions } from '../actions/diff';
 import { DiffMethod } from '../actions/diff';
@@ -479,7 +479,7 @@ export class Toolkit extends CloudAssemblySourceBuilder {
         stack: assetNode.parentStack,
         roleArn: options.roleArn,
         stackName: assetNode.parentStack.stackName,
-        forcePublish: options.force,
+        forcePublish: options.forceAssetPublishing,
       });
       await publishAssetSpan.end();
     };
@@ -575,7 +575,7 @@ export class Toolkit extends CloudAssemblySourceBuilder {
             notificationArns,
             tags,
             deploymentMethod: options.deploymentMethod,
-            force: options.force,
+            forceDeployment: options.forceDeployment,
             parameters: Object.assign({}, parameterMap['*'], parameterMap[stack.stackName]),
             usePreviousParameters: options.parameters?.keepExistingParameters,
             rollback,
@@ -596,22 +596,18 @@ export class Toolkit extends CloudAssemblySourceBuilder {
                 : `Stack is in a paused fail state (${r.status}) and command line arguments do not include "--no-rollback"`;
               const question = `${motivation}. Perform a regular deployment`;
 
-              if (options.force) {
-                await ioHelper.notify(IO.DEFAULT_TOOLKIT_WARN.msg(`${motivation}. Rolling back first (--force).`));
-              } else {
-                const confirmed = await ioHelper.requestResponse(IO.CDK_TOOLKIT_I5050.req(question, {
-                  motivation,
-                  concurrency,
-                }));
-                if (!confirmed) {
-                  throw new ToolkitError('Aborted by user');
-                }
+              const confirmed = await ioHelper.requestResponse(IO.CDK_TOOLKIT_I5050.req(question, {
+                motivation,
+                concurrency,
+              }));
+              if (!confirmed) {
+                throw new ToolkitError('Aborted by user');
               }
 
               // Perform a rollback
               await this._rollback(assembly, action, {
                 stacks: { patterns: [stack.hierarchicalId], strategy: StackSelectionStrategy.PATTERN_MUST_MATCH_SINGLE },
-                orphanFailedResources: options.force,
+                orphanFailedResources: options.orphanFailedResourcesDuringRollback,
               });
 
               // Go around through the 'while' loop again but switch rollback to true.
@@ -623,17 +619,12 @@ export class Toolkit extends CloudAssemblySourceBuilder {
               const motivation = 'Change includes a replacement which cannot be deployed with "--no-rollback"';
               const question = `${motivation}. Perform a regular deployment`;
 
-              // @todo no force here
-              if (options.force) {
-                await ioHelper.notify(IO.DEFAULT_TOOLKIT_WARN.msg(`${motivation}. Proceeding with regular deployment (--force).`));
-              } else {
-                const confirmed = await ioHelper.requestResponse(IO.CDK_TOOLKIT_I5050.req(question, {
-                  motivation,
-                  concurrency,
-                }));
-                if (!confirmed) {
-                  throw new ToolkitError('Aborted by user');
-                }
+              const confirmed = await ioHelper.requestResponse(IO.CDK_TOOLKIT_I5050.req(question, {
+                motivation,
+                concurrency,
+              }));
+              if (!confirmed) {
+                throw new ToolkitError('Aborted by user');
               }
 
               // Go around through the 'while' loop again but switch rollback to true.
@@ -709,8 +700,8 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     const workGraph = new WorkGraphBuilder(ioHelper, prebuildAssets).build(stacksAndTheirAssetManifests);
 
     // Unless we are running with '--force', skip already published assets
-    if (!options.force) {
-      await removePublishedAssets(workGraph, deployments, options);
+    if (!options.forceAssetPublishing) {
+      await removePublishedAssetsFromWorkGraph(workGraph, deployments, options);
     }
 
     const graphConcurrency: Concurrency = {
@@ -891,7 +882,7 @@ export class Toolkit extends CloudAssemblySourceBuilder {
           stack,
           roleArn: options.roleArn,
           toolkitStackName: this.toolkitStackName,
-          force: options.orphanFailedResources,
+          orphanFailedResources: options.orphanFailedResources,
           validateBootstrapStackVersion: options.validateBootstrapStackVersion,
           orphanLogicalIds: options.orphanLogicalIds,
         });

packages/@aws-cdk/toolkit-lib/test/actions/deploy.test.ts

@@ -198,12 +198,12 @@ describe('deploy', () => {
       successfulDeployment();
     });
 
-    test('force: true option is used for asset publishing', async () => {
+    test('forceAssetPublishing: true option is used for asset publishing', async () => {
       const publishSingleAsset = jest.spyOn(awsCdkApi.Deployments.prototype, 'publishSingleAsset').mockImplementation();
 
       const cx = await builderFixture(toolkit, 'stack-with-asset');
       await toolkit.deploy(cx, {
-        force: true,
+        forceAssetPublishing: true,
       });
 
       // THEN

packages/aws-cdk/lib/api/bootstrap/bootstrap-props.ts

@@ -21,7 +21,7 @@ export interface BootstrapEnvironmentOptions {
   readonly toolkitStackName?: string;
   readonly roleArn?: StringWithoutPlaceholders;
   readonly parameters?: BootstrappingParameters;
-  readonly force?: boolean;
+  readonly forceDeployment?: boolean;
 
   /**
    * The source of the bootstrap stack

packages/aws-cdk/lib/api/bootstrap/deploy-bootstrap.ts

@@ -76,7 +76,7 @@ export class BootstrapStack {
     parameters: Record<string, string | undefined>,
     options: Omit<BootstrapEnvironmentOptions, 'parameters'>,
   ): Promise<SuccessfulDeployStackResult> {
-    if (this.currentToolkitInfo.found && !options.force) {
+    if (this.currentToolkitInfo.found && !options.forceDeployment) {
       // Safety checks
       const abortResponse = {
         type: 'did-deploy-stack',
@@ -136,7 +136,7 @@ export class BootstrapStack {
       resolvedEnvironment: this.resolvedEnvironment,
       sdk: this.sdk,
       sdkProvider: this.sdkProvider,
-      force: options.force,
+      forceDeployment: options.forceDeployment,
       roleArn: options.roleArn,
       tags: options.tags,
       deploymentMethod: { method: 'change-set', execute: options.execute },

packages/aws-cdk/lib/api/deployments/deploy-stack.ts

@@ -149,7 +149,7 @@ export interface DeployStackOptions {
    * Deploy even if the deployed template is identical to the one we are about to deploy.
    * @default false
    */
-  readonly force?: boolean;
+  readonly forceDeployment?: boolean;
 
   /**
    * Rollback failed deployments
@@ -414,7 +414,7 @@ class FullCloudFormationDeployment {
         });
       }
 
-      if (this.options.force) {
+      if (this.options.forceDeployment) {
         await this.ioHelper.notify(IO.DEFAULT_TOOLKIT_WARN.msg(
           [
             'You used the --force flag, but CloudFormation reported that the deployment would not make any changes.',
@@ -713,7 +713,7 @@ async function canSkipDeploy(
   await ioHelper.notify(IO.DEFAULT_TOOLKIT_DEBUG.msg(`${deployName}: checking if we can skip deploy`));
 
   // Forced deploy
-  if (deployStackOptions.force) {
+  if (deployStackOptions.forceDeployment) {
     await ioHelper.notify(IO.DEFAULT_TOOLKIT_DEBUG.msg(`${deployName}: forced deployment`));
     return false;
   }

packages/aws-cdk/lib/api/deployments/deployments.ts

@@ -112,7 +112,7 @@ export interface DeployStackOptions {
    * Force deployment, even if the deployed template is identical to the one we are about to deploy.
    * @default false deployment will be skipped if the template is identical
    */
-  readonly force?: boolean;
+  readonly forceDeployment?: boolean;
 
   /**
    * Extra parameters for CloudFormation
@@ -179,9 +179,10 @@ export interface DeployStackOptions {
   /**
    * Whether to deploy if the app contains no stacks.
    *
+   * @deprecated this option seems to be unsed inside deployments
    * @default false
    */
-  ignoreNoStacks?: boolean;
+  readonly ignoreNoStacks?: boolean;
 }
 
 export interface RollbackStackOptions {
@@ -197,20 +198,6 @@ export interface RollbackStackOptions {
    */
   readonly roleArn?: string;
 
-  /**
-   * Don't show stack deployment events, just wait
-   *
-   * @default false
-   */
-  readonly quiet?: boolean;
-
-  /**
-   * Whether we are on a CI system
-   *
-   * @default false
-   */
-  readonly ci?: boolean;
-
   /**
    * Name of the toolkit stack, if not the default name
    *
@@ -219,13 +206,13 @@ export interface RollbackStackOptions {
   readonly toolkitStackName?: string;
 
   /**
-   * Whether to force a rollback or not
+   * Whether to automatically orphan all failed resources during the rollback
    *
-   * Forcing a rollback will orphan all undeletable resources.
+   * This will force a rollback that otherwise would have failed.
    *
    * @default false
    */
-  readonly force?: boolean;
+  readonly orphanFailedResources?: boolean;
 
   /**
    * Orphan the resources with the given logical IDs
@@ -444,7 +431,7 @@ export class Deployments {
       envResources: env.resources,
       tags: options.tags,
       deploymentMethod,
-      force: options.force,
+      forceDeployment: options.forceDeployment,
       parameters: options.parameters,
       usePreviousParameters: options.usePreviousParameters,
       rollback: options.rollback,
@@ -459,7 +446,7 @@ export class Deployments {
 
   public async rollbackStack(options: RollbackStackOptions): Promise<RollbackStackResult> {
     let resourcesToSkip: string[] = options.orphanLogicalIds ?? [];
-    if (options.force && resourcesToSkip.length > 0) {
+    if (options.orphanFailedResources && resourcesToSkip.length > 0) {
       throw new ToolkitError('Cannot combine --force with --orphan');
     }
 
@@ -501,7 +488,7 @@ export class Deployments {
           break;
 
         case RollbackChoice.CONTINUE_UPDATE_ROLLBACK:
-          if (options.force) {
+          if (options.orphanFailedResources) {
             // Find the failed resources from the deployment and automatically skip them
             // (Using deployment log because we definitely have `DescribeStackEvents` permissions, and we might not have
             // `DescribeStackResources` permissions).
@@ -569,7 +556,7 @@ export class Deployments {
       }
 
       // Either we need to ignore some resources to continue the rollback, or something went wrong
-      if (finalStackState.stackStatus.rollbackChoice === RollbackChoice.CONTINUE_UPDATE_ROLLBACK && options.force) {
+      if (finalStackState.stackStatus.rollbackChoice === RollbackChoice.CONTINUE_UPDATE_ROLLBACK && options.orphanFailedResources) {
         // Do another loop-de-loop
         continue;
       }

packages/aws-cdk/lib/cli/cdk-toolkit.ts

@@ -487,7 +487,7 @@ export class CdkToolkit {
             execute: options.execute,
             changeSetName: options.changeSetName,
             deploymentMethod: options.deploymentMethod,
-            force: options.force,
+            forceDeployment: options.force,
             parameters: Object.assign({}, parameterMap['*'], parameterMap[stack.stackName]),
             usePreviousParameters: options.usePreviousParameters,
             rollback,
@@ -670,7 +670,7 @@ export class CdkToolkit {
           stack,
           roleArn: options.roleArn,
           toolkitStackName: options.toolkitStackName,
-          force: options.force,
+          orphanFailedResources: options.force,
           validateBootstrapStackVersion: options.validateBootstrapStackVersion,
           orphanLogicalIds: options.orphanLogicalIds,
         });

packages/aws-cdk/lib/cli/cli.ts

@@ -295,7 +295,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
         return cli.bootstrap(args.ENVIRONMENTS, {
           source,
           roleArn: args.roleArn,
-          force: argv.force,
+          forceDeployment: argv.force,
           toolkitStackName: toolkitStackName,
           execute: args.execute,
           tags: configuration.settings.get(['tags']),

packages/aws-cdk/test/api/deployments/cloudformation-deployments.test.ts

@@ -932,7 +932,7 @@ test('rollback stack fails in UPDATE_COMPLETE state', async () => {
   expect(response.notInRollbackableState).toBe(true);
 });
 
-test('continue rollback stack with force ignores any failed resources', async () => {
+test('continue rollback stack with orphanFailedResources ignores any failed resources', async () => {
   // GIVEN
   givenStacks({
     '*': { template: {}, stackStatus: 'UPDATE_ROLLBACK_FAILED' },
@@ -954,7 +954,7 @@ test('continue rollback stack with force ignores any failed resources', async ()
   await deployments.rollbackStack({
     stack: testStack({ stackName: 'boop' }),
     validateBootstrapStackVersion: false,
-    force: true,
+    orphanFailedResources: true,
   });
 
   // THEN