Syntax Properties Return values Examples See also

AWS::SSM::MaintenanceWindowTask

The AWS::SSM::MaintenanceWindowTask resource defines information about a task for an AWS Systems Manager maintenance window. For more information, see RegisterTaskWithMaintenanceWindow in the AWS Systems Manager API Reference.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::SSM::MaintenanceWindowTask",
  "Properties" : {
      "CutoffBehavior" : String,
      "Description" : String,
      "LoggingInfo" : LoggingInfo,
      "MaxConcurrency" : String,
      "MaxErrors" : String,
      "Name" : String,
      "Priority" : Integer,
      "ServiceRoleArn" : String,
      "Targets" : [ Target, ... ],
      "TaskArn" : String,
      "TaskInvocationParameters" : TaskInvocationParameters,
      "TaskParameters" : Json,
      "TaskType" : String,
      "WindowId" : String
    }
}

YAML


Type: AWS::SSM::MaintenanceWindowTask
Properties:
  CutoffBehavior: String
  Description: String
  LoggingInfo: 
    LoggingInfo
  MaxConcurrency: String
  MaxErrors: String
  Name: String
  Priority: Integer
  ServiceRoleArn: String
  Targets: 
    - Target
  TaskArn: String
  TaskInvocationParameters: 
    TaskInvocationParameters
  TaskParameters: Json
  TaskType: String
  WindowId: String

Properties

CutoffBehavior

The specification for whether tasks should continue to run after the cutoff time specified in the maintenance windows is reached.

Required: No

Type: String

Allowed values: CONTINUE_TASK | CANCEL_TASK

Update requires: No interruption

Description

A description of the task.

Required: No

Type: String

Minimum: 1

Maximum: 128

Update requires: No interruption

LoggingInfo

Information about an Amazon S3 bucket to write Run Command task-level logs to.

Note

LoggingInfo has been deprecated. To specify an Amazon S3 bucket to contain logs for Run Command tasks, instead use the OutputS3BucketName and OutputS3KeyPrefix options in the TaskInvocationParameters structure. For information about how Systems Manager handles these options for the supported maintenance window task types, see AWS::SSM::MaintenanceWindowTask MaintenanceWindowRunCommandParameters.

Required: No

Type: LoggingInfo

Update requires: No interruption

MaxConcurrency

The maximum number of targets this task can be run for, in parallel.

Note

Although this element is listed as "Required: No", a value can be omitted only when you are registering or updating a targetless task You must provide a value in all other cases.

For maintenance window tasks without a target specified, you can't supply a value for this option. Instead, the system inserts a placeholder value of 1. This value doesn't affect the running of your task.

Required: No

Type: String

Pattern: ^([1-9][0-9]*|[1-9][0-9]%|[1-9]%|100%)$

Minimum: 1

Maximum: 7

Update requires: No interruption

MaxErrors

The maximum number of errors allowed before this task stops being scheduled.

Note

Although this element is listed as "Required: No", a value can be omitted only when you are registering or updating a targetless task You must provide a value in all other cases.

Required: No

Type: String

Pattern: ^([1-9][0-9]*|[0]|[1-9][0-9]%|[0-9]%|100%)$

Minimum: 1

Maximum: 7

Update requires: No interruption

Name

The task name.

Required: No

Type: String

Pattern: ^[a-zA-Z0-9_\-.]{3,128}$

Minimum: 3

Maximum: 128

Update requires: No interruption

Priority

The priority of the task in the maintenance window. The lower the number, the higher the priority. Tasks that have the same priority are scheduled in parallel.

Required: Yes

Type: Integer

Minimum: 0

Update requires: No interruption

ServiceRoleArn

The Amazon Resource Name (ARN) of the IAM service role for AWS Systems Manager to assume when running a maintenance window task. If you do not 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 is created when you run RegisterTaskWithMaintenanceWindow.

However, 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 in the in the AWS Systems Manager User Guide.

Required: No

Type: String

Update requires: No interruption

Targets

The targets, either instances or window target IDs.

Specify instances using Key=InstanceIds,Values=instanceid1,instanceid2.
Specify window target IDs using Key=WindowTargetIds,Values=window-target-id-1,window-target-id-2.

Required: No

Type: Array of Target

Minimum: 0

Maximum: 5

Update requires: No interruption

TaskArn

The resource that the task uses during execution.

For RUN_COMMAND and AUTOMATION task types, TaskArn is the SSM document name or Amazon Resource Name (ARN).

For LAMBDA tasks, TaskArn is the function name or ARN.

For STEP_FUNCTIONS tasks, TaskArn is the state machine ARN.

Required: Yes

Type: String

Minimum: 1

Maximum: 1600

Update requires: No interruption

TaskInvocationParameters

The parameters to pass to the task when it runs. Populate only the fields that match the task type. All other fields should be empty.

Important

When you update a maintenance window task that has options specified in TaskInvocationParameters, you must provide again all the TaskInvocationParameters values that you want to retain. The values you do not specify again are removed. For example, suppose that when you registered a Run Command task, you specified TaskInvocationParameters values for Comment, NotificationConfig, and OutputS3BucketName. If you update the maintenance window task and specify only a different OutputS3BucketName value, the values for Comment and NotificationConfig are removed.

Required: No

Type: TaskInvocationParameters

Update requires: No interruption

TaskParameters

The parameters to pass to the task when it runs.

Note

TaskParameters has been deprecated. To specify parameters to pass to a task when it runs, instead use the Parameters option in the TaskInvocationParameters structure. For information about how Systems Manager handles these options for the supported maintenance window task types, see MaintenanceWindowTaskInvocationParameters.

Required: No

Type: Json

Update requires: No interruption

TaskType

The type of task. Valid values: RUN_COMMAND, AUTOMATION, LAMBDA, STEP_FUNCTIONS.

Required: Yes

Type: String

Allowed values: RUN_COMMAND | AUTOMATION | STEP_FUNCTIONS | LAMBDA

Update requires: Replacement

WindowId

The ID of the maintenance window where the task is registered.

Required: Yes

Type: String

Pattern: ^mw-[0-9a-f]{17}$

Minimum: 20

Maximum: 20

Update requires: Replacement

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the maintenance window task ID, such as 12a345b6-bbb7-4bb6-90b0-8c9577a2d2b9.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Examples

Create a Run Command task that targets instances using a resource group name
Create a Run Command task that targets instances using a maintenance window target ID
Create a Run Command task that runs a PowerShell script
Create a task that runs an Automation runbook
Create a Step Functions task that targets a maintenance window target ID
Create a Step Functions task that targets an instance ID
Create a task that runs an AWS Lambda function

Create a Run Command task that targets instances using a resource group name

The following example creates a maintenance window Run Command task that installs patches on instances using a using a resource group name as the target.

JSON


{
    "Resources": {
        "PatchTask": {
            "Type": "AWS::SSM::MaintenanceWindowTask",
            "Properties": {
                "Description": "Apply OS patches on instances in target",
                "MaxConcurrency": 1,
                "MaxErrors": 1,
                "Priority": 0,
                "TaskType": "RUN_COMMAND",
                "WindowId": {
                    "Ref": "MaintenanceWindow"
                },
                "TaskArn": "AWS-RunPatchBaseline",
                "TaskInvocationParameters": {
                    "MaintenanceWindowRunCommandParameters": {
                        "Parameters": {
                            "Operation": [
                                "Install"
                            ],
                            "RebootOption": [
                                "NoReboot"
                            ]
                        }
                    }
                },
                "Targets": [
                    {
                        "Key": "WindowTargetIds",
                        "Values": [
                            {
                                "Ref": "MaintenanceWindowTarget"
                            }
                        ]
                    }
                ]
            }
        },
        "MaintenanceWindow": {
            "Type": "AWS::SSM::MaintenanceWindow",
            "Properties": {
                "Name": "MaintenanceWindow",
                "AllowUnassociatedTargets": true,
                "Cutoff": 0,
                "Description": "Maintenance window for instances",
                "Duration": 1,
                "Schedule": "cron(20 17 ? * MON-FRI *)"
            }
        },
        "MaintenanceWindowTarget": {
            "Type": "AWS::SSM::MaintenanceWindowTarget",
            "Properties": {
                "ResourceType": "RESOURCE_GROUP",
                "Targets": [
                    {
                        "Key": "resource-groups:Name",
                        "Values": [
                            "TestResourceGroup"
                        ]
                    }
                ],
                "WindowId": {
                    "Ref": "MaintenanceWindow"
                }
            }
        }
    }
}

YAML


---
Resources:
  PatchTask:
    Type: AWS::SSM::MaintenanceWindowTask
    Properties:
      Description: Apply OS patches on instances in target
      MaxConcurrency: 1
      MaxErrors: 1
      Priority: 0
      TaskType: RUN_COMMAND
      WindowId:
        Ref: MaintenanceWindow
      TaskArn: AWS-RunPatchBaseline
      TaskInvocationParameters:
        MaintenanceWindowRunCommandParameters:
          Parameters:
            Operation:
            - Install
            RebootOption:
            - NoReboot
      Targets:
      - Key: WindowTargetIds
        Values:
        - Ref: MaintenanceWindowTarget
  MaintenanceWindow:
    Type: AWS::SSM::MaintenanceWindow
    Properties:
      Name: MaintenanceWindow
      AllowUnassociatedTargets: true
      Cutoff: 0
      Description: Maintenance window for instances
      Duration: 1
      Schedule: cron(20 17 ? * MON-FRI *)
  MaintenanceWindowTarget:
    Type: AWS::SSM::MaintenanceWindowTarget
    Properties:
      ResourceType: RESOURCE_GROUP
      Targets:
      - Key: resource-groups:Name
        Values:
        - TestResourceGroup
      WindowId:
        Ref: MaintenanceWindow

Create a Run Command task that targets instances using a maintenance window target ID

The following example creates a maintenance window Run Command task that installs patches on instances but does not reboot them. The maintenance window task targets managed instances using a maintenance window target ID.

JSON


{
    "Resources": {
        "MaintenanceWindowRunCommandTask": {
            "Type": "AWS::SSM::MaintenanceWindowTask",
            "Properties": {
                "WindowId": "MaintenanceWindow",
                "Targets": [
                    {
                        "Key": "WindowTargetIds",
                        "Values": [
                            "MaintenanceWindowTarget"
                        ]
                    }
                ],
                "TaskType": "RUN_COMMAND",
                "TaskArn": "AWS-RunPatchBaseline",
                "TaskInvocationParameters": {
                    "MaintenanceWindowRunCommandParameters": {
                        "Parameters": {
                            "Operation": [
                                "Install"
                            ],
                            "RebootOption": [
                                "NoReboot"
                            ]
                        }
                    },
                    "MaxConcurrency": 7,
                    "MaxErrors": 7,
                    "Priority": 5
                },
                "DependsOn": "MaintenanceWindowTarget"
            }
        }
    }
}

YAML


---
Resources:
  MaintenanceWindowRunCommandTask:
    Type: AWS::SSM::MaintenanceWindowTask
    Properties:
      WindowId: MaintenanceWindow
      Targets:
      - Key: WindowTargetIds
        Values:
        - MaintenanceWindowTarget
      TaskType: RUN_COMMAND
      TaskArn: AWS-RunPatchBaseline
      TaskInvocationParameters:
        MaintenanceWindowRunCommandParameters:
          Parameters:
            Operation:
            - Install
            RebootOption:
            - NoReboot
      MaxConcurrency: 7
      MaxErrors: 7
      Priority: 5
      DependsOn: MaintenanceWindowTarget

Create a Run Command task that runs a PowerShell script

The following example demonstrates running a command with AWS-RunPowerShellScript.

JSON


{
    "Resources": {
        "MaintenanceWindowRunCommandTask": {
            "Type": "AWS::SSM::MaintenanceWindowTask",
            "Properties": {
                "WindowId": {
                    "Ref": "MaintenanceWindow"
                },
                "Targets": [
                    {
                        "Key": "WindowTargetIds",
                        "Values": [
                            "MaintenanceWindowTarget"
                        ]
                    }
                ],
                "TaskType": "RUN_COMMAND",
                "TaskArn": "AWS-RunPowerShellScript",
                "TaskInvocationParameters": {
                    "MaintenanceWindowRunCommandParameters": {
                        "Comment": "This is a comment",
                        "CloudWatchOutputConfig": {
                            "CloudWatchLogGroupName": "MyLogGroupName",
                            "CloudWatchOutputEnabled": true
                        },
                        "Parameters": {
                            "executionTimeout": [
                                "3600"
                            ],
                            "commands": [
                                "Get-Service myImportantService | Restart-Service\nGet-ExecutionPolicy -List\nSet-ExecutionPolicy -Scope Process AllSigned\n"
                            ]
                        }
                    }
                },
                "MaxConcurrency": 7,
                "MaxErrors": 7,
                "Priority": 5
            },
            "DependsOn": "MaintenanceWindowTarget"
        }
    }
}

YAML


---
Resources:
  MaintenanceWindowRunCommandTask:
    Type: 'AWS::SSM::MaintenanceWindowTask'
    Properties:
      WindowId: !Ref MaintenanceWindow
      Targets:
        - Key: WindowTargetIds
          Values:
            - MaintenanceWindowTarget
      TaskType: RUN_COMMAND
      TaskArn: AWS-RunPowerShellScript
      TaskInvocationParameters:
        MaintenanceWindowRunCommandParameters:
          Comment: This is a comment
          CloudWatchOutputConfig:
            CloudWatchLogGroupName: MyLogGroupName
            CloudWatchOutputEnabled: true
          Parameters:
            executionTimeout:
              - '3600'
            commands:
              - Get-Service myImportantService | Restart-Service
              - Get-ExecutionPolicy -List
              - Set-ExecutionPolicy -Scope Process AllSigned
      MaxConcurrency: 7
      MaxErrors: 7
      Priority: 5
    DependsOn: MaintenanceWindowTarget

Create a task that runs an Automation runbook

The following example creates a Systems Manager maintenance window task that uses the runbook AWS-PatchInstanceWithRollback to patch instances.

JSON


{
    "Resources": {
        "MaintenanceWindowStepFunctionsTask": {
            "Type": "AWS::SSM::MaintenanceWindowTask",
            "Properties": {
                "WindowId": "MaintenanceWindow",
                "Targets": [
                    {
                        "Key": "WindowTargetIds",
                        "Values": [
                            "MaintenanceWindowTarget"
                        ]
                    }
                ],
                "TaskArn": "AWS-PatchInstanceWithRollback",
                "ServiceRoleArn": "arn:aws:iam::111222333444:role/MyMaintenanceWindowServiceRole",
                "TaskType": "AUTOMATION",
                "TaskInvocationParameters": {
                    "MaintenanceWindowAutomationParameters": {
                        "DocumentVersion": "1",
                        "Parameters": {
                            "InstanceId": [
                                "{{RESOURCE_ID}}"
                            ]
                        }
                    }
                },
                "Priority": 1,
                "MaxConcurrency": 5,
                "MaxErrors": 5,
                "Name": "AutomationTask"
            },
            "DependsOn": "MaintenanceWindowTarget"
        }
    }
}

YAML


---
Resources:
  MaintenanceWindowStepFunctionsTask:
    Type: AWS::SSM::MaintenanceWindowTask
    Properties:
      WindowId: MaintenanceWindow
      Targets:
      - Key: WindowTargetIds
        Values:
        - MaintenanceWindowTarget
      TaskArn: AWS-PatchInstanceWithRollback
      ServiceRoleArn: arn:aws:iam::111222333444:role/MyMaintenanceWindowServiceRole
      TaskType: AUTOMATION
      TaskInvocationParameters:
        MaintenanceWindowAutomationParameters:
          DocumentVersion: 1
          Parameters:
            InstanceId:
              - '{{RESOURCE_ID}}'
      Priority: 1
      MaxConcurrency: 5
      MaxErrors: 5
      Name: AutomationTask
    DependsOn: MaintenanceWindowTarget

Create a Step Functions task that targets a maintenance window target ID

The following example creates a Systems Manager maintenance window task that runs the specified Step Function. The maintenance window task targets managed instances using a maintenance window target ID.

JSON


{
    "Resources": {
        "MaintenanceWindowStepFunctionsTask": {
            "Type": "AWS::SSM::MaintenanceWindowTask",
            "Properties": {
                "WindowId": "MaintenanceWindow",
                "Targets": [
                    {
                        "Key": "WindowTargetIds",
                        "Values": [
                            "MaintenanceWindowTarget"
                        ]
                    }
                ],
                "TaskArn": "SSMStepFunctionDemo",
                "ServiceRoleArn": "StepFunctionRole.Arn",
                "TaskType": "STEP_FUNCTIONS",
                "TaskInvocationParameters": {
                    "MaintenanceWindowStepFunctionsParameters": {
                        "Input": "{\"instanceId\":\"{{TARGET_ID}}\", \"wait_time\": 20}",
                        "Name": "{{INVOCATION_ID}}"
                    }
                },
                "Priority": 1,
                "MaxConcurrency": 5,
                "MaxErrors": 5,
                "Name": "StepFunctionsTask"
            },
            "DependsOn": "MaintenanceWindowTarget"
        }
    }
}

YAML


---
Resources:
  MaintenanceWindowStepFunctionsTask:
    Type: AWS::SSM::MaintenanceWindowTask
    Properties:
      WindowId: MaintenanceWindow
      Targets:
      - Key: WindowTargetIds
        Values:
        - MaintenanceWindowTarget
      TaskArn: SSMStepFunctionDemo
      ServiceRoleArn: StepFunctionRole.Arn
      TaskType: STEP_FUNCTIONS
      TaskInvocationParameters:
        MaintenanceWindowStepFunctionsParameters:
          Input: '{"instanceId":"{{TARGET_ID}}", "wait_time": 20}'
          Name: "{{INVOCATION_ID}}"
      Priority: 1
      MaxConcurrency: 5
      MaxErrors: 5
      Name: StepFunctionsTask
   DependsOn: MaintenanceWindowTarget

Create a Step Functions task that targets an instance ID

The following example creates a Systems Manager maintenance window task that runs the specified Step Function. The maintenance window task targets the specified instance IDs.

JSON


{
    "Resources": {
        "StepFunctionsTask": {
            "Type": "AWS::SSM::MaintenanceWindowTask",
            "Properties": {
                "WindowId": "MaintenanceWindow",
                "Targets": [
                    {
                        "Key": "InstanceIds",
                        "Values": [
                            "i-012345678912345678"
                        ]
                    }
                ],
                "TaskArn": "SSMStepFunctionDemo",
                "ServiceRoleArn": "StepFunctionRole.Arn",
                "TaskType": "STEP_FUNCTIONS",
                "TaskInvocationParameters": {
                    "MaintenanceWindowStepFunctionsParameters": {
                        "Input": "{\"instanceId\":\"{{TARGET_ID}}\", \"wait_time\": 20}",
                        "Name": "{{INVOCATION_ID}}"
                    }
                },
                "Priority": 1,
                "MaxConcurrency": 5,
                "MaxErrors": 5,
                "Name": "StepFunctionsTask"
            },
            "DependsOn": "MaintenanceWindowTarget"
        }
    }
}

YAML


---
Resources:
  StepFunctionsTask:
    Type: 'AWS::SSM::MaintenanceWindowTask'
    Properties:
      WindowId: MaintenanceWindow
      Targets:
      - Key: InstanceIds
        Values:
        - i-012345678912345678
      TaskArn: SSMStepFunctionDemo
      ServiceRoleArn: StepFunctionRole.Arn
      TaskType: STEP_FUNCTIONS
      TaskInvocationParameters:
        MaintenanceWindowStepFunctionsParameters:
          Input: '{"instanceId":"{{TARGET_ID}}", "wait_time": 20}'
          Name: "{{INVOCATION_ID}}"
      Priority: 1
      MaxConcurrency: 5
      MaxErrors: 5
      Name: StepFunctionsTask
    DependsOn: MaintenanceWindowTarget

Create a task that runs an AWS Lambda function

The following example runs an AWS Lambda function to restart instances.

Note

The value for Payload in MaintenanceWindowLambdaParameters must be formatted as a Base64-encoded binary data object.

JSON


{
   "Resources": {
      "LambdaTask": {
         "Type": "AWS::SSM::MaintenanceWindowTask",
         "Properties": {
            "WindowId": "mw-04fd6f19dfEXAMPLE",
            "TaskArn": "arn:aws:lambda:us-east-2:111222333444:function:MyLambdaTaskArn",
            "ServiceRoleArn": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
            "TaskType": "LAMBDA",
            "TaskInvocationParameters": {
               "MaintenanceWindowLambdaParameters": {
                  "ClientContext": "eyJ0ZXN0Q29udGV4dCI6Ik5vdGhp==trucated==EXAMPLE",
                  "Qualifier": "$LATEST",
                  "Payload": "eyJJbnN0YW5jZUlkIjoie3tSRVNPVVJDRV9JRH19IiwidGFyZ2V0VHlwZSI6Int7VEFSR0VUX1RZUEV9fSJ9"
               }
            },
            "Priority": 1,
            "Name": "UpdateLambdaTaskEXAMPLE"
         }
      }
   }
}

YAML


---
Resources:
  LambdaTask:
    Type: 'AWS::SSM::MaintenanceWindowTask'
    Properties:
      WindowId: mw-04fd6f19dfEXAMPLE
      TaskArn: >-
        arn:aws:lambda:us-east-2:111222333444:function:MyLambdaTaskArn
      ServiceRoleArn: >-
        arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM
      TaskType: LAMBDA
      TaskInvocationParameters:
        MaintenanceWindowLambdaParameters:
          ClientContext: eyJ0ZXN0Q29udGV4dCI6Ik5vdGhp==trucated==EXAMPLE
          Qualifier: $LATEST
          Payload: >-
            eyJJbnN0YW5jZUlkIjoie3tSRVNPVVJDRV9JRH19IiwidGFyZ2V0VHlwZSI6Int7VEFSR0VUX1RZUEV9fSJ9
      Priority: 1
      Name: UpdateLambdaTaskEXAMPLE