ターゲットとレート制御を使用するオートメーションの実行 - AWS Systems Manager
ターゲットとレート制御を使用してオートメーションを実行する (コンソール)ターゲットとレート制御を使用してオートメーションを実行する (コマンドライン)

ターゲットとレート制御を使用するオートメーションの実行

AWS Systems Manager オートメーションを使用すると、ターゲットを使用して AWS リソースのフリートで自動化処理を実行できます。さらに、同時実行値とエラーのしきい値を指定することで、フリート全体のオートメーションのデプロイを制御することができます。同時実行値は、オートメーションを同時に実行できるリソースの数を決定します。オートメーションには、オプトインできる適応同時実行モードも用意されています。適応同時実行では、同時実行される自動化処理数のクオータが、100 個から最大 500 個まで自動的にスケーリングされます。エラーのしきい値は、Systems Manager がオートメーションの他のリソースへの送信を停止するまでの、オートメーションの失敗の許容量を決定します。同時実行数とエラーのしきい値機能は、まとめてレート制御と呼ばれます。

同時実行とエラーしきい値の詳細については、「同時実行数とエラーのしきい値について」を参照してください。ターゲットの詳細については、「ターゲットについて」を参照してください。

以下の手順で、Systems Manager コンソールおよび AWS Command Line Interface (AWS CLI) を使用して、適応同時実行を有効化する方法、ならびに、ターゲットおよびレート制御を使用したオートメーションの実行方法について説明します。

ターゲットとレート制御を使用してオートメーションを実行する (コンソール)

次の手順では、Systems Manager コンソールを使用してターゲットおよびレート制御により、シンプルなオートメーションを実行する方法を説明します。

ターゲットとレート制御を使用してオートメーションを実行するには

  1. AWS Systems Manager コンソール (https://console.aws.amazon.com/systems-manager/) を開きます。

  2. ナビゲーションペインで、[オートメーション]、[オートメーションの実行] の順に選択します。

  3. [Automation document (自動化ドキュメント)] リストで、ランブックを選択します。[Document categories (ドキュメントカテゴリ)] ペインで 1 つ以上のオプションを選択して、目的に応じて SSM ドキュメントをフィルタリングします。自分が所有するランブックを表示するには、[Owned by me (自分が所有)] タブを選択します。自分のアカウントと共有されているランブックを表示するには、[Shared with me (共有ファイル)] タブを選択します。すべてのランブックを表示するには、[すべてのドキュメント] タブを選択します。

    注記

    ランブックの名前を選択すると、ランブックに関する情報を表示できます。

  4. [Document details (ドキュメントの詳細)] セクションで、[Document version (ドキュメントのバージョン)] が実行するバージョンに設定されていることを確認します。システムには、次のバージョンのオプションが含まれています。

    • [Default version at runtime (ランタイムのデフォルトバージョン)]: 自動化ランブックが定期的に更新され、新しいデフォルトバージョンが割り当てられている場合は、このオプションを選択します。

    • [Latest version at runtime (ランタイムの最新バージョン)]: 自動化ランブックが定期的に更新され、直前に更新されたバージョンを実行する場合は、このオプションを選択します。

    • [Default (デフォルト)]: ドキュメントの最初のバージョンを実行するには、このオプションを選択します。これはデフォルト設定です。

  5. [Next] を選択します。

  6. [Execution Mode (実行モード)] セクションで [Rate Control (レート制御)] を選択します。ターゲットとレート制御を使用する場合は、このモードまたは [Multi-account and Region (マルチアカウントとリージョン)] を使用する必要があります。

  7. [Targets (ターゲット)] セクションで、オートメーションを実行する AWS リソースをどのようにターゲットにするかを選択します。これらのオプションは必須です。

    1. [Parameter (パラメータ)] リストを使用してパラメータを選択します。[Parameter (パラメータ)] リストの項目は、この手順の開始時に選択した自動化ドキュメントのランブックによって決まります。パラメータを選択して、自動化ワークフローが実行されるリソースの種類を定義します。

    2. [Targets (ターゲット)] リストを使用して、リソースをターゲットにする方法を選択します。

      1. パラメータ値を使用してターゲットリソースを選択した場合は、[Input parameters (パラメータの入力)] セクションで選択したパラメータのパラメータ値を入力します。

      2. AWS Resource Groups を使用してターゲットリソースを選択した場合、[Resource Group (リソースグループ)] リストからグループの名前を選択します。

      3. タグを使用してターゲットリソースを選択した場合は、タグキーと (オプションとして) タグ値をフィールドに入力します。[Add] (追加) をクリックします。

      4. 現在の AWS アカウント および AWS リージョン にあるすべてのインスタンスでオートメーションランブックを実行する場合、[All instances (すべてのインスタンス)] を選択します。

  8. [Input parameters (入力パラメータ)] セクションで、必要な入力を指定します。必要に応じて、[AutomationAssumeRole] リストから IAM サービスロールを選択できます。

    注記

    [Input parameters (入力パラメータ)] セクションでオプションを選択する必要はありません。これは、タグまたはリソースグループを使用してリソースをターゲットとしたためです。例えば、AWS-RestartEC2Instance ランブックを選択した場合、[Input parameters (入力パラメータ)] セクションでインスタンス ID を指定または選択する必要はありません。オートメーションの実行では、指定したタグまたはリソースグループを使用してインスタンスを再起動します。

  9. [Rate control (レート制御)] セクションのオプションを使用して、各アカウントとリージョンのペア内でオートメーションを実行できる AWS リソースの数を制限します。

    [Concurrency (同時実行数)] セクションでオプションを選択します。

    • [targets (ターゲット)] を選択して、自動化ワークフローを同時に実行できるターゲットの絶対数を入力します。

    • [percentage (パーセント値)] を選択して、自動化ワークフローを同時に実行できるターゲットセットのパーセント値を入力します。

  10. [Error threshold (エラーのしきい値)] セクションでオプションを選択します。

    • [errors (エラー)] を選択して、自動化が他のリソースへのワークフローの送信を停止するまでに許容されるエラーの絶対数を入力します。

    • [percentage (パーセント値)] を選択して、自動化が他のリソースへのワークフローの送信を停止するまでに許容されるエラーのパーセント値を入力します。

  11. [Execute] を選択します。

レート制御のオートメーションによって開始されたオートメーションを表示するには、ナビゲーションペインで [オートメーション] を選択し、[Show child automations (子オートメーションを表示)] を選択します。

ターゲットとレート制御を使用してオートメーションを実行する (コマンドライン)

次の手順では、AWS CLI (Linux または Windows) または AWS Tools for PowerShell を使用して、ターゲットとレート制御でオートメーションを実行する方法を説明します。

ターゲットとレート制御を使用してオートメーションを実行するには

  1. まだ AWS CLI または AWS Tools for PowerShell をインストールして設定していない場合は、インストールして設定します。

    詳細については、「AWS コマンドラインツールのインストールまたはアップグレード」を参照してください。

  2. ドキュメントのリストを表示するには、次のコマンドを実行します。

    Linux & macOS
    aws ssm list-documents
    Windows
    aws ssm list-documents
    PowerShell
    Get-SSMDocumentList

    使用するランブックの名前を書き留めます。

  3. 以下のコマンドを実行して、ランブックの詳細を表示します。InstanceId オプションに使用するパラメータ名 (例: --target-parameter-name) を書き留めます。このパラメータは、オートメーションが実行されるリソースのタイプを決定します。

    Linux & macOS
    aws ssm describe-document \
    --name runbook_name
    Windows
    aws ssm describe-document ^
    --name runbook_name
    PowerShell
    Get-SSMDocumentDescription `
    -Name runbook_name

  4. 実行するターゲットとレート制御オプションを使用するコマンドを作成します。便利なテンプレートコマンドを次に示します。

    タグを使用したターゲット設定

    Linux & macOS
    aws ssm start-automation-execution \
    --document-name runbook_name \
    --targets Key=tag:key_name,Values=value \
    --target-parameter-name parameter_name \
    --parameters "input_parameter_name1=input_parameter_value1,input_parameter_name2=input_parameter_value2" \
    --max-concurrency 10 \
    --max-errors 25%
    Windows
    aws ssm start-automation-execution ^
    --document-name runbook_name ^
    --targets Key=tag:key_name,Values=value ^
    --target-parameter-name parameter_name ^
    --parameters "input_parameter_name1=input_parameter_value1,input_parameter_name2=input_parameter_value2" ^
    --max-concurrency 10 ^
    --max-errors 25%
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "tag:key_name"
$Targets.Values = "value"

Start-SSMAutomationExecution `
    DocumentName "RunbookName" `
    -Targets $Targets `
    -TargetParameterName "Parameter_Name" `
    -Parameter @{"input_parameter_name1"="input_parameter_value1";"input_parameter_name2"="input_parameter_value2"} `
    -MaxConcurrency "a_number_of_instances_or_a_percentage_of_target_set" `
    -MaxError "a_number_of_errors_or_a_percentage_of_target_set"

    パラメータ値を使用したターゲット設定

    Linux & macOS
    aws ssm start-automation-execution \
    --document-name runbook_name \
    --targets Key=ParameterValues,Values=value_1,value_2,value_3 \
    --target-parameter-name parameter_name \
    --parameters "input_parameter_name1=input_parameter_value1" \
    --max-concurrency 10 \
    --max-errors 25%
    Windows
    aws ssm start-automation-execution ^
    --document-name runbook_name ^
    --targets Key=ParameterValues,Values=value_1,value_2,value_3 ^
    --target-parameter-name parameter_name ^
    --parameters "input_parameter_name1=input_parameter_value1" ^
    --max-concurrency 10 ^
    --max-errors 25%
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ParameterValues"
$Targets.Values = "value_1","value_2","value_3"

Start-SSMAutomationExecution `
    -DocumentName "RunbookName" `
    -Targets $Targets `
    -TargetParameterName "Parameter_Name" `
    -Parameter @{"input_parameter_name1"="input_parameter_value1"} `
    -MaxConcurrency "a_number_of_instances_or_a_percentage_of_target_set" `
    -MaxError "a_number_of_errors_or_a_percentage_of_target_set"

    AWS Resource Groups を使用したターゲット設定

    Linux & macOS
    aws ssm start-automation-execution \
    --document-name runbook_name \
    --targets Key=ResourceGroup,Values=Resource_Group_name \
    --target-parameter-name parameter_name \
    --parameters "input_parameter_name1=input_parameter_value1,input_parameter_name2=input_parameter_value2" \
    --max-concurrency 10 \
    --max-errors 25%
    Windows
    aws ssm start-automation-execution ^
    --document-name runbook_name ^
    --targets Key=ResourceGroup,Values=Resource_Group_name ^
    --target-parameter-name parameter_name ^
    --parameters "input_parameter_name1=input_parameter_value1,input_parameter_name2=input_parameter_value2" ^
    --max-concurrency 10 ^
    --max-errors 25%
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "Resource_Group_Name"

Start-SSMAutomationExecution `
    -DocumentName "RunbookName" `
    -Targets $Targets `
    -TargetParameterName "Parameter_Name" `
    -Parameter @{"input_parameter_name1"="input_parameter_value1";"input_parameter_name2"="input_parameter_value2"} `
    -MaxConcurrency "a_number_of_instances_or_a_percentage_of_target_set" `
    -MaxError "a_number_of_errors_or_a_percentage_of_target_set"

    現在の AWS アカウント と AWS リージョン で、すべてのインスタンスをターゲットに設定

    Linux & macOS
    aws ssm start-automation-execution \
    --document-name runbook_name \
    --targets "Key=AWS::EC2::Instance,Values=*"  \
    --target-parameter-name instanceId \
    --parameters "input_parameter_name1=input_parameter_value1" \
    --max-concurrency 10 \
    --max-errors 25%
    Windows
    aws ssm start-automation-execution ^
    --document-name runbook_name ^
    --targets Key=AWS::EC2::Instance,Values=* ^
    --target-parameter-name instanceId ^
    --parameters "input_parameter_name1=input_parameter_value1" ^
    --max-concurrency 10 ^
    --max-errors 25%
    PowerShell
    $Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "AWS::EC2::Instance"
$Targets.Values = "*"

Start-SSMAutomationExecution `
    -DocumentName "RunbookName" `
    -Targets $Targets `
    -TargetParameterName "instanceId" `
    -Parameter @{"input_parameter_name1"="input_parameter_value1"} `
    -MaxConcurrency "a_number_of_instances_or_a_percentage_of_target_set" `
    -MaxError "a_number_of_errors_or_a_percentage_of_target_set"

    コマンドによって実行 ID が返されます。この ID をクリップボードにコピーします。この ID を使用して、オートメーションの状態を表示できます。

    Linux & macOS
    {
    "AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
}
    Windows
    {
    "AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
}
    PowerShell
    a4a3c0e9-7efd-462a-8594-01234EXAMPLE

  5. 以下のコマンドを実行して、オートメーションを表示します。

    Linux & macOS
    aws ssm describe-automation-executions \
    --filter Key=ExecutionId,Values=a4a3c0e9-7efd-462a-8594-01234EXAMPLE
    Windows
    aws ssm describe-automation-executions ^
    --filter Key=ExecutionId,Values=a4a3c0e9-7efd-462a-8594-01234EXAMPLE
    PowerShell
    Get-SSMAutomationExecutionList | `
    Where {$_.AutomationExecutionId -eq "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"}

  6. オートメーションの進捗の詳細を表示するには、以下のコマンドを実行します。

    Linux & macOS
    aws ssm get-automation-execution \
    --automation-execution-id a4a3c0e9-7efd-462a-8594-01234EXAMPLE
    Windows
    aws ssm get-automation-execution ^
    --automation-execution-id a4a3c0e9-7efd-462a-8594-01234EXAMPLE
    PowerShell
    Get-SSMAutomationExecution `
    -AutomationExecutionId a4a3c0e9-7efd-462a-8594-01234EXAMPLE

    システムが以下のような情報を返します。

    Linux & macOS
    {
    "AutomationExecution": {
        "StepExecutionsTruncated": false,
        "AutomationExecutionStatus": "Success",
        "MaxConcurrency": "1",
        "Parameters": {},
        "MaxErrors": "1",
        "Outputs": {},
        "DocumentName": "AWS-StopEC2Instance",
        "AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE",
        "ResolvedTargets": {
            "ParameterValues": [
                "i-02573cafcfEXAMPLE"
            ],
            "Truncated": false
        },
        "ExecutionEndTime": 1564681619.915,
        "Targets": [
            {
                "Values": [
                    "DEV"
                ],
                "Key": "tag:ENV"
            }
        ],
        "DocumentVersion": "1",
        "ExecutionStartTime": 1564681576.09,
        "ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
        "StepExecutions": [
            {
                "Inputs": {
                    "InstanceId": "i-02573cafcfEXAMPLE"
                },
                "Outputs": {},
                "StepName": "i-02573cafcfEXAMPLE",
                "ExecutionEndTime": 1564681619.093,
                "StepExecutionId": "86c7b811-3896-4b78-b897-01234EXAMPLE",
                "ExecutionStartTime": 1564681576.836,
                "Action": "aws:executeAutomation",
                "StepStatus": "Success"
            }
        ],
        "TargetParameterName": "InstanceId",
        "Mode": "Auto"
    }
}
    Windows
    {
    "AutomationExecution": {
        "StepExecutionsTruncated": false,
        "AutomationExecutionStatus": "Success",
        "MaxConcurrency": "1",
        "Parameters": {},
        "MaxErrors": "1",
        "Outputs": {},
        "DocumentName": "AWS-StopEC2Instance",
        "AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE",
        "ResolvedTargets": {
            "ParameterValues": [
                "i-02573cafcfEXAMPLE"
            ],
            "Truncated": false
        },
        "ExecutionEndTime": 1564681619.915,
        "Targets": [
            {
                "Values": [
                    "DEV"
                ],
                "Key": "tag:ENV"
            }
        ],
        "DocumentVersion": "1",
        "ExecutionStartTime": 1564681576.09,
        "ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
        "StepExecutions": [
            {
                "Inputs": {
                    "InstanceId": "i-02573cafcfEXAMPLE"
                },
                "Outputs": {},
                "StepName": "i-02573cafcfEXAMPLE",
                "ExecutionEndTime": 1564681619.093,
                "StepExecutionId": "86c7b811-3896-4b78-b897-01234EXAMPLE",
                "ExecutionStartTime": 1564681576.836,
                "Action": "aws:executeAutomation",
                "StepStatus": "Success"
            }
        ],
        "TargetParameterName": "InstanceId",
        "Mode": "Auto"
    }
}
    PowerShell
    AutomationExecutionId       : a4a3c0e9-7efd-462a-8594-01234EXAMPLE
AutomationExecutionStatus   : Success
CurrentAction               : 
CurrentStepName             : 
DocumentName                : AWS-StopEC2Instance
DocumentVersion             : 1
ExecutedBy                  : arn:aws:sts::123456789012:assumed-role/Administrator/Admin
ExecutionEndTime            : 8/1/2019 5:46:59 PM
ExecutionStartTime          : 8/1/2019 5:46:16 PM
FailureMessage              : 
MaxConcurrency              : 1
MaxErrors                   : 1
Mode                        : Auto
Outputs                     : {}
Parameters                  : {}
ParentAutomationExecutionId : 
ProgressCounters            : 
ResolvedTargets             : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
StepExecutions              : {i-02573cafcfEXAMPLE}
StepExecutionsTruncated     : False
Target                      : 
TargetLocations             : {}
TargetMaps                  : {}
TargetParameterName         : InstanceId
Targets                     : {tag:Name}
    注記

    コンソールで、オートメーションのステータスをモニタリングすることもできます。[Automation executions (オートメーション実行)] リストで、先ほど開始した実行を選択し、[Execution steps (実行ステップ)] タブを選択します。このタブには、オートメーションアクションのステータスが表示されます。