部署时间构建
AWS CDK L3 构造允许您为特定目的运行一个构建任务 。 目前,该图书馆支持下列使用案例:
- 构建网络前端静态文件
- 构建容器图像
- 为容器图像构建可搜索OCI(SOCI)索引
使用量
从 npm 安装 :
npm i @cdklabs/deploy-time-build
这个库定义了几种用于特定用途的L3构造. 以下是每个案例的用法.
构建节点js 应用程序
您可以在部署时间前构建一个节点. js app, 如 React 前端 app NodejsBuild 构造.
以下代码是使用构造的实例 :
import { NodejsBuild } from '@cdklabs/deploy-time-build';
new NodejsBuild(this, 'ExampleBuild', {
assets: [
{
path: 'example-app',
exclude: ['dist', 'node_modules'],
},
],
destinationBucket,
distribution,
outputSourceDirectory: 'dist',
buildCommands: ['npm ci', 'npm run build'],
buildEnvironment: {
VITE_API_ENDPOINT: api.url,
},
nodejsVersion: 24,
});
请注意,有可能通过环境变量 VITE_API_ENDPOINT: api.url ,并注入建筑环境(在此情况下是一个活化过程)
由此产生的建筑文物将部署到 destinationBucket 从代码构建.
您可以通过 assets 属性。 这些资产被提取到相应的子目录. 例如,假设您指定的资产如下:
new NodejsBuild(this, 'ExampleBuild', {
assets: [
{
// directory containing source code and package.json
path: 'example-app',
exclude: ['dist', 'node_modules'],
commands: ['npm install'],
},
{
// directory that is also required for the build
path: 'module1',
},
],
destinationBucket,
distribution,
outputSourceDirectory: 'dist',
nodejsVersion: 24,
});
然后,所取目录将定位如下:
. # a temporary directory (automatically created)
├── example-app # extracted example-app assets
│ ├── src/ # dist or node_modules directories are excluded even if they exist locally.
│ ├── package.json # npm install will be executed since its specified in `commands` property.
│ └── package-lock.json
└── module1 # extracted module1 assets
您也可以覆盖通过 extractPath 每个资产的财产.
与 outputEnvFile 属性启用, a .env 文件会自动生成并上传到您的 S3 桶。 此文件可以在本地运行您的前端工程 。 通过运行堆栈输出中添加的命令,您可以将文件下载到您的本地机器.
请检查 示例目录 一个完整的例子.
允许从建筑环境进入其他AWS资源
自兹 NodejsBuild 构造工具 iam.IGrantable 界面,您可以使用 grant* 允许从建筑环境进入的其他构造方法.
declare const someBucket: s3.IBucket;
declare const build: NodejsBuild;
someBucket.grantReadWrite(build);
您还可以使用 iam.Grant 允许任何行动和资源.
declare const build: NodejsBuild;
iam.Grant.addToPrincipal({ grantee: build, actions: ['s3:ListBucket'], resourceArns:['*'] })
动机 - 为什么我们需要 NodejsBuild 构造?
在2023年的CDK日, 见下文录制或幻灯片:
缓存
您可以启用 npm 缓存以加速使用 cache 属性 :
new NodejsBuild(this, 'ExampleBuild', {
assets: [
{
path: 'example-app',
exclude: ['dist', 'node_modules'],
},
],
destinationBucket,
outputSourceDirectory: 'dist',
cache: CacheType.S3, // or CacheType.LOCAL
nodejsVersion: 24,
});
有两种缓存类型:
CacheType.S3: 将 npm 缓存目录存储在 S3 桶中 。 在不同的主机上运行的不经常.CacheType.LOCAL:将 npm 缓存目录存储在构建主机上. 速度比S3快,但只有在相同的主机上运行才有效.
计算类型
您可以使用 computeType 属性 :
new NodejsBuild(this, 'ExampleBuild', {
assets: [
{
path: 'example-app',
exclude: ['dist', 'node_modules'],
},
],
destinationBucket,
outputSourceDirectory: 'dist',
computeType: ComputeType.MEDIUM,
nodejsVersion: 24,
});
考虑因素
由于此构建每次您部署堆栈时都会构建您前端的应用程序, 并且输入资产有任何变化( 而目前 Lambda 函数中甚至没有构建缓存 !) , 部署的时间往往会更长( 例如, 即使是简单的应用程序, 也只有几分钟 ) example 目录。 ) 如果您想要频繁部署更改( magine ) , 可能会导致开发者经历更糟糕 cdk watch 部署总是重建你的前端应用程序.
为了缓解这个问题,你可以将前端构造的堆栈与其他堆栈分开,特别是为了一个 dev 环境. 另一种解决办法是将固定字符串设为资产散列,并避免在每次部署的基础上继续使用.
new NodejsBuild(this, 'ExampleBuild', {
assets: [
{
path: '../frontend',
exclude: ['node_modules', 'dist'],
commands: ['npm ci'],
// Set a fixed string as a asset hash to prevent deploying changes.
// This can be useful for an environment you use to develop locally.
assetHash: 'frontend_asset',
},
],
destinationBucket,
distribution,
outputSourceDirectory: 'dist',
nodejsVersion: 24,
});
构建容器图像
您可以在部署时使用以下代码构建容器图像:
import { ContainerImageBuild } from '@cdklabs/deploy-time-build';
const image = new ContainerImageBuild(this, 'Build', {
directory: 'example-image',
buildArgs: { DUMMY_FILE_SIZE_MB: '15' },
tag: 'my-image-tag',
});
new DockerImageFunction(this, 'Function', {
code: image.toLambdaDockerImageCode(),
});
const armImage = new ContainerImageBuild(this, 'BuildArm', {
directory: 'example-image',
platform: Platform.LINUX_ARM64,
repository: image.repository,
zstdCompression: true,
});
new FargateTaskDefinition(this, 'TaskDefinition', {
runtimePlatform: { cpuArchitecture: CpuArchitecture.ARM64 }
}).addContainer('main', {
image: armImage.toEcsDockerImageCode(),
});
第三个参数(props)是多克-伊玛格-阿塞特属性的超集. 您可以设置一些额外的属性, 如 tag, (中文(简体) ), repository,以及 zstdCompression。 。 。 .
为容器图像构建 SOCI 索引
可搜索 OCI (SOCI) 是帮助在远门 1. 4.0 上更快地启动亚马逊ECS任务的方法. 您可以使用 SociIndexV2Build 构造.
以下代码是使用构造的实例 :
import { SociIndexV2Build } from '@cdklabs/deploy-time-build';
const asset = new DockerImageAsset(this, 'Image', { directory: 'example-image' });
const sociIndex = new SociIndexV2Build(this, 'SociV2Index', {
repository: asset.repository,
inputImageTag: asset.assetHash,
outputImageTag: `${asset.assetHash}-soci`,
});
// Use with ECS Fargate
const taskDefinition = new FargateTaskDefinition(this, 'TaskDefinition');
taskDefinition.addContainer('main', {
image: sociIndex.toEcsDockerImageCode(),
});
// Or create from DockerImageAsset using utility method
const sociIndexFromAsset = SociIndexV2Build.fromDockerImageAsset(this, 'SociV2Index2', asset);
这个 SociIndexV2Build 构造 :
- 使用输入容器图像并构建 SOCI v2 索引
- 使用嵌入的 SOCI 索引输出新图像标签
- 提供
toEcsDockerImageCode()易与ECS任务使用的方法 - 在输入和输出图像时使用相同的ECR寄存器
我们目前使用 soci-wrapper 建立和推动SCI指数.
[尖叫声] 前一个
SocideIndexBuild构造现已贬值。 AWS Fargate上的SOCI新客户只能使用SOCI指数表 v2. 见 本条 更多细节.
动机 - 为什么我们需要 SociIndexBuild 构造?
目前还有其他几种方法来构建SICI指数; 1. 使用 soci-snapshotter CLI,或作 2. 使用 cfn-ecr-aws-soci-index-建设者 溶液,其中无一能从AWS CDK直接被使用. 熟悉CDK的,应当经常将容器图像作为CDK资产来部署,这是与ECS等其他L2构造融合的理想方式. 为了使SOCI的开发者经验与普通容器图像相近 SociIndexBuild 允许您直接从 CDK 中部署 SOCI 索引,而不在 CDK 上下文之外设置任何依赖性.
发展
维护者的命令 :
# run test locally
npx tsc -p tsconfig.dev.json
npx integ-runner
npx integ-runner --update-on-failed