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

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

演练：使用文档生成器创建自定义运行手册

以下演练演示如何在 Systems Manager Automation 控制台中使用文档生成器创建自定义运行手册，然后运行自定义运行手册。

您创建的运行手册的第一步运行一个脚本以启动 Amazon Elastic Compute Cloud （EC2） 实例。第二步运行另一个脚本来监控要更改为 的实例状态检查。ok. 然后，将为自动化报告总体状态 Success。

开始前的准备工作

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

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

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

  • 验证您的 AWS 账户中是否具有 Automation 的 IAM 服务角色（也称为代入角色）。该角色是必需的，因为本演练使用 aws：executeScript 操作。

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

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

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

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

步骤 1：创建自定义运行手册

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

提示

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

使用文档生成器创建自定义运行手册

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

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

    -或者-

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

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

  4. 对于 Name，为运行手册键入以下描述性名称：LaunchInstanceAndCheckStatus。

  5. （可选）对于 Document description （文档描述），使用 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 AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}

  6. 对于 Assume role （担任角色），输入自动化的 IAM 服务角色（担任角色）的 ARN，格式为 arn:aws:iam::111122223333:role/AutomationServiceRole。将您的 AWS 账户 ID 替换为 111122223333.

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

    重要

    对于不属于 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 系统映像 (AMI) ID 启动 EC2 实例。如果要使用不同的 AMI，请将该值替换为 AMI ID。

    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. （可选）展开 Document tags （文档标签） 以将资源标签应用于您的运行手册。对于 Tag key （标签键），输入 Purpose，对于 Tag value （标签值），输入 LaunchInstanceAndCheckState。

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

    1. 对于 Step name （步骤名称），为自动化的第一步输入以下描述性步骤名称：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 （输出） 并执行以下操作：

    • 对于 Name （名称），输入 payload。

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

    • 对于 Type （类型），选择 StringMap.

  14. 选择 Add step （添加步骤） 以将第二个步骤添加到运行手册。第二步查询在步骤 1 中启动的实例的状态，并等到返回的状态为 ok.

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

    1. 对于 Step name （步骤名称），为自动化的第二步输入以下描述性名称：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. 选择 Create automation （创建自动化） 以保存运行手册。

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

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

运行自定义运行手册

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

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

  3. 在 Automation 文档列表中，选择我拥有的选项卡，然后选择您创建的自定义运行手册 LaunchInstanceAndCheckStatus 旁边的按钮。

  4. 在 Document details （文档详细信息） 部分中，对于 Document version （文档版本），验证是否已选择 Default version at runtime （运行时的默认版本）。

  5. 选择 Next (下一步).

  6. 在 Execute automation document （执行自动化文档） 页面的顶部，验证是否已选择 Simple execution （简单执行）。

  7. 选择 Execute (执行).

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

    注意

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

  9. （可选）除非您计划将该演练创建的 EC2 实例用于其他目的，否则，您可以终止该实例。有关信息，请参阅 https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/terminating-instances.html 中的终止您的实例Amazon EC2 用户指南（适用于 Linux 实例）。

    您可以按在中标记实例时使用的名称 LaunchedBySsmAutomation步骤 1：创建自定义运行手册 来标识实例。