aws-cdk
Version:
AWS CDK CLI, the command line tool for CDK apps
195 lines (166 loc) • 7.39 kB
Markdown
# Deploy Command Technical Architecture
This document provides technical implementation details for contributors debugging or modifying the `cdk deploy` command. It shows the exact function calls and file locations in the execution path.
For a high-level conceptual overview of the deploy process, see the [README](../README.md#deploy-flowchart).
## Technical Flowchart
```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).