• AWS Systems Manager CloudWatch ダッシュボードは、2026 年 4 月 30 日以降は利用できなくなります。お客様は、これまでと同様に Amazon CloudWatch コンソールを使用して、Amazon CloudWatch ダッシュボードの表示、作成、管理を継続できます。詳細については、「[Amazon CloudWatch ダッシュボードのドキュメント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)」を参照してください。
# ドキュメントコンポーネント
このセクションには、SSM ドキュメントを構成するコンポーネントに関する情報が含まれます。
**Topics**
+ [スキーマ、機能、および例](documents-schemas-features.md)
+ [データ要素とパラメータ](documents-syntax-data-elements-parameters.md)
+ [コマンドドキュメントプラグインリファレンス](documents-command-ssm-plugin-reference.md)
# スキーマ、機能、および例
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` ドキュメントスキーマの詳細については、「[セッションドキュメントスキーマ](session-manager-schema.md)」を参照してください。
`Command` および `Policy` ドキュメントで最新バージョンのスキーマを使用することで、次の機能を利用できます。
**スキーマバージョン 2.2 ドキュメントの機能**
| 機能 | 詳細 |
| --- | --- |
| ドキュメントの編集 | ドキュメントは更新可能になりました。バージョン 1.2 では、ドキュメントを更新した場合に別の名前で保存する必要がありました。 |
| バージョンの自動管理 | ドキュメントを更新すると新しいバージョンが作成されます。これはスキーマのバージョンではなく、ドキュメントのバージョンです。 |
| デフォルトバージョン | ドキュメントに複数のバージョンがある場合、どのバージョンがデフォルトのドキュメントかを指定できます。 |
| 順序付け | ドキュメントのプラグインまたは*ステップ*を指定した順序で実行します。 |
| クロスプラットフォームのサポート | クロスプラットフォームをサポートすることで、同じ SSM ドキュメント内で異なるプラグインに異なるオペレーティングシステムを指定できます。クロスプラットフォームのサポートはステップ内の `precondition` パラメータを使用します。 |
| パラメータ補間 | 補間とは、文字列に変数値を挿入または置換することを意味します。文字列を使用する前に、実際の値で空白を埋めるものと考えてください。SSM ドキュメントのコンテキストでは、パラメータ補間により、コマンドを実行する前に文字列パラメータを環境変数に対して補間することができるため、コマンドインジェクションに対するセキュリティを高めることができます。`ENV_VAR` に設定すると、エージェントは、パラメータの値を含む `SSM_parameter-name` という名前の環境変数を作成します。 |
**注記**
新しい Systems Manager 機能および SSM ドキュメント機能を使用するには、インスタンスの AWS Systems Manager SSM Agent を常に最新バージョンに更新しておく必要があります。詳細については、「[Run Command を使用して SSM Agent を更新する](run-command-tutorial-update-software.md#rc-console-agentexample)」を参照してください。
次の表はスキーマのメジャーバージョン間の相違点の一覧です。
****
| バージョン 1.2 | バージョン 2.2 (最新バージョン) | 詳細 |
| --- | --- | --- |
| runtimeConfig | mainSteps | バージョン 2.2 では、`mainSteps` の代わりに `runtimeConfig` セクションを使用します。`mainSteps` セクションでは、Systems Manager でステップを順番に実行できます。 |
| プロパティ | inputs | バージョン 2.2 では、`inputs` セクションの代わりに `properties` セクションを使用します。`inputs` セクションは、ステップのパラメータを受け入れます。 |
| commands | runCommand | バージョン 2.2 では、`inputs` セクションは `runCommand` パラメータを使用します。`commands` パラメータは使用しません。 |
| id | action | バージョン 2.2 では、`Action` の代わりに `ID` を使用します。これは名前のみの変更です。 |
| 該当なし | name | バージョン 2.2 では、`name` はステップの任意のユーザー定義名です。 |
**前提条件パラメータを使用する**
スキーマバージョン 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 ドキュメントの最上位要素を示しています。
------
#### [ 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"
allowedValues:
- "Hello World"
mainSteps:
- action: "aws:runPowerShellScript"
name: "example"
inputs:
timeoutSeconds: '60'
runCommand:
- "Write-Output {{Message}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Example document",
"parameters": {
"Message": {
"type": "String",
"description": "Example parameter",
"default": "Hello World",
"allowedValues": ["Hello World"]
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "example",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"Write-Output {{Message}}"
]
}
}
]
}
```
------
**スキーマバージョン 2.2 の precondition パラメータ例**
スキーマバージョン 2.2 ではクロスプラットフォームのサポートを提供します。つまり、単一の SSM ドキュメント内で異なるプラグインに異なるオペレーティングシステムを指定できます。クロスプラットフォームのサポートは、次の例のようにステップ内で `precondition`パラメータを使用します。`precondition` パラメータは、SSM ドキュメントで定義した入力パラメータの検証にも使用できます。これは、次の例の 2 番目にあります。
------
#### [ 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"
]
}
}
]
}
```
------
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
parameters:
action:
type: String
allowedValues:
- Install
- Uninstall
confirmed:
type: String
allowedValues:
- True
- False
mainSteps:
- action: aws:runShellScript
name: InstallAwsCLI
precondition:
StringEquals:
- "{{ action }}"
- "Install"
inputs:
runCommand:
- sudo apt install aws-cli
- action: aws:runShellScript
name: UninstallAwsCLI
precondition:
StringEquals:
- "{{ action }} {{ confirmed }}"
- "Uninstall True"
inputs:
runCommand:
- sudo apt remove aws-cli
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"parameters": {
"action": {
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"confirmed": {
"type": "String",
"allowedValues": [
true,
false
]
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "InstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }}",
"Install"
]
},
"inputs": {
"runCommand": [
"sudo apt install aws-cli"
]
}
},
{
"action": "aws:runShellScript",
"name": "UninstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }} {{ confirmed }}",
"Uninstall True"
]
},
"inputs": {
"runCommand": [
"sudo apt remove aws-cli"
]
}
}
]
}
```
------
**SSM Agent のバージョンが 3.3.2746.0 より前である、スキーマバージョン 2.2 補間の例**
バージョンが 3.3.2746.0 より前である SSM Agent では、エージェントは `interpolationType` パラメータを無視し、代わりに raw 文字列の置換を実行します。`SSM_parameter-name` を明示的に参照する場合は、これを明示的に設定する必要があります。次の Linux の例では、`SSM_Message` 環境変数が明示的に参照されています。
```
{
"schemaVersion": "2.2",
"description": "An example document",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern: "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**注記**
SSM ドキュメントが二重中括弧 `{{ }}` を使用していない場合、`allowedPattern` は理論的には必要ありません。
**スキーマバージョン 2.2 State Manager の例**
Systems Manager のツールである State Manager で以下の SSM ドキュメントを使用すると、ClamAV のウイルス対策ソフトウェアをダウンロードしてインストールできます。State Manager によって特定の設定が適用されます。つまり、State Manager 関連付けが実行されるごとに、ClamAV ソフトウェアがインストールされているかが、システムによってチェックされます。インストールされていない場合には、State Manager はこのドキュメントを返します。
------
#### [ 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 インベントリの例**
State Manager で以下の 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` セクションの `aws:configurePackage` ステップには `action` プラグインが含まれています。
**注記**
Linux オペレーティングシステムでは、`AmazonCloudWatchAgent` パッケージ、および `AWSSupport-EC2Rescue` パッケージのみがサポートされています。
------
#### [ 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."
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."
}
},
"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 の 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/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
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.11
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.11
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
```
## 安全なパラメータ処理の例
ここでは、環境変数 `interpolationType` を使用した安全なパラメータ処理の例を紹介します。
### 基本的なセキュアコマンドの実行
この例は、コマンドパラメータを安全に処理する方法を示しています。
**注記**
SSM ドキュメントが二重中括弧 `{{ }}` を使用していない場合、`allowedPattern` は理論的には必要ありません。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: An example document.
parameters:
Message:
type: String
description: "Message to be printed"
default: Hello
interpolationType: ENV_VAR
allowedPattern: "^[^"]*$"
mainSteps:
- action: aws:runShellScript
name: printMessage
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- echo {{Message}}
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition": {
"StringEquals": ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}]
}
```
------
### インタプリタ型言語でのパラメータの使用
この例は、Python での安全なパラメータ処理を示しています。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### 下位互換性の例
この例は、下位互換性を保ちながらパラメータを安全に処理する方法を示しています。
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**注記**
SSM ドキュメントが二重中括弧 `{{ }}` を使用していない場合、`allowedPattern` は理論的には必要ありません。
## パラメータのセキュリティベストプラクティス
SSM ドキュメントでパラメータを処理するときは、次のベストプラクティスに従います。
+ **環境変数補間を使用する** - コマンド実行に使用する文字列パラメータには、常に `interpolationType: "ENV_VAR"` を使用します。
+ **入力検証を実装する** - `allowedPattern` を使用して、パラメータ値を安全なパターンに制限します。
+ **レガシーシステムを処理する** - 環境変数補間をサポートしていない SSM Agent の古いバージョン向けにフォールバックロジックを含めます。
+ **特殊文字をエスケープする** - コマンドにパラメータ値を使用するときは、特殊文字を適切にエスケープして、シェルによる解釈を防ぎます。
+ **パラメータスコープを制限する** - ユースケースには、できる限り制限の厳しいパラメータパターンを使用します。
# データ要素とパラメータ
このトピックでは、SSM ドキュメントで使用されるデータ要素について説明します。ドキュメントの作成に使用されるスキーマのバージョンは、ドキュメントで使用できる構文とデータ要素を定義します。コマンドドキュメントには、スキーマバージョン 2.2 以降を使用することをお勧めします。Automation ランブックはスキーマバージョン 0.3 を使用します。さらに、Automation ランブックでは、マークアップ言語である Markdown の使用がサポートされています。これにより、wiki スタイルの説明をドキュメントやドキュメント内の個々のステップに追加できます。Markdown の使用に関する詳細については、「AWS マネジメントコンソール 入門ガイド」の「[コンソールでの Markdown の使用](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html)」を参照してください。
次のセクションでは、SSM ドキュメントに含めることができるデータ要素について説明します。
## 最上位のデータ要素
**schemaVersion**
使用するスキーマバージョン。
型: バージョン
必須: はい
**description**
ドキュメントの目的を説明するために提供する情報。またこのフィールドを使用して、ドキュメントの実行にパラメータの値が必要か否か、またはパラメータの値の指定が任意か否かを指定することもできます。必須と任意のパラメータはこのトピックのサンプルをご参照ください。
タイプ: 文字列
必須: いいえ
**パラメータ**
ドキュメントが許可するパラメータを定義する構造。
文字列パラメータを処理する際のセキュリティを強化するには、`interpolationType` プロパティを指定して環境変数補間を使用します。`ENV_VAR` に設定すると、システムは、パラメータの値を含む `SSM_parameter-name` という名前の環境変数を作成します。
次は、環境変数 `interpolationType` を使用するパラメータの例です。
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition" : {
"StringEquals" : ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}
}
```
SSM ドキュメントが二重中括弧 `{{ }}` を使用していない場合、`allowedPattern` は理論的には必要ありません。
頻繁に使用するパラメータの場合は、そのパラメータを AWS Systems Manager のツールである Parameter Store に保存することをお勧めします。次に、デフォルト値として Parameter Store パラメータを参照するパラメータをドキュメントで定義できます。Parameter Store パラメータを参照するには、次の構文を使用します。
```
{{ssm:parameter-name}}
```
他のドキュメントパラメータと同じ方法で、Parameter Store パラメータを参照するパラメータを使用できます。次の例では、`commands` パラメータのデフォルト値は Parameter Store パラメータ `myShellCommands` です。`commands` パラメータを `runCommand` 文字列として指定すると、ドキュメントは `myShellCommands` パラメータに格納されているコマンドを実行します。
```
---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
commands:
type: StringList
description: "(Required) The commands to run on the instance."
default: ["{{ ssm:myShellCommands }}"],
interpolationType : 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: runShellScriptDefaultParams
inputs:
runCommand:"{{ commands }}"
```
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScriptDefaultParams",
"inputs": {
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
`String` および `StringList` Parameter Store パラメータは、ドキュメントの `parameters` セクションで参照できます。`SecureString` Parameter Store パラメータは参照できません。
の詳細については、「Parameter Store」を参照してください。[AWS Systems Manager Parameter Store](systems-manager-parameter-store.md)
型: 構造
`parameters`構造は次のフィールドと値を受け入れます。
+ `type`: (必須) その値として `String`、`StringList`、`Integer`、`Boolean`、`MapList`、`StringMap` を使用できます。各タイプの例を表示するには、次のセクションの「[SSM ドキュメントパラメータ `type` の例](#top-level-properties-type)」を参照してください。
**注記**
コマンドタイプのドキュメントでは、`String` および `StringList` パラメータタイプのみがサポートされます。
+ `description`: (オプション) パラメータグループの説明。
+ `default`: (オプション) Parameter Store でのパラメータのデフォルト値またはパラメータへの参照。
+ `allowedValues`: (オプション) パラメータに使用できる値の配列。パラメータに使用できる値を定義すると、ユーザー入力が検証されます。使用できない値をユーザーが入力すると、実行の開始に失敗します。
------
#### [ YAML ]
```
DirectoryType:
type: String
description: "(Required) The directory type to launch."
default: AwsMad
allowedValues:
- AdConnector
- AwsMad
- SimpleAd
```
------
#### [ JSON ]
```
"DirectoryType": {
"type": "String",
"description": "(Required) The directory type to launch.",
"default": "AwsMad",
"allowedValues": [
"AdConnector",
"AwsMad",
"SimpleAd"
]
}
```
------
+ `allowedPattern`: (オプション) ユーザー入力がパラメータに対して定義されたパターンと一致するかどうかを検証する正規表現。ユーザー入力が使用できるパターンと一致しない場合、実行は開始されません。
**注記**
Systems Manager は、`allowedPattern` について 2 つの検証を実行します。1 つ目の検証は、ドキュメントを使用するときに API レベルで [Java 正規表現ライブラリ](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html)を使用して実行されます。2 つ目の検証は、ドキュメントを処理する前に [GO regexp ライブラリ](https://pkg.go.dev/regexp)を使用して SSM Agent に対して実行されます。
------
#### [ YAML ]
```
InstanceId:
type: String
description: "(Required) The instance ID to target."
allowedPattern: "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$"
default: ''
```
------
#### [ JSON ]
```
"InstanceId": {
"type": "String",
"description": "(Required) The instance ID to target.",
"allowedPattern": "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$",
"default": ""
}
```
------
+ `displayType`: (オプション) `textfield` の `textarea` または AWS マネジメントコンソール のいずれかを表示するために使用されます。`textfield` は、1 行のテキストボックスで、`textarea` は、複数行のテキストエリアです。
+ `minItems`: (オプション) 許可される項目の最小数。
+ `maxItems`: (オプション) 許可される項目の最大数。
+ `minChars`: (オプション) 許可される項目の最小数。
+ `maxChars`: (オプション) を許可されているパラメータ文字の最大数。
+ `interpolationType`: (オプション) コマンドを実行する前にパラメータ値をどのように処理するかを定義します。`ENV_VAR` に設定すると、パラメータ値は `SSM_parameter-name` という名前の環境変数として使用できるようになります。この機能を使うと、パラメータ値をリテラル文字列として処理することによりコマンドインジェクションを防げるようになります。
型: 文字列
有効な値: `ENV_VAR`
必須：いいえ
**variables**
(スキーマバージョン 0.3 のみ) 自動化ランブックのステップ全体で参照または更新できる値。変数はパラメーターと似ていますが、非常に重要な点において異なります。パラメーター値はランブックのコンテキストでは静的ですが、変数の値はランブックのコンテキストでは変更できます。変数の値を更新する場合、データ型は定義されたデータ型と一致する必要があります。オートメーションの変数値の更新に関する詳細は、「[`aws:updateVariable` — ランブック変数の値を更新します。](automation-action-update-variable.md)」を参照してください。
型: ブール値｜整数｜マップリスト｜文字列｜文字列リスト｜文字列マップ
必須: いいえ
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"variables": [
"payload": {
"type": "StringMap",
"default": "{}"
}
]
}
```
**runtimeConfig**
(スキーマバージョン 1.2 のみ) 1 つ以上の Systems Manager プラグインによって適用されるインスタンスの構成。プラグインは必ずしも順番に実行されるとは限りません。
型: Dictionary
必須: いいえ
**mainSteps**
(スキーマバージョン 0.3、2.0、および 2.2 のみ) 複数のステップ (プラグイン) を含むことができるオブジェクト。プラグインはステップ内で定義されます。ステップは、ドキュメントに記載されている順番に実行されます。
型: Dictionary
必須: はい
**出力**
(スキーマバージョン 0.3 のみ) このドキュメントの実行によって生成され、他のプロセスで使用できるデータ。例えば、ドキュメントで新しい AMI を作成する場合、出力値として「CreateImage.ImageId」を指定すると、この出力を使用して後続のオートメーションの実行から新しいインスタンスを作成できます。出力の詳細については、「[アクション出力の入力としての使用](automation-action-outputs-inputs.md)」を参照してください。
型: Dictionary
必須: いいえ
**files**
(スキーマバージョン 0.3 のみ) ドキュメントに添付され、自動実行時に実行されるスクリプトファイル (およびそのチェックサム)。`aws:executeScript` アクションを含むドキュメントのうち、添付ファイルが 1 つ以上のステップに指定されているもののみに適用されます。
オートメーションランブックでサポートされているランタイムについては、「[`aws:executeScript` – スクリプトを実行する](automation-action-executeScript.md)」を参照してください。Automation ランブックにスクリプトを含める方法の詳細については、「[ランブックでのスクリプトの使用](automation-document-script-considerations.md)」および「[オートメーションランブックのビジュアルデザインエクスペリエンス](automation-visual-designer.md)」を参照してください。
アタッチメントの付いたオートメーションランブックを作成するときは、`--attachments` オプション (AWS CLI の場合) または `Attachments` (API および SDK の場合) を使用して添付ファイルを指定する必要があります。SSM ドキュメントと、Amazon Simple Storage Service (Amazon S3) バケット内に保存されているファイルの両方で、ファイルの場所を指定できます。詳細については、「AWS Systems Manager API リファレンス」の「[Attachments](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments)」(アタッチメント) を参照してください。
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
型: Dictionary
必須: いいえ
## SSM ドキュメントパラメータ `type` の例
SSM ドキュメント内のパラメータのデータ型は静的です。つまり、パラメータのデータ型は定義後に変更することはできません。SSM ドキュメントプラグインでパラメータを使用する場合、パラメータのデータ型をプラグインの入力内で動的に変更することはできません。例えば、`Integer` プラグインの `runCommand` 入力内の `aws:runShellScript` パラメータを参照することはできません。この入力は文字列または文字列のリストを受け入れるためです。プラグインの入力にパラメータを使用するには、パラメータのデータ型が、入力の受け入れ可能なデータ型と一致している必要があります。例えば、`Boolean` プラグインの `allowDowngrade` 入力には `aws:updateSsmAgent` 型のパラメータを指定する必要があります。パラメータのデータ型がプラグインの入力のデータ型と一致しない場合、SSM ドキュメントの検証は失敗となり、システムによってドキュメントは作成されません。これは、他のプラグイン、もしくは AWS Systems Manager のオートメーションアクション用に、入力内にある下流のパラメータを使用する場合にも当てはまります。例えば、`aws:runDocument` プラグインの `documentParameters` 入力にある `StringList` パラメータを参照することはできません。ダウンストリーム SSM ドキュメントパラメータのタイプが `StringList` パラメータで、かつ参照しようとしているパラメータと一致する場合でも、`documentParameters` 入力は、文字列へのマッピングを受け入れます。
オートメーションアクションでパラメータを使用するときは、ほとんどの場合、SSM ドキュメントを作成するときにパラメータのデータ型は検証されません。`aws:runCommand` アクションを使用する場合にのみ、SSM ドキュメントを作成するときにパラメータのデータ型が検証されます。それ以外の場合、オートメーションの実行中、アクションが実行される前にその入力が検証されるときに、パラメータが検証されます。例えば、入力パラメータが `String` であり、それを `MaxInstanceCount` アクションの `aws:runInstances` 入力の値として参照する場合は、SSM ドキュメントが作成されます。ただし、ドキュメントを実行すると、`aws:runInstances` アクションの検証中にオートメーションは失敗します。`MaxInstanceCount` 入力に `Integer` が必要なためです。
以下に示しているのは、各パラメータ `type` の例です。
文字列
引用符で囲んだ 0 個以上の Unicode 文字のシーケンス。例えば、"i-1234567890abcdef0" など。バックスラッシュを使用してエスケープします。
文字列パラメータには、セキュリティを高めるために環境変数補間を有効にする値 `ENV_VAR` を持つ、オプションの `interpolationType` フィールドを含めることができます。
```
---
InstanceId:
type: String
description: "(Optional) The target EC2 instance ID."
interpolationType: ENV_VAR
```
```
"InstanceId":{
"type":"String",
"description":"(Optional) The target EC2 instance ID.",
"interpolationType": "ENV_VAR"
}
```
StringList
カンマ区切りの文字列項目のリスト。例えば、["cd \$1", "pwd"] など。
```
---
commands:
type: StringList
description: "(Required) Specify a shell script or a command to run."
default: ""
minItems: 1
displayType: textarea
```
```
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
```
Boolean
`true` または `false` のみを使用できます。"true" または 0 は使用できません。
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"canRun": {
"type": "Boolean",
"description": "",
"default": true
}
```
整数
整数。小数 (3.14159 など) や引用符で囲んだ数字 ("3" など) は使用できません。
```
---
timeout:
type: Integer
description: The type of action to perform.
default: 100
```
```
"timeout": {
"type": "Integer",
"description": "The type of action to perform.",
"default": 100
}
```
StringMap
キーと値のマッピング。キーと値は文字列でなければなりません。例えば、\$1"Env": "Prod"\$1 など。
```
---
notificationConfig:
type: StringMap
description: The configuration for events to be notified about
default:
NotificationType: 'Command'
NotificationEvents:
- 'Failed'
NotificationArn: "$dependency.topicArn"
maxChars: 150
```
```
"notificationConfig" : {
"type" : "StringMap",
"description" : "The configuration for events to be notified about",
"default" : {
"NotificationType" : "Command",
"NotificationEvents" : ["Failed"],
"NotificationArn" : "$dependency.topicArn"
},
"maxChars" : 150
}
```
MapList
StringMap オブジェクトのリスト。
```
blockDeviceMappings:
type: MapList
description: The mappings for the create image inputs
default:
- DeviceName: "/dev/sda1"
Ebs:
VolumeSize: "50"
- DeviceName: "/dev/sdm"
Ebs:
VolumeSize: "100"
maxItems: 2
```
```
"blockDeviceMappings":{
"type":"MapList",
"description":"The mappings for the create image inputs",
"default":[
{
"DeviceName":"/dev/sda1",
"Ebs":{
"VolumeSize":"50"
}
},
{
"DeviceName":"/dev/sdm",
"Ebs":{
"VolumeSize":"100"
}
}
],
"maxItems":2
}
```
## SSM コマンドドキュメントの内容の表示
AWS Systems Manager (SSM) コマンドドキュメントの必須パラメータとオプションのパラメータ、およびドキュメントが実行するアクションをプレビューするには、Systems Manager コンソールでドキュメントのコンテンツを表示できます。
**SSM コマンドドキュメントの内容を表示するには**
1. AWS Systems Manager コンソール ([https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/)) を開きます。
1. ナビゲーションペインで、**[ドキュメント]** を選択します。
1. 検索ボックスで、[**ドキュメントのタイプ**] を選択し、[**コマンド**] を選択します。
1. ドキュメントの名前を選択し、[**コンテンツ**] タブをクリックします。
1. [コンテンツ] フィールドで、ドキュメントで使用できるパラメータとアクションステップを確認します。
例えば、次の図は、(1) `version` と (2) `allowDowngrade` が `AWS-UpdateSSMAgent` ドキュメントのオプションのパラメータで、ドキュメントによって実行される最初のアクションが (3) `aws:updateSsmAgent` であることを示しています。
![\[Systems Manager コンソールで SSM ドキュメントの内容を表示する\]](http://docs.aws.amazon.com/ja_jp/systems-manager/latest/userguide/images/view-document-content.png)
# コマンドドキュメントプラグインリファレンス
このリファレンスでは、AWS Systems Manager (SSM) コマンドドキュメントで指定できるプラグインが説明されています。これらのプラグインは、オートメーションアクションを使用する SSM オートメーションランブックでは使用できません。AWS Systems Manager Automation アクションについては、「[Systems Manager Automation アクションのリファレンス](automation-actions.md)」を参照してください。
Systems Manager は、SSM ドキュメントの内容を読み取ることによって、マネージドインスタンスで実行するアクションを判別します。各ドキュメントにはコード実行セクションが含まれています。ドキュメントのスキーマバージョンに応じて、このコード実行セクションには 1 つ以上のプラグインまたはステップが含まれます。このヘルプトピックの目的上、プラグインとステップは*プラグイン*と呼んでいます。このセクションには、各 Systems Manager プラグインに関して説明します。ドキュメントの作成に関する情報やスキーマのバージョンの違いなど、ドキュメントの詳細については、「[AWS Systems Manager ドキュメント](documents.md)」を参照してください。
`aws:runShellScript` や `aws:runPowerShellScript` などの文字列パラメータを受け入れるプラグインの場合、`interpolationType` パラメータを使用して、パラメータ入力を潜在的に実行可能なコマンドではなく文字列リテラルとして処理することにより、セキュリティを高めることができます。例えば、次のようになります。
```
{
"schemaVersion": "2.2",
"description": "runShellScript with command strings stored as Parameter Store parameter",
"parameters": {
"commands": {
"type": "StringList",
"description": "(Required) The commands to run on the instance.",
"default": ["{{ ssm:myShellCommands }}"],
"interpolationType" : "ENV_VAR"
}
},
//truncated
}
```
**注記**
ここで説明するプラグインの中には、Windows Server インスタンスまたは Linux インスタンスのいずれかでのみ実行されるものがあります。各プラグインにはプラットフォームの依存関係が記載されています。
macOS 向けの Amazon Elastic Compute Cloud (Amazon EC2) インスタンスでは、以下のドキュメントプラグインがサポートされています。
`aws:refreshAssociation`
`aws:runShellScript`
`aws:runPowerShellScript`
`aws:softwareInventory`
`aws:updateSsmAgent`
**Topics**
+ [共有入力](#shared-inputs)
+ [`aws:applications`](#aws-applications)
+ [`aws:cloudWatch`](#aws-cloudWatch)
+ [`aws:configureDocker`](#aws-configuredocker)
+ [`aws:configurePackage`](#aws-configurepackage)
+ [`aws:domainJoin`](#aws-domainJoin)
+ [`aws:downloadContent`](#aws-downloadContent)
+ [`aws:psModule`](#aws-psModule)
+ [`aws:refreshAssociation`](#aws-refreshassociation)
+ [`aws:runDockerAction`](#aws-rundockeraction)
+ [`aws:runDocument`](#aws-rundocument)
+ [`aws:runPowerShellScript`](#aws-runPowerShellScript)
+ [`aws:runShellScript`](#aws-runShellScript)
+ [`aws:softwareInventory`](#aws-softwareinventory)
+ [`aws:updateAgent`](#aws-updateagent)
+ [`aws:updateSsmAgent`](#aws-updatessmagent)
## 共有入力
あらゆるプラグインが以下の入力を使用できるのは、SSM Agent バージョン 3.0.502 以降のみです。
**finallyStep**
ドキュメントに実行させる最後のステップです。この入力がステップに定義されている場合、`exit` または `onFailure` 入力で指定されている `onSuccess` 値よりもこれが優先されます。この入力が定義されたステップを期待どおりに実行するには、このステップをドキュメントの `mainSteps` で定義されている最後のステップにする必要があります。
タイプ: ブール値
有効な値: `true` \$1 `false`
必須: いいえ
**onFailure**
`exit` 値を使用するプラグインにこの入力を指定して、ステップが失敗した場合は、ステップのステータスにこの障害が反映され、`finallyStep` が定義されない限り、ドキュメントは残りのステップを実行しません。`successAndExit` 値を使用するプラグインにこの入力を値で指定して、ステップが失敗した場合は、ステップのステータスが成功になり、`finallyStep` が定義されない限り、ドキュメントは残りのステップを実行しません。
型: 文字列
有効な値: `exit` \$1 `successAndExit`
必須: いいえ
**onSuccess**
プラグインにこの入力を指定し、ステップが正常に実行した場合、`finallyStep` が定義されている場合を除き、ドキュメントは残りのステップを実行しません。
型: 文字列
有効な値: `exit`
必須: いいえ
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Shared inputs example
parameters:
customDocumentParameter:
type: String
description: Example parameter for a custom Command-type document.
mainSteps:
- action: aws:runDocument
name: runCustomConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomDocument"
documentParameters: '"documentParameter":{{customDocumentParameter}}'
onSuccess: exit
- action: aws:runDocument
name: ifConfigurationFailure
inputs:
documentType: SSMDocument
documentPath: "yourCustomRepairDocument"
onFailure: exit
- action: aws:runDocument
name: finalConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomFinalDocument"
finallyStep: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Shared inputs example",
"parameters": {
"customDocumentParameter": {
"type": "String",
"description": "Example parameter for a custom Command-type document."
}
},
"mainSteps":[
{
"action": "aws:runDocument",
"name": "runCustomConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomDocument",
"documentParameters": "\"documentParameter\":{{customDocumentParameter}}",
"onSuccess": "exit"
}
},
{
"action": "aws:runDocument",
"name": "ifConfigurationFailure",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomRepairDocument",
"onFailure": "exit"
}
},
{
"action": "aws:runDocument",
"name":"finalConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomFinalDocument",
"finallyStep": true
}
}
]
}
```
------
## `aws:applications`
EC2 インスタンスでアプリケーションをインストール、修復、またはアンインストールします。このプラグインは、Windows Server オペレーティングシステムでのみ実行されます。
### 構文
#### スキーマ 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:applications plugin
parameters:
source:
description: "(Required) Source of msi."
type: String
mainSteps:
- action: aws:applications
name: example
inputs:
action: Install
source: "{{ source }}"
```
------
#### [ JSON ]
```
{
"schemaVersion":"2.2",
"description":"aws:applications",
"parameters":{
"source":{
"description":"(Required) Source of msi.",
"type":"String"
}
},
"mainSteps":[
{
"action":"aws:applications",
"name":"example",
"inputs":{
"action":"Install",
"source":"{{ source }}"
}
}
]
}
```
------
#### スキーマ 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:applications:
properties:
- id: 0.aws:applications
action: "{{ action }}"
parameters: "{{ parameters }}"
source: "{{ source }}"
sourceHash: "{{ sourceHash }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:applications":{
"properties":[
{
"id":"0.aws:applications",
"action":"{{ action }}",
"parameters":"{{ parameters }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}"
}
]
}
}
}
```
------
### プロパティ
**action**
取るべきアクション｡
タイプ: Enum
有効な値: `Install` \$1 `Repair` \$1 `Uninstall`
必須: はい
**パラメータ**
インストーラのパラメータ。
型: 文字列
必須: いいえ
**source**
アプリケーションの `.msi` ファイルの URL。
型: 文字列
必須: はい
**sourceHash**
`.msi` ファイルの SHA256 ハッシュ。
型: 文字列
必須: いいえ
## `aws:cloudWatch`
Windows Server から Amazon CloudWatch または Amazon CloudWatch Logs にデータをエクスポートし、CloudWatch メトリクスを使用してデータをモニタリングします。このプラグインは、Windows Server オペレーティングシステムでのみ実行されます。Amazon Elastic Compute Cloud (Amazon EC2) との CloudWatch 統合の設定の詳細については、「Amazon CloudWatch ユーザーガイド」の「[CloudWatch エージェントを使用したメトリクス、ログ、トレースの収集](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)」を参照してください。
**重要**
CloudWatch の統合エージェントによって、ログデータを Amazon CloudWatch Logs に送信するためのツールとして SSM Agent が置き換えられました。SSM Agent aws:cloudWatch プラグインはサポートされていません。ログ収集プロセスには、統合された CloudWatch エージェントのみを使用することをお勧めします。詳細については、以下の各トピックを参照してください。
[統合された CloudWatch Logs へのノードログの送信 (CloudWatch エージェント)](monitoring-cloudwatch-agent.md)
[Windows Server ノードのログ収集を CloudWatch エージェントに移行する](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate)
「Amazon CloudWatch ユーザーガイド」の「[CloudWatch エージェントを使用してメトリクス、ログ、トレースを収集する](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)」。
次のデータ型をエクスポートおよび監視できます。
**ApplicationEventLog**
アプリケーションイベントログデータを CloudWatch Logs に送信します。
**CustomLogs**
テキストベースのログファイルを Amazon CloudWatch Logs に送信します｡ CloudWatch プラグインは、ログファイルのフィンガープリントを作成します。次に、システムは各フィンガープリントにデータオフセットを関連付けます。プラグインは、変更があったときにファイルをアップロードし、オフセットを記録し、オフセットをフィンガープリントに関連付けます。この方法は、ユーザーがプラグインを有効にし、多数のファイルを含むディレクトリにサービスを関連付け、システムがすべてのファイルをアップロードすることを避けるために使用されます。
アプリケーションがポーリング中にログをトランケートまたは消去しようとすると、`LogDirectoryPath` で指定されたログではエントリが失われることに注意してください。たとえば、ログファイルのサイズを制限する場合は、その制限に達すると新しいログファイルを作成し、新しいファイルにデータを書き続ける必要があります。
**ETW**
Windows のイベントトレース (ETW) データを CloudWatch Logs に送信します｡
**IIS**
IIS ログデータを CloudWatch Logs に送信します。
**PerformanceCounter**
Windows パフォーマンスカウンターを CloudWatch に送信します｡ メトリクスとして CloudWatch にアップロードするさまざまなカテゴリを選択できます。アップロードするパフォーマンスカウンタごとに、一意の ID (たとえば、「PerformanceCounter2」、「PerformanceCounter3」など) を持つ[**PerformanceCounter**] セクションを作成し、そのプロパティを設定します。
AWS Systems Manager SSM Agent または CloudWatch プラグインが停止した場合、パフォーマンスカウンターのデータは、CloudWatch にログ記録されません。この動作は、カスタムログまたは Windows イベントログとは異なります。SSM Agent または CloudWatch プラグインを使用できる場合、カスタムログと Windows イベントログはパフォーマンスカウンタデータを保持し、CloudWatch にアップロードします。
**SecurityEventLog**
セキュリティイベントログデータを CloudWatch Logs に送信します。
**SystemEventLog**
システムイベントログデータを CloudWatch Logs に送信します。
データの送信先として以下を定義できます。
**CloudWatch**
パフォーマンスカウンターのメトリクスデータの送信先。同じデータを別の場所に送信するには、一意の ID (例: 「CloudWatch2」、「CloudWatch3」) を使用してセクションを追加し、新しい ID ごとに異なるリージョンを指定します。
**CloudWatchLogs**
ログデータの送信先。一意の ID (例: 「CloudWatchLogs2」、「CloudWatchLogs3」) を含むセクションを追加し、新しい ID ごとに異なるリージョンを指定して、同じデータを別の場所に送信できます。
### 構文
```
"runtimeConfig":{
"aws:cloudWatch":{
"settings":{
"startType":"{{ status }}"
},
"properties":"{{ properties }}"
}
}
```
### 設定とプロパティ
**AccessKey**
お客様のアクセスキー ID。IAM ロールを使用してインスタンスを起動しない限り、このプロパティは必須です。このプロパティは SSM では使用できません。
型: 文字列
必須: いいえ
**CategoryName**
パフォーマンスモニターのパフォーマンスカウンタカテゴリ。
型: 文字列
必須: はい
**CounterName**
パフォーマンスモニターのパフォーマンスカウンターの名前。
型: 文字列
必須: はい
**CultureName**
タイムスタンプが記録されるロケール。**CultureName** を空白にした場合は、Windows Server インスタンスで使用されているものと同じロケールになります。
型: 文字列
有効な値: サポートされている値のリストについては、Microsoft ウェブサイトの「[National Language Support (NLS)](https://msdn.microsoft.com/en-us/library/cc233982.aspx)」を参照してください。**div**、**div-MV**、**hu**、および **hu-HU** の値はサポートされません。
必須: いいえ
**DimensionName**
Amazon CloudWatch メトリクスのディメンション。`DimensionName` を指定する場合は、`DimensionValue` を指定する必要があります。これらのパラメータにより、メトリクスが一覧表示される別のビューが表示されます。複数のメトリクスに同じディメンションを使用して、特定のディメンションに属するすべてのメトリクスを表示することができます。
型: 文字列
必須: いいえ
**DimensionValue**
Amazon CloudWatch メトリクスのディメンション値。
型: 文字列
必須: いいえ
**エンコード**
使用するファイルエンコード (たとえば、UTF-8)。表示名ではなく、エンコード名を使用します。
タイプ: 文字列
有効な値: サポートされる値の一覧については、Microsoft Learn Library の「[Encoding クラス](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0)」を参照してください。
必須: はい
**フィルタ**
ログ名のプレフィックス。すべてのファイルをモニタリングするには、このパラメータを空白のままにします。
型: 文字列
有効な値: サポートされる値の一覧については、MSDN ライブラリの「[FileSystemWatcherFilter プロパティ](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx)」を参照してください。
必須: いいえ
**フロー**
アップロードする各データタイプ、およびデータの送信先 (CloudWatch または CloudWatch Logs)。例えば、[`"Id": "PerformanceCounter"`] で定義されたパフォーマンスカウンタを CloudWatch に送信するには、`"Id": "CloudWatch"` で定義された送信先、[**"PerformanceCounter,CloudWatch"**] を入力します。同様に、カスタムログ、ETW ログ、システムログを `"Id": "ETW"` で定義された CloudWatch Logs の送信先に送信するには、「**"(ETW),CloudWatchLogs"**」と入力します。加えて、同じパフォーマンスカウンターまたはログファイルを複数の宛先に送信することもできます。たとえば、アプリケーションログを `"Id": "CloudWatchLogs"` と `"Id": "CloudWatchLogs2"` で定義した 2 つの異なる宛先に送信するには、「**"ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)"**」と入力します。
型: 文字列
有効な値 (ソース): `ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog`
有効な値 (送信先): `CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch`*n* \$1 `CloudWatchLogs`*n*
必須: はい
**FullName**
コンポーネントのフルネーム。
型: 文字列
必須: はい
**ID**
データソースまたは送信先を識別します。この識別子は、設定ファイル内で一意である必要があります。
型: 文字列
必須: はい
**InstanceName**
パフォーマンスカウンターインスタンスの名前。各パフォーマンスカウンターコンポーネントではメトリクスが 1 つしかサポートされないため、アスタリスク (\$1) を使用してすべてのインスタンスを指定しないでください。ただし、**\$1Total** は使用できます。
型: 文字列
必須: はい
**レベル**
Amazon CloudWatch に送信するメッセージのタイプ。
型: 文字列
有効な値:
+ **1** - エラーメッセージだけがアップロードされます。
+ **2** - 警告メッセージだけがアップロードされます。
+ **4** - 情報メッセージだけがアップロードされます。
値を加算すると、複数の種類のメッセージを含めることができます。たとえば、**3** はエラーメッセージ (**1**) と警告メッセージ (**2**) が含まれることを意味します。**7** の値は、エラーメッセージ (**1**)、警告メッセージ (**2**)、情報メッセージ (**4**) が含まれることを意味します。
必須: はい
Windows セキュリティログではレベルを 7 に設定する必要があります。
**LineCount**
ログファイルを識別するヘッダーの行数。たとえば、IIS のログファイルのヘッダーはほぼ同じです。「**3**」と入力すると、ログファイルのヘッダーの最初の 3 行が読み取られ、ログファイルを識別できます。IIS のログファイルでは、3 行目は日付と時刻のタイムスタンプで、ログファイル間で異なります。
タイプ: 整数
必須: いいえ
**LogDirectoryPath**
CustomLogs の場合、EC2 インスタンスにログが保存されるパス。IIS ログの場合、IIS ログが個々のサイト (たとえば、**C:\$1\$1inetpub\$1\$1logs\$1\$1LogFiles\$1\$1W3SVC*n***) に保存されるフォルダ。IIS ログの場合、W3C ログ形式のみがサポートされます。IIS、NCSA、カスタム形式はサポートされません。
型: 文字列
必須: はい
**LogGroup**
ロググループの名前です。この名前は、CloudWatch コンソールの [**ロググループ**] 画面に表示されます。
型: 文字列
必須: はい
**LogName**
ログファイルの名前。
1. ログの名前を検索するには、イベントビューアーのナビゲーションペインで、[**Applications and Services Logs**] を選択します。
1. ログの一覧で、アップロードするログを右クリックし (例えば、[`Microsoft`] > [`Windows`] > [`Backup`] > [`Operational`] など)、**[Create Custom View]** を選択します。
1. [**Create Custom View**] ダイアログボックスの [**XML**] タブを選択します。[**LogName**] は、