SSM ドキュメントの構文 - AWS Systems Manager

SSM ドキュメントの構文

ドキュメントの構文は作成に使用するスキーマのバージョンによって定義されます。コマンドドキュメントには、スキーマバージョン 2.2 以降を使用することをお勧めします。オートメーションドキュメントは、スキーマバージョン 0.3 を使用します。さらに、オートメーションドキュメントでは、マークアップ言語である Markdown の使用がサポートされています。これにより、wiki スタイルの説明をドキュメントやドキュメント内の個々のステップに追加できます。Markdown の使用の詳細については、「AWS での Markdown の使用」を参照してください。

最上位の要素は SSM ドキュメントの構造を提供します。このトピックの情報は Command および Automation SSM ドキュメントに関連しています。

最上位の要素

schemaVersion

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

型: バージョン

必須: はい

description

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

型: 文字列

必須: いいえ

パラメータ

ドキュメントが許可するパラメータを定義する構造。頻繁に参照するパラメータの場合は、そのパラメータを Systems Manager パラメータストア に保存してそこを参照することをお勧めします。String および StringList パラメータストア パラメータは、ドキュメントの本セクションで参照できます。SecureStringパラメータストア パラメータは、ドキュメントの本セクションでは参照できません。詳細については、「AWS Systems Manager パラメータストア」を参照してください。

型: 構造

parameters構造は次のフィールドと値を受け入れます。

  • type: (必須) その値として StringStringListBooleanIntegerMapListStringMap を使用できます。各タイプの例を表示するには、次のセクションの「SSM ドキュメントパラメータ type の例」を参照してください。

  • description: (オプション) パラメータグループの説明。

  • default: (オプション) パラメータストア でのパラメータのデフォルト値またはパラメータへの参照。

  • 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: (オプション) ユーザー入力がパラメータに対して定義されたパターンと一致するかどうかを検証する正規表現。ユーザー入力が使用できるパターンと一致しない場合、実行は開始されません。

    YAML
    InstanceId: type: String description: "(Required) The instance ID to target." allowedPattern: "^i-[a-z0-9]{8,17}$" default: ''
    JSON
    "InstanceId": { "type": "String", "description": "(Required) The instance ID to target.", "allowedPattern": "^i-[a-z0-9]{8,17}$", "default": "" }
  • displayType: (オプション) AWS Management Console の textfield または textarea のいずれかを表示するために使用されます。textfield は、1 行のテキストボックスで、textarea は、複数行のテキストエリアです。

  • minItems: (オプション) 許可される項目の最小数。

  • maxItems: (オプション) 許可される項目の最大数。

  • minChars: (オプション) 許可される項目の最小数。

  • maxChars: (オプション) を許可されているパラメータ文字の最大数。

必須: いいえ

runtimeConfig

(スキーマバージョン 1.2 のみ) 1 つ以上の Systems Manager プラグインによって適用されるインスタンスの構成。プラグインは必ずしも順番に実行されるとは限りません。

型: Dictionary<string,PluginConfiguration>

必須: いいえ

mainSteps

(スキーマバージョン 0.3、2.0、および 2.2 のみ) 複数のステップ (プラグイン) を含むことができるオブジェクト。プラグインはステップ内で定義されます。ステップは、ドキュメントに記載されている順番に実行されます。

型: Dictionary<string,PluginConfiguration>

必須: はい

出力

(スキーマバージョン 0.3 のみ) このドキュメントの実行によって生成され、他のプロセスで使用できるデータ。たとえば、ドキュメントで新しい AMI を作成する場合、出力値として「CreateImage.ImageId」を指定すると、この出力を使用して後続のオートメーションの実行から新しいインスタンスを作成できます。出力の詳細については、「入力と出力の使用」を参照してください。

型: Dictionary<string,OutputConfiguration>

必須: いいえ

files

(スキーマバージョン 0.3 のみ) ドキュメントに添付され、自動実行時に実行されるスクリプトファイル (およびそのチェックサム)。aws:executeScript アクションを含むドキュメントのうち、添付ファイルが 1 つ以上のステップに指定されているもののみに適用されます。

スクリプトランタイムのサポートとして、オートメーションドキュメントは現在 Python 3.6、Python 3.7、および PowerShell Core 6.0 用のスクリプトをサポートしています。オートメーションドキュメントにスクリプトを含める方法の詳細については、「スクリプトを実行するオートメーションドキュメントの作成」および「 チュートリアル: ドキュメントビルダーを使用してカスタムのオートメーションドキュメントを作成する」を参照してください。

オートメーションドキュメントまたはプレイブックを作成するときは、--attachments オプション (AWS CLI の場合) または Attachments (API および SDK の場合) を使用して添付ファイルを指定します。ローカルファイルと Amazon S3 バケット内に保存されているファイルの両方について、ファイルの場所を指定できます。

YAML
--- files: launch.py: checksums: sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
JSON
"files": { "launch.py": { "checksums": { "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE" } } }

型: Dictionary<string,FilesConfiguration>

必須: いいえ

SSM ドキュメントパラメータ type の例

SSM ドキュメント内のパラメータのデータ型は静的です。つまり、パラメータのデータ型は定義後に変更することはできません。SSM ドキュメントプラグインでパラメータを使用する場合、パラメータのデータ型をプラグインの入力内で動的に変更することはできません。たとえば、aws:runShellScript プラグインの runCommand 入力内の Integer パラメータを参照することはできません。この入力は文字列または文字列のリストを受け入れるためです。プラグインの入力にパラメータを使用するには、パラメータのデータ型が、入力の受け入れ可能なデータ型と一致している必要があります。たとえば、aws:updateSsmAgent プラグインの allowDowngrade 入力には Boolean 型のパラメータを指定する必要があります。パラメータのデータ型がプラグインの入力のデータ型と一致しない場合、SSM ドキュメントの検証は失敗となり、システムによってドキュメントは作成されません。

SSM Automation アクションでパラメータを使用するときは、ほとんどの場合、SSM ドキュメントを作成するときにパラメータのデータ型は検証されません。aws:runCommand アクションを使用する場合にのみ、SSM ドキュメントを作成するときにパラメータのデータ型が検証されます。それ以外の場合、オートメーションの実行中、アクションが実行される前にその入力が検証されるときに、パラメータが検証されます。たとえば、入力パラメータが String であり、それを aws:runInstances アクションの MaxInstanceCount 入力の値として参照する場合は、SSM ドキュメントが作成されます。ただし、ドキュメントを実行すると、aws:runInstances アクションの検証中にオートメーションは失敗します。MaxInstanceCount 入力に Integer が必要なためです。

以下に示しているのは、各パラメータ type の例です。

文字列

引用符で囲んだ 0 個以上の Unicode 文字のシーケンス。たとえば、"i-1234567890abcdef0" など。バックスラッシュを使用してエスケープします。

YAML
--- InstanceId: type: String description: "(Required) The target EC2 instance ID."
JSON
"InstanceId":{ "type":"String", "description":"(Required) The target EC2 instance ID." }
StringList

カンマ区切りの文字列項目のリスト。たとえば、["cd ~", "pwd"] など。

YAML
--- commands: type: StringList description: "(Required) Specify a shell script or a command to run." minItems: 1 displayType: textarea
JSON
"commands":{ "type":"StringList", "description":"(Required) Specify a shell script or a command to run.", "minItems":1, "displayType":"textarea" }
Boolean

true または false のみを使用できます。"true" または 0 は使用できません。

YAML
--- canRun: type: Boolean description: '' default: true
JSON
"canRun": { "type": "Boolean", "description": "", "default": true }
整数

整数。小数 (3.14159 など) や引用符で囲んだ数字 ("3" など) は使用できません。

YAML
--- timeout: type: Integer description: The type of action to perform. default: 100
JSON
"timeout": { "type": "Integer", "description": "The type of action to perform.", "default": 100 }
StringMap

キーと値のマッピング。キーには文字列のみを使用できます。たとえば、{"Env": "Prod"} など。

YAML
--- notificationConfig: type: StringMap description: The configuration for events to be notified about default: NotificationType: Command NotificationEvents: - Failed NotificationArn: "$dependency.topicArn" maxChars: 150
JSON
"notificationConfig" : { "type" : "StringMap", "description" : "The configuration for events to be notified about", "default" : { "NotificationType" : "Command", "NotificationEvents" : ["Failed"], "NotificationArn" : "$dependency.topicArn" }, "maxChars" : 150 }
MapList

StringMap 項目のリスト。

YAML
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
JSON
"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 }