範例:向維護時段註冊任務 - AWS Systems Manager

範例:向維護時段註冊任務

您可以在 Run Command (AWS Systems Manager 的一項功能) 中使用 AWS Command Line Interface (AWS CLI) 註冊一項任務以及維護時段,如註冊任務及維護時段中所示。您也可以依照本主題稍後的示範,為 Systems Manager Automation 工作流程、AWS Lambda 函數和 AWS Step Functions 任務註冊任務。

注意

為維護時段 Run Command 類型任務指定一或多個目標。視任務而定,對於其他維護時段任務類型 (Automation、AWS Lambda 和 AWS Step Functions),目標是選用的。如需有關執行未指定目標之任務的詳細資訊,請參閱 註冊不含目標的維護時段任務

在這個主題中,我們提供的範例是使用 AWS Command Line Interface (AWS CLI) 命令 register-task-with-maintenance-window 來向維護時段註冊四種支援任務。此範例僅用於示範,但您可以進行修改來建立可運作的任務註冊命令。

使用 --cli-input-json 選項

為了更有效地管理您的任務選項,您可以使用命令選項 --cli-input-json,內含 JSON 檔案中參考的選項值。

若要使用我們在以下範例中提供的範本 JSON 檔案內容,請在您的本機機器上執行下列動作:

  1. 建立包含 MyRunCommandTask.jsonMyAutomationTask.json 這類名稱或您偏好的另一個名稱來建立檔案。

  2. 將我們的 JSON 範本內容複製到此檔案中。

  3. 將檔案內容修改為任務註冊適用的內容,然後儲存檔案。

  4. 在您存放該檔案的相同目錄中執行下列命令。替換 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

有關虛擬參數

在某些範例中,我們使用虛擬參數做為將 ID 資訊傳遞到任務的方法。例如,{{TARGET_ID}}{{RESOURCE_ID}} 可以用來將 AWS 資源的 ID 傳遞給 Automation、Lambda 和 Step Functions 任務。如需 --task-invocation-parameters 內容中虛擬參數的詳細資訊,請參閱有關虛擬參數

其他資訊

如需一些基本 register-task-with-maintenance-window 選項的詳細資訊,請參閱 關於 register-task-with-maintenance-windows 選項

如需命令選項的完整詳細資訊,請參閱下列主題:

任務註冊範例

下列區段提供的範本 AWS CLI 命令可用來註冊可與 --cli-input-json 選項搭配使用的支援任務類型和 JSON 範本。

以下範例示範如何使用 AWS CLI 向維護時段註冊 Systems Manager Run Command 任務。

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\"]}}}"

要與 --cli-input-json 檔案選項搭配使用的 JSON 內容:

{ "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:us-east-2:123456789012:my-sns-topic-name", "NotificationEvents": [ "All" ], "NotificationType": "Invocation" }, "OutputS3BucketName": "DOC-EXAMPLE-BUCKET", "OutputS3KeyPrefix": "DOC-EXAMPLE-FOLDER", "TimeoutSeconds": 3600 } } }

以下範例示範如何使用 AWS CLI 向維護時段註冊 Systems Manager Automation 任務:

AWS CLI 命令

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"

要與 --cli-input-json 檔案選項搭配使用的 JSON 內容:

{ "WindowId": "mw-0c50858d01EXAMPLE", "TaskArn": "AWS-PatchInstanceWithRollback", "TaskType": "AUTOMATION","TaskInvocationParameters": { "Automation": { "DocumentVersion": "1", "Parameters": { "instanceId": [ "{{RESOURCE_ID}}" ] } } } }

以下範例示範如何使用 AWS CLI 向維護時段註冊 Lambda 函數任務。

對於這些範例,建立 Lambda 函數的使用者會將其命名為 SSMrestart-my-instances 並建立名為 instanceIdtargetType 的兩個參數。

重要

適用於 Maintenance Windows 的 IAM 政策需要您為 Lambda 函數 (或別名) 名稱新增 SSM 字首。在繼續註冊這類任務前,請在 AWS Lambda 中將其名稱更新為包含 SSM。例如,如果 Lambda 函數名稱為 MyLambdaFunction,請變更為 SSMMyLambdaFunction

AWS CLI 命令

Linux & macOS
重要

如果您使用的是 AWS CLI 版本 2,則您必須在以下命令中包含 --cli-binary-format raw-in-base64-out (如果您的 Lambda 酬載不是 base64 編碼的)。cli_binary_format 選項僅在版本 2 中可用。如需有關此類別和其他 AWS CLI config 檔案設定的資訊,請參閱《AWS Command Line Interface 使用者指南》中的受支援 config 檔案設定

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:us-east-2:123456789012:function:serverlessrepo-SSMrestart-my-instances-C4JF9EXAMPLE" \ --task-invocation-parameters '{"Lambda":{"Payload":"{\"InstanceId\":\"{{RESOURCE_ID}}\",\"targetType\":\"{{TARGET_TYPE}}\"}","Qualifier": "$LATEST"}}'
PowerShell
重要

如果您使用的是 AWS CLI 版本 2,則您必須在以下命令中包含 --cli-binary-format raw-in-base64-out (如果您的 Lambda 酬載不是 base64 編碼的)。cli_binary_format 選項僅在版本 2 中可用。如需有關此類別和其他 AWS CLI config 檔案設定的資訊,請參閱《AWS Command Line Interface 使用者指南》中的受支援 config 檔案設定

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:us-east-2:123456789012:function:serverlessrepo-SSMrestart-my-instances-C4JF9EXAMPLE" ` --task-invocation-parameters '{\"Lambda\":{\"Payload\":\"{\\\"InstanceId\\\":\\\"{{RESOURCE_ID}}\\\",\\\"targetType\\\":\\\"{{TARGET_TYPE}}\\\"}\",\"Qualifier\": \"$LATEST\"}}'

要與 --cli-input-json 檔案選項搭配使用的 JSON 內容:

{ "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 }

以下範例示範如何使用 AWS CLI 向維護時段註冊 Step Functions 狀態機器任務。

對於這些範例,建立步驟函數狀態機器的使用者會使用名為 instanceId 的參數建立名為 SSMMyStateMachine 的狀態機器。

重要

適用於 Maintenance Windows 的 AWS Identity and Access Management (IAM) 政策需要您為 Step Functions 狀態機器名稱加上 SSM 字首。在繼續註冊這類任務前,您必須在 AWS Step Functions 中將其名稱更新為包含 SSM。例如,如果狀態機器名稱為 MyStateMachine,請變更為 SSMMyStateMachine

AWS CLI 命令

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:us-east-2: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:us-east-2: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"

要與 --cli-input-json 檔案選項搭配使用的 JSON 內容:

{ "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 }