会话文档架构 - AWS Systems Manager

会话文档架构

以下信息介绍了会话文档的架构元素。AWS 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) 托管式节点之间数据的 AWS KMS key 的 ID。

类型：字符串

必需：否

runAsEnabled

如果设置为 true，则必须在 runAsDefaultUser 输入中指定一个存在于要连接的托管式节点上的用户账户。否则，会话将无法启动。默认情况下，会话使用 AWS 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 中存储这些参数，以便进行引用。您可以在文档的这一部分引用 String 和 StringList Parameter Store 参数。您不能在文档的这一部分引用 SecureString Parameter Store 参数。您可以使用以下格式引用 Parameter Store 参数：

{{ssm:parameter-name}}

有关 Parameter Store 的更多信息，请参阅 AWS 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
      }
   }
}