架构、功能和示例
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 文档中的不同插件指定不同操作系统。跨平台支持在某个步骤中使用 |
注意
您必须将实例上的 AWS 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 版架构 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
