View a markdown version of this page

共享 SSM 文档 - AWS Systems Manager
共享 SSM 文档的最佳做法阻止 SSM 文档的公开共享使用 AWS RAM 共享 SSM 文档使用账户权限共享 SSM 文档使用共享 SSM 文档

共享 SSM 文档

您可以通过两种方式与同一 AWS 区域中的其他账户共享 AWS Systems Manager（SSM）文档。对于新的文档共享，建议使用 AWS Resource Access Manager（AWS RAM）。使用 AWS RAM，您可以与 AWS Organizations 中的整个组织或组织单元（OU）共享文档，或与个人 AWS 账户共享文档。您还可以从 AWS RAM 控制台管理所有共享。有关更多信息，请参阅 使用 AWS RAM 共享 SSM 文档。

您也可以使用账户权限（原有共享机制）来共享文档。使用账户权限，您可以直接修改文档权限，以便与特定 AWS 账户 ID 私密共享文档，或与所有人公开共享文档。账户权限共享仍受支持。有关更多信息，请参阅 使用账户权限共享 SSM 文档。

如果您已使用账户权限来共享文档，则可以将这些共享迁移到 AWS RAM。有关更多信息，请参阅 将现有共享文档迁移到 AWS RAM。

您不能同时以公开和私密方式共享同一文档。也不能同时对同一个文档使用 AWS RAM 共享和账户权限 (ModifyDocumentPermission) 共享。

警告

请仅使用从可信来源获取的共享 SSM 文档。使用任何共享文档时，请务必在使用前仔细查看文件内容，了解它会如何更改您的实例配置。有关共享文档最佳实践的更多信息，请参阅 共享 SSM 文档的最佳做法。

限制

在开始使用 SSM 文档时，请注意下列限制。

  • 仅所有者可共享文档。

  • 文档只能与同一个 AWS 区域 中的其他账户共享。不支持跨区域共享。

重要

在 Systems Manager 中，Amazon 拥有的 SSM 文档是由 Amazon Web Services 自己创建和管理的文档。Amazon 拥有的文档在文档名称中包含 AWS-* 之类的前缀。文档的所有者被视为 Amazon，而不是 AWS 内的特定用户账户。这些文档可供所有人公开使用。

共享 SSM 文档的最佳做法

在共享或使用共享文档之前，请阅读以下指南。

使用 AWS RAM 共享文档（建议）

对于新的文档共享，建议使用 AWS Resource Access Manager（AWS RAM），而非 ModifyDocumentPermission API 操作。通过 AWS RAM 进行共享时，您可以与 AWS Organizations 中的整个组织或组织单元（OU）共享文档，不必列出个人 AWS 账户 ID。您还可以使用基于资源的策略来管理访问权限，并在 AWS RAM 控制台中集中查看和审核所有共享内容。要查看步骤，请参阅使用 AWS RAM 共享 SSM 文档。通过 ModifyDocumentPermission 与个人 AWS 账户 ID 共享的文档仍受支持。如需将已共享的文档移至 AWS RAM，请参阅将现有共享文档迁移到 AWS RAM。

删除敏感信息

请仔细审查您的 AWS Systems Manager (SSM) 文档并删除任何敏感信息。例如，请确保文档不包含您的 AWS 凭证。如果您与特定个人共享文档，这些用户可查看文档中的信息。如果您公开共享文档，则任何人都可查看文档中的信息。

阻止文档的公开共享

查看您账户中所有公开共享的 SSM 文档，并确认是否要继续共享这些文档。要停止与公众共享文档，必须按照本主题 修改共享 SSM 文档的权限 部分所述来修改文档权限设置。启用“阻止公开共享”设置不会影响您当前与公众共享的任何文档。除非您的应用场景需要您与公众共享文档，否则建议在 Systems Manager 文档控制台的首选项部分，为您的 SSM 文档开启阻止公开共享设置。启用此设置可防止对 SSM 文档进行不需要的访问。阻止公开共享设置是一个帐户级别设置，每个 AWS 区域 的设置可能不同。

使用 IAM 信任策略限制 Run Command 操作

为将有权访问该文档的用户创建限制性 AWS Identity and Access Management（IAM）policy。IAM policy 确定用户可在 Amazon Elastic Compute Cloud（Amazon EC2）控制台中或通过使用 AWS Command Line Interface（AWS CLI）或 AWS Tools for Windows PowerShell 调用 ListDocuments 查看哪些 SSM 文档。该策略还限制用户可使用 SSM 文档执行的操作。您可创建限制性策略，以便用户只能使用特定文档。有关更多信息，请参阅 客户管理型策略示例。

使用共享 SSM 文档时要小心

审查与您共享的每个文档（特别是公开文档）的内容，以了解将在您的实例上运行的命令。一个文档在运行后可能会有意或无意具有负面影响。如果文档引用外部网络，请在使用文档前审查外部源。

使用文档哈希发送命令

在共享文档时，系统将创建 Sha-256 哈希并将其分配给文档。系统还将保存文档内容的快照。使用共享文档发送命令时，可在命令中指定哈希，以确保下列条件为 true：

  • 您正在从正确的 Systems Manager 文档运行命令

  • 在与您共享之后文档内容未更改。

如果哈希与指定文档不匹配，或者共享文档的内容已更改，则命令将返回 InvalidDocument 异常。哈希无法验证来自外部位置的文档内容。

使用插值参数来增强安全性

对于 SSM 文档中的 String 类型参数，可使用参数和值 interpolationType": "ENV_VAR 增强对命令注入攻击的防御能力，方法是将参数输入视为字符串文本值，而非可能的可执行命令。在这种情况下，代理会创建一个包含参数值的环境变量 SSM_parameter-name。我们建议对现有所有包含 String 类型参数的 SSM 文档进行更新，以纳入 "interpolationType": "ENV_VAR"。有关更多信息，请参阅 编写 SSM 文档内容。

阻止 SSM 文档的公开共享

开始前，请查看您 AWS 账户 中所有公开共享的 SSM 文档，并确认是否要继续共享它们。要停止与公众共享 SSM 文档，必须按照本主题 修改共享 SSM 文档的权限 部分所述修改文档权限设置。启用“阻止公开共享”设置不会影响您当前与公众共享的任何 SSM 文档。启用“阻止公开共享”设置后，您将无法与公众共享任何其他 SSM 文档。

除非您的应用场景需要您与公众共享文档，否则我们建议为您的 SSM 文档开启阻止公开共享设置。启用此设置可防止对 SSM 文档进行不需要的访问。阻止公开共享设置是一个帐户级别设置，每个 AWS 区域 的设置可能不同。完成以下任务以阻止您目前正在共享的任何 SSM 文档的公开共享。

阻止公开共享（控制台）

要阻止 SSM 文档的公开共享

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

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

  3. 选择首选项，然后在阻止公开共享部分中选择编辑。

  4. 选择阻止公开共享复选框，然后选择保存。

阻止公开共享（命令行）

打开 AWS Command Line Interface (AWS CLI）或 AWS Tools for Windows PowerShell 并运行以下命令以阻止 SSM 文档的公开共享。

Linux & macOS
aws ssm update-service-setting  \
    --setting-id /ssm/documents/console/public-sharing-permission \
    --setting-value Disable \
    --region 'The AWS 区域 you want to block public sharing in'
Windows
aws ssm update-service-setting ^
    --setting-id /ssm/documents/console/public-sharing-permission ^
    --setting-value Disable ^
    --region "The AWS 区域 you want to block public sharing in"
PowerShell
Update-SSMServiceSetting `
    -SettingId /ssm/documents/console/public-sharing-permission `
    -SettingValue Disable `
    –Region The AWS 区域 you want to block public sharing in

使用以下命令确认设置值已更新。

Linux & macOS
aws ssm get-service-setting   \
    --setting-id /ssm/documents/console/public-sharing-permission \
    --region The AWS 区域 you blocked public sharing in
Windows
aws ssm get-service-setting  ^
    --setting-id /ssm/documents/console/public-sharing-permission ^
    --region "The AWS 区域 you blocked public sharing in"
PowerShell
Get-SSMServiceSetting `
    -SettingId /ssm/documents/console/public-sharing-permission `
    -Region The AWS 区域 you blocked public sharing in

使用 IAM 限制访问阻止公开共享

您可以创建 AWS Identity and Access Management (IAM) 策略，这些策略限制用户修改阻止公开共享设置。这可以防止用户允许对 SSM 文档进行不需要的访问。

以下是一个 IAM policy 示例，该策略阻止用户更新阻止公开共享设置。要使用此示例，您必须将示例 Amazon Web Services 账户 ID 替换为您自己的账户 ID。

JSON
{
    "Version":"2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "ssm:UpdateServiceSetting",
            "Resource": "arn:aws:ssm:*:444455556666:servicesetting/ssm/documents/console/public-sharing-permission"
        }
    ]
}

使用 AWS RAM 共享 SSM 文档

AWS Resource Access Manager（AWS RAM）是共享 AWS Systems Manager（SSM）文档的推荐方式。使用 AWS RAM，您可以创建资源共享（这会授予对文档的访问权限），并通过 AWS RAM 控制台管理所有共享。可与以下三种类型的主体共享 SSM 文档：

  • AWS Organizations 中的整个组织。

  • AWS 中的组织单元（OU）。

  • 个人 AWS 账户。

仅可与同一 AWS 区域中的账户共享文档，并且仅文档所有者才能共享文档。有关通过 AWS RAM 进行共享的更多信息，请参阅《AWS Resource Access Manager 用户指南》中的 AWS RAM 入门。

重要

使用 AWS RAM 共享 SSM 文档时，您共享的是文档的所有版本，而不仅是默认版本。

注意

AWS RAM 仅支持私密共享。要公开共享文档，请改用使用账户权限共享 SSM 文档中的步骤。

注意

与组织外部的 AWS 账户共享文档时，使用者必须先接受 AWS RAM 中的资源共享邀请，才能访问该文档。在已启用 AWS RAM 共享的组织内共享时，无需邀请，AWS RAM 会自动授予访问权限。

通过 AWS RAM 共享 SSM 文档时，AWS RAM 服务配额适用。有关更多信息，请参阅《AWS Resource Access Manager 用户指南》中的 AWS RAM 的服务配额。

要管理现有共享（例如，更新主体或停止共享通过 AWS RAM 共享的文档），请参阅《AWS Resource Access Manager 用户指南》中的使用共享的 AWS 资源。

使用 AWS RAM 共享文档（控制台）

使用 AWS RAM 共享文档

  1. 打开 AWS RAM 控制台，网址：https://console.aws.amazon.com/ram/。

  2. 在导航窗格中，选择资源共享，然后选择创建资源共享。

  3. 对于名称，输入资源共享的名称。

  4. 在资源下，选择资源类型 SSM 文档，然后选择要共享的文档。

  5. （可选）在托管权限下，查看 AWS RAM 应用于共享文档的托管权限。

  6. 选择下一步。在主体下，添加要与之共享的组织、OU 或 AWS 账户。要与组织或 OU 共享，必须在 AWS Organizations 中启用共享功能。

  7. 选择下一步，检查您的选择，然后选择创建资源共享。

使用 AWS RAM 共享文档（命令行）

在本地计算机上打开 AWS Command Line Interface（AWS CLI）或 AWS Tools for Windows PowerShell，然后运行以下命令，通过创建 AWS RAM 资源共享来共享文档。对于 --principals 参数，请指定组织 ARN、OU ARN 或 AWS 账户 ID。

Linux & macOS
aws ram create-resource-share \
    --name MyDocumentShare \
    --resource-arns arn:aws:ssm:region:account-id:document/document-name \
    --principals principal
Windows
aws ram create-resource-share ^
    --name MyDocumentShare ^
    --resource-arns arn:aws:ssm:region:account-id:document/document-name ^
    --principals principal
注意

创建共享后，AWS RAM 可能需要几分钟来传播更改，使用者账户才能看到更改。

将现有共享文档迁移到 AWS RAM

如果当前使用账户权限（ModifyDocumentPermission API 操作）来共享文档，则可以运行 AWS-MigrateSSMDocumentSharingToRAM 运行手册来将其迁移到 AWS RAM 资源共享。此 AWS 自有 AWS Systems Manager Automation 运行手册可将文档从账户权限共享迁移到 AWS RAM 资源共享，同时保留文档的现有使用者。

注意

运行 AWS-MigrateSSMDocumentSharingToRAM 运行手册会使用 AWS Systems Manager Automation，因此会产生相应的费用。有关更多信息，请参阅 AWS Systems Manager 定价。

注意

公开共享的文档无法迁移，因为 AWS RAM 仅支持私密共享。如果您指定公开共享的文档，运行手册将失败。如果您迁移账户中的所有文档，运行手册会跳过公开共享的文档。要迁移公开共享的文档，请先停止公开共享，然后再与所需的账户、组织单元（OU）或组织共享。

重要

迁移文档后，您可以通过 AWS RAM 管理该文档的共享。ModifyDocumentPermission 和 DescribeDocumentPermission API 操作会针对已迁移的文档返回 4xx 错误。如果迁移失败或被取消，运行手册会自动回滚更改。

从“权限”视图迁移文档（控制台）

  1. 打开 AWS Systems Manager 控制台，在导航窗格中选择文档。

  2. 选择要迁移的文档。

  3. 选择详细信息选项卡。

  4. 在权限部分中，选择迁移到 RAM。Systems Manager 会打开迁移到 RAM 页面，以便您开始迁移。

  5. 对于待迁移文档，请选择要迁移的文档。选择单个文档，或选择所有文档，迁移账户中使用账户权限共享的所有文档。

  6. 对于 AutomationAssumeRole，请选择 Systems Manager Automation 在执行迁移时代入的 IAM 角色。

  7. （可选）对于 组织单元，请添加要与之共享文档的组织 ID 或组织单元（OU）ID。

  8. 选择开始迁移。

有关参数的完整列表、AutomationAssumeRole 角色所需的 IAM 权限以及运行手册的分步说明，请参阅《AWS Systems Manager Automation 运行手册参考》中的 AWS-MigrateSSMDocumentSharingToRAM。

使用账户权限共享 SSM 文档

您可以通过修改文档权限来共享 AWS Systems Manager（SSM）文档来向特定 AWS 账户 ID（私密共享）或所有人（公开共享）授予访问权限。您可以从 Systems Manager 控制台共享文档，也可以使用 AWS Command Line Interface（AWS CLI）、AWS Tools for Windows PowerShell 或 AWS SDK 以编程方式调用 ModifyDocumentPermission API 操作来共享文档。从控制台共享文档时，只能共享文档的默认版本。在共享文档之前，请获取要与之共享的 AWS 账户 ID。共享文档时，需指定这些账户 ID。

注意

对于新的文档共享，建议改为使用 AWS Resource Access Manager（AWS RAM）。使用 AWS RAM，您可以与整个组织或 OU 共享，并在一处集中管理所有共享内容。有关更多信息，请参阅 使用 AWS RAM 共享 SSM 文档。

限制

使用账户权限共享文档时，请注意以下限制。

  • 您必须先停止共享文档，然后才能删除它。有关更多信息，请参阅 修改共享 SSM 文档的权限。

  • 您最多可与 1,000 个 AWS 账户 共享一个文档。您可以在 支持 中心中请求提高该限制。对于限制类型，选择 EC2 Systems Manager 并描述您的请求理由。

  • 您可公开共享最多 5 个 SSM 文档。您可以在 支持支持中心中请求提高该限制。对于限制类型，选择 EC2 Systems Manager 并描述您的请求理由。

有关 Systems Manager Service Quotas 的更多信息，请参阅 AWS Systems ManagerService Quotas 。

共享文档（控制台）

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

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

  3. 在文档列表中，选择要共享的文档，然后选择查看详细信息。在权限选项卡中，确保您是文档所有者。只有文档所有者才可共享文档。

  4. 选择编辑。

  5. 要公开共享命令，请选择公开，然后选择保存。要私下共享命令，请选择私有，输入 AWS 账户 ID，选择添加权限，然后选择保存。

共享文档（命令行）

以下过程要求您为命令行会话指定 AWS 区域。

  1. 在本地计算机上打开 AWS CLI 或 AWS Tools for Windows PowerShell 并运行以下命令来指定凭证。

    在下面的命令中，将 region 替换为您自己的信息。有关支持的 region 值的列表，请参阅《Amazon Web Services 一般参考》中的 Systems Manager service endpoints 的 Region 列。

    Linux & macOS
    aws config

AWS Access Key ID: [your key]
AWS Secret Access Key: [your key]
Default region name: region
Default output format [None]:
    Windows
    aws config

AWS Access Key ID: [your key]
AWS Secret Access Key: [your key]
Default region name: region
Default output format [None]:
    PowerShell
    Set-AWSCredentials –AccessKey your key –SecretKey your key
Set-DefaultAWSRegion -Region region

  2. 使用以下命令查看文档的权限。

    Linux & macOS
    aws ssm describe-document-permission \
    --name document name \
    --permission-type Share
    Windows
    aws ssm describe-document-permission ^
    --name document name ^
    --permission-type Share
    PowerShell
    Get-SSMDocumentPermission `
    –Name document name `
    -PermissionType Share

  3. 使用以下命令修改文档的权限并共享文档。您必须是文档的所有者才能编辑权限。或者，对于与特定 AWS 账户 ID 共享的文档，您可以使用 --shared-document-version 参数指定要共享的文档的版本。如果您不指定版本，系统将共享文档的Default版本。如果您公开（与 all）共享文档，则默认共享指定文档的所有版本。以下示例命令根据特定个人的 AWS 账户 ID 与该个人私下共享文档。

    Linux & macOS
    aws ssm modify-document-permission \
    --name document name \
    --permission-type Share \
    --account-ids-to-add AWS 账户 ID
    Windows
    aws ssm modify-document-permission ^
    --name document name ^
    --permission-type Share ^
    --account-ids-to-add AWS 账户 ID
    PowerShell
    Edit-SSMDocumentPermission `
    –Name document name `
    -PermissionType Share `
    -AccountIdsToAdd AWS 账户 ID

  4. 使用以下命令公开共享文档。

    注意

    如果您公开（与 all）共享文档，则默认共享指定文档的所有版本。

    Linux & macOS
    aws ssm modify-document-permission \
    --name document name \
    --permission-type Share \
    --account-ids-to-add 'all'
    Windows
    aws ssm modify-document-permission ^
    --name document name ^
    --permission-type Share ^
    --account-ids-to-add "all"
    PowerShell
    Edit-SSMDocumentPermission `
    -Name document name `
    -PermissionType Share `
    -AccountIdsToAdd ('all')

修改共享 SSM 文档的权限

如果您共享一条命令，则在您删除对 AWS Systems Manager (SSM) 文档的访问权限或删除 SSM 文档之前，用户可查看和使用该命令。但是，只要文档已共享，您就无法删除它。您必须先停止共享，然后再删除它。

注意

本节适用于使用账户权限共享的文档。如需管理通过 AWS RAM 共享的文档，请参阅使用 AWS RAM 共享 SSM 文档。

停止共享文档（控制台）

停止共享文档

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

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

  3. 在文档列表中，选择要停止共享的文档，然后选择详细信息。在权限部分中，确认自己是文档所有者。只有文档所有者才可停止共享文档。

  4. 选择编辑。

  5. 选择 X 以删除不应再具有此命令的访问权限的 AWS 账户 ID，然后选择保存。

停止共享文档（命令行）

在本地计算机上打开 AWS CLI 或 AWS Tools for Windows PowerShell，然后运行以下命令以停止共享文档。

Linux & macOS
aws ssm modify-document-permission \
    --name document name \
    --permission-type Share \
    --account-ids-to-remove 'AWS 账户 ID'
Windows
aws ssm modify-document-permission ^
    --name document name ^
    --permission-type Share ^
    --account-ids-to-remove "AWS 账户 ID"
PowerShell
Edit-SSMDocumentPermission `
    -Name document name `
    -PermissionType Share `
    –AccountIdsToRemove AWS 账户 ID

使用共享 SSM 文档

共享 AWS Systems Manager (SSM) 文档时，系统将生成一个 Amazon Resource Name (ARN) 并将其分配给命令。如果您从 Systems Manager 控制台选择并运行某个共享文档，则不会看到此 ARN。但如果您要使用 Systems Manager 控制台以外的方法运行共享 SSM 文档，则必须在 DocumentName 请求参数中指定文档的完整 ARN。当您运行列出文档的命令时，将为您显示 SSM 文档的完整 ARN。

注意

您无需为 AWS 公有文档（以 AWS-* 开头的文档）或您拥有的文档指定 ARN。

使用共享 SSM 文档（命令行）

列出所有公有 SSM 文档

Linux & macOS
aws ssm list-documents \
    --filters Key=Owner,Values=Public
Windows
aws ssm list-documents ^
    --filters Key=Owner,Values=Public
PowerShell
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Owner"
$filter.Values = "Public"

Get-SSMDocumentList `
    -Filters @($filter)

列出已与您共享的私有 SSM 文档

Linux & macOS
aws ssm list-documents \
    --filters Key=Owner,Values=Private
Windows
aws ssm list-documents ^
    --filters Key=Owner,Values=Private
PowerShell
$filter = New-Object Amazon.SimpleSystemsManagement.Model.DocumentKeyValuesFilter
$filter.Key = "Owner"
$filter.Values = "Private"

Get-SSMDocumentList `
    -Filters @($filter)

列出可供您使用的所有 SSM 文档

Linux & macOS
aws ssm list-documents
Windows
aws ssm list-documents
PowerShell
Get-SSMDocumentList

获取有关已与您共享的 SSM 文档的信息

Linux & macOS
aws ssm describe-document \
    --name arn:aws:ssm:us-east-2:12345678912:document/documentName
Windows
aws ssm describe-document ^
    --name arn:aws:ssm:us-east-2:12345678912:document/documentName
PowerShell
Get-SSMDocumentDescription `
    –Name arn:aws:ssm:us-east-2:12345678912:document/documentName

运行共享的 SSM 文档

Linux & macOS
aws ssm send-command \
    --document-name arn:aws:ssm:us-east-2:12345678912:document/documentName \
    --instance-ids ID
Windows
aws ssm send-command ^
    --document-name arn:aws:ssm:us-east-2:12345678912:document/documentName ^
    --instance-ids ID
PowerShell
Send-SSMCommand `
    –DocumentName arn:aws:ssm:us-east-2:12345678912:document/documentName `
    –InstanceIds ID