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

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

AWS Systems Manager を使用すると、ターゲットを使用して AWS リソースのフリートでオートメーションを実行できます。さらに、同時実行値とエラーのしきい値を指定することで、フリート全体のオートメーションのデプロイを制御することができます。同時実行値は、オートメーションを同時に実行できるリソースの数を決定します。エラーのしきい値は、Systems Manager がワークフローの他のリソースへの送信を停止するまでの、オートメーションの失敗の許容量を決定します。同時実行数とエラーのしきい値機能は、まとめてレート制御と呼ばれます。

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

以下の手順では、AWS Systems Manager コンソール、AWS Command Line Interface (AWS CLI)、AWS Tools for Windows PowerShell を使用して、ターゲットおよびレート制御を使用したオートメーションを実行する方法について説明します。

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

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

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

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

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

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

    注記

    ドキュメント名を選択すると、ドキュメントに関する情報を表示できます。

  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 Group (リソースグループ)] リストからグループの名前を選択します。

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

      4. 現在の 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
    aws ssm list-documents
    Windows
    aws ssm list-documents
    PowerShell
    Get-SSMDocumentList

    実行する自動化ドキュメントの名前を記録します。

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

    Linux
    aws ssm describe-document \ --name document_name
    Windows
    aws ssm describe-document ^ --name document_name
    PowerShell
    Get-SSMDocumentDescription ` -Name document_name
  4. 実行するターゲットとレート制御オプションを使用するコマンドを作成します。便利なテンプレートコマンドを次に示します。

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

    Linux
    aws ssm start-automation-execution \ --document-name document_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 document_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 "DocumentName" ` -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
    aws ssm start-automation-execution \ --document-name document_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 document_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 "DocumentName" ` -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 リソースグループ を使用したターゲット設定

    Linux
    aws ssm start-automation-execution \ --document-name document_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 document_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 "DocumentName" ` -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 アカウントとリージョンのすべてのインスタンスをターゲットに設定する

    Linux
    aws ssm start-automation-execution \ --document-name document_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 document_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 "DocumentName" ` -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
    {
        "AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
    }
    Windows
    {
        "AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
    }
    PowerShell
    a4a3c0e9-7efd-462a-8594-01234EXAMPLE
  5. 以下のコマンドを実行して、オートメーション実行を表示します。

    Linux
    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
    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
    {
        "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 (実行ステップ)] タブを選択します。このタブには、オートメーションアクションのステータスが表示されます。