AWS Systems Manager
User Guide

Tutorial: Update a Maintenance Window (AWS CLI)

This tutorial demonstrates how to use the AWS CLI to update a maintenance window. It also shows you how to update different task types, including those for Systems Manager Run Command, Systems Manager Automation, AWS Lambda, and AWS Step Functions.

The examples in this section use the following Systems Manager actions for updating a maintenance window.

For information about using the Systems Manager console to update a maintenance window, see Update or Delete a Maintenance Window (Console).

As you follow the steps in this tutorial, replace the values in italicized red text with your own options and IDs. For example, replace the maintenance window ID mw-0c50858d01EXAMPLE and the instance ID i-02573cafcfEXAMPLE with IDs of resources you create.

To update a maintenance window (AWS CLI)

  1. Open the AWS CLI and run the following command to update a target to include a name and a description:

    aws ssm update-maintenance-window-target --window-id "mw-0c50858d01EXAMPLE" --window-target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --name "My-Maintenance-Window-Target" --description "Description for my maintenance window target"

    The system returns information like the following:

    {
        "WindowId": "mw-0c50858d01EXAMPLE",
        "WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE",
        "Targets": [
            {
                "Key": "InstanceIds",
                "Values": [
                    "i-02573cafcfEXAMPLE"
                ]
            }
        ],
        "Name": "My-Maintenance-Window-Target",
        "Description": "Description for my maintenance window target"
    }
  2. Run the following command to use the replace option to remove the description field and add an additional target. The description field is removed, because the update does not include the field (a null value). Be sure to specify an additional instance that has been configured for use with Systems Manager:

    aws ssm update-maintenance-window-target --window-id "mw-0c50858d01EXAMPLE" --window-target-id "d208dedf-3f6b-41ff-ace8-8e751EXAMPLE" --targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE" --name "My-Maintenance-Window-Target" --replace

    The system returns information like the following:

    {
        "WindowId": "mw-0c50858d01EXAMPLE",
        "WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE",
        "Targets": [
            {
                "Key": "InstanceIds",
                "Values": [
                    "i-02573cafcfEXAMPLE",
                    "i-0471e04240EXAMPLE"
                ]
            }
        ],
        "Name": "My-Maintenance-Window-Target"
    }
  3. The start-date option allows you to delay activation of a maintenance window until a specified future date. The end-date option allows you to set a date and time in the future after which the maintenance window no longer runs. Specify the options in ISO-8601 Extended format.

    Run the following command to specify a date and time range for regularly scheduled maintenance window executions:

    aws ssm update-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --start-date "2020-10-01T10:10:10Z" --end-date "2020-11-01T10:10:10Z"
  4. If you created a Run Command task, run the following command to update it:

    Tip

    If your target is an Amazon EC2 instance for Windows Server, change df to ipconfig, and AWS-RunShellScript to AWS-RunPowerShellScript in the following command.

    aws ssm update-maintenance-window-task --window-id "mw-0c50858d01EXAMPLE" --window-task-id "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --task-arn "AWS-RunShellScript" --service-role-arn "arn:aws:iam::111122223333:role/MaintenanceWindowsRole" --task-invocation-parameters "RunCommand={Comment=Revising my Run Command task,Parameters={commands=df}}" --priority 1 --max-concurrency 10 --max-errors 4 --name "My-Task-Name" --description "A description for my Run Command task"

    The system returns information like the following:

    {
        "WindowId": "mw-0c50858d01EXAMPLE",
        "WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
        "Targets": [
            {
                "Key": "WindowTargetIds",
                "Values": [
                    "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
                ]
            }
        ],
        "TaskArn": "AWS-RunShellScript",
        "ServiceRoleArn": "arn:aws:iam::111122223333:role/MaintenanceWindowsRole",
        "TaskParameters": {},
        "TaskInvocationParameters": {
            "RunCommand": {
                "Comment": "Revising my Run Command task",
                "Parameters": {
                    "commands": [
                        "df"
                    ]
                }
            }
        },
        "Priority": 1,
        "MaxConcurrency": "10",
        "MaxErrors": "4",
        "Name": "My-Task-Name",
        "Description": "A description for my Run Command task"
    }
  5. If you are updating a Lambda task, adapt and run the following command to update the task:

    aws ssm update-maintenance-window-task --window-id mw-0c50858d01EXAMPLE --window-task-id 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --task-arn "arn:aws:lambda:us-east-2:111122223333:function:SSMTestLambda" --service-role-arn "arn:aws:iam::111122223333:role/MaintenanceWindowsRole" --task-invocation-parameters '{"Lambda":{"Payload":"{\"targetId\":\"{{TARGET_ID}}\",\"targetType\":\"{{TARGET_TYPE}}\"}"}}' --priority 1 --max-concurrency 10 --max-errors 5 --name "New-Lambda-Task-Name" --description "A description for my Lambda task"

    The system returns information like the following:

    {
        "WindowId": "mw-0c50858d01EXAMPLE",
        "WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
        "Targets": [
            {
                "Key": "WindowTargetIds",
                "Values": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
            }
        ],
        "TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestLambda",
        "ServiceRoleArn": "arn:aws:iam::111122223333:role/MaintenanceWindowsRole",
        "TaskParameters": {},
        "TaskInvocationParameters": {
            "Lambda": {
                "Payload": "e30="
            }
        },
        "Priority": 1,
        "MaxConcurrency": "10",
        "MaxErrors": "5",
        "Name": "New-Lambda-Task-Name",
        "Description": "A description for my Lambda task"
    }
  6. If you are updating an AWS Step Functions task, adapt and run the following command to update its task-invocation-parameters:

    aws ssm update-maintenance-window-task --window-id "mw-0c50858d01EXAMPLE" --window-task-id "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --task-arn "arn:aws:states:us-east-2:111122223333:execution:SSMStepFunctionTest" --service-role-arn "arn:aws:iam::111122223333:role/MaintenanceWindowsRole" --task-invocation-parameters '{"StepFunctions":{"Input":"{\"instanceId\":\"{{ TARGET_ID }}\"}"}}' --priority 0 --max-concurrency 10 --max-errors 5 --name "My-Step-Functions-Task" --description "A description for my Step Functions task"

    The system returns information like the following:

    {
        "WindowId": "mw-0c50858d01EXAMPLE",
        "WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
        "Targets": [
            {
                "Key": "WindowTargetIds",
                "Values": [
                    "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
                ]
            }
        ],
        "TaskArn": "arn:aws:states:us-east-2:111122223333:execution:SSMStepFunctionTest",
        "ServiceRoleArn": "arn:aws:iam::111122223333:role/MaintenanceWindowsRole",
        "TaskParameters": {},
        "TaskInvocationParameters": {
            "StepFunctions": {
                "Input": "{\"instanceId\":\"{{ TARGET_ID }}\"}"
            }
        },
        "Priority": 0,
        "MaxConcurrency": "10",
        "MaxErrors": "5",
        "Name": "My-Step-Functions-Task",
        "Description": "A description for my Step Functions task"
    }
  7. Run the following command to unregister a target from a maintenance window. This example uses the safe parameter to determine if the target is referenced by any tasks and therefore safe to unregister:

    aws ssm deregister-target-from-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --window-target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --safe

    The system returns information like the following:

    An error occurred (TargetInUseException) when calling the DeregisterTargetFromMaintenanceWindow operation: This Target cannot be deregistered because it is still referenced in Task: 4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE
  8. Run the following command to unregister a target from a maintenance window even if the target is referenced by a task. You can force the unregister operation by using the no-safe parameter:

    aws ssm deregister-target-from-maintenance-window --window-id "mw-0c50858d01EXAMPLE" --window-target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" --no-safe

    The system returns information like the following:

    {
        "WindowId": "mw-0c50858d01EXAMPLE",
        "WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
    }
    
  9. Run the following command to update a Run Command task. This example uses a Systems Manager Parameter Store parameter called UpdateLevel, which is formated as follows:'{{ssm:UpdateLevel}}'

    aws ssm update-maintenance-window-task --window-id "mw-0c50858d01EXAMPLE" --window-task-id "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" --targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" --task-invocation-parameters "RunCommand={Comment=A comment for my task update,Parameters={UpdateLevel='{{ssm:UpdateLevel}}'}}"

    The system returns information like the following:

    {
        "WindowId": "mw-0c50858d01EXAMPLE",
        "WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
        "Targets": [
            {
                "Key": "InstanceIds",
                "Values": [
                    "i-02573cafcfEXAMPLE"
                ]
            }
        ],
        "TaskArn": "AWS-RunShellScript",
        "ServiceRoleArn": "arn:aws:iam::111122223333:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
        "TaskParameters": {},
        "TaskInvocationParameters": {
            "RunCommand": {
                "Comment": "A comment for my task update",
                "Parameters": {
                    "UpdateLevel": [
                        "{{ssm:UpdateLevel}}"
                    ]
                }
            }
        },
        "Priority": 10,
        "MaxConcurrency": "1",
        "MaxErrors": "1"
    }
  10. Run the following command to update an Automation task to specify WINDOW_ID and WINDOW_TASK_ID parameters for the task-invocation-parameters parameter:

    aws ssm update-maintenance-window-task --window-id "mw-0c50858d01EXAMPLE" --window-task-id "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE" --targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE --task-arn "AutoTestDoc" --service-role-arn arn:aws:iam::111122223333:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM --task-invocation-parameters "Automation={Parameters={instanceId='{{TARGET_ID}}',initiator='{{WINDOW_ID}}.Task-{{WINDOW_TASK_ID}}'}}" --priority 3 --max-concurrency 10 --max-errors 5

    The system returns information like the following:

    {
        "WindowId": "mw-0c50858d01EXAMPLE",
        "WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE",
        "Targets": [
            {
                "Key": "WindowTargetIds",
                "Values": [
                    "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
                ]
            }
        ],
        "TaskArn": "AutoTestDoc",
        "ServiceRoleArn": "arn:aws:iam::111122223333:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
        "TaskParameters": {},
        "TaskInvocationParameters": {
            "Automation": {
                "Parameters": {
                    "multi": [
                        "{{WINDOW_TASK_ID}}"
                    ],
                    "single": [
                        "{{WINDOW_ID}}"
                    ]
                }
            }
        },
        "Priority": 0,
        "MaxConcurrency": "10",
        "MaxErrors": "5",
        "Name": "My-Automation-Task",
        "Description": "A description for my Automation task"
    }