add info on breaking deadlock on shared resources

doc_source/cli.md

@@ -289,7 +289,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="w335aac23b7c31c11"></a>
+### Specifying context values<a name="w337aac23b7c31c11"></a>
 
 Use the `--context` or `-c` option to pass [runtime context](context.md) values to your CDK app\.
 
@@ -308,15 +308,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="w335aac23b7c31c13"></a>
+### Specifying display format<a name="w337aac23b7c31c13"></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="w335aac23b7c31c15"></a>
+### Specifying output directory<a name="w337aac23b7c31c15"></a>
 
 Add the `--output` \(`-o`\) option to write the synthesized templates to a directory other than `cdk.out`\.
 
@@ -340,7 +340,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="w335aac23b7c33c11"></a>
+### Specifying AWS CloudFormation parameters<a name="w337aac23b7c33c11"></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\.
 
@@ -362,7 +362,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="w335aac23b7c33c13"></a>
+### Specifying outputs file<a name="w337aac23b7c33c13"></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\.
 
@@ -557,7 +557,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="w335aac23b7c39b7b1"></a>
+### `cdk list` \(`ls`\)<a name="w337aac23b7c39b7b1"></a>
 
 ```
 cdk list [STACKS..]
@@ -570,7 +570,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk synthesize` \(`synth`\)<a name="w335aac23b7c39b7b3"></a>
+### `cdk synthesize` \(`synth`\)<a name="w337aac23b7c39b7b3"></a>
 
 ```
 cdk synthesize [STACKS..]
@@ -586,7 +586,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk bootstrap`<a name="w335aac23b7c39b7b5"></a>
+### `cdk bootstrap`<a name="w337aac23b7c39b7b5"></a>
 
 ```
 cdk bootstrap [ENVIRONMENTS..]
@@ -655,7 +655,7 @@ Options:
                                             example)                    [string]
 ```
 
-### `cdk deploy`<a name="w335aac23b7c39b7b7"></a>
+### `cdk deploy`<a name="w337aac23b7c39b7b7"></a>
 
 ```
 cdk deploy [STACKS..]
@@ -705,7 +705,7 @@ Options:
                                              [string] [choices: "bar", "events"]
 ```
 
-### `cdk destroy`<a name="w335aac23b7c39b7b9"></a>
+### `cdk destroy`<a name="w337aac23b7c39b7b9"></a>
 
 ```
 cdk destroy [STACKS..]
@@ -724,7 +724,7 @@ Options:
                             stacks                                     [boolean]
 ```
 
-### `cdk diff`<a name="w335aac23b7c39b7c11"></a>
+### `cdk diff`<a name="w337aac23b7c39b7c11"></a>
 
 ```
 cdk diff [STACKS..]
@@ -744,7 +744,7 @@ Options:
                             with                                        [string]
 ```
 
-### `cdk init`<a name="w335aac23b7c39b7c13"></a>
+### `cdk init`<a name="w337aac23b7c39b7c13"></a>
 
 ```
 cdk init [TEMPLATE]
@@ -766,7 +766,7 @@ Options:
                             project                   [boolean] [default: false]
 ```
 
-### `cdk context`<a name="w335aac23b7c39b7c15"></a>
+### `cdk context`<a name="w337aac23b7c39b7c15"></a>
 
 ```
 cdk context

doc_source/resources.md

@@ -263,6 +263,10 @@ var stack2 = new StackThatExpectsABucket(app, "Stack2", new StackProps { Env = p
 
 If the AWS CDK determines that the resource is in the same account and Region, but in a different stack, it automatically synthesizes AWS CloudFormation [exports](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-exports.html) in the producing stack and an [Fn::ImportValue](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html) in the consuming stack to transfer that information from one stack to the other\.
 
+Referencing a resource from one stack in a different stack creates a dependency between the two stacks,\. Once this dependency is established, removing the use of the shared resource from the consuming stack can cause an unexpected deployment failure if the AWS CDK Toolkit deploys the producing stack before the consuming stack\. This happens if there is another dependency between the two stacks, but it can also happen that the producing stack is chosen by the AWS CDK Toolkit to be deployed first\. The AWS CloudFormation export is removed from the producing stack because it is no longer needed, but the exported resource is still being used in the consuming stack because its update has not yet been deployed, so deploying the producer stack fails\.
+
+To break this deadlock, remove the use of the shared resource from the consuming stack \(which will remove the automatic export from the producing stack\), then manually add the same export to the producing stack using exactly the same logical ID as the automatically\-generated export\. Remove the use of the shared resource in the consuming stack and deploy both stacks\. Then remove the manual export \(and the shared resource if it is no longer nededed\), and deploy both stacks again\. The stack's `[exportValue\(\)](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_core.Stack.html#exportwbrvalueexportedvalue-options)` method is a convenient way to create the manual export for this purpose \(see the example in the linked method reference\)\.
+
 ## Physical names<a name="resources_physical_names"></a>
 
 The logical names of resources in AWS CloudFormation are different from the names of resources that are shown in the AWS Management Console after AWS CloudFormation has deployed the resources\. The AWS CDK calls these final names *physical names*\.

doc_source/tagging.md

@@ -90,7 +90,7 @@ Tags.Of(myConstruct).Remove("key");
 
 ------
 
-## Tag priorities<a name="w335aac15c23c21"></a>
+## Tag priorities<a name="w337aac15c23c21"></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="w335aac21b9b7"></a>
+## Importing an AWS CloudFormation template<a name="w337aac21b9b7"></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\.