AWS cdk documentation change
Summary
Formatting and grammatical improvements, markdown link syntax fixes, placeholder notation changes (backticks to angle brackets), and code example corrections
Security assessment
The changes are primarily formatting and grammatical fixes. No explicit security vulnerabilities, patches, or new security features are introduced. The documentation updates clarify existing security practices (like IAM role usage) but do not add new security guidance or address specific vulnerabilities.
Diff
diff --git a/cdk/v2/guide/customize-synth.md b/cdk/v2/guide/customize-synth.md index 8398f5b6c..1e19cd241 100644 --- a//cdk/v2/guide/customize-synth.md +++ b//cdk/v2/guide/customize-synth.md @@ -15 +15 @@ The AWS CDK includes the following built-in synthesizers that you can use to cus - * `[DefaultStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html)` – If you don't specify a synthesizer, this one is used automatically. It supports cross-account deployments and deployments using the [CDK Pipelines](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html) construct. Its bootstrap contract requires an existing Amazon S3 bucket with a known name, an existing Amazon ECR repository with a known name, and five existing IAM roles with known names. The default bootstrapping template meets these requirements. + * [`DefaultStackSynthesizer`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html) – If you don’t specify a synthesizer, this one is used automatically. It supports cross-account deployments and deployments using the [CDK Pipelines](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html) construct. Its bootstrap contract requires an existing Amazon S3 bucket with a known name, an existing Amazon ECR repository with a known name, and five existing IAM roles with known names. The default bootstrapping template meets these requirements. @@ -17 +17 @@ The AWS CDK includes the following built-in synthesizers that you can use to cus - * `[CliCredentialsStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizer.html)` – This synthesizer's bootstrap contract requires an existing Amazon S3 bucket and existing Amazon ECR repository. It does not require any IAM roles. To perform deployments, this synthesizer relies on the permissions of the CDK CLI user and is recommend for organizations that want to restrict IAM deployment credentials. This synthesizer doesn't support cross-account deployments or CDK Pipelines. + * [`CliCredentialsStackSynthesizer`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizer.html) – This synthesizer’s bootstrap contract requires an existing Amazon S3 bucket and existing Amazon ECR repository. It does not require any IAM roles. To perform deployments, this synthesizer relies on the permissions of the CDK CLI user and is recommend for organizations that want to restrict IAM deployment credentials. This synthesizer doesn’t support cross-account deployments or CDK Pipelines. @@ -19 +19 @@ The AWS CDK includes the following built-in synthesizers that you can use to cus - * `[LegacyStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.LegacyStackSynthesizer.html)` – This synthesizer emulates CDK v1 synthesis behavior. Its bootstrap contract requires an existing Amazon S3 bucket of an arbitrary name and expects the locations of assets to be passed in as CloudFormation stack parameters. If you use this synthesizer, you must use the CDK CLI to perform deployment. + * [`LegacyStackSynthesizer`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.LegacyStackSynthesizer.html) – This synthesizer emulates CDK v1 synthesis behavior. Its bootstrap contract requires an existing Amazon S3 bucket of an arbitrary name and expects the locations of assets to be passed in as CloudFormation stack parameters. If you use this synthesizer, you must use the CDK CLI to perform deployment. @@ -36,8 +36,8 @@ Bootstrap resource | Description | Default expected resource name | Purpose -Amazon S3 bucket | Staging bucket | cdk-hnb659fds-assets-`ACCOUNT`-`REGION` | Stores file assets. -Amazon ECR repository | Staging repository | cdk-hnb659fds-container-assets-`ACCOUNT`-`REGION` | Stores and manages Docker image assets. -IAM role | Deploy role | cdk-hnb659fds-deploy-role-`ACCOUNT`-`REGION` | Assumed by the CDK CLI and potentially CodePipeline to assume other roles and start the AWS CloudFormation deployment. The trust policy of this role controls who can deploy with the AWS CDK in this AWS environment. -IAM role | AWS CloudFormation execution role | cdk-hnb659fds-cfn-exec-role-`ACCOUNT`-`REGION` | This role is used by AWS CloudFormation to perform the deployment. The policies of this role control what operations the CDK deployment can perform. -IAM role | Lookup role | cdk-hnb659fds-lookup-role-`ACCOUNT`-`REGION` | This role is used when the CDK CLI needs to perform environmental context lookups. The trust policy of this role controls who can look up information in the environment. -IAM role | File publishing role | cdk-hnb659fds-file-publishing-role-`ACCOUNT`-`REGION` | This role is used to upload assets to the Amazon S3 staging bucket. It is assumed from the deploy role. -IAM role | Image publishing role | cdk-hnb659fds-image-publishing-role-`ACCOUNT`-`REGION` | This role is used to upload Docker images to the Amazon ECR staging repository. It is assumed from the deploy role. -SSM parameter | Bootstrap version parameter | /cdk-bootstrap/hnb659fds/`version` | The version of the bootstrap template. It is used by the bootstrap template and the CDK CLI to validate requirements. +Amazon S3 bucket | Staging bucket | cdk-hnb659fds-assets-<ACCOUNT>-<REGION> | Stores file assets. +Amazon ECR repository | Staging repository | cdk-hnb659fds-container-assets-<ACCOUNT>-<REGION> | Stores and manages Docker image assets. +IAM role | Deploy role | cdk-hnb659fds-deploy-role-<ACCOUNT>-<REGION> | Assumed by the CDK CLI and potentially CodePipeline to assume other roles and start the AWS CloudFormation deployment. The trust policy of this role controls who can deploy with the AWS CDK in this AWS environment. +IAM role | AWS CloudFormation execution role | cdk-hnb659fds-cfn-exec-role-<ACCOUNT>-<REGION> | This role is used by AWS CloudFormation to perform the deployment. The policies of this role control what operations the CDK deployment can perform. +IAM role | Lookup role | cdk-hnb659fds-lookup-role-<ACCOUNT>-<REGION> | This role is used when the CDK CLI needs to perform environmental context lookups. The trust policy of this role controls who can look up information in the environment. +IAM role | File publishing role | cdk-hnb659fds-file-publishing-role-<ACCOUNT>-<REGION> | This role is used to upload assets to the Amazon S3 staging bucket. It is assumed from the deploy role. +IAM role | Image publishing role | cdk-hnb659fds-image-publishing-role-<ACCOUNT>-<REGION> | This role is used to upload Docker images to the Amazon ECR staging repository. It is assumed from the deploy role. +SSM parameter | Bootstrap version parameter | /cdk-bootstrap/hnb659fds/<version> | The version of the bootstrap template. It is used by the bootstrap template and the CDK CLI to validate requirements. @@ -45 +45 @@ SSM parameter | Bootstrap version parameter | /cdk-bootstrap/hnb659fds/`versio -One way to customize CDK stack synthesis, is by modifying the `[DefaultStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html)`. You can customize this synthesizer for a single CDK stack using the `synthesizer` property of your `Stack` instance. You can also modify `DefaultStackSynthesizer` for all stacks in your CDK app using the `defaultStackSynthesizer` property of your `App` instance. +One way to customize CDK stack synthesis, is by modifying the [`DefaultStackSynthesizer`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html). You can customize this synthesizer for a single CDK stack using the `synthesizer` property of your `Stack` instance. You can also modify `DefaultStackSynthesizer` for all stacks in your CDK app using the `defaultStackSynthesizer` property of your `App` instance. @@ -92,0 +93 @@ Java + ) @@ -140 +141 @@ All of the other `DefaultStackSynthesizer` properties relate to the names of the -All properties accept the special placeholders `${Qualifier}`, `${AWS::Partition}`, `${AWS::AccountId}`, and `${AWS::Region}`. These placeholders are replaced with the values of the `qualifier` parameter and the AWS partition, account ID, and AWS Region values for the stack's environment, respectively. +All properties accept the special placeholders `${Qualifier}`, `${AWS::Partition}`, `${AWS::AccountId}`, and `${AWS::Region}`. These placeholders are replaced with the values of the `qualifier` parameter and the AWS partition, account ID, and AWS Region values for the stack’s environment, respectively. @@ -142 +143 @@ All properties accept the special placeholders `${Qualifier}`, `${AWS::Partition -The following example shows the most commonly used properties for `DefaultStackSynthesizer` along with their default values, as if you were instantiating the synthesizer. For a complete list, see [DefaultStackSynthesizerProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizerProps.html#properties): +The following example shows the most commonly used properties for `DefaultStackSynthesizer` along with their default values, as if you were instantiating the synthesizer. For a complete list, see [`DefaultStackSynthesizerProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizerProps.html#properties): @@ -342 +342 @@ C# -To modify the security credentials used to provide permissions during CDK deployments, you can customize synthesis by using `[CliCredentialsStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizer.html)`. This synthesizer works with the default AWS resources that are created during bootstrapping to store assets, such as the Amazon S3 bucket and Amazon ECR repository. Instead of using the default IAM roles created by the CDK during bootstrapping, it uses the security credentials of the actor initiating deployment. Therefore, the security credentials of the actor must have valid permissions to perform all deployment actions. The following diagram illustrates the deployment process when using this synthesizer: +To modify the security credentials used to provide permissions during CDK deployments, you can customize synthesis by using [`CliCredentialsStackSynthesizer`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizer.html). This synthesizer works with the default AWS resources that are created during bootstrapping to store assets, such as the Amazon S3 bucket and Amazon ECR repository. Instead of using the default IAM roles created by the CDK during bootstrapping, it uses the security credentials of the actor initiating deployment. Therefore, the security credentials of the actor must have valid permissions to perform all deployment actions. The following diagram illustrates the deployment process when using this synthesizer: @@ -344 +344 @@ To modify the security credentials used to provide permissions during CDK deploy - + @@ -357 +357 @@ When using `CliCredentialsStackSynthesizer`: -When using this synthesizer, you can use a separate CloudFormation execution role by specifying it using the `[--role-arn](./ref-cli-cmd.html#ref-cli-cmd-options-role-arn)` option with any CDK CLI command. +When using this synthesizer, you can use a separate CloudFormation execution role by specifying it using the [\--role-arn](./ref-cli-cmd.html#ref-cli-cmd-options-role-arn) option with any CDK CLI command. @@ -365,2 +365,2 @@ Bootstrap resource | Description | Default expected resource name | Purpose -Amazon S3 bucket | Staging bucket | cdk-hnb659fds-assets-`ACCOUNT`-`REGION` | Stores file assets. -Amazon ECR repository | Staging repository | cdk-hnb659fds-container-assets-`ACCOUNT`-`REGION` | Stores and manages Docker image assets. +Amazon S3 bucket | Staging bucket | cdk-hnb659fds-assets-<ACCOUNT>-<REGION> | Stores file assets. +Amazon ECR repository | Staging repository | cdk-hnb659fds-container-assets-<ACCOUNT>-<REGION> | Stores and manages Docker image assets. @@ -413,0 +414 @@ Java + ) @@ -427 +428 @@ C# -The following example shows the most commonly used properties for `CliCredentialsStackSynthesizer` along with their default values. For a complete list, see [CliCredentialsStackSynthesizerProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizerProps.html): +The following example shows the most commonly used properties for `CliCredentialsStackSynthesizer` along with their default values. For a complete list, see [`CliCredentialsStackSynthesizerProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CliCredentialsStackSynthesizerProps.html): @@ -521 +521 @@ The `LegacyStackSynthesizer` emulates the behavior of CDK v1 deployments. The se -You can use the `LegacyStackSynthesizer` if you are migrating from CDK v1 to CDK v2, and are unable to re-bootstrap your environments. For new projects, we recommend that you don't use `LegacyStackSynthesizer`. +You can use the `LegacyStackSynthesizer` if you are migrating from CDK v1 to CDK v2, and are unable to re-bootstrap your environments. For new projects, we recommend that you don’t use `LegacyStackSynthesizer`. @@ -529 +529 @@ Bootstrap resource | Description | Default expected resource name | Purpose -Amazon S3 bucket | Staging bucket | cdk-hnb659fds-assets-`ACCOUNT`-`REGION` | Stores file assets. +Amazon S3 bucket | Staging bucket | cdk-hnb659fds-assets-<ACCOUNT>-<REGION> | Stores file assets. @@ -550 +550 @@ When you use this synthesizer, the following process is performed during deploym - * If necessary, and if permissions are valid, Docker image assets are published to the repository named by the `repositoryName` property of the asset. The default value is `'aws-cdk/assets'` if you don't provide a repository name. + * If necessary, and if permissions are valid, Docker image assets are published to the repository named by the `repositoryName` property of the asset. The default value is `'aws-cdk/assets'` if you don’t provide a repository name.