SSM ドキュメントスキーマと機能 - AWS Systems Manager

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

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

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

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

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

  • JSON あるいは YAML でドキュメントを作成できます。

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

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

ドキュメントの編集

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

バージョンの自動管理

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

デフォルトバージョン

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

順序付け

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

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

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

注記

新しい Systems Manager 機能および SSM ドキュメント機能を使用するには、インスタンスの SSM エージェント を常に最新バージョンに更新しておく必要があります。詳細については、「Run Command を使用して SSM エージェント を更新する」を参照してください。

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

バージョン 1.2 バージョン 2.2 (最新バージョン) 詳細

runtimeConfig

mainSteps

バージョン 2.2 では、runtimeConfig の代わりに mainSteps セクションを使用します。mainSteps セクションでは、Systems Manager がステップを順番に実行できるようになります。

プロパティ

inputs

バージョン 2.2 では、properties セクションの代わりに inputs セクションを使用します。inputs セクションは、ステップのパラメータを受け入れます。

commands

runCommand

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

id

action

バージョン 2.2 では、ID の代わりに Action を使用します。これは名前のみの変更です。

該当なし

name

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

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

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

スキーマバージョン 2.2 以降を使用するドキュメントの場合、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 ドキュメントの最上位要素を示しています。

YAML
--- schemaVersion: "2.2" description: A description of the document. parameters: parameter 1: property 1: "value" property 2: "value" parameter 2: property 1: "value" property 2: "value" mainSteps: - action: Plugin name name: A name for the step. inputs: input 1: "value" input 2: "value" input 3: "{{ parameter 1 }}"
JSON
{ "schemaVersion": "2.2", "description": "A description of the document.", "parameters": { "parameter 1": { "property 1": "value", "property 2": "value" }, "parameter 2":{ "property 1": "value", "property 2": "value" } }, "mainSteps": [ { "action": "Plugin name", "name": "A name for the step.", "inputs": { "input 1": "value", "input 2": "value", "input 3": "{{ parameter 1 }}" } } ] }

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

以下の例では、aws:runPowerShellScript プラグインを使用してターゲットインスタンスで PowerShell コマンドを実行しています。

YAML
--- schemaVersion: "2.2" description: "Example document" parameters: Message: type: "String" description: "Example parameter" default: "Hello World" mainSteps: - action: "aws:runPowerShellScript" name: "example" inputs: runCommand: - "Write-Output {{Message}}"
JSON
{ "schemaVersion": "2.2", "description": "Example document", "parameters": { "Message": { "type": "String", "description": "Example parameter", "default": "Hello World" } }, "mainSteps": [ { "action": "aws:runPowerShellScript", "name": "example", "inputs": { "runCommand": [ "Write-Output {{Message}}" ] } } ] }

スキーマバージョン 2.2 の前提条件パラメータの例

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

YAML
--- 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
JSON
{ "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.2 ステートマネージャーの例

ステートマネージャー で以下の SSM ドキュメントを使用すると、ClamAV のウイルス対策ソフトウェアをダウンロードしてインストールできます。ステートマネージャー によって特定の設定が適用されます。つまり、ステートマネージャー 関連付けが実行されるごとに、ClamAV ソフトウェアがインストールされているかが、システムによってチェックされます。インストールされていない場合には、ステートマネージャー はこのドキュメントを返します。

YAML
--- schemaVersion: '2.2' description: State Manager Bootstrap Example parameters: {} mainSteps: - action: aws:runShellScript name: configureServer inputs: runCommand: - sudo yum install -y httpd24 - sudo yum --enablerepo=epel install -y clamav
JSON
{ "schemaVersion": "2.2", "description": "State Manager Bootstrap Example", "parameters": {}, "mainSteps": [ { "action": "aws:runShellScript", "name": "configureServer", "inputs": { "runCommand": [ "sudo yum install -y httpd24", "sudo yum --enablerepo=epel install -y clamav" ] } } ] }

スキーマバージョン 2.2 インベントリの例

SSM で以下の ステートマネージャー ドキュメントを使用すると、インスタンスに関するインベントリメタデータを収集できます。

YAML
--- schemaVersion: '2.2' description: Software Inventory Policy Document. parameters: applications: type: String default: Enabled description: "(Optional) Collect data for installed applications." allowedValues: - Enabled - Disabled awsComponents: type: String default: Enabled description: "(Optional) Collect data for AWS Components like amazon-ssm-agent." allowedValues: - Enabled - Disabled networkConfig: type: String default: Enabled description: "(Optional) Collect data for Network configurations." allowedValues: - Enabled - Disabled windowsUpdates: type: String default: Enabled description: "(Optional) Collect data for all Windows Updates." allowedValues: - Enabled - Disabled instanceDetailedInformation: type: String default: Enabled description: "(Optional) Collect additional information about the instance, including the CPU model, speed, and the number of cores, to name a few." allowedValues: - Enabled - Disabled customInventory: type: String default: Enabled description: "(Optional) Collect data for custom inventory." allowedValues: - Enabled - Disabled mainSteps: - action: aws:softwareInventory name: collectSoftwareInventoryItems inputs: applications: "{{ applications }}" awsComponents: "{{ awsComponents }}" networkConfig: "{{ networkConfig }}" windowsUpdates: "{{ windowsUpdates }}" instanceDetailedInformation: "{{ instanceDetailedInformation }}" customInventory: "{{ customInventory }}"
JSON
{ "schemaVersion": "2.2", "description": "Software Inventory Policy Document.", "parameters": { "applications": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for installed applications.", "allowedValues": [ "Enabled", "Disabled" ] }, "awsComponents": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.", "allowedValues": [ "Enabled", "Disabled" ] }, "networkConfig": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for Network configurations.", "allowedValues": [ "Enabled", "Disabled" ] }, "windowsUpdates": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for all Windows Updates.", "allowedValues": [ "Enabled", "Disabled" ] }, "instanceDetailedInformation": { "type": "String", "default": "Enabled", "description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.", "allowedValues": [ "Enabled", "Disabled" ] }, "customInventory": { "type": "String", "default": "Enabled", "description": "(Optional) Collect data for custom inventory.", "allowedValues": [ "Enabled", "Disabled" ] } }, "mainSteps": [ { "action": "aws:softwareInventory", "name": "collectSoftwareInventoryItems", "inputs": { "applications": "{{ applications }}", "awsComponents": "{{ awsComponents }}", "networkConfig": "{{ networkConfig }}", "windowsUpdates": "{{ windowsUpdates }}", "instanceDetailedInformation": "{{ instanceDetailedInformation }}", "customInventory": "{{ customInventory }}" } } ] }

スキーマバージョン 2.2 AWS-ConfigureAWSPackage の例

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

注記

Linux オペレーティングシステムでは、AWSSupport-EC2Rescue パッケージ、および AmazonCloudWatchAgent パッケージのみがサポートされています。

YAML
--- schemaVersion: '2.2' description: 'Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.' 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 allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$" version: type: String 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." default: latest mainSteps: - action: aws:configurePackage name: configurePackage inputs: name: "{{ name }}" action: "{{ action }}" version: "{{ version }}"
JSON
{ "schemaVersion": "2.2", "description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.", "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", "allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$" }, "version": { "type": "String", "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.", "default": "latest" } }, "mainSteps":[ { "action": "aws:configurePackage", "name": "configurePackage", "inputs": { "name": "{{ name }}", "action": "{{ action }}", "version": "{{ version }}" } } ] }

スキーマバージョン 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 のオートメーションドキュメントの最上位要素を JSON 形式で示します。

{ "description": "document-description", "schemaVersion": "0.3", "assumeRole": "{{assumeRole}}", "parameters": { "parameter-1": { "type": "String", "description": "parameter-1-description", "default": "" }, { "parameter-2": { "type": "String", "description": "parameter-2-description", "default": "" } }, "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 オートメーションドキュメントの例

次の例では、オートメーションドキュメントの内容を YAML 形式で示します。このバージョン 0.3 のドキュメントスキーマの実例では、Markdown を使用してドキュメントの説明をフォーマットする方法も示しています。

description: >- ##Title: LaunchInstanceAndCheckState ----- **Purpose**: This Automation document 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.6 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.6 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