這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
資產是本機檔案、目錄或 Docker 映像，可以綁定到 AWS CDK 程式庫和應用程式中。例如，資產可能是包含 AWS Lambda 函數處理常式程式碼的目錄。資產可以代表應用程式需要操作的任何成品。
下列教學影片提供 CDK 資產的全面概觀，並說明如何在基礎設施中將其用作程式碼 (IaC)。
您可以透過特定建構公開APIs AWS 新增資產。例如，當您定義 lambda.Function 建構時，程式碼屬性可讓您傳遞資產 （目錄）。 Function會使用資產來綁定目錄內容，並將其用於函數的程式碼。同樣地，定義 Amazon ECS 任務定義時，ecs.ContainerImage.fromAsset 會使用從本機目錄建置的 Docker 映像。
資產詳細資訊
當您參考應用程式中的資產時，從您的應用程式合成的雲端組件會包含中繼資料資訊以及 CLI AWS CDK 的指示。這些指示包括在哪裡尋找本機磁碟上的資產，以及根據資產類型執行的綁定類型，例如壓縮 (zip) 的目錄或要建置的 Docker 映像。
AWS CDK 會產生資產的來源雜湊。這可以在建構時間用來判斷資產的內容是否已變更。
根據預設， 在來源雜湊下cdk.out， 會在雲端組合目錄中 AWS CDK 建立資產的複本，預設為 。如此一來，雲端組件會獨立運作，因此，如果移至不同的主機進行部署，仍然可以部署。如需詳細資訊，請參閱 雲端組件。
當 AWS CDK 部署參考資產的應用程式 （直接透過應用程式程式碼或透過程式庫） 時， AWS CDK CLI 會先準備並將資產發佈至 Amazon S3 儲存貯體或 Amazon ECR 儲存庫。(S3 儲存貯體或儲存庫是在引導期間建立。) 只有在那時，堆疊中定義的資源才會部署。
本節說明架構中可用的低階 APIs。
資產類型
AWS CDK 支援下列類型的資產：
- Amazon S3 資產
-
這些是 AWS CDK 上傳至 Amazon S3 的本機檔案和目錄。
- Docker 影像
-
這些是 AWS CDK 上傳至 Amazon ECR 的 Docker 映像。
這些資產類型會在下列各節中說明。
Amazon S3 資產
您可以將本機檔案和目錄定義為資產，套件 AWS CDK 會透過 aws-s3-assets 模組將其上傳至 Amazon 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 函數範例
常見的使用案例是使用處理常式程式碼建立 Lambda 函數做為 Amazon S3 資產。
下列範例使用 Amazon S3 資產，在本機目錄 中定義 Python 處理常式handler。它也會建立 Lambda 函數，以本機目錄資產做為 code 屬性。以下是處理常式的 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 程式庫和應用程式中參考的部署時間屬性。CLI AWS CDK 命令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 支援透過 aws-ecr-assets 模組將本機 Docker 映像綁定為資產。
下列範例定義了在本機建置並推送至 Amazon ECR 的 Docker 映像。映像是從本機 Docker 內容目錄 （使用 Dockerfile) 建置，並由 AWS CDK CLI 或應用程式的 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 程式庫和應用程式中參考的部署時間屬性。CLI AWS CDK 命令cdk synth會將資產屬性顯示為 AWS CloudFormation 參數。
Amazon ECS 任務定義範例
常見的使用案例是建立 Amazon ECS 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)
});部署時間屬性範例
下列範例示範如何使用 部署時間屬性imageUri，repository以及 以 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，當您直接或透過 ContainerImage.fromEcrRepository (Python：from_ecr_repository) 使用資產時， 會為您 AWS CDK 管理許可。如果您直接使用 Docker 映像資產，請確定耗用主體具有提取映像的許可。
在大多數情況下，您應該使用 asset.repository.grantPull 方法 (Python：grant_pull。 這會修改主體的 IAM 政策，使其能夠從此儲存庫提取映像。 如果提取映像的委託人不在同一個帳戶中，或者是 AWS 服務，其在您的帳戶中不擔任角色 （例如 AWS CodeBuild)，您必須授予資源政策的提取許可，而不是委託人的政策。 使用 asset.repository.addToResourcePolicy 方法 (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) 方法。
