AWS cdk high security documentation change
Summary
Updated documentation with formatting changes, placeholder syntax improvements, removed 'Security notes' section, and corrected CLI command examples.
Security assessment
The removal of the 'Security notes' topic eliminates existing security guidance, which could lead to misconfigurations if users are unaware of critical security practices. This is direct evidence of reducing security documentation.
Diff
diff --git a/cdk/v2/guide/cdk-pipeline.md b/cdk/v2/guide/cdk-pipeline.md index faaecf514..00689776e 100644 --- a//cdk/v2/guide/cdk-pipeline.md +++ b//cdk/v2/guide/cdk-pipeline.md @@ -11 +11 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -Use the [CDK Pipelines](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html) module from the AWS Construct Library to configure continuous delivery of AWS CDK applications. When you commit your CDK app's source code into AWS CodeCommit, GitHub, or AWS CodeStar, CDK Pipelines can automatically build, test, and deploy your new version. +Use the [CDK Pipelines](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html) module from the AWS Construct Library to configure continuous delivery of AWS CDK applications. When you commit your CDK app’s source code into AWS CodeCommit, GitHub, or AWS CodeStar, CDK Pipelines can automatically build, test, and deploy your new version. @@ -19,19 +18,0 @@ CDK Pipelines supports two APIs. One is the original API that was made available -###### Topics - - * Bootstrap your AWS environments - - * Initialize a project - - * Define a pipeline - - * Application stages - - * Testing deployments - - * Security notes - - * Troubleshooting - - - - @@ -42 +23 @@ Before you can use CDK Pipelines, you must bootstrap the AWS [environment](./env -A CDK Pipeline involves at least two environments. The first environment is where the pipeline is provisioned. The second environment is where you want to deploy the application's stacks or stages to (stages are groups of related stacks). These environments can be the same, but a best practice recommendation is to isolate stages from each other in different environments. +A CDK Pipeline involves at least two environments. The first environment is where the pipeline is provisioned. The second environment is where you want to deploy the application’s stacks or stages to (stages are groups of related stacks). These environments can be the same, but a best practice recommendation is to isolate stages from each other in different environments. @@ -73 +54 @@ macOS/Linux - npx cdk bootstrap aws://ACCOUNT-NUMBER/REGION --profile ADMIN-PROFILE \ + npx cdk bootstrap aws://<ACCOUNT-NUMBER>/<REGION> --profile <ADMIN-PROFILE> \ @@ -80 +61 @@ Windows - npx cdk bootstrap aws://ACCOUNT-NUMBER/REGION --profile ADMIN-PROFILE ^ + npx cdk bootstrap aws://<ACCOUNT-NUMBER></REGION> --profile< ADMIN-PROFILE> ^ @@ -83 +64 @@ Windows -To bootstrap additional environments into which AWS CDK applications will be deployed by the pipeline, use the following commands instead. The `--trust` option indicates which other account should have permissions to deploy AWS CDK applications into this environment. For this option, specify the pipeline's AWS account ID. +To bootstrap additional environments into which AWS CDK applications will be deployed by the pipeline, use the following commands instead. The `--trust` option indicates which other account should have permissions to deploy AWS CDK applications into this environment. For this option, specify the pipeline’s AWS account ID. @@ -91 +72 @@ macOS/Linux - npx cdk bootstrap aws://ACCOUNT-NUMBER/REGION --profile ADMIN-PROFILE \ + npx cdk bootstrap aws://<ACCOUNT-NUMBER>/<REGION> --profile <ADMIN-PROFILE> \ @@ -93 +74 @@ macOS/Linux - --trust PIPELINE-ACCOUNT-NUMBER + --trust <PIPELINE-ACCOUNT-NUMBER> @@ -99 +80 @@ Windows - npx cdk bootstrap aws://ACCOUNT-NUMBER/REGION --profile ADMIN-PROFILE ^ + npx cdk bootstrap aws://<ACCOUNT-NUMBER>/<REGION> --profile <ADMIN-PROFILE> ^ @@ -101 +82 @@ Windows - --trust PIPELINE-ACCOUNT-NUMBER + --trust <PIPELINE-ACCOUNT-NUMBER> @@ -119,2 +99,0 @@ After enabling termination protection, you can use the AWS CLI or CloudFormation -###### To enable termination protection - @@ -127 +106 @@ After enabling termination protection, you can use the AWS CLI or CloudFormation - $ aws cloudformation describe-stacks --stack-name CDKToolkit --query "Stacks[0].EnableTerminationProtection" + $ aws cloudformation describe-stacks --stack-name <CDKToolkit> --query "Stacks[0].EnableTerminationProtection" @@ -138 +117 @@ Create a new, empty GitHub project and clone it to your workstation in the `my-p - git clone GITHUB-CLONE-URL my-pipeline + git clone <GITHUB-CLONE-URL> my-pipeline @@ -143 +122 @@ Create a new, empty GitHub project and clone it to your workstation in the `my-p -You can use a name other than `my-pipeline` for your app's main directory. However, if you do so, you will have to tweak the file and class names later in this topic. This is because the AWS CDK Toolkit bases some file and class names on the name of the main directory. +You can use a name other than `my-pipeline` for your app’s main directory. However, if you do so, you will have to tweak the file and class names later in this topic. This is because the AWS CDK Toolkit bases some file and class names on the name of the main directory. @@ -165 +144 @@ Python -After the app has been created, also enter the following two commands. These activate the app's Python virtual environment and install the AWS CDK core dependencies. +After the app has been created, also enter the following two commands. These activate the app’s Python virtual environment and install the AWS CDK core dependencies. @@ -200 +179 @@ After the app has been created, also enter the following command to install the -Be sure to commit your `cdk.json` and `cdk.context.json` files to 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 unexpected changes in your results. For more information, see [Context values and the AWS CDK](./context.html). +Be sure to commit your `cdk.json` and `cdk.context.json` files to 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 unexpected changes in your results. For more information, see [Context values and the AWS CDK](./context.html). @@ -204 +183 @@ Be sure to commit your `cdk.json` and `cdk.context.json` files to source control -Your CDK Pipelines application will include at least two stacks: one that represents the pipeline itself, and one or more stacks that represent the application deployed through it. Stacks can also be grouped into _stages_ , which you can use to deploy copies of infrastructure stacks to different environments. For now, we'll consider the pipeline, and later delve into the application it will deploy. +Your CDK Pipelines application will include at least two stacks: one that represents the pipeline itself, and one or more stacks that represent the application deployed through it. Stacks can also be grouped into _stages_ , which you can use to deploy copies of infrastructure stacks to different environments. For now, we’ll consider the pipeline, and later delve into the application it will deploy. @@ -206 +185 @@ Your CDK Pipelines application will include at least two stacks: one that repres -The construct [`CodePipeline`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.CodePipeline.html) is the construct that represents a CDK Pipeline that uses AWS CodePipeline as its deployment engine. When you instantiate `CodePipeline` in a stack, you define the source location for the pipeline (such as a GitHub repository). You also define the commands to build the app. +The construct ` [CodePipeline](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.CodePipeline.html) ` is the construct that represents a CDK Pipeline that uses AWS CodePipeline as its deployment engine. When you instantiate `CodePipeline` in a stack, you define the source location for the pipeline (such as a GitHub repository). You also define the commands to build the app. @@ -214 +193 @@ By default, the pipeline authenticates to GitHub using a personal access token s -You'll also need to update the instantiation of the pipeline stack to specify the AWS account and Region. +You’ll also need to update the instantiation of the pipeline stack to specify the AWS account and Region. @@ -219 +198 @@ TypeScript -In `lib/my-pipeline-stack.ts` (may vary if your project folder isn't named `my-pipeline`): +In `lib/my-pipeline-stack.ts` (may vary if your project folder isn’t named `my-pipeline`): @@ -240 +219 @@ In `lib/my-pipeline-stack.ts` (may vary if your project folder isn't named `my-p -In `bin/my-pipeline.ts` (may vary if your project folder isn't named `my-pipeline`): +In `bin/my-pipeline.ts` (may vary if your project folder isn’t named `my-pipeline`): @@ -260 +239 @@ JavaScript -In `lib/my-pipeline-stack.js` (may vary if your project folder isn't named `my-pipeline`): +In `lib/my-pipeline-stack.js` (may vary if your project folder isn’t named `my-pipeline`): @@ -282 +261 @@ In `lib/my-pipeline-stack.js` (may vary if your project folder isn't named `my-p -In `bin/my-pipeline.js` (may vary if your project folder isn't named `my-pipeline`): +In `bin/my-pipeline.js` (may vary if your project folder isn’t named `my-pipeline`): @@ -303 +282 @@ Python -In `my-pipeline/my-pipeline-stack.py` (may vary if your project folder isn't named `my-pipeline`): +In `my-pipeline/my-pipeline-stack.py` (may vary if your project folder isn’t named `my-pipeline`): @@ -342 +321 @@ Java -In `src/main/java/com/myorg/MyPipelineStack.java` (may vary if your project folder isn't named `my-pipeline`): +In `src/main/java/com/myorg/MyPipelineStack.java` (may vary if your project folder isn’t named `my-pipeline`): @@ -373 +352 @@ In `src/main/java/com/myorg/MyPipelineStack.java` (may vary if your project fold -In `src/main/java/com/myorg/MyPipelineApp.java` (may vary if your project folder isn't named `my-pipeline`): +In `src/main/java/com/myorg/MyPipelineApp.java` (may vary if your project folder isn’t named `my-pipeline`): @@ -401 +379 @@ C# -In `src/MyPipeline/MyPipelineStack.cs` (may vary if your project folder isn't named `my-pipeline`): +In `src/MyPipeline/MyPipelineStack.cs` (may vary if your project folder isn’t named `my-pipeline`): @@ -426 +404 @@ In `src/MyPipeline/MyPipelineStack.cs` (may vary if your project folder isn't na -In `src/MyPipeline/Program.cs` (may vary if your project folder isn't named `my-pipeline`): +In `src/MyPipeline/Program.cs` (may vary if your project folder isn’t named `my-pipeline`): @@ -573 +551 @@ You must deploy a pipeline manually once. After that, the pipeline keeps itself -Now that you've done the initial deployment, your local AWS account no longer needs administrative access. This is because all changes to your app will be deployed via the pipeline. All you need to be able to do is push to GitHub. +Now that you’ve done the initial deployment, your local AWS account no longer needs administrative access. This is because all changes to your app will be deployed via the pipeline. All you need to be able to do is push to GitHub. @@ -579 +557 @@ To define a multi-stack AWS application that can be added to the pipeline all at -The stage contains the stacks that make up your application. If there are dependencies between the stacks, the stacks are automatically added to the pipeline in the right order. Stacks that don't depend on each other are deployed in parallel. You can add a dependency relationship between stacks by calling `stack1.addDependency(stack2)`. +The stage contains the stacks that make up your application. If there are dependencies between the stacks, the stacks are automatically added to the pipeline in the right order. Stacks that don’t depend on each other are deployed in parallel. You can add a dependency relationship between stacks by calling `stack1.addDependency(stack2)`. @@ -583 +561 @@ Stages accept a default `env` argument, which becomes the default environment fo -An application is added to the pipeline by calling `[addStage](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.CodePipeline.html#addwbrstagestage-optionss)()` with instances of [`Stage`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stage.html). A stage can be instantiated and added to the pipeline multiple times to define different stages of your DTAP or multi-Region application pipeline. +An application is added to the pipeline by calling ` [addStage()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.CodePipeline.html#addwbrstagestage-optionss) ` with instances of [Stage](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stage.html). A stage can be instantiated and added to the pipeline multiple times to define different stages of your DTAP or multi-Region application pipeline. @@ -631 +609 @@ Edit `lib/my-pipeline-stack.ts` to add the stage to our pipeline. - **import{ MyPipelineAppStage } from './my-pipeline-app-stage';** + import { MyPipelineAppStage } from './my-pipeline-app-stage'; @@ -645 +623 @@ Edit `lib/my-pipeline-stack.ts` to add the stage to our pipeline. - **pipeline.addStage(new MyPipelineAppStage(this, "test",{ + pipeline.addStage(new MyPipelineAppStage(this, "test", { @@ -647 +625 @@ Edit `lib/my-pipeline-stack.ts` to add the stage to our pipeline. - }));** + })); @@ -696,2 +674,2 @@ Edit `lib/my-pipeline-stack.ts` to add the stage to our pipeline. - **const{ MyPipelineAppStage } = require('./my-pipeline-app-stage'); - ** + const { MyPipelineAppStage } = require('./my-pipeline-app-stage'); + @@ -710 +688 @@ Edit `lib/my-pipeline-stack.ts` to add the stage to our pipeline. - **pipeline.addStage(new MyPipelineAppStage(this, "test",{ + pipeline.addStage(new MyPipelineAppStage(this, "test", { @@ -712 +690 @@ Edit `lib/my-pipeline-stack.ts` to add the stage to our pipeline. - }));** + })); @@ -758 +736 @@ Edit `my_pipeline/my-pipeline-stack.py` to add the stage to our pipeline. - **from my_pipeline.my_pipeline_app_stage import MyPipelineAppStage** + from my_pipeline.my_pipeline_app_stage import MyPipelineAppStage @@ -773 +751 @@ Edit `my_pipeline/my-pipeline-stack.py` to add the stage to our pipeline. - **pipeline.add_stage(MyPipelineAppStage(self, "test", + pipeline.add_stage(MyPipelineAppStage(self, "test", @@ -775 +752,0 @@ Edit `my_pipeline/my-pipeline-stack.py` to add the stage to our pipeline. - ** @@ -841 +818 @@ Edit `src/main/java/com.myorg/MyPipelineStack.java` to add the stage to our pipe - **import software.amazon.awscdk.Environment;** + import software.amazon.awscdk.Environment; @@ -844 +821 @@ Edit `src/main/java/com.myorg/MyPipelineStack.java` to add the stage to our pipe - **import software.amazon.awscdk.StageProps;** + import software.amazon.awscdk.StageProps; @@ -865 +842 @@ Edit `src/main/java/com.myorg/MyPipelineStack.java` to add the stage to our pipe - **pipeline.addStage(new MyPipelineAppStage(this, "test", StageProps.builder() + pipeline.addStage(new MyPipelineAppStage(this, "test", StageProps.builder() @@ -870 +847 @@ Edit `src/main/java/com.myorg/MyPipelineStack.java` to add the stage to our pipe - .build()));** + .build())); @@ -940 +917,2 @@ Edit `src/MyPipeline/MyPipelineStack.cs` to add the stage to our pipeline. - **pipeline.AddStage(new MyPipelineAppStage(this, "test", new StageProps{ + pipeline.AddStage(new MyPipelineAppStage(this, "test", new StageProps + { @@ -945 +923 @@ Edit `src/MyPipeline/MyPipelineStack.cs` to add the stage to our pipeline. - }));** + })); @@ -950 +928 @@ Edit `src/MyPipeline/MyPipelineStack.cs` to add the stage to our pipeline. -Every application stage added by `addStage()` results in the addition of a corresponding pipeline stage, represented by a [StageDeployment](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.StageDeployment.html) instance returned by the `addStage()` call. You can add pre-deployment or post-deployment actions to the stage by calling its `addPre()` or `addPost()` method. +Every application stage added by `addStage()` results in the addition of a corresponding pipeline stage, represented by a ` [StageDeployment](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.StageDeployment.html) ` instance returned by the `addStage()` call. You can add pre-deployment or post-deployment actions to the stage by calling its `addPre()` or `addPost()` method. @@ -1018 +996 @@ C# -You can add stages to a [Wave](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.Wave.html) to deploy them in parallel, for example when deploying a stage to multiple accounts or Regions. +You can add stages to a ` [Wave](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.Wave.html) ` to deploy them in parallel, for example when deploying a stage to multiple accounts or Regions. @@ -1096 +1073 @@ C# -You can add steps to a CDK Pipeline to validate the deployments that you're performing. For example, you can use the CDK Pipeline library's `[ShellStep](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.ShellStep.html)` to perform tasks such as the following: +You can add steps to a CDK Pipeline to validate the deployments that you’re performing. For example, you can use the CDK Pipeline library’s ` [ShellStep](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines.ShellStep.html) ` to perform tasks such as the following: @@ -1160 +1137 @@ Many AWS CloudFormation deployments result in the generation of resources with u -To use outputs, expose the `CfnOutput` object you're interested in. Then, pass it in a step's `envFromCfnOutputs` property to make it available as an environment variable within that step. +To use outputs, expose the `CfnOutput` object you’re interested in. Then, pass it in a step’s `envFromCfnOutputs` property to make it available as an environment variable within that step. @@ -1526 +1502 @@ The following issues are commonly encountered while getting started with CDK Pip - CREATE_FAILED | AWS::CodePipeline::Pipeline | Pipeline/Pipeline + CREATE_FAILED | {aws}::CodePipeline::Pipeline | Pipeline/Pipeline @@ -1535 +1511 @@ Check your GitHub access token. It might be missing, or might not have the permi - CREATE_FAILED | AWS::KMS::Key | Pipeline/Pipeline/ArtifactsBucketEncryptionKey + CREATE_FAILED | {aws}::KMS::Key | Pipeline/Pipeline/ArtifactsBucketEncryptionKey @@ -1540 +1516 @@ One of the target environments has not been bootstrapped with the new bootstrap -**Stack is in ROLLBACK_COMPLETE state and can not be updated.** +**Stack is in ROLLBACK_COMPLETE state and cannot be updated** @@ -1544 +1520 @@ One of the target environments has not been bootstrapped with the new bootstrap - Stack STACK_NAME is in ROLLBACK_COMPLETE state and can not be updated. (Service: + Stack <STACK_NAME> is in ROLLBACK_COMPLETE state and cannot be updated. (Service: