スキーマ、機能、および例
AWS Systems Manager (SSM) ドキュメントでは以下のスキーマバージョンを使用しています。
-
Commandタイプのドキュメントは、スキーマバージョン 1.2、2.0 および 2.2 を使用できます。使用しているドキュメントがスキーマ 1.2 である場合は、スキーマバージョン 2.2 を使用するドキュメントを作成することをお勧めします。 -
Policyタイプのドキュメントは、スキーマバージョン 2.0 以降を使用する必要があります。 -
Automationタイプのドキュメントは、スキーマバージョン 0.3 を使用する必要があります。 -
Sessionタイプのドキュメントは、スキーマバージョン 1.0 を使用する必要があります。 -
JSON あるいは YAML でドキュメントを作成できます。
Session ドキュメントスキーマの詳細については、「セッションドキュメントスキーマ」を参照してください。
Command および Policy ドキュメントで最新バージョンのスキーマを使用することで、次の機能を利用できます。
| 機能 | 詳細 |
|---|---|
|
ドキュメントの編集 |
ドキュメントは更新可能になりました。バージョン 1.2 では、ドキュメントを更新した場合に別の名前で保存する必要がありました。 |
|
バージョンの自動管理 |
ドキュメントを更新すると新しいバージョンが作成されます。これはスキーマのバージョンではなく、ドキュメントのバージョンです。 |
|
デフォルトバージョン |
ドキュメントに複数のバージョンがある場合、どのバージョンがデフォルトのドキュメントかを指定できます。 |
|
順序付け |
ドキュメントのプラグインまたはステップを指定した順序で実行します。 |
|
クロスプラットフォームのサポート |
クロスプラットフォームをサポートすることで、同じ SSM ドキュメント内で異なるプラグインに異なるオペレーティングシステムを指定できます。クロスプラットフォームのサポートはステップ内の |
注記
新しい Systems Manager 機能および SSM ドキュメント機能を使用するには、インスタンスの AWS Systems Manager SSM Agent を常に最新バージョンに更新しておく必要があります。詳細については、「Run Command を使用して SSM Agent を更新する」を参照してください。
次の表はスキーマのメジャーバージョン間の相違点の一覧です。
| バージョン 1.2 | バージョン 2.2 (最新バージョン) | 詳細 |
|---|---|---|
|
runtimeConfig |
mainSteps |
バージョン 2.2 では、 |
|
プロパティ |
inputs |
バージョン 2.2 では、 |
|
commands |
runCommand |
バージョン 2.2 では、 |
|
id |
action |
バージョン 2.2 では、 |
|
該当なし |
name |
バージョン 2.2 では、 |
前提条件パラメータを使用する
スキーマバージョン 2.2 以降では、precondition パラメータを使用して、各プラグインのターゲットオペレーティングシステムを指定したり、SSM ドキュメントで定義した入力パラメータを検証したりすることができます。precondition パラメータは、SSM ドキュメントの入力パラメータと、platformType、Linux、および MacOS の値を使用する Windows の参照をサポートします。StringEquals 演算子のみがサポートされています。
スキーマバージョン 2.2 以降を使用するドキュメントの場合、precondition が指定されていないと、各プラグインはそのプラグインとオペレーティングシステムとの互換性に基づいて実行またはスキップされます。オペレーティングシステムとのプラグインの互換性は、precondition の前に評価されます。スキーマ 2.0 以前を使用するドキュメントの場合は、互換性のないプラグインはエラーをスローします。
例えば、スキーマバージョンが 2.2 のドキュメントで、precondition が指定されておらず aws:runShellScript プラグインが一覧表示されている場合、そのステップは Linux インスタンスで実行されますが、Windows Server インスタンスではシステムによってこれがスキップされます。これは、aws:runShellScript が Windows Server インスタンスと互換性がないためです。しかし、スキーマバージョンが 2.0 のドキュメントでは、aws:runShellScript プラグインを指定して、ドキュメントを Windows Server インスタンスで実行した場合、実行は失敗します。SSM ドキュメントでの前提条件パラメータの例は後でこのセクションで確認できます。
スキーマバージョン 2.2
最上位の要素
以下の例では、スキーマバージョン 2.2 を使用した SSM ドキュメントの最上位要素を示しています。
スキーマバージョン 2.2 の例
以下の例では、aws:runPowerShellScript プラグインを使用してターゲットインスタンスで PowerShell コマンドを実行しています。
スキーマバージョン 2.2 の precondition パラメータ例
スキーマバージョン 2.2 ではクロスプラットフォームのサポートを提供します。つまり、単一の SSM ドキュメント内で異なるプラグインに異なるオペレーティングシステムを指定できます。クロスプラットフォームのサポートは、次の例のようにステップ内で preconditionパラメータを使用します。precondition パラメータは、SSM ドキュメントで定義した入力パラメータの検証にも使用できます。これは、次の例の 2 番目にあります。
スキーマバージョン 2.2 State Manager の例
Systems Manager の一機能である State Manager で以下の SSM ドキュメントを使用すると、ClamAV のウイルス対策ソフトウェアをダウンロードしてインストールできます。State Manager によって特定の設定が適用されます。つまり、State Manager 関連付けが実行されるごとに、ClamAV ソフトウェアがインストールされているかが、システムによってチェックされます。インストールされていない場合には、State Manager はこのドキュメントを返します。
スキーマバージョン 2.2 インベントリの例
State Manager で以下の SSM ドキュメントを使用すると、インスタンスに関するインベントリのメタデータを収集できます。
スキーマバージョン 2.2 AWS-ConfigureAWSPackage の例
以下の例は AWS-ConfigureAWSPackage ドキュメントを示しています。mainSteps セクションの aws:configurePackage ステップには action プラグインが含まれています。
注記
Linux オペレーティングシステムでは、AmazonCloudWatchAgent パッケージ、および AWSSupport-EC2Rescue パッケージのみがサポートされています。
スキーマバージョン 1.2
次の例では、スキーマバージョン 1.2 のドキュメントの最上位要素を示します。
{ "schemaVersion":"1.2", "description":"A description of the SSM 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" } ] } } }
スキーマバージョン 1.2 aws:runShellScript の例
以下の例は AWS-RunShellScript SSM ドキュメントを示しています。runtimeConfig セクションには aws:runShellScript プラグインが含まれます。
{ "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 172800 (48 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 }}" } ] } } }
スキーマバージョン 0.3
最上位の要素
次の例では、スキーマバージョン 0.3 の Automation ランブックの最上位要素を JSON 形式で示します。
{ "description": "document-description", "schemaVersion": "0.3", "assumeRole": "{{assumeRole}}", "parameters": { "parameter1": { "type": "String", "description": "parameter-1-description", "default": "" }, "parameter2": { "type": "String", "description": "parameter-2-description", "default": "" } }, "variables": { "variable1": { "type": "StringMap", "description": "variable-1-description", "default": {} }, "variable2": { "type": "String", "description": "variable-2-description", "default": "default-value" } }, "mainSteps": [ { "name": "myStepName", "action": "action-name", "maxAttempts": 1, "inputs": { "Handler": "python-only-handler-name", "Runtime": "runtime-name", "Attachment": "script-or-zip-name" }, "outputs": { "Name": "output-name", "Selector": "selector.value", "Type": "data-type" } } ], "files": { "script-or-zip-name": { "checksums": { "sha256": "checksum" }, "size":1234} } }
YAML Automation ランブックの例
次の例では、Automation ランブックの内容を YAML 形式で示します。このバージョン 0.3 のドキュメントスキーマの実例では、Markdown を使用してドキュメントの説明をフォーマットする方法も示しています。
description: >- ##Title: LaunchInstanceAndCheckState ----- **Purpose**: This Automation runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this document continuously checks the instance status check value for the launched instance until the status ```ok``` is returned. ##Parameters: ----- Name | Type | Description | Default Value ------------- | ------------- | ------------- | ------------- assumeRole | String | (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. | - imageId | String | (Optional) The AMI ID to use for launching the instance. The default value uses the latest Amazon Linux AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }} schemaVersion: '0.3' assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole' parameters: imageId: type: String default: '{{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}' description: >- (Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux AMI ID. tagValue: type: String default: ' LaunchedBySsmAutomation' description: >- (Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation. instanceType: type: String default: t2.micro description: >- (Optional) The instance type to use for the instance. The default value is t2.micro. mainSteps: - name: LaunchEc2Instance action: 'aws:executeScript' outputs: - Name: payload Selector: $.Payload Type: StringMap inputs: Runtime: python3.8 Handler: launch_instance Script: '' InputPayload: image_id: '{{ imageId }}' tag_value: '{{ tagValue }}' instance_type: '{{ instanceType }}' Attachment: launch.py description: >- **About This Step** This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided python script. - name: WaitForInstanceStatusOk action: 'aws:executeScript' inputs: Runtime: python3.8 Handler: poll_instance Script: |- def poll_instance(events, context): import boto3 import time ec2 = boto3.client('ec2') instance_id = events['InstanceId'] print('[INFO] Waiting for instance status check to report ok', instance_id) instance_status = "null" while True: res = ec2.describe_instance_status(InstanceIds=[instance_id]) if len(res['InstanceStatuses']) == 0: print("Instance status information is not available yet") time.sleep(5) continue instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status'] print('[INFO] Polling to get status of the instance', instance_status) if instance_status == 'ok': break time.sleep(10) return {'Status': instance_status, 'InstanceId': instance_id} InputPayload: '{{ LaunchEc2Instance.payload }}' description: >- **About This Step** The python script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned. files: launch.py: checksums: sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
