Tutorial: View information about maintenance windows (Amazon CLI)
This tutorial includes commands to help you update or get information about your maintenance windows, tasks, executions, and invocations. The examples are organized by command to demonstrate how to use command options to filter for the type of detail you want to see.
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.
For information about setting up and configuring the Amazon Command Line Interface (Amazon CLI), see Installing, updating, and uninstalling the Amazon CLI and Configuring the Amazon CLI.
Command examples
Examples for 'describe-maintenance-windows'
List all maintenance windows in your Amazon Web Services account
Run the following command.
aws ssm describe-maintenance-windows
The system returns information like the following.
{ "WindowIdentities":[ { "WindowId":"mw-0c50858d01EXAMPLE", "Name":"My-First-Maintenance-Window", "Enabled":true, "Duration":2, "Cutoff":0, "NextExecutionTime": "2019-05-18T17:01:01.137Z" }, { "WindowId":"mw-9a8b7c6d5eEXAMPLE", "Name":"My-Second-Maintenance-Window", "Enabled":true, "Duration":4, "Cutoff":1, "NextExecutionTime": "2019-05-30T03:30:00.137Z" }, ] }
List all enabled maintenance windows
Run the following command.
aws ssm describe-maintenance-windows --filters "Key=Enabled,Values=true"
The system returns information like the following.
{ "WindowIdentities":[ { "WindowId":"mw-0c50858d01EXAMPLE", "Name":"My-First-Maintenance-Window", "Enabled":true, "Duration":2, "Cutoff":0, "NextExecutionTime": "2019-05-18T17:01:01.137Z" }, { "WindowId":"mw-9a8b7c6d5eEXAMPLE", "Name":"My-Second-Maintenance-Window", "Enabled":true, "Duration":4, "Cutoff":1, "NextExecutionTime": "2019-05-30T03:30:00.137Z" }, ] }
List all disabled maintenance windows
Run the following command.
aws ssm describe-maintenance-windows --filters "Key=Enabled,Values=false"
The system returns information like the following.
{ "WindowIdentities": [ { "WindowId": "mw-6e5c9d4b7cEXAMPLE", "Name": "My-Disabled-Maintenance-Window", "Enabled": false, "Duration": 2, "Cutoff": 1 } ] }
List all maintenance windows having names that start with a certain prefix
Run the following command.
aws ssm describe-maintenance-windows --filters "Key=Name,Values=My"
The system returns information like the following.
{ "WindowIdentities": [ { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window", "Enabled": true, "Duration": 2, "Cutoff": 0, "NextExecutionTime": "2019-05-18T17:01:01.137Z" }, { "WindowId": "mw-9a8b7c6d5eEXAMPLE", "Name": "My-Second-Maintenance-Window", "Enabled": true, "Duration": 4, "Cutoff": 1, "NextExecutionTime": "2019-05-30T03:30:00.137Z" }, { "WindowId": "mw-6e5c9d4b7cEXAMPLE", "Name": "My-Disabled-Maintenance-Window", "Enabled": false, "Duration": 2, "Cutoff": 1 } ] }
Examples for 'describe-maintenance-window-targets'
Display the targets for a maintenance window matching a specific owner information value
Run the following command.
Note
The supported filter keys are Type,
WindowTargetId and OwnerInformation.
The system returns information like the following.
{ "Targets": [ { "WindowId": "mw-0c50858d01EXAMPLE", "WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE", "ResourceType": "INSTANCE", "Targets": [ { "Key": "tag:Name", "Values": [ "Production" ] } ], "OwnerInformation": "CostCenter1", "Name": "Target1" } ] }
Examples for 'describe-maintenance-window-tasks'
Show all registered tasks that invoke the SSM command document
AWS-RunPowerShellScript
Run the following command.
The system returns information like the following.
{ "Tasks":[ { "ServiceRoleArn": "arn:aws-cn:iam::111122223333:role/MyMaintenanceWindowServiceRole", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE", "TaskParameters":{ "commands":{ "Values":[ "driverquery.exe" ] } }, "Priority":3, "Type":"RUN_COMMAND", "Targets":[ { "TaskTargetId":"i-02573cafcfEXAMPLE", "TaskTargetType":"INSTANCE" } ] }, { "ServiceRoleArn":"arn:aws-cn:iam::111122223333:role/MyMaintenanceWindowServiceRole", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE", "TaskParameters":{ "commands":{ "Values":[ "ipconfig" ] } }, "Priority":1, "Type":"RUN_COMMAND", "Targets":[ { "TaskTargetId":"i-02573cafcfEXAMPLE", "TaskTargetType":"WINDOW_TARGET" } ] } ] }
Show all registered tasks that have a priority of "3"
Run the following command.
The system returns information like the following.
{ "Tasks":[ { "ServiceRoleArn":"arn:aws-cn:iam::111122223333:role/MyMaintenanceWindowServiceRole", "MaxErrors":"1", "TaskArn":"AWS-RunPowerShellScript", "MaxConcurrency":"1", "WindowTaskId":"4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE", "TaskParameters":{ "commands":{ "Values":[ "driverquery.exe" ] } }, "Priority":3, "Type":"RUN_COMMAND", "Targets":[ { "TaskTargetId":"i-02573cafcfEXAMPLE", "TaskTargetType":"INSTANCE" } ] } ] }
Show all registered tasks that have a priority of "1" and use Run Command
Run the following command.
The system returns information like the following.
{ "Tasks": [ { "WindowId": "mw-0c50858d01EXAMPLE", "WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE", "TaskArn": "AWS-RunShellScript", "Type": "RUN_COMMAND", "Targets": [ { "Key": "InstanceIds", "Values": [ "i-02573cafcfEXAMPLE" ] } ], "TaskParameters": {}, "Priority": 1, "ServiceRoleArn": "arn:aws-cn:iam::111122223333:role/MyMaintenanceWindowServiceRole", "MaxConcurrency": "1", "MaxErrors": "1" }, { "WindowId": "mw-0c50858d01EXAMPLE", "WindowTaskId": "8a5c4629-31b0-4edd-8aea-33698EXAMPLE", "TaskArn": "AWS-UpdateSSMAgent", "Type": "RUN_COMMAND", "Targets": [ { "Key": "InstanceIds", "Values": [ "i-0471e04240EXAMPLE" ] } ], "TaskParameters": {}, "Priority": 1, "ServiceRoleArn": "arn:aws-cn:iam::111122223333:role/MyMaintenanceWindowServiceRole", "MaxConcurrency": "1", "MaxErrors": "1", "Name": "My-Run-Command-Task", "Description": "My Run Command task to update SSM Agent on an instance" } ] }
Examples for 'describe-maintenance-windows-for-target'
List information about the maintenance window targets or tasks associated with a specific node
Run the following command.
The system returns information like the following.
{ "WindowIdentities": [ { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window" }, { "WindowId": "mw-9a8b7c6d5eEXAMPLE", "Name": "My-Second-Maintenance-Window" } ] }
Examples for 'describe-maintenance-window-executions'
List all tasks run before a certain date
Run the following command.
The system returns information like the following.
{ "WindowExecutions": [ { "WindowId": "mw-0c50858d01EXAMPLE", "WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE", "Status": "FAILED", "StatusDetails": "The following SSM parameters are invalid: LevelUp", "StartTime": 1557617747.993, "EndTime": 1557617748.101 }, { "WindowId": "mw-9a8b7c6d5eEXAMPLE", "WindowExecutionId": "791b72e0-f0da-4021-8b35-f95dfEXAMPLE", "Status": "SUCCESS", "StartTime": 1557594085.428, "EndTime": 1557594090.978 }, { "WindowId": "mw-0c50858d01EXAMPLE", "WindowExecutionId": "ecec60fa-6bb0-4d26-98c7-140308EXAMPLE", "Status": "SUCCESS", "StartTime": 1557593793.483, "EndTime": 1557593798.978 } ] }
List all tasks run after a certain date
Run the following command.
The system returns information like the following.
{ "WindowExecutions": [ { "WindowId": "mw-0c50858d01EXAMPLE", "WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE", "Status": "FAILED", "StatusDetails": "The following SSM parameters are invalid: LevelUp", "StartTime": 1557617747.993, "EndTime": 1557617748.101 }, { "WindowId": "mw-9a8b7c6d5eEXAMPLE", "WindowExecutionId": "791b72e0-f0da-4021-8b35-f95dfEXAMPLE", "Status": "SUCCESS", "StartTime": 1557594085.428, "EndTime": 1557594090.978 }, { "WindowId": "mw-0c50858d01EXAMPLE", "WindowExecutionId": "ecec60fa-6bb0-4d26-98c7-140308EXAMPLE", "Status": "SUCCESS", "StartTime": 1557593793.483, "EndTime": 1557593798.978 } ] }
Examples for 'describe-maintenance-window-schedule'
Display the next ten scheduled maintenance window runs for a particular node
Run the following command.
The system returns information like the following.
{ "ScheduledWindowExecutions": [ { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window", "ExecutionTime": "2019-05-18T23:35:24.902Z" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window", "ExecutionTime": "2019-05-25T23:35:24.902Z" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window", "ExecutionTime": "2019-06-01T23:35:24.902Z" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window", "ExecutionTime": "2019-06-08T23:35:24.902Z" }, { "WindowId": "mw-9a8b7c6d5eEXAMPLE", "Name": "My-Second-Maintenance-Window", "ExecutionTime": "2019-06-15T23:35:24.902Z" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window", "ExecutionTime": "2019-06-22T23:35:24.902Z" }, { "WindowId": "mw-9a8b7c6d5eEXAMPLE", "Name": "My-Second-Maintenance-Window", "ExecutionTime": "2019-06-29T23:35:24.902Z" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window", "ExecutionTime": "2019-07-06T23:35:24.902Z" }, { "WindowId": "mw-9a8b7c6d5eEXAMPLE", "Name": "My-Second-Maintenance-Window", "ExecutionTime": "2019-07-13T23:35:24.902Z" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "My-First-Maintenance-Window", "ExecutionTime": "2019-07-20T23:35:24.902Z" } ], "NextToken": "AAEABUXdceT92FvtKld/dGHELj5Mi+GKW/EXAMPLE" }
Display the maintenance window schedule for nodes tagged with a certain key-value pair
Run the following command.
The system returns information like the following.
{ "ScheduledWindowExecutions": [ { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "DemoRateStartDate", "ExecutionTime": "2019-10-20T05:34:56-07:00" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "DemoRateStartDate", "ExecutionTime": "2019-10-21T05:34:56-07:00" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "DemoRateStartDate", "ExecutionTime": "2019-10-22T05:34:56-07:00" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "DemoRateStartDate", "ExecutionTime": "2019-10-23T05:34:56-07:00" }, { "WindowId": "mw-0c50858d01EXAMPLE", "Name": "DemoRateStartDate", "ExecutionTime": "2019-10-24T05:34:56-07:00" } ], "NextToken": "AAEABccwSXqQRGKiTZ1yzGELR6cxW4W/EXAMPLE" }
Display start times for next four runs of a maintenance window
Run the following command.
The system returns information like the following.
{ "WindowSchedule": [ { "ScheduledWindowExecutions": [ { "ExecutionTime": "2019-10-04T10:10:10Z", "Name": "My-First-Maintenance-Window", "WindowId": "mw-0c50858d01EXAMPLE" }, { "ExecutionTime": "2019-10-11T10:10:10Z", "Name": "My-First-Maintenance-Window", "WindowId": "mw-0c50858d01EXAMPLE" }, { "ExecutionTime": "2019-10-18T10:10:10Z", "Name": "My-First-Maintenance-Window", "WindowId": "mw-0c50858d01EXAMPLE" }, { "ExecutionTime": "2019-10-25T10:10:10Z", "Name": "My-First-Maintenance-Window", "WindowId": "mw-0c50858d01EXAMPLE" } ] } ] }