This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.
In the AWS Cloud Development Kit (AWS CDK), tokens are placeholders for values that aren’t known when defining constructs or synthesizing stacks. These values will be fully resolved at deployment, when your actual infrastructure is created. When developing AWS CDK applications, you will work with tokens to manage these values across your application.
Token example
The following is an example of a CDK stack that defines a construct for an Amazon Simple Storage Service (Amazon S3) bucket. Since the
name of our bucket is not yet known, the value for bucketName is stored as a token:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// Store value of the S3 bucket name
const myBucketName = myBucket.bucketName;
// Print the current value for the S3 bucket name at synthesis
console.log("myBucketName: " + bucketName);
}
}When we run cdk synth to synthesize our stack, the value for myBucketName will be
displayed in the token format of ${Token[TOKEN.. This token format is a
result of how the AWS CDK encodes tokens. In this example, the token is encoded as a string:1234]}
$cdk synth --quietmyBucketName: ${Token[TOKEN.21]}
Since the value for our bucket name is not known at synthesis, the token is rendered as
myBucket. Our AWS CloudFormation template uses the <unique-hash>Ref
intrinsic function to reference its value, which will be known at deployment:
Resources:
myBucket5AF9C99B:
# ...
Outputs:
bucketNameOutput:
Description: The name of the S3 bucket
Value:
Ref: myBucket5AF9C99BFor more information on how the unique hash is generated, see Generated logical IDs in your AWS CloudFormation template.
Passing tokens
Tokens can be passed around as if they were the actual value they represent. The following is an example that passes the token for our bucket name to a construct for an AWS Lambda function:
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Define a Lambda function
const myFunction = new lambda.Function(this, "myFunction", {
runtime: lambda.Runtime.NODEJS_20_X,
handler: "index.handler",
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
functionName: myBucketName + "Function", // Pass token for the S3 bucket name
environment: {
BUCKET_NAME: myBucketName, // Pass token for the S3 bucket name
}
});
}
}When we synthesize our template, the Ref and Fn::Join intrinsic functions are used to
specify the values, which will be known at deployment:
Resources:
myBucket5AF9C99B:
Type: AWS::S3::Bucket
# ...
myFunction884E1557:
Type: AWS::Lambda::Function
Properties:
# ...
Environment:
Variables:
BUCKET_NAME:
Ref: myBucket5AF9C99B
FunctionName:
Fn::Join:
- ""
- - Ref: myBucket5AF9C99B
- Function
# ...How token encodings work
Tokens are objects that implement the IResolvable interface, which contains a
single resolve method. During synthesis, the AWS CDK calls this method to produce the final value for tokens
in your CloudFormation template.
Note
You'll rarely work directly with the IResolvable interface. You will most likely only see
string-encoded versions of tokens.
Token encoding types
Tokens participate in the synthesis process to produce arbitrary values of any type. Other functions typically
only accept arguments of basic types, such as string or number. To use tokens in these
cases, you can encode them into one of three types by using static methods on the cdk.Token class.
-
Token.asStringto generate a string encoding (or call.toString()on the token object). -
Token.asListto generate a list encoding. -
Token.asNumberto generate a numeric encoding.
These take an arbitrary value, which can be an IResolvable, and encode them into a primitive value
of the indicated type.
Important
Because any one of the previous types can potentially be an encoded token, be careful when you parse or try to read their contents. For example, if you attempt to parse a string to extract a value from it, and the string is an encoded token, your parsing fails. Similarly, if you try to query the length of an array or perform math operations with a number, you must first verify that they aren't encoded tokens.
How to check for tokens in your app
To check whether a value has an unresolved token in it, call the Token.isUnresolved (Python:
is_unresolved) method. The following is an example that checks if the value for our Amazon S3 bucket name is
a token. If its not a token, we then validate the length of the bucket name:
// ...
export class CdkDemoAppStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
// Define an S3 bucket
const myBucket = new s3.Bucket(this, 'myBucket');
// ...
// Check if bucket name is a token. If not, check if length is less than 10 characters
if (cdk.Token.isUnresolved(myBucketName)) {
console.log("Token identified.");
} else if (!cdk.Token.isUnresolved(myBucketName) && myBucketName.length > 10) {
throw new Error('Maximum length for name is 10 characters.');
};
// ...When we run cdk synth, myBucketName is identified as a token:
$cdk synth --quietToken identified.
Note
You can use token encodings to escape the type system. For example, you could string-encode a token that produces a number value at synthesis time. If you use these functions, it's your responsibility to make sure that your template resolves to a usable state after synthesis.
Working with string-encoded tokens
String-encoded tokens look like the following.
${TOKEN[Bucket.Name.1234]}
They can be passed around like regular strings, and can be concatenated, as shown in the following example.
const functionName = bucket.bucketName + 'Function';You can also use string interpolation, if your language supports it, as shown in the following example.
const functionName = `${bucket.bucketName}Function`;Avoid manipulating the string in other ways. For example, taking a substring of a string is likely to break the string token.
Working with list-encoded tokens
List-encoded tokens look like the following:
["#{TOKEN[Stack.NotificationArns.1234]}"]
The only safe thing to do with these lists is pass them directly to other constructs. Tokens in string list form cannot be concatenated, nor can an element be taken from the token. The only safe way to manipulate them is by using AWS CloudFormation intrinsic functions like Fn.select.
Working with number-encoded tokens
Number-encoded tokens are a set of tiny negative floating-point numbers that look like the following.
-1.8881545897087626e+289As with list tokens, you cannot modify the number value, as doing so is likely to break the number token.
The following is an example of a construct that contains a token encoded as a number:
import { Stack, Duration, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as rds from 'aws-cdk-lib/aws-rds';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
const vpc = new ec2.Vpc(this, 'MyVpc', {
maxAzs: 3, // Maximum number of availability zones to use
});
// Define an RDS database cluster
const dbCluster = new rds.DatabaseCluster(this, 'MyRDSCluster', {
engine: rds.DatabaseClusterEngine.AURORA,
instanceProps: {
vpc,
},
});
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// Print the value for our token at synthesis
console.log("portToken: " + portToken);
}
}When we run cdk synth, the value for portToken is displayed as a number-encoded
token:
$cdk synth --quietportToken: -1.8881545897087968e+289
Pass number-encoded tokens
When you pass number-encoded tokens to other constructs, it may make sense to convert them to strings first. For example, if you want to use the value of a number-encoded string as part of a concatenated string, converting it helps with readability.
In the following example, portToken is a number-encoded token that we want to pass to our Lambda
function as part of connectionString:
import { Stack, Duration, CfnOutput, StackProps } from 'aws-cdk-lib';
// ...
import * as lambda from 'aws-cdk-lib/aws-lambda';
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Example connection string with the port token as a number
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portToken}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
runtime: lambda.Runtime.NODEJS_20_X,
handler: 'index.handler',
code: lambda.Code.fromInline(`
exports.handler = async function(event) {
return {
statusCode: 200,
body: JSON.stringify('Hello World!'),
};
};
`),
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}If we pass this value to connectionString, the output value when we run cdk synth may
be confusing due to the number-encoded string:
$cdk synth --quietconnectionString: jdbc:mysql://mydb.cluster.amazonaws.com:-1.888154589708796e+289/mydatabase
To convert a number-encoded token to a string, use cdk.Tokenization.stringifyNumber(. In the following example,
we convert the number-encoded token to a string before defining our connection string:token)
import { Stack, Duration, Tokenization, CfnOutput, StackProps } from 'aws-cdk-lib';
// ...
export class CdkDemoAppStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
// Define a new VPC
// ...
// Define an RDS database cluster
// ...
// Get the port token (this is a token encoded as a number)
const portToken = dbCluster.clusterEndpoint.port;
// ...
// Convert the encoded number to an encoded string for use in the connection string
const portAsString = Tokenization.stringifyNumber(portToken);
// Example connection string with the port token as a string
const connectionString = `jdbc:mysql://mydb.cluster.amazonaws.com:${portAsString}/mydatabase`;
// Use the connection string as an environment variable in a Lambda function
const myFunction = new lambda.Function(this, 'MyLambdaFunction', {
// ...
environment: {
DATABASE_CONNECTION_STRING: connectionString, // Using the port token as part of the string
},
});
// Output the value of our connection string at synthesis
console.log("connectionString: " + connectionString);
// Output the connection string
new CfnOutput(this, 'ConnectionString', {
value: connectionString,
});
}
}When we run cdk synth, the value for our connection string is represented in a cleaner and clearer
format:
$cdk synth --quietconnectionString: jdbc:mysql://mydb.cluster.amazonaws.com:${Token[TOKEN.242]}/mydatabase
Lazy values
In addition to representing deploy-time values, such as AWS CloudFormation parameters, tokens are also commonly used to represent synthesis-time lazy values. These are values for which the final value will be determined before synthesis has completed, but not at the point where the value is constructed. Use tokens to pass a literal string or number value to another construct, while the actual value at synthesis time might depend on some calculation that has yet to occur.
You can construct tokens representing synth-time lazy values using static methods on the Lazy class,
such as Lazy.string and Lazy.number. These methods accept an
object whose produce property is a function that accepts a context argument and returns the final value
when called.
The following example creates an Auto Scaling group whose capacity is determined after its creation.
let actualValue: number;
new AutoScalingGroup(this, 'Group', {
desiredCapacity: Lazy.numberValue({
produce(context) {
return actualValue;
}
})
});
// At some later point
actualValue = 10;Converting to JSON
Sometimes you want to produce a JSON string of arbitrary data, and you may not know whether the data contains
tokens. To properly JSON-encode any data structure, regardless of whether it contains tokens, use the method stack.toJsonString, as shown in the following example.
const stack = Stack.of(this);
const str = stack.toJsonString({
value: bucket.bucketName
});