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

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

SSM 文档语法

文档语法由用于创建文档的架构版本定义。我们建议您对 Command 文档使用架构版本 2.2 或更高版本。自动化运行手册使用 0.3 版架构。此外,Automation 运行手册还支持使用 Markdown(一种标记语言),它允许您为文档和文档中的各个步骤添加 Wiki 样式的描述。有关使用 Markdown 的更多信息,请参阅在 中使用 MarkdownAmazon

顶级元素提供 SSM 文档的结构。本主题中的信息与CommandAutomationSSM 文档。

顶级元素

schemaVersion

要使用的架构版本。

类型: Version

:必需 是

description

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

类型: 字符串

:必需 否

参数

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

{{ssm:parameter-name}}

有关参数存储的更多信息,请参阅Amazon Systems Manager Parameter Store

类型: 结构

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

  • type:(必需)允许的值包括:StringStringListInteger BooleanMapList, 和StringMap。要查看每种类型的示例,请参阅下一节中的 SSM 文档参数type示例

    注意

    要使用数字作为参数值,请使用String作为参数类型。

  • 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:(可选)验证用户输入是否与参数的定义模式匹配的正则表达式。如果用户输入与允许的模式不匹配,则执行无法启动。

    注意

    在 SSM 文档中,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:(可选)用于在 Amazon Web Services Management Console中显示 textfieldtextareatextfield 是单行文本框。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 的脚本。有关在 Automation Runbook 中包含脚本的更多信息,请参阅创建运行脚本的运行手册 演练:使用文档生成器创建自定义 Runbook

创建自动化运行簿时,可以使用--attachments选项(用于Amazon 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 文档中的参数类型是静态的。这意味着参数类型在定义后无法更改。将参数用于 SSM 文档插件时,不能在插件的输入中动态更改参数的类型。例如,您不能在 aws:runShellScript 插件的 runCommand 输入中引用 Integer 参数,因为此输入接受字符串或字符串列表。要将参数用于插件输入,参数类型必须与接受的类型匹配。例如,您必须为 aws:updateSsmAgent 插件的 allowDowngrade 输入指定 Boolean 类型参数。如果参数类型与插件的输入类型不匹配,则 SSM 文档无法验证,并且系统不会创建文档。

将参数与Amazon Systems Manager大多数情况下创建 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 }
整数

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