Skip to content

CDK Constructs: Abstraction with Liability

If you publish a CDK construct, you’re not shipping a helper function but operational decisions – about defaults, upgrade paths and what ends up in the consumer’s CloudFormation template.

≈ 10 min readSoftwareAWSCloud

CDK Constructs: Abstraction with Liability

An abstraction you import is responsibility you hand off – that is the unspoken assumption when a team pulls its first ready-made CDK construct into its project. Three lines of code, one cdk deploy, and the S3 bucket, CloudFront distribution and bucket policy are in place. After all, someone else has thought through the details.

I think exactly this assumption is wrong, and in both directions. If you use a construct, you don’t hand off responsibility – you import someone else’s decisions into your own CloudFormation template, onto your own AWS bill and into your own attack surface. And if you publish a construct, you haven’t simply shared code – from now on you are liable for defaults, for upgrade paths and for everything that ends up in other people’s production. A construct is abstraction with liability. That sets it apart from almost everything else I get from npm.

Three levels, three different promises#

The CDK sorts its building blocks into three levels, and the liability question arises differently on each. L1 constructs (CfnBucket, CfnDistribution) are generated one-to-one mappings of the CloudFormation resources. They promise nothing except completeness: every property, no default, no opinion. L2 constructs (s3.Bucket, lambda.Function) are handwritten wrappers with an opinion – sensible defaults, convenience methods like grantRead, automatically wired IAM policies. Finally, L3 constructs, also called patterns in CDK parlance, wire several services together into a domain building block: “static website with a CDN”, “API with Lambda and DynamoDB”.

The higher the level, the bigger the promise – and the bigger the liability. An L1 construct can hardly surprise me, because it decides nothing. An L3 construct decides almost everything, and I can’t tell from the code. That is exactly why L3 constructs are so tempting: they read like domain concepts (“a website”, “an API”) and hide the fact that underneath lies a bundle of very concrete operational decisions. What really happens only shows up in synthesis:

flowchart LR
  L3[L3: StaticSite<br/>own pattern] --> L2[L2: s3.Bucket<br/>CloudFrontWebDistribution]
  L2 --> L1[L1: CfnBucket<br/>CfnDistribution]
  L1 --> SYNTH[cdk synth]
  SYNTH --> TPL[CloudFormation template<br/>several hundred lines]
  TPL --> DEPLOY[cdk deploy]
  DEPLOY --> RES[real resources:<br/>cost, permissions, attack surface]

The arrow on the far right is where a construct differs from a library function. A function from lodash produces an array at runtime. A construct produces a CloudFront distribution that costs money, a bucket that may or may not be public, and IAM statements that allow someone to do something. If map has a bug, a test fails. If a construct has a bug, a bucket lies open on the internet or a removal policy deletes production data when the stack is torn down. That’s no reason to do without abstraction – but it is a reason to treat it differently.

A construct of my own and its uncomfortable decisions#

This really became clear to me when I built a small construct myself: a static website in S3, delivered via CloudFront. It was the third or fourth handwritten stack of this kind around me, always the same sixty lines, so extracting it was the obvious move. The first draft was done quickly. Things got interesting with the questions the first draft left open.

import { Construct, RemovalPolicy } from '@aws-cdk/core';
import * as s3 from '@aws-cdk/aws-s3';
import * as cloudfront from '@aws-cdk/aws-cloudfront';
import * as deployment from '@aws-cdk/aws-s3-deployment';

export interface StaticSiteProps {
  readonly sourcePath: string;
  readonly retainBucket?: boolean;
}

export class StaticSite extends Construct {
  public readonly siteBucket: s3.Bucket;
  public readonly distribution: cloudfront.CloudFrontWebDistribution;

  constructor(scope: Construct, id: string, props: StaticSiteProps) {
    super(scope, id);

    const originAccessIdentity = new cloudfront.OriginAccessIdentity(
      this,
      'OriginAccessIdentity'
    );

    this.siteBucket = new s3.Bucket(this, 'SiteBucket', {
      encryption: s3.BucketEncryption.S3_MANAGED,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      removalPolicy: props.retainBucket
        ? RemovalPolicy.RETAIN
        : RemovalPolicy.DESTROY,
    });
    this.siteBucket.grantRead(originAccessIdentity);

    this.distribution = new cloudfront.CloudFrontWebDistribution(this, 'Distribution', {
      originConfigs: [
        {
          s3OriginSource: {
            s3BucketSource: this.siteBucket,
            originAccessIdentity,
          },
          behaviors: [{ isDefaultBehavior: true }],
        },
      ],
    });

    new deployment.BucketDeployment(this, 'DeploySite', {
      sources: [deployment.Source.asset(props.sourcePath)],
      destinationBucket: this.siteBucket,
      distribution: this.distribution,
    });
  }
}

Each of these lines is an operational decision I make for all future users. The bucket is not public but only reachable through the Origin Access Identity – that is the right decision, but it isn’t a given: the bare s3.Bucket from the CDK still sets no public access block to this day if you don’t specify one. Encryption is turned on, even though the content of a public website strictly speaking doesn’t need it – because nobody should have to discuss later why this particular bucket is unencrypted. And the removal policy defaults to DESTROY.

I thought longest about this last default. The CDK itself retains buckets when a stack is torn down (RETAIN), because a bucket with content can’t simply be deleted and because data loss is the most expensive of all errors. For a website construct whose bucket content is regenerated from the build on every deployment, however, RETAIN is the wrong protection: it leaves an orphaned bucket behind for every test stack torn down, and after three months nobody knows which of them can go. So DESTROY as the default and retainBucket as the way out for cases where the bucket does contain more than build artifacts. Maybe that’s the wrong trade-off – but it now sits in one line of interface definition and can therefore be discussed. Before, it was hidden, unspoken, in sixty lines of copied stack code.

The two public readonly fields are just as deliberate. A construct that hides its inner resources forces its users to fork at the first special case. If you need to get at the CfnDistribution, you can reach it via this.distribution.node.defaultChild and use addPropertyOverride to override anything my abstraction didn’t anticipate:

const cfnDistribution = site.distribution.node
  .defaultChild as cloudfront.CfnDistribution;

cfnDistribution.addPropertyOverride(
  'DistributionConfig.ViewerCertificate.MinimumProtocolVersion',
  'TLSv1.2_2019'
);

These escape hatches are not a blemish on the abstraction but part of the contract. In infrastructure, an abstraction without a way out is a dead end, and you only ever notice dead ends once you’re already standing in one.

cdk synth is the test of truth#

For the other side of liability – the consumer’s – there is a tool I consider more important than any documentation: synthesis. cdk synth writes out the CloudFormation template that results from the whole construct tree. The template doesn’t lie. It contains every resource, every policy, every default that any construct has set anywhere.

npm install @aws-cdk/aws-s3@1.57.0 @aws-cdk/aws-cloudfront@1.57.0

cdk synth StaticSiteStack > synthesized.yaml

# what did the abstraction actually decide for me?
grep -A 6 'PublicAccessBlockConfiguration' synthesized.yaml
grep -B 2 'DeletionPolicy' synthesized.yaml

# and before every deployment: what changes against reality?
cdk diff StaticSiteStack

Before I use someone else’s construct, I build a minimal example, synthesize and read. Not the whole template line by line – but specifically the places where other people’s defaults become expensive or dangerous. That takes half an hour and has paid off every time so far: once I found a CloudFront price class this way that delivered worldwide where Europe would have been enough; another time a log configuration that was simply missing, which would only have been noticed at the first incident. A pattern with three lines of application code easily produces several hundred lines of template, and somewhere in there are the answers to the questions the README doesn’t answer:

  • Which IAM statements are created, and do they contain wildcards I didn’t order?
  • Which resources cost money continuously, even when nobody uses the system?
  • What is publicly reachable, what is encrypted, what has which DeletionPolicy?
  • Which properties can I change through the interface – and for which do I need the escape hatch on day one?

This spring, AWS launched its own library of such patterns with the Solutions Constructs: vetted two-service combinations such as CloudFront in front of API Gateway in front of Lambda, with defaults along the Well-Architected Framework. I have read some of them, used a few, and find the source code especially instructive – there you see how many lines of default logic it takes for “CloudFront plus S3” to be wired really sensibly, including the details that are regularly missing from handwritten stacks. That is exactly the value of someone else’s L3 abstraction: not that I no longer need to know anything, but that someone has already made and written down the decisions I can hold my own up against. I already looked at how such checks can be automated instead of depending on discipline in Policy as Code for CDK – for me, synthesis and rule checking now belong together.

What the author owes#

That leaves the question of what you take on when you publish yourself. After half a year with my own construct and quite a few others I’ve read, I have a provisional list, and it is longer than I realized when I extracted the first sixty lines.

First there are the defaults, about which everything has already been said above – with the addition that a published default is practically impossible to change. If you tighten it, you break existing deployments; if you loosen it, you make existing users less secure without them noticing. A default is a promise with a very long term.

Then the upgrade paths. The CDK currently ships a new version almost weekly, we’re at 1.5x, and modules like CloudFront still carry the experimental stamp, so they may change in minor releases. A construct I publish spans this movement: my users raise their CDK version and expect my construct to come along. Peer dependencies on the right @aws-cdk packages, prompt releases after upstream changes, a changelog that mentions template changes – that is not a bonus, that is half the work. And because the CDK also generates Python, Java and .NET bindings via jsii, the shape of the API alone (no TypeScript specialties that jsii can’t represent) decides whom I can reach as users at all.

Then there are tests, and on the right level. Unit tests against your own TypeScript logic check only half the truth; what I’m liable for is the template. With @aws-cdk/assert, you can pin down both – individual assertions (expect(stack).to(haveResource('AWS::S3::Bucket', { PublicAccessBlockConfiguration: … }))) for the decisions that must never flip, and a snapshot of the entire synthesized template so that every change in the output becomes visible in review rather than at the user’s end. Since I started doing this, I’ve caught two upstream changes before they reached a release – both would have changed the template without a single line of my code changing.

And finally the template output itself. Logical IDs in the template are derived from the construct path; if you rename or move children while refactoring your construct, you change the IDs – and CloudFormation then replaces resources instead of updating them. For a CloudFront distribution that means half an hour of waiting; for a bucket with data, an incident. That’s why for me cdk diff against a deployed example stack comes before every release of the construct, for the same reason it comes before every deployment. Since July, CDK Pipelines (Developer Preview) has offered a building block that pulls such checks into a self-mutating deployment pipeline – still fresh, but the direction is right: delivering a construct is infrastructure too and wants to be treated as such.

Bottom line#

A little over a year ago, I wrote about what changes when infrastructure becomes a programming language. Constructs are the continuation of that: if infrastructure is code, it also takes on the properties of code – reuse, packaging, versioning. Only the cost of errors remains that of infrastructure.

That’s why I think both comfortable attitudes are wrong. “I write everything myself, then I know what’s in it” doesn’t scale and reproduces the same forgotten details in every stack. “I take the ready-made pattern, then I don’t have to understand it” mistakes abstraction for absolution. What works for me lies in between: L3 abstractions, yes, including your own – but read before use, synthesized before trust, and, when publishing, with the awareness that from now on you share in decisions about other people’s production environments. A construct is not a snippet. It is a contract about defaults, ways out and upgrade paths, and cdk synth is the document in which this contract is written in black and white.

Further reading#

Revised and translated from German with the help of AI.