AWS cdk documentation change
Summary
Updated documentation formatting, code examples, and clarified synthesizer configuration details. Fixed syntax in Python/Go examples and improved logical ID generation explanation.
Security assessment
Changes focus on documentation clarity, code example corrections, and synthesizer configuration explanations. No explicit security vulnerabilities, mitigations, or security feature additions are mentioned. Changes to logical ID generation explanations are about template structure, not security controls.
Diff
diff --git a/cdk/v2/guide/configure-synth.md b/cdk/v2/guide/configure-synth.md index b2b32e6dc..7c2a86cbb 100644 --- a//cdk/v2/guide/configure-synth.md +++ b//cdk/v2/guide/configure-synth.md @@ -5 +5 @@ -How synthesis and bootstrapping work togetherConfigure CDK synthesisHow to synthesize a CDK stackHow synthesis works by defaultCustomize CDK stack synthesis +How synthesis and bootstrapping work togetherHow to configure CDK stack synthesisHow to synthesize a CDK stackHow synthesis works by defaultCustomize CDK stack synthesis @@ -19 +19 @@ For your CDK apps to properly deploy, the CloudFormation templates produced duri - * CloudFormation templates produced during synthesis include information on which bootstrap resources to use. During synthesis, the CDK CLI doesn't know specifically how your AWS environment has been bootstrapped. Instead, the CDK CLI produces CloudFormation templates based on the synthesizer you configure for each CDK stack. For a deployment to be successful, the synthesizer must produce CloudFormation templates that reference the correct bootstrap resources to use. + * CloudFormation templates produced during synthesis include information on which bootstrap resources to use. During synthesis, the CDK CLI doesn’t know specifically how your AWS environment has been bootstrapped. Instead, the CDK CLI produces CloudFormation templates based on the synthesizer you configure for each CDK stack. For a deployment to be successful, the synthesizer must produce CloudFormation templates that reference the correct bootstrap resources to use. @@ -28 +28 @@ The CDK comes with a default synthesizer and bootstrapping configuration that ar -You configure CDK stack synthesis using the `synthesizer` property of your `[Stack](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html)` instance. This property specifies how your CDK stacks will be synthesized. You provide an instance of a class that implements `[IStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IStackSynthesizer.html)` or `[IReusableStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IReusableStackSynthesizer.html)`. Its methods will be invoked every time an asset is added to the stack or when the stack is synthesized. The following is a basic example of using this property within your stack: +You configure CDK stack synthesis using the `synthesizer` property of your [`Stack`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Stack.html) instance. This property specifies how your CDK stacks will be synthesized. You provide an instance of a class that implements [`IStackSynthesizer`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IStackSynthesizer.html) or [`IReusableStackSynthesizer`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IReusableStackSynthesizer.html). Its methods will be invoked every time an asset is added to the stack or when the stack is synthesized. The following is a basic example of using this property within your stack: @@ -71,0 +72 @@ Java + ) @@ -211,0 +212 @@ Go +By default, the AWS CDK uses ` [`DefaultStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html) `. If you don’t configure a synthesizer, this synthesizer will be used. @@ -213,3 +214 @@ Go -By default, the AWS CDK uses `[DefaultStackSynthesizer](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.DefaultStackSynthesizer.html)`. If you don’t configure a synthesizer, this synthesizer will be used. - -If you don't modify bootstrapping, such as making changes to the bootstrap stack or template, you don’t have to modify stack synthesis. You don’t even have to provide a synthesizer. The CDK will use the default `DefaultStackSynthesizer` class to configure CDK stack synthesis to properly interact with your bootstrap stack. +If you don’t modify bootstrapping, such as making changes to the bootstrap stack or template, you don’t have to modify stack synthesis. You don’t even have to provide a synthesizer. The CDK will use the default `DefaultStackSynthesizer` class to configure CDK stack synthesis to properly interact with your bootstrap stack. @@ -221 +220 @@ To synthesize a CDK stack, use the AWS CDK Command Line Interface (AWS CDK CLI) -If your CDK app contains a single stack, or to synthesize all stacks, you don't have to provide the CDK stack name as an argument. By default, the CDK CLI will synthesize your CDK stacks into AWS CloudFormation templates. A `json` formatted template for each stack is saved to the `cdk.out` directory. If your app contains a single stack, a `yaml` formatted template is printed to `stdout`. The following is an example: +If your CDK app contains a single stack, or to synthesize all stacks, you don’t have to provide the CDK stack name as an argument. By default, the CDK CLI will synthesize your CDK stacks into AWS CloudFormation templates. A `json` formatted template for each stack is saved to the `cdk.out` directory. If your app contains a single stack, a `yaml` formatted template is printed to `stdout`. The following is an example: @@ -244 +243 @@ If you don’t synthesize a stack and run `cdk deploy`, the CDK CLI will automat -### Generated logical IDs in your AWS CloudFormation template +**Generated logical IDs in your AWS CloudFormation template** @@ -246 +244,0 @@ If you don’t synthesize a stack and run `cdk deploy`, the CDK CLI will automat -When you synthesize a CDK stack to produce a CloudFormation template, logical IDs are generated from the following sources, formatted as `<construct-path><construct-ID><unique-hash>`: @@ -248,5 +246 @@ When you synthesize a CDK stack to produce a CloudFormation template, logical ID - * **Construct path** – The entire path to the construct in your CDK app. This path excludes the ID of the L1 construct, which is always `Resource` or `Default`, and the ID of the top-level stack that it's a part of. - - * **Construct ID** – The ID that you provide as the second argument when instantiating your construct. - - * **Unique hash** – The AWS CDK generates an 8 character unique hash using a deterministic hashing algorithm. This unique hash helps to ensure that logical ID values in your template are unique from one another. The deterministic behavior of this hash generation ensures that the generated logical ID value for each construct remains the same every time that you perform synthesis. The hash value will only change if you modify specific construct values such as your construct's ID or its path. +When you synthesize a CDK stack to produce a CloudFormation template, logical IDs are generated from the following sources, formatted as `construct-pathconstruct-IDunique-hash`: @@ -253,0 +248 @@ When you synthesize a CDK stack to produce a CloudFormation template, logical ID + * **Construct path** – The entire path to the construct in your CDK app. This path excludes the ID of the L1 construct, which is always `Resource` or `Default`, and the ID of the top-level stack that it’s a part of. @@ -254,0 +250 @@ When you synthesize a CDK stack to produce a CloudFormation template, logical ID + * **Construct ID** – The ID that you provide as the second argument when instantiating your construct. @@ -255,0 +252 @@ When you synthesize a CDK stack to produce a CloudFormation template, logical ID + * **Unique hash** – The AWS CDK generates an 8 character unique hash using a deterministic hashing algorithm. This unique hash helps to ensure that logical ID values in your template are unique from one another. The deterministic behavior of this hash generation ensures that the generated logical ID value for each construct remains the same every time that you perform synthesis. The hash value will only change if you modify specific construct values such as your construct’s ID or its path. @@ -313 +306 @@ Python - def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None: + def __init__(self, scope: Construct, construct_id: str, **kwargs) - None: @@ -394 +384 @@ Go - stack := awscdk.NewStack(scope, &id, &sprops) + stack := awscdk.NewStack(scope, id, sprops) @@ -396 +386 @@ Go - awss3.NewBucket(stack, jsii.String("myBucket"), &awss3.BucketProps{ + awss3.NewBucket(stack, jsii.String("myBucket"), awss3.BucketProps{ @@ -406,2 +396 @@ Go -When we run `cdk synth`, a logical ID in the format of `myBucket`unique-hash`` gets generated. The following is an example of this resource in the generated AWS CloudFormation template: - +When we run `cdk synth`, a logical ID in the format of `myBucketunique-hash` gets generated. The following is an example of this resource in the generated AWS CloudFormation template: @@ -520 +506 @@ Python - def __init__(self, scope: Construct, id: str) -> None: + def __init__(self, scope: Construct, id: str) - None: @@ -531 +517 @@ Python - def __init__(self, scope: Construct, id: str) -> None: + def __init__(self, scope: Construct, id: str) - None: @@ -539 +525 @@ Python - def __init__(self, scope: Construct, id: str, **kwargs) -> None: + def __init__(self, scope: Construct, id: str, **kwargs) - None: @@ -673 +654 @@ Go - bar := constructs.NewConstruct(scope, &id) + bar := constructs.NewConstruct(scope, id) @@ -676 +657 @@ Go - awss3.NewBucket(bar, jsii.String("Bucket"), &awss3.BucketProps{ + awss3.NewBucket(bar, jsii.String("Bucket"), awss3.BucketProps{ @@ -690 +671 @@ Go - foo := constructs.NewConstruct(scope, &id) + foo := constructs.NewConstruct(scope, id) @@ -704 +685 @@ Go - stack := awscdk.NewStack(scope, &id, &props.StackProps) + stack := awscdk.NewStack(scope, id, props.StackProps) @@ -716 +697 @@ Go - NewMyCustomAppStack(app, "MyCustomAppStack", &MyCustomAppStackProps{ + NewMyCustomAppStack(app, "MyCustomAppStack", MyCustomAppStackProps{ @@ -723,2 +704 @@ Go -When we run `cdk synth`, a logical ID in the format of `FooBarBucket`unique-hash`` gets generated. The following is an example of this resource in the generated AWS CloudFormation template: - +When we run `cdk synth`, a logical ID in the format of `FooBarBucketunique-hash` gets generated. The following is an example of this resource in the generated AWS CloudFormation template: @@ -738 +721 @@ When we run `cdk synth`, a logical ID in the format of `FooBarBucket`unique-hash -If the default CDK synthesis behavior doesn't suit your needs, you can customize CDK synthesis. To do this, you modify `DefaultStackSynthesizer`, use other available built-in synthesizers, or create your own synthesizer. For instructions, see [Customize CDK stack synthesis](./customize-synth.html). +If the default CDK synthesis behavior doesn’t suit your needs, you can customize CDK synthesis. To do this, you modify `DefaultStackSynthesizer`, use other available built-in synthesizers, or create your own synthesizer. For instructions, see [Customize CDK stack synthesis](./customize-synth.html).