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

2023-02-232024-04-21

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

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

https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-runbook-reference.html

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

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

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ssm-document.html#aws-resource-ssm-document-return-values

このランブックを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テンプレートを配置しています。

https://github.com/awstut-an-r/awstut-fa/tree/main/119

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

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アクションを設定します。
指定可能なアクションは以下のページで確認できます。

https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/automation-actions.html

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

https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/automation-action-runcommand.html

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公式ページに従って、サービスロールを作成します。

https://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/automation-permissions.html

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)