Systems Manager Automation ランブックから他の AWS のサービスを呼び出す
ランブックで次のオートメーションアクションを使用すると、他の AWS のサービスおよび他の Systems Manager の機能を呼び出すことができます。
-
aws:executeAwsApi: このオートメーションアクションは、AWS API オペレーションを呼び出して実行します。API 操作のほとんどはサポートされていますが、すべての API オペレーションがテストされているわけではありません。例えば、次の API オペレーションがサポートされています。CreateImage、Delete bucket、RebootDBInstance、および CreateGroups。Get Object アクションなどのストリーミング API オペレーションはサポートされていません。 -
aws:waitForAwsResourceProperty: このオートメーションアクションにより、続行する前にオートメーションが特定のリソース状態またはイベント状態を待てるようにします。例えば、Amazon Relational Database Service (Amazon RDS) DescribeDBInstances API オペレーションでこのアクションを使用すると、データベースインスタンスが起動するまでオートメーションを一時停止できます。 -
aws:assertAwsResourceProperty: このオートメーションアクションを使用すると、特定のステップの、特定のリソース状態またはイベント状態をアサートできます。たとえば、オートメーションのステップが EC2 インスタンスの起動を待つように指定することができます。次に、Amazon Elastic Compute Cloud (Amazon EC2) DescribeInstanceStatus API オペレーションを実行し、DesiredValue プロパティをrunningにします。これにより、オートメーションはインスタンスの実行を待機し、インスタンスが実際に実行されているときに続行されます。
次に、aws:executeAwsApi アクションを使用して S3 バケットの読み書きのアクセス許可をオフにする YAML のサンプルのランブックを示します。
--- description: Disable S3-Bucket's public WriteRead access via private ACL schemaVersion: "0.3" assumeRole: "{{ AutomationAssumeRole }}" parameters: S3BucketName: type: String description: (Required) S3 Bucket subject to access restriction AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: DisableS3BucketPublicReadWrite action: aws:executeAwsApi inputs: Service: s3 Api: PutBucketAcl Bucket: "{{S3BucketName}}" ACL: private isEnd: true ...
以下に、3つのアクションすべてを使用するYAMLのサンプルランブックがあります。オートメーションでは、次の処理が行われます。
-
aws:executeAwsApiアクションを使用して Amazon EC2 DescribeImages API オペレーションを呼び出し、特定の Windows Server 2016 AMI の名前を取得します。イメージ ID をImageIdとして出力します。 -
aws:executeAwsApiアクションを使用して、Amazon EC2 RunInstances API オペレーションを呼び出し、前の手順のImageIdを使用するインスタンスを 1 つ起動します。インスタンス ID をInstanceIdとして出力します。 -
aws:waitForAwsResourcePropertyアクションを使用して Amazon EC2 DescribeInstanceStatus API オペレーションをポーリングし、インスタンスがrunning状態になるまで待機します。アクションは 60 秒でタイムアウトします。60 秒間のポーリング後にインスタンス状態がrunningにならなかった場合、このステップはタイムアウトします。 -
aws:assertAwsResourcePropertyアクションを使用して Amazon EC2DescribeInstanceStatusAPI オペレーションを呼び出し、インスタンスがrunning状態であることをアサートします。インスタンス状態がrunningではない場合、このステップは失敗します。
--- description: Sample runbook using AWS API operations schemaVersion: '0.3' assumeRole: "{{ AutomationAssumeRole }}" parameters: AutomationAssumeRole: type: String description: "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf." default: '' ImageName: type: String description: "(Optional) Image Name to launch EC2 instance with." default: "Windows_Server-2016-English-Full-Base-2018.07.11" mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ ImageName }}" outputs: - Name: ImageId Selector: "$.Images[0].ImageId" Type: "String" - name: launchOneInstance action: aws:executeAwsApi inputs: Service: ec2 Api: RunInstances ImageId: "{{ getImageId.ImageId }}" MaxCount: 1 MinCount: 1 outputs: - Name: InstanceId Selector: "$.Instances[0].InstanceId" Type: "String" - name: waitUntilInstanceStateRunning action: aws:waitForAwsResourceProperty # timeout is strongly encouraged for action - aws:waitForAwsResourceProperty timeoutSeconds: 60 inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running - name: assertInstanceStateRunning action: aws:assertAwsResourceProperty inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running outputs: - "launchOneInstance.InstanceId" ...
入力と出力の使用
前述の各オートメーションアクションを使用すると、サービス名前空間、API オペレーション名、入力パラメータ、および出力パラメータを指定して、特定の API オペレーションを呼び出すことができます。入力は、選択した API オペレーションによって定義されます。API オペレーション (メソッド) は、以下の「サービスリファレンス
各オートメーションアクションのスキーマは、次の場所で表示できます。
スキーマには、各アクションを使用するための必須フィールドの説明が含まれています。
Selector/PropertySelector フィールドの使用
各オートメーションアクションでは、出力 Selector (aws:executeAwsApi 用) または PropertySelector (aws:assertAwsResourceProperty および aws:waitForAwsResourceProperty 用) を指定する必要があります。これらのフィールドは、AWS API オペレーションから JSON 応答を処理するために使用されます。これらのフィールドは JSONPath 構文を使用します。
次に、aws:executeAwsAPi アクションのこの概念を説明する例を示します。
--- mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ ImageName }}" outputs: - Name: ImageId Selector: "$.Images[0].ImageId" Type: "String" ...
aws:executeAwsApi ステップ getImageId で、オートメーションは DescribeImages API オペレーションを呼び出し、ec2 からレスポンスを受け取ります。次に、オートメーションは Selector -
"$.Images[0].ImageId" を API レスポンスに適用し、選択した値を出力 ImageId 変数に割り当てます。同じ自動化の他のステップでは、ImageId を指定して "{{
getImageId.ImageId }}" の値を使用できます。
次に、aws:waitForAwsResourceProperty アクションのこの概念を説明する例を示します。
--- - name: waitUntilInstanceStateRunning action: aws:waitForAwsResourceProperty # timeout is strongly encouraged for action - aws:waitForAwsResourceProperty timeoutSeconds: 60 inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running ...
aws:waitForAwsResourceProperty ステップ waitUntilInstanceStateRunning で、オートメーションは DescribeInstanceStatus API オペレーションを呼び出し、ec2 からレスポンスを受け取ります。次に、オートメーションは PropertySelector -
"$.InstanceStatuses[0].InstanceState.Name" をレスポンスに適用し、指定された戻り値が DesiredValues リスト (この場合は running) の値と一致するかどうかを確認します。このステップは、レスポンスが running のインスタンスの状態を返すまでプロセスを繰り返します。
JSONPath をランブックで使用する
JSONPath 式は、「$.」で始まる文字列で、JSON 要素内の 1 つ以上のコンポーネントを選択するために使用されます。次のリストには、Systems Manager Automation でサポートされている JSONPath 演算子に関する情報が含まれています。
-
Dot-notated child (.): JSON オブジェクトで使用します。この演算子は、特定のキーの値を選択します。
-
Deep-scan (..): JSON 要素で使用します。この演算子は、レベル別に JSON 要素レベルをスキャンし、特定のキーで値のリストを選択します。この演算子の戻り型は、常に JSON 配列です。オートメーションアクションの出力タイプのコンテキストでは、演算子は StringList または MapList のいずれかになります。
-
Array-Index([ ]): JSON 配列で使用します。この演算子は、特定のインデックスの値を取得します。
JSONPath 演算子をよりよく理解するために、ec2 DescribeInstances API オペレーションの次の JSON 応答を確認してください。このレスポンスの下には、DescribeInstances API オペレーションからのレスポンスにさまざまな JSONPath 式を適用してさまざまな結果を示すいくつかの例があります。
{ "NextToken": "abcdefg", "Reservations": [ { "OwnerId": "123456789012", "ReservationId": "r-abcd12345678910", "Instances": [ { "ImageId": "ami-12345678", "BlockDeviceMappings": [ { "Ebs": { "DeleteOnTermination": true, "Status": "attached", "VolumeId": "vol-000000000000" }, "DeviceName": "/dev/xvda" } ], "State": { "Code": 16, "Name": "running" } } ], "Groups": [] }, { "OwnerId": "123456789012", "ReservationId": "r-12345678910abcd", "Instances": [ { "ImageId": "ami-12345678", "BlockDeviceMappings": [ { "Ebs": { "DeleteOnTermination": true, "Status": "attached", "VolumeId": "vol-111111111111" }, "DeviceName": "/dev/xvda" } ], "State": { "Code": 80, "Name": "stopped" } } ], "Groups": [] } ] }
JSONPath 例 1: JSON レスポンスから特定の文字列を取得する
JSONPath: $.Reservations[0].Instances[0].ImageId Returns: "ami-12345678" Type: String
JSONPath 例 2: JSON レスポンスから特定のブーリアンを取得する
JSONPath: $.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination Returns: true Type: Boolean
JSONPath 例 3: JSON レスポンスから特定の整数を取得する
JSONPath: $.Reservations[0].Instances[0].State.Code Returns: 16 Type: Integer
JSONPath 例 4: JSON レスポンスを詳細にスキャンし、VolumeId のすべての値を StringList として取得する
JSONPath: $.Reservations..BlockDeviceMappings..VolumeId Returns: [ "vol-000000000000", "vol-111111111111" ] Type: StringList
JSONPath 例 5: 特定の BlockDeviceMappings オブジェクトを StringMap として取得する
JSONPath: $.Reservations[0].Instances[0].BlockDeviceMappings[0] Returns: { "Ebs" : { "DeleteOnTermination" : true, "Status" : "attached", "VolumeId" : "vol-000000000000" }, "DeviceName" : "/dev/xvda" } Type: StringMap
JSONPath 例 6: JSON レスポンスを詳細にスキャンし、すべての State のオブジェクトを MapList として取得します
JSONPath: $.Reservations..Instances..State Returns: [ { "Code" : 16, "Name" : "running" }, { "Code" : 80, "Name" : "stopped" } ] Type: MapList
AWS Identity and Access Management (IAM) サービスロールを使用して他のサービスを呼び出す自動化ワークフローを実行する場合は、それらのサービスを呼び出すためのアクセス許可をサービスロールに設定する必要がある点に注意してください。この要件は、AWS-ConfigureS3BucketLogging、AWS-CreateDynamoDBBackup、AWS-RestartEC2Instance ランブックなど、すべての AWS オートメーションランブック (AWS-* ランブック) に適用されます。この要件は、他のサービスを呼び出すアクションを使用して他の AWS のサービスを呼び出すように作成したカスタムオートメーションランブックにも適用されます。例えば、aws:executeAwsApi、aws:createStack、または aws:copyImage のアクションを使用する場合は、それらのサービスを呼び出すためのアクセス許可を持つサービスロールを設定します。ロールに IAM インラインポリシーを追加することで、他の AWS のサービスへのアクセス許可を有効にできます。詳細については、「」を参照してください(オプション) 他の AWS のサービスを呼び出すためのオートメーションインラインポリシーを追加する
サンプルチュートリアル: Systems Manager Automation のランブックから Amazon RDS インスタンスを起動する
このサンプルチュートリアルでは、Amazon Relational Database Service (Amazon RDS) データベースインスタンスが実行中かどうかを確認するために、3 つの API オペレーションをすべて使用する Systems Manager Automation ランブックを YAML で作成および実行する方法を示します。DB インスタンスが実行されていない場合は、オートメーションによって起動されます。
Amazon RDS API オペレーションをランブックから呼び出すには
-
テキストエディタを開き、次のランブックの内容をファイルに貼り付けます。確認する自動化ロールとインスタンス ID を指定します。後で mainSteps アクションを追加します。
--- description: Start RDS instance schemaVersion: "0.3" assumeRole: "The_Automation_role_to_use_when_running_the_runbook" parameters: InstanceId:The_instance_ID_to_starttype: String description: (Required) RDS instance ID to start AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: -
オートメーションの最初のステップでは、インスタンスがすでに実行されているかどうかを判断する必要があります。
aws:assertAwsResourcePropertyアクションを使用して、特定のインスタンスステータスを判断し、アサートできます。aws:assertAwsResourcePropertyアクションをランブックに追加する前に、必要な入力を決定して指定する必要があります。以下のリストは、必要な入力を決定し、指定する方法を示しています。リストの後に、ランブックにこの情報を入力する方法の例を見ることができます。-
スキーマを表示し、aws:assertAwsResourceProperty – AWS リソースの状態またはイベントの状態をアサートする アクションで使用可能なすべての入力を表示します。
-
呼び出すサービスの名前空間を決定します。AWS のサービスの名前空間は、アマゾン ウェブ サービス全般のリファレンスの「Amazon リソースネーム (ARN) と AWS のサービスの名前空間」に一覧表示されています。Amazon RDS の名前空間は
rdsです。 -
データベースインスタンスの状態を表示するためにどの Amazon RDS API オペレーションを使用するかを決定します。API オペレーション (メソッド) は、「Amazon RDS メソッド
」ページで表示できます。 -
DescribeDBInstances API オペレーションに 1 つ以上のリクエストパラメータを指定します。たとえば、このアクションは
DBInstanceIdentifierリクエストパラメータを使用します。 -
1 つ以上の PropertySelector を決定します。PropertySelector は、この API オペレーションのリクエストによって返される応答オブジェクトです。例えば、Amazon RDS メソッド
で。describe_db_instances メソッドを選択し、[Response Structure (レスポンス構造)] セクションまで下にスクロールします。[DBInstances] は応答オブジェクトとして表示されます。このチュートリアルでは、 DBInstancesとDBInstanceStatusを PropertySelectors として指定します。JSONPath を使用して PropertySelectors を入力することに注意してください。これは、ランブック内の情報を次のようにフォーマットすることを意味します。PropertySelector: "$.DBInstances[0].DBInstanceStatus". -
1 つ以上の DesiredValues を指定します。指定する値がわからない場合は、DescribeDBInstances API オペレーションを実行して値を決定します。このチュートリアルでは、available と starting を指定します。
-
次の例に示すように、収集した情報をランブックに入力します。
--- description: Start RDS instance schemaVersion: "0.3" assumeRole: "The_Automation_role_to_use_when_running_the_runbook" parameters: InstanceId:The_instance_ID_to_starttype: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name:AssertNotStartingOrAvailableaction: aws:assertAwsResourceProperty isCritical:falseonFailure:step:StartInstancenextStep:CheckStartinputs: Service:rdsApi:DescribeDBInstancesDBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available", "starting"] -
-
前のアクションによって開始されていないと判断された場合は、mainSteps セクションに
aws:executeAwsApiアクションを指定してインスタンスを開始します。-
スキーマを表示して、aws:executeAwsApi — AWS API オペレーションの呼び出しと実行 の使用可能なすべての入力を表示します。
-
Amazon RDS StartDBInstance
API オペレーションを指定して、インスタンスを起動します。 -
次の例に示すように、収集した情報をランブックに入力します。
--- description: Start RDS instance schemaVersion: "0.3" assumeRole: "{{ The_Automation_role_to_use_when_running_the_runbook }}" parameters: InstanceId: type: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: AssertNotStartingOrAvailable action: aws:assertAwsResourceProperty isCritical: false onFailure: step:StartInstance nextStep: CheckStart inputs: Service: rds Api: DescribeDBInstances DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available", "starting"] - name:StartInstanceaction: aws:executeAwsApi inputs: Service:rdsApi:StartDBInstanceDBInstanceIdentifier: "{{InstanceId}}" -
-
mainSteps セクションの
aws:waitForAwsResourcePropertyアクションを指定して、オートメーションを終了する前にインスタンスが開始するのを待ちます。-
スキーマを表示して、aws:waitForAwsResourceProperty – AWS リソースプロパティを待つ の使用可能なすべての入力を表示します。
-
Amazon RDS DescribeDBInstances
API オペレーションを指定して、インスタンスの状態を判断します。 -
$.DBInstances[0].DBInstanceStatusをPropertySelectorと指定します。 -
available を
DesiredValueと指定します。 -
次の例に示すように、収集した情報をランブックに入力します。
--- description: Start RDS instance schemaVersion: "0.3" assumeRole: "{{ The_Automation_role_to_use_when_running_the_runbook }}" parameters: InstanceId: type: String description: (Required) RDS Instance Id to stop AutomationAssumeRole: type: String description: (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. default: "" mainSteps: - name: AssertNotStartingOrAvailable action: aws:assertAwsResourceProperty isCritical: false onFailure: step:StartInstance nextStep: CheckStart inputs: Service: rds Api: DescribeDBInstances DBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available", "starting"] - name: StartInstance action: aws:executeAwsApi inputs: Service: rds Api: StartDBInstance DBInstanceIdentifier: "{{InstanceId}}" - name:CheckStartaction: aws:waitForAwsResourceProperty onFailure: Abort maxAttempts: 10 timeoutSeconds: 600 inputs: Service:rdsApi:DescribeDBInstancesDBInstanceIdentifier: "{{InstanceId}}" PropertySelector: "$.DBInstances[0].DBInstanceStatus" DesiredValues: ["available"] isEnd: true ... -
-
ファイルを sample.yaml として保存します。
-
AWS CLI で次のコマンドを実行して、ランブックを AWS アカウント に追加します。
aws ssm create-document --name sampleRunbook --document-type Automation --document-format YAML --content file://sample.yaml -
次のコマンドを実行して、先ほど作成したランブックを使用してオートメーションを開始します。オートメーションを開始した後、Systems Manager によって返された実行 ID を記録します。
aws ssm start-automation-execution --document-name sampleRunbook -
以下のコマンドを実行して、実行のステータスを表示します。
aws ssm get-automation-execution --automation-execution-idautomation_execution_id
AWSAPI を呼び出す定義済みのランブック
Systems Manager Automation には、AWS API の呼び出しを行う以下の事前定義されたランブックが含まれています。
| ランブック名 | 目的 |
|---|---|
|
Amazon RDS インスタンスを起動します。 |
|
|
Amazon RDS インスタンスを停止します。 |
|
|
Amazon RDS インスタンスを再起動します。 |
|
|
Amazon Elastic Block Store (Amazon EBS) ボリュームスナップショットを作成します。 |
|
|
Amazon EBS ボリュームスナップショットを削除します。 |
|
|
Amazon Simple Storage Service (Amazon S3) バケットのログ記録を有効にします。 |
|
|
プライベート ACL を使用して、S3 バケットに対する読み書きのアクセス許可をオフにします。 |
|
|
S3 バケットのバージョニングを有効または停止します。 |
|
|
Amazon DynamoDB テーブルのバックアップを削除します。 |
前述の表のリンクを選択するか、次の手順を使用して、Systems Manager コンソールでこれらのランブックの詳細を表示します。
AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/
) を開きます。 ナビゲーションペインで、[ドキュメント] を選択します。
-または-
AWS Systems Manager ホームページが最初に開く場合は、メニューアイコン (
) を選択してナビゲーションペインを開き、[ドキュメント] を選択します。-
ランブックを選択し、[詳細を表示] を選択します。
-
[Content] タブを選択します。
