|
| Systems Manager 参数 | 在 AWS Systems Manager Parameter Store 内定义的变量。该参数不能在步骤输入中直接引用。访问该参数可能需要权限。 |
description: Launch new Windows test instance schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String default: '' description: >- (Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook. LatestAmi: type: String default: >- {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}} description: The latest Windows Server 2016 AMI queried from the public parameter. mainSteps: - name: launchInstance action: 'aws:runInstances' maxAttempts: 3 timeoutSeconds: 1200 onFailure: Abort inputs: ImageId: '{{LatestAmi}}' ...
... "parameters": { "amiId": { "type": "String", "default": "ami-7f2e6015", "description": "list of commands to run as part of first step" }, "alternateAmiId": { "type": "String", "description": "The alternate AMI to try if this first fails".
... mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ImageName}}" outputs: - Name: ImageIdList Selector: "$.Images" Type: "StringList" - name: copyMyImages action: aws:copyImage maxAttempts: 3 onFailure: Abort inputs: SourceImageId: {{getImageId.ImageIdList}} SourceRegion: ap-northeast-2 ImageName: Encrypted Copies of LAMP base AMI in ap-northeast-2 Encrypted: true ... Note: You must provide the type required by the Automation action. In this case, aws:copyImage requires a "String" type variable but the preceding step outputs a "StringList" type variable.
|
# 创建您自己的运行手册
自动化运行手册定义了自动化运行时 Systems Manager 在托管实例和其他 AWS 资源上执行的*操作*。Automation 是 AWS Systems Manager 中的一项工具。运行手册包含一个或多个按顺序运行的步骤。每个步骤是根据单个操作生成的。可以将一个步骤的输出作为后面步骤的输入。
运行这些操作及其步骤的过程称为*自动化*。
让您可以在 AWS 环境中自动完成各种不同操作的运行手册支持的操作类型。例如，通过使用 `executeScript` 操作类型，您可以直接在运行手册中嵌入 Python 或 PowerShell 脚本。（在创建自定义运行手册时，您可以按内联方式添加脚本，或者从 S3 存储桶或本地计算机中附加脚本。） 您可以使用 `createStack` 和 `deleteStack` 操作类型自动管理 AWS CloudFormation 资源。此外，通过使用 `executeAwsApi` 操作类型，步骤可以在任意 AWS 服务中运行*任意* API 操作，包括创建或删除 AWS 资源、启动其他进程、触发通知等。
有关自动化支持的所有 20 种操作类型的列表，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
AWS Systems Manager 自动化提供了几个包含预定义步骤的文档，您可以使用这些步骤执行常见任务，例如重新启动一个或多个 Amazon Elastic Compute Cloud (Amazon EC2) 实例或创建 Amazon Machine Image (AMI)。您还可以创建自己的运行手册并与其他 AWS 账户 共享，或者向所有自动化用户公开。
运行手册是使用 YAML 或 JSON 编写的。但是，通过使用 Systems Manager 自动化中的**文档生成器**，您可以创建运行手册，而无需使用本机 JSON 或 YAML 创作。
**重要**
如果您运行使用 AWS Identity and Access Management (IAM) 服务角色调用其他服务的自动化工作流程，请注意必须使用权限将该服务角色配置为调用这些服务。该要求适用于所有 AWS 自动化运行手册（`AWS-*` 运行手册），例如 `AWS-ConfigureS3BucketLogging`、`AWS-CreateDynamoDBBackup` 和 `AWS-RestartEC2Instance` 运行手册等。对于您创建的任何自定义自动化运行手册，如果这些文档使用调用其他服务的操作来调用其他 AWS 服务，则此要求同样适用。例如，如果使用 `aws:executeAwsApi`、`aws:createStack` 或 `aws:copyImage` 操作，则您必须配置具有权限的服务角色来调用这些服务。您可以将 IAM 内联策略添加到该角色，从而向其他 AWS 服务授予权限。有关更多信息，请参阅 [（可选）添加自动化内联策略或客户管理型策略来调用其他 AWS 服务](automation-setup-iam.md#add-inline-policy)。
有关可在运行手册中指定的操作的信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
有关使用 AWS Toolkit for Visual Studio Code 创建运行手册的信息，请参阅 *《AWS Toolkit for Visual Studio Code 用户指南》* 中的 [使用 Systems Manager 自动化文档](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/systems-manager-automation-docs.html)。
有关使用视觉设计器创建自定义运行手册的信息，请参阅 [自动化运行手册的视觉对象设计体验](automation-visual-designer.md)。
**Contents**
+ [自动化运行手册的视觉对象设计体验](automation-visual-designer.md)
+ [视觉对象设计体验界面概述](visual-designer-interface-overview.md)
+ [操作浏览器](visual-designer-interface-overview.md#visual-designer-actions)
+ [Canvas](visual-designer-interface-overview.md#visual-designer-canvas)
+ [表单](visual-designer-interface-overview.md#visual-designer-form)
+ [键盘快捷键](visual-designer-interface-overview.md#visual-designer-keyboard-shortcuts)
+ [使用视觉对象设计体验](visual-designer-use.md)
+ [创建运行手册工作流程](visual-designer-use.md#visual-designer-create-runbook-workflow)
+ [设计运行手册](visual-designer-use.md#visual-designer-build)
+ [更新运行手册](visual-designer-use.md#visual-designer-update-runbook)
+ [导出运行手册](visual-designer-use.md#visual-designer-export-runbook)
+ [配置操作的输入和输出](visual-designer-action-inputs-outputs.md)
+ [为操作提供输入数据](visual-designer-action-inputs-outputs.md#providing-input)
+ [定义操作的输出数据](visual-designer-action-inputs-outputs.md#defining-output)
+ [视觉对象设计体验中的错误处理](visual-designer-error-handling.md)
+ [出现错误时重试操作](visual-designer-error-handling.md#retry-actions)
+ [超时](visual-designer-error-handling.md#timeout-seconds)
+ [失败的操作](visual-designer-error-handling.md#failure-actions)
+ [取消的操作](visual-designer-error-handling.md#cancel-actions)
+ [关键操作](visual-designer-error-handling.md#critical-actions)
+ [结束操作](visual-designer-error-handling.md#end-actions)
+ [教程：使用视觉对象设计体验创建运行手册](visual-designer-tutorial.md)
+ [步骤 1：导航到视觉对象设计体验](visual-designer-tutorial.md#navigate-console)
+ [步骤 2：创建工作流程](visual-designer-tutorial.md#create-workflow)
+ [步骤 3：查看自动生成的代码](visual-designer-tutorial.md#view-generated-code)
+ [步骤 4：运行新的运行手册](visual-designer-tutorial.md#use-tutorial-runbook)
+ [第 5 步：清理](visual-designer-tutorial.md#cleanup-tutorial-runbook)
+ [创作自动化运行手册](automation-authoring-runbooks.md)
+ [识别您的使用案例](automation-authoring-runbooks.md#automation-authoring-runbooks-use-case)
+ [设置开发环境](automation-authoring-runbooks.md#automation-authoring-runbooks-environment)
+ [开发运行手册内容](automation-authoring-runbooks.md#automation-authoring-runbooks-developing-content)
+ [示例 1：创建父子运行手册](automation-authoring-runbooks-parent-child-example.md)
+ [创建子运行手册](automation-authoring-runbooks-parent-child-example.md#automation-authoring-runbooks-child-runbook)
+ [创建父运行手册](automation-authoring-runbooks-parent-child-example.md#automation-authoring-runbooks-parent-runbook)
+ [示例 2：脚本化运行手册](automation-authoring-runbooks-scripted-example.md)
+ [其他运行手册示例](automation-document-examples.md)
+ [部署 VPC 架构和 Microsoft Active Directory 域控制器](automation-document-architecture-deployment-example.md)
+ [从最新快照还原根卷](automation-document-instance-recovery-example.md)
+ [创建 AMI 和跨区域副本](automation-document-backup-maintenance-example.md)
+ [创建填充 AWS 资源的输入参数](populating-input-parameters.md)
+ [正在使用文档生成器创建运行手册](automation-document-builder.md)
+ [使用文档生成器创建运行手册](automation-document-builder.md#create-runbook)
+ [创建运行脚本的运行手册](automation-document-builder.md#create-runbook-scripts)
+ [在运行手册中使用脚本](automation-document-script-considerations.md)
+ [使用运行手册的权限](automation-document-script-considerations.md#script-permissions)
+ [将脚本添加到运行手册](automation-document-script-considerations.md#adding-scripts)
+ [运行手册的脚本限制](automation-document-script-considerations.md#script-constraints)
+ [在运行手册中使用条件语句](automation-branch-condition.md)
+ [使用 `aws:branch` 操作](automation-branch-condition.md#branch-action-explained)
+ [在运行手册中创建 `aws:branch` 步骤](automation-branch-condition.md#create-branch-action)
+ [关于创建输出变量](automation-branch-condition.md#branch-action-output)
+ [示例 `aws:branch` 运行手册](automation-branch-condition.md#branch-runbook-examples)
+ [使用运算符创建复杂的分支自动化](automation-branch-condition.md#branch-operators)
+ [如何使用条件选项的示例](automation-branch-condition.md#conditional-examples)
+ [使用操作输出作为输入](automation-action-outputs-inputs.md)
+ [在运行手册中使用 JSONPath](automation-action-outputs-inputs.md#automation-action-json-path)
+ [为 Automation 创建 Webhook 集成](creating-webhook-integrations.md)
+ [创建集成（控制台）](creating-webhook-integrations.md#creating-integrations-console)
+ [创建集成（命令行）](creating-webhook-integrations.md#creating-integrations-commandline)
+ [为集成创建 Webhooks](creating-webhook-integrations.md#creating-webhooks)
+ [处理运行手册中的超时](automation-handling-timeouts.md)
# 自动化运行手册的视觉对象设计体验
AWS Systems Manager Automation 提供低代码的视觉对象设计体验，可帮助您创建自动化运行手册。视觉对象设计体验提供拖放界面，可以选择添加自己的代码，这样您就可以更轻松地创建和编辑运行手册。借助视觉对象设计体验，您可以执行以下操作：
+ 控制条件语句。
+ 控制如何筛选或转换每个操作的输入和输出。
+ 配置错误处理。
+ 制作新运行手册的原型。
+ 使用原型运行手册作为采用 AWS Toolkit for Visual Studio Code 进行本地开发的起点。
创建或编辑运行手册时，您可以从 [Automation 控制台](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/)访问视觉对象设计体验。创建运行手册时，视觉对象设计体验会验证您的工作并自动生成代码。您可以查看生成的代码，也可以将其导出以供本地开发。完成后，您可以保存并运行运行手册以及在 Systems Manager Automation 控制台中检查结果。
**Topics**
+ [界面概述](visual-designer-interface-overview.md)
+ [使用视觉对象设计体验](visual-designer-use.md)
+ [配置输入和输出](visual-designer-action-inputs-outputs.md)
+ [视觉对象设计体验中的错误处理](visual-designer-error-handling.md)
+ [教程：使用视觉对象设计体验创建运行手册](visual-designer-tutorial.md)
# 视觉对象设计体验界面概述
Systems Manager Automation 的视觉对象设计体验是一种低代码的视觉对象工作流程设计器，可帮助您创建自动化运行手册。
通过界面组件的概述了解视觉对象设计体验：
![\[视觉对象设计体验组件\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_overview.png)
+ **操作**浏览器包含**操作**、**AWS API** 和**运行手册**选项卡。
+ 在*画布*中，您可以将操作拖放到工作流程图中、更改操作顺序以及选择要配置或查看的操作。
+ 在**表单**面板中，您可以查看和编辑在画布上选择的任何操作的属性。选择**内容**开关以查看运行手册的 YAML 或 JSON，并突出显示当前选定的操作。
当您需要帮助时，**信息**链接会打开一个包含上下文信息的面板。这些面板还包括指向 Systems Manager Automation 文档中相关主题的链接。
## 操作浏览器
在**操作**浏览器中，您可以选择要拖放到工作流程图中的操作。您可以使用**操作**浏览器顶部的搜索字段搜索所有操作。**操作**浏览器包含以下选项卡：
+ **操作**选项卡提供了自动化操作列表，您可以将这些操作拖放到画布中运行手册的工作流程图中。
+ **AWS API** 选项卡提供了 AWS API 列表，您可以将这些 API 拖放到画布中运行手册的工作流程图中。
+ **运行手册**选项卡提供了几个随时可用、可重复使用的运行手册作为构建块，您可以将其用于各种用例。例如，您可以使用运行手册在工作流程中对 Amazon EC2 实例执行常见的修复任务，而无需重新创建相同的操作。
![\[视觉对象设计体验操作浏览器\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_actions_multi_view.png)
## Canvas
选择要添加到自动化中的操作后，将其拖动到画布并放入工作流程图中。您还可以拖放操作，将其移动到运行手册工作流程中的不同位置。如果您的工作流程很复杂，您可能无法在画布面板上查看其所有内容。使用画布顶部的控件来放大或缩小。要查看工作流程的不同部分，您可以在画布中拖动工作流程图。
在**操作**浏览器中拖动一项操作，将其放入运行手册的工作流程图中。有一条线将显示其在您工作流程中的放置位置。要更改操作的顺序，您可以将其拖动到工作流程中的其他位置。新操作已添加到您的工作流程中，其代码已自动生成。
![\[视觉对象设计体验画布\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_canvas.png)
## 表单
在运行手册工作流程中添加操作后，您可以对其进行配置以满足您的用例。选择希望配置的操作，您将在**表单**面板中看到其参数和选项。您还可以通过选择**内容**开关来查看 YAML 或 JSON 代码。与您所选操作关联的代码会突出显示。
![\[视觉对象设计体验表单面板\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_form.png)
![\[视觉对象设计体验内容面板\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_content.png)
## 键盘快捷键
视觉对象设计体验支持下表中所示的键盘快捷键。
| 键盘快捷键 | 函数 |
| --- | --- |
| Ctrl\$1Z | 撤销上次的操作。 |
| Ctrl\$1Shift\$1Z | 重做上次的操作。 |
| Alt\$1C | 将工作流程置于画布中心。 |
| 退格键 | 删除所有选定状态。 |
| 删除 | 删除所有选定状态。 |
| Ctrl\$1D | 复制所选状态。 |
# 使用视觉对象设计体验
学习使用视觉对象设计体验创建、编辑和运行运行手册工作流程。工作流程准备就绪后，您可以将其保存或导出。您还可以使用视觉对象设计体验进行快速原型制作。
## 创建运行手册工作流程
1. 登录 [Systems Manager Automation 控制台](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/)。
1. 选择**创建运行手册**。
1. 在**名称**方框中，输入运行手册的名称，例如 `MyNewRunbook`。
1. 在**设计**和**代码**切换开关旁边，选择铅笔图标并输入运行手册的名称。
现在，您可以为新的运行手册设计工作流程。
## 设计运行手册
要使用视觉对象设计体验设计运行手册工作流程，您可以将自动化操作从**操作**浏览器拖动到画布中，将其放置在运行手册工作流程中所需的位置。您也可以通过将操作拖动到不同的位置来重新排序工作流程中的操作。当您将操作拖动到画布上时，工作流程中可以放置该操作的任何位置都会显示一条线。将操作放入画布后，其代码将自动生成并添加到运行手册的内容中。
如果您知道希望添加的操作的名称，请使用**操作**浏览器顶部的搜索框来查找该操作。
将操作放入画布后，使用右侧的**表单**面板对其进行配置。此面板包含您在画布上放置的每个自动化操作或 API 操作的**常规**、**输入**、**输出**和**配置**选项卡。例如，**常规**选项卡由以下部分组成：
+ **步骤名称**用于标识该步骤。为步骤名称指定唯一值。
+ **描述**可帮助您描述在运行手册的工作流程中操作正在执行的内容。
**输入**选项卡包含因操作而异的字段。例如，`aws:executeScript` 自动化操作由以下部分组成：
+ **运行时系统**是运行所提供脚本的语言。
+ **处理程序**是函数的名称。您必须确保在处理程序中定义的函数具有两个参数：`events` 和 `context`。PowerShell 运行时系统不支持此参数。
+ **脚本**是您想要在工作流程期间运行的嵌入式脚本。
+ （可选）**附件**适用于可由操作调用的独立脚本或 .zip 文件。对于 JSON 运行手册，此参数为必需项。
**输出**选项卡可帮助您指定希望从操作中输出的值。您可以在工作流程的后续操作中引用输出值，也可以根据操作生成输出以用于日志记录。并非所有操作都将有**输出**选项卡，因为并非所有操作都支持输出。例如，`aws:pause` 操作就不支持输出。对于支持输出的操作，**输出**选项卡由以下部分组成：
+ **名称**是用于输出值的名称。您可以在工作流程的后续操作中引用输出。
+ **选择器**是以 `"$."` 开头的 JSONPath 表达式字符串，用于选择 JSON 元素中的一个或多个组件。
+ **类型**是输出值的数据类型。例如，`String` 或 `Integer` 数据类型。
**配置**选项卡包含所有自动化操作均可使用的属性和选项。该操作由以下部分组成：
+ **最大尝试次数**属性是操作失败时重试的次数。
+ **超时秒数**属性指定操作的超时值。
+ **至关重要**属性确定操作失败是否会停止整个自动化。
+ **下一步**属性确定自动化在运行手册中接下来要执行的操作。
+ **失败时**属性确定操作失败时自动化在运行手册中接下来要执行的操作。
+ **取消时**属性确定用户取消自动操作时自动化在运行手册中接下来要执行的操作。
要删除操作，您可以使用画布上方工具栏中的退格键，或者右键单击并选择**删除操作**。
随着工作流程的发展，其可能不适合画布。为帮助使工作流程适合画布，请尝试以下选项之一：
+ 使用侧面板上的控件调整面板大小或关闭面板。
+ 使用画布顶部的工具栏放大或缩小工作流程图。
## 更新运行手册
您可以通过创建新版本的运行手册来更新现有的运行手册工作流程。可以通过使用视觉对象设计体验或直接编辑代码来更新运行手册。要更新现有运行手册，请参照以下过程：
1. 登录 [Systems Manager Automation 控制台](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/)。
1. 选择要更新的运行手册。
1. 选择 **Create new version**。
1. 视觉对象设计体验有两个窗格：代码窗格和视觉对象工作流程窗格。在视觉对象工作流程窗格中选择**设计**，以使用视觉对象设计体验编辑您的工作流程。完成后，选择**创建新版本**以保存更改并退出。
1. （可选）使用代码窗格以 YAML 或 JSON 格式编辑运行手册内容。
## 导出运行手册
要导出运行手册的工作流程 YAML 或 JSON 代码以及工作流程图，请参照以下过程：
1. 在**文档**控制台中选择您的运行手册。
1. 选择 **Create new version**。
1. 在**操作**下拉菜单中，选择是否要导出图表或运行手册，以及您喜欢的格式。
# 配置操作的输入和输出
每个自动化操作都会根据其收到的输入进行响应。在大多数情况下，您随后会将输出传递给后续操作。在视觉对象设计体验中，您可以在**表单**面板的**输入**和**输出**选项卡中配置操作的输入和输出数据。
有关如何定义和使用自动化操作输出的详细信息，请参阅 [使用操作输出作为输入](automation-action-outputs-inputs.md)。
## 为操作提供输入数据
每个自动化操作都有一个或多个输入，您必须为其提供值。您为操作输入提供的值由操作接受的数据类型和格式决定。例如，这些 `aws:sleep` 操作要求 `Duration` 输入采用 ISO 8601 格式的字符串值。
通常，您在运行手册的工作流程中使用操作，这些操作将返回要在后续操作中使用的输出。请务必确保输入值正确，以避免运行手册的工作流程出现错误。输入值也很重要，因为其决定了操作是否返回预期的输出。例如，在使用 `aws:executeAwsApi` 操作时，您需要确保为 API 操作提供了正确的值。
## 定义操作的输出数据
一些自动化操作在执行其定义的操作后会返回输出。返回输出的操作要么具有预定义的输出，要么允许您自己定义输出。例如，`aws:createImage` 操作具有返回 `ImageId` 和 `ImageState` 的预定义输出。相比之下，通过 `aws:executeAwsApi` 操作，您可以定义您想要从指定 API 操作中获得的输出。因此，您可以从单个 API 操作中返回一个或多个值，以便在后续操作中使用。
为自动化操作定义自己的输出需要您指定输出的名称、数据类型和输出值。要继续使用 `aws:executeAwsApi` 操作作为示例，假设您正在从 Amazon EC2 调用 `DescribeInstances` API 操作。在此示例中，您想要返回或输出 Amazon EC2 实例的 `State`，并根据输出对运行手册的工作流程进行分支。您可以选择命名输出 **InstanceState**，然后使用 **String** 数据类型。
定义输出实际值的过程因操作而异。例如，如果您使用的是 `aws:executeScript` 操作，则必须在函数中使用 `return` 语句为输出提供数据。对于 `aws:executeAwsApi`、`aws:waitForAwsResourceProperty` 和 `aws:assertAwsResourceProperty` 等其他操作，则需要 `Selector`。`Selector`（或某些操作所指的 `PropertySelector`），是一个 JSONPath 字符串，用于处理来自 API 操作的 JSON 响应。了解 API 操作的 JSON 响应对象的结构至关重要，这样您才能为输出选择正确的值。使用前面提到 `DescribeInstances` API 操作，请参阅以下 JSON 响应示例：
```
{
"reservationSet": {
"item": {
"reservationId": "r-1234567890abcdef0",
"ownerId": 123456789012,
"groupSet": "",
"instancesSet": {
"item": {
"instanceId": "i-1234567890abcdef0",
"imageId": "ami-bff32ccc",
"instanceState": {
"code": 16,
"name": "running"
},
"privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal",
"dnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com",
"reason": "",
"keyName": "my_keypair",
"amiLaunchIndex": 0,
"productCodes": "",
"instanceType": "t2.micro",
"launchTime": "2018-05-08T16:46:19.000Z",
"placement": {
"availabilityZone": "eu-west-1c",
"groupName": "",
"tenancy": "default"
},
"monitoring": {
"state": "disabled"
},
"subnetId": "subnet-56f5f000",
"vpcId": "vpc-11112222",
"privateIpAddress": "192.168.1.88",
"ipAddress": "54.194.252.215",
"sourceDestCheck": true,
"groupSet": {
"item": {
"groupId": "sg-e4076000",
"groupName": "SecurityGroup1"
}
},
"architecture": "x86_64",
"rootDeviceType": "ebs",
"rootDeviceName": "/dev/xvda",
"blockDeviceMapping": {
"item": {
"deviceName": "/dev/xvda",
"ebs": {
"volumeId": "vol-1234567890abcdef0",
"status": "attached",
"attachTime": "2015-12-22T10:44:09.000Z",
"deleteOnTermination": true
}
}
},
"virtualizationType": "hvm",
"clientToken": "xMcwG14507example",
"tagSet": {
"item": {
"key": "Name",
"value": "Server_1"
}
},
"hypervisor": "xen",
"networkInterfaceSet": {
"item": {
"networkInterfaceId": "eni-551ba000",
"subnetId": "subnet-56f5f000",
"vpcId": "vpc-11112222",
"description": "Primary network interface",
"ownerId": 123456789012,
"status": "in-use",
"macAddress": "02:dd:2c:5e:01:69",
"privateIpAddress": "192.168.1.88",
"privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal",
"sourceDestCheck": true,
"groupSet": {
"item": {
"groupId": "sg-e4076000",
"groupName": "SecurityGroup1"
}
},
"attachment": {
"attachmentId": "eni-attach-39697adc",
"deviceIndex": 0,
"status": "attached",
"attachTime": "2018-05-08T16:46:19.000Z",
"deleteOnTermination": true
},
"association": {
"publicIp": "54.194.252.215",
"publicDnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com",
"ipOwnerId": "amazon"
},
"privateIpAddressesSet": {
"item": {
"privateIpAddress": "192.168.1.88",
"privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal",
"primary": true,
"association": {
"publicIp": "54.194.252.215",
"publicDnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com",
"ipOwnerId": "amazon"
}
}
},
"ipv6AddressesSet": {
"item": {
"ipv6Address": "2001:db8:1234:1a2b::123"
}
}
}
},
"iamInstanceProfile": {
"arn": "arn:aws:iam::123456789012:instance-profile/AdminRole",
"id": "ABCAJEDNCAA64SSD123AB"
},
"ebsOptimized": false,
"cpuOptions": {
"coreCount": 1,
"threadsPerCore": 1
}
}
}
}
}
}
```
在 JSON 响应对象中，实例 `State` 嵌套在 `Instances` 对象中，而该对象嵌套在 `Reservations` 对象中。要返回实例 `State` 的值，请使用以下字符串作为 `Selector`，以便可以在输出中使用该值：**\$1.Reservations[0].Instances[0].State.Name**。
要在运行手册工作流程的后续操作中引用输出值，请使用以下格式：`{{ StepName.NameOfOutput }}`。例如 **\$1\$1 GetInstanceState.InstanceState \$1\$1**。在视觉对象设计体验中，您可以使用输入下拉菜单选择要在后续操作中使用的输出值。在后续操作中使用输出时，输出的数据类型必须与输入的数据类型相匹配。在此示例中，`InstanceState` 输出为 `String`。因此，要在后续操作的输入中使用该值，输入必须接受 `String`。
# 视觉对象设计体验中的错误处理
默认情况下，当操作报告错误时，自动化会完全停止运行手册的工作流程。这是因为所有操作 `onFailure` 属性的默认值为 `Abort`。您可以配置自动化如何处理运行手册工作流程中错误。即使您配置了错误处理，某些错误仍可能导致自动化失败。有关更多信息，请参阅 [Systems Manager 自动化故障排除](automation-troubleshooting.md)。在视觉对象设计体验中，您可以在**配置**面板中配置错误处理。
![\[错误处理选项\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_error_handling.png)
## 出现错误时重试操作
要在出现错误时重试操作，请为**最大尝试次数**属性指定一个值。默认值是 1。如果您指定的值大于 1，则直到所有重试尝试失败后，才会将此操作视为失败。
## 超时
您可以为操作配置超时，以设置操作在失败之前可以运行的最大秒数。要配置超时，请在**超时秒数**属性中输入操作在失败之前应等待的秒数。如果达到超时并且操作的 `Max attempts` 值大于 1，则在重试完成之前该步骤不会被视为已超时。
## 失败的操作
默认情况下，当操作失败时，自动化会完全停止运行手册的工作流程。您可以通过为运行手册中操作的**失败时**属性指定替代值来修改此行为。如果您希望工作流程继续到运行手册中的下一步，请选择**继续**。如果您希望工作流程跳至运行手册中的其他后续步骤，请选择**步骤**，然后输入该步骤的名称。
## 取消的操作
默认情况下，当用户取消操作时，自动化会完全停止运行手册的工作流程。您可以通过为运行手册中操作的**取消时**属性指定替代值来修改此行为。如果您希望工作流程跳至运行手册中的其他后续步骤，请选择**步骤**，然后输入该步骤的名称。
## 关键操作
您可以将某项操作指定为*关键*操作，这意味着其决定了自动化的总体报告状态。如果具有此指定的步骤失败，则无论其他操作是否成功，自动化都会将最终状态报告为 `Failed`。要将某项操作配置为关键，请将**至关重要**属性的默认值保留为 **True**。
## 结束操作
**结束**属性在指定操作结束时停止自动化。此属性的默认值为 `false`。如果您为操作配置此属性，则无论操作成功还是失败，自动化都会停止。此属性最常与 `aws:branch` 操作一起使用，以处理意外或未定义的输入值。以下示例显示了期望实例状态为 `running`、`stopping` 或 `stopped` 的运行手册。如果实例处于不同的状态，则自动化结束。
![\[视觉对象设计体验就是结束示例\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_is_end_example.png)
# 教程：使用视觉对象设计体验创建运行手册
在本教程中，您将学习使用 Systems Manager Automation 提供的视觉对象设计体验的基础知识。在视觉对象设计体验中，您可以创建使用多个操作的运行手册。您可以使用拖放功能在画布上排列操作。您还可以搜索、选择和配置这些操作。然后，您可以查看为运行手册工作流程自动生成的 YAML 代码、退出视觉对象设计体验、运行运行手册并查看执行详情。
本教程还向您展示了如何更新运行手册和查看新版本。在本教程的最后，您将执行清理步骤并删除运行手册。
完成本教程的学习后，您将知道如何使用视觉对象设计体验来创建运行手册。您还将了解如何更新、运行和删除运行手册。
**注意**
在开始学习本教程之前，请确保完成 [设置自动化](automation-setup.md)。
**Topics**
+ [步骤 1：导航到视觉对象设计体验](#navigate-console)
+ [步骤 2：创建工作流程](#create-workflow)
+ [步骤 3：查看自动生成的代码](#view-generated-code)
+ [步骤 4：运行新的运行手册](#use-tutorial-runbook)
+ [第 5 步：清理](#cleanup-tutorial-runbook)
## 步骤 1：导航到视觉对象设计体验
1. 登录 [Systems Manager Automation 控制台](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/)。
1. 选择**创建自动化运行手册**。
## 步骤 2：创建工作流程
在视觉对象设计体验中，工作流程是画布上运行手册的图形表示。您可以使用视觉对象设计体验来定义、配置和检查运行手册的各个操作。
**创建工作流程**
1. 在**设计**和**代码**切换开关旁边，选择铅笔图标并输入运行手册的名称。在本教程中，请输入 **VisualDesignExperienceTutorial**。
![\[视觉对象设计体验为您的运行手册命名\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_tutorial_name.png)
1. 在**表单**面板的**文档属性**部分，展开**输入参数**下拉菜单，然后选择**添加参数**。
1. 在**参数名称**字段中，输入 **InstanceId**。
1. 在**类型**下拉菜单中，选择 **AWS::EC2::Instance**。
1. 选择**必需**开关。
![\[创建运行手册的参数\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_actions_tutorial_parameter.png)
1. 在 **AWS API** 浏览器中，在搜索栏中输入 **DescribeInstances**。
1. 将 **Amazon EC2 – DescribeInstances** 操作拖动到空白画布上。
1. 对于**步骤名称**，请输入一个值。在本教程中，您可以使用名称 **GetInstanceState**。
![\[选择 Amazon EC2 描述实例 API 操作。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_tutorial_api_action.png)
1. 展开**其他输入**下拉菜单，然后在**输入名称**字段中输入 **InstanceIds**。
1. 选择**输入**选项卡。
1. 在**输入值**字段中，选择 **InstanceId** 文档输入。这将引用在过程开始时创建的输入参数的值。鉴于 `DescribeInstances` 操作的 **InstanceIds** 输入接受 `StringList` 值，必须将 **InstanceId** 输入用方括号括起来。**输入值**的 YAML 应与以下内容匹配：**['\$1\$1 InstanceId \$1\$1']**。
1. 在**输出**选项卡中，请选择**添加输出**，然后在**名称**字段中输入 **InstanceState**。
1. 在**选择器**字段中，请输入 **\$1.Reservations[0].Instances[0].State.Name**。
1. 在**类型**下拉菜单中，请选择**字符串**。
1. 从**操作**浏览器中拖动**分支**操作，然后将其放入 **`GetInstanceState`** 步骤下方。
1. 对于**步骤名称**，请输入一个值。在本教程中，请使用名称 `BranchOnInstanceState`。
要定义分支逻辑，请执行以下操作：
1. 在画布上选择 **`Branch`** 状态。然后，在**输入**和**选择**下，选择铅笔图标以编辑**规则 \$11**。
1. 选择**添加条件**。
1. 在**规则 \$11 的条件**对话框中，从**变量**下拉菜单中选择 **GetInstanceState.InstanceState** 步骤输出。
1. 对于**运算符**，请选择**等于**。
1. 对于**值**，请从下拉列表中选择**字符串**。输入 **stopped**。
![\[定义分支操作的条件。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_tutorial_condition.png)
1. 选择**保存条件**。
1. 选择**添加新的选择规则**。
1. 为**规则 \$12** 选择**添加条件**。
1. 在**规则 \$12 的条件**对话框中，从**变量**下拉菜单中选择 **GetInstanceState.InstanceState** 步骤输出。
1. 对于**运算符**，请选择**等于**。
1. 对于**值**，请从下拉列表中选择**字符串**。输入 **stopping**。
1. 选择**保存条件**。
1. 选择**添加新的选择规则**。
1. 对于**规则 \$13**，请选择**添加条件**。
1. 在**规则 \$13 的条件**对话框中，从**变量**下拉菜单中选择 **GetInstanceState.InstanceState** 步骤输出。
1. 对于**运算符**，请选择**等于**。
1. 对于**值**，请从下拉列表中选择**字符串**。输入 **running**。
1. 选择**保存条件**。
1. 在**默认规则**中，选择**转到结尾**作为**默认步骤**。
1. 将**更改实例状态**操作拖动到 **\$1\$1 GetInstanceState.InstanceState \$1\$1 == "stopped"** 条件下的**将操作拖动到此处**空白框中。
1. 对于**步骤名称**，请输入 **StartInstance**。
1. 在**输入**选项卡的**实例 ID** 下，从下拉菜单中选择 **InstanceId** 文档输入值。
1. 对于**期望状态**，请指定 **`running`**。
1. 将**等待 AWS 资源**操作拖动到 **\$1\$1 GetInstanceState.InstanceState \$1\$1 == "stopping"** 条件下的**将操作拖动到此处**空白框中。
1. 对于**步骤名称**，请输入一个值。在本教程中，请使用名称 `WaitForInstanceStop`。
1. 对于**服务**字段，请选择 **Amazon EC2**。
1. 对于 **API** 字段，请选择 **DescribeInstances**。
1. 对于**属性选择器**字段，请输入 **\$1.Reservations[0].Instances[0].State.Name**。
1. 对于**期望值**参数，请输入 **`["stopped"]`**。
1. 在 **WaitForInstanceStop** 操作的**配置**选项卡中，从**下一步**下拉菜单中选择 **StartInstance**。
1. 将**在实例上运行命令**操作拖动到 **\$1\$1 GetInstanceState.InstanceState \$1\$1 == "running"** 条件下的**将操作拖动到此处**空白框中。
1. 对于**步骤名称**，请输入 **SayHello**。
1. 在**输入**选项卡中，输入 **AWS-RunShellScript** 作为**文档名称**参数。
1. 对于 **InstanceId**，请从下拉菜单中选择 **InstanceId** 文档输入值。
1. 展开**其他输入**下拉菜单，在**输入名称**下拉菜单中，选择**参数**。
1. 在**输入值**字段中，请输入 **`{"commands": "echo 'Hello World'"}`**。
1. 在画布中查看已完成的运行手册，然后选择**创建运行手册**以保存教程运行手册。
![\[查看和创建运行手册。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/visual_designer_tutorial_complete.png)
## 步骤 3：查看自动生成的代码
当您将操作从**操作**浏览器拖放到画布上时，视觉对象设计体验会自动实时编写运行手册的 YAML 或 JSON 内容。您可以查看和编辑此代码。要查看自动生成的代码，在**设计**和**代码**切换开关中选择**代码**。
## 步骤 4：运行新的运行手册
创建运行手册后，您可以运行自动化。
**运行新的自动化运行手册**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**自动化**，然后选择**执行自动化**。
1. 在**自动化文档**列表中，请选择运行手册。在**文档类别**窗格中选择一个或多个选项，以便根据 SSM 文档的用途对其进行筛选。要查看您拥有的运行手册，请选择**我拥有的**选项卡。要查看与您的账户共享的运行手册，请选择**与我共享**选项卡。要查看所有运行手册，请选择**所有文档**选项卡。
**注意**
您可以通过选择运行手册名称来查看有关该手册的信息。
1. 在**文档详细信息**部分中，验证**文档版本**已设置为要运行的版本。系统包括以下版本选项：
+ **运行时的默认版本** – 如果定期更新自动化运行手册并分配新的默认版本，请选择此选项。
+ **运行时的最新版本** – 如果定期更新自动化运行手册并且想要运行最新更新的版本，请选择此选项。
+ **1（默认）** – 选择此选项可执行文档的第一个版本，即默认版本。
1. 选择**下一步**。
1. 在**执行自动化运行手册**部分，请选择**简单执行**。
1. 在 **输入参数** 部分中，指定所需的输入。或者，您也可以从 **AutomationAssumeRole** 列表选择一个 IAM 服务角色。
1. （可选）选择一个 Amazon CloudWatch 警报应用于您的自动化，以便进行监控。要将 CloudWatch 警报附加到自动化，启动自动化的 IAM 主体必须具有 `iam:createServiceLinkedRole` 操作的权限。有关 CloudWatch 警报的更多信息，请参阅[使用 Amazon CloudWatch 警报](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。如果您的警报激活，自动化将停止。如果使用 AWS CloudTrail，您将在跟踪中看到 API 调用。
1. 选择**执行**。
## 第 5 步：清理
**删除您的运行手册**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 选择**我拥有的**选项卡。
1. 找到 **VisualDesignExperienceTutorial** 运行手册。
1. 在文档卡页面上选择按钮，然后从**操作**下拉菜单中选择**删除文档**。
# 创作自动化运行手册
Automation 是 AWS Systems Manager 中的一项工具，其中的每个运行手册定义了一个自动化。自动化运行手册定义了在自动化过程中执行的操作。在运行手册内容中，您可以定义 Systems Manager 对托管实例和 AWS 资源执行的输入参数、输出和操作。
自动化包含几个预定义的运行手册，您可以用它们来执行常见任务，例如重启一个或多个 Amazon Elastic Compute Cloud (Amazon EC2) 实例，或创建 Amazon Machine Image (AMI)。但是，您的使用案例可能会超出预定义运行手册的功能。如果是这种情况，您可以创建自己的运行手册并根据需要修改它们。
运行手册由自动化操作、这些操作的参数以及您指定的输入参数组成。运行手册的内容是以 YAML 或 JSON 格式编写的。如果不熟悉 YAML 或 JSON，建议使用视觉设计器，或者在尝试创作自己的运行手册之前了解更多关于任一标记语言的信息。有关视觉设计器的更多信息，请参阅 [自动化运行手册的视觉对象设计体验](automation-visual-designer.md)。
以下部分将帮助您创作第一个运行手册。
## 识别您的使用案例
创作运行手册的第一步是确定您的使用案例。例如，您计划了 `AWS-CreateImage` 运行手册，以便每天在您的所有生产 Amazon EC2 实例上运行。月底时，您决定拥有的映像数量超过恢复点所需的映像。接下来，您希望在创建新 AMI 时，自动删除 Amazon EC2 实例的最早 AMI。为了实现此目的，您可以创建执行以下操作的新运行手册：
1. 运行 `aws:createImage` 操作，并在映像描述中指定实例 ID。
1. 运行 `aws:waitForAwsResourceProperty` 操作来轮询图像的状态，直到此状态为 `available`。
1. 在图像状态变为 `available` 后，`aws:executeScript` 操作会运行一个自定义 Python 脚本，用于收集与 Amazon EC2 实例关联的所有映像的 ID。脚本使用您在创建时指定的映像描述中的实例 ID 进行筛选，完成此操作。然后，脚本根据图像的 `creationDate` 对图像 ID 列表进行排序，并输出最早的 AMI。
1. 最后，`aws:deleteImage` 操作运行，使用上一步输出中的 ID 删除最早的 AMI。
在这种情况下，您已经使用 `AWS-CreateImage` 运行手册，但发现您的使用案例需要更大的灵活性。这是一种常见的情况，因为运行手册和自动化操作之间可能存在重叠。因此，您可能需要调整用于解决您的使用案例的运行手册或操作。
例如，`aws:executeScript` 和 `aws:invokeLambdaFunction` 操作都允许您在自动化过程中运行自定义脚本。要在它们之间进行选择，您可能更喜欢 `aws:invokeLambdaFunction`，因为它还支持其他运行时语言。但是，您可能更喜欢 `aws:executeScript`，因为它允许您直接在 YAML 运行手册中创作脚本内容，并提供脚本内容作为 JSON 运行手册的附件。您也可以考虑 `aws:executeScript`，因为其 AWS Identity and Access Management (IAM) 设置更简单。因为它使用 `AutomationAssumeRole` 提供的权限，`aws:executeScript` 不需要使用额外的 AWS Lambda 函数执行角色。
在任何给定的情况下，一个操作可能会比另一个操作提供更大的灵活性或更多功能。因此，我们建议您查看要使用的运行手册或操作的可用输入参数，以确定哪些参数最适合您的使用案例和首选项。
## 设置开发环境
确定您的使用案例以及要在运行手册中使用的预定义运行手册或自动化操作后，请为运行手册的内容设置开发环境。要开发您的运行手册内容，我们建议使用 AWS Toolkit for Visual Studio Code 而不是 Systems Manager 文档控制台。
Toolkit for VS Code 是 Visual Studio 代码（VS 代码）的开源扩展，提供了比 Systems Manager 文档控制台更多的功能。有用的功能包括针对 YAML 和 JSON 的模式验证、自动化操作类型的代码片段以及对各种 YAML 和 JSON 格式选项的自动完成支持。
有关安装 Toolkit for VS Code 的更多信息，请参阅[安装 AWS Toolkit for Visual Studio Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/setup-toolkit.html)。有关使用适用于 Toolkit for VS Code 开发运行手册的更多信息，请参阅 *AWS Toolkit for Visual Studio Code 用户指南*中的[使用 Systems Manager 运行手册](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/systems-manager-automation-docs.html)
## 开发运行手册内容
确定使用案例并设置环境后，您便做好了开发适用于运行手册内容的准备。您的使用案例和首选项在很大程度上决定了您在运行手册内容中使用的自动化操作或运行手册。与允许您完成类似任务的其他操作相比，某些操作仅支持输入参数的子集。其他操作具有特定的输出，例如 `aws:createImage`，其中一些操作允许您定义自己的输出，例如 `aws:executeAwsApi`。
如果您不确定如何在运行手册中使用特定操作，我们建议您查看 [Systems Manager 自动化操作参考](automation-actions.md) 中的操作对应条目。我们还建议您查看预定义运行手册的内容，以查看有关如何使用这些操作的实例。有关运行手册的实际应用程序的更多实例，请参阅 [其他运行手册示例](automation-document-examples.md)。
为了展示运行手册内容在简单性和灵活性方面的差异，以下教程提供了如何分阶段修补 Amazon EC2 实例组的示例：
+ [示例 1：创建父子运行手册](automation-authoring-runbooks-parent-child-example.md) - 在此示例中，父子关系中使用了两个运行手册。父运行手册启动子运行手册的速率控制自动化。
+ [示例 2：脚本化运行手册](automation-authoring-runbooks-scripted-example.md) - 此示例演示如何通过将内容压缩到单个运行手册中并使用运行手册中的脚本来完成示例 1 的相同任务。
# 示例 1：创建父子运行手册
以下示例演示如何创建两个运行手册，以便分阶段修补已标记的 Amazon Elastic Compute Cloud (Amazon EC2) 实例组。这些运行手册用于父子关系，其中父运行手册用于启动子运行手册的速率控制自动化。有关使用速率控制自动化的更多信息，请参阅 [大规模运行自动化操作](running-automations-scale.md)。有关此示例中使用的自动化操作的更多信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
## 创建子运行手册
此示例运行手册解决以下情形。Emily 是 AnyCompany Consultants, LLC 的系统工程师。她需要为托管主数据库和辅助数据库的 Amazon Elastic Compute Cloud (Amazon EC2) 实例组配置补丁程序。应用程序每天 24 小时访问这些数据库，因此两个数据库实例中必须有一个始终可用。
她确定分阶段修补实例是最佳方法。首先将对数据库实例的主组进行修补，然后修补数据库实例的辅助组。此外，为了避免由于使之前已停止的实例运行而产生额外的成本，Emily 希望在进行修补之前将修补的实例返回到其原始状态。
Emily 通过与实例关联的标签来标识数据库实例的主组和辅助组。她决定创建一个父运行手册，用于启动子运行手册的速率控制自动化。通过这种方法，她可以将与数据库实例的主组和辅助组关联的标签设置为目标，并管理子自动化的并发性。查看了可用于修补的 Systems Manager (SSM) 文档后，她选择了 `AWS-RunPatchBaseline` 文档。通过使用此 SSM 文档，她的同事可以在修补操作完成后查看相关的修补程序合规性信息。
为了开始创建运行手册内容，Emily 查看了可用的自动化操作，并开始为子运行手册创作内容，如下所示：
1. 首先，她为运行手册的架构和描述提供值，并定义子运行手册的输入参数。
通过使用 `AutomationAssumeRole` 参数，Emily 和她的同事可以使用现有的 IAM 角色，以允许自动化代表他们执行运行手册中的操作。Emily 使用 `InstanceId` 参数来确定应修补的实例。（可选）`Operation`、`RebootOption` 和 `SnapshotId` 参数可用于为 `AWS-RunPatchBaseline` 的文档参数提供值。为了防止向这些运行手册参数提供无效值，她根据需要定义了 `allowedValues`。
------
#### [ YAML ]
```
schemaVersion: '0.3'
description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: >-
'(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the
actions on your behalf. If no role is specified, Systems Manager
Automation uses your IAM permissions to operate this runbook.'
default: ''
InstanceId:
type: String
description: >-
'(Required) The instance you want to patch.'
SnapshotId:
type: String
description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.'
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.'
allowedValues:
- Install
- Scan
default: Install
```
------
#### [ JSON ]
```
{
"schemaVersion":"0.3",
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.",
"default":""
},
"InstanceId":{
"type":"String",
"description":"(Required) The instance you want to patch."
},
"SnapshotId":{
"type":"String",
"description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.",
"default":""
},
"RebootOption":{
"type":"String",
"description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.",
"allowedValues":[
"NoReboot",
"RebootIfNeeded"
],
"default":"RebootIfNeeded"
},
"Operation":{
"type":"String",
"description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.",
"allowedValues":[
"Install",
"Scan"
],
"default":"Install"
}
}
},
```
------
1. 定义完顶层元素后，Emily 继续创作构成运行手册的 `mainSteps` 的操作。第一步使用 `aws:executeAwsApi` 操作输出 `InstanceId` 输入参数中指定的目标实例的当前状态。此操作的输出将用于后续操作。
------
#### [ YAML ]
```
mainSteps:
- name: getInstanceState
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
outputs:
- Name: instanceState
Selector: '$.Reservations[0].Instances[0].State.Name'
Type: String
nextStep: branchOnInstanceState
```
------
#### [ JSON ]
```
"mainSteps":[
{
"name":"getInstanceState",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"inputs":null,
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
]
},
"outputs":[
{
"Name":"instanceState",
"Selector":"$.Reservations[0].Instances[0].State.Name",
"Type":"String"
}
],
"nextStep":"branchOnInstanceState"
},
```
------
1. Emily 没有手动启动和跟踪需要修补的每个实例的原始状态，而是根据目标实例的状态使用上一操作的输出对自动化进行分支。这允许自动化根据 `aws:branch` 操作中定义的条件运行不同的步骤，并提高了自动化的整体效率，无需人工干预。
如果实例状态已为 `running`，则自动化将继续使用 `aws:runCommand` 操作，利用 `AWS-RunPatchBaseline` 文档修补实例。
如果实例的状态为 `stopping`，则自动化使用 `aws:waitForAwsResourceProperty` 操作轮询实例以达到 `stopped` 状态，使用 `executeAwsApi` 操作启动实例，并轮询实例以达到 `running` 状态，然后再修补实例。
如果实例的状态为 `stopped`，则自动化将启动实例并轮询实例以达到 `running` 状态，然后再使用相同的操作修补实例。
------
#### [ YAML ]
```
- name: branchOnInstanceState
action: 'aws:branch'
onFailure: Abort
inputs:
Choices:
- NextStep: startInstance
Variable: '{{getInstanceState.instanceState}}'
StringEquals: stopped
- NextStep: verifyInstanceStopped
Variable: '{{getInstanceState.instanceState}}'
StringEquals: stopping
- NextStep: patchInstance
Variable: '{{getInstanceState.instanceState}}'
StringEquals: running
isEnd: true
- name: startInstance
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: StartInstances
InstanceIds:
- '{{InstanceId}}'
nextStep: verifyInstanceRunning
- name: verifyInstanceRunning
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
PropertySelector: '$.Reservations[0].Instances[0].State.Name'
DesiredValues:
- running
nextStep: patchInstance
- name: verifyInstanceStopped
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
PropertySelector: '$.Reservations[0].Instances[0].State.Name'
DesiredValues:
- stopped
nextStep: startInstance
- name: patchInstance
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 5400
inputs:
DocumentName: 'AWS-RunPatchBaseline'
InstanceIds:
- '{{InstanceId}}'
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
```
------
#### [ JSON ]
```
{
"name":"branchOnInstanceState",
"action":"aws:branch",
"onFailure":"Abort",
"inputs":{
"Choices":[
{
"NextStep":"startInstance",
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"stopped"
},
{
"Or":[
{
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"stopping"
}
],
"NextStep":"verifyInstanceStopped"
},
{
"NextStep":"patchInstance",
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"running"
}
]
},
"isEnd":true
},
{
"name":"startInstance",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"Service":"ec2",
"Api":"StartInstances",
"InstanceIds":[
"{{InstanceId}}"
]
},
"nextStep":"verifyInstanceRunning"
},
{
"name":"verifyInstanceRunning",
"action":"aws:waitForAwsResourceProperty",
"timeoutSeconds":120,
"inputs":{
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
],
"PropertySelector":"$.Reservations[0].Instances[0].State.Name",
"DesiredValues":[
"running"
]
},
"nextStep":"patchInstance"
},
{
"name":"verifyInstanceStopped",
"action":"aws:waitForAwsResourceProperty",
"timeoutSeconds":120,
"inputs":{
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
],
"PropertySelector":"$.Reservations[0].Instances[0].State.Name",
"DesiredValues":[
"stopped"
],
"nextStep":"startInstance"
}
},
{
"name":"patchInstance",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":5400,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"InstanceIds":[
"{{InstanceId}}"
],
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
}
}
},
```
------
1. 修补操作完成后，Emily 希望自动化将目标实例返回到自动化开始之前的状态。她通过再次使用第一个动作的输出来完成此操作。自动化根据目标实例的原始状态，使用 `aws:branch` 操作进行分支。如果实例之前处于 `running` 以外的任何状态，实例将停止。否则，如果实例状态为 `running`，则自动化结束。
------
#### [ YAML ]
```
- name: branchOnOriginalInstanceState
action: 'aws:branch'
onFailure: Abort
inputs:
Choices:
- NextStep: stopInstance
Not:
Variable: '{{getInstanceState.instanceState}}'
StringEquals: running
isEnd: true
- name: stopInstance
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: StopInstances
InstanceIds:
- '{{InstanceId}}'
```
------
#### [ JSON ]
```
{
"name":"branchOnOriginalInstanceState",
"action":"aws:branch",
"onFailure":"Abort",
"inputs":{
"Choices":[
{
"NextStep":"stopInstance",
"Not":{
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"running"
}
}
]
},
"isEnd":true
},
{
"name":"stopInstance",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"Service":"ec2",
"Api":"StopInstances",
"InstanceIds":[
"{{InstanceId}}"
]
}
}
]
}
```
------
1. Emily 检查完成的子运行手册内容，并在同一 AWS 账户 和 AWS 区域 中创建运行手册作为目标实例。现在，她已经准备好继续创建父运行手册的内容。下面是完成的子运行手册内容。
------
#### [ YAML ]
```
schemaVersion: '0.3'
description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: >-
'(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the
actions on your behalf. If no role is specified, Systems Manager
Automation uses your IAM permissions to operate this runbook.'
default: ''
InstanceId:
type: String
description: >-
'(Required) The instance you want to patch.'
SnapshotId:
type: String
description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.'
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.'
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: getInstanceState
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
outputs:
- Name: instanceState
Selector: '$.Reservations[0].Instances[0].State.Name'
Type: String
nextStep: branchOnInstanceState
- name: branchOnInstanceState
action: 'aws:branch'
onFailure: Abort
inputs:
Choices:
- NextStep: startInstance
Variable: '{{getInstanceState.instanceState}}'
StringEquals: stopped
- Or:
- Variable: '{{getInstanceState.instanceState}}'
StringEquals: stopping
NextStep: verifyInstanceStopped
- NextStep: patchInstance
Variable: '{{getInstanceState.instanceState}}'
StringEquals: running
isEnd: true
- name: startInstance
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: StartInstances
InstanceIds:
- '{{InstanceId}}'
nextStep: verifyInstanceRunning
- name: verifyInstanceRunning
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
PropertySelector: '$.Reservations[0].Instances[0].State.Name'
DesiredValues:
- running
nextStep: patchInstance
- name: verifyInstanceStopped
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- '{{InstanceId}}'
PropertySelector: '$.Reservations[0].Instances[0].State.Name'
DesiredValues:
- stopped
nextStep: startInstance
- name: patchInstance
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 5400
inputs:
DocumentName: 'AWS-RunPatchBaseline'
InstanceIds:
- '{{InstanceId}}'
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
- name: branchOnOriginalInstanceState
action: 'aws:branch'
onFailure: Abort
inputs:
Choices:
- NextStep: stopInstance
Not:
Variable: '{{getInstanceState.instanceState}}'
StringEquals: running
isEnd: true
- name: stopInstance
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: StopInstances
InstanceIds:
- '{{InstanceId}}'
```
------
#### [ JSON ]
```
{
"schemaVersion":"0.3",
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"'(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'",
"default":""
},
"InstanceId":{
"type":"String",
"description":"'(Required) The instance you want to patch.'"
},
"SnapshotId":{
"type":"String",
"description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.",
"default":""
},
"RebootOption":{
"type":"String",
"description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.",
"allowedValues":[
"NoReboot",
"RebootIfNeeded"
],
"default":"RebootIfNeeded"
},
"Operation":{
"type":"String",
"description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.",
"allowedValues":[
"Install",
"Scan"
],
"default":"Install"
}
},
"mainSteps":[
{
"name":"getInstanceState",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"inputs":null,
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
]
},
"outputs":[
{
"Name":"instanceState",
"Selector":"$.Reservations[0].Instances[0].State.Name",
"Type":"String"
}
],
"nextStep":"branchOnInstanceState"
},
{
"name":"branchOnInstanceState",
"action":"aws:branch",
"onFailure":"Abort",
"inputs":{
"Choices":[
{
"NextStep":"startInstance",
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"stopped"
},
{
"Or":[
{
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"stopping"
}
],
"NextStep":"verifyInstanceStopped"
},
{
"NextStep":"patchInstance",
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"running"
}
]
},
"isEnd":true
},
{
"name":"startInstance",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"Service":"ec2",
"Api":"StartInstances",
"InstanceIds":[
"{{InstanceId}}"
]
},
"nextStep":"verifyInstanceRunning"
},
{
"name":"verifyInstanceRunning",
"action":"aws:waitForAwsResourceProperty",
"timeoutSeconds":120,
"inputs":{
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
],
"PropertySelector":"$.Reservations[0].Instances[0].State.Name",
"DesiredValues":[
"running"
]
},
"nextStep":"patchInstance"
},
{
"name":"verifyInstanceStopped",
"action":"aws:waitForAwsResourceProperty",
"timeoutSeconds":120,
"inputs":{
"Service":"ec2",
"Api":"DescribeInstances",
"InstanceIds":[
"{{InstanceId}}"
],
"PropertySelector":"$.Reservations[0].Instances[0].State.Name",
"DesiredValues":[
"stopped"
],
"nextStep":"startInstance"
}
},
{
"name":"patchInstance",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":5400,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"InstanceIds":[
"{{InstanceId}}"
],
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
}
}
},
{
"name":"branchOnOriginalInstanceState",
"action":"aws:branch",
"onFailure":"Abort",
"inputs":{
"Choices":[
{
"NextStep":"stopInstance",
"Not":{
"Variable":"{{getInstanceState.instanceState}}",
"StringEquals":"running"
}
}
]
},
"isEnd":true
},
{
"name":"stopInstance",
"action":"aws:executeAwsApi",
"onFailure":"Abort",
"inputs":{
"Service":"ec2",
"Api":"StopInstances",
"InstanceIds":[
"{{InstanceId}}"
]
}
}
]
}
```
------
有关此示例中使用的自动化操作的更多信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
## 创建父运行手册
此示例运行手册继续了上一节介绍的场景。现在 Emily 已经创建了子运行手册，她开始为父运行手册创作内容，如下所示：
1. 首先，她为运行手册的架构和描述提供值，并定义父运行手册的输入参数。
通过使用 `AutomationAssumeRole` 参数，Emily 和她的同事可以使用现有的 IAM 角色，使自动化代表他们执行运行手册中的操作。Emily 使用 `PatchGroupPrimaryKey` 和 `PatchGroupPrimaryValue` 参数来指定与将要修补的数据库实例的主组关联的标签。她使用 `PatchGroupSecondaryKey` 和 `PatchGroupSecondaryValue` 参数来指定与将要修补的数据库实例的辅助组关联的标签。
------
#### [ YAML ]
```
description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.'
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
default: ''
PatchGroupPrimaryKey:
type: String
description: '(Required) The key of the tag for the primary group of instances you want to patch.''
PatchGroupPrimaryValue:
type: String
description: '(Required) The value of the tag for the primary group of instances you want to patch.'
PatchGroupSecondaryKey:
type: String
description: '(Required) The key of the tag for the secondary group of instances you want to patch.'
PatchGroupSecondaryValue:
type: String
description: '(Required) The value of the tag for the secondary group of instances you want to patch.'
```
------
#### [ JSON ]
```
{
"schemaVersion": "0.3",
"description": "An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"assumeRole": "{{AutomationAssumeRole}}",
"parameters": {
"AutomationAssumeRole": {
"type": "String",
"description": "(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.",
"default": ""
},
"PatchGroupPrimaryKey": {
"type": "String",
"description": "(Required) The key of the tag for the primary group of instances you want to patch."
},
"PatchGroupPrimaryValue": {
"type": "String",
"description": "(Required) The value of the tag for the primary group of instances you want to patch."
},
"PatchGroupSecondaryKey": {
"type": "String",
"description": "(Required) The key of the tag for the secondary group of instances you want to patch."
},
"PatchGroupSecondaryValue": {
"type": "String",
"description": "(Required) The value of the tag for the secondary group of instances you want to patch."
}
}
},
```
------
1. 定义顶层元素后，Emily 继续创作构成运行手册的 `mainSteps` 的操作。
第一个操作使用她刚刚创建的子运行手册启动速率控制自动化，该子运行手册将与在 `PatchGroupPrimaryKey` 和 `PatchGroupPrimaryValue` 输入参数中所指定标签关联的实例设置为目标。她使用提供给输入参数的值来指定与要修补的主数据库实例组相关联的标签的键和值。
第一个自动化完成后，第二个操作将使用子运行手册启动另一个速率控制自动化，该子运行手册将与在 `PatchGroupSecondaryKey` 和 `PatchGroupSecondaryValue` 输入参数中所指定标签关联的实例设置为目标。她使用提供给输入参数的值来指定与要修补的辅助数据库实例组相关联的标签的键和值。
------
#### [ YAML ]
```
mainSteps:
- name: patchPrimaryTargets
action: 'aws:executeAutomation'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: RunbookTutorialChildAutomation
Targets:
- Key: 'tag:{{PatchGroupPrimaryKey}}'
Values:
- '{{PatchGroupPrimaryValue}}'
TargetParameterName: 'InstanceId'
- name: patchSecondaryTargets
action: 'aws:executeAutomation'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: RunbookTutorialChildAutomation
Targets:
- Key: 'tag:{{PatchGroupSecondaryKey}}'
Values:
- '{{PatchGroupSecondaryValue}}'
TargetParameterName: 'InstanceId'
```
------
#### [ JSON ]
```
"mainSteps":[
{
"name":"patchPrimaryTargets",
"action":"aws:executeAutomation",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"RunbookTutorialChildAutomation",
"Targets":[
{
"Key":"tag:{{PatchGroupPrimaryKey}}",
"Values":[
"{{PatchGroupPrimaryValue}}"
]
}
],
"TargetParameterName":"InstanceId"
}
},
{
"name":"patchSecondaryTargets",
"action":"aws:executeAutomation",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"RunbookTutorialChildAutomation",
"Targets":[
{
"Key":"tag:{{PatchGroupSecondaryKey}}",
"Values":[
"{{PatchGroupSecondaryValue}}"
]
}
],
"TargetParameterName":"InstanceId"
}
}
]
}
```
------
1. Emily 检查完成的父运行手册内容，并在相同的 AWS 账户和 AWS 区域中创建运行手册作为目标实例。现在，她已经准备好测试自己的运行手册，以确保在将自动化实施到生产环境之前，自动化能够按需运行。下面是完成的父运行手册内容。
------
#### [ YAML ]
```
description: An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
default: ''
PatchGroupPrimaryKey:
type: String
description: (Required) The key of the tag for the primary group of instances you want to patch.
PatchGroupPrimaryValue:
type: String
description: '(Required) The value of the tag for the primary group of instances you want to patch. '
PatchGroupSecondaryKey:
type: String
description: (Required) The key of the tag for the secondary group of instances you want to patch.
PatchGroupSecondaryValue:
type: String
description: '(Required) The value of the tag for the secondary group of instances you want to patch. '
mainSteps:
- name: patchPrimaryTargets
action: 'aws:executeAutomation'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: RunbookTutorialChildAutomation
Targets:
- Key: 'tag:{{PatchGroupPrimaryKey}}'
Values:
- '{{PatchGroupPrimaryValue}}'
TargetParameterName: 'InstanceId'
- name: patchSecondaryTargets
action: 'aws:executeAutomation'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: RunbookTutorialChildAutomation
Targets:
- Key: 'tag:{{PatchGroupSecondaryKey}}'
Values:
- '{{PatchGroupSecondaryValue}}'
TargetParameterName: 'InstanceId'
```
------
#### [ JSON ]
```
{
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"schemaVersion":"0.3",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.",
"default":""
},
"PatchGroupPrimaryKey":{
"type":"String",
"description":"(Required) The key of the tag for the primary group of instances you want to patch."
},
"PatchGroupPrimaryValue":{
"type":"String",
"description":"(Required) The value of the tag for the primary group of instances you want to patch. "
},
"PatchGroupSecondaryKey":{
"type":"String",
"description":"(Required) The key of the tag for the secondary group of instances you want to patch."
},
"PatchGroupSecondaryValue":{
"type":"String",
"description":"(Required) The value of the tag for the secondary group of instances you want to patch. "
}
},
"mainSteps":[
{
"name":"patchPrimaryTargets",
"action":"aws:executeAutomation",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"RunbookTutorialChildAutomation",
"Targets":[
{
"Key":"tag:{{PatchGroupPrimaryKey}}",
"Values":[
"{{PatchGroupPrimaryValue}}"
]
}
],
"TargetParameterName":"InstanceId"
}
},
{
"name":"patchSecondaryTargets",
"action":"aws:executeAutomation",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"RunbookTutorialChildAutomation",
"Targets":[
{
"Key":"tag:{{PatchGroupSecondaryKey}}",
"Values":[
"{{PatchGroupSecondaryValue}}"
]
}
],
"TargetParameterName":"InstanceId"
}
}
]
}
```
------
有关此示例中使用的自动化操作的更多信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
# 示例 2：脚本化运行手册
此示例运行手册解决以下情形。Emily 是 AnyCompany Consultants, LLC 的系统工程师。她之前创建了两个运行手册，这两个运行手册用于父子关系，以修补托管主数据库和辅助数据库的 Amazon Elastic Compute Cloud (Amazon EC2) 实例的组。应用程序每天 24 小时访问这些数据库，因此这两个数据库实例中必须有一个始终可用。
基于此要求，她构建了一个解决方案，使用 `AWS-RunPatchBaseline` Systems Manager (SSM) 文档分阶段修补实例。通过使用此 SSM 文档，她的同事可以在修补操作完成后查看相关的修补程序合规性信息。
首先修补数据库实例的主组，然后修补数据库实例的辅助组。此外，为了避免由于运行之前已停止的实例而产生额外的成本，Emily 确保自动化将修补的实例恢复到修补之前的原始状态。Emily 使用与数据库实例的主组和辅助组关联的标签来确定应按照所需顺序修补哪些实例。
她现有的自动化解决方案有效，但她希望尽可能改进自己的解决方案。为了帮助维护运行手册内容并简化故障排除工作，她希望将自动化压缩到一个运行手册中，并简化输入参数的数量。此外，她希望避免创建多个子自动化。
在审查了可用的自动化操作后，Emily 确定可以使用 `aws:executeScript` 操作来运行她的自定义 Python 脚本，从而改进她的解决方案。她现在开始创作运行手册的内容，如下所示：
1. 首先，她为运行手册的架构和描述提供值，并定义父运行手册的输入参数。
通过使用 `AutomationAssumeRole` 参数，Emily 和她的同事可以使用现有的 IAM 角色，使自动化代表他们执行运行手册中的操作。与[示例 1](automation-authoring-runbooks-parent-child-example.md) 不同的是，`AutomationAssumeRole` 参数现在是必需的，而不是可选的。因为这个运行手册包括 `aws:executeScript` 操作，所以始终需要一个 AWS Identity and Access Management (IAM) 服务角色（或担任角色）。此要求是必要的，因为某些为操作指定的 Python 脚本调用 AWS API 操作。
Emily 使用 `PrimaryPatchGroupTag` 和 `SecondaryPatchGroupTag` 参数指定与要修补的数据库实例的主要和辅助组关联的标签。为了简化所需的输入参数，她决定使用 `StringMap` 参数，而不是使用多个 `String`参数，因为她在示例 1 运行手册中使用了后者。（可选）`Operation`、`RebootOption` 和 `SnapshotId` 参数可用于为 `AWS-RunPatchBaseline` 的文档参数提供值。为了防止向这些运行手册参数提供无效值，她根据需要定义了 `allowedValues`。
------
#### [ YAML ]
```
description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.'
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
PrimaryPatchGroupTag:
type: StringMap
description: '(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}'
SecondaryPatchGroupTag:
type: StringMap
description: '(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}'
SnapshotId:
type: String
description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.'
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.'
allowedValues:
- Install
- Scan
default: Install
```
------
#### [ JSON ]
```
{
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"schemaVersion":"0.3",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook."
},
"PrimaryPatchGroupTag":{
"type":"StringMap",
"description":"(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}"
},
"SecondaryPatchGroupTag":{
"type":"StringMap",
"description":"(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}"
},
"SnapshotId":{
"type":"String",
"description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.",
"default":""
},
"RebootOption":{
"type":"String",
"description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.",
"allowedValues":[
"NoReboot",
"RebootIfNeeded"
],
"default":"RebootIfNeeded"
},
"Operation":{
"type":"String",
"description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.",
"allowedValues":[
"Install",
"Scan"
],
"default":"Install"
}
}
},
```
------
1. 定义顶层元素后，Emily 继续创作构成运行手册的 `mainSteps` 的操作。第一步收集与 `PrimaryPatchGroupTag` 参数中指定的标签关联的所有实例的 ID，并输出 `StringMap` 参数，其中包含实例 ID 和实例的当前状态。此操作的输出将用于后续操作。
请注意，`script` 输入参数不支持 JSON 运行手册。JSON 运行手册必须使用 `attachment` 输入参数提供脚本内容。
------
#### [ YAML ]
```
mainSteps:
- name: getPrimaryInstanceState
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getInstanceStates
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def getInstanceStates(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
tag = events['primaryTag']
tagKey, tagValue = list(tag.items())[0]
instanceQuery = ec2.describe_instances(
Filters=[
{
"Name": "tag:" + tagKey,
"Values": [tagValue]
}]
)
if not instanceQuery['Reservations']:
noInstancesForTagString = "No instances found for specified tag."
return({ 'noInstancesFound' : noInstancesForTagString })
else:
queryResponse = instanceQuery['Reservations']
originalInstanceStates = {}
for results in queryResponse:
instanceSet = results['Instances']
for instance in instanceSet:
instanceId = instance['InstanceId']
originalInstanceStates[instanceId] = instance['State']['Name']
return originalInstanceStates
outputs:
- Name: originalInstanceStates
Selector: $.Payload
Type: StringMap
nextStep: verifyPrimaryInstancesRunning
```
------
#### [ JSON ]
```
"mainSteps":[
{
"name":"getPrimaryInstanceState",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"getInstanceStates",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"originalInstanceStates",
"Selector":"$.Payload",
"Type":"StringMap"
}
],
"nextStep":"verifyPrimaryInstancesRunning"
},
```
------
1. Emily 将上一个操作的输出用于另一个 `aws:executeScript` 操作，以验证与 `PrimaryPatchGroupTag` 参数中所指定标签相关联的所有实例均处于 `running` 状态。
如果实例状态已处于 `running` 或者 `shutting-down` 状态，则脚本将继续遍历剩余的实例。
如果实例的状态为 `stopping`，则脚本轮询实例以达到 `stopped` 状态并启动实例。
如果实例的状态为 `stopped`，脚本将启动实例。
------
#### [ YAML ]
```
- name: verifyPrimaryInstancesRunning
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: verifyInstancesRunning
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def verifyInstancesRunning(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped':
print("The target instance " + instance + " is stopped. The instance will now be started.")
ec2.start_instances(
InstanceIds=[instance]
)
elif instanceDict[instance] == 'stopping':
print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.")
while instanceDict[instance] != 'stopped':
poll = ec2.get_waiter('instance_stopped')
poll.wait(
InstanceIds=[instance]
)
ec2.start_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: waitForPrimaryRunningInstances
```
------
#### [ JSON ]
```
{
"name":"verifyPrimaryInstancesRunning",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"verifyInstancesRunning",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"waitForPrimaryRunningInstances"
},
```
------
1. Emily 验证与 `PrimaryPatchGroupTag` 参数中指定的标签相关联的所有实例已启动或已处于 `running` 状态。然后，她使用另一个脚本来验证所有实例（包括在上一操作中启动的实例）已处于 `running` 状态。
------
#### [ YAML ]
```
- name: waitForPrimaryRunningInstances
action: 'aws:executeScript'
timeoutSeconds: 300
onFailure: Abort
inputs:
Runtime: python3.11
Handler: waitForRunningInstances
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def waitForRunningInstances(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
poll = ec2.get_waiter('instance_running')
poll.wait(
InstanceIds=[instance]
)
nextStep: returnPrimaryTagKey
```
------
#### [ JSON ]
```
{
"name":"waitForPrimaryRunningInstances",
"action":"aws:executeScript",
"timeoutSeconds":300,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"waitForRunningInstances",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"returnPrimaryTagKey"
},
```
------
1. Emily 使用两个脚本来返回键的单个 `String` 值和 `PrimaryPatchGroupTag` 参数中指定的标签的值。这些操作返回的值允许她直接向 `Targets` 文档的参数 `AWS-RunPatchBaseline` 提供值。然后，自动化将继续使用 `aws:runCommand` 操作，利用 `AWS-RunPatchBaseline` 文档修补实例。
------
#### [ YAML ]
```
- name: returnPrimaryTagKey
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['primaryTag']
tagKey = list(tag)[0]
stringKey = "tag:" + tagKey
return {'tagKey' : stringKey}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: primaryPatchGroupKey
Selector: $.Payload.tagKey
Type: String
nextStep: returnPrimaryTagValue
- name: returnPrimaryTagValue
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['primaryTag']
tagKey = list(tag)[0]
tagValue = tag[tagKey]
return {'tagValue' : tagValue}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: primaryPatchGroupValue
Selector: $.Payload.tagValue
Type: String
nextStep: patchPrimaryInstances
- name: patchPrimaryInstances
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
Targets:
- Key: '{{returnPrimaryTagKey.primaryPatchGroupKey}}'
Values:
- '{{returnPrimaryTagValue.primaryPatchGroupValue}}'
MaxConcurrency: 10%
MaxErrors: 10%
nextStep: returnPrimaryToOriginalState
```
------
#### [ JSON ]
```
{
"name":"returnPrimaryTagKey",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"primaryPatchGroupKey",
"Selector":"$.Payload.tagKey",
"Type":"String"
}
],
"nextStep":"returnPrimaryTagValue"
},
{
"name":"returnPrimaryTagValue",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"primaryPatchGroupValue",
"Selector":"$.Payload.tagValue",
"Type":"String"
}
],
"nextStep":"patchPrimaryInstances"
},
{
"name":"patchPrimaryInstances",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
},
"Targets":[
{
"Key":"{{returnPrimaryTagKey.primaryPatchGroupKey}}",
"Values":[
"{{returnPrimaryTagValue.primaryPatchGroupValue}}"
]
}
],
"MaxConcurrency":"10%",
"MaxErrors":"10%"
},
"nextStep":"returnPrimaryToOriginalState"
},
```
------
1. 修补操作完成后，Emily 希望自动化将与 `PrimaryPatchGroupTag` 参数中所指定标签相关联的目标实例返回到自动化开始之前的状态。她通过再次使用脚本中第一个操作的输出来完成此操作。根据目标实例的原始状态，如果该实例以前处于 `running` 以外的任何状态，则实例将停止。否则，如果实例状态为 `running`，则脚本将继续遍历剩余的实例。
------
#### [ YAML ]
```
- name: returnPrimaryToOriginalState
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnToOriginalState
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def returnToOriginalState(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping':
ec2.stop_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: getSecondaryInstanceState
```
------
#### [ JSON ]
```
{
"name":"returnPrimaryToOriginalState",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnToOriginalState",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"getSecondaryInstanceState"
},
```
------
1. 针对与 `PrimaryPatchGroupTag` 参数中所指定标签相关联的实例的修补操作已完成。现在 Emily 复制了运行手册内容中以前的所有操作，将与 `SecondaryPatchGroupTag` 参数中所指定标签相关联的实例设置为目标。
------
#### [ YAML ]
```
- name: getSecondaryInstanceState
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getInstanceStates
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def getInstanceStates(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
tag = events['secondaryTag']
tagKey, tagValue = list(tag.items())[0]
instanceQuery = ec2.describe_instances(
Filters=[
{
"Name": "tag:" + tagKey,
"Values": [tagValue]
}]
)
if not instanceQuery['Reservations']:
noInstancesForTagString = "No instances found for specified tag."
return({ 'noInstancesFound' : noInstancesForTagString })
else:
queryResponse = instanceQuery['Reservations']
originalInstanceStates = {}
for results in queryResponse:
instanceSet = results['Instances']
for instance in instanceSet:
instanceId = instance['InstanceId']
originalInstanceStates[instanceId] = instance['State']['Name']
return originalInstanceStates
outputs:
- Name: originalInstanceStates
Selector: $.Payload
Type: StringMap
nextStep: verifySecondaryInstancesRunning
- name: verifySecondaryInstancesRunning
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: verifyInstancesRunning
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def verifyInstancesRunning(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped':
print("The target instance " + instance + " is stopped. The instance will now be started.")
ec2.start_instances(
InstanceIds=[instance]
)
elif instanceDict[instance] == 'stopping':
print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.")
while instanceDict[instance] != 'stopped':
poll = ec2.get_waiter('instance_stopped')
poll.wait(
InstanceIds=[instance]
)
ec2.start_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: waitForSecondaryRunningInstances
- name: waitForSecondaryRunningInstances
action: 'aws:executeScript'
timeoutSeconds: 300
onFailure: Abort
inputs:
Runtime: python3.11
Handler: waitForRunningInstances
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def waitForRunningInstances(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
poll = ec2.get_waiter('instance_running')
poll.wait(
InstanceIds=[instance]
)
nextStep: returnSecondaryTagKey
- name: returnSecondaryTagKey
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['secondaryTag']
tagKey = list(tag)[0]
stringKey = "tag:" + tagKey
return {'tagKey' : stringKey}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: secondaryPatchGroupKey
Selector: $.Payload.tagKey
Type: String
nextStep: returnSecondaryTagValue
- name: returnSecondaryTagValue
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['secondaryTag']
tagKey = list(tag)[0]
tagValue = tag[tagKey]
return {'tagValue' : tagValue}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: secondaryPatchGroupValue
Selector: $.Payload.tagValue
Type: String
nextStep: patchSecondaryInstances
- name: patchSecondaryInstances
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
Targets:
- Key: '{{returnSecondaryTagKey.secondaryPatchGroupKey}}'
Values:
- '{{returnSecondaryTagValue.secondaryPatchGroupValue}}'
MaxConcurrency: 10%
MaxErrors: 10%
nextStep: returnSecondaryToOriginalState
- name: returnSecondaryToOriginalState
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnToOriginalState
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def returnToOriginalState(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping':
ec2.stop_instances(
InstanceIds=[instance]
)
else:
pass
```
------
#### [ JSON ]
```
{
"name":"getSecondaryInstanceState",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"getInstanceStates",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"originalInstanceStates",
"Selector":"$.Payload",
"Type":"StringMap"
}
],
"nextStep":"verifySecondaryInstancesRunning"
},
{
"name":"verifySecondaryInstancesRunning",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"verifyInstancesRunning",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"waitForSecondaryRunningInstances"
},
{
"name":"waitForSecondaryRunningInstances",
"action":"aws:executeScript",
"timeoutSeconds":300,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"waitForRunningInstances",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"returnSecondaryTagKey"
},
{
"name":"returnSecondaryTagKey",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"secondaryPatchGroupKey",
"Selector":"$.Payload.tagKey",
"Type":"String"
}
],
"nextStep":"returnSecondaryTagValue"
},
{
"name":"returnSecondaryTagValue",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"secondaryPatchGroupValue",
"Selector":"$.Payload.tagValue",
"Type":"String"
}
],
"nextStep":"patchSecondaryInstances"
},
{
"name":"patchSecondaryInstances",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
},
"Targets":[
{
"Key":"{{returnSecondaryTagKey.secondaryPatchGroupKey}}",
"Values":[
"{{returnSecondaryTagValue.secondaryPatchGroupValue}}"
]
}
],
"MaxConcurrency":"10%",
"MaxErrors":"10%"
},
"nextStep":"returnSecondaryToOriginalState"
},
{
"name":"returnSecondaryToOriginalState",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnToOriginalState",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
}
}
]
}
```
------
1. Emily 查看已完成的脚本化运行手册内容，并在同一 AWS 账户和 AWS 区域中创建运行手册作为目标实例。现在，她已经准备好测试运行手册，以确保在将自动化实施到生产环境之前自动化能够按需运行。下面是完成的脚本化运行手册内容。
------
#### [ YAML ]
```
description: An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'
PrimaryPatchGroupTag:
type: StringMap
description: '(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}'
SecondaryPatchGroupTag:
type: StringMap
description: '(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}'
SnapshotId:
type: String
description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.'
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.'
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: getPrimaryInstanceState
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getInstanceStates
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def getInstanceStates(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
tag = events['primaryTag']
tagKey, tagValue = list(tag.items())[0]
instanceQuery = ec2.describe_instances(
Filters=[
{
"Name": "tag:" + tagKey,
"Values": [tagValue]
}]
)
if not instanceQuery['Reservations']:
noInstancesForTagString = "No instances found for specified tag."
return({ 'noInstancesFound' : noInstancesForTagString })
else:
queryResponse = instanceQuery['Reservations']
originalInstanceStates = {}
for results in queryResponse:
instanceSet = results['Instances']
for instance in instanceSet:
instanceId = instance['InstanceId']
originalInstanceStates[instanceId] = instance['State']['Name']
return originalInstanceStates
outputs:
- Name: originalInstanceStates
Selector: $.Payload
Type: StringMap
nextStep: verifyPrimaryInstancesRunning
- name: verifyPrimaryInstancesRunning
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: verifyInstancesRunning
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def verifyInstancesRunning(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped':
print("The target instance " + instance + " is stopped. The instance will now be started.")
ec2.start_instances(
InstanceIds=[instance]
)
elif instanceDict[instance] == 'stopping':
print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.")
while instanceDict[instance] != 'stopped':
poll = ec2.get_waiter('instance_stopped')
poll.wait(
InstanceIds=[instance]
)
ec2.start_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: waitForPrimaryRunningInstances
- name: waitForPrimaryRunningInstances
action: 'aws:executeScript'
timeoutSeconds: 300
onFailure: Abort
inputs:
Runtime: python3.11
Handler: waitForRunningInstances
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def waitForRunningInstances(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
poll = ec2.get_waiter('instance_running')
poll.wait(
InstanceIds=[instance]
)
nextStep: returnPrimaryTagKey
- name: returnPrimaryTagKey
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['primaryTag']
tagKey = list(tag)[0]
stringKey = "tag:" + tagKey
return {'tagKey' : stringKey}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: primaryPatchGroupKey
Selector: $.Payload.tagKey
Type: String
nextStep: returnPrimaryTagValue
- name: returnPrimaryTagValue
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
primaryTag: '{{PrimaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['primaryTag']
tagKey = list(tag)[0]
tagValue = tag[tagKey]
return {'tagValue' : tagValue}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: primaryPatchGroupValue
Selector: $.Payload.tagValue
Type: String
nextStep: patchPrimaryInstances
- name: patchPrimaryInstances
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
Targets:
- Key: '{{returnPrimaryTagKey.primaryPatchGroupKey}}'
Values:
- '{{returnPrimaryTagValue.primaryPatchGroupValue}}'
MaxConcurrency: 10%
MaxErrors: 10%
nextStep: returnPrimaryToOriginalState
- name: returnPrimaryToOriginalState
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnToOriginalState
InputPayload:
targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}'
Script: |-
def returnToOriginalState(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping':
ec2.stop_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: getSecondaryInstanceState
- name: getSecondaryInstanceState
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getInstanceStates
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def getInstanceStates(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
tag = events['secondaryTag']
tagKey, tagValue = list(tag.items())[0]
instanceQuery = ec2.describe_instances(
Filters=[
{
"Name": "tag:" + tagKey,
"Values": [tagValue]
}]
)
if not instanceQuery['Reservations']:
noInstancesForTagString = "No instances found for specified tag."
return({ 'noInstancesFound' : noInstancesForTagString })
else:
queryResponse = instanceQuery['Reservations']
originalInstanceStates = {}
for results in queryResponse:
instanceSet = results['Instances']
for instance in instanceSet:
instanceId = instance['InstanceId']
originalInstanceStates[instanceId] = instance['State']['Name']
return originalInstanceStates
outputs:
- Name: originalInstanceStates
Selector: $.Payload
Type: StringMap
nextStep: verifySecondaryInstancesRunning
- name: verifySecondaryInstancesRunning
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: verifyInstancesRunning
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def verifyInstancesRunning(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped':
print("The target instance " + instance + " is stopped. The instance will now be started.")
ec2.start_instances(
InstanceIds=[instance]
)
elif instanceDict[instance] == 'stopping':
print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.")
while instanceDict[instance] != 'stopped':
poll = ec2.get_waiter('instance_stopped')
poll.wait(
InstanceIds=[instance]
)
ec2.start_instances(
InstanceIds=[instance]
)
else:
pass
nextStep: waitForSecondaryRunningInstances
- name: waitForSecondaryRunningInstances
action: 'aws:executeScript'
timeoutSeconds: 300
onFailure: Abort
inputs:
Runtime: python3.11
Handler: waitForRunningInstances
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def waitForRunningInstances(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
poll = ec2.get_waiter('instance_running')
poll.wait(
InstanceIds=[instance]
)
nextStep: returnSecondaryTagKey
- name: returnSecondaryTagKey
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['secondaryTag']
tagKey = list(tag)[0]
stringKey = "tag:" + tagKey
return {'tagKey' : stringKey}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: secondaryPatchGroupKey
Selector: $.Payload.tagKey
Type: String
nextStep: returnSecondaryTagValue
- name: returnSecondaryTagValue
action: 'aws:executeScript'
timeoutSeconds: 120
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnTagValues
InputPayload:
secondaryTag: '{{SecondaryPatchGroupTag}}'
Script: |-
def returnTagValues(events,context):
tag = events['secondaryTag']
tagKey = list(tag)[0]
tagValue = tag[tagKey]
return {'tagValue' : tagValue}
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: secondaryPatchGroupValue
Selector: $.Payload.tagValue
Type: String
nextStep: patchSecondaryInstances
- name: patchSecondaryInstances
action: 'aws:runCommand'
onFailure: Abort
timeoutSeconds: 7200
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
Targets:
- Key: '{{returnSecondaryTagKey.secondaryPatchGroupKey}}'
Values:
- '{{returnSecondaryTagValue.secondaryPatchGroupValue}}'
MaxConcurrency: 10%
MaxErrors: 10%
nextStep: returnSecondaryToOriginalState
- name: returnSecondaryToOriginalState
action: 'aws:executeScript'
timeoutSeconds: 600
onFailure: Abort
inputs:
Runtime: python3.11
Handler: returnToOriginalState
InputPayload:
targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}'
Script: |-
def returnToOriginalState(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceDict = events['targetInstances']
for instance in instanceDict:
if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping':
ec2.stop_instances(
InstanceIds=[instance]
)
else:
pass
```
------
#### [ JSON ]
```
{
"description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.",
"schemaVersion":"0.3",
"assumeRole":"{{AutomationAssumeRole}}",
"parameters":{
"AutomationAssumeRole":{
"type":"String",
"description":"(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook."
},
"PrimaryPatchGroupTag":{
"type":"StringMap",
"description":"(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}"
},
"SecondaryPatchGroupTag":{
"type":"StringMap",
"description":"(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}"
},
"SnapshotId":{
"type":"String",
"description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.",
"default":""
},
"RebootOption":{
"type":"String",
"description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.",
"allowedValues":[
"NoReboot",
"RebootIfNeeded"
],
"default":"RebootIfNeeded"
},
"Operation":{
"type":"String",
"description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.",
"allowedValues":[
"Install",
"Scan"
],
"default":"Install"
}
},
"mainSteps":[
{
"name":"getPrimaryInstanceState",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"getInstanceStates",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"originalInstanceStates",
"Selector":"$.Payload",
"Type":"StringMap"
}
],
"nextStep":"verifyPrimaryInstancesRunning"
},
{
"name":"verifyPrimaryInstancesRunning",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"verifyInstancesRunning",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"waitForPrimaryRunningInstances"
},
{
"name":"waitForPrimaryRunningInstances",
"action":"aws:executeScript",
"timeoutSeconds":300,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"waitForRunningInstances",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"returnPrimaryTagKey"
},
{
"name":"returnPrimaryTagKey",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"primaryPatchGroupKey",
"Selector":"$.Payload.tagKey",
"Type":"String"
}
],
"nextStep":"returnPrimaryTagValue"
},
{
"name":"returnPrimaryTagValue",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"primaryTag":"{{PrimaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"primaryPatchGroupValue",
"Selector":"$.Payload.tagValue",
"Type":"String"
}
],
"nextStep":"patchPrimaryInstances"
},
{
"name":"patchPrimaryInstances",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
},
"Targets":[
{
"Key":"{{returnPrimaryTagKey.primaryPatchGroupKey}}",
"Values":[
"{{returnPrimaryTagValue.primaryPatchGroupValue}}"
]
}
],
"MaxConcurrency":"10%",
"MaxErrors":"10%"
},
"nextStep":"returnPrimaryToOriginalState"
},
{
"name":"returnPrimaryToOriginalState",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnToOriginalState",
"InputPayload":{
"targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"getSecondaryInstanceState"
},
{
"name":"getSecondaryInstanceState",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"getInstanceStates",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"originalInstanceStates",
"Selector":"$.Payload",
"Type":"StringMap"
}
],
"nextStep":"verifySecondaryInstancesRunning"
},
{
"name":"verifySecondaryInstancesRunning",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"verifyInstancesRunning",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"waitForSecondaryRunningInstances"
},
{
"name":"waitForSecondaryRunningInstances",
"action":"aws:executeScript",
"timeoutSeconds":300,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"waitForRunningInstances",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
},
"nextStep":"returnSecondaryTagKey"
},
{
"name":"returnSecondaryTagKey",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"secondaryPatchGroupKey",
"Selector":"$.Payload.tagKey",
"Type":"String"
}
],
"nextStep":"returnSecondaryTagValue"
},
{
"name":"returnSecondaryTagValue",
"action":"aws:executeScript",
"timeoutSeconds":120,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnTagValues",
"InputPayload":{
"secondaryTag":"{{SecondaryPatchGroupTag}}"
},
"Script":"..."
},
"outputs":[
{
"Name":"Payload",
"Selector":"$.Payload",
"Type":"StringMap"
},
{
"Name":"secondaryPatchGroupValue",
"Selector":"$.Payload.tagValue",
"Type":"String"
}
],
"nextStep":"patchSecondaryInstances"
},
{
"name":"patchSecondaryInstances",
"action":"aws:runCommand",
"onFailure":"Abort",
"timeoutSeconds":7200,
"inputs":{
"DocumentName":"AWS-RunPatchBaseline",
"Parameters":{
"SnapshotId":"{{SnapshotId}}",
"RebootOption":"{{RebootOption}}",
"Operation":"{{Operation}}"
},
"Targets":[
{
"Key":"{{returnSecondaryTagKey.secondaryPatchGroupKey}}",
"Values":[
"{{returnSecondaryTagValue.secondaryPatchGroupValue}}"
]
}
],
"MaxConcurrency":"10%",
"MaxErrors":"10%"
},
"nextStep":"returnSecondaryToOriginalState"
},
{
"name":"returnSecondaryToOriginalState",
"action":"aws:executeScript",
"timeoutSeconds":600,
"onFailure":"Abort",
"inputs":{
"Runtime":"python3.11",
"Handler":"returnToOriginalState",
"InputPayload":{
"targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}"
},
"Script":"..."
}
}
]
}
```
------
有关此示例中使用的自动化操作的更多信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
# 其他运行手册示例
以下示例运行手册演示了如何使用 AWS Systems Manager 自动化操作来自动执行常见部署、故障排除和维护任务。
**注意**
本部分提供的示例运行手册旨在演示如何创建自定义运行手册以支持您的特定操作需求。这些运行手册并非供您在生产环境中原样使用。但是，您可以自定义这些文档来满足自己的使用需求。
**Topics**
+ [部署 VPC 架构和 Microsoft Active Directory 域控制器](automation-document-architecture-deployment-example.md)
+ [从最新快照还原根卷](automation-document-instance-recovery-example.md)
+ [创建 AMI 和跨区域副本](automation-document-backup-maintenance-example.md)
# 部署 VPC 架构和 Microsoft Active Directory 域控制器
要提高效率并实现常见任务的标准化，可以选择自动执行部署。如果您定期在多个账户和 AWS 区域 中部署相同的架构，此操作会很有帮助。自动进行架构部署还可以降低在手动部署架构时发生人为错误的可能性。AWS Systems Manager自动化操作可帮助您做到这一点。Automation 是 AWS Systems Manager 中的一项工具。
以下示例 AWS Systems Manager 运行手册执行这些操作：
+ 使用 Systems Manager Parameter Store 检索最新的 Windows Server 2016 Amazon Machine Image（AMI），在启动将配置作为域控制器的 EC2 实例时使用。Parameter Store 是 AWS Systems Manager 中的一项工具。
+ 使用 `aws:executeAwsApi` 自动化操作调用多个 AWS API 操作来创建 VPC 架构。域控制器实例在私有子网中启动，使用 NAT 网关连接到 Internet。这允许实例上的 SSM Agent 以访问必需的 Systems Manager 端点。
+ 使用 `aws:waitForAwsResourceProperty` 自动化操作确认上一个操作所启动的实例对于 `Online` 处于 AWS Systems Manager 状态。
+ 使用 `aws:runCommand` 自动化操作配置作为 Microsoft Active Directory 域控制器启动的实例。
------
#### [ YAML ]
```
---
description: Custom Automation Deployment Example
schemaVersion: '0.3'
parameters:
AutomationAssumeRole:
type: String
default: ''
description: >-
(Optional) The ARN of the role that allows Automation to perform the
actions on your behalf. If no role is specified, Systems Manager
Automation uses your IAM permissions to run this runbook.
mainSteps:
- name: getLatestWindowsAmi
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ssm
Api: GetParameter
Name: >-
/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base
outputs:
- Name: amiId
Selector: $.Parameter.Value
Type: String
nextStep: createSSMInstanceRole
- name: createSSMInstanceRole
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: iam
Api: CreateRole
AssumeRolePolicyDocument: >-
{"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"Service":["ec2.amazonaws.com"]},"Action":["sts:AssumeRole"]}]}
RoleName: sampleSSMInstanceRole
nextStep: attachManagedSSMPolicy
- name: attachManagedSSMPolicy
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: iam
Api: AttachRolePolicy
PolicyArn: 'arn:aws:iam::aws:policy/service-role/AmazonSSMManagedInstanceCore'
RoleName: sampleSSMInstanceRole
nextStep: createSSMInstanceProfile
- name: createSSMInstanceProfile
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: iam
Api: CreateInstanceProfile
InstanceProfileName: sampleSSMInstanceRole
outputs:
- Name: instanceProfileArn
Selector: $.InstanceProfile.Arn
Type: String
nextStep: addSSMInstanceRoleToProfile
- name: addSSMInstanceRoleToProfile
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: iam
Api: AddRoleToInstanceProfile
InstanceProfileName: sampleSSMInstanceRole
RoleName: sampleSSMInstanceRole
nextStep: createVpc
- name: createVpc
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateVpc
CidrBlock: 10.0.100.0/22
outputs:
- Name: vpcId
Selector: $.Vpc.VpcId
Type: String
nextStep: getMainRtb
- name: getMainRtb
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeRouteTables
Filters:
- Name: vpc-id
Values:
- '{{ createVpc.vpcId }}'
outputs:
- Name: mainRtbId
Selector: '$.RouteTables[0].RouteTableId'
Type: String
nextStep: verifyMainRtb
- name: verifyMainRtb
action: aws:assertAwsResourceProperty
onFailure: Abort
inputs:
Service: ec2
Api: DescribeRouteTables
RouteTableIds:
- '{{ getMainRtb.mainRtbId }}'
PropertySelector: '$.RouteTables[0].Associations[0].Main'
DesiredValues:
- 'True'
nextStep: createPubSubnet
- name: createPubSubnet
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateSubnet
CidrBlock: 10.0.103.0/24
AvailabilityZone: us-west-2c
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: pubSubnetId
Selector: $.Subnet.SubnetId
Type: String
nextStep: createPubRtb
- name: createPubRtb
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateRouteTable
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: pubRtbId
Selector: $.RouteTable.RouteTableId
Type: String
nextStep: createIgw
- name: createIgw
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateInternetGateway
outputs:
- Name: igwId
Selector: $.InternetGateway.InternetGatewayId
Type: String
nextStep: attachIgw
- name: attachIgw
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AttachInternetGateway
InternetGatewayId: '{{ createIgw.igwId }}'
VpcId: '{{ createVpc.vpcId }}'
nextStep: allocateEip
- name: allocateEip
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AllocateAddress
Domain: vpc
outputs:
- Name: eipAllocationId
Selector: $.AllocationId
Type: String
nextStep: createNatGw
- name: createNatGw
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateNatGateway
AllocationId: '{{ allocateEip.eipAllocationId }}'
SubnetId: '{{ createPubSubnet.pubSubnetId }}'
outputs:
- Name: natGwId
Selector: $.NatGateway.NatGatewayId
Type: String
nextStep: verifyNatGwAvailable
- name: verifyNatGwAvailable
action: aws:waitForAwsResourceProperty
timeoutSeconds: 150
inputs:
Service: ec2
Api: DescribeNatGateways
NatGatewayIds:
- '{{ createNatGw.natGwId }}'
PropertySelector: '$.NatGateways[0].State'
DesiredValues:
- available
nextStep: createNatRoute
- name: createNatRoute
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateRoute
DestinationCidrBlock: 0.0.0.0/0
NatGatewayId: '{{ createNatGw.natGwId }}'
RouteTableId: '{{ getMainRtb.mainRtbId }}'
nextStep: createPubRoute
- name: createPubRoute
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateRoute
DestinationCidrBlock: 0.0.0.0/0
GatewayId: '{{ createIgw.igwId }}'
RouteTableId: '{{ createPubRtb.pubRtbId }}'
nextStep: setPubSubAssoc
- name: setPubSubAssoc
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AssociateRouteTable
RouteTableId: '{{ createPubRtb.pubRtbId }}'
SubnetId: '{{ createPubSubnet.pubSubnetId }}'
- name: createDhcpOptions
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateDhcpOptions
DhcpConfigurations:
- Key: domain-name-servers
Values:
- '10.0.100.50,10.0.101.50'
- Key: domain-name
Values:
- sample.com
outputs:
- Name: dhcpOptionsId
Selector: $.DhcpOptions.DhcpOptionsId
Type: String
nextStep: createDCSubnet1
- name: createDCSubnet1
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateSubnet
CidrBlock: 10.0.100.0/24
AvailabilityZone: us-west-2a
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: firstSubnetId
Selector: $.Subnet.SubnetId
Type: String
nextStep: createDCSubnet2
- name: createDCSubnet2
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateSubnet
CidrBlock: 10.0.101.0/24
AvailabilityZone: us-west-2b
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: secondSubnetId
Selector: $.Subnet.SubnetId
Type: String
nextStep: createDCSecGroup
- name: createDCSecGroup
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateSecurityGroup
GroupName: SampleDCSecGroup
Description: Security Group for Sample Domain Controllers
VpcId: '{{ createVpc.vpcId }}'
outputs:
- Name: dcSecGroupId
Selector: $.GroupId
Type: String
nextStep: authIngressDCTraffic
- name: authIngressDCTraffic
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AuthorizeSecurityGroupIngress
GroupId: '{{ createDCSecGroup.dcSecGroupId }}'
IpPermissions:
- FromPort: -1
IpProtocol: '-1'
IpRanges:
- CidrIp: 0.0.0.0/0
Description: Allow all traffic between Domain Controllers
nextStep: verifyInstanceProfile
- name: verifyInstanceProfile
action: aws:waitForAwsResourceProperty
maxAttempts: 5
onFailure: Abort
inputs:
Service: iam
Api: ListInstanceProfilesForRole
RoleName: sampleSSMInstanceRole
PropertySelector: '$.InstanceProfiles[0].Arn'
DesiredValues:
- '{{ createSSMInstanceProfile.instanceProfileArn }}'
nextStep: iamEventualConsistency
- name: iamEventualConsistency
action: aws:sleep
inputs:
Duration: PT2M
nextStep: launchDC1
- name: launchDC1
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: RunInstances
BlockDeviceMappings:
- DeviceName: /dev/sda1
Ebs:
DeleteOnTermination: true
VolumeSize: 50
VolumeType: gp2
- DeviceName: xvdf
Ebs:
DeleteOnTermination: true
VolumeSize: 100
VolumeType: gp2
IamInstanceProfile:
Arn: '{{ createSSMInstanceProfile.instanceProfileArn }}'
ImageId: '{{ getLatestWindowsAmi.amiId }}'
InstanceType: t2.micro
MaxCount: 1
MinCount: 1
PrivateIpAddress: 10.0.100.50
SecurityGroupIds:
- '{{ createDCSecGroup.dcSecGroupId }}'
SubnetId: '{{ createDCSubnet1.firstSubnetId }}'
TagSpecifications:
- ResourceType: instance
Tags:
- Key: Name
Value: SampleDC1
outputs:
- Name: pdcInstanceId
Selector: '$.Instances[0].InstanceId'
Type: String
nextStep: launchDC2
- name: launchDC2
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: RunInstances
BlockDeviceMappings:
- DeviceName: /dev/sda1
Ebs:
DeleteOnTermination: true
VolumeSize: 50
VolumeType: gp2
- DeviceName: xvdf
Ebs:
DeleteOnTermination: true
VolumeSize: 100
VolumeType: gp2
IamInstanceProfile:
Arn: '{{ createSSMInstanceProfile.instanceProfileArn }}'
ImageId: '{{ getLatestWindowsAmi.amiId }}'
InstanceType: t2.micro
MaxCount: 1
MinCount: 1
PrivateIpAddress: 10.0.101.50
SecurityGroupIds:
- '{{ createDCSecGroup.dcSecGroupId }}'
SubnetId: '{{ createDCSubnet2.secondSubnetId }}'
TagSpecifications:
- ResourceType: instance
Tags:
- Key: Name
Value: SampleDC2
outputs:
- Name: adcInstanceId
Selector: '$.Instances[0].InstanceId'
Type: String
nextStep: verifyDCInstanceState
- name: verifyDCInstanceState
action: aws:waitForAwsResourceProperty
inputs:
Service: ec2
Api: DescribeInstanceStatus
IncludeAllInstances: true
InstanceIds:
- '{{ launchDC1.pdcInstanceId }}'
- '{{ launchDC2.adcInstanceId }}'
PropertySelector: '$.InstanceStatuses..InstanceState.Name'
DesiredValues:
- running
nextStep: verifyInstancesOnlineSSM
- name: verifyInstancesOnlineSSM
action: aws:waitForAwsResourceProperty
timeoutSeconds: 600
inputs:
Service: ssm
Api: DescribeInstanceInformation
InstanceInformationFilterList:
- key: InstanceIds
valueSet:
- '{{ launchDC1.pdcInstanceId }}'
- '{{ launchDC2.adcInstanceId }}'
PropertySelector: '$.InstanceInformationList..PingStatus'
DesiredValues:
- Online
nextStep: installADRoles
- name: installADRoles
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{ launchDC1.pdcInstanceId }}'
- '{{ launchDC2.adcInstanceId }}'
Parameters:
commands: |-
try {
Install-WindowsFeature -Name AD-Domain-Services -IncludeManagementTools
}
catch {
Write-Error "Failed to install ADDS Role."
}
nextStep: setAdminPassword
- name: setAdminPassword
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{ launchDC1.pdcInstanceId }}'
Parameters:
commands:
- net user Administrator "sampleAdminPass123!"
nextStep: createForest
- name: createForest
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{ launchDC1.pdcInstanceId }}'
Parameters:
commands: |-
$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force
try {
Install-ADDSForest -DomainName "sample.com" -DomainMode 6 -ForestMode 6 -InstallDNS -DatabasePath "D:\NTDS" -SysvolPath "D:\SYSVOL" -SafeModeAdministratorPassword $dsrmPass -Force
}
catch {
Write-Error $_
}
try {
Add-DnsServerForwarder -IPAddress "10.0.100.2"
}
catch {
Write-Error $_
}
nextStep: associateDhcpOptions
- name: associateDhcpOptions
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AssociateDhcpOptions
DhcpOptionsId: '{{ createDhcpOptions.dhcpOptionsId }}'
VpcId: '{{ createVpc.vpcId }}'
nextStep: waitForADServices
- name: waitForADServices
action: aws:sleep
inputs:
Duration: PT1M
nextStep: promoteADC
- name: promoteADC
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{ launchDC2.adcInstanceId }}'
Parameters:
commands: |-
ipconfig /renew
$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force
$domAdminUser = "sample\Administrator"
$domAdminPass = "sampleAdminPass123!" | ConvertTo-SecureString -asPlainText -Force
$domAdminCred = New-Object System.Management.Automation.PSCredential($domAdminUser,$domAdminPass)
try {
Install-ADDSDomainController -DomainName "sample.com" -InstallDNS -DatabasePath "D:\NTDS" -SysvolPath "D:\SYSVOL" -SafeModeAdministratorPassword $dsrmPass -Credential $domAdminCred -Force
}
catch {
Write-Error $_
}
```
------
#### [ JSON ]
```
{
"description": "Custom Automation Deployment Example",
"schemaVersion": "0.3",
"assumeRole": "{{ AutomationAssumeRole }}",
"parameters": {
"AutomationAssumeRole": {
"type": "String",
"description": "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook.",
"default": ""
}
},
"mainSteps": [
{
"name": "getLatestWindowsAmi",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ssm",
"Api": "GetParameter",
"Name": "/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base"
},
"outputs": [
{
"Name": "amiId",
"Selector": "$.Parameter.Value",
"Type": "String"
}
],
"nextStep": "createSSMInstanceRole"
},
{
"name": "createSSMInstanceRole",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "CreateRole",
"AssumeRolePolicyDocument": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":[\"ec2.amazonaws.com\"]},\"Action\":[\"sts:AssumeRole\"]}]}",
"RoleName": "sampleSSMInstanceRole"
},
"nextStep": "attachManagedSSMPolicy"
},
{
"name": "attachManagedSSMPolicy",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "AttachRolePolicy",
"PolicyArn": "arn:aws:iam::aws:policy/service-role/AmazonSSMManagedInstanceCore",
"RoleName": "sampleSSMInstanceRole"
},
"nextStep": "createSSMInstanceProfile"
},
{
"name": "createSSMInstanceProfile",
"action":"aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "CreateInstanceProfile",
"InstanceProfileName": "sampleSSMInstanceRole"
},
"outputs": [
{
"Name": "instanceProfileArn",
"Selector": "$.InstanceProfile.Arn",
"Type": "String"
}
],
"nextStep": "addSSMInstanceRoleToProfile"
},
{
"name": "addSSMInstanceRoleToProfile",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "AddRoleToInstanceProfile",
"InstanceProfileName": "sampleSSMInstanceRole",
"RoleName": "sampleSSMInstanceRole"
},
"nextStep": "createVpc"
},
{
"name": "createVpc",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateVpc",
"CidrBlock": "10.0.100.0/22"
},
"outputs": [
{
"Name": "vpcId",
"Selector": "$.Vpc.VpcId",
"Type": "String"
}
],
"nextStep": "getMainRtb"
},
{
"name": "getMainRtb",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeRouteTables",
"Filters": [
{
"Name": "vpc-id",
"Values": ["{{ createVpc.vpcId }}"]
}
]
},
"outputs": [
{
"Name": "mainRtbId",
"Selector": "$.RouteTables[0].RouteTableId",
"Type": "String"
}
],
"nextStep": "verifyMainRtb"
},
{
"name": "verifyMainRtb",
"action": "aws:assertAwsResourceProperty",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeRouteTables",
"RouteTableIds": ["{{ getMainRtb.mainRtbId }}"],
"PropertySelector": "$.RouteTables[0].Associations[0].Main",
"DesiredValues": ["True"]
},
"nextStep": "createPubSubnet"
},
{
"name": "createPubSubnet",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateSubnet",
"CidrBlock": "10.0.103.0/24",
"AvailabilityZone": "us-west-2c",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs":[
{
"Name": "pubSubnetId",
"Selector": "$.Subnet.SubnetId",
"Type": "String"
}
],
"nextStep": "createPubRtb"
},
{
"name": "createPubRtb",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateRouteTable",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs": [
{
"Name": "pubRtbId",
"Selector": "$.RouteTable.RouteTableId",
"Type": "String"
}
],
"nextStep": "createIgw"
},
{
"name": "createIgw",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateInternetGateway"
},
"outputs": [
{
"Name": "igwId",
"Selector": "$.InternetGateway.InternetGatewayId",
"Type": "String"
}
],
"nextStep": "attachIgw"
},
{
"name": "attachIgw",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AttachInternetGateway",
"InternetGatewayId": "{{ createIgw.igwId }}",
"VpcId": "{{ createVpc.vpcId }}"
},
"nextStep": "allocateEip"
},
{
"name": "allocateEip",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AllocateAddress",
"Domain": "vpc"
},
"outputs": [
{
"Name": "eipAllocationId",
"Selector": "$.AllocationId",
"Type": "String"
}
],
"nextStep": "createNatGw"
},
{
"name": "createNatGw",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateNatGateway",
"AllocationId": "{{ allocateEip.eipAllocationId }}",
"SubnetId": "{{ createPubSubnet.pubSubnetId }}"
},
"outputs":[
{
"Name": "natGwId",
"Selector": "$.NatGateway.NatGatewayId",
"Type": "String"
}
],
"nextStep": "verifyNatGwAvailable"
},
{
"name": "verifyNatGwAvailable",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 150,
"inputs": {
"Service": "ec2",
"Api": "DescribeNatGateways",
"NatGatewayIds": [
"{{ createNatGw.natGwId }}"
],
"PropertySelector": "$.NatGateways[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "createNatRoute"
},
{
"name": "createNatRoute",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateRoute",
"DestinationCidrBlock": "0.0.0.0/0",
"NatGatewayId": "{{ createNatGw.natGwId }}",
"RouteTableId": "{{ getMainRtb.mainRtbId }}"
},
"nextStep": "createPubRoute"
},
{
"name": "createPubRoute",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateRoute",
"DestinationCidrBlock": "0.0.0.0/0",
"GatewayId": "{{ createIgw.igwId }}",
"RouteTableId": "{{ createPubRtb.pubRtbId }}"
},
"nextStep": "setPubSubAssoc"
},
{
"name": "setPubSubAssoc",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AssociateRouteTable",
"RouteTableId": "{{ createPubRtb.pubRtbId }}",
"SubnetId": "{{ createPubSubnet.pubSubnetId }}"
}
},
{
"name": "createDhcpOptions",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateDhcpOptions",
"DhcpConfigurations": [
{
"Key": "domain-name-servers",
"Values": ["10.0.100.50,10.0.101.50"]
},
{
"Key": "domain-name",
"Values": ["sample.com"]
}
]
},
"outputs": [
{
"Name": "dhcpOptionsId",
"Selector": "$.DhcpOptions.DhcpOptionsId",
"Type": "String"
}
],
"nextStep": "createDCSubnet1"
},
{
"name": "createDCSubnet1",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateSubnet",
"CidrBlock": "10.0.100.0/24",
"AvailabilityZone": "us-west-2a",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs": [
{
"Name": "firstSubnetId",
"Selector": "$.Subnet.SubnetId",
"Type": "String"
}
],
"nextStep": "createDCSubnet2"
},
{
"name": "createDCSubnet2",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateSubnet",
"CidrBlock": "10.0.101.0/24",
"AvailabilityZone": "us-west-2b",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs": [
{
"Name": "secondSubnetId",
"Selector": "$.Subnet.SubnetId",
"Type": "String"
}
],
"nextStep": "createDCSecGroup"
},
{
"name": "createDCSecGroup",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateSecurityGroup",
"GroupName": "SampleDCSecGroup",
"Description": "Security Group for Example Domain Controllers",
"VpcId": "{{ createVpc.vpcId }}"
},
"outputs": [
{
"Name": "dcSecGroupId",
"Selector": "$.GroupId",
"Type": "String"
}
],
"nextStep": "authIngressDCTraffic"
},
{
"name": "authIngressDCTraffic",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AuthorizeSecurityGroupIngress",
"GroupId": "{{ createDCSecGroup.dcSecGroupId }}",
"IpPermissions": [
{
"FromPort": -1,
"IpProtocol": "-1",
"IpRanges": [
{
"CidrIp": "0.0.0.0/0",
"Description": "Allow all traffic between Domain Controllers"
}
]
}
]
},
"nextStep": "verifyInstanceProfile"
},
{
"name": "verifyInstanceProfile",
"action": "aws:waitForAwsResourceProperty",
"maxAttempts": 5,
"onFailure": "Abort",
"inputs": {
"Service": "iam",
"Api": "ListInstanceProfilesForRole",
"RoleName": "sampleSSMInstanceRole",
"PropertySelector": "$.InstanceProfiles[0].Arn",
"DesiredValues": [
"{{ createSSMInstanceProfile.instanceProfileArn }}"
]
},
"nextStep": "iamEventualConsistency"
},
{
"name": "iamEventualConsistency",
"action": "aws:sleep",
"inputs": {
"Duration": "PT2M"
},
"nextStep": "launchDC1"
},
{
"name": "launchDC1",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "RunInstances",
"BlockDeviceMappings": [
{
"DeviceName": "/dev/sda1",
"Ebs": {
"DeleteOnTermination": true,
"VolumeSize": 50,
"VolumeType": "gp2"
}
},
{
"DeviceName": "xvdf",
"Ebs": {
"DeleteOnTermination": true,
"VolumeSize": 100,
"VolumeType": "gp2"
}
}
],
"IamInstanceProfile": {
"Arn": "{{ createSSMInstanceProfile.instanceProfileArn }}"
},
"ImageId": "{{ getLatestWindowsAmi.amiId }}",
"InstanceType": "t2.micro",
"MaxCount": 1,
"MinCount": 1,
"PrivateIpAddress": "10.0.100.50",
"SecurityGroupIds": [
"{{ createDCSecGroup.dcSecGroupId }}"
],
"SubnetId": "{{ createDCSubnet1.firstSubnetId }}",
"TagSpecifications": [
{
"ResourceType": "instance",
"Tags": [
{
"Key": "Name",
"Value": "SampleDC1"
}
]
}
]
},
"outputs": [
{
"Name": "pdcInstanceId",
"Selector": "$.Instances[0].InstanceId",
"Type": "String"
}
],
"nextStep": "launchDC2"
},
{
"name": "launchDC2",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "RunInstances",
"BlockDeviceMappings": [
{
"DeviceName": "/dev/sda1",
"Ebs": {
"DeleteOnTermination": true,
"VolumeSize": 50,
"VolumeType": "gp2"
}
},
{
"DeviceName": "xvdf",
"Ebs": {
"DeleteOnTermination": true,
"VolumeSize": 100,
"VolumeType": "gp2"
}
}
],
"IamInstanceProfile": {
"Arn": "{{ createSSMInstanceProfile.instanceProfileArn }}"
},
"ImageId": "{{ getLatestWindowsAmi.amiId }}",
"InstanceType": "t2.micro",
"MaxCount": 1,
"MinCount": 1,
"PrivateIpAddress": "10.0.101.50",
"SecurityGroupIds": [
"{{ createDCSecGroup.dcSecGroupId }}"
],
"SubnetId": "{{ createDCSubnet2.secondSubnetId }}",
"TagSpecifications": [
{
"ResourceType": "instance",
"Tags": [
{
"Key": "Name",
"Value": "SampleDC2"
}
]
}
]
},
"outputs": [
{
"Name": "adcInstanceId",
"Selector": "$.Instances[0].InstanceId",
"Type": "String"
}
],
"nextStep": "verifyDCInstanceState"
},
{
"name": "verifyDCInstanceState",
"action": "aws:waitForAwsResourceProperty",
"inputs": {
"Service": "ec2",
"Api": "DescribeInstanceStatus",
"IncludeAllInstances": true,
"InstanceIds": [
"{{ launchDC1.pdcInstanceId }}",
"{{ launchDC2.adcInstanceId }}"
],
"PropertySelector": "$.InstanceStatuses[0].InstanceState.Name",
"DesiredValues": [
"running"
]
},
"nextStep": "verifyInstancesOnlineSSM"
},
{
"name": "verifyInstancesOnlineSSM",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 600,
"inputs": {
"Service": "ssm",
"Api": "DescribeInstanceInformation",
"InstanceInformationFilterList": [
{
"key": "InstanceIds",
"valueSet": [
"{{ launchDC1.pdcInstanceId }}",
"{{ launchDC2.adcInstanceId }}"
]
}
],
"PropertySelector": "$.InstanceInformationList[0].PingStatus",
"DesiredValues": [
"Online"
]
},
"nextStep": "installADRoles"
},
{
"name": "installADRoles",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{ launchDC1.pdcInstanceId }}",
"{{ launchDC2.adcInstanceId }}"
],
"Parameters": {
"commands": [
"try {",
" Install-WindowsFeature -Name AD-Domain-Services -IncludeManagementTools",
"}",
"catch {",
" Write-Error \"Failed to install ADDS Role.\"",
"}"
]
}
},
"nextStep": "setAdminPassword"
},
{
"name": "setAdminPassword",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{ launchDC1.pdcInstanceId }}"
],
"Parameters": {
"commands": [
"net user Administrator \"sampleAdminPass123!\""
]
}
},
"nextStep": "createForest"
},
{
"name": "createForest",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{ launchDC1.pdcInstanceId }}"
],
"Parameters": {
"commands": [
"$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force",
"try {",
" Install-ADDSForest -DomainName \"sample.com\" -DomainMode 6 -ForestMode 6 -InstallDNS -DatabasePath \"D:\\NTDS\" -SysvolPath \"D:\\SYSVOL\" -SafeModeAdministratorPassword $dsrmPass -Force",
"}",
"catch {",
" Write-Error $_",
"}",
"try {",
" Add-DnsServerForwarder -IPAddress \"10.0.100.2\"",
"}",
"catch {",
" Write-Error $_",
"}"
]
}
},
"nextStep": "associateDhcpOptions"
},
{
"name": "associateDhcpOptions",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AssociateDhcpOptions",
"DhcpOptionsId": "{{ createDhcpOptions.dhcpOptionsId }}",
"VpcId": "{{ createVpc.vpcId }}"
},
"nextStep": "waitForADServices"
},
{
"name": "waitForADServices",
"action": "aws:sleep",
"inputs": {
"Duration": "PT1M"
},
"nextStep": "promoteADC"
},
{
"name": "promoteADC",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{ launchDC2.adcInstanceId }}"
],
"Parameters": {
"commands": [
"ipconfig /renew",
"$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force",
"$domAdminUser = \"sample\\Administrator\"",
"$domAdminPass = \"sampleAdminPass123!\" | ConvertTo-SecureString -asPlainText -Force",
"$domAdminCred = New-Object System.Management.Automation.PSCredential($domAdminUser,$domAdminPass)",
"try {",
" Install-ADDSDomainController -DomainName \"sample.com\" -InstallDNS -DatabasePath \"D:\\NTDS\" -SysvolPath \"D:\\SYSVOL\" -SafeModeAdministratorPassword $dsrmPass -Credential $domAdminCred -Force",
"}",
"catch {",
" Write-Error $_",
"}"
]
}
}
}
]
}
```
------
# 从最新快照还原根卷
根卷上的操作系统可能会出于各种原因而受损。例如，在执行修补操作后，实例可能会因内核或注册表损坏而无法成功启动。自动执行常见故障排除任务（例如，从修补操作前拍摄的最新快照还原根卷）可以减少停机时间并加快故障排除工作。AWS Systems Manager自动化操作可帮助您做到这一点。Automation 是 AWS Systems Manager 中的一项工具。
以下示例 AWS Systems Manager 运行手册执行这些操作：
+ 使用 `aws:executeAwsApi` 自动化操作从实例的根卷检索详细信息。
+ 使用 `aws:executeScript` 自动化操作检索根卷的最新快照。
+ 如果找到了根卷的快照，则使用 `aws:branch` 自动化操作继续执行自动化。
------
#### [ YAML ]
```
---
description: Custom Automation Troubleshooting Example
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
AutomationAssumeRole:
type: String
description: "(Required) The ARN of the role that allows Automation to perform
the actions on your behalf. If no role is specified, Systems Manager Automation
uses your IAM permissions to use this runbook."
default: ''
InstanceId:
type: String
description: "(Required) The Instance Id whose root EBS volume you want to restore the latest Snapshot."
default: ''
mainSteps:
- name: getInstanceDetails
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- "{{ InstanceId }}"
outputs:
- Name: availabilityZone
Selector: "$.Reservations[0].Instances[0].Placement.AvailabilityZone"
Type: String
- Name: rootDeviceName
Selector: "$.Reservations[0].Instances[0].RootDeviceName"
Type: String
nextStep: getRootVolumeId
- name: getRootVolumeId
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeVolumes
Filters:
- Name: attachment.device
Values: ["{{ getInstanceDetails.rootDeviceName }}"]
- Name: attachment.instance-id
Values: ["{{ InstanceId }}"]
outputs:
- Name: rootVolumeId
Selector: "$.Volumes[0].VolumeId"
Type: String
nextStep: getSnapshotsByStartTime
- name: getSnapshotsByStartTime
action: aws:executeScript
timeoutSeconds: 45
onFailure: Abort
inputs:
Runtime: python3.11
Handler: getSnapshotsByStartTime
InputPayload:
rootVolumeId : "{{ getRootVolumeId.rootVolumeId }}"
Script: |-
def getSnapshotsByStartTime(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
rootVolumeId = events['rootVolumeId']
snapshotsQuery = ec2.describe_snapshots(
Filters=[
{
"Name": "volume-id",
"Values": [rootVolumeId]
}
]
)
if not snapshotsQuery['Snapshots']:
noSnapshotFoundString = "NoSnapshotFound"
return { 'noSnapshotFound' : noSnapshotFoundString }
else:
jsonSnapshots = snapshotsQuery['Snapshots']
sortedSnapshots = sorted(jsonSnapshots, key=lambda k: k['StartTime'], reverse=True)
latestSortedSnapshotId = sortedSnapshots[0]['SnapshotId']
return { 'latestSnapshotId' : latestSortedSnapshotId }
outputs:
- Name: Payload
Selector: $.Payload
Type: StringMap
- Name: latestSnapshotId
Selector: $.Payload.latestSnapshotId
Type: String
- Name: noSnapshotFound
Selector: $.Payload.noSnapshotFound
Type: String
nextStep: branchFromResults
- name: branchFromResults
action: aws:branch
onFailure: Abort
inputs:
Choices:
- NextStep: createNewRootVolumeFromSnapshot
Not:
Variable: "{{ getSnapshotsByStartTime.noSnapshotFound }}"
StringEquals: "NoSnapshotFound"
isEnd: true
- name: createNewRootVolumeFromSnapshot
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateVolume
AvailabilityZone: "{{ getInstanceDetails.availabilityZone }}"
SnapshotId: "{{ getSnapshotsByStartTime.latestSnapshotId }}"
outputs:
- Name: newRootVolumeId
Selector: "$.VolumeId"
Type: String
nextStep: stopInstance
- name: stopInstance
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: StopInstances
InstanceIds:
- "{{ InstanceId }}"
nextStep: verifyVolumeAvailability
- name: verifyVolumeAvailability
action: aws:waitForAwsResourceProperty
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
PropertySelector: "$.Volumes[0].State"
DesiredValues:
- "available"
nextStep: verifyInstanceStopped
- name: verifyInstanceStopped
action: aws:waitForAwsResourceProperty
timeoutSeconds: 120
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- "{{ InstanceId }}"
PropertySelector: "$.Reservations[0].Instances[0].State.Name"
DesiredValues:
- "stopped"
nextStep: detachRootVolume
- name: detachRootVolume
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DetachVolume
VolumeId: "{{ getRootVolumeId.rootVolumeId }}"
nextStep: verifyRootVolumeDetached
- name: verifyRootVolumeDetached
action: aws:waitForAwsResourceProperty
timeoutSeconds: 30
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ getRootVolumeId.rootVolumeId }}"
PropertySelector: "$.Volumes[0].State"
DesiredValues:
- "available"
nextStep: attachNewRootVolume
- name: attachNewRootVolume
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: AttachVolume
Device: "{{ getInstanceDetails.rootDeviceName }}"
InstanceId: "{{ InstanceId }}"
VolumeId: "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
nextStep: verifyNewRootVolumeAttached
- name: verifyNewRootVolumeAttached
action: aws:waitForAwsResourceProperty
timeoutSeconds: 30
inputs:
Service: ec2
Api: DescribeVolumes
VolumeIds:
- "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
PropertySelector: "$.Volumes[0].Attachments[0].State"
DesiredValues:
- "attached"
nextStep: startInstance
- name: startInstance
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: StartInstances
InstanceIds:
- "{{ InstanceId }}"
```
------
#### [ JSON ]
```
{
"description": "Custom Automation Troubleshooting Example",
"schemaVersion": "0.3",
"assumeRole": "{{ AutomationAssumeRole }}",
"parameters": {
"AutomationAssumeRole": {
"type": "String",
"description": "(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook.",
"default": ""
},
"InstanceId": {
"type": "String",
"description": "(Required) The Instance Id whose root EBS volume you want to restore the latest Snapshot.",
"default": ""
}
},
"mainSteps": [
{
"name": "getInstanceDetails",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeInstances",
"InstanceIds": [
"{{ InstanceId }}"
]
},
"outputs": [
{
"Name": "availabilityZone",
"Selector": "$.Reservations[0].Instances[0].Placement.AvailabilityZone",
"Type": "String"
},
{
"Name": "rootDeviceName",
"Selector": "$.Reservations[0].Instances[0].RootDeviceName",
"Type": "String"
}
],
"nextStep": "getRootVolumeId"
},
{
"name": "getRootVolumeId",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DescribeVolumes",
"Filters": [
{
"Name": "attachment.device",
"Values": [
"{{ getInstanceDetails.rootDeviceName }}"
]
},
{
"Name": "attachment.instance-id",
"Values": [
"{{ InstanceId }}"
]
}
]
},
"outputs": [
{
"Name": "rootVolumeId",
"Selector": "$.Volumes[0].VolumeId",
"Type": "String"
}
],
"nextStep": "getSnapshotsByStartTime"
},
{
"name": "getSnapshotsByStartTime",
"action": "aws:executeScript",
"timeoutSeconds": 45,
"onFailure": "Continue",
"inputs": {
"Runtime": "python3.11",
"Handler": "getSnapshotsByStartTime",
"InputPayload": {
"rootVolumeId": "{{ getRootVolumeId.rootVolumeId }}"
},
"Attachment": "getSnapshotsByStartTime.py"
},
"outputs": [
{
"Name": "Payload",
"Selector": "$.Payload",
"Type": "StringMap"
},
{
"Name": "latestSnapshotId",
"Selector": "$.Payload.latestSnapshotId",
"Type": "String"
},
{
"Name": "noSnapshotFound",
"Selector": "$.Payload.noSnapshotFound",
"Type": "String"
}
],
"nextStep": "branchFromResults"
},
{
"name": "branchFromResults",
"action": "aws:branch",
"onFailure": "Abort",
"inputs": {
"Choices": [
{
"NextStep": "createNewRootVolumeFromSnapshot",
"Not": {
"Variable": "{{ getSnapshotsByStartTime.noSnapshotFound }}",
"StringEquals": "NoSnapshotFound"
}
}
]
},
"isEnd": true
},
{
"name": "createNewRootVolumeFromSnapshot",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateVolume",
"AvailabilityZone": "{{ getInstanceDetails.availabilityZone }}",
"SnapshotId": "{{ getSnapshotsByStartTime.latestSnapshotId }}"
},
"outputs": [
{
"Name": "newRootVolumeId",
"Selector": "$.VolumeId",
"Type": "String"
}
],
"nextStep": "stopInstance"
},
{
"name": "stopInstance",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "StopInstances",
"InstanceIds": [
"{{ InstanceId }}"
]
},
"nextStep": "verifyVolumeAvailability"
},
{
"name": "verifyVolumeAvailability",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 120,
"inputs": {
"Service": "ec2",
"Api": "DescribeVolumes",
"VolumeIds": [
"{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
],
"PropertySelector": "$.Volumes[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "verifyInstanceStopped"
},
{
"name": "verifyInstanceStopped",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 120,
"inputs": {
"Service": "ec2",
"Api": "DescribeInstances",
"InstanceIds": [
"{{ InstanceId }}"
],
"PropertySelector": "$.Reservations[0].Instances[0].State.Name",
"DesiredValues": [
"stopped"
]
},
"nextStep": "detachRootVolume"
},
{
"name": "detachRootVolume",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "DetachVolume",
"VolumeId": "{{ getRootVolumeId.rootVolumeId }}"
},
"nextStep": "verifyRootVolumeDetached"
},
{
"name": "verifyRootVolumeDetached",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 30,
"inputs": {
"Service": "ec2",
"Api": "DescribeVolumes",
"VolumeIds": [
"{{ getRootVolumeId.rootVolumeId }}"
],
"PropertySelector": "$.Volumes[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "attachNewRootVolume"
},
{
"name": "attachNewRootVolume",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "AttachVolume",
"Device": "{{ getInstanceDetails.rootDeviceName }}",
"InstanceId": "{{ InstanceId }}",
"VolumeId": "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
},
"nextStep": "verifyNewRootVolumeAttached"
},
{
"name": "verifyNewRootVolumeAttached",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 30,
"inputs": {
"Service": "ec2",
"Api": "DescribeVolumes",
"VolumeIds": [
"{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}"
],
"PropertySelector": "$.Volumes[0].Attachments[0].State",
"DesiredValues": [
"attached"
]
},
"nextStep": "startInstance"
},
{
"name": "startInstance",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "StartInstances",
"InstanceIds": [
"{{ InstanceId }}"
]
}
}
],
"files": {
"getSnapshotsByStartTime.py": {
"checksums": {
"sha256": "sampleETagValue"
}
}
}
}
```
------
# 创建 AMI 和跨区域副本
创建实例的 Amazon Machine Image (AMI) 是备份和恢复操作中的常用过程。也可以选择将 AMI 作为灾难恢复架构的一部分复制到另一个 AWS 区域。如果问题需要进行故障转移，则自动执行常见的维护任务可以减少停机时间。AWS Systems Manager自动化操作可帮助您做到这一点。Automation 是 AWS Systems Manager 中的一项工具。
以下示例 AWS Systems Manager 运行手册执行这些操作：
+ 使用 `aws:executeAwsApi` 自动化操作创建 AMI。
+ 使用 `aws:waitForAwsResourceProperty` 自动化操作确认 AMI 的可用性。
+ 使用 `aws:executeScript` 自动化操作将 AMI 复制到目标区域。
------
#### [ YAML ]
```
---
description: Custom Automation Backup and Recovery Example
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
AutomationAssumeRole:
type: String
description: "(Required) The ARN of the role that allows Automation to perform
the actions on your behalf. If no role is specified, Systems Manager Automation
uses your IAM permissions to use this runbook."
default: ''
InstanceId:
type: String
description: "(Required) The ID of the EC2 instance."
default: ''
mainSteps:
- name: createImage
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: CreateImage
InstanceId: "{{ InstanceId }}"
Name: "Automation Image for {{ InstanceId }}"
NoReboot: false
outputs:
- Name: newImageId
Selector: "$.ImageId"
Type: String
nextStep: verifyImageAvailability
- name: verifyImageAvailability
action: aws:waitForAwsResourceProperty
timeoutSeconds: 600
inputs:
Service: ec2
Api: DescribeImages
ImageIds:
- "{{ createImage.newImageId }}"
PropertySelector: "$.Images[0].State"
DesiredValues:
- available
nextStep: copyImage
- name: copyImage
action: aws:executeScript
timeoutSeconds: 45
onFailure: Abort
inputs:
Runtime: python3.11
Handler: crossRegionImageCopy
InputPayload:
newImageId : "{{ createImage.newImageId }}"
Script: |-
def crossRegionImageCopy(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2', region_name='us-east-1')
newImageId = events['newImageId']
ec2.copy_image(
Name='DR Copy for ' + newImageId,
SourceImageId=newImageId,
SourceRegion='us-west-2'
)
```
------
#### [ JSON ]
```
{
"description": "Custom Automation Backup and Recovery Example",
"schemaVersion": "0.3",
"assumeRole": "{{ AutomationAssumeRole }}",
"parameters": {
"AutomationAssumeRole": {
"type": "String",
"description": "(Required) The ARN of the role that allows Automation to perform\nthe actions on your behalf. If no role is specified, Systems Manager Automation\nuses your IAM permissions to run this runbook.",
"default": ""
},
"InstanceId": {
"type": "String",
"description": "(Required) The ID of the EC2 instance.",
"default": ""
}
},
"mainSteps": [
{
"name": "createImage",
"action": "aws:executeAwsApi",
"onFailure": "Abort",
"inputs": {
"Service": "ec2",
"Api": "CreateImage",
"InstanceId": "{{ InstanceId }}",
"Name": "Automation Image for {{ InstanceId }}",
"NoReboot": false
},
"outputs": [
{
"Name": "newImageId",
"Selector": "$.ImageId",
"Type": "String"
}
],
"nextStep": "verifyImageAvailability"
},
{
"name": "verifyImageAvailability",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 600,
"inputs": {
"Service": "ec2",
"Api": "DescribeImages",
"ImageIds": [
"{{ createImage.newImageId }}"
],
"PropertySelector": "$.Images[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "copyImage"
},
{
"name": "copyImage",
"action": "aws:executeScript",
"timeoutSeconds": 45,
"onFailure": "Abort",
"inputs": {
"Runtime": "python3.11",
"Handler": "crossRegionImageCopy",
"InputPayload": {
"newImageId": "{{ createImage.newImageId }}"
},
"Attachment": "crossRegionImageCopy.py"
}
}
],
"files": {
"crossRegionImageCopy.py": {
"checksums": {
"sha256": "sampleETagValue"
}
}
}
}
```
------
# 创建填充 AWS 资源的输入参数
Automation 是 Systems Manager 中的一项工具，可在 AWS 管理控制台中填充与您为输入参数定义的资源类型相匹配的 AWS 资源。与资源类型匹配的 AWS 账户 中的资源将显示在下拉列表中供您选择。您可以为 Amazon Elastic Compute Cloud (Amazon EC2) 实例、Amazon Simple Storage Service (Amazon S3) 存储桶以及 AWS Identity and Access Management (IAM) 角色定义输入参数类型。支持的类型定义与用于查找匹配资源的正则表达式如下：
+ `AWS::EC2::Instance::Id` - `^m?i-([a-z0-9]{8}|[a-z0-9]{17})$`
+ `List` - `^m?i-([a-z0-9]{8}|[a-z0-9]{17})$`
+ `AWS::S3::Bucket::Name` - `^[0-9a-z][a-z0-9\\-\\.]{3,63}$`
+ `List` - `^[0-9a-z][a-z0-9\\-\\.]{3,63}$`
+ `AWS::IAM::Role::Arn` - `^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):iam::[0-9]{12}:role/.*$`
+ `List` - `^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):iam::[0-9]{12}:role/.*$`
以下是在运行手册内容中定义的输入参数类型的示例。
------
#### [ YAML ]
```
description: Enables encryption on an Amazon S3 bucket
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
BucketName:
type: 'AWS::S3::Bucket::Name'
description: (Required) The name of the Amazon S3 bucket you want to encrypt.
SSEAlgorithm:
type: String
description: (Optional) The server-side encryption algorithm to use for the default encryption.
default: AES256
AutomationAssumeRole:
type: 'AWS::IAM::Role::Arn'
description: (Optional) The Amazon Resource Name (ARN) of the role that allows Automation to perform the actions on your behalf.
default: ''
mainSteps:
- name: enableBucketEncryption
action: 'aws:executeAwsApi'
inputs:
Service: s3
Api: PutBucketEncryption
Bucket: '{{BucketName}}'
ServerSideEncryptionConfiguration:
Rules:
- ApplyServerSideEncryptionByDefault:
SSEAlgorithm: '{{SSEAlgorithm}}'
isEnd: true
```
------
#### [ JSON ]
```
{
"description": "Enables encryption on an Amazon S3 bucket",
"schemaVersion": "0.3",
"assumeRole": "{{ AutomationAssumeRole }}",
"parameters": {
"BucketName": {
"type": "AWS::S3::Bucket::Name",
"description": "(Required) The name of the Amazon S3 bucket you want to encrypt."
},
"SSEAlgorithm": {
"type": "String",
"description": "(Optional) The server-side encryption algorithm to use for the default encryption.",
"default": "AES256"
},
"AutomationAssumeRole": {
"type": "AWS::IAM::Role::Arn",
"description": "(Optional) The Amazon Resource Name (ARN) of the role that allows Automation to perform the actions on your behalf.",
"default": ""
}
},
"mainSteps": [
{
"name": "enableBucketEncryption",
"action": "aws:executeAwsApi",
"inputs": {
"Service": "s3",
"Api": "PutBucketEncryption",
"Bucket": "{{BucketName}}",
"ServerSideEncryptionConfiguration": {
"Rules": [
{
"ApplyServerSideEncryptionByDefault": {
"SSEAlgorithm": "{{SSEAlgorithm}}"
}
}
]
}
},
"isEnd": true
}
]
}
```
------
# 正在使用文档生成器创建运行手册
如果 AWS Systems Manager 公有运行手册不支持您希望在 AWS 资源上执行的操作，您可以创建自己的运行手册。要创建自定义运行手册，您可以手动创建包含相应自动化操作的本地 YAML 或 JSON 格式文件。或者，您也可以使用 Systems Manager Automation 控制台中的文档生成器来构建自定义运行手册。
通过使用文档生成器，您可以将自动化操作添加到自定义运行手册中，并提供所需的参数，而无需使用 JSON 或 YAML 语法。在添加步骤并创建运行手册后，系统将您添加的操作转换为 Systems Manager 可用于运行自动化的 YAML 格式。
自动化文档支持使用 Markdown（一种标记语言），它允许您为运行手册和其中的各个步骤添加 Wiki 样式的描述。有关使用 Markdown 的更多信息，请参阅[在 AWS 中使用 Markdown](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)。
## 使用文档生成器创建运行手册
**开始前的准备工作**
我们建议您阅读可在运行手册中使用的各种操作。有关更多信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
**使用文档生成器创建运行手册**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 选择**创建自动化**。
1. 对于**名称**，为运行手册输入一个描述性名称。
1. 对于**文档描述**，请提供运行手册的 markdown 样式描述。您可以提供使用运行手册的说明、编号的步骤或描述运行手册的任何其他类型的信息。请参阅默认文本以了解设置内容格式的信息。
**提示**
在**隐藏预览**和**显示预览**之间切换，以便在编写时查看描述内容的效果。
1. （可选）对于 **Assume role (担任角色)**，请输入代表您执行操作的服务角色的名称或 ARN。如果未指定角色，自动化使用运行自动化的用户的访问权限。
**重要**
对于不归 Amazon 所有并使用 `aws:executeScript` 操作的运行手册，必须指定一个角色。有关信息，请参阅[使用运行手册的权限](automation-document-script-considerations.md#script-permissions)。
1. （可选）对于**输出**，请输入执行该运行手册的自动化的任何输出以供其他进程使用。
例如，如果文档创建新的 AMI，您可以指定 ["CreateImage.ImageId"]，然后使用该输出以在后续自动化中创建新的实例。
1. （可选）展开**输入参数**部分，然后执行以下操作。
1. 对于**参数名称**，请输入要创建的运行手册参数的描述性名称。
1. 对于**类型**，请选择参数的类型，例如 `String` 或 `MapList`。
1. 对于**必需**，请执行以下操作之一：
+ 如果必须在运行时提供该运行手册参数的值，请选择**是**。
+ 如果该参数不是必需的，请选择**否**，然后（可选）在**默认值**中输入默认参数值。
1. 对于**描述**，请输入运行手册参数的描述。
**注意**
要添加更多运行手册参数，请选择**添加参数**。要删除运行手册参数，请选择 **X**（删除）按钮。
1. （可选）展开**目标类型**部分，然后选择一种目标类型以定义可以运行自动化的资源的类型。例如，要在 EC2 实例上使用运行手册，请选择 `/AWS::EC2::Instance`。
**注意**
如果指定“`/`”值，则运行文档可以在所有类型的资源上运行。有关有效资源类型列表，请参阅 *AWS CloudFormation 用户指南* 中的 [AWS 资源类型参考](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html)。
1. （可选）展开**文档标签**部分，然后输入一个或多个标签键值对以应用于运行手册。标签可以轻松标识、划分和搜索资源。
1. 在**步骤 1** 部分中，提供以下信息。
+ 对于**步骤名称**，请输入自动化的第一步的描述性名称。
+ 对于**操作类型**，请选择用于该步骤的操作类型。
有关可用操作类型的列表和信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
+ 对于**描述**，请输入自动化步骤的描述。您可以使用 Markdown 设置文本格式。
+ 根据选定的**操作类型**，在**步骤输入**部分中输入操作类型所需的输入。例如，如果选择了 `aws:approve` 操作，您必须为 `Approvers` 属性指定一个值。
有关步骤输入字段的信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)中的选定操作类型的条目。例如：[`aws:executeStateMachine` - 运行 AWS Step Functions 状态机。](automation-action-executeStateMachine.md)。
+ （可选）对于**其他输入**，请提供运行手册所需的任何其他输入值。可用的输入类型取决于您为步骤选择的操作类型。（请注意，某些操作类型需要使用输入值。）
**注意**
要添加更多输入，请选择 **Add optional input (添加可选的输入)**。要删除输入，请选择 **X**（删除）按钮。
+ （可选）对于**输出**，请输入执行该步骤的任何输出以供其他进程使用。
**注意**
**输出**并非适用于所有操作类型。
+ （可选）展开**通用属性**部分，然后指定所有自动化操作的通用操作属性。例如，对于**超时秒数**，您可以提供一个值以指定步骤在停止之前可以运行多长时间（以秒为单位）。
有关更多信息，请参阅 [所有操作共享的属性](automation-actions.md#automation-common)。
**注意**
要添加更多步骤，请选择**添加步骤**，然后重复创建步骤的过程。要删除步骤，请选择**删除步骤**。
1. 选择**创建自动化**以保存运行手册。
## 创建运行脚本的运行手册
以下过程展示了如何在 AWS Systems Manager Automation 控制台中使用文档生成器创建运行脚本的自定义运行手册。
您创建的运行手册的第一步运行一个脚本以启动 Amazon Elastic Compute Cloud (Amazon EC2) 实例。第二步运行另一个脚本来监控要更改为 `ok` 的实例状态检查。然后，报告自动化的整体状态 `Success`。
**开始前的准备工作**
确保您已完成以下步骤：
+ 确认您具有管理员权限，或为您授予了相应的权限以在 AWS Identity and Access Management (IAM) 中访问 Systems Manager。
有关信息，请参阅[验证用户的运行手册访问权限](automation-setup.md#automation-setup-user-access)。
+ 确认在您的 AWS 账户 账户中具有自动化的 IAM 服务角色（也称为*担任角色*）。该角色是必需的，因为该演练使用 `aws:executeScript` 操作。
有关创建此角色的信息，请参阅 [为自动化配置服务角色（担任角色）访问权限](automation-setup.md#automation-setup-configure-role)。
有关用于运行 `aws:executeScript` 的 IAM 服务角色要求的信息，请参阅 [使用运行手册的权限](automation-document-script-considerations.md#script-permissions)。
+ 确认您具有启动 EC2 实例的权限。
有关更多信息，请参阅《Amazon EC2 用户指南》**中的 [IAM 与 Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#intro-to-iam)。
**创建使用文档生成器运行脚本的自定义运行手册**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 选择**创建自动化**。
1. 对于**名称**，请为运行手册键入以下描述性名称：**LaunchInstanceAndCheckStatus**。
1. （可选）对于**文档描述)**，请使用 Markdown 将默认文本替换为该运行手册的描述。示例如下：
```
##Title: LaunchInstanceAndCheckState
-----
**Purpose**: This runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this runbook continuously checks the instance status check value for the launched instance until the status ```ok``` is returned.
##Parameters:
-----
Name | Type | Description | Default Value
------------- | ------------- | ------------- | -------------
assumeRole | String | (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. | -
imageId | String | (Optional) The AMI ID to use for launching the instance. The default value uses the latest Amazon Linux 2023 AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 }}
```
1. 对于**担任角色**，请使用 **arn:aws:iam::111122223333:role/AutomationServiceRole** 格式输入自动化的自动化 IAM 服务角色（担任角色）的 ARN。使用您的 AWS 账户 ID 替代 111122223333。
您指定的角色用于提供启动自动化执行所需的权限。
**重要**
对于不归 Amazon 所有并使用 `aws:executeScript` 操作的运行手册，必须指定一个角色。有关信息，请参阅[使用运行手册的权限](automation-document-script-considerations.md#script-permissions)。
1. 展开**输入参数**，然后执行以下操作。
1. 对于**参数名称**，请输入 **imageId**。
1. 对于**类型**，选择 **String**。
1. 对于**必需**，请选择 `No`。
1. 对于**默认值**，请输入以下内容。
```
{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 }}
```
**注意**
该值使用最新的 Amazon Linux 2023 Amazon Machine Image（AMI）ID 启动 Amazon EC2 实例。如果要使用不同的 AMI，请将该值替换为您的 AMI ID。
1. 对于**描述**，请输入以下内容。
```
(Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux 2023 AMI ID.
```
1. 选择**添加参数)**以创建第二个参数 **tagValue**，然后输入以下内容。
1. 对于**参数名称**，请输入 **tagValue**。
1. 对于**类型**，选择 **String**。
1. 对于**必需**，请选择 `No`。
1. 对于**默认值**，请输入 **LaunchedBySsmAutomation**。这会将标签键对值 `Name:LaunchedBySsmAutomation` 添加到实例中。
1. 对于**描述**，请输入以下内容。
```
(Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation.
```
1. 选择**添加参数** 以创建第三个参数 **instanceType**，然后输入以下信息。
1. 对于**参数名称**，请输入 **instanceType**。
1. 对于**类型**，选择 **String**。
1. 对于**必需**，请选择 `No`。
1. 对于**默认值**，请输入 **t2.micro**。
1. 对于**参数描述**，请输入以下内容。
```
(Optional) The instance type to use for the instance. The default value is t2.micro.
```
1. 展开**目标类型**，然后选择 **"/"**。
1. （可选）展开**文档标签**以将资源标签应用于运行手册。为**标签键** 输入 **Purpose**，并为**标签值**输入 **LaunchInstanceAndCheckState**。
1. 在**步骤 1** 部分中，完成以下步骤。
1. 对于**步骤名称**，为自动化的第一步输入以下描述性步骤名称：**LaunchEc2Instance**。
1. 对于**操作类型**，请选择**运行脚本)** (**aws:executeScript**)。
1. 对于**描述**，请输入自动化步骤的描述，例如以下内容。
```
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script.
```
1. 展开**输入**。
1. 对于**运行时**，请选择运行提供的脚本所使用的运行时语言。
1. 对于**处理程序**，输入 **launch\$1instance**。这是在以下脚本中声明的函数名称。
**注意**
这对于 PowerShell 不是必需的。
1. 对于**脚本**，请将默认内容替换为以下内容。请确保将脚本与相应的运行时值匹配。
------
#### [ Python ]
```
def launch_instance(events, context):
import boto3
ec2 = boto3.client('ec2')
image_id = events['image_id']
tag_value = events['tag_value']
instance_type = events['instance_type']
tag_config = {'ResourceType': 'instance', 'Tags': [{'Key':'Name', 'Value':tag_value}]}
res = ec2.run_instances(ImageId=image_id, InstanceType=instance_type, MaxCount=1, MinCount=1, TagSpecifications=[tag_config])
instance_id = res['Instances'][0]['InstanceId']
print('[INFO] 1 EC2 instance is successfully launched', instance_id)
return { 'InstanceId' : instance_id }
```
------
#### [ PowerShell ]
```
Install-Module AWS.Tools.EC2 -Force
Import-Module AWS.Tools.EC2
$payload = $env:InputPayload | ConvertFrom-Json
$imageid = $payload.image_id
$tagvalue = $payload.tag_value
$instanceType = $payload.instance_type
$type = New-Object Amazon.EC2.InstanceType -ArgumentList $instanceType
$resource = New-Object Amazon.EC2.ResourceType -ArgumentList 'instance'
$tag = @{Key='Name';Value=$tagValue}
$tagSpecs = New-Object Amazon.EC2.Model.TagSpecification
$tagSpecs.ResourceType = $resource
$tagSpecs.Tags.Add($tag)
$res = New-EC2Instance -ImageId $imageId -MinCount 1 -MaxCount 1 -InstanceType $type -TagSpecification $tagSpecs
return @{'InstanceId'=$res.Instances.InstanceId}
```
------
1. 展开**其他输入**。
1. 对于**输入名称**，请选择 **InputPayload**。对于**输入值**，请输入以下 YAML 数据。
```
image_id: "{{ imageId }}"
tag_value: "{{ tagValue }}"
instance_type: "{{ instanceType }}"
```
1. 展开**输出**，然后执行以下操作：
+ 对于**名称**，请输入 **payload**。
+ 对于**选择器**，请输入 **\$1.Payload**。
+ 对于**类型**，选择 `StringMap`。
1. 选择**添加步骤**将第二步添加到运行手册中。第二步查询在步骤 1 中启动的实例的状态，并等到返回的状态为 `ok`。
1. 在 **Step 2 (步骤 2)** 部分中，执行以下操作。
1. 对于**步骤名称**，请为自动化的第二步输入以下描述性名称：**WaitForInstanceStatusOk**。
1. 对于**操作类型**，请选择**运行脚本** (**aws:executeScript**)。
1. 对于**描述**，请输入自动化步骤的描述，例如以下内容。
```
**About This Step**
The script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned.
```
1. 对于**运行时**，选择用于执行提供的脚本的运行时语言。
1. 对于**处理程序**，输入 **poll\$1instance**。这是在以下脚本中声明的函数名称。
**注意**
这对于 PowerShell 不是必需的。
1. 对于**脚本**，请将默认内容替换为以下内容。请确保将脚本与相应的运行时值匹配。
------
#### [ Python ]
```
def poll_instance(events, context):
import boto3
import time
ec2 = boto3.client('ec2')
instance_id = events['InstanceId']
print('[INFO] Waiting for instance status check to report ok', instance_id)
instance_status = "null"
while True:
res = ec2.describe_instance_status(InstanceIds=[instance_id])
if len(res['InstanceStatuses']) == 0:
print("Instance status information is not available yet")
time.sleep(5)
continue
instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
print('[INFO] Polling to get status of the instance', instance_status)
if instance_status == 'ok':
break
time.sleep(10)
return {'Status': instance_status, 'InstanceId': instance_id}
```
------
#### [ PowerShell ]
```
Install-Module AWS.Tools.EC2 -Force
$inputPayload = $env:InputPayload | ConvertFrom-Json
$instanceId = $inputPayload.payload.InstanceId
$status = Get-EC2InstanceStatus -InstanceId $instanceId
while ($status.Status.Status -ne 'ok'){
Write-Host 'Polling get status of the instance', $instanceId
Start-Sleep -Seconds 5
$status = Get-EC2InstanceStatus -InstanceId $instanceId
}
return @{Status = $status.Status.Status; InstanceId = $instanceId}
```
------
1. 展开**其他输入**。
1. 对于**输入名称**，请选择 **InputPayload**。对于**输入值**，请输入以下内容：
```
{{ LaunchEc2Instance.payload }}
```
1. 选择**创建自动化**以保存运行手册。
# 在运行手册中使用脚本
自动化运行手册支持将脚本作为自动化的一部分运行。Automation 是 AWS Systems Manager 中的一项工具。通过使用运行手册，您可以直接在 AWS 中运行脚本，而无需创建单独的计算环境来运行脚本。由于运行手册可以将脚本步骤与其他自动化步骤类型（例如批准）一起运行，因此您能够在紧急或不明确的情况下手动进行干预。您可以把来自运行手册中 `aws:executeScript` 操作的输出添加到 Amazon CloudWatch Logs。有关更多信息，请参阅 [使用 CloudWatch Logs 记录自动化操作输出](automation-action-logging.md)。
## 使用运行手册的权限
要使用运行手册，Systems Manager 必须使用 AWS Identity and Access Management (IAM) 角色的权限。自动化用于确定使用哪个角色的权限的方法取决于一些因素，以及步骤是否使用 `aws:executeScript` 操作。
对于不使用 `aws:executeScript` 的运行手册，自动化将使用以下两种权限来源之一：
+ 在运行手册中指定或作为参数传递的 IAM 服务角色或担任角色的权限。
+ 如果未指定 IAM 服务角色，则为启动自动化的用户的权限。
不过，如果运行手册中的步骤包含 `aws:executeScript` 操作，并且为该操作指定的 Python 或 PowerShell 脚本调用任何 AWS API 操作，则始终需要使用 IAM 服务角色（担任角色）。自动化按以下顺序检查该角色：
+ 在运行手册中指定或作为参数传递的 IAM 服务角色或担任角色的权限。
+ 如果找不到任何角色，自动化尝试在没有任何权限的情况下运行为 `aws:executeScript` 指定的 Python 或 PowerShell 脚本。如果脚本调用 AWS API 操作（例如，Amazon EC2 `CreateImage` 操作）或者尝试对 AWS 资源（例如 EC2 实例）执行操作，则包含脚本的步骤将失败，并且 Systems Manager 返回一条错误消息以报告失败。
## 将脚本添加到运行手册
您可以通过内联方式将脚本作为运行手册中的步骤的一部分，从而将其添加到运行手册中。您还可以从本地计算机中上传脚本或指定脚本所在的 Amazon Simple Storage Service (Amazon S3) 存储桶，以将脚本附加到运行手册。在运行脚本的步骤完成后，脚本的输出将作为 JSON 对象提供，您可以将其作为运行手册中的后续步骤的输入。有关 `aws:executeScript` 操作以及如何使用脚本附件的更多信息，请参阅 [`aws:executeScript` - 运行脚本](automation-action-executeScript.md)。
## 运行手册的脚本限制
运行手册强制执行 5 个文件附加文件的限制。脚本可以采用 Python 脚本 (.py) 或 PowerShell Core 脚本 (.ps1) 的形式，也可以作为 .zip 文件中的内容附加。
# 在运行手册中使用条件语句
默认情况下，在运行手册的 `mainSteps` 部分中定义的步骤将按先后顺序运行。在一个操作完成后，`mainSteps` 部分中指定的下一个操作将开始。此外，如果一个操作无法运行，则整个自动化将失败（默认情况下）。可以使用本节所述的 `aws:branch` 自动化操作和运行手册选项来创建执行*条件分支*的自动化。也就是说，您可以创建在评估不同选项后跳转到不同步骤或在某个步骤完成时动态响应更改的自动化。以下是可用于创建动态自动化的选项的列表：
+ **`aws:branch`**：此自动化操作让您能够创建一个动态自动化，该自动化可以在一个步骤中评估多个选项，然后根据评估结果跳转到运行手册中的不同步骤。
+ **`nextStep`**：此选项指定在成功完成一个步骤后，接下来处理自动化中的哪个步骤。
+ **`isEnd`**：此选项在特定步骤结束时停止自动化。该选项的默认值为 false。
+ **`isCritical`**：此选项将一个步骤指定为成功完成自动化的关键步骤。如果具有此分派的步骤失败，自动化会将自动化的最终状态报告为 `Failed`。该选项的默认值为 `true`。
+ **`onFailure`**：此选项指示自动化在失败时是应中止、继续还是转到其他步骤。该选项的默认值为 abort。
下一节介绍 `aws:branch` 自动化操作。有关 `nextStep`、`isEnd`、`isCritical` 和 `onFailure` 选项的更多信息，请参阅 [示例 `aws:branch` 运行手册](#branch-runbook-examples)。
## 使用 `aws:branch` 操作
`aws:branch` 操作提供适用于自动化的大部分动态条件分支选项。如前所述，此操作让自动化能够在一个步骤中评估多个条件，然后根据评估结果跳转到新的步骤。`aws:branch` 操作的功能类似于编程中的 `IF-ELIF-ELSE` 语句。
下面是一个 `aws:branch` 步骤的 YAML 示例：
```
- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
PostProcessing
```
在为步骤指定 `aws:branch` 操作时，请指定自动化必须评估的 `Choices`。自动化可以根据在运行手册的 `Parameters` 部分中指定的参数值来评估 `Choices`。自动化也可以基于上一步的输出来评估 `Choices`。
自动化使用布尔表达式评估每个选择。如果评估确定第一个选择为 `true`，自动化跳转到为该选择指定的步骤。如果评估确定第一个选择为 `false`，自动化程评估下一个选择。如果您的步骤包含三个或更多的 `Choices`，自动化按顺序评估每个选择，直到某个选择的评估结果为 `true`。然后，自动化跳转到为结果为 `true` 的选择指定的步骤。
如果所有 `Choices` 都为 `true`，则工作流程检查该步骤是否包含 `Default` 值。`Default` 值定义当所有选择都为 `true` 时工作流程应跳转到的步骤。如果没有为该步骤指定 `Default` 值，自动化处理文档中的下一个步骤。
以下是 YAML 的 `aws:branch` 步骤，命名为 **chooseOSfromParameter**。此步骤包含两个 `Choices`：(`NextStep: runWindowsCommand`) 和 (`NextStep: runLinuxCommand`)。自动化评估这些 `Choices`，以确定应为适当的操作系统运行哪个命令。每个选择的 `Variable` 都使用 `{{OSName}}`，这是运行手册作者在运行手册的 `Parameters` 部分中定义的参数。
```
mainSteps:
- name: chooseOSfromParameter
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{OSName}}"
StringEquals: Windows
- NextStep: runLinuxCommand
Variable: "{{OSName}}"
StringEquals: Linux
```
以下是 YAML 的 `aws:branch` 步骤，命名为 **chooseOSfromOutput**。此步骤包含两个 `Choices`：(`NextStep: runPowerShellCommand`) 和 (`NextStep: runShellCommand`)。自动化评估这些 `Choices`，以确定应为适当的操作系统运行哪个命令。每个选择的 `Variable` 都使用 `{{GetInstance.platform}}`，这是文档中上一步的输出。此示例还包含一个名为 `Default` 的选项。如果自动化评估两个的结果都为 `Choices`，而且两个选择均为 `true`，自动化跳转到名为 `PostProcessing` 的步骤。
```
mainSteps:
- name: chooseOSfromOutput
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
PostProcessing
```
### 在运行手册中创建 `aws:branch` 步骤
在运行手册中创建 `aws:branch` 步骤时，请定义自动化应对其进行评估的 `Choices` 以确定自动化应跳转到哪个步骤。如前所述，`Choices` 使用布尔表达式进行评估。每个选择都必须定义以下选项：
+ **NextStep**：当指定的选择为 `true` 时，运行手册要处理的下一个步骤。
+ **变量**：指定在运行手册的 `Parameters` 部分中定义的参数的名称（在 `Variables` 部分中定义的参数），或指定上一步的输出对象。
使用以下格式指定变量值。
`Variable: "{{variable name}}"`
使用以下格式指定参数值。
`Variable: "{{parameter name}}"`
使用以下格式指定输出对象变量：
`Variable: "{{previousStepName.outputName}}"`
**注意**
下一节[关于创建输出变量](#branch-action-output)更详细地介绍如何创建输出变量。
+ **Operation**：用于评估选择的标准，例如 `StringEquals: Linux`。`aws:branch` 操作支持以下运算：
**字符串运算**
+ 字符串等于
+ EqualsIgnoreCase
+ StartsWith
+ EndsWith
+ 包含
**数值运算**
+ NumericEquals
+ NumericGreater
+ NumericLesser
+ NumericGreaterOrEquals
+ NumericLesser
+ NumericLesserOrEquals
**布尔运算**
+ BooleanEquals
**重要**
创建运行手册时，系统将验证运行手册中的每个操作。在尝试创建运行手册时，如果某个操作不受支持，系统会返回错误。
+ **Default**：指定当所有 `Choices` 都为 `true` 时自动化应跳转到的回退步骤。
**注意**
如果不想指定 `Default` 值，则可以指定 `isEnd` 选项。如果所有 `Choices` 都为 `true` 并且未指定 `Default` 值，自动化在此步骤结束时停止。
使用以下模板可以帮助您在运行手册中构建 `aws:branch` 步骤：将每个*示例资源占位符*替换为您自己的信息。
------
#### [ YAML ]
```
mainSteps:
- name: step name
action: aws:branch
inputs:
Choices:
- NextStep: step to jump to if evaluation for this choice is true
Variable: "{{parameter name or output from previous step}}"
Operation type: Operation value
- NextStep: step to jump to if evaluation for this choice is true
Variable: "{{parameter name or output from previous step}}"
Operation type: Operation value
Default:
step to jump to if all choices are false
```
------
#### [ JSON ]
```
{
"mainSteps":[
{
"name":"a name for the step",
"action":"aws:branch",
"inputs":{
"Choices":[
{
"NextStep":"step to jump to if evaluation for this choice is true",
"Variable":"{{parameter name or output from previous step}}",
"Operation type":"Operation value"
},
{
"NextStep":"step to jump to if evaluation for this choice is true",
"Variable":"{{parameter name or output from previous step}}",
"Operation type":"Operation value"
}
],
"Default":"step to jump to if all choices are false"
}
}
]
}
```
------
#### 关于创建输出变量
要创建引用上一步输出的 `aws:branch` 选择，您需要标识上一步的名称和输出字段的名称。然后，使用以下格式组合步骤和字段的名称：
`Variable: "{{previousStepName.outputName}}"`
例如，以下示例中的第一个步骤名为 `GetInstance`。然后，在 `outputs` 下，有一个名为 `platform` 的字段。在第二个步骤 (`ChooseOSforCommands`) 中，作者希望将平台字段的输出引用为变量。要创建变量，只需将步骤名称 (GetInstance) 与输出字段名称 (platform) 组合在一起即可创建 `Variable: "{{GetInstance.platform}}"`。
```
mainSteps:
- Name: GetInstance
action: aws:executeAwsApi
inputs:
Service: ssm
Api: DescribeInstanceInformation
Filters:
- Key: InstanceIds
Values: ["{{ InstanceId }}"]
outputs:
- Name: myInstance
Selector: "$.InstanceInformationList[0].InstanceId"
Type: String
- Name: platform
Selector: "$.InstanceInformationList[0].PlatformType"
Type: String
- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
Sleep
```
这是一个示例，展示了从上一步和输出创建 *"Variable": "\$1\$1 describeInstance.Platform \$1\$1"* 的方法。
```
- name: describeInstance
action: aws:executeAwsApi
onFailure: Abort
inputs:
Service: ec2
Api: DescribeInstances
InstanceIds:
- "{{ InstanceId }}"
outputs:
- Name: Platform
Selector: "$.Reservations[0].Instances[0].Platform"
Type: String
nextStep: branchOnInstancePlatform
- name: branchOnInstancePlatform
action: aws:branch
inputs:
Choices:
- NextStep: runEC2RescueForWindows
Variable: "{{ describeInstance.Platform }}"
StringEquals: windows
Default: runEC2RescueForLinux
```
### 示例 `aws:branch` 运行手册
下面是一些使用 `aws:branch` 的示例运行手册。
**示例 1：使用 `aws:branch` 和输出变量基于操作系统类型运行命令**
在此示例的第一步（`GetInstance`）中，运行手册作者使用 `aws:executeAwsApi` 操作来调用 `ssm` `DescribeInstanceInformation` API 操作。作者使用此操作确定实例使用的操作系统的类型。`aws:executeAwsApi` 操作输出实例 ID 和平台类型。
在第二个步骤 (`ChooseOSforCommands`) 中，作者使用了 `aws:branch` 操作和两个 `Choices`：(`NextStep: runPowerShellCommand`) 和 (`NextStep: runShellCommand`)。自动化使用上一步 (`Variable: "{{GetInstance.platform}}"`) 的输出评估实例的操作系统。自动化跳转到指定操作系统的步骤。
```
---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
AutomationAssumeRole:
default: ""
type: String
mainSteps:
- name: GetInstance
action: aws:executeAwsApi
inputs:
Service: ssm
Api: DescribeInstanceInformation
outputs:
- Name: myInstance
Selector: "$.InstanceInformationList[0].InstanceId"
Type: String
- Name: platform
Selector: "$.InstanceInformationList[0].PlatformType"
Type: String
- name: ChooseOSforCommands
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{GetInstance.platform}}"
StringEquals: Linux
Default:
Sleep
- name: runShellCommand
action: aws:runCommand
inputs:
DocumentName: AWS-RunShellScript
InstanceIds:
- "{{GetInstance.myInstance}}"
Parameters:
commands:
- ls
isEnd: true
- name: runPowerShellCommand
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- "{{GetInstance.myInstance}}"
Parameters:
commands:
- ls
isEnd: true
- name: Sleep
action: aws:sleep
inputs:
Duration: PT3S
```
**示例 2：使用 `aws:branch` 和参数变量基于操作系统类型运行命令**
运行手册作者在 `parameters` 部分的运行手册开头定义了几个参数选项。一个参数名为 `OperatingSystemName`。在第一个步骤 (`ChooseOS`) 中，作者使用了 `aws:branch` 操作和两个 `Choices`：(`NextStep: runWindowsCommand`) 和 (`NextStep: runLinuxCommand`)。这些 `Choices` 的变量引用在参数部分 (`Variable: "{{OperatingSystemName}}"`) 中指定的参数选项。当用户运行此自动化时，他们在运行时为 `OperatingSystemName` 指定值。自动化在 `Choices` 评估期间使用运行时参数。自动化基于为 `OperatingSystemName` 指定的运行时参数跳转到指定操作系统的步骤。
```
---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
AutomationAssumeRole:
default: ""
type: String
OperatingSystemName:
type: String
LinuxInstanceId:
type: String
WindowsInstanceId:
type: String
mainSteps:
- name: ChooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{OperatingSystemName}}"
StringEquals: windows
- NextStep: runLinuxCommand
Variable: "{{OperatingSystemName}}"
StringEquals: linux
Default:
Sleep
- name: runLinuxCommand
action: aws:runCommand
inputs:
DocumentName: "AWS-RunShellScript"
InstanceIds:
- "{{LinuxInstanceId}}"
Parameters:
commands:
- ls
isEnd: true
- name: runWindowsCommand
action: aws:runCommand
inputs:
DocumentName: "AWS-RunPowerShellScript"
InstanceIds:
- "{{WindowsInstanceId}}"
Parameters:
commands:
- date
isEnd: true
- name: Sleep
action: aws:sleep
inputs:
Duration: PT3S
```
### 使用运算符创建复杂的分支自动化
您可以在 `aws:branch` 步骤中使用 `And`、`Or` 和 `Not` 运算符来创建复杂的分支自动化。
**“And”运算符**
如果某个选择的多个变量需要为 `true`，可以使用 `And` 运算符。在下面的示例中，第一个选择评估实例是否 `running` 并且使用的是 `Windows` 操作系统。如果这*两个*变量的评估结果都为真，自动化跳转到 `runPowerShellCommand` 步骤。如果一个或多个变量为 `false`，自动化评估第二个选择的变量。
```
mainSteps:
- name: switch2
action: aws:branch
inputs:
Choices:
- And:
- Variable: "{{GetInstance.pingStatus}}"
StringEquals: running
- Variable: "{{GetInstance.platform}}"
StringEquals: Windows
NextStep: runPowerShellCommand
- And:
- Variable: "{{GetInstance.pingStatus}}"
StringEquals: running
- Variable: "{{GetInstance.platform}}"
StringEquals: Linux
NextStep: runShellCommand
Default:
sleep3
```
**“Or”运算符**
如果*某个*选择的多个变量需要为真，可以使用 `Or` 运算符。在下面的示例中，第一个选择评估参数字符串是不是 `Windows` 和 AWS Lambda 步骤的输出是不是真。如果*任意一个*变量的评估结果都为真，自动化跳转到 `RunPowerShellCommand` 步骤。如果两个变量都为假，自动化评估第二个选择的变量。
```
- Or:
- Variable: "{{parameter1}}"
StringEquals: Windows
- Variable: "{{BooleanParam1}}"
BooleanEquals: true
NextStep: RunPowershellCommand
- Or:
- Variable: "{{parameter2}}"
StringEquals: Linux
- Variable: "{{BooleanParam2}}"
BooleanEquals: true
NextStep: RunShellScript
```
**“Not”运算符**
当变量*不*为真时，如果您想要跳转到定义的步骤，则使用 `Not` 运算符。在下面的示例中，第一个选择评估参数字符串是不是 `Not Linux`。如果变量的评估结果不为 Linux，自动化跳转到 `sleep2` 步骤。如果第一个选择的评估结果*为* Linux，自动化评估下一个选择。
```
mainSteps:
- name: switch
action: aws:branch
inputs:
Choices:
- NextStep: sleep2
Not:
Variable: "{{testParam}}"
StringEquals: Linux
- NextStep: sleep1
Variable: "{{testParam}}"
StringEquals: Windows
Default:
sleep3
```
## 如何使用条件选项的示例
本部分包括有关如何使用运行手册中的动态选项的其他示例。本部分中的每个示例均扩展以下运行手册。该运行手册包含两个操作。第一个操作名为 `InstallMsiPackage`。它使用 `aws:runCommand` 操作将应用程序安装到 Windows Server 实例上。第二个操作名为 `TestInstall`。它使用 `aws:invokeLambdaFunction` 操作在成功安装应用程序后测试该应用程序。步骤 1 指定 `onFailure: Abort`。这意味着，如果应用程序未成功安装，自动化会在进入步骤 2 前停止。
**示例 1：包含两个线性操作的运行手册**
```
---
schemaVersion: '0.3'
description: Install MSI package and run validation.
assumeRole: "{{automationAssumeRole}}"
parameters:
automationAssumeRole:
type: String
description: "(Required) Assume role."
packageName:
type: String
description: "(Required) MSI package to be installed."
instanceIds:
type: String
description: "(Required) Comma separated list of instances."
mainSteps:
- name: InstallMsiPackage
action: aws:runCommand
maxAttempts: 2
onFailure: Abort
inputs:
InstanceIds:
- "{{instanceIds}}"
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
- name: TestInstall
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: TestLambdaFunction
...
```
**使用 `onFailure` 选项创建跳转到不同步骤的动态自动化**
下面的示例使用 `onFailure: step:step name`、`nextStep` 和 `isEnd` 选项创建一个动态自动化。在此示例中，如果 `InstallMsiPackage` 操作失败，自动化将跳转到名为 *PostFailure* (`onFailure: step:PostFailure`) 的操作以运行 AWS Lambda 函数，从而在安装失败时执行某个操作。如果安装成功，自动化将跳转到 TestInstall 操作 (`nextStep: TestInstall`)。`TestInstall` 和 `PostFailure` 步骤都使用 `isEnd` 选项 (`isEnd: true`)，以便自动化在任一步骤完成时结束。
**注意**
可以选择在 `mainSteps` 部分的最后一步中使用 `isEnd` 选项。如果最后一个步骤未跳转到其他步骤，自动化会在最后一步中运行操作后停止。
**示例 2：跳转到不同步骤的动态自动化**
```
mainSteps
- name: InstallMsiPackage
action: aws:runCommand
onFailure: step:PostFailure
maxAttempts: 2
inputs:
InstanceIds:
- "{{instanceIds}}"
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestInstall
- name: TestInstall
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: TestLambdaFunction
isEnd: true
- name: PostFailure
action: aws:invokeLambdaFunction
maxAttempts: 1
timeoutSeconds: 500
inputs:
FunctionName: PostFailureRecoveryLambdaFunction
isEnd: true
...
```
**注意**
在处理运行手册之前，系统将验证运行手册不会创建无限循环。如果检测到无限循环，自动化将返回一个错误和一个显示哪些步骤创建循环的循环跟踪。
**创建定义关键步骤的动态自动化**
您可以指定一个对于自动化的整体成功很重要的步骤。如果关键步骤失败，自动化会将自动化状态报告为 `Failed`，即使已成功运行一个或多个步骤也是如此。在以下示例中，用户在 *InstallMsiPackage* 步骤失败 (`onFailure: step:VerifyDependencies`) 时标识 *VerifyDependencies* 步骤。用户指定 `InstallMsiPackage` 步骤为非关键步骤 (`isCritical: false`)。在此示例中，如果应用程序安装失败，自动化处理 `VerifyDependencies` 步骤以确定是否因一个或多个依赖项缺失而导致应用程序安装失败。
**示例 3：定义自动化的关键步骤**
```
---
name: InstallMsiPackage
action: aws:runCommand
onFailure: step:VerifyDependencies
isCritical: false
maxAttempts: 2
inputs:
InstanceIds:
- "{{instanceIds}}"
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- msiexec /i {{packageName}}
nextStep: TestPackage
...
```
# 使用操作输出作为输入
多个自动化操作会返回预定义的输出。您可以使用格式 `{{stepName.outputName}}` 将这些输出作为输入传递到运行手册的后续步骤。您还可以在运行手册中为自动化操作定义自定义输出。让您可以运行脚本，或调用其他 AWS 服务 的 API 操作一次，以便您在后续操作中重复使用这些值作为输入。运行手册中的参数类型是静态的。这意味着参数类型在定义后无法更改。要定义步骤输出，请提供以下字段：
+ 名称：（必需）输出名称，用于在后续步骤中引用输出值。
+ 选择器：（必需）用于确定输出值的 JSONPath 表达式。
+ 类型：（可选）选择器字段返回的值的数据类型。有效的类型值为 `String`、`Integer`、`Boolean`、`StringList`、`StringMap`、`MapList`。默认值为 `String`。
如果输出的值与您指定的数据类型不匹配，自动化会尝试转换该数据类型。例如，如果返回的值是 `Integer`，但指定的 `Type` 是 `String`，则最终输出值为 `String` 值。支持以下类型转换：
+ `String` 值可以转换为 `StringList`、`Integer` 和 `Boolean`。
+ `Integer` 值可以转换为 `String` 和 `StringList`。
+ `Boolean` 值可以转换为 `String` 和 `StringList`。
+ 包含一个元素的 `StringList`、`IntegerList` 或 `BooleanList` 值可以转换为 `String`、`Integer` 或 `Boolean`。
将参数或输出与自动化操作一起使用时，不能在操作的输入中动态更改数据类型。
这份示例运行手册演示了如何定义操作输出，并将该值引用为后续操作的输入。运行手册执行以下操作：
+ 使用 `aws:executeAwsApi` 操作调用 Amazon EC2 DescribeImages API 操作来获取特定 Windows Server 2016 AMI 的名称。它将映像 ID 输出为 `ImageId`。
+ 使用 `aws:executeAwsApi` 操作调用 Amazon EC2 RunInstances API 操作来启动一个实例，它使用上一步中的 `ImageId`。它将实例 ID 输出为 `InstanceId`。
+ 使用 ` aws:waitForAwsResourceProperty` 操作轮询 Amazon EC2 DescribeInstanceStatus API 操作来等待实例进入 `running` 状态。此操作的超时时间为 60 秒。如果实例在轮询 60 秒后未能进入 `running` 状态，则此步骤超时。
+ 使用 `aws:assertAwsResourceProperty` 操作调用 Amazon EC2 `DescribeInstanceStatus` API 操作来断言实例处于 `running` 状态。如果实例状态不为 `running`，则此步骤失败。
```
---
description: Sample runbook using AWS API operations
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
AutomationAssumeRole:
type: String
description: "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf."
default: ''
ImageName:
type: String
description: "(Optional) Image Name to launch EC2 instance with."
default: "Windows_Server-2022-English-Full-Base*"
mainSteps:
- name: getImageId
action: aws:executeAwsApi
inputs:
Service: ec2
Api: DescribeImages
Filters:
- Name: "name"
Values:
- "{{ ImageName }}"
outputs:
- Name: ImageId
Selector: "$.Images[0].ImageId"
Type: "String"
- name: launchOneInstance
action: aws:executeAwsApi
inputs:
Service: ec2
Api: RunInstances
ImageId: "{{ getImageId.ImageId }}"
MaxCount: 1
MinCount: 1
outputs:
- Name: InstanceId
Selector: "$.Instances[0].InstanceId"
Type: "String"
- name: waitUntilInstanceStateRunning
action: aws:waitForAwsResourceProperty
timeoutSeconds: 60
inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
- name: assertInstanceStateRunning
action: aws:assertAwsResourceProperty
inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
outputs:
- "launchOneInstance.InstanceId"
...
```
前面介绍的每个自动化操作都允许您通过指定服务命名空间、API 操作名称、输入参数和输出参数来调用特定的 API 操作。输入由您选择的 API 操作定义。您可以在以下[服务参考](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html)页面的左侧导航栏中选择服务来查看 API 操作（也称为方法）。在要调用的服务的**客户端**部分中选择一种方法。例如，以下页面中列出了 Amazon Relational Database Service (Amazon RDS) 的所有 API 操作（方法）：[Amazon RDS 方法](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html)。
您可以在以下位置查看每个自动化操作的架构：
+ [`aws:assertAwsResourceProperty` - 断言 AWS 资源状态或事件状态](automation-action-assertAwsResourceProperty.md)
+ [`aws:executeAwsApi` - 调用并运行 AWS API 操作](automation-action-executeAwsApi.md)
+ [`aws:waitForAwsResourceProperty` - 等待 AWS 资源属性](automation-action-waitForAwsResourceProperty.md)
架构包括使用每个操作所需字段的描述。
**使用 Selector/PropertySelector 字段**
每个自动化操作都要求您指定一个输出 `Selector`（用于 `aws:executeAwsApi`）或 `PropertySelector`（用于 `aws:assertAwsResourceProperty` 和 `aws:waitForAwsResourceProperty`)。这些字段用于处理 AWS API 操作的 JSON 响应。这些字段使用 JSONPath 语法。
以下是帮助说明这一概念的 `aws:executeAwsAPi` 操作的示例：
```
---
mainSteps:
- name: getImageId
action: aws:executeAwsApi
inputs:
Service: ec2
Api: DescribeImages
Filters:
- Name: "name"
Values:
- "{{ ImageName }}"
outputs:
- Name: ImageId
Selector: "$.Images[0].ImageId"
Type: "String"
...
```
在 `aws:executeAwsApi` 步骤 `getImageId` 中，自动化将调用 `DescribeImages` API 操作并接收来自 `ec2` 的响应。然后，自动化将 `Selector - "$.Images[0].ImageId"` 应用于 API 响应，并将所选值分配给输出 `ImageId` 变量。通过指定 `"{{ getImageId.ImageId }}"`，同一自动化中的其他步骤可以使用 `ImageId` 的值。
以下是帮助说明这一概念的 `aws:waitForAwsResourceProperty` 操作的示例：
```
---
- name: waitUntilInstanceStateRunning
action: aws:waitForAwsResourceProperty
# timeout is strongly encouraged for action - aws:waitForAwsResourceProperty
timeoutSeconds: 60
inputs:
Service: ec2
Api: DescribeInstanceStatus
InstanceIds:
- "{{ launchOneInstance.InstanceId }}"
PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
DesiredValues:
- running
...
```
在 `aws:waitForAwsResourceProperty` 步骤 `waitUntilInstanceStateRunning` 中，自动化将调用 `DescribeInstanceStatus` API 操作并接收来自 `ec2` 的响应。然后，自动化将 `PropertySelector - "$.InstanceStatuses[0].InstanceState.Name"` 应用于响应，并检查指定的返回值是否与 `DesiredValues` 列表中的值匹配（在本例中为 `running`）。此步骤重复这一过程，直到响应返回 `running` 实例状态。
## 在运行手册中使用 JSONPath
JSONPath 表达式是以“\$1”开头的字符串。用于选择 JSON 元素中的一个或多个组件。下面的列表包含有关 Systems Manager 自动化支持的 JSONPath 运算符的信息：
+ **点表示的子字段 (.)**：用于 JSON 对象。此运算符选择特定键的值。
+ **深层扫描 (..)**：用于 JSON 元素。此运算符逐级扫描 JSON 元素，并使用特定键选择值列表。此运算符的返回类型始终为 JSON 数组。在自动化步骤输出类型上下文中，运算符可以是 StringList 或 MapList。
+ **数组索引 ([ ])**：用于 JSON 数组。此运算符获取特定索引的值。
+ **筛选条件 ([?(*expression*)])**：与 JSON 数组一起使用。此运算符筛选条件 JSON 数组值与筛选条件表达式中定义的标准相匹配。筛选条件表达式只能使用以下运算符：==、\$1=、>、<、>= 或 <=。不支持将多个筛选条件表达式与 AND (&&) 或 OR (\$1\$1) 组合使用。此运算符的返回类型始终为 JSON 数组。
为了更好地理解 JSONPath 运算符，请查看以下 ec2 `DescribeInstances` API 操作的 JSON 响应。此响应下面提供了几个示例，它们说明通过向 `DescribeInstances` API 操作响应应用不同的 JSONPath 表达式获取的不同结果。
```
{
"NextToken": "abcdefg",
"Reservations": [
{
"OwnerId": "123456789012",
"ReservationId": "r-abcd12345678910",
"Instances": [
{
"ImageId": "ami-12345678",
"BlockDeviceMappings": [
{
"Ebs": {
"DeleteOnTermination": true,
"Status": "attached",
"VolumeId": "vol-000000000000"
},
"DeviceName": "/dev/xvda"
}
],
"State": {
"Code": 16,
"Name": "running"
}
}
],
"Groups": []
},
{
"OwnerId": "123456789012",
"ReservationId": "r-12345678910abcd",
"Instances": [
{
"ImageId": "ami-12345678",
"BlockDeviceMappings": [
{
"Ebs": {
"DeleteOnTermination": true,
"Status": "attached",
"VolumeId": "vol-111111111111"
},
"DeviceName": "/dev/xvda"
}
],
"State": {
"Code": 80,
"Name": "stopped"
}
}
],
"Groups": []
}
]
}
```
**JSONPath 示例 1：从 JSON 响应获取特定的 String**
```
JSONPath:
$.Reservations[0].Instances[0].ImageId
Returns:
"ami-12345678"
Type: String
```
**JSONPath 示例 2：从 JSON 响应获取特定的 Boolean**
```
JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination
Returns:
true
Type: Boolean
```
**JSONPath 示例 3：从 JSON 响应获取特定的 Integer**
```
JSONPath:
$.Reservations[0].Instances[0].State.Code
Returns:
16
Type: Integer
```
**JSONPath 示例 4：深层扫描 JSON 响应，然后以 StringList 的形式获取 VolumeId 的所有值**
```
JSONPath:
$.Reservations..BlockDeviceMappings..VolumeId
Returns:
[
"vol-000000000000",
"vol-111111111111"
]
Type: StringList
```
**JSONPath 示例 5：以 StringMap 的形式获取特定的 BlockDeviceMappings 对象**
```
JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0]
Returns:
{
"Ebs" : {
"DeleteOnTermination" : true,
"Status" : "attached",
"VolumeId" : "vol-000000000000"
},
"DeviceName" : "/dev/xvda"
}
Type: StringMap
```
**JSONPath 示例 6：深层扫描 JSON 响应，然后以 MapList 的形式获取所有 State 对象**
```
JSONPath:
$.Reservations..Instances..State
Returns:
[
{
"Code" : 16,
"Name" : "running"
},
{
"Code" : 80,
"Name" : "stopped"
}
]
Type: MapList
```
**JSONPath 示例 7：筛选处于 `running` 状态的实例**
```
JSONPath:
$.Reservations..Instances[?(@.State.Name == 'running')]
Returns:
[
{
"ImageId": "ami-12345678",
"BlockDeviceMappings": [
{
"Ebs": {
"DeleteOnTermination": true,
"Status": "attached",
"VolumeId": "vol-000000000000"
},
"DeviceName": "/dev/xvda"
}
],
"State": {
"Code": 16,
"Name": "running"
}
}
]
Type: MapList
```
**JSONPath 示例 8：返回未处于 `running` 状态实例的 `ImageId`**
```
JSONPath:
$.Reservations..Instances[?(@.State.Name != 'running')].ImageId
Returns:
[
"ami-12345678"
]
Type: StringList | String
```
# 为 Automation 创建 Webhook 集成
要在自动化期间使用 Webhooks 发送消息，请创建集成。可以在自动化过程中使用您的运行手册中的 `aws:invokeWebhook` 操作调用集成。如果尚未创建 Webhook，请参阅 [为集成创建 Webhooks](#creating-webhooks)。要了解有关 `aws:invokeWebhook` 操作的更多信息，请参阅 [`aws:invokeWebhook` – 调用 Automation Webhook 集成](invoke-webhook.md)。
如以下程序所示，您可以使用 Systems Manager Automation 控制台或您的首选命令行工具来创建集成。
## 创建集成（控制台）
**要为 Automation 创建集成（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **自动化**。
1. 请选择 **Integrations**（集成）选项卡。
1. 请选择 **Add integration**（添加集成），然后选择 **Webhook**。
1. 请输入要为集成包括的所需值和任何可选值。
1. 请选择 **Add**（添加）来创建集成。
## 创建集成（命令行）
要使用命令行工具创建集成，您必须为集成创建所需的 `SecureString` 参数。Automation 使用 Parameter Store（Systems Manager 中的一项工具）中的预留命名空间来存储有关集成的信息。如果您使用 AWS 管理控制台 创建集成，Automation 会为您处理此过程。在命名空间之后，您必须指定要创建的集成类型，然后指定集成的名称。目前，Automation 支持 `webhook` 类型集成。
`webhook` 类型集成支持的字段如下：
+ 说明
+ headers
+ payload
+ URL
**开始前的准备工作**
安装并配置 AWS Command Line Interface (AWS CLI) 或 AWS Tools for PowerShell（如果尚未这样做）。有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)以及[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
**要为 Automation 创建集成（命令行）**
+ 运行下列命令以为集成创建所需的 `SecureString` 参数。将每个*示例资源占位符*替换为您自己的信息。`/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/` 命名空间在 Parameter Store 中为集成预留。参数的名称必须使用此命名空间，后跟集成的名称。例如 `/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration`。
------
#### [ Linux & macOS ]
```
aws ssm put-parameter \
--name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" \
--type "SecureString" \
--data-type "aws:ssm:integration" \
--value '{"description": "My first webhook integration for Automation.", "url": "myWebHookURL"}'
```
------
#### [ Windows ]
```
aws ssm put-parameter ^
--name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" ^
--type "SecureString" ^
--data-type "aws:ssm:integration" ^
--value "{\"description\":\"My first webhook integration for Automation.\",\"url\":\"myWebHookURL\"}"
```
------
#### [ PowerShell ]
```
Write-SSMParameter `
-Name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" `
-Type "SecureString"
-DataType "aws:ssm:integration"
-Value '{"description": "My first webhook integration for Automation.", "url": "myWebHookURL"}'
```
------
## 为集成创建 Webhooks
在使用您的提供商创建 Webhooks 时，请注意以下几点：
+ 协议必须是 HTTPS。
+ 支持自定义请求标头。
+ 可以指定默认的请求正文。
+ 当使用 `aws:invokeWebhook` 操作调用集成时，可以覆盖默认的请求正文。
# 处理运行手册中的超时
`timeoutSeconds` 属性由所有自动化操作共享。您可以使用此属性指定操作的执行超时值。此外，您还可以更改操作超时如何影响自动化和整体执行状态。另外，您可以通过定义操作的 `onFailure` 和 `isCritical` 共享属性来完成此操作。
例如，根据您的使用案例，您可能希望自动化继续执行其他操作，并且在操作超时的情况下不影响自动化的整体状态。在此示例中，您可以使用 `timeoutSeconds` 属性指定操作超时之前等待的时间长度。然后，您可以指定存在超时的情况下自动化应转到的操作（即步骤）。使用 `onFailure` 属性的格式 `step:step name` 指定值，而不是指定默认值 `Abort`。默认情况下，如果操作超时，在自动化执行状态将为 `Timed Out`。要防止超时影响自动化执行状态，请为 `false` 属性指定 `isCritical`。
以下示例演示如何为此情况中描述的操作定义共享属性。
------
#### [ YAML ]
```
- name: verifyImageAvailability
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 600
isCritical: false
onFailure: 'step:getCurrentImageState'
inputs:
Service: ec2
Api: DescribeImages
ImageIds:
- '{{ createImage.newImageId }}'
PropertySelector: '$.Images[0].State'
DesiredValues:
- available
nextStep: copyImage
```
------
#### [ JSON ]
```
{
"name": "verifyImageAvailability",
"action": "aws:waitForAwsResourceProperty",
"timeoutSeconds": 600,
"isCritical": false,
"onFailure": "step:getCurrentImageState",
"inputs": {
"Service": "ec2",
"Api": "DescribeImages",
"ImageIds": [
"{{ createImage.newImageId }}"
],
"PropertySelector": "$.Images[0].State",
"DesiredValues": [
"available"
]
},
"nextStep": "copyImage"
}
```
------
有关所有自动化操作共享的属性的更多信息，请参阅 [所有操作共享的属性](automation-actions.md#automation-common)。
# Systems Manager 自动化运行手册参考
为了帮助您快速入门，AWS Systems Manager 提供了预定义运行手册。这些运行手册由 Amazon Web Services、AWS 支持 和 AWS Config 维护。运行手册参考描述了 Systems Manager、支持 和 AWS Config 提供的每个预定义运行手册。有关更多信息，请参阅 [Systems Manager 自动化运行手册参考](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide)。
# 教程
以下教程可帮助您使用 AWS Systems Manager Automation 来解决常见应用场景的问题。这些教程演示了如何将自己的运行手册、Automation 提供的预定义运行手册以及别的 Systems Manager 工具与其他 AWS 服务一起使用。
**Contents**
+ [更新 AMIs](automation-tutorial-update-ami.md)
+ [更新 Linux AMI](automation-tutorial-update-patch-linux-ami.md)
+ [更新 Linux AMI（AWS CLI）](automation-tutorial-update-ami.md#update-patch-linux-ami-cli)
+ [更新 Windows Server AMI](automation-tutorial-update-patch-windows-ami.md)
+ [使用 Automation、AWS Lambda 和 Parameter Store 来更新黄金 AMI](automation-tutorial-update-patch-golden-ami.md)
+ [任务 1：在 Systems Manager Parameter Store 中创建一个参数](automation-tutorial-update-patch-golden-ami.md#create-parameter-ami)
+ [任务 2：为 AWS Lambda 创建 IAM 角色](automation-tutorial-update-patch-golden-ami.md#create-lambda-role)
+ [任务 3：创建 AWS Lambda 函数](automation-tutorial-update-patch-golden-ami.md#create-lambda-function)
+ [任务 4：创建运行手册并修补 AMI](automation-tutorial-update-patch-golden-ami.md#create-custom-ami-update-runbook)
+ [使用 Automation 和 Jenkins 更新 AMIs](automation-tutorial-update-patch-ami-jenkins-integration.md)
+ [更新自动扩缩组的 AMIs](automation-tutorial-update-patch-windows-ami-autoscaling.md)
+ [创建 **PatchAMIAndUpdateASG** 运行手册](automation-tutorial-update-patch-windows-ami-autoscaling.md#create-autoscaling-update-runbook)
+ [使用 AWS 支持 自助服务运行手册](automation-tutorial-support-runbooks.md)
+ [在无法访问的实例上运行 EC2Rescue 工具](automation-ec2rescue.md)
+ [工作原理](automation-ec2rescue.md#automation-ec2rescue-how)
+ [开始前的准备工作](automation-ec2rescue.md#automation-ec2rescue-begin)
+ [向 `AWSSupport-EC2Rescue` 授予在您的实例上执行操作的权限](automation-ec2rescue.md#automation-ec2rescue-access)
+ [使用 IAM policy 授予权限](automation-ec2rescue.md#automation-ec2rescue-access-iam)
+ [使用 CloudFormation 模板授予权限](automation-ec2rescue.md#automation-ec2rescue-access-cfn)
+ [运行自动化](automation-ec2rescue.md#automation-ec2rescue-executing)
+ [在 EC2 实例上重置密码和 SSH 密钥](automation-ec2reset.md)
+ [工作原理](automation-ec2reset.md#automation-ec2reset-how)
+ [开始前的准备工作](automation-ec2reset.md#automation-ec2reset-begin)
+ [向 AWSSupport-EC2Rescue 授予在您的实例上执行操作的权限](automation-ec2reset.md#automation-ec2reset-access)
+ [使用 IAM policy 授予权限](automation-ec2reset.md#automation-ec2reset-access-iam)
+ [使用 CloudFormation 模板授予权限](automation-ec2reset.md#automation-ec2reset-access-cfn)
+ [运行自动化](automation-ec2reset.md#automation-ec2reset-executing)
+ [使用输入变压器将数据传递到 Automation](automation-tutorial-eventbridge-input-transformers.md)
# 更新 AMIs
以下教程说明了如何更新 Amazon Machine Image（AMIs）以包含最新补丁。
**Topics**
+ [更新 Linux AMI](automation-tutorial-update-patch-linux-ami.md)
+ [更新 Linux AMI（AWS CLI）](#update-patch-linux-ami-cli)
+ [更新 Windows Server AMI](automation-tutorial-update-patch-windows-ami.md)
+ [使用 Automation、AWS Lambda 和 Parameter Store 来更新黄金 AMI](automation-tutorial-update-patch-golden-ami.md)
+ [使用 Automation 和 Jenkins 更新 AMIs](automation-tutorial-update-patch-ami-jenkins-integration.md)
+ [更新自动扩缩组的 AMIs](automation-tutorial-update-patch-windows-ami-autoscaling.md)
# 更新 Linux AMI
本 Systems Manager Automation 演练向您展示了如何使用控制台或 AWS CLI 和 `AWS-UpdateLinuxAmi` 运行手册，使用您指定的最新软件包补丁更新Linux AMI。Automation 是 AWS Systems Manager 中的一项工具。`AWS-UpdateLinuxAmi` 运行手册也能自动安装其他具体站点相关的软件包和配置。您可以使用该演练更新各种 Linux 分发版，包括 Ubuntu Server、Red Hat Enterprise Linux（RHEL）或 Amazon Linux AMIs。有关支持的 Linux 版本的完整列表，请参阅 [Patch Manager 先决条件](patch-manager-prerequisites.md)。
使用 `AWS-UpdateLinuxAmi` 运行手册可以自动完成映像维护任务，而无需使用 JSON 或 YAML 编写运行手册。您可以使用 `AWS-UpdateLinuxAmi` 运行手册执行以下类型的任务。
+ 在 Amazon Linux、Red Hat Enterprise Linux 或 Ubuntu Server Amazon Machine Image（AMI）上升级所有分发版本程序包和 Amazon 软件。这是默认运行手册行为。
+ 在现有映像上安装 AWS Systems Manager SSM Agent 可启用 Systems Manager 的各项工具，例如使用 AWS Systems Manager Run Command 执行远程命令，或者使用 Inventory 收集软件清单。
+ 安装其他软件包。
**开始前的准备工作**
在您开始使用运行手册之前，请先为自动化配置角色和 EventBridge（后者可选）。有关更多信息，请参阅 [设置自动化](automation-setup.md)。此演练还要求您指定 AWS Identity and Access Management (IAM) 实例配置文件的名称。有关创建 IAM 实例配置文件的更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
`AWS-UpdateLinuxAmi` 运行手册接受以下输入参数。
****
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| SourceAmiId | 字符串 | （必需）源 AMI ID。 |
| IamInstanceProfileName | 字符串 | （必需）您在[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)中创建的 IAM 实例配置文件角色的名称。实例配置文件角色为自动化提供在您实例上执行操作的权限，例如运行命令或启动和停止服务。运行手册仅使用实例配置文件角色的名称。如果您指定 Amazon Resource Name (ARN)，则自动化会失败。 |
| AutomationAssumeRole | 字符串 | （必需）您在 [设置自动化](automation-setup.md) 中创建的 IAM 服务角色的名称。服务角色（也称为担任角色）为自动化提供权限，用于担任您的 IAM 角色和代表您执行操作。例如，在运行手册中运行 `aws:createImage` 操作时，服务角色允许自动化创建新的 AMI。对于此参数，必须指定完整的 ARN。 |
| TargetAmiName | 字符串 | （可选）新 AMI 在创建之后的名称。默认名称是系统生成的字符串，其中包括源 AMI ID 以及创建时间和日期。 |
| InstanceType | 字符串 | (可选) 启动作为工作区主机的实例的类型。实例类型因区域而异。默认类型为 t2.micro。 |
| PreUpdateScript | 字符串 | (可选) 在应用更新前要运行的脚本的 URL。默认值 (\$1"none\$1") 不运行脚本。 |
| PostUpdateScript | 字符串 | (可选) 在应用软件包更新后要运行的脚本的 URL。默认值 (\$1"none\$1") 不运行脚本。 |
| IncludePackages | 字符串 | (可选) 仅更新这些指定的软件包。默认值 (\$1"all\$1") 将应用所有可用的更新。 |
| ExcludePackages | 字符串 | (可选) 在所有情况下从更新中排除的软件包的名称。默认值 (\$1"none\$1") 不排除任何软件包。 |
**自动化步骤**
`AWS-UpdateLinuxAmi` 运行手册默认情况下包括以下自动化操作。
**步骤 1：launchInstance（`aws:runInstances` 操作） **
此步骤使用 Amazon Elastic Compute Cloud (Amazon EC2) 用户数据和 IAM 实例配置文件角色启动实例。用户数据根据操作系统安装相应的 SSM Agent。安装 SSM Agent 后，即可使用 Systems Manager 工具，例如 Run Command、State Manager和 Inventory。
**步骤 2：updateOSSoftware（`aws:runCommand`操作） **
此步骤在已启动实例上运行以下命令：
+ 从 Amazon S3 下载更新脚本。
+ 运行可选的更新前脚本。
+ 更新分发软件包和 Amazon 软件。
+ 运行可选的更新后脚本。
执行日志存储在 /tmp 文件夹中，供用户以后查看。
如果您希望升级特定软件包集，则可以使用 `IncludePackages` 参数提供列表。在提供时，系统仅尝试更新这些软件包及其依赖项。不执行任何其他更新。默认情况下，如果未指定*包含* 软件包，则程序将更新所有可用软件包。
如果要在升级中排除特定软件包集，则可以向 `ExcludePackages` 参数提供列表。如果提供，这些软件包保持其当前版本，与任何其他指定的选项无关。默认情况下，在未指定任何*排除*软件包时，将不排除软件包。
**步骤 3：stopInstance（`aws:changeInstanceState` 操作）**
此步骤停止已更新实例。
**步骤 4：createImage（`aws:createImage` 操作） **
此步骤创建一个新 AMI，带有可将其链接到源 ID 和创建时间的描述性名称。例如：“EC2 自动化在 \$1\$1global:DATE\$1TIME\$1\$1 从 \$1\$1SourceAmiId\$1\$1 生成了 AMI”，其中 DATE\$1TIME 和 SourceID 表示自动化变量。
**步骤 5：terminateInstance（`aws:changeInstanceState` 操作） **
此步骤通过终止正在运行的实例来清除执行过程。
**Output**
自动化返回新的 AMI ID 作为输出。
**注意**
默认情况下，当自动化运行 `AWS-UpdateLinuxAmi` 运行手册时，系统会在默认 VPC (172.30.0.0/16) 中创建一个临时实例。如果您删除了默认 VPC，会收到以下错误：
`VPC not defined 400`
要解决此问题，您必须复制 `AWS-UpdateLinuxAmi` 运行手册并指定子网 ID。有关更多信息，请参阅 [VPC not defined 400](automation-troubleshooting.md#automation-trbl-common-vpc)。
**使用自动化创建经过修补的 AMI (AWS Systems Manager)**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **自动化**。
1. 选择**执行自动化**。
1. 在**自动化文档**列表中，选择 `AWS-UpdateLinuxAmi`。
1. 在**文档详细信息**部分，验证**文档版本**是否设置为**运行时的默认版本**。
1. 选择**下一步**。
1. 在**执行模式**部分中，选择**简单执行**。
1. 在**输入参数**部分，输入在**开始前的准备工作**部分收集的信息。
1. 选择**执行**。控制台将显示自动化执行的状态。
在自动化完成后，请从更新后的 AMI 启动测试实例以验证更改。
**注意**
如果自动化有任何步骤失败，**自动化执行**页面上会列出有关失败的信息。自动化设计为在成功完成所有任务后终止临时实例。如果步骤失败，系统可能不会终止实例。因此，如果某个步骤失败，请手动终止临时实例。
## 更新 Linux AMI（AWS CLI）
此 AWS Systems Manager 自动化演练介绍如何使用 AWS Command Line Interface (AWS CLI) 和 Systems Manager `AWS-UpdateLinuxAmi` 运行手册通过指定的最新版本软件包自动修补 Linux Amazon Machine Image (AMI)。Automation 是 AWS Systems Manager 中的一项工具。`AWS-UpdateLinuxAmi` 运行手册也能自动安装其他具体站点相关的软件包和配置。您可以使用该演练更新各种 Linux 分发版，包括 Ubuntu Server、Red Hat Enterprise Linux（RHEL）或 Amazon Linux AMIs。有关支持的 Linux 版本的完整列表，请参阅 [Patch Manager 先决条件](patch-manager-prerequisites.md)。
使用 `AWS-UpdateLinuxAmi` 运行手册可以自动完成映像维护任务，而无需使用 JSON 或 YAML 编写运行手册。您可以使用 `AWS-UpdateLinuxAmi` 运行手册执行以下类型的任务。
+ 在 Amazon Linux、RHEL 或 Ubuntu Server Amazon Machine Image（AMI）上升级所有分发版本程序包和 Amazon 软件。这是默认运行手册行为。
+ 在现有映像上安装 AWS Systems Manager SSM Agent 以启用 Systems Manager 功能，例如使用 AWS Systems Manager Run Command 的远程命令执行，或者使用 Inventory 的软件清单收集。
+ 安装其他软件包。
**开始前的准备工作**
在您开始使用运行手册之前，请先为自动化配置角色和 EventBridge（后者可选）。有关更多信息，请参阅 [设置自动化](automation-setup.md)。此演练还要求您指定 AWS Identity and Access Management (IAM) 实例配置文件的名称。有关创建 IAM 实例配置文件的更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
`AWS-UpdateLinuxAmi` 运行手册接受以下输入参数。
****
| 参数 | 类型 | 描述 |
| --- | --- | --- |
| SourceAmiId | 字符串 | （必需）源 AMI ID。您可以使用 AWS Systems Manager Parameter Store *公有*参数自动引用最新的 Linux Amazon EC2 AMI ID。有关更多信息，请参阅[使用 AWS Systems Manager Parameter Store 查询最新 Amazon Linux AMI ID](https://aws.amazon.com/blogs/compute/query-for-the-latest-amazon-linux-ami-ids-using-aws-systems-manager-parameter-store/)。 |
| IamInstanceProfileName | 字符串 | （必需）您在[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)中创建的 IAM 实例配置文件角色的名称。实例配置文件角色为自动化提供在您实例上执行操作的权限，例如运行命令或启动和停止服务。运行手册仅使用实例配置文件角色的名称。 |
| AutomationAssumeRole | 字符串 | （必需）您在 [设置自动化](automation-setup.md) 中创建的 IAM 服务角色的名称。服务角色（也称为担任角色）为自动化提供权限，用于担任您的 IAM 角色和代表您执行操作。例如，在运行手册中运行 `aws:createImage` 操作时，服务角色允许自动化创建新的 AMI。对于此参数，必须指定完整的 ARN。 |
| TargetAmiName | 字符串 | （可选）新 AMI 在创建之后的名称。默认名称是系统生成的字符串，其中包括源 AMI ID 以及创建时间和日期。 |
| InstanceType | 字符串 | (可选) 启动作为工作区主机的实例的类型。实例类型因区域而异。默认类型为 t2.micro。 |
| PreUpdateScript | 字符串 | (可选) 在应用更新前要运行的脚本的 URL。默认值 (\$1"none\$1") 不运行脚本。 |
| PostUpdateScript | 字符串 | (可选) 在应用软件包更新后要运行的脚本的 URL。默认值 (\$1"none\$1") 不运行脚本。 |
| IncludePackages | 字符串 | (可选) 仅更新这些指定的软件包。默认值 (\$1"all\$1") 将应用所有可用的更新。 |
| ExcludePackages | 字符串 | (可选) 在所有情况下从更新中排除的软件包的名称。默认值 (\$1"none\$1") 不排除任何软件包。 |
**自动化步骤**
默认情况下，`AWS-UpdateLinuxAmi` 运行手册包括以下步骤。
**步骤 1：launchInstance（`aws:runInstances` 操作） **
此步骤使用 Amazon Elastic Compute Cloud (Amazon EC2) 用户数据和 IAM 实例配置文件角色启动实例。用户数据根据操作系统安装相应的 SSM Agent。安装 SSM Agent 后，即可使用 Systems Manager 工具，例如 Run Command、State Manager和 Inventory。
**步骤 2：updateOSSoftware（`aws:runCommand`操作） **
此步骤在已启动实例上运行以下命令：
+ 从 Amazon Simple Storage Service (Amazon S3) 下载更新脚本。
+ 运行可选的更新前脚本。
+ 更新分发软件包和 Amazon 软件。
+ 运行可选的更新后脚本。
执行日志存储在 /tmp 文件夹中，供用户以后查看。
如果您希望升级特定软件包集，则可以使用 `IncludePackages` 参数提供列表。在提供时，系统仅尝试更新这些软件包及其依赖项。不执行任何其他更新。默认情况下，如果未指定*包含* 软件包，则程序将更新所有可用软件包。
如果要在升级中排除特定软件包集，则可以向 `ExcludePackages` 参数提供列表。如果提供，这些软件包保持其当前版本，与任何其他指定的选项无关。默认情况下，在未指定任何*排除*软件包时，将不排除软件包。
**步骤 3：stopInstance（`aws:changeInstanceState` 操作）**
此步骤停止已更新实例。
**步骤 4：createImage（`aws:createImage` 操作） **
此步骤创建一个新 AMI，带有可将其链接到源 ID 和创建时间的描述性名称。例如：“EC2 自动化在 \$1\$1global:DATE\$1TIME\$1\$1 从 \$1\$1SourceAmiId\$1\$1 生成了 AMI”，其中 DATE\$1TIME 和 SourceID 表示自动化变量。
**步骤 5：terminateInstance（`aws:changeInstanceState` 操作） **
此步骤通过终止正在运行的实例来清除执行过程。
**输出**
自动化返回新的 AMI ID 作为输出。
**注意**
默认情况下，当自动化运行 `AWS-UpdateLinuxAmi` 运行手册时，系统会在默认 VPC (172.30.0.0/16) 中创建一个临时实例。如果您删除了默认 VPC，会收到以下错误：
`VPC not defined 400`
要解决此问题，您必须复制 `AWS-UpdateLinuxAmi` 运行手册并指定子网 ID。有关更多信息，请参阅 [VPC not defined 400](automation-troubleshooting.md#automation-trbl-common-vpc)。
**使用自动化创建经过修补的 AMI**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令来运行 `AWS-UpdateLinuxAmi` 运行手册。将每个*示例资源占位符*替换为您自己的信息。
```
aws ssm start-automation-execution \
--document-name "AWS-UpdateLinuxAmi" \
--parameters \
SourceAmiId=AMI ID, \
IamInstanceProfileName=IAM instance profile, \
AutomationAssumeRole='arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole'
```
该命令将会返回执行 ID。请将该 ID 复制到剪贴板。您将使用该 ID 查看自动化的状态。
```
{
"AutomationExecutionId": "automation execution ID"
}
```
1. 要使用 AWS CLI 查看自动化，请运行以下命令：
```
aws ssm describe-automation-executions
```
1. 运行以下命令以查看有关运行手册进程的详细信息。将 *automation execution ID* 替换为您自己的信息。
```
aws ssm get-automation-execution --automation-execution-id automation execution ID
```
更新过程可能需要 30 分钟或者更久。
**注意**
您也可以在控制台中监控自动化的状态。在列表中，选择您刚才运行的自动化，然后选择**步骤**选项卡。该选项卡将显示自动化操作的状态。
在自动化完成后，请从更新后的 AMI 启动测试实例以验证更改。
**注意**
如果自动化有任何步骤失败，**自动化执行**页面上会列出有关失败的信息。自动化设计为在成功完成所有任务后终止临时实例。如果步骤失败，系统可能不会终止实例。因此，如果某个步骤失败，请手动终止临时实例。
# 更新 Windows Server AMI
使用 `AWS-UpdateWindowsAmi` 运行手册可以在 Amazon Windows Amazon Machine Image (AMI) 上自动完成映像维护任务，而无需使用 JSON 或 YAML 编写工作流程。本运行手册在 Windows Server 2008 R2 或更高版本中受支持。您可以使用 `AWS-UpdateWindowsAmi` 运行手册执行以下类型的任务。
+ 安装所有 Windows 更新并升级 Amazon 软件 (默认行为)。
+ 安装特定 Windows 更新并升级 Amazon 软件。
+ 使用您的脚本自定义 AMI。
**开始前的准备工作**
在开始使用运行手册之前，[为自动化配置角色](automation-setup-iam.md)以添加 `iam:PassRole` 策略，此策略引用要授予其访问权限的实例配置文件的 ARN。也可选择为 Automation（AWS Systems Manager 中的一项工具）配置 Amazon EventBridge。有关更多信息，请参阅 [设置自动化](automation-setup.md)。此演练还要求您指定 AWS Identity and Access Management (IAM) 实例配置文件的名称。有关创建 IAM 实例配置文件的更多信息，请参阅[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)。
**注意**
AWS Systems Manager SSM Agent 的更新通常会在不同时间向不同区域推广。自定义或更新 AMI 时，请仅使用为您工作所在的区域发布的源 AMI。这将确保您使用该区域发布的最新 SSM Agent并避免兼容性问题。
`AWS-UpdateWindowsAmi` 运行手册接受以下输入参数。
****
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| SourceAmiId | 字符串 | （必需）源 AMI ID。您可以使用 Systems Manager Parameter Store *公有*参数自动引用最新的 Windows Server AMI ID。有关更多信息，请参阅[使用 AWS Systems ManagerParameter Store 查询最新的 Windows AMI ID](https://aws.amazon.com/blogs/mt/query-for-the-latest-windows-ami-using-systems-manager-parameter-store/)。 |
| SubnetId | 字符串 | （可选）要在其中启动临时实例的子网。如果您已删除默认 VPC，则必须为此参数指定值。 |
| IamInstanceProfileName | 字符串 | （必需）您在[配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)中创建的 IAM 实例配置文件角色的名称。实例配置文件角色为自动化提供在您实例上执行操作的权限，例如运行命令或启动和停止服务。运行手册仅使用实例配置文件角色的名称。 |
| AutomationAssumeRole | 字符串 | （必需）您在 [设置自动化](automation-setup.md) 中创建的 IAM 服务角色的名称。服务角色（也称为担任角色）为自动化提供权限，用于担任您的 IAM 角色和代表您执行操作。例如，在运行手册中运行 `aws:createImage` 操作时，服务角色允许自动化创建新的 AMI。对于此参数，必须指定完整的 ARN。 |
| TargetAmiName | 字符串 | （可选）新 AMI 在创建之后的名称。默认名称是系统生成的字符串，其中包括源 AMI ID 以及创建时间和日期。 |
| InstanceType | 字符串 | (可选) 启动作为工作区主机的实例的类型。实例类型因区域而异。默认类型为 t2.medium。 |
| PreUpdateScript | 字符串 | (可选) 要在更新 AMI 之前运行的脚本。在运行手册中或在运行时输入脚本作为参数。 |
| PostUpdateScript | 字符串 | （可选）要在更新 AMI 之后运行的脚本。在运行手册中或在运行时输入脚本作为参数。 |
| IncludeKbs | 字符串 | (可选) 指定一个或多个要包括的 Microsoft 知识库 (KB) 文章 ID。可以使用逗号分隔值安装多个 ID。有效格式：KB9876543 或 9876543。 |
| ExcludeKbs | 字符串 | (可选) 指定一个或多个要排除的 Microsoft 知识库 (KB) 文章 ID。可以使用逗号分隔值排除多个 ID。有效格式：KB9876543 或 9876543。 |
| 类别 | 字符串 | (可选) 指定一个或多个更新类别。可以使用逗号分隔值筛选类别。选项：关键更新、安全更新、定义更新、Update Rollup、Service Pack、工具、更新或驱动程序。有效格式包括单个条目，例如：关键更新。或者，可以指定逗号分隔列表：关键更新,安全更新,定义更新。 |
| SeverityLevels | 字符串 | (可选) 指定一个或多个与更新关联的 MSRC 严重性级别。可以使用逗号分隔值筛选严重性级别。选项：关键、重要、低、中或未指定。有效格式包括单个条目，例如：关键。或者，可以指定逗号分隔列表：关键,重要,低。 |
**自动化步骤**
默认情况下，`AWS-UpdateWindowsAmi` 运行手册包括以下步骤。
**步骤 1：launchInstance（`aws:runInstances` 操作）**
此步骤以从指定的 `SourceAmiID` 启动一个具有 IAM 实例配置文件角色的实例。
**步骤 2：runPreUpdateScript（`aws:runCommand` 操作）**
此步骤可让您以字符串形式指定一个在安装更新前运行的脚本。
**步骤 3：更新 EC2Config（`aws:runCommand` 操作）**
此步骤使用 `AWS-InstallPowerShellModule` 运行手册下载 AWS 共有 PowerShell 模块。Systems Manager 使用 SHA-256 哈希验证模块的完整性。然后，Systems Manager 将检查操作系统，以确定是更新 EC2Config 还是 EC2Launch。EC2Config 通过 Windows Server 2012 R2 在 Windows Server 2008 R2 上运行。EC2Launch 在 Windows Server 2016 上运行。
**步骤 4：updateSSMAgent（`aws:runCommand`操作）**
此步骤通过使用 `AWS-UpdateSSMAgent` 运行手册更新 SSM Agent。
**步骤 5：updateAWSPVDriver（`aws:runCommand`操作）**
此步骤通过使用 `AWS-ConfigureAWSPackage` 运行手册更新 AWS PV 驱动程序。
**步骤 6：updateAwsEnaNetworkDriver（`aws:runCommand`操作）**
此步骤通过使用 `AWS-ConfigureAWSPackage` 运行手册更新 AWS ENA 网络驱动程序。
**步骤 7：installWindowsUpdates（`aws:runCommand` 操作） **
此步骤使用 `AWS-InstallWindowsUpdates` 运行手册安装 Windows 更新。默认情况下，Systems Manager 搜索并安装任何缺失的更新。可以通过指定下列参数之一更改默认行为：`IncludeKbs`、`ExcludeKbs`、`Categories` 或 `SeverityLevels`。
**步骤 8：runPostUpdateScript（`aws:runCommand` 操作)**
此步骤可让您以字符串形式指定一个在安装更新后运行的脚本。
**步骤 9：runSysprepGeneralize（`aws:runCommand` 操作) **
此步骤使用 `AWS-InstallPowerShellModule` 运行手册下载 AWS 共有 PowerShell 模块。Systems Manager 使用 SHA-256 哈希验证模块的完整性。然后 Systems Manager 使用 AWS 支持的方法针对 EC2Launch (Windows Server 2016) 或 EC2Config（Windows Server 2008 R2 到 2012 R2）运行 sysprep。
**步骤 10：stopInstance（`aws:changeInstanceState` 操作） **
此步骤停止已更新实例。
**步骤 11：createImage（`aws:createImage` 操作） **
此步骤创建一个新 AMI，带有可将其链接到源 ID 和创建时间的描述性名称。例如：“EC2自动化在 \$1\$1global:DATE\$1TIME\$1\$1 从 \$1\$1SourceAmiId\$1\$1 生成了 AMI”，其中 DATE\$1TIME 和 SourceID 表示自动化变量。
**步骤 12：TerminateInstance（`aws:changeInstanceState` 操作） **
此步骤通过终止正在运行的实例来清除自动化。
**Output**
此部分可让您将各个步骤的输出或任何参数的值指定为自动化输出。默认情况下，输出是由执行创建的已更新 Windows AMI 的 ID。
**注意**
默认情况下，当自动化运行 `AWS-UpdateWindowsAmi` 运行手册并创建一个临时实例时，系统会使用默认 VPC (172.30.0.0/16)。如果您删除了默认 VPC，会收到以下错误：
VPC not defined 400
要解决此问题，您必须复制 `AWS-UpdateWindowsAmi` 运行手册并指定子网 ID。有关更多信息，请参阅 [VPC not defined 400](automation-troubleshooting.md#automation-trbl-common-vpc)。
**使用自动化创建经过修补的 Windows AMI**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令来运行 `AWS-UpdateWindowsAmi` 运行手册。将每个*示例资源占位符*替换为您自己的信息。以下示例命令使用的是最新的 Amazon EC2 AMI，以最大限度减少需应用的补丁数量。如果您多次运行此命令，则必须为 `targetAMIname` 指定唯一的值。AMI 名称必须唯一。
```
aws ssm start-automation-execution \
--document-name="AWS-UpdateWindowsAmi" \
--parameters SourceAmiId='AMI ID',IamInstanceProfileName='IAM instance profile',AutomationAssumeRole='arn:aws:iam::{{global:ACCOUNT_ID}}:role/AutomationServiceRole'
```
该命令将会返回执行 ID。请将该 ID 复制到剪贴板。您将使用该 ID 查看自动化的状态。
```
{
"AutomationExecutionId": "automation execution ID"
}
```
1. 要使用 AWS CLI 查看自动化，请运行以下命令：
```
aws ssm describe-automation-executions
```
1. 要查看有关自动化进程的详细信息，请运行以下命令。
```
aws ssm get-automation-execution
--automation-execution-id automation execution ID
```
**注意**
根据应用的补丁数量，在该示例自动化中运行的 Windows 修补过程可能需要 30 分钟或更长时间才能完成。
# 使用 Automation、AWS Lambda 和 Parameter Store 来更新黄金 AMI
以下示例使用组织维护和定期修补自己专有 AMIs 的模型，而非构建自 Amazon Elastic Compute Cloud (Amazon EC2) AMIs。
以下过程说明了如何将操作系统（OS）补丁自动应用到已被视为最新的 AMI 或*最新* AMI。在示例中，参数 `SourceAmiId` 的默认值由名为 `latestAmi` 的 AWS Systems Manager Parameter Store 参数定义。`latestAmi` 的值由调用的 AWS Lambda 函数在自动化结束时更新。由于采用了此自动化流程，修补 AMIs 所需的时间和工作量可最大限度减少，因为修补操作始终都应用到最新的 AMI。Parameter Store 和 Automation 都是 AWS Systems Manager 的工具。
**开始前的准备工作**
配置自动化角色以及（可选）为自动化配置 Amazon EventBridge。有关更多信息，请参阅 [设置自动化](automation-setup.md)。
**Topics**
+ [任务 1：在 Systems Manager Parameter Store 中创建一个参数](#create-parameter-ami)
+ [任务 2：为 AWS Lambda 创建 IAM 角色](#create-lambda-role)
+ [任务 3：创建 AWS Lambda 函数](#create-lambda-function)
+ [任务 4：创建运行手册并修补 AMI](#create-custom-ami-update-runbook)
## 任务 1：在 Systems Manager Parameter Store 中创建一个参数
在 Parameter Store 中创建一个使用以下信息的字符串参数：
+ **名称**：`latestAmi`。
+ **值**：AMI ID。例如：` ami-188d6e0e`。
有关如何创建 Parameter Store 字符串参数的信息，请参阅 [在 Systems Manager 中创建 Parameter Store 参数](sysman-paramstore-su-create.md)。
## 任务 2：为 AWS Lambda 创建 IAM 角色
使用以下过程为 AWS Lambda 创建 IAM 服务角色。这些策略授予 Lambda 权限，以便使用 Lambda 函数和 Systems Manager 来更新 `latestAmi` 参数的值。
**为 Lambda 创建 IAM 服务角色**
1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中选择**策略**，然后选择**创建策略**。
1. 选择 **JSON** 选项卡。
1. 将默认内容替换为以下策略。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:us-east-1:111122223333:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:/aws/lambda/function name:*"
]
}
]
}
```
------
1. 选择**下一步：标签**。
1. （可选）添加一个或多个标签键值对，以组织、跟踪或控制此策略的访问权限。
1. 选择**下一步：审核**。
1. 在**查看策略**页面上，对于**名称**，输入内联策略的名称，例如 **amiLambda**。
1. 选择**创建策略**。
1. 重复步骤 2 和 3。
1. 粘贴以下策略。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:PutParameter",
"Resource": "arn:aws:ssm:us-east-1:111122223333:parameter/latestAmi"
},
{
"Effect": "Allow",
"Action": "ssm:DescribeParameters",
"Resource": "*"
}
]
}
```
------
1. 选择**下一步：标签**。
1. （可选）添加一个或多个标签键值对，以组织、跟踪或控制此策略的访问权限。
1. 选择**下一步：审核**。
1. 在**查看策略**页面上，对于**名称**，输入内联策略的名称，例如 **amiParameter**。
1. 选择**创建策略**。
1. 在导航窗格中，选择 **Roles（角色）**，然后选择 **Create role（创建角色）**。
1. 直接在**使用案例**下，选择 **Lambda**，然后选择**下一步**。
1. 在**添加权限**页面上，使用**搜索**字段查找之前创建的两个策略。
1. 选中策略旁边的复选框，然后选择**下一步**。
1. 对于**角色名称**，请输入新角色的名称，如 **lambda-ssm-role**或所需其他名称。
**注意**
由于多个实体可能引用该角色，因此创建角色后无法更改角色的名称。
1. （可选）添加一个或多个标签键值对，以组织、追踪或控制对此角色的访问，然后选择**创建角色**。
## 任务 3：创建 AWS Lambda 函数
使用以下过程创建 Lambda 函数，该函数自动更新 `latestAmi` 参数的值。
**创建 Lambda 函数**
1. 通过以下网址登录 AWS 管理控制台 并打开 AWS Lambda 控制台：[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/)。
1. 选择**创建函数**。
1. 在**创建函数**页面上，选择**从头开始创作**。
1. 对于**函数名称**，请输入 **Automation-UpdateSsmParam**。
1. 对于**运行时系统**，选择 **Python 3.11**。
1. 对于**架构**，选择 Lambda 用于运行该函数的计算机处理器类型，即 **x86\$164** 或 **arm64**，
1. 在**权限**部分中，展开**更改默认执行角色**。
1. 选择**使用现有角色**，然后为您在任务 2 中创建的 Lambda 选择服务角色。
1. 选择**创建函数**。
1. 在**代码源**区域中的 **lambda\$1function** 选项卡上，删除该字段中的预填充代码，然后粘贴以下代码示例。
```
from __future__ import print_function
import json
import boto3
print('Loading function')
#Updates an SSM parameter
#Expects parameterName, parameterValue
def lambda_handler(event, context):
print("Received event: " + json.dumps(event, indent=2))
# get SSM client
client = boto3.client('ssm')
#confirm parameter exists before updating it
response = client.describe_parameters(
Filters=[
{
'Key': 'Name',
'Values': [ event['parameterName'] ]
},
]
)
if not response['Parameters']:
print('No such parameter')
return 'SSM parameter not found.'
#if parameter has a Description field, update it PLUS the Value
if 'Description' in response['Parameters'][0]:
description = response['Parameters'][0]['Description']
response = client.put_parameter(
Name=event['parameterName'],
Value=event['parameterValue'],
Description=description,
Type='String',
Overwrite=True
)
#otherwise just update Value
else:
response = client.put_parameter(
Name=event['parameterName'],
Value=event['parameterValue'],
Type='String',
Overwrite=True
)
responseString = 'Updated parameter %s with value %s.' % (event['parameterName'], event['parameterValue'])
return responseString
```
1. 依次选择**文件、保存**。
1. 要测试 Lambda 函数，请从**测试**菜单中选择**配置测试事件**。
1. 对于**事件名称**，输入测试事件的名称，如 **MyTestEvent**。
1. 使用以下 JSON 替换现有文本。将 *AMI ID* 替换为您自己的信息来设置 `latestAmi` 参数值。
```
{
"parameterName":"latestAmi",
"parameterValue":"AMI ID"
}
```
1. 选择**保存**。
1. 选择**测试**以测试该函数。在**执行结果**选项卡上，应将状态报告为**已成功**，以及有关更新的其他详细信息。
## 任务 4：创建运行手册并修补 AMI
使用以下过程创建并运行运行手册，该文档修补您为 **latestAmi** 参数指定的 AMI。在自动化完成后，使用新修补的 AMI 的 ID 更新 **latestAmi** 的值。后续自动化使用先前执行创建的 AMI。
**创建运行手册并运行**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 对于**创建文档**，选择**自动化**。
1. 对于**名称**，请输入 **UpdateMyLatestWindowsAmi**。
1. 选择**编辑器**选项卡，然后选择**编辑**。
1. 当系统提示时，选择**确定**。
1. 在**文档编辑器**字段中，将默认内容替换为以下 YAML 示例运行手册内容。
```
---
description: Systems Manager Automation Demo - Patch AMI and Update ASG
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to execute this document.'
default: ''
SourceAMI:
type: String
description: The ID of the AMI you want to patch.
default: '{{ ssm:latestAmi }}'
SubnetId:
type: String
description: The ID of the subnet where the instance from the SourceAMI parameter is launched.
SecurityGroupIds:
type: StringList
description: The IDs of the security groups to associate with the instance that's launched from the SourceAMI parameter.
NewAMI:
type: String
description: The name of of newly patched AMI.
default: 'patchedAMI-{{global:DATE_TIME}}'
InstanceProfile:
type: String
description: The name of the IAM instance profile you want the source instance to use.
SnapshotId:
type: String
description: (Optional) The snapshot ID to use to retrieve a patch baseline snapshot.
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: (Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: startInstances
action: 'aws:runInstances'
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
ImageId: '{{ SourceAMI }}'
InstanceType: m5.large
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: '{{ InstanceProfile }}'
SubnetId: '{{ SubnetId }}'
SecurityGroupIds: '{{ SecurityGroupIds }}'
- name: verifyInstanceManaged
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 600
inputs:
Service: ssm
Api: DescribeInstanceInformation
InstanceInformationFilterList:
- key: InstanceIds
valueSet:
- '{{ startInstances.InstanceIds }}'
PropertySelector: '$.InstanceInformationList[0].PingStatus'
DesiredValues:
- Online
onFailure: 'step:terminateInstance'
- name: installPatches
action: 'aws:runCommand'
timeoutSeconds: 7200
onFailure: Abort
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
InstanceIds:
- '{{ startInstances.InstanceIds }}'
- name: stopInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: stopped
- name: createImage
action: 'aws:createImage'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceId: '{{ startInstances.InstanceIds }}'
ImageName: '{{ NewAMI }}'
NoReboot: false
ImageDescription: Patched AMI created by Automation
- name: terminateInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: terminated
- name: updateSsmParam
action: aws:invokeLambdaFunction
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
FunctionName: Automation-UpdateSsmParam
Payload: '{"parameterName":"latestAmi", "parameterValue":"{{createImage.ImageId}}"}'
outputs:
- createImage.ImageId
```
1. 选择**创建自动化**。
1. 在导航窗格中，选择**自动化**，然后选择**执行自动化**。
1. 在 **Choose document**（选择文档）页面上，选择 **Owned by me**（我拥有的）选项卡。
1. 搜索 **UpdateMyLatestWindowsAmi** 运行手册，然后选择 **UpdateMyLatestWindowsAmi** 卡中的按钮。
1. 选择**下一步**。
1. 选择**简单执行**。
1. 指定输入参数的值。
1. 选择**执行**。
1. 自动化完成后，在导航窗格中选择 **Parameter Store**，并确认 `latestAmi` 的新值与自动化返回的值匹配。您还可以验证新 AMI ID 与 Amazon EC2 控制台的 **AMI** 部分中的自动化输出匹配。
# 使用 Automation 和 Jenkins 更新 AMIs
如果组织在 CI/CD 管道中使用 Jenkins 软件，则可以添加 Automation 作为构建后步骤，用于将应用程序发行版预安装到 Amazon Machine Images（AMIs）中。Automation 是 AWS Systems Manager 中的一项工具。您还可以使用 Jenkins 计划功能来调用 Automation 并创建自己的操作系统（OS）修补计划。
以下示例显示如何从运行在本地或 Amazon Elastic Compute Cloud（Amazon EC2）上的 Jenkins 服务器调用 Automation。对于身份验证，Jenkins 服务器使用 AWS 凭证，该凭证基于您在示例中创建并附加到实例配置文件的 IAM 策略。
**注意**
配置实例时，请务必遵循 Jenkins 安全最佳实践。
**开始前的准备工作**
在配置 Automation 用于 Jenkins 之前，请完成以下任务：
+ 完成 [使用 Automation、AWS Lambda 和 Parameter Store 来更新黄金 AMI](automation-tutorial-update-patch-golden-ami.md) 示例。以下示例使用在该示例中创建的 **UpdateMyLatestWindowsAmi** 运行手册。
+ 为自动化配置 IAM 角色。Systems Manager 需要实例配置文件角色和服务角色 ARN 来处理自动化。有关更多信息，请参阅 [设置自动化](automation-setup.md)。
**为 Jenkins 服务器创建 IAM 策略**
1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中选择**策略**，然后选择**创建策略**。
1. 选择 **JSON** 选项卡。
1. 将每个*示例资源占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:StartAutomationExecution",
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/UpdateMyLatestWindowsAmi",
"arn:aws:ssm:us-east-1:111122223333:automation-execution/*"
]
}
]
}
```
------
1. 选择**查看策略**。
1. 在**查看策略**页面上，对于**名称**，输入内联策略的名称，例如 **JenkinsPolicy**。
1. 选择**创建策略**。
1. 在导航窗格中，选择**角色**。
1. 选择附加到 Jenkins 服务器的实例配置文件。
1. 在**权限**选项卡中，选择**添加权限**，然后选择**附加策略**。
1. 在**其他权限策略**部分中，输入您在之前步骤中创建的策略名称。例如，**JenkinsPolicy**。
1. 选中您的策略旁边的复选框，然后选择**附加策略**。
按照以下过程在 Jenkins 服务器上配置 AWS CLI。
**为 Automation 配置 Jenkins 服务器**
1. 使用首选浏览器连接到 8080 端口上的 Jenkins 服务器，以便访问管理界面。
1. 输入 `/var/lib/jenkins/secrets/initialAdminPassword` 在中找到的密码。要显示您的密码，请运行以下命令。
```
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
```
1. Jenkins 安装脚本会将您引导到**自定义 Jenkins** 页面。选择**安装建议的插件**。
1. 安装完成后，依次选择**管理员凭证**、**保存凭证**、**开始使用 Jenkins**。
1. 在左侧导航窗格中，选择**管理 Jenkins**，然后选择**管理插件**。
1. 选**可用**选项卡，然后输入 **Amazon EC2 plugin**。
1. 选中 **Amazon EC2 plugin** 的复选框，然后选择**安装但不重新启动**。
1. 安装完成后，选择**返回首页**。
1. 选择**管理 Jenkins**，然后选择**管理节点和云**。
1. 在**配置云**部分中，选择**添加新云**，然后选择 **Amazon EC2**。
1. 在其余字段中输入您的信息。确保选择**使用 EC2 实例配置文件获取凭证**选项。
按照以下过程配置 Jenkins 项目来调用 Automation。
**配置 Jenkins 服务器来调用 Automation**
1. 在 Web 浏览器中打开 Jenkins 控制台。
1. 选择要配置用于自动化的项目，然后选择**配置**。
1. 在**构建**选项卡上，选择**添加构建步骤**。
1. 选择**执行 shell** 或**执行 Windows 批命令**（具体取决于您的操作系统)。
1. 在 **Command**（命令）字段中，运行 AWS CLI 命令，如下所示。将每个*示例资源占位符*替换为您自己的信息。
```
aws ssm start-automation-execution \
--document-name runbook name \
--region AWS 区域 of your source AMI \
--parameters runbook parameters
```
以下示例命令使用 **UpdateMyLatestWindowsAmi** 运行手册以及在 [使用 Automation、AWS Lambda 和 Parameter Store 来更新黄金 AMI](automation-tutorial-update-patch-golden-ami.md) 中创建的 Systems Manager 参数 `latestAmi`：
```
aws ssm start-automation-execution \
--document-name UpdateMyLatestWindowsAmi \
--parameters \
"sourceAMIid='{{ssm:latestAmi}}'"
--region region
```
在 Jenkins 中，命令类似于以下屏幕截图中的示例。
![\[Jenkins 软件中的示例命令。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/sysman-ami-jenkins2.png)
1. 在 Jenkins 项目中，选择**立即构建**。Jenkins 会返回类似于以下示例的输出。
![\[Jenkins 软件中的示例命令输出。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/sysman-ami-jenkins.png)
# 更新自动扩缩组的 AMIs
以下示例使用新修补的 AMI 更新自动扩缩组。此方法确保新映像自动可供使用 Auto Scaling 组的不同计算环境使用。
此示例中自动化的最后一步使用 Python 函数创建将使用新修补的 AMI 的新启动模板。然后更新自动扩缩组以使用新的启动模板。在此类型的 Auto Scaling 方案中，用户可以终止 Auto Scaling 组中的现有实例以强制启动使用新映像的实例。或者，用户可以等待以允许缩减或扩展事件正常启动较新的实例。
**开始前的准备工作**
在开始本示例之前，请完成以下任务。
+ 为 Automation（AWS Systems Manager 中的一项工具）配置 IAM 角色。Systems Manager 需要实例配置文件角色和服务角色 ARN 来处理自动化。有关更多信息，请参阅 [设置自动化](automation-setup.md)。
## 创建 **PatchAMIAndUpdateASG** 运行手册
使用以下过程创建 **PatchAMIAndUpdateASG** 运行手册，它将修补您为 **SourceAMI** 参数指定的 AMI。运行手册还会更新自动扩缩组以使用最新修补后的 AMI。
**创建运行手册并运行**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 在**创建文档**下拉菜单中，选择**自动化**。
1. 在**名称**字段中，输入 **PatchAMIAndUpdateASG**。
1. 选择 **Editor**（编辑器）选项卡，然后选择 **Edit**（编辑）。
1. 出现提示时选择 **OK**（确定），然后删除 **Document editor**（文档编辑器）字段中的内容。
1. 在 **Document editor**（文档编辑器）字段中，粘贴以下 YAML 示例运行手册内容。
```
---
description: Systems Manager Automation Demo - Patch AMI and Update ASG
schemaVersion: '0.3'
assumeRole: '{{ AutomationAssumeRole }}'
parameters:
AutomationAssumeRole:
type: String
description: '(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to execute this document.'
default: ''
SourceAMI:
type: String
description: '(Required) The ID of the AMI you want to patch.'
SubnetId:
type: String
description: '(Required) The ID of the subnet where the instance from the SourceAMI parameter is launched.'
SecurityGroupIds:
type: StringList
description: '(Required) The IDs of the security groups to associate with the instance launched from the SourceAMI parameter.'
NewAMI:
type: String
description: '(Optional) The name of of newly patched AMI.'
default: 'patchedAMI-{{global:DATE_TIME}}'
TargetASG:
type: String
description: '(Required) The name of the Auto Scaling group you want to update.'
InstanceProfile:
type: String
description: '(Required) The name of the IAM instance profile you want the source instance to use.'
SnapshotId:
type: String
description: (Optional) The snapshot ID to use to retrieve a patch baseline snapshot.
default: ''
RebootOption:
type: String
description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.'
allowedValues:
- NoReboot
- RebootIfNeeded
default: RebootIfNeeded
Operation:
type: String
description: (Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.
allowedValues:
- Install
- Scan
default: Install
mainSteps:
- name: startInstances
action: 'aws:runInstances'
timeoutSeconds: 1200
maxAttempts: 1
onFailure: Abort
inputs:
ImageId: '{{ SourceAMI }}'
InstanceType: m5.large
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: '{{ InstanceProfile }}'
SubnetId: '{{ SubnetId }}'
SecurityGroupIds: '{{ SecurityGroupIds }}'
- name: verifyInstanceManaged
action: 'aws:waitForAwsResourceProperty'
timeoutSeconds: 600
inputs:
Service: ssm
Api: DescribeInstanceInformation
InstanceInformationFilterList:
- key: InstanceIds
valueSet:
- '{{ startInstances.InstanceIds }}'
PropertySelector: '$.InstanceInformationList[0].PingStatus'
DesiredValues:
- Online
onFailure: 'step:terminateInstance'
- name: installPatches
action: 'aws:runCommand'
timeoutSeconds: 7200
onFailure: Abort
inputs:
DocumentName: AWS-RunPatchBaseline
Parameters:
SnapshotId: '{{SnapshotId}}'
RebootOption: '{{RebootOption}}'
Operation: '{{Operation}}'
InstanceIds:
- '{{ startInstances.InstanceIds }}'
- name: stopInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: stopped
- name: createImage
action: 'aws:createImage'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceId: '{{ startInstances.InstanceIds }}'
ImageName: '{{ NewAMI }}'
NoReboot: false
ImageDescription: Patched AMI created by Automation
- name: terminateInstance
action: 'aws:changeInstanceState'
maxAttempts: 1
onFailure: Continue
inputs:
InstanceIds:
- '{{ startInstances.InstanceIds }}'
DesiredState: terminated
- name: updateASG
action: 'aws:executeScript'
timeoutSeconds: 300
maxAttempts: 1
onFailure: Abort
inputs:
Runtime: python3.11
Handler: update_asg
InputPayload:
TargetASG: '{{TargetASG}}'
NewAMI: '{{createImage.ImageId}}'
Script: |-
from __future__ import print_function
import datetime
import json
import time
import boto3
# create auto scaling and ec2 client
asg = boto3.client('autoscaling')
ec2 = boto3.client('ec2')
def update_asg(event, context):
print("Received event: " + json.dumps(event, indent=2))
target_asg = event['TargetASG']
new_ami = event['NewAMI']
# get object for the ASG we're going to update, filter by name of target ASG
asg_query = asg.describe_auto_scaling_groups(AutoScalingGroupNames=[target_asg])
if 'AutoScalingGroups' not in asg_query or not asg_query['AutoScalingGroups']:
return 'No ASG found matching the value you specified.'
# gets details of an instance from the ASG that we'll use to model the new launch template after
source_instance_id = asg_query.get('AutoScalingGroups')[0]['Instances'][0]['InstanceId']
instance_properties = ec2.describe_instances(
InstanceIds=[source_instance_id]
)
source_instance = instance_properties['Reservations'][0]['Instances'][0]
# create list of security group IDs
security_groups = []
for group in source_instance['SecurityGroups']:
security_groups.append(group['GroupId'])
# create a list of dictionary objects for block device mappings
mappings = []
for block in source_instance['BlockDeviceMappings']:
volume_query = ec2.describe_volumes(
VolumeIds=[block['Ebs']['VolumeId']]
)
volume_details = volume_query['Volumes']
device_name = block['DeviceName']
volume_size = volume_details[0]['Size']
volume_type = volume_details[0]['VolumeType']
device = {'DeviceName': device_name, 'Ebs': {'VolumeSize': volume_size, 'VolumeType': volume_type}}
mappings.append(device)
# create new launch template using details returned from instance in the ASG and specify the newly patched AMI
time_stamp = time.time()
time_stamp_string = datetime.datetime.fromtimestamp(time_stamp).strftime('%m-%d-%Y_%H-%M-%S')
new_template_name = f'{new_ami}_{time_stamp_string}'
try:
ec2.create_launch_template(
LaunchTemplateName=new_template_name,
LaunchTemplateData={
'BlockDeviceMappings': mappings,
'ImageId': new_ami,
'InstanceType': source_instance['InstanceType'],
'IamInstanceProfile': {
'Arn': source_instance['IamInstanceProfile']['Arn']
},
'KeyName': source_instance['KeyName'],
'SecurityGroupIds': security_groups
}
)
except Exception as e:
return f'Exception caught: {str(e)}'
else:
# update ASG to use new launch template
asg.update_auto_scaling_group(
AutoScalingGroupName=target_asg,
LaunchTemplate={
'LaunchTemplateName': new_template_name
}
)
return f'Updated ASG {target_asg} with new launch template {new_template_name} which uses AMI {new_ami}.'
outputs:
- createImage.ImageId
```
1. 选择**创建自动化**。
1. 在导航窗格中，选择**自动化**，然后选择**执行自动化**。
1. 在 **Choose document**（选择文档）页面上，选择 **Owned by me**（我拥有的）选项卡。
1. 搜索 **PatchAMIAndUpdateASG** 运行手册，然后选择 **PatchAMIAndUpdateASG** 卡中的按钮。
1. 选择**下一步**。
1. 选择**简单执行**。
1. 指定输入参数的值。确保您指定的 `SubnetId` 和 `SecurityGroupIds` 允许访问公有 Systems Manager 端点或 Systems Manager 的接口端点。
1. 选择**执行**。
1. 自动化完成后，在 Amazon EC2 控制台中，选择 **Auto Scaling**（自动扩缩），然后选择 **Launch Templates**（启动配置）。验证您是否看到了新的启动模板，并且它使用了新的 AMI。
1. 选择 **Auto Scaling**，然后选择 **Auto Scaling 组**。验证自动扩缩组使用了新的启动模板。
1. 终止 Auto Scaling 组中的一个或多个实例。替换实例使用新的 AMI 启动。
# 使用 AWS 支持 自助服务运行手册
本部分介绍如何使用由 AWS 支持 团队创建的自助自动化。这些自动化可帮助您管理 AWS 的资源。
**支持自动化工作流**
Support Workflows (SAW) 是由 AWS 支持 团队撰写并维护的自动化运行手册。这些运行手册帮助您对有关 AWS 资源的常见问题进行故障排除，主动监控和识别网络问题，收集和分析日志，等等。
SAW 运行手册使用 **`AWSSupport`** 前缀 例如 [https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-activatewindowswithamazonlicense.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awssupport-activatewindowswithamazonlicense.html)。
此外,具有 Business Support\$1 及更高 AWS Support 计划的客户还可以访问使用 **`AWSPremiumSupport`** 前缀的运行手册。例如 [https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awspremiumsupport-troubleshootEC2diskusage.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-awspremiumsupport-troubleshootEC2diskusage.html)。
如需了解关于 AWS 支持 的更多信息，请参阅 [AWS 支持 入门](https://docs.aws.amazon.com/awssupport/latest/user/getting-started.html)。
**Topics**
+ [在无法访问的实例上运行 EC2Rescue 工具](automation-ec2rescue.md)
+ [在 EC2 实例上重置密码和 SSH 密钥](automation-ec2reset.md)
# 在无法访问的实例上运行 EC2Rescue 工具
EC2Rescue 可以帮助您诊断有关 Linux 和 Windows Server 的 Amazon Elastic Compute Cloud (Amazon EC2) 实例的问题并进行故障排除。您可以手动运行工具，如[使用适用于 Linux Server 的 EC2Rescue](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Linux-Server-EC2Rescue.html) 和[使用适用于 Windows Server 的 EC2Rescue](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Windows-Server-EC2Rescue.html)。或者，您也可以使用 Systems Manager 自动化和 **`AWSSupport-ExecuteEC2Rescue`** 运行手册。Automation 是 AWS Systems Manager 中的一项工具。**`AWSSupport-ExecuteEC2Rescue`** 运行手册旨在全面执行 Systems Manager 的操作、CloudFormation 的操作和 Lambda 功能，从而将使用 EC2Rescue 通常所需的步骤自动化。
您可以使用 **`AWSSupport-ExecuteEC2Rescue`** 运行手册，对不同类型的操作系统 (OS) 问题进行故障排除和潜在修复。不支持带有加密根卷的实例。有关完整列表，请参阅以下主题：
**Windows**：请参阅*将适用于 Windows Server 的 EC2Rescue 与命令行配合使用*中的[抢救操作](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-cli.html#ec2rw-rescue)。
**Linux** 和 **macOS**：一些适用于 Linux 的 EC2Rescue 模块会检测并尝试修复问题。有关更多信息，请参阅 GitHub 上各个模块的 [https://github.com/awslabs/aws-ec2rescue-linux/tree/master/docs](https://github.com/awslabs/aws-ec2rescue-linux/tree/master/docs) 文档。
## 工作原理
如下文所示，使用自动化和 **`AWSSupport-ExecuteEC2Rescue`** 运行手册对实例进行故障排除：
+ 您为无法访问的实例指定 ID 并启动运行手册。
+ 系统创建一个临时 VPC，然后运行一系列 Lambda 函数以配置该 VPC。
+ 系统在与您的原始实例相同的可用区内为您的临时 VPC 标识一个子网。
+ 系统启动一个临时的启用了 SSM 的 帮助程序实例。
+ 系统停止您的原始实例并创建备份。然后，它将原始根卷附加到帮助程序实例。
+ 系统使用 Run Command 在帮助程序实例上运行 EC2Rescue。EC2Rescue 识别并尝试修复有关已附加的原始根卷的问题。完成后，EC2Rescue 重新将根卷附加回原始实例。
+ 系统重启您的原始实例，并终止临时实例。系统也将终止临时 VPC 和在自动化开始时创建的 Lambda 函数。
## 开始前的准备工作
运行以下自动化之前，请执行以下操作：
+ 复制无法访问的实例的实例 ID。您将在过程中指定此 ID。
+ (可选) 收集无法访问实例所在可用区中子网的 ID。EC2Rescue 实例将在此子网中创建。如果不指定子网，自动化会在您的 AWS 账户中创建新建一个临时 VPC。验证您的 AWS 账户是否至少有一个可用 VPC。默认情况下，一个区域中可以创建 5 个 VPC。如果您已在该区域中创建 5 个 VPC，自动化将会失败，但不会对您的实例进行更改。有关 Amazon VPC 配额的更多信息，请参阅 *Amazon VPC 用户指南*中的 [VPC 和子网](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-vpcs-subnets)。
+ 或者，您可以为自动化创建并指定一个 AWS Identity and Access Management (IAM) 角色。如果您不指定此角色，自动化将在运行自动化的用户的环境中运行。
### 向 `AWSSupport-EC2Rescue` 授予在您的实例上执行操作的权限
在自动化执行期间，EC2Rescue 需要权限才能在您的实例上执行一系列操作。这些操作调用 AWS Lambda、IAM 和 Amazon EC2 服务，安全地尝试修复实例的问题。如果您在 AWS 账户 和/或 VPC 中具有管理员级权限，您可能能够在不按照本部分中所述配置权限的情况下运行自动化。如果您没有管理员级权限，则您或管理员必须使用以下选项之一配置权限。
+ [使用 IAM policy 授予权限](#automation-ec2rescue-access-iam)
+ [使用 CloudFormation 模板授予权限](#automation-ec2rescue-access-cfn)
#### 使用 IAM policy 授予权限
您可以将以下 IAM policy 作为内联策略附加到您的用户、组或角色；也可以创建新的 IAM 托管策略，并将其附加到您的用户、组或角色。有关将内联策略添加到您的用户、组或角色的更多信息，请参阅[使用内联策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html)。有关创建新的托管策略的更多信息，请参阅[使用托管策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html)。
**注意**
如果创建新的 IAM 托管式策略，则还必须将 **AmazonSSMAutomationRole** 托管式策略附加到该策略，以便实例与 Systems Manager API 通信。
**适用于 AWSSupport-EC2Rescue 的 IAM policy**
将 *account ID* 替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:111122223333:function:AWSSupport-EC2Rescue-*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::awssupport-ssm.*/*.template",
"arn:aws:s3:::awssupport-ssm.*/*.zip"
],
"Effect": "Allow"
},
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:PutRolePolicy",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DeleteInstanceProfile"
],
"Resource": [
"arn:aws:iam::111122223333:role/AWSSupport-EC2Rescue-*",
"arn:aws:iam::111122223333:instance-profile/AWSSupport-EC2Rescue-*"
],
"Effect": "Allow"
},
{
"Action": [
"lambda:CreateFunction",
"ec2:CreateVpc",
"ec2:ModifyVpcAttribute",
"ec2:DeleteVpc",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:DetachInternetGateway",
"ec2:DeleteInternetGateway",
"ec2:CreateSubnet",
"ec2:DeleteSubnet",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:CreateRouteTable",
"ec2:AssociateRouteTable",
"ec2:DisassociateRouteTable",
"ec2:DeleteRouteTable",
"ec2:CreateVpcEndpoint",
"ec2:DeleteVpcEndpoints",
"ec2:ModifyVpcEndpoint",
"ec2:Describe*",
"autoscaling:DescribeAutoScalingInstances"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
```
------
#### 使用 CloudFormation 模板授予权限
CloudFormation 使用预配置模板自动化创建 IAM 角色和策略的过程。使用 CloudFormation，通过以下过程为 EC2Rescue 自动化创建所需的 IAM 角色和策略。
**为 EC2Rescue 创建所需的 IAM 角色和策略**
1. 下载 [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip) 文件并将 `AWSSupport-EC2RescueRole.json` 解压到本地计算机上的目录。
1. 如果您的 AWS 账户是一个特殊分区，请编辑模板以将 ARN 值更改为您的分区的值。
例如，对于中国地区，将出现的所有 `arn:aws` 更改为 `arn:aws-cn`。
1. 登录到 AWS 管理控制台 并打开 CloudFormation 控制台 [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。
1. 依次选择**创建堆栈**和**使用新资源（标准）**。
1. 在**创建堆栈**页面上，对于**先决条件 - 准备模板**，选择**模板已就绪**。
1. 对于**指定模板**，选择**上传模板文件**。
1. 选择**选择文件**，然后进行浏览并从您解压缩 `AWSSupport-EC2RescueRole.json` 文件的目录中选择此文件。
1. 选择**下一步**。
1. 在**指定堆栈详细信息**页上，对于**堆栈名称**字段，输入用于标识此堆栈的名称，然后选择**下一步**。
1. （可选）在**标签** 区域，将一个或多个标签键名称/值对应用到堆栈。
标签是您分配给资源的可选元数据。标签可让您按各种标准（如用途、所有者或环境）对资源进行分类。例如，您可能需要对堆栈进行标记，以确定其运行的任务类型、涉及的目标或其他资源的类型以及其运行的环境。
1. 选择 **Next**（下一步）
1. 在**审核**页面上，审核堆栈详细信息，然后向下滚动并选择**我确认 CloudFormation 可能创建 IAM 资源**选项。
1. 选择**创建堆栈**。
CloudFormation 将持续几分钟显示 **CREATE\$1IN\$1PROGRESS** 状态。创建堆栈后，状态将变为 **CREATE\$1COMPLETE**。您还可以选择刷新图标来检查创建过程的状态。
1. 在**堆栈**列表中，选择您刚刚创建的堆栈的选项按钮，然后选择**输出**选项卡。
1. 记下**值**。这是 AssumeRole 的 ARN。在下一个过程 [运行自动化](#automation-ec2rescue-executing) 中运行自动化时指定此 ARN。
## 运行自动化
**重要**
以下自动化将停止无法访问的实例。停止实例可能导致附加的实例存储卷（如果存在）上的数据丢失。如果未关联弹性 IP，停止实例也可能导致公有 IP 更改。
**运行 `AWSSupport-ExecuteEC2Rescue` 自动化**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **自动化**。
1. 选择**执行自动化**。
1. 在**自动化文档**部分中，从列表中选择 **Amazon 所拥有**。
1. 在运行手册列表中，选择卡片中的 `AWSSupport-ExecuteEC2Rescue`，然后选择**下一步**。
1. 在**执行自动化文档**页面上，选择**简单执行**。
1. 在**文档详细信息**部分中，验证**文档版本** 是否设置为最高默认版本。例如，**\$1DEFAULT** 或 **3 (默认值))**。
1. 在**输入参数**部分中，指定以下参数：
1. 对于 **UnreachableInstanceId**，指定无法访问实例的 ID。
1. （可选）对于 **EC2RescueInstanceType**，为 EC2Rescue 实例指定实例类型。默认的实例类型为 `t2.medium`。
1. 对于 **AutomationAssumeRole**，如果您通过使用本主题前面介绍的 CloudFormation 过程为此自动化创建了角色，则选择您在 CloudFormation 控制台中创建的 AssumeRole 的 ARN。
1. （可选）如果在排查实例故障时需要收集操作系统级别的日志，请为 **LogDestination** 指定 S3 存储桶。日志会自动上传到此指定存储桶。
1. 对于 **SubnetId**，指定无法访问实例所在可用区中某个现有 VPC 的子网。默认情况下，Systems Manager 会新建一个 VPC，但您可以根据需要指定现有 VPC 中的某个子网。
**注意**
如果未看到指定存储桶或子网 ID 的选项，请确认使用的是不是运行手册的最新**默认**版本。
1. （可选）在**标签**区域，应用一个或多个标签键名称/值对以帮助识别自动化，例如 `Key=Purpose,Value=EC2Rescue`。
1. 选择**执行**。
运行手册创建一个备份 AMI，作为自动化的一部分。自动化创建的所有其他资源都会自动删除，但此 AMI 将保留在您的账户中。此 AMI 遵从以下命名约定：
备份 AMI：AWSSupport-EC2Rescue:*UnreachableInstanceId*
在 Amazon EC2 控制台中，可以通过搜索自动化执行 ID 查找此 AMI。
# 在 EC2 实例上重置密码和 SSH 密钥
您可以使用 `AWSSupport-ResetAccess` 运行手册在适用于 Windows Server 的 Amazon Elastic Compute Cloud（Amazon EC2）实例上自动重新启用本地管理员密码生成，以及在适用于 Linux 的 EC2 实例上生成新的 SSH 密钥。`AWSSupport-ResetAccess` 运行手册旨在执行 AWS Systems Manager 操作、AWS CloudFormation 操作和 AWS Lambda 函数的组合，从而将重置本地管理员密码通常所需的步骤自动化。
您可以使用 Automation（AWS Systems Manager 中的一项工具）搭配 `AWSSupport-ResetAccess` 运行手册来解决以下问题：
**Windows**
*您丢失了 EC2 密钥对*：要解决此问题，您可以使用 **AWSSupport-ResetAccess** 运行手册，从当前实例创建启用了密码的 AMI，从 AMI 启动新实例，然后选择您拥有的密钥对。
*您丢失了本地管理员密码*：要解决此问题，您可以使用 `AWSSupport-ResetAccess` 运行手册生成可以使用当前 EC2 密钥对解密的一个新密码。
**Linux**
*您丢失了 EC2 密钥对，或者配置了对实例的 SSH 访问但丢失*：要解决此问题，您可以使用 `AWSSupport-ResetAccess` 运行手册创建当前实例的新 SSH 密钥，这使您能够重新连接到该实例。
**注意**
如果适用于 Windows Server 的 EC2 实例针对 Systems Manager 进行了配置，也可以使用 EC2Rescue 和 AWS Systems Manager Run Command 重置您的本地管理员密码。有关更多信息，请参阅《Amazon EC2 用户指南》**中的[将 EC2Rescue for Windows Server 与 Systems Manager Run Command 结合使用](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-ssm.html)。
**相关信息**
《Amazon EC2 用户指南》**中的[使用 PuTTY 从 Windows 连接到 Linux 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/putty.html)。
## 工作原理
使用自动化和 `AWSSupport-ResetAccess` 运行手册进行故障排除的工作原理如下：
+ 您指定实例的 ID 并运行运行手册。
+ 系统创建一个临时 VPC，然后运行一系列 Lambda 函数以配置该 VPC。
+ 系统在与您的原始实例相同的可用区内为您的临时 VPC 标识一个子网。
+ 系统启动一个临时的启用了 SSM 的 帮助程序实例。
+ 系统停止您的原始实例并创建备份。然后，它将原始根卷附加到帮助程序实例。
+ 系统使用 Run Command 在帮助程序实例上运行 EC2Rescue。在 Windows 上，EC2Rescue 通过在附加的原始根卷上使用 EC2Config 或 EC2Launch 为本地管理员启用密码生成。在 Linux 上，EC2Rescue 生成并注入新的 SSH 密钥并将私有密钥加密保存到 Parameter Store 中。完成后，EC2Rescue 重新将根卷附加回原始实例。
+ 系统根据您的实例创建新 Amazon Machine Image (AMI)，现在密码生成已启用。您可以使用此 AMI 创建新 EC2 实例，并根据需要关联新密钥对。
+ 系统重启您的原始实例，并终止临时实例。系统也将终止临时 VPC 和在自动化开始时创建的 Lambda 函数。
+ **Windows**：您的实例生成一个新密码，您可以使用分配给实例的当前密钥对从 Amazon EC2 控制台对该密码进行解码。
**Linux**：您可以使用存储在 Systems Manager Parameter Store 中的 SSH 密钥（格式为 **/ec2rl/openssh/*instance ID*/key**）通过 SSH 连接到实例。
## 开始前的准备工作
运行以下自动化之前，请执行以下操作：
+ 复制要重置管理员密码的实例的实例 ID。您将在过程中指定此 ID。
+ (可选) 收集无法访问实例所在可用区中子网的 ID。EC2Rescue 实例将在此子网中创建。如果不指定子网，自动化会在您的 AWS 账户中创建新建一个临时 VPC。验证您的 AWS 账户是否至少有一个可用 VPC。默认情况下，一个区域中可以创建 5 个 VPC。如果您已在该区域中创建 5 个 VPC，自动化将会失败，但不会对您的实例进行更改。有关 Amazon VPC 配额的更多信息，请参阅 *Amazon VPC 用户指南*中的 [VPC 和子网](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-vpcs-subnets)。
+ 或者，您可以为自动化创建并指定一个 AWS Identity and Access Management (IAM) 角色。如果您不指定此角色，自动化将在运行自动化的用户的环境中运行。
### 向 AWSSupport-EC2Rescue 授予在您的实例上执行操作的权限
在自动化期间，EC2Rescue 需要权限才能在您的实例上执行一系列操作。这些操作调用 AWS Lambda、IAM 和 Amazon EC2 服务，安全地尝试修复实例的问题。如果您在 AWS 账户 和/或 VPC 中具有管理员级权限，您可能能够在不按照本部分中所述配置权限的情况下运行自动化。如果您没有管理员级权限，则您或管理员必须使用以下选项之一配置权限。
+ [使用 IAM policy 授予权限](#automation-ec2reset-access-iam)
+ [使用 CloudFormation 模板授予权限](#automation-ec2reset-access-cfn)
#### 使用 IAM policy 授予权限
您可以将以下 IAM policy 作为内联策略附加到您的用户、组或角色；也可以创建新的 IAM 托管策略，并将其附加到您的用户、组或角色。有关将内联策略添加到您的用户、组或角色的更多信息，请参阅[使用内联策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html)。有关创建新的托管策略的更多信息，请参阅[使用托管策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html)。
**注意**
如果创建新的 IAM 托管式策略，则还必须将 **AmazonSSMAutomationRole** 托管式策略附加到该策略，以便实例与 Systems Manager API 通信。
**`AWSSupport-ResetAccess` 的 IAM policy**
将 *account ID* 替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:DeleteFunction",
"lambda:GetFunction"
],
"Resource": "arn:aws:lambda:*:111122223333:function:AWSSupport-EC2Rescue-*",
"Effect": "Allow"
},
{
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::awssupport-ssm.*/*.template",
"arn:aws:s3:::awssupport-ssm.*/*.zip"
],
"Effect": "Allow"
},
{
"Action": [
"iam:CreateRole",
"iam:CreateInstanceProfile",
"iam:GetRole",
"iam:GetInstanceProfile",
"iam:PutRolePolicy",
"iam:DetachRolePolicy",
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:AddRoleToInstanceProfile",
"iam:RemoveRoleFromInstanceProfile",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DeleteInstanceProfile"
],
"Resource": [
"arn:aws:iam::111122223333:role/AWSSupport-EC2Rescue-*",
"arn:aws:iam::111122223333:instance-profile/AWSSupport-EC2Rescue-*"
],
"Effect": "Allow"
},
{
"Action": [
"lambda:CreateFunction",
"ec2:CreateVpc",
"ec2:ModifyVpcAttribute",
"ec2:DeleteVpc",
"ec2:CreateInternetGateway",
"ec2:AttachInternetGateway",
"ec2:DetachInternetGateway",
"ec2:DeleteInternetGateway",
"ec2:CreateSubnet",
"ec2:DeleteSubnet",
"ec2:CreateRoute",
"ec2:DeleteRoute",
"ec2:CreateRouteTable",
"ec2:AssociateRouteTable",
"ec2:DisassociateRouteTable",
"ec2:DeleteRouteTable",
"ec2:CreateVpcEndpoint",
"ec2:DeleteVpcEndpoints",
"ec2:ModifyVpcEndpoint",
"ec2:Describe*"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
```
------
#### 使用 CloudFormation 模板授予权限
CloudFormation 使用预配置模板自动化创建 IAM 角色和策略的过程。使用 CloudFormation，通过以下过程为 EC2Rescue 自动化创建所需的 IAM 角色和策略。
**为 EC2Rescue 创建所需的 IAM 角色和策略**
1. 下载 [https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip](https://docs.aws.amazon.com/systems-manager/latest/userguide/samples/AWSSupport-EC2RescueRole.zip) 文件并将 `AWSSupport-EC2RescueRole.json` 解压到本地计算机上的目录。
1. 如果您的 AWS 账户是一个特殊分区，请编辑模板以将 ARN 值更改为您的分区的值。
例如，对于中国地区，将出现的所有 `arn:aws` 更改为 `arn:aws-cn`。
1. 登录到 AWS 管理控制台 并打开 CloudFormation 控制台 [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/)。
1. 依次选择**创建堆栈**和**使用新资源（标准）**。
1. 在**创建堆栈**页面上，对于**先决条件 - 准备模板**，选择**模板已就绪**。
1. 对于**指定模板**，选择**上传模板文件**。
1. 选择**选择文件**，然后进行浏览并从您解压缩 `AWSSupport-EC2RescueRole.json` 文件的目录中选择此文件。
1. 选择**下一步**。
1. 在**指定堆栈详细信息**页上，对于**堆栈名称**字段，输入用于标识此堆栈的名称，然后选择**下一步**。
1. （可选）在**标签** 区域，将一个或多个标签键名称/值对应用到堆栈。
标签是您分配给资源的可选元数据。标签可让您按各种标准（如用途、所有者或环境）对资源进行分类。例如，您可能需要对堆栈进行标记，以确定其运行的任务类型、涉及的目标或其他资源的类型以及其运行的环境。
1. 选择 **Next**（下一步）
1. 在**审核**页面上，审核堆栈详细信息，向下滚动并选择**我确认 CloudFormation 可能创建 IAM 资源**选项。
1. CloudFormation 将持续几分钟显示 **CREATE\$1IN\$1PROGRESS** 状态。创建堆栈后，状态将变为 **CREATE\$1COMPLETE**。您还可以选择刷新图标来检查创建过程的状态。
1. 在堆栈列表中，选择您刚刚创建的堆栈旁边的选项，然后选择**输出**选项卡。
1. 复制**值**。这是 AssumeRole 的 ARN。在运行自动化时，您将指定此 ARN。
## 运行自动化
以下过程介绍如何使用 AWS Systems Manager 控制台运行 `AWSSupport-ResetAccess` 运行手册。
**重要**
以下自动化执行将停止实例。停止实例可能导致附加的实例存储卷（如果存在）上的数据丢失。如果未关联弹性 IP，停止实例也可能导致公有 IP 更改。要避免这些配置更改，请使用 Run Command 重置访问权限。有关更多信息，请参阅《Amazon EC2 用户指南》**中的[将 EC2Rescue for Windows Server 与 Systems Manager Run Command 结合使用](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2rw-ssm.html)。
**要运行 AWSSupport-ResetAccess Automation，请执行以下操作：**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **自动化**。
1. 选择**执行自动化**。
1. 在**自动化文档**部分中，从列表中选择 **Amazon 所拥有**。
1. 在运行手册列表中，选择 **AWSSupport-ResetAccess** 卡片中的按钮，然后选择**下一步**。
1. 在**执行运行手册**页面上，选择**简单执行**。
1. 在**文档详细信息**部分中，验证**文档版本** 是否设置为最高默认版本。例如，**\$1DEFAULT** 或 **3 (默认值))**。
1. 在**输入参数**部分中，指定以下参数：
1. 对于 **InstanceID**，指定无法访问实例的 ID。
1. 对于 **SubnetId**，指定您指定的实例所在可用区中某个现有 VPC 的子网。默认情况下，Systems Manager 会新建一个 VPC，但您可以根据需要指定现有 VPC 中的某个子网。
**注意**
如果未看到指定子网 ID 的选项，请确认使用的是不是运行手册的最新**默认**版本。
1. 对于 **EC2RescueInstanceType**，为 EC2Rescue 实例指定实例类型。默认的实例类型为 `t2.medium`。
1. 对于 **AssumeRole**，如果是使用本主题前面介绍的 CloudFormation 过程为此自动化创建的角色，则指定您在 CloudFormation 控制台记下的 AssumeRole ARN。
1. （可选）在**标签**区域，应用一个或多个标签键名称/值对以帮助识别自动化，例如 `Key=Purpose,Value=ResetAccess`。
1. 选择**执行**。
1. 要监控自动化过程，请选择正在运行的自动化，然后选择**步骤**选项卡。完成自动化后，选择**描述**选项卡，然后选择**查看输出**以查看结果。要查看单个步骤的输出，请选择**步骤**选项卡，然后选择步骤旁的**查看输出**。
运行手册创建一个备份 AMI 和已启用密码的 AMI 作为自动化的一部分。自动化创建的所有其他资源都会自动删除，但这些 AMIs 将保留在您的账户中。这些 AMIs 遵从以下命名约定：
+ 备份 AMI：`AWSSupport-EC2Rescue:InstanceID`
+ 启用了密码的 AMI：AWSSupport-EC2Rescue: Password-enabled AMI from *Instance ID*
可以通过搜索自动化执行 ID 查找这些 AMIs。
对于 Linux，您的实例的新 SSH 私有密钥加密保存到 Parameter Store 中。参数名称为 **/ec2rl/openssh/*instance ID*/key**。
# 使用输入变压器将数据传递到 Automation
此 AWS Systems Manager Automation 教程展示了如何使用 Amazon EventBridge 的输入转换器功能，从实例状态更改事件中提取 Amazon Elastic Compute Cloud (Amazon EC2) 实例的 `instance-id`。Automation 是 AWS Systems Manager 中的一项工具。我们使用输入转换器将该数据作为 `InstanceId` 输入参数传递给 `AWS-CreateImage` 运行手册目标。当任何实例更改为 `stopped` 状态时，均将触发该规则。
有关使用输入转换器的更多信息，请参阅 *Amazon EventBridge 用户指南*中的[教程：使用输入转换器自定义要传递给事件目标的内容](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-input-transformer-tutorial.html)。
**开始前的准备工作**
验证是否已向 Systems Manager 自动化服务角色添加了 EventBridge 所需的权限和信任策略。有关更多信息，请参阅 *Amazon EventBridge 用户指南*中的[管理 EventBridge 资源访问权限概述](https://docs.aws.amazon.com/eventbridge/latest/userguide/iam-access-control-identity-based-eventbridge.html)。
**将输入转换器与自动化结合使用**
1. 打开位于 [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/) 的 Amazon EventBridge 控制台。
1. 在导航窗格中，选择**规则**。
1. 选择**创建规则**。
1. 为规则输入名称和描述。
规则不能与同一区域中的另一个规则和同一事件总线上的名称相同。
1. 对于**事件总线**，请选择要与此规则关联的事件总线。如果您希望此规则响应来自您自己的 AWS 账户的匹配事件，请选择 **defaul**（默认）。当您账户中的某个 AWS 服务发出一个事件时，它始终会发送到您账户的默认事件总线。
1. 对于**规则类型**，选择**具有事件模式的规则**。
1. 选择**下一步**。
1. 对于**事件源**，选择**AWS 事件或 EventBridge 合作伙伴事件**。
1. 在**事件模式**部分，选择**使用模式表单**。
1. 对于 **Event source**（事件源），选择 **AWS services**（服务）。
1. 在 **AWS service**（服务）中，选择 **EC2**。
1. 对于**事件类型**，请选择 **EC2 实例状态更改通知**。
1. 对于**事件类型规范 1**，选择**特定状态**，然后选择**已停止**。
1. 对于**事件类型规范 2**，选择**任何实例**，或选择**特定实例 ID** 并输入要监控的实例的 ID。
1. 选择**下一步**。
1. 对于**目标类型**，选择**AWS 服务**。
1. 对于 **Target**（目标），选择 **Systems Manager Automation**。
1. 对于 **Document**（文档），选择 **AWS-CreateImage**。
1. 在 **Configure automation parameter(s)**（配置自动化参数）部分中，选择 **Input Transformer**（输入转换器）。
1. 对于 **Input path**（输入路径），输入 **\$1"instance":"\$1.detail.instance-id"\$1**。
1. 对于 **Template**（模板），输入 **\$1"InstanceId":[]\$1**。
1. 对于 **Execution role**（执行角色），选择 **Use existing role**（使用现有角色），然后选择您的自动化服务角色。
1. 选择 **Next（下一步）**。
1. （可选）为规则输入一个或多个标签。有关更多信息，请参阅 *Amazon EventBridge 用户指南*中的[标记 Amazon EventBridge 资源](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-tagging.html)。
1. 选择 **Next（下一步）**。
1. 查看规则详细信息并选择**创建规则**。
# 了解 Systems Manager Automation 返回的状态
AWS Systems Manager自动化报告有关运行自动化时自动化操作或步骤所经历的各种状态的详细状态信息，以及整体自动化的同类信息。Automation 是 AWS Systems Manager 中的一项工具。您可以使用以下方法监视自动化状态。
+ 在 Systems Manager 自动化控制台中监控**执行状态**。
+ 使用您的首选命令行工具。对于 AWS Command Line Interface(AWS CLI），您可以使用 [describe-automation-step-executions](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-automation-step-executions.html) 或 [get-automation-execution](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-automation-execution.html)。对于 AWS Tools for Windows PowerShell，您可以使用 [Get-SSMAutomationStepExecution](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMAutomationStepExecution.html) 或 [Get-SSMAutomationExecution](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-SSMAutomationExecution.html)。
+ 配置 Amazon EventBridge 以响应操作或自动化状态更改。
有关处理自动化中超时的更多信息，请参阅[处理运行手册中的超时](automation-handling-timeouts.md)。
## 关于自动化状态
除了整体自动化之外，自动化还会报告单个自动化操作的状态详细信息。
整体自动化状态可能不同于单个操作或步骤报告的状态，如下表所述。
**操作的详细状态**
| Status | Details |
| --- | --- |
| 待处理 | 该步骤尚未开始运行。如果自动化使用条件操作，则在自动化完成后，如果运行步骤的条件未满足，步骤将保持此状态。如果在步骤运行之前取消了自动化，则步骤也会保持此状态。 |
| InProgress | 步骤正在运行。 |
| IN LIST | 步骤正在等待输入。 |
| 成功 | 步骤成功完成。这是最终状态。 |
| 超时 | 步骤或批准未在指定的超时期限之前完成。这是最终状态。 |
| 正在取消 | 请求者取消步骤后，该步骤正在停止。 |
| 已取消 | 该步骤在完成之前已由请求者停止。这是最终状态。 |
| 已失败 | 该步骤未成功完成。这是最终状态。 |
| Exited | 仅通过 `aws:loop` 操作返回。循环未完全完成。使用 `nextStep`、`onCancel` 或 `onFailure` 属性将循环内的步骤移至外部步骤。 |
**自动化的详细状态**
| Status | Details |
| --- | --- |
| 待处理 | 自动化尚未开始运行。 |
| InProgress | 自动化正在运行。 |
| IN LIST | 自动化正在等待输入。 |
| 成功 | 已成功完成操作。这是最终状态。 |
| 超时 | 步骤或批准未在指定的超时期限之前完成。这是最终状态。 |
| 正在取消 | 请求者取消后，自动化正在停止。 |
| 已取消 | 自动化在完成之前被请求者停止。这是最终状态。 |
| 已失败 | 自动化未成功完成。这是最终状态。 |
# Systems Manager 自动化故障排除
利用以下信息，帮助排查 AWS Systems Manager Automation（AWS Systems Manager 中的一项工具）出现的问题。本主题介绍了依据自动化错误消息解决问题的特定任务。
**Topics**
+ [常见自动化错误](#automation-trbl-common)
+ [自动化执行无法启动](#automation-trbl-access)
+ [执行已启动，但是状态为“失败”](#automation-trbl-exstrt)
+ [执行已启动，但超时](#automation-trbl-to)
## 常见自动化错误
此部分提供有关常见自动化错误的信息。
### VPC not defined 400
默认情况下，当自动化运行 `AWS-UpdateLinuxAmi` 运行手册或 `AWS-UpdateWindowsAmi` 运行手册时，系统会在默认 VPC (172.30.0.0/16) 中创建一个临时实例。如果您删除了默认 VPC，会收到以下错误：
`VPC not defined 400`
要解决此问题，您必须为 `SubnetId` 输入参数指定值。
## 自动化执行无法启动
如果您没有为自动化正确配置 AWS Identity and Access Management（IAM）角色和策略，自动化可能因拒绝访问错误或担任角色无效错误而失败。
### 拒绝访问
以下示例描述了自动化执行因拒绝访问错误无法启动的情况。
**对 Systems Manager API 的访问被拒绝**
**错误消息**：`User: user arn isn't authorized to perform: ssm:StartAutomationExecution on resource: document arn (Service: AWSSimpleSystemsManagement; Status Code: 400; Error Code: AccessDeniedException; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)`
+ 可能的原因 1：尝试启动自动化的用户没有调用 `StartAutomationExecution` API 的权限。要解决此问题，请将所需的 IAM policy 附加到用于启动自动化的用户。
+ 可能的原因 2：尝试启动自动化的用户拥有调用 `StartAutomationExecution` API 的权限，但是无权使用特定运行手册来调用该 API。要解决此问题，请将所需的 IAM policy 附加到用于启动自动化的用户。
**由于缺少 PassRole 权限而导致访问被拒**
**错误消息**：`User: user arn isn't authorized to perform: iam:PassRole on resource: automation assume role arn (Service: AWSSimpleSystemsManagement; Status Code: 400; Error Code: AccessDeniedException; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)`
尝试启动自动化的 IAM 用户没有担任角色所需的 PassRole 权限。要解决此问题，请将 iam:PassRole 策略附加到尝试启动自动化的用户的角色。有关更多信息，请参阅 [任务 2：将 iam:PassRole 策略附加到您的自动化角色](automation-setup-iam.md#attach-passrole-policy)。
### 担任角色无效
运行自动化时，要么在运行手册中提供担任角色，要么将担任角色作为运行手册的一个参数值传递。如果未指定或未正确配置担任角色，可出现不同类型的错误。
**担任角色格式错误**
**错误消息**：`The format of the supplied assume role ARN isn't valid.`担任角色格式不正确。要解决该问题，请验证运行手册中是否指定了有效的担任角色，或者在启动自动化时指定为运行时的参数。
**无法担任担任角色**
**错误消息**：`The defined assume role is unable to be assumed. (Service: AWSSimpleSystemsManagement; Status Code: 400; Error Code: InvalidAutomationExecutionParametersException; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)`
+ 可能的原因 1：担任角色不存在。要解决该问题，请创建角色。有关更多信息，请参阅 [设置自动化](automation-setup.md)。创建此角色的特定详细信息在以下主题中介绍 [任务 1：为自动化创建服务角色](automation-setup-iam.md#create-service-role)。
+ 可能的原因 2：担任角色没有与 Systems Manager 服务的信任关系。要解决该问题，请创建信任关系。有关更多信息，请参阅 *《IAM 用户指南》*中的[我无法担任角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_roles.html#troubleshoot_roles_cant-assume-role)。
## 执行已启动，但是状态为“失败”
### 操作特定的失败
运行手册包含步骤，并且步骤按顺序运行。每个步骤会调用一项或多项 AWS 服务 API。API 可确定本步的输入、行为和输出。在多个位置错误可能导致步骤失败。失败消息指示出现错误的时间和位置。
要查看 Amazon Elastic Compute Cloud (Amazon EC2) 控制台中的失败消息，请选择失败步骤的**查看输出**链接。要查看 AWS CLI 中的失败消息，请调用 `get-automation-execution` 并查找失败的 `StepExecution` 中的 `FailureMessage` 属性。
在以下示例中，与 `aws:runInstance` 操作相关联的步骤失败。每个示例探讨了不同类型的错误。
**缺少映像**
**错误消息**：`Automation Step Execution fails when it's launching the instance(s). Get Exception from RunInstances API of ec2 Service. Exception Message from RunInstances API: [The image id '[ami id]' doesn't exist (Service: AmazonEC2; Status Code: 400; Error Code: InvalidAMIID.NotFound; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)]. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
`aws:runInstances` 操作收到的 `ImageId` 输入不存在。要解决该问题，请用正确的 AMI ID 更新运行手册或参数值。
**担任角色策略缺少足够的权限**
**错误消息**：`Automation Step Execution fails when it's launching the instance(s). Get Exception from RunInstances API of ec2 Service. Exception Message from RunInstances API: [You aren't authorized to perform this operation. Encoded authorization failure message: xxxxxxx (Service: AmazonEC2; Status Code: 403; Error Code: UnauthorizedOperation; Request ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)]. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
担任角色的权限不足，无法在 EC2 实例上调用 `RunInstances` API。要解决此问题，请将 IAM policy 附加到有权调用 `RunInstances` API 的担任角色。有关更多信息，请参阅[使用控制台为 Automation 创建服务角色](automation-setup-iam.md)。
**意外状态**
**错误消息**：`Step fails when it's verifying launched instance(s) are ready to be used. Instance i-xxxxxxxxx entered unexpected state: shutting-down. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
+ 可能的原因 1：实例或 Amazon EC2 服务有问题。要解决此问题，请登录到实例或查阅实例系统日志以了解实例启动关闭的原因。
+ 可能的原因 2：为 `aws:runInstances` 操作指定的用户数据脚本有问题或语法错误。验证用户数据脚本的语法。另外，请验证用户数据脚本是否未关闭实例，或者调用了关闭该实例的其他脚本。
**操作特定失败参考**
如果步骤失败，失败消息可能指示失败时正在调用哪个服务。下表列出每个操作调用的服务。该表还提供指向有关每个服务的信息的链接。
****
| Action | 此操作调用的 AWS 服务 | 有关此服务的信息 | 排查内容问题 |
| --- | --- | --- | --- |
| `aws:runInstances` | Amazon EC2 | [Amazon EC2 用户指南](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/) | [EC2 实例故障排除](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-troubleshoot.html) |
| `aws:changeInstanceState` | Amazon EC2 | [Amazon EC2 用户指南](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/) | [EC2 实例故障排除](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-troubleshoot.html) |
| `aws:runCommand` | Systems Manager | [AWS Systems Manager Run Command](run-command.md) | [对 Systems Manager Run Command 进行故障排除](troubleshooting-remote-commands.md) |
| `aws:createImage` | Amazon EC2 | [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) | |
| `aws:createStack` | CloudFormation | [《AWS CloudFormation 用户指南》](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) | [CloudFormation 问题排查](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html) |
| `aws:deleteStack` | CloudFormation | [《AWS CloudFormation 用户指南》](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) | [CloudFormation 问题排查](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html) |
| `aws:deleteImage` | Amazon EC2 | [亚马逊机器映像](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) | |
| `aws:copyImage` | Amazon EC2 | [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) | |
| `aws:createTag` | Amazon EC2，Systems Manager | [EC2 资源和标签](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_Resources.html) | |
| `aws:invokeLambdaFunction` | AWS Lambda | [AWS Lambda 开发人员指南](https://docs.aws.amazon.com/lambda/latest/dg/) | [Lambda 故障排除](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-functions.html) |
### 自动化服务内部错误
**错误消息**：`Internal Server Error. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
自动化 服务中的一个问题导致指定运行手册无法正确运行。要解决此问题，请联系 AWS 支持。请提供执行 ID 和客户 ID (如果有)。
## 执行已启动，但超时
**错误消息**：`Step timed out while step is verifying launched instance(s) are ready to be used. Please refer to Automation Service Troubleshooting Guide for more diagnosis details.`
`aws:runInstances` 操作中的步骤超时。如果运行本步骤操作所花的时间超出此步骤中为 `timeoutSeconds` 指定的值，就会发生这种情况。要解决此问题，请为 `aws:runInstances` 操作中的 `timeoutSeconds` 参数指定更长的值。如果不能解决问题，请调查步骤运行时间超出预期的原因
# AWS Systems Manager Change Calendar
Change Calendar（AWS Systems Manager 中的一项工具）让您能够设置可以或不可以在 AWS 账户中执行指定操作（例如在 [Systems Manager Automation](systems-manager-automation.md) 运行手册中）的日期和时间范围。在 Change Calendar 中，这些范围称为*事件*。在您创建 Change Calendar 条目时，您将创建类型 `ChangeCalendar` 的 [Systems Manager 文档](documents.md) 在 Change Calendar 中，文档以纯文本格式存储 [iCalendar 2.0](https://icalendar.org/) 数据。您添加到 Change Calendar 条目的事件将成为该文档的一部分。要开始使用 Change Calendar，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/change-calendar)。在导航窗格中，请选择 **Change Calendar**。
您可以在 Systems Manager 控制台中创建日历及其事件。您还可以导入从受支持的第三方日历提供程序导出的 iCalendar (`.ics`) 文件，以将其事件添加到您的日历。受支持的提供程序包括 Google 日历、Microsoft Outlook 和 iCloud 日历。
Change Calendar 条目可以是以下两种类型之一：
**`DEFAULT_OPEN`**，即 Open by default (预设情况下打开)
默认情况下，除日历事件期间外，所有操作都可以运行。在事件期间，`DEFAULT_OPEN` 日历的状态为 `CLOSED`，且事件被阻止运行。
**`DEFAULT_CLOSED`**，即 Closed by default (预设情况下关闭)
默认情况下，除日历事件期间外，所有操作都被阻止运行。在事件期间，`DEFAULT_CLOSED` 日历的状态为 `OPEN`，且操作被允许运行。
您可以选择将所有计划的自动化工作流程、维护时段和 State Manager 关联自动添加到日历中。您也可以从日历显示中删除其中任何一种单独类型。
## 谁应该使用 Change Calendar？
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
+ 执行以下操作类型的 AWS 客户：
+ 创建或运行自动化运行手册。
+ 在 Change Manager 中创建更改请求。
+ 运行维护时段。
+ 在 State Manager 中创建关联。
Automation、Change Manager、Maintenance Windows、和State Manager都是 AWS Systems Manager 中的工具。通过将这些工具与 Change Calendar 集成在一起，您可以根据与每个操作类型关联的更改日历的当前状态，来允许或阻止这些操作类型。
+ 负责维护 Systems Manager 托管式节点配置的一致性、稳定性和功能性的管理员。
## 的优势Change Calendar
以下是 Change Calendar 的一些优势。
+ **在应用更改之前进行审核**
Change Calendar 条目可以帮助确保在应用对环境可能会造成破坏的更改之前对其进行审核。
+ **仅在合适时间应用更改**
Change Calendar 条目有助于在事件期间保持环境稳定。例如，在您预期会有大量资源需求（例如在会议或公共营销促销期间）时，可以创建一个 Change Calendar 条目来阻止更改。当您预计管理员只能提供有限的支持（例如在度假或假期）时，日历条目也可以阻止更改。在管理员提供的支持有限，无法对失败的操作或部署进行故障排除时，您可以使用日历条目允许在一天或一周中的特定时间以外进行更改。
+ **获取日历当前或之后的状态**
您可以运行 Systems Manager `GetCalendarState` API 操作，显示日历的当前状态、在指定时间的状态或下次计划日历状态更改的时间。
**注意**
`GetCalendarState` API 的配额为每秒 10 个请求。有关 Systems Manager 配额的更多信息，请参阅*《Amazon Web Services 一般参考》*中的 [Systems Manager 服务配额](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm)。
+
**EventBridge 支持**
支持此 Systems Manager 工具作为 Amazon EventBridge 规则中的一个*事件*类型。有关更多信息，请参阅 [使用 Amazon EventBridge 监控 Systems Manager 事件](monitoring-eventbridge-events.md) 和 [引用：Amazon EventBridge 事件模式和 Systems Manager 类型](reference-eventbridge-events.md)。
**Topics**
+ [谁应该使用 Change Calendar？](#systems-manager-change-calendar-who)
+ [的优势Change Calendar](#systems-manager-change-calendar-benefits)
+ [设置 Change Calendar](systems-manager-change-calendar-prereqs.md)
+ [使用 Change Calendar](systems-manager-change-calendar-working.md)
+ [向自动化运行手册添加 Change Calendar 依赖关系](systems-manager-change-calendar-automations.md)
+ [排除 Change Calendar 问题](change-calendar-troubleshooting.md)
# 设置 Change Calendar
使用 Change Calendar（AWS Systems Manager 中的一项工具）前请完成以下操作。
## 安装最新的命令行工具
安装最新的命令行工具，以获取有关日历状态的信息。
| 要求 | 说明 |
| --- | --- |
| AWS CLI | （可选）要使用 AWS Command Line Interface (AWS CLI) 获取有关日历状态的信息，请在本地计算机上安装 AWS CLI 的最新版本。 有关如何安装或升级 CLI 的更多信息，请参阅 *AWS Command Line Interface 用户指南*中的[安装、更新和卸载 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)。 |
| AWS Tools for PowerShell | （可选）要使用 Tools for PowerShell 获取有关日历状态的信息，请在本地计算机上安装 Tools for PowerShell 的最新版本。 有关如何安装或升级 Tools for PowerShell 的更多信息，请参阅 *AWS Tools for PowerShell 用户指南*中的[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。 |
## 设置权限
如果已为您的用户、组或角色分配了管理员权限，则您对 Change Calendar 有完全访问权。如果您没有管理员权限，则管理员必须通过向您的用户、组或角色分配 `AmazonSSMFullAccess` 托管策略或分配提供必要权限的策略，来向您授予权限。
使用 Change Calendar 需要以下权限。
**Change Calendar 条目**
要创建、更新或删除 Change Calendar 条目（包括在条目中添加和删除事件），附加到用户、组或角色的策略必须允许执行以下操作：
+ `ssm:CreateDocument`
+ `ssm:DeleteDocument`
+ `ssm:DescribeDocument`
+ `ssm:DescribeDocumentPermission`
+ `ssm:GetCalendar`
+ `ssm:ListDocuments`
+ `ssm:ModifyDocumentPermission`
+ `ssm:PutCalendar`
+ `ssm:UpdateDocument`
+ `ssm:UpdateDocumentDefaultVersion`
**日历状态**
要获取有关日历当前或之后状态的信息，附加到用户、组或角色的策略必须允许执行以下操作：
+ `ssm:GetCalendarState`
**操作事件**
要查看操作事件，例如维护时段、关联和计划的自动化，附加到用户、组或角色的策略必须允许执行以下操作：
+ `ssm:DescribeMaintenanceWindows`
+ `ssm:DescribeMaintenanceWindowExecution`
+ `ssm:DescribeAutomationExecutions`
+ `ssm:ListAssociations`
**注意**
由您的账户以外的账户拥有（即该账户创建）的 Change Calendar 条目为只读，即使它们与您的账户共享也是如此。维护时段、State Manager 关联和自动化不会共享。
# 使用 Change Calendar
您可以使用 AWS Systems Manager 控制台添加、管理或删除 Change Calendar（AWS Systems Manager 中的一项工具）条目。您还可以从受支持的第三方日历提供程序导入事件，方法是导入从源日历导出的 iCalendar (`.ics`) 文件。而且，您也可以使用 `GetCalendarState` API 操作或 `get-calendar-state` AWS Command Line Interface (AWS CLI) 命令在特定时间获取有关 Change Calendar 状态的信息。
**Topics**
+ [创建更改日历](change-calendar-create.md)
+ [在 Change Calendar 中创建和管理事件](change-calendar-events.md)
+ [导入和管理来自第三方日历的事件](third-party-events.md)
+ [更新更改日历](change-calendar-update.md)
+ [共享更改日历](change-calendar-share.md)
+ [删除更改日历](change-calendar-delete.md)
+ [获取更改日历的状态](change-calendar-getstate.md)
# 创建更改日历
在 Change Calendar（AWS Systems Manager 中的一项工具）中创建条目时，您要用到使用 `text` 格式的 Systems Manager 文档（SSM 文档）。
**创建更改日历**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Change Calendar**。
1. 选择 **Create calendar（创建日历）**。
–或者–
如果 **Change Calendar** 主页首先打开，则选择 **Create change calendar**（创建更改日历）。
1. 在 **Create calendar (创建日历)** 页面上的 **Calendar details (日历详细信息)** 中，输入日历条目的名称。日历条目名称可以包含字母、数字、句点、短划线和下划线。名称应该足够具体，以便一目了然地确定日历条目的用途。例如，**support-off-hours**。创建日历条目后，您将无法更新此名称。
1. （可选）对于 **Description**（描述），输入日历条目的描述。
1. （可选）在 **Import calendar (导入日历)** 区域中，选择 **Choose file (选择文件)**，以选择您从第三方日历提供程序导出的 iCalendar (`.ics`) 文件。导入该文件会将其事件添加到您的日历中。
受支持的提供程序包括 Google 日历、Microsoft Outlook 和 iCloud 日历。
有关更多信息，请参阅 [从第三方日历提供程序导入事件](change-calendar-import.md)。
1. 在 **Calendar type (日历类型)** 中，选择以下选项之一。
+ **Open by default (预设情况下打开)** - 日历处于打开状态（自动化操作可以运行，直到事件开始），然后在关联事件的持续时间内关闭。
+ **Closed by default (预设情况下关闭)** - 日历处于关闭状态（自动化操作无法运行，直到事件开始），但在关联事件的持续时间内打开。
1. （可选）在**变更管理事件**中，选择**向日历添加变更管理事件**。此选项会在您的月度日历显示中显示所有的计划维护时段、State Manager 关联、自动化工作流程和 Change Manager 变更请求。
**提示**
如果稍后要从日历显示中永久移除这些事件类型，请编辑日历，清除此复选框，然后选择**保存**。
1. 选择 **Create calendar（创建日历）**。
创建日历条目后，Systems Manager 将在 **Change Calendar** 列表中显示您的日历条目。列显示日历版本和日历拥有者的 AWS 账户 编号。在创建或导入至少一个事件之前，您的日历条目无法阻止或允许任何操作。有关创建事件的信息，请参阅 [创建Change Calendar 事件](change-calendar-create-event.md)。有关导入事件的信息，请参阅 [从第三方日历提供程序导入事件](change-calendar-import.md)。
# 在 Change Calendar 中创建和管理事件
在 AWS Systems Manager Change Calendar 中创建日历后，可以创建、更新和删除打开或关闭的日历中包含的事件。Change Calendar 是 AWS Systems Manager 中的一项工具。
**提示**
作为直接在 Systems Manager 控制台中创建事件的替代方法，您可以从受支持的第三方日历应用程序导入 iCalendar (`.ics`) 文件。有关信息，请参阅[导入和管理来自第三方日历的事件](third-party-events.md)。
**Topics**
+ [创建Change Calendar 事件](change-calendar-create-event.md)
+ [更新 Change Calendar 事件](change-calendar-update-event.md)
+ [删除 Change Calendar 事件](change-calendar-delete-event.md)
# 创建Change Calendar 事件
在向 Change Calendar（AWS Systems Manager 中的一项工具）中的条目添加事件时，您要指定暂停日历条目默认操作的时间段。例如，如果日历条目类型为预设情况下关闭，则日历在事件期间可以更改。（或者，您可以创建一个咨询活动，该活动仅在日历上发挥信息作用。）
目前，您只能使用控制台创建 Change Calendar 事件。事件将添加到您在创建 Change Calendar 条目时创建的 Change Calendar 文档中。
**创建 Change Calendar 事件**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Change Calendar**。
1. 在日历的列表中，请选择要向其添加事件的日历条目的名称。
1. 在日历条目的详细信息页面上，选择 **Create event (创建事件)**。
1. 在 **Create scheduled event (创建计划事件)** 页面的 **Event details (事件详细信息)** 中，输入事件的显示名称。事件名称可以包含字母、数字、句点、短划线和下划线。名称应该足够具体，以便确定事件的用途。例如，**nighttime-hours**。
1. 对于 **Description**（描述），输入事件的描述。例如，**The support team isn't available during these hours**。
1. （可选）如果您希望此事件仅作为视觉通知或提醒，请选择 **Advisory**（咨询）复选框。咨询事件在您的日历上不起任何功能作用。它们仅为查看日历的用户提供信息。
1. 对于 **Event start date**（事件开始日期），以 `MM/DD/YYYY` 格式输入或选择开始事件的日期，并以 `hh:mm:ss` 格式（小时、分钟和秒）输入在指定日期开始事件的时间。
1. 对于 **Event end date**（事件结束日期），以 `MM/DD/YYYY` 格式输入或选择结束事件的日期，并以 `hh:mm:ss` 格式（小时、分钟和秒）输入在指定日期结束事件的时间。
1. 在 **Schedule time zone**（计划时区）中，选择应用于事件开始和结束时间的时区。您可以输入城市名称或不同于格林威治标准时间 (GMT) 的时区的一部分，以便更快地查找时区。默认值为协调世界时 (UTC)。
1. （可选）要创建每天、每周或每月重复的事件，请启用 **Recurrence**（重复），然后指定重复的频率和可选的结束日期。
1. 选择 **Create scheduled event (创建计划事件)**。新事件将添加到您的日历条目中，并显示在日历条目详细信息页面的 **Events (事件)** 选项卡上。
# 更新 Change Calendar 事件
按照以下过程在 AWS Systems Manager 控制台中更新 Change Calendar 事件。Change Calendar 是 AWS Systems Manager 中的一项工具。
**更新 Change Calendar 事件**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Change Calendar**。
1. 在日历的列表中，请选择要编辑其事件的日历条目的名称。
1. 在日历条目的详细信息页面上，选择 **Events (事件)**。
1. 在日历页面中，选择要编辑的事件。
**提示**
使用左上角的按钮可向后或向前移动一年，或者向后或向前移动一个月。如果需要，请通过从右上角的列表中选择正确的时区来更改时区。
1. 在 **Event details**（事件详细信息）中，请选择 **Edit**（编辑）。
要更改事件名称和描述，请添加或替换当前文本值。
1. 要更改 **Event start date**（事件开始日期）值，请选择当前的开始日期，然后从日历中选择一个新日期。要更改开始时间，请选择当前开始时间，然后从列表中选择一个新时间。
1. 要更改 **Event end date**（事件结束日期）值，请选择当前日期，然后从日历中选择一个新的结束日期。要更改结束时间，请选择当前结束时间，然后从列表中选择一个新时间。
1. 要更改 **Schedule time zone**（计划时区）值，请选择应用于事件开始和结束时间的时区。您可以输入城市名称或不同于格林威治标准时间 (GMT) 的时区的一部分，以便更快地查找时区。默认值为协调世界时 (UTC)。
1. （可选）如果您希望此事件仅作为视觉通知或提醒，请选择 **Advisory**（咨询）复选框。咨询事件在您的日历上不起任何功能作用。它们仅为查看日历的用户提供信息。
1. 选择**保存**。您的更改将显示在日历条目详细信息页面的 **Events (事件)** 选项卡上。选择您更新的事件以查看更改。
# 删除 Change Calendar 事件
您可以使用 AWS 管理控制台，在 Change Calendar（AWS Systems Manager 中的一项工具）中逐个删除事件。
**提示**
如果您在创建日历时选择了**向日历添加变更管理事件**，则可以执行以下操作：
要在日历显示中*暂时*隐藏变更管理事件类型，请为每月预览顶部的类型选择 **X**。
要从日历显示中*永久*移除这些类型，请编辑日历，清除**向日历添加变更管理事件**复选框，然后选择**保存**。从日历显示中移除类型并不会将其从您的账户中删除。
**删除 Change Calendar 事件**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Change Calendar**。
1. 在日历的列表中，请选择要删除其事件的日历条目的名称。
1. 在日历条目的详细信息页面上，选择 **Events (事件)**。
1. 在日历页面中，选择要删除的事件。
**提示**
使用左上角的按钮可将日历向后或向前移动一年，或者向后或向前移动一个月。如果需要，请通过从右上角的列表中选择正确的时区来更改时区。
1. 在 **Event details (事件详细信息)** 页面上，选择 **Delete (删除)**。当系统提示您确认是否要删除该事件时，请选择 **Confirm**（确认）。
# 导入和管理来自第三方日历的事件
作为直接在 AWS Systems Manager 控制台中，创建事件的替代方法，您可以从受支持的第三方日历应用程序导入 iCalendar (`.ics`) 文件。日历可以同时包含导入的事件和您在 Change Calendar（AWS Systems Manager 中的一项工具）中创建的事件。
**开始前的准备工作**
在尝试导入日历文件之前，请查看以下要求和约束：
日历文件格式
只支持有效的 iCalendar 文件 (`.ics`)。
受支持的日历提供程序
仅支持从以下第三方日历提供程序导出的 `.ics` 文件：
+ Google 日历（[导出说明](https://support.google.com/calendar/answer/37111)）
+ Microsoft Outlook（[导出说明](https://support.microsoft.com/en-us/office/export-an-outlook-calendar-to-google-calendar-662fa3bb-0794-4b18-add8-9968b665f4e6)）
+ iCloud 日历（[导出指令](https://support.apple.com/guide/calendar/import-or-export-calendars-icl1023/mac)）
文件大小
您可以导入任意数量的有效 `.ics` 文件。但是，每个日历的所有导入文件的总大小不能超过 64KB。
要最小化 `.ics` 文件的大小，请确保只导出有关日历条目的基本详细信息。如有必要，请减少用于导出的时间段的长度。
时区
除了日历名称、日历提供程序和至少一个事件之外，导出的 `.ics` 文件还应指明日历的时区。如果没有，或者在确定时区时出现问题，系统将在您导入文件后提示您指定一个时区。
重复性事件限制
您导出的 `.ics` 文件可以包含重复性事件。但是，如果曾在源日历中删除过某一重复性事件的一次或多次发生，则导入将失败。
**Topics**
+ [从第三方日历提供程序导入事件](change-calendar-import.md)
+ [更新来自第三方日历提供程序的所有事件](change-calendar-import-add-remove.md)
+ [删除从第三方日历导入的所有事件](change-calendar-delete-ics.md)
# 从第三方日历提供程序导入事件
可以使用以下过程从受支持的第三方日历应用程序导入 iCalendar (`.ics`) 文件。该文件中包含的事件将合并到您打开或关闭的日历的规则中。您可以将文件导入自己使用 Change Calendar（AWS Systems Manager 中的一项工具）创建的新日历或现有日历。
导入 `.ics` 文件后，可以使用 Change Calendar 界面从该文件中删除单个事件。有关信息，请参阅[删除 Change Calendar 事件](change-calendar-delete-event.md)。您还可以通过删除 `.ics` 文件，来删除源日历中的所有事件。有关信息，请参阅[删除从第三方日历导入的所有事件](change-calendar-delete-ics.md)。
**从第三方日历提供程序导入事件**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Calendar**。
1. 要从新日历开始，请选择 **Create calendar (创建日历)**。在 **Import calendar (导入日历)** 区域中，选择 **Choose file (选择文件)**。有关创建新日历的其他步骤的信息，请参阅 [创建更改日历](change-calendar-create.md)。
–或者–
要将第三方事件导入到现有日历中，请选择现有日历的名称，以将其打开。
1. 请选择 **Actions, Edit**（操作、编辑），然后在 **Import calendar**（导入日历）区域中，请选择 **Choose file**（选择文件）。
1. 在您的本地计算机上，导航到已导出的 `.ics` 文件，并选择该文件。
1. 如果出现提示，对于 **Select a time zone (选择时区)**，请选择哪一个时区适用于该日历。
1. 选择**保存**。
# 更新来自第三方日历提供程序的所有事件
如果在导入源日历的 iCalendar `.ics` 文件后，向源日历中添加了多个事件，或从其中删除了多个事件，则可以将这些更改反映在 Change Calendar 中。首先，重新导出源日历，再将新文件导入 Change Calendar（AWS Systems Manager 中的一项工具）。更改日历中的事件将被更新，以反映较新文件的内容。
**更新来自第三方日历提供程序的所有事件**
1. 在您的第三方日历中，只要您希望将某些事件反映在 Change Calendar 中，即可添加或删除这些事件，然后将该日历重新导出到新 `.ics` 文件。
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Calendar**。
1. 从日历列表中，选择日历名称。
1. 选择**选择文件**，然后导航到替换 `.ics` 文件，并选择该文件。
1. 为了响应有关覆盖现有文件的通知，请选择 **Confirm (确认)**。
# 删除从第三方日历导入的所有事件
如果您不再希望将从第三方提供程序导入的任何事件包含在日历中，则可删除已导入的 iCalendar `.ics` 文件。
**删除从第三方日历导入的所有事件**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Calendar**。
1. 从日历列表中，选择日历名称。
1. 在 **Import calendar (导入日历)** 区域中的 **My imported calendars (我导入的日历)** 下，找到导入日历的名称，然后选择其卡片中的 **X**。
1. 选择**保存**。
# 更新更改日历
您可以更新更改日历的描述，但不能更新其名称。尽管您可以更改日历的默认状态，但请注意，这会反转更改操作在与该日历关联的事件期间的行为。例如，如果您将日历的状态从 **Open by default (预设情况下打开)** 更改为 **Closed by default (预设情况下关闭)**，则当创建了关联事件的用户不希望进行更改时，可能会在事件期间发生不希望的更改。
在更新更改日历时，您要编辑在创建该条目时创建的 Change Calendar 文档。Change Calendar 是 AWS Systems Manager 中的一项工具。
**更新更改日历**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Change Calendar**。
1. 在日历的列表中，请选择要更新的日历的名称。
1. 在日历的详细信息页面上，请选择 **Actions, Edit**（操作、编辑）。
1. 在 **Description (描述)** 中，您可以更改描述文本。您不能编辑更改日历的名称。
1. 要更改日历状态，请在 **Calendar type (日历类型)** 中选择其他值。请注意，这会反转更改操作在与该日历关联的事件期间的行为。在更改日历类型之前，您应与其他 Change Calendar 用户验证并确保更改日历类型不会在其已创建的事件期间导致不希望的更改。
+ **Open by default (预设情况下打开)** - 日历处于打开状态（自动化操作可以运行，直到事件开始），然后在关联事件的持续时间内关闭。
+ **Closed by default (预设情况下关闭)** - 日历处于关闭状态（自动化操作无法运行，直到事件启动），但在关联事件的持续时间内打开。
1. 选择**保存**。
在至少添加一个事件之前，您的日历无法阻止或允许任何操作。有关如何添加事件的信息，请参阅 [创建Change Calendar 事件](change-calendar-create-event.md)。
# 共享更改日历
您可以使用 AWS Systems Manager 控制台，在 Change Calendar（AWS Systems Manager 中的一项工具）中与其他 AWS 账户共享日历。共享日历时，日历对于共享账户中的用户为只读。维护时段、State Manager 关联和自动化不会共享。
**共享更改日历**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Change Calendar**。
1. 在日历的列表中，请选择要共享的日历的名称。
1. 在日历的详细信息页面上，请选择 **Sharing**（共享）选项卡。
1. 依次选择 **Actions, Share**（操作、共享）。
1. 在 **Share calendar (共享日历)** 中，对于 **Account ID (账户 ID)**，输入有效 AWS 账户 的 ID 号，然后选择 **Share (共享)**。
共享账户的用户可以读取更改日历，但他们不能进行更改。
# 删除更改日历
您可以使用 Systems Manager 控制台或 AWS Command Line Interface（AWS CLI），在 Change Calendar（AWS Systems Manager 中的一项工具）中删除日历。删除更改日历会删除所有关联的事件。
**删除更改日历**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择 **Change Calendar**。
1. 在日历的列表中，请选择要删除的日历的名称。
1. 在日历的详细信息页面上，请选择 **Actions, Delete**（操作、删除）。当系统提示您确认是否要删除日历时，选择 **Delete (删除)**。
# 获取更改日历的状态
您可以在 Change Calendar（AWS Systems Manager 中的一项工具）中获取日历的整体状态或者日历在特定时间的状态。您还可以显示日历状态下次从 `OPEN` 更改为 `CLOSED`（或反之）的时间。
**注意**
有关将 Change Calendar 与 Amazon EventBridge 集成以自动监控日历状态变化的信息，请参阅[Change Calendar 与 Amazon EventBridge 集成](monitoring-systems-manager-event-examples.md#change-calendar-eventbridge-integration)。EventBridge 集成在日历状态转换时提供事件驱动的通知，补充基于轮询的 `GetCalendarState` API 操作方法。
您只能使用 `GetCalendarState` API 操作完成此任务。本节中的过程使用 AWS Command Line Interface (AWS CLI)。
**获取更改日历的状态**
+ 运行以下命令，以显示一个或多个日历在特定时间的状态。`--calendar-names` 参数是必需项，但 `--at-time` 是可选项。将每个*示例资源占位符*替换为您自己的信息。
------
#### [ Linux & macOS ]
```
aws ssm get-calendar-state \
--calendar-names "Calendar_name_or_document_ARN_1" "Calendar_name_or_document_ARN_2" \
--at-time "ISO_8601_time_format"
```
示例如下：
```
aws ssm get-calendar-state \
--calendar-names "arn:aws:ssm:us-east-2:123456789012:document/MyChangeCalendarDocument" "arn:aws:ssm:us-east-2:123456789012:document/SupportOffHours" \
--at-time "2020-07-30T11:05:14-0700"
```
------
#### [ Windows ]
```
aws ssm get-calendar-state ^
--calendar-names "Calendar_name_or_document_ARN_1" "Calendar_name_or_document_ARN_2" ^
--at-time "ISO_8601_time_format"
```
示例如下：
```
aws ssm get-calendar-state ^
--calendar-names "arn:aws:ssm:us-east-2:123456789012:document/MyChangeCalendarDocument" "arn:aws:ssm:us-east-2:123456789012:document/SupportOffHours" ^
--at-time "2020-07-30T11:05:14-0700"
```
------
此命令会返回如下信息。
```
{
"State": "OPEN",
"AtTime": "2020-07-30T16:18:18Z",
"NextTransitionTime": "2020-07-31T00:00:00Z"
}
```
结果显示指定日历条目（由您的账户拥有或与您的账户共享）在 `--at-time` 的值所指定时间的日历状态（无论日历的类型为 `DEFAULT_OPEN` 还是 `DEFAULT_CLOSED`），以及下一次转换的时间。如果您不添加 `--at-time` 参数，则使用当前时间。
**注意**
如果在一个请求中指定了多个日历，则仅当该请求中的所有日历都处于打开状态时，该命令才会返回 `OPEN` 的状态。如果该请求中的一个或多个日历处于关闭状态，则返回的状态为 `CLOSED`。
# 向自动化运行手册添加 Change Calendar 依赖关系
要让 Automation 操作遵循 Change Calendar（AWS Systems Manager 中的一项工具），请在使用 [`aws:assertAwsResourceProperty`](automation-action-assertAwsResourceProperty.md) 操作的 Automation 运行手册中添加一个步骤。将该操作配置为运行 `GetCalendarState` 以验证指定的日历条目是否处于所需状态（`OPEN` 或 `CLOSED`）。只有在日历状态为 `OPEN` 时才允许自动化运行手册继续执行下一步。以下是基于 YAML 的示例，摘录了只有当日历状态与在 `DesiredValues` 中指定的状态 `OPEN` 匹配时，才能继续到下一步 `LaunchInstance` 的自动化运行手册。
示例如下：
```
mainSteps:
- name: MyCheckCalendarStateStep
action: 'aws:assertAwsResourceProperty'
inputs:
Service: ssm
Api: GetCalendarState
CalendarNames: ["arn:aws:ssm:us-east-2:123456789012:document/SaleDays"]
PropertySelector: '$.State'
DesiredValues:
- OPEN
description: "Use GetCalendarState to determine whether a calendar is open or closed."
nextStep: LaunchInstance
- name: LaunchInstance
action: 'aws:executeScript'
inputs:
Runtime: python3.11
...
```
# 排除 Change Calendar 问题
利用以下信息，帮助排查Change Calendar（AWS Systems Manager 中的一项工具）出现的问题。
**Topics**
+ [“Calendar import failed (日历导入失败)”错误](#change-manager-troubleshooting-1)
## “Calendar import failed (日历导入失败)”错误
**问题**：在导入 iCalendar (`.ics`) 文件时，系统报告日历导入失败。
+ **解决方案 1** – 确保您导入的是从受支持的第三方日历提供程序导出的文件，受支持的第三方日历提供程序包括以下几个：
+ Google 日历（[导出说明](https://support.google.com/calendar/answer/37111)）
+ Microsoft Outlook（[导出说明](https://support.microsoft.com/en-us/office/export-an-outlook-calendar-to-google-calendar-662fa3bb-0794-4b18-add8-9968b665f4e6)）
+ iCloud 日历（[导出指令](https://support.apple.com/guide/calendar/import-or-export-calendars-icl1023/mac)）
+ **解决方案 2** – 如果源日历包含任何重复性事件，请确保没有取消或删除该事件的任何一次发生。目前，Change Calendar 不支持导入发生单次取消的重复性事件。要解决该问题，请从源日历中删除重复性事件，重新导出日历，再将该日历重新导入到 Change Calendar 中，然后使用 Change Calendar 界面添加该重复性事件。有关信息，请参阅[创建Change Calendar 事件](change-calendar-create-event.md)。
+ **解决方案 3** – 确保源日历至少包含一个事件。上载 `.ics` 不包含事件的文件不会成功。
+ **解决方案 4** – 如果系统报告导入因 `.ics` 过大而失败，请确保只导出有关日历条目的基本详细信息。如有必要，请减少用于导出的时间段的长度。
+ **解决方案 5** – 如果 Change Calendar 无法确定您导出的日历的时区，则当您尝试从 **Events (事件)** 选项卡中导入该日历时，您可能会收到以下消息：“Calendar import failed. Change Calendar couldn't locate a valid time zone.（日历导入失败，找不到有效时区。） 您可以从 Edit (编辑) 菜单中导入该日历。在本例中，请选择 **Actions (操作)、Edit (编辑)**，然后尝试从 **Edit calendar (编辑日历)** 页面导入该文件。
+ **解决方案 6** – 请勿编辑 `.ics` 文件，然后再导入。尝试修改文件的内容可能会损坏日历数据。如果您在尝试导入之前修改了文件，则请再次从源日历导出日历，然后重新尝试上载。
# AWS Systems Manager Change Manager
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
Change Manager（AWS Systems Manager 中的一项工具）是一个企业变更管理框架，用于请求、批准、实施和报告应用程序配置及基础设施的操作变更。如果您使用 AWS Organizations，可从单个*委托管理员账户*管理多个 AWS 账户 和整个 AWS 区域中的更改。或者，也可使用*本地账户*管理单个 AWS 账户 的更改。使用 Change Manager 可管理对 AWS 资源和本地部署资源的变更。要开始使用 Change Manager，请打开 [Systems Manager 控制台](https://console.aws.amazon.com//systems-manager/change-manager)。在导航窗格中，请选择 **Change Manager**。
借助 Change Manager，您可以使用预先批准的*更改模板*，帮助自动完成对资源的更改过程，并帮助避免在进行操作更改时出现意外结果。每个更改模板指定以下内容：
+ 在创建更改请求时，有一个或多个自动化运行手册可供用户选择。对您的资源进行的更改将在自动化 Runbook 中定义。您可以将自定义运行手册或 [AWS 托管运行手册](automation-documents-reference.md)包含在您创建的更改模板中。当用户创建更改请求时，他们可以选择要在该请求中包含哪一个可用的运行手册。此外，您还可以创建更改模板，让提出请求的用户在更改请求中指定任何运行手册。
+ 账户中的用户，必须审核使用该更改模板提出的更改请求。
+ Amazon Simple Notification Service (Amazon SNS) 主题，用于通知指定审批人员，更改请求已准备好进行审核。
+ Amazon CloudWatch 告警，用于监控运行手册工作流。
+ Amazon SNS 主题，用于针对使用更改模板创建的更改请求，发送有关状态变化的通知。
+ 要应用于更改模板的标签，用于对更改模板进行分类和筛选。
+ 是否可以在没有批准步骤的情况下运行从更改模板创建的更改请求（自动批准的请求）。
通过与 Systems Manager 中的另一项工具 Change Calendar 集成，Change Manager 还可以帮助您安全地实施更改，同时避免计划与重要业务事件发生冲突。Change Manager 与 AWS Organizations 和 AWS IAM Identity Center 集成，可帮助您使用现有的身份管理系统从单个账户管理整个组织中的更改。您可以从 Change Manager 监控更改进度，并审核整个组织中的操作更改，从而提高可见性、改善问责制。
Change Manager 为您的[持续集成](https://aws.amazon.com/devops/continuous-integration) (CI) 实践和[持续交付](https://aws.amazon.com/devops/continuous-delivery) (CD) 方法补充了安全控制措施。Change Manager 不适用于作为自动发布流程（例如 CI/CD 管道）的组成部分进行的更改，除非存在例外情况，或者需要批准。
## Change Manager 的工作原理
在确定需要标准或紧急操作更改时，组织中的某个人员会根据为在您的组织或账户中使用而创建的更改模板之一创建更改请求。
如果请求的更改需要手动批准，Change Manager 将通过 Amazon SNS 通知来通知指定的审批人员，更改请求已准备好供其审核。您可以在更改模板中为更改请求指定审批者，也可以让用户在更改请求本身中指定审批者。您可以将不同的审核人员分配给不同的模板。例如，分配一个用户、用户组或 AWS Identity and Access Management (IAM) 角色，他们必须批准对托管式节点的更改请求；而对数据库更改，则分配另一个用户、组或 IAM 角色。如果更改模板允许自动审批，并且请求者的用户策略不禁止它，则用户还可以选择为其请求运行自动化运行手册，而无需审核步骤（更改冻结事件除外）。
对于每个更改模板，您可以添加最多五个级别的审批人员。例如，您可能要求技术审核人员先批准根据更改模板创建的更改请求，然后需要一个或多个经理的第二级批准。
Change Manager 已与 [AWS Systems Manager Change Calendar](systems-manager-change-calendar.md) 集成。当请求的更改获得批准后，系统将首先确定该请求是否与其他已计划的业务活动冲突。如果检测到冲突，Change Manager 可以阻止更改，或在启动运行手册工作流之前要求进行额外批准。例如，您可能只允许在工作时间进行更改，以确保团队可以管理任何意外问题。对于请求在上述时间以外运行的任何更改，您可以要求更高级别的管理人员以*更改冻结审批人员*的形式批准。对于紧急更改，Change Manager 可以跳过检查 Change Calendar 是否存在冲突或在批准更改请求后阻止事件的步骤。
当需要实施已批准的更改时，Change Manager 将运行在关联的更改请求中指定的自动化运行手册。在运行手册工作流运行时，只允许在已批准的更改请求中定义的操作。这种方法有助于您避免在实施更改时出现意外结果。
除了限制在运行手册工作流运行时可以进行的更改之外，Change Manager 还可以帮助您控制并发和错误阈值。您可以选择运行手册工作流一次可在多少个资源上运行，更改一次可在多少个账户中运行，以及在停止流程和（如果运行手册包含回滚脚本）回滚之前允许多少次故障。您还可以使用 CloudWatch 告警监控正在进行的更改的进度。
运行手册工作流完成后，您可以查看有关所做更改的详细信息。这些详细信息包括更改请求的原因、使用的更改模板、请求和批准更改的人员，以及更改的实施方式。
**更多信息**
在 *AWS 新闻博客*上[介绍 AWS Systems ManagerChange Manager](https://aws.amazon.com/blogs/aws/introducing-systems-manager-change-manager/)
## 我的操作如何从 Change Manager 获益？
Change Manager 具有以下优势：
+ **降低服务中断和停机风险**
Change Manager 可以确保在运行手册工作流运行时，仅实施已批准的更改，从而使操作更改更安全。您可以阻止计划外和未经审核的更改。Change Manager 可以帮助您避免由于人为错误导致的多种类型的意外结果，这些结果需要花费宝贵时间进行研究和回溯。
+ **获取更改历史记录的详细审核和报告**
Change Manager 提供了一种一致的问责制方法，用于报告和审核在整个组织中所做的更改、更改的目的，以及与批准和实施这些更改的人员有关的详细信息。
+ **避免计划冲突或违规**
Change Manager 可以根据您的组织的活动更改日历来检测计划冲突，例如假日事件或新产品上市。您可以允许运行手册工作流仅在工作时间运行，也可以仅在获得额外批准的情况下才允许它们运行。
+ **使更改要求适应不断变化的业务**
在不同的业务期间，您可以实施不同的更改管理要求。例如，在月末报告、纳税季节或其他关键业务期间，您可以阻止更改，或对可能带来不必要的运营风险的更改要求董事级批准。
+ **集中管理多个账户的更改**
通过与 Organizations 集成，Change Manager 使您可以通过单个委托管理员账户管理所有组织单位 (OU) 中的更改。您可以启用 Change Manager，与您的整个组织一起使用，也可以仅与您的部分 OU 一起使用。
## 谁应该使用 Change Manager？
Change Manager 适用于以下 AWS 客户和组织：
+ 任何希望改善对其云环境或本地环境所做操作更改的安全性和治理性的 AWS 客户。
+ 希望提高多个团队间的协作和可见性，通过避免停机提高应用程序可用性，以及降低与手动和重复性任务相关的风险的组织。
+ 必须遵循更改管理的最佳做法的组织。
+ 对于其应用程序配置和基础设施所做的更改，需要完全可审核的历史记录的客户。
## Change Manager 的主要功能是什么？
Change Manager 包含以下主要功能：
+ **对更改管理最佳做法的综合支持**
借助 Change Manager，您可以将所选择的更改管理最佳做法应用于您的操作。您可以选择启用选项：
+ 检查 Change Calendar，以查看事件当前是否受到限制，以便仅在已打开日历期间进行更改。
+ 在获得更改冻结审批人员额外批准的情况下，允许在受限事件期间进行更改。
+ 要求为所有更改模板指定 CloudWatch 告警。
+ 要求在您的账户中创建的所有更改模板经过审核和批准，然后才能使用它们创建更改请求。
+ **针对已关闭日历期间和紧急更改请求的不同批准路径**
您可以允许一个选项来检查受限事件的 Change Calendar，并阻止已批准的更改请求，直到事件完成为止。但是，您也可以指定第二组审批人员，即更改冻结审批人员，即使日历已关闭，他们也可以允许进行更改。您还可以创建紧急更改模板。从紧急更改模板创建的更改请求仍然需要常规批准，但不受日历限制的约束，也不需要更改冻结批准。
+ **控制如何以及何时开始运行手册工作流**
运行手册工作流可以根据计划开始，也可以在批准完成后立即开始（受日历限制规则约束）。
+ **内置通知支持**
指定您的组织中应该审核和批准更改模板及更改请求的人员。将 Amazon SNS 主题分配给更改模板，以便向该主题的订阅者发送与使用该更改模板创建的更改请求的状态变化有关的通知。
+ **与 AWS Systems Manager Change Calendar 集成**
Change Manager 允许管理员限制在指定时间段内的计划更改。例如，您可以创建一个策略，该策略仅允许在工作时间进行更改，以确保团队有时间处理任何问题。您还可以在重要业务活动期间限制更改。例如，零售业务可在大型销售活动期间限制更改。您还可以在受限时段期间内要求获得额外批准。
+ **与 AWS IAM Identity Center 和 Active Directory 支持集成**
借助 IAM Identity Center 集成，您的组织成员可以访问 AWS 账户，并使用 Systems Manager 基于通用用户身份管理其资源。使用 IAM Identity Center，您可以分配对整个 AWS 中账户的用户访问权限。
通过与 Active Directory 集成，可以指定 Active Directory 账户中的用户担任为 Change Manager 操作创建的更改模板的审批人员。
+ **与 Amazon CloudWatch 告警集成**
Change Manager 与 CloudWatch 告警集成。Change Manager 可在运行手册工作流期间侦听 CloudWatch 告警，并执行为相应告警定义的任何操作，包括发送通知。
+ **与 AWS CloudTrail Lake 集成**
通过在 AWS CloudTrail Lake 中创建事件数据存储，您可以查看有关您的账户或组织中运行的变更请求所做更改的可审批信息。存储的事件信息包括以下详细信息：
+ 运行的 API 操作
+ 这些操作所包含的请求参数
+ 运行该操作的用户
+ 在此过程中更新的资源
+ **与 AWS Organizations 集成**
使用 Organizations 提供的跨账户功能，您可以使用委托管理员账户来管理您的组织内 OU 中的 Change Manager 操作。在您的 Organizations 管理账户中，可以指定哪个账户作为委托管理员账户。您还能够控制可在您的哪些 OU 中使用 Change Manager。
## 使用 Change Manager 是否需要收取费用？
是的。Change Manager 是按使用量付费的。您仅需按实际用量付费。有关更多信息，请参阅 [AWS Systems Manager 定价](https://aws.amazon.com/systems-manager/pricing/)。
## Change Manager 的主要组件是什么？
用于管理组织或账户中的更改过程的 Change Manager 组件包括以下内容：
### 委托管理员账户
如果您在整个组织中使用 Change Manager，则将使用委托管理员账户。此 AWS 账户被指定为管理包括 Change Manager 在内的整个 Systems Manager 中的操作活动的账户。委托管理员账户可以管理整个组织中的更改活动。在将组织设置为使用 Change Manager 时，可以指定您的哪些账户以此角色提供服务。委托管理员账户必须是其分配到的组织单位 (OU) 的唯一成员。如果您仅将 Change Manager 用于单个AWS 账户，则不需要委托管理员账户。
**重要**
如果您在整个组织中使用 Change Manager，我们建议始终从委托管理员账户进行更改。虽然您可以从组织中的其他账户进行更改，但这些更改不会在委派管理员账户中报告，也无法从该账户查看。
### 更改模板
更改模板是 Change Manager 中的一个配置设置集合，它定义了所需的批准、可用的运行手册和更改请求的通知选项等内容。
您可以要求您的组织或账户中的用户创建的更改模板经过批准流程，然后才能使用这些模板。
Change Manager 支持两种类型的更改模板。对于基于*紧急更改模板*，请求的更改可以进行，即使在 Change Calendar。对于基于*标准更改模板*，则无法进行请求的更改，如果 Change Calendar 除非收到指定的额外批准*更改冻结事件*审批。
### 更改请求
更改请求是 Change Manager 中的一个请求，旨在运行更新您的 AWS 或本地环境中一个或多个资源的自动化运行手册。更改请求是使用更改模板创建的。
在创建更改请求时，您的组织或账户中的一个或多个审批人员必须审核和批准该请求。如果没有获得所需的批准，则不允许运行应用您请求的更改的运行手册工作流。
在系统中，更改请求是 AWS Systems Manager OpsCenter 中一种类型的 OpsItem。不过，`/aws/changerequest` 类型的 OpsItems 不会显示在 OpsCenter 中。作为 OpsItems，更改请求与其他类型的 OpsItems 一样，也受相同强制配额的约束。
此外，要以编程方式创建更改请求，不能调用 `CreateOpsItem` API 操作，而应使用 `[https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html)` API 操作。但必须先批准更改请求，而不能立即运行，并且 Change Calendar 中不能有任何阻止性事件阻碍工作流运行。当收到批准并且日历未被阻止（或者已经获得绕过阻止性日历事件的权限）时，`StartChangeRequestExecution` 操作才能完成。
### 运行手册工作流
运行手册工作流是对您的云环境或本地环境中的目标资源进行所请求的更改的过程。每个更改请求都将指定一个自动化运行手册，用于进行所请求的更改。在获得所有所需的批准后，并且 Change Calendar 中不存在阻止性事件的情况下，运行手册工作流才能发生。如果已为特定日期和时间安排更改，即便已经获得所有批准并且日历未被阻止，运行手册工作流也将在到达计划时间后才会开始。
**Topics**
+ [Change Manager 的工作原理](#how-change-manager-works)
+ [我的操作如何从 Change Manager 获益？](#change-manager-benefits)
+ [谁应该使用 Change Manager？](#change-manager-who)
+ [Change Manager 的主要功能是什么？](#change-manager-features)
+ [使用 Change Manager 是否需要收取费用？](#change-manager-cost)
+ [Change Manager 的主要组件是什么？](#change-manager-primary-components)
+ [设置 Change Manager](change-manager-setting-up.md)
+ [使用 Change Manager](working-with-change-manager.md)
+ [审计和记录 Change Manager 活动](change-manager-auditing.md)
+ [排除 Change Manager 问题](change-manager-troubleshooting.md)
# 设置 Change Manager
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
您可以使用 Change Manager（AWS Systems Manager 中的一项工具）来管理对整个组织的更改（按照 AWS Organizations 中的配置）或对单个 AWS 账户的更改。
如果您将 Change Manager 用于组织，请从主题 [为组织设置 Change Manager（管理账户）](change-manager-organization-setup.md) 开始，然后继续阅读 [配置 Change Manager 选项和最佳实践](change-manager-account-setup.md)。
如果您将 Change Manager 用于单个账户，则请直接阅读 [配置 Change Manager 选项和最佳实践](change-manager-account-setup.md)。
**注意**
如果您首先将 Change Manager 用于某一单个账户，而后来又将该账户添加到允许 Change Manager 的组织单位，则您的单个账户设置将被忽略。
**Topics**
+ [为组织设置 Change Manager（管理账户）](change-manager-organization-setup.md)
+ [配置 Change Manager 选项和最佳实践](change-manager-account-setup.md)
+ [为 Change Manager 配置角色和权限](change-manager-permissions.md)
+ [控制对自动批准运行手册工作流的访问](change-manager-auto-approval-access.md)
# 为组织设置 Change Manager（管理账户）
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
如果要将 Change Manager（AWS Systems Manager 中的一项工具）用于在 AWS Organizations 中设置的组织，则本主题中的任务适用。如果您仅要将 Change Manager 用于单个 AWS 账户，则请跳至主题 [配置 Change Manager 选项和最佳实践](change-manager-account-setup.md)。
在充当 Organizations 内*管理账户*的 AWS 账户 中执行本节中的任务。有关管理账户和其他 Organizations 概念的信息，请参阅 [AWS Organizations 术语和概念](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html)。
如果您需要打开 Organizations 并在继续操作之前将您的账户指定为管理账户，请参阅 *AWS Organizations 用户指南*中的[创建和管理组织](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org.html)。
**注意**
此设置过程无法在以下 AWS 区域中执行：
欧洲（米兰）(eu-south-1)
中东（巴林）(me-south-1)
非洲（开普敦）(af-south-1)
亚太地区（香港）(ap-east-1)
对于此过程，请确保您在管理账户中的其他区域工作。
在设置过程中，您要在Quick Setup（AWS Systems Manager 中的一项工具）中执行以下主要任务。
+ **任务 1：为您的组织注册委托管理员账户**
使用 Change Manager 执行的、与更改相关的任务，在您的某一成员账户中进行管理，您将该账户指定为*委托管理员账户*。您为 Change Manager 注册的委托管理员账户，将成为您的所有 Systems Manager 操作的委托管理员账户。（您可以有多个用于其他 AWS 服务 的委托管理员账户。） 您的 Change Manager 委托管理员账户（与管理账户不同）可以管理整个组织的更改活动，包括更改模板、更改请求，以及对每个更改模板和更改请求的批准。在委托管理员账户中，您还可以为 Change Manager 操作指定其他配置选项。
**重要**
委托管理员账户必须是其在 Organizations 中分配到的组织单位 (OU) 的唯一成员。
+ **任务 2：为您要用于 Change Manager 操作的更改请求者角色或自定义工作职能定义和指定运行手册访问策略**
为在 Change Manager 中创建更改请求，则必须向您的成员账户中的用户授予 AWS Identity and Access Management (IAM) 权限，这些权限允许他们仅访问自动化运行手册，以及更改您选择提供给他们的模板。
**注意**
当用户创建更改请求时，他们首先需要选择更改模板。此更改模板可能会提供多个运行手册，但用户只能为每个更改请求选择一个运行手册。还可以将更改模板配置为允许用户在其请求中包含任何可用的运行手册。
要授予所需权限，Change Manager 使用了*工作职能*的概念，IAM 也使用了此概念。但是，与 IAM 中的 [AWS 工作职能托管策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html)不同，您既可以指定 Change Manager 工作职能的名称，也可以为这些工作职能指定 IAM 权限。
在配置工作职能时，我们建议创建自定义策略，并仅提供执行更改管理任务所需的权限。例如，您可以根据定义的*工作职能*指定权限，以限制用户访问特定的运行手册集。
例如，您可以创建名为 `DBAdmin` 的工作职能。对于此工作职能，您可以仅授予与 Amazon DynamoDB 数据库相关的运行手册所需的权限，例如 `AWS-CreateDynamoDbBackup` 和 `AWSConfigRemediation-DeleteDynamoDbTable`。
作为另一个示例，您可能希望仅授予某些用户使用与 Amazon Simple Storage Service (Amazon S3) 存储桶相关的运行手册所需的权限，例如 `AWS-ConfigureS3BucketLogging` 和 `AWSConfigRemediation-ConfigureS3BucketPublicAccessBlock`。
Change Manager 的 Quick Setup 中的配置过程还会为您提供一组完整 Systems Manager 管理权限，以应用于您创建的管理角色。
您部署的每一项 Change Manager Quick Setup 配置，都会在您的委托管理员账户中创建一项工作职能，这些工作职能拥有在您选择的组织单位中运行 Change Manager 模板和自动化运行手册的权限。您最多可以为 Change Manager 创建 15 项 Quick Setup 配置。
+ **任务 3：选择您的组织中哪些成员账户能够使用 Change Manager**
您可以将 Change Manager 用于在 Organizations 中设置的所有组织单位内的所有成员账户，以及所有 AWS 区域（成员账户在其中进行操作）内的所有成员账户。如果愿意，您可以改为仅将 Change Manager 用于您的某些组织单位。
**重要**
在开始此过程之前，我们强烈建议您认真阅读其步骤，以了解您所做的配置选择和所授予的权限。特别是应规划您要创建的自定义工作职能，以及您分配给各项工作职能的权限。这可确保稍后将您创建的工作职能策略附加到各个用户、用户组或 IAM 角色时，仅会向他们授予您希望他们拥有的权限。
作为最佳时间，首先使用 AWS 账户 管理员登录来设置委托管理员账户。然后，在创建更改模板并确定每个更改模板使用的运行手册之后，配置工作职能及其权限。
要设置 Change Manager 以便用于组织，请在 Systems Manager 控制台的 Quick Setup 区域中执行以下任务。
对于要为您的组织创建的每个工作职能，均应重复此任务。您创建的每项工作职能均可拥有针对一组不同组织单位的权限。
**在 Organizations 管理账户中为 Change Manager 设置组织**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Quick Setup**。
1. 在 **Change Manager** 选项卡上，选择 **Create**（创建）。
1. 对于 **Delegated administrator account (委托管理员账户)**，输入要用于在 Change Manager 中管理更改模板、更改请求和运行手册工作流的 AWS 账户 的 ID。
如果您之前已为 Systems Manager 指定了委托管理员账户，则此字段中已报告其 ID。
**重要**
委托管理员账户必须是其在 Organizations 中分配到的组织单位 (OU) 的唯一成员。
如果您注册的委托管理员账户后来从该角色注销，则系统会同时删除其管理 Systems Manager 操作的权限。请注意，您必须返回 Quick Setup，指定不同的委托管理员账户，然后再次指定所有工作职能和权限。
如果您在整个组织中使用 Change Manager，我们建议始终从委托管理员账户进行更改。虽然您可以从组织中的其他账户进行更改，但这些更改不会在委派管理员账户中报告，也无法从该账户查看。
1. 在 **Permissions to request and make changes (请求和进行更改的权限)** 部分中，执行以下操作。
**注意**
您创建的每一项部署配置仅会为一项工作功能提供权限策略。您可以在以后返回到 Quick Setup，在创建要在操作中使用的更改模板时创建更多工作职能。
**创建管理角色** – 对于拥有所有 AWS 操作的 IAM 权限的管理员工作职能，请执行以下操作。
**重要**
授予用户完整管理权限应该谨慎行事，并且仅当用户的角色需要完整的 Systems Manager 访问权限时才能执行。有关 Systems Manager 访问权限的安全注意事项的重要信息，请参阅 [对 AWS Systems Manager 进行身份和访问管理](security-iam.md) 和 [Systems Manager 的安全最佳实践](security-best-practices.md)。
1. 对于 **Job function (工作职能)**，请输入用于标识此角色及其权限的名称，例如 **MyAWSAdmin**。
1. 对于 **Role and permissions option (角色和权限选项)**，请选择 **Administrator permissions (管理员权限)**。
**创建其他工作职能** – 要创建非管理角色，请执行以下操作：
1. 对于 **Job function (工作职能)**，输入用于标识此角色的名称，并建议其权限。您选择的名称应能表示您将为其提供权限的运行手册的范围，例如 `DBAdmin` 或 `S3Admin`。
1. 对于 **Role and permissions option (角色和权限选项)**，请选择 **Custom permissions (自定义权限)**。
1. 在 **Permissions policy editor (权限策略编辑器)** 中，以 JSON 格式输入 IAM 权限，以向此工作职能授予这些权限。
**提示**
我们建议您使用 IAM policy 编辑器构建策略，然后将策略 JSON 粘贴到 **Permissions policy**（权限策略）字段中。
**示例策略：DynamoDB 数据库管理**
例如，您可以从策略内容开始，该内容为使用工作职能需要访问的 Systems Manager 文档（SSM 文档）提供权限。下面是一段示例策略内容，该内容将授予对与 DynamoDB 数据库相关的所有 AWS 托管式自动化运行手册和在位于美国东部（俄亥俄）区域 (`us-east-2`) 的示例 AWS 账户 `123456789012` 中创建的两个更改模板的访问权限。
该策略还包括对 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html) 操作的权限，在 Change Calendar 中创建更改请求时需要该权限。
**注意**
此示例并不全面。可能需要额外的权限才能使用其他 AWS 资源，例如数据库和节点。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:CreateDocument",
"ssm:DescribeDocument",
"ssm:DescribeDocumentParameters",
"ssm:DescribeDocumentPermission",
"ssm:GetDocument",
"ssm:ListDocumentVersions",
"ssm:ModifyDocumentPermission",
"ssm:UpdateDocument",
"ssm:UpdateDocumentDefaultVersion"
],
"Resource": [
"arn:aws:ssm:us-east-1:*:document/AWS-CreateDynamoDbBackup",
"arn:aws:ssm:us-east-1:*:document/AWS-AWS-DeleteDynamoDbBackup",
"arn:aws:ssm:us-east-1:*:document/AWS-DeleteDynamoDbTableBackups",
"arn:aws:ssm:us-east-1:*:document/AWSConfigRemediation-DeleteDynamoDbTable",
"arn:aws:ssm:us-east-1:*:document/AWSConfigRemediation-EnableEncryptionOnDynamoDbTable",
"arn:aws:ssm:us-east-1:*:document/AWSConfigRemediation-EnablePITRForDynamoDbTable",
"arn:aws:ssm:us-east-1:111122223333:document/MyFirstDBChangeTemplate",
"arn:aws:ssm:us-east-1:111122223333:document/MySecondDBChangeTemplate"
]
},
{
"Effect": "Allow",
"Action": "ssm:ListDocuments",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "ssm:StartChangeRequestExecution",
"Resource": [
"arn:aws:ssm:us-east-1:111122223333:document/*",
"arn:aws:ssm:us-east-1:111122223333:automation-execution/*"
]
}
]
}
```
------
有关 IAM policy 的更多信息，请参阅《IAM 用户指南》中的 [AWS 资源的访问权限管理](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html)和[创建 IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。
1. 在 **Targets (目标)** 部分中，请选择是将对您创建的工作职能的权限授予整个组织，还是仅授予部分组织单位。
如果选择 **Entire organization (整个组织)**，请继续执行步骤 9。
如果选择 **Custom (自定义)**，则请继续执行步骤 8。
1. 在 **Target OUs (目标 OU)** 部分中，选中要使用 Change Manager 的组织单位的复选框。
1. 选择 **Create（创建）**。
当系统为您的组织完成 Change Manager 设置后，它将显示您的部署摘要。此摘要信息包含为您配置的工作职能创建的角色的名称。例如 `AWS-QuickSetup-SSMChangeMgr-DBAdminInvocationRole`。
**注意**
Quick Setup 将使用 AWS CloudFormation StackSets 来部署您的配置。您还可以查看有关 CloudFormation 控制台中已完成的部署配置的信息。有关 StackSets 的信息，请参阅 *AWS CloudFormation 用户指南*中的[使用 AWS CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html)。
下一步是配置其他 Change Manager 选项。您可以在您的委托管理员账户或您允许使用 Change Manager 的组织单位内的任何账户中完成此任务。您可以配置多个选项，例如选择用户身份管理选项、指定哪些用户可以审核及批准或拒绝更改模板和更改请求，以及选择允许组织使用哪些最佳实践选项。有关信息，请参阅[配置 Change Manager 选项和最佳实践](change-manager-account-setup.md)。
# 配置 Change Manager 选项和最佳实践
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
无论是在整个组织中还是在单个 AWS 账户中使用 Change Manager（AWS Systems Manager 中的一项工具），都必须执行本节中的任务。
如果您将 Change Manager 用于组织，可以在您的委托管理员账户或您允许使用 Change Manager 的组织单位内的任何账户中执行以下任务。
**Topics**
+ [任务 1：配置 Change Manager 用户身份管理和模板审核人员](#cm-configure-account-task-1)
+ [任务 2：配置 Change Manager 更改冻结事件审批人员和最佳实践](#cm-configure-account-task-2)
+ [为 Change Manager 通知配置 Amazon SNS 主题](change-manager-sns-setup.md)
## 任务 1：配置 Change Manager 用户身份管理和模板审核人员
在首次访问 Change Manager 时，请执行此过程中的该任务。您可以在以后更新这些配置设置，方法是返回到 Change Manager，然后选择 **Settings (设置)** 选项卡上的 **Edit (编辑)**。
**配置 Change Manager 用户身份管理和模板审核人员**
1. 登录到 AWS 管理控制台。
如果您将 Change Manager 用于组织，请使用您的委托管理员账户的凭证登录。用户必须拥有更新 Change Manager 设置的必要 AWS Identity and Access Management（IAM）权限。
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Manager**。
1. 在服务主页上，根据可用选项，执行以下操作之一：
+ 如果您将 Change Manager 用于 AWS Organizations，请选择 **Set up delegated account (设置委托账户)**。
+ 如果您将 Change Manager 用于单个 AWS 账户，请选择 **Set up Change Manager (设置 Change Manager)**。
- 或者 -
选择 **Create sample change request (创建示例更改请求)**、**Skip (跳过)**，然后选择 **Settings (设置)** 选项卡。
1. 对于 **User identity management (用户身份管理)**，请选择以下选项之一。
+ **AWS Identity and Access Management（IAM）**- 确定提出和批准请求以及使用您的现有用户、组和角色在 Change Manager 中执行其他操作的用户的身份。
+ **AWS IAM Identity Center（IAM Identity Center）** – 允许 [IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/) 创建和管理身份，或连接到您的现有身份源，以确定在 Change Manager 中执行操作的用户的身份。
1. 在 **Template reviewer notification**（模板审核人员通知）部分，指定 Amazon Simple Notification Service (Amazon SNS) 主题，这些主题将要用于通知模板审核人员新的更改模板或更改模板版本已准备就绪可供审核。请确保已将您选择的 Amazon SNS 主题配置为向您的模板审核人员发送通知。
有关为更改模板审核人员通知创建和配置 Amazon SNS 主题的信息，请参阅 [为 Change Manager 通知配置 Amazon SNS 主题](change-manager-sns-setup.md)。
1. 要为模板审核人员通知指定 Amazon SNS 主题，请选择以下选项之一：
+ **Enter an SNS Amazon Resource Name (ARN) (输入 SNS Amazon 资源名称 (ARN))** – 对于 **Topic ARN (主题 ARN)**，请输入现有 Amazon SNS 主题的 ARN。此主题可以位于您组织的任何账户中。
+ **Select an existing SNS topic（选择现有 SNS 主题）** – 对于 **Target notification topic（设定通知主题目标）**，选择您当前的 AWS 账户中现有 Amazon SNS 主题的 ARN。（如果您尚未在当前的 AWS 账户 和 AWS 区域 中创建任何 Amazon SNS 主题，则此选项不可用。）
**注意**
您选择的 Amazon SNS 主题必须被配置为指定它所发送的通知，以及接收这些通知的订阅者。其访问策略还必须向 Systems Manager 授予权限，以便 Change Manager 可以发送通知。有关信息，请参阅[为 Change Manager 通知配置 Amazon SNS 主题](change-manager-sns-setup.md)。
1. 选择 **Add notification（添加通知）**。
1. 在 **Change template reviewers (更改模板审核人员)** 部分中，在您的组织或账户选择用户审核新的更改模板或更改模板版本，然后才能在操作中使用它们。
更改模板审核人员负责验证其他用户提交的、要在 Change Manager 运行手册工作流中使用的模板的适用性和安全性。
可以通过执行以下操作选择更改模板审核人员：
1. 选择 **Add (添加)**。
1. 选中您要指定为更改模板审核人员的每个用户、组或 IAM 角色名称旁边的复选框。
1. 选择 **Add approvers (添加审批人员)**。
1. 选择 **Submit (提交)**。
完成此初始设置过程后，请按 [任务 2：配置 Change Manager 更改冻结事件审批人员和最佳实践](#cm-configure-account-task-2) 中的步骤操作，配置其他 Change Manager 设置和最佳实践。
## 任务 2：配置 Change Manager 更改冻结事件审批人员和最佳实践
在您完成 [任务 1：配置 Change Manager 用户身份管理和模板审核人员](#cm-configure-account-task-1) 中的步骤之后，可为*更改冻结事件*期间的更改请求指定额外的审核人员，还可指定您希望允许哪些可用的最佳实践用于 Change Manager 操作。
更改冻结事件意味着在当前更改日历中设置限制（AWS Systems Manager Change Calendar 中的日历状态为 `CLOSED`）。在这些情况下，除了更改请求的常规审批人员以外，或者如果更改请求是使用允许自动批准的模板创建的，更改冻结审批人员必须为此更改请求的运行授予权限。如果他们不这样做，则不会处理该更改，直到日历状态再次为 `OPEN` 时为止。
**配置 Change Manager 更改冻结事件审批人员和最佳实践**
1. 在导航窗格中，请选择 **Change Manager**。
1. 选择 **Settings (设置)** 选项卡，然后选择 **Edit (编辑)**。
1. 在 **Approvers for change freeze events (更改冻结事件的审批人员)** 部分中，选择您的组织或账户中可以批准更改即便在 Change Calendar 中使用的日历当前处于 CLOSED (已关闭) 状态也能运行的用户。
**注意**
要允许更改冻结审核，必须打开 **Best practices (最佳实践)** 中的 **Check Change Calendar for restricted change events (检查更改日历中的受限更改事件)** 选项。
通过执行以下操作，选择更改冻结事件的审批人员：
1. 选择**添加**。
1. 选中您要指定为更改冻结事件审批人员的每个用户、组或 IAM 角色名称旁边的复选框。
1. 选择 **Add approvers (添加审批人员)**。
1. 在 **Best practices (最佳实践)** 部分中，启用您要针对以下各个选项强制实施的最佳实践。
+ 选项：**Check Change Calendar for restricted change events (检查更改日历中的受限更改事件)**
要指定 Change Manager 检查 Change Calendar 中的日历，以确保更改不会已被计划的事件阻止，请首先选中 **Enabled (已启用)** 复选框，然后从 **Change Calendar (更改日历)** 列表中选择要检查受限事件的日历。
有关 Change Calendar 的更多信息，请参阅 [AWS Systems Manager Change Calendar](systems-manager-change-calendar.md)。
+ 选项：**SNS topic for approvers for closed events (用于已关闭事件的审批人员的 SNS 主题)**
1. 选择以下选项之一，在您的账户中指定 Amazon Simple Notification Service (Amazon SNS) 主题，用于在更改冻结事件期间向审批人员发送通知。（请注意，您还必须在 **Best practices (最佳实践)** 上方的 **Approvers for change freeze events (更改冻结事件的审批人员)** 部分中指定审批人员。）
+ **Enter an SNS Amazon Resource Name (ARN) (输入 SNS Amazon 资源名称 (ARN))** – 对于 **Topic ARN (主题 ARN)**，请输入现有 Amazon SNS 主题的 ARN。此主题可以位于您组织的任何账户中。
+ **Select an existing SNS topic（选择现有 SNS 主题）** – 对于 **Target notification topic（设定通知主题目标）**，选择您当前的 AWS 账户中现有 Amazon SNS 主题的 ARN。（如果您尚未在当前的 AWS 账户 和 AWS 区域 中创建任何 Amazon SNS 主题，则此选项不可用。）
**注意**
您选择的 Amazon SNS 主题必须被配置为指定它所发送的通知，以及接收这些通知的订阅者。其访问策略还必须向 Systems Manager 授予权限，以便 Change Manager 可以发送通知。有关信息，请参阅[为 Change Manager 通知配置 Amazon SNS 主题](change-manager-sns-setup.md)。
1. 选择 **Add notification（添加通知）**。
+ 选项：**Require monitors for all templates (所有模板都需要监控器)**
如果您希望确保您的组织或账户的所有模板都指定 Amazon CloudWatch 告警来监控您的更改操作，请选中 **Enabled**（已启用）复选框。
+ 选项：**Require template review and approval before use (使用前需要审核和批准模板)**
要确保在不基于已审核和已批准的模板的情况下，不创建任何更改请求，也不运行任何运行手册工作流，请选中 **Enabled (已启用)** 复选框。
1. 选择**保存**。
# 为 Change Manager 通知配置 Amazon SNS 主题
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
您可以将 Change Manager（AWS Systems Manager 中的一项工具）配置为针对与更改请求和更改模板有关的事件向 Amazon Simple Notification Service（Amazon SNS）主题发送通知。要接收针对您向其添加了主题的 Change Manager 事件的通知，请完成以下任务。
**Topics**
+ [任务 1：创建并订阅 Amazon SNS 主题](#change-manager-sns-setup-create-topic)
+ [任务 2：更新 Amazon SNS 访问策略](#change-manager-sns-setup-encryption-policy)
+ [任务 3：（可选）更新 AWS Key Management Service 访问策略](#change-manager-sns-setup-KMS-policy)
## 任务 1：创建并订阅 Amazon SNS 主题
首先，必须创建一个 Amazon SNS 主题并订阅此主题。有关更多信息，请参阅 *Amazon Simple Notification Service 开发人员指南*中的[创建 Amazon SNS 主题](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html)和[订阅 Amazon SNS 主题](https://docs.aws.amazon.com/sns/latest/dg/sns-tutorial-create-subscribe-endpoint-to-topic.html)。
**注意**
要接收通知，您必须指定与委托管理员账户位于相同 AWS 区域 和 AWS 账户 的 Amazon SNS 主题的 Amazon Resource Name (ARN)。
## 任务 2：更新 Amazon SNS 访问策略
请使用以下过程更新 Amazon SNS 访问策略，以便 Systems Manager 能将 Change Manager 通知发布到您在“任务 1”中创建的 Amazon SNS 主题。如果不完成这项任务，Change Manager 将没有权限针对您为其添加主题的事件发送通知。
1. 访问 [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home)，登录 AWS 管理控制台 并打开 Amazon SNS 控制台。
1. 在导航窗格中，选择 **Topics (主题)**。
1. 选择您在“任务 1”中创建的主题，然后选择 **Edit (编辑)**。
1. 展开**访问策略**。
1. 将以下 `Sid` 数据块添加并更新到现有策略中，并将每个*用户输入占位符*替换为您的信息。
```
{
"Sid": "Allow Change Manager to publish to this topic",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "sns:Publish",
"Resource": "arn:aws:sns:region:account-id:topic-name",
"Condition": {
"StringEquals": {
"aws:SourceAccount": [
"account-id"
]
}
}
}
```
在现有 `Sid` 数据块后输入此数据块，然后针对您创建的主题，将 *region*、*account-id* 和 *topic-name* 替换为适当的值。
1. 选择**保存更改**。
现在，当您添加到主题中的事件类型发生时，系统将向 Amazon SNS 主题发送通知。
**重要**
如果您已使用 AWS Key Management Service (AWS KMS) 服务器端加密密钥配置了 Amazon SNS 主题，则必须完成“任务 3”。
## 任务 3：（可选）更新 AWS Key Management Service 访问策略
如果您为 Amazon SNS 主题启用了 AWS Key Management Service (AWS KMS) 服务器端加密，则还必须更新您在配置该主题时选择的 AWS KMS key 的访问策略。请使用以下过程更新访问策略，以便 Systems Manager 能将 Change Manager 批准通知发布到您在“任务 1”中创建的 Amazon SNS 主题。
1. 访问 [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms)，打开 AWS KMS 控制台。
1. 在导航窗格中，选择 **Customer managed keys (客户托管密钥)**。
1. 选择您在创建主题时选择的客户托管密钥的 ID。
1. 在 **Key Policy (密钥策略)** 部分中，选择 **Switch to policy view (切换到策略视图)**。
1. 选择**编辑**。
1. 在现有策略中的现有 `Sid` 块之一之后输入以下 `Sid` 块。将每个*用户输入占位符*替换为您自己的信息。
```
{
"Sid": "Allow Change Manager to decrypt the key",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey*"
],
"Resource": "arn:aws:kms:region:account-id:key/key-id",
"Condition": {
"StringEquals": {
"aws:SourceAccount": [
"account-id"
]
}
}
}
```
1. 现在，在资源策略中现有的 `Sid` 块之一之后输入以下 `Sid` 块，以帮助防止[跨服务混淆代理问题](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)。
此块使用 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) 和 [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) 全局条件上下文键来限制 Systems Manager 向资源提供其他服务的权限。
将每个*用户输入占位符*替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Configure confused deputy protection for AWS KMS keys used in Amazon SNS topic when called from Systems Manager",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": [
"sns:Publish"
],
"Resource": "arn:aws:sns:us-east-1:111122223333:topic-name",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:ssm:us-east-1:111122223333:*"
},
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
1. 选择**保存更改**。
# 为 Change Manager 配置角色和权限
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
默认情况下，Change Manager 没有对您的资源执行操作的权限。您必须使用 AWS Identity and Access Management (IAM) 服务角色或*担任角色*授予访问权限。该角色可以让 Change Manager 代表您安全地运行在批准的更改请求中指定的运行手册工作流。该角色向 AWS Security Token Service (AWS STS) [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) 授予对 Change Manager 的信任。
通过向角色提供这些权限以代表企业中的用户行事，用户本身不需要被授予该权限数组。权限允许的操作仅限于批准的操作。
当您的账户或企业中的用户创建更改请求时，他们可以选择此担任角色来执行更改操作。
您可以为 Change Manager 创建新的担任角色，也可以利用所需的权限更新现有角色。
如果您需要为 Change Manager 创建一个服务角色，请完成以下任务。
**Topics**
+ [任务 1：为 Change Manager 创建担任角色策略](#change-manager-role-policy)
+ [任务 2：为 Change Manager 创建担任角色](#change-manager-role)
+ [任务 3：将 `iam:PassRole` 策略附加到其他角色](#change-manager-passpolicy)
+ [任务 4：向担任角色添加内联策略以调用其他 AWS 服务](#change-manager-role-add-inline-policy)
+ [任务 5：配置用户对 Change Manager 的访问权限](#change-manager-passrole)
## 任务 1：为 Change Manager 创建担任角色策略
使用以下过程创建将附加到您的 Change Manager 担任角色的策略。
**为 Change Manager 创建担任角色策略**
1. 访问：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)，打开 IAM 控制台。
1. 在导航窗格中选择 **Policies**，然后选择 **Create Policy**。
1. 在 **Create policy**（创建策略）页面上，选择 **JSON** 选项卡，将默认内容替换为以下内容，您将在以下步骤中针对自己的 Change Manager 操作对其进行修改。
**注意**
如果要创建用于单个 AWS 账户 的策略，而不是具有多个账户和 AWS 区域 的企业，则可以省略第一个数据块。对于使用 Change Manager 的单个账户，不需要 `iam:PassRole` 权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/AWS-SystemsManager-job-functionAdministrationRole",
"Condition": {
"StringEquals": {
"iam:PassedToService": "ssm.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"ssm:DescribeDocument",
"ssm:GetDocument",
"ssm:StartChangeRequestExecution"
],
"Resource": [
"arn:aws:ssm:us-east-1::document/template-name",
"arn:aws:ssm:us-east-1:111122223333:automation-execution/*"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:ListOpsItemEvents",
"ssm:GetOpsItem",
"ssm:ListDocuments",
"ssm:DescribeOpsItems"
],
"Resource": "*"
}
]
}
```
------
1. 对于 `iam:PassRole` 操作，更新 `Resource` 值以包括为您的企业定义的所有工作职能的 ARN，您希望对这些工作职能授予启动运行手册工作流的权限。
1. 将 *region*、*account-id*、*template-name*、*delegated-admin-account-id* 和 *job-function* 占位符替换为 Change Manager 操作的值。
1. 对于第二个 `Resource` 语句，修改列表以包括要授予权限的所有更改模板。或者，指定 `"Resource": "*"` 为企业中的所有更改模板授予权限。
1. 选择**下一步：标签**。
1. （可选）添加一个或多个标签键值对，以组织、跟踪或控制此策略的访问权限。
1. 选择**下一步：审核**。
1. 在 **Review policy**（查看策略）页面上的 **Name**（名称）框中输入一个名称，例如 **MyChangeManagerAssumeRole**，然后输入可选描述。
1. 选择 **Create policy**（创建策略），然后继续转至 [任务 2：为 Change Manager 创建担任角色](#change-manager-role)。
## 任务 2：为 Change Manager 创建担任角色
使用以下过程为 Change Manager 创建 Change Manager 担任角色（一种服务角色类型）。
**为 Change Manager 创建担任角色**
1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 在导航窗格中，选择**角色**，然后选择**创建角色**。
1. 对于 **Select trusted entity**（选择可信实体），完成以下选择：
1. 对于**可信实体类型**，选择 **AWS 服务**。
1. 对于**其他 AWS 服务 的应用场景**，选择 **Systems Manager**
1. 选择 **Systems Manager**，如下图所示。
![\[展示了将 Systems Manager 选为应用场景的选项屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/iam_use_cases_for_MWs.png)
1. 选择**下一步**。
1. 在 **Attached permissions policy**（附加的权限策略）页面上，搜索您在 [任务 1：为 Change Manager 创建担任角色策略](#change-manager-role-policy) 中创建的担任角色策略，比如 **MyChangeManagerAssumeRole**。
1. 选中担任角色策略名称旁边的复选框，然后选择 **Next: Tags**（下一步：标签）。
1. 对于**Role name**（角色名称），请输入新实例配置文件的名称，例如 **MyChangeManagerAssumeRole**。
1. （可选）对于 **Description**（描述），更新该实例角色的描述。
1. （可选）添加一个或多个标签键值对，以组织、跟踪或控制此角色的访问权限。
1. 选择**下一步：审核**。
1. （可选）对于 **Tags**（标签），添加一个或多个标签键值对，以组织、跟踪或控制此角色的访问，然后选择 **Create role**（创建角色）。系统将让您返回到 **角色** 页面。
1. 选择 **Create role (创建角色)**。系统将让您返回到 **角色** 页面。
1. 在**角色**页面中，选择刚刚创建的角色以打开**摘要**页面。
## 任务 3：将 `iam:PassRole` 策略附加到其他角色
使用以下过程将 `iam:PassRole` 策略附加到 IAM 实例配置文件或 IAM 服务角色。（Systems Manager 服务使用 IAM 实例配置文件与 EC2 实例进行通信。对于[混合和多云](operating-systems-and-machine-types.md#supported-machine-types)环境中的非 EC2 托管式节点，改用 IAM 服务角色。）
通过附加 `iam:PassRole` 策略，Change Manager 服务可以在运行运行手册工作流时将担任角色权限传递给其他服务或 Systems Manager 工具。
**将 `iam:PassRole` 策略附加到 IAM 实例配置文件或服务角色**
1. 通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中，选择**角色**。
1. 搜索您创建的 Change Manager 担任角色（如 **MyChangeManagerAssumeRole**），然后选择其名称。
1. 在担任角色的 **Summary**（摘要）页面中，选择 **Permissions**（权限）选项卡。
1. 选择 **Add permissions, Create inline policy**（添加权限、创建内联策略）。
1. 在 **Create policy (创建策略)** 页面上，选择 **Visual editor (可视化编辑器)** 选项卡。
1. 选择**服务**，然后选择 **IAM**。
1. 在 **Filter actions**（筛选操作）文本框中，输入 **PassRole**，然后选择 **PassRole** 选项。
1. 展开 **Resources**（资源）。确保已选择**特定**，然后选择**添加 ARN**。
1. 在 **Specify ARN for role**（为角色指定 ARN）字段中，输入要向其传递担任角色权限的 IAM 实例配置文件角色或 IAM 服务角色的 ARN。系统会自动填充**账户**和**具有路径的角色名称**字段。
1. 选择 **Add (添加)**。
1. 选择**查看策略**。
1. 对于 **Name**（名称），输入一个名称来标识此策略，然后选择 **Create policy**（创建策略）。
**更多信息**
+ [配置 Systems Manager 所需的实例权限](setup-instance-permissions.md)
+ [在混合和多云环境中创建 Systems Manager 所需的 IAM 服务角色](hybrid-multicloud-service-role.md)
## 任务 4：向担任角色添加内联策略以调用其他 AWS 服务
当更改请求使用 Change Manager 代入角色调用其他 AWS 服务时，必须为代入角色配置调用这些服务的权限。此要求适用于可能在更改请求中使用的所有 AWS 自动化运行手册（AWS-\$1 运行手册），例如 `AWS-ConfigureS3BucketLogging`、`AWS-CreateDynamoDBBackup` 和 `AWS-RestartEC2Instance` 运行手册。对于您创建的任何自定义运行手册，如果这些文档使用调用其他服务的操作来调用其他 AWS 服务，则此要求同样适用。例如，如果您使用 `aws:executeAwsApi`、`aws:CreateStack` 或 `aws:copyImage` 操作，则您必须配置具有权限的服务角色来调用这些服务。您可以通过将 IAM 内联策略添加到角色以向其他 AWS 服务授予权限。
**将内联策略添加到代入角色以调用其他 AWS 服务（IAM 控制台）**
1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中，选择**角色**。
1. 在列表中，选择要更新的担任角色的名称，例如 `MyChangeManagerAssumeRole`。
1. 选择**权限**选项卡。
1. 选择 **Add permissions, Create inline policy**（添加权限、创建内联策略）。
1. 选择 **JSON** 选项卡。
1. 输入您希望调用的 AWS 服务的 JSON 策略文档。以下是两个示例 JSON 策略文档。
**Simple Storage Service (Amazon S3) `PutObject` 和 `GetObject` 示例**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
------
**Amazon EC2 `CreateSnapshot` 和 `DescribeSnapShots` 示例**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":"ec2:CreateSnapshot",
"Resource":"*"
},
{
"Effect":"Allow",
"Action":"ec2:DescribeSnapshots",
"Resource":"*"
}
]
}
```
------
有关 IAM policy 语言的详细信息，请参阅《IAM 用户指南》中的 [IAM JSON 策略参考](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html)。
1. 完成后，选择**查看策略**。[策略验证程序](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_policy-validator.html)将报告任何语法错误。
1. 对于 **Name**（名称），输入一个名称来标识您创建的策略。查看策略**摘要**以查看您的策略授予的权限。然后，选择**创建策略**以保存您的工作。
1. 创建内联策略后，它会自动嵌入您的角色。
## 任务 5：配置用户对 Change Manager 的访问权限
如果已为您的用户、组或角色分配了管理员权限，则您有权访问 Change Manager。如果您没有管理员权限，则管理员必须为您的用户、组或角色分配 `AmazonSSMFullAccess` 托管策略或提供类似权限的策略。
使用以下过程配置用户，以使用 Change Manager。您选择的用户将拥有配置并运行 Change Manager 的权限。
根据您在组织中使用的身份应用程序，您可以选择三个可用选项中的任何一个来配置用户访问权限。在配置用户访问权限时，请分配或添加以下内容：
1. 分配提供访问 Systems Manager 权限的 `AmazonSSMFullAccess` 策略或类似策略。
1. 分配 `iam:PassRole` 策略。
1. 为您在 [任务 2：为 Change Manager 创建担任角色](#change-manager-role) 末尾复制的 Change Manager 担任角色添加 ARN。
要提供访问权限，请为您的用户、组或角色添加权限：
+ AWS IAM Identity Center 中的用户和群组：
创建权限集合。按照《AWS IAM Identity Center 用户指南》**中[创建权限集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)的说明进行操作。
+ 通过身份提供者在 IAM 中托管的用户：
创建适用于身份联合验证的角色。按照《IAM 用户指南》**中[针对第三方身份提供者创建角色（联合身份验证）](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)的说明进行操作。
+ IAM 用户：
+ 创建您的用户可以担任的角色。按照《IAM 用户指南》**中[为 IAM 用户创建角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)的说明进行操作。
+ （不推荐使用）将策略直接附加到用户或将用户添加到用户组。按照《IAM 用户指南》**中[向用户添加权限（控制台）](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console)中的说明进行操作。
您已完成了为 Change Manager 配置所需的角色。您现在可以在 Change Manager 操作中使用 Change Manager 担任角色 ARN。
# 控制对自动批准运行手册工作流的访问
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
在为您的组织或账户创建的每个更改模板中，您可以指定从该模板创建的更改请求是否可以作为自动批准的更改请求运行，这意味着这些更改请求将在没有审核步骤的情况下自动运行（更改冻结事件除外）。
但是，您可能希望阻止某些用户、组或 AWS Identity and Access Management (IAM) 角色运行自动批准的更改请求，即使更改模板允许此操作也是如此。您可以将 `ssm:AutoApprove` 条件键用于分配给用户、组或 IAM 角色的 IAM policy 中的 `StartChangeRequestExecution` 操作，借此实现上述目标。
您可以将以下策略添加为内联策略，其中将该条件指定为 `false`，以阻止用户运行可自动批准的更改请求。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ssm:StartChangeRequestExecution",
"Resource": "*",
"Condition": {
"BoolIfExists": {
"ssm:AutoApprove": "false"
}
}
}
]
}
```
------
有关指定内联策略的信息，请参阅 *IAM 用户指南*中的[内联策略](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_managed-vs-inline.html#inline-policies)及[添加和删除 IAM 身份权限](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
有关 Systems Manager 策略条件键的更多信息，请参阅 [Systems Manager 的条件键](security_iam_service-with-iam.md#policy-conditions)。
# 使用 Change Manager
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
借助 Change Manager（AWS Systems Manager 中的一项工具），整个组织或单个 AWS 账户中的（已获必要权限）用户可以执行与更改相关的任务。Change Manager 任务如下：
+ 创建、审核和批准或拒绝更改模板。
更改模板是 Change Manager 中的一个配置设置集合，它定义了所需的批准、可用的运行手册和更改请求的通知选项等内容。
+ 创建、审核和批准或拒绝更改请求。
更改请求是 Change Manager 中的一个请求，旨在运行更新您的 AWS 或本地环境中一个或多个资源的自动化运行手册。更改请求是使用更改模板创建的。
+ 可以指定组织或账户中的哪些用户可以成为更改模板和更改请求的审核人员。
+ 可以编辑配置设置，例如如何在 Change Manager 中管理用户身份，以及在您的 Change Manager 操作中强制实施哪些可用的*最佳实践*选项。有关配置这些设置的信息，请参阅 [配置 Change Manager 选项和最佳实践](change-manager-account-setup.md)。
**Topics**
+ [使用更改模板](change-templates.md)
+ [使用更改请求](change-requests.md)
+ [审核更改请求详细信息、任务和时间表（控制台）](reviewing-changes.md)
+ [查看更改请求的聚合计数（命令行）](change-requests-review-aggregate-command-line.md)
# 使用更改模板
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
更改模板是 Change Manager 中的一个配置设置集合，它定义了所需的批准、可用的运行手册和更改请求的通知选项等内容。
**注意**
AWS 提供了一个示例 [Hello World](change-templates-aws-managed.md) 更改模板，您可使用该示例来试用 Change Manager（AWS Systems Manager 中的一项工具）。但是，您可以创建自己的更改模板，来定义您要允许对组织或账户中的资源进行的更改。
在运行手册工作流运行时进行的更改基于自动化运行手册的内容。在您创建的每个更改模板中，都可以包含一个或多个自动化运行手册，提出更改请求的用户可以从中选择这些运行手册，以便在更新过程中运行。您还可以创建允许请求者为更改请求选择任何可用的自动化运行手册的更改模板。
要创建更改模板，可以使用 **Create template (创建模板)** 控制台页面中的 **Builder (生成器)** 选项，来构建更改模板。或者，使用 **Editor (编辑器)** 选项，可以借助您要用于运行手册工作流的配置手动编写 JSON 或 YAML 内容。您还可以使用命令行工具创建更改模板，将该更改模板的 JSON 内容存储在外部文件中。
**Topics**
+ [试用 AWS 托管 `Hello World` 更改模板](change-templates-aws-managed.md)
+ [创建更改模板](change-templates-create.md)
+ [审核和批准或拒绝更改模板](change-templates-review.md)
+ [删除更改模板](change-templates-delete.md)
# 试用 AWS 托管 `Hello World` 更改模板
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
您可以使用示例更改模板 `AWS-HelloWorldChangeTemplate`（该模板使用示例 Automation 运行手册 `AWS-HelloWorld`），在完成 Change Manager（AWS Systems Manager 中的一项工具）的设置后，对审核和批准流程进行测试。此模板用于测试或验证已配置的权限、审批人员指定和批准流程。AWS 已经批准在您的组织或账户中使用此更改模板。但是，基于此更改模板的任何更改请求，仍然必须得到您的组织或账户中的审核人员的批准。
与此模板关联的运行手册工作流的结果，不会对资源进行更改，而是在“自动化”步骤的输出中打印一条消息。
**开始前的准备工作**
在开始之前，请确保您已完成以下任务：
+ 如果您使用 AWS Organizations 管理整个组织中的更改，请完成 [为组织设置 Change Manager（管理账户）](change-manager-organization-setup.md) 中描述的组织设置任务。
+ 按照 [配置 Change Manager 选项和最佳实践](change-manager-account-setup.md)中的描述，为您的委托管理员账户或单个账户配置 Change Manager。
**注意**
如果您在 Change Manager 设置中打开了最佳实践选项 **Require monitors for all templates (所有模板都需要监控器)**，请在测试 Hello World 更改模板时暂时关闭该选项。
**试用 AWS 托管 Hello World 更改模板**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Manager**。
1. 选择 **Create request (创建请求)**。
1. 选择名为 `AWS-HelloWorldChangeTemplate` 的更改模板，然后选择 **Next (下一步)**。
1. 对于 **Name (名称)**，请输入更改请求的名称，以便于识别其用途，例如 **MyChangeRequestTest**。
1. 有关创建更改请求的其余步骤，请参阅 [创建更改请求创建更改请求（控制台）](change-requests-create.md)。
**后续步骤**
有关批准更改请求的信息，请参阅 [审核和批准或拒绝更改请求](change-requests-review.md)。
要查看您的更改请求的状态和结果，请在 Change Manager 中的 **Requests (请求)** 选项卡上选择您的更改请求的名称。
# 创建更改模板
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
更改模板是 Change Manager 中的一个配置设置集合，它定义了所需的批准、可用的运行手册和更改请求的通知选项等内容。
您可以使用控制台（内含“生成器”和“编辑器”选项）或命令行工具，在 Change Manager（AWS Systems Manager 中的一项工具）中为操作创建更改模板。
**Topics**
+ [关于更改模板中的批准](cm-approvals-templates.md)
+ [使用 Builder (生成器) 创建更改模板](change-templates-custom-builder.md)
+ [使用 Editor (编辑器) 创建更改模板](change-templates-custom-editor.md)
+ [使用命令行工具创建更改模板](change-templates-tools.md)
# 关于更改模板中的批准
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
对于您创建的每个更改模板，您最多可以为通过该更改模板创建的更改请求指定五个批准*级别*。对于其中每个级别，您最多可以指定五个潜在*审批者*。审批者并不限于单个用户。您还可以将 IAM 组或 IAM 角色指定为单独的审批者。对于 IAM 组和 IAM 角色，属于该组或角色的一个或多个用户可以提供批准，以获得更改请求所需的批准总数。您还可以指定数量超过您的更改模板所需数量的审批者。
Change Manager 支持两种主要的批准方法：*逐级批准*和*逐行批准*。在某些情况下，也可以将这两种类型组合在一起。我们建议在您的 Change Manager 操作中仅使用逐级批准。
------
#### [ Per-level approvals ]
*推荐*。自 2023 年 1 月 23 日起，Change Manager 支持逐级批准。在此模型中，对于更改模板中的每个批准级别，您首先需要指定该级别需要多少次批准。然后，您需要为该级别至少指定对应数量的审批者，并且可以指定更多审批者。但只有您指定数量的逐级审批者才需要批准更改请求。例如，您可以指定五个审批者，但需要三次批准。
有关此批准类型的控制台视图和 JSON 示例，请参阅 [逐级批准配置示例](approval-type-samples.md#per-level-approvals)。
------
#### [ Per-line approvals ]
*支持向后兼容性*。原始版本的 Change Manager 仅支持逐行批准。在此模型中，为批准级别指定的每个审批者都以一个批准行来表示。每个审批者都必须批准一次更改请求，该更改请求才能在该级别获得批准。在 2023 年 1 月 23 日之前，这是唯一受支持的批准模型。在此日期之前创建的更改模板继续支持逐行批准，但我们建议改用逐级批准。
有关此批准类型的控制台视图和 JSON 示例，请参阅 [逐行批准配置示例](approval-type-samples.md#per-line-approvals)。
------
#### [ Combined per-line and per-level approvals ]
*不推荐*。在控制台中，**构建器**选项卡不再支持添加逐行批准。但在某些情况下，您最终可能会在更改模板中同时包含逐行和逐级批准。如果您更新在 2023 年 1 月 23 日之前创建的更改模板，或者通过手动编辑更改模板的 YAML 内容来创建或更新更改模板，则可能会发生这种情况。
有关此批准类型的控制台视图和 JSON 示例，请参阅 [逐级和逐行组合批准配置示例](approval-type-samples.md#combined-approval-levels)。
------
**重要**
虽然可以创建将逐行和逐级批准组合在一起的更改模板，但不建议或不必使用此配置。无论哪种批准类型，需要较多批准者（逐行或逐级批准）优先。例如：
如果更改模板指定了三次逐级批准，但指定了五次逐行批准，则需要五次批准。
如果更改模板指定了四次逐级批准，但指定了两次逐行批准，则需要四次批准。
您可以通过手动编辑 YAML 或 JSON 内容，来创建同时包括逐行和逐级批准的级别。然后，**构建器**选项卡将显示用于为该级别和单个行指定所需批准数量的控件。但您使用控制台添加的新级别仍然仅支持逐级批准配置。
## 更改请求通知和拒绝
Amazon SNS 通知
在使用您的更改模板创建更改请求后，将向已为该级别的批准通知指定的 Amazon Simple Notification Service（Amazon SNS）主题的订阅用户发送通知。您可以在更改模板中指定通知主题，也可以允许创建更改请求的用户指定通知主题。
在某一级别获得最低所需批准数量后，将向订阅下一级别 Amazon SNS 主题的审批者发送通知，依此类推。
确保您指定的 IAM 角色、组和用户共同提供足够的审批者，以满足您指定的所需批准数量。例如，如果您仅将一个包含三个用户的 IAM 组指定为审批者，则您无法指定在该级别必须获得五次批准，只能指定三次或以下。
更改请求拒绝
无论您指定了多少个批准级别和审批者，只需拒绝一次更改请求，就会阻止执行该请求的运行手册工作流。
# Change Manager 批准类型示例
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
以下示例演示了 Change Manager 中三种批准类型的控制台视图和 JSON 内容。
**Topics**
+ [逐级批准配置示例](#per-level-approvals)
+ [逐行批准配置示例](#per-line-approvals)
+ [逐级和逐行组合批准配置示例](#combined-approval-levels)
## 逐级批准配置示例
在下图所示的逐级批准级别设置中，需要三次批准。这些批准可以来自被指定为审批者的 IAM 用户、组和角色的任意组合。指定的审批者包括两个 IAM 用户（John Stiles 和 Ana Carolina Silva），一个包含三个成员的用户组（`GroupOfThree`），以及一个代表十个用户的用户角色（`RoleOfTen`）。
如果 `GroupOfThree` 组中的所有三个用户都批准了更改请求，则该更改请求即获得了该级别的批准。不必获得来自每个用户、组或角色的批准。最低批准数量可以来自指定审批者的任意组合。我们建议对您的 Change Manager 操作进行逐级批准。
![\[批准级别显示需要三次批准和四个指定审批者。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/Add-approval-2.png)
以下示例说明了此配置的部分 YAML 代码。
**注意**
此版本的 YAML 代码包括一个额外的输入 `MinRequiredApprovals`（包含首字母大写 `M`）。此输入的值表示需要从所有可用审核者获得多少次批准。另请注意，`Approvers` 列表中每个审批者的 `minRequiredApprovals`（首字母小写 `m`）值为 `0`（零）。这表示相应审批者可以为总批准数做出贡献，但不需要这样做。
```
schemaVersion: "0.3"
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: aws:approve
timeoutSeconds: 604800
inputs:
Message: Please approve this change request
MinRequiredApprovals: 3
EnhancedApprovals:
Approvers:
- approver: John Stiles
type: IamUser
minRequiredApprovals: 0
- approver: Ana Carolina Silva
type: IamUser
minRequiredApprovals: 0
- approver: GroupOfThree
type: IamGroup
minRequiredApprovals: 0
- approver: RoleOfTen
type: IamRole
minRequiredApprovals: 0
templateInformation: >
#### What is the purpose of this change?
//truncated
```
## 逐行批准配置示例
在下图所示的批准级别设置中，指定了四个审批者。其中包括两个 IAM 用户（John Stiles 和 Ana Carolina Silva），一个包含三个成员的用户组（`GroupOfThree`），以及一个代表十个用户的用户角色（`RoleOfTen`）。为了实现向后兼容性支持逐行批准，但不推荐使用该类型。
![\[批准级别显示需要四个逐行审批者。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/Add-approval-1.png)
要使更改请求在此逐行批准配置中获得批准，该更该请求必须获得所有审批者行的批准：John Stiles、Ana Carolina Silva、`GroupOfThree` 组的一名成员，以及 `RoleOfTen` 角色的一名成员。
以下示例说明了此配置的部分 YAML 代码。
**注意**
请注意，每个 `minRequiredApprovals` 审批者的值均为 `1`。这表示需要从每个审批者获得一次批准。
```
schemaVersion: "0.3"
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: aws:approve
timeoutSeconds: 10000
inputs:
Message: Please approve this change request
EnhancedApprovals:
Approvers:
- approver: John Stiles
type: IamUser
minRequiredApprovals: 1
- approver: Ana Carolina Silva
type: IamUser
minRequiredApprovals: 1
- approver: GroupOfThree
type: IamGroup
minRequiredApprovals: 1
- approver: RoleOfTen
type: IamRole
minRequiredApprovals: 1
executableRunBooks:
- name: AWS-HelloWorld
version: $DEFAULT
templateInformation: >
#### What is the purpose of this change?
//truncated
```
## 逐级和逐行组合批准配置示例
在下图所示的逐级和逐行组合批准设置中，为级别指定了三次批准，但为行项目批准指定了四次批准。无论哪种批准类型，需要更多批准的类型都优先于另一种类型，所以此配置需要四次批准。不推荐使用按级别和按行组合批准。
![\[批准级别显示级别需要三次批准，但行级别需要四次批准。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/Add-approval-3.png)
```
schemaVersion: "0.3"
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: aws:approve
timeoutSeconds: 604800
inputs:
Message: Please approve this change request
MinRequiredApprovals: 3
EnhancedApprovals:
Approvers:
- approver: John Stiles
type: IamUser
minRequiredApprovals: 1
- approver: Ana Carolina Silva
type: IamUser
minRequiredApprovals: 1
- approver: GroupOfThree
type: IamGroup
minRequiredApprovals: 1
- approver: RoleOfTen
type: IamRole
minRequiredApprovals: 1
templateInformation: >
#### What is the purpose of this change?
//truncated
```
**Topics**
+ [关于更改模板中的批准](cm-approvals-templates.md)
+ [使用 Builder (生成器) 创建更改模板](change-templates-custom-builder.md)
+ [使用 Editor (编辑器) 创建更改模板](change-templates-custom-editor.md)
+ [使用命令行工具创建更改模板](change-templates-tools.md)
# 使用 Builder (生成器) 创建更改模板
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
将生成器用于 Change Manager（AWS Systems Manager 中的一项工具）中的更改模板，即可配置在更改模板中定义的运行手册工作流，免于使用使用 JSON 或 YAML 语法。在您指定选项后，系统会将您的输入转换为 YAML 格式，Systems Manager 可以将其用于运行运行手册工作流。
**使用 Builder (生成器) 创建更改模板**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Manager**。
1. 选择**创建模板**。
1. 对于 **Name (名称)**，请输入模板的名称，以便于识别其用途，例如 **UpdateEC2LinuxAMI**。
1. 在 **Change template details (更改模板详细信息)** 部分中，执行以下操作：
+ 对于 **Description (描述)**，请提供有关如何以及何时使用您所创建的更改模板的简要说明。
此描述可帮助创建更改请求的用户确定他们是否使用了正确的更改模板。它可以帮助审核更改请求的人员了解是否应该批准该请求。
+ 对于 **Change template type (更改模板类型)**，请指定您是创建标准更改模板还是紧急更改模板。
紧急更改模板用于即便 AWS Systems Manager Change Calendar 所使用的日历中的某个事件阻止更改，也必须进行更改的情况。从紧急更改模板创建的更改请求仍然必须由其指定的审批人员批准，但即便日历被阻止，所请求的更改仍可运行。
+ 对于 **Runbook options (运行手册选项)**，请指定用户在创建更改请求时可以从中选择的运行手册。您可以添加一个运行手册或多个运行手册。或者，您也可以允许请求者指定要使用哪一个运行手册。在上述任何情况下，更改请求中都只能包含一个运行手册。
+ 对于 **Runbook (运行手册)**，请选择用户可以为其更改请求从中选择的运行手册的名称及其版本。无论您向更改模板添加了多少个运行手册，每个更改请求只能选择一个运行手册。
如果您先前选择了 **Any runbook can be used (可以使用任何运行手册)**，则您无需指定运行手册。
**提示**
选择运行手册和运行手册版本，然后选择 **View (查看)**，以便在 Systems Manager Documents (文档) 界面中检查运行手册的内容。
1. 在 **Template information (模板信息)** 部分中，使用 Markdown 输入从此更改模板创建更改请求的用户的信息。我们提供了一组问题，您可以为创建更改请求的用户提供这些问题，也可以添加其他信息和问题作为替代。
**注意**
Markdown 是一种标记语言，允许您为文档和文档中的各个步骤中添加维基百科式的描述。有关使用 Markdown 的更多信息，请参阅[在 AWS 中使用 Markdown](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)。
我们建议为用户提供问题，询问有关其更改请求的信息，以帮助审批人员决定是否批准每个更改请求，例如列出作为更改的组成部分需要运行的任何手动步骤和回滚计划。
**提示**
在 **Hide preview (隐藏预览)** 和 **Show preview (显示预览)** 之间切换，以便查看您的哪些内容看起来符合您的编写要求。
1. 在 **Change request approvals (更改请求批准)** 部分中，执行以下操作：
+ （可选）如果您希望允许从此更改模板创建的更改请求自动运行，而不需要任何审批人员进行审核（更改冻结事件除外），则请选择 **Enable auto-approval (启用自动批准)**。
**注意**
在更改模板中启用自动批准，可为用户提供绕过审核人员的*选项*。他们仍然可以在创建更改请求时选择指定审核人员。因此，您仍然必须在更改模板中指定审批人员选项。
**重要**
如果您为更改模板启用了自动批准，则用户可以使用该模板提交更改请求，这些更改请求在运行前无需审核人员进行审核（更改冻结事件审批人员除外）。如果您要限制特定用户、组或 IAM 角色提交自动批准请求，可以使用 IAM policy 中的某一条件来实现此目的。有关更多信息，请参阅 [控制对自动批准运行手册工作流的访问](change-manager-auto-approval-access.md)。
+ 对于**此级别所需的批准数量**，选择通过此更改模板创建的更改请求对于此级别必须获得的批准数量。
+ 要添加强制的第一级审批人员，请选择 **Add approver (添加审批人员)**，然后从以下选项中进行选择：
+ **Template specified approvers (模板指定的审批人员)** – 从您的账户中选择一个或多个用户、组或 AWS Identity and Access Management (IAM) 角色，以批准从此更改模板创建的更改请求。使用此模板创建的任何更改请求都必须由您指定的每个审批人员进行审核和批准。
+ **Request specified approvers**（请求指定的审批人员）：提出更改请求的用户将在提出该请求时指定审核人员，并可从您账户中的用户列表中进行选择。
您在 **Required (必需)** 列中输入的数字确定使用此更改模板的更改请求必须指定的审核人员的数量。
**重要**
在 2023 年 1 月 23 日之前，**构建器**选项卡仅支持指定逐行批准。新更改模板和您使用**构建器**选项卡添加到现有更改模板的新级别，仅支持逐级批准。我们建议在您的 Change Manager 操作中仅使用逐级批准。
有关更多信息，请参阅 [关于更改模板中的批准](cm-approvals-templates.md)。
+ 对于 **SNS topic to notify approvers (要通知审批人员的 SNS 主题)**，请执行以下操作：
1. 选择以下选项之一，在您的账户中指定 Amazon Simple Notification Service (Amazon SNS) 主题，用于向审批人员发送更改请求已准备好供其审核的通知：
+ **Enter an SNS Amazon Resource Name (ARN) (输入 SNS Amazon 资源名称 (ARN))** – 对于 **Topic ARN (主题 ARN)**，请输入现有 Amazon SNS 主题的 ARN。此主题可以位于您组织的任何账户中。
+ **Select an existing SNS topic（选择现有 SNS 主题）** – 对于 **Target notification topic（设定通知主题目标）**，选择您当前的 AWS 账户中现有 Amazon SNS 主题的 ARN。（如果您尚未在当前的 AWS 账户 和 AWS 区域 中创建任何 Amazon SNS 主题，则此选项不可用。）
+ **Specify SNS topic when the change request is created (创建更改请求时指定 SNS 主题)** – 创建更改请求的用户可以指定要用于通知的 Amazon SNS 主题。
**注意**
您选择的 Amazon SNS 主题必须被配置为指定它所发送的通知，以及接收这些通知的订阅者。其访问策略还必须向 Systems Manager 授予权限，以便 Change Manager 可以发送通知。有关信息，请参阅[为 Change Manager 通知配置 Amazon SNS 主题](change-manager-sns-setup.md)。
1. 选择 **Add notification（添加通知）**。
1. （可选）要添加其他级别的审批人员，请选择 **Add approval level (添加批准级别)**，然后在与此级别对应的模板指定的审批人员和请求指定的审批人员之间进行选择。然后选择 SNS 主题以通知此级别的审批人员。
在第一级审批人员收到所有批准后，会通知第二级审批人员，依此类推。
您可以在每个模板中添加最多五个级别的审批人员。例如，您可能需要担任技术角色的用户提供第一级别的批准，然后需要管理人员提供第二级别的批准。
1. 在 **Monitoring (监控)** 部分中，对于 **CloudWatch alarm to monitor (要监控的 CloudWatch 告警)**，请输入当前账户中 Amazon CloudWatch 告警的名称，以监控基于此模板的运行手册工作流的进度。
**提示**
要创建新告警，或要审核您要指定的告警的设置，请选择 **Open the Amazon CloudWatch console (打开 Amazon CloudWatch 控制台)**。有关使用 CloudWatch 告警的信息，请参阅 *Amazon CloudWatch 用户指南*中的[使用 CloudWatch 告警](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)。
1. 在 **Notifications**（通知）部分执行以下操作：
1. 选择以下选项之一，在您的账户中指定 Amazon SNS 主题，用于发送有关使用此更改模板创建的更改请求的通知：
+ **Enter an SNS Amazon Resource Name (ARN) (输入 SNS Amazon 资源名称 (ARN))** – 对于 **Topic ARN (主题 ARN)**，请输入现有 Amazon SNS 主题的 ARN。此主题可以位于您组织的任何账户中。
+ **Select an existing SNS topic（选择现有 SNS 主题）** – 对于 **Target notification topic（设定通知主题目标）**，选择您当前的 AWS 账户中现有 Amazon SNS 主题的 ARN。（如果您尚未在当前的 AWS 账户 和 AWS 区域 中创建任何 Amazon SNS 主题，则此选项不可用。）
**注意**
您选择的 Amazon SNS 主题必须被配置为指定它所发送的通知，以及接收这些通知的订阅者。其访问策略还必须向 Systems Manager 授予权限，以便 Change Manager 可以发送通知。有关信息，请参阅[为 Change Manager 通知配置 Amazon SNS 主题](change-manager-sns-setup.md)。
1. 选择 **Add notification（添加通知）**。
1. （可选）在 **Tags (标签)** 部分中，将一个或多个标签键名/键值对应用于更改模板。
标签是您分配给资源的可选元数据。通过使用标签，您可以按各种方式（如用途、所有者或环境）对资源进行分类。例如，您可能希望标记更改模板，以标识它所进行的更改的类型及其运行的环境。在这种情况下，您可以指定以下键名/键值对：
+ `Key=TaskType,Value=InstanceRepair`
+ `Key=Environment,Value=Production`
1. 选择 **Save and preview (保存和预览)**。
1. 审核您所创建的更改模板的详细信息。
如果要在提交更改模板以供审核之前对其进行更改，请选择 **Actions (操作)、Edit (编辑)**。
如果您对更改模板的内容感到满意，请选择 **Submit for review (提交以供审核)**。您的组织或账户内在 Change Manager 中的 **Settings (设置)** 选项卡上被指定为模板审核人员的用户，将收到新的更改模板正等待其审核的通知。
如果已为更改模板指定 Amazon SNS 主题，则当更改模板被拒绝或批准时，系统会发送通知。如果您没有收到与此更改模板相关的通知，可在稍后返回 Change Manager 以检查其状态。
# 使用 Editor (编辑器) 创建更改模板
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
按照本主题中的步骤操作，通过输入 JSON 或 YAML，而不是使用控制台控件，即可在 Change Manager（AWS Systems Manager 中的一项工具）中配置更改模板。
**使用 Editor (编辑器) 创建更改模板**
1. 在导航窗格中，请选择 **Change Manager**。
1. 选择**创建模板**。
1. 对于 **Name (名称)**，请输入模板的名称，以便于识别其用途，例如 **RestartEC2LinuxInstance**。
1. 在 **Change template details (更改模板详细信息)** 上方，选择 **Editor (编辑器)**。
1. 在 **Document editor (文档编辑器)** 部分中，选择 **Edit (编辑)**，然后为您的更改模板输入 JSON 或 YAML 内容。
示例如下：
**注意**
参数 `minRequiredApprovals` 用于指定对于使用此模板创建的更改请求，必须取得多少指定级别的审阅者批准。
此示例演示了两个级别的批准。您可以指定最多五个级别的批准，但只需要一个级别。
在第一级，每个更改请求必须取得指定用户“John-Doe”的批准。然后，该更改请求必须由 IAM 角色 `Admin` 的任意三个成员批准。
有关批准更改模板的更多信息，请参阅 [关于更改模板中的批准](cm-approvals-templates.md)。
------
#### [ YAML ]
```
description: >-
This change template demonstrates the feature set available for creating
change templates for Change Manager. This template starts a Runbook workflow
for the Automation runbook called AWS-HelloWorld.
templateInformation: >
### Document Name: HelloWorldChangeTemplate
## What does this document do?
This change template demonstrates the feature set available for creating
change templates for Change Manager. This template starts a Runbook workflow
for the Automation runbook called AWS-HelloWorld.
## Input Parameters
* ApproverSnsTopicArn: (Required) Amazon Simple Notification Service ARN for
approvers.
* Approver: (Required) The name of the approver to send this request to.
* ApproverType: (Required) The type of reviewer.
* Allowed Values: IamUser, IamGroup, IamRole, SSOGroup, SSOUser
## Output Parameters
This document has no outputs
schemaVersion: '0.3'
parameters:
ApproverSnsTopicArn:
type: String
description: Amazon Simple Notification Service ARN for approvers.
Approver:
type: String
description: IAM approver
ApproverType:
type: String
description: >-
Approver types for the request. Allowed values include IamUser, IamGroup,
IamRole, SSOGroup, and SSOUser.
executableRunBooks:
- name: AWS-HelloWorld
version: '1'
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: 'aws:approve'
timeoutSeconds: 3600
inputs:
Message: >-
A sample change request has been submitted for your review in Change
Manager. You can approve or reject this request.
EnhancedApprovals:
NotificationArn: '{{ ApproverSnsTopicArn }}'
Approvers:
- approver: John-Doe
type: IamUser
minRequiredApprovals: 1
- name: ApproveAction2
action: 'aws:approve'
timeoutSeconds: 3600
inputs:
Message: >-
A sample change request has been submitted for your review in Change
Manager. You can approve or reject this request.
EnhancedApprovals:
NotificationArn: '{{ ApproverSnsTopicArn }}'
Approvers:
- approver: Admin
type: IamRole
minRequiredApprovals: 3
```
------
#### [ JSON ]
```
{
"description": "This change template demonstrates the feature set available for creating
change templates for Change Manager. This template starts a Runbook workflow
for the Automation runbook called AWS-HelloWorld",
"templateInformation": "### Document Name: HelloWorldChangeTemplate\n\n
## What does this document do?\n
This change template demonstrates the feature set available for creating change templates for Change Manager.
This template starts a Runbook workflow for the Automation runbook called AWS-HelloWorld.\n\n
## Input Parameters\n* ApproverSnsTopicArn: (Required) Amazon Simple Notification Service ARN for approvers.\n
* Approver: (Required) The name of the approver to send this request to.\n
* ApproverType: (Required) The type of reviewer. * Allowed Values: IamUser, IamGroup, IamRole, SSOGroup, SSOUser\n\n
## Output Parameters\nThis document has no outputs\n",
"schemaVersion": "0.3",
"parameters": {
"ApproverSnsTopicArn": {
"type": "String",
"description": "Amazon Simple Notification Service ARN for approvers."
},
"Approver": {
"type": "String",
"description": "IAM approver"
},
"ApproverType": {
"type": "String",
"description": "Approver types for the request. Allowed values include IamUser, IamGroup, IamRole, SSOGroup, and SSOUser."
}
},
"executableRunBooks": [
{
"name": "AWS-HelloWorld",
"version": "1"
}
],
"emergencyChange": false,
"autoApprovable": false,
"mainSteps": [
{
"name": "ApproveAction1",
"action": "aws:approve",
"timeoutSeconds": 3600,
"inputs": {
"Message": "A sample change request has been submitted for your review in Change Manager. You can approve or reject this request.",
"EnhancedApprovals": {
"NotificationArn": "{{ ApproverSnsTopicArn }}",
"Approvers": [
{
"approver": "John-Doe",
"type": "IamUser",
"minRequiredApprovals": 1
}
]
}
}
},
{
"name": "ApproveAction2",
"action": "aws:approve",
"timeoutSeconds": 3600,
"inputs": {
"Message": "A sample change request has been submitted for your review in Change Manager. You can approve or reject this request.",
"EnhancedApprovals": {
"NotificationArn": "{{ ApproverSnsTopicArn }}",
"Approvers": [
{
"approver": "Admin",
"type": "IamRole",
"minRequiredApprovals": 3
}
]
}
}
}
]
}
```
------
1. 选择 **Save and preview (保存和预览)**。
1. 审核您所创建的更改模板的详细信息。
如果要在提交更改模板以供审核之前对其进行更改，请选择 **Actions (操作)、Edit (编辑)**。
如果您对更改模板的内容感到满意，请选择 **Submit for review (提交以供审核)**。您的组织或账户内在 Change Manager 中的 **Settings (设置)** 选项卡上被指定为模板审核人员的用户，将收到新的更改模板正等待其审核的通知。
如果已为更改模板指定 Amazon Simple Notification Service (Amazon SNS) 主题，则当更改模板被拒绝或批准时，系统会发送通知。如果您没有收到与此更改模板相关的通知，可在稍后返回 Change Manager 以检查其状态。
# 使用命令行工具创建更改模板
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
以下过程介绍了如何使用 AWS Command Line Interface（AWS CLI）（在 Linux、macOS 或 Windows Server 上）或 AWS Tools for Windows PowerShell 在 Change Manager（AWS Systems Manager 中的一个工具）中创建更改请求。
**创建更改模板**
1. 安装并配置 AWS Tools for PowerShell (AWS CLI)（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)以及[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
1. 在本地计算机上使用 `MyChangeTemplate.json` 之类的名称创建一个 JSON 文件，然后将更改模板的内容粘贴到此文件中。
**注意**
更改模板使用架构 0.3 版本，该版本包含的支持与针对自动化运行手册的支持不完全相同。
示例如下：
**注意**
参数 `minRequiredApprovals` 用于指定对于使用此模板创建的更改请求，必须取得多少指定级别的审阅者批准。
此示例演示了两个级别的批准。您可以指定最多五个级别的批准，但只需要一个级别。
在第一级，每个更改请求必须取得指定用户“John-Doe”的批准。然后，该更改请求必须由 IAM 角色 `Admin` 的任意三个成员批准。
有关批准更改模板的更多信息，请参阅 [关于更改模板中的批准](cm-approvals-templates.md)。
```
{
"description": "This change template demonstrates the feature set available for creating
change templates for Change Manager. This template starts a Runbook workflow
for the Automation runbook called AWS-HelloWorld",
"templateInformation": "### Document Name: HelloWorldChangeTemplate\n\n
## What does this document do?\n
This change template demonstrates the feature set available for creating change templates for Change Manager.
This template starts a Runbook workflow for the Automation runbook called AWS-HelloWorld.\n\n
## Input Parameters\n* ApproverSnsTopicArn: (Required) Amazon Simple Notification Service ARN for approvers.\n
* Approver: (Required) The name of the approver to send this request to.\n
* ApproverType: (Required) The type of reviewer. * Allowed Values: IamUser, IamGroup, IamRole, SSOGroup, SSOUser\n\n
## Output Parameters\nThis document has no outputs\n",
"schemaVersion": "0.3",
"parameters": {
"ApproverSnsTopicArn": {
"type": "String",
"description": "Amazon Simple Notification Service ARN for approvers."
},
"Approver": {
"type": "String",
"description": "IAM approver"
},
"ApproverType": {
"type": "String",
"description": "Approver types for the request. Allowed values include IamUser, IamGroup, IamRole, SSOGroup, and SSOUser."
}
},
"executableRunBooks": [
{
"name": "AWS-HelloWorld",
"version": "1"
}
],
"emergencyChange": false,
"autoApprovable": false,
"mainSteps": [
{
"name": "ApproveAction1",
"action": "aws:approve",
"timeoutSeconds": 3600,
"inputs": {
"Message": "A sample change request has been submitted for your review in Change Manager. You can approve or reject this request.",
"EnhancedApprovals": {
"NotificationArn": "{{ ApproverSnsTopicArn }}",
"Approvers": [
{
"approver": "John-Doe",
"type": "IamUser",
"minRequiredApprovals": 1
}
]
}
}
},
{
"name": "ApproveAction2",
"action": "aws:approve",
"timeoutSeconds": 3600,
"inputs": {
"Message": "A sample change request has been submitted for your review in Change Manager. You can approve or reject this request.",
"EnhancedApprovals": {
"NotificationArn": "{{ ApproverSnsTopicArn }}",
"Approvers": [
{
"approver": "Admin",
"type": "IamRole",
"minRequiredApprovals": 3
}
]
}
}
}
]
}
```
1. 运行以下命令创建更改模板。
------
#### [ Linux & macOS ]
```
aws ssm create-document \
--name MyChangeTemplate \
--document-format JSON \
--document-type Automation.ChangeTemplate \
--content file://MyChangeTemplate.json \
--tags Key=tag-key,Value=tag-value
```
------
#### [ Windows ]
```
aws ssm create-document ^
--name MyChangeTemplate ^
--document-format JSON ^
--document-type Automation.ChangeTemplate ^
--content file://MyChangeTemplate.json ^
--tags Key=tag-key,Value=tag-value
```
------
#### [ PowerShell ]
```
$json = Get-Content -Path "C:\path\to\file\MyChangeTemplate.json" | Out-String
New-SSMDocument `
-Content $json `
-Name "MyChangeTemplate" `
-DocumentType "Automation.ChangeTemplate" `
-Tags "Key=tag-key,Value=tag-value"
```
------
有关可以指定的其他选项的信息，请参阅 [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-document.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-document.html)。
系统将返回类似于以下内容的信息。
```
{
"DocumentDescription":{
"CreatedDate":1.585061751738E9,
"DefaultVersion":"1",
"Description":"Use this template to update an EC2 Linux AMI. Requires one
approver specified in the template and an approver specified in the request.",
"DocumentFormat":"JSON",
"DocumentType":"Automation",
"DocumentVersion":"1",
"Hash":"0d3d879b3ca072e03c12638d0255ebd004d2c65bd318f8354fcde820dEXAMPLE",
"HashType":"Sha256",
"LatestVersion":"1",
"Name":"MyChangeTemplate",
"Owner":"123456789012",
"Parameters":[
{
"DefaultValue":"",
"Description":"Level one approvers",
"Name":"LevelOneApprovers",
"Type":"String"
},
{
"DefaultValue":"",
"Description":"Level one approver type",
"Name":"LevelOneApproverType",
"Type":"String"
},
"cloudWatchMonitors": {
"monitors": [
"my-cloudwatch-alarm"
]
}
],
"PlatformTypes":[
"Windows",
"Linux"
],
"SchemaVersion":"0.3",
"Status":"Creating",
"Tags":[
]
}
}
```
您的组织或账户内在 Change Manager 中的 **Settings (设置)** 选项卡上被指定为模板审核人员的用户，将收到新的更改模板正等待其审核的通知。
如果已为更改模板指定 Amazon Simple Notification Service (Amazon SNS) 主题，则当更改模板被拒绝或批准时，系统会发送通知。如果您没有收到与此更改模板相关的通知，可在稍后返回 Change Manager 以检查其状态。
# 审核和批准或拒绝更改模板
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
如果您在 Change Manager（AWS Systems Manager 中的一项工具）中被指定为更改模板的审核人员，只要有新的更改模板或新版本的更改模板等待审核，您就会收到通知。Amazon Simple Notification Service (Amazon SNS) 主题可以发送通知。
**注意**
此功能取决于是否已将您的账户配置为使用 Amazon SNS 主题发送更改模板审核通知。有关指定模板审核人员通知主题的信息，请参阅 [任务 1：配置 Change Manager 用户身份管理和模板审核人员](change-manager-account-setup.md#cm-configure-account-task-1)。
要审核更改模板，请访问您的通知中的链接，登录到 AWS 管理控制台，然后按照本过程中的步骤进行操作。
**审核和批准或拒绝更改模板**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Manager**。
1. 在 **Overview (概述)** 选项卡底部的 **Change templates (更改模板)** 部分中，选择 **Pending review (等待审核)** 中的编号。
1. 在 **Change templates (更改模板)** 列表中，找到并选择要审核的更改模板的名称。
1. 在摘要页面中，审核更改模板的建议内容，然后执行以下操作之一：
+ 要批准更改模板（这将允许在更改请求中使用该模板），请选择 **Approve**（批准）。
+ 要拒绝更改模板（这将阻止在更改请求中使用该模板），请选择 **Reject**（拒绝）。
# 删除更改模板
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
本主题介绍如何删除您在 Change Manager（Systems Manager 中的一项工具）中创建的模板。如果您正在为企业使用 Change Manager，则此过程将在委托管理员账户中执行。
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Manager**。
1. 选择 **Templates** 选项卡。
1. 选择要删除的模板的名称。
1. 选择 **Actions, Delete template**（操作，删除模板）。
1. 在确认对话框中，输入 **DELETE** 一词，然后选择 **Delete**（删除）。
# 使用更改请求
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
更改请求是 Change Manager 中的一个请求，旨在运行更新您的 AWS 或本地环境中一个或多个资源的自动化运行手册。更改请求是使用更改模板创建的。
在 Change Manager（AWS Systems Manager 中的一项工具）中创建更改请求时，组织或账户中的一个或多个审批人员必须审核并批准该请求。如果没有获得所需的批准，则不允许运行进行您请求的更改的运行手册工作流。
**Topics**
+ [创建更改请求](change-requests-create.md)
+ [审核和批准或拒绝更改请求](change-requests-review.md)
# 创建更改请求
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
在 Change Manager（AWS Systems Manager 中的一项工具）中创建更改请求时，您选择的更改模板通常会执行以下操作：
+ 为更改请求指定审批人员或者指定所需审批人员的数量
+ 指定要用于将您的更改请求通知审批人员的 Amazon Simple Notification Service (Amazon SNS) 主题
+ 指定 Amazon CloudWatch 告警，以监控更改请求的运行手册工作流
+ 确定您可以从哪些自动化运行手册中进行选择，以进行所请求的更改
在某些情况下，可能会配置更改模板，以使您能指定自己的自动化运行手册以供使用，并指定应该审核和批准该请求的人员。
**重要**
如果您在整个组织中使用 Change Manager，我们建议始终从委托管理员账户进行更改。虽然您可以从组织中的其他账户进行更改，但这些更改不会在委派管理员账户中报告，也无法从该账户查看。
**Topics**
+ [关于更改请求批准](#cm-approvals-requests)
+ [创建更改请求（控制台）](#change-requests-create-console)
+ [创建更改请求 (AWS CLI)](#change-requests-create-cli)
## 关于更改请求批准
根据更改模板中指定的要求，您在该模板中创建的更改请求可能需要获得最多五个*级别*的批准，然后才能为该请求执行运行手册工作流。对于每个级别，模板创建者最多可以指定五个潜在*审批者*。审批者并不限于单个用户。从这个意义上讲，审批者也可以是 IAM 组或 IAM 角色。对于 IAM 组和 IAM 角色，属于该组或角色的一个或多个用户可以提供批准，以获得更改请求所需的批准总数。模板创建者还可以指定数量超过更改模板所需数量的审批者。
**原始审批工作流以及经过更新的审批工作流和/或审批**
使用在 2023 年 1 月 23 日之前创建的更改模板，必须获得每个指定审批者的批准，更改请求才能在该级别获得批准。例如，在下图所示的批准级别设置中，指定了四个审批者。指定的审批者包括两个用户（John Stiles 和 Ana Carolina Silva），一个包含三个成员的用户组（GroupOfThree），以及一个代表十个用户的用户角色（RoleOfTen）。
![\[批准级别显示需要四个逐行审批者。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/Add-approval-1.png)
要使更改请求在此级别获得批准，该更改请求必须经过 John Stiles、Ana Carolina Silva、`GroupOfThree` 组的一名成员和 `RoleOfTen` 角色的一名成员的批准。
使用在 2023 年 1 月 23 日或之后创建的更改模板，模板创建者可为每个批准级别指定所需批准的总数。这些批准可以来自已被指定为审批者的用户、组和角色的任意组合。一个更改模板对于一个级别可能只需要一次批准，但举例来说，需要指定两个单独的用户、两个组和一个角色作为潜在审批者。
例如，在下图所示的批准级别区域中，需要三次批准。模板指定的审批者包括两个用户（John Stiles 和 Ana Carolina Silva），一个包含三个成员的用户组（`GroupOfThree`），以及一个代表十个用户的用户角色（`RoleOfTen`）。
![\[批准级别显示需要三次批准和四个指定审批者。\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/Add-approval-2.png)
如果 `GroupOfThree` 组中的所有三个用户都批准了您的更改请求，则该更改请求即获得了该级别的批准。不必获得来自每个用户、组或角色的批准。最低批准数量可以来自潜在审批者的任意组合。
在创建更改请求后，将向已为该级别的批准通知指定的 Amazon SNS 主题的订阅用户发送通知。更改模板创建者可能已经指定了必须使用的通知主题，或者允许您指定通知主题。
在某一级别获得最低所需批准数量后，将向订阅下一级别 Amazon SNS 主题的审批者发送通知，依此类推。
无论指定了多少个批准级别和审批者，只需拒绝一次更改请求，就会阻止执行该请求的运行手册工作流。
## 创建更改请求（控制台）
以下过程介绍了如何使用 Systems Manager 控制台创建更改请求。
**创建更改请求（控制台）**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Manager**。
1. 选择 **Create request (创建请求)**。
1. 搜索并选择要用于此更改请求的更改模板。
1. 选择**下一步**。
1. 对于 **Name (名称)**，请输入更改请求的名称，以便于识别其用途，例如 **UpdateEC2LinuxAMI-us-east-2**。
1. 对于 **Runbook (运行手册)**，请选择您要用于进行所请求的更改的运行手册。
**注意**
如果选择运行手册的选项不可用，则更改模板作者已指定了必须使用哪个运行手册。
1. 对于 **Change request information (更改请求信息)**，请使用 Markdown 提供有关更改请求的其他信息，以帮助审核人员决定是批准还是拒绝更改请求。您使用的模板的作者可能已提供了说明或需要您解答的问题。
**注意**
Markdown 是一种标记语言，允许您为文档和文档中的各个步骤中添加维基百科式的描述。有关使用 Markdown 的更多信息，请参阅[在 AWS 中使用 Markdown](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)。
1. 在 **Workflow start time (工作流开始时间)** 部分中，选择以下选项之一：
+ **Run the operation at a scheduled time (在计划时间运行该操作)** – 对于 **Requested start time (请求的开始时间)**，请输入您建议运行此请求的运行手册工作流的日期和时间。对于 **Estimated end time (估计结束时间)**，请输入您预计运行手册工作流完成的日期和时间。（此时间仅是您为审核人员提供的估计值。）
**提示**
选择 **View Change Calendar (查看更改日历)**，以检查您指定的时间内是否存在任何阻止事件。
+ **Run the operation as soon as possible after approval (批准后尽快运行操作)**— 如果更改请求获得批准，则运行手册工作流将在出现可以进行更改的非限制时段时立即运行。
1. 在 **Change request approvals (更改请求批准)** 部分中，执行以下操作：
1. 如果出现 **Approval type (批准类型)** 选项，请选择以下选项之一：
+ **Automatic approval (自动批准)** – 您选择的更改模板将被配置为允许更改请求自动运行，而无需任何审批人员审核。继续执行步骤 11。
**注意**
在管理 Systems Manager 使用的 IAM policy 中指定的权限，不得限制您为使更改请求能够自动运行而提交自动批准更改请求。
+ **Specify approvers (指定审批人员)** – 您必须添加一个或多个用户、组或 IAM 角色，才能查看和批准此更改请求。
**注意**
即便在管理 Systems Manager 使用的 IAM policy 中指定的权限允许您运行自动批准更改请求，您也可以选择指定审核人员。
1. 选择 **Add approver (添加审批人员)**，然后从可用审核人员的列表中选择一个或多个用户、组或 AWS Identity and Access Management (IAM) 角色。
**注意**
可能已指定了一个或多个审批人员。这意味着已在您选择的更改模板中指定了强制审批人员。不能从请求中移除这些批准者。如果**添加审批者**按钮不可用，则您选择的模板不允许将其他审核者添加到请求。
有关批准更改请求的更多信息，请参阅 [关于更改请求批准](#cm-approvals-requests)。
1. 在 **SNS topic to notify approvers (用于通知审批人员的 SNS 主题)** 中，请选择以下选项之一，以便在您的账户中指定要用于向您添加到此更改请求的审批人员发送通知的 Amazon SNS 主题。
**注意**
如果用于指定 Amazon SNS 主题的选项不可用，则您选择的更改模板已指定了要使用的 Amazon SNS 主题。
+ **Enter an SNS Amazon Resource Name (ARN)** [输入 SNS Amazon 资源名称 (ARN)] – 对于 **Topic ARN**（主题 ARN），请输入现有 Amazon SNS 主题的 ARN。此主题可以位于您组织的任何账户中。
+ **Select an existing SNS topic (选择现有 SNS 主题)** – 对于 **Target notification topic (设定通知主题目标)**，选择您的当前账户中现有 Amazon SNS 主题的 ARN。（如果您尚未在当前的 AWS 账户 和 AWS 区域 中创建任何 Amazon SNS 主题，则此选项不可用。）
**注意**
您选择的 Amazon SNS 主题必须被配置为指定它所发送的通知，以及接收这些通知的订阅者。其访问策略还必须向 Systems Manager 授予权限，以便 Change Manager 可以发送通知。有关信息，请参阅[为 Change Manager 通知配置 Amazon SNS 主题](change-manager-sns-setup.md)。
1. 选择 **Add notification（添加通知）**。
1. 选择**下一步**。
1. 对于 **IAM role (IAM 角色)**，请选择*您的当前账户中*拥有所需权限、能够运行为此更改请求指定的运行手册的 IAM 角色。
此角色也称为 自动化的服务角色或代入角色。有关该角色的更多信息，请参阅 [设置自动化](automation-setup.md)。
1. 在 **Deployment location (部署位置)** 部分中，选择以下选项之一：
**注意**
如果您仅将 Change Manager 用于单个 AWS 账户，而非用于在 AWS Organizations 中设置的组织，则不需要指定部署位置。
+ **Apply change to this account (将更改应用于此账户)** – 运行手册工作流仅在当前账户中运行。对于组织，这意味着委托管理员账户。
+ **Apply change to multiple organizational units (OUs) (将更改应用于多个组织单元 (OU))** – 请执行以下操作：
1. 对于 **Accounts and organizational units (OUs) (账户和组织单位 (OU))**，请输入您的组织中成员账户的 ID，格式为 **123456789012**；或组织单位的 ID，格式为 **o-o96EXAMPLE**。
1. （可选）对于 **Execution role name (执行角色名称)**，请输入*目标账户*或 OU 中拥有所需权限、能够运行为此更改请求指定的运行手册的 IAM 角色的名称。您指定的任何 OU 中的所有账户都应该为此角色使用相同的名称。
1. （可选）对于您要指定的每个额外账户或 OU，请选择 **Add another target location (添加其他目标位置)**，并重复步骤 a 和 b。
1. 对于 **Target AWS 区域 (目标 Amazon Web Services Region)**，请选择要在其中进行更改的 Region，例如为美国东部（俄亥俄）区域选择 `Ohio (us-east-2)`。
1. 展开 **Rate control (速率控制)**。
对于 **Concurrency (并发)**，请输入一个数字，然后从列表中选择此数字是表示可在其中同时运行运行手册工作流的账户数量还是百分比。
对于 **Error threshold (错误阈值)**，请输入一个数字，然后从列表中选择此数字是表示在停止操作之前其中的运行手册工作流可能失败的账户数量还是百分比。
1. 在 **Deployment targets (部署目标)** 部分中，执行以下操作：
1. 选择下列选项之一：
+ **Single resource (单个资源)** – 仅对一个资源进行更改。例如，单个节点或单个 Amazon Machine Image (AMI)，具体取决于在此更改请求的运行手册中定义的操作。
+ **Multiple resources (多个资源)** – 对于 **Parameter (参数)**，请从此更改请求的运行手册内的可用参数中进行选择。此选择反映了要更新的资源的类型。
例如，如果此更改请求的运行手册为 `AWS-RetartEC2Instance`，则可选择 `InstanceId`，然后通过从以下选项中进行选择，来定义要更新的实例：
+ **Specify tags (指定标签)** - 输入标记要更新的所有资源时使用的键值对。
+ **Choose a resource group (选择资源组)** - 选择要更新的所有资源所属的资源组的名称。
+ **Specify parameter values (指定参数值)** - 确定 **Runbook parameters (运行手册参数)** 部分中要更新的资源。
+ **Target all instances**（将所有实例设为目标）- 对目标位置中的所有托管式节点进行更改。
1. 如果您选择了 **Multiple resources (多个资源)**，请展开 **Rate control (速率控制)**。
对于 **Concurrency (并发)**，请输入一个数字，然后从列表中选择此数字是表示运行手册工作流可以同时更新的目标的数量还是百分比。
对于 **Error threshold (错误阈值)**，请输入一个数字，然后从列表中选择此数字是表示在停止操作之前更新可能失败的目标的数量还是百分比。
1. 如果您选择了 **Specify parameter values (指定参数值)**，以更新上一步中的多个资源：在 **Runbook parameters (运行手册参数)** 部分中，指定所需输入参数的值。您必须提供的参数值基于与所选更改模板相关联的自动化运行手册的内容。
例如，如果更改模板使用 `AWS-RetartEC2Instance` 运行手册，则您必须为 **InstanceId** 参数输入一个或多个实例 ID。或者，选择 **Show interactive instance picker (显示交互式实例选择器)**，然后逐个选择可用实例。
1. 选择**下一步**。
1. 在 **Review and submit (审核并提交)** 页面上，仔细检查您为此更改请求指定的资源和选项。
对于您要对其进行更改的任何部分，请选择 **Edit (编辑)** 按钮。
如果您对更改请求详细信息感到满意，请选择 **Submit for approval (提交以供批准)**。
如果已在您为请求选择的更改模板中指定了 Amazon SNS 主题，则当该请求被拒绝或批准时，系统会发送通知。如果您未收到有关该请求的通知，您可以返回到 Change Manager 以检查您的请求的状态。
## 创建更改请求 (AWS CLI)
您可以使用 AWS Command Line Interface (AWS CLI) 创建更改请求，方法是在 JSON 文件中指定更改请求的选项和参数，并使用 `--cli-input-json` 选项将其包含在您的命令中。
**创建更改请求 (AWS CLI)**
1. 安装并配置 AWS Tools for PowerShell (AWS CLI)（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)以及[安装 AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html)。
1. 在本地计算机上使用 `MyChangeRequest.json` 之类的名称创建一个 JSON 文件，然后将以下内容粘贴到此文件中。
将*占位符*替换为您的更改请求的值。
**注意**
此示例 JSON 使用 `AWS-HelloWorldChangeTemplate` 更改模板和 `AWS-HelloWorld` 运行手册创建更改请求。要帮助您根据自己的更改请求调整此示例，请参阅**《AWS Systems Manager API Reference》中的 [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_StartChangeRequestExecution.html)，以了解有关所有可用参数的信息
有关批准更改请求的更多信息，请参阅 [关于更改请求批准](#cm-approvals-requests)。
```
{
"ChangeRequestName": "MyChangeRequest",
"DocumentName": "AWS-HelloWorldChangeTemplate",
"DocumentVersion": "$DEFAULT",
"ScheduledTime": "2021-12-30T03:00:00",
"ScheduledEndTime": "2021-12-30T03:05:00",
"Tags": [
{
"Key": "Purpose",
"Value": "Testing"
}
],
"Parameters": {
"Approver": [
"JohnDoe"
],
"ApproverType": [
"IamUser"
],
"ApproverSnsTopicArn": [
"arn:aws:sns:us-east-2:123456789012:MyNotificationTopic"
]
},
"Runbooks": [
{
"DocumentName": "AWS-HelloWorld",
"DocumentVersion": "1",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Parameters": {
"AutomationAssumeRole": [
"arn:aws:iam::123456789012:role/MyChangeManagerAssumeRole"
]
}
}
],
"ChangeDetails": "### Document Name: HelloWorldChangeTemplate\n\n## What does this document do?\nThis change template demonstrates the feature set available for creating change templates for Change Manager. This template starts a Runbook workflow for the Automation document called AWS-HelloWorld.\n\n## Input Parameters\n* ApproverSnsTopicArn: (Required) Amazon Simple Notification Service ARN for approvers.\n* Approver: (Required) The name of the approver to send this request to.\n* ApproverType: (Required) The type of reviewer.\n * Allowed Values: IamUser, IamGroup, IamRole, SSOGroup, SSOUser\n\n## Output Parameters\nThis document has no outputs \n"
}
```
1. 在创建此 JSON 文件的目录中，运行以下命令。
```
aws ssm start-change-request-execution --cli-input-json file://MyChangeRequest.json
```
系统将返回类似于以下内容的信息。
```
{
"AutomationExecutionId": "b3c1357a-5756-4839-8617-2d2a4EXAMPLE"
}
```
# 审核和批准或拒绝更改请求
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
如果在 Change Manager（AWS Systems Manager 中的一项工具）中被指定为更改请求的审核人员，只要有新的更改请求等待审核，您就会通过 Amazon Simple Notification Service（Amazon SNS）主题收到通知。
**注意**
此功能取决于是否在更改模板中指定了 Amazon SNS 来发送审核通知。有关信息，请参阅[为 Change Manager 通知配置 Amazon SNS 主题](change-manager-sns-setup.md)。
要审核更改请求，可以访问您的通知中的链接，或直接登录到 AWS 管理控制台，然后按照本过程中的步骤进行操作。
**注意**
如果在更改模板中为审核人员分配了 Amazon SNS 主题，则当更改请求状态发生变化时，会向该主题的订阅者发送通知。
有关批准更改请求的更多信息，请参阅 [关于更改请求批准](change-requests-create.md#cm-approvals-requests)。
## 审核和批准或拒绝更改请求（控制台）
以下过程介绍了如何使用 Systems Manager 控制台审核和批准或拒绝更改请求。
**审核和批准或拒绝更改请求**
1. 打开您收到的电子邮件通知中的链接，然后登录到 AWS 管理控制台，它将引导您转到供您审核的更改请求。
1. 在摘要页面中，审核更改请求的建议内容。
要批准更改请求，请选择 **Approve (批准)**。在对话框中，提供您要为此批准添加的任何注释，然后选择 **Approve (批准)**。此请求所代表的运行手册工作流将按计划开始运行，或在更改未被任何限制阻止时立即开始运行。
–或者–
要拒绝更改请求，请选择 **Reject (拒绝)**。在对话框中，提供您要为此拒绝添加的任何注释，然后选择 **Reject (拒绝)**。
**批量审核和批准或拒绝更改请求**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，请选择 **Change Manager**。
1. 选择 **Approvals**（批准）选项卡。
1. （可选）通过选择每个请求的名称来查看等待批准的请求的详细信息，然后返回到 **Approvals**（批准）选项卡。
1. 选中要批准的每个更改请求的复选框。
–或者–
选中要拒绝的每个更改请求的复选框。
1. 在对话框中，提供您要为此批准或拒绝添加的任何注释。
1. 根据您是要批准还是拒绝选定的更改请求，选择 **Approve**（批准）或 **Reject**（拒绝）。
## 审核和批准或拒绝更改请求（命令行）
以下过程介绍了如何使用 AWS Command Line Interface（AWS CLI）（在 Linux、macOS 或 Windows Server 上）审核并批准或拒绝更改请求。
**审核和批准或拒绝更改请求**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 在您的本地计算机上创建一个 JSON 文件，该文件将为您的 AWS CLI 调用指定参数。
```
{
"OpsItemFilters":
[
{
"Key": "OpsItemType",
"Values": ["/aws/changerequest"],
"Operator": "Equal"
}
],
"MaxResults": number
}
```
您可以通过在该 JSON 文件中指定审批人员的 Amazon Resource Name (ARN) 来筛选特定审批人员的结果。见下列。
```
{
"OpsItemFilters":
[
{
"Key": "OpsItemType",
"Values": ["/aws/changerequest"],
"Operator": "Equal"
},
{
"Key": "ChangeRequestByApproverArn",
"Values": ["arn:aws:iam::account-id:user/user-name"],
"Operator": "Equal"
}
],
"MaxResults": number
}
```
1. 运行以下命令可以查看您在 JSON 文件中指定的最大更改请求数量。
------
#### [ Linux & macOS ]
```
aws ssm describe-ops-items \
--cli-input-json file://filename.json
```
------
#### [ Windows ]
```
aws ssm describe-ops-items ^
--cli-input-json file://filename.json
```
------
1. 运行以下命令可以批准或拒绝更改请求。
------
#### [ Linux & macOS ]
```
aws ssm send-automation-signal \
--automation-execution-id ID \
--signal-type Approve_or_Reject \
--payload Comment="message"
```
------
#### [ Windows ]
```
aws ssm send-automation-signal ^
--automation-execution-id ID ^
--signal-type Approve_or_Reject ^
--payload Comment="message"
```
------
如果已在您为请求选择的更改模板中指定了 Amazon SNS 主题，则当该请求被拒绝或批准时，系统会发送通知。如果您未收到有关该请求的通知，您可以返回到 Change Manager 以检查您的请求的状态。有关使用此命令时其他选项的信息，请参阅 **《AWS CLI Command Reference》的 AWS Systems Manager 部分中的 [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-automation-signal.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-automation-signal.html)。
# 审核更改请求详细信息、任务和时间表（控制台）
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
您可以在 Change Manager（AWS Systems Manager 中的一项工具）的控制面板中查看有关更改请求（包括已处理其更改的请求）的信息。这些详细信息包含一个链接，它指向运行进行更改的运行手册的自动化操作。在创建请求时会生成自动化执行 ID，但仅在获得所有批准并且没有部署任何阻止更改的限制的情况下，该流程才会运行。
**审核更改请求详细信息、任务和时间表**
1. 在导航窗格中，请选择 **Change Manager**。
1. 选择 **Requests (请求)** 选项卡。
1. 在 **Change requests (更改请求)** 部分中，搜索您要审核的更改请求。
您可以使用 **Create date range (创建日期范围)** 选项，将结果限制在特定时间段内。
您可以通过以下属性筛选请求：
+ `Status`
+ `Request ID`
+ `Approver`
+ `Requester`
例如，要查看有关在过去 24 小时内成功完成的所有更改请求的详细信息，请执行以下操作：
1. 对于 **Create date range (创建日期范围)**，请选择 **1d**。
1. 在搜索框中，选择 **Status (状态)、CompletedWithSuccess**。
1. 在结果中，选择要审核其结果的、已成功完成的更改请求的名称。
1. 在以下选项卡上查看有关更改请求的信息：
+ **Request details (请求详细信息)** - 查看有关更改请求的基本详细信息，包括请求者、更改模板，和为更改选择的自动化运行手册。您还可以访问指向自动化操作详细信息的链接，查看有关请求中指定的任何运行手册参数、分配给更改请求的 Amazon CloudWatch 告警以及为请求提供的批准和注释的信息。
+ **Task (任务)** - 查看有关更改中的任务的信息，包括已完成的更改请求的任务状态、目标资源、关联的自动化运行手册中的步骤，以及并发和错误阈值详细信息。
+ **Timeline (时间表)** - 查看与更改请求关联的所有事件的摘要，按日期和时间列出。该摘要将指明创建更改请求的时间、指定的审批人员的操作、已批准的更改请求计划运行时间的记录、运行手册工作流详细信息，以及运行手册中整个更改流程和每个步骤的状态变化。
+ **Associated events**（关联事件）：查看有关在 [AWS CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html) 中记录的变更请求的可审批详细信息。详细信息包括运行了哪些 API 操作、这些操作包含的请求参数、运行操作的用户账户、在此过程中更新的资源等。
当您启用 CloudTrail Lake 事件跟踪时，CloudTrail Lake 会为与您的变更请求相关的事件创建事件数据存储。事件详细信息适用于提出变更请求的账户或组织。您可以通过账户或组织中的任何变更请求启用 CloudTrail Lake 事件跟踪。有关启用 CloudTrail Lake 集成和创建事件数据存储的信息，请参阅 [监控您的变更请求事件](monitoring-change-request-events.md)。
**注意**
使用 **CloudTrail Lake** 需要付费。有关详细信息，请参阅 [AWS CloudTrail 定价](https://aws.amazon.com/cloudtrail/pricing/)。
# 查看更改请求的聚合计数（命令行）
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
您可以使用 [GetOpsSummary](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetOpsSummary.html) API 操作，查看 Change Manager（AWS Systems Manager 中的一项工具）中更改请求的汇总计数。此 API 操作可以返回单个 AWS 区域中的单个 AWS 账户的计数，或者多个账户和多个区域的计数。
**注意**
如果您要查看多个 AWS 账户 和多个 AWS 区域 的聚合计数，必须设置和配置资源数据同步。有关更多信息，请参阅 [为 Inventory 创建资源数据同步](inventory-create-resource-data-sync.md)。
以下过程介绍了如何使用 AWS Command Line Interface（AWS CLI）（在 Linux、macOS 或 Windows Server 上）查看更改请求的聚合计数。
**查看更改请求的聚合计数**
1. 安装并配置 AWS Command Line Interface（AWS CLI）（如果尚未执行该操作）。
有关信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 运行以下命令之一。
**Single account and Region (单个账户和区域)**
此命令将返回为其配置您的 AWS CLI 会话的 AWS 账户 和 AWS 区域 的所有更改请求的计数。
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
该调用将返回类似于以下内容的信息。
```
{
"Entities": [
{
"Data": {
"AWS:OpsItem": {
"Content": [
{
"Count": "38",
"Status": "Open"
}
]
}
}
}
]
}
```
**Multiple accounts and/or Regions (多个账户和/或区域)**
此命令将返回在资源数据同步中指定的 AWS 账户和 AWS 区域的所有更改请求的计数。
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--sync-name resource_data_sync_name \
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--sync-name resource_data_sync_name ^
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
该调用将返回类似于以下内容的信息。
```
{
"Entities": [
{
"Data": {
"AWS:OpsItem": {
"Content": [
{
"Count": "43",
"Status": "Open"
},
{
"Count": "2",
"Status": "Resolved"
}
]
}
}
}
]
}
```
**Multiple accounts and a specific Region (多个账户和某一特定区域)**
此命令将返回在资源数据同步中指定的 AWS 账户 的所有更改请求的计数。但是，它只会返回该命令中指定的区域中的数据。
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--sync-name resource_data_sync_name \
--filters Key=AWS:OpsItem.SourceRegion,Values='Region',Type=Equal Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--sync-name resource_data_sync_name ^
--filters Key=AWS:OpsItem.SourceRegion,Values='Region',Type=Equal Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators AggregatorType=count,AttributeName=Status,TypeName=AWS:OpsItem
```
------
**Multiple accounts and Regions with output grouped by Region (输出按区域分组的多个账户和区域)**
此命令将返回在资源数据同步中指定的 AWS 账户和 AWS 区域的所有更改请求的计数。输出将显示每个区域的计数信息。
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--sync-name resource_data_sync_name \
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators '[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"Status","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceRegion"}]}]'
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--sync-name resource_data_sync_name ^
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators '[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"Status","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceRegion"}]}]'
```
------
该调用将返回类似于以下内容的信息。
```
{
"Entities": [
{
"Data": {
"AWS:OpsItem": {
"Content": [
{
"Count": "38",
"SourceRegion": "us-east-1",
"Status": "Open"
},
{
"Count": "4",
"SourceRegion": "us-east-2",
"Status": "Open"
},
{
"Count": "1",
"SourceRegion": "us-west-1",
"Status": "Open"
},
{
"Count": "2",
"SourceRegion": "us-east-2",
"Status": "Resolved"
}
]
}
}
}
]
}
```
**Multiple accounts and Regions with output grouped by accounts and Regions (输出按帐户和区域分组的多个账户和区域)**
此命令将返回在资源数据同步中指定的 AWS 账户 和 AWS 区域 的所有更改请求的计数。输出将按账户和区域对计数信息进行分组。
------
#### [ Linux & macOS ]
```
aws ssm get-ops-summary \
--sync-name resource_data_sync_name \
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal \
--aggregators '[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"Status","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceAccountId","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceRegion"}]}]}]'
```
------
#### [ Windows ]
```
aws ssm get-ops-summary ^
--sync-name resource_data_sync_name ^
--filters Key=AWS:OpsItem.OpsItemType,Values="/aws/changerequests",Type=Equal ^
--aggregators '[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"Status","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceAccountId","Aggregators":[{"AggregatorType":"count","TypeName":"AWS:OpsItem","AttributeName":"SourceRegion"}]}]}]'
```
------
该调用将返回类似于以下内容的信息。
```
{
"Entities": [
{
"Data": {
"AWS:OpsItem": {
"Content": [
{
"Count": "38",
"SourceAccountId": "123456789012",
"SourceRegion": "us-east-1",
"Status": "Open"
},
{
"Count": "4",
"SourceAccountId": "111122223333",
"SourceRegion": "us-east-2",
"Status": "Open"
},
{
"Count": "1",
"SourceAccountId": "111122223333",
"SourceRegion": "us-west-1",
"Status": "Open"
},
{
"Count": "2",
"SourceAccountId": "444455556666",
"SourceRegion": "us-east-2",
"Status": "Resolved"
},
{
"Count": "1",
"SourceAccountId": "222222222222",
"SourceRegion": "us-east-1",
"Status": "Open"
}
]
}
}
}
]
}
```
# 审计和记录 Change Manager 活动
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
您可以使用 Amazon CloudWatch 和 AWS CloudTrail 警报，审核 Change Manager（AWS Systems Manager 中的一项工具）中的活动。
有关 Systems Manager 的审计和日志记录选项的更多信息，请参阅 [AWS Systems Manager 中的日志记录和监控](monitoring.md)。
## 使用 CloudWatch 告警审计 Change Manager
您可以配置 CloudWatch 告警并将其分配给更改模板。如果满足该告警中定义的任何条件，则将执行为该告警指定的操作。在告警配置中，您可以指定 Amazon Simple Notification Service (Amazon SNS) 主题，以便在满足告警条件时发送通知。
有关创建 Change Manager 模板的信息，请参阅 [使用更改模板](change-templates.md)。
有关创建 CloudWatch 告警的信息，请参阅 [Amazon CloudWatch 用户指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)中的*使用 CloudWatch 告警*。
## 使用 CloudTrail 审计 Change Manager 的活动
CloudTrail 可以捕获在 Systems Manager 控制台、AWS Command Line Interface (AWS CLI) 和 Systems Manager 软件开发工具包中进行的 API 调用。您可以在 CloudTrail 控制台或 Amazon Simple Storage Service (Amazon S3) 存储桶中查看信息，这些信息存储在其中。账户的所有 CloudTrail 日志都存储在一个存储桶中。
Change Manager 操作的日志可以显示更改模板文档创建、更改模板和更改请求批准及拒绝、自动化运行手册生成的活动等。有关查看和使用 Systems Manager 活动的 CloudTrail 日志的更多信息，请参阅 [使用 AWS CloudTrail 记录 AWS Systems Manager API 调用](monitoring-cloudtrail-logs.md)。
# 排除 Change Manager 问题
**Change Manager 可用性变更**
自 2025 年 11 月 7 日起，AWS Systems Manager Change Manager 将不再向新客户开放。如果想要使用 Change Manager，请在该日期之前注册。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [AWS Systems Manager Change Manager 可用性变更](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html)。
利用以下信息，帮助排查Change Manager（AWS Systems Manager 中的一项工具）出现的问题。
**Topics**
+ [在使用 Active Directory（组）时，在更改请求批准期间出现“Group *\$1GUID\$1* not found”（未找到组 \$1GUID\$1）错误。](#change-manager-troubleshooting-sso)
## 在使用 Active Directory（组）时，在更改请求批准期间出现“Group *\$1GUID\$1* not found”（未找到组 \$1GUID\$1）错误。
**问题**：在将 AWS IAM Identity Center（IAM Identity Center）用于用户身份管理时，已在 Change Manager 中获得批准权限的 Active Directory 组成员收到“not authorized”（未授权）或“group not found”（未找到组）错误。
+ **解决方法**：当您在 IAM Identity Center 中选择 Active Directory 组以访问 AWS 管理控制台 时，系统将计划定期同步，以将这些 Active Directory 组中的信息复制到 IAM Identity Center。必须完成此流程，然后通过 Active Directory 组成员身份授权的用户才能成功批准请求。有关更多信息，请参阅 *AWS IAM Identity Center 用户指南*中的[连接到您的 Microsoft AD 目录](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-ad.html)。
# AWS Systems Manager 文档
AWS Systems Manager 文档 (SSM document) 定义 Systems Manager 对您的托管实例执行的操作。Systems Manager 包括 100 个预先配置的文档，您可以在运行时通过指定参数进行使用。您可以在 Systems Manager 文档控制台中找到预配置的文档，方法是选择 **Owned by Amazon**（Amazon 所有）选项卡，或者通过在调用 `ListDocuments` API 操作时指定 Amazon `Owner` 筛选条件。文档使用 JavaScript 对象表示法 (JSON) 或 YAML，并包括您指定的步骤和参数。
为增强安全性，从 2025 年 7 月 14 日起，SSM 文档在处理参数时支持环境变量插值。此功能在 2.2 版架构和 3.3.2746.0 或更高版本的 SSM Agent 中可用，可帮助防范命令注入攻击。
要开始使用 SSM 文档，请打开 [Systems Manager 控制台](https://console.aws.amazon.com/systems-manager/documents)。在导航窗格中，选择**文档**。
**重要**
在 Systems Manager 中，*Amazon 拥有的* SSM 文档是由 Amazon Web Services 自己创建和管理的文档。*Amazon 拥有的*文档在文档名称中包含 `AWS-*` 之类的前缀。文档的所有者被视为 Amazon，而不是 AWS 内的特定用户账户。这些文档可供所有人公开使用。
## 我的组织如何从 Documents 工具获益？
Documents（AWS Systems Manager 中的一项工具）具有以下优点：
+ **文档类别**
为了帮助您找到所需的文档，请根据要搜索的文档类型选择一个类别。要扩大搜索范围，您可以选择同一文档类型的多个类别。不支持选择不同文档类型的类别。分类仅支持 Amazon 拥有的文档。
+ **文档版本**
您可以创建并保存不同版本的文档。您可以为每个文档指定默认版本。文档的默认版本可以更新到较新版本或恢复到较旧版本。当您更改文档的内容时，Systems Manager 将自动递增文档的版本。您可以通过在控制台、AWS Command Line Interface (AWS CLI) 命令或 API 调用中指定文档版本来检索或使用任何版本的文档。
+ **根据您的需求自定义文档**
如果您要通过文档自定义步骤和操作，可以自行创建文档。系统将文档与您的 AWS 账户 一起存储在创建其所在的 AWS 区域 中。有关如何创建 SSM 文档的更多信息，请参阅 [创建 SSM 文档内容](documents-creating-content.md)。
+ **标记文档**
您可以标记文档，以便根据为其分配的标签快速识别一个或多个文档。例如，您可以为特定环境、部门、用户、组或时间段的文档添加标签。此外，您还可以通过创建一个指定用户或组可访问的标签的 AWS Identity and Access Management (IAM) policy 来限制对文档的访问。
+ **共享文档**
您可以将文档公开，或者将它们与同一 AWS 区域 区域中的特定 AWS 账户 共享。在账户之间共享文档可能很有用，例如，如果您希望提供给客户或员工的所有 Amazon Elastic Compute Cloud (Amazon EC2) 实例都能够具有相同配置。除了保持实例上的应用程序或补丁的最新状态，您可能还希望限制客户实例执行某些活动。或者，您可能需要确保整个组织的员工账户使用的实例均被授予访问特定内部资源的访问权限。有关更多信息，请参阅 [共享 SSM 文档](documents-ssm-sharing.md)。
## 谁应该使用文档？
+ 任何希望使用 Systems Manager 工具大规模提高其运营效率、减少与手动干预相关的错误以及缩短解决常见问题的时间的 AWS 客户。
+ 希望自动执行部署和配置任务的基础设施专家。
+ 想要可靠地解决常见问题、提高故障排除效率和减少重复性操作的管理员。
+ 想要自动执行通常需要手动执行的任务的用户。
## SSM 文档有哪些类型？
下表介绍了不同类型的 SSM 文档及其使用。
****
| Type | 一起使用 | Details |
| --- | --- | --- |
| ApplicationConfiguration ApplicationConfigurationSchema | [AWS AppConfig](https://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html) | AWS AppConfig 是 AWS Systems Manager 中的一项工具，可让您创建、管理以及快速部署应用程序配置。您可以通过创建使用 `ApplicationConfiguration` 文档类型的文档，从而将配置数据存储到 SSM 文档中。有关更多信息，请参阅《AWS AppConfig 用户指南》**中的[自由度配置](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile.html#free-form-configurations)。 如果在 SSM 文档中创建配置，则必须指定对应的 JSON Schema。该 schema 使用 `ApplicationConfigurationSchema` 文档类型，并且与一组规则类似，它会定义每个应用程序配置设置允许的属性。有关更多信息，请参阅《AWS AppConfig 用户指南》**中的[关于验证器](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-creating-configuration-and-profile-validators.html)。 |
| 自动化运行手册 | [自动化](systems-manager-automation.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | 在执行常规维护和部署任务 – 如创建或更新 Amazon Machine Image (AMI)时使用自动化手册 - 使用自动化运行手册。State Manager 使用自动化运行手册应用配置。这些操作可以在实例生命周期内的任何时刻在一个或多个目标上运行。Maintenance Windows 使用自动化运行手册基于指定的计划执行常规维护和部署任务。 macOS 的 EC2 实例也支持基于 Linux 的操作系统支持的所有自动化运行手册。 |
| 更改日历文档 | [Change Calendar](systems-manager-change-calendar.md) | Change Calendar 是 AWS Systems Manager 中的一项工具，使用 `ChangeCalendar` 文档类型。Change Calendar 文档存储日历条目和关联的事件，这些事件可以允许或阻止自动化操作更改您的环境。在 Change Calendar 中，文档以明文格式存储 [iCalendar 2.0](https://icalendar.org/) 数据。 Change Calendar 在 EC2 实例上不支持 macOS。 |
| AWS CloudFormation 模板 | [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) | AWS CloudFormation 模板描述您要在 CloudFormation 堆栈中调配的资源。通过将 CloudFormation 模板存储为 Systems Manager 文档，您可以受益于 Systems Manager 文档功能。其中包括创建和比较模板的多个版本，以及与同一 AWS 区域 中的其它账号共享模板。 您可以使用 Application Manager（Systems Manager 中的一项工具）创建和编辑 CloudFormation 模板及堆栈。有关更多信息，请参阅 [在 Application Manager 中使用 CloudFormation 模板和堆栈](application-manager-working-stacks.md)。 |
| 命令文档 | [Run Command](run-command.md) [State Manager](systems-manager-state.md) [Maintenance Windows](maintenance-windows.md) | Run Command 是 AWS Systems Manager 中的一项工具，使用命令文档运行命令。State Manager是 AWS Systems Manager 中的一项工具，使用命令文档应用配置。这些操作可以在实例生命周期内的任何时刻在一个或多个目标上运行。Maintenance Windows 是 AWS Systems Manager 中的一项工具，使用命令文档基于指定的计划应用配置。 大多数命令文档在所有 Linux 和 Systems Manager 所支持的 Windows Server 操作系统上受支持。macOS 的 EC2 实例支持以下命令文档： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/documents.html) |
| AWS Config 一致性包模板 | [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) | AWS Config 一致性包模板是 YAML 格式的文档，用于创建包含 AWS Config 规则（托管或自定义）和修复操作列表的一致性包。 有关更多信息，请参阅[一致性包](https://docs.aws.amazon.com/config/latest/developerguide/conformance-packs.html)。 |
| 软件包文档 | [Distributor](distributor.md) | 在 Distributor（AWS Systems Manager 中的一项工具）中，软件包用 SSM 文档表示。软件包文档包括附加的 ZIP 存档文件，其中包含要在托管实例上安装的软件或资产。在 Distributor 中创建软件包会创建软件包文档。 Oracle Linux 和 macOS 托管实例上不受支持 Distributor。 |
| 策略文档 | [State Manager](systems-manager-state.md) | Inventory 是 AWS Systems Manager 中的一项工具，使用 `AWS-GatherSoftwareInventory` 策略文档和State Manager关联从托管式实例中收集清单数据。在创建您自己的 SSM 文档时，自动化文档和命令文档是在托管实例上实施策略的首选方法。 Systems Manager 清单和 `AWS-GatherSoftwareInventory` 策略文档在 Systems Manager 所支持的所有操作系统上均受支持。 |
| 事件后分析模板 | [Incident Manager 事件后分析](https://docs.aws.amazon.com/incident-manager/latest/userguide/analysis.html) | Incident Manager 使用事件后分析模板基于 AWS 运营管理最佳实践创建分析。 使用模板创建分析，您的团队可以使用该分析来了解如何改进事件响应。 |
| 会话文档 | [Session Manager](session-manager.md) | Session Manager 是 AWS Systems Manager 中的一项工具，使用会话文档确定要启动哪些类型的会话，例如端口转发会话、运行交互式命令的会话或创建 SSH 隧道的会话。 Systems Manager 支持的所有 Linux 和 Windows Server 操作系统都支持会话文档。macOS 的 EC2 实例支持以下命令文档： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/documents.html) |
**SSM 文档配额**
有关 SSM 服务配额的更多信息，请参阅《Amazon Web Services 一般参考》**中的 [Systems Manager Service Quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm)。
**Topics**
+ [我的组织如何从 Documents 工具获益？](#ssm-docs-benefits)
+ [谁应该使用文档？](#documents-who)
+ [SSM 文档有哪些类型？](#what-are-document-types)
+ [文档组件](documents-components.md)
+ [创建 SSM 文档内容](documents-creating-content.md)
+ [使用文档](documents-using.md)
+ [参数处理问题的疑难解答](parameter-troubleshooting.md)
# 文档组件
本部分包含有关构成 SSM 文档的组件的信息。
**Topics**
+ [架构、功能和示例](documents-schemas-features.md)
+ [数据元素和参数](documents-syntax-data-elements-parameters.md)
+ [命令文档插件参考](documents-command-ssm-plugin-reference.md)
# 架构、功能和示例
AWS Systems Manager (SSM) 文档当前使用以下架构版本。
+ `Command` 型文档可以使用 1.2、2.0 和 2.2 版架构。如果您使用架构 1.2 文档，我们建议您创建使用架构版本 2.2 的文件。
+ `Policy` 型文档必须使用 2.0 版或更高版本的架构。
+ `Automation` 型文档必须使用 0.3 版架构。
+ `Session` 型文档必须使用 1.0 版架构。
+ 您可以创建 JSON 或 YAML 格式的文档。
有关 `Session` 文档架构的更多信息，请参阅 [会话文档架构](session-manager-schema.md)。
通过为 `Command` 和 `Policy` 文档使用最新架构版本，您可以利用以下功能。
**2.2 版架构文档功能**
| 功能 | Details |
| --- | --- |
| 编辑文档 | 文档现在可以更新。如果版本为 1.2，对文档的任何更新都需要另存为其他名称。 |
| 自动版本控制 | 对文档的任何更新都会创建一个新版本。这不是架构版本，而是文档版本。 |
| 默认版本 | 如果您拥有某个文档的多个版本，可以指定哪个版本是默认文档。 |
| 顺序 | 文档中的插件或*步骤*按指定的顺序运行。 |
| 跨平台支持 | 跨平台支持可让您为同一个 SSM 文档中的不同插件指定不同操作系统。跨平台支持在某个步骤中使用 `precondition` 参数。 |
| 参数插值 | 插值是指将变量值插入或替换到字符串中。可以将其想象为在使用字符串之前用实际值填充空白。在 SSM 文档上下文中，参数插值允许在执行命令之前将字符串参数插值到环境变量中，从而更好地防范命令注入攻击。设置为 `ENV_VAR` 时，代理会创建一个包含参数值的环境变量 `SSM_parameter-name`。 |
**注意**
您必须将实例上的 AWS Systems Manager SSM Agent 更新到最新版本才能使用新的 Systems Manager 功能和 SSM 文档功能。有关更多信息，请参阅 [使用 Run Command 更新 SSM Agent](run-command-tutorial-update-software.md#rc-console-agentexample)。
下表列出了主要架构版本之间的区别。
****
| 版本 1.2 | 版本 2.2（最新版本） | Details |
| --- | --- | --- |
| runtimeConfig | mainSteps | 在版本 2.2 中，`mainSteps` 部分替换了 `runtimeConfig` 部分。这些区域有：`mainSteps` 部分允许 Systems Manager 按顺序运行步骤。 |
| 属性 | 输入 | 在版本 2.2 中，`inputs` 部分替换了 `properties` 部分。`inputs` 部分接受步骤参数。 |
| 命令 | runCommand | 在版本 2.2 中，`inputs` 部分接收 `runCommand` 参数，而不是 `commands` 参数。 |
| id | action | 在版本 2.2 中，`Action` 替换了 `ID`。这只是更改了名称。 |
| 不适用 | 名称 | 在版本 2.2 中，`name` 是用户定义的任意步骤名称。 |
**使用前提条件参数**
在 2.2 版或更高版本架构中，您可以使用 `precondition` 参数为每个插件指定目标操作系统验证您在 SSM 文档中定义的输入参数。`precondition` 参数支持引用 SSM 文档的输入参数，`platformType` 使用`Linux` 的值、`MacOS`,和 `Windows`。仅支持 `StringEquals` 运算符。
对于使用 2.2 版或更高版本架构的文档，如果未指定 `precondition`，每个插件将被运行或跳过，具体取决于插件与操作系统的兼容性。插件与操作系统的兼容性在 `precondition` 之前被评估。对于使用 2.0 版或更低版本架构的文档，不兼容的插件将会引发错误。
例如，在 2.2 版架构文档中，如果未指定 `precondition`，将会列出 `aws:runShellScript` 插件，该步骤在 Linux 实例上运行，但系统会在 Windows Server 实例上跳过该步骤，因为 `aws:runShellScript` 与 Windows Server 实例不兼容。但是，对于 2.0 版架构文档，如果您指定 `aws:runShellScript` 插件，然后在 Windows Server 实例上运行文档，执行将会失败。本节稍后将介绍在 SSM 文档中使用前提条件参数的示例。
## 架构版本 2.2
**顶级元素**
以下示例使用 2.2 版架构显示 SSM 文档的顶级元素。
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: A description of the document.
parameters:
parameter 1:
property 1: "value"
property 2: "value"
parameter 2:
property 1: "value"
property 2: "value"
mainSteps:
- action: Plugin name
name: A name for the step.
inputs:
input 1: "value"
input 2: "value"
input 3: "{{ parameter 1 }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "A description of the document.",
"parameters": {
"parameter 1": {
"property 1": "value",
"property 2": "value"
},
"parameter 2":{
"property 1": "value",
"property 2": "value"
}
},
"mainSteps": [
{
"action": "Plugin name",
"name": "A name for the step.",
"inputs": {
"input 1": "value",
"input 2": "value",
"input 3": "{{ parameter 1 }}"
}
}
]
}
```
------
**2.2 版架构示例**
以下示例使用 `aws:runPowerShellScript` 插件在目标实例上运行 PowerShell 命令。
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: "Example document"
parameters:
Message:
type: "String"
description: "Example parameter"
default: "Hello World"
allowedValues:
- "Hello World"
mainSteps:
- action: "aws:runPowerShellScript"
name: "example"
inputs:
timeoutSeconds: '60'
runCommand:
- "Write-Output {{Message}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Example document",
"parameters": {
"Message": {
"type": "String",
"description": "Example parameter",
"default": "Hello World",
"allowedValues": ["Hello World"]
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "example",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"Write-Output {{Message}}"
]
}
}
]
}
```
------
**架构版本 2.2 前提条件参数示例**
2.2 版架构提供跨平台支持。这意味着在一个 SSM 文档内，您可以为不同的插件指定不同的操作系统。跨平台支持在某个步骤中使用 `precondition` 参数，如下例所示。您也可以使用 `precondition` 参数来验证您在 SSM 文档中定义的输入参数。您可以在以下第二个示例中看到此内容。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: cross-platform sample
mainSteps:
- action: aws:runPowerShellScript
name: PatchWindows
precondition:
StringEquals:
- platformType
- Windows
inputs:
runCommand:
- cmds
- action: aws:runShellScript
name: PatchLinux
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- cmds
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "cross-platform sample",
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "PatchWindows",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
},
{
"action": "aws:runShellScript",
"name": "PatchLinux",
"precondition": {
"StringEquals": [
"platformType",
"Linux"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
}
]
}
```
------
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
parameters:
action:
type: String
allowedValues:
- Install
- Uninstall
confirmed:
type: String
allowedValues:
- True
- False
mainSteps:
- action: aws:runShellScript
name: InstallAwsCLI
precondition:
StringEquals:
- "{{ action }}"
- "Install"
inputs:
runCommand:
- sudo apt install aws-cli
- action: aws:runShellScript
name: UninstallAwsCLI
precondition:
StringEquals:
- "{{ action }} {{ confirmed }}"
- "Uninstall True"
inputs:
runCommand:
- sudo apt remove aws-cli
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"parameters": {
"action": {
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"confirmed": {
"type": "String",
"allowedValues": [
true,
false
]
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "InstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }}",
"Install"
]
},
"inputs": {
"runCommand": [
"sudo apt install aws-cli"
]
}
},
{
"action": "aws:runShellScript",
"name": "UninstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }} {{ confirmed }}",
"Uninstall True"
]
},
"inputs": {
"runCommand": [
"sudo apt remove aws-cli"
]
}
}
]
}
```
------
**2.2 版架构插值示例（3.3.2746.0 之前的 SSM Agent 版本）**
在 3.3.2746.0 之前的 SSM Agent 版本中，代理会忽略 `interpolationType` 参数，转而执行原始字符串的替换。若要显式引用 `SSM_parameter-name`，则必须明确设置此项。以下 Linux 示例显式引用了环境变量 `SSM_Message`。
```
{
"schemaVersion": "2.2",
"description": "An example document",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern: "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**注意**
如果 SSM 文档未使用以下双大括号，则 `allowedPattern` 在技术上是不必要的：`{{ }}`
**2.2 版架构 State Manager 示例**
您可以将以下 SSM 文档用于State Manager（Systems Manager 中的一项工具）来下载并安装 ClamAV 防病毒软件。State Manager会强制实施特定配置，这意味着每次运行State Manager关联时，系统都会检查是否安装了 ClamAV 软件。如果未安装，State Manager 会重新运行本文档。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
name: configureServer
inputs:
runCommand:
- sudo yum install -y httpd24
- sudo yum --enablerepo=epel install -y clamav
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "State Manager Bootstrap Example",
"parameters": {},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "configureServer",
"inputs": {
"runCommand": [
"sudo yum install -y httpd24",
"sudo yum --enablerepo=epel install -y clamav"
]
}
}
]
}
```
------
**2.2 版架构清单示例**
您可以将以下 SSM 文档用于 State Manager,以收集关于实例的清单元数据。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:
applications:
type: String
default: Enabled
description: "(Optional) Collect data for installed applications."
allowedValues:
- Enabled
- Disabled
awsComponents:
type: String
default: Enabled
description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
allowedValues:
- Enabled
- Disabled
networkConfig:
type: String
default: Enabled
description: "(Optional) Collect data for Network configurations."
allowedValues:
- Enabled
- Disabled
windowsUpdates:
type: String
default: Enabled
description: "(Optional) Collect data for all Windows Updates."
allowedValues:
- Enabled
- Disabled
instanceDetailedInformation:
type: String
default: Enabled
description: "(Optional) Collect additional information about the instance, including
the CPU model, speed, and the number of cores, to name a few."
allowedValues:
- Enabled
- Disabled
customInventory:
type: String
default: Enabled
description: "(Optional) Collect data for custom inventory."
allowedValues:
- Enabled
- Disabled
mainSteps:
- action: aws:softwareInventory
name: collectSoftwareInventoryItems
inputs:
applications: "{{ applications }}"
awsComponents: "{{ awsComponents }}"
networkConfig: "{{ networkConfig }}"
windowsUpdates: "{{ windowsUpdates }}"
instanceDetailedInformation: "{{ instanceDetailedInformation }}"
customInventory: "{{ customInventory }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Software Inventory Policy Document.",
"parameters": {
"applications": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for installed applications.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"awsComponents": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"networkConfig": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for Network configurations.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"windowsUpdates": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for all Windows Updates.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"instanceDetailedInformation": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"customInventory": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for custom inventory.",
"allowedValues": [
"Enabled",
"Disabled"
]
}
},
"mainSteps": [
{
"action": "aws:softwareInventory",
"name": "collectSoftwareInventoryItems",
"inputs": {
"applications": "{{ applications }}",
"awsComponents": "{{ awsComponents }}",
"networkConfig": "{{ networkConfig }}",
"windowsUpdates": "{{ windowsUpdates }}",
"instanceDetailedInformation": "{{ instanceDetailedInformation }}",
"customInventory": "{{ customInventory }}"
}
}
]
}
```
------
**2.2 版架构 `AWS-ConfigureAWSPackage` 示例**
以下示例显示 `AWS-ConfigureAWSPackage` 文档。这些区域有：`mainSteps`部分包括`aws:configurePackage`插件`action`步骤。
**注意**
在 Linux 操作系统上，仅支持 `AmazonCloudWatchAgent` 和 `AWSSupport-EC2Rescue` 软件包。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Install or uninstall the latest version or specified version of an AWS
package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver,
AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.'
parameters:
action:
description: "(Required) Specify whether or not to install or uninstall the package."
type: String
allowedValues:
- Install
- Uninstall
name:
description: "(Required) The package to install/uninstall."
type: String
allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
version:
type: String
description: "(Optional) A specific version of the package to install or uninstall."
mainSteps:
- action: aws:configurePackage
name: configurePackage
inputs:
name: "{{ name }}"
action: "{{ action }}"
version: "{{ version }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
"parameters": {
"action": {
"description":"(Required) Specify whether or not to install or uninstall the package.",
"type":"String",
"allowedValues":[
"Install",
"Uninstall"
]
},
"name": {
"description": "(Required) The package to install/uninstall.",
"type": "String",
"allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
},
"version": {
"type": "String",
"description": "(Optional) A specific version of the package to install or uninstall."
}
},
"mainSteps":[
{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"version": "{{ version }}"
}
}
]
}
```
------
## 架构版本 1.2
以下示例显示 1.2 版架构文档的顶级元素。
```
{
"schemaVersion":"1.2",
"description":"A description of the SSM document.",
"parameters":{
"parameter 1":{
"one or more parameter properties"
},
"parameter 2":{
"one or more parameter properties"
},
"parameter 3":{
"one or more parameter properties"
}
},
"runtimeConfig":{
"plugin 1":{
"properties":[
{
"one or more plugin properties"
}
]
}
}
}
```
**1.2 版架构 `aws:runShellScript` 示例**
以下示例显示 `AWS-RunShellScript` SSM 文档。**runtimeConfig** 部分包含 `aws:runShellScript` 插件。
```
{
"schemaVersion":"1.2",
"description":"Run a shell script or specify the commands to run.",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
},
"workingDirectory":{
"type":"String",
"default":"",
"description":"(Optional) The path to the working directory on your instance.",
"maxChars":4096
},
"executionTimeout":{
"type":"String",
"default":"3600",
"description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
"allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
}
},
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
## 架构版本 0.3
**顶级元素**
以下示例显示 JSON 格式的架构 0.3 版自动化运行手册的顶级元素。
```
{
"description": "document-description",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"parameter1": {
"type": "String",
"description": "parameter-1-description",
"default": ""
},
"parameter2": {
"type": "String",
"description": "parameter-2-description",
"default": ""
}
},
"variables": {
"variable1": {
"type": "StringMap",
"description": "variable-1-description",
"default": {}
},
"variable2": {
"type": "String",
"description": "variable-2-description",
"default": "default-value"
}
},
"mainSteps": [
{
"name": "myStepName",
"action": "action-name",
"maxAttempts": 1,
"inputs": {
"Handler": "python-only-handler-name",
"Runtime": "runtime-name",
"Attachment": "script-or-zip-name"
},
"outputs": {
"Name": "output-name",
"Selector": "selector.value",
"Type": "data-type"
}
}
],
"files": {
"script-or-zip-name": {
"checksums": {
"sha256": "checksum"
},
"size": 1234
}
}
}
```
**YAML 自动化运行手册示例**
以下示例显示了 YAML 格式的自动化运行手册的内容。0.3 版文档架构的此工作示例还演示了如何使用 Markdown 格式化文档描述。
```
description: >-
##Title: LaunchInstanceAndCheckState
-----
**Purpose**: This Automation runbook first launches an EC2 instance
using the AMI ID provided in the parameter ```imageId```. The second step of
this document continuously checks the instance status check value for the
launched instance until the status ```ok``` is returned.
##Parameters:
-----
Name | Type | Description | Default Value
------------- | ------------- | ------------- | -------------
assumeRole | String | (Optional) The ARN of the role that allows Automation to
perform the actions on your behalf. | -
imageId | String | (Optional) The AMI ID to use for launching the instance.
The default value uses the latest Amazon Linux AMI ID available. | {{
ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
description: >-
(Optional) The AMI ID to use for launching the instance. The default value
uses the latest released Amazon Linux AMI ID.
tagValue:
type: String
default: ' LaunchedBySsmAutomation'
description: >-
(Optional) The tag value to add to the instance. The default value is
LaunchedBySsmAutomation.
instanceType:
type: String
default: t2.micro
description: >-
(Optional) The instance type to use for the instance. The default value is
t2.micro.
mainSteps:
- name: LaunchEc2Instance
action: 'aws:executeScript'
outputs:
- Name: payload
Selector: $.Payload
Type: StringMap
inputs:
Runtime: python3.11
Handler: launch_instance
Script: ''
InputPayload:
image_id: '{{ imageId }}'
tag_value: '{{ tagValue }}'
instance_type: '{{ instanceType }}'
Attachment: launch.py
description: >-
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript```
action and the provided python script.
- name: WaitForInstanceStatusOk
action: 'aws:executeScript'
inputs:
Runtime: python3.11
Handler: poll_instance
Script: |-
def poll_instance(events, context):
import boto3
import time
ec2 = boto3.client('ec2')
instance_id = events['InstanceId']
print('[INFO] Waiting for instance status check to report ok', instance_id)
instance_status = "null"
while True:
res = ec2.describe_instance_status(InstanceIds=[instance_id])
if len(res['InstanceStatuses']) == 0:
print("Instance status information is not available yet")
time.sleep(5)
continue
instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
print('[INFO] Polling to get status of the instance', instance_status)
if instance_status == 'ok':
break
time.sleep(10)
return {'Status': instance_status, 'InstanceId': instance_id}
InputPayload: '{{ LaunchEc2Instance.payload }}'
description: >-
**About This Step**
The python script continuously polls the instance status check value for
the instance launched in Step 1 until the ```ok``` status is returned.
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
## 安全处理参数示例
以下示例演示使用环境变量 `interpolationType` 安全处理参数。
### 基本安全命令执行
本示例说明如何安全处理命令参数：
**注意**
在不使用以下双大括号的 SSM 文档中，`allowedPattern` 在技术上是不必要的：`{{ }}`
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: An example document.
parameters:
Message:
type: String
description: "Message to be printed"
default: Hello
interpolationType: ENV_VAR
allowedPattern: "^[^"]*$"
mainSteps:
- action: aws:runShellScript
name: printMessage
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- echo {{Message}}
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition": {
"StringEquals": ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}]
}
```
------
### 在解释性语言中使用参数
本示例演示在 Python 中安全处理参数：
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### 向后兼容性示例
本示例展示如何安全处理参数，同时保持向后兼容性：
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**注意**
在不使用以下双大括号的 SSM 文档中，`allowedPattern` 在技术上是不必要的：`{{ }}`
## 参数安全的最佳实践
在处理 SSM 文档中的参数时，请遵循以下最佳实践：
+ **使用环境变量插值**：即将用于命令执行的字符串参数始终使用 `interpolationType: "ENV_VAR"`。
+ **实现输入验证**：使用 `allowedPattern` 将参数值限制为安全模式。
+ **处理遗留系统**：为不支持环境变量插值的旧版 SSM Agent 添加回退逻辑。
+ **转义特殊字符**：在命令中使用参数值时，请对特殊字符进行恰当转义以防止被 shell 解释。
+ **限制参数范围**：为用例使用尽可能严格的参数模式。
# 数据元素和参数
本主题介绍 SSM 文档中使用的数据元素。用于创建文档的架构版本定义了文档接受的语法和数据元素。我们建议您对命令文档使用架构版本 2.2 或更高版本。自动化运行手册使用架构版本 0.3。此外，自动化运行手册还支持使用 Markdown（一种标记语言），它允许您为文档和文档中的各个步骤添加 Wiki 样式的描述。有关使用 Markdown 的详细信息，请参阅*《AWS 管理控制台 入门指南》*中的[在控制台中使用 Markdown](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)。
以下部分介绍了 SSM 文档中可以包含的数据元素。
## 顶级数据元素
**schemaVersion**
要使用的架构版本。
类型：版本
是否必需：是
**描述**
您提供的描述文档目的的信息。您还可以使用此字段来指定参数是否需要一个值才能运行文档，或者为参数提供值是否为可选项。可在本主题的所有示例中查看必需参数和可选参数。
类型：字符串
必需：否
**参数**
定义文档接受的参数的结构。
为增强处理字符串参数的安全性，可通过指定 `interpolationType` 属性来使用环境变量插值。设置为 `ENV_VAR` 时，系统会创建一个包含参数值的环境变量 `SSM_parameter-name`。
下面是一个使用环境变量 `interpolationType` 的参数的示例：
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition" : {
"StringEquals" : ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}
}
```
在不使用以下双大括号的 SSM 文档中，`allowedPattern` 在技术上是不必要的：`{{ }}`
对于经常使用的参数，建议将这些参数存储在 Parameter Store（AWS Systems Manager 中的一项工具）中。然后，可以在文档中定义参数，并引用 Parameter Store 参数作为默认值。要引用 Parameter Store 参数，请使用以下语法。
```
{{ssm:parameter-name}}
```
可以使用参数通过与任何其他文档参数相同的方式引用 Parameter Store 参数。在以下示例中，`commands` 参数的默认值是 Parameter Store 参数 `myShellCommands`。如果将 `commands` 参数指定为 `runCommand` 字符串，文档将运行存储在 `myShellCommands` 参数中的命令。
```
---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
commands:
type: StringList
description: "(Required) The commands to run on the instance."
default: ["{{ ssm:myShellCommands }}"],
interpolationType : 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: runShellScriptDefaultParams
inputs:
runCommand:"{{ commands }}"
```
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScriptDefaultParams",
"inputs": {
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
您可以在文档的 `parameters` 部分引用 `String` 和 `StringList` Parameter Store 参数。您不能引用 `SecureString` Parameter Store 参数。
有关 Parameter Store 的更多信息，请参阅 [AWS Systems Manager Parameter Store](systems-manager-parameter-store.md)。
类型：结构
`parameters` 结构接受以下字段和值：
+ `type`：(必需) 允许的值包括：`String`、`StringList`、`Integer`、`Boolean`、`MapList` 和 `StringMap`。要查看每种类型的示例，请参阅下一节中的 [文档参数 `type` 示例](#top-level-properties-type)。
**注意**
命令类型文档仅支持 `String` 和 `StringList` 参数类型。
+ `description`：(可选) 关于参数的描述。
+ `default`：（可选）参数的默认值或对 Parameter Store 中参数的引用。
+ `allowedValues`：（可选）参数允许的值数组。定义参数的允许值将验证用户输入。如果用户输入了不允许的值，则执行将无法启动。
------
#### [ YAML ]
```
DirectoryType:
type: String
description: "(Required) The directory type to launch."
default: AwsMad
allowedValues:
- AdConnector
- AwsMad
- SimpleAd
```
------
#### [ JSON ]
```
"DirectoryType": {
"type": "String",
"description": "(Required) The directory type to launch.",
"default": "AwsMad",
"allowedValues": [
"AdConnector",
"AwsMad",
"SimpleAd"
]
}
```
------
+ `allowedPattern`：（可选）验证用户输入是否与参数的定义模式匹配的正则表达式。如果用户输入与允许的模式不匹配，则执行无法启动。
**注意**
Systems Manager 会执行两次 `allowedPattern` 验证。第一次验证是在您使用文档时利用 [Java 正则表达式库](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html)在 API 级别进行。第二次验证是在处理文档之前通过使用 [GO 正则表达式库](https://pkg.go.dev/regexp)在 SSM Agent 上进行。
------
#### [ YAML ]
```
InstanceId:
type: String
description: "(Required) The instance ID to target."
allowedPattern: "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$"
default: ''
```
------
#### [ JSON ]
```
"InstanceId": {
"type": "String",
"description": "(Required) The instance ID to target.",
"allowedPattern": "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$",
"default": ""
}
```
------
+ `displayType`：（可选）用于在 AWS 管理控制台 中显示 `textfield` 或 `textarea`。`textfield` 是单行文本框。`textarea` 是多行文本区域。
+ `minItems`：(可选) 允许的最小项目数。
+ `maxItems`：(可选) 允许的最大项目数。
+ `minChars`：(可选) 允许的最小参数字符数。
+ `maxChars`：(可选) 允许的最大参数字符数。
+ `interpolationType`：（可选）定义在执行命令之前如何处理参数值。如果设置为 `ENV_VAR`，则可以将参数值用作名为 `SSM_parameter-name` 的环境变量。此功能通过将参数值视为文字字符串，从而帮助防范命令注入攻击。
类型：字符串
有效值：`ENV_VAR`
必需：否
**变量**
（仅限架构版本 0.3）您可以在自动化运行手册的整个步骤中引用或更新的值。变量与参数类似，但在重要方面有所区别。参数值在运行手册的上下文中是静态的，但是变量的值可以在运行手册的上下文中更改。更新变量的值时，数据类型必须与定义的数据类型相匹配。有关更新自动化中的变量值的信息，请参阅 [`aws:updateVariable` – 更新运行手册变量的值](automation-action-update-variable.md)
类型：Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap
必需：否
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(仅限 1.2 版架构) 由一个或多个 Systems Manager 插件应用的实例的配置。不保证插件按顺序运行。
类型：Dictionary
必需：否
**mainSteps**
（仅架构版本 0.3、2.0 和 2.2）可以包含多个步骤（插件）的对象。插件在步骤内定义。步骤按文档中列出的先后顺序运行。
类型：Dictionary
是否必需：是
**输出**
（仅架构版本 0.3）通过执行本文档而生成的可用于其他进程的数据。例如，如果文档创建新的 AMI，您可以指定 “CreateImage.ImageId” 作为输出值，然后使用该输出以在后续自动化执行中创建新的实例。有关输出的更多信息，请参阅 [使用操作输出作为输入](automation-action-outputs-inputs.md)。
类型：Dictionary
必需：否
**文件**
（仅架构版本 0.3）附加到文档并在自动化执行期间运行的脚本文件（及其校验和）。仅适用于包含 `aws:executeScript` 操作且已在一个或多个步骤中指定附件的文档。
要了解自动化运行手册支持的运行时，请参阅 [`aws:executeScript` - 运行脚本](automation-action-executeScript.md)。有关在自动化运行手册中包含脚本的更多信息，请参阅 [在运行手册中使用脚本](automation-document-script-considerations.md) 和 [自动化运行手册的视觉对象设计体验](automation-visual-designer.md)。
使用附件创建自动化运行手册时，可以使用 `--attachments` 选项（对于 AWS CLI）或 `Attachments`（对于 API 和开发工具包）指定附件文件。您可以为存储在 Amazon Simple Storage Service（Amazon S3）存储桶中的 SSM 文档和文件指定文件位置。有关更多信息，请参阅 AWS Systems Manager API 参考中的[附件](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments)。
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
类型：Dictionary
必需：否
## 文档参数 `type` 示例
SSM 文档中的参数类型是静态的。这意味着参数类型在定义后无法更改。将参数用于 SSM 文档插件时，不能在插件的输入中动态更改参数的类型。例如，您不能在 `aws:runShellScript` 插件的 `runCommand` 输入中引用 `Integer` 参数，因为此输入接受字符串或字符串列表。要将参数用于插件输入，参数类型必须与接受的类型匹配。例如，您必须为`aws:updateSsmAgent` 插件的 `allowDowngrade` 输入指定 `Boolean` 类型参数。如果参数类型与插件的输入类型不匹配，则 SSM 文档无法验证，并且系统不会创建文档。在其他插件或 AWS Systems Manager 自动化操作的输入中使用下游参数时也是如此。例如，您不能引用 `aws:runDocument` 插件的 `documentParameters` 输入内的 `StringList` 参数。`documentParameters` 输入接受字符串映射，即使下游 SSM 文档参数类型是 `StringList` 参数并与您要引用的参数匹配。
将参数用于自动化操作时，大多数情况下创建 SSM 文档时不会验证参数类型。只有在使用 `aws:runCommand` 操作的情况下，才会在创建 SSM 文档时验证参数类型。在所有其他情况下，在运行操作之前验证该操作的输入时，会在自动化执行期间进行参数验证。例如，如果输入参数为 `String` 并将其引用为 `aws:runInstances` 操作 `MaxInstanceCount` 输入的值，则会创建 SSM 文档。但是，在运行该文档期间，验证 `aws:runInstances` 操作时自动化将失败，因为 `MaxInstanceCount` 输入需要 `Integer`。
下面是每个参数的示例 `type`。
字符串
使用引号括起来的零个或多个 Unicode 字符序列。例如，"i-1234567890abcdef0"。使用反斜杠转义。
字符串参数可包括一个值为 `ENV_VAR` 的可选 `interpolationType` 字段，以启用环境变量插值增强安全性。
```
---
InstanceId:
type: String
description: "(Optional) The target EC2 instance ID."
interpolationType: ENV_VAR
```
```
"InstanceId":{
"type":"String",
"description":"(Optional) The target EC2 instance ID.",
"interpolationType": "ENV_VAR"
}
```
StringList
以逗号分隔的字符串项目列表。例如，["cd \$1", "pwd"]。
```
---
commands:
type: StringList
description: "(Required) Specify a shell script or a command to run."
default: ""
minItems: 1
displayType: textarea
```
```
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
```
布尔值
仅接受 `true` 或 `false`。不接受 "true" 或 0。
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
整数
整数。不接受小数（例如 3.14159）或使用引号的数字（例如 "3"）。
```
---
timeout:
type: Integer
description: The type of action to perform.
default: 100
```
```
"timeout": {
"type": "Integer",
"description": "The type of action to perform.",
"default": 100
}
```
StringMap
键到值的映射。密钥和值必须是字符串。例如，\$1"Env": "Prod"\$1。
```
---
notificationConfig:
type: StringMap
description: The configuration for events to be notified about
default:
NotificationType: 'Command'
NotificationEvents:
- 'Failed'
NotificationArn: "$dependency.topicArn"
maxChars: 150
```
```
"notificationConfig" : {
"type" : "StringMap",
"description" : "The configuration for events to be notified about",
"default" : {
"NotificationType" : "Command",
"NotificationEvents" : ["Failed"],
"NotificationArn" : "$dependency.topicArn"
},
"maxChars" : 150
}
```
MapList
StringMap 对象的列表。
```
blockDeviceMappings:
type: MapList
description: The mappings for the create image inputs
default:
- DeviceName: "/dev/sda1"
Ebs:
VolumeSize: "50"
- DeviceName: "/dev/sdm"
Ebs:
VolumeSize: "100"
maxItems: 2
```
```
"blockDeviceMappings":{
"type":"MapList",
"description":"The mappings for the create image inputs",
"default":[
{
"DeviceName":"/dev/sda1",
"Ebs":{
"VolumeSize":"50"
}
},
{
"DeviceName":"/dev/sdm",
"Ebs":{
"VolumeSize":"100"
}
}
],
"maxItems":2
}
```
## 查看 SSM 命令文档内容
要预览需要的和可选参数 AWS Systems Manager(SSM) 命令文档，除了文档运行的操作外，您还可以在 Systems Manager 控制台中查看此文档的内容。
**查看 SSM 命令文档内容**
1. 访问 [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)，打开 AWS Systems Manager 控制台。
1. 在导航窗格中，选择**文档**。
1. 在搜索框中，选择**文档类型**，然后选择**命令**。
1. 选择文档的名称，然后选择**内容**选项卡。
1. 在内容字段中，查看文档的可用参数和操作步骤。
例如，下图显示 (1) `version` 和 (2) `allowDowngrade` 是 `AWS-UpdateSSMAgent` 文档的可选参数，并且文档运行的第一个操作是 (3) `aws:updateSsmAgent`。
![\[在 Systems Manager 控制台中查看 SSM 文档内容\]](http://docs.aws.amazon.com/zh_cn/systems-manager/latest/userguide/images/view-document-content.png)
# 命令文档插件参考
此参考介绍可在 AWS Systems Manager (SSM) 命令类型文档中指定的插件。这些插件不能在使自动化操作的 SSM 自动化运行手册中使用。有关 AWS Systems Manager 自动化操作的信息，请参阅 [Systems Manager 自动化操作参考](automation-actions.md)。
Systems Manager 通过读取 SSM 文档的内容确定在托管实例上执行的操作。每个文档都包含代码执行部分。根据文档的架构版本，此代码执行部分可能包含一个或多个插件或步骤。为了便于理解本帮助主题，我们将这些插件和步骤都称为*插件*。本部分包含有关每个 Systems Manager 插件的信息。有关文档的详细信息（包括有关创建文档和架构版本之间的差异的信息），请参阅 [AWS Systems Manager 文档](documents.md)。
对于接受字符串参数（例如 `aws:runShellScript` 和 `aws:runPowerShellScript`）的插件，可以使用 `interpolationType` 参数增强安全性，方法是将参数输入视为字符串文本值，而非可能的可执行命令。例如：
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
//truncated
}
```
**注意**
此处介绍的部分插件仅在 Windows Server 实例或 Linux 实例上运行。每个插件都记录了平台依赖关系。
macOS 的 Amazon Elastic Compute Cloud (Amazon EC2) 实例支持以下文档插件：
`aws:refreshAssociation`
`aws:runShellScript`
`aws:runPowerShellScript`
`aws:softwareInventory`
`aws:updateSsmAgent`
**Topics**
+ [共享输入](#shared-inputs)
+ [`aws:applications`](#aws-applications)
+ [`aws:cloudWatch`](#aws-cloudWatch)
+ [`aws:configureDocker`](#aws-configuredocker)
+ [`aws:configurePackage`](#aws-configurepackage)
+ [`aws:domainJoin`](#aws-domainJoin)
+ [`aws:downloadContent`](#aws-downloadContent)
+ [`aws:psModule`](#aws-psModule)
+ [`aws:refreshAssociation`](#aws-refreshassociation)
+ [`aws:runDockerAction`](#aws-rundockeraction)
+ [`aws:runDocument`](#aws-rundocument)
+ [`aws:runPowerShellScript`](#aws-runPowerShellScript)
+ [`aws:runShellScript`](#aws-runShellScript)
+ [`aws:softwareInventory`](#aws-softwareinventory)
+ [`aws:updateAgent`](#aws-updateagent)
+ [`aws:updateSsmAgent`](#aws-updatessmagent)
## 共享输入
仅在版本 3.0.502 和更高版本的 SSM Agent 中，所有插件都可以使用以下输入：
**最终步骤**
您希望文档运行的最后一步。如果此输入是为某个步骤定义的，则它优先于 `onFailure` 或 `onSuccess` 输入中指定的 `exit` 值。为了使具有此输入的步骤按预期运行，该步骤必须是文档 `mainSteps` 中定义的最后一个步骤。
类型：布尔值
有效值：`true` \$1 `false`
必需：否
**onFailure**
如果您为插件指定此输入的 `exit` 值并且步骤失败，则步骤状态会显示失败，并且文档不会运行任何剩余步骤，除非 `finallyStep` 已定义。如果您为插件指定此输入的 `successAndExit` 值并且步骤失败，则步骤状态会显示成功，并且文档不会运行任何剩余的步骤，除非 `finallyStep` 已定义。
类型：字符串
有效值：`exit` \$1 `successAndExit`
必需：否
**onSuccess**
如果您为插件指定此输入并且步骤成功运行，则文档不会运行任何剩余的步骤，除非 `finallyStep` 已定义。
类型：字符串
有效值：`exit`
必需：否
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Shared inputs example
parameters:
customDocumentParameter:
type: String
description: Example parameter for a custom Command-type document.
mainSteps:
- action: aws:runDocument
name: runCustomConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomDocument"
documentParameters: '"documentParameter":{{customDocumentParameter}}'
onSuccess: exit
- action: aws:runDocument
name: ifConfigurationFailure
inputs:
documentType: SSMDocument
documentPath: "yourCustomRepairDocument"
onFailure: exit
- action: aws:runDocument
name: finalConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomFinalDocument"
finallyStep: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Shared inputs example",
"parameters": {
"customDocumentParameter": {
"type": "String",
"description": "Example parameter for a custom Command-type document."
}
},
"mainSteps":[
{
"action": "aws:runDocument",
"name": "runCustomConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomDocument",
"documentParameters": "\"documentParameter\":{{customDocumentParameter}}",
"onSuccess": "exit"
}
},
{
"action": "aws:runDocument",
"name": "ifConfigurationFailure",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomRepairDocument",
"onFailure": "exit"
}
},
{
"action": "aws:runDocument",
"name":"finalConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomFinalDocument",
"finallyStep": true
}
}
]
}
```
------
## `aws:applications`
在 EC2 实例上安装、修复或卸载应用程序。此插件仅在 Windows Server 操作系统中运行。
### 语法
#### Schema 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:applications plugin
parameters:
source:
description: "(Required) Source of msi."
type: String
mainSteps:
- action: aws:applications
name: example
inputs:
action: Install
source: "{{ source }}"
```
------
#### [ JSON ]
```
{
"schemaVersion":"2.2",
"description":"aws:applications",
"parameters":{
"source":{
"description":"(Required) Source of msi.",
"type":"String"
}
},
"mainSteps":[
{
"action":"aws:applications",
"name":"example",
"inputs":{
"action":"Install",
"source":"{{ source }}"
}
}
]
}
```
------
#### Schema 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:applications:
properties:
- id: 0.aws:applications
action: "{{ action }}"
parameters: "{{ parameters }}"
source: "{{ source }}"
sourceHash: "{{ sourceHash }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:applications":{
"properties":[
{
"id":"0.aws:applications",
"action":"{{ action }}",
"parameters":"{{ parameters }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}"
}
]
}
}
}
```
------
### 属性
**action**
要执行的操作。
类型：Enum
有效值：`Install` \$1`Repair` \$1`Uninstall`
是否必需：是
**参数**
安装程序的参数。
类型：字符串
必需：否
**source**
应用程序的 `.msi` 文件的 URL。
类型：字符串
是否必需：是
**sourceHash**
`.msi` 文件的 SHA256 哈希值。
类型：字符串
必需：否
## `aws:cloudWatch`
从中导出数据 Windows Server 添加到 Amazon CloudWatch 视台或 Amazon CloudWatch Logs 中，并使用云监控指标监控数据。此插件仅在 Windows Server 操作系统中运行。要详细了解如何配置 CloudWatch 与 Amazon Elastic Compute Cloud（Amazon EC2）的集成，请参阅《Amazon CloudWatch 用户指南》**中的[使用 CloudWatch 代理收集指标、日志和跟踪信息](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
**重要**
统一的 CloudWatch 代理已取代 SSM Agent，作为将日志数据发送到 Amazon CloudWatch Logs 的工具。不支持 SSM Agent aws:cloudWatch 插件。我们建议仅将统一的 CloudWatch 代理用于您的日志收集过程。有关更多信息，请参阅以下主题：
[将节点日志发送到统一的 CloudWatch Logs（CloudWatch 代理）](monitoring-cloudwatch-agent.md)
[将 Windows Server 节点日志收集迁移到 CloudWatch 代理](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate)
《Amazon CloudWatch 用户指南》**中的[使用 CloudWatch 代理收集指标、日志和跟踪信息](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
您可以导出和监视以下数据类型：
**ApplicationEventLog**
将应用程序事件日志数据发送到 CloudWatch Logs。
**CustomLogs**
将任何基于文本的日志文件发送到 Amazon CloudWatch Logs。CloudWatch 插件会为日志文件创建指纹。系统随后将数据偏移与每个指纹进行关联。该插件会在出现更改时上传文件，记录偏移，然后将该偏移与指纹关联。此方法用于避免出现这种情况：用户启用插件后，将服务与包含大量文件的目录关联，然后系统会上传所有文件。
请注意，如果应用程序在轮询期间截断或尝试清除日志，为 `LogDirectoryPath` 指定的任何日志都可能丢失条目。例如，如果您要限制日志文件大小，请在达到此限制时创建新的日志文件，然后继续将数据写入新文件。
**ETW**
将 Windows (ETW) 事件跟踪数据发送到 CloudWatch Logs。
**IIS**
将 IIS 日志数据发送到 CloudWatch Logs
**PerformanceCounter**
将 Windows 性能计数器发送到 CloudWatch。您可以选择不同类别作为指标上传到 CloudWatch。对于要上传的每个性能计数器，创建具有唯一 ID 的 **PerformanceCounter** 部分 (例如“PerformanceCounter2”、“PerformanceCounter3”等)，然后配置其属性。
如果 AWS Systems Manager SSM Agent 或 CloudWatch 插件已停止，则性能计数器数据不再记录到 CloudWatch 中。此行为不同于自定义日志或 Windows 事件日志。自定义日志和 Windows 事件日志会保留性能计数器数据，并在 SSM Agent 后或 CloudWatch 插件可用时将其上传到 CloudWatch。
**SecurityEventLog**
将安全日志数据发送到 CloudWatch Logs。
**SystemEventLog**
将系统事件日志数据发送到 CloudWatch Logs。
可为数据定义以下目标：
**CloudWatch**
发送性能计数器指标数据时所在的目标。可添加具有唯一 ID 的更多部分 (例如，“CloudWatch2”和“CloudWatch3”等)，并为每个新 ID 指定一个不同的区域，将相同数据发送到不同位置。
**CloudWatchLogs**
发送日志数据时所在的目标。可添加具有唯一 ID 的更多部分 (例如，“CloudWatchLogs2”和“CloudWatchLogs3”等)，并为每个新 ID 指定一个不同的区域，将相同数据发送到不同位置。
### 语法
```
"runtimeConfig":{
"aws:cloudWatch":{
"settings":{
"startType":"{{ status }}"
},
"properties":"{{ properties }}"
}
}
```
### 设置和属性
**AccessKey**
您的访问密钥 ID。如果未使用 IAM 角色启动实例，则必须指定此属性。此属性不能与 SSM 一起使用。
类型：字符串
必需：否
**CategoryName**
性能监视器提供的性能计数器类别。
类型：字符串
是否必需：是
**CounterName**
性能监视器提供的性能计数器名称。
类型：字符串
是否必需：是
**CultureName**
记录时间戳的区域设置。如果 **CultureName** 为空，则它默认为您的 Windows Server 实例所使用的相同区域位置。
类型：字符串
有效值：有关支持的值的列表，请参阅 Microsoft 网站上的[国家语言支持 (NLS)](https://msdn.microsoft.com/en-us/library/cc233982.aspx)。不支持 **div**、**div-MV**、**hu** 和 **hu-HU** 值。
必需：否
**DimensionName**
Amazon CloudWatch 指标的维度。如果您要指定 `DimensionName`，则必须指定 `DimensionValue`。这些参数在列出指标时提供另一个视图。您可以对多个指标使用同一个维度，以便查看属于特定维度的所有指标。
类型：字符串
必需：否
**DimensionValue**
Amazon CloudWatch 指标的维度值。
类型：字符串
必需：否
**编码**
要使用的文件编码 (例如 UTF-8)。使用编码名称，而不是显示名称。
类型：字符串
有效值：有关支持的值的列表，请参阅 Microsoft Learn 库中的 [Encoding Class](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0)。
是否必需：是
**筛选条件**
日志名称的前缀。将此参数保留空白以监控所有文件。
类型：字符串
有效值：有关支持的值的列表，请参阅 MSDN 库中的 [FileSystemWatcherFilter 属性](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx)主题。
必需：否
**流**
要上传的每个数据类型以及数据的目标（CloudWatch 或 CloudWatch Logs ）。例如，要将在 `"Id": "PerformanceCounter"` 下定义的性能计数器发送到在 `"Id": "CloudWatch"` 下定义的 CloudWatch 目标，请输入 **“PerformanceCounter,CloudWatch”**。同样，要将自定义日志、ETW 日志和系统日志发送到 `"Id": "ETW"` 下定义的 CloudWatch Logs 目标，请输入 **“(ETW),CloudWatchLogs”**。此外，还可以将相同性能计数器或日志文件发送到多个目标。例如，要将应用程序日志发送到在 `"Id": "CloudWatchLogs"` 和 `"Id": "CloudWatchLogs2"` 下定义的两个不同目标，请输入 **"ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)"**。
类型：字符串
有效值 (源)：`ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog`
有效值 (目标)：`CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch`*n* \$1 `CloudWatchLogs`*n*
是否必需：是
**FullName**
组件的完整名称。
类型：字符串
是否必需：是
**Id**
标识数据源或目标。此标识符在配置文件中必须是唯一的。
类型：字符串
是否必需：是
**InstanceName**
性能计数器实例的名称。请勿使用星号 (\$1) 标识所有实例，因为每个性能计数器组件仅支持一个指标。不过可以使用 **\$1Total**。
类型：字符串
是否必需：是
**级别**
发送到 Amazon CloudWatch 的消息类型。
类型：字符串
有效值：
+ **1** – 仅上传错误消息。
+ **2** – 仅上传警告消息。
+ **4** – 仅上传信息消息。
您可以将这些值加在一起以包含多种类型的消息。例如，**3** 表示将包含错误消息 (**1**) 和警告消息 (**2**)。值 **7** 表示将包含错误消息 (**1**)、警告消息 (**2**) 和说明性消息 (**4**)。
是否必需：是
应将 Windows 安全日志的级别设置为 7。
**LineCount**
标识日志文件的标头中的行数。例如，IIS 日志文件拥有几乎相同的标头。您可以输入 **3**，系统会读取日志文件标头的前三行以进行识别。在 IIS 日志文件中，第三行是日期和时间戳，各日志文件的日期和时间戳互不相同。
类型：整数
必需：否
**LogDirectoryPath**
对于 CustomLogs，这是日志在 EC2 实例上的存储路径。对于 IIS 日志，这是为单个站点存储 IIS 日志的文件夹 (例如 **C:\$1\$1inetpub\$1\$1logs\$1\$1LogFiles\$1\$1W3SVC*n***)。对于 IIS 日志，仅支持 W3C 日志格式。不支持 IIS、NCSA 和自定义格式。
类型：字符串
是否必需：是
**LogGroup**
日志组的名称。此名称显示在 CloudWatch 控制台的 **Log Groups（日志组）**屏幕上。
类型：字符串
是否必需：是
**LogName**
日志文件的名称。
1. 要查找日志的名称，请在事件查看器的导航窗格中，选择 **Applications and Services Logs (应用程序和服务日志)**。
1. 在日志列表中，右键单击要上传的日志（例如 `Microsoft` > `Windows` > `Backup` > `Operational`），然后选择**创建自定义视图**。
1. 在 **Create Custom View (创建自定义视图)** 对话框中，选择 **XML** 选项卡。**LogName** 位于