AWS CDK 工具包库

AWS Cloud Development Kit(AWS CDK)工具包库使您能够执行需要AWS程序访问的CDK动作. 您可以使用 AWS CDK 工具包库来实施诸如靴子绑定,合成等动作,并通过代码而不是命令行界面(CLI)命令来部署. 通过这个库,您可以创建自定义工具,构建专门的CLI应用程序,并将CDK程序访问能力整合到您的开发工作流程中.

启动 AWS CDK 工具包库

步骤1:安装 CDK 工具包库

添加数据 @aws-cdk/toolkit-lib 代码基础的软件包 :

npm install --save @aws-cdk/toolkit-lib

第2步:创建并配置新的 CDK 工具包实例

您将使用 CDK 工具包实例来定义要在您的 CDK 应用程序上执行的动作 . 以下是创建CDK工具包新实例的例子:

import { Toolkit } from '@aws-cdk/toolkit-lib';

const cdk = new Toolkit({
   // Optional configuration options go here
});

您可以在创建期间选择自定义 CDK 工具包实例 . 关于说明,见 配置您的 CDK 工具包实例。 。 。 .

步骤 3: 为您的 CDK 应用程序创建云组装源

A 类 云团 代表由 CDK app 生成的 AWS CloudFormation 模板和部署文物. 利用CDK, 云会是在合成过程中产生的, 是用来提供你的基础设施的. CDK 工具包创建 云团 从a 云组源。 。 。 .

这个 云组源 cDK工具箱的一个基本组成部分,它界定了创建一个 云团 从你的应用程序. 例如,CDK应用程序在准备就绪之前可能需要用额外的上下文值进行多次合成. 一旦创建,你就可以使用你的 云组源 用 CDK 工具箱执行动作.

下面是创建一个 云组源 使用 组装构建器功能数字 :

import * as core from 'aws-cdk-lib/core';

declare const cdk: Toolkit;

const cx = await cdk.fromAssemblyBuilder(async (props) => {
  const app = new core.App({
    outdir: props.outdir,
    context: props.context,
  });

  // Define your stacks here
  new MyStack(app, 'MyStack', {
    env: {
      account: props.CDK_DEFAULT_ACCOUNT,
      region: props.CDK_DEFAULT_REGION,
    },
  });

  return app.synth();
});

详情见 云组源。 。 。 .

步骤 4: 为您的 CDK 应用程序定义方案行动

现在您已经创建了 CDK 工具包实例和 Cloud Assembly Source, 您可以开始定义方案行动 . 下面是一个基本例子,可以部署 MyStack 堆栈 :

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.deploy(cx, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["MyStack"],
  },
});

第5步:进一步定制光盘工具包

您可以为您的需要进一步配置和定制 CDK 工具包 :

• 信件和请求 - CDK工具包提供有条理的信息流,并向客户请求,例如使用CDK工具包的人类行为者或应用程序。 关于说明,见 信件交互( M)。 。 。 .
• 处理错误 - CDK工具箱使用结构化错误帮助您在工具箱操作中识别和处理问题。 您可以将错误处理整合到您的应用程序中, 或者根据您的需要进一步定制它们 。 关于说明,见 处理错误。 。 。 .

行动

CDK工具包库为下列生命周期行动提供方案接口. 对进一步行动的支持将逐步扩大.

合成

合成是生产AWS CloudFormation模板和从CDK应用中部署文物的过程. 综合介绍见 配置并进行 CDK 堆栈合成。 。 。 . 在 CDK 工具包库中,您可以使用合成生成一个可重复使用的快照 云组源。 。 。 . 如果同一来源将被用于多个工具包行动,这将是有益的, 因为 云团 无需多次生产.

declare const cdk: Toolkit;
declare const source: ICloudAssemblySource;

// Will run the CDK app defined in the Cloud Assembly Source
// This is an expensive and slow operation
// But its result can be stored and re-used
const cx = await cdk.synth(source, {
  validateStacks: true, // set to `false` to not throw an error if stacks in the assembly contain error annotations
})

// Will use the previously synthesized Cloud Assembly
// This is now a cheap and fast operation
const appDetails = await cdk.list(cx);

您也可以查询关于已合成的信息 云团数字 :

const cloudAssembly = await cx.produce();
const template = cloudAssembly.getStackByName("my-stack").template;

列表

列表操作在一个 CDK 应用程序中提供有关堆栈及其依赖的高级信息.

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

const details = await cdk.list(cx, {
  // optionally provide a stack selector to control which stacks are returned
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"],
  }
});

微调

您可以创建一个应用程序的 diff 来详细了解下个部署中将会发生什么变化.

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

const stackDiffs = await cdk.diff(cx, {
  // optionally provide a stack selector to control which stacks you want to create a diff for
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"],
  }
});

部署

部署是使用在合成过程中生成的CloudFormation模板和资产在AWS提供或更新基础设施的过程. 关于部署的介绍,见 部署 AWS CDK 应用程序。 。 。 . 有了CDK工具包库,可以程序控制部署,包括堆栈选择,回滚行为,部署监测.

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.deploy(cx, {
  deploymentMethod: { method: "direct " }, // use direct deployments instead of change-sets
  parameters: StackParameters.exactly({ /* ... */ }), // provide new values for stack parameters
})

倒滚

当部署失败或需要倒转时,回滚返回堆栈到其最后一个稳定状态. CDK工具包库允许您在程序上滚动失败的部署 .

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.rollback(cx, {
  orphanFailedResources: false, // set to `true` to automatically orphan all failed resources
})

监视

使用手表特性来持续监视您的 CDK 应用程序用于本地修改并自动执行部署或热浪. 这将创建一个文件监视器, 一旦您的代码退出, 文件监视器就会终止 .

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.watch(cx, {
  include: [], // optionally provide a list of file path patterns to watch
  exclude: [], // or exclude files by file path patterns
})

漂移

漂流探测对维持基础设施的可靠性至关重要. 它识别您部署的资源在您的 CDK 代码之外被修改的时间 . 这使得您可以快速处理未经授权的更改 . 这些变化可能导致安全漏洞,合规问题,或者你云层环境中出人意料的行为.

使用漂移操作检测您的 CDK 应用程序中的漂移 :

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

const stackDrifts = await cdk.drift(cx, {
  // optionally provide a stack selector to control which stacks are checked for drift
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"],
  }
});

销毁

使用销毁特性从 AWS 中删除 CDK 堆栈及其相关资源 :

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

await cdk.destroy(cx, {
  // optionally provide a stack selector to control which stacks are destroyed
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: ["my-stack"],
  }
})

配置您的 CDK 工具包实例

信件交互( M)

CDK工具包提供了结构化流程: 信件 财务报告和审定财务报表 请求 回到客户端 与工具包整合.

• 信件 - 向客户通报行动的进展和状况。 不需要回应.
• 请求 - 允许客户端回复的特别信息。 如果没有答复,工具包将使用默认答复.

CDK工具包图书馆通过一个 IoHost。 。 。 . 考虑一下 IoHost 作为确定CDK工具包的通信工作方式的蓝图. 对于每条信息或请求,工具包称为: notify 或者说 requestResponse 方法 IoHost。 。 。 .

自定义IoHost

您可以配置自定义 IoHost 控制信息流动,并将其纳入工作流程和自动化. 以下为简单记录所有消息对象的 stdout 实例执行 :

const toolkit = new toolkitLib.Toolkit({
  ioHost: {
    notify: async function (msg) {
      console.log(msg);
    },
    requestResponse: async function (msg) {
      console.log(msg);
      return msg.defaultResponse;
    }
  }
})

CDK工具包等待每个呼叫完成,允许客户端在处理消息或请求时进行HTTP请求等同步操作. 当你执行一个 IoHost 界面,您可以处理这些通信(例如记录到 Cloud Watch 或提示用户输入),也可以不采取行动立即返回. 如果您的执行无法对请求做出回应, CDK 工具包会以默认值进行.

默认 NonInteractiveIoHost

默认情况下, CDK 工具包库将使用 NonInteractiveIoHost 执行模仿 AWS CDK 工具包 CLI 的行为. 这个 NonInteractiveIoHost 可供您使用,作为可延长的基础.

配置您的 AWS 配置文件

工具包内部使用AWS SDK客户端,向AWS发出必要的API呼叫. 认证配置从环境中自动加载, 但您可以明确指定要使用的基础证书 :

import { Toolkit, BaseCredentials } from '@aws-cdk/toolkit-lib';

const cdk = new Toolkit({
  sdkConfig: {
    baseCredentials: BaseCredentials.awsCliCompatible({ profile: "my-profile" })
  },
});

配置 SDK 调用代理

工具包内部使用AWS SDK客户端,向AWS发出必要的API呼叫. 您可以指定一个节点.js代理来配置 SDK 调用 . 这使得您可以配置第三方软件包 proxy-agent 到代理所有 SDK 调用 :

import { ProxyAgent } from 'proxy-agent';
import { Toolkit } from '@aws-cdk/toolkit-lib';

const cdk = new Toolkit({
  sdkConfig: {
    httpOptions: {
      agent: new ProxyAgent(),
    },
  },
});

配置工具箱动作

CDK工具包库提供的每一个动作都有自己的选项. 然而,在多种行动之间有一些论点和选择.

云组源

这个 云组源 cDK工具箱的一个基本组成部分,它界定了创建一个 云团 从你的应用程序. 例如,CDK应用程序在准备就绪之前可能需要用额外的上下文值进行多次合成. 一旦创建,你就可以使用你的 云组源 用 CDK 工具箱执行动作.

每个 云组源 必须执行 ICloudAssemblySource 接口。 这使得您可以定义自己的自定义源 .

interface ICloudAssemblySource {
  produce(): Promise<cxapi.CloudAssembly>;
}

为方便起见,CDK工具包库提供了一系列标准来源,可以使用 fromXyz() 工具箱实例上的帮助方法 .

大多数已存在的 CCDK app 被写成 JavaScript app 或使用 jsii 语言. 使用 CDK 工具包库,您可以通过提供 CDK 应用程序 app 字符串在 a 中找到 cdk.json 文件 :

declare const cdk: Toolkit;

// TypeScript
await cdk.fromCdkApp("tsx app.ts");

// Python
await cdk.fromCdkApp("python app.py");

这个 AssemblyBuilder 函数提供了Lookups等基本工具包功能,但除此之外,允许您执行任何自定义源. 例如,您在飞行上构建了内置的 CDK 应用程序 。 通常传递给运行中的 CDK 框架的合成操作参数 在通过环境变量的子进程中,通过参数对象传递,您需要将它们明确传递到框架中:

declare const cdk: Toolkit;

const cx = await cdk.fromAssemblyBuilder(async (props) => {
  const app = new core.App({
    outdir: props.outdir,
    context: props.context,
  });

  // Define your stacks here
  new MyStack(app, 'MyStack', {
    env: {
      account: props.CDK_DEFAULT_ACCOUNT,
      region: props.CDK_DEFAULT_REGION,
    },
  });

  return app.synth();
});

注意: AssemblyBuilder 无法安全执行 同时,因为它改变了全球共享的 process.env设置 clobberEnv: false 来避免这种情况,但您的构建者功能需要做一个 多一点工作。 见文件 clobberEnv 举个例子.

现有 云团 目录可用作此类源 :

declare const cdk: Toolkit;

const cx = await cdk.fromAssemblyDirectory("cdk.out");

堆栈选择

CDK工具包的大多数行动都采用 StackSelector 要配置堆栈,该操作应当使用. A 类 StackSelector 和一些可选的额外值.

要选择所有堆栈,请使用 ALL_STACKS 战略:

const allStacks = { strategy: StackSelectionStrategy.ALL_STACKS };

要从主组件中选择顶级堆栈,请使用 MAIN_ASSEMBLY 战略:

const mainStacks = { strategy: StackSelectionStrategy.MAIN_ASSEMBLY };

这个 ONLY_SINGLE 策略允许您确保给定的集合包含完全一个堆栈,并选择它:

const mainStacks = { strategy: StackSelectionStrategy.ONLY_SINGLE };

要通过 ID 选择堆栈,请使用 PATTERN_MUST_MATCH 增加一个 patterns 属性. 如果没有匹配的堆栈,此策略会出错 .

const matchStacks = {
  strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
  patterns: ["MyStack"],
};

您可以选择声明, 通过使用 : PATTERN_MUST_MATCH_SINGLE, (中文(简体) ), 或通过使用完全无法匹配 PATTERN_MATCH。 。 。 .

处理错误

CDK工具包使用结构化错误帮助您在CDK工具包操作中识别和处理问题. 这些错误提供了详细的信息,说明出错的原因.

每个出错都包括以下来源之一,代表出错来源: 1

• 工具包 - 出自 CDK 工具包出错.
• 用户 - 出自用户的错误,例如配置或用户输入错误.

每个出错还包含一个特定的出错类型,如认证或验证,以及一个描述性消息. 您可以在应用程序中捕捉和处理这些错误,以给出适当的响应或倒置行为. 如果 CDK 工具包抛出其他例外, 它们是错误, 您应该通过提出问题来报告

如何处理错误

在CDK工具包库中,所有出错都会被抛出作为常规例外.

使用由 CDK 工具包提供的帮助方法来检测出错误类型. 即使输入了错误,也不要依赖检查的例子,因为它们在使用同一个包的多份副本时可以出乎意料地表现.

下面是一个基本的例子:

declare const cdk: Toolkit;
declare const cx: ICloudAssemblySource;

try {
  // Attempt a CDK Toolkit operation
  const deployment = await cdk.deploy(cx, {
    stacks: ['MyStack']
  });

} catch (error) {
  // Handle user error
  if (ToolkitError.isToolkitError(error) && error.source === 'user') {
    console.error('Hey, something is wrong with your app!', error.message);
  } else {
    throw error;
  }
}