CDK基础设施

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

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

使用方式

生成基础设施项目

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

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.
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 项目配置和构建目标
• checkov.yml Checkov 配置文件

提示

您的基础设施是一个 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。

安全测试

项目中添加了 checkov 目标，使用 Checkov 对基础设施进行安全检查。

pnpm

pnpm nx run <my-infra>:checkov

yarn

yarn nx run <my-infra>:checkov

npm

npx nx run <my-infra>:checkov

bun

bunx nx run <my-infra>:checkov

安全测试结果位于根目录的 dist 文件夹下，路径为 dist/packages/<my-infra-project>/checkov。

注意

Checkov 通过 uvx 运行，因此需要 安装 uv（如果尚未安装）。

警告

默认情况下，checkov.yml 文件会抑制部分 Checkov 规则。建议根据您的使用场景重新审查这些规则。

抑制 Checkov 检查

在某些情况下，您可能需要抑制特定资源上的某些规则。可通过两种方式实现：

在指定构造上抑制规则

import { suppressRules } from ':my-scope/common-constructs';

// 抑制指定构造的 CKV_AWS_XXX 规则
suppressRules(construct, ['CKV_AWS_XXX'], '原因说明');

在派生构造上抑制规则

import { suppressRules } from ':my-scope/common-constructs';

// 如果构造或其派生构造是 Bucket 实例，则抑制 CKV_AWS_XXX 规则
suppressRules(construct, ['CKV_AWS_XXX'], '原因说明', (construct) => construct instanceof Bucket);

引导 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 流水线中部署时，请使用 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 参考。