AWS cdk documentation change
Summary
Updated documentation formatting: replaced straight quotes with curly quotes, fixed markdown syntax for CLI commands, and improved code examples with proper shell prompts.
Security assessment
Changes are purely stylistic/formatting improvements. No security vulnerabilities, mitigations, or security features are mentioned. The context caching mechanism described is a stability feature rather than a security control.
Diff
diff --git a/cdk/v2/guide/context.md b/cdk/v2/guide/context.md index 6b8e93fe3..43627dffc 100644 --- a//cdk/v2/guide/context.md +++ b//cdk/v2/guide/context.md @@ -13 +13 @@ Context values are key-value pairs that can be associated with an app, stack, or -The CDK Toolkit uses context to cache values retrieved from your AWS account during synthesis. Values include the Availability Zones in your account or the Amazon Machine Image (AMI) IDs currently available for Amazon EC2 instances. Because these values are provided by your AWS account, they can change between runs of your CDK application. This makes them a potential source of unintended change. The CDK Toolkit's caching behavior "freezes" these values for your CDK app until you decide to accept the new values. +The CDK Toolkit uses context to cache values retrieved from your AWS account during synthesis. Values include the Availability Zones in your account or the Amazon Machine Image (AMI) IDs currently available for Amazon EC2 instances. Because these values are provided by your AWS account, they can change between runs of your CDK application. This makes them a potential source of unintended change. The CDK Toolkit’s caching behavior "freezes" these values for your CDK app until you decide to accept the new values. @@ -15 +15 @@ The CDK Toolkit uses context to cache values retrieved from your AWS account dur -Imagine the following scenario without context caching. Let's say you specified "latest Amazon Linux" as the AMI for your Amazon EC2 instances, and a new version of this AMI was released. Then, the next time you deployed your CDK stack, your already-deployed instances would be using the outdated ("wrong") AMI and would need to be upgraded. Upgrading would result in replacing all your existing instances with new ones, which would probably be unexpected and undesired. +Imagine the following scenario without context caching. Let’s say you specified "latest Amazon Linux" as the AMI for your Amazon EC2 instances, and a new version of this AMI was released. Then, the next time you deployed your CDK stack, your already-deployed instances would be using the outdated ("wrong") AMI and would need to be upgraded. Upgrading would result in replacing all your existing instances with new ones, which would probably be unexpected and undesired. @@ -17 +17 @@ Imagine the following scenario without context caching. Let's say you specified -Instead, the CDK records your account's available AMIs in your project's `cdk.context.json` file, and uses the stored value for future synthesis operations. This way, the list of AMIs is no longer a potential source of change. You can also be sure that your stacks will always synthesize to the same AWS CloudFormation templates. +Instead, the CDK records your account’s available AMIs in your project’s `cdk.context.json` file, and uses the stored value for future synthesis operations. This way, the list of AMIs is no longer a potential source of change. You can also be sure that your stacks will always synthesize to the same AWS CloudFormation templates. @@ -25 +25 @@ Context keys are strings. Values may be any type supported by JSON: numbers, str -If your constructs create their own context values, incorporate your library's package name in its keys so they won't conflict with other packages' context values. +If your constructs create their own context values, incorporate your library’s package name in its keys so they won’t conflict with other packages' context values. @@ -36 +36 @@ The following context key illustrates the format used by the AWS CDK, including -Cached context values are managed by the AWS CDK and its constructs, including constructs you may write. Do not add or change cached context values by manually editing files. It can be useful, however, to review `cdk.context.json` occasionally to see what values are being cached. Context values that don't represent cached values should be stored under the `context` key of `cdk.json`. This way, they won't be cleared when cached values are cleared. +Cached context values are managed by the AWS CDK and its constructs, including constructs you may write. Do not add or change cached context values by manually editing files. It can be useful, however, to review `cdk.context.json` occasionally to see what values are being cached. Context values that don’t represent cached values should be stored under the `context` key of `cdk.json`. This way, they won’t be cleared when cached values are cleared. @@ -44 +44 @@ Context values can be provided to your AWS CDK app in six different ways: - * Through the **\--context** option to the **cdk** command. (These values are always strings.) + * Through the `--context` option to the `cdk` command. (These values are always strings.) @@ -46 +46 @@ Context values can be provided to your AWS CDK app in six different ways: - * In the project's `cdk.context.json` file. + * In the project’s `cdk.context.json` file. @@ -48 +48 @@ Context values can be provided to your AWS CDK app in six different ways: - * In the `context` key of the project's `cdk.json` file. + * In the `context` key of the project’s `cdk.json` file. @@ -61 +61 @@ The project file `cdk.context.json` is where the AWS CDK caches context values r -Because they're part of your application's state, `cdk.json` and `cdk.context.json` must be committed to source control along with the rest of your app's source code. Otherwise, deployments in other environments (for example, a CI pipeline) might produce inconsistent results. +Because they’re part of your application’s state, `cdk.json` and `cdk.context.json` must be committed to source control along with the rest of your app’s source code. Otherwise, deployments in other environments (for example, a CI pipeline) might produce inconsistent results. @@ -63 +63 @@ Because they're part of your application's state, `cdk.json` and `cdk.context.js -Context values are scoped to the construct that created them; they are visible to child constructs, but not to parents or siblings. Context values that are set by the AWS CDK Toolkit (the **cdk** command) can be set automatically, from a file, or from the **\--context** option. Context values from these sources are implicitly set on the `App` construct. Therefore, they're visible to every construct in every stack in the app. +Context values are scoped to the construct that created them; they are visible to child constructs, but not to parents or siblings. Context values that are set by the AWS CDK Toolkit (the `cdk` command) can be set automatically, from a file, or from the `--context` option. Context values from these sources are implicitly set on the `App` construct. Therefore, they’re visible to every construct in every stack in the app. @@ -65 +65 @@ Context values are scoped to the construct that created them; they are visible t -Your app can read a context value using the `construct.node.tryGetContext` method. If the requested entry isn't found on the current construct or any of its parents, the result is `undefined`. (Alternatively, the result could be your language's equivalent, such as `None` in Python.) +Your app can read a context value using the `construct.node.tryGetContext` method. If the requested entry isn’t found on the current construct or any of its parents, the result is `undefined`. (Alternatively, the result could be your language’s equivalent, such as `None` in Python.) @@ -69 +69 @@ Your app can read a context value using the `construct.node.tryGetContext` metho -The AWS CDK supports several context methods that enable AWS CDK apps to obtain contextual information from the AWS environment. For example, you can get a list of Availability Zones that are available in a given AWS account and Region, using the [stack.availabilityZones](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#availabilityzones) method. +The AWS CDK supports several context methods that enable AWS CDK apps to obtain contextual information from the AWS environment. For example, you can get a list of Availability Zones that are available in a given AWS account and Region, using the [`stack.availabilityZones`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#availabilityzones) method. @@ -73 +73 @@ The following are the context methods: -[HostedZone.fromLookup](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_route53.HostedZone.html#static-fromwbrlookupscope-id-query) +[`HostedZone.fromLookup`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_route53.HostedZone.html#static-fromwbrlookupscope-id-query) @@ -78 +78 @@ Gets the hosted zones in your account. -[stack.availabilityZones](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#availabilityzones) +[`stack.availabilityZones`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#availabilityzones) @@ -83 +83 @@ Gets the supported Availability Zones. -[StringParameter.valueFromLookup](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ssm.StringParameter.html#static-valuewbrfromwbrlookupscope-parametername) +[`StringParameter.valueFromLookup`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ssm.StringParameter.html#static-valuewbrfromwbrlookupscope-parametername) @@ -86 +86 @@ Gets the supported Availability Zones. -Gets a value from the current Region's Amazon EC2 Systems Manager Parameter Store. +Gets a value from the current Region’s Amazon EC2 Systems Manager Parameter Store. @@ -88 +88 @@ Gets a value from the current Region's Amazon EC2 Systems Manager Parameter Stor -[Vpc.fromLookup](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html#static-fromwbrlookupscope-id-options) +[`Vpc.fromLookup`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Vpc.html#static-fromwbrlookupscope-id-options) @@ -93 +93 @@ Gets the existing Amazon Virtual Private Clouds in your accounts. -[LookupMachineImage](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.LookupMachineImage.html) +[`LookupMachineImage`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.LookupMachineImage.html) @@ -98 +98 @@ Looks up a machine image for use with a NAT instance in an Amazon Virtual Privat -If a required context value isn't available, the AWS CDK app notifies the CDK Toolkit that the context information is missing. Next, the CLI queries the current AWS account for the information and stores the resulting context information in the `cdk.context.json` file. Then, it executes the AWS CDK app again with the context values. +If a required context value isn’t available, the AWS CDK app notifies the CDK Toolkit that the context information is missing. Next, the CLI queries the current AWS account for the information and stores the resulting context information in the `cdk.context.json` file. Then, it executes the AWS CDK app again with the context values. @@ -102 +102 @@ If a required context value isn't available, the AWS CDK app notifies the CDK To -Use the **cdk context** command to view and manage the information in your `cdk.context.json` file. To see this information, use the **cdk context** command without any options. The output should be something like the following. +Use the `cdk context` command to view and manage the information in your `cdk.context.json` file. To see this information, use the `cdk context` command without any options. The output should be something like the following. @@ -115 +115 @@ Use the **cdk context** command to view and manage the information in your `cdk. - Run cdk context --reset KEY_OR_NUMBER to remove a context key. If it is a cached value, it will be refreshed on the next cdk synth. + Run @@ -117 +117,9 @@ Use the **cdk context** command to view and manage the information in your `cdk. -To remove a context value, run **cdk context --reset** , specifying the value's corresponding key or number. The following example removes the value that corresponds to the second key in the preceding example. This value represents the list of Availability Zones in the Europe (Ireland) Region. + cdk context --reset KEY_OR_NUMBER + + to remove a context key. If it is a cached value, it will be refreshed on the next + + cdk synth + + . + +To remove a context value, run `cdk context --reset`, specifying the value’s corresponding key or number. The following example removes the value that corresponds to the second key in the preceding example. This value represents the list of Availability Zones in the Europe (Ireland) Region. @@ -131 +138 @@ Therefore, if you want to update to the latest version of the Amazon Linux AMI, - cdk synth + $ cdk synth @@ -133 +140 @@ Therefore, if you want to update to the latest version of the Amazon Linux AMI, -To clear all of the stored context values for your app, run **cdk context --clear** , as follows. +To clear all of the stored context values for your app, run `cdk context --clear`, as follows. @@ -136 +143 @@ To clear all of the stored context values for your app, run **cdk context --clea - cdk context --clear + $ cdk context --clear @@ -145 +152 @@ Use the `--context` (`-c` for short) option to pass runtime context values to yo - cdk synth --context key=value MyStack + $ cdk synth --context key=value MyStack @@ -147 +154 @@ Use the `--context` (`-c` for short) option to pass runtime context values to yo -To specify multiple context values, repeat the **\--context** option any number of times, providing one key-value pair each time. +To specify multiple context values, repeat the `--context` option any number of times, providing one key-value pair each time. @@ -150 +157 @@ To specify multiple context values, repeat the **\--context** option any number - cdk synth --context key1=value1 --context key2=value2 MyStack + $ cdk synth --context key1=value1 --context key2=value2 MyStack @@ -152 +159 @@ To specify multiple context values, repeat the **\--context** option any number -When synthesizing multiple stacks, the specified context values are passed to all stacks. To provide different context values to individual stacks, either use different keys for the values, or use multiple **cdk synth** or **cdk deploy** commands. +When synthesizing multiple stacks, the specified context values are passed to all stacks. To provide different context values to individual stacks, either use different keys for the values, or use multiple `cdk synth` or `cdk deploy` commands. @@ -299 +306 @@ C# -You can use **cdk diff** to see the effects of passing in a context value on the command line: +You can use `cdk diff` to see the effects of passing in a context value on the command line: @@ -302 +309 @@ You can use **cdk diff** to see the effects of passing in a context value on the - cdk diff -c vpcid=vpc-0cb9c31031d0d3e22 + $ cdk diff -c vpcid=vpc-0cb9c31031d0d3e22 @@ -313 +319 @@ The resulting context values can be viewed as shown here. - cdk context -j + $ cdk context -j