Skip to content

Commit e73de14

Browse files
9pace9pace
committed
docs(aws-cdk): move detailed deploy architecture to new file
1 parent 73e4fd3 commit e73de14

File tree

2 files changed

+196
-193
lines changed

2 files changed

+196
-193
lines changed

‎packages/aws-cdk/README.md‎

Lines changed: 2 additions & 193 deletions
Original file line numberDiff line numberDiff line change
@@ -570,9 +570,8 @@ and might have breaking changes in the future.
570570

571571
##### Deploy flowchart
572572

573-
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.
574-
575-
This flowchart provides a high-level overview of the deployment architecture and key decision points:
573+
This flowchart provides a high-level overview of the deployment architecture and key decision points.
574+
For technical implementation details (function calls, file locations), see [docs/deploy-architecture.md](./docs/deploy-architecture.md).
576575

577576
```mermaid
578577
graph TD
@@ -702,196 +701,6 @@ graph LR
702701
style L7 fill:#e0f2f1,stroke:#00695c,stroke-width:2px
703702
```
704703

705-
##### Technical Implementation Details
706-
707-
For contributors debugging or modifying the deploy command, this technical flowchart shows the exact function calls and file locations in the execution path.
708-
709-
```mermaid
710-
graph TD
711-
%% CLI Entry Point
712-
n1["cdk deploy<br/>(User Command)"]
713-
n2["cli.ts: exec()"]
714-
n3["cli.ts: main()"]
715-
716-
%% Deploy Method
717-
n4["cdk-toolkit.ts: CdkToolkit.deploy()"]
718-
n5["cdk-toolkit.ts: selectStacksForDeploy()"]
719-
n6["Check if synthesis needed"]
720-
721-
%% Synthesis Process
722-
n7["cloud-executable.ts: doSynthesize()"]
723-
n29{"Context missing?"}
724-
n34["cloud-executable.ts: synthesizer()"]
725-
n9["cli.ts: execProgram()"]
726-
n10["childProcess.spawn()<br/>(Run CDK App)"]
727-
n11["CDK App Process Started"]
728-
n35["CDK App: app.synth()"]
729-
n36["@aws-cdk/core: synthesize()<br/>Generate CloudFormation JSON"]
730-
n12["Write templates to cdk.out/"]
731-
n13["Return CloudAssembly object"]
732-
733-
%% Stack Selection
734-
n14["cloud-assembly.ts:<br/>assembly.selectStacks()"]
735-
n15["cloud-assembly.ts:<br/>validateStacks()"]
736-
n16["Return StackCollection"]
737-
738-
%% Asset Processing
739-
n17["cdk-toolkit.ts:<br/>ResourceMigrator.tryMigrateResources()"]
740-
n18["work-graph.ts:<br/>WorkGraphBuilder.build()"]
741-
n37["work-graph.ts:<br/>analyzeDeploymentOrder()"]
742-
n19["work-graph.ts:<br/>workGraph.doParallel()"]
743-
744-
%% Parallel Execution Nodes
745-
n20["asset-build.ts: buildAsset()<br/>(Sequential: concurrency=1)"]
746-
n21["asset-publishing.ts: publishAsset()<br/>(Parallel: concurrency=8)"]
747-
n44["deploy-stack.ts: deployStack()<br/>(Parallel: configurable)"]
748-
n45["await Promise.all()<br/>Wait for dependencies"]
749-
750-
%% Deployment Process
751-
n22["cdk-toolkit.ts: deployStack()"]
752-
n23["deploy-stack.ts:<br/>CloudFormationStack.lookup()"]
753-
n24["deploy-stack.ts:<br/>makeBodyParameter()"]
754-
n25["deploy-stack.ts:<br/>publishAssets()"]
755-
n38["deploy-stack.ts:<br/>requireApproval()"]
756-
757-
%% Hotswap Decision
758-
n30{"--hotswap flag set?"}
759-
n31["hotswap-deployments.ts:<br/>tryHotswapDeployment()"]
760-
761-
%% Standard CloudFormation Deployment
762-
n26["deploy-stack.ts:<br/>FullCloudFormationDeployment.performDeployment()"]
763-
n27["AWS SDK: CloudFormation<br/>createChangeSet() OR<br/>updateStack()"]
764-
n28["CloudFormation Service"]
765-
n32["deploy-stack.ts:<br/>StackActivityMonitor.start()"]
766-
n33["deploy-stack.ts:<br/>waitForStackDeploy()"]
767-
768-
%% Completion
769-
n39["deploy-stack.ts:<br/>getStackOutputs()"]
770-
n40["cdk-toolkit.ts:<br/>printStackOutputs()"]
771-
772-
%% Main Flow Connections
773-
n1 --> n2
774-
n2 --> n3
775-
n3 --> n4
776-
n4 --> n5
777-
n5 --> n6
778-
n6 --> n7
779-
n7 --> n29
780-
n29 -->|"Yes"| n34
781-
n34 --> n9
782-
n9 --> n10
783-
n10 --> n11
784-
n11 --> n35
785-
n35 --> n36
786-
n36 --> n12
787-
n12 --> n13
788-
n13 -->|"Loop if context missing"| n29
789-
n29 -->|"No"| n14
790-
n14 --> n15
791-
n15 --> n16
792-
n16 --> n17
793-
n17 --> n18
794-
n18 --> n37
795-
n37 --> n19
796-
797-
%% Parallel execution from workGraph.doParallel()
798-
n19 -.->|"Parallel"| n20
799-
n19 -.->|"Parallel"| n21
800-
n19 -.->|"Parallel"| n44
801-
802-
%% Dependency relationships
803-
n20 --> n45
804-
n21 --> n45
805-
n44 --> n45
806-
n45 --> n22
807-
n22 --> n23
808-
n23 --> n24
809-
n24 --> n25
810-
n25 --> n38
811-
n38 --> n30
812-
n30 -->|"Yes"| n31
813-
n30 -->|"No"| n26
814-
n31 --> n39
815-
n26 --> n27
816-
n27 --> n28
817-
n28 --> n32
818-
n32 --> n33
819-
n33 --> n39
820-
n39 --> n40
821-
822-
%% Simplified Color Scheme - Only 3 colors
823-
%% External Systems (Light Red)
824-
style n1 fill:#ffebee,stroke:#c62828,stroke-width:2px
825-
style n28 fill:#ffebee,stroke:#c62828,stroke-width:2px
826-
827-
%% CDK App Process (Light Green)
828-
style n10 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
829-
style n11 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
830-
style n35 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
831-
style n36 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
832-
style n12 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
833-
834-
%% Decision Points (Light Yellow)
835-
style n29 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
836-
style n30 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
837-
style n38 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
838-
style n45 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
839-
840-
%% Everything else - CDK CLI Code (Light Blue)
841-
style n2 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
842-
style n3 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
843-
style n4 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
844-
style n5 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
845-
style n6 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
846-
style n7 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
847-
style n9 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
848-
style n13 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
849-
style n14 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
850-
style n15 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
851-
style n16 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
852-
style n17 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
853-
style n18 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
854-
style n19 fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
855-
style n20 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
856-
style n21 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
857-
style n22 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
858-
style n23 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
859-
style n24 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
860-
style n25 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
861-
style n26 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
862-
style n27 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
863-
style n31 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
864-
style n32 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
865-
style n33 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
866-
style n34 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
867-
style n37 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
868-
style n39 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
869-
style n40 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
870-
style n44 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
871-
872-
```
873-
874-
**Legend (Node Categories):**
875-
```mermaid
876-
graph LR
877-
L1["External Systems"]~~~L2["CDK App Process"]~~~L3["CDK CLI Code"]~~~L4["Decision Points"]
878-
879-
style L1 fill:#ffebee,stroke:#c62828,stroke-width:2px
880-
style L2 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
881-
style L3 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
882-
style L4 fill:#fff9c4,stroke:#f57f17,stroke-width:2px
883-
```
884-
885-
**Parallel Execution Model:**
886-
887-
The deploy process uses a sophisticated work graph (`workGraph.doParallel()` in `work-graph.ts`) to manage parallel execution:
888-
889-
- **Asset Building** (concurrency: 1): Compiles Docker images, Lambda code, etc. sequentially to avoid overwhelming system resources
890-
- **Asset Publishing** (concurrency: 8): Uploads assets to S3/ECR in parallel for faster deployment
891-
- **Stack Deployment** (configurable): Deploys multiple stacks in parallel while respecting dependencies
892-
893-
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).
894-
895704
### `cdk rollback`
896705

897706
If a deployment performed using `cdk deploy --no-rollback` fails, your

0 commit comments

Comments
 (0)