• 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). # 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}}"
        }
    }
|