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

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

会话文档架构

以下信息介绍了会话文档的架构元素。Amazon Systems Manager Session Manager 使用会话文档来确定要启动哪些类型的会话,例如标准会话、端口转发会话或运行交互式命令的会话。

schemaVersion

会话文档的架构版本。会话文档仅支持版本 1.0。

类型:字符串

必需:是

description

为会话文档指定的描述。例如,“用于启动与 Session Manager 的端口转发会话的文档”。

类型:字符串

必需:否

sessionType

会话文档用于建立的会话类型。

类型:字符串

必需:是

有效值:InteractiveCommands | NonInteractiveCommands | Port | Standard_Stream

inputs

用于使用此会话文档建立的会话的会话首选项。用于创建 Standard_Stream 会话的会话文档需要此元素。

类型:StringMap

必需:否

s3BucketName

您希望在会话结束时将会话日志发送到的 Amazon Simple Storage Service (Amazon S3) 存储桶。

类型:字符串

必需:否

s3KeyPrefix

将日志发送到您在输入 s3BucketName 时指定的 Amazon S3 存储桶时使用的前缀。有关对 Amazon S3 中存储的对象使用共享前缀的更多信息,请参阅 Amazon Simple Storage Service 用户指南中的如何在 S3 存储桶中使用文件夹?

类型:字符串

必需:否

s3EncryptionEnabled

如果设置为 true,则输入 s3BucketName 时指定的 Amazon S3 存储桶必须进行加密。

类型:布尔值

必需:是

cloudWatchLogGroupName

您希望在会话结束时将会话日志发送到的 Amazon CloudWatch Logs (CloudWatch Logs) 组名称。

类型:字符串

必需:否

cloudWatchEncryptionEnabled

如果设置为 true,则输入 cloudWatchLogGroupName 时指定的日志组必须进行加密。

类型:布尔值

必需:是

cloudWatchStreamingEnabled

如果设置为 true,会话数据日志流将持续发送到您在输入 cloudWatchLogGroupName 时指定的日志组。如果设置为 false,会话日志将在会话结束时发送到您在输入 cloudWatchLogGroupName 时指定的日志组。

类型:布尔值

必需:是

kmsKeyId

您要用来进一步加密本地客户端与所连接的 Amazon Elastic Compute Cloud (Amazon EC2) 托管式节点之间数据的 Amazon KMS key 的 ID。

类型:字符串

必需:否

runAsEnabled

如果设置为 true,则必须在 runAsDefaultUser 输入中指定一个存在于要连接的托管式节点上的用户账户。否则,会话将无法启动。默认情况下,会话使用 Amazon Systems Manager SSM Agent 创建的 ssm-user 账户启动。只有连接到 Linux 托管式节点才支持“运行身份”功能。

类型:布尔值

必需:是

runAsDefaultUser

当 Linux 输入设置为 true 时,用于在 runAsEnabled 托管式节点上启动会话的用户账户的名称。您为此输入指定的用户账户必须存在于要连接的托管式节点上;否则,会话将无法启动。

类型:字符串

必需:否

idleSessionTimeout

结束会话前允许处于非活动状态的时间长度。此输入以分钟为单位。

类型:字符串

有效值:1-60

必需:否

maxSessionDuration

会话结束前允许的最长时间。此输入以分钟为单位。

类型:字符串

有效值:1-1440

必需:否

shellProfile

根据操作系统指定的要在会话中应用的首选项,例如 Shell 首选项、环境变量、工作目录以及在启动会话时运行多个命令。

类型:StringMap

必需:否

windows

为 Windows 托管式节点上的会话指定的 Shell 首选项、环境变量、工作目录和命令。

类型:字符串

必需:否

linux

为 Linux 托管式节点上的会话指定的 Shell 首选项、环境变量、工作目录和命令。

类型:字符串

必需:否

parameters

定义文档接受的参数的对象。有关定义文档参数的更多信息,请参阅顶级数据元素中的参数。对于经常引用的参数,建议在 Systems Manager Parameter Store 中存储这些参数,以便进行引用。您可以在文档的这一部分引用 StringStringList Parameter Store 参数。您不能在文档的这一部分引用 SecureString Parameter Store 参数。您可以使用以下格式引用 Parameter Store 参数:

{{ssm:parameter-name}}

有关 Parameter Store 的更多信息,请参阅 Amazon Systems Manager Parameter Store

类型:StringMap

必需:否

properties

StartSession API 操作中使用的一个对象,其值由您指定。

对于用于 InteractiveCommands 会话的会话文档,属性对象包含要在您指定的操作系统上运行的命令。您还可以 runAsElevated 布尔属性来确定命令是否作为 root 运行。有关更多信息,请参阅限制对会话中命令的访问

对于用于 Port 会话的会话文档,属性对象包含应将流量重定向到的端口号。有关示例,请参阅本主题后文中的 Port 类型会话文档示例。

类型:StringMap

必需:否

Standard_Stream 类型会话文档示例

YAML
---
schemaVersion: '1.0'
description: Document to hold regional settings for Session Manager
sessionType: Standard_Stream
inputs:
s3BucketName: ''
s3KeyPrefix: ''
s3EncryptionEnabled: true
cloudWatchLogGroupName: ''
cloudWatchEncryptionEnabled: true
cloudWatchStreamingEnabled: true
kmsKeyId: ''
runAsEnabled: true
runAsDefaultUser: ''
idleSessionTimeout: '20'
maxSessionDuration: '60'
shellProfile:
windows: ''
linux: ''
JSON
{ "schemaVersion": "1.0", "description": "Document to hold regional settings for Session Manager", "sessionType": "Standard_Stream", "inputs": { "s3BucketName": "", "s3KeyPrefix": "", "s3EncryptionEnabled": true, "cloudWatchLogGroupName": "", "cloudWatchEncryptionEnabled": true, "cloudWatchStreamingEnabled": true, "kmsKeyId": "", "runAsEnabled": true, "runAsDefaultUser": "", "idleSessionTimeout": "20", "maxSessionDuration": "60", "shellProfile": { "windows": "date", "linux": "pwd;ls" } } }

InteractiveCommands 类型会话文档示例

YAML
--- schemaVersion: '1.0' description: Document to view a log file on a Linux instance sessionType: InteractiveCommands
parameters: logpath: type: String description: The log file path to read. default: "/var/log/amazon/ssm/amazon-ssm-agent.log" allowedPattern: "^[a-zA-Z0-9-_/]+(.log)$"
properties: linux: commands: "tail -f {{ logpath }}" runAsElevated: true
JSON
{ "schemaVersion": "1.0", "description": "Document to view a log file on a Linux instance", "sessionType": "InteractiveCommands", "parameters": { "logpath": { "type": "String", "description": "The log file path to read.", "default": "/var/log/amazon/ssm/amazon-ssm-agent.log", "allowedPattern": "^[a-zA-Z0-9-_/]+(.log)$" } }, "properties": { "linux": { "commands": "tail -f {{ logpath }}", "runAsElevated": true } } }

Port 类型会话文档示例

YAML
--- schemaVersion: '1.0' description: Document to open given port connection over Session Manager sessionType: Port parameters: paramExample: type: string description: document parameter
properties: portNumber: anyPortNumber
JSON
{ "schemaVersion": "1.0", "description": "Document to open given port connection over Session Manager", "sessionType": "Port", "parameters": { "paramExample": { "type": "string", "description": "document parameter" } }, "properties": { "portNumber": "anyPortNumber" } }

包含特殊字符的会话文档示例

YAML
--- schemaVersion: '1.0' description: Example document with quotation marks sessionType: InteractiveCommands parameters: Test: type: String description: Test Input maxChars: 32 properties: windows: commands: | $Test = '{{ Test }}' $myVariable = \"Computer name is $env:COMPUTERNAME\" Write-Host "Test variable: $myVariable`.`nInput parameter: $Test" runAsElevated: false
JSON
{ "schemaVersion":"1.0", "description":"Test document with quotation marks", "sessionType":"InteractiveCommands", "parameters":{ "Test":{ "type":"String", "description":"Test Input", "maxChars":32 } }, "properties":{ "windows":{ "commands":[ "$Test = '{{ Test }}'", "$myVariable = \\\"Computer name is $env:COMPUTERNAME\\\"", "Write-Host \"Test variable: $myVariable`.`nInput parameter: $Test\"" ], "runAsElevated":false } } }