演练：使用文档生成器创建自定义 Runbook - Amazon Web Services Systems Manager
第 1 步：创建自定义运行簿第 2 步：运行自定义运行手册
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

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

演练：使用文档生成器创建自定义 Runbook

下面的演练演示了如何在Amazon Web Services Systems Manager自动化控制台创建自定义 Runbook，然后运行自定义 Runbook。自动化是Amazon Web Services Systems Manager。

您创建的 Runbook 的第一步运行一个脚本以启动 Amazon Elastic Compute Cloud (Amazon EC2) 实例。第二步运行另一个脚本来监控要更改为 ok 的实例状态检查。然后，整体状态Success报告用于自动化。

开始前的准备工作

在开始本演练之前，请执行以下操作：

  • 确认您具有管理员权限，或为您授予了相应的权限以在 AWS Identity and Access Management (IAM) 中访问 Systems Manager。

    有关信息，请参阅 验证用户的运行手册访问权限。

  • 确认具有用于 Automation 的 IAM 服务角色（也称为承角色）在您的Amazon Web Services 账户。该角色是必需的，因为该演练使用aws:executeScriptaction.

    有关创建此角色的信息，请参阅为 Automation 配置服务角色（代入角色）访问权限。

    有关运行时的 IAM 服务角色要求的信息aws:executeScript，请参阅使用运行手册的权限。

  • 确认您具有启动 EC2 实例的权限。

    想要了解有关信息，请参阅IAM 和 Amazon EC2中的适用于 Linux 实例的 Amazon EC2 用户指南。

第 1 步：创建自定义运行簿

可以使用以下过程创建自定义运行手册，以启动 Amazon EC2 实例并等待实例状态检查变为ok。

提示

如果您复制该演练中的值并粘贴到文档生成器中（例如参数名称和处理程序名称），请确保删除添加到您输入的文本值中的任何前导或尾随空格。

使用文档生成器创建自定义 Runbook

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

  2. 在导航窗格中，选择 Documents。

    -或者-

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

  3. 选择 Create automation (创建自动化)。

  4. 适用于名称下，为运行簿键入以下描述性名称：LaunchInstanceAndCheckStatus。

  5. （可选）文档说明中，请使用 Markdown 将默认文本替换为该 Runbook 的描述。以下是示例。 

    ##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 AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}

  6. 适用于承担角色中，输入自动化所需的 IAM 服务角色（担任角色）的 ARN，格式为arn:aws:iam::111122223333:role/AutomationServiceRole。替换您的Amazon Web Services 账户用于查询的编号。

    您指定的角色用于提供启动 Automation 所需的权限。

    重要

    对于不归 Amazon 所有并使用aws:executeScript操作，必须指定一个角色。有关信息，请参阅 使用运行手册的权限。

  7. 展开 Input parameters (输入参数)，然后执行以下操作。

    1. 对于 Parameter name (参数名称)，请输入 imageId。

    2. 对于 Type (类型)，选择 String。

    3. 对于 Required (必需)，请选择 No。

    4. 对于 Default value (默认值)，请输入以下内容。 

      {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}
      注意

      该值使用最新的 Amazon Linux 启动 Amazon EC2 实例Amazon Machine Image(AMI) ID。如果您希望使用不同的AMI，请将值替换为AMIID。

    5. 对于 Description (描述)，请输入以下内容。 

      (Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux AMI ID.

  8. 选择 Add a parameter (添加参数) 以创建第二个参数 tagValue，然后输入以下内容。

    1. 对于 Parameter name (参数名称)，请输入 tagValue。

    2. 对于 Type (类型)，选择 String。

    3. 对于 Required (必需)，请选择 No。

    4. 对于 Default value (默认值)，请输入 LaunchedBySsmAutomation。这会将标签键对值 Name:LaunchedBySsmAutomation 添加到实例中。

    5. 对于 Description (描述)，请输入以下内容。 

      (Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation.

  9. 选择 Add a parameter (添加参数) 以创建第三个参数 instanceType，然后输入以下信息。

    1. 对于 Parameter name (参数名称)，请输入 instanceType。

    2. 对于 Type (类型)，选择 String。

    3. 对于 Required (必需)，请选择 No。

    4. 对于 Default value (默认值)，请输入 t2.micro。

    5. 对于 Parameter description (参数描述)，请输入以下内容。 

      (Optional) The instance type to use for the instance. The default value is t2.micro.

  10. 展开 Target type (目标类型)，然后选择 "/"。

  11. （可选）展开文档标签将资源标签应用于 Runbook。为 Tag key (标签键) 输入 Purpose，并为 Tag value (标签值) 输入 LaunchInstanceAndCheckState。

  12. 在 Step 1 (步骤 1) 部分中，完成以下步骤。

    1. 适用于步骤名称中，为自动化的第一步输入以下描述性步骤名称：LaunchEc2Instance。

    2. 对于 Action type (操作类型)，请选择 Run a script (运行脚本) (aws:executeScript)。

    3. 对于 Description (描述)，请输入自动化步骤的描述，例如以下内容。 

      **About This Step**

This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script.

    4. 展开 Inputs (输入)。

    5. 对于 Runtime (运行时)，请选择运行提供的脚本所使用的运行时语言。

    6. 对于 Handler (处理程序)，输入 launch_instance。这是在以下脚本中声明的函数名称。

      注意

      这对于 PowerShell 不是必需的。

    7. 对于 Script (脚本)，请将默认内容替换为以下内容。请确保将脚本与相应的运行时值匹配。

      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}

    8. 展开 Additional inputs (其他输入)。

    9. 对于 Input name (输入名称)，请选择 InputPayload。对于 Input value (输入值)，请输入以下 YAML 数据。 

      image_id: "{{ imageId }}"
tag_value: "{{ tagValue }}"
instance_type: "{{ instanceType }}"

  13. 展开 Outputs (输出)，然后执行以下操作：

    • 对于名称，输入 payload。

    • 对于 Selector (选择器)，请输入 $.Payload。

    • 对于 Type (类型)，选择 StringMap。

  14. 选择添加步骤以将第二步添加到 Runbook 中。第二步查询在步骤 1 中启动的实例的状态，并等到返回的状态为 ok。

  15. 在 Step 2 (步骤 2) 部分中，执行以下操作。

    1. 适用于步骤名称中，为 Automation 的第二步输入以下描述性名称：WaitForInstanceStatusOk。

    2. 对于 Action type (操作类型)，请选择 Run a script (运行脚本) (aws:executeScript)。

    3. 对于 Description (描述)，请输入自动化步骤的描述，例如以下内容。 

      **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.

    4. 对于 Runtime (运行时)，选择用于执行提供的脚本的运行时语言。

    5. 对于 Handler (处理程序)，输入 poll_instance。这是在以下脚本中声明的函数名称。

      注意

      这对于 PowerShell 不是必需的。

    6. 对于 Script (脚本)，请将默认内容替换为以下内容。请确保将脚本与相应的运行时值匹配。

      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}

    7. 展开 Additional inputs (其他输入)。

    8. 对于 Input name (输入名称)，请选择 InputPayload。对于 Input value (输入值)，请输入以下内容： 

      {{ LaunchEc2Instance.payload }}

  16. 选择创建自动化以保存运行簿。

第 2 步：运行自定义运行手册

使用以下过程运行在步骤 1 中创建的自定义运行簿。自定义 Runbook 启动一个 EC2 实例，并等待实例检查变为ok状态。

运行自定义运行簿

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

  2. 在导航窗格中，选择 Automation (自动化)，然后选择 Execute automation (执行自动化)。

  3. 在自动化文档列表中，选择我拥有的选项卡，然后选择您创建的自定义 Runbook 旁边的按钮，LaunchInstanceAndCheckStatus。

  4. 在 Document details (文档详细信息) 部分中，对于 Document version (文档版本)，请确认选择了 Default version at runtime (运行时的默认版本)。

  5. 选择 Next。

  6. 在 Execute automation document (执行自动化文档) 页面顶部，请确认选择了 Simple execution (简单执行)。

  7. 选择 Execute (执行)。

  8. 在自动化中的两个步骤完成后，在已执行的步骤区域中，选择步骤的步骤 ID 以查看步骤详细信息，包括任何步骤输出。

    注意

    返回 ok 状态可能需要几分钟的时间。

  9. （可选）除非您计划将该演练创建的 EC2 实例用于其他目的，否则，您可以终止该实例。想要了解有关信息，请参阅终止您的实例中的适用于 Linux 实例的 Amazon EC2 用户指南。

    您可以通过名称标识实例LaunchedBySsmAutomation你标记了它第 1 步：创建自定义运行簿。