调用其他AmazonSystems Manager 自动化运行手册中的服务 - Amazon Web Services Systems Manager
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

调用其他AmazonSystems Manager 自动化运行手册中的服务

您可以调用其他Amazon服务和其他 Systems Manager 功能,方法是在 Runbook 中使用以下自动化操作:

  • aws:executeAwsApi:此自动化操作调用并运行AmazonAPI 操作。支持大多数 API 操作,但某些 API 操作未经过测试。例如,以下 API 操作支持:CreateImage删除存储桶RebootDBInstance, 和CreateGroups。不支持流式处理 API 操作,例如 Get Object 操作。

  • aws:waitForAwsResourceProperty:此 Automation 操作让您的 Automation 能够等待特定的资源状态或事件状态,然后再继续自动化。例如,您可以将此操作与 Amazon Relational Database Service (Amazon RDS) 一起使用。DescribeDBInstancesAPI 操作来暂停 Automation,以等待数据库实例启动。

  • aws:assertAwsResourceProperty:此 Automation 操作可用于对特定步骤的资源状态或事件状态进行断言。例如,您可以指定某个步骤必须等待 EC2 实例启动。然后它将调用 Amazon Elastic Compute Cloud (Amazon EC2)DescribeInstanceStatus使用 “DesiredValue” 属性的 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 格式的示例运行手册。Automation 执行以下操作:

  • 使用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 EC2DescribeInstanceStatusAPI 操作来断言实例位于running状态。如果实例状态不为 running,则此步骤失败。

--- description: Sample runbook using Amazon 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" ...

使用输入和输出

前面介绍的每个 Automation 操作都允许您通过指定服务命名空间、API 操作名称、输入参数和输出参数来调用特定的 API 操作。输入由您选择的 API 操作定义。您可以在以下服务参考页面的左侧导航栏中选择服务来查看 API 操作(也称为方法)。在要调用的服务的 Client 部分中选择一种方法。例如,以下页面中列出了 Amazon 关系数据库服务 (Amazon RDS) 的所有 API 操作(方法):Amazon RDS 方法

您可以在以下位置查看每个 Automation 操作的架构:

架构包括使用每个操作所需字段的描述。

使用 Selector/PropertySelector 字段

每个 “自动化” 操作都要求您指定Selector(用于aws:executeAwsApi)或PropertySelector(用于aws:assertAwsResourcePropertyaws:waitForAwsResourceProperty)。这些字段用于处理 Amazon API 操作的 JSON 响应。这些字段使用 JSONPath 语法。

以下是帮助说明这一概念的示例,以帮助说明aws:executeAwsAPiaction.

--- 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:executeAwsApistepgetImageId,则自动化将调用DescribeImagesAPI 操作并从接收响应ec2。然后自动化应用Selector - "$.Images[0].ImageId"添加到 API 响应,并将所选值分配给输出ImageId变量。同一自动化中的其他步骤可以使用ImageId指定"{{ getImageId.ImageId }}"

以下是帮助说明这一概念的示例,以帮助说明aws:waitForAwsResourcePropertyaction.

--- - 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:waitForAwsResourcePropertystepwaitUntilInstanceStateRunning,则自动化将调用DescribeInstanceStatusAPI 操作并从接收响应ec2。然后自动化应用PropertySelector - "$.InstanceStatuses[0].InstanceState.Name"设置为响应,并检查指定的返回值是否与DesiredValues列表(在这种情况下running)。此步骤重复这一过程,直到响应返回 running 实例状态。

在运行手册中使用 JSONPath

JSONPath 表达式是以 “$” 开头的字符串。,用于选择 JSON 元素中的一个或多个组件。下面的列表包含有关 Systems Manager 自动化支持的 JSONPath 运算符的信息:

  • 点表示的子字段 (.):将与 JSON 对象一起使用。此运算符选择特定键的值。

  • 深层扫描 (..):与 JSON 元素一起使用。此运算符逐级扫描 JSON 元素,并使用特定键选择值列表。此运算符的返回类型始终为 JSON 数组。在 Automation 操作输出类型上下文中,运算符可以是 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 响应获取特定的布尔值

JSONPath: $.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination Returns: true Type: Boolean

JSOnPath 示例 3 从 JSON 响应获取特定的整数

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 的形式获取特定的 BlockDappings 对象

JSONPath: $.Reservations[0].Instances[0].BlockDeviceMappings[0] Returns: { "Ebs" : { "DeleteOnTermination" : true, "Status" : "attached", "VolumeId" : "vol-000000000000" }, "DeviceName" : "/dev/xvda" } Type: StringMap

JSON路径示例 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) 服务角色调用其他服务的自动化工作流程,请注意必须使用权限将该服务角色配置为调用这些服务。该要求适用于所有AmazonAutomation 运行手册 (AWS-*运行手册),例如AWS-ConfigureS3BucketLoggingAWS-CreateDynamoDBBackup, 和AWS-RestartEC2Instance运行手册,仅举几个例子。对于您创建的所有自定义自动化运行簿,如果这些运行手册调用其他Amazon服务,通过使用调用其他服务的操作。例如,如果您使用aws:executeAwsApiaws:createStack,或者aws:copyImage操作,则您必须配置具有权限的服务角色来调用这些服务。您可以启用对其他Amazon服务,方法是将 IAM 内联策略添加到该角色。有关更多信息,请参阅 (可选)添加 Automation 内联策略来调用其他Amazon服务

示例演练:从 Systems Manager 自动化运行手册启动 Amazon RDS 实例

此示例演练说明如何创建和运行 YAML 格式的 Systems Manager Automation 运行手册,该运行手册使用所有三个 API 操作来检查 Amazon Relational Database Service (Amazon RDS) 数据库实例是否正在运行。如果数据库实例未运行,则自动化将启动它。

从运行手册调用 Amazon RDS API 操作

  1. 打开文本编辑器并将以下 Runbook 内容粘贴到文件中。指定 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:
  2. 对于自动化的第一步,您需要确定实例是否已在运行。您可以使用aws:assertAwsResourceProperty操作以确定和断言特定的实例状态。在您可以添加aws:assertAwsResourceProperty操作添加到 Runbook,您必须确定并指定所需的输入。下面的列表介绍如何确定和指定所需的输入。您可以在列表后面的 Runbook 中看到有关如何输入此信息的示例。

    1. 查看架构以了解 aws:assertAwsResourceProperty— 断言Amazon资源状态或事件状态 操作的所有可用输入。

    2. 确定要调用的服务的命名空间。您可以查看Amazon服务命名空间Amazon 资源名称 (ARN) 和和Amazon服务命名空间中的Amazon Web Services 一般参考。Amazon RDS 的命名空间为rds

    3. 确定哪个 Amazon RDS API 操作可用于查看数据库实例的状态。您可以在Amazon RDS 方法页.

    4. 为 DescribeDBInstances API 操作指定一个或多个请求参数。例如,此操作使用 DBInstanceIdentifier 请求参数。

    5. 确定一个或多个 PropertySelectors。PropertySelector 是此 API 操作的请求返回的响应对象。例如,在Amazon RDS 方法。选择 describe_db_instances 方法,然后向下滚动到 Response Structure (响应结构) 部分。DBInstances 被列为响应对象。出于本演练的目的,请将 DBInstancesDBInstanceStatus 指定为 PropertySelectors。请注意,PropertySelectors 是使用 JSONPath 输入的。也就是说,您需要对 Runbook 中的信息进行格式化,如下所示。

      PropertySelector: "$.DBInstances[0].DBInstanceStatus".

    6. 指定一个或多个 DesiredValues。如果不知道要指定的值,可以运行 DescribeDBInstances API 操作确定可能的值。在本演练中,请指定 availablestarting

    7. 将收集的信息输入到 Runbook 中,如以下示例所示。

    --- 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"]
  3. 指定aws:executeAwsApi操作,以便在上一个操作确定实例未启动时启动实例。

    1. 查看架构以了解 aws:executeAwsApi— 调用并运行AmazonAPI 操作 的所有可用输入。

    2. 指定 Amazon RDSStartDBInstanceAPI 操作来启动实例。

    3. 将收集的信息输入到 Runbook 中,如以下示例所示。

    --- 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}}"
  4. 指定aws:waitForAwsResourceProperty操作,以 mainSteps 在完成自动化之前等待实例启动。

    1. 查看架构以了解 aws:waitForAwsResourceProperty— 等待Amazon资源属性 的所有可用输入。

    2. 指定 Amazon RDSDescribeDBInstancesAPI 操作来确定实例状态。

    3. $.DBInstances[0].DBInstanceStatus 指定为 PropertySelector

    4. available 指定为 DesiredValue

    5. 将收集的信息输入到 Runbook 中,如以下示例所示。

    --- 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 ...
  5. 将文件保存为 sample.yaml。

  6. 在AmazonCLI 将运行手册添加到Amazon Web Services 账户。

    aws ssm create-document --name sampleRunbook --document-type Automation --document-format YAML --content file://sample.yaml
  7. 运行以下命令,以使用刚刚创建的 Runbook 启动自动化。开始自动化后,Systems Manager 返回的执行 ID。

    aws ssm start-automation-execution --document-name sampleRunbook
  8. 运行以下命令查看执行状态。

    aws ssm get-automation-execution --automation-execution-id automation_execution_id

调用的预定义运行手册AmazonAPI

Systems Manager Automation 包括以下调用AmazonAPI。

Run Command 目的

AWS-StartRdsInstance

启动 Amazon RDS 实例。

AWS-StopRdsInstance

停止 Amazon RDS 实例。

AWS-RebootRdsInstance

重新启动 Amazon RDS 实例。

AWS-CreateSnapshot

创建 Amazon Elastic Block Store (Amazon EBS) 卷快照。

AWS-DeleteSnapshot

删除 Amazon EBS 卷快照。

AWS-ConfigureS3BucketLogging

启用 Amazon Simple Storage Service (Amazon S3) 存储桶上的日志记录。

AWS-DisableS3BucketPublicReadWrite

使用专用 ACL 禁用 S3 存储桶的读写权限。

AWS-ConfigureS3BucketVersioning

在 S3 存储桶上启用或暂停版本控制。

AWS-DeleteDynamoDbBackup

删除 Amazon DynamoDB 表备份。

可以选择上表中的链接,或使用以下过程在 Systems Manager 控制台中查看有关这些 Runbook 的更多详细信息。

  1. 打开Amazon Web Services Systems Manager控制台https://console.aws.amazon.com/systems-manager/

  2. 在导航窗格中,选择 Documents

    -或者-

    如果Amazon Web Services Systems Manager首先打开主页,选择菜单图标( ) 以打开导航窗格中的,然后选择。文档在导航窗格中。

  3. 选择运行手册,然后选择查看详细信息

  4. 选择内容选项卡。