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

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

从 AWS Automation 运行手册调用其他 Systems Manager 服务

您可以在运行手册中使用以下自动化操作来调用其他 AWS 服务和其他 Systems Manager 功能。

  • aws:executeAwsApi:此自动化操作调用并运行 AWS API 操作。支持大多数 API 操作,但某些 API 操作未经过测试。例如,支持以下 API 操作:CreateImageDelete bucket (删除存储桶)RebootDBInstanceCreateGroups 等。不支持流式处理 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 操作定义。您可以在以下服务参考页面的左侧导航窗格中选择服务来查看 API 操作(也称为方法)。在要调用的服务的 Client (客户端) 部分中选择一种方法。例如,以下页面中列出了 Amazon Relational Database Service (Amazon RDS) 的所有 API 操作(方法):Amazon RDS 方法.

您可以在以下位置中查看每个自动化操作的架构:

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

使用 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-ConfigureS3BucketLoggingAWS-CreateDynamoDBBackupAWS-RestartEC2Instance 文档。对于您创建的所有自定义自动化文档,如果这些文档使用调用其他服务的操作调用其他 AWS 服务,此要求同样适用。例如,如果您使用 aws:executeAwsApiaws:createStackaws:copyImage 操作,则必须配置具有权限的服务角色来调用这些服务。您可以通过将 IAM 内联策略添加到角色来启用其他 AWS 服务的权限。有关更多信息,请参阅(可选)添加 Automation 内联策略来调用其他 AWS 服务

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

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

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

  1. 打开文本编辑器并将以下运行手册内容粘贴到该文件中。指定 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 操作添加到运行手册中。下面的列表介绍如何确定和指定所需的输入。您可以查看一个示例,了解如何在列表后面的运行手册中输入此信息。

    1. 查看架构以了解 aws:assertAwsResourceProperty – 声明 AWS 资源状态或事件状态 操作的所有可用输入。

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

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

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

    5. 确定一个或多个 PropertySelectors。PropertySelector 是此 API 操作的请求返回的响应对象。例如,在 Amazon RDS 方法.上。选择 describe_db_instances 方法并向下滚动到 Response Structure 部分。DBInstances 被列为响应对象。出于本演练的目的,请将 DBInstancesDBInstanceStatus 指定为 PropertySelectors。请注意,PropertySelectors 是使用 JSONPath 输入的。这意味着,您需要按如下所示设置运行手册中的信息的格式:

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

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

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

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

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

    2. 指定 Amazon RDS StartDBInstance API 操作以启动实例。

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

    --- 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. 在 mainSteps 部分中指定 aws:waitForAwsResourceProperty 操作,以等待实例启动后再完成自动化。

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

    2. 指定 Amazon RDS DescribeDBInstances API 操作来确定实例状态。

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

    4. available 指定为 DesiredValue.

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

    --- 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. 在 AWS CLI 中运行以下命令以将运行手册添加到您的 AWS 账户。

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

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

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

调用 AWS API 的预定义运行手册

Systems Manager Automation 包括以下调用 AWS API 的预定义运行手册。

运行手册名称 目的

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 (DynamoDB) 表备份。

单击上表中的链接,或者使用以下过程在 Systems Manager 控制台中查看有关这些运行手册的更多详细信息。

  1. 通过以下网址打开 AWS Systems Manager 控制台:https://console.amazonaws.cn/systems-manager/

  2. 在导航窗格中,选择文档

    -或者-

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

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

  4. 选择 Content 选项卡。