ランブックでの条件文の使用 - AWS Systems Manager

ランブックでの条件文の使用

デフォルトでは、ランブックの mainSteps セクションで定義したステップは順番に実行されます。1 つのアクションが完了した後、mainSteps セクションで指定された次のアクションが開始されます。さらに、アクションが失敗した場合は、(デフォルトでは) オートメーション全体の実行に失敗します。このセクションで説明されている aws:branch オートメーションアクションおよびランブックオプションを使用すると、条件付き分岐を実行するオートメーションを作成できます。つまり、異なる選択肢を評価した後に異なるステップにジャンプするオートメーションを作成したり、ステップが完了したときに変更に動的に応答するオートメーションを作成することができます。動的オートメーションの作成に使用できるオプションのリストは次のとおりです。

  • aws:branch: この自動化アクションを使用すると、1 つのステップで複数の選択肢を評価し、その評価結果に基づいてランブックの異なるステップにジャンプする動的オートメーションを作成できます。

  • nextStep: このオプションは、ステップを正常に完了した後に、次に処理するオートメーションのステップを指定します。

  • isEnd: このオプションでは、特定のステップの最後にオートメーションを停止します。このオプションのデフォルト値は false です。

  • isCritical: このオプションはオートメーションの正常な完了のために、ステップを critical として指定します。この指定のステップが失敗した場合、オートメーションはオートメーションの失敗の最終的なステータスを Failed としてレポートします。このオプションのデフォルト値は true です。

  • onFailure: このオプションは失敗時にオートメーションを中止するか、続行するか、または別のステップに移行するかを示します。このオプションのデフォルト値は中止です。

次のセクションでは、aws:branch オートメーションアクションについて説明します。nextStepisEndisCriticalonFailure オプションの詳細については、「aws:branch ランブックの例」を参照してください。

aws:branch アクションの使用

aws:branch アクションは、オートメーションのための最も動的な条件分岐オプションを提供します。前述のとおり、このアクションによって、オートメーションで複数の条件を 1 つのステップで評価し、その評価の結果に基づいて新しいステップにジャンプすることができます。aws:branch アクションは、プログラミングで IF-ELIF-ELSE ステートメントのように機能します。

以下に、aws:branch ステップの YAML の例を示します。

- name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: PostProcessing

ステップの aws:branch アクションを指定する場合、オートメーションが評価する必要のある Choices を指定します。オートメーションは、ランブックの Choices セクションで指定したパラメータの値に基づいて、Parameters を評価できます。オートメーションは、前の手順の出力に基づいて Choices を評価することもできます。

自動化は、ブール式を使用して各選択肢を評価します。最初の選択肢が true であると判断された場合、オートメーションはその選択肢で指定されたステップにジャンプします。最初の選択肢が false であると判断された場合、オートメーションは次の選択肢を評価します。ステップに 3 つ以上の Choices が含まれている場合、オートメーションは、true である選択肢を評価するまで、各選択肢を順番に評価します。次に、オートメーションは、true の選択のために指定されたステップにジャンプします。

Choices である true がない場合、オートメーションはステップに Default 値が含まれているかどうかを確認します。Default 値は、true である選択肢がない場合にオートメーションがジャンプするステップを定義します。ステップに Default 値が指定されていない場合、オートメーションはランブックの次のステップを処理します。

以下は YAML の [chooseOSfromParameter] という名前の aws:branch ステップです。ステップには、2 つの Choices が含まれています。 (NextStep: runWindowsCommand) および (NextStep: runLinuxCommand)。オートメーションは、これらの Choices を評価して、適切なオペレーティングシステムで実行するコマンドを決定します。各選択肢の Variable は、{{OSName}} を使用します。これは、ランブック作成者がランブックの Parameters セクションで定義したパラメータです。

mainSteps: - name: chooseOSfromParameter action: aws:branch inputs: Choices: - NextStep: runWindowsCommand Variable: "{{OSName}}" StringEquals: Windows - NextStep: runLinuxCommand Variable: "{{OSName}}" StringEquals: Linux

以下は YAML の [chooseOSfromOutput] という名前の aws:branch ステップです。ステップには、2 つの Choices が含まれています。 (NextStep: runPowerShellCommand) および (NextStep: runShellCommand)。オートメーションは、これらの Choices を評価して、適切なオペレーティングシステムで実行するコマンドを決定します。各選択肢の Variable は、{{GetInstance.platform}} を使用します。これは、ランブックの前のステップからの出力です。この例では Default というオプションも含まれています。オートメーションが両方の Choices を評価し 、どちらの選択肢も true である場合、オートメーションは PostProcessing というステップにジャンプします。

mainSteps: - name: chooseOSfromOutput action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: PostProcessing

ランブック aws:branch でのステップの作成

ランブック aws:branch でステップを作成するときは、オートメーションが次にジャンプするステップを決定するために評価するChoices を定義します。前述のように、Choices はブール式を使用して評価されます。各選択肢は、次のオプションを定義する必要があります。

  • NextStep : 指定された選択肢が true である場合に処理するランブックの次のステップ。

  • Variable: ランブックの Parameters セクションで定義されているパラメータの名前を指定するか、Variables セクションで定義されている変数の名前を指定するか、前のステップからの出力オブジェクトを指定します。

    次の形式を使用して変数の値を指定します。

    Variable: "{{variable name}}"

    次の形式を使用してパラメータの値を指定します。

    Variable: "{{parameter name}}"

    次の形式を使用して出力オブジェクト変数を指定します。

    Variable: "{{previousStepName.outputName}}"

    注記

    出力変数の作成については、次のセクション「出力変数の作成について」でさらに詳しく説明します。

  • Operation: StringEquals: Linux などの選択肢を評価するために使用される基準。aws:branch アクションは、次の操作をサポートします。

    文字列演算子
    • StringEquals

    • EqualsIgnoreCase

    • StartsWith

    • EndsWith

    • Contains

    数値演算子
    • NumericEquals

    • NumericGreater

    • NumericLesser

    • NumericGreaterOrEquals

    • NumericLesser

    • NumericLesserOrEquals

    ブール演算子
    • BooleanEquals

    重要

    ランブックを作成すると、システムはランブック内の各オペレーションを検証します。オペレーションがサポートされていない場合は、ランブックの作成時にエラーが返されます。

  • Default: Choices である true がない場合にオートメーションがジャンプするフォールバックステップを指定します。

    注記

    Default 値を指定しない場合は、isEnd オプションを指定できます。Choices である true がない場合、および Default 値が指定されていない場合は、オートメーションはステップの最後で停止します。

次のテンプレートを使用して、ランブックの aws:branch ステップを構築します。各リソースプレースホルダーの例をユーザー自身の情報に置き換えます。

YAML
mainSteps: - name: step name action: aws:branch inputs: Choices: - NextStep: step to jump to if evaluation for this choice is true Variable: "{{parameter name or output from previous step}}" Operation type: Operation value - NextStep: step to jump to if evaluation for this choice is true Variable: "{{parameter name or output from previous step}}" Operation type: Operation value Default: step to jump to if all choices are false
JSON
{ "mainSteps":[ { "name":"a name for the step", "action":"aws:branch", "inputs":{ "Choices":[ { "NextStep":"step to jump to if evaluation for this choice is true", "Variable":"{{parameter name or output from previous step}}", "Operation type":"Operation value" }, { "NextStep":"step to jump to if evaluation for this choice is true", "Variable":"{{parameter name or output from previous step}}", "Operation type":"Operation value" } ], "Default":"step to jump to if all choices are false" } } ] }

出力変数の作成について

前のステップからの出力を参照する aws:branch 選択肢を作成するには、前のステップの名前と出力フィールドの名前を特定する必要があります。次に、以下の形式を使用して、ステップ名とフィールド名を結合します。

Variable: "{{previousStepName.outputName}}"

例えば、次の例の最初のステップは GetInstance という名前です。そして、outputs の下に、platform というフィールドがあります。2 番目のステップ (ChooseOSforCommands) では、作成者はプラットフォームフィールドからの出力を変数として参照しようとしています。変数を作成するには、単純にステップ名 (GetInstance) と出力フィールド名 (platform) を組み合わせて Variable: "{{GetInstance.platform}}" を作成します。

mainSteps: - Name: GetInstance action: aws:executeAwsApi inputs: Service: ssm Api: DescribeInstanceInformation Filters: - Key: InstanceIds Values: ["{{ InstanceId }}"] outputs: - Name: myInstance Selector: "$.InstanceInformationList[0].InstanceId" Type: String - Name: platform Selector: "$.InstanceInformationList[0].PlatformType" Type: String - name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: Sleep

前のステップと出力から "Variable": "{{ describeInstance.Platform }}" を作成する方法例を示します。

- name: describeInstance action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: DescribeInstances InstanceIds: - "{{ InstanceId }}" outputs: - Name: Platform Selector: "$.Reservations[0].Instances[0].Platform" Type: String nextStep: branchOnInstancePlatform - name: branchOnInstancePlatform action: aws:branch inputs: Choices: - NextStep: runEC2RescueForWindows Variable: "{{ describeInstance.Platform }}" StringEquals: windows Default: runEC2RescueForLinux

aws:branch ランブックの例

以下に、aws:branch を使用するランブックの例をいくつか挙げます。

例 1: 出力変数で aws:branch を使用し、オペレーティングシステムの種類に基づいてコマンドを実行する

この例 (GetInstance) の最初の手順では、ランブック作成者は aws:executeAwsApi アクションを使用して、ssm DescribeInstanceInformation API オペレーションを呼び出します。作成者はこのアクションを使用して、インスタンスが使用しているオペレーティングシステムのタイプを判別します。aws:executeAwsApi アクションはインスタンス ID とプラットフォームタイプを出力します。

2 番目のステップ (ChooseOSforCommands) では、2 つの aws:branch (Choices) と (NextStep: runPowerShellCommand) を使用して NextStep: runShellCommand アクションを使用します。自動化は、前の手順 (Variable: "{{GetInstance.platform}}") の出力を使用して、インスタンスのオペレーティングシステムを評価します。オートメーションは、指定されたオペレーティングシステムのステップにジャンプします。

--- schemaVersion: '0.3' assumeRole: "{{AutomationAssumeRole}}" parameters: AutomationAssumeRole: default: "" type: String mainSteps: - name: GetInstance action: aws:executeAwsApi inputs: Service: ssm Api: DescribeInstanceInformation outputs: - Name: myInstance Selector: "$.InstanceInformationList[0].InstanceId" Type: String - Name: platform Selector: "$.InstanceInformationList[0].PlatformType" Type: String - name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: Sleep - name: runShellCommand action: aws:runCommand inputs: DocumentName: AWS-RunShellScript InstanceIds: - "{{GetInstance.myInstance}}" Parameters: commands: - ls isEnd: true - name: runPowerShellCommand action: aws:runCommand inputs: DocumentName: AWS-RunPowerShellScript InstanceIds: - "{{GetInstance.myInstance}}" Parameters: commands: - ls isEnd: true - name: Sleep action: aws:sleep inputs: Duration: PT3S

例 2: パラメータ変数で aws:branch を使用し、オペレーティングシステムの種類に基づいてコマンドを実行する

ランブック作成者は、parameters セクションのランブックの先頭にいくつかのパラメータオプションを定義します。1 つのパラメータの名前は OperatingSystemName です。最初のステップ (ChooseOS) では、2 つの aws:branch (Choices) と (NextStep: runWindowsCommand) を使用して NextStep: runLinuxCommand アクションを使用します。これらの Choices の変数は、パラメータセクション (Variable: "{{OperatingSystemName}}") で指定されたパラメータオプションを参照します。ユーザーがこのランブックを実行すると、実行時に OperatingSystemName の値を指定します 。オートメーションでは、Choices の評価時にランタイムパラメータが使用されます。オートメーションは、OperatingSystemName に指定されたランタイムパラメータに基づいて、指定されたオペレーティングシステムのステップにジャンプします。

--- schemaVersion: '0.3' assumeRole: "{{AutomationAssumeRole}}" parameters: AutomationAssumeRole: default: "" type: String OperatingSystemName: type: String LinuxInstanceId: type: String WindowsInstanceId: type: String mainSteps: - name: ChooseOS action: aws:branch inputs: Choices: - NextStep: runWindowsCommand Variable: "{{OperatingSystemName}}" StringEquals: windows - NextStep: runLinuxCommand Variable: "{{OperatingSystemName}}" StringEquals: linux Default: Sleep - name: runLinuxCommand action: aws:runCommand inputs: DocumentName: "AWS-RunShellScript" InstanceIds: - "{{LinuxInstanceId}}" Parameters: commands: - ls isEnd: true - name: runWindowsCommand action: aws:runCommand inputs: DocumentName: "AWS-RunPowerShellScript" InstanceIds: - "{{WindowsInstanceId}}" Parameters: commands: - date isEnd: true - name: Sleep action: aws:sleep inputs: Duration: PT3S

演算子を使用した複雑な分岐オートメーションの作成

And ステップで OrNot、および aws:branch 演算子を使用して、複雑な分岐オートメーションを作成できます。

"And" 演算子

選択肢の複数の変数を And にする場合は、true 演算子を使用します。次の例では、最初の選択肢に対して、インスタンスが running の状態で、Windows オペレーティングシステムを使用しているかどうかを評価します。これらの変数の両方が true と評価された場合、オートメーションは runPowerShellCommand ステップにジャンプします。1 つ以上の変数が false の場合、オートメーションは 2 番目の選択肢の変数を評価します。

mainSteps: - name: switch2 action: aws:branch inputs: Choices: - And: - Variable: "{{GetInstance.pingStatus}}" StringEquals: running - Variable: "{{GetInstance.platform}}" StringEquals: Windows NextStep: runPowerShellCommand - And: - Variable: "{{GetInstance.pingStatus}}" StringEquals: running - Variable: "{{GetInstance.platform}}" StringEquals: Linux NextStep: runShellCommand Default: sleep3
"OR" 演算子

選択肢の複数の変数のいずれかを true にする場合は、Or 演算子を使用します。次の例では、最初の選択は、パラメータ文字列が Windows であるかどうか、AWS Lambda ステップからの出力が true かどうかを評価します。これらの変数のどちらかが true であると判断された場合、オートメーションは RunPowerShellCommand ステップにジャンプします。両方の変数が false の場合、オートメーションは 2 番目の選択肢の変数を評価します。

- Or: - Variable: "{{parameter1}}" StringEquals: Windows - Variable: "{{BooleanParam1}}" BooleanEquals: true NextStep: RunPowershellCommand - Or: - Variable: "{{parameter2}}" StringEquals: Linux - Variable: "{{BooleanParam2}}" BooleanEquals: true NextStep: RunShellScript
"Not" 演算子

変数が true でない場合に定義されたステップにジャンプする場合は、Not 演算子を使用します。次の例では、最初の選択肢は、パラメータ文字列が Not Linux かどうかを評価します。変数が Linux ではないと判断された場合、オートメーションは sleep2 ステップにジャンプします。最初の選択肢が Linux であると判断された場合、オートメーションは次の選択肢を評価します。

mainSteps: - name: switch action: aws:branch inputs: Choices: - NextStep: sleep2 Not: Variable: "{{testParam}}" StringEquals: Linux - NextStep: sleep1 Variable: "{{testParam}}" StringEquals: Windows Default: sleep3

条件オプションの使用例

このセクションでは、ランブックで動的オプションを使用するさまざまな例について説明します。このセクションのそれぞれの例では、次のランブックを拡張します。このランブックには 2 つのアクションがあります。最初のアクションは InstallMsiPackage という名前です。aws:runCommand アクションを使用して、Windows Server インスタンスにアプリケーションをインストールします。2 番目のアクションは、TestInstall という名前です。このアクションは、aws:invokeLambdaFunction アクションを使用し、アプリケーションが正常にインストールされているかどうか、インストールされているアプリケーションのテストを実行します。ステップ 1 で onFailure: Abort を指定します。つまり、アプリケーションがインストールされなかった場合は、オートメーションの実行はステップ 2 より前で停止します。

例 1:2 つのリニアアクションがあるランブック

--- schemaVersion: '0.3' description: Install MSI package and run validation. assumeRole: "{{automationAssumeRole}}" parameters: automationAssumeRole: type: String description: "(Required) Assume role." packageName: type: String description: "(Required) MSI package to be installed." instanceIds: type: String description: "(Required) Comma separated list of instances." mainSteps: - name: InstallMsiPackage action: aws:runCommand maxAttempts: 2 onFailure: Abort inputs: InstanceIds: - "{{instanceIds}}" DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} - name: TestInstall action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: TestLambdaFunction ...

onFailure オプションを使用し、別のステップにジャンプする動的オートメーションを作成する

次の例では、onFailure: step:step namenextStep、および isEnd オプションを使用して、動的オートメーションを作成します。この例では、InstallMsiPackage アクションが失敗すると、自動化は PostFailure (onFailure: step:PostFailure) というアクションにジャンプし、インストールに失敗したイベントの何らかのアクションを実行する AWS Lambda 関数を実行します。インストールが成功した場合は、自動化は TestInstall アクション (nextStep: TestInstall) にジャンプします。TestInstall ステップと PostFailure ステップの両方で isEnd オプション (isEnd: true) を使用すると、これらのステップのいずれかが完了したときにオートメーションが終了します。

注記

isEnd セクションの最後のステップでの、mainSteps オプションの使用はオプションです。最後のステップが他のステップにジャンプしない場合、最後のステップのアクションの実行後にオートメーションは停止します。

例 2: 別のステップにジャンプする動的オートメーション

mainSteps - name: InstallMsiPackage action: aws:runCommand onFailure: step:PostFailure maxAttempts: 2 inputs: InstanceIds: - "{{instanceIds}}" DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} nextStep: TestInstall - name: TestInstall action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: TestLambdaFunction isEnd: true - name: PostFailure action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: PostFailureRecoveryLambdaFunction isEnd: true ...
注記

ランブックを処理する前に、システムはランブックが無限ループを作成していないことを確認します。無限ループが検出された場合、自動化はエラー、およびどのステップがループを作成しているかを示すサークルトレースを返します。

重要な手順を定義する動的オートメーションの作成

オートメーション全体の成功にとって非常に重要なステップを指定できます。重要なステップが失敗した場合、1 つ以上のステップが正常に実行されたとしても、オートメーションは実行のステータスを Failed としてレポートします。次の例では、InstallMsiPackage ステップが失敗した (onFailure: step:VerifyDependencies) 場合に、ユーザーは VerifyDependencies ステップを識別します。ユーザーは、InstallMsiPackage ステップが critical ではないことを指定します (isCritical: false)。この例では、アプリケーションのインストールに失敗した場合、自動化は VerifyDependencies ステップを処理して、アプリケーションのインストールが失敗する原因となる、1 つ以上の依存関係が欠落していないかどうかを判断します。

例 3: オートメーションを定義する重要なステップ

--- name: InstallMsiPackage action: aws:runCommand onFailure: step:VerifyDependencies isCritical: false maxAttempts: 2 inputs: InstanceIds: - "{{instanceIds}}" DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} nextStep: TestPackage ...