런북에서 조건문 사용 - AWS Systems Manager

런북에서 조건문 사용

기본적으로 실행서의 mainSteps 섹션에서 정의하는 단계는 순차적으로 실행됩니다. 한 작업이 완료된 후에는 mainSteps 섹션에 지정된 다음 작업이 시작됩니다. 또한 작업 실행에 실패할 경우 기본적으로 전체 자동화가 실패합니다. 이 섹션에 설명된 aws:branch 자동화 작업 및 실행서 옵션을 사용하여 조건부 분기를 수행하는 자동화를 생성할 수 있습니다. 다시 말해서 단계 완료 시 변경 내용에 동적으로 응답하거나 다양한 선택 항목을 평가한 후 다른 단계로 이동하는 자동화를 생성할 수 있습니다. 동적 자동화를 생성하는 데 사용할 수 있는 옵션 목록은 다음과 같습니다.

  • aws:branch: 이 자동화 작업을 통해 한 단계에서 여러 선택 항목을 평가한 다음 평가 결과에 따라 실행서의 다른 단계로 이동하는 동적 자동화를 생성할 수 있습니다.

  • nextStep: 이 옵션은 한 단계를 성공적으로 완료한 후 처리할 자동화의 단계를 지정합니다.

  • isEnd: 이 옵션은 특정 단계 종료 시 자동화를 중지합니다. 이 옵션의 기본값은 false입니다.

  • isCritical: 이 옵션은 자동화의 성공적 완료에 대해 단계를 심각으로 지정합니다. 이 지정이 있는 단계가 실패하면 Automation은 자동화의 최종 상태를 Failed로 보고합니다. 이 옵션의 기본값은 true입니다.

  • onFailure: 이 옵션은 실패 시 자동화가 중지되어야 하는지, 계속되어야 하는지 또는 다른 단계로 이동해야 하는지를 나타냅니다. 이 옵션의 기본값은 중단입니다.

다음 섹션에서는 aws:branch 자동화 작업을 설명합니다. nextStep, isEnd, isCriticalonFailure 옵션에 대한 자세한 내용은 예제 aws:branch 실행서 섹션을 참조하세요.

aws:branch 작업 수행

aws:branch 작업은 자동화에 대한 가장 동적인 조건부 분기 옵션을 제공합니다. 앞에서 언급한 바와 같이, 이 작업을 사용하면 자동화가 한 단계에서 여러 조건을 평가한 다음 해당 평가의 결과에 따라 새 단계로 이동할 수 있습니다. 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를 지정할 수 있습니다. 이 자동화는 실행서의 Parameters 섹션에 지정된 파라미터의 값에 따라 Choices를 평가할 수 있습니다. 이 자동화는 이전 단계의 출력에 따라 Choices를 평가할 수도 있습니다.

이 자동화는 부울 식을 사용하여 각 선택을 평가합니다. 평가에서 첫 번째 선택 항목이 true인 것으로 확인되면 자동화는 해당 선택 항목에 지정된 단계로 이동합니다. 평가에서 첫 번째 선택 항목이 false인 것으로 확인되면 자동화는 다음 선택 항목을 평가합니다. 단계에 세 개 이상의 Choices가 포함된 경우 자동화는 true인 선택 항목을 평가할 때까지 순서대로 각 선택 항목을 평가합니다. 그런 다음 이 워크플로는 true인 선택 항목에 지정된 단계로 이동합니다.

Choices 중에 true인 항목이 없는 경우 자동화는 단계에 Default 값이 포함되었는지 확인합니다. Default 값은 선택 항목 중에 true인 항목이 없는 경우 자동화에서 이동해야 하는 단계를 정의합니다. 단계에 대한 Default 값이 지정되지 않은 경우 자동화는 실행서의 다음 단계를 처리합니다.

다음은 chooseOSfromParameter라는 YAML의 aws:branch 단계입니다. 이 단계에는 NextStep: runWindowsCommandNextStep: runLinuxCommand라는 두 Choices가 포함되어 있습니다. 이 자동화는 이러한 Choices를 평가하여 해당 운영 체제에 대해 실행할 명령을 결정합니다. 각 선택 항목에 대한 Variable{{OSName}}을 사용하며, 이것은 실행서 작성자가 실행서의 Parameters 섹션에 정의한 파라미터입니다.

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

다음은 chooseOSfromOutput이라는 YAML의 aws:branch 단계입니다. 이 단계에는 NextStep: runPowerShellCommandNextStep: runShellCommand라는 두 Choices가 포함되어 있습니다. 이 자동화는 이러한 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

    • 포함

    수치 연산
    • NumericEquals

    • NumericGreater

    • NumericLesser

    • NumericGreaterOrEquals

    • NumericLesser

    • NumericLesserOrEquals

    부울 연산
    • BooleanEquals

    중요

    실행서를 생성하면 시스템에서 실행서의 각 작업을 검증합니다. 작업이 지원되지 않는 경우 실행서를 생성할 때 오류가 발생합니다.

  • Default: Choices 중 어떤 것도 true가 아니면 자동화에서 이동해야 할 폴백 단계를 지정합니다.

    참고

    Default 값을 지정하지 않으려면 isEnd 옵션을 지정할 수 있습니다. Choices 중 어느 것도 true가 아니며 Default 값을 지정하지 않은 경우 자동화는 단계의 끝에서 중지됩니다.

다음 템플릿을 사용하여 실행서에서 aws:branch 단계를 생성합니다. 각 example resource placeholder를 사용자의 정보로 바꿉니다.

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이라는 필드가 있습니다. 두 번째 단계(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 및 플랫폼 유형을 출력합니다.

두 번째 단계(ChooseOSforCommands)에서 작성자는 aws:branch 작업과 두ChoicesNextStep: runPowerShellCommandNextStep: 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 섹션에서 여러 파라미터 옵션을 정의합니다. 파라미터 하나의 이름은 OperatingSystemName입니다. 첫 번째 단계(ChooseOS)에서 작성자는 aws:branch 작업과 두ChoicesNextStep: runWindowsCommandNextStep: 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

연산자를 사용하여 복합 분기 자동화 생성

aws:branch 단계에서 And, OrNot 연산자를 사용하여 복합 문기 자동화를 생성할 수 있습니다.

'And' 연산자

선택 항목에 대해 여러 변수가 true가 되도록 하려는 경우 And 연산자를 사용합니다. 다음 예제에서는 첫 번째 선택 항목이 인스턴스가 running이고 Windows 운영 체제를 사용하는지 여부를 평가합니다. 이들 변수 모두를 평가한 결과가 true이면 이 자동화는 runPowerShellCommand 단계로 이동합니다. 변수 중 하나 이상이 false이면 이 자동화는 두 번째 선택 항목에 대한 변수를 평가합니다.

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이면 이 자동화는 두 번째 선택 항목에 대한 변수를 평가합니다.

- 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 인스턴스에 애플리케이션을 설치합니다. 두 번째 작업의 이름은 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 name, nextStepisEnd 옵션을 사용하여 동적 자동화를 생성합니다. 이 예제에서 InstallMsiPackage 작업이 실패하면 자동화가 PostFailure(onFailure: step:PostFailure)라는 작업으로 이동하여 설치가 실패할 경우 특정 작업을 수행하는 AWS Lambda 함수를 실행합니다. 설치에 성공하면 이 자동화는 TestInstall 작업(nextStep: TestInstall)으로 이동합니다. 두 단계 중 하나가 완료될 때 자동화가 끝나도록 두 TestInstallPostFailure 단계에 모두 isEnd 옵션(isEnd: true)이 사용됩니다.

참고

mainSteps 섹션의 마지막 단계에서 isEnd 옵션을 사용하는 것은 선택 사항입니다. 마지막 단계가 다른 단계로 건너뛰지 않으면 마지막 단계에서 작업을 실행한 후 자동화가 중지됩니다.

예 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 ...
참고

실행서를 처리하기 전에 시스템은 실행서가 무한 루프를 생성하지 않는지 확인합니다. 무한 루프가 감지되면 자동화는 오류와 순환 추적을 반환하여 루프를 생성하는 단계를 표시합니다.

중요 단계를 정의하는 동적 자동화 생성

단계가 자동화의 전체 성공에 중요한지를 지정할 수 있습니다. 중요 단계가 실패하면 하나 이상의 단계가 성공적으로 실행되더라도 Automation은 자동화 상태를 Failed로 보고합니다. 다음 예에서 사용자는 InstallMsiPackage 단계가 실패하는 경우(onFailure: step:VerifyDependencies) VerifyDependencies 단계를 식별합니다. 사용자는 InstallMsiPackage 단계가 중요하지 않다고 지정합니다(isCritical: false). 이 예에서는 애플리케이션 설치에 실패한 경우 자동화가 VerifyDependencies 단계를 처리하여 하나 이상의 종속성이 누락되어 결과적으로 애플리케이션 설치에 실패했는지 여부를 확인합니다.

예제 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 ...