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

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

以下演练说明了如何在 Amazon Systems Manager 自动化控制台中使用文档生成器来创建一个自定义运行手册，然后运行该自定义运行手册。自动化是 Amazon Systems Manager 的一项功能。

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

开始前的准备工作

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

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

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

  • 确认在您的 Amazon Web Services 账户 账户中具有自动化的 IAM 服务角色（也称为担任角色）。该角色是必需的，因为该演练使用 aws:executeScript 操作。

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

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

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

    有关更多信息，请参阅 Amazon EC2 安全组中的适用于 Linux 实例的 Amazon EC2 用户指南。

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

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

提示

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

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

  1. 访问 https://console.aws.amazon.com/systems-manager/，打开 Amazon Systems Manager 控制台。

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

    -或者-

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

  3. 选择创建自动化。

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

  5. （可选）对于文档描述)，请使用 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. 对于担任角色，请使用 arn:aws:iam::111122223333:role/AutomationServiceRole 格式输入自动化的自动化 IAM 服务角色（担任角色）的 ARN。使用您的 Amazon Web Services 账户 ID 替代 111122223333。

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

    重要

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

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

    1. 对于参数名称，请输入 imageId。

    2. 对于类型，选择 String。

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

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

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

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

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

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

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

    1. 对于参数名称，请输入 tagValue。

    2. 对于类型，选择 String。

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

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

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

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

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

    1. 对于参数名称，请输入 instanceType。

    2. 对于类型，选择 String。

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

    4. 对于默认值，请输入 t2.micro。

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

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

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

  11. （可选）展开文档标签以将资源标签应用于运行手册。为标签键 输入 Purpose，并为标签值输入 LaunchInstanceAndCheckState。

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

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

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

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

      **About This Step**

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

    4. 展开输入。

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

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

      注意

      这对于 PowerShell 不是必需的。

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

      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. 展开其他输入。

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

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

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

    • 对于 Name (名称)，请输入 payload。

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

    • 对于类型，选择 StringMap。

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

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

    1. 对于步骤名称，请为自动化的第二步输入以下描述性名称：WaitForInstanceStatusOk。

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

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

      **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. 对于运行时，选择用于执行提供的脚本的运行时语言。

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

      注意

      这对于 PowerShell 不是必需的。

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

      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. 展开其他输入。

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

      {{ LaunchEc2Instance.payload }}

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

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

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

运行自定义运行手册

  1. 访问 https://console.aws.amazon.com/systems-manager/，打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中，选择自动化，然后选择执行自动化。

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

  4. 在文档详细信息 部分中，对于文档版本，请确认选择了运行时的默认版本。

  5. 选择 Next (下一步)。

  6. 在执行自动化文档页面顶部，请确认选择了简单执行。

  7. 选择执行。

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

    注意

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

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

    您可以通过名称 LaunchedBySsmAutomation 标识您在 步骤 1：创建自定义运行手册 中进行标记的实例。