Creating associations
State Manager, a capability of Amazon Systems Manager, helps you keep your Amazon resources in a state that you define and reduce configuration drift. To do this, State Manager uses associations. An association is a configuration that you assign to your Amazon resources. The configuration defines the state that you want to maintain on your resources. For example, an association can specify that antivirus software must be installed and running on a managed node, or that certain ports must be closed.
An association specifies a schedule for when to apply the configuration and the targets for the association. For example, an association for antivirus software might run once a day on all managed nodes in an Amazon Web Services account. If the software isn't installed on a node, then the association could instruct State Manager to install it. If the software is installed, but the service isn't running, then the association could instruct State Manager to start the service.
Warning
When you create an association, you can choose an Amazon resource group of managed nodes as the target for the association. If an Amazon Identity and Access Management (IAM) user, group, or role has permission to create an association that targets a resource group of managed nodes, then that user, group, or role automatically has root-level control of all nodes in the group. Permit only trusted administrators to create associations.
Association targets and rate controls
An association specifies which managed nodes, or targets, should receive the association. State Manager includes several features to help you target your managed nodes and control how the association is deployed to those targets. For more information about targets and rate controls, see About targets and rate controls in State Manager associations.
Tagging associations
You can assign tags to an association when you create it by using a command line tool such as the Amazon CLI or Amazon Tools for PowerShell. Adding tags to an association by using the Systems Manager console isn't supported. For more information about tags, see Tagging Systems Manager resources.
Running associations
By default, State Manager runs an association immediately after you create it, and then according to the schedule that you've defined.
The system also runs associations according to the following rules:
-
State Manager attempts to run the association on all specified or targeted nodes during an interval.
-
If an association doesn't run during an interval (because, for example, a concurrency value limited the number of nodes that could process the association at one time), then State Manager attempts to run the association during the next interval.
-
State Manager runs the association after changes to the association's configuration, target nodes, documents, or parameters. For more information, see When are associations applied to resources?
-
State Manager records history for all skipped intervals. You can view the history on the Execution History tab.
Scheduling associations
You can schedule associations to run at basic intervals such as every 10 hours, or you can create more advanced schedules using custom cron and rate expressions. You can also prevent associations from running when you first create them.
Using cron and rate expressions to schedule association runs
In addition to standard cron and rate expressions, State Manager also supports cron expressions that include a day of the week and the number sign (#) to designate the nth day of a month to run an association. Here is an example that runs a cron schedule on the third Tuesday of every month at 23:30 UTC:
cron(30 23 ? * TUE#3 *)
Here is an example that runs on the second Thursday of every month at midnight UTC:
cron(0 0 ? * THU#2 *)
State Manager also supports the (L) sign to indicate the last X day of the month. Here is an example that runs a cron schedule on the last Tuesday of every month at midnight UTC:
cron(0 0 ? * 3L *)
To further control when an association runs, for example if you want to run an
association two days after patch Tuesday, you can specify an offset. An
offset defines how many days to wait after the
scheduled day to run an association. For example, if you specified a cron
schedule of cron(0 0 ? * THU#2 *)
, you could specify the number 3
in the Schedule offset field to run the association each
Sunday after the second Thursday of the month.
Note
To use offsets, you must either select Apply association only at
the next specified Cron interval in the console or specify
the ApplyOnlyAtCronInterval
parameter from the command line.
When either of these options are activated, State Manager doesn't run the
association immediately after you create it.
For more information about cron and rate expressions, see Reference: Cron and rate expressions for Systems Manager.
Create an association (console)
The following procedure describes how to use the Systems Manager console to create a State Manager association.
Important
This procedure describes how to create an association that uses either a
Command
or a Policy
document to target managed
nodes. For information about creating an association that uses an Automation
runbook to target nodes or other types of Amazon resources, see Scheduling
automations with State Manager associations.
To create a State Manager association
Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/
. In the navigation pane, choose State Manager.
-
Choose Create association.
-
In the Name field, specify a name.
-
In the Document list, choose the option next to a document name. Note the document type. This procedure applies to
Command
andPolicy
documents. For information about creating an association that uses an Automation runbook, see Scheduling automations with State Manager associations.Important
State Manager doesn't support running associations that use a new version of a document if that document is shared from another account. State Manager always runs the
default
version of a document if shared from another account, even though the Systems Manager console shows that a new version was processed. If you want to run an association using a new version of a document shared form another account, you must set the document version todefault
. -
For Parameters, specify the required input parameters.
-
(Optional) Choose a CloudWatch alarm to apply to your association for monitoring.
Note
Note the following information about this step.
-
The alarms list displays a maximum of 100 alarms. If you don't see your alarm in the list, use the Amazon Command Line Interface to create the association. For more information, see Create an association (command line).
-
To attach a CloudWatch alarm to your command, the IAM principal that creates the association must have permission for the
iam:createServiceLinkedRole
action. For more information about CloudWatch alarms, see Using Amazon CloudWatch alarms. -
If your alarm activates, any pending command invocations or automations do not run.
-
-
For Targets, choose an option. For information about using targets, see About targets and rate controls in State Manager associations.
-
In the Specify schedule section, choose either On Schedule or No schedule. If you choose On Schedule, use the buttons provided to create a cron or rate schedule for the association.
If you don't want the association to run immediately after you create it, choose Apply association only at the next specified Cron interval.
-
(Optional) In the Schedule offset field, specify a number between 1 and 6.
-
In the Advanced options section use Compliance severity to choose a severity level for the association and use Change Calendars to choose a change calendar for the association.
Compliance reporting indicates whether the association state is compliant or noncompliant, along with the severity level you indicate here. For more information, see About State Manager association compliance.
The change calendar determines when the association runs. If the calendar is closed, the association isn't applied. If the calendar is open, the association runs accordingly. For more information, see Amazon Systems Manager Change Calendar.
-
In the Rate control section, choose options to control how the association runs on multiple nodes. For more information about using rate controls, see About targets and rate controls in State Manager associations.
In the Concurrency section, choose an option:
-
Choose targets to enter an absolute number of targets that can run the association simultaneously.
-
Choose percentage to enter a percentage of the target set that can run the association simultaneously.
In the Error threshold section, choose an option:
-
Choose errors to enter an absolute number of errors that are allowed before State Manager stops running associations on additional targets.
-
Choose percentage to enter a percentage of errors that are allowed before State Manager stops running associations on additional targets.
-
(Optional) For Output options, to save the command output to a file, select the Enable writing output to S3 box. Enter the bucket and prefix (folder) names in the boxes.
Note
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile assigned to the managed node, not those of the IAM user performing this task. For more information, see Configure instance permissions required for Systems Manager or Create an IAM service role for a hybrid environment. In addition, if the specified S3 bucket is in a different Amazon Web Services account, verify that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket.
Following are the minimal permissions required to turn on Amazon S3 output for an association. You can further restrict access by attaching IAM policies to users or roles within an account. At minimum, an Amazon EC2 instance profile should have an IAM role with the
AmazonSSMManagedInstanceCore
managed policy and the following inline policy.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:PutObjectAcl" ], "Resource": "arn:aws-cn:s3:::
amzn-s3-demo-bucket
/*" } ] }For minimal permissions, the Amazon S3 bucket you export to must have the default settings defined by the Amazon S3 console. For more information about creating Amazon S3 buckets, see Creating a bucket in the Amazon S3 User Guide.
Note
API operations that are initiated by the SSM document during an association run are not logged in Amazon CloudTrail.
-
Choose Create Association.
Note
If you delete the association you created, the association no longer runs on any targets of that association.
Create an association (command line)
The following procedure describes how to use the Amazon CLI (on Linux or Windows) or Tools for PowerShell to create a State Manager association. This section includes several examples that show how to use targets and rate controls. Targets and rate controls allow you to assign an association to dozens or hundreds of nodes while controlling the execution of those associations. For more information about targets and rate controls, see About targets and rate controls in State Manager associations.
Important
This procedure describes how to create an association that uses either a
Command
or a Policy
document to target managed
nodes. For information about creating an association that uses an Automation
runbook to target nodes or other types of Amazon resources, see Scheduling
automations with State Manager associations.
Before you begin
The targets
parameter is an array of search criteria that
targets nodes using a Key
,Value
combination that
you specify. If you plan to create an association on dozens or hundreds of
node by using the targets
parameter, review the following
targeting options before you begin the procedure.
Target specific nodes by specifying IDs
--targets Key=InstanceIds,Values=
instance-id-1
,instance-id-2
,instance-id-3
--targets Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE
Target instances by using tags
--targets Key=tag:
tag-key
,Values=tag-value-1
,tag-value-2
,tag-value-3
--targets Key=tag:Environment,Values=Development,Test,Pre-production
Target nodes by using Amazon Resource Groups
--targets Key=resource-groups:Name,Values=
resource-group-name
--targets Key=resource-groups:Name,Values=WindowsInstancesGroup
Target all instances in the current Amazon Web Services account and Amazon Web Services Region
--targets Key=InstanceIds,Values=*
Note
Note the following information.
-
State Manager doesn't support running associations that use a new version of a document if that document is shared from another account. State Manager always runs the
default
version of a document if shared from another account, even though the Systems Manager console shows that a new version was processed. If you want to run an association using a new version of a document shared form another account, you must set the document version todefault
. -
You can specify a maximum of five tag keys by using the Amazon CLI. If you use the Amazon CLI, all tag keys specified in the
create-association
command must be currently assigned to the node. If they aren't, State Manager fails to target the node for an association. For information about assigning tags to your nodes, see Tagging Systems Manager resources. -
When you create an association, you specify when the schedule runs. Specify the schedule by using a cron or rate expression. For more information about cron and rate expressions, see Cron and rate expressions for associations.
To create an association
Install and configure the Amazon CLI or the Amazon Tools for PowerShell, if you haven't already.
For information, see Installing or updating the latest version of the Amazon CLI and Installing the Amazon Tools for PowerShell.
-
Use the following format to create a command that creates a State Manager association. Replace each
example resource placeholder
with your own information.The following example creates an association on nodes tagged with
"Environment,Linux"
. The association uses theAWS-UpdateSSMAgent
document to update the SSM Agent on the targeted nodes at 2:00 UTC every Sunday morning. This association runs simultaneously on 10 nodes maximum at any given time. Also, this association stops running on more nodes for a particular execution interval if the error count exceeds 5. For compliance reporting, this association is assigned a severity level of Medium.The following example targets node IDs by specifying a wildcard value (*). This allows Systems Manager to create an association on all nodes in the current Amazon Web Services account and Amazon Web Services Region. This association runs simultaneously on 10 nodes maximum at any given time. Also, this association stops running on more nodes for a particular execution interval if the error count exceeds 5. For compliance reporting, this association is assigned a severity level of Medium. This association uses a schedule offset, which means it runs two days after the specified cron schedule. It also includes the
ApplyOnlyAtCronInterval
parameter, which is required to use the schedule offset and which means the association won't run immediately after it is created.The following example creates an association on nodes in Resource Groups. The group is named "HR-Department". The association uses the
AWS-UpdateSSMAgent
document to update SSM Agent on the targeted nodes at 2:00 UTC every Sunday morning. This association runs simultaneously on 10 nodes maximum at any given time. Also, this association stops running on more nodes for a particular execution interval if the error count exceeds 5. For compliance reporting, this association is assigned a severity level of Medium. This association runs at the specified cron schedule. It doesn't run immediately after the association is created.The following example creates an association that runs on nodes tagged with a specific node ID. The association uses the SSM Agent document to update SSM Agent on the targeted nodes once when the change calendar is open. The association checks the calendar state when it runs. If the calendar is closed at launch time and the association is only run once, it won't run again because the association run window has passed. If the calendar is open, the association runs accordingly.
Note
If you add new nodes to the tags or resource groups that an association acts on when the change calendar is closed, the association is applied to those nodes once the change calendar opens.
The following example creates an association that runs on nodes tagged with a specific node ID. The association uses the SSM Agent document to update SSM Agent on the targeted nodes on the targeted nodes at 2:00 AM every Sunday. This association runs only at the specified cron schedule when the change calendar is open. When the association is created, it checks the calendar state. If the calendar is closed, the association isn't applied. When the interval to apply the association starts at 2:00 AM on Sunday, the association checks to see if the calendar is open. If the calendar is open, the association runs accordingly.
Note
If you add new nodes to the tags or resource groups that an association acts on when the change calendar is closed, the association is applied to those nodes once the change calendar opens.
Note
If you delete the association you created, the association no longer runs
on any targets of that association. Also, if you specified the
apply-only-at-cron-interval
parameter, you can reset this
option. To do so, specify the no-apply-only-at-cron-interval
parameter when you update the association from the command line. This
parameter forces the association to run immediately after updating the
association and according to the interval specified.