Using AWS CDK constructs with Pulumi
It may still be in beta, but Pulumi's AWS CDK interop certainly works — and it's neat. If you're a fan of CDK, or even if you'd just like to take advantage of one of the many CDK constructs out there on the internet, you'll be happy to learn that it lets you drop CDK constructs right into your Pulumi programs and work with them as though they were regular ol' Pulumi resources.
The blog post announcing the beta is a good place to learn more about how the two-way integration works, but the gist is that by wrapping CDK constructs in a class that inherits from a @pulumi/cdk Stack
, you define the boundary between your CDK "stuff" and the rest of the Pulumi program, and expose properties on that class for whatever CDK-based resources you want to expose to the rest of the program. Deployments happen entirely with Pulumi, too — no CloudFormation in sight — so they're especially fast compared to what you might be used to with CDK and CloudFormation.
Here's a super-simple example showing two S3 buckets, one defined with CDK and the other with Pulumi, in the same program, just to give you an idea how things are typically set up structurally:
import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";
import * as pulumicdk from "@pulumi/cdk";
import * as cdk from "aws-cdk-lib";
// The CDK stack declares and exposes an S3 bucket.
class CDKStack extends pulumicdk.Stack {
bucket: pulumi.Output<string>;
constructor(id: string, options?: pulumicdk.StackOptions) {
super(id, options);
// 1️⃣ Declare a bucket with CDK.
const bucket = new cdk.aws_s3.Bucket(this, "cdk-bucket", {
accessControl: cdk.aws_s3.BucketAccessControl.PUBLIC_READ,
});
// The stack exposes the bucket name as a public property.
this.bucket = this.asOutput(bucket.bucketName);
// The constructor runs CDK synth.
this.synth();
}
}
// Instantiate the CDKStack.
const cdkStack = new CDKStack("cdk-stack");
// 2️⃣ Declare a bucket with @pulumi/aws.
const bucket = new aws.s3.Bucket("pulumi-bucket", {
acl: aws.s3.PublicReadAcl,
});
// 3️⃣ Export both bucket names.
export const cdkBucketName = cdkStack.bucket;
export const pulumiBucketName = bucket.bucket;
Notice the bucket
defined on the CDKStack
class is typed as a pulumi.Output<string>
, and it's set using the class's inherited .asOutput()
method. That bit of Pulumi magic is what lets you use the computed property of the CDK Bucket
instance (here, its name) as a Pulumi output — which in turn can be passed as an input to other Pulumi resources. (And the reverse is also true: You can pass outputs of Pulumi resources to CDK declarations as well.) For example, to add a file to the bucket we declared with CDK above, you'd add these few lines:
// ...
// Add a file to the CDK bucket.
const file = new aws.s3.BucketObject("some-file.txt", {
bucket: cdkStack.bucket, // ⬅️ Where the magic happens.
acl: aws.s3.PublicReadAcl,
content: "Hello, world!",
});
As of now, the integration is only supported in TypeScript, and to use it, you'll need to make sure your AWS account and target region are properly "bootstrapped" first. (CDK constructs require this.) But once you've done so, you should be able to integrate any CDK construct into your program using the same general approach.
Here's another example combining three resources — two declared with AWS CDK and one with Pulumi — to deploy a static website on AWS. The CDK subclass defines a bucket and CloudFront distribution, exposing the bucket and distribution on its public API as Pulumi outputs. The outer Pulumi program uses those outputs to upload files to the bucket using a Synced Folder component and then finishes by exporting the generated CloudFront distribution URL:
import * as pulumi from "@pulumi/pulumi";
import * as pulumicdk from "@pulumi/cdk";
import * as synced from "@pulumi/synced-folder";
import * as cdk from "aws-cdk-lib";
const config = new pulumi.Config();
const path = "./www";
const indexDocument = "index.html";
const errorDocument = "error.html";
// The CDK stack defines an S3 bucket and CloudFront distribution.
class CDKStack extends pulumicdk.Stack {
bucketName: pulumi.Output<string>;
originURL: pulumi.Output<string>;
cdnURL: pulumi.Output<string>;
constructor(id: string, options?: pulumicdk.StackOptions) {
super(id, options);
// Origin bucket.
const bucket = new cdk.aws_s3.Bucket(this, "bucket", {
websiteIndexDocument: indexDocument,
websiteErrorDocument: errorDocument,
accessControl: cdk.aws_s3.BucketAccessControl.PUBLIC_READ,
});
// CloudFront distribution.
const cdn = new cdk.aws_cloudfront.Distribution(this, "cdn", {
defaultRootObject: indexDocument,
defaultBehavior: {
origin: new cdk.aws_cloudfront_origins.S3Origin(bucket),
},
});
// Export the bucket name, bucket URL, and CDN URL as Pulumi outputs.
this.bucketName = this.asOutput(bucket.bucketName);
this.originURL = this.asOutput(bucket.bucketWebsiteUrl);
this.cdnURL = this.asOutput(`https://${cdn.distributionDomainName}`);
this.synth();
}
}
const cdkStack = new CDKStack("cdk-stack");
// Sync a local folder to the bucket exported by the CDK stack.
const folder = new synced.S3BucketFolder("folder", {
bucketName: cdkStack.bucketName,
path: path,
acl: "public-read",
});
// Export the CloudFront URLs.
export const cdnURL = cdkStack.cdnURL;
When you deploy this program with Pulumi — assuming you've got a ./www
folder alongside index.ts
with a few web pages in it — you'll see that in a few minutes, the CloudFront CDN is deployed and the website's ready for browsing:
$ pulumi up
...
Updating (dev)
View Live: https://app.pulumi.com/cnunciato/cdk-test/dev/updates/1
Type Name Status
+ pulumi:pulumi:Stack cdk-test-dev created (267s)
+ ├─ cdk:index:Stack cdk-stack created (0.38s)
+ │ └─ cdk:construct:CDKStack cdk-stack/cdk-stack created (0.51s)
+ │ ├─ cdk:construct:Bucket cdk-stack/cdk-stack/bucket created (0.40s)
+ │ │ └─ aws-native:s3:Bucket bucket43879c71 created (27s)
+ │ └─ cdk:construct:Distribution cdk-stack/cdk-stack/cdn created (0.66s)
+ │ └─ aws-native:cloudfront:Distribution cdnE31FB0B1 created (233s)
+ └─ synced-folder:index:S3BucketFolder folder created (0.76s)
+ ├─ aws:s3:BucketObject index.html created (0.56s)
+ └─ aws:s3:BucketObject error.html created (0.68s)
Outputs:
cdnURL : "https://d22v9g8qsaxm4x.cloudfront.net"
Resources:
+ 10 created
Duration: 4m29s
Neat, right?
Now, I'll admit I haven't spent a ton of time with this stuff yet — and it is still in preview, so I wouldn't be surprised if there were still a few bugs to be found here and there. Also, because it's built on the AWS Native provider (which is itself built on the AWS Cloud Control API), not all AWS resources are available out of the box just yet, so you may need to "map in" a few resources here if you run into those gaps. (Which reminds me — I should probably add an example that covers this as well!) But so far, it definitely works as advertised, so I'm sure I'll be poking around on the Construct Hub in my free time in the weeks ahead.
Hope it helps! You'll find the full code for the example in the book's examples repository on GitHub:
Have fun!
Member discussion