Menu
Amazon EC2 Systems Manager
User Guide

Maintenance Window CLI Walkthrough

The following walkthrough introduces you to Maintenance Windows concepts and walks you through the process of creating and configuring a Maintenance Window using the AWS CLI. You'll perform the walkthrough on a test instance that is configured for Systems Manager. After you finish the walkthrough, you can delete the test instance.

Creating and Configuring a Maintenance Window Using the CLI

To create and configure a Maintenance Window Using the AWS CLI

  1. Download the AWS CLI to your local machine.

  2. Open the AWS CLI and execute the following command to create a Maintenance Window that runs at 4 PM on every Tuesday for 4 hours, with a 1 hour cutoff, and that allows unassociated targets. For more information about creating cron expressions for the schedule parameter, see Cron Schedules for Systems Manager.

    Copy
    aws ssm create-maintenance-window --name "My-First-Maintenance-Window" --schedule "cron(0 16 ? * TUE *)" --duration 4 --cutoff 1 --allow-unassociated-targets

    The system returns information like the following.

    Copy
    { "WindowId":"mw-ab12cd34ef56gh78" }
  3. Execute the following command to list all Maintenance Windows in your AWS account.

    Copy
    aws ssm describe-maintenance-windows

    The system returns information like the following.

    Copy
    { "WindowIdentities":[ { "Duration":4, "Cutoff":1, "WindowId":"mw-ab12cd34ef56gh78", "Enabled":true, "Name":"My-First-Maintenance-Window" } ] }
  4. Execute the following command to register the instance you created earlier as a target for this Maintenance Windows. The system returns a Maintenance Window target ID. You will use this ID in a later step to register a task for this Maintenance Window.

    Copy
    aws ssm register-target-with-maintenance-window --window-id "mw-ab12cd34ef56gh78" --target "Key=InstanceIds,Values=ID" --owner-information "Single instance" --resource-type "INSTANCE"

    The system returns information like the following.

    Copy
    { "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }

    You could register multiple instances using the following command.

    Copy
    aws ssm register-target-with-maintenance-window --window-id "mw-ab12cd34ef56gh78" --targets "Key=InstanceIds,Values=ID 1,ID 2" --owner-information "Two instances in a list" --resource-type "INSTANCE"

    You could also register instances using EC2 tags.

    Copy
    aws ssm register-target-with-maintenance-window --window-id "mw-ab12cd34ef56gh78" --targets "Key=tag:Environment,Values=Prod" "Key=Role,Values=Web" --owner-information "Production Web Servers" --resource-type "INSTANCE"
  5. Use the following command to display the targets for a Maintenance Window.

    Copy
    aws ssm describe-maintenance-window-targets --window-id "mw-ab12cd34ef56gh78"

    The system returns information like the following.

    Copy
    { "Targets":[ { "ResourceType":"INSTANCE", "OwnerInformation":"Single instance", "WindowId":"mw-ab12cd34ef56gh78", "Targets":[ { "Values":[ "i-11aa22bb33cc44dd5" ], "Key":"InstanceIds" } ], "WindowTargetId":"a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4" }, { "ResourceType":"INSTANCE", "OwnerInformation":"Two instances in a list", "WindowId":"mw-ab12cd34ef56gh78", "Targets":[ { "Values":[ "i-1a2b3c4d5e6f7g8h9", "i-aa11bb22cc33dd44e " ], "Key":"InstanceIds" } ], "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }, { "ResourceType":"INSTANCE", "OwnerInformation":"Production Web Servers", "WindowId":"mw-ab12cd34ef56gh78", "Targets":[ { "Values":[ "Prod" ], "Key":"tag:Environment" }, { "Values":[ "Web" ], "Key":"tag:Role" } ], "WindowTargetId":"1111aaa-2222-3333-4444-1111aaa " } ] }
  6. Execute the following command to register a task on the instance you created earlier. This task uses Systems Manager Run Command to execute the df command using the AWS-RunShellScript document. This command uses the following parameters:

    • targets: Specify either Key=WindowTargetIds,Values=Window Target ID to specify a target registered with the Maintenance Window or Key=InstanceIds,Values=Instance ID to specify individual instances registered with the Maintenance Window.

    • task-arn: Specify the name of a Systems Manager Run Command document. For example: AWS-RunShellScript, AWS-RunPowerShellScript, or arn:aws:ssm:us-east-1:123456789:document/Restart_Apache (for a shared document).

    • window-id: Specify the ID of the target Maintenance Window.

    • task-type: Specify RUN_COMMAND. Currently only Run Command tasks are supported.

    • task-parameters: Specify required and optional parameters for the Run Command document.

    • max-concurrency: (Optional) Specify the maximum number of instances that are allowed to execute the command at the same time. You can specify a number such as 10 or a percentage such as 10%.

    • max-errors: (Optional) Specify the maximum number of errors allowed without the command failing. When the command fails one more time beyond the value of MaxErrors, the systems stops sending the command to additional targets. You can specify a number such as 10 or a percentage such as 10%.

    • priority: Specify the priority of the task in the Maintenance Window. The lower the number the higher the priority (for example, 1 is highest priority). Tasks in a Maintenance Window are scheduled in priority order. Tasks that have the same priority are scheduled in parallel.

    Copy
    aws ssm register-task-with-maintenance-window --window-id mw-ab12cd34ef56gh78 --task-arn "AWS-RunShellScript" --targets "Key=InstanceIds,Values=Instance ID" --service-role-arn "arn:aws:iam::1122334455:role/MW-Role" --task-type "RUN_COMMAND" --task-parameters "{\"commands\":{\"Values\":[\"df\"]}}" --max-concurrency 1 --max-errors 1 --priority 10

    The system returns information like the following.

    Copy
    { "WindowTaskId":"44444444-5555-6666-7777-88888888" }

    You can also register a task using a Maintenance Window target ID. The Maintenance Window target ID was returned from an earlier command.

    Copy
    aws ssm register-task-with-maintenance-window --targets "Key=WindowTargetIds,Values=Window Target ID" --task-arn "AWS-RunShellScript" --service-role-arn "arn:aws:iam::1122334455:role/MW-Role" --window-id "mw-ab12cd34ef56gh78" --task-type "RUN_COMMAND" --task-parameters "{\"commands\":{\"Values\":[\"df\"]}}" --max-concurrency 1 --max-errors 1 --priority 10

    The system returns information like the following.

    Copy
    { "WindowTaskId":"44444444-5555-6666-7777-88888888" }
  7. Execute the following command to list all registered tasks for a Maintenance Window.

    Copy
    aws ssm describe-maintenance-window-tasks --window-id "mw-ab12cd34ef56gh78"

    The system returns information like the following.

    Copy
    { "Tasks":[ { "ServiceRoleArn":"arn:aws:iam::11111111:role/MW-Role", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"3333-3333-3333-333333", "TaskParameters":{ "commands":{ "Values":[ "driverquery.exe" ] } }, "Priority":3, "Type":"RUN_COMMAND", "Targets":[ { "Values":[ "i-1a2b3c4d5e6f7g8h9" ], "Key":"InstanceIds" } ] }, { "ServiceRoleArn":"arn:aws:iam::2222222222:role/MW-Role", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"44444-44-44-444444", "TaskParameters":{ "commands":{ "Values":[ "ipconfig.exe" ] } }, "Priority":1, "Type":"RUN_COMMAND", "Targets":[ { "Values":[ "555555-55555-555-5555555" ], "Key":"WindowTargetIds" } ] } ] }
  8. Execute the following command to view a list of task executions for a specific Maintenance Window.

    Copy
    aws ssm describe-maintenance-window-executions --window-id "mw-ab12cd34ef56gh78"

    The system returns information like the following.

    Copy
    { "WindowExecutions":[ { "Status":"SUCCESS", "WindowExecutionId":"1111-1111-1111-11111", "StartTime":1478230495.469 }, { "Status":"SUCCESS", "WindowExecutionId":"2222-2-2-22222222-22", "StartTime":1478231395.677 }, # ... omitting a number of entries in the interest of space... { "Status":"SUCCESS", "WindowExecutionId":"33333-333-333-3333333", "StartTime":1478272795.021 }, { "Status":"SUCCESS", "WindowExecutionId":"4444-44-44-44444444", "StartTime":1478273694.932 } ], "NextToken":111111 ..." }
  9. Execute the following command to get information about a Maintenance Window task execution.

    Copy
    aws ssm get-maintenance-window-execution --window-execution-id "1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"

    The system returns information like the following.

    Copy
    { "Status":"SUCCESS", "TaskIds":[ "333-33-3333-333333" ], "StartTime":1478230495.472, "EndTime":1478230516.505, "WindowExecutionId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }
  10. Execute the following command to list the tasks executed as part of a Maintenance Window execution.

    Copy
    aws ssm describe-maintenance-window-execution-tasks --window-execution-id "1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"

    The system returns information like the following.

    Copy
    { "WindowExecutionTaskIdentities":[ { "Status":"SUCCESS", "EndTime":1478230516.425, "StartTime":1478230495.782, "TaskId":"33333-333-333-3333333" } ] }
  11. Execute the following command to get the details of a task execution.

    Copy
    aws ssm get-maintenance-window-execution-task --window-execution-id "555555-555-55-555555" --task-id "4444-4444-4444-444444"

    The system returns information like the following.

    Copy
    { "Status":"SUCCESS", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "ServiceRole":"arn:aws:iam::333333333:role/MW-Role", "WindowExecutionId":"555555-555-55-555555", "Priority":0, "StartTime":1478230495.782, "EndTime":1478230516.425, "Type":"RUN_COMMAND", "TaskParameters":[ ], "TaskExecutionId":"4444-4444-4444-444444" }
  12. Execute the following command to get the specific task invocations performed for a task execution.

    Copy
    aws ssm describe-maintenance-window-execution-task-invocations --window-execution-id "555555-555-55-555555" --task-id "4444-4444-4444-444444"

    The system returns information like the following.

    Copy
    { "WindowExecutionTaskInvocationIdentities":[ { "Status":"SUCCESS", "Parameters":"{\" documentName \" : \" AWS-RunPowerShellScript \" , \" instanceIds \" :[ \" i-1a2b3c4d5e6f7g8h9 \" , \" i-0a 00def7faa94f1dc \" ], \" parameters \" :{ \" commands \" :[ \" ipconfig.exe \" ]}, \" maxConcurrency \" : \" 1 \" , \" maxErrors \" : \" 1 \" }", "ExecutionId":"555555-555-55-555555", "InvocationId":"3333-33333-3333-33333", "StartTime":1478230495.842, "EndTime":1478230516.291 } ] }

Additional Maintenance Window Configuration Commands

This section includes commands to help you update or get information about your Maintenance Windows, tasks, executions, and invocations.

List All Maintenance Windows in Your AWS Account

Copy
aws ssm describe-maintenance-windows

The system returns information like the following.

Copy
{ "WindowIdentities":[ { "Duration":2, "Cutoff":0, "WindowId":"mw-ab12cd34ef56gh78", "Enabled":true, "Name":"IAD-Every-15-Minutes" }, { "Duration":4, "Cutoff":1, "WindowId":"mw-1a2b3c4d5e6f7g8h9", "Enabled":true, "Name":"My-First-Maintenance-Window" }, { "Duration":8, "Cutoff":2, "WindowId":"mw-123abc456def789", "Enabled":false, "Name":"Every-Day" } ] }

List all enabled Maintenance Windows

Copy
aws ssm describe-maintenance-windows --filters "Key=Enabled,Values=true"

The system returns information like the following.

Copy
{ "WindowIdentities":[ { "Duration":2, "Cutoff":0, "WindowId":"mw-ab12cd34ef56gh78", "Enabled":true, "Name":"IAD-Every-15-Minutes" }, { "Duration":4, "Cutoff":1, "WindowId":"mw-1a2b3c4d5e6f7g8h9", "Enabled":true, "Name":"My-First-Maintenance-Window" } ] }

List all Disabled Maintenance Windows

Copy
aws ssm describe-maintenance-windows --filters "Key=Enabled,Values=false"

The system returns information like the following.

Copy
{ "WindowIdentities":[ { "Duration":8, "Cutoff":2, "WindowId":"mw-1a2b3c4d5e6f7g8h9", "Enabled":false, "Name":"Every-Day" } ] }

Filter by Name

In this example, the command returns all Maintenance Windows with a name starting with 'My'.

Copy
aws ssm describe-maintenance-windows --filters "Key=Name,Values=My"

The system returns information like the following.

Copy
{ "WindowIdentities":[ { "Duration":4, "Cutoff":1, "WindowId":"mw-1a2b3c4d5e6f7g8h9", "Enabled":true, "Name":"My-First-Maintenance-Window" } ] }

Modify a Maintenance Window

You can modify the following parameters: Name, Schedule, Duration, Cutoff, AllowUnassociatedTargets, and Enabled. The following example modifies the name value.

Copy
aws ssm update-maintenance-window --window-id "mw-1a2b3c4d5e6f7g8h9" --name "My-Renamed-MW"

The system returns information like the following.

Copy
{ "Cutoff": 1, "Name": "My-Renamed-MW", "Schedule": "cron(0 16 ? * TUE *)", "Enabled": true, "AllowUnassociatedTargets": true, "WindowId": "mw-1a2b3c4d5e6f7g8h9", "Duration": 4 }

Modifying the unassociated targets parameter

Copy
aws ssm update-maintenance-window --window-id "mw-1a2b3c4d5e6f7g8h9" --no-allow-unassociated-targets

The system returns information like the following.

Copy
{ "Cutoff": 2, "Name": "Every-Tuesday-4pm", "Schedule": "cron(0 16 ? * TUE *)", "Enabled": true, "AllowUnassociatedTargets": false, "WindowId": "mw-1a2b3c4d5e6f7g8h9", "Duration": 8 }
Copy
aws ssm update-maintenance-window --window-id "mw-1a2b3c4d5e6f7g8h9" --allow-unassociated-targets --no-enabled

The system returns information like the following.

Copy
{ "Cutoff": 2, "Name": "Every-Tuesday-4pm", "Schedule": "cron(0 16 ? * TUE *)", "Enabled": false, "AllowUnassociatedTargets": true, "WindowId": "mw-1a2b3c4d5e6f7g8h9", "Duration": 8 }

Display the Targets for a Maintenance Window Matching a Specific Owner Information Value

Copy
aws ssm describe-maintenance-window-targets --window-id "mw-ab12cd34ef56gh78" --filters "Key=OwnerInformation,Values=Single instance"

The system returns information like the following.

Copy
{ "Targets":[ { "TargetType":"INSTANCE", "TagFilters":[ ], "TargetIds":[ "i-1a2b3c4d5e6f7g8h9" ], "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2", "OwnerInformation":"Single instance" } ] }

Show All Registered Tasks that Invoke the AWS-RunPowerShellScript Run Command

Copy
aws ssm describe-maintenance-window-tasks --window-id "mw-ab12cd34ef56gh78" --filters "Key=TaskArn,Values=AWS-RunPowerShellScript"

The system returns information like the following.

Copy
{ "Tasks":[ { "ServiceRoleArn":"arn:aws:iam::444444444444:role/MW-Role", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e6c", "TaskParameters":{ "commands":{ "Values":[ "driverquery.exe" ] } }, "Priority":3, "Type":"RUN_COMMAND", "Targets":[ { "TaskTargetId":"i-1a2b3c4d5e6f7g8h9", "TaskTargetType":"INSTANCE" } ] }, { "ServiceRoleArn":"arn:aws:iam::333333333333:role/MW-Role", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"33333-33333-333-33333", "TaskParameters":{ "commands":{ "Values":[ "ipconfig.exe" ] } }, "Priority":1, "Type":"RUN_COMMAND", "Targets":[ { "TaskTargetId":"44444-444-4444-444444", "TaskTargetType":"WINDOW_TARGET" } ] } ] }

Show All Registered Tasks that Have a Priority of 3

Copy
aws ssm describe-maintenance-window-tasks --window-id "mw-ab12cd34ef56gh78" --filters "Key=Priority,Values=3"

The system returns information like the following.

Copy
{ "Tasks":[ { "ServiceRoleArn":"arn:aws:iam::222222222:role/MW-Role", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"333333-333-33333-33333", "TaskParameters":{ "commands":{ "Values":[ "driverquery.exe" ] } }, "Priority":3, "Type":"RUN_COMMAND", "Targets":[ { "TaskTargetId":"i-1a2b3c4d5e6f7g8h9", "TaskTargetType":"INSTANCE" } ] } ] }

Show All Registered Tasks that Have a Priority of 1 and Use Run Command

Copy
aws ssm describe-maintenance-window-tasks --window-id "mw-ab12cd34ef56gh78" --filters "Key=Priority,Values=1" "Key=TaskType,Values=RUN_COMMAND"

The system returns information like the following.

Copy
{ "Tasks":[ { "ServiceRoleArn":"arn:aws:iam::333333333:role/MW-Role", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"66666-555-66-555-6666", "TaskParameters":{ "commands":{ "Values":[ "ipconfig.exe" ] } }, "Priority":1, "Type":"RUN_COMMAND", "Targets":[ { "TaskTargetId":"777-77-777-7777777", "TaskTargetType":"WINDOW_TARGET" } ] } ] }

List All Tasks Executed Before a Date

Copy
aws ssm describe-maintenance-window-executions --window-id "mw-ab12cd34ef56gh78" --filters "Key=ExecutedBefore,Values=2016-11-04T05:00:00Z"

The system returns information like the following.

Copy
{ "WindowExecutions":[ { "Status":"SUCCESS", "EndTime":1478229594.666, "WindowExecutionId":"", "StartTime":1478229594.666 }, { "Status":"SUCCESS", "WindowExecutionId":"06dc5f8a-9ef0-4ae9-a466-ada2d4ce2d22", "StartTime":1478230495.469 }, { "Status":"SUCCESS", "WindowExecutionId":"57ad6419-023e-44b0-a831-6687334390b2", "StartTime":1478231395.677 }, { "Status":"SUCCESS", "WindowExecutionId":"ed1372b7-866b-4d64-bc2a-bbfd5195f4ae", "StartTime":1478232295.529 }, { "Status":"SUCCESS", "WindowExecutionId":"154eb2fa-6390-4cb7-8c9e-55686b88c7b3", "StartTime":1478233195.687 }, { "Status":"SUCCESS", "WindowExecutionId":"1c4de752-eff6-4778-b477-1681c6c03cf1", "StartTime":1478234095.553 }, { "Status":"SUCCESS", "WindowExecutionId":"56062f75-e4d8-483f-b5c2-906d613409a4", "StartTime":1478234995.12 } ] }

List All Tasks Executed After a Date

Copy
aws ssm describe-maintenance-window-executions --window-id "mw-ab12cd34ef56gh78" --filters "Key=ExecutedAfter,Values=2016-11-04T17:00:00Z"

The system returns information like the following.

Copy
{ "WindowExecutions":[ { "Status":"SUCCESS", "WindowExecutionId":"33333-4444-444-5555555", "StartTime":1478279095.042 }, { "Status":"SUCCESS", "WindowExecutionId":"55555-6666-6666-777777", "StartTime":1478279994.958 }, { "Status":"SUCCESS", "WindowExecutionId":"8888-888-888-888888", "StartTime":1478280895.149 } ] }

Remove a Target from a Maintenance Window

Copy
aws ssm deregister-target-from-maintenance-window --region an SSM region --window-id "mw-ab12cd34ef56gh78" --window-target-id "1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"

The system returns information like the following.

Copy
{ "WindowId":"mw-ab12cd34ef56gh78", "WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2" }

Remove a Task from a Maintenance Window

Copy
aws ssm deregister-task-from-maintenance-window --window-id "mw-ab12cd34ef56gh78" --window-task-id "1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e6c"

The system returns information like the following.

Copy
{ "WindowTaskId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e6c", "WindowId":"mw-ab12cd34ef56gh78" }

Delete a Maintenance Window

Copy
aws ssm delete-maintenance-window --window-id "mw-1a2b3c4d5e6f7g8h9"

The system returns information like the following:

Copy
{ "WindowId":"mw-1a2b3c4d5e6f7g8h9" }