本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
从 AWS Automation 运行手册调用其他 Systems Manager 服务
您可以在运行手册中使用以下自动化操作来调用其他 AWS 服务和其他 Systems Manager 功能。
-
aws:executeAwsApi:此自动化操作调用并运行 AWS API 操作。支持大多数 API 操作,但某些 API 操作未经过测试。例如,支持以下 API 操作:CreateImage、Delete bucket (删除存储桶)、RebootDBInstance 和 CreateGroups 等。不支持流式处理 API 操作,例如 Get Object 操作。
-
aws:waitForAwsResourceProperty:此自动化操作使您的自动化能够等待特定的资源状态或事件状态,然后再继续自动化。例如,您可以将此操作与 Amazon Relational Database Service (Amazon RDS) DescribeDBInstances API 操作结合使用来暂停自动化,以便数据库实例有时间启动。
-
aws:assertAwsResourceProperty:此 Automation 操作使您能够对特定步骤的资源状态或事件状态进行断言。例如,您可以指定步骤必须等待 EC2 实例启动。然后,它将使用 Amazon EC2 的 DesiredValue 属性调用 DescribeInstanceStatus API 操作。
running
这可确保自动化等待一个正在运行的实例,然后在实例实际上正在运行时继续。
下面是一个 YAML 格式的示例运行手册,它使用 aws:executeAwsApi 操作禁用 S3 存储桶的读写权限。
--- description: Disable S3-Bucket's public WriteRead access via private ACL schemaVersion: "0.3" assumeRole: "{{ AutomationAssumeRole }}" parameters: S3BucketName: type: String description: (Required) S3 Bucket subject to access restriction AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: DisableS3BucketPublicReadWrite action: aws:executeAwsApi inputs: Service: s3 Api: PutBucketAcl Bucket: "{{S3BucketName}}" ACL: private isEnd: true ...
下面是一个使用所有三个操作的示例 YAML 运行手册。自动化执行以下操作:
-
使用 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 actions 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-2016-English-Full-Base-2018.07.11" 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 # 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 - 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 操作定义。您可以在以下服务参考
您可以在以下位置中查看每个自动化操作的架构:
架构包括使用每个操作所需字段的描述。
使用 Selector/PropertySelector 字段
每个 Automation 操作都要求您指定输出 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
变量。通过指定 ImageId
,同一自动化中的其他步骤可以使用 "{{ getImageId.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 表达式是以“$”开头的字符串。,用于选择 JSON 元素中的一个或多个组件。下面的列表包含有关 Systems Manager Automation 支持的 JSONPath 运算符的信息:
-
点表示的子字段 (.):用于 JSON 对象。此运算符选择特定键的值。
-
深层扫描 (..):用于 JSON 元素。此运算符逐级扫描 JSON 元素,并使用特定键选择值列表。注意,此运算符的返回类型始终为 JSON 数组。在自动化操作输出类型的上下文中,运算符可以是 StringList 或 MapList。
-
数组索引 ([ ]):用于 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
如果您运行使用 AWS Identity and Access Management (IAM) 服务角色调用其他服务的自动化工作流程,请注意必须使用权限将该服务角色配置为调用这些服务。此要求适用于所有
AWS Automation 文档(AWS-*
文档),例如 AWS-ConfigureS3BucketLogging
、AWS-CreateDynamoDBBackup
和 AWS-RestartEC2Instance
文档。对于您创建的所有自定义自动化文档,如果这些文档使用调用其他服务的操作调用其他 AWS 服务,此要求同样适用。例如,如果您使用 aws:executeAwsApi
、aws:createStack
或 aws:copyImage
操作,则必须配置具有权限的服务角色来调用这些服务。您可以通过将 IAM 内联策略添加到角色来启用其他 AWS 服务的权限。有关更多信息,请参阅(可选)添加 Automation 内联策略来调用其他 AWS 服务。
示例演练:从 Amazon RDS Automation 运行手册启动 Systems Manager 实例
此示例演练说明如何创建并运行 YAML 格式的 Systems Manager Automation 运行手册,该运行手册使用所有三个 API 操作来查看 Amazon Relational Database Service (Amazon RDS) 数据库实例是否正在运行。如果数据库实例未运行,则自动化将启动它。
从运行手册调用 Amazon RDS API 操作
-
打开文本编辑器并将以下运行手册内容粘贴到该文件中。指定 Automation 角色和要检查的实例 ID。稍后您将添加 mainSteps 操作。
--- description: Start RDS instance schemaVersion: "0.3" assumeRole: "
The_Automation_role_to_use_when_running_the_runbook
" parameters: InstanceId:The_instance_ID_to_start
type: String description: (Required) RDS instance ID to start AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: -
在自动化的第一步中,您需要确定实例是否已运行。可以使用 aws:assertAwsResourceProperty 操作来确定和断言特定的实例状态。您必须先确定并指定所需的输入,然后才能将 aws:assertAwsResourceProperty 操作添加到运行手册中。下面的列表介绍如何确定和指定所需的输入。您可以查看一个示例,了解如何在列表后面的运行手册中输入此信息。
-
查看架构以了解 aws:assertAwsResourceProperty – 声明 AWS 资源状态或事件状态 操作的所有可用输入。
-
确定要调用的服务的命名空间。您可以在 AWS 的 Amazon 资源名称 (ARN) 和 AWS 服务命名空间中查看 服务命名空间的列表。Amazon Web Services 一般参考Amazon RDS 的命名空间为
rds
. -
确定哪个 Amazon RDS API 操作可用于查看数据库实例的状态。您可以在 Amazon RDS 方法
页面上查看 API 操作(也称为方法)。 -
为 DescribeDBInstances API 操作指定一个或多个请求参数。例如,此操作使用
DBInstanceIdentifier
请求参数。 -
确定一个或多个 PropertySelectors。PropertySelector 是此 API 操作的请求返回的响应对象。例如,在 Amazon RDS 方法
.上。选择 describe_db_instances 方法并向下滚动到 Response Structure 部分。DBInstances 被列为响应对象。出于本演练的目的,请将 DBInstances
和DBInstanceStatus
指定为 PropertySelectors。请注意,PropertySelectors 是使用 JSONPath 输入的。这意味着,您需要按如下所示设置运行手册中的信息的格式:PropertySelector: "$.DBInstances[0].DBInstanceStatus"
. -
指定一个或多个 DesiredValues。如果您不知道要指定的值,请运行 DescribeDBInstances API 操作以确定可能的值。在本演练中,请指定 available 和 starting.
-
将收集的信息输入到运行手册中,如以下示例所示。
--- description: Start RDS instance schemaVersion: "0.3" assumeRole: "
The_Automation_role_to_use_when_running_the_runbook
" parameters: InstanceId:The_instance_ID_to_start
type: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name:AssertNotStartingOrAvailable
action: aws:assertAwsResourceProperty isCritical:false
onFailure:step:StartInstance
nextStep:CheckStart
inputs: Service:rds
Api:DescribeDBInstances
DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus
" DesiredValues: ["available
", "starting
"] -
-
在 mainSteps 部分中指定 aws:executeAwsApi 操作,以便在上一个操作确定实例未启动时启动实例。
-
查看架构以了解 的所有可用输入。aws:executeAwsApi – 调用并运行 AWS API 操作.
-
指定 Amazon RDS StartDBInstance
API 操作以启动实例。 -
将收集的信息输入到运行手册中,如以下示例所示。
--- description: Start RDS instance schemaVersion: "0.3" assumeRole: "{{ The_Automation_role_to_use_when_running_the_runbook }}" parameters: InstanceId: type: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: AssertNotStartingOrAvailable action: aws:assertAwsResourceProperty isCritical: false onFailure: step:StartInstance nextStep: CheckStart inputs: Service: rds Api: DescribeDBInstances DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available", "starting"] - name:
StartInstance
action: aws:executeAwsApi inputs: Service:rds
Api:StartDBInstance
DBInstanceIdentifier: "{{InstanceId}}" -
-
在 mainSteps 部分中指定 aws:waitForAwsResourceProperty 操作,以等待实例启动后再完成自动化。
-
查看架构以了解 的所有可用输入。aws:waitForAwsResourceProperty – 等待 AWS 资源属性.
-
指定 Amazon RDS DescribeDBInstances
API 操作来确定实例状态。 -
将
$.DBInstances[0].DBInstanceStatus
指定为PropertySelector
-
将 available 指定为
DesiredValue
. -
将收集的信息输入到运行手册中,如以下示例所示。
--- description: Start RDS instance schemaVersion: "0.3" assumeRole: "{{ The_Automation_role_to_use_when_running_the_runbook }}" parameters: InstanceId: type: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: AssertNotStartingOrAvailable action: aws:assertAwsResourceProperty isCritical: false onFailure: step:StartInstance nextStep: CheckStart inputs: Service: rds Api: DescribeDBInstances DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available", "starting"] - name: StartInstance action: aws:executeAwsApi inputs: Service: rds Api: StartDBInstance DBInstanceIdentifier: "{{InstanceId}}" - name:
CheckStart
action: aws:waitForAwsResourceProperty onFailure: Abort maxAttempts: 10 timeoutSeconds: 600 inputs: Service:rds
Api:DescribeDBInstances
DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus
" DesiredValues: ["available
"] isEnd: true ... -
-
将文件保存为 sample.yaml。
-
在 AWS CLI 中运行以下命令以将运行手册添加到您的 AWS 账户。
aws ssm create-document --name sampleRunbook --document-type Automation --document-format YAML --content file://sample.yaml
-
运行以下命令以使用刚创建的运行手册启动自动化。启动自动化后,记下 Systems Manager 返回的执行 ID。
aws ssm start-automation-execution --document-name sampleRunbook
-
运行以下命令查看执行状态。
aws ssm get-automation-execution --automation-execution-id
automation_execution_id
调用 AWS API 的预定义运行手册
Systems Manager Automation 包括以下调用 AWS API 的预定义运行手册。
运行手册名称 | 目的 |
---|---|
启动 Amazon RDS 实例。 |
|
停止 Amazon RDS 实例。 |
|
重启 Amazon RDS 实例。 |
|
创建 Amazon Elastic Block Store (Amazon EBS) 卷快照。 |
|
删除 Amazon EBS 卷快照。 |
|
在 Amazon Simple Storage Service (Amazon S3) 存储桶上启用日志记录。 |
|
使用专用 ACL 禁用 S3 存储桶的读写权限。 |
|
在 S3 存储桶上启用或暂停版本控制。 |
|
删除 Amazon DynamoDB (DynamoDB) 表备份。 |
单击上表中的链接,或者使用以下过程在 Systems Manager 控制台中查看有关这些运行手册的更多详细信息。
-
通过以下网址打开 AWS Systems Manager 控制台:https://console.amazonaws.cn/systems-manager/
。 -
在导航窗格中,选择文档。
-或者-
如果 AWS Systems Manager 主页首先打开,请选择菜单图标 (
) 以打开导航窗格,然后在导航窗格中选择文档。
-
选择运行手册,然后选择 View details (查看详细信息)。
-
选择 Content 选项卡。