チュートリアル: ドキュメントビルダーを使用してカスタムランブックを作成する - AWS Systems Manager
ステップ 1: カスタムランブックを作成する手順 2: カスタムランブックを実行する

チュートリアル: ドキュメントビルダーを使用してカスタムランブックを作成する

以下のチュートリアルでは、AWS Systems Manager オートメーションコンソールのドキュメントビルダーを使用してカスタムランブックを作成し、カスタムランブックを実行する方法を示します。オートメーションは の一機能ですAWS Systems Manager

作成したランブックの最初のステップでは、スクリプトを実行して Amazon Elastic Compute Cloud (Amazon EC2) インスタンスを起動します。2 番目のステップでは、インスタンスのステータスチェックが ok に変更されるかどうかを監視する別のスクリプトが実行されます。次に、オートメーション実行の全体的なステータス Success が報告されます。

開始する前に

このウォークスルーを開始する前に、次を行う必要があります。

  • 管理者権限を持っているか、または AWS Identity and Access Management (IAM) で Systems Manager にアクセスするための適切なアクセス許可が付与されていることを確認します。

    詳細については、 ランブックへのユーザーアクセスの確認 を参照してください。

  • AWS アカウント に Automation の IAM サービスロール (継承ロールとも呼ばれる) があることを確認します。このチュートリアルでは aws:executeScript アクションを使用するため、このロールが必要です。

    このロールの作成の詳細については、「オートメーションのサービスロール（ロールを引き受ける）アクセスの設定」を参照してください。

    [aws:executeScript] を実行するための IAM サービスロールの要件については、「ランブックを使用するためのアクセス許可」を参照してください。

  • EC2 インスタンスを起動するアクセス許可があることを確認します。

    詳細については、Linux インスタンス用の Amazon EC2 ユーザーガイドの「IAM と Amazon EC2」を参照してください。

ステップ 1: カスタムランブックを作成する

Amazon EC2 インスタンスを起動し、インスタンスのステータスチェックが ok に変わるのを待機するカスタムランブックを作成するには、以下の手順に従います。

ヒント

このチュートリアルからパラメータ名やハンドラ名などの値をドキュメントビルダーにコピーして貼り付ける場合は、入力したテキスト値に追加した先頭または末尾のスペースを削除してください。

ドキュメントビルダーを使用してカスタムランブックを作成するには

  1. AWS Systems Manager コンソール (https://console.aws.amazon.com/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 に置き換えます。

    指定したロールは、オートメーションの開始に必要なアクセス許可を提供するために使用されます。

    重要

    aws:executeScript アクションを使用する Amazon が所有していないランブックの場合、ロールを指定する必要があります。詳細については、ランブックを使用するためのアクセス許可 を参照してください。

  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 Machine Image (AMI) ID を使用して Amazon 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 (パラメータの追加)] を選択して 2 番目のパラメータ、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 (パラメータの追加)] を選択して 3 番目のパラメータ、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. [入力] を展開します。

    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 (ステップを追加)] を選択して、ランブックに 2 番目のステップを追加します。2 番目のステップは、ステップ 1 で起動されたインスタンスのステータスをクエリし、返されるステータスが ok になるまで待機します。

  15. [Step 2 (ステップ 2)] セクションで、次の操作を行います。

    1. [Step name (ステップ名)] に、オートメーションの 2 番目のステップを表すわかりやすい名前を入力します: 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.aws.amazon.com/systems-manager/) を開きます。

  2. ナビゲーションペインで、[オートメーション]、[オートメーションの実行] の順に選択します。

  3. [Automation document (オートメーションドキュメント)] リストで、[Owned by me (所有者)] タブを選択し、作成したカスタムランブックの横にあるボタン 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 インスタンスを他の目的に使用する予定がない限り、インスタンスを終了できます。詳細については、Linux インスタンス用 Amazon EC2 ユーザーガイドの「インスタンスの終了」を参照してください。

    インスタンスは、ステップ 1: カスタムランブックを作成する でタグ付けした [LaunchedBySsmAutomation] という名前で識別できます。