How to use the Ref Intrinsic Function in AWS CDK


Borislav Hadzhiev

Last updated: Apr 14, 2022


Check out my new book

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 ran 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:

import * as s3 from 'aws-cdk-lib/aws-s3'; import * as cdk from 'aws-cdk-lib'; 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 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:

npx aws-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's ref:

// 👇 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:

npx aws-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 #

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.
book cover
You can use the search field on my Home Page to filter through all of my articles.