Menu
AWS Systems Manager
User Guide

Systems Manager State Manager Walkthroughs

The following walkthroughs can help you understand how to create and configure State Manager associations by using the Amazon EC2 console or the AWS CLI. These walkthrough can also help you understand how to automatically perform common administrative tasks by using State Manager.

Walkthrough: Automatically Update the SSM Agent

The following procedure walks you through the process of creating a State Manager association using the AWS Command Line Interface (AWS CLI). The association automatically updates the SSM Agent according to a schedule that you specify. For more information about the SSM Agent, see Installing and Configuring SSM Agent.

To view details about the different versions of SSM Agent, see the release notes.

Before You Begin

Before you complete the following procedure, verify that you have at least one running Amazon EC2 instance (Linux or Windows) that is configured for Systems Manager. For more information, see Systems Manager Prerequisites.

To create an association for automatically updating the SSM Agent

  1. Download the latest version of the AWS CLI to your local machine.

  2. Open the AWS CLI and run the following command to specify your credentials and a Region. You must either have administrator privileges in Amazon EC2, or you must have been granted the appropriate permission in AWS Identity and Access Management (IAM).

    aws configure

    The system prompts you to specify the following.

    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  3. Execute the following command to create an association by targeting instances using Amazon EC2 tags. The Schedule parameter sets a schedule to run the association every Sunday morning at 2:00 a.m. (UTC).

    aws ssm create-association --targets Key=tag:TagKey,Values=TagValue --name AWS-UpdateSSMAgent --schedule-expression "cron(0 0 2 ? * SUN *)"

    Note

    State Manager associations do not support all cron and rate expressions. For more information about creating cron and rate expressions for associations, see Working with Cron and Rate Expressions for Systems Manager.

    If you want, you can also target multiple instances by specifying instances IDs in a comma-separated list.

    aws ssm create-association --targets Key=instanceids,Values=InstanceID,InstanceID,InstanceID --name your document name --schedule-expression "cron(0 0 2 ? * SUN *)"

    The system returns information like the following.

    { "AssociationDescription": { "ScheduleExpression": "cron(0 0 2 ? * SUN *)", "Name": "AWS-UpdateSSMAgent", "Overview": { "Status": "Pending", "DetailedStatus": "Creating" }, "AssociationId": "123..............", "DocumentVersion": "$DEFAULT", "LastUpdateAssociationDate": 1504034257.98, "Date": 1504034257.98, "AssociationVersion": "1", "Targets": [ { "Values": [ "TagValue" ], "Key": "tag:TagKey" } ] } }

    The system attempts to create the association on the instance(s) and immediately apply the state. The association status shows Pending.

  4. Execute the following command to view an updated status of the association you just created.

    aws ssm list-associations

    Note

    If your instances are currently running the most recent version of the SSM Agent, the status shows Failed. This is expected behavior. When a new version of the SSM Agent is published, the association automatically installs the new agent, and the status shows Success.

Walkthrough: Automatically Update PV Drivers on EC2 Windows Instances

Amazon Windows AMIs contain a set of drivers to permit access to virtualized hardware. These drivers are used by Amazon EC2 to map instance store and Amazon EBS volumes to their devices. We recommend that you install the latest drivers to improve stability and performance of your EC2 Windows instances. For more information about PV drivers, see AWS PV Drivers.

The following walkthrough shows you how to configure a State Manager association to automatically download and install new AWS PV drivers when the drivers become available.

Before You Begin

Before you complete the following procedure, verify that you have at least one Amazon EC2 Windows instance running that is configured for Systems Manager. For more information, see Systems Manager Prerequisites.

The following procedure describes steps that you perform in the Amazon EC2 console. You can also perform these steps in the new AWS Systems Manager console. The steps in the new console will differ from the steps below.

To create a State Manager association that automatically updates PV drivers

  1. Open the Amazon EC2 console, expand Systems Manager Services in the navigation pane, and then choose State Manager.

  2. Choose Create Association.

  3. In the Association Name field, type a descriptive name.

  4. In the Select Document list, choose AWS-ConfigureAWSPackage.

  5. In the Select Targets by section, choose an option.

    Note

    If you choose to target instances by using tags, and you specify tags that map to Linux instances, the association succeeds on the Windows instance, but fails on the Linux instances. The overall status of the association shows Failed.

  6. In the Schedule section, choose an option. Updated PV drivers are only released a few times a year, so you can schedule the association to run once a month, if you want.

  7. In the Parameters section, choose Install from the Action list.

  8. From the Name list, choose AWSPVDriver. You can leave the Version field empty.

  9. In the Advanced section, choose Write to S3 if you want to write association details to an Amazon S3 bucket.

  10. Disregard the S3Region field. This field is deprecated. Specify the name of your bucket in the S3Bucket Name field. If want to write output to a sub-folder, specify the sub-folder name in the S3Key Prefix field.

  11. Choose Create Association, and then choose Close. The system attempts to create the association on the instance(s) and immediately apply the state. The association status shows Pending.

  12. In the right corner of the Association page, choose the refresh button. If you created the association on one or more EC2 Windows instances, the status changes to Success. If your instances are not properly configured for Systems Manager, or if you inadvertently targeted Linux instances, the status shows Failed.

  13. If the status is Failed, choose the Instances tab and verify that the association was successfully created on your EC2 Windows instances. If Windows instances show a status of Failed, verify that the SSM Agent is running on the instance, and verify that the instance is configured with an IAM role for Systems Manager. For more information, see Systems Manager Prerequisites.