AWS cdk documentation change
Summary
Updated token syntax representation in documentation examples, expanded code samples with missing closing braces/imports, adjusted markdown link formatting, and improved code comments.
Security assessment
Changes involve syntax adjustments (e.g., token format from backticks to angle brackets), code example completeness (adding imports/closing braces), and markdown corrections. No references to security vulnerabilities, mitigations, or new security features are present. The modifications focus on clarity and accuracy of token handling documentation rather than security implications.
Diff
diff --git a/cdk/v2/guide/tokens.md b/cdk/v2/guide/tokens.md index 9810fe205..65eea917c 100644 --- a//cdk/v2/guide/tokens.md +++ b//cdk/v2/guide/tokens.md @@ -187 +187 @@ Go -When we run `cdk synth` to synthesize our stack, the value for `myBucketName` will be displayed in the token format of `${Token[TOKEN.`1234`]}`. This token format is a result of how the AWS CDK encodes tokens. In this example, the token is encoded as a string: +When we run `cdk synth` to synthesize our stack, the value for `myBucketName` will be displayed in the token format of `${Token[TOKEN.<1234>]}`. This token format is a result of how the AWS CDK encodes tokens. In this example, the token is encoded as a string: @@ -193 +193 @@ When we run `cdk synth` to synthesize our stack, the value for `myBucketName` wi -Since the value for our bucket name is not known at synthesis, the token is rendered as `myBucket`<unique-hash>``. Our AWS CloudFormation template uses the `Ref` intrinsic function to reference its value, which will be known at deployment: +Since the value for our bucket name is not known at synthesis, the token is rendered as `myBucket<unique-hash>`. Our AWS CloudFormation template uses the `Ref` intrinsic function to reference its value, which will be known at deployment: @@ -197 +197 @@ Since the value for our bucket name is not known at synthesis, the token is rend - myBucket5AF9C99B: + myBucket<5AF9C99B>: @@ -203 +203 @@ Since the value for our bucket name is not known at synthesis, the token is rend - Ref: myBucket5AF9C99B + Ref: myBucket<5AF9C99B> @@ -479 +479 @@ When we synthesize our template, the `Ref` and `Fn::Join` intrinsic functions ar - myBucket5AF9C99B: + myBucket<5AF9C99B>: @@ -482 +482 @@ When we synthesize our template, the `Ref` and `Fn::Join` intrinsic functions ar - myFunction884E1557: + myFunction<884E1557>: @@ -489 +489 @@ When we synthesize our template, the `Ref` and `Fn::Join` intrinsic functions ar - Ref: myBucket5AF9C99B + Ref: myBucket<5AF9C99B> @@ -493 +493 @@ When we synthesize our template, the `Ref` and `Fn::Join` intrinsic functions ar - - - Ref: myBucket5AF9C99B + - - Ref: myBucket<5AF9C99B> @@ -499 +499 @@ When we synthesize our template, the `Ref` and `Fn::Join` intrinsic functions ar -Tokens are objects that implement the `[IResolvable](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IResolvable.html)` 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. +Tokens are objects that implement the [`IResolvable`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IResolvable.html) 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. @@ -503 +503 @@ Tokens are objects that implement the `[IResolvable](https://docs.aws.amazon.com -You'll rarely work directly with the `IResolvable` interface. You will most likely only see string-encoded versions of tokens. +You’ll rarely work directly with the `IResolvable` interface. You will most likely only see string-encoded versions of tokens. @@ -507 +507 @@ You'll rarely work directly with the `IResolvable` interface. You will most like -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](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html)` class. +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`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html) class. @@ -522 +522 @@ These take an arbitrary value, which can be an `IResolvable`, and encode them in -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. +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. @@ -526 +526 @@ Because any one of the previous types can potentially be an encoded token, be ca -To check whether a value has an unresolved token in it, call the `[Token.isUnresolved](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-iswbrunresolvedobj)` (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: +To check whether a value has an unresolved token in it, call the [`Token.isUnresolved`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Token.html#static-iswbrunresolvedobj) (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: @@ -549,0 +550,2 @@ TypeScript + } + } @@ -574,0 +577,2 @@ JavaScript + } + } @@ -609,0 +614 @@ Java + import software.amazon.awscdk.services.s3.Bucket; @@ -625,0 +631,3 @@ Java + // Get the bucket name + String myBucketName = myBucket.getBucketName(); + @@ -635,0 +644 @@ Java + } @@ -658,0 +668,3 @@ C# + // Get the bucket name + var myBucketName = myBucket.BucketName; + @@ -669,0 +682,3 @@ C# + } + } + } @@ -696,0 +712 @@ Go + } @@ -706 +722 @@ When we run `cdk synth`, `myBucketName` is identified as a token: -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. +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. @@ -802 +818 @@ List-encoded tokens look like the following: -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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-select.html). +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`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-select.html). @@ -1298,0 +1315,5 @@ C# + using Amazon.CDK.AWS.RDS; + using Amazon.CDK; + using Constructs; + using System; + using System.Collections.Generic; @@ -1311 +1332,3 @@ C# - // ... + { + // ... properties would go here + }); @@ -1421 +1444 @@ If we pass this value to `connectionString`, the output value when we run `cdk s -To convert a number-encoded token to a string, use `[cdk.Tokenization.stringifyNumber(`token`)](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tokenization.html#static-stringifywbrnumberx)`. In the following example, we convert the number-encoded token to a string before defining our connection string: +To convert a number-encoded token to a string, use [`cdk.Tokenization.stringifyNumber(<token>)`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Tokenization.html#static-stringifywbrnumberx). In the following example, we convert the number-encoded token to a string before defining our connection string: @@ -1729 +1752 @@ In addition to representing deploy-time values, such as AWS CloudFormation [para -You can construct tokens representing synth-time lazy values using static methods on the `Lazy` class, such as `[Lazy.string](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Lazy.html#static-stringproducer-options)` and `[Lazy.number](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Lazy.html#static-numberproducer)`. These methods accept an object whose `produce` property is a function that accepts a context argument and returns the final value when called. +You can construct tokens representing synth-time lazy values using static methods on the `Lazy` class, such as [`Lazy.string`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Lazy.html#static-stringproducer-options) and [`Lazy.number`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Lazy.html#static-numberproducer). These methods accept an object whose `produce` property is a function that accepts a context argument and returns the final value when called. @@ -1836 +1858 @@ C# -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](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#towbrjsonwbrstringobj-space)`, as shown in the following example. +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`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#towbrjsonwbrstringobj-space), as shown in the following example.