AWS cdk documentation change
Summary
Formatting and typographical corrections including code syntax highlighting, apostrophe standardization, and markdown link formatting. Adjusted C# code example syntax and fixed list item formatting for tag names.
Security assessment
Changes are primarily editorial improvements (e.g., code formatting with backticks, typographical fixes). No explicit security vulnerabilities, mitigations, or new security features are introduced. References to security-related topics like KMS encryption or IAM grants were already present and remain unchanged in substance.
Diff
diff --git a/cdk/v2/guide/resources.md b/cdk/v2/guide/resources.md index 8643b359a..8ba59a5fa 100644 --- a//cdk/v2/guide/resources.md +++ b//cdk/v2/guide/resources.md @@ -15 +15 @@ This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on -As described in [AWS CDK Constructs](./constructs.html), the AWS CDK provides a rich class library of constructs, called _AWS constructs_ , that represent all AWS resources. +As described in [AWS CDK Constructs](./constructs.html), the AWS CDK provides a rich class library of constructs, called _constructs_ , that represent all AWS resources. @@ -17 +17 @@ As described in [AWS CDK Constructs](./constructs.html), the AWS CDK provides a -To create an instance of a resource using its corresponding construct, pass in the scope as the first argument, the logical ID of the construct, and a set of configuration properties (props). For example, here's how to create an Amazon SQS queue with AWS KMS encryption using the [sqs.Queue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.Queue.html) construct from the AWS Construct Library. +To create an instance of a resource using its corresponding construct, pass in the scope as the first argument, the logical ID of the construct, and a set of configuration properties (props). For example, here’s how to create an Amazon SQS queue with AWS KMS encryption using the [`sqs.Queue`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.Queue.html) construct from the AWS Construct Library. @@ -225 +225 @@ You can refer to resources in a different stack as long as they are defined in t - * Store a reference to the construct as an attribute of the stack that produces the resource. (To get a reference to the current construct's stack, use `Stack.of(this)`.) + * Store a reference to the construct as an attribute of the stack that produces the resource. (To get a reference to the current construct’s stack, use `Stack.of(this)`.) @@ -311 +311 @@ C# -If the AWS CDK determines that the resource is in the same environment, but in a different stack, it automatically synthesizes AWS CloudFormation [exports](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-exports.html) in the producing stack and an [Fn::ImportValue](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html) in the consuming stack to transfer that information from one stack to the other. +If the AWS CDK determines that the resource is in the same environment, but in a different stack, it automatically synthesizes AWS CloudFormation [exports](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-exports.html) in the producing stack and an [`Fn::ImportValue`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html) in the consuming stack to transfer that information from one stack to the other. @@ -315 +315 @@ If the AWS CDK determines that the resource is in the same environment, but in a -Referencing a resource from one stack in a different stack creates a dependency between the two stacks. This makes sure that they're deployed in the right order. After the stacks are deployed, this dependency is concrete. After that, removing the use of the shared resource from the consuming stack can cause an unexpected deployment failure. This happens if there is another dependency between the two stacks that force them to be deployed in the same order. It can also happen without a dependency if the producing stack is simply chosen by the CDK Toolkit to be deployed first. The AWS CloudFormation export is removed from the producing stack because it's no longer needed, but the exported resource is still being used in the consuming stack because its update is not yet deployed. Therefore, deploying the producer stack fails. +Referencing a resource from one stack in a different stack creates a dependency between the two stacks. This makes sure that they’re deployed in the right order. After the stacks are deployed, this dependency is concrete. After that, removing the use of the shared resource from the consuming stack can cause an unexpected deployment failure. This happens if there is another dependency between the two stacks that force them to be deployed in the same order. It can also happen without a dependency if the producing stack is simply chosen by the CDK Toolkit to be deployed first. The AWS CloudFormation export is removed from the producing stack because it’s no longer needed, but the exported resource is still being used in the consuming stack because its update is not yet deployed. Therefore, deploying the producer stack fails. @@ -317 +317 @@ Referencing a resource from one stack in a different stack creates a dependency -To break this deadlock, remove the use of the shared resource from the consuming stack. (This removes the automatic export from the producing stack.) Next, manually add the same export to the producing stack using exactly the same logical ID as the automatically generated export. Remove the use of the shared resource in the consuming stack and deploy both stacks. Then, remove the manual export (and the shared resource if it's no longer needed) and deploy both stacks again. The stack's `[exportValue()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#exportwbrvalueexportedvalue-options)` method is a convenient way to create the manual export for this purpose. (See the example in the linked method reference.) +To break this deadlock, remove the use of the shared resource from the consuming stack. (This removes the automatic export from the producing stack.) Next, manually add the same export to the producing stack using exactly the same logical ID as the automatically generated export. Remove the use of the shared resource in the consuming stack and deploy both stacks. Then, remove the manual export (and the shared resource if it’s no longer needed) and deploy both stacks again. The stack’s [`exportValue()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html#exportwbrvalueexportedvalue-options) method is a convenient way to create the manual export for this purpose. (See the example in the linked method reference.) @@ -321 +321 @@ To break this deadlock, remove the use of the shared resource from the consuming -Suppose you want to use a resource already available in your AWS account in your AWS CDK app. This might be a resource that was defined through the console, an AWS SDK, directly with AWS CloudFormation, or in a different AWS CDK application. You can turn the resource's ARN (or another identifying attribute, or group of attributes) into a proxy object. The proxy object serves as a reference to the resource by calling a static factory method on the resource's class. +Suppose you want to use a resource already available in your AWS account in your AWS CDK app. This might be a resource that was defined through the console, an AWS SDK, directly with AWS CloudFormation, or in a different AWS CDK application. You can turn the resource’s ARN (or another identifying attribute, or group of attributes) into a proxy object. The proxy object serves as a reference to the resource by calling a static factory method on the resource’s class. @@ -325 +325 @@ When you create such a proxy, the external resource **does not** become a part o -The following example shows how to reference a bucket based on an existing bucket with the ARN **arn:aws:s3:::amzn-s3-demo-bucket1** , and an Amazon Virtual Private Cloud based on an existing VPC having a specific ID. +The following example shows how to reference a bucket based on an existing bucket with the ARN `arn:aws:s3:::amzn-s3-demo-bucket1`, and an Amazon Virtual Private Cloud based on an existing VPC having a specific ID. @@ -416 +416 @@ Go -Let's take a closer look at the [`Vpc.fromLookup()`](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-ec2.Vpc.html#static-fromwbrlookupscope-id-options) method. Because the `ec2.Vpc` construct is complex, there are many ways you might want to select the VPC to be used with your CDK app. To address this, the VPC construct has a `fromLookup` static method (Python: `from_lookup`) that lets you look up the desired Amazon VPC by querying your AWS account at synthesis time. +Let’s take a closer look at the [`Vpc.fromLookup()`](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-ec2.Vpc.html#static-fromwbrlookupscope-id-options) method. Because the `ec2.Vpc` construct is complex, there are many ways you might want to select the VPC to be used with your CDK app. To address this, the VPC construct has a `fromLookup` static method (Python: `from_lookup`) that lets you look up the desired Amazon VPC by querying your AWS account at synthesis time. @@ -420 +420 @@ To use `Vpc.fromLookup()`, the system that synthesizes the stack must have acces -Furthermore, `Vpc.fromLookup()` works only in stacks that are defined with an explicit **account** and **region** (see [Environments for the AWS CDK](./environments.html)). If the AWS CDK tries to look up an Amazon VPC from an [environment-agnostic stack](./stacks.html#stack-api), the CDK Toolkit doesn't know which environment to query to find the VPC. +Furthermore, `Vpc.fromLookup()` works only in stacks that are defined with an explicit **account** and **region** (see [Environments for the AWS CDK](./environments.html)). If the AWS CDK tries to look up an Amazon VPC from an [environment-agnostic stack](./stacks.html#stack-api), the CDK Toolkit doesn’t know which environment to query to find the VPC. @@ -422 +422 @@ Furthermore, `Vpc.fromLookup()` works only in stacks that are defined with an ex -You must provide `Vpc.fromLookup()` attributes sufficient to uniquely identify a VPC in your AWS account. For example, there can only ever be one default VPC, so it's sufficient to specify the VPC as the default. +You must provide `Vpc.fromLookup()` attributes sufficient to uniquely identify a VPC in your AWS account. For example, there can only ever be one default VPC, so it’s sufficient to specify the VPC as the default. @@ -469 +469 @@ You can also use the `tags` property to query for VPCs by tag. You can add tags - * _Name_ – The name of the VPC. + * **Name** – The name of the VPC. @@ -471 +471 @@ You can also use the `tags` property to query for VPCs by tag. You can add tags - * _aws-cdk:subnet-name_ – The name of the subnet. + * **aws-cdk:subnet-name** – The name of the subnet. @@ -473 +473 @@ You can also use the `tags` property to query for VPCs by tag. You can add tags - * _aws-cdk:subnet-type_ – The type of the subnet: Public, Private, or Isolated. + * **aws-cdk:subnet-type** – The type of the subnet: Public, Private, or Isolated. @@ -511,2 +511,4 @@ C# - Vpc.FromLookup(this, id = "PublicVpc", new VpcLookupOptions - { Tags = new Dictionary<string, string> { ["aws-cdk:subnet-type"] = "Public" }); + Vpc.FromLookup(this, id: "PublicVpc", new VpcLookupOptions + { + Tags = new Dictionary<string, string> { ["aws-cdk:subnet-type"] = "Public" } + }); @@ -522 +524 @@ Go -Results of `Vpc.fromLookup()` are cached in the project's `cdk.context.json` file. (See [Context values and the AWS CDK](./context.html).) Commit this file to version control so that your app will continue to refer to the same Amazon VPC. This works even if you later change the attributes of your VPCs in a way that would result in a different VPC being selected. This is particularly important if you're deploying the stack in an environment that doesn't have access to the AWS account that defines the VPC, such as [CDK Pipelines](./cdk-pipeline.html). +Results of `Vpc.fromLookup()` are cached in the project’s `cdk.context.json` file. (See [Context values and the AWS CDK](./context.html).) Commit this file to version control so that your app will continue to refer to the same Amazon VPC. This works even if you later change the attributes of your VPCs in a way that would result in a different VPC being selected. This is particularly important if you’re deploying the stack in an environment that doesn’t have access to the AWS account that defines the VPC, such as [CDK Pipelines](./cdk-pipeline.html). @@ -524 +526 @@ Results of `Vpc.fromLookup()` are cached in the project's `cdk.context.json` fil -Although you can use an external resource anywhere you'd use a similar resource defined in your AWS CDK app, you cannot modify it. For example, calling `addToResourcePolicy` (Python: `add_to_resource_policy`) on an external `s3.Bucket` does nothing. +Although you can use an external resource anywhere you’d use a similar resource defined in your AWS CDK app, you cannot modify it. For example, calling `addToResourcePolicy` (Python: `add_to_resource_policy`) on an external `s3.Bucket` does nothing. @@ -528 +530 @@ Although you can use an external resource anywhere you'd use a similar resource -The logical names of resources in AWS CloudFormation are different from the names of resources that are shown in the AWS Management Console after they're deployed by AWS CloudFormation. The AWS CDK calls these final names _physical names_. +The logical names of resources in AWS CloudFormation are different from the names of resources that are shown in the AWS Management Console after they’re deployed by AWS CloudFormation. The AWS CDK calls these final names _physical names_. @@ -532 +534 @@ For example, AWS CloudFormation might create the Amazon S3 bucket with the logic -You can specify a physical name when creating constructs that represent resources by using the property `<resourceType>`Name. The following example creates an Amazon S3 bucket with the physical name `amzn-s3-demo-bucket`. +You can specify a physical name when creating constructs that represent resources by using the property `<resourceType>Name`. The following example creates an Amazon S3 bucket with the physical name `amzn-s3-demo-bucket`. @@ -577 +579 @@ Go -Assigning physical names to resources has some disadvantages in AWS CloudFormation. Most importantly, any changes to deployed resources that require a resource replacement, such as changes to a resource's properties that are immutable after creation, will fail if a resource has a physical name assigned. If you end up in that state, the only solution is to delete the AWS CloudFormation stack, then deploy the AWS CDK app again. See the [AWS CloudFormation documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html) for details. +Assigning physical names to resources has some disadvantages in AWS CloudFormation. Most importantly, any changes to deployed resources that require a resource replacement, such as changes to a resource’s properties that are immutable after creation, will fail if a resource has a physical name assigned. If you end up in that state, the only solution is to delete the AWS CloudFormation stack, then deploy the AWS CDK app again. See the [AWS CloudFormation documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html) for details. @@ -579 +581 @@ Assigning physical names to resources has some disadvantages in AWS CloudFormati -In some cases, such as when creating an AWS CDK app with cross-environment references, physical names are required for the AWS CDK to function correctly. In those cases, if you don't want to bother with coming up with a physical name yourself, you can let the AWS CDK name it for you. To do so, use the special value `PhysicalName.GENERATE_IF_NEEDED`, as follows. +In some cases, such as when creating an AWS CDK app with cross-environment references, physical names are required for the AWS CDK to function correctly. In those cases, if you don’t want to bother with coming up with a physical name yourself, you can let the AWS CDK name it for you. To do so, use the special value `PhysicalName.GENERATE_IF_NEEDED`, as follows. @@ -762 +764 @@ Higher-level constructs make least-privilege permissions achievable by offering -The following example creates the permissions to allow a Lambda function's execution role to read and write objects to a particular Amazon S3 bucket. If the Amazon S3 bucket is encrypted with an AWS KMS key, this method also grants permissions to the Lambda function's execution role to decrypt with the key. +The following example creates the permissions to allow a Lambda function’s execution role to read and write objects to a particular Amazon S3 bucket. If the Amazon S3 bucket is encrypted with an AWS KMS key, this method also grants permissions to the Lambda function’s execution role to decrypt with the key. @@ -814 +816 @@ The grant methods return an `iam.Grant` object. Use the `success` attribute of t -If a specific grant method isn't available for the particular use case, you can use a generic grant method to define a new grant with a specified list of actions. +If a specific grant method isn’t available for the particular use case, you can use a generic grant method to define a new grant with a specified list of actions. @@ -857 +859 @@ Many resources, such as Lambda functions, require a role to be assumed when exec -The grant methods are built using lower-level APIs for handling with IAM policies. Policies are modeled as [PolicyDocument](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyDocument.html) objects. Add statements directly to roles (or a construct's attached role) using the `addToRolePolicy` method (Python: `add_to_role_policy`), or to a resource's policy (such as a `Bucket` policy) using the `addToResourcePolicy` (Python: `add_to_resource_policy`) method. +The grant methods are built using lower-level APIs for handling with IAM policies. Policies are modeled as [PolicyDocument](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.PolicyDocument.html) objects. Add statements directly to roles (or a construct’s attached role) using the `addToRolePolicy` method (Python: `add_to_role_policy`), or to a resource’s policy (such as a `Bucket` policy) using the `addToResourcePolicy` (Python: `add_to_resource_policy`) method. @@ -1083 +1085 @@ C# - { FromPort = 443, ToPort = 443 }); + { FromPort = 443, ToPort = 443 })); @@ -1246 +1246 @@ Value | Meaning -AWS CloudFormation does not remove Amazon S3 buckets that contain files even if their removal policy is set to `DESTROY`. Attempting to do so is an AWS CloudFormation error. To have the AWS CDK delete all files from the bucket before destroying it, set the bucket's `autoDeleteObjects` property to `true`. +AWS CloudFormation does not remove Amazon S3 buckets that contain files even if their removal policy is set to `DESTROY`. Attempting to do so is an AWS CloudFormation error. To have the AWS CDK delete all files from the bucket before destroying it, set the bucket’s `autoDeleteObjects` property to `true`. @@ -1354 +1354 @@ Go -You can also apply a removal policy directly to the underlying AWS CloudFormation resource via the `applyRemovalPolicy()` method. This method is available on some stateful resources that do not have a `removalPolicy` property in their L2 resource's props. Examples include the following: +You can also apply a removal policy directly to the underlying AWS CloudFormation resource via the `applyRemovalPolicy()` method. This method is available on some stateful resources that do not have a `removalPolicy` property in their L2 resource’s props. Examples include the following: @@ -1410 +1410 @@ C# -The AWS CDK's `RemovalPolicy` translates to AWS CloudFormation's `DeletionPolicy`. However, the default in AWS CDK is to retain the data, which is the opposite of the AWS CloudFormation default. +The AWS CDK’s `RemovalPolicy` translates to AWS CloudFormation’s `DeletionPolicy`. However, the default in AWS CDK is to retain the data, which is the opposite of the AWS CloudFormation default.