AWS cdk documentation change
Summary
Fixed typos, corrected markdown link syntax, updated code examples (primarily Go language syntax), and improved documentation clarity for AWS CDK asset handling. Changes include infrastructure spelling correction, quote style fixes, and code example adjustments for struct initialization.
Security assessment
The changes are primarily grammatical improvements, documentation formatting, and code example corrections. No specific security vulnerabilities or weaknesses are addressed. Security-related IAM permission guidance (e.g., grantRead/grantPull) already existed and was only reformatted with markdown links.
Diff
diff --git a/cdk/v2/guide/assets.md b/cdk/v2/guide/assets.md index 9e99896c8..3b8af4c73 100644 --- a//cdk/v2/guide/assets.md +++ b//cdk/v2/guide/assets.md @@ -13 +13 @@ Assets are local files, directories, or Docker images that can be bundled into A -The following tutorial video provides a comprehensive overview of CDK assets, and explains how you can use them in your insfrastructure as code (IaC). +The following tutorial video provides a comprehensive overview of CDK assets, and explains how you can use them in your infrastructure as code (IaC). @@ -15 +15 @@ The following tutorial video provides a comprehensive overview of CDK assets, an -You add assets through APIs that are exposed by specific AWS constructs. For example, when you define a [lambda.Function](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html) construct, the [code](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html#code) property lets you pass an [asset](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html#static-fromwbrassetpath-options) (directory). `Function` uses assets to bundle the contents of the directory and use it for the function's code. Similarly, [ecs.ContainerImage.fromAsset](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerImage.html#static-fromwbrassetdirectory-props) uses a Docker image built from a local directory when defining an Amazon ECS task definition. +You add assets through APIs that are exposed by specific AWS constructs. For example, when you define a [`lambda.Function`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html) construct, the [`code`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html#code) property lets you pass an [`asset`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html#static-fromwbrassetpath-options) (directory). `Function` uses assets to bundle the contents of the directory and use it for the function’s code. Similarly, [`ecs.ContainerImage.fromAsset`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerImage.html#static-fromwbrassetdirectory-props) uses a Docker image built from a local directory when defining an Amazon ECS task definition. @@ -19 +19 @@ You add assets through APIs that are exposed by specific AWS constructs. For exa -When you refer to an asset in your app, the [cloud assembly](./deploy.html#deploy-how-synth-assemblies) that's synthesized from your application includes metadata information with instructions for the AWS CDK CLI. The instructions include where to find the asset on the local disk and what type of bundling to perform based on the asset type, such as a directory to compress (zip) or a Docker image to build. +When you refer to an asset in your app, the [cloud assembly](./deploy.html#deploy-how-synth-assemblies) that’s synthesized from your application includes metadata information with instructions for the AWS CDK CLI. The instructions include where to find the asset on the local disk and what type of bundling to perform based on the asset type, such as a directory to compress (zip) or a Docker image to build. @@ -47 +47 @@ These asset types are explained in the following sections. -You can define local files and directories as assets, and the AWS CDK packages and uploads them to Amazon S3 through the [aws-s3-assets](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets-readme.html) module. +You can define local files and directories as assets, and the AWS CDK packages and uploads them to Amazon S3 through the [`aws-s3-assets`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets-readme.html) module. @@ -149 +149 @@ Go - awss3assets.NewAsset(stack, jsii.String("SampleZippedDirAsset"), &awss3assets.AssetProps{ + awss3assets.NewAsset(stack, jsii.String("SampleZippedDirAsset"), awss3assets.AssetProps{ @@ -153 +153 @@ Go - awss3assets.NewAsset(stack, jsii.String("SampleSingleFileAsset"), &awss3assets.AssetProps{ + awss3assets.NewAsset(stack, jsii.String("SampleSingleFileAsset"), awss3assets.AssetProps{ @@ -157 +157 @@ Go -In most cases, you don't need to directly use the APIs in the `aws-s3-assets` module. Modules that support assets, such as `aws-lambda`, have convenience methods so that you can use assets. For Lambda functions, the [fromAsset()](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html#static-fromwbrassetpath-options) static method enables you to specify a directory or a .zip file in the local file system. +In most cases, you don’t need to directly use the APIs in the `aws-s3-assets` module. Modules that support assets, such as `aws-lambda`, have convenience methods so that you can use assets. For Lambda functions, the [`fromAsset()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html#static-fromwbrassetpath-options) static method enables you to specify a directory or a .zip file in the local file system. @@ -308 +307 @@ Go - stack := awscdk.NewStack(scope, &id, &sprops) + stack := awscdk.NewStack(scope, id, sprops) @@ -315,2 +314,2 @@ Go - awslambda.NewFunction(stack, jsii.String("myLambdaFunction"), &awslambda.FunctionProps{ - Code: awslambda.AssetCode_FromAsset(jsii.String(path.Join(dirName, "handler")), &awss3assets.AssetOptions{}), + awslambda.NewFunction(stack, jsii.String("myLambdaFunction"), awslambda.FunctionProps{ + Code: awslambda.AssetCode_FromAsset(jsii.String(path.Join(dirName, "handler")), awss3assets.AssetOptions{}), @@ -324 +323 @@ Go -The `Function` method uses assets to bundle the contents of the directory and use it for the function's code. +The `Function` method uses assets to bundle the contents of the directory and use it for the function’s code. @@ -332 +331 @@ Java `.jar` files are ZIP files with a different extension. These are uploaded a -Amazon S3 asset types also expose [deploy-time attributes](./resources.html#resources-attributes) that can be referenced in AWS CDK libraries and apps. The AWS CDK CLI command **cdk synth** displays asset properties as AWS CloudFormation parameters. +Amazon S3 asset types also expose [deploy-time attributes](./resources.html#resources-attributes) that can be referenced in AWS CDK libraries and apps. The AWS CDK CLI command `cdk synth` displays asset properties as AWS CloudFormation parameters. @@ -334 +333 @@ Amazon S3 asset types also expose [deploy-time attributes](./resources.html#reso -The following example uses deploy-time attributes to pass the location of an image asset into a Lambda function as environment variables. (The kind of file doesn't matter; the PNG image used here is only an example.) +The following example uses deploy-time attributes to pass the location of an image asset into a Lambda function as environment variables. (The kind of file doesn’t matter; the PNG image used here is only an example.) @@ -456 +455 @@ C# - Environment = new Dictionary<string, string> + Environment = new Dictionarystring, string @@ -482 +481 @@ Go - imageAsset := awss3assets.NewAsset(stack, jsii.String("SampleAsset"), &awss3assets.AssetProps{ + imageAsset := awss3assets.NewAsset(stack, jsii.String("SampleAsset"), awss3assets.AssetProps{ @@ -486 +485 @@ Go - awslambda.NewFunction(stack, jsii.String("myLambdaFunction"), &awslambda.FunctionProps{ + awslambda.NewFunction(stack, jsii.String("myLambdaFunction"), awslambda.FunctionProps{ @@ -490 +489 @@ Go - Environment: &map[string]*string{ + Environment: map[string]*string{ @@ -499 +498 @@ Go -If you use Amazon S3 assets directly through the [aws-s3-assets](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets-readme.html) module, IAM roles, users, or groups, and you need to read assets in runtime, then grant those assets IAM permissions through the [asset.grantRead](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.Asset.html#grantwbrreadgrantee) method. +If you use Amazon S3 assets directly through the [`aws-s3-assets`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets-readme.html) module, IAM roles, users, or groups, and you need to read assets in runtime, then grant those assets IAM permissions through the [`asset.grantRead`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.Asset.html#grantwbrreadgrantee) method. @@ -607 +604 @@ Go - asset := awss3assets.NewAsset(stack, jsii.String("MyFile"), &awss3assets.AssetProps{ + asset := awss3assets.NewAsset(stack, jsii.String("MyFile"), awss3assets.AssetProps{ @@ -611 +608 @@ Go - group := awsiam.NewGroup(stack, jsii.String("MyUserGroup"), &awsiam.GroupProps{}) + group := awsiam.NewGroup(stack, jsii.String("MyUserGroup"), awsiam.GroupProps{}) @@ -617 +614 @@ Go -The AWS CDK supports bundling local Docker images as assets through the [aws-ecr-assets](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr_assets-readme.html) module. +The AWS CDK supports bundling local Docker images as assets through the [`aws-ecr-assets`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr_assets-readme.html) module. @@ -619 +616 @@ The AWS CDK supports bundling local Docker images as assets through the [aws-ecr -The following example defines a Docker image that is built locally and pushed to Amazon ECR. Images are built from a local Docker context directory (with a Dockerfile) and uploaded to Amazon ECR by the AWS CDK CLI or your app's CI/CD pipeline. The images can be naturally referenced in your AWS CDK app. +The following example defines a Docker image that is built locally and pushed to Amazon ECR. Images are built from a local Docker context directory (with a Dockerfile) and uploaded to Amazon ECR by the AWS CDK CLI or your app’s CI/CD pipeline. The images can be naturally referenced in your AWS CDK app. @@ -693 +690 @@ Go - asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), &awsecrassets.DockerImageAssetProps{ + asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), awsecrassets.DockerImageAssetProps{ @@ -697 +694 @@ Go -The `my-image` directory must include a Dockerfile. The AWS CDK CLI builds a Docker image from `my-image`, pushes it to an Amazon ECR repository, and specifies the name of the repository as an AWS CloudFormation parameter to your stack. Docker image asset types expose [deploy-time attributes](./resources.html#resources-attributes) that can be referenced in AWS CDK libraries and apps. The AWS CDK CLI command **cdk synth** displays asset properties as AWS CloudFormation parameters. +The `my-image` directory must include a Dockerfile. The AWS CDK CLI builds a Docker image from `my-image`, pushes it to an Amazon ECR repository, and specifies the name of the repository as an AWS CloudFormation parameter to your stack. Docker image asset types expose [deploy-time attributes](./resources.html#resources-attributes) that can be referenced in AWS CDK libraries and apps. The AWS CDK CLI command `cdk synth` displays asset properties as AWS CloudFormation parameters. @@ -701 +698 @@ The `my-image` directory must include a Dockerfile. The AWS CDK CLI builds a Doc -A common use case is to create an Amazon ECS [TaskDefinition](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.TaskDefinition.html) to run Docker containers. The following example specifies the location of a Docker image asset that the AWS CDK builds locally and pushes to Amazon ECR. +A common use case is to create an Amazon ECS [`TaskDefinition`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.TaskDefinition.html) to run Docker containers. The following example specifies the location of a Docker image asset that the AWS CDK builds locally and pushes to Amazon ECR. @@ -788,0 +786 @@ Java + ) @@ -832 +830 @@ Go - taskDefinition := awsecs.NewTaskDefinition(stack, jsii.String("TaskDef"), &awsecs.TaskDefinitionProps{ + taskDefinition := awsecs.NewTaskDefinition(stack, jsii.String("TaskDef"), awsecs.TaskDefinitionProps{ @@ -837 +835 @@ Go - asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), &awsecrassets.DockerImageAssetProps{ + asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), awsecrassets.DockerImageAssetProps{ @@ -841 +839 @@ Go - taskDefinition.AddContainer(jsii.String("MyOtherContainer"), &awsecs.ContainerDefinitionOptions{ + taskDefinition.AddContainer(jsii.String("MyOtherContainer"), awsecs.ContainerDefinitionOptions{ @@ -847 +845 @@ Go -The following example shows how to use the deploy-time attributes `repository` and `imageUri` to create an Amazon ECS task definition with the AWS Fargate launch type. Note that the Amazon ECR repo lookup requires the image's tag, not its URI, so we snip it from the end of the asset's URI. +The following example shows how to use the deploy-time attributes `repository` and `imageUri` to create an Amazon ECS task definition with the AWS Fargate launch type. Note that the Amazon ECR repo lookup requires the image’s tag, not its URI, so we snip it from the end of the asset’s URI. @@ -980 +978 @@ Go - asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyImage"), &awsecrassets.DockerImageAssetProps{ + asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyImage"), awsecrassets.DockerImageAssetProps{ @@ -984 +982 @@ Go - taskDefinition := awsecs.NewFargateTaskDefinition(stack, jsii.String("TaskDef"), &awsecs.FargateTaskDefinitionProps{ + taskDefinition := awsecs.NewFargateTaskDefinition(stack, jsii.String("TaskDef"), awsecs.FargateTaskDefinitionProps{ @@ -989 +987 @@ Go - taskDefinition.AddContainer(jsii.String("MyOtherContainer"), &awsecs.ContainerDefinitionOptions{ + taskDefinition.AddContainer(jsii.String("MyOtherContainer"), awsecs.ContainerDefinitionOptions{ @@ -1043 +1041 @@ C# - BuildArgs = new Dictionary<string, string> + BuildArgs = new Dictionarystring, string @@ -1058 +1056 @@ Go - asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), &awsecrassets.DockerImageAssetProps{ + asset := awsecrassets.NewDockerImageAsset(stack, jsii.String("MyBuildImage"), awsecrassets.DockerImageAssetProps{ @@ -1060 +1058 @@ Go - BuildArgs: &map[string]*string{ + BuildArgs: map[string]*string{ @@ -1067 +1065 @@ Go -If you use a module that supports Docker image assets, such as [aws-ecs](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs-readme.html), the AWS CDK manages permissions for you when you use assets directly or through [ContainerImage.fromEcrRepository](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerImage.html#static-fromwbrecrwbrrepositoryrepository-tag) (Python: `from_ecr_repository`). If you use Docker image assets directly, make sure that the consuming principal has permissions to pull the image. +If you use a module that supports Docker image assets, such as [`aws-ecs`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs-readme.html), the AWS CDK manages permissions for you when you use assets directly or through [`ContainerImage.fromEcrRepository`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecs.ContainerImage.html#static-fromwbrecrwbrrepositoryrepository-tag) (Python: `from_ecr_repository`). If you use Docker image assets directly, make sure that the consuming principal has permissions to pull the image. @@ -1069 +1067 @@ If you use a module that supports Docker image assets, such as [aws-ecs](https:/ -In most cases, you should use [asset.repository.grantPull](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr.Repository.html#grantwbrpullgrantee) method (Python: `grant_pull`. This modifies the IAM policy of the principal to enable it to pull images from this repository. If the principal that is pulling the image is not in the same account, or if it's an AWS service that doesn't assume a role in your account (such as AWS CodeBuild), you must grant pull permissions on the resource policy and not on the principal's policy. Use the [asset.repository.addToResourcePolicy](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr.Repository.html#addwbrtowbrresourcewbrpolicystatement) method (Python: `add_to_resource_policy`) to grant the appropriate principal permissions. +In most cases, you should use [`asset.repository.grantPull`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr.Repository.html#grantwbrpullgrantee) method (Python: `grant_pull`). This modifies the IAM policy of the principal to enable it to pull images from this repository. If the principal that is pulling the image is not in the same account, or if it’s an AWS service that doesn’t assume a role in your account (such as AWS CodeBuild), you must grant pull permissions on the resource policy and not on the principal’s policy. Use the [`asset.repository.addToResourcePolicy`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ecr.Repository.html#addwbrtowbrresourcewbrpolicystatement) method (Python: `add_to_resource_policy`) to grant the appropriate principal permissions.