Background
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.
Basics
Before we dive in, let’s just make sure we’ve got the basics covered
cdk ls
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
cdk synth $STACK_NAME >1.yaml
is your friend, a debugging tool. It shows the generated CloudFormation.
cdk.out directory
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)Build
with nameSynth
(a CodeBuild project that runscdk synth
)Build
with nameSelfMutate
(a CodeBuild project that runscdk deploy
to update the pipeline)Build
with nameFileAsset1
(a CodeBuild project that runscdk-assets publish
). From reading sources: there might be severalcdk-assets publish
commands 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
useChangeSets
):- CHANGE_SET_REPLACE
- CHANGE_SET_EXECUTE
cdk-assets
“It will take the assets listed in the manifest, prepare them as required and upload them to the locations indicated in the manifest.”
Note that 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-assets
knows how to zip directories and how to upload files and directories to S3.
(From reading source code) Didn’t see in use but apparentlycdk-assets
can also run an executable to package a file (or directory?). In this case the content-type of the output is assumed to beapplication/zip
. 🤷‍♂️ - Docker images.
cdk-assets
knows 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.out
during 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 esbuild
)
Docker Images
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.
Deploy
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