メニュー
Amazon EC2 Systems Manager
ユーザーガイド

Systems Manager ドキュメント

Amazon EC2 Systems Manager ドキュメントは、マネージドインスタンスで Systems Manager が実行するアクションを定義します。Systems Manager には、実行時にパラメータを指定して使用できる事前設定済みのドキュメントが十数個含まれています。ドキュメントは JavaScript Object Notation (JSON) を使用します。ドキュメントにはユーザーが指定するパラメータやステップが含まれています。

次の表は、さまざまなタイプの SSM ドキュメントを説明したものです。

タイプ 以下で使用 詳細

コマンドのドキュメント

Run Command

ステートマネージャー

Run Command はコマンドドキュメントを使用してコマンドを実行します。ステートマネージャー はコマンドドキュメントを使用してポリシーを適用します。これらのアクションは、インスタンスのライフサイクル中にいつでも、1 つまたは複数のターゲットで実行できます。

ポリシードキュメント

ステートマネージャー

ポリシードキュメントはターゲットにポリシーを適用します。ポリシードキュメントが削除された場合、ポリシー (インベントリ収集など) が発生しなくなります。

オートメーションドキュメント

オートメーション

Amazon Machine Image (AMI) の作成や更新など、一般的なメンテナンスやデプロイメントタスクを実行する際に、オートメーションドキュメントを使用します。

SSM ドキュメントの制限の詳細については、「Amazon EC2 Systems Manager の制限」を参照してください。

Systems Manager 事前定義済みドキュメント

すぐに開始できるように、Systems Manager には事前定義済みドキュメントが用意されています。これらのドキュメントは、Amazon EC2 コンソールで表示できます。EC2 コンソールで、[Systems Manager Shared Resources] を展開し、[Documents] を選択します。ドキュメントを選択したら、次の図に示すように、下部ペインのタブを使用して選択したドキュメントに関する情報を確認します。

 Systems Manager ドキュメント

また、AWS CLI および Tools for Windows PowerShell コマンドを使用して、ドキュメントの一覧を表示したりドキュメントに関する説明を取得したりできます。

AWS CLI

Copy
aws ssm list-documents
Copy
aws ssm describe-document --name "document_name"

Tools for Windows PowerShell

Copy
Get-SSMDocumentList
Copy
Get-SSMDocumentDescription -Name "document_name"

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

現在 Systems Manager ドキュメントでは以下のスキーマバージョンを使用しています。

  • Command タイプのドキュメントではスキーマバージョン 1.2、2.0、および 2.2 を使用できます。現在使用しているドキュメントがスキーマ 1.2 である場合は、スキーマバージョン 2.2 を使用するドキュメントを作成することをお勧めします。

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

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

Command および Policy ドキュメントで最新バージョンのスキーマを使用することで、次の機能を利用できます。

スキーマバージョン 2.2 ドキュメントの機能

機能 詳細

ドキュメントの編集

ドキュメントは更新可能になりました。バージョン 1.2 では、ドキュメントを更新した場合に別の名前で保存する必要がありました。

バージョンの自動管理

ドキュメントを更新すると新しいバージョンが作成されます。これはスキーマのバージョンではなく、ドキュメントのバージョンです。

デフォルトバージョン

ドキュメントに複数のバージョンがある場合、どのバージョンがデフォルトのドキュメントかを指定できます。

順序付け

ドキュメントのプラグインまたはステップを指定した順序で実行します。

クロスプラットフォームのサポート

クロスプラットフォームをサポートすることで、同じ SSM ドキュメント内で異なるプラグインに異なるオペレーティングシステムを指定できます。クロスプラットフォームのサポートはステップ内の precondition パラメータを使用します。

注記

新しい Systems Manager 機能および SSM ドキュメント機能を使用するには、インスタンスの SSM エージェントを最新バージョンに更新する必要があります。詳細については、「EC2 コンソールからコマンドを実行する」の「例: SSM エージェントの更新」というタイトルのセクションを参照してください。

次の表はスキーマのメジャーバージョン間の相違点の一覧です。

バージョン 1.2 バージョン 2.0 詳細

runtimeConfig

mainSteps

バージョン 2.0 以降では、mainSteps セクションは runtimeConfig に置き換えられます。mainSteps セクションを使うと、Systems Manager はステップを順に実行できます。

プロパティ

inputs

バージョン 2.0 以降では、inputs セクションは properties セクションに置き換えられます。inputs セクションは、ステップのパラメータを受け入れます。

commands

runCommand

バージョン 2.0 以降では、inputs セクションは runCommand パラメータを使用します。commands パラメータは使用しません。

id

action

バージョン 2.0 以降では、Action セクションは ID に置き換えられます。これは名前のみの変更です。

該当なし

name

バージョン 2.0 以降では、name はステップの任意のユーザー定義名です。

SSM ドキュメントの構文

ドキュメントの構文は作成に使用するスキーマのバージョンによって定義されます。バージョン 2.2 以降のスキーマを使用することをお勧めします。このスキーマバージョンを使用したドキュメントには、次の最上位要素が含まれます。これらの要素で指定できるプロパティについては、Amazon EC2 Systems Manager API Reference の Top-level Elements を参照してください。

  • schemaVersion: 使用するスキーマバージョン。

  • Description: ドキュメントの目的を説明するために提供する情報。

  • Parameters: ドキュメントで受け入れるパラメータ。頻繁に参照するパラメータの場合は、そのパラメータを Systems Manager パラメーターストアに保存してそこを参照することをお勧めします。ドキュメントのこのセクションで String および StringList Systems Manager パラメータを参照できます。ドキュメントのこのセクションで Secure String Systems Manager パラメータを参照することはできません。詳細については、「Systems Manager パラメータストア」を参照してください。

  • mainSteps: 複数のステップ (プラグイン) を含めることができるオブジェクト。ステップには、1 つまたは複数のアクション、任意の前提条件、アクションの一意の名前、これらのアクションの入力 (パラメータ) が含まれます。サポートされるプラグインおよびプラグインのプロパティのリストについては、Amazon EC2 Systems Manager API Reference の「SSM プラグイン」を参照してください。

    重要

    アクションの名前にスペースを含めることはできません。名前にスペースが含まれる場合、InvalidDocumentContent エラーが発生します。

前提条件パラメータを使用する

スキーマバージョン 2.2 以降では、precondition パラメータを使用して各プラグインのターゲットオペレーティングシステムを指定できます。precondition パラメータは platformType、および Windows または Linux いずれかの値をサポートします。

スキーマバージョン 2.2 以降を使用するドキュメントの場合、precondition が指定されていないと、各プラグインはそのプラグインとオペレーティングシステムとの互換性に基づいて実行またはスキップされます。スキーマ 2.0 以前を使用するドキュメントの場合は、互換性のないプラグインはエラーをスローします。

たとえば、スキーマバージョンが 2.2 のドキュメントで、precondition が指定されておらず aws:runShellScript プラグインがリストされている場合、そのステップは Linux インスタンスで実行されますが、Windows インスタンスではシステムによってスキップされます。これは、aws:runShellScript が Windows インスタンスと互換性がないためです。しかし、スキーマバージョンが 2.0 のドキュメントでは、aws:runShellScript プラグインを指定して、ドキュメントを Windows インスタンスで実行した場合、実行は失敗します。

スキーマバージョン 2.0 以降の構文

次の例では、スキーマバージョン 2.0 以降のドキュメントの最上位要素を示します。

Copy
{ "schemaVersion":"2.0", "description":"A description of the document.", "parameters":{ "parameter 1":{ "one or more parameter properties" }, "parameter 2":{ "one or more parameter properties" }, "parameter 3":{ "one or more parameter properties" } }, "mainSteps":[ { "action":"plugin 1", "name":"A name for this action.", "inputs":{ "name":"{{ input 1 }}", "name":"{{ input 2 }}", "name":"{{ input 3 }}", } } ] }

スキーマバージョン 2.2 の例

スキーマバージョン 2.2 ではクロスプラットフォームのサポートを提供します。つまり、単一の SSM ドキュメント内で異なるプラグインに異なるオペレーティングシステムを指定できます。クロスプラットフォームのサポートは、次の例のようにステップ内で preconditionパラメータを使用します。

Copy
{ "schemaVersion":"2.2", "description":"cross-platform sample", "mainSteps":[ { "action":"aws:runPowerShellScript", "name":"PatchWindows", "precondition":{ "StringEquals":[ "platformType", "Windows" ] }, "inputs":{ "runCommand":[ "cmds" ] } }, { "action":"aws:runShellScript", "name":"PatchLinux", "precondition":{ "StringEquals":[ "platformType", "Linux" ] }, "inputs":{ "runCommand":[ "cmds" ] } } ] }

スキーマバージョン 2.0 の例

次の例は AWS-ConfigureAWSPackage ドキュメントを示します。mainSteps セクションは action ステップに aws:configurePackage プラグインを含みます。

Copy
{ "schemaVersion": "2.0", "description": "Install or uninstall the latest version or specified version of an AWS package.", "parameters": { "action": { "description": "(Required) Specify whether or not to install or uninstall the package.", "type": "String", "allowedValues": [ "Install", "Uninstall" ] }, "name": { "description": "(Required) The package to install/uninstall.", "type": "String", "allowedValues": [ "AWSPVDriver" ] }, "version": { "description": "(Optional) A specific version of the package to install or uninstall. If installing, the system installs the latest published version, by default. If uninstalling, the system uninstalls the currently installed version, by default. If no installed version is found, the latest published version is downloaded, and the uninstall action is run.", "type": "String", "default": "", "allowedPattern": "(^(?:(\\d+)\\.)(?:(\\d+)\\.)(\\d+)$|^$)" } }, "mainSteps": [{ "action": "aws:configurePackage", "name": "configurePackage", "inputs": { "name": "{{ name }}", "action": "{{ action }}", "version": "{{ version }}" } }] }

スキーマバージョン 1.2 の構文

次の例では、スキーマバージョン 1.2 のドキュメントの最上位要素を示します。

Copy
{ "schemaVersion":"1.2", "description":"A description of the Systems Manager document.", "parameters":{ "parameter 1":{ "one or more parameter properties" }, "parameter 2":{ "one or more parameter properties" }, "parameter 3":{ "one or more parameter properties" } }, "runtimeConfig":{ "plugin 1":{ "properties":[ { "one or more plugin properties" } ] } } }

注記

aws:applications、aws:psModule、aws:runShellScript、および aws:runPowerShellScript プラグインを使用してプロパティの配列を指定できます。

スキーマバージョン 1.2 の例

次の例は AWS-RunShellScript Systems Manager ドキュメントを示します。runtimeConfig セクションには aws:runShellScript プラグインが含まれます。

Copy
{ "schemaVersion":"1.2", "description":"Run a shell script or specify the commands to run.", "parameters":{ "commands":{ "type":"StringList", "description":"(Required) Specify a shell script or a command to run.", "minItems":1, "displayType":"textarea" }, "workingDirectory":{ "type":"String", "default":"", "description":"(Optional) The path to the working directory on your instance.", "maxChars":4096 }, "executionTimeout":{ "type":"String", "default":"3600", "description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 28800 (8 hours).", "allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)" } }, "runtimeConfig":{ "aws:runShellScript":{ "properties":[ { "id":"0.aws:runShellScript", "runCommand":"{{ commands }}", "workingDirectory":"{{ workingDirectory }}", "timeoutSeconds":"{{ executionTimeout }}" } ] } } }

ドキュメントのバージョンと実行

ドキュメントの異なるバージョンを作成して保存できます。その後、各ドキュメントのデフォルトのバージョンを指定できます。ドキュメントのデフォルトバージョンは、新しいバージョンに更新したり、古いバージョンのドキュメントに戻すことができます。ステートマネージャードキュメントのデフォルトバージョンを変更した場合、そのドキュメントを使用する関連付けでは、次回に Systems Manager が関連付けをインスタンスに適用するときに、新しいデフォルトのバージョンを使い始めます。

ドキュメントの JSON コンテンツを変更すると、Systems Manager は自動的にドキュメントのバージョンを増やします。ドキュメントの以前のバージョンは、取得と表示が可能です。ステートマネージャードキュメントは、インスタンスまたはタグ付けされたグループと関連付けることができます。

また、 ドキュメントに関する以下の詳細情報に注意してください。

  • 異なる ドキュメントを使用する別の関連付けを作成して、ターゲットに複数のドキュメントを割り当てることができます。

  • ターゲットに複数のドキュメントを関連付ける場合、AWS CLI、AWS Tools for Windows PowerShell、または SSM SDK を使用して、関連付けられたすべてのドキュメント全体で実行されるすべてのプラグインの一覧を表示できます。

  • ドキュメント内のステップは順番に実行されます。

  • アクセス許可がある限り、ステートマネージャー で共有ドキュメントを使用できますが、共有ドキュメントをインスタンスに関連付けることはできません。1 つ以上のターゲットに関連付けられたドキュメントを使用または共有する場合は、ドキュメントのコピーを作成し、そのコピーを使用または共有する必要があります。

  • 競合するプラグインでドキュメントを作成する場合 (たとえば、ドメイン結合やドメインからの削除)、実行された最後のプラグインが最終状態になります。ステートマネージャー はドキュメントのコマンドまたはプラグインの論理シーケンスまたは合理性を検証しません。

  • ドキュメントを処理するときに、インスタンスの関連付けが最初に適用され、次にタグ付けされたグループの関連付けが適用されます。インスタンスが、タグ付けされた複数のグループの一部である場合、タグ付けされたグループの一部であるドキュメントは、特定の順序で実行されません。インスタンスがインスタンス ID によって複数のドキュメントから直接対象になっている場合、特定の実行順序はありません。

ドキュメントのカスタマイズ

ドキュメントのステップやアクションをカスタマイズする場合は、独自のドキュメントを作成できます。初めてドキュメントを使用してインスタンスでアクションを実行する際に、システムはドキュメントを AWS アカウントに保存します。Systems Manager ドキュメントの作成方法の詳細については、「Systems Manager ドキュメントの作成」を参照してください。

ドキュメントの共有

ドキュメントを公開するか、または特定の AWS アカウントと共有できます。詳細については、「Systems Manager ドキュメントの共有」を参照してください。