CloudFormationを使用してSSM Automationランブック作成入門
現在、デフォルトで多くのSSM Automationランブックが提供されています。
ただし自身の用途に合致するランブックが存在しない場合は、ランブックを自作することができます。
本ページでは、カスタムランブックを作成します。
ランブックの内容は、AWS公式ページで紹介されているサンプルを参考にします。
このランブックをEC2インスタンスに関連付けて動作を確認します。
構築する環境
プライベートサブネット内にEC2インスタンスを作成します。
インスタンスは最新のAmazon Linux 2とします。
SSM Automationランブックを作成します。
このランブックの用途は、EC2インスタンスで任意のコマンドを実行するものです。
今回は「echo Hello World」コマンドを実行します。
このランブックとインスタンスの関連付けも作成します。
CloudFormationテンプレートファイル
上記の構成をCloudFormationで構築します。
以下のURLにCloudFormationテンプレートを配置しています。
テンプレートファイルのポイント解説
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アクションを設定します。
指定可能なアクションは以下のページで確認できます。
今回はaws:runCommandを指定します。
このアクションはインスタンスに対して、SSM Run Commandにて、任意のSSMドキュメントを実行するものです。
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公式ページに従って、サービスロールを作成します。
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ランブック
作成したランブックを確認します。
ランブックが正常に作成されていることがわかります。
このランブックには3つのパラメータが存在し、SSMドキュメントAWS-RunShellScriptを使用して、インスタンスに対して任意のコマンドを実行する内容です。
SSM関連付け
関連付けを確認します。
先述のランブックに対する関連付けが作成されていることがわかります。
ランブックを実行するためのパラメータです。
今回インスタンスで実行するコマンドですが、echoコマンドで「Hello World」を出力するものです。
ターゲットを見ると、タグ名MyDocumentの値が「Group1」であるインスタンスが対象であることがわかります。
ランブックの実行履歴を確認します。
正常に実行が完了しています。
実行されたステップの詳細ログを確認します。
インスタンスに対して、SSMドキュメントAWS-RunShellScriptが正常に実行されて、「Hello World」が出力されたことがわかります。
まとめ
このようにカスタムランブックを作成し、これをEC2インスタンスに関連づけることができました。
