CDK基础设施

AWS CDK 是一个通过代码定义云基础设施并通过 AWS CloudFormation 进行部署的框架。

TypeScript 基础设施生成器会创建一个用 TypeScript 编写的 AWS CDK 基础设施应用。生成的应用程序通过 CFN Guard 检查集成了安全最佳实践。

使用方式

生成基础设施项目

您可以通过两种方式生成新的基础设施项目：

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#infra
5. 填写必需参数
6. 点击 Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra

yarn

yarn nx g @aws/nx-plugin:ts#infra

npm

npx nx g @aws/nx-plugin:ts#infra

bun

bunx nx g @aws/nx-plugin:ts#infra

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --dry-run

选项参数

参数	类型	默认值	描述
name 必需	string	-	The name of the application.
ruleSet	string	aws_prototyping	Rule set to validate your AWS resources with.
directory	string	packages	The directory of the new application.

生成器输出

生成器将在 <directory>/<name> 目录下创建以下项目结构：

• 文件夹src

  • main.ts 实例化 CDK 部署阶段的应用程序入口点
  • 文件夹stages CDK 阶段定义

    • application-stage.ts 定义要在阶段中部署的堆栈集合
  • 文件夹stacks CDK 堆栈定义

    • application-stack.ts 主应用堆栈
• cdk.json CDK 配置
• project.json 项目配置与构建目标

提示

您的基础设施是一个 TypeScript 项目，因此可以参考 TypeScript 项目文档 了解其常规使用的详细信息。

实现 CDK 基础设施

您可以在 src/stacks/application-stack.ts 中开始编写 CDK 基础设施代码，例如：

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // 在此声明您的基础设施
    new Bucket(this, 'MyBucket');
  }
}

阶段与堆栈

您会注意到顶层的 src/main.ts 文件实例化了一个名为 <namespace>-sandbox 的 CDK 阶段，该阶段用于您自己的开发和测试。

src/main.ts

new ApplicationStage(app, 'project-sandbox', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

您可以添加更多阶段，例如定义部署到不同环境的 beta 和 prod 阶段：

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012', // beta 环境账户
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109', // 生产环境账户
    region: 'us-west-2',
  },
});

阶段定义了应一起部署以构成应用程序的堆栈集合。您可以在阶段内实例化任意数量的堆栈，例如：

src/stages/application-stage.ts

import { Stage, StageProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { BackendStack } from '../stacks/backend-stack.js';
import { FrontendStack } from '../stacks/frontend-stack.js';

/**
 * 定义构成应用程序的 CDK 堆栈集合
 */
export class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    new BackendStack(this, 'Backend', {
      crossRegionReferences: true,
    })

    new FrontendStack(this, 'Frontend', {
      crossRegionReferences: true,
    });
  }
}

API 基础设施

如果您使用过 tRPC API 或 FastAPI 生成器创建 API，您会注意到 packages/common/constructs 中已有一些可用于部署它们的构造。

例如，如果您创建了一个名为 my-api 的 tRPC API，只需导入并实例化该构造即可添加部署所需的所有基础设施：

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 添加 API 的基础设施
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

网站基础设施

如果您使用过 CloudScape 网站 生成器，您会注意到 packages/common/constructs 中已有部署所需的构造。例如：

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 添加网站的基础设施
    new MyWebsite(this, 'MyWebsite');
  }
}

为确保网站 运行时配置 包含所有 API 配置，必须在所有 API 构造之后声明网站。

合成基础设施

作为 build 目标的一部分，除了运行 默认的编译、检查与测试目标 外，您的基础设施项目会被_合成_为 CloudFormation 模板。您也可以通过运行 synth 目标单独执行此操作：

pnpm

pnpm nx run <my-infra>:synth

yarn

yarn nx run <my-infra>:synth

npm

npx nx run <my-infra>:synth

bun

bunx nx run <my-infra>:synth

您可以在根目录的 dist 文件夹下找到合成后的云装配件，路径为 dist/packages/<my-infra-project>/cdk.out。

初始化 AWS 账户

如果是首次向 AWS 账户部署 CDK 应用，需要先进行初始化。

首先，确保已为您的 AWS 账户配置凭证。

接着，使用 cdk bootstrap 命令：

npx cdk bootstrap aws://<account-id>/<region>

更多详情请参考 CDK 文档。

部署到 AWS

构建完成后，您可以使用 deploy 目标将基础设施部署到 AWS。

警告

在 CI/CD 流水线中部署时请使用 deploy-ci 目标，详见下文。

首先，确保已为您的 AWS 账户配置凭证。

接着，运行部署目标：

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/*

提示

上述命令会部署 <my-infra>-sandbox 阶段的所有堆栈。只要在 main.ts 中定义过其他阶段，您也可以指定它们。

您还可以通过指定完整堆栈名称来部署单个堆栈，例如：

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/Application

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/Application

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/Application

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/Application

在 CI/CD 流水线中部署到 AWS

若要在 CI/CD 流水线中部署到 AWS，请使用 deploy-ci 目标。

pnpm

pnpm nx run <my-infra>:deploy-ci my-stage/*

yarn

yarn nx run <my-infra>:deploy-ci my-stage/*

npm

npx nx run <my-infra>:deploy-ci my-stage/*

bun

bunx nx run <my-infra>:deploy-ci my-stage/*

该目标与常规 deploy 目标的区别在于，它确保部署的是预先合成的云装配件，而非动态合成。这有助于避免因软件包版本变化导致的非确定性问题，确保流水线每个阶段都使用相同的云装配件进行部署。

销毁 AWS 基础设施

使用 destroy 目标来销毁您的资源：

pnpm

pnpm nx run <my-infra>:destroy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:destroy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:destroy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:destroy <my-infra>-sandbox/*

更多信息

有关 CDK 的更多信息，请参考 CDK 开发者指南 和 API 参考文档。