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.
Tokens and the AWS CDK
Tokens represent values that can only be resolved at a later time in the app lifecycle. For example, the name of an Amazon Simple Storage Service (Amazon S3) bucket that you define in your
CDK app is only allocated when the AWS CloudFormation template is synthesized. If you print the bucket.bucketName
attribute, which is a string, you will see that it contains something like the following:
${TOKEN[Bucket.Name.1234]}
This is how the AWS CDK encodes a token whose value is not yet known at construction time, but will become available later. The AWS CDK calls these placeholders tokens. In this case, it's a token encoded as a string.
You can pass this string around as if it was the name of the bucket. In the following example, the bucket name is specified as an environment variable to an AWS Lambda function.
When the AWS CloudFormation template is finally synthesized, the token is rendered as the AWS CloudFormation intrinsic { "Ref":
"MyBucket" }
. At deployment time, AWS CloudFormation replaces this intrinsic with the actual name of the bucket that was
created.
Topics
Tokens and token encodings
Tokens are objects that implement the IResolvable interface, which contains a single
resolve
method. The AWS CDK calls this method during synthesis to produce the final value for the AWS CloudFormation
template. Tokens participate in the synthesis process to produce arbitrary values of any type.
Note
You'll rarely work directly with the IResolvable
interface. You will most likely only see
string-encoded versions of tokens.
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.asString
to generate a string encoding (or call.toString()
on the token object) -
Token.asList
to generate a list encoding -
Token.asNumber
to 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.
To check whether a value has an unresolved token in it, call the Token.isUnresolved
(Python:
is_unresolved
) method.
The following example validates that a string value, which could be a token, is no more than 10 characters long.
If name is a token, validation isn't performed, and an error could still occur in a later stage in the lifecycle, such as during deployment.
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.
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.
You can also use string interpolation, if your language supports it, as shown in the following example.
Avoid manipulating the string in other ways. For example, taking a substring of a string is likely to break the string token.
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.
Number-encoded tokens
Number-encoded tokens are a set of tiny negative floating-point numbers that look like the following.
-1.8881545897087626e+289
As with list tokens, you cannot modify the number value, as doing so is likely to break the number token. The only allowed operation is to pass the value around to another construct.
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.
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.