Hotswap Deployments
Relevant source files
The following files were used as context for generating this wiki page:
Hotswap deployments are a feature of the AWS CDK designed to accelerate development cycles by attempting to perform faster, short-circuit deployments. When possible, this mechanism bypasses AWS CloudFormation and updates AWS resources directly. This is achieved by passing the --hotswap flag to the cdk deploy command. If a change does not support hotswapping, the tool automatically falls back to a full CloudFormation deployment.
This feature deliberately introduces drift in CloudFormation stacks to speed up deployments. Consequently, it should only be used for development purposes and never for production deployments. Hotswapping is considered an experimental feature.
Sources: packages/aws-cdk/README.md, packages/aws-cdk/lib/api/hotswap-deployments.ts:1-13
Hotswap Process Flow
The hotswap deployment process is initiated by the tryHotswapDeployment function. It determines if a set of stack changes can be deployed directly via AWS SDK calls instead of through a full CloudFormation update.
The process is as follows:
- The current deployed CloudFormation template is fetched.
- A diff is performed between the current template and the newly synthesized template from the CDK app.
- The system evaluates all resource differences to determine if they are "hotswappable".
- If all changes are hotswappable, the system applies them directly using the AWS SDK. A
DeployStackResultis returned, indicating success. - If any change is not hotswappable, the function returns
undefined, signaling that a standard CloudFormation deployment must be performed.
Sources: packages/aws-cdk/lib/api/hotswap-deployments.ts:15-32
This diagram illustrates the decision flow within the tryHotswapDeployment function.
Identifying Hotswappable Changes
The core of the hotswap mechanism is its ability to identify which changes can be safely applied outside of CloudFormation. This is handled by the findAllHotswappableChanges function, which iterates through every resource difference identified by cfn_diff.diffTemplate.
For each resource change, a series of checks are performed to determine its hotswap eligibility. Currently, the primary supported hotswap change is for AWS Lambda function code assets.
Sources: packages/aws-cdk/lib/api/hotswap-deployments.ts:59-75
Change Hotswap Impact
Each resource change is categorized with a ChangeHotswapImpact level. This determines the subsequent action.
| Impact Level | Description |
|---|---|
REQUIRES_FULL_DEPLOYMENT | The change is not hotswappable and requires a full CloudFormation deployment. This immediately stops the hotswap attempt. |
IRRELEVANT | The change does not affect the deployment in a way that requires a hotswap action (e.g., metadata changes). |
HotswapOperation (object) | The change is hotswappable, and an operation object is returned that contains the logic to apply the change. |
Sources: packages/aws-cdk/lib/api/hotswap/common.ts:11-18, packages/aws-cdk/lib/api/hotswap-deployments.ts:66-73
Hotswappable Lambda Functions
A change to an AWS::Lambda::Function resource is considered hotswappable if the only modification is to its code asset. The function isHotswappableLambdaFunctionChange in lambda-functions.ts implements this logic.
It specifically checks for changes to the Code.S3Bucket and Code.S3Key properties that correspond to a CDK asset parameter. If these are the only changes, it returns a LambdaFunctionHotswapOperation object. Any other change to the Lambda function's properties will result in REQUIRES_FULL_DEPLOYMENT.
Sources: packages/aws-cdk/lib/api/hotswap/lambda-functions.ts:12-32
Applying Hotswap Changes
If all changes are determined to be hotswappable, the applyAllHotswappableChanges function executes them. It takes the list of HotswapOperation objects and calls the apply() method on each one.
Sources: packages/aws-cdk/lib/api/hotswap-deployments.ts:77-85
HotswapOperation Interface
The HotswapOperation is a core abstraction that encapsulates the logic for a specific hotswap action.
This class diagram shows the structure of the HotswapOperation interface and its implementation for Lambda functions.
The apply() method of the LambdaFunctionHotswapOperation performs the following steps:
- Determines the physical name of the Lambda function. It first checks if the name is hardcoded in the template; otherwise, it uses the
LazyListStackResourcesutility to look up the physical ID from the deployed stack. - Calls the
updateFunctionCodemethod of the AWS Lambda SDK with the new S3 bucket and key for the code asset.
Sources: packages/aws-cdk/lib/api/hotswap/lambda-functions.ts:50-70
Resource Discovery with LazyListStackResources
To apply changes, the physical ID of a resource is often needed. The LazyListStackResources class provides an optimized way to fetch resource information for a stack. It caches the results of the listStackResources API call, ensuring the potentially expensive operation is only performed once per deployment, and only if needed.
Sources: packages/aws-cdk/lib/api/hotswap-deployments.ts:87-110
This sequence diagram shows the process of applying a Lambda function hotswap change.