AWS CDK has a lot of surprising concepts. I've added some of my favorites.

By “favorites,” I mean the ones I still run into periodically and get caught and surprised by. Even after years of developing CDK applications and libraries.

1. CDK library or app do not deploy resources: it only generates definitions. Cloudformation deploys them from the stacks CDK generates.

2. Moreover, CDK library or app do not call Cloudformation either - the CDK CLI or CDK Pipelines (Codepipline) do

3. CDK CLI can not deploy anything directly by default - it has first upload artifacts somewhere (S3, ECR registry)

4. value lookups (ssm.StringParameter.valueFromLookup) do not run during deployment - CDK makes these calls during synthesizing

5. ... unless you use method like StringParameter.valueForStringParameter - which Cloudformation resolves during deployment

6. all compute logic to define resources runs "client side" (const bucket = this.prefix + props.env) - the deployment usually gets Cloudformation template with computed tokens

7. "Stack" construct is to list _what_ resources to create; the "Construct" is what defines _how_ to create them

8. the "id" in each construct is not the name of AWS resource. Rather, the "name", "resourceName" and similar props is what defines custom names

9. CDK app does not destroy stacks removed from the App, CDK CLI command "destroy stackNameXyz" is what calls Cloudformation destroy

10. application will cache results in cdk.context.json without updating on subsequent runs. Have to use CDK CLI to clear cache (cdk context --clear) and then app refreshes values

Quite a list!

Most of these surprises are due to the fact the CDK apps and libraries are distributed in nature. There are multiple steps and multiple locations for CDK application to function: writing resources, local lookups, bootstrapping, assets uploads, Cloudformation calls...

The core functionality is pretty standard: define, synthesize, upload, deploy.

Try this to remember core functions Dogs Swim Upstream Daily.

And now you will not forget what CDK Top Dogs do daily