Amazon EC2 Systems Manager
用户指南
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Systems Manager 文档

Amazon EC2 Systems Manager 文档定义 Systems Manager 对您的托管实例执行的操作。Systems Manager 包括十多个预先配置的文档,可以通过在运行时指定参数进行使用。文档使用 JavaScript Object Notation (JSON),并包括您指定的步骤和参数。

下表介绍了不同类型的 SSM 文档。

Type 一起使用 详细信息

命令文档

Run Command

状态管理器

Run Command 使用命令文档执行命令。State Manager 使用命令文档应用策略。在实例生命周期内的任何时刻,这些操作都可在一个或多个目标上运行,

策略文档

状态管理器

策略文档对您的目标执行策略。如果删除策略文档,将不再执行该策略 (例如,收集清单)。

自动化文档

自动化

在执行常规维护和部署任务时 – 如创建或更新 Amazon 系统映像 (AMI) – 使用自动化文档。

有关 SSM 文档限制的信息,请参阅 Amazon EC2 Systems Manager 限制

Systems Manager 预定义文档

为了帮助您快速入门,Systems Manager 提供了预定义文档。可在 Amazon EC2 控制台中查看这些文档。在 EC2 控制台中,展开 Systems Manager Shared Resources,然后选择 Documents。您在选择某个文档后,可以通过下方窗格中的选项卡查看所选文档的相关信息,如下图所示。

 Systems Manager 文档

您还可以使用 AWS CLI 和 Tools for Windows PowerShell 命令查看一组文档,并获得这些文档的描述。

AWS CLI

Copy
aws ssm list-documents
Copy
aws ssm describe-document --name "document_name"

Tools for Windows PowerShell

Copy
Get-SSMDocumentList
Copy
Get-SSMDocumentDescription -Name "document_name"

文档架构和功能

Systems Manager 文档当前使用以下架构版本。

  • Command 型文档可以使用 1.2、2.0 和 2.2 版架构。如果您目前使用 1.2 版架构文档,我们建议您创建使用 2.0 版架构的文档。

  • Policy 型文档必须使用 2.0 版或更高版本的架构。

  • Automation 型文档必须使用 0.3 版架构。

通过为 CommandPolicy 文档使用最新架构版本,您可以利用以下功能。

2.2 版架构文档功能

功能 详细信息

编辑文档

文档现在可以更新。如果版本为 1.2,对文档的任何更新都需要另存为其他名称。

自动版本控制

对文档的任何更新都会创建一个新版本。这不是架构版本,而是文档版本。

默认版本

如果您拥有某个文档的多个版本,可以指定哪个版本是默认文档。

顺序

文档中的插件或步骤按指定的顺序执行。

跨平台支持

跨平台支持可让您为同一个 SSM 文档中的不同插件指定不同操作系统。跨平台支持在某个步骤中使用 precondition 参数。

注意

您必须将实例上的 SSM 代理更新至最新版本才能使用新的 Systems Manager 功能和 SSM 文档功能。有关更多信息,请参阅 从 EC2 控制台执行命令 中标题为示例:更新 SSM 代理的部分。

下表列出了主要架构版本之间的区别。

版本 1.2 版本 2.0 详细信息

runtimeConfig

mainSteps

在 2.0 版或更高版本中,mainSteps 部分替换了 runtimeConfig 部分。mainSteps 部分启用了 Systems Manager,以便依顺序执行步骤。

属性

inputs

在 2.0 版或更高版本中,inputs 部分替换了 properties 部分。inputs 部分接受步骤参数。

命令

runCommand

在 2.0 版或更高版本中,inputs 部分接收 runCommand 参数,而不是 commands 参数。

id

action

在 2.0 版或更高版本中,Action 替换了 ID。这只是更改了名称。

不适用

name

在 2.0 版或更高版本中,name 是用户定义的任意步骤名称。

SSM 文档语法

文档语法由用于创建文档的架构版本定义。我们建议您使用 2.2 版或更高版本的架构。使用此架构版本的文档包含以下顶级元素。有关您可以在这些元素中指定的属性的信息,请参阅 Amazon EC2 Systems Manager API Reference 中的顶级元素

  • schemaVersion:使用的架构版本。

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

  • Parameters:文档接受的参数。对于您经常引用的参数,我们建议您在 Systems Manager Parameter Store 中存储这些参数,然后进行引用。您可以在文档的这一部分引用 StringStringList Systems Manager 参数。您不能在文档的这一部分引用 Secure String Systems Manager 参数。有关更多信息,请参阅 Systems Manager Parameter Store

  • mainSteps:可以包含多个步骤 (插件) 的对象。步骤包括一个或多个操作、可选前提条件、各操作的唯一名称以及这些操作的 inputs (参数)。有关支持的插件和插件属性的列表,请参阅 Amazon EC2 Systems Manager API Reference 中的 SSM 插件

使用前提条件参数

在 2.2 版或更高版本架构中,您可以使用 precondition 参数为每个插件指定目标操作系统。precondition 参数支持 platformType 和值 WindowsLinux

对于使用 2.2 版或更高版本架构的文档,如果未指定 precondition,每个插件将被执行或跳过,具体取决于插件与操作系统的兼容性。对于使用 2.0 版或更低版本架构的文档,不兼容的插件将会引发错误。

例如,在 2.2 版架构文档中,如果未指定 precondition,将会列出 aws:runShellScript 插件,该步骤在 Linux 实例上执行,但系统会在 Windows 实例上跳过该步骤,因为 aws:runShellScript 与 Windows 实例不兼容。但是,对于 2.0 版架构文档,如果您指定 aws:runShellScript 插件,然后在 Windows 实例上运行文档,执行将会失败。

2.0 版或更高版本架构的语法

以下示例显示 2.0 版或更高版本架构文档的顶级元素。

Copy
{ "schemaVersion":"2.0", "description":"A description of the document.", "parameters":{ "parameter 1":{ "one or more parameter properties" }, "parameter 2":{ "one or more parameter properties" }, "parameter 3":{ "one or more parameter properties" } }, "mainSteps":[ { "action":"plugin 1", "name":"A name for this action.", "inputs":{ "name":"{{ input 1 }}", "name":"{{ input 2 }}", "name":"{{ input 3 }}", } } ] }

2.2 版架构示例

2.2 版架构提供跨平台支持。这意味着在一个 SSM 文档内,您可以为不同的插件指定不同的操作系统。跨平台支持在某个步骤中使用 precondition 参数,如下例所示。

Copy
{ "schemaVersion":"2.2", "description":"cross-platform sample", "mainSteps":[ { "action":"aws:runPowerShellScript", "name":"Patch Windows", "precondition":{ "StringEquals":[ "platformType", "Windows" ] }, "inputs":{ "runCommand":[ "cmds" ] } }, { "action":"aws:runRunShellScript", "name":"Patch Linux", "precondition":{ "StringEquals":[ "platformType", "Linux" ] }, "inputs":{ "runCommand":[ "cmds" ] } } ] }

2.0 版架构示例

以下示例显示 AWS-ConfigureAWSPackage 文档。mainSteps 部分在 action 步骤中包括 aws:configurePackage 插件。

Copy
{ "schemaVersion": "2.0", "description": "Install or uninstall the latest version or specified version of an AWS package.", "parameters": { "action": { "description": "(Required) Specify whether or not to install or uninstall the package.", "type": "String", "allowedValues": [ "Install", "Uninstall" ] }, "name": { "description": "(Required) The package to install/uninstall.", "type": "String", "allowedValues": [ "AWSPVDriver" ] }, "version": { "description": "(Optional) A specific version of the package to install or uninstall. If installing, the system installs the latest published version, by default. If uninstalling, the system uninstalls the currently installed version, by default. If no installed version is found, the latest published version is downloaded, and the uninstall action is run.", "type": "String", "default": "", "allowedPattern": "(^(?:(\\d+)\\.)(?:(\\d+)\\.)(\\d+)$|^$)" } }, "mainSteps": [{ "action": "aws:configurePackage", "name": "configurePackage", "inputs": { "name": "{{ name }}", "action": "{{ action }}", "version": "{{ version }}" } }] }

1.2 版架构的语法

以下示例显示 1.2 版架构文档的顶级元素。

Copy
{ "schemaVersion":"1.2", "description":"A description of the Systems Manager 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" } ] } } }

注意

aws:applications、aws:psModule、aws:runShellScript 和 aws:runPowerShellScript 插件允许您指定属性阵列。

1.2 版架构示例

以下示例显示 AWS-RunShellScript Systems Manager 文档。runtimeConfig 部分包含 aws:runShellScript 插件。

Copy
{ "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 28800 (8 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 }}" } ] } } }

文档版本与执行

您可以创建并保存不同版本的文档。您可以为每个文档指定默认版本。文档的默认版本可以更新到较新版本或恢复到较旧版本。如果您更改 State Manager 策略或命令文档的默认版本,则在下次 Systems Manager 将关联应用到实例时,使用该文档的所有关联均开始使用新的默认版本。

当您更改文档的 JSON 内容时,Systems Manager 将自动递增文档的版本。您可以检索并查看之前的版本。State Manager 策略或命令文档可以与实例或标记的实例组关联。

另请注意有关文档的以下详细信息。

  • 通过创建使用不同文档的不同关联,您可以将多个策略文档指定到同一个目标。

  • 如果您将多个文档关联到一个目标,您可以使用 AWS CLI 或软件开发工具包来查看将在所有关联的文档上执行的插件的综合列表。

  • 各个步骤在文档中的指定顺序即为其执行顺序。

  • 只要有权限,您就可以将共享 文档用于 State Manager,但是您无法将共享文档与实例关联。如果您想要使用或分享与一个或多个目标相关联的文档,则您必须先创建文档副本,然后才能使用或分享。

  • 如果您创建的文档含有互相冲突的插件 (例如加入域的插件和从域中删除的插件),则最终状态取决于最后执行的插件。State Manager 不会验证文档中的命令或插件的逻辑顺序或合理性。

  • 处理文档时,系统首先应用实例关联,然后应用标记实例组关联。如果实例处于多个标记实例组中,则对应标记实例组的文档不会以任何特定顺序执行。如果实例通过其实例 ID 直接对应多个文档,那么也不存在特定的执行顺序。

自定义文档

如果您要通过文档自定义步骤和操作,可以自行创建文档。当您首次使用某一文档对实例执行操作时,系统会将此文档存储在您的 AWS 账户中。有关如何创建 Systems Manager 文档的更多信息,请参阅创建 Systems Manager 文档

共享文档

您可以将文档公开,或者与特定 AWS 账户共享。有关更多信息,请参阅 共享 Systems Manager 文档