正在使用文档生成器创建运行手册 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

正在使用文档生成器创建运行手册

如果 Amazon Systems Manager 公共运行手册不支持您要对 Amazon 资源执行的所有操作,则可以创建自己的运行手册。要创建自定义运行手册,您可以手动创建包含相应自动化操作的本地 YAML 或 JSON 格式文件。或者,您也可以使用 Systems Manager Automation 控制台中的文档生成器来构建自定义运行手册。

通过使用文档生成器,您可以将自动化操作添加到自定义运行手册中,并提供所需的参数,而无需使用 JSON 或 YAML 语法。在添加步骤并创建运行手册后,系统将您添加的操作转换为 Systems Manager 可用于运行自动化的 YAML 格式。

自动化文档支持使用 Markdown(一种标记语言),它允许您为运行手册和其中的各个步骤添加 Wiki 样式的描述。有关使用 Markdown 的更多信息,请参阅在 Amazon 中使用 Markdown

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

开始前的准备工作

我们建议您阅读可在运行手册中使用的各种操作。有关更多信息,请参阅Systems Manager 自动化操作参考

使用文档生成器创建运行手册
  1. 打开 Amazon Systems Manager 控制台,网址为 https://console.aws.amazon.com/systems-manager/

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

    –或者–

    如果首先打开 Amazon Systems Manager 主页,请选择菜单图标 ( 
    The menu icon
  ) 以打开导航窗格,然后在导航窗格中选择 “文档”。

  3. 选择创建自动化

  4. 对于名称,为运行手册输入一个描述性名称。

  5. 对于文档描述,请提供运行手册的 markdown 样式描述。您可以提供使用运行手册的说明、编号的步骤或描述运行手册的任何其他类型的信息。请参阅默认文本以了解设置内容格式的信息。

    提示

    隐藏预览显示预览之间切换,以便在编写时查看描述内容的效果。

  6. (可选)对于 Assume role (担任角色),请输入代表您执行操作的服务角色的名称或 ARN。如果未指定角色,自动化使用运行自动化的用户的访问权限。

    重要

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

  7. (可选)对于输出,请输入执行该运行手册的自动化的任何输出以供其他进程使用。

    例如,如果您的运行手册创建了一个新的 AMI,则可以指定 [”。CreateImage ImageId“],然后使用此输出在随后的自动化中创建新实例。

  8. (可选)展开输入参数部分,然后执行以下操作。

    1. 对于参数名称,请输入要创建的运行手册参数的描述性名称。

    2. 对于类型,请选择参数的类型,例如 StringMapList

    3. 对于必需,请执行以下操作之一:

      • 如果必须在运行时提供该运行手册参数的值,请选择

      • 如果该参数不是必需的,请选择,然后(可选)在默认值中输入默认参数值。

    4. 对于描述,请输入运行手册参数的描述。

    注意

    要添加更多运行手册参数,请选择添加参数。要删除运行手册参数,请选择 X(删除)按钮。

  9. (可选)展开目标类型部分,然后选择一种目标类型以定义可以运行自动化的资源的类型。例如,要在 EC2 实例上使用运行手册,请选择 /AWS::EC2::Instance

    注意

    如果指定“/”值,则运行文档可以在所有类型的资源上运行。有关有效资源类型列表,请参阅 Amazon CloudFormation 用户指南 中的 Amazon 资源类型参考

  10. (可选)展开文档标签部分,然后输入一个或多个标签键值对以应用于运行手册。标签可以轻松标识、划分和搜索资源。有关更多信息,请参阅 标记 Systems Manager 文档

  11. 步骤 1 部分中,提供以下信息。

    • 对于步骤名称,请输入自动化的第一步的描述性名称。

    • 对于操作类型,请选择用于该步骤的操作类型。

      有关可用操作类型的列表和信息,请参阅 Systems Manager 自动化操作参考

    • 对于描述,请输入自动化步骤的描述。您可以使用 Markdown 设置文本格式。

    • 根据选定的操作类型,在步骤输入部分中输入操作类型所需的输入。例如,如果选择了 aws:approve 操作,您必须为 Approvers 属性指定一个值。

      有关步骤输入字段的信息,请参阅 Systems Manager 自动化操作参考中的选定操作类型的条目。例如:aws:executeStateMachine - 运行 Amazon Step Functions 状态机。

    • (可选)对于其他输入,请提供运行手册所需的任何其他输入值。可用的输入类型取决于您为步骤选择的操作类型。(请注意,某些操作类型需要使用输入值。)

      注意

      要添加更多输入,请选择 Add optional input (添加可选的输入)。要删除输入,请选择 X(删除)按钮。

    • (可选)对于输出,请输入执行该步骤的任何输出以供其他进程使用。

      注意

      输出并非适用于所有操作类型。

    • (可选)展开通用属性部分,然后指定所有自动化操作的通用操作属性。例如,对于超时秒数,您可以提供一个值以指定步骤在停止之前可以运行多长时间(以秒为单位)。

      有关更多信息,请参阅 所有操作共享的属性

    注意

    要添加更多步骤,请选择添加步骤,然后重复创建步骤的过程。要删除步骤,请选择删除步骤

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

创建运行脚本的运行手册

以下过程展示了如何在 Amazon Systems Manager Automation 控制台中使用文档生成器创建运行脚本的自定义运行手册。

您创建的运行手册的第一步运行一个脚本以启动 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 实例的权限。

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

创建使用文档生成器运行脚本的自定义运行手册
  1. 打开 Amazon Systems Manager 控制台,网址为 https://console.aws.amazon.com/systems-manager/

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

    –或者–

    如果首先打开 Amazon Systems Manager 主页,请选择菜单图标 ( 
    The menu icon
  ) 以打开导航窗格,然后在导航窗格中选择 “文档”。

  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 账户 身份证件代替 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 }}
      注意

      此值使用最新的亚马逊 Linux 1 Amazon Machine Image (AMI) ID 启动亚马逊 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. 展开输出,然后执行以下操作:

    • 名称中,输入 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. 选择创建自动化以保存运行手册。