ランブック作成のためのドキュメントビルダーの使用 - AWS Systems Manager
ドキュメントビルダーを使用してランブックを作成するスクリプトを実行するランブックを作成する

ランブック作成のためのドキュメントビルダーの使用

AWS Systems Manager の公開ランブックが、AWS リソースで実行するすべてのアクションをサポートしない場合、独自のランブックを作成できます。カスタムランブックを作成するには、適切なオートメーションアクションを含むローカルの YAML または JSON 形式のファイルを手動で作成します。また別の方法として、Systems Manager Automation コンソールでドキュメントビルダーを使用し、カスタムランブックを構築することも可能です

ドキュメントビルダーを使用すると、JSON または YAML 構文を使用しなくても、オートメーションアクションをカスタムランブックに追加し、必要なパラメータを指定できます。ステップを追加してランブックを作成すると、追加したアクションが、Systems Manager がオートメーションの実行に使用できる YAML 形式に変換されます。

ランブックでは、マークアップ言語である Markdown の使用がサポートされています。これにより、wiki スタイルの説明をランブックやランブック内の個々のステップに追加できます。Markdown の使用に関する詳細については、「AWS での Markdown の使用」を参照してください。

ドキュメントビルダーを使用してランブックを作成する

開始する前に

ランブック内で使用できる他のさまざまなアクションについても、確認してみることをお勧めします。詳細については、「Systems Manager Automation アクションのリファレンス」を参照してください。

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

  1. AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/) を開きます。

  2. ナビゲーションペインで、[ドキュメント] を選択します。

  3. [Create automation (オートメーションを作成)] を選択します。

  4. [名前] に、ランブックのわかりやすい名前を入力します。

  5. [Document description (ドキュメントの説明)] に、ランブックのマークダウンスタイルの説明を入力します。ランブック、番号付きステップ、またはその他の種類の情報を使用してランブックを説明できます。コンテンツの書式設定については、デフォルトのテキストを参照してください。

    ヒント

    [Hide preview (プレビューを非表示)] と [Show preview (プレビューを表示)] を切り替えて、作成時に説明の内容がどのように表示されるかを確認します。

  6. （オプション） [Assume role (ロールの継承)] に、ユーザーに代わってアクションを実行するサービスロールの名前または ARN を入力します。ロールを指定しない場合、オートメーションはオートメーションを実行するユーザーのアクセス許可を使用します。

    重要

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

  7. （オプション） [Outputs (出力)] に、このランブックを実行するための出力を入力して、他のプロセスで使用できるようにします。

    たとえば、ドキュメントが新しい AMI を作成する場合、["CreateImage.ImageId"] を指定し、この出力を使用して後続のオートメーションで新しいインスタンスを作成します。

  8. （オプション） [Input parameters (入力パラメータ)] セクションを展開し、次の操作を行います。

    1. [Parameter name (パラメータ名)] に、作成するランブックパラメータのわかりやすい名前を入力します。

    2. [Type (タイプ)] で、パラメータのタイプ（String や MapList など）を選択します。

    3. [Required (必須)] で、次のいずれかの操作を行います。

      • ランタイムにこのランブックパラメータの値を指定する必要がある場合は、[Yes (はい)] を選択します。

      • パラメータが不要な場合は、[No (いいえ)] を選択し、（オプション） [Default value (デフォルト値)] にデフォルトのパラメータ値を入力します。

    4. [Description (説明)] に、ランブックパラメータの説明を入力します。

    注記

    ランブックパラメータをさらに追加するには、[Add a parameter (パラメータを追加)] を選択します。ランブックパラメータを削除するには、[X] (削除) ボタンを選択します。

  9. (オプション) [Target type (ターゲットタイプ)] セクションを展開し、ターゲットタイプを選択して、オートメーションが実行できるリソースの種類を定義します。たとえば、EC2 インスタンスでランブックを使用するには、/AWS::EC2::Instance を選択します。

    注記

    「/」の値を指定すると、ランブックはすべてのタイプのリソースで実行できます。有効なリソースタイプのリストについては、AWS CloudFormation ユーザーガイドの AWS リソースタイプのリファレンスをご参照ください。

  10. (オプション) [Document tags (ドキュメントタグ)] セクションを展開し、ランブックに適用するタグキーと値のペアを 1 つ以上入力します。タグを使用すると、リソースの識別、整理、検索が容易になります。詳細については、「システムマネージャのドキュメントにタグを付ける」を参照してください。

  11. [Step 1 (ステップ 1)] セクションで、次の情報を入力します。

    • [Step name (ステップ名)] に、オートメーションの最初のステップのわかりやすい名前を入力します。

    • [Action type (アクションタイプ)] で、このステップで使用するアクションタイプを選択します。

      使用可能なアクションタイプのリストと情報については、「Systems Manager Automation アクションのリファレンス」を参照してください。

    • [Description (説明)] に、オートメーションステップの説明を入力します。Markdown を使用してテキストの書式を設定できます。

    • 選択した [Action type (アクションタイプ)] に応じて、[Step inputs (ステップ入力)] セクションにアクションタイプに必要な入力を入力します。たとえば、アクション aws:approve を選択した場合は、Approvers プロパティの値を指定する必要があります。

      ステップ入力フィールドの詳細については、選択したアクションタイプの「Systems Manager Automation アクションのリファレンス」のエントリを参照してください。例: aws:executeStateMachine – AWS Step Functions ステートマシンを実行する。

    • (オプション) [Additional inputs (追加入力)] で、ランブックに必要な追加の入力値を指定します。使用可能な入力タイプは、ステップで選択したアクションタイプによって異なります。（一部のアクションタイプには入力値が必要です）。

      注記

      さらに入力を追加するには、[Add optional input (オプションの入力を追加)] を選択します。入力を削除するには、[X] （削除）ボタンを選択します。

    • (オプション) [Outputs (入力)] に、このステップの出力を入力して、他のプロセスで使用できるようにします。

      注記

      [Outputs (出力)] は、すべてのアクションタイプで使用できるわけではありません。

    • (オプション) [Common properties (共通プロパティ)] セクションを展開し、すべてのオートメーションアクションに共通するアクションのプロパティを指定します。例えば、[Timeout seconds (タイムアウト秒)] には、ステップが停止するまでの実行時間を指定するための値を秒単位で指定できます。

      詳細については、「すべてのアクションで共有されるプロパティ」を参照してください。

    注記

    ステップをさらに追加するには、[Add step (ステップを追加)] を選択し、ステップを作成する手順を繰り返します。ステップを削除するには、[Remove step (ステップを削除)] を選択します。

  12. [Create automation (オートメーションを作成)] を選択してランブックを保存します。

スクリプトを実行するランブックを作成する

次の手順で、AWS Systems Manager Automation コンソールでドキュメントビルダーを使用し、スクリプトを実行するためにカスタムランブックを作成する方法について説明します。

作成したランブックの最初のステップでは、スクリプトを実行して 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 インスタンスを起動するアクセス許可があることを確認します。

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

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

  1. AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/) を開きます。

  2. ナビゲーションペインで、[ドキュメント] を選択します。

  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 1 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 (オートメーションを作成)] を選択してランブックを保存します。