# @cdklabs/cdk-ssm-documents 中文文档

规范地址：https://npmcn.com/package/%40cdklabs/cdk-ssm-documents/

版本：0\.0\.82
npm 元数据更新时间：2026-10-26T20:45:01.221Z
中文译文更新时间：2026-11-09T06:21:44.829Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cdklabs/cdk-ssm-documents
原文对照：https://npmcn.com/package/%40cdklabs/cdk-ssm-documents/?lang=original
项目主页：https://github.com/cdklabs/cdk-ssm-documents#readme
源码仓库：https://github.com/cdklabs/cdk-ssm-documents

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：57.6 MB，10180 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18\.12\.0
- 运行依赖：14 个
- peer 依赖：constructs ^10\.5\.1，aws-cdk-lib ^2\.189\.1
- 首次发布：2022-07-05T08:16:14.623Z
- 最新版本发布：2026-10-26T20:45:00.210Z
- 近 30 天下载量：12122（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 32 个）

## 中文简介

该库为SSM文档的执行提供了基于代码的效用. SSM文档对象可用于打印YAML/JSON文档并模仿本地文档处理.

## 安装

```sh
npm install @cdklabs/cdk-ssm-documents
```

也可以使用：`pnpm add @cdklabs/cdk-ssm-documents`、`yarn add @cdklabs/cdk-ssm-documents`、`bun add @cdklabs/cdk-ssm-documents`

## README

# SSM 文档 CDK

该库为SSM文档的执行提供了基于代码的效用. SSM文档对象可用于打印YAML/JSON文档并模仿本地文档处理.

本图书馆对SSM文件进行高层次摘要,每一步骤及文件本身均为对象。 构建这些对象所需的属性与适用于这些对象的设置相关,使其制作简单. 此库可用于在本地测试您的文档, 然后再将其应用到 SSM 上 .

由于该图书馆用JSII写出,因此可以被导出到支持JSII的其他语言(Java,Python).

这就是你想用的东西:

1.  在AWS上不部署资源或执行实际的SSM的能力.
2.  通过重新使用现有项目使文件之间的步骤得以重复使用
3.  创建可重复使用的步组( “ Patterns ” ) 的逻辑更高层次分组
4.  用于编写文档的简单接口
5.  从文件( 或字符串) 导入已有的文档, 并在当地模仿它们进行测试 .

## 使用量

### 文档创建

键入符使用 (Execute AWS API step)... 以下创建 AWS CDK 堆栈中的自动化文件 .

```ts
import { AutomationDocument } from './automation-document';

export class HelloWorld extends Stack {
  constructor(app: Construct, id: string) {
    super(app, id);

    // Create AutomationDocument
    const myDoc = new AutomationDocument(this, "MyDoc", {
      documentFormat: DocumentFormat.JSON,
      documentName: "MyDoc",
      docInputs: [Input.ofTypeString('MyInput', { defaultValue: 'a' })],
    });

    // Define your steps...
    myDoc.addStep(new PauseStep(this, "MyPauseStep", {
      name: "MyPauseStep",
      explicitNextStep: StepRef.fromName("step1") // Optional (will default to next added step)
    }));

    myDoc.addStep(new ExecuteScriptStep(this, "MyExecuteStep", {
      name: "step1",
      language: ScriptLanguage.python(PythonVersion.VERSION_3_11, 'my_func'),
      code: ScriptCode.fromFile(resolve("test/test_file.py")),
      // OR ScriptCode.inline("def my_func(args, context):\n  return {'MyReturn': args['MyInput'] + '-suffix'}\n"),
      outputs: [{
        outputType: DataTypeEnum.STRING,
        name: "MyFuncOut",
        selector: "$.Payload.MyReturn"
      }],
      onFailure: OnFailure.abort(),
      inputPayload: { MyInput: StringVariable.of('MyInput') },
    }));
  }
}
```

### JSON/YAML 文档导出为 YAML/ JSON

您可以使用 CDK 来部署上述文档. 要将上述文档对象打印为JSON(或YAML),请做如下操作:

```ts
const myDocJson = myDoc.print(); // Print YAML by setting the documentFormat to YAML
```

### 文件模拟

要在模拟模式下运行文档对象,请使用以下操作. 模拟模式不会击中SSM API,而是模仿了在SSM执行中会发生的处决. 运行发生在本地并允许您对外部服务(例如AWS API)的调用进行嘲弄,或者使用您的本地证书引用这些服务.

```ts
import { Simulation } from './simulation';

const myDocJson = Simulation.ofAutomation(myDoc, {}).simulate({ MyInput: "FooBar" });
```

### 命令文档

下面是使用库创建命令文档的例子. 对于所有命令插件,尚不支持命令文档的模拟. 您可以使用 Docker 图像/ 容器作为游乐场, 用于测试 Command 文档执行 .

在这个例子中有一个完整的CDK堆栈. 注意到 `CommandDocument` 以字段保存,以便从测试代码中测试.

```typescript
export class HelloCdkStack extends Stack {
  readonly myCommandDoc: CommandDocument;
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.myCommandDoc = new CommandDocument(this, "MyCommandDoc", {
      docInputs: [Input.ofTypeString('FirstCommand', { defaultValue: 'a' })],
    })
    const runScriptStep = new RunShellScriptStep(this, "MyShellScript", {
      runCommand: [
        StringVariable.of("FirstCommand"),
        HardCodedString.of("mkdir asdf"),
      ],
    });
    this.myCommandDoc.addStep(runScriptStep);
  }
}
```

下面是一个例子,你将如何运行 一个模拟上面 `CommandDocument`。 。 。 .

目前, `bash` 必须在容器中提供,否则对吊工的处决不会成功.

```typescript
test('Test command doc', () => {
  const app = new cdk.App();
  const stack = new HelloCdk.HelloCdkStack(app, 'MyTestStack');
  // 1. $ docker pull amazonlinux
  // 2. $ docker run -di amazonlinux
  const simulation = Simulation.ofCommand(stack.myCommandDoc, {
    simulationPlatform: Platform.LINUX,
    environment: DockerEnvironment.fromContainer('MY_CONTAINER_ID')
  });
  simulation.simulate({FirstCommand: 'mkdir foobar'})
  // 3. The document should run the first command (create 'foobar') and create file 'asdf'
  // 4. $ docker exec -it <container name> bash
  // 5. Ensure that 'asdf' and 'foobar' were written to /tmp
});
```

## 模式( 高级构造)

在典型的CDK风格中,可以将经常被用过的步组组组组装入更高级的构造.

考虑是否通常创建自动文档, 开始记录时间, 结束记录全部时间 。 您可以创建高级自动化文档,并在实施自动化时扩展该文档.

见 `TimedDocument` (c) 要求执行《公约》.

或者考虑多个步骤的情况,这些步骤总是一起运行,例如重启和实例,并等待其活动.

以下示例来自 `RebootInstanceAndWait` 类 :

```ts
export class RebootInstanceAndWait extends CompositeAutomationStep {

  readonly reboot: AwsApiStep;
  readonly describe: WaitForResourceStep;

  constructor(scope: Construct, id: string, instanceId: IStringVariable) {
    super(scope, id);
    this.reboot = new AwsApiStep(this, 'RebootInstances', {
      service: AwsService.EC2,
      pascalCaseApi: 'RebootInstances',
      apiParams: { InstanceIds: [instanceId] },
      outputs: [],
    });
    this.describe = new WaitForResourceStep(this, 'DescribeInstances', {
      service: AwsService.EC2,
      pascalCaseApi: 'DescribeInstances',
      apiParams: { InstanceIds: [instanceId] },
      selector: '$.Reservations[0].Instances[0].State.Name',
      desiredValues: ['running'],
    });
  }

  addToDocument(doc: AutomationDocumentBuilder): void {
    doc.addStep(this.reboot);
    doc.addStep(this.describe);
  }
}

```

现在,你可以使用 `RebootInstanceAndWait` 作为文件中的一个步骤,将列入儿童步骤.

## 现有文件

您是否有一个可用模拟转换为代码和/或本地测试的现有文档 ?

### 导入已存在的文档

以下是您如何导入一个已有文档, 然后在本地模拟它, 使用被模拟的 AWS 资源的例子 :

```ts
// Initialize Mocks
const sleeper = new MockSleep();
const awsInvoker = new MockAwsInvoker();
awsInvoker.whenThen(
    // when invoked with...
    {awsApi: 'listBuckets', awsParams: {}, service: AwsService.S3},
    // then response with...
    {Owner: {ID: "BUCKET_ID"}})

// ======> Create document from file <=======
const stack: Stack = new Stack();
const myAutomationDoc = StringDocument.fromFile(stack, "MyAutomationDoc", 'test/myAutomation.json', {
                                                                        // ======================
});

// Execute simulation
const simOutput = Simulation.ofAutomation(myAutomationDoc, {
  sleepHook: sleeper,
  awsInvoker: awsInvoker
}).simulate({});

// Assert simulation result
assert.deepEqual(awsInvoker.previousInvocations, [
    { awsApi: 'listBuckets', awsParams: {}, service: AwsService.S3 }]);
assert.deepEqual(sleeper.sleepMilliInvocations, [3000]);
assert.deepEqual(simOutput.outputs['simulationSteps'], ['MySleep', 'GetBucketId']);
```

### 导入已存在的步骤

也可以抓取字符串步骤(或步骤)并导入为 CDK 步骤构造. 这可用于将已有的文档转换为CDK,每个步骤都单独定义. 这将允许您修改步骤,并在其他文档中重复使用.

以下是一个简单的睡眠步骤副本的例子

```ts
StringStep.fromYaml(this, `
    name: sleep
    action: aws:sleep
    inputs:
      Duration: PT0M
`, {});
```

以上将返回 CDK 构造 SleepStep .

## 事件管理器

这个库为事件响应提供L2构造如下:

```typescript
new IncidentResponse(this, "MyIncidentResponsePlan", {
      incidentTemplate: IncidentTemplate.critical('EC2 Instance Utilization Impacted', {
        summary: 'EC2 Instance Impacted'
      }),
      actions: [
        IncidentResponseAction.ssmAutomation(myAutomationDoc, ec2CwAlarmRole, {
          parameters: {
            IncidentRecordArn: StringVariable.of('INCIDENT_RECORD_ARN'),
            InvolvedResources: StringVariable.of('INVOLVED_RESOURCES'),
            AutomationAssumeRole: HardCodedString.of(ec2CwAlarmRole.roleArn),
          }
        })
      ]
});
```

注意到如何 `myAutomationDoc` 指的是使用此库创建的自动化文件.

## 什么是计划?

此库目前包含自动化文档和命令文档步骤 . 完全支持自动化文件的模拟。 命令文件的模拟有限.

继续听!

## 相关项目

-   [https://github.com/udondan/cdk-ssm-document 页面存档备份,存于互联网档案馆](https://github.com/udondan/cdk-ssm-document)

## 警卫

见 [捐款](https://npmcn.com/package/%40cdklabs/cdk-ssm-documents/CONTRIBUTING.md#security-issue-notifications) 更多信息.

## 许可证

这个项目根据Apache-2.0许可证获得许可证.

## 常见问题

### @cdklabs/cdk-ssm-documents 是什么？

该库为SSM文档的执行提供了基于代码的效用\. SSM文档对象可用于打印YAML/JSON文档并模仿本地文档处理\.

### 如何安装 @cdklabs/cdk-ssm-documents？

在项目目录运行 npm install @cdklabs/cdk-ssm-documents，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.5\.1）、aws-cdk-lib（^2\.189\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cdklabs/cdk-ssm-documents 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cdklabs/cdk-ssm-documents 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cdklabs/cdk-ssm-documents 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 18\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cdklabs/cdk-ssm-documents 可以商用吗？

@cdklabs/cdk-ssm-documents 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cdklabs/cdk-ssm-documents 的下载量有多少？

根据 npm 官方下载统计，@cdklabs/cdk-ssm-documents 在 2026/10/10 – 2026/11/08 这 30 天内被下载 12,122 次，日均约 404 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cdklabs/cdk-ssm-documents 还在维护吗？

最新版本 0\.0\.82 发布于 2026/10/27（13 天前）；至今共发布 69 个版本，其中过去 12 个月发布了 32 个；首次发布于 2022/07/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。