架构、功能和示例
AWS 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 文档中的不同插件指定不同操作系统。跨平台支持在某个步骤中使用 |
| 参数插值 | 插值是指将变量值插入或替换到字符串中。可以将其想象为在使用字符串之前用实际值填充空白。在 SSM 文档上下文中，参数插值允许在执行命令之前将字符串参数插值到环境变量中，从而更好地防范命令注入攻击。设置为 |
注意
您必须将实例上的 AWS Systems Manager SSM Agent 更新到最新版本才能使用新的 Systems Manager 功能和 SSM 文档功能。有关更多信息，请参阅 使用 Run Command 更新 SSM Agent。
下表列出了主要架构版本之间的区别。
| 版本 1.2 | 版本 2.2（最新版本） | 说明 |
|---|---|---|
|
runtimeConfig |
mainSteps |
在版本 2.2 中， |
|
属性 |
输入 |
在版本 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 实例上运行该文档会导致执行失败。
架构版本 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 结合使用来下载和安装 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/al2023-ami-kernel-6.1-x86_64 }} schemaVersion: '0.3' assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole' parameters: imageId: type: String default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}' 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.11 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.11 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 解释。
-
限制参数范围：为用例使用尽可能严格的参数模式。
