创建关联 - Amazon Systems Manager
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

创建关联

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 资源

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

开始前的准备工作

创建关联时,可以指定关联的计划,也可以立即运行关联。如果指定计划,则必须以 cron 或 rate 表达式的形式输入计划。有关 cron 和 rate 表达式的更多信息,请参阅 参考:适用于 Systems Manager 的 Cron 和 Rate 表达式

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

关于创建关联

在创建关联时,原定设置下,系统会立即在指定的资源上运行该关联。在初始运行后,关联会根据定义的计划和以下规则按周期运行:

  • State Manager 在间隔期间会尝试在所有指定或目标节点上运行关联。

  • 如果在某个周期内未运行某一关联(例如,由于并发值限制了可以同时处理关联的节点数),State Manager 将尝试在下一个周期运行该关联。

  • State Manager 会记录所有已跳过间隔的历史记录。可在 Execution History (执行历史记录) 选项卡上查看历史记录。

对于根据计划运行的关联,可以指定定义关联运行时间的标准 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,以便在每月的第二个星期四之后的每个星期天运行关联。

注意

要使用偏移量,必须在控制台中选择 Apply association only at the next specified Cron interval(仅在下一个指定的 Cron 周期应用关联)选项,或者必须从命令行指定 ApplyOnlyAtCronInterval 参数。此选项将告知 State Manager 不要在创建关联后立即运行关联。

创建关联(控制台)

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

警告

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

创建 State Manager 关联

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

  2. 在导航窗格中,选择 State Manager

    -或者-

    如果首先打开 Amazon Systems Manager 主页,选择菜单图标 ( ) 打开导航窗格,然后选择 State Manager

  3. 选择 Create association(创建关联)

  4. 名称 字段中指定名称。

  5. 文档列表中,选择文档名称旁边的选项。请注意文档类型。此过程适用于 CommandPolicy 文档。有关创建使用自动化运行手册的关联的信息,请参阅 使用 State Manager 关联运行自动化

    重要

    如果该文档是从其他账户共享的,则 State Manager 不支持运行使用该文档的新版本的关联。如果文档是共享自另一个账户,即使 Systems Manager 控制台显示已处理该文档的新版本,状态管理器仍会运行该文档的 default 版本。如果要使用共享自另一个账户的文档的新版本来运行关联,则必须将文档版本设置为 default

  6. 对于 Parameters (参数),请指定所需的输入参数。

  7. (可选)选择一个 CloudWatch 警报以应用于您的关联进行监控。要将 CloudWatch 警报附加到命令,创建关联的 IAM 主体必须具有 iam:createServiceLinkedRole 操作的权限。有关 CloudWatch 警报的更多信息,请参阅使用 Amazon CloudWatch 警报。请注意,如果您的警报激活,任何待处理的命令调用或自动化都不会运行。

  8. 对于 Targets (目标),选择一个选项。有关使用目标的信息,请参阅 关于 State Manager 关联中的目标和速率控制

  9. Specify schedule (指定计划) 部分中,选择 On Schedule (按计划)No schedule (无计划)。如果选择 On Schedule (按计划),则可使用提供的按钮为关联创建 cron 或 rate 计划。

    如果您不希望关联在创建后立即运行,请选中 Apply association only at the next specified Cron interval (仅在下一个指定的 Cron 周期应用关联)

  10. (可选)在 Schedule offset(计划偏移量)字段中,指定一个介于 1 和 6 之间的数字。

  11. 高级选项部分使用合规性严重性选择关联的严重级别,然后使用更改日历选择关联的更改日历。

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

    更改日历确定关联何时运行。如果日历已关闭,则不应用关联。如果日历处于打开状态,则相应地运行关联。有关更多信息,请参阅Amazon Systems Manager Change Calendar

  12. Rate control(速率控制)部分中,选择用于控制如何在多个节点上运行关联的选项。有关使用速率控制的更多信息,请参阅 关于 State Manager 关联中的目标和速率控制

    并发部分中,选择一个选项:

    • 选择 targets (目标) 输入可同时运行关联的目标的绝对数量。

    • 选择 percentage (百分比) 输入可同时运行关联的目标集的百分比。

    错误阈值部分中,选择一个选项:

    • 选择 errors (错误) 以输入允许的错误绝对数量,超过该数量后 State Manager 停止对其他目标运行关联。

    • 选择 percentage (百分比) 以输入允许的错误百分比,超过该百分比后 State Manager 停止对其他目标运行关联。

  13. (可选)对于 Output options (输出选项),要将命令输出保存到文件,请选中 Enable writing output to S3 (启用将输出写入 S3) 方框。在方框中输入存储桶和前缀(文件夹)名称。

    注意

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

    以下是为关联打开 Amazon S3 输出所需的最低权限。您可以进一步限制对账户内个别 IAM 用户或角色的访问权限。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 用户指南中的创建存储桶

  14. 选择创建关联

注意

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

创建关联(命令行)

以下过程介绍了如何使用 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
注意

使用标签时,您只能使用一个标签键。如果要使用多个标签键把节点设为目标,请使用 resource group 选项。

通过使用 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

  • 当创建关联时,需要指定计划运行的时间。使用 cron 或 rate 表达式指定计划。有关 cron 和 rate 表达式的更多信息,请参阅 适用于关联的 Cron 和 Rate 表达式

创建关联

  1. 安装并配置 Amazon CLI 或 Amazon Tools for PowerShell(如果尚未执行该操作)。

    想要了解有关信息,请参阅安装或升级Amazon命令行工具.

  2. 使用以下格式创建一个命令以创建 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 时,将在特定执行间隔内停止在更多节点上运行该关联。对于合规性报告,为该关联分配中等严重级别。

    Linux & macOS
    aws ssm create-association \ --association-name Update_SSM_Agent_Linux \ --targets Key=tag:Environment,Values=Linux \ --name AWS-UpdateSSMAgent \ --compliance-severity "MEDIUM" \ --schedule "cron(0 2 ? * SUN *)" \ --max-errors "5" \ --max-concurrency "10"
    Windows
    aws ssm create-association ^ --association-name Update_SSM_Agent_Linux ^ --targets Key=tag:Environment,Values=Linux ^ --name AWS-UpdateSSMAgent ^ --compliance-severity "MEDIUM" ^ --schedule "cron(0 2 ? * SUN *)" ^ --max-errors "5" ^ --max-concurrency "10"
    PowerShell
    New-SSMAssociation ` -AssociationName Update_SSM_Agent_Linux ` -Name AWS-UpdateSSMAgent ` -Target @{ "Key"="tag:Environment" "Values"="Linux" } ` -ComplianceSeverity MEDIUM ` -ScheduleExpression "cron(0 2 ? * SUN *)" ` -MaxConcurrency 10 ` -MaxError 5

    以下示例创建关联,该关联通过使用 AWS-RunPatchBaseline 文档扫描节点寻找缺失的补丁。此关联的目标是 us-east-2 区域中账户中的所有托管式节点。关联指定 “操作” 和 “RebootOption” 参数。

    Linux & macOS
    aws ssm create-association \ --name "AWS-RunPatchBaseline" \ --association-name "ScanningInstancesForMissingUpdate" \ --targets "Key=instanceids,Values=*" \ --parameters "Operation=Scan,RebootOption=NoReboot" \ --region us-east-2
    Windows
    aws ssm create-association ^ --name "AWS-RunPatchBaseline" ^ --association-name "ScanningInstancesForMissingUpdate" ^ --targets "Key=instanceids,Values=*" ^ --parameters "Operation=Scan,RebootOption=NoReboot" ^ --region us-east-2
    PowerShell
    New-SSMAssociation ` -AssociationName ScanningInstancesForMissingUpdate ` -Name AWS-RunPatchBaseline ` -Target @{ "Key"="instanceids" "Values"="*" } ` -Parameters "Operation=Scan,RebootOption=NoReboot" ` -Region us-east-2

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

    Linux & macOS
    aws ssm create-association \ --association-name Update_SSM_Agent_Linux \ --name "AWS-UpdateSSMAgent" \ --targets "Key=instanceids,Values=*" \ --compliance-severity "MEDIUM" \ --schedule "cron(0 2 ? * SUN#2 *)" \ --apply-only-at-cron-interval \ --schedule-offset 2 \ --max-errors "5" \ --max-concurrency "10" \
    Windows
    aws ssm create-association ^ --association-name Update_SSM_Agent_Linux ^ --name "AWS-UpdateSSMAgent" ^ --targets "Key=instanceids,Values=*" ^ --compliance-severity "MEDIUM" ^ --schedule "cron(0 2 ? * SUN#2 *)" ^ --apply-only-at-cron-interval ^ --schedule-offset 2 ^ --max-errors "5" ^ --max-concurrency "10" ^ --apply-only-at-cron-interval
    PowerShell
    New-SSMAssociation ` -AssociationName Update_SSM_Agent_All ` -Name AWS-UpdateSSMAgent ` -Target @{ "Key"="InstanceIds" "Values"="*" } ` -ScheduleExpression "cron(0 2 ? * SUN#2 *)" ` -ApplyOnlyAtCronInterval ` -ScheduleOffset 2 ` -MaxConcurrency 10 ` -MaxError 5 ` -ComplianceSeverity MEDIUM ` -ApplyOnlyAtCronInterval

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

    Linux & macOS
    aws ssm create-association \ --association-name Update_SSM_Agent_Linux \ --targets Key=resource-groups:Name,Values=HR-Department \ --name AWS-UpdateSSMAgent \ --compliance-severity "MEDIUM" \ --schedule "cron(0 2 ? * SUN *)" \ --max-errors "5" \ --max-concurrency "10" \ --apply-only-at-cron-interval
    Windows
    aws ssm create-association ^ --association-name Update_SSM_Agent_Linux ^ --targets Key=resource-groups:Name,Values=HR-Department ^ --name AWS-UpdateSSMAgent ^ --compliance-severity "MEDIUM" ^ --schedule "cron(0 2 ? * SUN *)" ^ --max-errors "5" ^ --max-concurrency "10" ^ --apply-only-at-cron-interval
    PowerShell
    New-SSMAssociation ` -AssociationName Update_SSM_Agent_Linux ` -Name AWS-UpdateSSMAgent ` -Target @{ "Key"="resource-groups:Name" "Values"="HR-Department" } ` -ScheduleExpression "cron(0 2 ? * SUN *)" ` -MaxConcurrency 10 ` -MaxError 5 ` -ComplianceSeverity MEDIUM ` -ApplyOnlyAtCronInterval

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

    注意

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

    Linux & macOS
    aws ssm create-association \ --association-name CalendarAssociation \ --targets "Key=instanceids,Values=i-0cb2b964d3e14fd9f" \ --name AWS-UpdateSSMAgent \ --calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" \ --schedule "rate(1day)"
    Windows
    aws ssm create-association ^ --association-name CalendarAssociation ^ --targets "Key=instanceids,Values=i-0cb2b964d3e14fd9f" ^ --name AWS-UpdateSSMAgent ^ --calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" ^ --schedule "rate(1day)"
    PowerShell
    New-SSMAssociation ` -AssociationName CalendarAssociation ` -Target @{ "Key"="tag:instanceids" "Values"="i-0cb2b964d3e14fd9f" } ` -Name AWS-UpdateSSMAgent ` -CalendarNames "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" ` -ScheduleExpression "rate(1day)"

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

    注意

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

    Linux & macOS
    aws ssm create-association \ --association-name MultiCalendarAssociation \ --targets "Key=instanceids,Values=i-0cb2b964d3e14fd9f" \ --name AWS-UpdateSSMAgent \ --calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2" \ --schedule "cron(0 2 ? * SUN *)"
    Windows
    aws ssm create-association ^ --association-name MultiCalendarAssociation ^ --targets "Key=instanceids,Values=i-0cb2b964d3e14fd9f" ^ --name AWS-UpdateSSMAgent ^ --calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2" ^ --schedule "cron(0 2 ? * SUN *)"
    PowerShell
    New-SSMAssociation ` -AssociationName MultiCalendarAssociation ` -Name AWS-UpdateSSMAgent ` -Target @{ "Key"="tag:instanceids" "Values"="i-0cb2b964d3e14fd9f" } ` -CalendarNames "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2" ` -ScheduleExpression "cron(0 2 ? * SUN *)"
注意

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