add information about importing IAM resources (plus some ID churn)

mbeacom · Apr 28, 2022 · 58c8c9c · 58c8c9c
1 parent 81ed625
commit 58c8c9c
Show file tree

Hide file tree

Showing 10 changed files with 76 additions and 42 deletions.
diff --git a/v1/cli.md b/v1/cli.md
@@ -349,7 +349,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="w303aac31b7c35c11"></a>
+### Specifying context values<a name="w314aac31b7c35c11"></a>
 
 Use the `--context` or `-c` option to pass [runtime context](context.md) values to your CDK app\.
 
@@ -368,15 +368,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="w303aac31b7c35c13"></a>
+### Specifying display format<a name="w314aac31b7c35c13"></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="w303aac31b7c35c15"></a>
+### Specifying output directory<a name="w314aac31b7c35c15"></a>
 
 Add the `--output` \(`-o`\) option to write the synthesized templates to a directory other than `cdk.out`\.
 
@@ -444,7 +444,7 @@ Git\-style wildcards, both `*` and `**`, can be used in the `"watch"` and `"buil
 **Important**  
 Watch mode is not recommended for production deployments\.
 
-### Specifying AWS CloudFormation parameters<a name="w303aac31b7c37c17"></a>
+### Specifying AWS CloudFormation parameters<a name="w314aac31b7c37c17"></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\.
 
@@ -466,7 +466,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="w303aac31b7c37c19"></a>
+### Specifying outputs file<a name="w314aac31b7c37c19"></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\.
 
@@ -723,7 +723,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="w303aac31b7c43b7b1"></a>
+### `cdk list` \(`ls`\)<a name="w314aac31b7c43b7b1"></a>
 
 ```
 cdk list [STACKS..]
@@ -736,7 +736,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk synthesize` \(`synth`\)<a name="w303aac31b7c43b7b3"></a>
+### `cdk synthesize` \(`synth`\)<a name="w314aac31b7c43b7b3"></a>
 
 ```
 cdk synthesize [STACKS..]
@@ -757,7 +757,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk bootstrap`<a name="w303aac31b7c43b7b5"></a>
+### `cdk bootstrap`<a name="w314aac31b7c43b7b5"></a>
 
 ```
 cdk bootstrap [ENVIRONMENTS..]
@@ -837,7 +837,7 @@ Options:
                                             example)                    [string]
 ```
 
-### `cdk deploy`<a name="w303aac31b7c43b7b7"></a>
+### `cdk deploy`<a name="w314aac31b7c43b7b7"></a>
 
 ```
 cdk deploy [STACKS..]
@@ -915,7 +915,7 @@ Options:
                                                        [boolean] [default: true]
 ```
 
-### `cdk destroy`<a name="w303aac31b7c43b7b9"></a>
+### `cdk destroy`<a name="w314aac31b7c43b7b9"></a>
 
 ```
 cdk destroy [STACKS..]
@@ -934,7 +934,7 @@ Options:
                            stacks                                      [boolean]
 ```
 
-### `cdk diff`<a name="w303aac31b7c43b7c11"></a>
+### `cdk diff`<a name="w314aac31b7c43b7c11"></a>
 
 ```
 cdk diff [STACKS..]
@@ -960,7 +960,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk init`<a name="w303aac31b7c43b7c13"></a>
+### `cdk init`<a name="w314aac31b7c43b7c13"></a>
 
 ```
 cdk init [TEMPLATE]
@@ -982,7 +982,7 @@ Options:
                            project                    [boolean] [default: false]
 ```
 
-### `cdk context`<a name="w303aac31b7c43b7c15"></a>
+### `cdk context`<a name="w314aac31b7c43b7c15"></a>
 
 ```
 cdk context

diff --git a/v1/manage-dependencies.md b/v1/manage-dependencies.md
@@ -31,7 +31,7 @@ If you prefer, you may use Yarn in place of NPM\. However, the CDK does not supp
 nodeLinker: node-modules
 ```
 
-### Applications<a name="w303aac15c13c11"></a>
+### Applications<a name="w314aac15c13c11"></a>
 
 The following is an example `package.json` generated by cdk init \-\-language typescript\. The file generated for JavaScript is similar, just without the TypeScript\-related entries\.
 
@@ -72,7 +72,7 @@ All AWS CDK dependencies must have the same version\.
 
 Specify versions of libraries and tools needed to test your app \(for example, the `jest` testing framework\) in the `devDependencies` section of `package.json`\. Optionally, use ^ to specify that later compatible versions are acceptable\.
 
-### Construct libraries<a name="w303aac15c13c13"></a>
+### Construct libraries<a name="w314aac15c13c13"></a>
 
 If you're developing a construct library, specify its dependencies via a combination of the `peerDependencies` and `devDependencies` sections, as shown in the following example `package.json` file\.
 
@@ -99,7 +99,7 @@ In `devDependencies`, specify the tools and libraries you need for testing, opti
 **Warning**  
 `peerDependencies` are installed automatically only by NPM 7 and later\. If you are using NPM 6 or earlier, or if you are using Yarn, you must include the dependencies of your dependencies in `devDependencies`, or they will not be installed, and you will receive a warning about unresolved peer dependencies
 
-### Installing and updating dependencies<a name="w303aac15c13c17"></a>
+### Installing and updating dependencies<a name="w314aac15c13c17"></a>
 
 Run the following command to install your project's dependencies\.
 
@@ -145,7 +145,7 @@ The python \-m pip invocation works on most systems; pip requires that PIP's exe
 
 cdk init \-\-language python creates a virtual environment for your new project, which allows each project to have its own versions of dependencies, as well as a basic `requirements.txt` file\. You must activate this virtual environment \(source \.venv/bin/activate\) each time you begin working with the project\.
 
-### Applications<a name="w303aac15c15c11"></a>
+### Applications<a name="w314aac15c15c11"></a>
 
 An example `requirements.txt` follows\. Because PIP does not have a dependency\-locking feature, we recommend that you use the == operator to specify exact versions for all dependencies, as shown here\.
 
@@ -169,7 +169,7 @@ python -m pip install -r requirements.txt
 **Tip**  
 The pip freeze command outputs the versions of all installed dependencies in a format that can be written to a text file and used as a requirements file with `pip install -r`\. This file is convenient for pinning all dependencies \(indluding transitive ones\) to the exact versions you tested with\. To avoid problems when upgrading packages later, use a separate file for this, e\.g\. `freeze.txt` not `requirements.txt`, and regenerate it when you upgrade your project's dependencies\.
 
-### Construct libraries<a name="w303aac15c15c13"></a>
+### Construct libraries<a name="w314aac15c15c13"></a>
 
 In libraries, dependencies are specified in `setup.py`, so that transitive dependencies are automatically downloaded when the package is consumed by an application\. Otherwise, every application that wants to use your package needs to copy your dependencies into their `requirements.txt`\. An example `setup.py` is shown here\.
 

diff --git a/v1/permissions.md b/v1/permissions.md
@@ -486,4 +486,21 @@ bucket.AddToResourcePolicy(new PolicyStatement(new PolicyStatementProps
 }));
 ```
 
-------
+------
+
+## Using external IAM objects<a name="permissions_existing"></a>
+
+If you have defined an IAM user, principal, group, or role outside your AWS CDK app, you can use that IAM object in your AWS CDK app by creating a reference to it using its ARN or \(for users, groups, and roles\) its name\. The returned reference can then be used to grant permissions or to construct policy statements as explained above\.
++ For users, call `[User\.fromUserArn\(\)](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.User.html#static-fromwbruserwbrarnscope-id-userarn)` or `[User\.fromUserName\(\)](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.User.html#static-fromwbruserwbrnamescope-id-username)`\. `User.fromUserAttributes()` is also available, but currently provides the same functionality as `User.fromUserArn()`\.
++ For principals, instantiate an `[ArnPrincipal](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.ArnPrincipal.html)` object\.
++ For groups, call `[Group\.fromGroupArn\(\)](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.Group.html#static-fromwbrgroupwbrarnscope-id-grouparn)` or `[Group\.fromGroupName\(\)](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.Group.html#static-fromwbrgroupwbrnamescope-id-groupname)`\.
++ For roles, call `[Role\.fromRoleArn\(\)](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.Role.html#static-fromwbrrolewbrarnscope-id-rolearn-options)` or `[Role\.fromRoleName\(\)](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.Role.html#static-fromwbrrolewbrnamescope-id-rolename)`\.
+
+Policies \(including managed policies\) can be imported in similar fashion using the methods listed below\. You can use references to these objects anywhere an IAM policy is required\.
++ `[Policy\.fromPolicyName](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.Policy.html#static-fromwbrpolicywbrnamescope-id-policyname)`
++ `[ManagedPolicy\.fromManagedPolicyArn](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrarnscope-id-managedpolicyarn)`
++ `[ManagedPolicy\.fromManagedPolicyName](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.ManagedPolicy.html#static-fromwbrmanagedwbrpolicywbrnamescope-id-managedpolicyname)`
++ `[ManagedPolicy\.fromAwsManagedPolicyName](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-iam.ManagedPolicy.html#static-fromwbrawswbrmanagedwbrpolicywbrnamemanagedpolicyname)`
+
+**Note**  
+As with all references to external AWS resources, you cannot modify imported IAM objects in your CDK app\.
diff --git a/v1/tagging.md b/v1/tagging.md
@@ -92,7 +92,7 @@ Tags.Of(myConstruct).Remove("key");
 
 If you are using `Stage` constructs, apply the tag at the `Stage` level or below\. Tags are not applied across `Stage` boundaries\.
 
-## Tag priorities<a name="w303aac21c23c23"></a>
+## Tag priorities<a name="w314aac21c23c23"></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\. 
 

diff --git a/v1/use_cfn_template.md b/v1/use_cfn_template.md
@@ -56,7 +56,7 @@ dotnet add package Amazon.CDK.CloudFormation.Include
 
 ------
 
-## Importing an AWS CloudFormation template<a name="w303aac29b9c11"></a>
+## Importing an AWS CloudFormation template<a name="w314aac29b9c11"></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\.
 

diff --git a/v2/cli.md b/v2/cli.md
@@ -341,7 +341,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="w306aac31b7c31c11"></a>
+### Specifying context values<a name="w317aac31b7c31c11"></a>
 
 Use the `--context` or `-c` option to pass [runtime context](context.md) values to your CDK app\.
 
@@ -360,15 +360,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="w306aac31b7c31c13"></a>
+### Specifying display format<a name="w317aac31b7c31c13"></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="w306aac31b7c31c15"></a>
+### Specifying output directory<a name="w317aac31b7c31c15"></a>
 
 Add the `--output` \(`-o`\) option to write the synthesized templates to a directory other than `cdk.out`\.
 
@@ -436,7 +436,7 @@ Git\-style wildcards, both `*` and `**`, can be used in the `"watch"` and `"buil
 **Important**  
 Watch mode is not recommended for production deployments\.
 
-### Specifying AWS CloudFormation parameters<a name="w306aac31b7c33c17"></a>
+### Specifying AWS CloudFormation parameters<a name="w317aac31b7c33c17"></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\.
 
@@ -458,7 +458,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="w306aac31b7c33c19"></a>
+### Specifying outputs file<a name="w317aac31b7c33c19"></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\.
 
@@ -715,7 +715,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="w306aac31b7c39b7b1"></a>
+### `cdk list` \(`ls`\)<a name="w317aac31b7c39b7b1"></a>
 
 ```
 cdk list [STACKS..]
@@ -728,7 +728,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk synthesize` \(`synth`\)<a name="w306aac31b7c39b7b3"></a>
+### `cdk synthesize` \(`synth`\)<a name="w317aac31b7c39b7b3"></a>
 
 ```
 cdk synthesize [STACKS..]
@@ -749,7 +749,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk bootstrap`<a name="w306aac31b7c39b7b5"></a>
+### `cdk bootstrap`<a name="w317aac31b7c39b7b5"></a>
 
 ```
 cdk bootstrap [ENVIRONMENTS..]
@@ -829,7 +829,7 @@ Options:
                                             example)                    [string]
 ```
 
-### `cdk deploy`<a name="w306aac31b7c39b7b7"></a>
+### `cdk deploy`<a name="w317aac31b7c39b7b7"></a>
 
 ```
 cdk deploy [STACKS..]
@@ -907,7 +907,7 @@ Options:
                                                        [boolean] [default: true]
 ```
 
-### `cdk destroy`<a name="w306aac31b7c39b7b9"></a>
+### `cdk destroy`<a name="w317aac31b7c39b7b9"></a>
 
 ```
 cdk destroy [STACKS..]
@@ -926,7 +926,7 @@ Options:
                            stacks                                      [boolean]
 ```
 
-### `cdk diff`<a name="w306aac31b7c39b7c11"></a>
+### `cdk diff`<a name="w317aac31b7c39b7c11"></a>
 
 ```
 cdk diff [STACKS..]
@@ -952,7 +952,7 @@ Options:
                                                       [boolean] [default: false]
 ```
 
-### `cdk init`<a name="w306aac31b7c39b7c13"></a>
+### `cdk init`<a name="w317aac31b7c39b7c13"></a>
 
 ```
 cdk init [TEMPLATE]
@@ -974,7 +974,7 @@ Options:
                            project                    [boolean] [default: false]
 ```
 
-### `cdk context`<a name="w306aac31b7c39b7c15"></a>
+### `cdk context`<a name="w317aac31b7c39b7c15"></a>
 
 ```
 cdk context

diff --git a/v2/manage-dependencies.md b/v2/manage-dependencies.md
@@ -31,7 +31,7 @@ If you prefer, you may use Yarn in place of NPM\. However, the CDK does not supp
 nodeLinker: node-modules
 ```
 
-### Applications<a name="w306aac15c13c11"></a>
+### Applications<a name="w317aac15c13c11"></a>
 
 The following is an example `package.json` generated by cdk init \-\-language typescript\. The file generated for JavaScript is similar, just without the TypeScript\-related entries\.
 
@@ -71,7 +71,7 @@ Specify exact versions for alpha construct library modules, which have APIs that
 
 Specify versions of libraries and tools needed to test your app \(for example, the `jest` testing framework\) in the `devDependencies` section of `package.json`\. Optionally, use ^ to specify that later compatible versions are acceptable\.
 
-### Construct libraries<a name="w306aac15c13c13"></a>
+### Construct libraries<a name="w317aac15c13c13"></a>
 
 If you're developing a construct library, specify its dependencies via a combination of the `peerDependencies` and `devDependencies` sections, as shown in the following example `package.json` file\.
 
@@ -101,7 +101,7 @@ In `devDependencies`, specify the tools and libraries you need for testing, opti
 **Warning**  
 `peerDependencies` are installed automatically only by NPM 7 and later\. If you are using NPM 6 or earlier, or if you are using Yarn, you must include the dependencies of your dependencies in `devDependencies`, or they will not be installed, and you will receive a warning about unresolved peer dependencies
 
-### Installing and updating dependencies<a name="w306aac15c13c17"></a>
+### Installing and updating dependencies<a name="w317aac15c13c17"></a>
 
 Run the following command to install your project's dependencies\.
 
@@ -147,7 +147,7 @@ The python \-m pip invocation works on most systems; pip requires that PIP's exe
 
 cdk init \-\-language python creates a virtual environment for your new project, which allows each project to have its own versions of dependencies, as well as a basic `requirements.txt` file\. You must activate this virtual environment \(source \.venv/bin/activate\) each time you begin working with the project\.
 
-### Applications<a name="w306aac15c15c11"></a>
+### Applications<a name="w317aac15c15c11"></a>
 
 An example `requirements.txt` follows\. Because PIP does not have a dependency\-locking feature, we recommend that you use the == operator to specify exact versions for all dependencies, as shown here\.
 
@@ -167,7 +167,7 @@ python -m pip install -r requirements.txt
 **Tip**  
 The pip freeze command outputs the versions of all installed dependencies in a format that can be written to a text file and used as a requirements file with `pip install -r`\. This file is convenient for pinning all dependencies \(indluding transitive ones\) to the exact versions you tested with\. To avoid problems when upgrading packages later, use a separate file for this, e\.g\. `freeze.txt` not `requirements.txt`, and regenerate it when you upgrade your project's dependencies\.
 
-### Construct libraries<a name="w306aac15c15c13"></a>
+### Construct libraries<a name="w317aac15c15c13"></a>
 
 In libraries, dependencies are specified in `setup.py`, so that transitive dependencies are automatically downloaded when the package is consumed by an application\. Otherwise, every application that wants to use your package needs to copy your dependencies into their `requirements.txt`\. An example `setup.py` is shown here\.
-Original file line number
+Diff line change
@@ Expand Up / @@ -56,7 +56,7 @@ dotnet add package Amazon.CDK.CloudFormation.Include @@
     ------
-    ## Importing an AWS CloudFormation template<a name="w303aac29b9c11"></a>
+    ## Importing an AWS CloudFormation template<a name="w314aac29b9c11"></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\.
@@ Expand Down @@