You use AWS CDK. It’s great. It does a lot for you. Then one day something goes wrong. OK, it didn’t happen yet. But you want to be prepared for that (at least to some extent). The following information is what I have found when I was preparing. Sharing to hopefully save the reader some time.
Before we dive in, let’s just make sure we’ve got the basics covered
cdk ls lists all the stacks in the app, including the pipeline.
Example from my test project:
$ cdk ls Proj1Stack Proj1Stack/Deploy1/LambdaStack1 Proj1Stack/Deploy2/LambdaStack1
- Proj1Stack is the pipeline.
- Deploy1 and Deploy2 are “stages”
cdk synth $STACK_NAME >1.yaml is your friend, a debugging tool. It shows the generated CloudFormation.
cdk.out is the directory where
cdk synth outputs everything that’s need for deploying (CloudFormation templates, related assets, metadata). They call it Cloud Assembly.
All assets are named based on the hash of their content so they are unique and immutable.
How the Generated Pipeline Looks Like?
When you use an opinionated pipeline, you can see the following generated CodePipeline actions:
Source(with long hash as output artifact name)
Synth(a CodeBuild project that runs
SelfMutate(a CodeBuild project that runs
cdk deployto update the pipeline)
FileAsset1(a CodeBuild project that runs
cdk-assets publish). From reading sources: there might be several
cdk-assets publishcommands configured in the CodeBuild project.
- Then two CloudFormation deploy actions per each “stage” you want to deploy to (usage of change sets is the default but can be disabled as per documentation, see
“It will take the assets listed in the manifest, prepare them as required and upload them to the locations indicated in the manifest.”
cdk-assets is not making any decisions; metadata in the
cdk.out directory has the information about assets, how to build/transform them and where they go.
cdk-assets can only handle two types of assets:
- files (including directories).
cdk-assetsknows how to zip directories and how to upload files and directories to S3.
(From reading source code) Didn’t see in use but apparently
cdk-assetscan also run an executable to package a file (or directory?). In this case the content-type of the output is assumed to be
- Docker images.
cdk-assetsknows how to build Docker images and push them into registry.
Sample command to see the list of assets:
npx cdk-assets ls -p cdk.out/Proj1Stack.assets.json
What is Built When?
Files – unprocessed
If the files/directories don’t need any processing, they are just copied over to
cdk synth and given a name which is a hash of the contents.
Example: Lambda function code
Files – processed
The processing happens during the
cdk synth so that
cdk.out contains already processed assets.
Example: Node.JS Lambda function code (processed by
tsc (optionally) and
cdk-assets builds a docker image and pushes it into the specified repository. The input for the build of the image is a directory in
cdk.out which has the
Dockerfile and related files.
After everything was built and uploaded during
cdk synth and
cdk-assets, the deploy uses CloudFormation template (templates?) from the
cdk.out directory. At this point the assets (which the template references) are in ECR and S3.
- I tried to condense the information that deemed important.
- Let me know if something is missing or if you see mistakes.
- The plan is to update this post as I discover new information.
- My mistakes so far
- Started taking notes quite a few hours into the process instead of from the start. Especially it would save me the jumping between the pipeline and the build projects to re-check what each action does.
- Editing this post tired
- Last edit: 2023-01-20