AWS

CloudFormationを使用してSSM Automationランブック作成入門

スポンサーリンク
CloudFormationを使用してSSM Automationランブック作成入門 AWS
スポンサーリンク
スポンサーリンク

CloudFormationを使用してSSM Automationランブック作成入門

現在、デフォルトで多くのSSM Automationランブックが提供されています。

Systems Manager Automation runbook reference - AWS Systems Manager Automation runbook reference
Learn about the predefined runbooks maintained by AWS, AWS Support, and AWS Config.

ただし自身の用途に合致するランブックが存在しない場合は、ランブックを自作することができます。

本ページでは、カスタムランブックを作成します。
ランブックの内容は、AWS公式ページで紹介されているサンプルを参考にします。

AWS::SSM::Document - AWS CloudFormation
Use the AWS CloudFormation AWS::SSM::Document resource for SSM.

このランブックをEC2インスタンスに関連付けて動作を確認します。

構築する環境

Diagram of introduction to creating SSM Automation Runbooks using CloudFormation

プライベートサブネット内にEC2インスタンスを作成します。
インスタンスは最新のAmazon Linux 2とします。

SSM Automationランブックを作成します。
このランブックの用途は、EC2インスタンスで任意のコマンドを実行するものです。
今回は「echo Hello World」コマンドを実行します。

このランブックとインスタンスの関連付けも作成します。

CloudFormationテンプレートファイル

上記の構成をCloudFormationで構築します。
以下のURLにCloudFormationテンプレートを配置しています。

awstut-fa/119 at main · awstut-an-r/awstut-fa
Contribute to awstut-an-r/awstut-fa development by creating an account on GitHub.

テンプレートファイルのポイント解説

Automationランブック

Resources:
  MyRunbook:
    Type: AWS::SSM::Document
    Properties: 
      Content:
        assumeRole: "{{AutomationAssumeRole}}"
        description: Run a script on Linux instances.
        schemaVersion: "0.3"
        parameters:
          AutomationAssumeRole:
            type: String
            description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf.
            default: ""
          Commands:
            type: String
            description: (Required) The commands to run or the path to an existing script on the instance.
            default: echo Hello World
          InstanceId:
            type: String
            description: (Required) The instance ID you want to run commands on.
            default: ""
        mainSteps:
          - name: sayHello
            action: aws:runCommand
            inputs:
              DocumentName: AWS-RunShellScript
              InstanceIds:
                - "{{InstanceId}}"
              Parameters:
                commands:
                  - "{{Commands}}"
      DocumentFormat: YAML
      DocumentType: Automation
      Name: !Sub "${Prefix}-MyRunbook"
      TargetType: /AWS::EC2::Instance
Code language: YAML (yaml)

Contentプロパティにランブックの中身を記載します。

冒頭でご紹介したサンプルを参考にして、EC2インスタンスで任意のコマンドを実行するランブックを作成します。

assumeRoleデータエレメントにAutomationがこのランブックを実行するためのサービスロールを指定します。
「”{{AutomationAssumeRole}}”」の記法で、後述するランブックのパラメータを参照することができます。

schemaVersionデータエレメントは「0.3」を指定します。
これは以下に引用した通り、Automationランブックを作成するための固定値です。

Automation タイプのドキュメントは、スキーマバージョン 0.3 を使用する必要があります。

SSM ドキュメントスキーマの機能と例

parametersデータエレメントで、このランブックを実行するためのパラメータを指定します。
今回は以下の3つのパラメータを受け取ります。

  • AutomationAssumeRole:Autometionがこのランブックを実行するために使用するサービスロールのARN
  • Commands:インスタンスで実行するコマンド
  • InstanceId:対象インスタンスのID

mainStepsデータエレメントにランブックで実行する処理を記載します。
実行する処理をステップと呼ばれる単位で定義します。

actionに実行するAutomationアクションを設定します。
指定可能なアクションは以下のページで確認できます。

Systems Manager Automation アクションのリファレンス - AWS Systems Manager
Automation アクションは、Automation Runbook の各ステップの入力、動作、および出力を決定します。

今回はaws:runCommandを指定します。
このアクションはインスタンスに対して、SSM Run Commandにて、任意のSSMドキュメントを実行するものです。

aws:runCommand – マネージドインスタンスでコマンドを実行する - AWS Systems Manager
指定されたコマンドを実行します。

inputsにアクションを実行するためのパラメータを指定します。
ここで指定するパラメータは実行するアクションに依ります。
今回は3つのパラメータを指定します。

  • DocumentName:実行するSSMドキュメントとしてAWS-RunShellScriptを指定する。
  • InstanceIds:SSMドキュメントを実行する対象のインスタンスのID。「{{InstanceId}}」の記法で、AutomationランブックのパラメータInstanceIdの値を参照する。
  • Parameters:commandsの値として、実行するLinuxコマンドを指定する。「{{Commands}}」の記法で、AutomationランブックのパラメータCommandsの値を参照する。

DocumentFormatプロパティでランブックのフォーマットを指定できます。
今回は「YAML」を指定します。

DocumentTypeプロパティで作成するドキュメントのタイプを指定します。
今回は「Automation」を指定します。

TargetTypeプロパティで、このランブックの対象リソースを設定できます。
今回はEC2インスタンスを対象としますので、「/AWS::EC2::Instance」を指定します。

Automation用サービスロール

Resources:
  MyRunbookRole:
    Type: AWS::IAM::Role
    DeletionPolicy: Delete
    Properties:
      AssumeRolePolicyDocument:
        Version: 2012-10-17
        Statement:
          - Effect: Allow
            Action: sts:AssumeRole
            Principal:
              Service:
                - ssm.amazonaws.com
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AmazonSSMAutomationRole
      Policies:
        - PolicyName: PassRolePolicy
          PolicyDocument:
            Version: 2012-10-17
            Statement:
              - Effect: Allow
                Action:
                  - iam:PassRole
                Resource:
                  - "*"
Code language: YAML (yaml)

通常、サービスロールを指定しない場合は、デフォルトのサービスリンクロール(SLR)であるAWSServiceRoleforAmazonSSMが使用されます。
今回は以下のAWS公式ページに従って、サービスロールを作成します。

方法 2: IAM を使用して、オートメーションのロールを設定する - AWS Systems Manager
IAM を使用して、Systems Manager Automation のサービスロールを作成します。

SSM関連付け

Resources:
  MyRunbookAssociation:
    Type: AWS::SSM::Association
    Properties:
      AssociationName: !Sub "${Prefix}-MyRunbookAssociation"
      AutomationTargetParameterName: InstanceId
      Name: !Ref MyRunbook
      Parameters:
        AutomationAssumeRole:
          - !GetAtt MyRunbookRole.Arn
        Commands:
          - "echo Hello World"
        InstanceId:
          - "{{RESOURCE_ID}}"
      Targets:
        - Key: !Sub "tag:${TagKey}"
          Values:
            - !Ref TagValue
      WaitForSuccessTimeoutSeconds: !Ref WaitForSuccessTimeoutSeconds
Code language: YAML (yaml)

上述のランブックとインスタンスの関連付けを作成します。

SSM関連付けを作成して、EC2インスタンスに対してSSM Automationランブックを実行するため方法については、以下のページをご確認ください。

今回は以下のタグが設定されているインスタンスを、関連付けの対象とします。

  • タグのキー:MyDocument
  • タグの値:Group1

上記の条件でインスタンスにタグ設定を行い、関連付けの対象にします。

ParametersプロパティのCommandsに、対象のインスタンスで実行するコマンドを指定します。
今回は「echo Hello World」を指定して、インスタンスでechoコマンドを実行します。

環境構築

CloudFormationを使用して、本環境を構築し、実際の挙動を確認します。

CloudFormationスタックを作成し、スタック内のリソースを確認する

CloudFormationスタックを作成します。
スタックの作成および各スタックの確認方法については、以下のページをご確認ください。

各スタックのリソースを確認した結果、今回作成された主要リソースの情報は以下の通りです。

  • EC2インスタンス:i-0ffc6032e2eec1e8d
  • カスタムSSM Automationランブック:fa-119-MyRunbook
  • SSM関連付け:01462c07-2c00-46d7-b28e-77f9c844f329

動作確認

準備が整いましたので、AWS Management Consoleから各リソースを確認します。

カスタムSSM Automationランブック

作成したランブックを確認します。

Detail of SSM 1.
Detail of SSM 2.
Detail of SSM 3.

ランブックが正常に作成されていることがわかります。

このランブックには3つのパラメータが存在し、SSMドキュメントAWS-RunShellScriptを使用して、インスタンスに対して任意のコマンドを実行する内容です。

SSM関連付け

関連付けを確認します。

Detail of SSM 4.

先述のランブックに対する関連付けが作成されていることがわかります。

Detail of SSM 5.

ランブックを実行するためのパラメータです。
今回インスタンスで実行するコマンドですが、echoコマンドで「Hello World」を出力するものです。

Detail of SSM 6.

ターゲットを見ると、タグ名MyDocumentの値が「Group1」であるインスタンスが対象であることがわかります。

ランブックの実行履歴を確認します。

Detail of SSM 7.

正常に実行が完了しています。

実行されたステップの詳細ログを確認します。

Detail of SSM 8.

インスタンスに対して、SSMドキュメントAWS-RunShellScriptが正常に実行されて、「Hello World」が出力されたことがわかります。

まとめ

このようにカスタムランブックを作成し、これをEC2インスタンスに関連づけることができました。

タイトルとURLをコピーしました