AWS cdk documentation change
Summary
Formatting changes to headers (markdown headers converted to bold text), minor typographic fixes (apostrophe style), code example syntax adjustments, and added documentation about handling unresolved values. Added new 'Deployment permissions' section (moved from previous heading).
Security assessment
Changes are primarily formatting improvements, typographic corrections, and clarification of deployment mechanics. The 'Configure security credentials' section was reformatted but not substantively changed. The new 'Deployment permissions' section documents existing permission requirements but does not introduce new security features or address vulnerabilities.
Diff
diff --git a/cdk/v2/guide/deploy.md b/cdk/v2/guide/deploy.md index 064040801..75b22e747 100644 --- a//cdk/v2/guide/deploy.md +++ b//cdk/v2/guide/deploy.md @@ -43 +43,2 @@ Before you can deploy an AWS CDK application, you must complete the following: -### Configure security credentials +**Configure security credentials** + @@ -47 +48,2 @@ To use the CDK CLI to interact with AWS, you must configure security credentials -### Bootstrap your AWS environment +**Bootstrap your AWS environment** + @@ -53 +55,2 @@ We recommend that you use the AWS CDK Command Line Interface (AWS CDK CLI) `cdk -### Configure AWS environments +**Configure AWS environments** + @@ -57 +60,2 @@ Each CDK stack must be associated with an environment to determine where the sta -### Develop your CDK app +**Develop your CDK app** + @@ -69 +73,2 @@ For your synthesized CloudFormation template to deploy successfully into your en -### The app lifecycle +**The app lifecycle** + @@ -81 +86 @@ Your code instantiates all of the defined constructs and then links them togethe -All constructs that have implemented the `prepare` method participate in a final round of modifications, to set up their final state. The preparation phase happens automatically. As a user, you don't see any feedback from this phase. It's rare to need to use the "prepare" hook, and generally not recommended. Be very careful when mutating the construct tree during this phase, because the order of operations could impact behavior. +All constructs that have implemented the `prepare` method participate in a final round of modifications, to set up their final state. The preparation phase happens automatically. As a user, you don’t see any feedback from this phase. It’s rare to need to use the "prepare" hook, and generally not recommended. Be very careful when mutating the construct tree during this phase, because the order of operations could impact behavior. @@ -88 +93 @@ During this phase, once the construct tree has been built, any [aspects](./aspec -All constructs that have implemented the `validate` method can validate themselves to ensure that they're in a state that will correctly deploy. You will get notified of any validation failures that happen during this phase. Generally, we recommend performing validation as soon as possible (usually as soon as you get some input) and throwing exceptions as early as possible. Performing validation early improves reliability as stack traces will be more accurate, and ensures that your code can continue to execute safely. +All constructs that have implemented the `validate` method can validate themselves to ensure that they’re in a state that will correctly deploy. You will get notified of any validation failures that happen during this phase. Generally, we recommend performing validation as soon as possible (usually as soon as you get some input) and throwing exceptions as early as possible. Performing validation early improves reliability as stack traces will be more accurate, and ensures that your code can continue to execute safely. @@ -93 +98 @@ All constructs that have implemented the `validate` method can validate themselv -This is the final stage of running your CDK app. It's triggered by a call to `app.synth()`, and it traverses the construct tree and invokes the `synthesize` method on all constructs. Constructs that implement `synthesize` can participate in synthesis and produce deployment artifacts to the resulting cloud assembly. These artifacts include CloudFormation templates, AWS Lambda application bundles, file and Docker image assets, and other deployment artifacts. In most cases, you won't need to implement the `synthesize` method. +This is the final stage of running your CDK app. It’s triggered by a call to `app.synth()`, and it traverses the construct tree and invokes the `synthesize` method on all constructs. Constructs that implement `synthesize` can participate in synthesis and produce deployment artifacts to the resulting cloud assembly. These artifacts include CloudFormation templates, AWS Lambda application bundles, file and Docker image assets, and other deployment artifacts. In most cases, you won’t need to implement the `synthesize` method. @@ -95 +100 @@ This is the final stage of running your CDK app. It's triggered by a call to `ap -### Running your app +**Running your app** @@ -97 +102,2 @@ This is the final stage of running your CDK app. It's triggered by a call to `ap -The CDK CLI needs to know how to run your CDK app. If you created the project from a template using the `cdk init` command, your app's `cdk.json` file includes an `app` key. This key specifies the necessary command for the language that the app is written in. If your language requires compilation, the command line performs this step before running the app automatically. + +The CDK CLI needs to know how to run your CDK app. If you created the project from a template using the `cdk init` command, your app’s `cdk.json` file includes an `app` key. This key specifies the necessary command for the language that the app is written in. If your language requires compilation, the command line performs this step before running the app automatically. @@ -148 +153 @@ Go -If you didn't create your project using the CDK CLI, or if you want to override the command line given in `cdk.json`, you can provide the `[--app](./ref-cli-cmd.html#ref-cli-cmd-options-app)` option when running the `cdk` command. +If you didn’t create your project using the CDK CLI, or if you want to override the command line given in `cdk.json`, you can provide the ` [--app](./ref-cli-cmd.html#ref-cli-cmd-options-app) ` option when running the `cdk` command. @@ -151 +156 @@ If you didn't create your project using the CDK CLI, or if you want to override - $ cdk --app 'executable' cdk-command ... + $ cdk --app '<executable>' <cdk-command> ... @@ -153 +158 @@ If you didn't create your project using the CDK CLI, or if you want to override -The `executable` part of the command indicates the command that should be run to execute your CDK application. Use quotation marks as shown, since such commands contain spaces. The `cdk-command` is a subcommand like `synth` or `deploy` that tells the CDK CLI what you want to do with your app. Follow this with any additional options needed for that subcommand. +The `<executable>` part of the command indicates the command that should be run to execute your CDK application. Use quotation marks as shown, since such commands contain spaces. The `<cdk-command>` is a subcommand like `synth` or `deploy` that tells the CDK CLI what you want to do with your app. Follow this with any additional options needed for that subcommand. @@ -158 +163 @@ The CDK CLI can also interact directly with an already-synthesized cloud assembl - $ cdk --app ./my-cloud-assembly ls + $ cdk --app <./my-cloud-assembly> ls @@ -160 +165 @@ The CDK CLI can also interact directly with an already-synthesized cloud assembl -### Cloud assemblies +**Cloud assemblies** @@ -162 +167,2 @@ The CDK CLI can also interact directly with an already-synthesized cloud assembl -The call to `app.synth()` is what tells the AWS CDK to synthesize a cloud assembly from an app. Typically you don't interact directly with cloud assemblies. They are files that include everything needed to deploy your app to a cloud environment. For example, it includes an AWS CloudFormation template for each stack in your app. It also includes a copy of any file assets or Docker images that you reference in your app. + +The call to `app.synth()` is what tells the AWS CDK to synthesize a cloud assembly from an app. Typically you don’t interact directly with cloud assemblies. They are files that include everything needed to deploy your app to a cloud environment. For example, it includes an AWS CloudFormation template for each stack in your app. It also includes a copy of any file assets or Docker images that you reference in your app. @@ -174 +180 @@ When you run `cdk deploy`, the CDK CLI initiates `cdk synth` to prepare for depl - + @@ -180 +186,3 @@ By the time the AWS CloudFormation deployment phase starts, your CDK app has alr - * The CDK app can't respond to events that happen during deployment, such as a resource being created or the whole deployment finishing. To run code during the deployment phase, you must inject it into the AWS CloudFormation template as a [custom resource](./cfn-layer.html#develop-customize-custom). For more information about adding a custom resource to your app, see the [AWS CloudFormation module](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudformation-readme.html), or the [custom-resource](https://github.com/aws-samples/aws-cdk-examples/tree/master/typescript/custom-resource/) example. You can also configure the [Triggers](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.triggers-readme.html) module to run code during deployments. + * The CDK app can’t respond to events that happen during deployment, such as a resource being created or the whole deployment finishing. To run code during the deployment phase, you must inject it into the AWS CloudFormation template as a [custom resource](./cfn-layer.html#develop-customize-custom). For more information about adding a custom resource to your app, see the [AWS CloudFormation module](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudformation-readme.html), or the [custom-resource](https://github.com/aws-samples/aws-cdk-examples/tree/master/typescript/custom-resource/) example. You can also configure the [Triggers](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.triggers-readme.html) module to run code during deployments. + + * The CDK app might have to work with values that can’t be known at the time it runs. For example, if the AWS CDK app defines an Amazon S3 bucket with an automatically generated name, and you retrieve the `bucket.bucketName` (Python: `bucket_name`) attribute, that value is not the name of the deployed bucket. Instead, you get a `Token` value. To determine whether a particular value is available, call `cdk.isUnresolved(value)` (Python: `is_unresolved`). See [Tokens and the AWS CDK](./tokens.html) for details. @@ -182 +189,0 @@ By the time the AWS CloudFormation deployment phase starts, your CDK app has alr - * The CDK app might have to work with values that can't be known at the time it runs. For example, if the AWS CDK app defines an Amazon S3 bucket with an automatically generated name, and you retrieve the `bucket.bucketName` (Python: `bucket_name`) attribute, that value is not the name of the deployed bucket. Instead, you get a `Token` value. To determine whether a particular value is available, call `cdk.isUnresolved(value)` (Python: `is_unresolved`). See [Tokens and the AWS CDK](./tokens.html) for details. @@ -185,0 +193 @@ By the time the AWS CloudFormation deployment phase starts, your CDK app has alr +**Deployment permissions** @@ -187 +194,0 @@ By the time the AWS CloudFormation deployment phase starts, your CDK app has alr -### Deployment permissions @@ -191 +198 @@ Before deployment can be performed, permissions must be established. The followi - +