创建 SSM 文档内容 - Amazon Systems Manager
编写 SSM 文档内容克隆 SSM 文档创建复合文档
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

创建 SSM 文档内容

如果 Amazon Systems Manager 公有文档不执行要对 Amazon 资源执行的所有操作，您可以创建自己的 SSM 文档。您还可以使用控制台克隆 SSM 文档。克隆文档将内容从现有文档复制到可以修改的新文档。创建或克隆文档时，文档的内容不得超过 64KB。此配额还包括在运行时指定的输入参数内容。创建新的 Command 或 Policy 文档时，我们建议您使用版本 2.2 或更高版本的架构，以便利用最新功能，例如文档编辑、自动版本控制、排序等。

编写 SSM 文档内容

要创建您自己的 SSM 文档内容，请务必了解可用于 SSM 文档的不同架构、功能、插件和语法。我们建议您熟悉以下资源。

Amazon 预定义的 SSM 文档可能会执行您所需的一些操作。您可以通过在自定义 SSM 文档中使用 aws:runDocument、aws:runCommand 或 aws:executeAutomation 插件来调用这些文档，具体取决于文档类型。您还可以将这些文档的某些部分复制到自定义的 SSM 文档中，并编辑内容以满足您的要求。

提示

创建 SSM 文档内容时，您可能会在测试时多次更改内容并更新 SSM 文档。以下命令使用最新内容更新 SSM 文档，并将文档的默认版本更新为文档的最新版本。

注意

Linux 和 Windows 命令使用 jq 命令行工具筛选 JSON 响应数据。

Linux & macOS
latestDocVersion=$(aws ssm update-document \
    --content file://path/to/file/documentContent.json \
    --name "ExampleDocument" \
    --document-format JSON \
    --document-version '$LATEST' \
    | jq -r '.DocumentDescription.LatestVersion')

aws ssm update-document-default-version \
    --name "ExampleDocument" \
    --document-version $latestDocVersion
Windows
latestDocVersion=$(aws ssm update-document ^
    --content file://C:\path\to\file\documentContent.json ^
    --name "ExampleDocument" ^
    --document-format JSON ^
    --document-version "$LATEST" ^
    | jq -r '.DocumentDescription.LatestVersion')

aws ssm update-document-default-version ^
    --name "ExampleDocument" ^
    --document-version $latestDocVersion
PowerShell
$content = Get-Content -Path "C:\path\to\file\documentContent.json" | Out-String
$latestDocVersion = Update-SSMDocument `
    -Content $content `
    -Name "ExampleDocument" `
    -DocumentFormat "JSON" `
    -DocumentVersion '$LATEST' `
    | Select-Object -ExpandProperty LatestVersion

Update-SSMDocumentDefaultVersion `
    -Name "ExampleDocument" `
    -DocumentVersion $latestDocVersion

SSM 文档的安全最佳实践

创建 SSM 文档时，请遵循以下安全最佳实践，以帮助防范命令注入攻击并确保安全处理参数：

  • 对将用于命令或脚本的字符串参数使用环境变量插值。为字符串参数添加值为 ENV_VAR 的 interpolationType 属性：

    {
    "command": {
        "type": "String",
        "description": "Command to execute",
        "interpolationType": "ENV_VAR"
    }
}

    您可以指定插值生成的值不接受双引号，从而进一步增强 SSM 文档的安全性：

    {
    "command": {
        "type": "String",
        "description": "Command to execute",
        "interpolationType": "ENV_VAR",
            "allowedPattern": "^[^"]*$"
    }
}

  • 在使用 Python、Ruby 或 Node.js 等解释性语言时，请使用恰当的环境变量语法来引用参数：

    # Python example
import os
command = os.environ['SSM_Message']

  • 为了向后兼容旧版 SSM Agent（3.3.2746.0 版之前），请为环境变量添加回退逻辑：

    if [ -z "${SSM_command+x}" ]; then
    export SSM_command="{{command}}"
fi

  • 将环境变量插值与 allowedPattern 相结合，提供额外的输入验证。在以下示例中，allowedPattern 的值 ^[^"]*$ 专门用于防止在字符串值中使用双引号：

    {
    "command": {
        "type": "String",
        "interpolationType": "ENV_VAR",
        "allowedPattern": "^[a-zA-Z0-9_-]+$"
    }
}

  • 在实现 SSM 文档之前，请确认以下安全注意事项：

    • 适用时，所有接受用户输入的字符串参数均使用环境变量插值。

    • 尽可能使用 allowedPattern 来实现输入验证。

    • 该文档包含了处理参数的恰当错误处理方法。

    • 对使用旧版 SSM Agent 的环境保持了向后兼容性。

克隆 SSM 文档

您可以克隆 Amazon Systems Manager 文档，使用 Systems Manager 文档控制台创建 SSM 文档。克隆 SSM 文档将内容从现有文档复制到可以修改的新文档中。无法克隆大于 64KB 的文档。

克隆 SSM 文档

  1. 访问 https://console.aws.amazon.com/systems-manager/，打开 Amazon Systems Manager 控制台。

  2. 在导航窗格中，选择文档。

  3. 在搜索框中，输入要克隆的文档的名称。

  4. 选择要克隆的文档的名称，然后选择操作下拉菜单中的克隆文档。

  5. 根据需要修改文档，然后选择创建文档保存文档。

编写 SSM 文档内容后，您可以通过以下方法之一使用您的内容创建 SSM 文档。

创建 SSM 文档

创建复合文档

复合 Amazon Systems Manager (SSM) 文档是自定义文档，可通过运行一个或多个次要 SSM 文档执行一系列操作。复合文档允许您为常见任务（例如引导软件或域加入实例）创建一组标准 SSM 文档，从而升级基础设施代码。您随后可以在同一个 Amazon Web Services 区域 中跨 Amazon Web Services 账户 共享这些文档，从而减少 SSM 文档的维护工作并确保文档一致性。

例如，您可以创建执行以下操作的复合文档：

  1. 安装允许列表中的所有修补程序。

  2. 安装防病毒软件。

  3. 从 GitHub 下载脚本并运行这些脚本。

在本例中，您的自定义 SSM 文档包含执行下面这些操作的以下插件：

  1. 用于运行 AWS-RunPatchBaseline 文档的 aws:runDocument 插件，它将安装所有允许列出的补丁。

  2. 可运行 AWS-InstallApplication 文档的 aws:runDocument 插件，这会安装防病毒软件。

  3. 可从 GitHub 下载脚本并运行这些脚本的 aws:downloadContent 插件。

复合和次要文档可存储在 Systems Manager、GitHub（公有和私有存储库）或 Amazon S3 中。可创建 JSON 或 YAML 格式的复合文档和次要文档。

注意

复合文档只能运行三个文档的最大文档深度。这意味着复合文档可以调用子文档；该子文档可调用最后一个文档。

要创建复合文档，请在自定义 SSM 文档中添加 aws:runDocument 插件并指定必需的输入。下面是可执行以下操作的复合文档示例：

  1. 运行 aws:downloadContent 插件，可从 GitHub 公有存储库将 SSM 文档下载到名为 bootstrap 的本地目录。SSM 文档称为 StateManagerBootstrap.yml (YAML 文档)。

  2. 运行 aws:runDocument 插件可运行 StateManagerBootstrap.yml 文档。未指定任何参数。

  3. 运行 aws:runDocument 插件以运行 AWS-ConfigureDocker pre-defined SSM 文档。指定的参数会在实例上安装 Docker。

{
  "schemaVersion": "2.2",
  "description": "My composite document for bootstrapping software and installing Docker.",
  "parameters": {
  },
  "mainSteps": [
    {
      "action": "aws:downloadContent",
      "name": "downloadContent",
      "inputs": {
        "sourceType": "GitHub",
        "sourceInfo": "{\"owner\":\"TestUser1\",\"repository\":\"TestPublic\", \"path\":\"documents/bootstrap/StateManagerBootstrap.yml\"}",
        "destinationPath": "bootstrap"
      }
    },
    {
      "action": "aws:runDocument",
      "name": "runDocument",
      "inputs": {
        "documentType": "LocalPath",
        "documentPath": "bootstrap",
        "documentParameters": "{}"
      }
    },
    {
      "action": "aws:runDocument",
      "name": "configureDocker",
      "inputs": {
        "documentType": "SSMDocument",
        "documentPath": "AWS-ConfigureDocker",
        "documentParameters": "{\"action\":\"Install\"}"
      }
    }
  ]
}
更多信息