sync changes from awsdocs

doc_source/assets.md

@@ -274,7 +274,7 @@ The `Function` method uses assets to bundle the contents of the directory and us
 
 Amazon S3 asset types also expose [deploy\-time attributes](resources.md#resources_attributes) that can be referenced in AWS CDK libraries and apps\. The AWS CDK CLI command cdk synth displays asset properties as AWS CloudFormation parameters\.
 
-The following example uses deploy\-time attributes to pass the location of an image asset into a Lambda function as environment variables\.
+The following example uses deploy\-time attributes to pass the location of an image asset into a Lambda function as environment variables\. \(The kind of file doesn't matter; the PNG image used here is just an example\.\)
 
 ------
 #### [ TypeScript ]

doc_source/best-practices.md

@@ -65,7 +65,7 @@ Dependencies on packages in the package repository are managed by your language'
 
 Shared packages need a different testing strategy: although for a single application it might be good enough to deploy the application to a testing environment and confirm that it still works, shared packages need to be tested independently of the consuming application, as if they were being released to the public\. \(Your organization might in fact choose to actually release some shared packages to the public\.\)
 
-Keep in mind that a construct can be arbitrary simple or complex\. A `Bucket` is a construct, but `CameraShopWebsite` could be a construct, too\.
+Keep in mind that a construct can be arbitrarily simple or complex\. A `Bucket` is a construct, but `CameraShopWebsite` could be a construct, too\.
 
 ### Infrastructure and runtime code live in the same package<a name="best-practices-code-all"></a>
 
@@ -119,9 +119,13 @@ Treat AWS CloudFormation as an implementation detail that the AWS CDK uses for r
 
 Names are a precious resource\. Every name can only be used once, so if you hard\-code a table name or bucket name into your infrastructure and application, you can't deploy that piece of infrastructure twice in the same account\. \(The name we're talking about here is the name specified by, for example, the `bucketName` property on an Amazon S3 bucket construct\.\)
 
-What's worse, you can't make changes to the resource that require it to be replaced\. If a property can only be set at resource creation, for example the `KeySchema` of an Amazon DynamoDB table, that property is immutable, and changing it requires a new resource\. But the new resource must have the same name in order to be a true replacement, and it can't, because the existing resource is still using that name\. 
+What's worse, you can't make changes to the resource that require it to be replaced\. If a property can only be set at resource creation, for example the `KeySchema` of an Amazon DynamoDB table, that property is immutable, and changing it requires a new resource\. But the new resource must have the same name in order to be a true replacement, and it can't while the existing resource is still using that name\.
 
-A better approach is to specify as few names as possible\. If you leave out resource names, the AWS CDK will generate them for you, and it'll do so in a way that won't cause these problems\. You then, for example, pass the generated table name \(which you can reference as `table.tableName` in your AWS CDK application\) as an environment variable into your AWS Lambda function, or you generate a configuration file on your Amazon EC2 instance on startup, or you write the actual table name to AWS Systems Manager Parameter Store and your application reads it from there\. It's like dependency injection, but for resources\.
+A better approach is to specify as few names as possible\. If you leave out resource names, the AWS CDK will generate them for you, and it'll do so in a way that won't cause these problems\. You then, for example, pass the generated table name \(which you can reference as `table.tableName` in your AWS CDK application\) as an environment variable into your AWS Lambda function, or you generate a configuration file on your Amazon EC2 instance on startup, or you write the actual table name to AWS Systems Manager Parameter Store and your application reads it from there\.
+
+If the place you need it is another AWS CDK stack, that's even easier\. Given one stack that defines the resource and another than needs to use it:
++ If the two stacks are in the same AWS CDK app, just pass a reference between the two stacks\. For example, save a reference to the resource's construct as an attribute of the defining stack \(`this.stack.uploadBucket = myBucket`\), then pass that attribute to the constructor of the stack that needs the resource\.
++ When the two stacks are in different AWS CDK apps, use a static `from` method to import an externally\-defined resource based on its ARN, name, or other attributes \(for example, `Table.fromarn()` for a DynamoDB table\)\. Use the `CfnOutput` consturct to print the ARN or other required value in the output of `cdk deploy`, or look in the AWS console\. Or the second app can parse the CloudFormation template generated by the first app and retrieve that value from the Outputs section\.
 
 ### Define removal policies and log retention<a name="best-practices-apps-removal-logs"></a>
 
@@ -138,7 +142,7 @@ There is no hard and fast rule to how many stacks your application needs\. You'l
 
 ### Commit `cdk.context.json` to avoid non\-deterministic behavior<a name="best-practices-apps-context"></a>
 
-Determinism is key to successful AWS CDK deployments\. A AWS CDK app should have essentially the same result whenever it is deployed \(notwithstanding necessary differences based on the environment where it's deployed\)\.
+Determinism is key to successful AWS CDK deployments\. A AWS CDK app should have essentially the same result whenever it is deployed to a given environment\.
 
 Since your AWS CDK app is written in a a general\-purpose programming language, it can execute arbitrary code, use arbitrary libraries, and make arbitrary network calls\. For example, you could use an AWS SDK to retrieve some information from your AWS account while synthesizing your app\. Recognize that doing so will result in additional credential setup requirements, increased latency, and a chance, however small, of failure every time you run `cdk synth`\.
 

doc_source/cdk_pipeline.md

@@ -144,7 +144,7 @@ If you are using Visual Studio, open the solution file in the `src` directory\.
 Install the CDK Pipelines module along with any others you'll be using\.
 
 **Tip**  
-Be sure to commit your `cdk.json` and `cdk.context.json` files in source control\. The context information \(such as feature flags and cached values retrieved from your AWS account\) are part of your project's state\. By design, cached values cannot be retrieved in a CI/CD environment, so having them in `cdk.context.json` is critical to successful deployment\.
+Be sure to commit your `cdk.json` and `cdk.context.json` files in source control\. The context information \(such as feature flags and cached values retrieved from your AWS account\) are part of your project's state\. The values may be different in another environment, which can cause instability \(unexpected changes\) in your results\.
 
 ------
 #### [ TypeScript ]
@@ -344,7 +344,9 @@ class MyPipelineStack(cdk.Stack):
                         pipeline_name="MyPipeline",
                         synth=ShellStep("Synth", 
                             input=CodePipelineSource.git_hub("OWNER/REPO", "main"),
-                            commands=["npm install -g aws-cdk", "cdk synth"]
+                            commands=["npm install -g aws-cdk", 
+                                "python -m pip install -r requirements.txt", 
+                                "cdk synth"]
                         )
                     )
 ```
@@ -413,7 +415,7 @@ public class MyPipelineApp {
         App app = new App();
 
         new MyPipelineStack(app, "PipelineStack", StackProps.builder()
-            .env(new Environment.Builder()
+            .env(new Environment.builder()
                 .account("111111111111")
                 .region("eu-west-1")
                 .build())
@@ -687,7 +689,9 @@ class MyPipelineStack(cdk.Stack):
                         pipeline_name="MyPipeline",
                         synth=ShellStep("Synth", 
                             input=CodePipelineSource.git_hub("OWNER/REPO", "main"),
-                            commands=["npm install -g aws-cdk", "cdk synth"]))
+                            commands=["npm install -g aws-cdk",
+                                "python -m pip install -r requirements.txt",
+                                "cdk synth"]))
 
         pipeline.add_stage(MyPipelineAppStage(self, "test",
             env=cdk.Environment(account="111111111111", region="eu-west-1")))
@@ -1244,7 +1248,9 @@ pipeline =  CodePipeline(self, "Pipeline",
                 pipeline_name="MyPipeline",
                 synth=ShellStep("Synth", 
                     input=source,
-                    commands=["npm install -g aws-cdk", "cdk synth"]))
+                    commands=["npm install -g aws-cdk",
+                        "python -m pip install -r requirements.txt",
+                        "cdk synth"]))
 
 stage = pipeline.add_stage(MyApplicationStage(self, "test",
             env=cdk.Environment(account="111111111111", region="eu-west-1")))
@@ -1373,7 +1379,9 @@ stage.addPost(new ShellStep('validate', {
 ```
 synth_step = ShellStep("Synth", 
                 input=CodePipelineSource.git_hub("OWNER/REPO", "main"),
-                commands=["npm install -g aws-cdk", "cdk synth"])
+                commands=["npm install -g aws-cdk",
+                  "python -m pip install -r requirements.txt",
+                  "cdk synth"])
 
 pipeline   = CodePipeline(self, "Pipeline", 
                 pipeline_name="MyPipeline",

doc_source/cli.md

@@ -336,7 +336,7 @@ The CDK Toolkit actually runs your app and synthesizes fresh templates before mo
 
 See `cdk synth --help` for all available options\. A few of the most\-frequently\-used options are covered below\.
 
-### Specifying context values<a name="w298aac27b7c31c11"></a>
+### Specifying context values<a name="w302aac27b7c31c11"></a>
 
 Use the `--context` or `-c` option to pass [runtime context](context.md) values to your CDK app\.
 
@@ -355,15 +355,15 @@ When deploying multiple stacks, the specified context values are normally passed
 cdk synth --context Stack1:key=value Stack2:key=value Stack1 Stack2
 ```
 
-### Specifying display format<a name="w298aac27b7c31c13"></a>
+### Specifying display format<a name="w302aac27b7c31c13"></a>
 
 By default, the synthesized template is displayed in YAML format\. Add the `--json` flag to display it in JSON format instead\.
 
 ```
 cdk synth --json MyStack
 ```
 
-### Specifying output directory<a name="w298aac27b7c31c15"></a>
+### Specifying output directory<a name="w302aac27b7c31c15"></a>
 
 Add the `--output` \(`-o`\) option to write the synthesized templates to a directory other than `cdk.out`\.
 
@@ -387,7 +387,7 @@ The CDK Toolkit runs your app and synthesizes fresh AWS CloudFormation templates
 
 See `cdk deploy --help` for all available options\. A few of the most\-frequently\-used options are covered below\.
 
-### Specifying AWS CloudFormation parameters<a name="w298aac27b7c33c11"></a>
+### Specifying AWS CloudFormation parameters<a name="w302aac27b7c33c11"></a>
 
 The AWS CDK Toolkit supports specifying AWS CloudFormation [parameters](parameters.md) at deployment\. You may provide these on the command line following the `--parameters` flag\.
 
@@ -409,7 +409,7 @@ cdk deploy MyStack YourStack --parameters MyStack:uploadBucketName=UploadBucket
 
 By default, the AWS CDK retains values of parameters from previous deployments and uses them in later deployments if they are not specified explicitly\. Use the `--no-previous-parameters` flag to require all parameters to be specified\.
 
-### Specifying outputs file<a name="w298aac27b7c33c13"></a>
+### Specifying outputs file<a name="w302aac27b7c33c13"></a>
 
 If your stack declares AWS CloudFormation outputs, these are normally displayed on the screen at the conclusion of deployment\. To write them to a file in JSON format, use the `--outputs-file` flag\.
 
@@ -623,7 +623,7 @@ If one of cdk.json or ~/.cdk.json exists, options specified there will be used
 as defaults. Settings in cdk.json take precedence.
 ```
 
-### `cdk list` \(`ls`\)<a name="w298aac27b7c39b7b1"></a>
+### `cdk list` \(`ls`\)<a name="w302aac27b7c39b7b1"></a>
 
 ```
 cdk list [STACKS..]
@@ -636,7 +636,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk synthesize` \(`synth`\)<a name="w298aac27b7c39b7b3"></a>
+### `cdk synthesize` \(`synth`\)<a name="w302aac27b7c39b7b3"></a>
 
 ```
 cdk synthesize [STACKS..]
@@ -657,7 +657,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk bootstrap`<a name="w298aac27b7c39b7b5"></a>
+### `cdk bootstrap`<a name="w302aac27b7c39b7b5"></a>
 
 ```
 cdk bootstrap [ENVIRONMENTS..]
@@ -732,7 +732,7 @@ Options:
                                             example)                    [string]
 ```
 
-### `cdk deploy`<a name="w298aac27b7c39b7b7"></a>
+### `cdk deploy`<a name="w302aac27b7c39b7b7"></a>
 
 ```
 cdk deploy [STACKS..]
@@ -789,7 +789,7 @@ Options:
                                                        [boolean] [default: true]
 ```
 
-### `cdk destroy`<a name="w298aac27b7c39b7b9"></a>
+### `cdk destroy`<a name="w302aac27b7c39b7b9"></a>
 
 ```
 cdk destroy [STACKS..]
@@ -808,7 +808,7 @@ Options:
                             stacks                                     [boolean]
 ```
 
-### `cdk diff`<a name="w298aac27b7c39b7c11"></a>
+### `cdk diff`<a name="w302aac27b7c39b7c11"></a>
 
 ```
 cdk diff [STACKS..]
@@ -834,7 +834,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk init`<a name="w298aac27b7c39b7c13"></a>
+### `cdk init`<a name="w302aac27b7c39b7c13"></a>
 
 ```
 cdk init [TEMPLATE]
@@ -856,7 +856,7 @@ Options:
                             project                   [boolean] [default: false]
 ```
 
-### `cdk context`<a name="w298aac27b7c39b7c15"></a>
+### `cdk context`<a name="w302aac27b7c39b7c15"></a>
 
 ```
 cdk context

doc_source/context.md

@@ -4,6 +4,9 @@ Context values are key\-value pairs that can be associated with a stack or const
 
 Context keys are strings, and values may be any type supported by JSON: numbers, strings, arrays, or objects\.
 
+**Important**  
+Context values are managed by the AWS CDK and its constructs, including constructs you may write\. You should not attempt to add context values manually\. It is useful to review `cdk.context.json` to see what values are being cached; by convention, the keys start with the name of the CDK package that set them\. You sholud follow this convention when setting your own values\.
+
 ## Construct context<a name="context_construct"></a>
 
 Context values can be provided to your AWS CDK app in six different ways:
@@ -43,9 +46,7 @@ Gets the existing Amazon Virtual Private Clouds in your accounts\.
 [LookupMachineImage](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-ec2.LookupMachineImage.html)  
 Looks up a machine image for use with a NAT instance in an Amazon Virtual Private Cloud\.
 
-If a given context information isn't available, the AWS CDK app notifies the AWS CDK CLI that the context information is missing\. The CLI then queries the current AWS account for the information, stores the resulting context information in the `cdk.context.json` file, and executes the AWS CDK app again with the context values\.
-
-Don't forget to add the `cdk.context.json` file to your source control repository to ensure that subsequent synth commands will return the same result, and that your AWS account won't be needed when synthesizing from your build system\.
+If a required context value isn't available, the AWS CDK app notifies the AWS CDK CLI that the context information is missing\. The CLI then queries the current AWS account for the information, stores the resulting context information in the `cdk.context.json` file, and executes the AWS CDK app again with the context values\.
 
 ## Viewing and managing context<a name="context_viewing"></a>
 

doc_source/get_ssm_value.md

@@ -5,12 +5,14 @@ The AWS CDK can retrieve the value of AWS Systems Manager Parameter Store attrib
 The AWS CDK supports retrieving both plain and secure values\. You may request a specific version of either kind of value\. For plain values only, you may omit the version from your request to receive the latest version\. You must always specify the version when requesting the value of a secure attribute\.
 
 **Note**  
- This topic shows how to read attributes from the AWS Systems Manager Parameter Store\. You can also read secrets from the AWS Secrets Manager \(see [Get a value from AWS Secrets Manager](get_secrets_manager_value.md)\)\.
+This topic shows how to read attributes from the AWS Systems Manager Parameter Store\. You can also read secrets from the AWS Secrets Manager \(see [Get a value from AWS Secrets Manager](get_secrets_manager_value.md)\)\.
 
 ## Reading Systems Manager values at deployment time<a name="ssm_read"></a>
 
 To read values from the Systems Manager Parameter Store, use the [valueForStringParameter](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-ssm.StringParameter.html#static-value-for-string-parameterscope-parametername-version) and [valueForSecureStringParameter](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-ssm.StringParameter.html#static-value-for-secure-string-parameterscope-parametername-version) methods, depending on whether the attribute you want is a plain string or a secure string value\. These methods return [tokens](tokens.md), not the actual value\. The value is resolved by AWS CloudFormation during deployment\.
 
+A [limited number of AWS services](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html#template-parameters-dynamic-patterns-resources) currently support this feature\.
+
 ------
 #### [ TypeScript ]
 
@@ -104,6 +106,11 @@ It is sometimes useful to "bake in" a parameter at synthesis time, so that the r
 
 To read a value from the Systems Manager parameter store at synthesis time, use the [valueFromLookup](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-ssm.StringParameter.html#static-value-wbr-from-wbr-lookupscope-parametername) method \(Python: `value_from_lookup`\)\. This method returns the actual value of the parameter as a [Runtime context](context.md) value\. If the value is not already cached in `cdk.json` or passed on the command line, it will be retrieved from the current AWS account\. For this reason, the stack *must* be synthesized with explicit account and region information\.
 
+Only plain Systems Manager strings may be retrieved, not secure strings\. It is not possible to request a specific version; the latest version is always returned\.
+
+**Important**  
+The retrieved value will end up in your synthenized AWS CloudFormation template, which may be a security risk depending on who has access to your your AWS CloudFormation templates and what kind of value it is\. Generally, don't use this feature for passwords, keys, or other values you want to keep private\.
+
 ------
 #### [ TypeScript ]
 
@@ -151,8 +158,6 @@ var stringValue = StringParameter.ValueFromLookup(this, "my-plain-parameter-name
 
 ------
 
-Only plain Systems Manager strings may be retrieved, not secure strings\. It is not possible to request a specific version; the latest version is always returned\.
-
 ## Writing values to Systems Manager<a name="ssm_write"></a>
 
 You can use the AWS CLI, the AWS Management Console, or an AWS SDK to set Systems Manager parameter values\. The following examples use the [ssm put\-parameter](https://docs.aws.amazon.com/cli/latest/reference/ssm/put-parameter.html) CLI command\.