SSM 文档语法 - AWS Systems Manager
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

SSM 文档语法

文档语法由用于创建文档的架构版本定义。我们建议您对命令文档使用架构版本 2.2 或更高版本。自动化文档使用架构版本 0.3。此外,Automation 文档还支持使用 Markdown(一种标记语言),它允许您为文档和文档中的各个步骤添加 Wiki 样式的描述。有关使用 Markdown 的更多信息,请参阅在 AWS https://docs.amazonaws.cn/general/latest/gr/aws-markdown.html中使用 Markdown。

顶级元素提供 SSM 文档的结构。本主题中的信息 CommandAutomation SSM 文档有关。

顶级元素

schemaVersion

要使用的架构版本。

类型:版本

必需:是

description

您提供的描述文档目的的信息。

类型:字符串

必需:否

parameters

定义文档接受的参数的结构。对于经常引用的参数,建议在 Systems Manager Parameter Store 中存储这些参数,然后进行引用。您可以在文档的这一部分引用 StringStringList Parameter Store 参数。您不能在文档的这一部分引用 SecureString Parameter Store 参数。您可以使用以下格式引用Parameter Store参数:

{{ssm:parameter-name}}

有关 的更多信息Parameter Store,请参阅AWS Systems Manager Parameter Store

类型:结构

parameters 结构接受以下字段和值:

  • type:(必需)允许的值包括String:、StringListBooleanMapListStringMap。 要查看每种类型的示例,请参阅下一节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 正则表达式语法,这不包括对查找的支持。

    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:(可选)用于在 中显示 textfieldtextarea AWS 管理控制台。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 文档当前支持 Python 3.6、Python 3.7 和 PowerShell Core 6.0 的脚本。有关在自动化文档中包含脚本的更多信息,请参阅 创建运行脚本的运行手册 演练:使用文档生成器创建自定义运行手册.

创建自动化文档或手册时,您可以使用 --attachments 选项(对于 AWS CLI)或 Attachments(对于 API 和开发工具包)指定附件文件。您可以为本地文件和存储在 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 文档插件时,不能在插件的输入中动态更改参数的类型。例如,您不能在 Integer 插件的 runCommand 输入中引用 aws:runShellScript 参数,因为此输入接受字符串或字符串列表。要将参数用于插件输入,参数类型必须与接受的类型匹配。例如,您必须为 Boolean 插件的 allowDowngrade 输入指定 aws:updateSsmAgent 类型参数。如果参数类型与插件的输入类型不匹配,则 SSM 文档无法验证,并且系统不会创建文档。

将参数用于 SSM Automation 操作时,大多数情况下创建 SSM 文档时不会验证参数类型。只有在使用 aws:runCommand 操作的情况下,才会在创建 SSM 文档时验证参数类型。在所有其他情况下,在运行操作之前验证该操作的输入时,会在自动化执行期间进行参数验证。例如,如果输入参数为 String 并将其引用为 MaxInstanceCount 操作 aws:runInstances 输入的值,则会创建 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" }
Boolean

仅接受 truefalse。 不接受“true”或 0。

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

整数。不接受小数(例如 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 }