データ要素とパラメータ

このトピックでは、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 パラメータに格納されているコマンドを実行します。

YAML

---
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 }}"]
mainSteps:
- action: aws:runShellScript
  name: runShellScriptDefaultParams
  inputs:
    runCommand:
    - "{{ commands }}"

JSON

{
    "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 }}"]
      }
    },
    "mainSteps": [
      {
        "action": "aws:runShellScript",
        "name": "runShellScriptDefaultParams",
        "inputs": {
            "runCommand": [
              "{{ commands }}"
          ]
        }
      }
    ]
  }

注記

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: (オプション) パラメータに使用できる値の配列。パラメータに使用できる値を定義すると、ユーザー入力が検証されます。使用できない値をユーザーが入力すると、実行の開始に失敗します。

  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 正規表現ライブラリを使用して実行されます。2 つ目の検証は、ドキュメントを処理する前に GO regexp ライブラリを使用して SSM Agent に対して実行されます。

  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: (オプション) textfield の textarea または AWS Management Console のいずれかを表示するために使用されます。textfield は、1 行のテキストボックスで、textarea は、複数行のテキストエリアです。

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

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

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

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

必須：いいえ

variables

(スキーマバージョン 0.3 のみ) 自動化ランブックのステップ全体で参照または更新できる値。変数はパラメーターと似ていますが、非常に重要な点において異なります。パラメーター値はランブックのコンテキストでは静的ですが、変数の値はランブックのコンテキストでは変更できます。変数の値を更新する場合、データ型は定義されたデータ型と一致する必要があります。オートメーションの変数値の更新に関する詳細は、「aws:updateVariable — ランブック変数の値を更新します。」を参照してください。

型: ブール値｜整数｜マップリスト｜文字列｜文字列リスト｜文字列マップ

必須：いいえ

YAML

variables:
    payload:
        type: StringMap
        default: "{}"

JSON

{
    "variables": [
        "payload": {
            "type": "StringMap",
            "default": "{}"
        }
    ]
}

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」(アタッチメント) を参照してください。

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 ドキュメントプラグインでパラメータを使用する場合、パラメータのデータ型をプラグインの入力内で動的に変更することはできません。例えば、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" など。バックスラッシュを使用してエスケープします。

YAML

---
InstanceId:
  type: String
  description: "(Optional) The target EC2 instance ID."

JSON

"InstanceId":{
  "type":"String",
  "description":"(Optional) The target EC2 instance ID."
}

StringList

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

YAML

---
commands:
  type: StringList
  description: "(Required) Specify a shell script or a command to run."
  default: ""
  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
}

SSM コマンドドキュメントの内容の表示

AWS Systems Manager (SSM) コマンドドキュメントの必須パラメータとオプションのパラメータ、およびドキュメントが実行するアクションをプレビューするには、Systems Manager コンソールでドキュメントのコンテンツを表示できます。

SSM コマンドドキュメントの内容を表示するには

1. AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/) を開きます。

2. ナビゲーションペインで、[ドキュメント] を選択します。

3. 検索ボックスで、[ドキュメントのタイプ] を選択し、[コマンド] を選択します。

4. ドキュメントの名前を選択し、[コンテンツ] タブをクリックします。

5. [コンテンツ] フィールドで、ドキュメントで使用できるパラメータとアクションステップを確認します。

   例えば、次の図は、(1) version と (2) allowDowngrade が AWS-UpdateSSMAgent ドキュメントのオプションのパラメータで、ドキュメントによって実行される最初のアクションが (3) aws:updateSsmAgent であることを示しています。