AWS::SSM::MaintenanceWindowTask - AWS CloudFormation

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.

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]*|[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

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": "AutomationRole.Arn", "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: AutomationRole.Arn 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

See also