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.
enableStageConfig	boolean		Enable centralized stage configuration (credentials, account, region) for multi-environment CDK deployments.

生成器输出

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

• 文件夹src

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

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

    • application-stack.ts 主应用堆栈
• cdk.json CDK 配置文件
• project.json 项目配置和构建目标
• checkov.yml Checkov 配置文件

如果您设置了 enableStageConfig 选项，生成器还会创建两个用于集中凭证管理的共享包（如果它们尚不存在）：

• 文件夹packages/common

  • 文件夹infra-config 阶段配置类型和凭证映射

    • 文件夹src

      • stages.types.ts 阶段凭证和配置的类型定义
      • stages.config.ts 您的阶段到凭证的映射（编辑此文件）
      • index.ts 用于从其他包导入的重新导出
  • 文件夹scripts 集中式部署/销毁脚本

    • 文件夹src

      • infra-deploy.ts 部署 bin 脚本
      • infra-destroy.ts 销毁 bin 脚本
      • 文件夹stage-credentials/ 共享逻辑（凭证查找、CDK 命令构建）

        • …

提示

您的基础设施是一个 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');
  }
}

阶段与堆栈

CDK 使用 阶段 来组合应一起部署到特定环境的堆栈。生成的 src/main.ts 会创建一个用于您自己开发和测试的沙箱阶段：

src/main.ts

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

env 属性告诉 CDK 要部署到哪个 AWS 账户和区域。CDK_DEFAULT_ACCOUNT 和 CDK_DEFAULT_REGION 由 CDK CLI 从您的活动 AWS 凭证中自动解析。有关更多详细信息，请参阅 CDK 环境文档。

如果您使用 enableStageConfig 生成，main.ts 会从集中式配置文件中读取账户和区域，当未设置配置时会回退到环境变量：

src/main.ts (使用 enableStageConfig)

import stagesConfig from ':my-scope/common-infra-config';

const projectStages = stagesConfig.projects?.['packages/infra']?.stages ?? {};
const sandboxConfig = projectStages['my-app-sandbox'];

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

您可以添加更多阶段来部署到不同的环境。例如，针对不同 AWS 账户的 beta 和 prod 阶段：

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012',
    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';

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,
    });
  }
}

阶段凭证配置

注意

本节适用于使用 enableStageConfig 生成的情况。如果不使用该选项，生成器会生成一个更简单的设置，您需要自己管理 AWS 凭证（例如，在部署前导出 AWS_PROFILE）。

当您有多个针对不同 AWS 账户的阶段时，手动管理凭证可能容易出错，尤其是随着阶段数量的增长。

enableStageConfig 选项通过生成两个共享包来解决这个问题：

• packages/common/infra-config — 一个单一的配置文件，您可以在其中将每个阶段映射到其 AWS 凭证、账户和区域。此文件可从工作区中的任何包导入，因此您的 CDK main.ts 可以从同一真实来源读取账户和区域。
• packages/common/scripts — infra-deploy 和 infra-destroy 命令，它们包装了 CDK 并自动解析凭证。当您运行 deploy 时，脚本会读取配置，为 CDK 子进程设置正确的 AWS 环境变量，并运行 cdk deploy。您的 shell 环境永远不会被修改。

配置凭证

编辑 packages/common/infra-config/src/stages.config.ts 将您的阶段映射到 AWS 凭证：

packages/common/infra-config/src/stages.config.ts

import type { StagesConfig } from './stages.types.js';

const config: StagesConfig = {
  projects: {
    // 键是相对于工作区根目录的项目路径。
    // 这与 project.json 中的路径和部署命令中的路径匹配。
    'packages/infra': {
      stages: {
        // 阶段名称必须与 main.ts 中的 CDK 阶段标识符匹配
        // （`new ApplicationStage(app, 'my-app-dev', ...)` 的第一个参数）。
        'my-app-dev': {
          credentials: { type: 'profile', profile: 'dev-account' },
          region: 'us-east-1',
        },
        'my-app-prod': {
          credentials: {
            type: 'assumeRole',
            assumeRole: 'arn:aws:iam::123456789012:role/DeployRole',
          },
          region: 'us-west-2',
          account: '123456789012',
        },
      },
    },
  },
  shared: {
    // 共享阶段可供所有基础设施项目使用。
    // 项目特定的条目优先于共享条目。
    stages: {
      sandbox: {
        credentials: { type: 'profile', profile: 'personal-sandbox' },
        region: 'us-east-1',
      },
    },
  },
};

export default config;

当您部署时，例如：

pnpm

pnpm nx run infra:deploy my-app-dev/*

yarn

yarn nx run infra:deploy my-app-dev/*

npm

npx nx run infra:deploy my-app-dev/*

bun

bunx nx run infra:deploy my-app-dev/*

部署脚本会：

1. 从命令参数中提取阶段名称 my-app-dev
2. 在配置中查找凭证：首先在 projects['packages/infra'] 下，然后在 shared 下
3. 如果找到，仅为 CDK 子进程设置 AWS_PROFILE（或承担 IAM 角色）
4. 如果未找到，则回退到您环境中的任何 AWS 凭证

这意味着没有任何配置的现有工作流程将继续工作 — 脚本仅在找到匹配条目时应用凭证。

凭证类型

支持两种凭证策略：

• profile — 使用 ~/.aws/config 中的命名 AWS CLI 配置文件。脚本为 CDK 进程设置 AWS_PROFILE。
• assumeRole — 使用指定的角色 ARN 调用 STS AssumeRole，并将临时凭证传递给 CDK。您可以选择指定一个 profile 作为 AssumeRole 调用的源凭证，一个用于跨账户信任策略的 externalId，以及一个以秒为单位的 sessionDuration。

账户和区域

每个阶段配置都包含一个必需的 region 和一个可选的 account：

• region（必需）— 要部署到的 AWS 区域（例如，us-east-1、eu-west-2）。
• account（可选）— AWS 账户 ID。如果省略，CDK 会在部署时从活动凭证中推断它。有关 CDK 如何解析账户和区域的信息，请参阅 CDK 环境文档。

生成的 main.ts 从配置中读取这些值，以便 CDK 合成和部署使用相同的环境设置：

src/main.ts

const sandboxConfig = projectStages['my-app-sandbox'];
new ApplicationStage(app, 'my-app-sandbox', {
  env: {
    account: sandboxConfig?.account ?? process.env.CDK_DEFAULT_ACCOUNT,
    region: sandboxConfig?.region ?? process.env.CDK_DEFAULT_REGION,
  },
});

共享阶段与项目特定阶段

共享阶段（在 shared.stages 下）适用于工作区中的任何基础设施项目。当多个项目部署到同一个沙箱账户时，这很有用 — 您只需定义一次凭证，而不是为每个项目重复定义。

项目特定阶段（在 projects['packages/infra'].stages 下）仅适用于该项目。当同一阶段名称同时存在时，项目特定条目优先。

提示

我们建议提交 stages.config.ts，以便团队共享阶段凭证的单一真实来源。如果它包含个人配置文件名称，您可以将其添加到 .gitignore 并使用本地覆盖。

API 基础设施

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

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

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: 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 { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: 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 应用，需要先进行 引导。引导会创建 CDK 管理部署所需的资源（用于资产的 S3 存储桶、IAM 角色等）。

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

然后，为您计划部署的每个账户和区域运行引导命令：

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

更多详情请参考 CDK 引导文档。

部署到 AWS

构建完成后，可通过 deploy 目标将基础设施部署到 AWS。

警告

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

首先，确保已配置 AWS 凭证。如果您使用 enableStageConfig 生成并在 packages/common/infra-config/src/stages.config.ts 中配置了阶段凭证，部署命令将自动解析并应用目标阶段的正确凭证。否则，请确保在您的环境中设置了 AWS 凭证（例如，通过 AWS_PROFILE 或环境变量）。有关可用选项，请参阅 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 参考。