AWS prescriptive-guidance documentation change
Summary
Updated example bucket names to use 'DOC-EXAMPLE-BUCKET' placeholder, fixed typos/grammar, adjusted markdown formatting, and clarified technical explanations about AWS CDK constructs.
Security assessment
Changes involve example standardization (replacing 'amzn-s3-demo-bucket' with placeholder), grammatical fixes, and non-security technical clarifications about CDK layers. No security vulnerabilities, configurations, or features are discussed or modified.
Diff
diff --git a/prescriptive-guidance/latest/aws-cdk-layers/layer-2.md b/prescriptive-guidance/latest/aws-cdk-layers/layer-2.md index d15dcb5f4..c22b64391 100644 --- a//prescriptive-guidance/latest/aws-cdk-layers/layer-2.md +++ b//prescriptive-guidance/latest/aws-cdk-layers/layer-2.md @@ -16 +16 @@ The packages also contain a collection of TypeScript types, enums, and interface - const role = new Bucket(this, "amzn-s3-demo-bucket", {/*...BucketProps*/}); + const role = new Bucket(this, "DOC-EXAMPLE-BUCKET", {/*...BucketProps*/}); @@ -21 +21 @@ The L2 construct takes the default properties, convenience methods, and other sy -All L2 constructs build their corresponding L1 constructs under the hood. However, L2 constructs don't actually extend L1 constructs. Both L1 and L2 constructs inherit a special class called [Construct](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html). In version 1 of the AWS CDK the `Construct` class was built into the development kit, but in version 2 it's a separate [standalone package](https://www.npmjs.com/package/constructs). This is so other packages such as the [Cloud Development Kit for Terraform (CDKTF)](https://developer.hashicorp.com/terraform/cdktf) can include it as a dependency. Any class that inherits the `Construct` class is an L1, L2, or an L3 construct. L2 constructs extend this class directly whereas L1 constructs extend a class called `CfnResource`, as shown in the following table. +All L2 constructs build their corresponding L1 constructs under the hood. However, L2 constructs don't actually extend L1 constructs. Both L1 and L2 constructs inherit a special class called [Construct](https://docs.aws.amazon.com/cdk/api/v2/docs/constructs.Construct.html). In version 1 of the AWS CDK the `Construct` class was built into the development kit, but in version 2 it's a separate [standalone package](https://www.npmjs.com/package/constructs). This is so other packages such as the [Cloud Development Kit for Terraform (CDKTF)](https://developer.hashicorp.com/terraform/cdktf) can include it as a dependency. Any class that inherits the `Construct` class is an L1, L2, or an L3 construct. L2 constructs extend this class directly while L1 constructs extend a class called `CfnResource`. @@ -27 +27 @@ _L1 construct_ _→ class_[ _CfnResource_](https://docs.aws.amazon.com/cdk/api/v -If both L1 and L2 constructs inherit the `Construct` class, why don't L2 constructs just extend L1? Well, the classes between the `Construct` class and layer 1 lock the L1 construct in place as a mirror image of the CloudFormation resource. They contain abstract methods (methods that downstream classes **must** include) like `_toCloudFormation`, which forces the construct to directly output CloudFormation syntax. L2 constructs skip over those classes and extend the `Construct` class directly. This gives them the flexibility to abstract much of the code needed for L1 constructs by building them separately within their constructors. +If both L1 and L2 constructs inherit the `Construct` class, why don't L2 constructs just extend L1? Well, the classes between the `Construct` class and layer 1 lock the L1 construct in place as a mirror image of the CloudFormation resource. They contain abstract methods (methods that downstream classes _must_ include) like `_toCloudFormation`, which forces the construct to directly output CloudFormation syntax. L2 constructs skip over those classes and extend the `Construct` class directly. This gives them the flexibility to abstract much of the code needed for L1 constructs by building them separately within their constructors. @@ -31 +31 @@ The previous section featured a side-by-side comparison of an S3 bucket from a C -**L1 construct for S3 bucket** | **L2 construct for S3 bucket** +L1 construct for S3 bucket| L2 construct for S3 bucket @@ -36 +36 @@ The previous section featured a side-by-side comparison of an S3 bucket from a C - bucketName: "amzn-s3-demo-bucket", + bucketName: "DOC-EXAMPLE-BUCKET", @@ -73 +73 @@ The previous section featured a side-by-side comparison of an S3 bucket from a C - bucketName: "amzn-s3-demo-bucket", + bucketName: "DOC-EXAMPLE-BUCKET", @@ -93 +93 @@ The simplest way to consolidate the code for provisioning a resource is to turn -Although the AWS CDK is available in several programming languages, it is written natively in TypeScript, so that language's type system is used to define the types that make up L2 constructs. Diving deep into that type system is beyond the scope of this guide; see the [TypeScript documentation](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html) for details. To summarize, a TypeScript `type` describes what kind of data a particular variable holds. This could be basic data such as a `string`, or more complex data such as an `object`. A TypeScript `interface` is another way of expressing the TypeScript object type, and a `struct` is another name for an interface. +Although the AWS CDK is available in several programming languages, it is written natively in TypeScript, so that language's type system is used to define the types that make up L2 constructs. Diving deep into that type system is beyond the scope of this guide; see the [TypeScript documentation](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html) for details. To summarize, a TypeScript type describes what kind of data a particular variable holds. This could be basic data such as a string, or more complex data such as an object. A TypeScript interface is another way of expressing the TypeScript object type, and a struct is another name for an interface. @@ -97 +97 @@ TypeScript doesn't use the term _struct_ , but if you look in the [AWS CDK API R -What the AWS CDK refers to as _structs_ are interfaces that represent any object used by an L2 construct. This includes the object types for the property arguments that are passed to the L2 construct during instantiation, such as `BucketProps` for the S3 Bucket construct and `TableProps` for the DynamoDB Table construct, as well as other TypeScript interfaces that are used within the AWS CDK. In short, if it's a TypeScript interface within the AWS CDK and its name isn't prefixed by the letter `I`, the AWS CDK calls it a _struct_. +What the AWS CDK refers to as structs are interfaces that represent any object used by an L2 construct. This includes the object types for the property arguments that are passed to the L2 construct during instantiation, like such as `BucketProps` for the S3 Bucket construct and `TableProps` for the DynamoDB Table construct, as well as other TypeScript interfaces that are used within the AWS CDK. In short, if it's a TypeSscript interface within the AWS CDK and it's name isn't prefixed by the letter `I`, the AWS CDK calls it a _struct_. @@ -99 +99 @@ What the AWS CDK refers to as _structs_ are interfaces that represent any object -Conversely, the AWS CDK uses the term _interface_ to represent the base elements a plain object would need to be considered a proper representation of a particular construct or helper class. That is, an interface describes what an L2 construct's public properties must be. All AWS CDK interface names are the names of existing constructs or helper classes prefixed by the letter `I`. All L2 constructs extend the `Construct` class, but they also implement their corresponding interface. So the L2 construct `Bucket` implements the `IBucket` interface. +Conversely, the AWS CDK uses the term _interface_ to represent the base elements a plain object would need to be considered a proper representation of a particular construct or helper class. That is, an interface describes what an L2 construct's public properties must be. All AWS CDK `interface` names are the names of existing constructs or helper classes prefixed by the letter `I`. All L2 constructs extend the `Construct` class, but they also implement their corresponding interface. So the L2 construct `Bucket` implements the `IBucket` interface. @@ -107 +107 @@ This distinction becomes very important when you import pre-existing resources i -To make this easier in practice, most L2 constructs have a set of static methods associated with them that return that L2 construct's interface. These static methods usually start with the word `from`. The first two arguments passed to these methods are the same `scope` and `id` arguments required for a standard L2 construct. However, the third argument isn't `props` but a small subset of properties (or sometimes just one property) that defines an interface. For this reason, when you pass an L2 construct, in most cases only the elements of the interface are required. This is so you can use imported resources as well, where possible. +To make this easier in practice, most L2 constructs have a set of static methods associated with them that return that L2 construct's interface. These static methods usually start with the word `from`. The first two arguments passed to these methods are the same `scope` and `id` arguments required for a standard L2 construct. However, the third argument isn't `props` but a small subset of properties (or sometimes just one property) that defines an interface. For this reason, when you pass an L2 construct, only the elements of the interface are required in most cases. This is so, where possible, you can use imported resources as well. @@ -113 +113 @@ To make this easier in practice, most L2 constructs have a set of static methods -However, you shouldn't rely heavily on interfaces. You should import resources and use interfaces directly only when absolutely necessary, because interfaces don't provide many of the properties—such as helper methods—that make an L2 construct so powerful. +However, you shouldn't rely heavily on interfaces. You should import resources and use interfaces directly only when absolutely necessary, because interfaces don't provide many of the properties―such as helper methods―that make an L2 construct so powerful. @@ -173 +173 @@ Sometimes an enum can't accomplish the programmatic logic needed to configure a -So although the `BucketEncryption` enum can reduce the amount of code needed to set an encryption algorithm on an S3 bucket, that same strategy would not work for setting time durations because there are simply too many possible values to choose from. Creating an enum for each value would be far more trouble than it's worth. For this reason, a helper class is used for an S3 bucket's default S3 Object Lock configuration settings, as represented by the [ObjectLockRetention](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.ObjectLockRetention.html) class. `ObjectLockRetention` contains two static methods: one for compliance retention and the other for governance retention. Both methods take an instance of the [Duration helper class ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Duration.html)as an argument to express the amount of time that the lock should be configured for. +So although the `BucketEncryption` enum can reduce the amount of code needed to set an encryption algorithm on an S3 bucket, that same strategy would not work for setting time durations because there are simply too many possible values to choose from. Creating an enum for each value would be far more trouble than it's worth. For this reason, a helper class is used for an S3 bucket's default S3 Object Lock configuration settings, as represented by the [ObjectLockRetention](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.ObjectLockRetention.html) class. `ObjectLockRetention` contains two static methods: one for `compliance` retention and the other for `governance retention`. Both methods take an instance of the [Duration helper class ](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Duration.html)as an argument to express the amount of time that the lock should be configured for.