Walkthrough: Create a maintenance window to update SSM Agent (Amazon CLI) - Amazon Systems Manager
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Walkthrough: Create a maintenance window to update SSM Agent (Amazon CLI)

The following walkthrough shows you how to use the Amazon Command Line Interface (Amazon CLI) to create an Amazon 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 Amazon Identity and Access Management (IAM). Additionally, verify that you have at least one running Amazon Elastic Compute Cloud (Amazon EC2) instance for Linux or Windows Server that is configured for Systems Manager. For more information, see Systems Manager prerequisites.

Step 1: Get started

To run commands using the Amazon CLI

  1. Install and configure the Amazon Command Line Interface (Amazon CLI), if you haven't already.

    For information, see Install or upgrade Amazon command line tools.

  2. 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 (Amazon CLI)

  1. Open the Amazon 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.

    Linux & macOS
    aws ssm create-maintenance-window \ --name "My-First-Maintenance-Window" \ --schedule "cron(0 2 ? * SUN *)" \ --duration 2 \ --schedule-timezone "America/Los_Angeles" \ --cutoff 1 \ --no-allow-unassociated-targets
    Windows
    aws ssm create-maintenance-window ^ --name "My-First-Maintenance-Window" ^ --schedule "cron(0 2 ? * SUN *)" ^ --duration 2 ^ --schedule-timezone "America/Los_Angeles" ^ --cutoff 1 ^ --no-allow-unassociated-targets

    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"
    }
  2. To list this and any other maintenance windows created in your Amazon Web Services account in your current Amazon Web Services 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 (Amazon 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 (Amazon CLI)

  1. Run the following command. Replace each example resource placeholder with your own information.

    Linux & macOS
    aws ssm register-target-with-maintenance-window \ --window-id "mw-0c50858d01EXAMPLE" \ --target "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" \ --resource-type "INSTANCE"
    Windows
    aws ssm register-target-with-maintenance-window ^ --window-id "mw-0c50858d01EXAMPLE" ^ --target "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" ^ --resource-type "INSTANCE"

    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.

    Linux & macOS
    aws ssm register-target-with-maintenance-window \ --window-id "mw-0c50858d01EXAMPLE" \ --targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE" \ --resource-type "INSTANCE"
    Windows
    aws ssm register-target-with-maintenance-window ^ --window-id "mw-0c50858d01EXAMPLE" ^ --targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE" ^ --resource-type "INSTANCE"

    Use the following command to register nodes by using tags.

    Linux & macOS
    aws ssm register-target-with-maintenance-window \ --window-id "mw-0c50858d01EXAMPLE" \ --targets "Key=tag:Environment,Values=Prod" "Key=tag:Role,Values=Web" \ --resource-type "INSTANCE"
    Windows
    aws ssm register-target-with-maintenance-window ^ --window-id "mw-0c50858d01EXAMPLE" ^ --targets "Key=tag:Environment,Values=Prod" "Key=tag:Role,Values=Web" ^ --resource-type "INSTANCE"
  2. 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 (Amazon CLI)

  1. Run the following command to register a Run Command task for the maintenance window using the WindowTargetId value in Step 3. Replace each example resource placeholder with your own information. The task updates SSM Agent by using the AWS-UpdateSSMAgent document.

    Linux & macOS
    aws ssm register-task-with-maintenance-window \ --window-id "mw-0c50858d01EXAMPLE" \ --task-arn "AWS-UpdateSSMAgent" \ --name "UpdateSSMAgent" \ --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \ --service-role-arn "arn:aws-cn:iam:account-id:role/MW-Role" \ --task-type "RUN_COMMAND" \ --max-concurrency 1 --max-errors 1 --priority 10
    Windows
    aws ssm register-task-with-maintenance-window ^ --window-id "mw-0c50858d01EXAMPLE" ^ --task-arn "AWS-UpdateSSMAgent" ^ --name "UpdateSSMAgent" ^ --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" ^ --service-role-arn "arn:aws-cn:iam:account-id:role/MW-Role" ^ --task-type "RUN_COMMAND" ^ --max-concurrency 1 --max-errors 1 --priority 10
    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"
    }
  2. 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"
            }
        ]
    }