기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # 사용자 지정 AWSTOE 구성 요소에 구성 요소 문서 프레임워크 사용 AWS Task Orchestrator and Executor (AWSTOE) 구성 요소 프레임워크를 사용하여 구성 요소를 빌드하려면 생성한 구성 요소에 적용되는 단계와 단계를 나타내는 YAML 기반 문서를 제공해야 합니다. 새 Amazon Machine Image(AMI) 또는 컨테이너 이미지를 생성할 때 구성 요소를 AWS 서비스 사용합니다. **Topics** + [구성 요소 문서 워크플로우](#component-doc-workflow) + [구성 요소 로깅](#component-logging) + [입력 및 출력 체인화](#document-chaining) + [문서 스키마 및 정의](#document-schema) + [문서 예제](#document-example) + [사용자 지정 구성 요소 문서에서 변수 사용](toe-user-defined-variables.md) + [에서 조건부 구문 사용 AWSTOE](toe-conditional-constructs.md) + [AWSTOE 구성 요소 문서에서 비교 연산자 사용](toe-comparison-operators.md) + [AWSTOE 구성 요소 문서에서 논리 연산자 사용](toe-logical-operators.md) + [에서 반복 구문 사용 AWSTOE](toe-looping-constructs.md) ## 구성 요소 문서 워크플로우 AWSTOE 구성 요소 문서는 단계와 단계를 사용하여 관련 작업을 그룹화하고 해당 작업을 구성 요소의 논리적 워크플로로 구성합니다. **작은 정보** 구성 요소를 사용하여 이미지를 빌드하는 서비스는 빌드 프로세스에 사용할 단계와 해당 단계의 실행 허용 시기에 대한 규칙을 구현할 수 있습니다. 이는 구성 요소를 설계할 때 고려해야 할 중요한 사항입니다. **단계** 단계는 이미지 빌드 프로세스를 통한 워크플로우의 진행 상황을 나타냅니다. 예를 들어 Image Builder 서비스는 생성한 이미지에 대해 *빌드 단계*에서 `build` 및 `validate` 단계를 사용합니다. *테스트 단계*에서 `test` 및 `container-host-test` 단계를 사용하여 최종 AMI를 생성하거나 컨테이너 이미지를 배포하기 전에 이미지 스냅샷 또는 컨테이너 이미지가 예상 결과를 생성하는지 확인합니다. 구성 요소가 실행되면 각 단계의 관련 명령이 구성 요소 문서에 표시된 순서대로 적용됩니다. **단계 규칙** + 각 단계 이름은 문서 내에서 고유해야 합니다. + 문서에 여러 단계를 정의할 수 있습니다. + 문서에 다음 단계 중 하나 이상을 포함해야 합니다. + **빌드** — Image Builder의 경우 이 단계는 일반적으로 *빌드 단계*에서 사용됩니다. + **검증** — Image Builder의 경우 이 단계는 일반적으로 *빌드 단계*에서 사용됩니다. + **테스트** — Image Builder의 경우 이 단계는 일반적으로 *테스트 단계*에서 사용됩니다. + 단계는 항상 문서에 정의된 순서대로 실행됩니다. 의 AWSTOE 명령 AWS CLI 에 지정된 순서는 영향을 주지 않습니다. **단계(Steps)** 단계는 각 단계 내의 워크플로우를 정의하는 개별 작업 단위입니다. 단계는 순차적으로 실행됩니다. 하지만 한 단계의 입력 또는 출력이 다음 단계에 입력으로 제공될 수도 있습니다. 이를 ‘체인화’라고 합니다. **단계 규칙** + 단계 이름은 해당 단계에 대해 고유해야 합니다. + 단계는 종료 코드를 반환하는 지원되는 작업(작업 모듈)을 사용해야 합니다. 지원되는 작업 모듈의 전체 목록, 작동 방식, 입력/출력 값 및 예제는 [AWSTOE 구성 요소 관리자가 지원하는 작업 모듈](toe-action-modules.md)(을)를 참조하세요. ## 구성 요소 로깅 AWSTOE 는 구성 요소가 실행될 때마다 새 이미지를 빌드하고 테스트하는 데 사용되는 새 로그 폴더를 EC2 인스턴스에 생성합니다. 컨테이너 이미지의 경우 로그 폴더가 컨테이너에 저장됩니다. 이미지 생성 프로세스 중에 문제가 발생하는 경우 문제를 해결하는 데 도움이 되도록 구성 요소를 실행하는 동안 AWSTOE 생성되는 모든 출력 파일과 입력 문서가 로그 폴더에 저장됩니다. 로그 폴더 이름은 다음과 같은 부분으로 구성됩니다. 1. **로그 디렉터리** - 서비스가 AWSTOE 구성 요소를 실행하면 명령에 대한 다른 설정과 함께 로그 디렉터리를 전달합니다. 다음 예제에서는 Image Builder에서 사용하는 로그 파일 형식을 보여 줍니다. + **Linux 및 macOS**: `/var/lib/amazon/toe/` + **Windows**: `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\` 1. **파일 접두사** - 모든 구성 요소에 사용되는 표준 접두사입니다: ‘`TOE_`‘. 1. **런타임** — YYYY-MM-DD\$1HH-MM-SS\$1UTC-0 형식의 타임스탬프입니다. 1. **실행 ID** -가 하나 이상의 구성 요소를 AWSTOE 실행할 때 할당되는 GUID입니다. 예시: `/var/lib/amazon/toe/TOE_2021-07-01_12-34-56_UTC-0_a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4` AWSTOE 는 로그 폴더에 다음 코어 파일을 저장합니다. **입력 파일** + **document.yaml** — 명령의 입력으로 사용되는 문서. 구성 요소가 실행된 후 이 파일은 아티팩트로 저장됩니다. **출력 파일** + **application.log** - 애플리케이션 로그에는 구성 요소가 실행될 때 발생하는 상황에 대한 AWSTOE 의 타임스탬프가 있는 디버그 수준 정보가 들어 있습니다. + **detailedoutput.json** — 이 JSON 파일에는 구성 요소 실행 시 적용되는 모든 문서, 단계에 대한 실행 상태, 입력, 출력 및 실패에 대한 자세한 정보가 들어 있습니다. + **console.log** - 콘솔 로그에는 구성 요소가 실행되는 동안 콘솔에 AWSTOE 쓰는 모든 표준 출력(stdout) 및 표준 오류(stderr) 정보가 포함됩니다. + **chaining.json** -이 JSON 파일은 체인 표현식을 해석하는 데 AWSTOE 적용된 최적화를 나타냅니다. **참고** 로그 폴더에는 여기에서 다루지 않은 다른 임시 파일도 포함될 수 있습니다. ## 입력 및 출력 체인화 AWSTOE 구성 관리 애플리케이션은 다음 형식으로 참조를 작성하여 입력과 출력을 연결하는 기능을 제공합니다. `{{ phase_name.step_name.inputs/outputs.variable }}` 또는 `{{ phase_name.step_name.inputs/outputs[index].variable }}` 체인화 기능을 사용하면 코드를 재활용하고 문서의 유지 관리 용이성을 개선할 수 있습니다. **체인화 규칙** + 체인화 표현식은 각 단계의 입력 섹션에서만 사용할 수 있습니다. + 체인화 표현식이 포함된 명령문은 따옴표로 묶어야 합니다. 예제: + **잘못된 표현식**: `echo {{ phase.step.inputs.variable }}` + **유효한 표현식**: `"echo {{ phase.step.inputs.variable }}"` + **유효한 표현식**: `'echo {{ phase.step.inputs.variable }}'` + 체인화 표현식은 동일한 문서 내 다른 단계의 변수를 참조할 수 있습니다. 하지만 호출 서비스에는 체인화 표현식이 단일 단계 컨텍스트 내에서만 작동하도록 요구하는 규칙이 있을 수 있습니다. 예를 들어 Image Builder는 각 단계를 독립적으로 실행하므로 *빌드 단계*에서 *테스트 단계*로의 체인화를 지원하지 않습니다. + 체인화 표현식의 인덱스는 0부터 시작하는 인덱싱을 따릅니다. 첫 번째 요소를 참조하는 인덱스는 0으로 시작합니다. **예시** 다음 예제 단계의 두 번째 항목에서 소스 변수를 참조하기 위한 체인화 패턴은 다음과 같습니다.`{{ build.SampleS3Download.inputs[1].source }}` ``` phases: - name: 'build' steps: - name: SampleS3Download action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://sample-bucket/sample1.ps1' destination: 'C:\sample1.ps1' - source: 's3://sample-bucket/sample2.ps1' destination: 'C:\sample2.ps1' ``` 다음 예제 단계의 출력 변수(‘Hello’와 동등)를 참조하기 위한 체인화 패턴은 다음과 같습니다.`{{ build.SamplePowerShellStep.outputs.stdout }}` ``` phases: - name: 'build' steps: - name: SamplePowerShellStep action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: commands: - 'Write-Host "Hello"' ``` ## 문서 스키마 및 정의 다음은 문서의 YAML 스키마입니다. ``` name: (optional) description: (optional) schemaVersion: "string" phases: - name: "string" steps: - name: "string" action: "string" timeoutSeconds: integer onFailure: "Abort|Continue|Ignore" maxAttempts: integer inputs: ``` 문서의 스키마 정의는 다음과 같습니다. | 필드 | 설명 | 형식 | 필수 | | --- | --- | --- | --- | | 이름 | 문서의 이름. | 문자열 | No | | 설명 | 문서에 대한 설명. | 문자열 | No | | schemaVersion | 문서의 스키마 버전, 현재 1.0입니다. | 문자열 | 예 | | 단계 | 단계를 포함한 단계 목록. | List | 예 | 단계의 스키마 정의는 다음과 같습니다. | 필드 | 설명 | 형식 | 필수 | | --- | --- | --- | --- | | 이름 | 단계 이름. | 문자열 | 예 | | 단계(steps) | 단계의 단계 목록. | List | 예 | 단계의 스키마 정의는 다음과 같습니다. | 필드 | 설명 | 형식 | 필수 | 기본값 | | --- | --- | --- | --- | --- | | 이름 | 단계에 대한 사용자 정의 이름. | 문자열 | | | | 작업 | 단계를 실행하는 모듈과 관련된 키워드. | 문자열 | | | | timeoutSeconds | 실패하거나 재시도하기 전에 단계가 실행되는 시간(초) 또한 무한 타임아웃을 나타내는 -1 값을 지원합니다. 0 및 기타 음수 값은 허용되지 않습니다. | Integer | 아니요 | 7,200초(120분) | | onFailure | 장애 발생 시 단계에서 취해야 할 조치를 지정합니다. 유효한 값은 다음과 같습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-use-documents.html) | 문자열 | No | 중단 | | maxAttempts | 단계가 실패하기 전까지 허용되는 최대 시도 횟수. | Integer | 아니요 | 1 | | 입력 | 작업 모듈이 단계를 실행하는 데 필요한 파라미터를 포함. | Dict | 예 | | ## 문서 예제 다음 예제는 대상 운영 체제에 대한 작업을 수행하는 AWSTOE 구성 요소 문서를 보여줍니다. ------ #### [ Linux ] **예제 1: 사용자 지정 바이너리 파일 실행** 다음은 Linux 인스턴스에서 사용자 지정 바이너리 파일을 다운로드하고 실행하는 예제 문서입니다. ``` name: LinuxBin description: Download and run a custom Linux binary file. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ Windows ] **예제 1: Windows 업데이트 설치** 다음은 사용 가능한 모든 Windows 업데이트를 설치하고, 구성 스크립트를 실행하고, AMI를 생성하기 전에 변경 사항을 검증하고, AMI가 생성된 후 변경 사항을 테스트하는 예제 문서입니다. ``` name: RunConfig_UpdateWindows description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.' schemaVersion: 1.0 phases: - name: build steps: - name: DownloadConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/config.ps1' destination: 'C:\config.ps1' - name: RunConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{build.DownloadConfigScript.inputs[0].destination}}' - name: RebootAfterConfigApplied action: Reboot inputs: delaySeconds: 60 - name: InstallWindowsUpdates action: UpdateOS - name: validate steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: Cleanup action: DeleteFile onFailure: Abort maxAttempts: 3 inputs: - path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}' - name: test steps: - name: DownloadTestConfigScript action: S3Download timeoutSeconds: 60 onFailure: Abort maxAttempts: 3 inputs: - source: 's3://customer-bucket/testConfig.ps1' destination: 'C:\testConfig.ps1' - name: ValidateConfigScript action: ExecutePowerShell timeoutSeconds: 120 onFailure: Abort maxAttempts: 3 inputs: file: '{{test.DownloadTestConfigScript.inputs[0].destination}}' ``` **예제 2: Windows 인스턴스 AWS CLI 에 설치** 다음은 설정 파일을 사용하여 Windows 인스턴스 AWS CLI 에를 설치하는 예제 문서입니다. ``` name: InstallCLISetUp description: Install &CLI; using the setup file schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLISetup.exe destination: C:\Windows\temp\AWSCLISetup.exe - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '/install' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` **예제 3: MSI 설치 관리자를 AWS CLI 사용하여 설치** 다음은 MSI 설치 관리자를 AWS CLI 사용하여를 설치하는 예제 문서입니다. ``` name: InstallCLIMSI description: Install &CLI; using the MSI installer schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://aws-cli/AWSCLI64PY3.msi destination: C:\Windows\temp\AWSCLI64PY3.msi - name: Install action: ExecuteBinary onFailure: Continue inputs: path: 'C:\Windows\System32\msiexec.exe' arguments: - '/i' - '{{ build.Download.inputs[0].destination }}' - '/quiet' - '/norestart' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ #### [ macOS ] **예제 1: 사용자 지정 macOS 바이너리 파일 실행** 다음은 macOS 인스턴스에서 사용자 지정 바이너리 파일을 다운로드하고 실행하는 예제 문서입니다. ``` name: macOSBin description: Download and run a binary file on macOS. schemaVersion: 1.0 phases: - name: build steps: - name: Download action: S3Download inputs: - source: s3://amzn-s3-demo-source-bucket/myapplication destination: /tmp/myapplication - name: Enable action: ExecuteBash onFailure: Continue inputs: commands: - 'chmod u+x {{ build.Download.inputs[0].destination }}' - name: Install action: ExecuteBinary onFailure: Continue inputs: path: '{{ build.Download.inputs[0].destination }}' arguments: - '--install' - name: Delete action: DeleteFile inputs: - path: '{{ build.Download.inputs[0].destination }}' ``` ------ # 사용자 지정 구성 요소 문서에서 변수 사용 변수를 사용하면 애플리케이션 전체에서 사용할 수 있는 의미 있는 이름으로 데이터에 레이블을 지정할 수 있습니다. 복잡한 워크플로에 대해 간단하고 읽기 쉬운 형식으로 사용자 지정 변수를 정의하고 AWSTOE 구성 요소의 YAML 애플리케이션 구성 요소 문서에서 참조할 수 있습니다. 이 섹션에서는 구문, 이름 제약 조건 및 예제 AWSTOE 를 포함하여 YAML 애플리케이션 구성 요소 문서에서 구성 요소의 변수를 정의하는 데 도움이 되는 정보를 제공합니다. ## 상수 상수는 한 번 정의하면 수정하거나 재정의할 수 없는 변경 불가능한 변수입니다. 상수는 AWSTOE 문서의 `constants` 섹션에 있는 값을 사용하여 정의할 수 있습니다. **상수 이름 지정 규칙** + 이름은 3\$1128자 이내로 작성해야 합니다. + 이름에는 영숫자(A-Z, a-z, 0-9), 하이픈(-) 또는 밑줄(\$1)만 포함될 수 있습니다. + 단, 문서 내에서 고유 이름을 갖도록 합니다. + 이름은 YAML 문자열로 지정되어야 합니다. **구문** ``` constants: - : type: value: ``` | 키 이름 | 필수 | 설명 | | --- | --- | --- | | `name` | 예 | 상수의 이름. 문서에 대해 고유해야 합니다(다른 파라미터 이름 또는 상수와 같지 않아야 함). | | `value` | 예 | 상수의 값. | | `type` | 예 | 상수의 유형. 지원되는 string 유형 | **문서 내 참조 상수 값** 다음과 같이 YAML 문서 내의 단계 또는 루프 입력에서 상수를 참조할 수 있습니다. + 상수 참조는 대/소문자를 구분하며 이름이 정확하게 일치해야 합니다. + 이름은 이중 중괄호 `{{` *MyConstant* `}}`로 묶어야 합니다. + 중괄호 내에는 공백이 허용되며 자동으로 잘립니다. 예를 들어, 다음 참조는 모두 유효합니다. `{{ MyConstant }}`, `{{ MyConstant}}`, `{{MyConstant }}`, `{{MyConstant}}` + YAML 문서의 참조는 문자열(작은따옴표 또는 큰따옴표로 묶음)로 지정해야 합니다. 예: `- {{ MyConstant }}`(은)는 문자열로 식별되지 않으므로 유효하지 않습니다. 그러나 `- '{{ MyConstant }}'` 및 `- "{{ MyConstant }}"` 참조는 모두 유효합니다. **예제** 단계 입력에서 참조되는 상수 ``` name: Download AWS CLI version 2 schemaVersion: 1.0 constants: - Source: type: string value: https://awscli.amazonaws.com/AWSCLIV2.msi phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` 루프 입력에서 참조되는 상수 ``` name: PingHosts schemaVersion: 1.0 constants: - Hosts: type: string value: 127.0.0.1,amazon.com phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ## 파라미터 파라미터는 호출 애플리케이션이 런타임에 제공할 수 있는 설정을 포함하는 변경 가능한 변수입니다. YAML 문서의 `Parameters` 섹션에서 파라미터를 정의할 수 있습니다. **파라미터 이름 규칙** + 이름은 3\$1128자 이내로 작성해야 합니다. + 이름에는 영숫자(A-Z, a-z, 0-9), 하이픈(-) 또는 밑줄(\$1)만 포함될 수 있습니다. + 단, 문서 내에서 고유 이름을 갖도록 합니다. + 이름은 YAML 문자열로 지정되어야 합니다. ### 구문 ``` parameters: - : type: default: description: ``` | 키 이름 | 필수 | 설명 | | --- | --- | --- | | `name` | 예 | 파라미터의 이름입니다. 문서에 대해 고유해야 합니다(다른 파라미터 이름 또는 상수와 같지 않아야 함). | | `type` | 예 | 파라미터의 데이터 유형입니다. 지원되는 유형에는 `string`(이)가 있습니다. | | `default` | 아니요 | 파라미터의 기본값입니다. | | `description` | 아니요 | 파라미터에 대해 설명합니다. | ### 문서의 참조 파라미터 값 다음과 같이 YAML 문서 내의 단계 또는 루프 입력에서 파라미터를 참조할 수 있습니다. + 파라미터 참조는 대/소문자를 구분하며 이름이 정확하게 일치해야 합니다. + 이름은 `{{` *MyParameter* `}}`라는 이중 중괄호로 묶어야 합니다. + 중괄호 내에는 공백이 허용되며 자동으로 잘립니다. 예를 들어, 다음 참조는 모두 유효합니다. `{{ MyParameter }}`, `{{ MyParameter}}`, `{{MyParameter }}`, `{{MyParameter}}` + YAML 문서의 참조는 문자열(작은따옴표 또는 큰따옴표로 묶음)로 지정해야 합니다. 예: `- {{ MyParameter }}`(은)는 문자열로 식별되지 않으므로 유효하지 않습니다. 그러나 `- '{{ MyParameter }}'` 및 `- "{{ MyParameter }}"` 참조는 모두 유효합니다. **예제** 다음 예제는 YAML 문서에서 파라미터를 사용하는 방법을 보여 줍니다. + 단계별 입력의 파라미터를 참조하세요. ``` name: Download AWS CLI version 2 schemaVersion: 1.0 parameters: - Source: type: string default: 'https://awscli.amazonaws.com/AWSCLIV2.msi' description: The AWS CLI installer source URL. phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` + 루프 입력의 파라미터를 참조하세요. ``` name: PingHosts schemaVersion: 1.0 parameters: - Hosts: type: string default: 127.0.0.1,amazon.com description: A comma separated list of hosts to ping. phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ### 런타임 시 파라미터 재정의 키-값 페어와 AWS CLI 함께의 `--parameters` 옵션을 사용하여 런타임 시 파라미터 값을 설정할 수 있습니다. + 파라미터 키-값 쌍을 등호(=)로 구분하여 이름과 값으로 지정합니다. + 여러 파라미터는 쉼표로 구분해야 합니다. + YAML 구성 요소 문서에 없는 파라미터 이름은 무시됩니다. + 파라미터 이름과 값이 모두 필요합니다. **중요** 구성 요소 파라미터는 일반 텍스트 값이며 AWS CloudTrail에 기록됩니다. AWS Secrets Manager 또는 AWS Systems Manager 파라미터 스토어를 사용하여 보안 암호를 저장하는 것이 좋습니다. Secrets Manager에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [Secrets Manager란 무엇입니까?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)를 참조하십시오. AWS Systems Manager Parameter Store에 대한 자세한 내용은 *AWS Systems Manager 사용 설명서*의 [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) 섹션을 참조하십시오. #### 구문 ``` --parameters name1=value1,name2=value2... ``` | CLI 옵션 | 필수 | 설명 | | --- | --- | --- | | --parameters *name*=*value*,... | 아니요 | 이 옵션은 파라미터 이름을 키로 사용하여 키-값 페어의 목록을 가져옵니다. | **예제** 다음 예제는 YAML 문서에서 파라미터를 사용하는 방법을 보여 줍니다. + 이 `--parameter` 옵션에 지정된 파라미터 키-값 쌍은 유효하지 않습니다. ``` --parameters ntp-server= ``` + AWS CLI에서 `--parameter` 옵션을 사용하여 하나의 파라미터 키-값 쌍을 설정합니다. ``` --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com ``` + AWS CLI에서 `--parameter` 옵션을 사용하여 여러 파라미터 키-값 쌍을 설정합니다. ``` --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com ``` ## Systems Manager Parameter Store 파라미터 사용 변수 앞에 AWS Systems Manager 를 붙여 구성 요소 문서에서 Parameter Store 파라미터(SSM 파라미터)를 참조할 수 있습니다`aws:ssm`. 예: `{{ aws:ssm:/my/param }}`는 SSM 파라미터의 값으로 해석됩니다`/my/param`. 이 기능은 다음 SSM 파라미터 유형을 지원합니다. + 문자열 - AWSTOE 문자열 유형에 매핑됩니다. + StringList - 유형에 매핑됩니다 AWSTOE `stringList`. + SecureString - AWSTOE 문자열 유형에 매핑됩니다. 파라미터 스토어에 대한 자세한 내용은 *AWS Systems Manager 사용 설명서*의 [AWS Systems Manager 파라미터 스토어](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)를 참조하세요. SSM 파라미터를 사용하여 AWS Secrets Manager 보안 암호를 참조할 수도 있습니다`SecureString`. 예를 들어 `{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`입니다. 자세한 내용은 [파라미터 스토어 파라미터에서 보안 암호 참조를 AWS Secrets Manager 참조하세요](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html). **중요** Image Builder는 로그에서 `SecureString` 파라미터 해상도를 제외합니다. 그러나 구성 요소 문서에서 실행된 명령을 통해 민감한 정보가 기록되지 않도록 할 책임도 있습니다. 예를 들어 보안 문자열과 함께 `echo` 명령을 사용하는 경우 명령은 로그에 일반 텍스트 값을 씁니다. ### 필수 IAM 권한 구성 요소에서 Systems Manager 파라미터를 사용하려면 인스턴스 역할에 파라미터 리소스 ARN에 대한 `ssm:GetParameter` 권한이 있어야 합니다. 예제: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ssm:GetParameter", "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" } ] } ``` ------ 암호화된 값에 액세스하려면 다음 권한도 필요합니다. + 고객 관리형으로 암호화된 `SecureString` 파라미터 또는 AWS Secrets Manager 값에 `kms:Decrypt`를 추가합니다 AWS KMS key. + Secrets Manager 보안 암호를 참조하는 `secretsmanager:GetSecretValue` 경우를 추가합니다. ### 구성 요소 문서에서 SSM 파라미터 참조 다음 예제에서는 구성 요소에서 Systems Manager 파라미터의 Systems Manager 파라미터 스토어 파라미터를 참조하는 방법을 보여줍니다. ``` name: UseSSMParameterVariable description: This is a sample component document that prints out the value of an SSM Parameter. Never do this for a SecureString parameter. schemaVersion: 1.0 phases: - name: verify steps: - name: EchoParameterValue action: ExecuteBash inputs: commands: - echo "Log SSM parameter name: /my/test/param, value {{ aws:ssm:/my/test/param }}." ``` ### SSM 파라미터에 대한 동적 런타임 변수 확인 AWSTOE는 변수 참조 내에서 런타임 시 값을 조작하거나 변환하는 데 사용할 수 있는 다음과 같은 내장 함수를 제공합니다. #### 함수 확인 `resolve` 함수는 다른 변수 참조 내부의 변수 참조를 해석하여 동적 변수 이름 참조를 허용합니다. 이는 파라미터 경로의 일부가 가변적이고 문서 파라미터로 전달될 수 있는 SSM 파라미터로 작업할 때 유용합니다. `resolve` 함수는 SSM 파라미터의 이름 부분에 대한 동적 확인만 지원합니다. ##### 구문 다음 예제`dynamic_variable`의는 SSM 파라미터의 이름을 나타내며 다음 중 하나여야 합니다. + SSM 파라미터 참조(예: `aws:ssm:/my/param`) + 구성 요소 문서 파라미터 참조(예: `parameter-name`) ``` {{ aws:ssm:resolve(dynamic_variable) }} ``` ##### 예: 런타임 시 SSM 파라미터 확인 다음 예제에서는 YAML 구성 요소 문서에서 `resolve` 함수를 사용하는 방법을 보여줍니다. ``` name: SsmParameterTest description: This component verifies an SSM parameter variable reference with the echo command. schemaVersion: 1.0 parameters: - parameter-name: type: string description: "test" phases: - name: validate steps: - name: PrintDynamicVariable action: ExecuteBash inputs: commands: - echo "{{ aws:ssm:resolve(parameter-name) }}" ``` # 에서 조건부 구문 사용 AWSTOE 조건부 구문은 지정된 조건부 표현식이 `true` 또는 `false`로 평가되는지 여부에 따라 구성 요소 문서에서 다양한 작업을 수행합니다. `if` 구문을 사용하여 구성 요소 문서의 실행 흐름을 제어할 수 있습니다. ## if 구문 `if` 구문을 사용하여 단계를 실행해야 하는지 여부를 평가할 수 있습니다. 기본적으로 `if` 조건식이 `true`로 평가되면 AWSTOE 는 단계를 실행하고 조건이 `false`로 평가되면 AWSTOE 는 단계를 건너뜁니다. 단계를 건너뛰면 AWSTOE 가 단계와 문서가 성공적으로 실행되었는지 평가할 때 성공 단계로 처리됩니다. **참고** 단계가 재시작을 트리거하더라도 `if` 문은 한 번만 평가됩니다. 단계가 다시 시작되면 `if` 문이 이미 평가되었음을 인식하고 중단된 위치에서 계속됩니다. ### 구문 ``` if: - : [then: ] [else: ] ``` | 키 이름 | 필수 | 설명 | | --- | --- | --- | | 조건식 | 예 | 조건식에는 최상위 수준에서 다음 유형의 연산자 중 정확히 하나가 포함될 수 있습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-conditional-constructs.html) 표현식이 여러 조건을 충족해야 하는 경우 논리 연산자를 사용하여 조건을 지정합니다. | | then | 아니요 | 조건식이 `true`로 평가되는 경우 수행할 작업을 정의합니다. | | else | 아니요 | 조건식이 `false`로 평가되는 경우 수행할 작업을 정의합니다. | | 단계 작업 | 조건부 | `then` 또는 `else`를 사용할 때는 다음 단계 작업 중 하나를 지정해야 합니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-conditional-constructs.html) | **예제 1: 패키지 설치** AWSTOE 구성 요소 문서의 다음 예제 단계는 논리 연산자를 사용하여 파라미터 값을 테스트하고 패키지의 압축이 풀린 경우 적절한 패키지 관리자 명령을 실행하여 애플리케이션을 설치합니다. ``` - name: InstallUnzipAptGet action: ExecuteBash if: and: - binaryExists: 'apt-get' - not: binaryExists: 'unzip' inputs: commands: - sudo apt-get update - sudo apt-get install -y unzip - name: InstallUnzipYum action: ExecuteBash if: and: - binaryExists: 'yum' - not: binaryExists: 'unzip' inputs: commands: - sudo yum install -y unzip - name: InstallUnzipZypper action: ExecuteBash if: and: - binaryExists: 'zypper' - not: binaryExists: 'unzip' inputs: commands: - sudo zypper refresh - sudo zypper install -y unzip ``` **예제 2: 단계 건너뛰기** 다음 예제에서는 단계를 건너뛰는 두 가지 방법을 보여줍니다. 하나는 논리적 연산자를 사용하고 다른 하나는 `Skip` 단계 작업과 비교 연산자를 사용합니다. ``` # Creates a file if it does not exist using not - name: CreateMyConfigFile-1 action: ExecuteBash if: not: fileExists: '/etc/my_config' inputs: commands: - echo "Hello world" > '/etc/my_config' # Creates a file if it does not exist using then and else - name: CreateMyConfigFile-2 action: ExecuteBash if: fileExists: '/etc/my_config' then: Skip else: Execute inputs: commands: - echo "Hello world" > '/etc/my_config' ``` # AWSTOE 구성 요소 문서에서 비교 연산자 사용 다음 비교 연산자를 **[Assert](toe-action-modules.md#action-modules-assertion)** 작업 모듈 및 [if 구문구문](toe-conditional-constructs.md#toe-conditional-if)를 사용하는 조건식과 함께 사용할 수 있습니다. 비교 연산자는 예를 들어 `stringIsEmpty`와 같은 단일 값으로 작동하거나 기준 값을 두 번째 값(변수 값)과 비교하여 조건식이 `true` 또는 `false`로 평가되는지 여부를 결정할 수 있습니다. 두 값에 대해 비교가 작동하는 경우 두 번째 값은 체인 변수일 수 있습니다. 다른 유형의 값을 비교할 때 비교 전에 다음과 같은 값 변환이 발생할 수 있습니다. + 숫자 비교의 경우 변수 값이 문자열인 경우는 평가 전에 문자열을 숫자로 AWSTOE 변환합니다. 변환이 불가능한 경우 비교에서 `false`를 반환합니다. 예를 들어 변수 값이 `"1.0"`인 경우 변환이 작동하지만 변수 값이 `"a10"`인 경우 변환이 실패합니다. + 문자열 비교의 경우 변수 값이 숫자인 경우는 평가 전에 문자열로 AWSTOE 변환합니다. ## 문자열 비교 다음 비교 연산자는 문자열을 사용하여 값을 비교하거나, 스페이스 또는 빈 문자열을 테스트하거나, 입력 값을 정규식 패턴과 비교합니다. 문자열 비교에서는 대/소문자를 구분하지 않으며 문자열 입력의 시작 또는 끝에 있는 스페이스를 제거하지 않습니다. **문자열 비교 연산자** + [stringIsEmpty](#stringIsEmpty) + [stringIsWhitespace](#stringIsWhitespace) + [stringEquals](#stringEquals) + [stringLessThan](#stringLessThan) + [stringLessThanEquals](#stringLessThanEquals) + [stringGreaterThan](#stringGreaterThan) + [stringGreaterThanEquals](#stringGreaterThanEquals) + [patternMatches](#patternMatches) **stringIsEmpty** 지정된 문자열에 문자가 없는 경우 `stringIsEmpty` 연산자가 `true`를 반환합니다. 예제: ``` # Evaluates to true stringIsEmpty: "" # Evaluates to false stringIsEmpty: " " # Evaluates to false stringIsEmpty: "Hello." ``` **stringIsWhitespace** `stringIsWhitespace`에 지정된 문자열에 스페이스만 포함되어 있는지 테스트합니다. 예제: ``` # Evaluates to true stringIsWhitespace: " " # Evaluates to false stringIsWhitespace: "" # Evaluates to false stringIsWhitespace: " Hello?" ``` **stringEquals** `stringEquals`에 지정된 문자열이 `value` 파라미터에 지정된 문자열과 정확히 일치하는지 테스트합니다. 예제: ``` # Evaluates to true stringEquals: 'Testing, testing...' value: 'Testing, testing...' # Evaluates to false stringEquals: 'Testing, testing...' value: 'Hello again.' # Evaluates to false stringEquals: 'Testing, testing...' value: 'TESTING, TESTING....' # Evaluates to false stringEquals: 'Testing, testing...' value: ' Testing, testing...' # Evaluates to false stringEquals: 'Testing, testing...' value: 'Testing, testing... ' ``` **stringLessThan** `stringLessThan`에 지정된 문자열이 `value` 파라미터에 지정된 문자열보다 작은지 테스트합니다. 예제: ``` # Evaluates to true # This comparison operator isn't case sensitive stringlessThan: 'A' value: 'a' # Evaluates to true - 'a' is less than 'b' stringlessThan: 'b' value: 'a' # Evaluates to true # Numeric strings compare as less than alphabetic strings stringlessThan: 'a' value: '0' # Evaluates to false stringlessThan: '0' value: 'a' ``` **stringLessThanEquals** `stringLessThanEquals`에 지정된 문자열이 `value` 파라미터에 지정된 문자열보다 작거나 같은지 테스트합니다. 예제: ``` # Evaluates to true - 'a' is equal to 'a' stringLessThanEquals: 'a' value: 'a' # Evaluates to true - since the comparison isn't case sensitive, 'a' is equal to 'A' stringLessThanEquals: 'A' value: 'a' # Evaluates to true - 'a' is less than 'b' stringLessThanEquals: 'b' value: 'a' # Evaluates to true - '0' is less than 'a' stringLessThanEquals: 'a' value: '0' # Evaluates to false - 'a' is greater than '0' stringLessThanEquals: '0' value: 'a' ``` **stringGreaterThan** `stringGreaterThan`에 지정된 문자열이 `value` 파라미터에 지정된 문자열보다 큰지 테스트합니다. 예제: ``` # Evaluates to false - since the comparison isn't case sensitive, 'A' is equal to 'a' stringGreaterThan: 'a' value: 'A' # Evaluates to true - 'b' is greater than 'a' stringGreaterThan: 'a' value: 'b' # Evaluates to true - 'a' is greater than '0' stringGreaterThan: '0' value: 'a' # Evaluates to false - '0' is less than 'a' stringGreaterThan: 'a' value: '0' ``` **stringGreaterThanEquals** `stringGreaterThanEquals`에 지정된 문자열이 `value` 파라미터에 지정된 문자열보다 크거나 같은지 테스트합니다. 예제: ``` # Evaluates to true - 'a' is equal to 'A' stringGreaterThanEquals: 'A' value: 'a' # Evaluates to true - 'b' is greater than 'a' stringGreaterThanEquals: 'a' value: 'b' # Evaluates to true - 'a' is greater than '0' stringGreaterThanEquals: '0' value: 'a' # Evaluates to false - '0' is less than 'a' stringGreaterThanEquals: 'a' value: '0' ``` **patternMatches** `value` 파라미터에 지정된 문자열이 `patternMatches`에 지정된 정규식 패턴과 일치하는지 테스트합니다. 비교에서 RE2 구문을 준수하는 [Golang regexp 패키지](https://pkg.go.dev/regexp)를 사용합니다. RE2 규칙에 대한 자세한 내용은 *GitHub*의 [Google / re2](https://github.com/google/re2/wiki/Syntax) 리포지토리를 참조하세요. 다음 예제에서는 `true`를 반환하는 패턴 일치를 보여줍니다. ``` patternMatches: '^[a-z]+$' value: 'ThisIsValue' ``` ## 숫자 비교 다음 비교 연산자는 숫자에 적용됩니다. 이러한 연산자에 대해 제공된 값은 YAML 사양에 따라 다음 유형 중 하나여야 합니다. 숫자 비교에 대한 지원은 예를 들어 [func(\$1Float) Cmp](https://pkg.go.dev/math/big#Float.Cmp)와 같은 golang big 패키지 비교 연산자를 사용합니다. + Integer + Float(-1.7e\$1308\$1\$11.7e\$1308의 숫자를 지원하는 float64 기반) + 다음 정규식 패턴과 일치하는 문자열: `^[-+]?([0-9]+[.])?[0-9]+$` **숫자 비교 연산자** + [numberEquals](#numberEquals) + [numberLessThan](#numberLessThan) + [numberLessThanEquals](#numberLessThanEquals) + [numberGreaterThan](#numberGreaterThan) + [numberGreaterThanEquals](#numberGreaterThanEquals) **numberEquals** `numberEquals`에 지정된 숫자가 `value` 파라미터에 지정된 숫자와 동일한지 테스트합니다. 다음 예제 비교에서는 모두 `true`를 반환합니다. ``` # Values provided as a positive number numberEquals: 1 value: 1 # Comparison value provided as a string numberEquals: '1' value: 1 # Value provided as a string numberEquals: 1 value: '1' # Values provided as floats numberEquals: 5.0 value: 5.0 # Values provided as a negative number numberEquals: -1 value: -1 ``` **numberLessThan** `numberLessThan`에 지정된 숫자가 `value` 파라미터에 지정된 숫자보다 작은지 테스트합니다. 예제: ``` # Evaluates to true numberLessThan: 2 value: 1 # Evaluates to true numberLessThan: 2 value: 1.9 # Evaluates to false numberLessThan: 2 value: '2' ``` **numberLessThanEquals** `numberLessThanEquals`에 지정된 숫자가 `value` 파라미터에 지정된 숫자보다 작거나 같은지 테스트합니다. 예제: ``` # Evaluates to true numberLessThanEquals: 2 value: 1 # Evaluates to true numberLessThanEquals: 2 value: 1.9 # Evaluates to true numberLessThanEquals: 2 value: '2' # Evaluates to false numberLessThanEquals: 2 value: 2.1 ``` **numberGreaterThan** `numberGreaterThan`에 지정된 숫자가 `value` 파라미터에 지정된 숫자보다 큰지 테스트합니다. 예제: ``` # Evaluates to true numberGreaterThan: 1 value: 2 # Evaluates to true numberGreaterThan: 1 value: 1.1 # Evaluates to false numberGreaterThan: 1 value: '1' ``` **numberGreaterThanEquals** `numberGreaterThanEquals`에 지정된 숫자가 `value` 파라미터에 지정된 숫자보다 크거나 같은지 테스트합니다. 예제: ``` # Evaluates to true numberGreaterThanEquals: 1 value: 2 # Evaluates to true numberGreaterThanEquals: 1 value: 1.1 # Evaluates to true numberGreaterThanEquals: 1 value: '1' # Evaluates to false numberGreaterThanEquals: 1 value: 0.8 ``` ## 파일 확인 다음 비교 연산자는 파일 해시를 확인하거나 파일 또는 폴더가 있는지 확인합니다. **파일 및 폴더 연산자** + [binaryExists](#binaryExists) + [fileExists](#fileExists) + [folderExists](#folderExists) + [fileMD5Equals](#fileMD5Equals) + [fileSHA1Equals](#fileSHA1Equals) + [fileSHA256Equals](#fileSHA256Equals) + [fileSHA512Equals](#fileSHA512Equals) **binaryExists** 현재 경로에서 애플리케이션을 사용할 수 있는지 테스트합니다. 예제: ``` binaryExists: 'foo' ``` Linux 및 macOS 시스템에서 *foo*라는 애플리케이션의 경우 bash 명령 **type *foo* >/dev/null 2>&1**와 동일하게 작동합니다. 여기서 **\$1? == 0**은 성공적인 비교를 나타냅니다. Windows 시스템에서 *foo*라는 애플리케이션의 경우 PowerShell 명령 **& C:\$1Windows\$1System32\$1where.exe /Q *foo***와 동일하게 작동합니다. 여기서 **\$1LASTEXITCODE = 0**은 성공적인 비교를 나타냅니다. **fileExists** 파일이 지정된 경로에 존재하는지 테스트합니다. 절대 또는 상대 경로를 제공할 수 있습니다. 지정한 위치가 존재하고 파일인 경우 비교는 `true`로 평가됩니다. 예제: ``` fileExists: '/path/to/file' ``` Linux 및 macOS 시스템에서는 bash 명령 **-d */path/to/file***와 동일하게 작동합니다. 여기서 **\$1? == 0**은 성공적인 비교를 나타냅니다. Windows 시스템에서는 PowerShell 명령 **Test-Path -Path '*C:\$1path\$1to\$1file*' -PathType 'Leaf'**와 동일하게 작동합니다. **folderExists** 폴더가 지정된 경로에 존재하는지 테스트합니다. 절대 또는 상대 경로를 제공할 수 있습니다. 지정한 위치가 존재하고 폴더인 경우 비교는 `true`로 평가됩니다. 예제: ``` folderExists: '/path/to/folder' ``` Linux 및 macOS 시스템에서는 bash 명령 **-d */path/to/folder***와 동일하게 작동합니다. 여기서 **\$1? == 0**은 성공적인 비교를 나타냅니다. Windows 시스템에서는 PowerShell 명령 **Test-Path -Path '*C:\$1path\$1to\$1folder*' -PathType 'Container'**와 동일하게 작동합니다. **fileMD5Equals** 파일의 MD5 해시가 지정된 값과 동일한지 테스트합니다. 예제: ``` fileMD5Equals: '' path: '/path/to/file' ``` **fileSHA1Equals** 파일의 SHA1 해시가 지정된 값과 동일한지 테스트합니다. 예제: ``` fileSHA1Equals: '' path: '/path/to/file' ``` **fileSHA256Equals** 파일의 SHA256 해시가 지정된 값과 동일한지 테스트합니다. 예제: ``` fileSHA256Equals: '' path: '/path/to/file' ``` **fileSHA512Equals** 파일의 SHA512 해시가 지정된 값과 동일한지 테스트합니다. 예제: ``` fileSHA512Equals: '' path: '/path/to/file' ``` # AWSTOE 구성 요소 문서에서 논리 연산자 사용 다음 논리 연산자를 사용하여 구성 요소 문서에서 조건식을 추가하거나 수정할 수 있습니다.는 조건이 지정된 순서대로 조건식을 AWSTOE 평가합니다. 구성 요소 문서의 비교 연산자에 대한 자세한 내용은 [AWSTOE 구성 요소 문서에서 비교 연산자 사용](toe-comparison-operators.md) 섹션을 참조하세요. **및** `and` 연산자를 사용하면 두 개 이상의 비교를 단일 표현식으로 평가할 수 있습니다. 이 표현식은 목록의 모든 조건이 true일 때 `true`로 평가됩니다. 그렇지 않으면 표현식은 `false`로 평가됩니다. **예시:** 다음 예제에서는 문자열과 숫자의 두 가지 비교를 수행합니다. 두 비교 모두 true이므로 표현식은 true로 평가됩니다. ``` and: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 1 ``` 다음 예제에서도 두 가지 비교를 수행합니다. 첫 번째 비교는 false로, 이 시점에서 평가가 중지되고 두 번째 비교는 건너뜁니다. 표현식은 `false`로 평가됩니다. ``` and: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` **또는** `or` 연산자를 사용하면 두 개 이상의 비교를 단일 표현식으로 평가할 수 있습니다. 표현식은 지정된 비교 중 하나가 true일 때 `true`로 평가됩니다. 지정된 비교 중 어느 것도 `true`로 평가되지 않으면 표현식은 `false`로 평가됩니다. **예시:** 다음 예제에서는 문자열과 숫자의 두 가지 비교를 수행합니다. 첫 번째 비교는 true이므로 표현식은 `true`로 평가되고 두 번째 비교는 건너뜁니다. ``` or: - stringEquals: 'test_string' value: 'test_string' - numberEquals: 1 value: 3 ``` 다음 예제에서도 두 가지 비교를 수행합니다. 첫 번째 비교는 false이며 평가는 계속됩니다. 두 번째 비교는 true이므로 표현식은 `true`로 평가됩니다. ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 1 ``` 마지막 예제에서는 두 비교가 모두 false이므로 표현식이 `false`로 평가됩니다. ``` or: - stringEquals: 'test_string' value: 'Hello world!' - numberEquals: 1 value: 3 ``` **not** `not` 연산자를 사용하면 단일 비교를 부정할 수 있습니다. 비교가 false인 경우 표현식이 `true`로 평가됩니다. 비교가 true인 경우 표현식이 `false`로 평가됩니다. **예시:** 다음 예제에서는 문자열 비교를 수행합니다. 비교가 false이므로 표현식이 `true`로 평가됩니다. ``` not: - stringEquals: 'test_string' value: 'Hello world!' ``` 다음 예제에서도 문자열 비교를 수행합니다. 비교가 true이므로 표현식이 `false`로 평가됩니다. ``` not: - stringEquals: 'test_string' value: 'test_string' ``` # 에서 반복 구문 사용 AWSTOE 이 섹션에서는 AWSTOE에서 반복 구문을 작성하는 데 도움이 되는 정보를 제공합니다. 반복 구문은 반복되는 명령 시퀀스를 정의합니다. AWSTOE에서는 다음과 같은 유형의 반복 구문을 사용할 수 있습니다. + `for` 구문 - 한정된 정수 시퀀스를 반복합니다. + `forEach` 구문 + 입력 목록이 있는 `forEach` 루프 - 유한한 문자열 컬렉션을 반복합니다. + 구분된 목록이 있는 `forEach` 루프 - 구분 기호로 연결된 유한한 문자열 컬렉션을 반복합니다. **참고** 반복 구문은 문자열 데이터 유형만 지원합니다. **Topics** + [참조 반복 변수](#toe-loop-iteration-variables) + [반복 구문의 유형](#toe-loop-types) + [단계 필드](#toe-loop-step-fields) + [단계별 및 반복 출력](#toe-loop-step-output) ## 참조 반복 변수 현재 반복 변수의 인덱스와 값을 참조하려면 반복 구문이 포함된 단계의 입력 본문 내에서 참조 표현식 `{{ loop.* }}`(을)를 사용해야 합니다. 이 표현식은 다른 단계의 반복 구문의 반복 변수를 참조하는 데 사용할 수 없습니다. 참조 표현식은 다음 멤버로 구성됩니다. + `{{ loop.index }}` - `0`에서 인덱싱된 현재 반복의 순서 위치입니다. + `{{ loop.value }}` - 현재 반복 변수와 관련된 값입니다. ### 루프 이름 모든 반복 구문에는 식별을 위한 선택적 이름 필드가 있습니다. 루프 이름을 제공하면 이 이름을 사용하여 단계 입력 본문에 있는 반복 변수를 참조할 수 있습니다. 명명된 반복의 반복 인덱스 및 값을 참조하려면 단계의 입력 본문에서 `{{ .* }}` 및 `{{ loop.* }}`(을)를 사용하세요. 이 표현식은 다른 단계의 명명된 반복 구문을 참조하는 데 사용할 수 없습니다. 참조 표현식은 다음 멤버로 구성됩니다. + `{{ .index }}` - `0`에서 인덱싱되는 명명된 반복의 현재 반복의 순서 위치입니다. + `{{ .value }}` - 명명된 루프의 현재 반복 변수와 관련된 값입니다. ### 참조 표현식 해결 는 다음과 같이 참조 표현식을 AWSTOE 확인합니다. + `{{ .* }}` - 다음 로직을 사용하여이 표현식을 AWSTOE 해결합니다. + 현재 실행 중인 단계의 루프가 `` 값과 일치하면 참조 표현식은 현재 실행 중인 단계의 반복 구조로 해석됩니다. + ``에서 명명된 반복 구조가 현재 실행 중인 단계 내에 나타나는 경우 해당 구문으로 해석됩니다. + `{{ loop.* }}` - 현재 실행 중인 단계에 정의된 반복 구문을 사용하여 표현식을 AWSTOE 해결합니다. 루프가 포함되지 않은 단계에서 참조 표현식을 사용하는 경우 AWSTOE 는 표현식을 확인하지 않으며 대체 없이 단계에 표시됩니다. **참고** YAML 컴파일러에서 올바르게 해석되려면 참조 표현식을 큰따옴표로 묶어야 합니다. ## 반복 구문의 유형 이 섹션에서는 AWSTOE에서 사용할 수 있는 반복 구문 유형에 대한 정보와 예제를 제공합니다. **Topics** + [`for` 루프](#toe-loop-types-for) + [입력 목록이 있는 `forEach` 루프](#toe-loop-types-foreach) + [구분된 목록이 있는 `forEach` 루프](#toe-loop-types-foreach-delimited) ### `for` 루프 `for` 루프는 변수의 시작과 끝으로 윤곽이 그려진 경계 내에 지정된 정수 범위에 대해 반복됩니다. 반복 값은 세트 `[start, end]` 내에 있으며 경계 값을 포함합니다. AWSTOE 는 `start`, `end`및 `updateBy` 값을 확인하여 조합으로 인해 무한 루프가 발생하지 않도록 합니다. `for` 루프 스키마 ``` - name: "StepName" action: "ActionModule" loop: name: "string" for: start: int end: int updateBy: int inputs: ... ``` **`for` 루프 입력** | 필드 | 설명 | 형식 | 필수 | 기본값 | | --- | --- | --- | --- | --- | | `name` | 루프의 고유 이름. 동일한 단계의 다른 루프 이름과 비교하여 고유해야 합니다. | 문자열 | No | "" | | `start` | 반복 시작 값. 체인 표현식은 허용되지 않습니다. | Integer | 예 | 해당 사항 없음 | | `end` | 반복 종료 값. 체인 표현식은 허용되지 않습니다. | Integer | 예 | 해당 사항 없음 | | `updateBy` | 덧셈을 통해 반복 값이 업데이트되는 경우의 차이. 0이 아닌 음수 또는 양수여야 합니다. 체인 표현식은 허용되지 않습니다. | Integer | 예 | 해당 사항 없음 | `for` 루프 입력 예제 ``` - name: "CalculateFileUploadLatencies" action: "ExecutePowerShell" loop: for: start: 100000 end: 1000000 updateBy: 100000 inputs: commands: - | $f = new-object System.IO.FileStream c:\temp\test{{ loop.index }}.txt, Create, ReadWrite $f.SetLength({{ loop.value }}MB) $f.Close() - c:\users\administrator\downloads\latencyTest.exe --file c:\temp\test{{ loop.index }}.txt - AWS s3 cp c:\users\administrator\downloads\latencyMetrics.json s3://bucket/latencyMetrics.json - | Remove-Item -Path c:\temp\test{{ loop.index }}.txt Remove-Item -Path c:\users\administrator\downloads\latencyMetrics.json ``` ### 입력 목록이 있는 `forEach` 루프 `forEach` 루프는 문자열과 체인 표현식일 수 있는 명시적 값 목록에서 반복됩니다. 입력 목록 스키마가 있는 `forEach` 루프 ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: - "string" inputs: ... ``` **입력 목록 입력이 있는 `forEach` 루프** | 필드 | 설명 | 형식 | 필수 | 기본값 | | --- | --- | --- | --- | --- | | `name` | 루프의 고유 이름. 동일한 단계의 다른 루프 이름과 비교하여 고유해야 합니다. | 문자열 | No | "" | | `forEach` 루프 문자열 목록 | 반복할 문자열 목록. 연결된 표현식을 목록에서 문자열로 받아들입니다. YAML 컴파일러가 올바르게 해석하려면 체인 표현식을 큰따옴표로 묶어야 합니다. | 문자열 목록 | 예 | 해당 사항 없음 | 입력 목록이 있는 `forEach` 루프 예제 1 ``` - name: "ExecuteCustomScripts" action: "ExecuteBash" loop: name: BatchExecLoop forEach: - /tmp/script1.sh - /tmp/script2.sh - /tmp/script3.sh inputs: commands: - echo "Count {{ BatchExecLoop.index }}" - sh "{{ loop.value }}" - | retVal=$? if [ $retVal -ne 0 ]; then echo "Failed" else echo "Passed" fi ``` 입력 목록이 있는 `forEach` 루프 예제 2 ``` - name: "RunMSIWithDifferentArgs" action: "ExecuteBinary" loop: name: MultiArgLoop forEach: - "ARG1=C:\Users ARG2=1" - "ARG1=C:\Users" - "ARG1=C:\Users ARG3=C:\Users\Administrator\Documents\f1.txt" inputs: commands: path: "c:\users\administrator\downloads\runner.exe" args: - "{{ MultiArgLoop.value }}" ``` 입력 목록이 있는 `forEach` 루프 예제 3 ``` - name: "DownloadAllBinaries" action: "S3Download" loop: name: MultiArgLoop forEach: - "bin1.exe" - "bin10.exe" - "bin5.exe" inputs: - source: "s3://bucket/{{ loop.value }}" destination: "c:\temp\{{ loop.value }}" ``` ### 구분된 목록이 있는 `forEach` 루프 루프는 구분자로 구분된 값을 포함하는 문자열을 반복합니다. 문자열의 구성 요소를 반복하려면 구분 기호를 AWSTOE 사용하여 문자열을 반복에 적합한 배열로 분할합니다. 구분된 목록 스키마가 있는 `forEach` 루프 ``` - name: "StepName" action: "ActionModule" loop: name: "string" forEach: list: "string" delimiter: ".,;:\n\t -_" inputs: ... ``` **구분된 목록 입력이 있는 `forEach` 루프** | 필드 | 설명 | 형식 | 필수 | 기본값 | | --- | --- | --- | --- | --- | | `name` | 루프에 부여된 고유 이름입니다. 동일한 단계의 다른 루프 이름과 비교할 때 고유해야 합니다. | 문자열 | No | "" | | `list` | 구성 문자열이 공통 구분 문자로 연결된 문자열로 구성된 문자열입니다. 체인 표현식도 사용할 수 있습니다. 연결된 표현식의 경우 YAML 컴파일러가 올바르게 해석할 수 있도록 큰따옴표로 묶어야 합니다. | 문자열 | 예 | 해당 사항 없음 | | `delimiter` | 블록 내에서 문자열을 구분하는 데 사용되는 문자입니다. 기본값은 쉼표 문자입니다. 지정된 목록에서 구분자를 하나만 사용할 수 있습니다.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-looping-constructs.html) 체인 표현식은 사용할 수 없습니다. | 문자열 | No | 쉼표: "," | **참고** `list`의 값은 변경할 수 없는 문자열로 취급됩니다. 런타임 중에 `list` 소스가 변경된 경우, 실행 중에는 반영되지 않습니다. 구분된 목록이 있는 `forEach` 루프 예제 1 이 예제에서는 다음 체인 표현식 패턴을 사용하여 다른 단계의 출력(`..[inputs | outputs].`)을 참조합니다. ``` - name: "RunMSIs" action: "ExecuteBinary" loop: forEach: list: "{{ build.GetAllMSIPathsForInstallation.outputs.stdout }}" delimiter: "\n" inputs: commands: path: "{{ loop.value }}" ``` 구분된 목록이 있는 `forEach` 루프 예제 2 ``` - name: "UploadMetricFiles" action: "S3Upload" loop: forEach: list: "/tmp/m1.txt,/tmp/m2.txt,/tmp/m3.txt,..." inputs: commands: - source: "{{ loop.value }}" destination: "s3://bucket/key/{{ loop.value }}" ``` ## 단계 필드 루프는 단계의 일부입니다. 단계 실행과 관련된 모든 필드는 개별 반복에 적용되지 않습니다. 단계 필드는 다음과 같이 단계 수준에서만 적용됩니다. + *timeoutSeconds* - 루프의 모든 루프는 이 필드에 지정된 기간 내에 실행되어야 합니다. 루프 실행 시간이 초과되면는 단계의 재시도 정책을 AWSTOE 실행하고 새 시도마다 제한 시간 파라미터를 재설정합니다. 최대 재시도 횟수에 도달한 후 루프 실행이 제한 시간 값을 초과하면, 루프 실행 시간이 초과되었다는 내용의 단계 실패 메시지가 나타납니다. + *onFailure* – 실패 처리가 단계에 다음과 같이 적용됩니다. + *onFailure*가 로 설정된 경우 루프를 `Abort` AWSTOE 종료하고 재시도 정책에 따라 단계를 재시도합니다. 최대 재시도 횟수가 지나면는 현재 단계를 실패로 AWSTOE 표시하고 프로세스 실행을 중지합니다. AWSTOE 는 상위 단계 및 문서의 상태 코드를 로 설정합니다`Failed`. **참고** 실패한 단계 이후에는 더 이상 단계가 실행되지 않습니다. + *onFailure*가 `Continue`(으)로 설정된 경우, AWSTOE 에서 루프를 종료하고 재시도 정책에 따라 단계를 재시도합니다. 최대 재시도 횟수가 지나면는 현재 단계를 실패로 AWSTOE 표시하고 다음 단계를 계속 실행합니다. AWSTOE 는 상위 단계 및 문서의 상태 코드를 로 설정합니다`Failed`. + *onFailure*가 `Ignore`(으)로 설정된 경우, AWSTOE 에서 루프를 종료하고 재시도 정책에 따라 단계를 재시도합니다. 최대 재시도 횟수가 지나면는 현재 단계를 로 AWSTOE 표시하고 다음 단계를 `IgnoredFailure`계속 실행합니다. AWSTOE 는 상위 단계 및 문서의 상태 코드를 로 설정합니다`SuccessWithIgnoredFailure`. **참고** 이는 여전히 성공적인 실행으로 간주되지만 하나 이상의 단계가 실패하여 무시되었음을 알려주는 정보가 포함되어 있습니다. + *maxAttempts * – 모든 재시도에 대해 전체 단계와 모든 반복이 처음부터 실행됩니다. + *status* – `status`단계 실행의 전체 상태에서 개별 반복의 상태를 나타내지는 않습니다. 루프가 있는 단계의 상태는 다음과 같이 결정합니다. + 단일 반복 실행에 실패할 경우, 단계 상태는 실패로 표시됩니다. + 모든 반복이 성공하면, 단계 상태가 성공으로 표시됩니다. + *startTime* - 단계 실행의 전체 시작 시간입니다. 개별 반복의 시작 시간을 나타내지 않습니다. + *endTime* - 단계 실행의 전체 종료 시간입니다. 개별 반복의 종료 시간을 나타내지 않습니다. + *failureMessage* - 제한 시간이 초과되지 않은 오류가 발생한 경우 실패한 반복 인덱스를 포함합니다. 시간 초과 오류가 발생한 경우, 루프 실행이 실패했다는 메시지가 표시됩니다. 실패 메시지의 크기를 최소화하기 위해 각 반복에 대한 개별 오류 메시지는 제공되지 않습니다. ## 단계별 및 반복 출력 모든 반복에는 출력값이 포함됩니다. 루프 실행이 끝나면는 성공한 모든 반복 출력을에 AWSTOE 통합합니다`detailedOutput.json`. 통합 출력은 작업 모듈의 출력 스키마에 정의된 해당 출력 키에 속하는 값을 정렬한 것입니다. 다음 예에서는 출력이 통합되는 방법을 보여줍니다. **반복 1에 `ExecuteBash`에 대한 출력** ``` { "stdout":"Hello" } ``` **반복 2에 `ExecuteBash`에 대한 출력** ``` { "stdout":"World" } ``` **단계에 `ExecuteBash`에 대한 출력** ``` { "stdout":"Hello\nWorld" } ``` 예를 들어, `ExecuteBash`, `ExecutePowerShell`, `ExecuteBinary`에서 작업 모듈 출력으로 `STDOUT`(을)를 반환하는 작업 모듈입니다. `STDOUT` 메시지는 새 줄 문자와 결합되어 `detailedOutput.json` 단계의 전체 출력을 생성합니다. AWSTOE 는 실패한 반복의 출력을 통합하지 않습니다.