Skip to content

Commit 6245c41

Browse files
9pace9pace
committed
docs: first cdk deploy flowchart
1 parent 75b8256 commit 6245c41

File tree

1 file changed

+181
-0
lines changed

1 file changed

+181
-0
lines changed

‎packages/aws-cdk/README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -567,6 +567,187 @@ and might have breaking changes in the future.
567567

568568
> *: `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.
569569
570+
#### Understanding the Deploy Process
571+
572+
The `cdk deploy` command follows a multi-phase process to deploy your infrastructure. This flowchart provides a high-level overview of the deployment process:
573+
574+
```mermaid
575+
graph TD
576+
%% Initialization Phase
577+
c1["Start: cdk deploy command"]
578+
c2["Parse CLI Arguments & Load Configuration"]
579+
c3["Initialize CDK Toolkit"]
580+
581+
%% Stack Selection Phase
582+
c4["Select Target Stacks"]
583+
c5["Validate Stack Selection"]
584+
585+
%% Synthesis Phase
586+
c6["Synthesis Phase"]
587+
c7{"Missing AWS Context?"}
588+
c8["Fetch Context from AWS"]
589+
c9["Execute CDK Application"]
590+
c10["Generate Cloud Assembly"]
591+
592+
%% Asset Processing Phase
593+
c11["Asset Processing Phase"]
594+
c12["Analyze Asset Dependencies"]
595+
c13["Build Assets in Parallel"]
596+
c14["Publish Assets in Parallel"]
597+
598+
%% Deployment Preparation Phase
599+
c15["Deployment Preparation"]
600+
c16["Check Security Approval Requirements"]
601+
c17{"Approval Required?"}
602+
c18["Request User Approval"]
603+
604+
%% Deployment Method Selection
605+
c19{"Deployment Method Selection"}
606+
c20["Hotswap Deployment"]
607+
c21["CloudFormation Deployment"]
608+
609+
%% Hotswap Path
610+
c22["Identify Hotswappable Resources"]
611+
c23["Update Resources Directly via AWS APIs"]
612+
613+
%% CloudFormation Path
614+
c24["Create/Update CloudFormation Stack"]
615+
c25["Monitor Stack Progress"]
616+
c26["Wait for Stack Completion"]
617+
618+
%% Completion Phase
619+
c27["Collect Stack Outputs"]
620+
c28["Report Deployment Status"]
621+
c29["End: Deployment Complete"]
622+
623+
%% Main Flow
624+
c1 --> c2
625+
c2 --> c3
626+
c3 --> c4
627+
c4 --> c5
628+
c5 --> c6
629+
630+
%% Synthesis Phase with Context Loop
631+
c6 --> c7
632+
c7 -->|"Yes"| c8
633+
c8 --> c9
634+
c9 --> c10
635+
c10 -->|"Loop if more context needed"| c7
636+
c7 -->|"No"| c11
637+
638+
%% Asset Processing Phase
639+
c11 --> c12
640+
c12 --> c13
641+
c13 --> c14
642+
c14 --> c15
643+
644+
%% Deployment Preparation
645+
c15 --> c16
646+
c16 --> c17
647+
c17 -->|"Yes"| c18
648+
c17 -->|"No"| c19
649+
c18 --> c19
650+
651+
%% Deployment Method Selection
652+
c19 -->|"Hotswap Available"| c20
653+
c19 -->|"Standard Deployment"| c21
654+
655+
%% Hotswap Path
656+
c20 --> c22
657+
c22 --> c23
658+
c23 --> c27
659+
660+
%% CloudFormation Path
661+
c21 --> c24
662+
c24 --> c25
663+
c25 --> c26
664+
c26 --> c27
665+
666+
%% Completion
667+
c27 --> c28
668+
c28 --> c29
669+
670+
%% Phase-based Color Coding
671+
%% Initialization Phase (Light Gray)
672+
style c1 fill:#f5f5f5,stroke:#757575,stroke-width:2px
673+
style c2 fill:#f5f5f5,stroke:#757575,stroke-width:2px
674+
style c3 fill:#f5f5f5,stroke:#757575,stroke-width:2px
675+
676+
%% Stack Selection Phase (Light Cyan)
677+
style c4 fill:#e0f7fa,stroke:#00838f,stroke-width:2px
678+
style c5 fill:#e0f7fa,stroke:#00838f,stroke-width:2px
679+
680+
%% Synthesis Phase (Light Blue)
681+
style c6 fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
682+
style c7 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
683+
style c8 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
684+
style c9 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
685+
style c10 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
686+
687+
%% Asset Processing Phase (Light Purple)
688+
style c11 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:3px
689+
style c12 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
690+
style c13 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
691+
style c14 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
692+
693+
%% Deployment Preparation (Light Yellow)
694+
style c15 fill:#fffde7,stroke:#f57f17,stroke-width:2px
695+
style c16 fill:#fffde7,stroke:#f57f17,stroke-width:2px
696+
style c17 fill:#fffde7,stroke:#f57f17,stroke-width:2px
697+
style c18 fill:#fffde7,stroke:#f57f17,stroke-width:2px
698+
699+
%% Deployment Method Selection (Light Amber)
700+
style c19 fill:#fff8e1,stroke:#ff6f00,stroke-width:2px
701+
702+
%% Hotswap Deployment (Light Green)
703+
style c20 fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px
704+
style c22 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
705+
style c23 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
706+
707+
%% CloudFormation Deployment (Light Red)
708+
style c21 fill:#ffebee,stroke:#c62828,stroke-width:3px
709+
style c24 fill:#ffebee,stroke:#c62828,stroke-width:2px
710+
style c25 fill:#ffebee,stroke:#c62828,stroke-width:2px
711+
style c26 fill:#ffebee,stroke:#c62828,stroke-width:2px
712+
713+
%% Completion Phase (Light Teal)
714+
style c27 fill:#e0f2f1,stroke:#00695c,stroke-width:2px
715+
style c28 fill:#e0f2f1,stroke:#00695c,stroke-width:2px
716+
style c29 fill:#e0f2f1,stroke:#00695c,stroke-width:2px
717+
718+
%% Legend at Bottom
719+
subgraph Legend[" "]
720+
direction LR
721+
L1["Initialization"]
722+
L2["Stack Selection"]
723+
L3["Synthesis"]
724+
L4["Asset Processing"]
725+
L5["Deployment Prep"]
726+
L6["Hotswap"]
727+
L7["CloudFormation"]
728+
L8["Completion"]
729+
730+
style L1 fill:#f5f5f5,stroke:#757575,stroke-width:2px
731+
style L2 fill:#e0f7fa,stroke:#00838f,stroke-width:2px
732+
style L3 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
733+
style L4 fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
734+
style L5 fill:#fffde7,stroke:#f57f17,stroke-width:2px
735+
style L6 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
736+
style L7 fill:#ffebee,stroke:#c62828,stroke-width:2px
737+
style L8 fill:#e0f2f1,stroke:#00695c,stroke-width:2px
738+
end
739+
```
740+
741+
**Key Phases:**
742+
743+
- **Synthesis Phase** (light blue): Converts your CDK code into CloudFormation templates. May iterate multiple times if AWS context information (like VPC IDs or availability zones) needs to be fetched.
744+
745+
- **Asset Processing Phase** (light purple): Builds and publishes assets (Docker images, Lambda code, files) in parallel to improve performance.
746+
747+
- **Hotswap Deployment** (light green): Fast deployment path that updates resources directly via AWS APIs, skipping CloudFormation. Only available for certain resource types when using `--hotswap` flag.
748+
749+
- **CloudFormation Deployment** (light red): Standard deployment path that uses CloudFormation change sets for full change tracking and rollback capabilities.
750+
570751
### `cdk rollback`
571752

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

0 commit comments

Comments
 (0)