Menu
Amazon EC2 Systems Manager
User Guide

State Manager Associations

After you define the actions to perform on your instances in a policy document, you create an association. An association binds a policy document and one or more targets. Any actions defined in the document will be applied to instances when you create the association and when the association runs during scheduled times. You can create an association using the Amazon EC2 console, the AWS CLI, AWS Tools for Windows PowerShell, or the AWS SDKs. For examples of how to create and use associations using the Amazon EC2 console and the AWS CLI, see Systems Manager State Manager Walkthroughs.

When you create an association, specify the following items.

  • A policy document to use.

  • The instances that should be associated with the policy document. You choose instances by manually selecting them, or by using the Targets option, which locates instances using EC2 tags.

  • A schedule, which specifies how often the association should run.

  • Parameters to execute when applying the association.

  • An Amazon S3 bucket where the output should be written.

Scheduling and Running Associations

State Manager processes association tasks when you create the association. You can also run tasks on demand or set a schedule when the association should be reapplied. If you set a schedule, you can still run the association on demand.

Note

If a new association is scheduled to run while an earlier association is still running, the earlier association will be timed out and the new association will execute.

Your instances are accessible while associations are running.

Creating Associations Using the Targets Parameter

You can create associations on tens, hundreds, or thousands of instances by using the targets parameter. The targets parameter accepts a Key,Value combination based on Amazon EC2 tags that you specified for your instances. When you execute the request to create the association, the system locates and attempts to create the association on all instances that match the specified criteria. For more information about the targets parameter, see, Sending Commands to a Fleet. For more information about Amazon EC2 tags, see Tagging Your Amazon EC2 Resources in the Amazon EC2 User Guide.

The following AWS CLI examples show you how to use the targets parameter when creating associations. The example commands have been truncated using [...].

Create an association for all the database servers (hosts with a tag named "Database" regardless of tag value).

Copy
aws ssm create-association --name value --targets "Key=tag:Database"[...]

Create an association for a managed instance named "ws-0123456789012345"

Copy
aws ssm create-association --name value --targets "Key=Instance Ids,Values=ws-0123456789"} [...]

Note

If you remove an instance from a tagged group that’s associated with a document, then the instance will be dissociated from the document.