架构、功能和示例
Amazon Systems Manager (SSM) 文档当前使用以下架构版本。
-
Command型文档可以使用 1.2、2.0 和 2.2 版架构。如果您使用架构 1.2 文档，我们建议您创建使用架构版本 2.2 的文件。 -
Policy型文档必须使用 2.0 版或更高版本的架构。 -
Automation型文档必须使用 0.3 版架构。 -
Session型文档必须使用 1.0 版架构。 -
您可以创建 JSON 或 YAML 格式的文档。
有关 Session 文档架构的更多信息，请参阅 会话文档架构。
通过为 Command 和 Policy 文档使用最新架构版本，您可以利用以下功能。
| 功能 | 详细信息 |
|---|---|
|
编辑文档 |
文档现在可以更新。如果版本为 1.2，对文档的任何更新都需要另存为其他名称。 |
|
自动版本控制 |
对文档的任何更新都会创建一个新版本。这不是架构版本，而是文档版本。 |
|
默认版本 |
如果您拥有某个文档的多个版本，可以指定哪个版本是默认文档。 |
|
顺序 |
文档中的插件或步骤按指定的顺序运行。 |
|
跨平台支持 |
跨平台支持可让您为同一个 SSM 文档中的不同插件指定不同操作系统。跨平台支持在某个步骤中使用 |
| 参数插值 | 允许在执行命令之前将字符串参数插值到环境变量中，从而更好地防范命令注入攻击。设置为 ENV_VAR 时，代理会创建一个包含参数值的环境变量 SSM_。 |
注意
您必须将实例上的 Amazon Systems Manager SSM Agent 更新到最新版本才能使用新的 Systems Manager 功能和 SSM 文档功能。有关更多信息，请参阅 使用 Run Command 更新 SSM Agent。
下表列出了主要架构版本之间的区别。
| 版本 1.2 | 版本 2.2（最新版本） | 详细信息 |
|---|---|---|
|
runtimeConfig |
mainSteps |
在版本 2.2 中， |
|
属性 |
inputs |
在版本 2.2 中， |
|
命令 |
runCommand |
在版本 2.2 中， |
|
id |
action |
在版本 2.2 中， |
|
不适用 |
名称 |
在版本 2.2 中， |
使用前提条件参数
在 2.2 版或更高版本架构中，您可以使用 precondition 参数为每个插件指定目标操作系统验证您在 SSM 文档中定义的输入参数。precondition 参数支持引用 SSM 文档的输入参数，platformType 使用Linux 的值、MacOS,和 Windows。仅支持 StringEquals 运算符。
对于使用 2.2 版或更高版本架构的文档，如果未指定 precondition，每个插件将被运行或跳过，具体取决于插件与操作系统的兼容性。插件与操作系统的兼容性在 precondition 之前被评估。对于使用 2.0 版或更低版本架构的文档，不兼容的插件将会引发错误。
例如，在 2.2 版架构文档中，如果未指定 precondition，将会列出 aws:runShellScript 插件，该步骤在 Linux 实例上运行，但系统会在 Windows Server 实例上跳过该步骤，因为 aws:runShellScript 与 Windows Server 实例不兼容。但是，对于 2.0 版架构文档，如果您指定 aws:runShellScript 插件，然后在 Windows Server 实例上运行文档，执行将会失败。本节稍后将介绍在 SSM 文档中使用前提条件参数的示例。
架构版本 2.2
顶级元素
以下示例使用 2.2 版架构显示 SSM 文档的顶级元素。
2.2 版架构示例
以下示例使用 aws:runPowerShellScript 插件在目标实例上运行 PowerShell 命令。
架构版本 2.2 前提条件参数示例
2.2 版架构提供跨平台支持。这意味着在一个 SSM 文档内，您可以为不同的插件指定不同的操作系统。跨平台支持在某个步骤中使用 precondition 参数，如下例所示。您也可以使用 precondition 参数来验证您在 SSM 文档中定义的输入参数。您可以在以下第二个示例中看到此内容。
2.2 版架构插值示例（3.3.2746.0 之前的 SSM Agent 版本）
在 3.3.2746.0 之前的 SSM Agent 版本中，代理会忽略 interpolationType 参数，转而执行原始字符串的替换。若要显式引用 SSM_，则必须明确设置此项。以下 Linux 示例显式引用了环境变量 parameter-nameSSM_Message。
{ "schemaVersion": "2.2", "description": "An example document", "parameters": { "Message": { "type": "String", "description": "Message to be printed", "default": "Hello", "interpolationType" : "ENV_VAR", "allowedPattern: "^[^"]*$" } }, "mainSteps": [{ "action": "aws:runShellScript", "name": "printMessage", "inputs": { "runCommand": [ "if [ -z "${SSM_Message+x}" ]; then", " export SSM_Message=\"{{Message}}\"", "fi", "", "echo $SSM_Message" ] } } }
注意
如果 SSM 文档未使用以下双大括号，则 allowedPattern 在技术上是不必要的：{{ }}
2.2 版架构 State Manager 示例
您可以将以下 SSM 文档用于State Manager（Systems Manager 中的一项工具）来下载并安装 ClamAV 防病毒软件。State Manager会强制实施特定配置，这意味着每次运行State Manager关联时，系统都会检查是否安装了 ClamAV 软件。如果未安装，State Manager 会重新运行本文档。
2.2 版架构清单示例
您可以将以下 SSM 文档用于 State Manager,以收集关于实例的清单元数据。
2.2 版架构 AWS-ConfigureAWSPackage 示例
以下示例显示 AWS-ConfigureAWSPackage 文档。这些区域有：mainSteps部分包括aws:configurePackage插件action步骤。
注意
在 Linux 操作系统上，仅支持 AmazonCloudWatchAgent 和 AWSSupport-EC2Rescue 软件包。
架构版本 1.2
以下示例显示 1.2 版架构文档的顶级元素。
{ "schemaVersion":"1.2", "description":"A description of the SSM document.", "parameters":{ "parameter 1":{ "one or more parameter properties" }, "parameter 2":{ "one or more parameter properties" }, "parameter 3":{ "one or more parameter properties" } }, "runtimeConfig":{ "plugin 1":{ "properties":[ { "one or more plugin properties" } ] } } }
1.2 版架构 aws:runShellScript 示例
以下示例显示 AWS-RunShellScript SSM 文档。runtimeConfig 部分包含 aws:runShellScript 插件。
{ "schemaVersion":"1.2", "description":"Run a shell script or specify the commands to run.", "parameters":{ "commands":{ "type":"StringList", "description":"(Required) Specify a shell script or a command to run.", "minItems":1, "displayType":"textarea" }, "workingDirectory":{ "type":"String", "default":"", "description":"(Optional) The path to the working directory on your instance.", "maxChars":4096 }, "executionTimeout":{ "type":"String", "default":"3600", "description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).", "allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)" } }, "runtimeConfig":{ "aws:runShellScript":{ "properties":[ { "id":"0.aws:runShellScript", "runCommand":"{{ commands }}", "workingDirectory":"{{ workingDirectory }}", "timeoutSeconds":"{{ executionTimeout }}" } ] } } }
架构版本 0.3
顶级元素
以下示例显示 JSON 格式的架构 0.3 版自动化运行手册的顶级元素。
{ "description": "document-description", "schemaVersion": "0.3", "assumeRole": "{{assumeRole}}", "parameters": { "parameter1": { "type": "String", "description": "parameter-1-description", "default": "" }, "parameter2": { "type": "String", "description": "parameter-2-description", "default": "" } }, "variables": { "variable1": { "type": "StringMap", "description": "variable-1-description", "default": {} }, "variable2": { "type": "String", "description": "variable-2-description", "default": "default-value" } }, "mainSteps": [ { "name": "myStepName", "action": "action-name", "maxAttempts": 1, "inputs": { "Handler": "python-only-handler-name", "Runtime": "runtime-name", "Attachment": "script-or-zip-name" }, "outputs": { "Name": "output-name", "Selector": "selector.value", "Type": "data-type" } } ], "files": { "script-or-zip-name": { "checksums": { "sha256": "checksum" }, "size":1234} } }
YAML 自动化运行手册示例
以下示例显示了 YAML 格式的自动化运行手册的内容。0.3 版文档架构的此工作示例还演示了如何使用 Markdown 格式化文档描述。
description: >- ##Title: LaunchInstanceAndCheckState ----- **Purpose**: This Automation runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this document continuously checks the instance status check value for the launched instance until the status ```ok``` is returned. ##Parameters: ----- Name | Type | Description | Default Value ------------- | ------------- | ------------- | ------------- assumeRole | String | (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. | - imageId | String | (Optional) The AMI ID to use for launching the instance. The default value uses the latest Amazon Linux AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }} schemaVersion: '0.3' assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole' parameters: imageId: type: String default: '{{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}' description: >- (Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux AMI ID. tagValue: type: String default: ' LaunchedBySsmAutomation' description: >- (Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation. instanceType: type: String default: t2.micro description: >- (Optional) The instance type to use for the instance. The default value is t2.micro. mainSteps: - name: LaunchEc2Instance action: 'aws:executeScript' outputs: - Name: payload Selector: $.Payload Type: StringMap inputs: Runtime: python3.8 Handler: launch_instance Script: '' InputPayload: image_id: '{{ imageId }}' tag_value: '{{ tagValue }}' instance_type: '{{ instanceType }}' Attachment: launch.py description: >- **About This Step** This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided python script. - name: WaitForInstanceStatusOk action: 'aws:executeScript' inputs: Runtime: python3.8 Handler: poll_instance Script: |- def poll_instance(events, context): import boto3 import time ec2 = boto3.client('ec2') instance_id = events['InstanceId'] print('[INFO] Waiting for instance status check to report ok', instance_id) instance_status = "null" while True: res = ec2.describe_instance_status(InstanceIds=[instance_id]) if len(res['InstanceStatuses']) == 0: print("Instance status information is not available yet") time.sleep(5) continue instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status'] print('[INFO] Polling to get status of the instance', instance_status) if instance_status == 'ok': break time.sleep(10) return {'Status': instance_status, 'InstanceId': instance_id} InputPayload: '{{ LaunchEc2Instance.payload }}' description: >- **About This Step** The python script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned. files: launch.py: checksums: sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
安全处理参数示例
以下示例演示使用环境变量 interpolationType 安全处理参数。
基本安全命令执行
本示例说明如何安全处理命令参数：
注意
在不使用以下双大括号的 SSM 文档中，allowedPattern 在技术上是不必要的：{{ }}
在解释性语言中使用参数
本示例演示在 Python 中安全处理参数：
向后兼容性示例
本示例展示如何安全处理参数，同时保持向后兼容性：
注意
在不使用以下双大括号的 SSM 文档中，allowedPattern 在技术上是不必要的：{{ }}
参数安全的最佳实践
在处理 SSM 文档中的参数时，请遵循以下最佳实践：
-
使用环境变量插值：即将用于命令执行的字符串参数始终使用
interpolationType: "ENV_VAR"。 -
实现输入验证：使用
allowedPattern将参数值限制为安全模式。 -
处理遗留系统：为不支持环境变量插值的旧版 SSM Agent 添加回退逻辑。
-
转义特殊字符：在命令中使用参数值时，请对特殊字符进行恰当转义以防止被 shell 解释。
-
限制参数范围：为用例使用尽可能严格的参数模式。