这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
资产是可以捆绑到 AWS CDK 库和应用程序中的本地文件、目录或 Docker 镜像。例如，资产可能是包含 AWS Lambda 函数处理程序代码的目录。资产可以代表应用程序需要操作的任何构件。
以下教程视频对 CDK 资产进行了全面概述，并说明了如何在基础设施即代码（IaC）中使用 CDK 资产。
您可以通过 APIs 添加由特定 AWS 构造公开的资产。例如，在定义 lambda.Function 构造时，代码属性允许您传递资产（目录）。Function 使用资产捆绑目录内容并将其用于函数的代码。同样，ecs。 ContainerImage.fromasset 在定义 Amazon ECS 任务定义时使用从本地目录构建的 Docker 镜像。
资产详细说明
当您在应用程序中引用资产时，从您的应用程序中合成的云程序集包含带有 AWS CDK CLI 说明的元数据信息。说明包括在资产在本地磁盘中的位置，以及根据资产类型 [例如要压缩的目录（zip）或待构建的 Docker 映像] 执行的捆绑类型。
AWS CDK 生成资产的源哈希值。这可以在构建时用于确定资产内容是否变更。
默认情况下，会在源哈希下 AWS CDK 创建云装配目录中的资源副本cdk.out，默认为该副本。这样云程序集实现了独立，因此，如果将其移至另一台主机进行部署，云程序集仍可部署。有关详细信息，请参阅云程序集。
AWS CDK 部署引用资产的应用程序（直接通过应用程序代码或通过库）时， AWS CDK CLI 会首先准备这些资产并将其发布到 Amazon S3 存储桶或 Amazon ECR 存储库。（S3 存储桶或存储库于启动期间创建。） 只有这样，堆栈中定义的资源才会部署。
本节介绍框架中 APIs 可用的低级别。
资产类型
AWS CDK 支持以下类型的资产：
- Amazon S3 资产
-
这些是 AWS CDK 上传到 Amazon S3 的本地文件和目录。
- Docker 映像
-
这些是 AWS CDK 上传到亚马逊 ECR 的 Docker 镜像。
这些资产类型将在以下部分详细介绍。
Amazon S3 资产
您可以将本地文件和目录定义为资产，然后通过 aw s-s3-assets 模块将它们 AWS CDK 打包并上传到 A mazon S3。
以下示例定义了本地目录资产和文件资产。
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
// Archived and uploaded to Amazon S3 as a .zip file
const directoryAsset = new Asset(this, "SampleZippedDirAsset", {
path: path.join(__dirname, "sample-asset-directory")
});
// Uploaded to Amazon S3 as-is
const fileAsset = new Asset(this, 'SampleSingleFileAsset', {
path: path.join(__dirname, 'file-asset.txt')
});在大多数情况下，您无需直接使用aws-s3-assets模块 APIs 中的。支持资产的模块（例如 aws-lambda）为您提供使用资产的便捷方法。对于 Lambda 函数，您可以采用 fromAsset() 静态方法在本地文件系统中指定目录或 .zip 文件。
Lambda 函数示例
常见用例是将处理程序代码作为 Amazon S3 资产用于创建 Lambda 函数。
以下示例使用 Amazon S3 资产在本地目录 handler 中定义 Python 处理程序。此外还创建了本地目录资产为 code 属性的 Lambda 函数。以下是该处理程序的 Python 代码。
def lambda_handler(event, context):
message = 'Hello World!'
return {
'message': message
}主 AWS CDK 应用程序的代码应如下所示。
import * as cdk from 'aws-cdk-lib';
import { Constructs } from 'constructs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as path from 'path';
export class HelloAssetStack extends cdk.Stack {
constructor(scope: Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);
new lambda.Function(this, 'myLambdaFunction', {
code: lambda.Code.fromAsset(path.join(__dirname, 'handler')),
runtime: lambda.Runtime.PYTHON_3_6,
handler: 'index.lambda_handler'
});
}
}Function 方法使用资产捆绑目录内容，并将其用于函数代码。
提示
Java .jar 文件是具有不同扩展名的 ZIP 文件。文件原样上传至 Amazon S3，但若作为 Lambda 函数部署，其中包含的文件会被提取，而这可能并非如您预期。为避免这种情况，请将 .jar 文件放在目录中并将目录指定为资产。
部署时属性示例
Amazon S3 资产类型还公开了可在 AWS CDK 库和应用程序中引用的部署时属性。C AWS CDK LI 命令cdk synth将资产属性显示为 AWS CloudFormation 参数。
以下示例使用部署时属性将映像资产位置作为环境变量传递至 Lambda 函数中。（文件类型无关紧要；此处使用的 PNG 图像仅为示例。）
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
import * as path from 'path';
const imageAsset = new Asset(this, "SampleAsset", {
path: path.join(__dirname, "images/my-image.png")
});
new lambda.Function(this, "myLambdaFunction", {
code: lambda.Code.asset(path.join(__dirname, "handler")),
runtime: lambda.Runtime.PYTHON_3_6,
handler: "index.lambda_handler",
environment: {
'S3_BUCKET_NAME': imageAsset.s3BucketName,
'S3_OBJECT_KEY': imageAsset.s3ObjectKey,
'S3_OBJECT_URL': imageAsset.s3ObjectUrl
}
});权限
若直接通过 aws-s3-assets 模块、IAM 角色、用户或组使用 Amazon S3 资产，并且需要在运行时读取资产，请通过 asset.grantRead 方法向这些资产授予 IAM 权限。
以下示例向 IAM 组授予文件资产的读取权限。
import { Asset } from 'aws-cdk-lib/aws-s3-assets';
import * as path from 'path';
const asset = new Asset(this, 'MyFile', {
path: path.join(__dirname, 'my-image.png')
});
const group = new iam.Group(this, 'MyUserGroup');
asset.grantRead(group);Docker 映像资产
AWS CDK 支持通过模块将本地 Docker 镜像捆绑为资产。aws-ecr-assets
以下示例定义本地构建并推送至 Amazon ECR 的 Docker 映像。镜像从本地 Docker 上下文目录（带有 Dockerfile）构建，并通过 CL AWS CDK I 或应用程序的 CI/CD 管道上传到 Amazon ECR。这些图像可以在您的 AWS CDK 应用程序中自然引用。
import { DockerImageAsset } from 'aws-cdk-lib/aws-ecr-assets';
const asset = new DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image')
});my-image 目录必须包含 Dockerfile。 AWS CDK CLI 从构建 Docker 映像my-image，将其推送到 Amazon ECR 存储库，并将存储库的名称指定为堆栈的 AWS CloudFormation
参数。Docker 镜像资产类型公开了可以在 AWS CDK 库和应用程序中引用的部署时属性。C AWS CDK LI 命令cdk
synth将资产属性显示为 AWS CloudFormation 参数。
Amazon ECS 任务定义示例
一个常见的用例是创建一台 Amazon 弹性云服务器TaskDefinition来运行 Docker 容器。以下示例指定了在本地 AWS CDK 构建并推送到 Amazon ECR 的 Docker 映像资产的位置。
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as ecr_assets from 'aws-cdk-lib/aws-ecr-assets';
import * as path from 'path';
const taskDefinition = new ecs.FargateTaskDefinition(this, "TaskDef", {
memoryLimitMiB: 1024,
cpu: 512
});
const asset = new ecr_assets.DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image')
});
taskDefinition.addContainer("my-other-container", {
image: ecs.ContainerImage.fromDockerImageAsset(asset)
});部署时属性示例
以下示例说明如何使用部署时间属性repository以及imageUri如何使用 AWS Fargate 启动类型创建 Amazon ECS 任务定义。请注意，Amazon ECR 存储库查询需要映像的标签而非其 URI，因此我们从资产 URI 的末尾截取标签。
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as path from 'path';
import { DockerImageAsset } from 'aws-cdk-lib/aws-ecr-assets';
const asset = new DockerImageAsset(this, 'my-image', {
directory: path.join(__dirname, "..", "demo-image")
});
const taskDefinition = new ecs.FargateTaskDefinition(this, "TaskDef", {
memoryLimitMiB: 1024,
cpu: 512
});
taskDefinition.addContainer("my-other-container", {
image: ecs.ContainerImage.fromEcrRepository(asset.repository, asset.imageUri.split(":").pop())
});构建参数示例
当 AWS CDK CLI 在部署期间构建映像时，您可以通过 buildArgs (Python:build_args) 属性选项为 Docker 构建步骤提供自定义的构建参数。
const asset = new DockerImageAsset(this, 'MyBuildImage', {
directory: path.join(__dirname, 'my-image'),
buildArgs: {
HTTP_PROXY: 'http://10.20.30.2:1234'
}
});权限
如果您使用支持 Docker 镜像资源的模块（例如 aws-ecs），则在您直接或通过使用资源时，它会为您 AWS CDK 管理权限。ContainerImage fromEcrRepository(Python:from_ecr_repository)。如果您直接使用 Docker 映像资产，请确保使用主体拥有拉取映像的权限。
在大多数情况下，你应该使用 asset.repository.gran tPull 方法 (Python:. grant_pull 这会修改委托人的 IAM 策略，使其能够从此存储库中提取图像。 如果拉取图片的委托人不在同一个账户中，或者该 AWS 服务不在你的账户中扮演角色（例如 AWS CodeBuild），则必须授予对资源策略而不是委托人策略的拉取权限。 使用 asset.repository。 addToResource授予相应委托人权限的策略方法 (Python:add_to_resource_policy)。
AWS CloudFormation 资源元数据
注意
本节仅与构造作者相关。在某些情况下，工具需要了解某个 CFN 资源正在使用本地资产。例如，您可以使用 AWS SAM CLI 在本地调用 Lambda 函数以进行调试。有关详细信息，请参阅AWS SAM 整合。
要启用此类用例，外部工具会查阅 AWS CloudFormation 资源上的一组元数据条目：
-
aws:asset:path– 指向资产的本地路径。 -
aws:asset:property– 使用资产的资源属性的名称。
通过使用这两个元数据条目，工具可以识别特定资源是否使用资产，并提供高级本地体验。
要将这些元数据条目添加至资源中，请使用 asset.addResourceMetadata（Python：add_resource_metadata）方法。
