Walkthrough: Create a maintenance window to update SSM Agent (AWS CLI)
The following walkthrough shows you how to use the AWS Command Line Interface (AWS CLI) to create an AWS Systems Manager maintenance window. The walkthrough also describes how to register your managed nodes as targets and register a Systems Manager Run Command task to update SSM Agent.
Before you begin
Before you complete the following procedure, you must either have administrator permissions on the nodes you want to configure or you must have been granted the appropriate permissions in AWS Identity and Access Management (IAM). Additionally, verify that you have at least one running managed node for Linux or Windows Server that is configured for Systems Manager in a hybrid and multicloud environment. For more information, see Setting up AWS Systems Manager.
Topics
Step 1: Get started
To run commands using the AWS CLI
Install and configure the AWS Command Line Interface (AWS CLI), if you haven't already.
For information, see Installing or updating the latest version of the AWS CLI.
-
Verify that a node is ready to be registered as a target for a maintenance window.
Run the following command to view which nodes are online.
aws ssm describe-instance-information --query "InstanceInformationList[*]"
Run the following command to view details about a particular node.
aws ssm describe-instance-information --instance-information-filter-list key=InstanceIds,valueSet=
instance-id
Step 2: Create the maintenance window
Use the following procedure to create a maintenance window and specify its basic options, such as schedule and duration.
Create a maintenance window (AWS CLI)
-
Open the AWS CLI and run the following commands to create a maintenance window that runs weekly on Sundays at 02:00, in the United States Pacific time zone, with a one hour cutoff.
For information about creating cron expressions for the
schedule
parameter, see Reference: Cron and rate expressions for Systems Manager.For an explanation of how the various schedule-related options for maintenance windows relate to one another, see Maintenance window scheduling and active period options.
For more information about working with the
--schedule
option, see Reference: Cron and rate expressions for Systems Manager.The system returns information like the following.
{ "WindowId":"mw-0c50858d01EXAMPLE" }
-
To list this and any other maintenance windows created in your AWS account in your current AWS Region, run the following command.
aws ssm describe-maintenance-windows
The system returns information like the following.
{ "WindowIdentities": [ { "Cutoff": 1, "Name": "My-First-Maintenance-Window", "NextExecutionTime": "2019-02-03T02:00-08:00", "Enabled": true, "WindowId": "mw-0c50858d01EXAMPLE", "Duration": 2 } ] }
Step 3: Register maintenance window targets (AWS CLI)
Use the following procedure to register a target with your maintenance window created in Step 2. By registering a target, you specify which nodes to update.
To register maintenance window targets (AWS CLI)
-
Run the following command. Replace each
example resource placeholder
with your own information.The system returns information like the following, which includes a maintenance window target ID. Copy or note the
WindowTargetId
value. You must specify this ID in the next step to register a task for this maintenance window.{ "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }
Alternative commands
Use the following command to register multiple managed nodes.
Use the following command to register nodes by using tags.
-
Run the following command to display the targets for a maintenance window.
aws ssm describe-maintenance-window-targets --window-id "
mw-0c50858d01EXAMPLE
"The system returns information like the following.
{ "Targets": [ { "ResourceType": "INSTANCE", "WindowId": "mw-0c50858d01EXAMPLE", "Targets": [ { "Values": [ "i-02573cafcfEXAMPLE" ], "Key": "InstanceIds" } ], "WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" }, { "ResourceType": "INSTANCE", "WindowId": "mw-0c50858d01EXAMPLE", "Targets": [ { "Values": [ "Prod" ], "Key": "tag:Environment" }, { "Values": [ "Web" ], "Key": "tag:Role" } ], "WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" } ] }
Step 4: Register a Run Command task for the maintenance window to update SSM Agent
Use the following procedure to register a Run Command task for the maintenance window you created in Step 2. The Run Command task updates SSM Agent on the registered targets.
To register a Run Command task for a maintenance window to update SSM Agent (AWS CLI)
-
Run the following command to register a Run Command task for the maintenance window using the
WindowTargetId
value in Step 3. Replace eachexample resource placeholder
with your own information. The task updates SSM Agent by using theAWS-UpdateSSMAgent
document.Note
If the targets you registered in the preceding step are Windows Server 2012 R2 or earlier, you must use the
AWS-UpdateEC2Config
document.The system returns information like the following.
{ "WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" }
-
Run the following command to list all registered tasks for a maintenance window.
aws ssm describe-maintenance-window-tasks --window-id "
mw-0c50858d01EXAMPLE
"The system returns information like the following.
{ "Tasks": [ { "ServiceRoleArn": "arn:aws:iam::111122223333:role/MW-Role", "MaxErrors": "1", "TaskArn": "AWS-UpdateSSMAgent", "MaxConcurrency": "1", "WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE", "TaskParameters": {}, "Priority": 10, "WindowId": "mw-0c50858d01EXAMPLE", "Type": "RUN_COMMAND", "Targets": [ { "Values": [ "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" ], "Key": "WindowTargetIds" } ], "Name": "UpdateSSMAgent" } ] }