AWS cdk documentation change
Summary
Updated terminology from 'AWS CloudFormation' to 'CloudFormation' in multiple sections
Security assessment
Changes are purely branding/terminology updates removing redundant 'AWS' prefix from CloudFormation references. No security vulnerabilities, mitigations, or security features are mentioned in the diff.
Diff
diff --git a/cdk/v1/guide/best-practices.md b/cdk/v1/guide/best-practices.md index fd2f5e8e5..09568b8ab 100644 --- a//cdk/v1/guide/best-practices.md +++ b//cdk/v1/guide/best-practices.md @@ -15 +15 @@ The AWS CDK reflects careful consideration of the needs of our customers and int -At deployment time, the AWS CDK synthesizes a cloud assembly that contains not only AWS CloudFormation templates describing your infrastructure in all target environments, but file assets containing your runtime code and their supporting files. With the CDK, every commit in your application's main version control branch can represent a complete, consistent, deployable version of your application. Your application can then be deployed automatically whenever a change is made. +At deployment time, the AWS CDK synthesizes a cloud assembly that contains not only CloudFormation templates describing your infrastructure in all target environments, but file assets containing your runtime code and their supporting files. With the CDK, every commit in your application's main version control branch can represent a complete, consistent, deployable version of your application. Your application can then be deployed automatically whenever a change is made. @@ -32 +32 @@ The philosophy behind the AWS CDK leads to our recommended best practices, which -In addition to the guidance in this document, you should also consider [best practices for AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/best-practices.html) as well as for the individual AWS services you use, where they are obviously applicable to CDK-defined infrastructure. +In addition to the guidance in this document, you should also consider [best practices for CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/best-practices.html) as well as for the individual AWS services you use, where they are obviously applicable to CDK-defined infrastructure. @@ -86 +86 @@ Keep in mind that a construct can be arbitrarily simple or complex. A `Bucket` i -The AWS CDK not only generates AWS CloudFormation templates for deploying infrastructure, it also bundles runtime assets like Lambda functions and Docker images and deploys them alongside your infrastructure. So it's not only possible to combine the code that defines your infrastructure and the code that implements your runtime logic into a single construct— it's a best practice. These two kinds of code don't need to live in separate repositories or even in separate packages. +The AWS CDK not only generates CloudFormation templates for deploying infrastructure, it also bundles runtime assets like Lambda functions and Docker images and deploys them alongside your infrastructure. So it's not only possible to combine the code that defines your infrastructure and the code that implements your runtime logic into a single construct— it's a best practice. These two kinds of code don't need to live in separate repositories or even in separate packages. @@ -130 +130 @@ In this section we discuss how best to write your AWS CDK applications, combinin -Although AWS CloudFormation lets you make decisions at deployment time (using `Conditions`, `{ Fn::If }`, and `Parameters`), and the AWS CDK gives you some access to these mechanisms, we recommend against using them. The types of values you can use, and the types of operations you can perform on them, are quite limited compared to those available in a general-purpose programming language. +Although CloudFormation lets you make decisions at deployment time (using `Conditions`, `{ Fn::If }`, and `Parameters`), and the AWS CDK gives you some access to these mechanisms, we recommend against using them. The types of values you can use, and the types of operations you can perform on them, are quite limited compared to those available in a general-purpose programming language. @@ -132 +132 @@ Although AWS CloudFormation lets you make decisions at deployment time (using `C -Instead, try to make all decisions, such as which construct to instantiate, in your AWS CDK application, using your programming language's `if` statements and other features. For example, a common CDK idiom, iterating over a list and instantiating a construct with values from each item in the list, simply isn't possible using AWS CloudFormation expressions. +Instead, try to make all decisions, such as which construct to instantiate, in your AWS CDK application, using your programming language's `if` statements and other features. For example, a common CDK idiom, iterating over a list and instantiating a construct with values from each item in the list, simply isn't possible using CloudFormation expressions. @@ -134 +134 @@ Instead, try to make all decisions, such as which construct to instantiate, in y -Treat AWS CloudFormation as an implementation detail that the AWS CDK uses for robust cloud deployments, not as a language target. You're not writing AWS CloudFormation templates in TypeScript or Python, you're writing CDK code that happens to use CloudFormation for deployment. +Treat CloudFormation as an implementation detail that the AWS CDK uses for robust cloud deployments, not as a language target. You're not writing CloudFormation templates in TypeScript or Python, you're writing CDK code that happens to use CloudFormation for deployment. @@ -178 +178 @@ Since your AWS CDK app is written in a general-purpose programming language, it -You should never modify your AWS account or resources during synthesis; synthesizing an app should not have side effects. Changes to your infrastructure should happen only in the deployment phase, after the AWS CloudFormation template has been generated. This way, if there's a problem, AWS CloudFormation will automatically roll back the change. To make changes that can't be easily made within the AWS CDK framework, use [custom resources](https://docs.aws.amazon.com/cdk/api/v1/docs/custom-resources-readme.html) to execute arbitrary code at deployment time. +You should never modify your AWS account or resources during synthesis; synthesizing an app should not have side effects. Changes to your infrastructure should happen only in the deployment phase, after the CloudFormation template has been generated. This way, if there's a problem, CloudFormation will automatically roll back the change. To make changes that can't be easily made within the AWS CDK framework, use [custom resources](https://docs.aws.amazon.com/cdk/api/v1/docs/custom-resources-readme.html) to execute arbitrary code at deployment time. @@ -208 +208 @@ If you require developers to always use predefined roles that were created by a -In traditional AWS CloudFormation scenarios, your goal is to produce a single artifact that is parameterized so that it can be deployed to various target environments after applying configuration values specific to those environments. In the CDK, you can, and should, build that configuration right into your source code. Create a stack for your production environment, and a separate one for each of your other stages, and put the configuration values for each right there in the code. Use services like [Secrets Manager](https://aws.amazon.com/secrets-manager/) and [Systems Manager](https://aws.amazon.com/systems-manager/) Parameter Store for sensitive values that you don't want to check in to source control, using the names or ARNs of those resources. +In traditional CloudFormation scenarios, your goal is to produce a single artifact that is parameterized so that it can be deployed to various target environments after applying configuration values specific to those environments. In the CDK, you can, and should, build that configuration right into your source code. Create a stack for your production environment, and a separate one for each of your other stages, and put the configuration values for each right there in the code. Use services like [Secrets Manager](https://aws.amazon.com/secrets-manager/) and [Systems Manager](https://aws.amazon.com/systems-manager/) Parameter Store for sensitive values that you don't want to check in to source control, using the names or ARNs of those resources. @@ -210 +210 @@ In traditional AWS CloudFormation scenarios, your goal is to produce a single ar -When you synthesize your application, the cloud assembly created in the `cdk.out` folder contains a separate template for each environment. Your entire build is deterministic: there are no out-of-band changes to your application, and any given commit always yields the exact same AWS CloudFormation template and accompanying assets, which makes unit testing much more reliable. +When you synthesize your application, the cloud assembly created in the `cdk.out` folder contains a separate template for each environment. Your entire build is deterministic: there are no out-of-band changes to your application, and any given commit always yields the exact same CloudFormation template and accompanying assets, which makes unit testing much more reliable.