データ要素とパラメータ
このトピックでは、SSM ドキュメントで使用されるデータ要素について説明します。ドキュメントの作成に使用されるスキーマのバージョンは、ドキュメントで使用できる構文とデータ要素を定義します。コマンドドキュメントには、スキーマバージョン 2.2 以降を使用することをお勧めします。Automation ランブックはスキーマバージョン 0.3 を使用します。さらに、Automation ランブックでは、マークアップ言語である Markdown の使用がサポートされています。これにより、wiki スタイルの説明をドキュメントやドキュメント内の個々のステップに追加できます。Markdown の使用に関する詳細については、「AWS Management Console 入門ガイド」の「コンソールでの Markdown の使用」を参照してください。
次のセクションでは、SSM ドキュメントに含めることができるデータ要素について説明します。
最上位のデータ要素
- schemaVersion
-
使用するスキーマバージョン。
型: バージョン
必須: はい
- description
-
ドキュメントの目的を説明するために提供する情報。またこのフィールドを使用して、ドキュメントの実行にパラメータの値が必要か否か、またはパラメータの値の指定が任意か否かを指定することもできます。必須と任意のパラメータはこのトピックのサンプルをご参照ください。
タイプ: 文字列
必須: いいえ
- パラメータ
-
ドキュメントが許可するパラメータを定義する構造。
頻繁に使用するパラメータの場合は、そのパラメータを AWS Systems Manager の一機能である Parameter Store に保存することをお勧めします。次に、デフォルト値として Parameter Store パラメータを参照するパラメータをドキュメントで定義できます。Parameter Store パラメータを参照するには、次の構文を使用します。
{{ssm:
parameter-name
}}他のドキュメントパラメータと同じ方法で、Parameter Store パラメータを参照するパラメータを使用できます。次の例では、
commands
パラメータのデフォルト値は Parameter Store パラメータmyShellCommands
です。commands
パラメータをrunCommand
文字列として指定すると、ドキュメントはmyShellCommands
パラメータに格納されているコマンドを実行します。注記
String
およびStringList
Parameter Store パラメータは、ドキュメントのparameters
セクションで参照できます。SecureString
Parameter Store パラメータは参照できません。Parameter Store の詳細については、「AWS Systems Manager Parameter Store」を参照してください。
型: 構造
parameters
構造は次のフィールドと値を受け入れます。-
type
: (必須) その値としてString
、StringList
、Integer
、Boolean
、MapList
、StringMap
を使用できます。各タイプの例を表示するには、次のセクションの「SSM ドキュメントパラメータ type の例」を参照してください。注記
コマンドタイプのドキュメントでは、
String
およびStringList
パラメータタイプのみがサポートされます。 -
description
: (オプション) パラメータグループの説明。 -
default
: (オプション) Parameter Store でのパラメータのデフォルト値またはパラメータへの参照。 -
allowedValues
: (オプション) パラメータに使用できる値の配列。パラメータに使用できる値を定義すると、ユーザー入力が検証されます。使用できない値をユーザーが入力すると、実行の開始に失敗します。 -
allowedPattern
: (オプション) ユーザー入力がパラメータに対して定義されたパターンと一致するかどうかを検証する正規表現。ユーザー入力が使用できるパターンと一致しない場合、実行は開始されません。注記
Systems Manager は、
allowedPattern
について 2 つの検証を実行します。1 つ目の検証は、ドキュメントを使用するときに API レベルで Java 正規表現ライブラリを使用して実行されます。2 つ目の検証は、ドキュメントを処理する前に GO regexp ライブラリ を使用して SSM Agent に対して実行されます。 -
displayType
: (オプション)textfield
のtextarea
または AWS Management Console のいずれかを表示するために使用されます。textfield
は、1 行のテキストボックスで、textarea
は、複数行のテキストエリアです。 -
minItems
: (オプション) 許可される項目の最小数。 -
maxItems
: (オプション) 許可される項目の最大数。 -
minChars
: (オプション) 許可される項目の最小数。 -
maxChars
: (オプション) を許可されているパラメータ文字の最大数。
必須:いいえ
-
- variables
-
(スキーマバージョン 0.3 のみ) 自動化ランブックのステップ全体で参照または更新できる値。変数はパラメーターと似ていますが、非常に重要な点において異なります。パラメーター値はランブックのコンテキストでは静的ですが、変数の値はランブックのコンテキストでは変更できます。変数の値を更新する場合、データ型は定義されたデータ型と一致する必要があります。オートメーションの変数値の更新に関する詳細は、「aws:updateVariable — ランブック変数の値を更新します。」を参照してください。
型: ブール値|整数|マップリスト|文字列|文字列リスト|文字列マップ
必須:いいえ
- 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 つ以上のステップに指定されているもののみに適用されます。スクリプトランタイムのサポートとして、Automation ランブックは Python 3.7、Python 3.8、PowerShell Core 6.0、および PowerShell 7.0 用のスクリプトをサポートしています。Automation ランブックにスクリプトを含める方法の詳細については、「ランブックでのスクリプトの使用」および「ランブック作成のためのドキュメントビルダーの使用」を参照してください。
アタッチメントの付いたオートメーションランブックを作成するときは、
--attachments
オプション (AWS CLI の場合) またはAttachments
(API および SDK の場合) を使用して添付ファイルを指定する必要があります。ローカルファイルと Amazon Simple Storage Service (Amazon S3) バケット内に保存されているファイルの両方について、ファイルの場所を指定できます。詳細については、「AWS Systems Manager API リファレンス」の「Attachments」(アタッチメント) を参照してください。型: Dictionary<string,FilesConfiguration>
必須: いいえ
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" など。バックスラッシュを使用してエスケープします。
- StringList
-
カンマ区切りの文字列項目のリスト。例えば、["cd ~", "pwd"] など。
- Boolean
-
true
またはfalse
のみを使用できます。"true" または 0 は使用できません。 - 整数
-
整数。小数 (3.14159 など) や引用符で囲んだ数字 ("3" など) は使用できません。
- StringMap
-
キーと値のマッピング。キーと値は文字列でなければなりません。例えば、{"Env": "Prod"} など。
- MapList
-
StringMap オブジェクトのリスト。
SSM コマンドドキュメントの内容の表示
AWS Systems Manager (SSM) コマンドドキュメントの必須パラメータとオプションのパラメータ、およびドキュメントが実行するアクションをプレビューするには、Systems Manager コンソールでドキュメントのコンテンツを表示できます。
SSM コマンドドキュメントの内容を表示するには
AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/
) を開きます。 ナビゲーションペインで、[ドキュメント] を選択します。
-
検索ボックスで、[ドキュメントのタイプ] を選択し、[コマンド] を選択します。
-
ドキュメントの名前を選択し、[コンテンツ] タブをクリックします。
-
[コンテンツ] フィールドで、ドキュメントで使用できるパラメータとアクションステップを確認します。
例えば、次の図は、(1)
version
と (2)allowDowngrade
がAWS-UpdateSSMAgent
ドキュメントのオプションのパラメータで、ドキュメントによって実行される最初のアクションが (3)aws:updateSsmAgent
であることを示しています。