命令文档插件参考 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

命令文档插件参考

此参考介绍可在 Amazon Systems Manager (SSM) 命令类型文档中指定的插件。这些插件不能在使自动化操作的 SSM 自动化运行手册中使用。有关 Amazon Systems Manager 自动化操作的信息,请参阅 Systems Manager 自动化操作参考

Systems Manager 通过读取 SSM 文档的内容确定在托管实例上执行的操作。每个文档都包含代码执行部分。根据文档的架构版本,此代码执行部分可能包含一个或多个插件或步骤。为了便于理解本帮助主题,我们将这些插件和步骤都称为插件。本部分包含有关每个 Systems Manager 插件的信息。有关文档的详细信息(包括有关创建文档和架构版本之间的差异的信息),请参阅 Amazon Systems Manager 文档

注意

此处介绍的部分插件仅在 Windows Server 实例或 Linux 实例上运行。每个插件都记录了平台依赖关系。

macOS 的 Amazon Elastic Compute Cloud (Amazon EC2) 实例支持以下文档插件:

  • aws:refreshAssociation

  • aws:runShellScript

  • aws:runPowerShellScript

  • aws:softwareInventory

  • aws:updateSsmAgent

共享输入

仅在版本 3.0.502 和更高版本的 SSM Agent 中,所有插件都可以使用以下输入:

最终步骤

您希望文档运行的最后一步。如果此输入是为某个步骤定义的,则它优先于 onFailureonSuccess 输入中指定的 exit 值。为了使具有此输入的步骤按预期运行,该步骤必须是文档 mainSteps 中定义的最后一个步骤。

类型:布尔值

有效值:true | false

必需:否

onFailure

如果您为插件指定此输入的 exit 值并且步骤失败,则步骤状态会显示失败,并且文档不会运行任何剩余步骤,除非 finallyStep 已定义。如果您为插件指定此输入的 successAndExit 值并且步骤失败,则步骤状态会显示成功,并且文档不会运行任何剩余的步骤,除非 finallyStep 已定义。

类型:字符串

有效值:exit | successAndExit

必需:否

onSuccess

如果您为插件指定此输入并且步骤成功运行,则文档不会运行任何剩余的步骤,除非 finallyStep 已定义。

类型:字符串

有效值:exit

必需:否

YAML
--- schemaVersion: '2.2' description: Shared inputs example parameters: customDocumentParameter: type: String description: Example parameter for a custom Command-type document. mainSteps: - action: aws:runDocument name: runCustomConfiguration inputs: documentType: SSMDocument documentPath: "yourCustomDocument" documentParameters: '"documentParameter":{{customDocumentParameter}}' onSuccess: exit - action: aws:runDocument name: ifConfigurationFailure inputs: documentType: SSMDocument documentPath: "yourCustomRepairDocument" onFailure: exit - action: aws:runDocument name: finalConfiguration inputs: documentType: SSMDocument documentPath: "yourCustomFinalDocument" finallyStep: true
JSON
{ "schemaVersion": "2.2", "description": "Shared inputs example", "parameters": { "customDocumentParameter": { "type": "String", "description": "Example parameter for a custom Command-type document." } }, "mainSteps":[ { "action": "aws:runDocument", "name": "runCustomConfiguration", "inputs": { "documentType": "SSMDocument", "documentPath": "yourCustomDocument", "documentParameters": "\"documentParameter\":{{customDocumentParameter}}", "onSuccess": "exit" } }, { "action": "aws:runDocument", "name": "ifConfigurationFailure", "inputs": { "documentType": "SSMDocument", "documentPath": "yourCustomRepairDocument", "onFailure": "exit" } }, { "action": "aws:runDocument", "name":"finalConfiguration", "inputs": { "documentType": "SSMDocument", "documentPath": "yourCustomFinalDocument", "finallyStep": true } } ] }

aws:applications

在 EC2 实例上安装、修复或卸载应用程序。此插件仅在 Windows Server 操作系统中运行。

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:applications plugin parameters: source: description: "(Required) Source of msi." type: String mainSteps: - action: aws:applications name: example inputs: action: Install source: "{{ source }}"
JSON
{ "schemaVersion":"2.2", "description":"aws:applications", "parameters":{ "source":{ "description":"(Required) Source of msi.", "type":"String" } }, "mainSteps":[ { "action":"aws:applications", "name":"example", "inputs":{ "action":"Install", "source":"{{ source }}" } } ] }

Schema 1.2

YAML
--- runtimeConfig: aws:applications: properties: - id: 0.aws:applications action: "{{ action }}" parameters: "{{ parameters }}" source: "{{ source }}" sourceHash: "{{ sourceHash }}"
JSON
{ "runtimeConfig":{ "aws:applications":{ "properties":[ { "id":"0.aws:applications", "action":"{{ action }}", "parameters":"{{ parameters }}", "source":"{{ source }}", "sourceHash":"{{ sourceHash }}" } ] } } }

属性

action

要执行的操作。

类型:Enum

有效值:Install |Repair |Uninstall

必需:是

参数

安装程序的参数。

类型:字符串

必需:否

应用程序的 .msi 文件的 URL。

类型:字符串

必需:是

sourceHash

.msi 文件的 SHA256 哈希值。

类型:字符串

必需:否

aws:cloudWatch

从中导出数据 Windows Server 添加到 Amazon CloudWatch 视台或 Amazon CloudWatch Logs 中,并使用云监控指标监控数据。此插件仅在 Windows Server 操作系统中运行。要详细了解如何配置 CloudWatch 与 Amazon Elastic Compute Cloud(Amazon EC2)的集成,请参阅《Amazon CloudWatch 用户指南》中的使用 CloudWatch 代理收集指标、日志和跟踪信息

重要

统一的 CloudWatch 代理已取代 SSM Agent,作为将日志数据发送到 Amazon CloudWatch Logs 的工具。不支持 SSM Agent aws:cloudWatch 插件。我们建议仅将统一的 CloudWatch 代理用于您的日志收集过程。有关更多信息,请参阅以下主题:

您可以导出和监视以下数据类型:

ApplicationEventLog

将应用程序事件日志数据发送到 CloudWatch Logs。

CustomLogs

将任何基于文本的日志文件发送到 Amazon CloudWatch Logs。CloudWatch 插件会为日志文件创建指纹。系统随后将数据偏移与每个指纹进行关联。该插件会在出现更改时上传文件,记录偏移,然后将该偏移与指纹关联。此方法用于避免出现这种情况:用户启用插件后,将服务与包含大量文件的目录关联,然后系统会上传所有文件。

警告

请注意,如果应用程序在轮询期间截断或尝试清除日志,为 LogDirectoryPath 指定的任何日志都可能丢失条目。例如,如果您要限制日志文件大小,请在达到此限制时创建新的日志文件,然后继续将数据写入新文件。

ETW

将 Windows (ETW) 事件跟踪数据发送到 CloudWatch Logs。

IIS

将 IIS 日志数据发送到 CloudWatch Logs

PerformanceCounter

将 Windows 性能计数器发送到 CloudWatch。您可以选择不同类别作为指标上传到 CloudWatch。对于要上传的每个性能计数器,创建具有唯一 ID 的 PerformanceCounter 部分 (例如“PerformanceCounter2”、“PerformanceCounter3”等),然后配置其属性。

注意

如果 Amazon Systems Manager SSM Agent 或 CloudWatch 插件已停止,则性能计数器数据不再记录到 CloudWatch 中。此行为不同于自定义日志或 Windows 事件日志。自定义日志和 Windows 事件日志会保留性能计数器数据,并在 SSM Agent 后或 CloudWatch 插件可用时将其上传到 CloudWatch。

SecurityEventLog

将安全日志数据发送到 CloudWatch Logs。

SystemEventLog

将系统事件日志数据发送到 CloudWatch Logs。

可为数据定义以下目标:

CloudWatch

发送性能计数器指标数据时所在的目标。可添加具有唯一 ID 的更多部分 (例如,“CloudWatch2”和“CloudWatch3”等),并为每个新 ID 指定一个不同的区域,将相同数据发送到不同位置。

CloudWatchLogs

发送日志数据时所在的目标。可添加具有唯一 ID 的更多部分 (例如,“CloudWatchLogs2”和“CloudWatchLogs3”等),并为每个新 ID 指定一个不同的区域,将相同数据发送到不同位置。

语法

"runtimeConfig":{ "aws:cloudWatch":{ "settings":{ "startType":"{{ status }}" }, "properties":"{{ properties }}" } }

设置和属性

AccessKey

您的访问密钥 ID。如果未使用 IAM 角色启动实例,则必须指定此属性。此属性不能与 SSM 一起使用。

类型:字符串

必需:否

CategoryName

性能监视器提供的性能计数器类别。

类型:字符串

必需:是

CounterName

性能监视器提供的性能计数器名称。

类型:字符串

必需:是

CultureName

记录时间戳的区域设置。如果 CultureName 为空,则它默认为您的 Windows Server 实例所使用的相同区域位置。

类型:字符串

有效值:有关支持的值的列表,请参阅 Microsoft 网站上的国家语言支持 (NLS)。不支持 divdiv-MVhuhu-HU 值。

必需:否

DimensionName

Amazon CloudWatch 指标的维度。如果您要指定 DimensionName,则必须指定 DimensionValue。这些参数在列出指标时提供另一个视图。您可以对多个指标使用同一个维度,以便查看属于特定维度的所有指标。

类型:字符串

必需:否

DimensionValue

Amazon CloudWatch 指标的维度值。

类型:字符串

必需:否

编码

要使用的文件编码 (例如 UTF-8)。使用编码名称,而不是显示名称。

类型:字符串

有效值:有关支持的值的列表,请参阅 Microsoft Learn 库中的 Encoding Class

必需:是

筛选条件

日志名称的前缀。将此参数保留空白以监控所有文件。

类型:字符串

有效值:有关支持的值的列表,请参阅 MSDN 库中的 FileSystemWatcherFilter 属性主题。

必需:否

要上传的每个数据类型以及数据的目标(CloudWatch 或 CloudWatch Logs )。例如,要将在 "Id": "PerformanceCounter" 下定义的性能计数器发送到在 "Id": "CloudWatch" 下定义的 CloudWatch 目标,请输入 “PerformanceCounter,CloudWatch”。同样,要将自定义日志、ETW 日志和系统日志发送到 "Id": "ETW" 下定义的 CloudWatch Logs 目标,请输入 “(ETW),CloudWatchLogs”。此外,还可以将相同性能计数器或日志文件发送到多个目标。例如,要将应用程序日志发送到在 "Id": "CloudWatchLogs""Id": "CloudWatchLogs2" 下定义的两个不同目标,请输入 "ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)"

类型:字符串

有效值 (源):ApplicationEventLog | CustomLogs | ETW | PerformanceCounter | SystemEventLog | SecurityEventLog

有效值 (目标):CloudWatch | CloudWatchLogs | CloudWatchn | CloudWatchLogsn

必需:是

FullName

组件的完整名称。

类型:字符串

必需:是

Id

标识数据源或目标。此标识符在配置文件中必须是唯一的。

类型:字符串

必需:是

InstanceName

性能计数器实例的名称。请勿使用星号 (*) 标识所有实例,因为每个性能计数器组件仅支持一个指标。不过可以使用 _Total

类型:字符串

必需:是

级别

发送到 Amazon CloudWatch 的消息类型。

类型:字符串

有效值:

  • 1 – 仅上传错误消息。

  • 2 – 仅上传警告消息。

  • 4 – 仅上传信息消息。

您可以将这些值加在一起以包含多种类型的消息。例如,3 表示将包含错误消息 (1) 和警告消息 (2)。值 7 表示将包含错误消息 (1)、警告消息 (2) 和说明性消息 (4)。

必需:是

注意

应将 Windows 安全日志的级别设置为 7。

LineCount

标识日志文件的标头中的行数。例如,IIS 日志文件拥有几乎相同的标头。您可以输入 3,系统会读取日志文件标头的前三行以进行识别。在 IIS 日志文件中,第三行是日期和时间戳,各日志文件的日期和时间戳互不相同。

类型:整数

必需:否

LogDirectoryPath

对于 CustomLogs,这是日志在 EC2 实例上的存储路径。对于 IIS 日志,这是为单个站点存储 IIS 日志的文件夹 (例如 C:\\inetpub\\logs\\LogFiles\\W3SVCn)。对于 IIS 日志,仅支持 W3C 日志格式。不支持 IIS、NCSA 和自定义格式。

类型:字符串

必需:是

LogGroup

日志组的名称。此名称显示在 CloudWatch 控制台的 Log Groups(日志组)屏幕上。

类型:字符串

必需:是

LogName

日志文件的名称。

  1. 要查找日志的名称,请在事件查看器的导航窗格中,选择 Applications and Services Logs (应用程序和服务日志)

  2. 在日志列表中,右键单击要上传的日志 (例如“Microsoft>Windows>备份>可操作”),然后选择创建自定义视图

  3. Create Custom View (创建自定义视图) 对话框中,选择 XML 选项卡。LogName 位于 <Select Path=> 标签中(例如 Microsoft-Windows-Backup)。将此文本复制到 LogName 参数。

类型:字符串

有效值:Application | Security | System | Microsoft-Windows-WinINet/Analytic

必需:是

LogStream

目标日志流。如果使用默认值 {instance_id},则将该实例的实例 ID 用作日志流名称。

类型:字符串

有效值:{instance_id} | {hostname} | {ip_address} <log_stream_name>

如果输入的日志流名称不存在,则 CloudWatch Logs 会自动创建该名称。可以使用文字字符串或预定义的变量({instance_id}{hostname}{ip_address}),或所有这三个变量的组合来定义日志流名称。

此参数中指定的日志流名称将在 CloudWatch 控制台中的 Log Groups > Streams for <YourLogStream>(日志组 > <YourLogStream> 的流)屏幕上显示。

必需:是

MetricName

您希望性能数据包含在其下的 CloudWatch 指标。

注意

不要在名称中使用特殊字符。如果您这样做,指标和相关警报可能无法正常工作。

类型:字符串

必需:是

NameSpace

您希望将写入性能计数器数据的指标命名空间。

类型:字符串

必需:是

PollInterval

必须在多少秒之后才能上传新性能计数器和日志数据。

类型:整数

有效值:将其设置为 5 秒或 5 秒以上。建议设置为十五秒 (00:00:15)。

必需:是

区域

要发送日志数据的 Amazon Web Services 区域。虽然可以将性能计数器发送到与日志数据发送目标不同的区域,但是我们建议您将此参数设置为运行实例的区域。

类型:字符串

有效值:Systems Manager 和 CloudWatch Logs 都支持的 Amazon Web Services 区域 区域ID,例如 us-east-2eu-west-1, 和 ap-southeast-1。对于每个服务支持的 Amazon Web Services 区域 的列表,请参阅《Amazon Web Services 一般参考》中的 Amazon CloudWatch Logs Service EndpointsSystems Manager service endpoints

必需:是

SecretKey

您的秘密访问密钥。如果未使用 IAM 角色启动实例,则必须指定此属性。

类型:字符串

必需:否

startType

打开或关闭实例上的 CloudWatch 功能。

类型:字符串

有效值:Enabled | Disabled

必需:是

TimestampFormat

要使用的时间戳格式。有关支持的值的列表,请参阅 MSDN 库中的自定义日期和时间格式字符串

类型:字符串

必需:是

TimeZoneKind

在日志时间戳中不包含时区信息时提供时区信息。如果此参数留空且时间戳不包括时区信息,则 CloudWatch Logs 默认为本地时区。如果时间戳已包含时区信息,则忽略此参数。

类型:字符串

有效值:Local | UTC

必需:否

单位

适当的指标计量单位。

类型:字符串

有效值:秒 | 微秒 | 毫秒 | 字节 | 千字节 | 兆字节 | 千兆字节 | 太兆字节 | 位 | 千位 | 兆位 | 千兆位 | 太兆位 | 百分比 | 计数 | 字节/秒 | 千字节/秒 | 兆字节/秒 | 千兆字节/秒 | 太兆字节/秒 | 位/秒 | 千位/秒 | 兆位/秒 | 千兆位/秒 | 太兆位/秒 | 计数/秒 | 无

必需:是

aws:configureDocker

(2.0 版或更高版本架构) 将实例配置为使用容器和 Docker。此插件在 Linux 和 Windows Server 操作系统中受支持。

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:configureDocker parameters: action: description: "(Required) The type of action to perform." type: String default: Install allowedValues: - Install - Uninstall mainSteps: - action: aws:configureDocker name: configureDocker inputs: action: "{{ action }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:configureDocker plugin", "parameters": { "action": { "description": "(Required) The type of action to perform.", "type": "String", "default": "Install", "allowedValues": [ "Install", "Uninstall" ] } }, "mainSteps": [ { "action": "aws:configureDocker", "name": "configureDocker", "inputs": { "action": "{{ action }}" } } ] }

输入

action

要执行的操作类型。

类型:Enum

有效值:Install | Uninstall

必需:是

aws:configurePackage

(2.0 版或更高版本架构)安装或卸载 Amazon Systems Manager Distributor 程序包。您可以安装所指定软件包的最新版本、默认版本或其中一个版本。Amazon 提供的软件包也受支持。此插件可在 Windows Server 和 Linux 操作系统上运行,但 Linux 操作系统不支持所有可用的软件包。

Windows Server 的可用 Amazon 程序包包括:AWSPVDriverAWSNVMeAwsEnaNetworkDriverAwsVssComponentsAmazonCloudWatchAgentCodeDeployAgent,和 AWSSupport-EC2Rescue.

适用于 Linux 操作系统的可用 Amazon 软件包包括:AmazonCloudWatchAgentCodeDeployAgent,和 AWSSupport-EC2Rescue

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:configurePackage parameters: name: description: "(Required) The name of the AWS package to install or uninstall." type: String action: description: "(Required) The type of action to perform." type: String default: Install allowedValues: - Install - Uninstall ssmParameter: description: "(Required) Argument stored in Parameter Store." type: String default: "{{ ssm:parameter_store_arg }}" mainSteps: - action: aws:configurePackage name: configurePackage inputs: name: "{{ name }}" action: "{{ action }}" additionalArguments: "{\"SSM_parameter_store_arg\": \"{{ ssmParameter }}\", \"SSM_custom_arg\": \"myValue\"}"
JSON
{ "schemaVersion": "2.2", "description": "aws:configurePackage", "parameters": { "name": { "description": "(Required) The name of the AWS package to install or uninstall.", "type": "String" }, "action": { "description": "(Required) The type of action to perform.", "type": "String", "default": "Install", "allowedValues": [ "Install", "Uninstall" ] }, "ssmParameter": { "description": "(Required) Argument stored in Parameter Store.", "type": "String", "default": "{{ ssm:parameter_store_arg }}" } }, "mainSteps": [ { "action": "aws:configurePackage", "name": "configurePackage", "inputs": { "name": "{{ name }}", "action": "{{ action }}", "additionalArguments": "{\"SSM_parameter_store_arg\": \"{{ ssmParameter }}\", \"SSM_custom_arg\": \"myValue\"}" } } ] }

输入

name

要安装或卸载的 Amazon 软件包名称。可用的软件包如下所述:AWSPVDriverAwsEnaNetworkDriverAwsVssComponents,和 AmazonCloudWatchAgent

类型:字符串

必需:是

action

安装或卸载软件包。

类型:Enum

有效值:Install | Uninstall

必需:是

安装类型

要执行的安装类型。如果指定 Uninstall and reinstall,该软件包将完全卸载,然后重新安装。在重新安装完成之前,应用程序不可用。如果指定 In-place update,将根据您在更新脚本中提供的指令,仅将新文件或更改的文件添加到现有的安装中。应用程序在整个更新过程中保持可用。这些区域有:已发布的软件包 Amazon 不支持 In-place update 选项。Uninstall and reinstall 为默认值。

类型:Enum

有效值:Uninstall and reinstall | In-place update

必需:否

附加参数

为安装、卸载或更新脚本提供的其他参数的 JSON 字符串。每个参数的前缀必须为 SSM_。可以使用约定 {{ssm:parameter-name}} 在附加参数中引用 Parameter Store 参数。要在安装、卸载或更新脚本过程中使用附加参数,必须使用适合操作系统的语法将参数作为环境变量引用。例如,在 PowerShell 中,您引用 SSM_arg 参数为 $Env:SSM_arg。您定义的参数数量没有限制,但附加参数输入有 4096 个字符限制。此限制包括您定义的所有秘钥和值。

类型:StringMap

必需:否

版本

要卸载或安装的特定版本的软件包。如果要安装,系统默认安装最新发布的版本。如果要卸载,系统默认卸载当前安装的版本。如果没有找到已安装的版本,则会下载最新发布的版本,然后运行卸载操作。

类型:字符串

必需:否

aws:domainJoin

将 EC2 实例加入域。此插件在 Linux 和 Windows Server 操作系统上运行。该插件会将 Linux 实例的主机名更改为 EC2AMAZ-XXXXXXX 格式。有关加入 EC2 实例的更多信息,请参阅 Amazon Directory Service 管理指南中的将 EC2 实例加入到 Amazon 托管 Microsoft AD 目录

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:domainJoin parameters: directoryId: description: "(Required) The ID of the directory." type: String directoryName: description: "(Required) The name of the domain." type: String directoryOU: description: "(Optional) The organizational unit to assign the computer object to." type: String dnsIpAddresses: description: "(Required) The IP addresses of the DNS servers for your directory." type: StringList mainSteps: - action: aws:domainJoin name: domainJoin inputs: directoryId: "{{ directoryId }}" directoryName: "{{ directoryName }}" directoryOU: "{{ directoryOU }}" dnsIpAddresses: "{{ dnsIpAddresses }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:domainJoin", "parameters": { "directoryId": { "description": "(Required) The ID of the directory.", "type": "String" }, "directoryName": { "description": "(Required) The name of the domain.", "type": "String" }, "directoryOU": { "description": "(Optional) The organizational unit to assign the computer object to.", "type": "String" }, "dnsIpAddresses": { "description": "(Required) The IP addresses of the DNS servers for your directory.", "type": "StringList" }, }, "mainSteps": [ { "action": "aws:domainJoin", "name": "domainJoin", "inputs": { "directoryId": "{{ directoryId }}", "directoryName": "{{ directoryName }}", "directoryOU":"{{ directoryOU }}", "dnsIpAddresses":"{{ dnsIpAddresses }}" } } ] }

Schema 1.2

YAML
--- runtimeConfig: aws:domainJoin: properties: directoryId: "{{ directoryId }}" directoryName: "{{ directoryName }}" directoryOU: "{{ directoryOU }}" dnsIpAddresses: "{{ dnsIpAddresses }}"
JSON
{ "runtimeConfig":{ "aws:domainJoin":{ "properties":{ "directoryId":"{{ directoryId }}", "directoryName":"{{ directoryName }}", "directoryOU":"{{ directoryOU }}", "dnsIpAddresses":"{{ dnsIpAddresses }}" } } } }

属性

directoryId

目录的 ID。

类型:字符串

必需:是

示例:"directoryId": "d-1234567890"

directoryName

域的名称。

类型:字符串

必需:是

示例:"directoryName": "example.com"

directoryOU

组织部门 (OU)。

类型:字符串

必需:否

示例:"directoryOU": "OU=test,DC=example,DC=com"

dnsIpAddresses

DNS 服务器的 IP 地址。

类型:StringList

必需:是

示例:"dnsIpAddresses": ["198.51.100.1","198.51.100.2"]

keepHostName

确定 Linux 实例在加入域时是否更改主机名。

类型:布尔值

必需:否

示例

有关示例,请参阅《Amazon Directory Service 管理指南》中的将 Amazon EC2 实例加入您的 Amazon Managed Microsoft AD

aws:downloadContent

(2.0 版或更高版本架构)从远程位置下载 SSM 文档和脚本。不支持 GitHub Enterprise 存储库。此插件在 Linux 和 Windows Server 操作系统中受支持。

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:downloadContent parameters: sourceType: description: "(Required) The download source." type: String sourceInfo: description: "(Required) The information required to retrieve the content from the required source." type: StringMap mainSteps: - action: aws:downloadContent name: downloadContent inputs: sourceType: "{{ sourceType }}" sourceInfo: "{{ sourceInfo }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:downloadContent", "parameters": { "sourceType": { "description": "(Required) The download source.", "type": "String" }, "sourceInfo": { "description": "(Required) The information required to retrieve the content from the required source.", "type": "StringMap" } }, "mainSteps": [ { "action": "aws:downloadContent", "name": "downloadContent", "inputs": { "sourceType":"{{ sourceType }}", "sourceInfo":"{{ sourceInfo }}" } } ] }

输入

sourceType

下载源 Systems Manager 支持以下下载脚本和 SSM 文档的源类型:GitHubGitHTTPS3,和SSMDocument

类型:字符串

必需:是

sourceInfo

从所需源检索内容所需的信息。

类型:StringMap

必需:是

对于 sourceType GitHub,,请指定以下内容:

  • owner:存储库所有者。

  • repository:存储库的名称。

  • path:您要下载的文件或目录所在的路径。

  • getOptions:用于从分支(而非主分支)或存储库中的特定提交中检索内容的额外选项。如果您在主分支中使用最新提交,则可以省略 getOptions。如果您的存储库是在 2020 年 10 月 1 日之后创建的,则默认分支可能被命名为 main 而不是 master。在这种情况下,需要为 getOptions 参数指定值。

    此参数采用以下格式:

    • branch:refs/heads/branch_name

      默认为 master

      要指定非默认分支,请使用以下格式:

      branch:refs/heads/branch_name

    • commitID:commitID

      默认为 head

      要在最新提交以外的提交中使用 SSM 文档的版本,请指定完整的提交 ID。例如:

      "getOptions": "commitID:bbc1ddb94...b76d3bEXAMPLE",
  • tokenInfo:以 {{ssm-secure:secure-string-token-name}} 格式存储 GitHub 访问令牌信息的 Systems Manager 参数(SecureString 参数)。

    注意

    tokenInfo 字段是唯一支持 SecureString 参数的 SSM 文档插件字段。任何其他字段和任何其他 SSM 文档插件都不支持 SecureString 参数。

{ "owner":"TestUser", "repository":"GitHubTest", "path":"scripts/python/test-script", "getOptions":"branch:master", "tokenInfo":"{{ssm-secure:secure-string-token}}" }

对于 sourceType Git,必须指定以下内容:

  • 存储库

    path:要下载的文件或目录的 Git repository URL。

    类型:字符串

此外,您可以指定以下任何可选参数:

  • getOptions

    用于从分支(而非主分支)或存储库中的特定提交中检索内容的额外选项。如果您在主分支中使用最新提交,则可以省略 getOptions。

    类型:字符串

    此参数采用以下格式:

    • branch:refs/heads/branch_name

      默认为 master

      仅当您的 SSM 文档存储在 master 以外的分支中时, "branch" 才是必需的。例如:

      "getOptions": "branch:refs/head/main"
    • commitID:commitID

      默认为 head

      要在最新提交以外的提交中使用 SSM 文档的版本,请指定完整的提交 ID。例如:

      "getOptions": "commitID:bbc1ddb94...b76d3bEXAMPLE",
  • privateSSHKey

    连接指定的repository 时要使用的 SSH 秘钥。可以使用以下格式为引用 SSH 密钥值 SecureString 参数:{{ssm-secure:your-secure-string-parameter}}

    类型:字符串

  • 跳过主机键检查

    确定连接到您指定的 repository 时 StrictHostKeyChecking 选项的值。默认值为 false

    类型:布尔值

  • username

    连接到使用 HTTP 指定的 repository 时使用的用户名。可以使用以下格式引用用户名值的 SecureString 参数:{{ssm-secure:your-secure-string-parameter}}

    类型:字符串

  • password

    连接到使用 HTTP 指定的 repository 时使用的密码。可以使用以下格式为引用密码值 SecureString 参数:{{ssm-secure:your-secure-string-parameter}}

    类型:字符串

对于 sourceTypeHTTP,必须指定以下内容:

  • url

    要下载的文件或目录的 URL。

    类型:字符串

此外,您可以指定以下任何可选参数:

  • allowInsecureDownload

    确定是否可以通过未使用安全套接字层 (SSL) 或传输层安全 (TLS) 加密的连接执行下载。默认值为 false。我们建议您不要在未加密的情况下执行下载。如果您选择这样做,您将承担所有相关风险。安全性是 Amazon 和您的共同责任。这被描述为责任共担共担模式。要了解更多信息,请参阅责任共担模式

    类型:布尔值

  • authMethod

    确定在连接到指定的 url 时是否要使用用户名和密码。如果指定 Basic 或者 Digest 时,您必须为 usernamepassword 参数提供值。使用 Digest 方法,3.0.1181.0 版本或更高版本的 SSM Agent 必须安装在实例上。Digest 方法支持 MD5 和 SHA256 加密。

    类型:字符串

    有效值:None |Basic |Digest

  • username

    连接到 url 您指定使用 Basic 身份验证。可以使用以下格式引用用户名值的 SecureString 参数:{{ssm-secure:your-secure-string-parameter}}

    类型:字符串

  • password

    连接到您使用 Basic 身份验证指定的 url 时使用的密码。可以使用以下格式为引用密码值 SecureString 参数:{{ssm-secure:your-secure-string-parameter}}

    类型:字符串

对于 sourceType S3,请指定以下内容:

  • 路径:要从 Amazon S3 下载的文件或目录的 URL。

{ "path": "https://s3.amazonaws.com/amzn-s3-demo-bucket/powershell/helloPowershell.ps1" }

对于 SourceType SSMDocument,请指定以下其中 项:

  • 名称:采用以下格式的文档的名称和版本:name:version。版本为可选项。

    { "name": "Example-RunPowerShellScript:3" }
  • name:采用以下格式的文档 ARN:arn:aws:ssm:region:account_id:document/document_name

    { "name":"arn:aws:ssm:us-east-2:3344556677:document/MySharedDoc" }
destinationPath

实例上的可选本地路径,用于下载文件。如果不指定路径,内容将下载到命令 ID 的相对路径。

类型:字符串

必需:否

aws:psModule

在 Amazon EC2 实例上安装 PowerShell 模块。此插件仅在 Windows Server 操作系统中运行。

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:psModule parameters: source: description: "(Required) The URL or local path on the instance to the application .zip file." type: String mainSteps: - action: aws:psModule name: psModule inputs: source: "{{ source }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:psModule", "parameters": { "source": { "description": "(Required) The URL or local path on the instance to the application .zip file.", "type": "String" } }, "mainSteps": [ { "action": "aws:psModule", "name": "psModule", "inputs": { "source": "{{ source }}" } } ] }

Schema 1.2

YAML
--- runtimeConfig: aws:psModule: properties: - runCommand: "{{ commands }}" source: "{{ source }}" sourceHash: "{{ sourceHash }}" workingDirectory: "{{ workingDirectory }}" timeoutSeconds: "{{ executionTimeout }}"
JSON
{ "runtimeConfig":{ "aws:psModule":{ "properties":[ { "runCommand":"{{ commands }}", "source":"{{ source }}", "sourceHash":"{{ sourceHash }}", "workingDirectory":"{{ workingDirectory }}", "timeoutSeconds":"{{ executionTimeout }}" } ] } } }

属性

runCommand

安装模块后要运行的 PowerShell 命令。

类型:StringList

必需:否

访问实例上应用程序 .zip 文件的 URL 或本地路径。

类型:字符串

必需:是

sourceHash

.zip 文件的 SHA256 哈希值。

类型:字符串

必需:否

timeoutSeconds

在被视为已失败前命令将运行的时间 (以秒为单位)。

类型:字符串

必需:否

workingDirectory

实例上工作目录的路径。

类型:字符串

必需:否

aws:refreshAssociation

(2.0 版或更高版本架构) 按需刷新 (强制应用) 关联。此操作将根据所选关联或绑定到目标的所有关联中定义的内容来更改系统状态。此插件仅在 Linux 和 Windows Server 操作系统上运行。

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:refreshAssociation parameters: associationIds: description: "(Optional) List of association IDs. If empty, all associations bound to the specified target are applied." type: StringList mainSteps: - action: aws:refreshAssociation name: refreshAssociation inputs: associationIds: - "{{ associationIds }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:refreshAssociation", "parameters": { "associationIds": { "description": "(Optional) List of association IDs. If empty, all associations bound to the specified target are applied.", "type": "StringList" } }, "mainSteps": [ { "action": "aws:refreshAssociation", "name": "refreshAssociation", "inputs": { "associationIds": [ "{{ associationIds }}" ] } } ] }

输入

associationIds

关联 ID 的列表。如果为空,则应用与指定目标绑定的所有关联。

类型:StringList

必需:否

aws:runDockerAction

(2.0 版或更高版本架构)在容器上运行 Docker 操作。此插件仅在 Linux 和 Windows Server 操作系统上运行。

语法

Schema 2.2

YAML
--- mainSteps: - action: aws:runDockerAction name: RunDockerAction inputs: action: "{{ action }}" container: "{{ container }}" image: "{{ image }}" memory: "{{ memory }}" cpuShares: "{{ cpuShares }}" volume: "{{ volume }}" cmd: "{{ cmd }}" env: "{{ env }}" user: "{{ user }}" publish: "{{ publish }}"
JSON
{ "mainSteps":[ { "action":"aws:runDockerAction", "name":"RunDockerAction", "inputs":{ "action":"{{ action }}", "container":"{{ container }}", "image":"{{ image }}", "memory":"{{ memory }}", "cpuShares":"{{ cpuShares }}", "volume":"{{ volume }}", "cmd":"{{ cmd }}", "env":"{{ env }}", "user":"{{ user }}", "publish":"{{ publish }}" } } ] }

输入

action

要执行的操作类型。

类型:字符串

必需:是

容器

Docker 容器 ID。

类型:字符串

必需:否

映像

Docker 映像名称。

类型:字符串

必需:否

cmd

容器命令。

类型:字符串

必需:否

memory

容器内存限制。

类型:字符串

必需:否

cpuShares

容器 CPU 份额 (相对权重)。

类型:字符串

必需:否

volume

容器卷挂载。

类型:StringList

必需:否

env

容器的环境变量。

类型:字符串

必需:否

用户

容器的用户名。

类型:字符串

必需:否

发布

容器已发布端口。

类型:字符串

必需:否

aws:runDocument

(2.0 版或更高版本架构)运行存储在 Systems Manager 或本地共享存储中的 SSM 文档。您可以将此插件与 aws:downloadContent 插件配合使用,以将远程位置的 SSM 文档下载到本地共享存储,然后运行该文档。此插件在 Linux 和 Windows Server 操作系统中受支持。此插件不支持运行 AWS-UpdateSSMAgent 文档或使用 aws:updateSsmAgent 插件的任何文档。

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:runDocument parameters: documentType: description: "(Required) The document type to run." type: String allowedValues: - LocalPath - SSMDocument mainSteps: - action: aws:runDocument name: runDocument inputs: documentType: "{{ documentType }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:runDocument", "parameters": { "documentType": { "description": "(Required) The document type to run.", "type": "String", "allowedValues": [ "LocalPath", "SSMDocument" ] } }, "mainSteps": [ { "action": "aws:runDocument", "name": "runDocument", "inputs": { "documentType": "{{ documentType }}" } } ] }

输入

documentType

要运行的文档类型。您可以运行本地文档 (LocalPath) 或存储在 Systems Manager (SSMDocument) 中的文档。

类型:字符串

必需:是

documentPath

文档的路径。如果 documentTypeLocalPath,则指定本地共享存储上文档的路径。如果 documentTypeSSMDocument,则指定文档的名称。

类型:字符串

必需:否

documentParameters

文档的参数。

类型:StringMap

必需:否

aws:runPowerShellScript

运行 PowerShell 脚本或者指定要运行的脚本的路径。此插件在 Microsoft Windows Server 和 Linux 操作系统上运行。

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:runPowerShellScript parameters: commands: type: String description: "(Required) The commands to run or the path to an existing script on the instance." default: Write-Host "Hello World" mainSteps: - action: aws:runPowerShellScript name: runPowerShellScript inputs: timeoutSeconds: '60' runCommand: - "{{ commands }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:runPowerShellScript", "parameters": { "commands": { "type": "String", "description": "(Required) The commands to run or the path to an existing script on the instance.", "default": "Write-Host \"Hello World\"" } }, "mainSteps": [ { "action": "aws:runPowerShellScript", "name": "runPowerShellScript", "inputs": { "timeoutSeconds": "60", "runCommand": [ "{{ commands }}" ] } } ] }

Schema 1.2

YAML
--- runtimeConfig: aws:runPowerShellScript: properties: - id: 0.aws:runPowerShellScript runCommand: "{{ commands }}" workingDirectory: "{{ workingDirectory }}" timeoutSeconds: "{{ executionTimeout }}"
JSON
{ "runtimeConfig":{ "aws:runPowerShellScript":{ "properties":[ { "id":"0.aws:runPowerShellScript", "runCommand":"{{ commands }}", "workingDirectory":"{{ workingDirectory }}", "timeoutSeconds":"{{ executionTimeout }}" } ] } } }

属性

runCommand

指定要运行的命令或实例上现有脚本的路径。

类型:StringList

必需:是

timeoutSeconds

在被视为已失败前命令将运行的时间(以秒为单位)。如果达到超时,Systems Manager 停止命令执行。

类型:字符串

必需:否

workingDirectory

实例上工作目录的路径。

类型:字符串

必需:否

aws:runShellScript

运行 Linux shell 脚本或者指定要运行的脚本的路径。此插件仅在 Linux 操作系统中运行。

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:runShellScript parameters: commands: type: String description: "(Required) The commands to run or the path to an existing script on the instance." default: echo Hello World mainSteps: - action: aws:runShellScript name: runShellScript inputs: timeoutSeconds: '60' runCommand: - "{{ commands }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:runShellScript", "parameters": { "commands": { "type": "String", "description": "(Required) The commands to run or the path to an existing script on the instance.", "default": "echo Hello World" } }, "mainSteps": [ { "action": "aws:runShellScript", "name": "runShellScript", "inputs": { "timeoutSeconds": "60", "runCommand": [ "{{ commands }}" ] } } ] }

Schema 1.2

YAML
--- runtimeConfig: aws:runShellScript: properties: - runCommand: "{{ commands }}" workingDirectory: "{{ workingDirectory }}" timeoutSeconds: "{{ executionTimeout }}"
JSON
{ "runtimeConfig":{ "aws:runShellScript":{ "properties":[ { "runCommand":"{{ commands }}", "workingDirectory":"{{ workingDirectory }}", "timeoutSeconds":"{{ executionTimeout }}" } ] } } }

属性

runCommand

指定要运行的命令或实例上现有脚本的路径。

类型:StringList

必需:是

timeoutSeconds

在被视为已失败前命令将运行的时间(以秒为单位)。如果达到超时,Systems Manager 停止命令执行。

类型:字符串

必需:否

workingDirectory

实例上工作目录的路径。

类型:字符串

必需:否

aws:softwareInventory

(2.0 版或更高版本架构)收集有关托管实例上应用程序、文件和配置的元数据。此插件仅在 Linux 和 Windows Server 操作系统上运行。在配置清单收集时,应该首先创建 Amazon Systems Manager State Manager 关联。Systems Manager 会在关联运行时收集清单数据。如果您不先创建关联,并试图调用 aws:softwareInventory 插件,则系统会返回以下错误:

The aws:softwareInventory plugin can only be invoked via ssm-associate.

一个实例一次只能配置一个清单关联。如果您为一个实例配置了两个或更多关联,则清单关联不会运行,而且系统不会收集清单数据。有关收集文件清单的更多信息,请参阅 Amazon Systems Manager 清单

语法

Schema 2.2

YAML
--- mainSteps: - action: aws:softwareInventory name: collectSoftwareInventoryItems inputs: applications: "{{ applications }}" awsComponents: "{{ awsComponents }}" networkConfig: "{{ networkConfig }}" files: "{{ files }}" services: "{{ services }}" windowsRoles: "{{ windowsRoles }}" windowsRegistry: "{{ windowsRegistry}}" windowsUpdates: "{{ windowsUpdates }}" instanceDetailedInformation: "{{ instanceDetailedInformation }}" customInventory: "{{ customInventory }}"
JSON
{ "mainSteps":[ { "action":"aws:softwareInventory", "name":"collectSoftwareInventoryItems", "inputs":{ "applications":"{{ applications }}", "awsComponents":"{{ awsComponents }}", "networkConfig":"{{ networkConfig }}", "files":"{{ files }}", "services":"{{ services }}", "windowsRoles":"{{ windowsRoles }}", "windowsRegistry":"{{ windowsRegistry}}", "windowsUpdates":"{{ windowsUpdates }}", "instanceDetailedInformation":"{{ instanceDetailedInformation }}", "customInventory":"{{ customInventory }}" } } ] }

输入

applications

(可选)收集已安装应用程序的元数据。

类型:字符串

必需:否

awsComponents

(可选)收集Amazon 组件(例如 amazon-ssm-agent)的元数据。

类型:字符串

必需:否

文件

(可选,需要 2.2.64.0 版本或更高版本的 SSM Agent )收集文件的元数据,包括文件名称、文件创建时间、文件上次修改和访问时间以及文件大小等等。有关收集文件清单的更多信息,请参阅 使用文件和 Windows 注册表清单

类型:字符串

必需:否

networkConfig

(可选)收集网络配置的元数据。

类型:字符串

必需:否

windowsUpdates

(可选)收集所有 Windows 更新的元数据。

类型:字符串

必需:否

instanceDetailedInformation

(可选)收集多于默认清单插件 (aws:instanceInformation)提供的信息的实例信息,包括 CPU 型号、速度和核心数量,等等。

类型:字符串

必需:否

服务

(可选,仅限 Windows 操作系统,需要 2.2.64.0 版本或更高版本的SSM Agent )收集服务配置的元数据。

类型:字符串

必需:否

windowsRegistry

(可选,仅限 Windows 操作系统,需要 2.2.64.0 版本或更高版本的SSM Agent)收集 Windows 注册表项和值。您可以选择一个键路径并以递归方式收集所有键和值。您还可以收集特定路径的特定注册表项及其值。清单会收集键路径、名称、类型和值。有关收集 Windows 注册表清单的更多信息,请参阅 使用文件和 Windows 注册表清单

类型:字符串

必需:否

windowsRoles

(可选,仅限 Windows 操作系统,需要 2.2.64.0 版本或更高版本的 SSM Agent )收集 Microsoft Windows 角色配置的元数据。

类型:字符串

必需:否

customInventory

(可选)收集自定义清单数据。有关自定义清单的更多信息,请参阅 使用自定义清单

类型:字符串

必需:否

aws:updateAgent

此命令可将 EC2Config 服务更新为最新版本或指定较旧版本。此插件仅在 Microsoft Windows Server 操作系统上运行。有关 EC2Config 服务的更多信息,请参阅《Amazon EC2 用户指南》中的使用 EC2Config 服务配置 Windows 实例(旧版)

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:updateAgent mainSteps: - action: aws:updateAgent name: updateAgent inputs: agentName: Ec2Config source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json
JSON
{ "schemaVersion": "2.2", "description": "aws:updateAgent", "mainSteps": [ { "action": "aws:updateAgent", "name": "updateAgent", "inputs": { "agentName": "Ec2Config", "source": "https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json" } } ] }

Schema 1.2

YAML
--- runtimeConfig: aws:updateAgent: properties: agentName: Ec2Config source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json allowDowngrade: "{{ allowDowngrade }}" targetVersion: "{{ version }}"
JSON
{ "runtimeConfig":{ "aws:updateAgent":{ "properties":{ "agentName":"Ec2Config", "source":"https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json", "allowDowngrade":"{{ allowDowngrade }}", "targetVersion":"{{ version }}" } } } }

属性

agentName

EC2Config。这是运行 EC2Config 服务的代理的名称。

类型:字符串

必需:是

allowDowngrade

允许将 EC2Config 服务降级为早期版本。如果设置为 False,则只能将该服务升级为更新的版本 (默认)。如果设置为 True,则指定早期版本。

类型:布尔值

必需:否

Systems Manager 复制要安装的 EC2Config 版本的位置。您无法更改此位置。

类型:字符串

必需:是

targetVersion

要安装的特定版本的 EC2Config 服务。如果未指定,服务将更新到最新版本。

类型:字符串

必需:否

aws:updateSsmAgent

将 SSM Agent 更新到最新版本或指定较旧版本。此插件在 Linux 和 Windows Server 操作系统上运行。有关更多信息,请参阅 使用 SSM Agent

语法

Schema 2.2

YAML
--- schemaVersion: '2.2' description: aws:updateSsmAgent parameters: allowDowngrade: default: 'false' description: "(Optional) Allow the Amazon SSM Agent service to be downgraded to an earlier version. If set to false, the service can be upgraded to newer versions only (default). If set to true, specify the earlier version." type: String allowedValues: - 'true' - 'false' mainSteps: - action: aws:updateSsmAgent name: updateSSMAgent inputs: agentName: amazon-ssm-agent source: https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json allowDowngrade: "{{ allowDowngrade }}"
JSON
{ "schemaVersion": "2.2", "description": "aws:updateSsmAgent", "parameters": { "allowDowngrade": { "default": "false", "description": "(Required) Allow the Amazon SSM Agent service to be downgraded to an earlier version. If set to false, the service can be upgraded to newer versions only (default). If set to true, specify the earlier version.", "type": "String", "allowedValues": [ "true", "false" ] } }, "mainSteps": [ { "action": "aws:updateSsmAgent", "name": "awsupdateSsmAgent", "inputs": { "agentName": "amazon-ssm-agent", "source": "https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json", "allowDowngrade": "{{ allowDowngrade }}" } } ] }

Schema 1.2

YAML
--- runtimeConfig: aws:updateSsmAgent: properties: - agentName: amazon-ssm-agent source: https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json allowDowngrade: "{{ allowDowngrade }}"
JSON
{ "runtimeConfig":{ "aws:updateSsmAgent":{ "properties":[ { "agentName":"amazon-ssm-agent", "source":"https://s3.{Region}.amazonaws.com/aws-ssm-{Region}/manifest.json", "allowDowngrade":"{{ allowDowngrade }}" } ] } } }

属性

agentName

amazon-ssm-agent。这是在实例上处理请求并运行命令的 Systems Manager agent 的名称。

类型:字符串

必需:是

allowDowngrade

允许将 SSM Agent 降级为早期版本。如果设置为 False,则只能将该代理升级为更新的版本 (默认)。如果设置为 True,则指定早期版本。

类型:布尔值

必需:是

复制 Systems Manager 要安装的 SSM Agent 版本的位置。您无法更改此位置。

类型:字符串

必需:是

targetVersion

要安装的特定版本的 SSM Agent。如果未指定,代理将更新到最新版本。

类型:字符串

必需:否