• AWS Systems Manager CloudWatch ダッシュボードは、2026 年 4 月 30 日以降は利用できなくなります。お客様は、これまでと同様に Amazon CloudWatch コンソールを使用して、Amazon CloudWatch ダッシュボードの表示、作成、管理を継続できます。詳細については、「[Amazon CloudWatch ダッシュボードのドキュメント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)」を参照してください。
# スキーマ、機能、および例
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 の古いバージョン向けにフォールバックロジックを含めます。
+ **特殊文字をエスケープする** - コマンドにパラメータ値を使用するときは、特殊文字を適切にエスケープして、シェルによる解釈を防ぎます。
+ **パラメータスコープを制限する** - ユースケースには、できる限り制限の厳しいパラメータパターンを使用します。