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" : { "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: 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
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 task-level logs to.
Note LoggingInfo
has been deprecated. To specify an S3 bucket to contain logs, instead use theOutputS3BucketName
andOutputS3KeyPrefix
options in theTaskInvocationParameters
structure. For information about how Systems Manager handles these options for the supported maintenance window task types, see AWS Systems Manager MaintenanceWindowTask TaskInvocationParameters.Required: No
Type: LoggingInfo
Update requires: No interruption
MaxConcurrency
-
The maximum number of targets this task can be run for, in parallel.
Required: No
Type: String
Minimum:
1
Maximum:
7
Pattern:
^([1-9][0-9]*|[1-9][0-9]%|[1-9]%|100%)$
Update requires: No interruption
MaxErrors
-
The maximum number of errors allowed before this task stops being scheduled.
Required: No
Type: String
Minimum:
1
Maximum:
7
Pattern:
^([1-9][0-9]*|[0]|[1-9][0-9]%|[0-9]%|100%)$
Update requires: No interruption
Name
-
The task name.
Required: No
Type: String
Minimum:
3
Maximum:
128
Pattern:
^[a-zA-Z0-9_\-.]{3,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 ARN of the IAM service role to use to publish Amazon Simple Notification Service (Amazon SNS) notifications for maintenance window Run Command tasks.
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: List of Target
Maximum:
5
Update requires: No interruption
-
TaskArn
-
The resource that the task uses during execution.
For
RUN_COMMAND
andAUTOMATION
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 theTaskInvocationParameters
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 specifiedTaskInvocationParameters
values forComment
,NotificationConfig
, andOutputS3BucketName
. If you update the maintenance window task and specify only a differentOutputS3BucketName
value, the values forComment
andNotificationConfig
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 theParameters
option in theTaskInvocationParameters
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:
AUTOMATION | LAMBDA | RUN_COMMAND | STEP_FUNCTIONS
Update requires: Replacement
WindowId
-
The ID of the maintenance window where the task is registered.
Required: Yes
Type: String
Minimum:
20
Maximum:
20
Pattern:
^mw-[0-9a-f]{17}$
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.
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", "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 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: Comment: Running security updates for OS with no reboot Parameters: Operation: - Install RebootOption: - NoReboot MaxConcurrency: 7 MaxErrors: 100% 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": "MaintenanceWindow", "Targets": [ { "Key": "WindowTargetIds", "Values": [ "MaintenanceWindowTarget" ] } ], "TaskType": "RUN_COMMAND", "TaskArn": "AWS-RunPowerShellScript", "TaskInvocationParameters": { "MaintenanceWindowRunCommandParameters": { "Comment": "This is a comment", "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: MaintenanceWindow Targets: - Key: WindowTargetIds Values: - MaintenanceWindowTarget TaskType: RUN_COMMAND TaskArn: AWS-RunPowerShellScript TaskInvocationParameters: MaintenanceWindowRunCommandParameters: Comment: This is a comment. Parameters: executionTimeout: - '3600' commands: |- Get-Service myImportantService | Restart-Service Get-ExecutionPolicy -List Set-ExecutionPolicy -Scope Process AllSigned Priority: 1 MaxConcurrency: 5 MaxErrors: 5 Name: StepFunctionsTask 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 a Lambda function
The following example runs a Lambda function to restart instances.
JSON
{ "Resources": { "MaintenanceWindowStepFunctionsTask": { "Type": "AWS::SSM::MaintenanceWindowTask", "Properties": { "WindowId": "MaintenanceWindow", "Targets": [ { "Key": "WindowTargetIds", "Values": [ "MaintenanceWindowTarget" ] } ], "TaskArn": "SSM_RestartMyInstances", "ServiceRoleArn": "Lambda.Arn", "TaskType": "LAMBDA", "TaskInvocationParameters": { "MaintenanceWindowLambdaParameters": { "ClientContext": "ew0KICAi--truncated--0KIEXAMPLE", "Qualifier": "$LATEST", "Payload": "{ \"instanceId\": \"{{RESOURCE_ID}}\", \"targetType\": \"{{TARGET_TYPE}}\" }" } } }, "Priority": 1, "MaxConcurrency": 5, "MaxErrors": 5, "Name": "LambdaTask" }, "DependsOn": "MaintenanceWindowTarget" } }
YAML
--- Resources: MaintenanceWindowAutomationTask: Type: AWS::SSM::MaintenanceWindowTask Properties: WindowId: MaintenanceWindow Targets: - Key: WindowTargetIds Values: - MaintenanceWindowTarget TaskArn: SSM_RestartMyInstances ServiceRoleArn: Lambda.Arn TaskType: LAMBDA TaskInvocationParameters: MaintenanceWindowAutomationParameters: ClientContext": "ew0KICAi--truncated--0KIEXAMPLE" Qualifier: '$LATEST' Payload: '{ \"instanceId\": \"{{RESOURCE_ID}}\", \"targetType\": \"{{TARGET_TYPE}}\" }' Priority: 1 MaxConcurrency: 5 MaxErrors: 5 Name: LambdaTask DependsOn: MaintenanceWindowTarget
See also
-
RegisterTaskWithMaintenanceWindow in the AWS Systems Manager API Reference.