SSM 文件語法 - AWS Systems Manager

SSM 文件語法

您的文件語法是根據當時建立文件所使用的結構描述版本來定義的。建議命令文件使用結構描述版本 2.2 或更新版本。Automation Runbook 使用結構描述版本 0.3。此外,Automation Runbook 支援使用 Markdown (一種標示語言),可讓您新增維基樣式的描述至文件內,以及在文件內新增個別步驟。如需有關使用 Markdown 的詳細資訊,請參閱在 AWS 中使用 Markdown

頂層元素提供 SSM 文件的結構。本主題中的資訊與 CommandAutomation SSM 文件有關。

頂層元素

schemaVersion

要使用的結構描述版本。

類型:版本

必要:是

描述

您提供來描述文件用途的資訊。

類型:字串

必要:否

parameters

一種結構,定義文件接受的參數。對於常用的參數,我們建議您將這些參數存放在 Parameter Store (AWS Systems Manager 的一個功能) 中,然後參考使用。您在文件的這部分可以參考 StringStringList Parameter Store 參數。您在文件的這部分不能參考 SecureString Parameter Store 參數。您可以使用下列格式參考 Parameter Store 參數:

{{ssm:parameter-name}}
YAML
AMI: type: String description: "(Required) The AMI to use when launching the instance." default: {{ssm:/aws/service/list/ami-windows-latest}}
JSON
"AMI": { "type": "String", "description": "(Required) The AMI to use when launching the instance.", "default": "{{ssm:/aws/service/list/ami-windows-latest}}" }

如需有關 Parameter Store 的詳細資訊,請參閱AWS Systems ManagerParameter Store

類型:結構

parameters 結結構接受下列的欄位和數值:

  • type:(必要) 允許的值包括:StringStringListIntegerBooleanMapListStringMap。若要查看每個類型的範例,在下一個部分請參閱 SSM 文件參數 type 範例

    注意

    若要使用數字作為參數值,請使用 String 作為參數類型。

  • 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:(選擇性) 規則運算式,可驗證使用者輸入是否符合參數定義的模式。如果使用者輸入不符合允許的模式,則無法開始執行。

    注意

    在 SSM 文件中,allowedPattern 欄位支援 Google re2 regex 語法,它不支援 lookaround。

    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 是單行文字方塊。textarea 是多行文字區域。

  • minItems:(選擇性) 允許項目數量的最小值。

  • maxItems:(選擇性) 允許項目數量的最大值。

  • minChars:(選擇性) 允許參數字元數量的最小值。

  • maxChars:(選擇性) 允許參數字元數量的最大值。

必要:否

runtimeConfig

(結構描述 1.2 版) 一個或多個 Systems Manager 外掛程式套用的執行個體組態。不能保證外掛程式按順序執行。

類型:Dictionary<string,PluginConfiguration>

必要:否

mainSteps

(僅限結構描述版本 0.3、2.0 和 2.2) 可以包含多個步驟 (外掛程式) 的物件。外掛程式在步驟中定義。步驟會按文件中列出的順序執行。

類型:Dictionary<string,PluginConfiguration>

必要:是

outputs

(僅限結構描述版本 0.3) 執行此文件所產生的資料,可用於其他程序。例如,如果您的文件建立新 AMI,您可以將 "CreateImage.ImageId" 指定為輸出值,然後使用此輸出在後續自動化執行中建立新的執行個體。如需輸出的詳細資訊,請參閱 使用輸入和輸出

類型:Dictionary<string,OutputConfiguration>

必要:否

files

(僅限結構描述 0.3) 連接至文件並在自動化執行期間執行的指令碼檔案 (及其檢查總和)。僅適用於包含 aws:executeScript 動作,以及已在一或多個步驟中指定附件的文件。

對於指令碼執行時間支援,Automation Runbook 支援 Python 3.6、Python 3.7 和 PowerShell Core 6.0 的指令碼。如需有關在 Automation Runbook 中包含指令碼的詳細資訊,請參閱 建立執行指令碼的 Runbook 演練:使用文件建置器建立自訂 Runbook

建立 Automation Runbook 時,您可以使用 --attachments 選項 (適用於 AWS CLI) 或 Attachments 選項 (適用於 API 和軟體開發套件) 來指定附件檔案。您可以為本機檔案和存放在 Amazon Simple Storage Service (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 文件外掛程式搭配使用時,無法在外掛程式的輸入中動態變更參數的類型。例如,您無法在 Integer 外掛程式的 runCommand 輸入中參考 aws:runShellScript 參數,因為此輸入接受字串或字串清單。若要對外掛程式輸入使用參數,參數類型必須與接受的類型相符。例如,您必須為 Boolean 外掛程式的 allowDowngrade 輸入指定 aws:updateSsmAgent 類型參數。如果您的參數類型與外掛程式的輸入類型不相符,則 SSM 文件便無法驗證,且系統不會建立文件。

搭配使用參數與 AWS Systems Manager 自動化動作時,在大多數情況下建立 SSM 文件並不會驗證參數類型。只有當您使用 aws:runCommand 動作時,才會在您建立 SSM 文件時驗證參數類型。在所有其他情況下,則會在執行動作之前驗證動作的輸入之時,在自動化執行期間進行參數驗證。例如,如果您的輸入參數為 String,而您將其參考為 aws:runInstances 動作的 MaxInstanceCount 輸入的數值,則會建立 SSM 文件。不過,執行文件時,自動化會在驗證 aws:runInstances 動作時會失敗,因為 MaxInstanceCount 輸入需要 Integer.

以下是每個參數 type 的範例。

字串

一連串零或多個 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" }
布林值

僅接受 truefalse。不接受「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 }