refactor(toolkit-lib)!: hotswap is now a deployment method

Author: mrgrain

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

@@ -1,19 +1,19 @@
 import type { BaseDeployOptions } from './private/deploy-options';
 import type { Tag } from '../../api/tags';
 
-export type DeploymentMethod = DirectDeploymentMethod | ChangeSetDeploymentMethod;
+export type DeploymentMethod = DirectDeployment | ChangeSetDeployment | HotswapDeployment;
 
-export interface DirectDeploymentMethod {
-  /**
-   * Use stack APIs to the deploy stack changes
-   */
+/**
+ * Use stack APIs to the deploy stack changes
+ */
+export interface DirectDeployment {
   readonly method: 'direct';
 }
 
-export interface ChangeSetDeploymentMethod {
-  /**
-   * Use change-set APIS to deploy a stack changes
-   */
+/**
+ * Use change-set APIs to deploy a stack changes
+ */
+export interface ChangeSetDeployment {
   readonly method: 'change-set';
 
   /**
@@ -37,6 +37,31 @@ export interface ChangeSetDeploymentMethod {
   readonly importExistingResources?: boolean;
 }
 
+/**
+ * Perform a 'hotswap' deployment to deploy a stack changes
+ *
+ * A 'hotswap' deployment will attempt to short-circuit CloudFormation
+ * and update the affected resources like Lambda functions directly.
+ */
+export interface HotswapDeployment {
+  readonly method: 'hotswap';
+
+  /**
+   * Represents configuration property overrides for hotswap deployments.
+   * Currently only supported by ECS.
+   *
+   * @default - no overrides
+   */
+  readonly properties?: HotswapProperties;
+
+  /**
+   * Fall back to a CloudFormation deployment when a non-hotswappable change is detected
+   *
+   * @default - do not fall back to a CloudFormation deployment
+   */
+  readonly fallback?: DirectDeployment | ChangeSetDeployment;
+}
+
 /**
  * When to build assets
  */
@@ -55,23 +80,6 @@ export enum AssetBuildTime {
   JUST_IN_TIME = 'just-in-time',
 }
 
-export enum HotswapMode {
-  /**
-   * Will fall back to CloudFormation when a non-hotswappable change is detected
-   */
-  FALL_BACK = 'fall-back',
-
-  /**
-   * Will not fall back to CloudFormation when a non-hotswappable change is detected
-   */
-  HOTSWAP_ONLY = 'hotswap-only',
-
-  /**
-   * Will not attempt to hotswap anything and instead go straight to CloudFormation
-   */
-  FULL_DEPLOYMENT = 'full-deployment',
-}
-
 export class StackParameters {
   /**
    * Use only existing parameters on the stack.
@@ -143,14 +151,6 @@ export interface DeployOptions extends BaseDeployOptions {
    * @default AssetBuildTime.ALL_BEFORE_DEPLOY
    */
   readonly assetBuildTime?: AssetBuildTime;
-
-  /**
-   * Represents configuration property overrides for hotswap deployments.
-   * Currently only supported by ECS.
-   *
-   * @default - no overrides
-   */
-  readonly hotswapProperties?: HotswapProperties;
 }
 
 /**

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

@@ -1,4 +1,4 @@
-import type { DeploymentMethod, DeployOptions, HotswapMode } from '..';
+import type { DeploymentMethod, DeployOptions } from '..';
 import type { StackSelector } from '../../../api/cloud-assembly';
 import type { CloudWatchLogEventMonitor } from '../../../api/logs-monitor/logs-monitor';
 
@@ -24,17 +24,10 @@ export interface BaseDeployOptions {
 
   /**
    * Deployment method
-   */
-  readonly deploymentMethod?: DeploymentMethod;
-
-  /**
-   * Whether to perform a 'hotswap' deployment.
-   * A 'hotswap' deployment will attempt to short-circuit CloudFormation
-   * and update the affected resources like Lambda functions directly.
    *
-   * @default - no hotswap
+   * @default ChangeSetDeployment
    */
-  readonly hotswap?: HotswapMode;
+  readonly deploymentMethod?: DeploymentMethod;
 
   /**
    * Rollback failed deployments

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

@@ -1,6 +1,5 @@
-import type { DeployOptions, HotswapProperties } from '..';
+import type { DeployOptions } from '..';
 import type { Deployments } from '../../../api/deployments';
-import { EcsHotswapProperties, HotswapPropertyOverrides } from '../../../api/hotswap';
 import type { WorkGraph } from '../../../api/work-graph';
 
 export function buildParameterMap(parameters?: Map<string, string | undefined>): { [name: string]: { [name: string]: string | undefined } } {
@@ -35,13 +34,3 @@ export async function removePublishedAssetsFromWorkGraph(graph: WorkGraph, deplo
     stackName: assetNode.parentStack.stackName,
   }));
 }
-
-/**
- * Create the HotswapPropertyOverrides class out of the Interface exposed to users
- */
-export function createHotswapPropertyOverrides(hotswapProperties: HotswapProperties): HotswapPropertyOverrides {
-  return new HotswapPropertyOverrides(new EcsHotswapProperties(
-    hotswapProperties.ecs?.minimumHealthyPercent,
-    hotswapProperties.ecs?.maximumHealthyPercent,
-  ));
-}

packages/@aws-cdk/toolkit-lib/lib/actions/watch/index.ts

@@ -1,3 +1,4 @@
+import type { DeploymentMethod } from '../deploy';
 import type { BaseDeployOptions } from '../deploy/private';
 
 export interface WatchOptions extends BaseDeployOptions {
@@ -21,4 +22,11 @@ export interface WatchOptions extends BaseDeployOptions {
    * @default process.cwd()
    */
   readonly watchDir?: string;
+
+  /**
+   * Deployment method
+   *
+   * @default HotswapDeployment
+   */
+  readonly deploymentMethod?: DeploymentMethod;
 }

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

@@ -26,14 +26,14 @@ import {
 } from './cfn-api';
 import { determineAllowCrossAccountAssetPublishing } from './checks';
 import type { DeployStackResult, SuccessfulDeployStackResult } from './deployment-result';
-import type { ChangeSetDeploymentMethod, DeploymentMethod } from '../../actions/deploy';
+import type { ChangeSetDeployment, DeploymentMethod, DirectDeployment } from '../../actions/deploy';
 import { ToolkitError } from '../../toolkit/toolkit-error';
 import { formatErrorMessage } from '../../util';
 import type { SDK, SdkProvider, ICloudFormationClient } from '../aws-auth/private';
 import type { TemplateBodyParameter } from '../cloudformation';
 import { makeBodyParameter, CfnEvaluationException, CloudFormationStack } from '../cloudformation';
 import type { EnvironmentResources, StringWithoutPlaceholders } from '../environment';
-import { HotswapMode, HotswapPropertyOverrides, ICON } from '../hotswap/common';
+import { HotswapPropertyOverrides, HotswapMode, ICON, createHotswapPropertyOverrides } from '../hotswap/common';
 import { tryHotswapDeployment } from '../hotswap/hotswap-deployments';
 import { IO, type IoHelper } from '../io/private';
 import type { ResourcesToImport } from '../resource-import';
@@ -158,17 +158,21 @@ export interface DeployStackOptions {
    */
   readonly rollback?: boolean;
 
-  /*
+  /**
    * Whether to perform a 'hotswap' deployment.
    * A 'hotswap' deployment will attempt to short-circuit CloudFormation
    * and update the affected resources like Lambda functions directly.
    *
    * @default - `HotswapMode.FULL_DEPLOYMENT` for regular deployments, `HotswapMode.HOTSWAP_ONLY` for 'watch' deployments
+   *
+   * @deprecated  Use 'deploymentMethod' instead
    */
   readonly hotswap?: HotswapMode;
 
   /**
    * Extra properties that configure hotswap behavior
+   *
+   * @deprecated Use 'deploymentMethod' instead
    */
   readonly hotswapPropertyOverrides?: HotswapPropertyOverrides;
 
@@ -202,9 +206,31 @@ export interface DeployStackOptions {
 
 export async function deployStack(options: DeployStackOptions, ioHelper: IoHelper): Promise<DeployStackResult> {
   const stackArtifact = options.stack;
-
   const stackEnv = options.resolvedEnvironment;
 
+  let deploymentMethod = options.deploymentMethod ?? { method: 'change-set' };
+  // Honour old hotswap option
+  // @TODO remove when we don't care about this export anymore
+  if (options.hotswap && deploymentMethod?.method !== 'hotswap') {
+    switch (options.hotswap) {
+      case HotswapMode.HOTSWAP_ONLY:
+        deploymentMethod = {
+          method: 'hotswap',
+          properties: options.hotswapPropertyOverrides,
+        };
+        break;
+      case HotswapMode.FALL_BACK:
+        deploymentMethod = {
+          method: 'hotswap',
+          properties: options.hotswapPropertyOverrides,
+          fallback: deploymentMethod,
+        };
+        break;
+      case HotswapMode.FULL_DEPLOYMENT:
+        break;
+    }
+  }
+
   options.sdk.appendCustomUserAgent(options.extraUserAgent);
   const cfn = options.sdk.cloudFormation();
   const deployName = options.deployName || stackArtifact.stackName;
@@ -246,14 +272,11 @@ export async function deployStack(options: DeployStackOptions, ioHelper: IoHelpe
     ? templateParams.updateExisting(finalParameterValues, cloudFormationStack.parameters)
     : templateParams.supplyAll(finalParameterValues);
 
-  const hotswapMode = options.hotswap ?? HotswapMode.FULL_DEPLOYMENT;
-  const hotswapPropertyOverrides = options.hotswapPropertyOverrides ?? new HotswapPropertyOverrides();
-
   if (await canSkipDeploy(options, cloudFormationStack, stackParams.hasChanges(cloudFormationStack.parameters), ioHelper)) {
     await ioHelper.notify(IO.DEFAULT_TOOLKIT_DEBUG.msg(`${deployName}: skipping deployment (use --force to override)`));
     // if we can skip deployment and we are performing a hotswap, let the user know
     // that no hotswap deployment happened
-    if (hotswapMode !== HotswapMode.FULL_DEPLOYMENT) {
+    if (deploymentMethod?.method === 'hotswap') {
       await ioHelper.notify(IO.DEFAULT_TOOLKIT_INFO.msg(
         format(
           `\n ${ICON} %s\n`,
@@ -290,16 +313,21 @@ export async function deployStack(options: DeployStackOptions, ioHelper: IoHelpe
     allowCrossAccount: await determineAllowCrossAccountAssetPublishing(options.sdk, ioHelper, bootstrapStackName),
   }, ioHelper);
 
-  if (hotswapMode !== HotswapMode.FULL_DEPLOYMENT) {
-    // attempt to short-circuit the deployment if possible
+  // attempt to short-circuit the deployment if possible
+  if (deploymentMethod?.method === 'hotswap') {
     try {
+      const hotswapModeNew = deploymentMethod?.fallback ? 'fall-back' : 'hotswap-only';
+      const hotswapPropertyOverrides = deploymentMethod.properties
+        ? createHotswapPropertyOverrides(deploymentMethod.properties)
+        : new HotswapPropertyOverrides();
+
       const hotswapDeploymentResult = await tryHotswapDeployment(
         options.sdkProvider,
         ioHelper,
         stackParams.values,
         cloudFormationStack,
         stackArtifact,
-        hotswapMode,
+        hotswapModeNew,
         hotswapPropertyOverrides,
       );
 
@@ -321,9 +349,10 @@ export async function deployStack(options: DeployStackOptions, ioHelper: IoHelpe
       )));
     }
 
-    if (hotswapMode === HotswapMode.FALL_BACK) {
+    if (deploymentMethod.fallback) {
       await ioHelper.notify(IO.DEFAULT_TOOLKIT_INFO.msg('Falling back to doing a full deployment'));
       options.sdk.appendCustomUserAgent('cdk-hotswap/fallback');
+      deploymentMethod = deploymentMethod.fallback;
     } else {
       return {
         type: 'did-deploy-stack',
@@ -336,6 +365,7 @@ export async function deployStack(options: DeployStackOptions, ioHelper: IoHelpe
 
   // could not short-circuit the deployment, perform a full CFN deploy instead
   const fullDeployment = new FullCloudFormationDeployment(
+    deploymentMethod,
     options,
     cloudFormationStack,
     stackArtifact,
@@ -364,6 +394,7 @@ class FullCloudFormationDeployment {
   private readonly uuid: string;
 
   constructor(
+    private readonly deploymentMethod: DirectDeployment | ChangeSetDeployment,
     private readonly options: DeployStackOptions,
     private readonly cloudFormationStack: CloudFormationStack,
     private readonly stackArtifact: cxapi.CloudFormationStackArtifact,
@@ -380,9 +411,7 @@ class FullCloudFormationDeployment {
   }
 
   public async performDeployment(): Promise<DeployStackResult> {
-    const deploymentMethod = this.options.deploymentMethod ?? {
-      method: 'change-set',
-    };
+    const deploymentMethod = this.deploymentMethod ?? { method: 'change-set' };
 
     if (deploymentMethod.method === 'direct' && this.options.resourcesToImport) {
       throw new ToolkitError('Importing resources requires a changeset deployment');
@@ -397,7 +426,7 @@ class FullCloudFormationDeployment {
     }
   }
 
-  private async changeSetDeployment(deploymentMethod: ChangeSetDeploymentMethod): Promise<DeployStackResult> {
+  private async changeSetDeployment(deploymentMethod: ChangeSetDeployment): Promise<DeployStackResult> {
     const changeSetName = deploymentMethod.changeSetName ?? 'cdk-deploy-change-set';
     const execute = deploymentMethod.execute ?? true;
     const importExistingResources = deploymentMethod.importExistingResources ?? false;

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

@@ -136,17 +136,21 @@ export interface DeployStackOptions {
    */
   readonly rollback?: boolean;
 
-  /*
+  /**
    * Whether to perform a 'hotswap' deployment.
    * A 'hotswap' deployment will attempt to short-circuit CloudFormation
    * and update the affected resources like Lambda functions directly.
    *
    * @default - `HotswapMode.FULL_DEPLOYMENT` for regular deployments, `HotswapMode.HOTSWAP_ONLY` for 'watch' deployments
+   *
+   * @deprecated Use 'deploymentMethod' instead
    */
   readonly hotswap?: HotswapMode;
 
   /**
    * Properties that configure hotswap behavior
+   *
+   * @deprecated Use 'deploymentMethod' instead
    */
   readonly hotswapPropertyOverrides?: HotswapPropertyOverrides;
 
@@ -395,6 +399,8 @@ export class Deployments {
 
   public async deployStack(options: DeployStackOptions): Promise<DeployStackResult> {
     let deploymentMethod = options.deploymentMethod;
+    // @deprecated changeSetName and execute
+    // @TODO remove when we don't care about this export anymore
     if (options.changeSetName || options.execute !== undefined) {
       if (deploymentMethod) {
         throw new ToolkitError(

packages/@aws-cdk/toolkit-lib/lib/api/hotswap/common.ts

@@ -120,6 +120,17 @@ export class EcsHotswapProperties implements IEcsHotswapProperties {
   }
 }
 
+/**
+ * Create the HotswapPropertyOverrides class out of the Interface exposed to users
+ */
+export function createHotswapPropertyOverrides(props: HotswapProperties): HotswapPropertyOverrides {
+  return new HotswapPropertyOverrides(new EcsHotswapProperties(
+    props.ecs?.minimumHealthyPercent,
+    props.ecs?.maximumHealthyPercent,
+    props.ecs?.stabilizationTimeoutSeconds,
+  ));
+}
+
 type PropDiffs = Record<string, PropertyDifference<any>>;
 
 class ClassifiedChanges {