共享 SSM 文档 - Amazon Systems Manager
共享 SSM 文档的最佳做法阻止 SSM 文档的公开共享共享 SSM 文档修改共享 SSM 文档的权限使用共享 SSM 文档
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

共享 SSM 文档

您可以与同一个 Amazon Web Services 区域 中的账户私下或公开共享 Amazon Systems Manager (SSM) 文档。要私下共享文档，请修改文档权限并允许特定个人根据其 Amazon Web Services 账户 ID 访问文档。要公开共享 SSM 文档，请修改文档权限并指定 All 。不能同时公开和私下共享文档。

警告

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

限制

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

  • 仅所有者可共享文档。

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

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

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

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

重要

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

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

共享 SSM 文档的最佳做法

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

删除敏感信息

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

阻止文档的公开共享

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

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

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

使用共享 SSM 文档时要小心

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

使用文档哈希发送命令

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

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

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

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

阻止 SSM 文档的公开共享

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

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

阻止公开共享（控制台）

要阻止 SSM 文档的公开共享

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

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

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

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

阻止公开共享（命令行）

打开 Amazon Command Line Interface (Amazon CLI）或 Amazon 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 Amazon Web Services 区域 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 Amazon Web Services 区域 you want to block public sharing in"
PowerShell
Update-SSMServiceSetting `
    -SettingId /ssm/documents/console/public-sharing-permission `
    -SettingValue Disable `
    –Region The Amazon Web Services 区域 you want to block public sharing in

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

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

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

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

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

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

共享 SSM 文档

您可以通过 Systems Manager 控制台共享 Amazon Systems Manager (SSM) 文档。从控制台共享文档时，只能共享文档的默认版本。您还可以通过使用 Amazon Command Line Interface (Amazon CLI)、 Amazon Tools for Windows PowerShell 或 Amazon SDK 调用 ModifyDocumentPermission API 操作，以编程方式共享 SSM 文档。在共享文档之前，获取要与之共享文档的人的 Amazon Web Services 账户 账户 ID。您将在共享文档时指定这些账户 ID。

共享文档（控制台）

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

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

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

  4. 选择编辑。

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

共享文档（命令行）

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

  1. 在本地计算机上打开 Amazon CLI 或 Amazon 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. 使用以下命令列出可供您使用的所有 SSM 文档。此列表包括您已创建的文档和与您共享的文档。

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

  3. 使用以下命令获取特定文档。

    Linux & macOS
    aws ssm get-document \
    --name document name
    Windows
    aws ssm get-document ^
    --name document name
    PowerShell
    Get-SSMDocument `
    –Name document name

  4. 使用以下命令获取文档的描述。

    Linux & macOS
    aws ssm describe-document \
    --name document name
    Windows
    aws ssm describe-document ^
    --name document name
    PowerShell
    Get-SSMDocumentDescription `
    –Name document name

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

    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

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

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

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

    注意

    如果您公开（与 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 文档的权限

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

停止共享文档（控制台）

停止共享文档

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

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

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

  4. 选择编辑。

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

停止共享文档（命令行）

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

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

使用共享 SSM 文档

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

注意

您无需为 Amazon 公有文档（以 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