• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# AWS Systems Manager Maintenance Windows
Maintenance Windows, a tool in AWS Systems Manager, helps you define a schedule for when to perform potentially disruptive actions on your nodes such as patching an operating system, updating drivers, or installing software or patches.
**Note**
State Manager and Maintenance Windows can perform some similar types of updates on your managed nodes. Which one you choose depends on whether you need to automate system compliance or perform high-priority, time-sensitive tasks during periods you specify.
For more information, see [Choosing between State Manager and Maintenance Windows](state-manager-vs-maintenance-windows.md).
With Maintenance Windows, you can schedule actions on numerous other AWS resource types, such as Amazon Simple Storage Service (Amazon S3) buckets, Amazon Simple Queue Service (Amazon SQS) queues, AWS Key Management Service (AWS KMS) keys, and many more.
For a full list of supported resource types that you can include in a maintenance window target, see [Resources you can use with AWS Resource Groups and Tag Editor](https://docs.aws.amazon.com/ARG/latest/userguide/supported-resources.html#supported-resources-console) in the *AWS Resource Groups User Guide*. To get started with Maintenance Windows, open the [Systems Manager console](https://console.aws.amazon.com//systems-manager/maintenance-windows). In the navigation pane, choose **Maintenance Windows**.
Each maintenance window has a schedule, a maximum duration, a set of registered targets (the managed nodes or other AWS resources that are acted upon), and a set of registered tasks. You can add tags to your maintenance windows when you create or update them. (Tags are keys that help identify and sort your resources within your organization.) You can also specify dates that a maintenance window shouldn't run before or after, and you can specify the international time zone on which to base the maintenance window schedule.
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](maintenance-windows-schedule-options.md).
For more information about working with the `--schedule` option, see [Reference: Cron and rate expressions for Systems Manager](reference-cron-and-rate-expressions.md).
**Supported task types**
With maintenance windows, you can run four types of tasks:
+ Commands in Run Command, a tool in Systems Manager
For more information about Run Command, see [AWS Systems Manager Run Command](run-command.md).
+ Workflows in Automation, a tool in Systems Manager
For more information about Automation workflows, see [AWS Systems Manager Automation](systems-manager-automation.md).
+ Functions in AWS Lambda
For more information about Lambda functions, see [Getting started with Lambda](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) in the *AWS Lambda Developer Guide*.
+ Tasks in AWS Step Functions
**Note**
Maintenance window tasks support Step Functions Standard state machine workflows only. They don't support Express state machine workflows. For information about state machine workflow types, see [Standard vs. Express Workflows](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-standard-vs-express.html) in the *AWS Step Functions Developer Guide*.
For more information about Step Functions, see the *[AWS Step Functions Developer Guide](https://docs.aws.amazon.com/step-functions/latest/dg/)*.
This means you can use maintenance windows to perform tasks such as the following on your selected targets.
+ Install or update applications.
+ Apply patches.
+ Install or update SSM Agent.
+ Run PowerShell commands and Linux shell scripts by using a Systems Manager Run Command task.
+ Build Amazon Machine Images (AMIs), boot-strap software, and configure nodes by using a Systems Manager Automation task.
+ Run AWS Lambda functions that invokes additional actions, such as scanning your nodes for patch updates.
+ Run AWS Step Functions state machines to perform tasks such as removing a node from an Elastic Load Balancing environment, patching the node, and then adding the node back to the Elastic Load Balancing environment.
+ Target nodes that are offline by specifying an AWS resource group as the target.
**Note**
One or more targets must be specified for maintenance window Run Command-type tasks. Depending on the task, targets are optional for other maintenance window task types (Automation, AWS Lambda, and AWS Step Functions). For more information about running tasks that don't specify targets, see [Registering maintenance window tasks without targets](maintenance-windows-targetless-tasks.md).
**EventBridge support**
This Systems Manager tool is supported as an *event* type in Amazon EventBridge rules. For information, see [Monitoring Systems Manager events with Amazon EventBridge](monitoring-eventbridge-events.md) and [Reference: Amazon EventBridge event patterns and types for Systems Manager](reference-eventbridge-events.md).
**Topics**
+ [Setting up Maintenance Windows](setting-up-maintenance-windows.md)
+ [Create and manage maintenance windows using the console](sysman-maintenance-working.md)
+ [Tutorials](maintenance-windows-tutorials.md)
+ [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md)
+ [Maintenance window scheduling and active period options](maintenance-windows-schedule-options.md)
+ [Registering maintenance window tasks without targets](maintenance-windows-targetless-tasks.md)
+ [Troubleshooting maintenance windows](troubleshooting-maintenance-windows.md)
# Setting up Maintenance Windows
Before users in your AWS account can create and schedule maintenance window tasks using Maintenance Windows, a tool in AWS Systems Manager, they must be granted the necessary permissions. In addition, you must create an IAM service role for maintenance windows and the IAM policy to attach to it.
**Before you begin**
In addition to the permissions you configure in this section, the IAM Entities (users, roles, or groups that will work with maintenance windows should already have general maintenance window permissions. You can grant these permissions by assigning the IAM policy `AmazonSSMFullAccess` to the Entities, or assigning a custom IAM policy that provides a smaller set of access permissions for Systems Manager that covers maintenance window tasks.
**Topics**
+ [Control access to maintenance windows using the console](configuring-maintenance-window-permissions-console.md)
+ [Control access to maintenance windows using the AWS CLI](configuring-maintenance-window-permissions-cli.md)
# Control access to maintenance windows using the console
The following procedures describe how to use the AWS Systems Manager console to create the required permissions and roles for maintenance windows.
**Topics**
+ [Task 1: Create a custom policy for your maintenance window service role using the console](#create-custom-policy-console)
+ [Task 2: Create a custom service role for maintenance windows using the console](#create-custom-role-console)
+ [Task 3: Grant permissions to specified users to register maintenance window tasks using the console](#allow-maintenance-window-access-console)
+ [Task 4: Prevent specified users from registering maintenance window tasks using the console](#deny-maintenance-window-access-console)
## Task 1: Create a custom policy for your maintenance window service role using the console
Maintenance window tasks require an IAM role to provide the permissions required to run on the target resources. The permissions are provided through an IAM policy attached to the role. The types of tasks you run and your other operational requirements determine the contents of this policy. We provide a base policy you can adapt to your needs. Depending on the tasks and types of tasks your maintenance windows run, you might not need all the permissions in this policy, and you might need to include additional permissions. You attach this policy to the role that you create later in [Task 2: Create a custom service role for maintenance windows using the console](#create-custom-role-console).
**To create a custom policy using the console**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Policies**, and then choose **Create policy**.
1. In the **Policy editor** area, choose **JSON**.
1. Replace the default contents with the following:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand",
"ssm:CancelCommand",
"ssm:ListCommands",
"ssm:ListCommandInvocations",
"ssm:GetCommandInvocation",
"ssm:GetAutomationExecution",
"ssm:StartAutomationExecution",
"ssm:ListTagsForResource",
"ssm:DescribeInstanceInformation",
"ssm:GetParameters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"states:DescribeExecution",
"states:StartExecution"
],
"Resource": [
"arn:aws:states:*:*:execution:*:*",
"arn:aws:states:*:*:stateMachine:*"
]
},
{
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:*:*:function:*"
]
},
{
"Effect": "Allow",
"Action": [
"resource-groups:ListGroups",
"resource-groups:ListGroupResources"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"tag:GetResources"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/maintenance-window-role-name",
"Condition": {
"StringEquals": {
"iam:PassedToService": [
"ssm.amazonaws.com"
]
}
}
}
]
}
```
------
1. Modify the JSON content as needed for the maintenance tasks that you run in your account. The changes you make are specific to your planned operations.
For example:
+ You can provide Amazon Resource Names (ARNs) for specific functions and state machines instead of using wildcard (\$1) qualifiers.
+ If you don’t plan to run AWS Step Functions tasks, you can remove the `states` permissions and (ARNs).
+ If you don’t plan to run AWS Lambda tasks, you can remove the `lambda` permissions and ARNs.
+ If you don't plan to run Automation tasks, you can remove the `ssm:GetAutomationExecution` and `ssm:StartAutomationExecution` permissions.
+ Add additional permissions that might be needed for the tasks to run. For example, some Automation actions work with AWS CloudFormation stacks. Therefore, the permissions `cloudformation:CreateStack`, `cloudformation:DescribeStacks`, and `cloudformation:DeleteStack` are required.
For another example, the Automation runbook `AWS-CopySnapshot` requires permissions to create an Amazon Elastic Block Store (Amazon EBS) snapshot. Therefore, the service role needs the permission `ec2:CreateSnapshot`.
For information about the role permissions needed by Automation runbooks, see the runbook descriptions in the [AWS Systems Manager Automation Runbook Reference](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-runbook-reference.html).
1. After completing the policy revisions, choose **Next**.
1. For **Policy name**, enter a name that identifies this as the policy attached to the service role you create. For example: **my-maintenance-window-role-policy**.
1. (Optional) In the **Add tags** area, add one or more tag-key value pairs to organize, track, or control access for this policy.
1. Choose **Create policy**.
Make a note of the name you specified for the policy. You refer to it in the next procedure, [Task 2: Create a custom service role for maintenance windows using the console](#create-custom-role-console).
## Task 2: Create a custom service role for maintenance windows using the console
The policy you created in the previous task is attached to the maintenance window service role you create in this task. When users register a maintenance window task, they specify this IAM role as part of the task configuration. The permissions in this role allow Systems Manager to run tasks in maintenance windows on your behalf.
**Important**
Previously, the Systems Manager console provided you with the ability to choose the AWS managed IAM service-linked role `AWSServiceRoleForAmazonSSM` to use as the maintenance role for your tasks. Using this role and its associated policy, `AmazonSSMServiceRolePolicy`, for maintenance window tasks is no longer recommended. If you're using this role for maintenance window tasks now, we encourage you to stop using it. Instead, create your own IAM role that enables communication between Systems Manager and other AWS services when your maintenance window tasks run.
Use the following procedure to create a custom service role for Maintenance Windows, so that Systems Manager can run Maintenance Windows tasks on your behalf. You attach the policy you created in the previous task to the custom service role you create.
**To create a custom service role for maintenance windows using the console**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Roles**, and then choose **Create role**.
1. For **Select trusted entity**, make the following choices:
1. For **Trusted entity type**, choose **AWS service**.
1. For **Use case**, choose **Systems Manager**
1. Choose **Systems Manager**.
The following image highlights the location of the Systems Manager option.
![\[Systems Manager is one of the options for Use case.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/iam_use_cases_for_MWs.png)
1. Choose **Next**.
1. In the **Permissions policies** area, in the search box, enter the name of the policy you created in [Task 1: Create a custom policy for your maintenance window service role using the console](#create-custom-policy-console), select the box next to its name, and then choose **Next**.
1. For **Role name**, enter a name that identifies this role as a Maintenance Windows role. For example: **my-maintenance-window-role**.
1. (Optional) Change the default role description to reflect the purpose of this role. For example: **Performs maintenance window tasks on your behalf**.
1. For **Step 1: Select trusted entities**, verify that the following policy is displayed in the **Trusted policy** box.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. For **Step 2: Add permissions**, verify that policy you created in [Task 1: Create a custom policy for your maintenance window service role using the console](#create-custom-policy-console) is present.
1. (Optional) In **Step 3: Add tags**, add one or more tag-key value pairs to organize, track, or control access for this role.
1. Choose **Create role**. The system returns you to the **Roles** page.
1. Choose the name of the IAM role you just created.
1. Copy or make a note of the role name and the **ARN** value in the **Summary** area. Users in your account specify this information when they create maintenance windows.
## Task 3: Grant permissions to specified users to register maintenance window tasks using the console
Providing users with permissions to access the custom service role for maintenance windows lets them use it with their maintenance windows tasks. This is in addition to permissions that you’ve already given them to work with the Systems Manager API commands for the Maintenance Windows tool. This IAM role conveys the permissions need to run a maintenance window task. As a result, a user can't register tasks with a maintenance window using your custom service role without the ability to pass these IAM permissions.
When you register a task with a maintenance window, you specify a service role to run the actual task operations. This is the role that the service assumes when it runs tasks on your behalf. Before that, to register the task itself, assign the IAM `PassRole` policy to an IAM entity (such as a user or group). This allows the IAM entity to specify, as part of registering those tasks with the maintenance window, the role that should be used when running tasks. For information, see [Grant a user permissions to pass a role to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) in the *IAM User Guide*.
**To configure permissions to allow users to register maintenance window tasks**
If an IAM entity (user, role, or group) is set up with administrator permissions, then the IAM user or role has access to Maintenance Windows. For IAM entities without administrator permissions, an administrator must grant the following permissions to the IAM entity. These are the minimum permissions required to register tasks with a maintenance window:
+ The `AmazonSSMFullAccess` managed policy, or a policy that provides comparable permissions.
+ The following `iam:PassRole` and `iam:ListRoles`permissions.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/my-maintenance-window-role"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "arn:aws:iam::111122223333:role/"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "arn:aws:iam::111122223333:role/aws-service-role/ssm.amazonaws.com/"
}
]
}
```
------
*my-maintenance-window-role* represents the name of the custom maintenance window service role you created earlier.
*account-id* represents the ID of your AWS account. Adding this permission for the resource `arn:aws:iam::account-id:role/` allows a user to view and choose from customer roles in the console when they create a maintenance window task. Adding this permission for `arn:aws:iam::account-id:role/aws-service-role/ssm.amazonaws.com/` allows a user to choose the Systems Manager service-linked role in the console when they create a maintenance window task.
To provide access, add permissions to your users, groups, or roles:
+ Users and groups in AWS IAM Identity Center:
Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*.
+ Users managed in IAM through an identity provider:
Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*.
+ IAM users:
+ Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*.
+ (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*.
**To configure permissions for groups that are allowed to register maintenance window tasks using the console**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **User groups**.
1. In the list of groups, select the name of the group you want to assign the `iam:PassRole` permission to, or first create a new group if necessary
1. On the **Permissions** tab, choose **Add permissions, Create inline policy**.
1. In the **Policy editor** area, choose **JSON**, and replace the default contents of the box with the following.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/my-maintenance-window-role"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "arn:aws:iam::111122223333:role/"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "arn:aws:iam::111122223333:role/aws-service-role/ssm.amazonaws.com/"
}
]
}
```
------
*my-maintenance-window-role* represents the name of the custom maintenance window role you created earlier.
*account-id* represents the ID of your AWS account. Adding this permission for the resource `arn:aws:iam::account-id:role/` allows a user to view and choose from customer roles in the console when they create a maintenance window task. Adding this permission for `arn:aws:iam::account-id:role/aws-service-role/ssm.amazonaws.com/` allows a user to choose the Systems Manager service-linked role in the console when they create a maintenance window task.
1. Choose **Next**.
1. On the **Review and create** page, enter a name in the **Policy name** box to identify this `PassRole` policy, such as **my-group-iam-passrole-policy**, and then choose **Create policy**.
## Task 4: Prevent specified users from registering maintenance window tasks using the console
You can deny the `ssm:RegisterTaskWithMaintenanceWindow` permission for the users in your AWS account who you don't want to register tasks with maintenance windows. This provides an extra layer of prevention for users who shouldn’t register maintenance window tasks.
**To configure permissions for groups that aren't allowed to register maintenance window tasks using the console**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **User groups**.
1. In the list of groups, select the name of the group you want to deny the `ssm:RegisterTaskWithMaintenanceWindow` permission from, or first create a new group if necessary.
1. On the **Permissions** tab, choose **Add permissions, Create inline policy**.
1. In the **Policy editor** area, choose **JSON**, and then replace the default contents of the box with the following.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "ssm:RegisterTaskWithMaintenanceWindow",
"Resource": "*"
}
]
}
```
------
1. Choose **Next**.
1. On the **Review and create** page, for **Policy name**, enter a name to identify this policy, such as **my-groups-deny-mw-tasks-policy**, and then choose **Create policy**.
# Control access to maintenance windows using the AWS CLI
The following procedures describe how to use the AWS Command Line Interface (AWS CLI) to create the required permissions and roles for Maintenance Windows, a tool in AWS Systems Manager.
**Topics**
+ [Task 1: Create trust policy and customer managed policy files in JSON format](#create-custom-policy-json-files-cli)
+ [Task 2: Create and verify a custom service role for maintenance windows using the AWS CLI](#create-custom-role-cli)
+ [Task 3: Grant permissions to specified users to register maintenance window tasks using the AWS CLI](#allow-maintenance-window-access-cli)
+ [Task 4: Prevent specified users from registering maintenance window tasks using the AWS CLI](#deny-maintenance-window-access-cli)
## Task 1: Create trust policy and customer managed policy files in JSON format
Maintenance window tasks require an IAM role to provide the permissions required to run on the target resources. The permissions are provided through an IAM policy attached to the role. The types of tasks you run and your other operational requirements determine the contents of this policy. We provide a base policy you can adapt to your needs. Depending on the tasks and types of tasks your maintenance windows run, you might not need all the permissions in this policy, and you might need to include additional permissions.
In this task, you specify the permissions needed for your custom maintenance window role in a pair of JSON files. You attach this policy to the role that you create later in [Task 2: Create and verify a custom service role for maintenance windows using the AWS CLI](#create-custom-role-cli).
**To create trust policy and customer managed policy files**
1. Copy and paste the following trust policy into a text file. Save this file with the following name and file extension: **mw-role-trust-policy.json**.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Copy and paste the following JSON policy into a different text file. In the same directory where you created the first file, save this file with the following name and file extension: **mw-role-custom-policy.json**.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:SendCommand",
"ssm:CancelCommand",
"ssm:ListCommands",
"ssm:ListCommandInvocations",
"ssm:GetCommandInvocation",
"ssm:GetAutomationExecution",
"ssm:StartAutomationExecution",
"ssm:ListTagsForResource",
"ssm:GetParameters"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"states:DescribeExecution",
"states:StartExecution"
],
"Resource": [
"arn:aws:states:*:*:execution:*:*",
"arn:aws:states:*:*:stateMachine:*"
]
},
{
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:*:*:function:*"
]
},
{
"Effect": "Allow",
"Action": [
"resource-groups:ListGroups",
"resource-groups:ListGroupResources"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"tag:GetResources"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/maintenance-window-role-name",
"Condition": {
"StringEquals": {
"iam:PassedToService": [
"ssm.amazonaws.com"
]
}
}
}
]
}
```
------
1. Modify the the content of `mw-role-custom-policy.json` as needed for the maintenance tasks that you run in your account. The changes you make are specific to your planned operations.
For example:
+ You can provide Amazon Resource Names (ARNs) for specific functions and state machines instead of using wildcard (\$1) qualifiers.
+ If you don’t plan to run AWS Step Functions tasks, you can remove the `states` permissions and (ARNs).
+ If you don’t plan to run AWS Lambda tasks, you can remove the `lambda` permissions and ARNs.
+ If you don't plan to run Automation tasks, you can remove the `ssm:GetAutomationExecution` and `ssm:StartAutomationExecution` permissions.
+ Add additional permissions that might be needed for the tasks to run. For example, some Automation actions work with AWS CloudFormation stacks. Therefore, the permissions `cloudformation:CreateStack`, `cloudformation:DescribeStacks`, and `cloudformation:DeleteStack` are required.
For another example, the Automation runbook `AWS-CopySnapshot` requires permissions to create an Amazon Elastic Block Store (Amazon EBS) snapshot. Therefore, the service role needs the permission `ec2:CreateSnapshot`.
For information about the role permissions needed by Automation runbooks, see the runbook descriptions in the [AWS Systems Manager Automation Runbook Reference](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-runbook-reference.html).
Save the file again after making any needed changes.
## Task 2: Create and verify a custom service role for maintenance windows using the AWS CLI
The policy you created in the previous task is attached to the maintenance window service role you create in this task. When users register a maintenance window task, they specify this IAM role as part of the task configuration. The permissions in this role allow Systems Manager to run tasks in maintenance windows on your behalf.
**Important**
Previously, the Systems Manager console provided you with the ability to choose the AWS managed IAM service-linked role `AWSServiceRoleForAmazonSSM` to use as the maintenance role for your tasks. Using this role and its associated policy, `AmazonSSMServiceRolePolicy`, for maintenance window tasks is no longer recommended. If you're using this role for maintenance window tasks now, we encourage you to stop using it. Instead, create your own IAM role that enables communication between Systems Manager and other AWS services when your maintenance window tasks run.
In this task, you run CLI commands to create your maintenance windows service role, adding the policy content from the JSON files you created.
**Create a custom service role for maintenance windows using the AWS CLI**
1. Open the AWS CLI and run the following command in the directory where you placed `mw-role-custom-policy.json` and `mw-role-trust-policy.json`. The command creates a maintenance window service role called `my-maintenance-window-role` and attaches the *trust policy* to it.
------
#### [ Linux & macOS ]
```
aws iam create-role \
--role-name "my-maintenance-window-role" \
--assume-role-policy-document file://mw-role-trust-policy.json
```
------
#### [ Windows ]
```
aws iam create-role ^
--role-name "my-maintenance-window-role" ^
--assume-role-policy-document file://mw-role-trust-policy.json
```
------
The system returns information similar to the following.
```
{
"Role": {
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
}
}
]
},
"RoleId": "AROAIIZKPBKS2LEXAMPLE",
"CreateDate": "2024-08-19T03:40:17.373Z",
"RoleName": "my-maintenance-window-role",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:role/my-maintenance-window-role"
}
}
```
**Note**
Make a note of the `RoleName` and the `Arn` values. You include them in the next command.
1. Run the following command to attach the *customer managed policy* to the role. Replace the *account-id* placeholder with your own AWS account ID
------
#### [ Linux & macOS ]
```
aws iam attach-role-policy \
--role-name "my-maintenance-window-role" \
--policy-arn "arn:aws:iam::account-id:policy/mw-role-custom-policy.json"
```
------
#### [ Windows ]
```
aws iam attach-role-policy ^
--role-name "my-maintenance-window-role" ^
--policy-arn "arn:aws:iam::account-id:policy/mw-role-custom-policy.json"
```
------
1. Run the following command to verify that your role has been created, and that the trust policy has been attached.
```
aws iam get-role --role-name my-maintenance-window-role
```
The command returns information similar to the following:
```
{
"Role": {
"Path": "/",
"RoleName": "my-maintenance-window-role",
"RoleId": "AROA123456789EXAMPLE",
"Arn": "arn:aws:iam::123456789012:role/my-maintenance-window-role",
"CreateDate": "2024-08-19T14:13:32+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ssm.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
},
"MaxSessionDuration": 3600,
"RoleLastUsed": {
"LastUsedDate": "2024-08-19T14:30:44+00:00",
"Region": "us-east-2"
}
}
}
```
1. Run the following command to verify that the customer managed policy has been attached to the role.
```
aws iam list-attached-role-policies --role-name my-maintenance-window-role
```
The command returns information similar to the following:
```
{
"AttachedPolicies": [
{
"PolicyName": "mw-role-custom-policy",
"PolicyArn": "arn:aws:iam::123456789012:policy/mw-role-custom-policy"
}
]
}
```
## Task 3: Grant permissions to specified users to register maintenance window tasks using the AWS CLI
Providing users with permissions to access the custom service role for maintenance windows lets them use it with their maintenance windows tasks. This is in addition to permissions that you’ve already given them to work with the Systems Manager API commands for the Maintenance Windows tool. This IAM role conveys the permissions need to run a maintenance window task. As a result, a user can't register tasks with a maintenance window using your custom service role without the ability to pass these IAM permissions.
When you register a task with a maintenance window, you specify a service role to run the actual task operations. This is the role that the service assumes when it runs tasks on your behalf. Before that, to register the task itself, assign the IAM `PassRole` policy to an IAM entity (such as a user or group). This allows the IAM entity to specify, as part of registering those tasks with the maintenance window, the role that should be used when running tasks. For information, see [Grant a user permissions to pass a role to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) in the *IAM User Guide*.
**To configure permissions for users who are allowed to register maintenance window tasks using the AWS CLI**
1. Copy and paste the following AWS Identity and Access Management (IAM) policy into a text editor and save it with the following name and file extension: `mw-passrole-policy.json`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/my-maintenance-window-role"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "arn:aws:iam::111122223333:role/"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "arn:aws:iam::111122223333:role/aws-service-role/ssm.amazonaws.com/"
}
]
}
```
------
Replace *my-maintenance-window-role* with the name of the custom maintenance window role you created earlier.
Replace *account-id* with the ID of your AWS account. Adding this permission for the resource `arn:aws:iam::account-id:role/` allows users in the group to view and choose from customer roles in the console when they create a maintenance window task. Adding this permission for `arn:aws:iam::account-id:role/aws-service-role/ssm.amazonaws.com/` allows users in the group to choose the Systems Manager service-linked role in the console when they create a maintenance window task.
1. Open the AWS CLI.
1. Depending on whether you're assigning the permission to an IAM entity (user or group), run one of the following commands.
+ **For an IAM entity:**
------
#### [ Linux & macOS ]
```
aws iam put-user-policy \
--user-name "user-name" \
--policy-name "policy-name" \
--policy-document file://path-to-document
```
------
#### [ Windows ]
```
aws iam put-user-policy ^
--user-name "user-name" ^
--policy-name "policy-name" ^
--policy-document file://path-to-document
```
------
For *user-name*, specify the user who assigns tasks to maintenance windows. For *policy-name*, specify the name you want to use to identify the policy, such as **my-iam-passrole-policy**. For *path-to-document*, specify the path to the file you saved in step 1. For example: `file://C:\Temp\mw-passrole-policy.json`
**Note**
To grant access for a user to register tasks for maintenance windows using the Systems Manager console, you must also assign the `AmazonSSMFullAccess` policy to your user (or an IAM policy that provides a smaller set of access permissions for Systems Manager that covers maintenance window tasks). Run the following command to assign the `AmazonSSMFullAccess` policy to your user.
```
aws iam attach-user-policy \
--policy-arn "arn:aws:iam::aws:policy/AmazonSSMFullAccess" \
--user-name "user-name"
```
```
aws iam attach-user-policy ^
--policy-arn "arn:aws:iam::aws:policy/AmazonSSMFullAccess" ^
--user-name "user-name"
```
+ **For an IAM group:**
------
#### [ Linux & macOS ]
```
aws iam put-group-policy \
--group-name "group-name" \
--policy-name "policy-name" \
--policy-document file://path-to-document
```
------
#### [ Windows ]
```
aws iam put-group-policy ^
--group-name "group-name" ^
--policy-name "policy-name" ^
--policy-document file://path-to-document
```
------
For *group-name*, specify the group whose members assign tasks to maintenance windows. For *policy-name*, specify the name you want to use to identify the policy, such as **my-iam-passrole-policy**. For *path-to-document*, specify the path to the file you saved in step 1. For example: `file://C:\Temp\mw-passrole-policy.json`
**Note**
To grant access for members of a group to register tasks for maintenance windows using the Systems Manager console, you must also assign the `AmazonSSMFullAccess` policy to your group. Run the following command to assign this policy to your group.
```
aws iam attach-group-policy \
--policy-arn "arn:aws:iam::aws:policy/AmazonSSMFullAccess" \
--group-name "group-name"
```
```
aws iam attach-group-policy ^
--policy-arn "arn:aws:iam::aws:policy/AmazonSSMFullAccess" ^
--group-name "group-name"
```
1. Run the following command to verify that the policy has been assigned to the group.
------
#### [ Linux & macOS ]
```
aws iam list-group-policies \
--group-name "group-name"
```
------
#### [ Windows ]
```
aws iam list-group-policies ^
--group-name "group-name"
```
------
## Task 4: Prevent specified users from registering maintenance window tasks using the AWS CLI
You can deny the `ssm:RegisterTaskWithMaintenanceWindow` permission for the users in your AWS account who you don't want to register tasks with maintenance windows. This provides an extra layer of prevention for users who shouldn’t register maintenance window tasks.
Depending on whether you're denying the `ssm:RegisterTaskWithMaintenanceWindow` permission for an individual user or a group, use one of the following procedures to prevent users from registering tasks with a maintenance window.
**To configure permissions for users who aren't allowed to register maintenance window tasks using the AWS CLI**
1. Copy and paste the following IAM policy into a text editor and save it with the following name and file extension: **deny-mw-tasks-policy.json**.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "ssm:RegisterTaskWithMaintenanceWindow",
"Resource": "*"
}
]
}
```
------
1. Open the AWS CLI.
1. Depending on whether you're assigning the permission to an IAM entity (user or group), run one of the following commands.
+ **For a user:**
------
#### [ Linux & macOS ]
```
aws iam put-user-policy \
--user-name "user-name" \
--policy-name "policy-name" \
--policy-document file://path-to-document
```
------
#### [ Windows ]
```
aws iam put-user-policy ^
--user-name "user-name" ^
--policy-name "policy-name" ^
--policy-document file://path-to-document
```
------
For *user-name*, specify the user to prevent from assigning tasks to maintenance windows. For *policy-name*, specify the name you want to use to identify the policy, such as **my-deny-mw-tasks-policy**. For *path-to-document*, specify the path to the file you saved in step 1. For example: `file://C:\Temp\deny-mw-tasks-policy.json`
+ **For a group:**
------
#### [ Linux & macOS ]
```
aws iam put-group-policy \
--group-name "group-name" \
--policy-name "policy-name" \
--policy-document file://path-to-document
```
------
#### [ Windows ]
```
aws iam put-group-policy ^
--group-name "group-name" ^
--policy-name "policy-name" ^
--policy-document file://path-to-document
```
------
For *group-name*, specify the group whose to prevent from assigning tasks to maintenance windows. For *policy-name*, specify the name you want to use to identify the policy, such as **my-deny-mw-tasks-policy**. For *path-to-document*, specify the path to the file you saved in step 1. For example: `file://C:\Temp\deny-mw-tasks-policy.json`
1. Run the following command to verify that the policy has been assigned to the group.
------
#### [ Linux & macOS ]
```
aws iam list-group-policies \
--group-name "group-name"
```
------
#### [ Windows ]
```
aws iam list-group-policies ^
--group-name "group-name"
```
------
# Create and manage maintenance windows using the console
This section describes how to create, configure, update, and delete maintenance windows using the AWS Systems Manager console. This section also provides information about managing the targets and tasks of a maintenance window.
**Important**
We recommend that you initially create and configure maintenance windows in a test environment.
**Before you begin**
Before you create a maintenance window, you must configure access to Maintenance Windows, a tool in AWS Systems Manager. For more information, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md).
**Topics**
+ [Create a maintenance window using the console](sysman-maintenance-create-mw.md)
+ [Assign targets to a maintenance window using the console](sysman-maintenance-assign-targets.md)
+ [Assign tasks to a maintenance window using the console](sysman-maintenance-assign-tasks.md)
+ [Disable or enable a maintenance window using the console](sysman-maintenance-disable.md)
+ [Update or delete maintenance window resources using the console](sysman-maintenance-update.md)
# Create a maintenance window using the console
In this procedure, you create a maintenance window in Maintenance Windows, a tool in AWS Systems Manager. You can specify its basic options, such as name, schedule, and duration. In later steps, you choose the targets, or resources, that it updates and the tasks that run when the maintenance window runs.
**Note**
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](maintenance-windows-schedule-options.md).
For more information about working with the `--schedule` option, see [Reference: Cron and rate expressions for Systems Manager](reference-cron-and-rate-expressions.md).
**To create a maintenance window using the console**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. Choose **Create maintenance window**.
1. For **Name**, enter a descriptive name to help you identify this maintenance window.
1. (Optional) For **Description**, enter a description to identify how this maintenance window will be used.
1. (Optional) If you want to allow a maintenance window task to run on managed nodes, even if you haven't registered those nodes as targets, choose **Allow unregistered targets**.
If you choose this option, then you can choose the unregistered nodes (by node ID) when you register a task with the maintenance window.
If you don't choose this option, then you must choose previously registered targets when you register a task with the maintenance window.
1. Specify a schedule for the maintenance window by using one of the three scheduling options.
For information about building cron/rate expressions, see [Reference: Cron and rate expressions for Systems Manager](reference-cron-and-rate-expressions.md).
1. For **Duration**, enter the number of hours the maintenance window will run. The value you specify determines the specific end time for the maintenance window based on the time it begins. No maintenance window tasks are permitted to start after the resulting endtime minus the number of hours you specify for **Stop initiating tasks** in the next step.
For example, if the maintenance window starts at 3 PM, the duration is three hours, and the **Stop initiating tasks** value is one hour, no maintenance window tasks can start after 5 PM.
1. For **Stop initiating tasks**, enter the number of hours before the end of the maintenance window that the system should stop scheduling new tasks to run.
1. (Optional) For **Window start date**, specify a date and time, in ISO-8601 Extended format, for when you want the maintenance window to become active. This allows you to delay activation of the maintenance window until the specified future date.
**Note**
You can't specify a start date and time that occurs in the past.
1. (Optional) For **Window end date**, specify a date and time, in ISO-8601 Extended format, for when you want the maintenance window to become inactive. This allows you to set a date and time in the future after which the maintenance window no longer runs.
1. (Optional) For **Schedule timezone**, specify the time zone to use as the basis for when scheduled maintenance windows run, in Internet Assigned Numbers Authority (IANA) format. For example: "America/Los\$1Angeles", "etc/UTC", or "Asia/Seoul".
For more information about valid formats, see the [Time Zone Database](https://www.iana.org/time-zones) on the IANA website.
1. (Optional) For **Schedule offset**, enter the number of days to wait after the date and time specified by a cron or rate expression before running the maintenance window. You can specify between one and six days.
**Note**
This option is available only if you specified a schedule by entering a cron or rate expression manually.
1. (Optional) In the **Manage tags** area, apply one or more tag key name/value pairs to the maintenance window.
Tags are optional metadata that you assign to a resource. Tags allow you to categorize a resource in different ways, such as by purpose, owner, or environment. For example, you might want to tag a maintenance window to identify the type of tasks it runs, the types of targets, and the environment it runs in. In this case, you could specify the following key name/value pairs:
+ `Key=TaskType,Value=AgentUpdate`
+ `Key=OS,Value=Windows`
+ `Key=Environment,Value=Production`
1. Choose **Create maintenance window**. The system returns you to the maintenance window page. The state of the maintenance window you just created is **Enabled**.
# Assign targets to a maintenance window using the console
In this procedure, you register a target with a maintenance window. In other words, you specify which resources the maintenance window performs actions on.
**Note**
If a single maintenance window task is registered with multiple targets, its task invocations occur sequentially and not in parallel. If your task must run on multiple targets at the same time, register a task for each target individually and assign each task the same priority level.
**To assign targets to a maintenance window using the console**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. In the list of maintenance windows, choose the maintenance window to add targets to.
1. Choose **Actions**, and then choose **Register targets**.
1. (Optional) For **Target name**, enter a name for the targets.
1. (Optional) For **Description**, enter a description.
1. (Optional) For **Owner information**, specify information to include in any Amazon EventBridge event raised while running tasks for these targets in this maintenance window.
For information about using EventBridge to monitor Systems Manager events, see [Monitoring Systems Manager events with Amazon EventBridge](monitoring-eventbridge-events.md).
1. In the **Targets** area, choose one of the options described in the following table.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-maintenance-assign-targets.html)
1. Choose **Register target**.
If you want to assign more targets to this maintenance window, choose the **Targets** tab, and then choose **Register target**. With this option, you can choose a different means of targeting. For example, if you previously targeted nodes by node ID, you can register new targets and target nodes by specifying tags applied to managed nodes or choosing resource types from a resource group.
# Assign tasks to a maintenance window using the console
In this procedure, you add a task to a maintenance window. Tasks are the actions performed when a maintenance window runs.
The following four types of tasks can be added to a maintenance window:
+ AWS Systems Manager Run Command commands
+ Systems Manager Automation workflows
+ AWS Step Functions tasks
+ AWS Lambda functions
**Important**
The IAM policy for Maintenance Windows requires that you add the prefix `SSM` to Lambda function (or alias) names. Before you proceed to register this type of task, update its name in AWS Lambda to include `SSM`. For example, if your Lambda function name is `MyLambdaFunction`, change it to `SSMMyLambdaFunction`.
**To assign tasks to a maintenance window**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. In the list of maintenance windows, choose a maintenance window.
1. Choose **Actions**, and then choose the option for the type of task you want to register with the maintenance window.
+ **Register Run command task**
+ **Register Automation task**
+ **Register Lambda task**
+ **Register Step Functions task**
**Note**
Maintenance window tasks support Step Functions Standard state machine workflows only. They don't support Express state machine workflows. For information about state machine workflow types, see [Standard vs. Express Workflows](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-standard-vs-express.html) in the *AWS Step Functions Developer Guide*.
1. (Optional) For **Name**, enter a name for the task.
1. (Optional) For **Description**, enter a description.
1. For **New task invocation cutoff**, if you don't want any new task invocations to start after the maintenance window cutoff time is reached, choose **Enabled**.
When this option is *not* enabled, the task continues running when the cutoff time is reached and starts new task invocations until completion.
**Note**
The status for tasks that are not completed when you enable this option is `TIMED_OUT`.
1. For this step, choose the tab for your selected task type.
------
#### [ Run Command ]
1. In the **Command document** list, choose the Systems Manager Command document (SSM document) that defines the tasks to run.
1. For **Document version**, choose the document version to use.
1. For **Task priority**, specify a priority for this task. Zero (`0`) is the highest priority. Tasks in a maintenance window are scheduled in priority order with tasks that have the same priority scheduled in parallel.
------
#### [ Automation ]
1. In the **Automation document** list, choose the Automation runbook that defines the tasks to run.
1. For **Document version**, choose the runbook version to use.
1. For **Task priority**, specify a priority for this task. Zero (`0`) is the highest priority. Tasks in a maintenance window are scheduled in priority order with tasks that have the same priority scheduled in parallel.
------
#### [ Lambda ]
1. In the **Lambda parameters** area, choose a Lambda function from the list.
1. (Optional) Provide any content for **Payload**, **Client Context**, or **Qualifier** that you want to include.
**Note**
In some cases, you can use a *pseudo parameter* as part of your `Payload` value. Then when the maintenance window task runs, it passes the correct values instead of the pseudo parameter placeholders. For information, see [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md).
1. For **Task priority**, specify a priority for this task. Zero (`0`) is the highest priority. Tasks in a maintenance window are scheduled in priority order with tasks that have the same priority scheduled in parallel.
------
#### [ Step Functions ]
1. In the **Step Functions parameters** area, choose a state machine from the list.
1. (Optional) Provide a name for the state machine execution and any content for **Input** that you want to include.
**Note**
In some cases, you can use a *pseudo parameter* as part of your `Input` value. Then when the maintenance window task runs, it passes the correct values instead of the pseudo parameter placeholders. For information, see [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md).
1. For **Task priority**, specify a priority for this task. Zero (`0`) is the highest priority. Tasks in a maintenance window are scheduled in priority order with tasks that have the same priority scheduled in parallel.
------
1. In the **Targets** area, choose one of the following:
+ **Selecting registered target groups**: Select one or more maintenance window targets you have registered with the current maintenance window.
+ **Selecting unregistered targets**: Choose available resources one by one as targets for the task.
If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips.
+ **Task target not required**: Targets for the task might already be specified in other functions for all but Run Command-type tasks.
Specify one or more targets for maintenance window Run Command-type tasks. Depending on the task, targets are optional for other maintenance window task types (Automation, AWS Lambda, and AWS Step Functions). For more information about running tasks that don't specify targets, see [Registering maintenance window tasks without targets](maintenance-windows-targetless-tasks.md).
**Note**
In many cases, you don't need to explicitly specify a target for an automation task. For example, say that you're creating an Automation-type task to update an Amazon Machine Image (AMI) for Linux using the `AWS-UpdateLinuxAmi` runbook. When the task runs, the AMI is updated with the latest available Linux distribution packages and Amazon software. New instances created from the AMI already have these updates installed. Because the ID of the AMI to be updated is specified in the input parameters for the runbook, there is no need to specify a target again in the maintenance window task.
1. *Automation tasks only:*
In the **Input parameters** area, provide values for any required or optional parameters needed to run your task.
**Note**
In some cases, you can use a *pseudo parameter* for certain input parameter values. Then when the maintenance window task runs, it passes the correct values instead of the pseudo parameter placeholders. For information, see [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md).
1. For **Rate control**:
+ For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time.
**Note**
If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage.
+ For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors.
1. (Optional) For **IAM service role**, choose a role to provide permissions for Systems Manager to assume when running a maintenance window task.
If you don't specify a service role ARN, Systems Manager uses a service-linked role in your account. This role is not listed in the drop-down menu. If no appropriate service-linked role for Systems Manager exists in your account, it's created when the task is registered successfully.
**Note**
For an improved security posture, we strongly recommend creating a custom policy and custom service role for running your maintenance window tasks. The policy can be crafted to provide only the permissions needed for your particular maintenance window tasks. For more information, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md).
1. *Run Command tasks only:*
(Optional) For **Output options**, do the following:
+ Select the **Enable writing to S3** check box to save the command output to a file. Enter the bucket and prefix (folder) names in the boxes.
+ Select the **CloudWatch output** check box to write complete output to Amazon CloudWatch Logs. Enter the name of a CloudWatch Logs log group.
**Note**
The permissions that grant the ability to write data to an S3 bucket or CloudWatch Logs are those of the instance profile assigned to the node, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md). In addition, if the specified S3 bucket or log group is in a different AWS account, verify that the instance profile associated with the node has the necessary permissions to write to that bucket.
1. *Run Command tasks only:*
In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box.
For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md).
1. *Run Command tasks only:*
In the **Parameters** area, specify parameters for the document.
**Note**
In some cases, you can use a *pseudo parameter* for certain input parameter values. Then when the maintenance window task runs, it passes the correct values instead of the pseudo parameter placeholders. For information, see [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md).
1. * Run Command and Automation tasks only:*
(Optional) In the **CloudWatch alarm** area, for **Alarm name**, choose an existing CloudWatch alarm to apply to your task for monitoring.
If the alarm activates, the task is stopped.
**Note**
To attach a CloudWatch alarm to your task, the IAM principal that runs the task must have permission for the `iam:createServiceLinkedRole` action. For more information about CloudWatch alarms, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html).
1. Depending on your task type, choose one of the following:
+ **Register Run command task**
+ **Register Automation task**
+ **Register Lambda task**
+ **Register Step Functions task**
# Disable or enable a maintenance window using the console
You can disable or enable a maintenance window in Maintenance Windows, a tool in AWS Systems Manager. You can choose one maintenance window at a time to either disable or enable the maintenance window from running. You can also select multiple or all maintenance windows to enable and disable.
This section describes how to disable or enable a maintenance window by using the Systems Manager console. For examples of how to do this by using the AWS Command Line Interface (AWS CLI), see [Tutorial: Update a maintenance window using the AWS CLI](maintenance-windows-cli-tutorials-update.md).
**Topics**
+ [Disable a maintenance window using the console](#sysman-maintenance-disable-mw)
+ [Enable a maintenance window using the console](#sysman-maintenance-enable-mw)
## Disable a maintenance window using the console
You can disable a maintenance window to pause a task for a specified period, and it will remain available to enable again later.
**To disable a maintenance window**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. Using the check box next to the maintenance window that you want to disable, select one or more maintenance windows.
1. Choose **Disable maintenance window** in the **Actions** menu. The system prompts you to confirm your actions.
## Enable a maintenance window using the console
You can enable a maintenance window to resume a task.
**Note**
If the maintenance window uses a rate schedule and the start date is currently set to a past date and time, the current date and time is used as the start date for the maintenance window. You can change the start date of the maintenance window before or after enabling it. For information, see [Update or delete maintenance window resources using the console](sysman-maintenance-update.md).
**To enable a maintenance window**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. Select the check box next to the maintenance window to enable.
1. Choose **Actions, Enable maintenance window**. The system prompts you to confirm your actions.
# Update or delete maintenance window resources using the console
You can update or delete a maintenance window in Maintenance Windows, a tool in AWS Systems Manager. You can also update or delete the targets or tasks of a maintenance window. If you edit the details of a maintenance window, you can change the schedule, targets, and tasks. You can also specify names and descriptions for windows, targets, and tasks, which helps you better understand their purpose, and makes it easier to manage your queue of windows.
This section describes how to update or delete a maintenance window, targets, and tasks by using the Systems Manager console. For examples of how to do this by using the AWS Command Line Interface (AWS CLI), see [Tutorial: Update a maintenance window using the AWS CLI](maintenance-windows-cli-tutorials-update.md).
**Topics**
+ [Updating or deleting a maintenance window using the console](#sysman-maintenance-update-mw)
+ [Updating or deregistering maintenance window targets using the console](#sysman-maintenance-update-target)
+ [Updating or deregistering maintenance window tasks using the console](#sysman-maintenance-update-tasks)
## Updating or deleting a maintenance window using the console
You can update a maintenance window to change its name, description, and schedule, and whether the maintenance window should allow unregistered targets.
**To update or delete a maintenance window**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. Select the button next to the maintenance window that you want to update or delete, and then do one of the following:
+ Choose **Delete**. The system prompts you to confirm your actions.
+ Choose **Edit**. On the **Edit maintenance window** page, change the values and options that you want, and then choose **Save changes**.
For information about the configuration choices you can make, see [Create a maintenance window using the console](sysman-maintenance-create-mw.md).
## Updating or deregistering maintenance window targets using the console
You can update or deregister the targets of a maintenance window. If you choose to update a maintenance window target you can specify a new target name, description, and owner. You can also choose different targets.
**To update or delete the targets of a maintenance window**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. Choose the name of the maintenance window that you want to update, choose the **Targets** tab, and then do one of the following:
+ To update targets, select the button next to the target to update, and then choose **Edit**.
+ To deregister targets, select the button next to the target to deregister, and then choose **Deregister target**. In the **Deregister maintenance windows target** dialog box, choose **Deregister**.
## Updating or deregistering maintenance window tasks using the console
You can update or deregister the tasks of a maintenance window. If you choose to update, you can specify a new task name, description, and owner. For Run Command and Automation tasks, you can choose a different SSM document for the tasks. You can't, however, edit a task to change its type. For example, if you created an Automation task, you can't edit that task and change it to a Run Command task.
**To update or delete the tasks of a maintenance window using the console**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. Choose the name of the maintenance window that you want to update.
1. Choose the **Tasks** tab, and then select the button next to the task to update.
1. Do one of the following:
+ To deregister a task, choose **Deregister task**.
+ To edit the task, choose **Edit**. Change the values and options that you want, and then choose **Edit task**.
# Tutorials
The tutorials in this section show you how to perform common tasks when working with maintenance windows.
**Complete prerequisites**
Before trying these tutorials, complete the following prerequisites.
+ **Configure the AWS CLI on your local machine** – Before you can run AWS CLI commands, you must install and configure the CLI on your local machine. For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
+ **Verify maintenance window roles and permissions** – An AWS administrator in your account must grant you the AWS Identity and Access Management (IAM) permissions you need to manage maintenance windows using the CLI. For information, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md).
+ **Create or configure an instance that is compatible with Systems Manager ** – You need at least one Amazon Elastic Compute Cloud (Amazon EC2) instance that is configured for use with Systems Manager to complete the tutorials. This means that SSM Agent is installed on the instance, and an IAM instance profile for Systems Manager is attached to the instance.
We recommend launching an instance from one AWS managed Amazon Machine Image (AMI) with the agent preinstalled. For more information, see [Find AMIs with the SSM Agent preinstalled](ami-preinstalled-agent.md).
For information about installing SSM Agent on an instance, see the following topics:
+ [Manually installing and uninstalling SSM Agent on EC2 instances for Windows Server](manually-install-ssm-agent-windows.md)
+ [Manually installing and uninstalling SSM Agent on EC2 instances for Linux](manually-install-ssm-agent-linux.md)
For information about configuring IAM permissions for Systems Manager to your instance, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md).
+ **Create additional resources as needed** – Run Command, a tool in Systems Manager, includes many tasks that don't require you to create resources other than those listed in this prerequisites topic. For that reason, we provide a simple Run Command task for you to use your first time through the tutorials. You also need an EC2 instance that is configured to use with Systems Manager, as described earlier in this topic. After you configure that instance, you can register a simple Run Command task.
The Systems Manager Maintenance Windows tool supports running the following four types of tasks:
+ Run Command commands
+ Systems Manager Automation workflows
+ AWS Lambda functions
+ AWS Step Functions tasks
In general, if a maintenance window task that you want to run requires additional resources, you should create them first. For example, if you want a maintenance window that runs an AWS Lambda function, create the Lambda function before you begin; for a Run Command task, create the S3 bucket that you can save command output to (if you plan to do so); and so on.
**Topics**
+ [Tutorials: Create and manage maintenance windows using the AWS CLI](maintenance-window-tutorial-cli.md)
+ [Tutorial: Create a maintenance window for patching using the console](maintenance-window-tutorial-patching.md)
# Tutorials: Create and manage maintenance windows using the AWS CLI
This section includes tutorials that help you learn how to use the AWS Command Line Interface (AWS CLI) to do the following:
+ Create and configure a maintenance window
+ View information about a maintenance window
+ View information about maintenance windows tasks and task executions
+ Update a maintenance window
+ Delete a maintenance window
**Keep track of resource IDs**
As you complete the tasks in these AWS CLI tutorials, keep track of resource IDs generated by the commands you run. You use many of these as input for subsequent commands. For example, when you create the maintenance window, the system provides you with a maintenance window ID in the following format.
```
{
"WindowId":"mw-0c50858d01EXAMPLE"
}
```
Make a note of the following system-generated IDs because the tutorials in this section use them:
+ `WindowId`
+ `WindowTargetId`
+ `WindowTaskId`
+ `WindowExecutionId`
+ `TaskExecutionId`
+ `InvocationId`
+ `ExecutionId`
You also need the ID of the EC2 instance that you plan to use in the tutorials. For example: `i-02573cafcfEXAMPLE`
**Topics**
+ [Tutorial: Create and configure a maintenance window using the AWS CLI](maintenance-windows-cli-tutorials-create.md)
+ [Tutorial: View information about maintenance windows using the AWS CLI](maintenance-windows-cli-tutorials-describe.md)
+ [Tutorial: View information about tasks and task executions using the AWS CLI](mw-cli-tutorial-task-info.md)
+ [Tutorial: Update a maintenance window using the AWS CLI](maintenance-windows-cli-tutorials-update.md)
+ [Tutorial: Delete a maintenance window using the AWS CLI](mw-cli-tutorial-delete-mw.md)
# Tutorial: Create and configure a maintenance window using the AWS CLI
This tutorial demonstrates how to use the AWS Command Line Interface (AWS CLI) to create and configure a maintenance window, its targets, and its tasks. The main path through the tutorial consists of simple steps. You create a single maintenance window, identify a single target, and set up a simple task for the maintenance window to run. Along the way, we provide information you can use to try more complicated scenarios.
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.
**Topics**
+ [Step 1: Create the maintenance window using the AWS CLI](mw-cli-tutorial-create-mw.md)
+ [Step 2: Register a target node with the maintenance window using the AWS CLI](mw-cli-tutorial-targets.md)
+ [Step 3: Register a task with the maintenance window using the AWS CLI](mw-cli-tutorial-tasks.md)
# Step 1: Create the maintenance window using the AWS CLI
In this step, you create a maintenance window and specify its basic options, such as name, schedule, and duration. In later steps, you choose the instance it updates and the task it runs.
In our example, you create a maintenance window that runs every five minutes. Normally, you wouldn't run a maintenance window this frequently. However, with this rate you can see your tutorial results quickly. We will show you how to change to a less frequent rate after the task has run successfully.
**Note**
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](maintenance-windows-schedule-options.md).
For more information about working with the `--schedule` option, see [Reference: Cron and rate expressions for Systems Manager](reference-cron-and-rate-expressions.md).
**To create a maintenance window using the AWS CLI**
1. Open the AWS Command Line Interface (AWS CLI) and run the following command on your local machine to create a maintenance window that does the following:
+ Runs every five minutes for up to two hours (as needed).
+ Prevents new tasks from starting within one hour of the end of the maintenance window operation.
+ Allows unassociated targets (instances that you haven't registered with the maintenance window).
+ Indicates through the use of custom tags that its creator intends to use it in a tutorial.
------
#### [ Linux & macOS ]
```
aws ssm create-maintenance-window \
--name "My-First-Maintenance-Window" \
--schedule "rate(5 minutes)" \
--duration 2 \
--cutoff 1 \
--allow-unassociated-targets \
--tags "Key=Purpose,Value=Tutorial"
```
------
#### [ Windows ]
```
aws ssm create-maintenance-window ^
--name "My-First-Maintenance-Window" ^
--schedule "rate(5 minutes)" ^
--duration 2 ^
--cutoff 1 ^
--allow-unassociated-targets ^
--tags "Key"="Purpose","Value"="Tutorial"
```
------
The system returns information similar to the following.
```
{
"WindowId":"mw-0c50858d01EXAMPLE"
}
```
1. Now run the following command to view details about this and any other maintenance windows already in your account.
```
aws ssm describe-maintenance-windows
```
The system returns information similar to the following.
```
{
"WindowIdentities":[
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Name": "My-First-Maintenance-Window",
"Enabled": true,
"Duration": 2,
"Cutoff": 1,
"NextExecutionTime": "2019-05-11T16:46:16.991Z"
}
]
}
```
Continue to [Step 2: Register a target node with the maintenance window using the AWS CLI](mw-cli-tutorial-targets.md).
# Step 2: Register a target node with the maintenance window using the AWS CLI
In this step, you register a target with your new maintenance window. In this case, you specify which node to update when the maintenance window runs.
For an example of registering more than one node at a time using node IDs, examples of using tags to identify multiple nodes, and examples of specifying resource groups as targets, see [Examples: Register targets with a maintenance window](mw-cli-tutorial-targets-examples.md).
**Note**
You should already have created an Amazon Elastic Compute Cloud (Amazon EC2) instance to use in this step, as described in the [Maintenance Windows tutorial prerequisites](maintenance-windows-tutorials.md).
**To register a target node with a maintenance window using the AWS CLI**
1. Run the following command on your local machine. Replace each *example resource placeholder* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--resource-type "INSTANCE" \
--target "Key=InstanceIds,Values=i-02573cafcfEXAMPLE"
```
------
#### [ Windows ]
```
aws ssm register-target-with-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--resource-type "INSTANCE" ^
--target "Key=InstanceIds,Values=i-02573cafcfEXAMPLE"
```
------
The system returns information similar to the following.
```
{
"WindowTargetId":"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
}
```
1. Now run the following command on your local machine to view details about your maintenance window target.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-targets \
--window-id "mw-0c50858d01EXAMPLE"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-targets ^
--window-id "mw-0c50858d01EXAMPLE"
```
------
The system returns information similar to the following.
```
{
"Targets": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE",
"ResourceType": "INSTANCE",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE"
]
}
]
}
]
}
```
Continue to [Step 3: Register a task with the maintenance window using the AWS CLI](mw-cli-tutorial-tasks.md).
# Examples: Register targets with a maintenance window
You can register a single node as a target using its node ID, as demonstrated in [Step 2: Register a target node with the maintenance window using the AWS CLI](mw-cli-tutorial-targets.md). You can also register one or more nodes as targets using the command formats on this page.
In general, there are two methods for identifying the nodes you want to use as maintenance window targets: specifying individual nodes, and using resource tags. The resource tags method provides more options, as shown in examples 2-3.
You can also specify one or more resource groups as the target of a maintenance window. A resource group can include nodes and many other types of supported AWS resources. Examples 4 and 5, next, demonstrate how to add resource groups to your maintenance window targets.
**Note**
If a single maintenance window task is registered with multiple targets, its task invocations occur sequentially and not in parallel. If your task must run on multiple targets at the same time, register a task for each target individually and assign each task the same priority level.
For more information about creating and managing resource groups, see [What are resource groups?](https://docs.aws.amazon.com/ARG/latest/userguide/resource-groups.html) in the *AWS Resource Groups User Guide* and [Resource Groups and Tagging for AWS](https://aws.amazon.com/blogs/aws/resource-groups-and-tagging/) in the *AWS News Blog*.
For information about quotas for Maintenance Windows, a tool in AWS Systems Manager, in addition to those specified in the following examples, see [Systems Manager service quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm) in the *Amazon Web Services General Reference*.
## Example 1: Register multiple targets using node IDs
Run the following command on your local machine format to register multiple nodes as targets using their node IDs. Replace each *example resource placeholder* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--resource-type "INSTANCE" \
--target "Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE"
```
------
#### [ Windows ]
```
aws ssm register-target-with-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE ^
--resource-type "INSTANCE" ^
--target "Key=InstanceIds,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE,i-07782c72faEXAMPLE
```
------
**Recommended use**: Most useful when registering a unique group of nodes with any maintenance window for the first time and they do *not* share a common node tag.
**Quotas:** You can specify up to 50 nodes total for each maintenance window target.
## Example 2: Register targets using resource tags applied to nodes
Run the following command on your local machine to register nodes that are all already tagged with a key-value pair you have assigned. Replace each *example resource placeholder* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--resource-type "INSTANCE" \
--target "Key=tag:Region,Values=East"
```
------
#### [ Windows ]
```
aws ssm register-target-with-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--resource-type "INSTANCE" ^
--target "Key=tag:Region,Values=East"
```
------
**Recommended use**: Most useful when registering a unique group of nodes with any maintenance window for the first time and they *do* share a common node tag.
**Quotas:** You can specify up to five key-value pairs total for each target. If you specify more than one key-value pair, a node must be tagged with *all* the tag keys and values you specify to be included in the target group.
**Note**
You can tag a group of nodes with the tag-key `Patch Group` or `PatchGroup` and assign the nodes a common key value, such as `my-patch-group`. (You must use `PatchGroup`, without a space, if you have [allowed tags in EC2 instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS).) Patch Manager, a tool in Systems Manager, evaluates the `Patch Group` or `PatchGroup` key on nodes to help determine which patch baseline applies to them. If your task will run the `AWS-RunPatchBaseline` SSM document (or the legacy `AWS-ApplyPatchBaseline` SSM document), you can specify the same `Patch Group` or `PatchGroup` key-value pair when you register targets with a maintenance window. For example: `--target "Key=tag:PatchGroup,Values=my-patch-group`. Doing so allows you to use a maintenance window to update patches on a group of nodes that are already associated with the same patch baseline. For more information, see [Patch groups](patch-manager-patch-groups.md).
## Example 3: Register targets using a group of tag keys (without tag values)
Run the following command on your local machine to register nodes that all have one or more tag keys assigned to them, regardless of their key values. Replace each *example resource placeholder* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--resource-type "INSTANCE" \
--target "Key=tag-key,Values=Name,Instance-Type,CostCenter"
```
------
#### [ Windows ]
```
aws ssm register-target-with-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--resource-type "INSTANCE" ^
--target "Key=tag-key,Values=Name,Instance-Type,CostCenter"
```
------
**Recommended use**: Useful when you want to target nodes by specifying multiple tag *keys* (without their values) rather than just one tag-key or a tag key-value pair.
**Quotas:** You can specify up to five tag-keys total for each target. If you specify more than one tag key, a node must be tagged with *all* the tag keys you specify to be included in the target group.
## Example 4: Register targets using a resource group name
Run the following command on your local machine to register a specified resource group, regardless of the type of resources it contains. Replace *mw-0c50858d01EXAMPLE* with your own information. If the tasks you assign to the maintenance window don't act on a type of resource included in this resource group, the system might report an error. Tasks for which a supported resource type is found continue to run despite these errors.
------
#### [ Linux & macOS ]
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--resource-type "RESOURCE_GROUP" \
--target "Key=resource-groups:Name,Values=MyResourceGroup"
```
------
#### [ Windows ]
```
aws ssm register-target-with-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--resource-type "RESOURCE_GROUP" ^
--target "Key=resource-groups:Name,Values=MyResourceGroup"
```
------
**Recommended use**: Useful when you want to quickly specify a resource group as a target without evaluating whether all of its resource types will be targeted by a maintenance window, or when you know that the resource group contains only the resource types that your tasks perform actions on.
**Quotas:** You can specify only one resource group as a target.
## Example 5: Register targets by filtering resource types in a resource group
Run the following command on your local machine to register only certain resource types that belong to a resource group that you specify. Replace *mw-0c50858d01EXAMPLE* with your own information. With this option, even if you add a task for a resource type that belongs to the resource group, the task won’t run if you haven’t explicitly added the resource type to the filter.
------
#### [ Linux & macOS ]
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--resource-type "RESOURCE_GROUP" \
--target "Key=resource-groups:Name,Values=MyResourceGroup" \
"Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::Instance,AWS::ECS::Cluster"
```
------
#### [ Windows ]
```
aws ssm register-target-with-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--resource-type "RESOURCE_GROUP" ^
--target "Key=resource-groups:Name,Values=MyResourceGroup" ^
"Key=resource-groups:ResourceTypeFilters,Values=AWS::EC2::Instance,AWS::ECS::Cluster"
```
------
**Recommended use**: Useful when you want to maintain strict control over the types of AWS resources your maintenance window can run actions on, or when your resource group contains a large number of resource types and you want to avoid unnecessary error reports in your maintenance window logs.
**Quotas:** You can specify only one resource group as a target.
# Step 3: Register a task with the maintenance window using the AWS CLI
In this step of the tutorial, you register an AWS Systems Manager Run Command task that runs the `df` command on your Amazon Elastic Compute Cloud (Amazon EC2) instance for Linux. The results of this standard Linux command show how much space is free and how much is used on the disk file system of your instance.
-or-
If you're targeting an Amazon EC2 instance for Windows Server instead of Linux, replace **df** in the following command with **ipconfig**. Output from this command lists details about the IP address, subnet mask, and default gateway for adapters on the target instance.
When you're ready to register other task types, or use more of the available Systems Manager Run Command options, see [Examples: Register tasks with a maintenance window](mw-cli-register-tasks-examples.md). There, we provide more information about all four task types, and some of their most important options, to help you plan for more extensive real-world scenarios.
**To register a task with a maintenance window**
1. Run the following command on your local machine. Replace each *example resource placeholder* with your own information. The version to run from a local Windows machine includes the escape characters ("/") that you need to run the command from your command line tool.
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id mw-0c50858d01EXAMPLE \
--task-arn "AWS-RunShellScript" \
--max-concurrency 1 --max-errors 1 \
--priority 10 \
--targets "Key=InstanceIds,Values=i-0471e04240EXAMPLE" \
--task-type "RUN_COMMAND" \
--task-invocation-parameters '{"RunCommand":{"Parameters":{"commands":["df"]}}}'
```
------
#### [ Windows ]
```
aws ssm register-task-with-maintenance-window ^
--window-id mw-0c50858d01EXAMPLE ^
--task-arn "AWS-RunShellScript" ^
--max-concurrency 1 --max-errors 1 ^
--priority 10 ^
--targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" ^
--task-type "RUN_COMMAND" ^
--task-invocation-parameters={\"RunCommand\":{\"Parameters\":{\"commands\":[\"df\"]}}}
```
------
The system returns information similar to the following:
```
{
"WindowTaskId": "4f7ca192-7e9a-40fe-9192-5cb15EXAMPLE"
}
```
1. Now run the following command to view details about the maintenance window task you created.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-tasks \
--window-id mw-0c50858d01EXAMPLE
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-tasks ^
--window-id mw-0c50858d01EXAMPLE
```
------
1. The system returns information similar to 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": 10,
"ServiceRoleArn": "arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole",
"MaxConcurrency": "1",
"MaxErrors": "1"
}
]
}
```
1. Wait until the task has had time to run, based on the schedule you specified in [Step 1: Create the maintenance window using the AWS CLI](mw-cli-tutorial-create-mw.md). For example, if you specified **--schedule "rate(5 minutes)"**, wait five minutes. Then run the following command to view information about any executions that occurred for this task.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-executions \
--window-id mw-0c50858d01EXAMPLE
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-executions ^
--window-id mw-0c50858d01EXAMPLE
```
------
The system returns information similar to the following.
```
{
"WindowExecutions": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593493.096,
"EndTime": 1557593498.611
}
]
}
```
**Tip**
After the task runs successfully, you can decrease the rate at which the maintenance window runs. For example, run the following command to decrease the frequency to once a week. Replace *mw-0c50858d01EXAMPLE* with your own information.
```
aws ssm update-maintenance-window \
--window-id mw-0c50858d01EXAMPLE \
--schedule "rate(7 days)"
```
```
aws ssm update-maintenance-window ^
--window-id mw-0c50858d01EXAMPLE ^
--schedule "rate(7 days)"
```
For information about managing maintenance window schedules, see [Reference: Cron and rate expressions for Systems Manager](reference-cron-and-rate-expressions.md) and [Maintenance window scheduling and active period options](maintenance-windows-schedule-options.md).
For information about using the AWS Command Line Interface (AWS CLI) to modify a maintenance window, see [Tutorial: Update a maintenance window using the AWS CLI](maintenance-windows-cli-tutorials-update.md).
For practice running AWS CLI commands to view more details about your maintenance window task and its executions, continue to [Tutorial: View information about tasks and task executions using the AWS CLI](mw-cli-tutorial-task-info.md).
**Accessing tutorial command output**
It's beyond the scope of this tutorial to use the AWS CLI to view the *output* of the Run Command command associated with your maintenance window task executions.
You could view this data, however, using the AWS CLI. (You could also view the output in the Systems Manager console or in a log file stored in an Amazon Simple Storage Service (Amazon S3) bucket, if you had configured the maintenance window to store command output there.) You would find that the output of the **df** command on an EC2 instance for Linux is similar to the following.
```
Filesystem 1K-blocks Used Available Use% Mounted on
devtmpfs 485716 0 485716 0% /dev
tmpfs 503624 0 503624 0% /dev/shm
tmpfs 503624 328 503296 1% /run
tmpfs 503624 0 503624 0% /sys/fs/cgroup
/dev/xvda1 8376300 1464160 6912140 18% /
```
The output of the **ipconfig** command on an EC2 instance for Windows Server is similar to the following:
```
Windows IP Configuration
Ethernet adapter Ethernet 2:
Connection-specific DNS Suffix . : example.com
IPv4 Address. . . . . . . . . . . : 10.24.34.0/23
Subnet Mask . . . . . . . . . . . : 255.255.255.255
Default Gateway . . . . . . . . . : 0.0.0.0
Ethernet adapter Ethernet:
Media State . . . . . . . . . . . : Media disconnected
Connection-specific DNS Suffix . : abc1.wa.example.net
Wireless LAN adapter Local Area Connection* 1:
Media State . . . . . . . . . . . : Media disconnected
Connection-specific DNS Suffix . :
Wireless LAN adapter Wi-Fi:
Connection-specific DNS Suffix . :
Link-local IPv6 Address . . . . . : fe80::100b:c234:66d6:d24f%4
IPv4 Address. . . . . . . . . . . : 192.0.2.0
Subnet Mask . . . . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . . . . : 192.0.2.0
Ethernet adapter Bluetooth Network Connection:
Media State . . . . . . . . . . . : Media disconnected
Connection-specific DNS Suffix . :
```
# Examples: Register tasks with a maintenance window
You can register a task in Run Command, a tool in AWS Systems Manager, with a maintenance window using the AWS Command Line Interface (AWS CLI), as demonstrated in [Register tasks with the maintenance window](mw-cli-tutorial-tasks.md). You can also register tasks for Systems Manager Automation workflows, AWS Lambda functions, and AWS Step Functions tasks, as demonstrated later in this topic.
**Note**
Specify one or more targets for maintenance window Run Command-type tasks. Depending on the task, targets are optional for other maintenance window task types (Automation, AWS Lambda, and AWS Step Functions). For more information about running tasks that don't specify targets, see [Registering maintenance window tasks without targets](maintenance-windows-targetless-tasks.md).
In this topic, we provide examples of using the AWS Command Line Interface (AWS CLI) command `register-task-with-maintenance-window` to register each of the four supported task types with a maintenance window. The examples are for demonstration only, but you can modify them to create working task registration commands.
**Using the --cli-input-json option**
To better manage your task options, you can use the command option `--cli-input-json`, with option values referenced in a JSON file.
To use the sample JSON file content we provide in the following examples, do the following on your local machine:
1. Create a file with a name such as `MyRunCommandTask.json`, `MyAutomationTask.json`, or another name that you prefer.
1. Copy the contents of our JSON sample into the file.
1. Modify the contents of the file for your task registration, and then save the file.
1. In the same directory where you stored the file, run the following command. Substitute your file name for *MyFile.json*.
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--cli-input-json file://MyFile.json
```
------
#### [ Windows ]
```
aws ssm register-task-with-maintenance-window ^
--cli-input-json file://MyFile.json
```
------
**Pseudo parameters in maintenance window tasks**
In some examples, we use *pseudo parameters* as the method to pass ID information to your tasks. For instance, `{{TARGET_ID}}` and `{{RESOURCE_ID}}` can be used to pass IDs of AWS resources to Automation, Lambda, and Step Functions tasks. For more information about pseudo parameters in `--task-invocation-parameters` content, see [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md).
**More info**
+ [Parameter options for the register-task-with-maintenance-windows command](mw-cli-task-options.md).
+ [https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html) in the *AWS CLI Command Reference*
+ [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_RegisterTaskWithMaintenanceWindow.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_RegisterTaskWithMaintenanceWindow.html) in the *AWS Systems Manager API Reference*
## Task registration examples
The following sections provide a sample AWS CLI command for registering a supported task type and a JSON sample that can be used with the `--cli-input-json` option.
### Register a Systems Manager Run Command task
The following examples demonstrate how to register Systems Manager Run Command tasks with a maintenance window using the AWS CLI.
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id mw-0c50858d01EXAMPLE \
--task-arn "AWS-RunShellScript" \
--max-concurrency 1 --max-errors 1 --priority 10 \
--targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" \
--task-type "RUN_COMMAND" \
--task-invocation-parameters '{"RunCommand":{"Parameters":{"commands":["df"]}}}'
```
------
#### [ Windows ]
```
aws ssm register-task-with-maintenance-window ^
--window-id mw-0c50858d01EXAMPLE ^
--task-arn "AWS-RunShellScript" ^
--max-concurrency 1 --max-errors 1 --priority 10 ^
--targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" ^
--task-type "RUN_COMMAND" ^
--task-invocation-parameters "{\"RunCommand\":{\"Parameters\":{\"commands\":[\"df\"]}}}"
```
------
**JSON content to use with `--cli-input-json` file option:**
```
{
"TaskType": "RUN_COMMAND",
"WindowId": "mw-0c50858d01EXAMPLE",
"Description": "My Run Command task to update SSM Agent on an instance",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Name": "My-Run-Command-Task",
"Priority": 10,
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "AWS-UpdateSSMAgent",
"TaskInvocationParameters": {
"RunCommand": {
"Comment": "A TaskInvocationParameters test comment",
"NotificationConfig": {
"NotificationArn": "arn:aws:sns:region:123456789012:my-sns-topic-name",
"NotificationEvents": [
"All"
],
"NotificationType": "Invocation"
},
"OutputS3BucketName": "amzn-s3-demo-bucket",
"OutputS3KeyPrefix": "S3-PREFIX",
"TimeoutSeconds": 3600
}
}
}
```
### Register a Systems Manager Automation task
The following examples demonstrate how to register Systems Manager Automation tasks with a maintenance window using the AWS CLI:
**AWS CLI command:**
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--task-arn "AWS-RestartEC2Instance" \
--service-role-arn arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole \
--task-type AUTOMATION \
--task-invocation-parameters "Automation={DocumentVersion=5,Parameters={InstanceId='{{RESOURCE_ID}}'}}" \
--priority 0 --name "My-Restart-EC2-Instances-Automation-Task" \
--description "Automation task to restart EC2 instances"
```
------
#### [ Windows ]
```
aws ssm register-task-with-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--task-arn "AWS-RestartEC2Instance" ^
--service-role-arn arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole ^
--task-type AUTOMATION ^
--task-invocation-parameters "Automation={DocumentVersion=5,Parameters={InstanceId='{{TARGET_ID}}'}}" ^
--priority 0 --name "My-Restart-EC2-Instances-Automation-Task" ^
--description "Automation task to restart EC2 instances"
```
------
**JSON content to use with `--cli-input-json` file option:**
```
{
"WindowId": "mw-0c50858d01EXAMPLE",
"TaskArn": "AWS-PatchInstanceWithRollback",
"TaskType": "AUTOMATION","TaskInvocationParameters": {
"Automation": {
"DocumentVersion": "1",
"Parameters": {
"instanceId": [
"{{RESOURCE_ID}}"
]
}
}
}
}
```
### Register an AWS Lambda task
The following examples demonstrate how to register Lambda function tasks with a maintenance window using the AWS CLI.
For these examples, the user who created the Lambda function named it `SSMrestart-my-instances` and created two parameters called `instanceId` and `targetType`.
**Important**
The IAM policy for Maintenance Windows requires that you add the prefix `SSM` to Lambda function (or alias) names. Before you proceed to register this type of task, update its name in AWS Lambda to include `SSM`. For example, if your Lambda function name is `MyLambdaFunction`, change it to `SSMMyLambdaFunction`.
**AWS CLI command:**
------
#### [ Linux & macOS ]
**Important**
If you are using version 2 of the AWS CLI, you must include the option `--cli-binary-format raw-in-base64-out` in the following command if your Lambda payload is not base64 encoded. The `cli_binary_format` option is available only in version 2. For information about this and other AWS CLI `config` file settings, see [Supported `config` file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-settings) in the *AWS Command Line Interface User Guide*.
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \
--priority 2 --max-concurrency 10 --max-errors 5 --name "My-Lambda-Example" \
--description "A description for my LAMBDA example task" --task-type "LAMBDA" \
--task-arn "arn:aws:lambda:region:123456789012:function:serverlessrepo-SSMrestart-my-instances-C4JF9EXAMPLE" \
--task-invocation-parameters '{"Lambda":{"Payload":"{\"InstanceId\":\"{{RESOURCE_ID}}\",\"targetType\":\"{{TARGET_TYPE}}\"}","Qualifier": "$LATEST"}}'
```
------
#### [ PowerShell ]
**Important**
If you are using version 2 of the AWS CLI, you must include the option `--cli-binary-format raw-in-base64-out` in the following command if your Lambda payload is not base64 encoded. The `cli_binary_format` option is available only in version 2. For information about this and other AWS CLI `config` file settings, see [Supported `config` file settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-settings) in the *AWS Command Line Interface User Guide*.
```
aws ssm register-task-with-maintenance-window `
--window-id "mw-0c50858d01EXAMPLE" `
--targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" `
--priority 2 --max-concurrency 10 --max-errors 5 --name "My-Lambda-Example" `
--description "A description for my LAMBDA example task" --task-type "LAMBDA" `
--task-arn "arn:aws:lambda:region:123456789012:function:serverlessrepo-SSMrestart-my-instances-C4JF9EXAMPLE" `
--task-invocation-parameters '{\"Lambda\":{\"Payload\":\"{\\\"InstanceId\\\":\\\"{{RESOURCE_ID}}\\\",\\\"targetType\\\":\\\"{{TARGET_TYPE}}\\\"}\",\"Qualifier\": \"$LATEST\"}}'
```
------
**JSON content to use with `--cli-input-json` file option:**
```
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "SSM_RestartMyInstances",
"TaskType": "LAMBDA",
"MaxConcurrency": "10",
"MaxErrors": "10",
"TaskInvocationParameters": {
"Lambda": {
"ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
"Payload": "{ \"instanceId\": \"{{RESOURCE_ID}}\", \"targetType\": \"{{TARGET_TYPE}}\" }",
"Qualifier": "$LATEST"
}
},
"Name": "My-Lambda-Task",
"Description": "A description for my LAMBDA task",
"Priority": 5
}
```
### Register a Step Functions task
The following examples demonstrate how to register Step Functions state machine tasks with a maintenance window using the AWS CLI.
**Note**
Maintenance window tasks support Step Functions Standard state machine workflows only. They don't support Express state machine workflows. For information about state machine workflow types, see [Standard vs. Express Workflows](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-standard-vs-express.html) in the *AWS Step Functions Developer Guide*.
For these examples, the user who created the Step Functions state machine created a state machine named `SSMMyStateMachine` with a parameter called `instanceId`.
**Important**
The AWS Identity and Access Management (IAM) policy for Maintenance Windows requires that you prefix Step Functions state machine names with `SSM`. Before you proceed to register this type of task, you must update its name in AWS Step Functions to include `SSM`. For example, if your state machine name is `MyStateMachine`, change it to `SSMMyStateMachine`.
**AWS CLI command:**
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \
--task-arn arn:aws:states:region:123456789012:stateMachine:SSMMyStateMachine-MggiqEXAMPLE \
--task-type STEP_FUNCTIONS \
--task-invocation-parameters '{"StepFunctions":{"Input":"{\"InstanceId\":\"{{RESOURCE_ID}}\"}", "Name":"{{INVOCATION_ID}}"}}' \
--priority 0 --max-concurrency 10 --max-errors 5 \
--name "My-Step-Functions-Task" --description "A description for my Step Functions task"
```
------
#### [ PowerShell ]
```
aws ssm register-task-with-maintenance-window `
--window-id "mw-0c50858d01EXAMPLE" `
--targets "Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" `
--task-arn arn:aws:states:region:123456789012:stateMachine:SSMMyStateMachine-MggiqEXAMPLE `
--task-type STEP_FUNCTIONS `
--task-invocation-parameters '{\"StepFunctions\":{\"Input\":\"{\\\"InstanceId\\\":\\\"{{RESOURCE_ID}}\\\"}\", \"Name\":\"{{INVOCATION_ID}}\"}}' `
--priority 0 --max-concurrency 10 --max-errors 5 `
--name "My-Step-Functions-Task" --description "A description for my Step Functions task"
```
------
**JSON content to use with `--cli-input-json` file option:**
```
{
"WindowId": "mw-0c50858d01EXAMPLE",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
]
}
],
"TaskArn": "SSM_MyStateMachine",
"TaskType": "STEP_FUNCTIONS",
"MaxConcurrency": "10",
"MaxErrors": "10",
"TaskInvocationParameters": {
"StepFunctions": {
"Input": "{ \"instanceId\": \"{{TARGET_ID}}\" }",
"Name": "{{INVOCATION_ID}}"
}
},
"Name": "My-Step-Functions-Task",
"Description": "A description for my Step Functions task",
"Priority": 5
}
```
# Parameter options for the register-task-with-maintenance-windows command
The **register-task-with-maintenance-window** command provides several options for configuring a task according to your needs. Some are required, some are optional, and some apply to only a single maintenance window task type.
This topic provides information about some of these options to help you work with samples in this tutorial section. For information about all command options, see **[https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html)** in the *AWS CLI Command Reference*.
**Command option: `--task-arn`**
The option `--task-arn` is used to specify the resource that the task operates on. The value that you specify depends on the type of task you're registering, as described in the following table.
**TaskArn formats for maintenance window tasks**
| Maintenance window task type | TaskArn value |
| --- | --- |
| **`RUN_COMMAND`** and ** `AUTOMATION`** | `TaskArn` is the SSM document name or Amazon Resource Name (ARN). For example: `AWS-RunBatchShellScript` -or- `arn:aws:ssm:region:111122223333:document/My-Document`. |
| **`LAMBDA`** | `TaskArn` is the function name or ARN. For example: `SSMMy-Lambda-Function` -or- `arn:aws:lambda:region:111122223333:function:SSMMyLambdaFunction`. The IAM policy for Maintenance Windows requires that you add the prefix `SSM` to Lambda function (or alias) names. Before you proceed to register this type of task, update its name in AWS Lambda to include `SSM`. For example, if your Lambda function name is `MyLambdaFunction`, change it to `SSMMyLambdaFunction`. |
| **`STEP_FUNCTIONS`** | `TaskArn` is the state machine ARN. For example: `arn:aws:states:us-east-2:111122223333:stateMachine:SSMMyStateMachine`. The IAM policy for maintenance windows requires that you prefix Step Functions state machine names with `SSM`. Before you register this type of task, you must update its name in AWS Step Functions to include `SSM`. For example, if your state machine name is `MyStateMachine`, change it to `SSMMyStateMachine`. |
**Command option: `--service-role-arn`**
The role for AWS Systems Manager to assume when running the maintenance window task.
For more information, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md)
**Command option: `--task-invocation-parameters`**
The `--task-invocation-parameters` option is used to specify the parameters that are unique to each of the four task types. The supported parameters for each of the four task types are described in the following table.
**Note**
For information about using pseudo parameters in `--task-invocation-parameters` content, such as \$1\$1TARGET\$1ID\$1\$1, see [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md).
Task invocation parameters options for maintenance window tasks
| Maintenance window task type | Available parameters | Example |
| --- | --- | --- |
| **`RUN_COMMAND`** | `Comment` `DocumentHash` `DocumentHashType` `NotificationConfig` `OutputS3BucketName` `OutPutS3KeyPrefix` `Parameters` `ServiceRoleArn` `TimeoutSeconds` | "TaskInvocationParameters": {
"RunCommand": {
"Comment": "My Run Command task comment",
"DocumentHash": "6554ed3d--truncated--5EXAMPLE",
"DocumentHashType": "Sha256",
"NotificationConfig": {
"NotificationArn": "arn:aws:sns:region:123456789012:my-sns-topic-name",
"NotificationEvents": [
"FAILURE"
],
"NotificationType": "Invocation"
},
"OutputS3BucketName": "amzn-s3-demo-bucket",
"OutputS3KeyPrefix": "S3-PREFIX",
"Parameters": {
"commands": [
"Get-ChildItem$env: temp-Recurse|Remove-Item-Recurse-force"
]
},
"ServiceRoleArn": "arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole",
"TimeoutSeconds": 3600
}
} |
| **`AUTOMATION`** | `DocumentVersion` `Parameters` | "TaskInvocationParameters": {
"Automation": {
"DocumentVersion": "3",
"Parameters": {
"instanceid": [
"{{TARGET_ID}}"
]
}
}
} |
| **`LAMBDA`** | `ClientContext` `Payload` `Qualifier` | "TaskInvocationParameters": {
"Lambda": {
"ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
"Payload": "{ \"targetId\": \"{{TARGET_ID}}\", \"targetType\": \"{{TARGET_TYPE}}\" }",
"Qualifier": "$LATEST"
}
} |
| **`STEP_FUNCTIONS`** | `Input` `Name` | "TaskInvocationParameters": {
"StepFunctions": {
"Input": "{ \"targetId\": \"{{TARGET_ID}}\" }",
"Name": "{{INVOCATION_ID}}"
}
} |
# Tutorial: View information about maintenance windows using the AWS 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 AWS Command Line Interface (AWS CLI), see [Installing, updating, and uninstalling the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).
**Topics**
+ [Examples for 'describe-maintenance-windows'](#mw-cli-tutorials-describe-maintenance-windows)
+ [Examples for 'describe-maintenance-window-targets'](#mw-cli-tutorials-describe-maintenance-window-targets)
+ [Examples for 'describe-maintenance-window-tasks'](#mw-cli-tutorials-describe-maintenance-window-tasks)
+ [Examples for 'describe-maintenance-windows-for-target'](#mw-cli-tutorials-describe-maintenance-windows-for-target)
+ [Examples for 'describe-maintenance-window-executions'](#mw-cli-tutorials-describe-maintenance-window-executions)
+ [Examples for 'describe-maintenance-window-schedule'](#mw-cli-tutorials-describe-maintenance-window-schedule)
## Examples for 'describe-maintenance-windows'
**List all maintenance windows in your AWS account**
Run the following command.
```
aws ssm describe-maintenance-windows
```
The system returns information similar to 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 similar to 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 similar to 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 similar to 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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-targets \
--window-id "mw-6e5c9d4b7cEXAMPLE" \
--filters "Key=OwnerInformation,Values=CostCenter1"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-targets ^
--window-id "mw-6e5c9d4b7cEXAMPLE" ^
--filters "Key=OwnerInformation,Values=CostCenter1"
```
------
**Note**
The supported filter keys are `Type`, `WindowTargetId` and `OwnerInformation`.
The system returns information similar to 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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-tasks \
--window-id "mw-0c50858d01EXAMPLE" \
--filters "Key=TaskArn,Values=AWS-RunPowerShellScript"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-tasks ^
--window-id "mw-0c50858d01EXAMPLE" ^
--filters "Key=TaskArn,Values=AWS-RunPowerShellScript"
```
------
The system returns information similar to the following.
```
{
"Tasks":[
{
"ServiceRoleArn": "arn:aws: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: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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-tasks \
--window-id "mw-9a8b7c6d5eEXAMPLE" \
--filters "Key=Priority,Values=3"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-tasks ^
--window-id "mw-9a8b7c6d5eEXAMPLE" ^
--filters "Key=Priority,Values=3"
```
------
The system returns information similar to the following.
```
{
"Tasks":[
{
"ServiceRoleArn":"arn:aws: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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-tasks \
--window-id "mw-0c50858d01EXAMPLE" \
--filters "Key=Priority,Values=1" "Key=TaskType,Values=RUN_COMMAND"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-tasks ^
--window-id "mw-0c50858d01EXAMPLE" ^
--filters "Key=Priority,Values=1" "Key=TaskType,Values=RUN_COMMAND"
```
------
The system returns information similar to 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: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: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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-windows-for-target \
--resource-type INSTANCE \
--targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" \
--max-results 10
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-windows-for-target ^
--resource-type INSTANCE ^
--targets "Key=InstanceIds,Values=i-02573cafcfEXAMPLE" ^
--max-results 10
```
------
The system returns information similar to 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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-executions \
--window-id "mw-9a8b7c6d5eEXAMPLE" \
--filters "Key=ExecutedBefore,Values=2019-05-12T05:00:00Z"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-executions ^
--window-id "mw-9a8b7c6d5eEXAMPLE" ^
--filters "Key=ExecutedBefore,Values=2019-05-12T05:00:00Z"
```
------
The system returns information similar to 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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-executions \
--window-id "mw-9a8b7c6d5eEXAMPLE" \
--filters "Key=ExecutedAfter,Values=2018-12-31T17:00:00Z"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-executions ^
--window-id "mw-9a8b7c6d5eEXAMPLE" ^
--filters "Key=ExecutedAfter,Values=2018-12-31T17:00:00Z"
```
------
The system returns information similar to 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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-schedule \
--resource-type INSTANCE \
--targets "Key=InstanceIds,Values=i-07782c72faEXAMPLE" \
--max-results 10
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-schedule ^
--resource-type INSTANCE ^
--targets "Key=InstanceIds,Values=i-07782c72faEXAMPLE" ^
--max-results 10
```
------
The system returns information similar to 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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-schedule \
--resource-type INSTANCE \
--targets "Key=tag:prod,Values=rhel7"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-schedule ^
--resource-type INSTANCE ^
--targets "Key=tag:prod,Values=rhel7"
```
------
The system returns information similar to 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.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-schedule \
--window-id "mw-0c50858d01EXAMPLE" \
--max-results "4"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-schedule ^
--window-id "mw-0c50858d01EXAMPLE" ^
--max-results "4"
```
------
The system returns information similar to 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"
}
]
}
]
}
```
# Tutorial: View information about tasks and task executions using the AWS CLI
This tutorial demonstrates how to use the AWS Command Line Interface (AWS CLI) to view details about your completed maintenance window tasks.
If you're continuing directly from [Tutorial: Create and configure a maintenance window using the AWS CLI](maintenance-windows-cli-tutorials-create.md), make sure you have allowed enough time for your maintenance window to run at least once in order to see its execution results.
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 view information about tasks and task executions using the AWS CLI**
1. Run the following command to view a list of task executions for a specific maintenance window.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-executions \
--window-id "mw-0c50858d01EXAMPLE"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-executions ^
--window-id "mw-0c50858d01EXAMPLE"
```
------
The system returns information similar to the following.
```
{
"WindowExecutions": [
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593793.483,
"EndTime": 1557593798.978
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "791b72e0-f0da-4021-8b35-f95dfEXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593493.096,
"EndTime": 1557593498.611
},
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowExecutionId": "ecec60fa-6bb0-4d26-98c7-140308EXAMPLE",
"Status": "SUCCESS",
"StatusDetails": "No tasks to execute.",
"StartTime": 1557593193.309,
"EndTime": 1557593193.334
}
]
}
```
1. Run the following command to get information about a maintenance window task execution.
------
#### [ Linux & macOS ]
```
aws ssm get-maintenance-window-execution \
--window-execution-id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE"
```
------
#### [ Windows ]
```
aws ssm get-maintenance-window-execution ^
--window-execution-id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE"
```
------
The system returns information similar to the following.
```
{
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"TaskIds": [
"c9b05aba-197f-4d8d-be34-e73fbEXAMPLE"
],
"Status": "SUCCESS",
"StartTime": 1557593493.096,
"EndTime": 1557593498.611
}
```
1. Run the following command to list the tasks run as part of a maintenance window execution.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-execution-tasks \
--window-execution-id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-execution-tasks ^
--window-execution-id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE"
```
------
The system returns information similar to the following.
```
{
"WindowExecutionTaskIdentities": [
{
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"TaskExecutionId": "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE",
"Status": "SUCCESS",
"StartTime": 1557593493.162,
"EndTime": 1557593498.57,
"TaskArn": "AWS-RunShellScript",
"TaskType": "RUN_COMMAND"
}
]
}
```
1. Run the following command to get the details of a task execution.
------
#### [ Linux & macOS ]
```
aws ssm get-maintenance-window-execution-task \
--window-execution-id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE" \
--task-id "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE"
```
------
#### [ Windows ]
```
aws ssm get-maintenance-window-execution-task ^
--window-execution-id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE" ^
--task-id "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE"
```
------
The system returns information similar to the following.
```
{
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"TaskExecutionId": "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE",
"TaskArn": "AWS-RunShellScript",
"ServiceRole": "arn:aws:iam::111122223333:role/MyMaintenanceWindowServiceRole",
"Type": "RUN_COMMAND",
"TaskParameters": [
{
"aws:InstanceId": {
"Values": [
"i-02573cafcfEXAMPLE"
]
},
"commands": {
"Values": [
"df"
]
}
}
],
"Priority": 10,
"MaxConcurrency": "1",
"MaxErrors": "1",
"Status": "SUCCESS",
"StartTime": 1557593493.162,
"EndTime": 1557593498.57
}
```
1. Run the following command to get the specific task invocations performed for a task execution.
------
#### [ Linux & macOS ]
```
aws ssm describe-maintenance-window-execution-task-invocations \
--window-execution-id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE" \
--task-id "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE"
```
------
#### [ Windows ]
```
aws ssm describe-maintenance-window-execution-task-invocations ^
--window-execution-id "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE" ^
--task-id "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE"
```
------
The system returns information similar to the following.
```
{
"WindowExecutionTaskInvocationIdentities": [
{
"WindowExecutionId": "14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE",
"TaskExecutionId": "c9b05aba-197f-4d8d-be34-e73fbEXAMPLE",
"InvocationId": "c336d2ab-09de-44ba-8f6a-6136cEXAMPLE",
"ExecutionId": "76a5a04f-caf6-490c-b448-92c02EXAMPLE",
"TaskType": "RUN_COMMAND",
"Parameters": "{\"documentName\":\"AWS-RunShellScript\",\"instanceIds\":[\"i-02573cafcfEXAMPLE\"],\"maxConcurrency\":\"1\",\"maxErrors\":\"1\",\"parameters\":{\"commands\":[\"df\"]}}",
"Status": "SUCCESS",
"StatusDetails": "Success",
"StartTime": 1557593493.222,
"EndTime": 1557593498.466
}
]
}
```
# Tutorial: Update a maintenance window using the AWS CLI
This tutorial demonstrates how to use the AWS Command Line Interface (AWS CLI) to update a maintenance window. It also shows you how to update different task types, including those for AWS Systems Manager Run Command and Automation, AWS Lambda, and AWS Step Functions.
The examples in this section use the following Systems Manager actions for updating a maintenance window:
+ [UpdateMaintenanceWindow](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_UpdateMaintenanceWindow.html)
+ [UpdateMaintenanceWindowTarget](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_UpdateMaintenanceWindowTarget.html)
+ [UpdateMaintenanceWindowTask](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_UpdateMaintenanceWindowTask.html)
+ [DeregisterTargetFromMaintenanceWindow](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DeregisterTargetFromMaintenanceWindow.html)
For information about using the Systems Manager console to update a maintenance window, see [Update or delete maintenance window resources using the console](sysman-maintenance-update.md).
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 using the AWS CLI**
1. Open the AWS CLI and run the following command to update a target to include a name and a description.
------
#### [ Linux & macOS ]
```
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"
```
------
#### [ Windows ]
```
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 similar to 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"
}
```
1. 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 doesn't include the field (a null value). Be sure to specify an additional node that has been configured for use with Systems Manager.
------
#### [ Linux & macOS ]
```
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
```
------
#### [ Windows ]
```
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 similar to the following.
```
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-02573cafcfEXAMPLE",
"i-0471e04240EXAMPLE"
]
}
],
"Name": "My-Maintenance-Window-Target"
}
```
1. 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.
------
#### [ Linux & macOS ]
```
aws ssm update-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--start-date "2020-10-01T10:10:10Z" \
--end-date "2020-11-01T10:10:10Z"
```
------
#### [ Windows ]
```
aws ssm update-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--start-date "2020-10-01T10:10:10Z" ^
--end-date "2020-11-01T10:10:10Z"
```
------
1. Run the following command to update a Run Command task.
**Tip**
If your target is an Amazon Elastic Compute Cloud (Amazon EC2) instance for Windows Server, change `df` to `ipconfig`, and `AWS-RunShellScript` to `AWS-RunPowerShellScript` in the following command.
------
#### [ Linux & macOS ]
```
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::account-id: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"
```
------
#### [ Windows ]
```
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::account-id: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 similar to 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"
}
```
1. Adapt and run the following command to update a Lambda task.
------
#### [ Linux & macOS ]
```
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:region:111122223333:function:SSMTestLambda" \
--service-role-arn "arn:aws:iam:account-id:role/MaintenanceWindowsRole" \
--task-invocation-parameters '{"Lambda":{"Payload":"{\"InstanceId\":\"{{RESOURCE_ID}}\",\"targetType\":\"{{TARGET_TYPE}}\"}"}}' \
--priority 1 --max-concurrency 10 --max-errors 5 \
--name "New-Lambda-Task-Name" \
--description "A description for my Lambda task"
```
------
#### [ Windows ]
```
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 --task-arn "arn:aws:lambda:region:111122223333:function:SSMTestLambda" ^
--service-role-arn "arn:aws:iam:account-id:role/MaintenanceWindowsRole" ^
--task-invocation-parameters '{"Lambda":{"Payload":"{\"InstanceId\":\"{{RESOURCE_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 similar to 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"
}
```
1. If you're updating a Step Functions task, adapt and run the following command to update its task-invocation-parameters.
------
#### [ Linux & macOS ]
```
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:region:execution:SSMStepFunctionTest" \
--service-role-arn "arn:aws:iam:account-id:role/MaintenanceWindowsRole" \
--task-invocation-parameters '{"StepFunctions":{"Input":"{\"InstanceId\":\"{{RESOURCE_ID}}\"}"}}' \
--priority 0 --max-concurrency 10 --max-errors 5 \
--name "My-Step-Functions-Task" \
--description "A description for my Step Functions task"
```
------
#### [ Windows ]
```
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:region:execution:SSMStepFunctionTest" ^
--service-role-arn "arn:aws:iam:account-id:role/MaintenanceWindowsRole" ^
--task-invocation-parameters '{"StepFunctions":{"Input":"{\"InstanceId\":\"{{RESOURCE_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 similar to 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\":\"{{RESOURCE_ID}}\"}"
}
},
"Priority": 0,
"MaxConcurrency": "10",
"MaxErrors": "5",
"Name": "My-Step-Functions-Task",
"Description": "A description for my Step Functions task"
}
```
1. 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.
------
#### [ Linux & macOS ]
```
aws ssm deregister-target-from-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--window-target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \
--safe
```
------
#### [ Windows ]
```
aws ssm deregister-target-from-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--window-target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" ^
--safe
```
------
The system returns information similar to 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
```
1. 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.
------
#### [ Linux & macOS ]
```
aws ssm deregister-target-from-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--window-target-id "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" \
--no-safe
```
------
#### [ Windows ]
```
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 similar to the following.
```
{
"WindowId": "mw-0c50858d01EXAMPLE",
"WindowTargetId": "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE"
}
```
1. Run the following command to update a Run Command task. This example uses a Systems Manager Parameter Store parameter called `UpdateLevel`, which is formatted as follows: '`{{ssm:UpdateLevel}}`'
------
#### [ Linux & macOS ]
```
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}}'}}"
```
------
#### [ Windows ]
```
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 similar to 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/MyMaintenanceWindowServiceRole",
"TaskParameters": {},
"TaskInvocationParameters": {
"RunCommand": {
"Comment": "A comment for my task update",
"Parameters": {
"UpdateLevel": [
"{{ssm:UpdateLevel}}"
]
}
}
},
"Priority": 10,
"MaxConcurrency": "1",
"MaxErrors": "1"
}
```
1. Run the following command to update an Automation task to specify `WINDOW_ID` and `WINDOW_TASK_ID` parameters for the `task-invocation-parameters` parameter:
------
#### [ Linux & macOS ]
```
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:account-id:role/MyMaintenanceWindowServiceRole \
--task-invocation-parameters "Automation={Parameters={InstanceId='{{RESOURCE_ID}}',initiator='{{WINDOW_ID}}.Task-{{WINDOW_TASK_ID}}'}}" \
--priority 3 --max-concurrency 10 --max-errors 5
```
------
#### [ Windows ]
```
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:account-id:role/MyMaintenanceWindowServiceRole ^
--task-invocation-parameters "Automation={Parameters={InstanceId='{{RESOURCE_ID}}',initiator='{{WINDOW_ID}}.Task-{{WINDOW_TASK_ID}}'}}" ^
--priority 3 --max-concurrency 10 --max-errors 5
```
------
The system returns information similar to 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/MyMaintenanceWindowServiceRole",
"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"
}
```
# Tutorial: Delete a maintenance window using the AWS CLI
To delete a maintenance window you created in these tutorials, run the following command.
```
aws ssm delete-maintenance-window --window-id "mw-0c50858d01EXAMPLE"
```
The system returns information similar to the following.
```
{
"WindowId":"mw-0c50858d01EXAMPLE"
}
```
# Tutorial: Create a maintenance window for patching using the console
**Important**
You can continue to use this legacy topic to create a maintenance window for patching. However, we recommend that you use a patch policy instead. For more information, see [Patch policy configurations in Quick Setup](patch-manager-policies.md) and [Configure patching for instances in an organization using a Quick Setup patch policy](quick-setup-patch-manager.md).
To minimize the impact on your server availability, we recommend that you configure a maintenance window to run patching during times that won't interrupt your business operations.
You must configure roles and permissions for Maintenance Windows, a tool in AWS Systems Manager, before beginning this procedure. For more information, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md).
**To create a maintenance window for patching**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Maintenance Windows**.
1. Choose **Create maintenance window**.
1. For **Name**, enter a name that designates this as a maintenance window for patching critical and important updates.
1. (Optional) For **Description**, enter a description.
1. Choose **Allow unregistered targets** if you want to allow a maintenance window task to run on managed nodes, even if you haven't registered those nodes as targets.
If you choose this option, then you can choose the unregistered nodes (by node ID) when you register a task with the maintenance window.
If you don't choose this option, then you must choose previously-registered targets when you register a task with the maintenance window.
1. In the top of the **Schedule** section, specify a schedule for the maintenance window by using one of the three scheduling options.
For information about building cron/rate expressions, see [Reference: Cron and rate expressions for Systems Manager](reference-cron-and-rate-expressions.md).
1. For **Duration**, enter the number of hours the maintenance window will run. The value you specify determines the specific end time for the maintenance window based on the time it begins. No maintenance window tasks are permitted to start after the resulting endtime minus the number of hours you specify for **Stop initiating tasks** in the next step.
For example, if the maintenance window starts at 3 PM, the duration is three hours, and the **Stop initiating tasks** value is one hour, no maintenance window tasks can start after 5 PM.
1. For **Stop initiating tasks**, enter the number of hours before the end of the maintenance window that the system should stop scheduling new tasks to run.
1. (Optional) For **Window start date**, specify a date and time, in ISO-8601 Extended format, for when you want the maintenance window to become active. This allows you to delay activation of the maintenance window until the specified future date.
1. (Optional) For **Window end date**, specify a date and time, in ISO-8601 Extended format, for when you want the maintenance window to become inactive. This allows you to set a date and time in the future after which the maintenance window no longer runs.
1. (Optional) For **Schedule timezone**, specify the time zone to base scheduled maintenance window executions on, in Internet Assigned Numbers Authority (IANA) format. For example: "America/Los\$1Angeles", "etc/UTC", or "Asia/Seoul".
For more information about valid formats, see the [Time Zone Database](https://www.iana.org/time-zones) on the IANA website.
1. (Optional) In the **Manage tags** area, apply one or more tag key name/value pairs to the maintenance window.
Tags are optional metadata that you assign to a resource. Tags allow you to categorize a resource in different ways, such as by purpose, owner, or environment. For example, you might want to tag this maintenance window to identify the type of tasks it runs. In this case, you could specify the following key name/value pair:
+ `Key=TaskType,Value=Patching`
1. Choose **Create maintenance window**.
1. In the maintenance windows list, choose the maintenance window you just created, and then choose **Actions**, **Register targets**.
1. (Optional) In the **Maintenance window target details** section, provide a name, a description, and owner information (your name or alias) for this target.
1. For **Target selection**, choose **Specify instance tags**.
1. For **Specify instance tags**, enter a tag key and a tag value to identify the nodes to register with the maintenance window, and then choose **Add**.
1. Choose **Register target**. The system creates a maintenance window target.
1. In the details page of the maintenance window you created, choose **Actions**, **Register Run command task**.
1. (Optional) For **Maintenance window task details**, provide a name and description for this task.
1. For **Command document**, choose `AWS-RunPatchBaseline`.
1. For **Task priority**, choose a priority. Zero (`0`) is the highest priority.
1. For **Targets**, under **Target by**, choose the maintenance window target you created earlier in this procedure.
1. For **Rate control**:
+ For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time.
**Note**
If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage.
+ For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors.
1. (Optional) For **IAM service role**, choose a role to provide permissions for Systems Manager to assume when running a maintenance window task.
If you don't specify a service role ARN, Systems Manager uses a service-linked role in your account. If no appropriate service-linked role for Systems Manager exists in your account, it's created when the task is registered successfully.
**Note**
For an improved security posture, we strongly recommend creating a custom policy and custom service role for running your maintenance window tasks. The policy can be crafted to provide only the permissions needed for your particular maintenance window tasks. For more information, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md).
1. (Optional) For **Output options**, to save the command output to a file, select the **Enable writing output to S3** box. Enter the bucket and prefix (folder) names in the boxes.
**Note**
The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile assigned to the managed node, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, verify that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket.
To stream the output to an Amazon CloudWatch Logs log group, select the **CloudWatch output** box. Enter the log group name in the box.
1. In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box.
For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md).
1. For **Parameters**:
+ For **Operation**, choose **Scan** to scan for missing patches, or choose **Install** to scan for and install missing patches.
+ You don't need to enter anything in the **Snapshot Id** field. This system automatically generates and provides this parameter.
+ You don't need to enter anything in the **Install Override List** field unless you want Patch Manager to use a different patch set than is specified for the patch baseline. For information, see [Parameter name: `InstallOverrideList`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-installoverridelist).
+ For **RebootOption**, specify whether you want nodes to reboot if patches are installed during the `Install` operation, or if Patch Manager detects other patches that were installed since the last node reboot. For information, see [Parameter name: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption).
+ (Optional) For **Comment**, enter a tracking note or reminder about this command.
+ For **Timeout (seconds)**, enter the number of seconds the system should wait for the operation to finish before it is considered unsuccessful.
1. Choose **Register Run command task**.
After the maintenance window task is complete, you can view patch compliance details in the Systems Manager console in the [Fleet Manager](fleet-manager.md) tool.
You can also view compliance information in the [Patch Manager](patch-manager.md) tool, on the **Compliance reporting** tab.
You can also use the [DescribePatchGroupState](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribePatchGroupState.html) and [DescribeInstancePatchStatesForPatchGroup](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeInstancePatchStatesForPatchGroup.html) APIs to view compliance details. For information about patch compliance data, see [About patch compliance](compliance-about.md#compliance-monitor-patch).
# Patching schedules using maintenance windows
After you configure a patch baseline (and optionally a patch group), you can apply patches to your node by using a maintenance window. A maintenance window can reduce the impact on server availability by letting you specify a time to perform the patching process that doesn't interrupt business operations. A maintenance window works like this:
1. Create a maintenance window with a schedule for your patching operations.
1. Choose the targets for the maintenance window by specifying the `Patch Group` or `PatchGroup` tag for the tag name, and any value for which you have defined Amazon Elastic Compute Cloud (Amazon EC2) tags, for example, "web servers" or "US-EAST-PROD. (You must use `PatchGroup`, without a space, if you have [allowed tags in EC2 instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS).
1. Create a new maintenance window task, and specify the `AWS-RunPatchBaseline` document.
When you configure the task, you can choose to either scan nodes or scan and install patches on the nodes. If you choose to scan nodes, Patch Manager, a tool in AWS Systems Manager, scans each node and generates a list of missing patches for you to review.
If you choose to scan and install patches, Patch Manager scans each node and compares the list of installed patches against the list of approved patches in the baseline. Patch Manager identifies missing patches, and then downloads and installs all missing and approved patches.
If you want to perform a one-time scan or install to fix an issue, you can use Run Command to call the `AWS-RunPatchBaseline` document directly.
**Important**
After installing patches, Systems Manager reboots each node. The reboot is required to make sure that patches are installed correctly and to ensure that the system didn't leave the node in a potentially bad state. (Exception: If the `RebootOption` parameter is set to `NoReboot` in the `AWS-RunPatchBaseline` document, the managed node isn't rebooted after Patch Manager runs. For more information, see [Parameter name: `RebootOption`](patch-manager-aws-runpatchbaseline.md#patch-manager-aws-runpatchbaseline-parameters-norebootoption).)
# Using pseudo parameters when registering maintenance window tasks
When you register a task in Maintenance Windows, a tool in AWS Systems Manager, you specify the parameters that are unique to each of the four task types. (In CLI commands, these are provided using the `--task-invocation-parameters` option.)
You can also reference certain values using *pseudo parameter* syntax, such as `{{RESOURCE_ID}}`, `{{TARGET_TYPE}}`, and `{{WINDOW_TARGET_ID}}`. When the maintenance window task runs, it passes the correct values instead of the pseudo parameter placeholders. The full list of pseudo parameters you can use is provided later in this topic in [Supported pseudo parameters](#pseudo-parameters).
**Important**
For the target type `RESOURCE_GROUP`, depending on the ID format needed for the task, you can choose between using `{{TARGET_ID}}` and `{{RESOURCE_ID}}` to reference the resource when your task runs. `{{TARGET_ID}}` returns the full ARN of the resource. `{{RESOURCE_ID}}` returns only a shorter name or ID of the resource, as shown in these examples.
`{{TARGET_ID}}` format: `arn:aws:ec2:us-east-1:123456789012:instance/i-02573cafcfEXAMPLE`
`{{RESOURCE_ID}}` format: `i-02573cafcfEXAMPLE`
For target type `INSTANCE`, both the `{{TARGET_ID}}` and `{{RESOURCE_ID}}` parameters yield the instance ID only. For more information, see [Supported pseudo parameters](#pseudo-parameters).
`{{TARGET_ID}}` and `{{RESOURCE_ID}}` can be used to pass IDs of AWS resources only to Automation, Lambda, and Step Functions tasks. These two pseudo parameters can't be used with Run Command tasks.
## Pseudo parameter examples
Suppose that your payload for an AWS Lambda task needs to reference an instance by its ID.
Whether you’re using an `INSTANCE` or a `RESOURCE_GROUP` maintenance window target, this can be achieved by using the `{{RESOURCE_ID}}` pseudo parameter. For example:
```
"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestFunction",
"TaskType": "LAMBDA",
"TaskInvocationParameters": {
"Lambda": {
"ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
"Payload": "{ \"instanceId\": \"{{RESOURCE_ID}}\" }",
"Qualifier": "$LATEST"
}
}
```
If your Lambda task is intended to run against another supported target type in addition to Amazon Elastic Compute Cloud (Amazon EC2) instances, such as an Amazon DynamoDB table, the same syntax can be used, and `{{RESOURCE_ID}}` yields the name of the table only. However, if you require the full ARN of the table, use `{{TARGET_ID}}`, as shown in the following example.
```
"TaskArn": "arn:aws:lambda:us-east-2:111122223333:function:SSMTestFunction",
"TaskType": "LAMBDA",
"TaskInvocationParameters": {
"Lambda": {
"ClientContext": "ew0KICAi--truncated--0KIEXAMPLE",
"Payload": "{ \"tableArn\": \"{{TARGET_ID}}\" }",
"Qualifier": "$LATEST"
}
}
```
The same syntax works for targeting instances or other resource types. When multiple resource types have been added to a resource group, the task runs against each of the appropriate resources.
**Important**
Not all resource types that might be included in a resource group yield a value for the `{{RESOURCE_ID}}` parameter. For a list of supported resource types, see [Supported pseudo parameters](#pseudo-parameters).
As another example, to run an Automation task that stops your EC2 instances, you specify the `AWS-StopEC2Instance` Systems Manager document (SSM document) as the `TaskArn` value and use the `{{RESOURCE_ID}}` pseudo parameter:
```
"TaskArn": "AWS-StopEC2Instance",
"TaskType": "AUTOMATION"
"TaskInvocationParameters": {
"Automation": {
"DocumentVersion": "1",
"Parameters": {
"instanceId": [
"{{RESOURCE_ID}}"
]
}
}
}
```
To run an Automation task that copies a snapshot of an Amazon Elastic Block Store (Amazon EBS) volume, you specify the `AWS-CopySnapshot` SSM document as the `TaskArn` value and use the `{{RESOURCE_ID}}` pseudo parameter.
```
"TaskArn": "AWS-CopySnapshot",
"TaskType": "AUTOMATION"
"TaskInvocationParameters": {
"Automation": {
"DocumentVersion": "1",
"Parameters": {
"SourceRegion": "us-east-2",
"targetType":"RESOURCE_GROUP",
"SnapshotId": [
"{{RESOURCE_ID}}"
]
}
}
}
```
## Supported pseudo parameters
The following list describes the pseudo parameters that you can specify using the `{{PSEUDO_PARAMETER}}` syntax in the `--task-invocation-parameters` option.
+ **`WINDOW_ID`**: The ID of the target maintenance window.
+ **`WINDOW_TASK_ID`**: The ID of the window task that is running.
+ **`WINDOW_TARGET_ID`**: The ID of the window target that includes the target (target ID).
+ **`WINDOW_EXECUTION_ID`**: The ID of the current window execution.
+ **`TASK_EXECUTION_ID`**: The ID of the current task execution.
+ **`INVOCATION_ID`**: The ID of the current invocation.
+ **`TARGET_TYPE`**: The type of target. Supported types include `RESOURCE_GROUP` and `INSTANCE`.
+ **`TARGET_ID`**:
If the target type you specify is `INSTANCE`, the `TARGET_ID` pseudo parameter is replaced by the ID of the instance. For example, `i-078a280217EXAMPLE`.
If the target type you specify is `RESOURCE_GROUP`, the value referenced for the task execution is the full ARN of the resource. For example: `arn:aws:ec2:us-east-1:123456789012:instance/i-078a280217EXAMPLE`. The following table provides sample `TARGET_ID` values for particular resource types in a resource group.
**Note**
`TARGET_ID` isn't supported for Run Command tasks.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-window-tasks-pseudo-parameters.html)
+ **`RESOURCE_ID`**: The short ID of a resource type contained in a resource group. The following table provides sample `RESOURCE_ID` values for particular resource types in a resource group.
**Note**
`RESOURCE_ID` isn't supported for Run Command tasks.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-window-tasks-pseudo-parameters.html)
**Note**
If the AWS resource group you specify includes resource types that don't yield a `RESOURCE_ID` value, and aren't listed in the preceding table, then the `RESOURCE_ID` parameter isn't populated. An execution invocation will still occur for that resource. In these cases, use the `TARGET_ID` pseudo parameter instead, which will be replaced with the full ARN of the resource.
# Maintenance window scheduling and active period options
When you create a maintenance window, you must specify how often the maintenance window runs by using a [Cron or rate expression](reference-cron-and-rate-expressions.md). Optionally, you can specify a date range during which the maintenance window can run on its regular schedule and a time zone on which to base that regular schedule.
Be aware, however, that the time zone option and the start date and end date options don't influence each other. Any start date and end date times that you specify (with or without an offset for your time zone) determine only the *valid period* during which the maintenance window can run on its schedule. A time zone option determines the international time zone that the maintenance window schedule is based on *during* its valid period.
**Note**
You specify start and end dates in ISO-8601 timestamp format. For example: `2021-04-07T14:29:00-08:00`
You specify time zones in Internet Assigned Numbers Authority (IANA) format. For example: `America/Chicago`, `Europe/Berlin` or `Asia/Tokyo`
**Topics**
+ [Example 1: Specify a maintenance window start date](#schedule-example-start-date)
+ [Example 2: Specify a maintenance window start date and end date](#schedule-example-start-end-date)
+ [Example 3: Create a maintenance window that runs only once](#schedule-example-one-time)
+ [Example 4: Specify the number of schedule offset days for a maintenance window](#schedule-example-schedule-offset)
## Example 1: Specify a maintenance window start date
Say that you use the AWS Command Line Interface (AWS CLI) to create a maintenance window with the following options:
+ `--start-date 2021-01-01T00:00:00-08:00`
+ `--schedule-timezone "America/Los_Angeles"`
+ `--schedule "cron(0 09 ? * WED *)"`
For example:
------
#### [ Linux & macOS ]
```
aws ssm create-maintenance-window \
--name "My-LAX-Maintenance-Window" \
--allow-unassociated-targets \
--duration 3 \
--cutoff 1 \
--start-date 2021-01-01T00:00:00-08:00 \
--schedule-timezone "America/Los_Angeles" \
--schedule "cron(0 09 ? * WED *)"
```
------
#### [ Windows ]
```
aws ssm create-maintenance-window ^
--name "My-LAX-Maintenance-Window" ^
--allow-unassociated-targets ^
--duration 3 ^
--cutoff 1 ^
--start-date 2021-01-01T00:00:00-08:00 ^
--schedule-timezone "America/Los_Angeles" ^
--schedule "cron(0 09 ? * WED *)"
```
------
This means that the first run of the maintenance window won't occur until *after* its specified start date and time, which is at 12:00 AM US Pacific Time on Friday, January 1, 2021. (This time zone is eight hours behind UTC time.) In this case, the start date and time of the window period don't represent when the maintenance windows first runs. Taken together, the `--schedule-timezone` and `--schedule` values mean that the maintenance window runs at 9 AM every Wednesday in the US Pacific Time Zone (represented by "America/Los Angeles" in IANA format). The first execution in the allowed period will be on Wednesday, January 4, 2021, at 9 AM US Pacific Time.
## Example 2: Specify a maintenance window start date and end date
Suppose that next you create a maintenance window with these options:
+ `--start-date 2019-01-01T00:03:15+09:00`
+ `--end-date 2019-06-30T00:06:15+09:00`
+ `--schedule-timezone "Asia/Tokyo"`
+ `--schedule "rate(7 days)"`
For example:
------
#### [ Linux & macOS ]
```
aws ssm create-maintenance-window \
--name "My-NRT-Maintenance-Window" \
--allow-unassociated-targets \
--duration 3 \
--cutoff 1 \
--start-date 2019-01-01T00:03:15+09:00 \
--end-date 2019-06-30T00:06:15+09:00 \
--schedule-timezone "Asia/Tokyo" \
--schedule "rate(7 days)"
```
------
#### [ Windows ]
```
aws ssm create-maintenance-window ^
--name "My-NRT-Maintenance-Window" ^
--allow-unassociated-targets ^
--duration 3 ^
--cutoff 1 ^
--start-date 2019-01-01T00:03:15+09:00 ^
--end-date 2019-06-30T00:06:15+09:00 ^
--schedule-timezone "Asia/Tokyo" ^
--schedule "rate(7 days)"
```
------
The allowed period for this maintenance window begins at 3:15 AM Japan Standard Time on January 1, 2019. The valid period for this maintenance window ends at 6:15 AM Japan Standard Time on Sunday, June 30, 2019. (This time zone is nine hours ahead of UTC time.) Taken together, the `--schedule-timezone` and `--schedule` values mean that the maintenance window runs at 3:15 AM every Tuesday in the Japan Standard Time Zone (represented by "Asia/Tokyo" in IANA format). This is because the maintenance window runs every seven days, and it becomes active at 3:15 AM on Tuesday, January 1. The last execution is at 3:15 AM Japan Standard Time on Tuesday, June 25, 2019. This is the last Tuesday before the allowed maintenance window period ends five days later.
## Example 3: Create a maintenance window that runs only once
Now you create a maintenance window with this option:
+ `--schedule "at(2020-07-07T15:55:00)"`
For example:
------
#### [ Linux & macOS ]
```
aws ssm create-maintenance-window \
--name "My-One-Time-Maintenance-Window" \
--schedule "at(2020-07-07T15:55:00)" \
--duration 5 \
--cutoff 2 \
--allow-unassociated-targets
```
------
#### [ Windows ]
```
aws ssm create-maintenance-window ^
--name "My-One-Time-Maintenance-Window" ^
--schedule "at(2020-07-07T15:55:00)" ^
--duration 5 ^
--cutoff 2 ^
--allow-unassociated-targets
```
------
This maintenance window runs just once, at 3:55 PM UTC time on July 7, 2020. The maintenance window is allowed to run up to five hours, as needed, but new tasks are prevented from starting two hours before the end of the maintenance window period.
## Example 4: Specify the number of schedule offset days for a maintenance window
Now you create a maintenance window with this option:
```
--schedule-offset 2
```
For example:
------
#### [ Linux & macOS ]
```
aws ssm create-maintenance-window \
--name "My-Cron-Offset-Maintenance-Window" \
--schedule "cron(0 30 23 ? * TUE#3 *)" \
--duration 4 \
--cutoff 1 \
--schedule-offset 2 \
--allow-unassociated-targets
```
------
#### [ Windows ]
```
aws ssm create-maintenance-window ^
--name "My-Cron-Offset-Maintenance-Window" ^
--schedule "cron(0 30 23 ? * TUE#3 *)" ^
--duration 4 ^
--cutoff 1 ^
--schedule-offset 2 ^
--allow-unassociated-targets
```
------
A schedule offset is the number of days to wait after the date and time specified by a CRON expression before running the maintenance window.
In the preceding example, the CRON expression schedules a maintenance window to run the third Tuesday of every month at 11:30 PM:
```
--schedule "cron(0 30 23 ? * TUE#3 *)
```
However, including `--schedule-offset 2` means that the maintenance window won't run until 11:30 PM two days *after* the third Tuesday of each month.
Schedule offsets are supported for CRON expressions only.
**More info**
+ [Reference: Cron and rate expressions for Systems Manager](reference-cron-and-rate-expressions.md)
+ [Create a maintenance window using the console](sysman-maintenance-create-mw.md)
+ [Tutorial: Create and configure a maintenance window using the AWS CLI](maintenance-windows-cli-tutorials-create.md)
+ [CreateMaintenanceWindow](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateMaintenanceWindow.html) in the *AWS Systems Manager API Reference*
+ [https://docs.aws.amazon.com/cli/latest/reference/ssm/create-maintenance-window.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/create-maintenance-window.html) in the *AWS Systems Manager section of the AWS CLI Command Reference*
+ [Time Zone Database](https://www.iana.org/time-zones) on the IANA website
# Registering maintenance window tasks without targets
For each maintenance window you create, you can specify one or more tasks to perform when the maintenance window runs. In most cases, you must specify the resources, or targets, that the task is to run on. In some cases, however, you don't need to specify targets explicitly in the task.
One or more targets must be specified for maintenance window Systems Manager Run Command-type tasks. Depending on the nature of the task, targets are optional for other maintenance window task types (Systems Manager Automation, AWS Lambda, and AWS Step Functions).
For Lambda and Step Functions task types, whether a target is required depends on the content of the function or state machine you have created.
**Note**
When a task has registered targets, Automation, AWS Lambda, and AWS Step Functions tasks resolve the targets from resource groups and tags and send one invocation per resolved resource, which results in multiple task invocations. But say, for example, that you want only one invocation for a Lambda task that's registered with a resource group containing more than one instance. In this case, if you are working in the AWS Management Console, choose the option **Task target not required** in the **Register Lambda task** or **Edit Lambda task** page. If you are using the AWS CLI command, do not specify targets using the `--targets` parameter when running the [https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html) command or [https://docs.aws.amazon.com/cli/latest/reference/ssm/update-maintenance-window-task.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/update-maintenance-window-task.html) command.
In many cases, you don't need to explicitly specify a target for an automation task. For example, say that you're creating an Automation-type task to update an Amazon Machine Image (AMI) for Linux using the `AWS-UpdateLinuxAmi` runbook. When the task runs, the AMI is updated with the latest available Linux distribution packages and Amazon software. New instances created from the AMI already have these updates installed. Because the ID of the AMI to be updated is specified in the input parameters for the runbook, there is no need to specify a target again in the maintenance window task.
Similarly, suppose you're using the AWS Command Line Interface (AWS CLI) to register a maintenance window Automation task that uses the `AWS-RestartEC2Instance` runbook. Because the node to restart is specified in the `--task-invocation-parameters` argument, you don't need to also specify a `--targets` option.
**Note**
For maintenance window tasks without a target specified, you can't supply values for `--max-errors` and `--max-concurrency`. Instead, the system inserts a placeholder value of `1`, which might be reported in the response to commands such as [https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-maintenance-window-tasks.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/describe-maintenance-window-tasks.html) and [https://docs.aws.amazon.com/cli/latest/reference/ssm/get-maintenance-window-task.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/get-maintenance-window-task.html). These values don't affect the running of your task and can be ignored.
The following example demonstrates omitting the `--targets`, `--max-errors`, and `--max-concurrency` options for a targetless maintenance window task.
------
#### [ Linux & macOS ]
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-ab12cd34eEXAMPLE" \
--service-role-arn "arn:aws:iam::123456789012:role/MaintenanceWindowAndAutomationRole" \
--task-type "AUTOMATION" \
--name "RestartInstanceWithoutTarget" \
--task-arn "AWS-RestartEC2Instance" \
--task-invocation-parameters "{\"Automation\":{\"Parameters\":{\"InstanceId\":[\"i-02573cafcfEXAMPLE\"]}}}" \
--priority 10
```
------
#### [ Windows ]
```
aws ssm register-task-with-maintenance-window ^
--window-id "mw-ab12cd34eEXAMPLE" ^
--service-role-arn "arn:aws:iam::123456789012:role/MaintenanceWindowAndAutomationRole" ^
--task-type "AUTOMATION" ^
--name "RestartInstanceWithoutTarget" ^
--task-arn "AWS-RestartEC2Instance" ^
--task-invocation-parameters "{\"Automation\":{\"Parameters\":{\"InstanceId\":[\"i-02573cafcfEXAMPLE\"]}}}" ^
--priority 10
```
------
**Note**
For maintenance window tasks registered before December 23, 2020: If you specified targets for the task and one is no longer required, you can update that task to remove the targets using the Systems Manager console or the [https://docs.aws.amazon.com/cli/latest/reference/ssm/update-maintenance-window-task.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/update-maintenance-window-task.html) AWS CLI command.
**More info**
+ [Error messages: "Maintenance window tasks without targets don't support MaxConcurrency values" and "Maintenance window tasks without targets don't support MaxErrors values"](troubleshooting-maintenance-windows.md#maxconcurrency-maxerrors-not-supported)
# Troubleshooting maintenance windows
Use the following information to help you troubleshoot problems with maintenance windows.
**Topics**
+ [Edit task error: On the page for editing a maintenance window task, the IAM role list returns an error message: "We couldn't find the IAM maintenance window role specified for this task. It might have been deleted, or it might not have been created yet."](#maintenance-window-role-troubleshooting)
+ [Not all maintenance window targets are updated](#targets-not-updated)
+ [Task fails with task invocation status: "The provided role does not contain the correct SSM permissions."](#incorrect-ssm-permissions)
+ [Task fails with error message: "Step fails when it is validating and resolving the step inputs"](#step-fails)
+ [Error messages: "Maintenance window tasks without targets don't support MaxConcurrency values" and "Maintenance window tasks without targets don't support MaxErrors values"](#maxconcurrency-maxerrors-not-supported)
## Edit task error: On the page for editing a maintenance window task, the IAM role list returns an error message: "We couldn't find the IAM maintenance window role specified for this task. It might have been deleted, or it might not have been created yet."
**Problem 1**: The AWS Identity and Access Management (IAM) maintenance window role you originally specified was deleted after you created the task.
**Possible fix**: 1) Select a different IAM maintenance window role, if one exists in your account, or create a new one and select it for the task.
**Problem 2**: If the task was created using the AWS Command Line Interface (AWS CLI), AWS Tools for Windows PowerShell, or an AWS SDK, a non-existent IAM maintenance window role name could have been specified. For example, the IAM maintenance window role could have been deleted before you created the task, or the role name could have been typed incorrectly, such as **myrole** instead of **my-role**.
**Possible fix**: Select the correct name of the IAM maintenance window role you want to use, or create a new one to specify for the task.
## Not all maintenance window targets are updated
**Problem:** You notice that maintenance window tasks didn't run on all the resources targeted by your maintenance window. For example, in the maintenance window run results, the task for that resource is marked as failed or timed out.
**Solution:** The most common reasons for a maintenance window task not running on a target resource involve connectivity and availability. For example:
+ Systems Manager lost connection to the resource before or during the maintenance window operation.
+ The resource was offline or stopped during the maintenance window operation.
You can wait for the next scheduled maintenance window time to run tasks on the resources. You can manually run the maintenance window tasks on the resources that weren't available or were offline.
## Task fails with task invocation status: "The provided role does not contain the correct SSM permissions."
**Problem**: You have specified a maintenance window service role for a task, but the task fails to run successfully and the task invocation status reports that "The provided role does not contain the correct SSM permissions."
+ **Solution**: In [Task 1: Create a custom policy for your maintenance window service role using the console](configuring-maintenance-window-permissions-console.md#create-custom-policy-console), we provide a basic policy you can attach to your [custom maintenance window service role](configuring-maintenance-window-permissions-console.md#create-custom-role-console). The policy includes the permissions needed for many task scenarios. However, due to the wide variety of tasks you can run, you might need to provide additional permissions in the policy for your maintenance window role.
For example, some Automation actions work with AWS CloudFormation stacks. Therefore, you might need to add the additional permissions `cloudformation:CreateStack`, `cloudformation:DescribeStacks`, and `cloudformation:DeleteStack` to the policy for your maintenance window service role.
For another example, the Automation runbook `AWS-CopySnapshot` requires permissions to create an Amazon Elastic Block Store (Amazon EBS) snapshot. Therefore, you might need to add the permission `ec2:CreateSnapshot`.
For information about the role permissions needed by an AWS managed Automation runbook, see the runbook descriptions in the [AWS Systems Manager Automation Runbook Reference](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-runbook-reference.html).
For information about the role permissions needed by an AWS managed SSM document, review the content of the document in the [Documents](https://console.aws.amazon.com//systems-manager/documents) section Systems Manager console.
For information about the role permissions needed for Step Functions tasks, Lambda tasks, and custom Automation runbooks and SSM documents, verify permission requirements with the author of those resources.
## Task fails with error message: "Step fails when it is validating and resolving the step inputs"
**Problem**: An Automation runbook or Systems Manager Command document you're using in a task requires that you specify inputs such as `InstanceId` or `SnapshotId`, but a value isn't supplied or isn't supplied correctly.
+ **Solution 1**: If your task is targeting a single resource, such as a single node or single snapshot, enter its ID in the input parameters for the task.
+ **Solution 2**: If your task is targeting multiple resources, such as creating images from multiple nodes when you use the runbook `AWS-CreateImage`, you can use one of the pseudo parameters supported for maintenance window tasks in the input parameters to represent node IDs in the command.
The following commands register a Systems Manager Automation task with a maintenance window using the AWS CLI. The `--targets` value indicates a maintenance window target ID. Also, even though the `--targets` parameter specifies a window target ID, parameters of the Automation runbook require that a node ID be provided. In this case, the command uses the pseudo parameter `{{RESOURCE_ID}}` as the `InstanceId` value.
**AWS CLI command:**
------
#### [ Linux & macOS ]
The following example command restarts Amazon Elastic Compute Cloud (Amazon EC2) instances that belong to the maintenance window target group with the ID e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE.
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--targets Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE \
--task-arn "AWS-RestartEC2Instance" \
--service-role-arn arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole \
--task-type AUTOMATION \
--task-invocation-parameters "Automation={DocumentVersion=5,Parameters={InstanceId='{{RESOURCE_ID}}'}}" \
--priority 0 --max-concurrency 10 --max-errors 5 --name "My-Restart-EC2-Instances-Automation-Task" \
--description "Automation task to restart EC2 instances"
```
------
#### [ Windows ]
```
aws ssm register-task-with-maintenance-window ^
--window-id "mw-0c50858d01EXAMPLE" ^
--targets Key=WindowTargetIds,Values=e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE ^
--task-arn "AWS-RestartEC2Instance" ^
--service-role-arn arn:aws:iam::123456789012:role/MyMaintenanceWindowServiceRole ^
--task-type AUTOMATION ^
--task-invocation-parameters "Automation={DocumentVersion=5,Parameters={InstanceId='{{RESOURCE_ID}}'}}" ^
--priority 0 --max-concurrency 10 --max-errors 5 --name "My-Restart-EC2-Instances-Automation-Task" ^
--description "Automation task to restart EC2 instances"
```
------
For more information about working with pseudo parameters for maintenance window tasks, see [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md) and [Task registration examples](mw-cli-register-tasks-examples.md#task-examples).
## Error messages: "Maintenance window tasks without targets don't support MaxConcurrency values" and "Maintenance window tasks without targets don't support MaxErrors values"
**Problem:** When you register a Run Command-type task, you must specify at least one target for the task to run on. For other task types (Automation, AWS Lambda, and AWS Step Functions), depending on the nature of the task, targets are optional. The options `MaxConcurrency` (the number of resources to run a task on at the same time) and `MaxErrors` (the number of failures to run the task on target resources before the task fails) aren't required or supported for maintenance window tasks that don't specify targets. The system generates these error messages if values are specified for either of these options when no task target is specified.
**Solution**: If you receive either of these errors, remove the values for concurrency and error threshold before continuing to register or update the maintenance window task.
For more information about running tasks that don't specify targets, see [Registering maintenance window tasks without targets](maintenance-windows-targetless-tasks.md) in the *AWS Systems Manager User Guide*.