Skip to content

docs(aws-cdk): technical and conceptual flowcharts for deploy #920

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(aws-cdk): technical and conceptual flowcharts for deploy #920

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6245c41
docs: first cdk deploy flowchart
9pace Oct 20, 2025
73e4fd3
docs(aws-cdk): technical and conceptual flowcharts for deploy
9pace Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
325 changes: 325 additions & 0 deletions packages/aws-cdk/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -567,6 +567,331 @@ and might have breaking changes in the future.

> *: `Fn::GetAtt` is only partially supported. Refer to [this implementation](https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/lib/api/cloudformation/evaluate-cloudformation-template.ts#L256-L266) for supported resources and attributes.


##### Deploy flowchart

The following diagrams illustrate the CDK deployment process at two levels of detail. The first diagram provides a conceptual overview suitable for understanding the high-level flow, while the second diagram shows the technical implementation details for contributors working on the CDK codebase.

This flowchart provides a high-level overview of the deployment architecture and key decision points:

```mermaid
graph TD
%% Initialization Phase
c1["Initialize Deployment"]

%% Stack Selection Phase
c4["Determine Which Stacks to Deploy"]
c5["Order Stacks by Dependencies"]

%% Synthesis Phase
c6["Synthesis Phase"]
c7{"Need AWS Account Info?<br/>(VPCs, Zones, AMIs)"}
c8["Query AWS & Cache to<br/>cdk.context.json"]
c9["Run Your CDK Code"]
c10["Generate CloudFormation Templates"]

%% Asset Processing Phase
c11["Asset Processing Phase"]
c13["Package Assets<br/>(Lambda code, Docker images)"]
c14["Upload to S3 & ECR"]

%% Deployment Method Selection
c19{"Fast Deploy Available?<br/>(--hotswap flag set?)"}
c20["Fast Deployment Path"]
c21["Standard Deployment Path"]

%% Hotswap Path
c22["Identify Resources to Update"]
c23["Update Resources Directly<br/>(Skip CloudFormation)"]

%% CloudFormation Path
c25["Deploy via CloudFormation"]
c27["Monitor Progress & Wait for Completion"]

%% Completion Phase
c29["Collect Outputs & Report Status"]
c30["End: Deployment Complete"]

%% Main Flow
c1 --> c4
c4 --> c5
c5 --> c6

%% Synthesis Phase with Context Loop
c6 --> c7
c7 -->|"Yes"| c8
c8 --> c9
c9 --> c10
c10 -->|"Loop if context missing<br/>(can repeat multiple times)"| c7
c7 -->|"No"| c11

%% Asset Processing Phase
c11 --> c13
c13 --> c14
c14 --> c19

%% Deployment Method Selection
c19 -->|"Yes: Fast Deploy"| c20
c19 -->|"No: Standard Deploy"| c21

%% Hotswap Path
c20 --> c22
c22 --> c23
c23 --> c29

%% CloudFormation Path
c21 --> c25
c25 --> c27
c27 --> c29

%% Completion
c29 --> c30

%% Phase-based Color Coding
%% Initialization Phase (Light Gray)
style c1 fill:#f5f5f5,stroke:#757575,stroke-width:2px

%% Stack Selection Phase (Light Cyan)
style c4 fill:#e0f7fa,stroke:#00838f,stroke-width:2px
style c5 fill:#e0f7fa,stroke:#00838f,stroke-width:2px

%% Synthesis Phase (Light Blue)
style c6 fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
style c7 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style c8 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style c9 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style c10 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px

%% Asset Processing Phase (Light Purple)
style c11 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:3px
style c13 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
style c14 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px

%% Deployment Method Selection (Light Amber)
style c19 fill:#fff8e1,stroke:#ff6f00,stroke-width:2px

%% Hotswap Deployment (Light Green)
style c20 fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px
style c22 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
style c23 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

%% CloudFormation Deployment (Light Red)
style c21 fill:#ffebee,stroke:#c62828,stroke-width:3px
style c25 fill:#ffebee,stroke:#c62828,stroke-width:2px
style c27 fill:#ffebee,stroke:#c62828,stroke-width:2px

%% Completion Phase (Light Teal)
style c29 fill:#e0f2f1,stroke:#00695c,stroke-width:2px
style c30 fill:#e0f2f1,stroke:#00695c,stroke-width:2px
```

**Legend:**
```mermaid
graph LR
L1["Initialization"] --> L2["Stack Selection"] --> L3["Synthesis"] --> L4["Asset Processing"] --> L5["Fast Deploy"]
L4 --> L6["Standard Deploy"]
L5 --> L7["Completion"]
L6 --> L7

style L1 fill:#f5f5f5,stroke:#757575,stroke-width:2px
style L2 fill:#e0f7fa,stroke:#00838f,stroke-width:2px
style L3 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style L4 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
style L5 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
style L6 fill:#ffebee,stroke:#c62828,stroke-width:2px
style L7 fill:#e0f2f1,stroke:#00695c,stroke-width:2px
```

##### Technical Implementation Details

For contributors debugging or modifying the deploy command, this technical flowchart shows the exact function calls and file locations in the execution path.

```mermaid
graph TD
%% CLI Entry Point
n1["cdk deploy<br/>(User Command)"]
n2["cli.ts: exec()"]
n3["cli.ts: main()"]

%% Deploy Method
n4["cdk-toolkit.ts: CdkToolkit.deploy()"]
n5["cdk-toolkit.ts: selectStacksForDeploy()"]
n6["Check if synthesis needed"]

%% Synthesis Process
n7["cloud-executable.ts: doSynthesize()"]
n29{"Context missing?"}
n34["cloud-executable.ts: synthesizer()"]
n9["cli.ts: execProgram()"]
n10["childProcess.spawn()<br/>(Run CDK App)"]
n11["CDK App Process Started"]
n35["CDK App: app.synth()"]
n36["@aws-cdk/core: synthesize()<br/>Generate CloudFormation JSON"]
n12["Write templates to cdk.out/"]
n13["Return CloudAssembly object"]

%% Stack Selection
n14["cloud-assembly.ts:<br/>assembly.selectStacks()"]
n15["cloud-assembly.ts:<br/>validateStacks()"]
n16["Return StackCollection"]

%% Asset Processing
n17["cdk-toolkit.ts:<br/>ResourceMigrator.tryMigrateResources()"]
n18["work-graph.ts:<br/>WorkGraphBuilder.build()"]
n37["work-graph.ts:<br/>analyzeDeploymentOrder()"]
n19["work-graph.ts:<br/>workGraph.doParallel()"]

%% Parallel Execution Nodes
n20["asset-build.ts: buildAsset()<br/>(Sequential: concurrency=1)"]
n21["asset-publishing.ts: publishAsset()<br/>(Parallel: concurrency=8)"]
n44["deploy-stack.ts: deployStack()<br/>(Parallel: configurable)"]
n45["await Promise.all()<br/>Wait for dependencies"]

%% Deployment Process
n22["cdk-toolkit.ts: deployStack()"]
n23["deploy-stack.ts:<br/>CloudFormationStack.lookup()"]
n24["deploy-stack.ts:<br/>makeBodyParameter()"]
n25["deploy-stack.ts:<br/>publishAssets()"]
n38["deploy-stack.ts:<br/>requireApproval()"]

%% Hotswap Decision
n30{"--hotswap flag set?"}
n31["hotswap-deployments.ts:<br/>tryHotswapDeployment()"]

%% Standard CloudFormation Deployment
n26["deploy-stack.ts:<br/>FullCloudFormationDeployment.performDeployment()"]
n27["AWS SDK: CloudFormation<br/>createChangeSet() OR<br/>updateStack()"]
n28["CloudFormation Service"]
n32["deploy-stack.ts:<br/>StackActivityMonitor.start()"]
n33["deploy-stack.ts:<br/>waitForStackDeploy()"]

%% Completion
n39["deploy-stack.ts:<br/>getStackOutputs()"]
n40["cdk-toolkit.ts:<br/>printStackOutputs()"]

%% Main Flow Connections
n1 --> n2
n2 --> n3
n3 --> n4
n4 --> n5
n5 --> n6
n6 --> n7
n7 --> n29
n29 -->|"Yes"| n34
n34 --> n9
n9 --> n10
n10 --> n11
n11 --> n35
n35 --> n36
n36 --> n12
n12 --> n13
n13 -->|"Loop if context missing"| n29
n29 -->|"No"| n14
n14 --> n15
n15 --> n16
n16 --> n17
n17 --> n18
n18 --> n37
n37 --> n19

%% Parallel execution from workGraph.doParallel()
n19 -.->|"Parallel"| n20
n19 -.->|"Parallel"| n21
n19 -.->|"Parallel"| n44

%% Dependency relationships
n20 --> n45
n21 --> n45
n44 --> n45
n45 --> n22
n22 --> n23
n23 --> n24
n24 --> n25
n25 --> n38
n38 --> n30
n30 -->|"Yes"| n31
n30 -->|"No"| n26
n31 --> n39
n26 --> n27
n27 --> n28
n28 --> n32
n32 --> n33
n33 --> n39
n39 --> n40

%% Simplified Color Scheme - Only 3 colors
%% External Systems (Light Red)
style n1 fill:#ffebee,stroke:#c62828,stroke-width:2px
style n28 fill:#ffebee,stroke:#c62828,stroke-width:2px

%% CDK App Process (Light Green)
style n10 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
style n11 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
style n35 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
style n36 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
style n12 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

%% Decision Points (Light Yellow)
style n29 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
style n30 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
style n38 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
style n45 fill:#fff9c4,stroke:#f57f17,stroke-width:2px

%% Everything else - CDK CLI Code (Light Blue)
style n2 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n3 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n4 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n5 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n6 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n7 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n9 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n13 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n14 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n15 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n16 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n17 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n18 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n19 fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
style n20 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n21 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n22 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n23 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n24 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n25 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n26 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n27 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n31 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n32 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n33 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n34 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n37 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n39 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n40 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style n44 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px

```

**Legend (Node Categories):**
```mermaid
graph LR
L1["External Systems"]~~~L2["CDK App Process"]~~~L3["CDK CLI Code"]~~~L4["Decision Points"]

style L1 fill:#ffebee,stroke:#c62828,stroke-width:2px
style L2 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
style L3 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style L4 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
```

**Parallel Execution Model:**

The deploy process uses a sophisticated work graph (`workGraph.doParallel()` in `work-graph.ts`) to manage parallel execution:

- **Asset Building** (concurrency: 1): Compiles Docker images, Lambda code, etc. sequentially to avoid overwhelming system resources
- **Asset Publishing** (concurrency: 8): Uploads assets to S3/ECR in parallel for faster deployment
- **Stack Deployment** (configurable): Deploys multiple stacks in parallel while respecting dependencies

The dotted lines indicate parallel execution paths from the work graph orchestrator. All operations respect dependency relationships before proceeding (node n45 represents the synchronization point).

### `cdk rollback`

If a deployment performed using `cdk deploy --no-rollback` fails, your
Expand Down
Loading