创建关联

State Manager（Amazon Systems Manager 的一种功能）可以帮助您将 Amazon 资源保持在您定义的状态，并减少配置偏移。为此，State Manager 会使用关联。关联是指分配给 Amazon 资源的配置。该配置定义要在资源上保持的状态。例如，关联可以指定必须在托管式节点上安装并运行防病毒软件，或必须关闭特定端口。

关联指定了何时应用关联的配置和目标的计划。例如，防病毒软件的关联可能会每天在 Amazon Web Services 账户中的所有托管式节点上运行一次。如果该软件未安装在节点上，则关联可以指示 State Manager 安装该软件。如果已安装该软件，但未运行服务，则关联可以指示 State Manager 开启服务。

注意

通过使用命令行工具（如 Amazon CLI 或 Amazon Tools for PowerShell）创建关联时，可以将标签指定给关联。不支持使用 Systems Manager 控制台将标签添加到关联。有关标签的更多信息，请参阅标记 Systems Manager 资源。

以下过程说明了如何创建使用 Command 或 Policy 文档来将托管式节点设为目标的关联。有关创建使用自动化运行手册以将节点或其他类型 Amazon 资源设为目标的关联的信息，请参阅使用 State Manager 关联调度自动化。

关联目标和速率控制

关联将指定哪些托管节点或目标应该接收关联。State Manager 包括的一些功能可帮助您将托管节点设置为目标，并控制如何将关联部署到这些目标。有关目标和速率控制的更多信息，请参阅关于 State Manager 关联中的目标和速率控制。

运行关联

默认情况下，State Manager 将在您创建关联后立即运行关联，然后根据您定义的计划运行。

该系统还会根据以下规则运行关联：

State Manager 在间隔期间会尝试在所有指定或目标节点上运行关联。
如果在某个周期内未运行某一关联（例如，由于并发值限制了可以同时处理关联的节点数），State Manager 将尝试在下一个周期运行该关联。
State Manager 将在更改关联的配置、目标节点、文档或参数后运行关联。有关更多信息，请参阅何时将关联应用于资源？
State Manager 会记录所有已跳过间隔的历史记录。可在 Execution History (执行历史记录) 选项卡上查看历史记录。

为关联制定计划

您可以安排关联以基本间隔（如每 10 小时）运行，也可以使用自定义 cron 和费率表达式创建更高级的计划。您还可以在首次创建关联时阻止关联运行。

使用 cron 和 rate 表达式为关联运行制定计划

除了标准 cron 和 rate 表达式外，State Manager 还支持多种 cron 表达式，其中包括在一周中的某一天运行关联，以及用于指定在一个月中的第 n 天运行关联的数字符号（#）。以下是一个在每月的第三个星期二 23:30 UTC 运行 cron 计划的示例：

cron(30 23 ? * TUE#3 *)

以下是一个在每月的第二个星期四在 UTC 午夜运行的示例：

cron(0 0 ? * THU#2 *)

State Manager 还支持 (L) 符号来表示一个月的最后一个 X 天。以下是一个在每月的最后一个星期二 UTC 午夜运行 cron 计划的示例：

cron(0 0 ? * 3L *)

要进一步控制关联运行的时间，例如，如果您想在星期二补丁后两天运行关联，可以指定偏移量。偏移量定义了在计划日期之后等待多少天再运行关联。例如，如果指定的 cron 计划为 cron(0 0 ? * THU#2 *)，则可以在 Schedule offset（计划偏移量）字段中指定数字 3，以便在每月的第二个星期四之后的每个星期天运行关联。

注意

要使用偏移量，必须在控制台中选择仅在下一个指定的 Cron 周期应用关联，或从命令行指定 ApplyOnlyAtCronInterval 参数。在激活其中任一选项后，State Manager 不会在您创建关联后立即运行该关联。

有关 cron 和 rate 表达式的更多信息，请参阅参考：适用于 Systems Manager 的 Cron 和 Rate 表达式。

创建关联（控制台）

以下过程介绍了如何使用 Systems Manager 控制台创建 State Manager 关联。

警告

创建关联时，可以选择托管式节点的 Amazon 资源组作为关联的目标。如果 Amazon Identity and Access Management (IAM) 用户、组或角色有权限创建将托管式节点资源组设为目标的关联，则该用户、组或角色将自动具有组中所有节点的根级控制权。只允许受信任的管理员创建关联。

创建 State Manager 关联

访问 https://console.aws.amazon.com/systems-manager/，打开 Amazon Systems Manager 控制台。
在导航窗格中，选择 State Manager。

-或者-

如果首先打开 Amazon Systems Manager 主页，选择菜单图标 ( ) 打开导航窗格，然后选择 State Manager。
选择 Create association（创建关联）。
在名称字段中指定名称。
在文档列表中，选择文档名称旁边的选项。请注意文档类型。此过程适用于 Command 和 Policy 文档。有关创建使用自动化运行手册的关联的信息，请参阅使用 State Manager 关联调度自动化。

重要
如果该文档是从其他账户共享的，则 State Manager 不支持运行使用该文档的新版本的关联。如果文档是共享自另一个账户，即使 Systems Manager 控制台显示已处理该文档的新版本，状态管理器仍会运行该文档的 default 版本。如果要使用共享自另一个账户的文档的新版本来运行关联，则必须将文档版本设置为 default。
对于 Parameters (参数)，请指定所需的输入参数。
（可选）选择一个 CloudWatch 警报以应用于您的关联进行监控。
注意
请注意与该步骤相关的以下信息。
- 警报列表最多显示 100 个警报。如果您未在列表中看到您的警报，请使用 Amazon Command Line Interface 创建关联。有关更多信息，请参阅创建关联（命令行）。
- 要将 CloudWatch 警报附加到命令，创建关联的 IAM 主体必须具有 iam:createServiceLinkedRole 操作的权限。有关 CloudWatch 警报的更多信息，请参阅使用 Amazon CloudWatch 警报。
- 如果您的警报激活，任何待处理的命令调用或自动化都不会运行。
对于 Targets (目标)，选择一个选项。有关使用目标的信息，请参阅关于 State Manager 关联中的目标和速率控制。
在 Specify schedule (指定计划) 部分中，选择 On Schedule (按计划) 或 No schedule (无计划)。如果选择 On Schedule (按计划)，则可使用提供的按钮为关联创建 cron 或 rate 计划。

如果您不希望关联在创建后立即运行，请选中 Apply association only at the next specified Cron interval (仅在下一个指定的 Cron 周期应用关联)。
（可选）在 Schedule offset（计划偏移量）字段中，指定一个介于 1 和 6 之间的数字。
在高级选项部分使用合规性严重性选择关联的严重级别，然后使用更改日历选择关联的更改日历。

合规性报告指示关联状态是合规还是不合规以及您在此处指示的严重级别。有关更多信息，请参阅关于 State Manager 关联合规性。

更改日历确定关联何时运行。如果日历已关闭，则不应用关联。如果日历处于打开状态，则相应地运行关联。有关更多信息，请参阅 Amazon Systems Manager Change Calendar。
在 Rate control（速率控制）部分中，选择用于控制如何在多个节点上运行关联的选项。有关使用速率控制的更多信息，请参阅关于 State Manager 关联中的目标和速率控制。

在并发部分中，选择一个选项：
- 选择 targets (目标) 输入可同时运行关联的目标的绝对数量。
- 选择 percentage (百分比) 输入可同时运行关联的目标集的百分比。
在错误阈值部分中，选择一个选项：
- 选择 errors (错误) 以输入允许的错误绝对数量，超过该数量后 State Manager 停止对其他目标运行关联。
- 选择 percentage (百分比) 以输入允许的错误百分比，超过该百分比后 State Manager 停止对其他目标运行关联。
（可选）对于 Output options (输出选项)，要将命令输出保存到文件，请选中 Enable writing output to S3 (启用将输出写入 S3) 方框。在方框中输入存储桶和前缀（文件夹）名称。

注意
授予将数据写入 S3 存储桶的能力的 S3 权限，是分配给托管式节点的实例配置文件的权限，而不是执行此任务的 IAM 用户的权限。有关更多信息，请参阅为 Systems Manager 配置实例权限或为混合环境创建 IAM 服务角色。此外，如果指定的 S3 存储桶位于不同的 Amazon Web Services 账户中，请确认与该托管式节点关联的实例配置文件或 IAM 服务角色具有写入该存储桶的所需权限。

以下是为关联打开 Amazon S3 输出所需的最低权限。您可以通过将 IAM policy 附加到账户内的用户或角色，以进一步限制访问权限。Amazon EC2 实例配置文件至少应具有一个具有 AmazonSSMManagedInstanceCore 托管策略和以下内联策略的 IAM 角色。
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*"
        }
    ]
}
```
对于最低权限，导出到的 Amazon S3 存储桶必须具有 Amazon S3 控制台定义的默认设置。有关创建存储桶的更多信息，请转至 Amazon S3 用户指南中的创建存储桶。

注意
在关联运行期间由 SSM 文档发起的 API 操作未登录 Amazon CloudTrail。
选择创建关联。

注意

如果您删除已创建的关联，则该关联将不再在该关联的任何目标上运行。

创建关联（命令行）

以下过程介绍了如何使用 Amazon CLI（在 Linux 或 Windows 上）或创建 State Manager 关联的 Tools for PowerShell 。本节包括几个示例，说明如何使用目标和速率控制。通过目标和速率控制，您可以将关联分配给数十个或数百个节点，同时控制这些关联的执行。有关目标和速率控制的更多信息，请参阅关于 State Manager 关联中的目标和速率控制。

开始前的准备工作

targets 参数是一组搜索条件，使用您指定的 Key,Value 组合将节点设为目标。如果您计划使用 targets 参数在数十个或数百个节点上创建关联，请在开始该过程之前查看以下设置目标选项。

通过指定 ID 将特定节点设为目标


--targets Key=InstanceIds,Values=instance-id-1,instance-id-2,instance-id-3


--targets Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE

通过使用标签将实例设为目标


--targets Key=tag:tag-key,Values=tag-value-1,tag-value-2,tag-value-3


--targets Key=tag:Environment,Values=Development,Test,Pre-production

通过使用 Amazon Resource Groups 将节点设为目标


--targets Key=resource-groups:Name,Values=resource-group-name


--targets Key=resource-groups:Name,Values=WindowsInstancesGroup

在当前 Amazon Web Services 账户和 Amazon Web Services 区域将所有的实例设为目标


--targets Key=InstanceIds,Values=*

注意

请注意以下信息。

如果该文档是从其他账户共享的，则 State Manager 不支持运行使用该文档的新版本的关联。如果文档是共享自另一个账户，即使 Systems Manager 控制台显示已处理该文档的新版本，状态管理器仍会运行该文档的 default 版本。如果要使用共享自另一个账户的文档的新版本来运行关联，则必须将文档版本设置为 default。
您可以使用 Amazon CLI 指定最多五个标签键。如果使用 Amazon CLI，则 create-association 命令中指定的所有标签键当前都必须分配给该节点。如果没有分配给该节点，则 State Manager 无法将该节点作为关联目标。有关为节点分配标签的信息，请参阅标记 Systems Manager 资源。
当创建关联时，需要指定计划运行的时间。使用 cron 或 rate 表达式指定计划。有关 cron 和 rate 表达式的更多信息，请参阅适用于关联的 Cron 和 Rate 表达式。

创建关联

安装并配置 Amazon CLI 或 Amazon Tools for PowerShell（如果尚未执行该操作）。

有关信息，请参阅安装或更新 Amazon CLI 的最新版本以及安装 Amazon Tools for PowerShell。

使用以下格式创建一个命令以创建 State Manager 关联。将每个示例资源占位符替换为您自己的信息。

Linux & macOS


aws ssm create-association \
    --name document_name \
    --document-version version_of_document_applied \
    --instance-id instances_to_apply_association_on \
    --parameters (if any) \
    --targets target_options \
    --schedule "cron_or_rate_expression" \
    --apply-only-at-cron-interval required_parameter_for_schedule_offsets \
    --schedule-offset number_between_1_and_6 \
    --output-location s3_bucket_to_store_output_details \
    --association-name association_name \
    --max-errors a_number_of_errors_or_a_percentage_of_target_set \
    --max-concurrency a_number_of_instances_or_a_percentage_of_target_set \
    --compliance-severity severity_level \
    --calendar-names change_calendar_names \
    --target-locations aws_region_or_account \
    --tags "Key=tag_key,Value=tag_value"

Windows


aws ssm create-association ^
    --name document_name ^
    --document-version version_of_document_applied ^
    --instance-id instances_to_apply_association_on ^
    --parameters (if any) ^
    --targets target_options ^
    --schedule "cron_or_rate_expression" ^
    --apply-only-at-cron-interval required_parameter_for_schedule_offsets ^
    --schedule-offset number_between_1_and_6 ^
    --output-location s3_bucket_to_store_output_details ^
    --association-name association_name ^
    --max-errors a_number_of_errors_or_a_percentage_of_target_set ^
    --max-concurrency a_number_of_instances_or_a_percentage_of_target_set ^
    --compliance-severity severity_level ^
    --calendar-names change_calendar_names ^
    --target-locations aws_region_or_account ^
    --tags "Key=tag_key,Value=tag_value"

PowerShell


New-SSMAssociation `
    -Name document_name `
    -DocumentVersion version_of_document_applied `
    -InstanceId instances_to_apply_association_on `
    -Parameters (if any) `
    -Target target_options `
    -ScheduleExpression "cron_or_rate_expression" `
    -ApplyOnlyAtCronInterval required_parameter_for_schedule_offsets `
    -ScheduleOffSet number_between_1_and_6 `
    -OutputLocation s3_bucket_to_store_output_details `
    -AssociationName association_name `
    -MaxError  a_number_of_errors_or_a_percentage_of_target_set
    -MaxConcurrency a_number_of_instances_or_a_percentage_of_target_set `
    -ComplianceSeverity severity_level `
    -CalendarNames change_calendar_names `
    -TargetLocations aws_region_or_account `
    -Tags "Key=tag_key,Value=tag_value"

以下示例在已贴标签 "Environment,Linux" 的节点上创建关联。该关联在每个星期日 2:00 UTC 时使用 AWS-UpdateSSMAgent 文档更新目标节点上的 SSM Agent。该关联在任意给定时间最多在 10 个节点上同时运行。此外，当错误计数超过 5 时，将在特定执行间隔内停止在更多节点上运行该关联。对于合规性报告，为该关联分配中等严重级别。

以下示例通过指定通配符值 (*) 来将节点 ID 指定为目标。这允许 Systems Manager 在当前 Amazon Web Services 账户和 Amazon Web Services 区域中的所有节点上创建关联。该关联在任意给定时间最多在 10 个节点上同时运行。此外，当错误计数超过 5 时，将在特定执行间隔内停止在更多节点上运行该关联。对于合规性报告，为该关联分配中等严重级别。此关联使用了计划偏移量，这意味着将在指定的 cron 计划后两天运行。其还包括 ApplyOnlyAtCronInterval 参数，该参数是使用计划偏移量所必需的，这意味着关联在创建后不会立即运行。

以下示例在 Resource Groups 中的节点上创建关联。该组名为“HR-Department”。该关联在每个星期日 2:00 UTC 时使用 AWS-UpdateSSMAgent 文档更新目标节点上的 SSM Agent。该关联在任意给定时间最多在 10 个节点上同时运行。此外，当错误计数超过 5 时，将在特定执行间隔内停止在更多节点上运行该关联。对于合规性报告，为该关联分配中等严重级别。此关联按指定的 cron 计划运行。它不会在创建后立即运行。

以下示例创建一个关联，该关联在已标记特定节点 ID 的节点上运行。当更改日历处于打开状态时，该关联使用 SSM Agent 文档在目标节点上更新 SSM Agent。关联在运行时检查日历状态。如果日历在启动时关闭，并且关联仅运行一次，则不会再次运行，因为关联运行窗口已通过。如果日历处于打开状态，则相应地运行关联。

注意

如果在更改日历关闭时将新节点添加到关联所依据的标签或 resource groups，则在更改日历打开后，关联将应用于这些节点。

以下示例创建一个关联，该关联在已标记特定节点 ID 的节点上运行。该关联在每个星期日 2:00 时使用 SSM Agent 文档更新目标节点上的 SSM Agent。此关联仅在更改日历打开时按指定的 cron 计划运行。创建关联时，它会检查日历状态。如果日历已关闭，则不应用关联。当应用关联的时间间隔从星期日凌晨 2:00 开始时，关联将检查日历是否处于打开状态。如果日历处于打开状态，则相应地运行关联。

注意

如果在更改日历关闭时将新节点添加到关联所依据的标签或 resource groups，则在更改日历打开后，关联将应用于这些节点。

注意

如果您删除已创建的关联，则该关联将不再在该关联的任何目标上运行。此外，如果指定了 apply-only-at-cron-interval 参数，还可以重置此选项。要执行此操作，请在从命令行更新关联时指定 no-apply-only-at-cron-interval 参数。此参数会强制关联在更新后立即运行，以及按照指定的周期运行。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

关于目标和速率控制

编辑关联

创建关联

注意

关联目标和速率控制

运行关联

为关联制定计划

使用 cron 和 rate 表达式为关联运行制定计划

注意

创建关联（控制台）

警告

创建 State Manager 关联

重要

注意

注意

注意

注意

创建关联（命令行）

开始前的准备工作

注意

创建关联

注意

注意

注意