various minor updates and some churn

Author: Jerry Kindall

doc_source/bootstrapping.md

@@ -12,7 +12,7 @@ The required resources are defined in a AWS CloudFormation stack, called the *bo
 The AWS CDK supports two bootstrap templates\. At this writing, the AWS CDK is transitioning from one of these templates to the other, but the original template \(dubbed "legacy"\) is still the default\. The newer template \("modern"\) is required by CDK Pipelines today, and will become the default at some point in the future\. For details, see [Bootstrapping templates](#bootstrapping-templates)\.
 
 **Important**  
-The modern bootstrap template grants the bootstrapping account read and write access to any Amazon S3 bucket in the same environment, as well as the ability to read secrets from AWS KMS\. All accounts trusted in the bootstrapped environment can perform the same actions\. If this is not what you want, use a [custom template](#bootstrapping-customizing-extended)\. These permissions are only required by [CDK Pipelines](cdk_pipeline.md)\.
+The modern bootstrap template grants the bootstrapped account read and write access to any Amazon S3 bucket in the same environment, as well as the ability to read secrets from AWS KMS\. All accounts trusted in the bootstrapped environment can perform the same actions\. If this is not what you want, use a [custom template](#bootstrapping-customizing-extended)\. These permissions are only required by [CDK Pipelines](cdk_pipeline.md)\.
 
 Environments are independent, so if you want to deploy to multiple environments \(different AWS accounts or different regions in the same account\), each environment must be bootstrapped separately\.
 
@@ -108,7 +108,7 @@ The main differences between the templates are as follows\.
 \* *We will add additional resources to the modern template as needed\.*
 
 **Important**  
-The modern bootstrap template grants the bootstrapping account read and write access to any Amazon S3 bucket in the same environment, as well as the ability to read secrets from AWS KMS\. All accounts trusted in the bootstrapped environment can perform the same actions\. If this is not what you want, use a [custom template](#bootstrapping-customizing-extended)\. These permissions are only required by [CDK Pipelines](cdk_pipeline.md)\.
+The modern bootstrap template grants the bootstrapped account read and write access to any Amazon S3 bucket in the same environment, as well as the ability to read secrets from AWS KMS\. All accounts trusted in the bootstrapped environment can perform the same actions\. If this is not what you want, use a [custom template](#bootstrapping-customizing-extended)\. These permissions are only required by [CDK Pipelines](cdk_pipeline.md)\.
 
 At some point in the future, the modern template will become the default bootstrapping template\. Until then, manually select the modern template when bootstrapping by setting the `CDK_NEW_BOOTSTRAP` environment variable\.
 

doc_source/cli.md

@@ -271,7 +271,7 @@ Older versions of the modern template created a Customer Master Key by default\.
 The AWS CDK Toolkit supports two bootstrap templates: the modern template and the legacy template\. The legacy template is the default, but the modern template is required by CDK Pipelines\. For more inforamtion, see [Bootstrapping](bootstrapping.md)\.
 
 **Important**  
-The modern bootstrap template grants the bootstrapping account read and write access to any Amazon S3 bucket in the same environment, as well as the ability to read secrets from AWS KMS\. All accounts trusted in the bootstrapped environment can perform the same actions\. If this is not what you want, use a [custom template](bootstrapping.md#bootstrapping-customizing-extended)\. These permissions are only required by [CDK Pipelines](cdk_pipeline.md)\.
+The modern bootstrap template grants the bootstrapped account read and write access to any Amazon S3 bucket in the same environment, as well as the ability to read secrets from AWS KMS\. All accounts trusted in the bootstrapped environment can perform the same actions\. If this is not what you want, use a [custom template](bootstrapping.md#bootstrapping-customizing-extended)\. These permissions are only required by [CDK Pipelines](cdk_pipeline.md)\.
 
 ## Creating a new app<a name="cli-init"></a>
 
@@ -335,7 +335,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="w289aac25b7c31c11"></a>
+### Specifying context values<a name="w297aac27b7c31c11"></a>
 
 Use the `--context` or `-c` option to pass [runtime context](context.md) values to your CDK app\.
 
@@ -354,15 +354,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="w289aac25b7c31c13"></a>
+### Specifying display format<a name="w297aac27b7c31c13"></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="w289aac25b7c31c15"></a>
+### Specifying output directory<a name="w297aac27b7c31c15"></a>
 
 Add the `--output` \(`-o`\) option to write the synthesized templates to a directory other than `cdk.out`\.
 
@@ -386,7 +386,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="w289aac25b7c33c11"></a>
+### Specifying AWS CloudFormation parameters<a name="w297aac27b7c33c11"></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\.
 
@@ -408,7 +408,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="w289aac25b7c33c13"></a>
+### Specifying outputs file<a name="w297aac27b7c33c13"></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\.
 
@@ -625,7 +625,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="w289aac25b7c39b7b1"></a>
+### `cdk list` \(`ls`\)<a name="w297aac27b7c39b7b1"></a>
 
 ```
 cdk list [STACKS..]
@@ -638,7 +638,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk synthesize` \(`synth`\)<a name="w289aac25b7c39b7b3"></a>
+### `cdk synthesize` \(`synth`\)<a name="w297aac27b7c39b7b3"></a>
 
 ```
 cdk synthesize [STACKS..]
@@ -654,7 +654,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk bootstrap`<a name="w289aac25b7c39b7b5"></a>
+### `cdk bootstrap`<a name="w297aac27b7c39b7b5"></a>
 
 ```
 cdk bootstrap [ENVIRONMENTS..]
@@ -723,7 +723,7 @@ Options:
                                             example)                    [string]
 ```
 
-### `cdk deploy`<a name="w289aac25b7c39b7b7"></a>
+### `cdk deploy`<a name="w297aac27b7c39b7b7"></a>
 
 ```
 cdk deploy [STACKS..]
@@ -776,7 +776,7 @@ Options:
                                              [string] [choices: "bar", "events"]
 ```
 
-### `cdk destroy`<a name="w289aac25b7c39b7b9"></a>
+### `cdk destroy`<a name="w297aac27b7c39b7b9"></a>
 
 ```
 cdk destroy [STACKS..]
@@ -795,7 +795,7 @@ Options:
                             stacks                                     [boolean]
 ```
 
-### `cdk diff`<a name="w289aac25b7c39b7c11"></a>
+### `cdk diff`<a name="w297aac27b7c39b7c11"></a>
 
 ```
 cdk diff [STACKS..]
@@ -815,7 +815,7 @@ Options:
                             with                                        [string]
 ```
 
-### `cdk init`<a name="w289aac25b7c39b7c13"></a>
+### `cdk init`<a name="w297aac27b7c39b7c13"></a>
 
 ```
 cdk init [TEMPLATE]
@@ -837,7 +837,7 @@ Options:
                             project                   [boolean] [default: false]
 ```
 
-### `cdk context`<a name="w289aac25b7c39b7c15"></a>
+### `cdk context`<a name="w297aac27b7c39b7c15"></a>
 
 ```
 cdk context

doc_source/index.md

@@ -43,6 +43,7 @@ Amazon's trademarks and trade dress may not be used in
    + [Aspects](aspects.md)
    + [Escape hatches](cfn_layer.md)
    + [Bootstrapping](bootstrapping.md)
++ [Best practices for developing and deploying cloud infrastructure with the AWS CDK](best-practices.md)
 + [API reference](reference.md)
 + [Examples](examples.md)
    + [Creating a serverless application using the AWS CDK](serverless_example.md)

doc_source/tagging.md

@@ -90,7 +90,7 @@ Tags.Of(myConstruct).Remove("key");
 
 ------
 
-## Tag priorities<a name="w289aac17c23c21"></a>
+## Tag priorities<a name="w297aac17c23c21"></a>
 
 The AWS CDK applies and removes tags recursively\. If there are conflicts, the tagging operation with the highest priority wins\. \(Priorities are set using the optional `priority` property\.\) If the priorities of two operations are the same, the tagging operation closest to the bottom of the construct tree wins\. By default, applying a tag has a priority of 100 \(except for tags added directly to an AWS CloudFormation resource, which has a priority of 50\) and removing a tag has a priority of 200\. 
 

doc_source/use_cfn_template.md

@@ -4,7 +4,7 @@ The [https://docs.aws.amazon.com/cdk/api/latest/docs/cloudformation-include-read
 
 This construct essentially adds an AWS CDK API wrapper to any resource in the template\. You can use this capability to migrate your existing AWS CloudFormation templates to the AWS CDK a piece at a time in order to take advantage of the AWS CDK's convenient higher\-level abstractions, or just to vend your AWS CloudFormation templates to AWS CDK developers by providing an AWS CDK construct API\.\.
 
-## Importing an AWS CloudFormation template<a name="w289aac23b9b7"></a>
+## Importing an AWS CloudFormation template<a name="w297aac25b9b7"></a>
 
  Here is a simple AWS CloudFormation template we'll use for the examples in this topic\. Save it as `my-template.json`\. After you've tried these examples with the provided template, you might explore further using a template for an actual stack you've already deployed, which you can obtain from the AWS CloudFormation console\.
 

doc_source/work-with-cdk-v2.md

@@ -15,7 +15,7 @@ The main changes in CDK v2 are:
 + CDK v2 requires that the environments you deploy into be boostrapped using the modern bootstrap stack; the legacy stack is no longer supported\. CDK v2 furthermore requires a new version of the modern stack\. Simply re\-bootstrap the affected environments to upgrade them\. It is not necessary to set any feature flags or environment variables to specify the modern bootstrap stack\.
 
 **Important**  
-The modern bootstrap template grants the bootstrapping account read and write access to any Amazon S3 bucket in the same environment, as well as the ability to read secrets from AWS KMS\. All accounts trusted in the bootstrapped environment can perform the same actions\. If this is not what you want, use a [custom template](bootstrapping.md#bootstrapping-customizing-extended)\. These permissions are only required by [CDK Pipelines](cdk_pipeline.md)\.
+The modern bootstrap template grants the bootstrapped account read and write access to any Amazon S3 bucket in the same environment, as well as the ability to read secrets from AWS KMS\. All accounts trusted in the bootstrapped environment can perform the same actions\. If this is not what you want, use a [custom template](bootstrapping.md#bootstrapping-customizing-extended)\. These permissions are only required by [CDK Pipelines](cdk_pipeline.md)\.
 
 Aside from this topic, the AWS CDK Developer Guide describes CDK v1\.x\. Most of the information in the Guide still applies in CDK v2, or can be adapted with only minor changes\. A v2 Developer Guide will be available at General Availability \(GA\) of CDK v2\. A version of the [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) is available for CDK v2\.
 
@@ -29,7 +29,7 @@ Most requirements for AWS CDK v2 are the same as for AWS CDK v1\.x\. See [Prereq
 
 To migrate your app to AWS CDK v2, first update the feature flags in `cdk.json`\. Then update your app's dependencies and imports as necessary for the programming language it is written in\.
 
-### Updating `cdk.json`<a name="w289aac13c11b5"></a>
+### Updating `cdk.json`<a name="w297aac13c11b5"></a>
 
 Remove all feature flags from `cdk.json`\. You can add one or more of the three flags listed below, set to `false`, if your app relies on these specific AWS CDK v1\.x behaviors\. Use the `cdk diff` command to inspect the changes to your synthesized template to see if any of these are needed\.