About register-task-with-maintenance-windows options - Amazon Systems Manager
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

About register-task-with-maintenance-windows options

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 register-task-with-maintenance-window in the Amazon CLI Command Reference.

About the --task-arn option

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-cn:ssm:region:111122223333:document/My-Document.

LAMBDA

TaskArn is the function name or ARN. For example:

SSMMy-Lambda-Function

-or-

arn:aws-cn:lambda:region:111122223333:function:SSMMyLambdaFunction.

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 Amazon 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.

Important

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 Amazon Step Functions to include SSM. For example, if your state machine name is MyStateMachine, change it to SSMMyStateMachine.
About the --service-role-arn option

The role for Amazon Systems Manager to assume when running the maintenance window task.

For more information, see Setting up Maintenance Windows

About the --task-invocation-parameters option

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 {{TARGET_ID}}, see Using pseudo parameters when registering maintenance window tasks.

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-cn:sns:region:123456789012:my-sns-topic-name",
                "NotificationEvents": [
                    "FAILURE"
                ],
                "NotificationType": "Invocation"
            },
            "OutputS3BucketName": "DOC-EXAMPLE-BUCKET",
            "OutputS3KeyPrefix": "DOC-EXAMPLE-FOLDER",
            "Parameters": {
                "commands": [
                    "Get-ChildItem$env: temp-Recurse|Remove-Item-Recurse-force"
                ]
            },
            "ServiceRoleArn": "arn:aws-cn: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}}"
        }
    }