How to use the Ref Intrinsic Function in AWS CDK

avatar

Borislav Hadzhiev

Sat Apr 24 20213 min read

Updated on Sat Apr 24 2021

Using the Ref Intrinsic Function in AWS CDK #

The Ref intrinsic function in CloudFormation returns the value of a parameter or resource.

Most commonly Ref returns the name of the resource. For example, if we reference an S3 bucket or a Dynamodb table, the value would resolve to the name of the resource.

Before a deployment is executed our CDK code gets compiled down to CloudFormation, so we're able to use the Ref intrinsic function in our CDK code.

In order to use the Ref intrinsic function in CDK we have to access the ref property on a CfnResource.

The code for this article is available on GitHub

To demo using refs, I'll create a simple CDK stack, that consists of a single S3 bucket:

lib/cdk-starter-stack.ts
import * as s3 from '@aws-cdk/aws-s3'; import * as cdk from '@aws-cdk/core'; export class MyCdkStack extends cdk.Stack { constructor(scope: cdk.App, id: string, props: cdk.StackProps) { super(scope, id, props); const s3Bucket = new s3.Bucket(this, 'avatars-bucket', { removalPolicy: cdk.RemovalPolicy.DESTROY, }); const cfnBucket = s3Bucket.node.defaultChild as s3.CfnBucket; // ๐Ÿ‘‡ get the bucket ref const bucketRef1 = cfnBucket.ref; console.log('bucketRef1 ๐Ÿ‘‰', bucketRef1); // ๐Ÿ‘‡ same thing but using the Fn class const bucketRef2 = cdk.Fn.ref(cfnBucket.logicalId); console.log('bucketRef2 ๐Ÿ‘‰', bucketRef2); } }

In the code snippet:

  1. we defined an S3 bucket using the Bucket construct

  2. we got access to the Bucket's CFN resource and casted the type to CfnBucket

  3. now we are able to access the ref property on the CfnBucket. We've then stored the ref in the bucketRef1 variable.

  4. alternatively, we can access the resource's ref by invoking the ref static method on the Fn class. The ref method takes 1 parameter - the logical id of the resource.

I'll now synth the stack to see if the ref values resolved at synthesis time:

shell
npx cdk synth

The output shows that the values are CDK Tokens:

ref tokens

In short, tokens in CDK are encoded values, that will get resolved at deployment time by CloudFormation. This means that we don't have access to the resolved value in our CDK code and we shouldn't use refs in conditional statements.

The Ref value will get resolved, by CloudFormation at deployment time. In order to demo this behavior, I'll provision an Output and set its value to be the bucket ref:

lib/cdk-starter-stack.ts
// ๐Ÿ‘‡ Output with the ref as a value new cdk.CfnOutput(this, 'myBucketRef', { value: bucketRef1, description: 'The name of the s3 bucket', });

If I run cdk synth, the CloudFormation template will get generated in the cdk.out directory:

cdk out ref

We can see that the Ref intrinsic function has been used in the Outputs section of our template.

Next, I'll deploy the CDK stack to see the Ref value resolved in our CloudFormation template:

shell
npx cdk deploy

If I open the CloudFormation console and click on the Outputs section, I can see the Ref value points to the bucket name:

cloudformation resolved ref

Further Reading #

Add me on LinkedIn

I'm a Web Developer with TypeScript, React.js, Node.js and AWS experience.

Let's connect on LinkedIn

Join my newsletter

I'll send you 1 email a week with links to all of the articles I've written that week

Buy Me A Coffee