Maintenance Window CLI Walkthrough

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 Specifying a Cron Schedule for Your Systems Manager Shared Components.

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

   The system returns information like the following.

   {
      "WindowId":"mw-ab12cd34ef56gh78"
   }

3. Execute the following command to list all Maintenance Windows in your AWS account.

   aws ssm describe-maintenance-windows --region an SSM region
   

   The system returns information like the following.

   {
      "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.

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

   The system returns information like the following.

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

   You could register multiple instances using the following command.

   aws ssm register-target-with-maintenance-window --region an SSM region --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.

   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.

   aws ssm describe-maintenance-window-targets --region an SSM region --window-id "mw-ab12cd34ef56gh78"
   

   The system returns information like the following.

   {
      "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.

   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.

   {
      "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.

   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.

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

7. Execute the following command to list all registered tasks for a Maintenance Window.

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

   The system returns information like the following.

   {
      "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.

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

   The system returns information like the following.

   {
      "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.

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

   The system returns information like the following.

   {
      "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.

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

    The system returns information like the following.

    {
       "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.

    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.

    {
       "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.

    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.

    {
       "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
          }
       ]
    }