기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Image Builder가 AWS Task Orchestrator and Executor 애플리케이션을 사용하여 구성 요소를 관리하는 방법
EC2 Image Builder는 AWS Task Orchestrator and Executor (AWSTOE) 애플리케이션을 사용하여 복잡한 워크플로를 오케스트레이션하고, 시스템 구성을 수정하고, 추가 개발 스크립트 또는 코드 없이 이미지를 테스트합니다. 이 애플리케이션은 선언적 문서 스키마를 구현하는 구성 요소를 관리하고 실행합니다.
AWSTOE 는 이미지를 생성할 때 Image Builder가 빌드 및 테스트 인스턴스에 설치하는 독립 실행형 애플리케이션입니다. EC2 인스턴스에 수동으로 설치하여 사용자 지정 구성 요소를 생성할 수도 있습니다. 추가 설정이 필요하지 않으며 온프레미스에서 실행할 수도 있습니다.
**Topics**
+ [AWSTOE 다운로드](#toe-downloads)
+ [지원되는 리전](#toe-supported-regions)
+ [AWSTOE 명령 참조](#toe-commands)
+ [를 사용하여 사용자 지정 구성 요소를 개발하도록 수동 설정 AWSTOE](toe-get-started.md)
+ [사용자 지정 AWSTOE 구성 요소에 구성 요소 문서 프레임워크 사용](toe-use-documents.md)
+ [AWSTOE 구성 요소 관리자가 지원하는 작업 모듈](toe-action-modules.md)
+ [AWSTOE run 명령에 대한 입력 구성](toe-run-config-input.md)
## AWSTOE 다운로드
설치하려면 아키텍처 및 플랫폼의 다운로드 링크를 AWSTOE선택합니다. 서비스의 VPC 엔드포인트(예: Image Builder)에 연결하는 경우 AWSTOE 다운로드를 위해 S3 버킷에 대한 액세스를 포함하는 사용자 지정 엔드포인트 정책이 연결되어 있어야 합니다. 그렇지 않으면 빌드 및 테스트 인스턴스가 부트스트랩 스크립트(`bootstrap.sh`)를 다운로드하고 AWSTOE 애플리케이션을 설치할 수 없습니다. 자세한 내용은 [Image Builder에 대한 VPC 엔드포인트 정책 생성하기](vpc-interface-endpoints.md#vpc-endpoint-policy)을 참조하세요.
**중요**
AWS 는 TLS 버전 1.0 및 1.1에 대한 지원을 단계적으로 중단합니다. AWSTOE 다운로드를 위해 S3 버킷에 액세스하려면 클라이언트 소프트웨어가 TLS 버전 1.2 이상을 사용해야 합니다. 자세한 내용은 [AWS 보안 블로그 게시물](https://aws.amazon.com/blogs/security/tls-1-2-required-for-aws-endpoints/)을 참조하세요.
| 아키텍처 | 플랫폼 | 다운로드 링크 | 예제 |
| --- | --- | --- | --- |
| 386 | AL 2 및 2023 RHEL 7, 8 및 9 Ubuntu 16.04, 18.04, 20.04, 22.04 및 24.04 CentOS 7 및 8 SUSE 12 및 15 | `https://awstoe-.s3..amazonaws.com/latest/linux/386/awstoe` | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/386/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/386/awstoe) |
| AMD64 | AL 2 및 2023 RHEL 7, 8 및 9 Ubuntu 16.04, 18.04, 20.04, 22.04 및 24.04 CentOS 7 및 8 CentOS Stream 8 SUSE 12 및 15 | https://awstoe-.s3..amazonaws.com/latest/linux/amd64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe) |
| AMD64 | macOS 10.14.x(Mojave), 10.15.x(Catalina), 11.x(Big Sur), 12.x(Monterey) | https://awstoe-region.s3.region.amazonaws.com/latest/darwin/amd64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/darwin/amd64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/darwin/amd64/awstoe) |
| AMD64 | Windows Server 2012 R2, 2016, 2019 및 2022 | `https://awstoe-.s3..amazonaws.com/latest/windows/amd64/awstoe.exe` | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/windows/amd64/awstoe.exe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/windows/amd64/awstoe.exe) |
| ARM64 | AL 2 및 2023 RHEL 7, 8 및 9 Ubuntu 16.04, 18.04, 20.04, 22.04 및 24.04 CentOS 7 및 8 CentOS Stream 8 SUSE 12 및 15 | https://awstoe-.s3..amazonaws.com/latest/linux/arm64/awstoe | [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/arm64/awstoe](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/arm64/awstoe) |
## 지원되는 리전
AWSTOE 는 다음 리전에서 독립 실행형 애플리케이션으로 지원됩니다.
| AWS 리전 이름 | AWS 리전 |
| --- | --- |
| 미국 동부(오하이오) | us-east-2 |
| 미국 동부(버지니아 북부) | us-east-1 |
| AWS GovCloud(미국 동부) | us-gov-east-1 |
| AWS GovCloud(미국 서부) | us-gov-west-1 |
| 미국 서부(캘리포니아 북부) | us-west-1 |
| 미국 서부(오리건) | us-west-2 |
| 아프리카(케이프타운) | af-south-1 |
| 아시아 태평양(홍콩) | ap-east-1 |
| 아시아 태평양(오사카) | ap-northeast-3 |
| 아시아 태평양(서울) | ap-northeast-2 |
| 아시아 태평양(뭄바이) | ap-south-1 |
| 아시아 태평양(하이데라바드) | ap-south-2 |
| 아시아 태평양(싱가포르) | ap-southeast-1 |
| 아시아 태평양(시드니) | ap-southeast-2 |
| 아시아 태평양(자카르타) | ap-southeast-3 |
| 아시아 태평양(도쿄) | ap-northeast-1 |
| 캐나다(중부) | ca-central-1 |
| 유럽(프랑크푸르트) | eu-central-1 |
| 유럽(취리히) | eu-central-2 |
| 유럽(스톡홀름) | eu-north-1 |
| 유럽(밀라노) | eu-south-1 |
| 유럽(스페인) | eu-south-2 |
| 유럽(아일랜드) | eu-west-1 |
| 유럽(런던) | eu-west-2 |
| 유럽(파리) | eu-west-3 |
| 이스라엘(텔아비브) | il-central-1 |
| 중동(UAE) | me-central-1 |
| 중동(바레인) | me-south-1 |
| 남아메리카(상파울루) | sa-east-1 |
| 중국(베이징) | cn-north-1 |
| 중국(닝샤) | cn-northwest-1 |
## AWSTOE 명령 참조
AWSTOE 는 Amazon EC2 인스턴스에서 실행되는 명령줄 구성 요소 관리 애플리케이션입니다. Image Builder는 EC2 빌드 또는 테스트 인스턴스를 시작할 때 인스턴스 AWSTOE 에를 설치합니다. 그런 다음에서 AWSTOE 명령을 실행 AWS CLI 하여 이미지 또는 컨테이너 레시피에 지정된 구성 요소를 설치하거나 검증합니다.
**참고**
일부 AWSTOE 작업 모듈을 Linux 서버에서 실행하려면 승격된 권한이 필요합니다. 상승된 권한을 사용하려면 명령 구문에 접두사로 **sudo**을(를) 붙이거나 아래 링크된 **sudo su** 명령을 실행하기 전에 로그인할 때 명령을 한 번 실행하세요. AWSTOE 작업 모듈에 대한 자세한 내용은 섹션을 참조하세요[AWSTOE 구성 요소 관리자가 지원하는 작업 모듈](toe-action-modules.md).
***[run](#cmd-run)***
**run** 명령을 사용하여 하나 이상의 구성 요소 문서에 대해 YAML 문서 스크립트를 실행합니다.
***[검증](#cmd-validate)***
**validate** 명령을 실행하여 하나 이상의 구성 요소 문서에 대해 YAML 문서 의미 체계를 검증합니다.
### awstoe 실행 명령
이 명령은 `--documents` 매개 변수로 지정된 구성 파일 또는 `--config` 매개 변수로 지정된 구성 요소 문서 목록에 포함된 순서대로 YAML 구성 요소 문서 스크립트를 실행합니다.
**참고**
다음 매개변수 중 하나를 정확히 지정해야 합니다.
--config
--documents
#### 구문
```
awstoe run [--config ] [--cw-ignore-failures ]
[--cw-log-group ] [--cw-log-region us-west-2] [--cw-log-stream ]
[--document-s3-bucket-owner ] [--documents ]
[--execution-id ] [--log-directory ]
[--log-s3-bucket-name ] [--log-s3-bucket-owner ]
[--log-s3-key-prefix ] [--parameters name1=value1,name2=value2...]
[--phases ] [--state-directory ] [--version ]
[--help] [--trace]
```
#### 매개 변수 및 옵션
매개 변수
**--config *`./config-example.json`***
간략한 형식: -c *`./config-example.json`*
구성 파일*(조건부)* 이 매개 변수는 이 명령이 실행 중인 구성 요소의 구성 설정이 포함된 JSON 파일의 파일 위치를 포함합니다. 구성 파일에 **run** 명령 설정을 지정하는 경우, `--documents` 매개 변수를 지정하면 안 됩니다. 입력 구성에 대한 자세한 정보는 [AWSTOE run 명령에 대한 입력 구성](toe-run-config-input.md) 섹션을 참조하세요.
유효한 위치에는 다음이 포함됩니다.
+ 로컬 파일 경로(*`./config-example.json`*)
+ S3 URI(`s3://bucket/key`)
**--cw-ignore-failures**
간략한 형식: 해당 사항 없음
CloudWatch Logs의 로깅 실패는 무시하세요.
**--cw-log-group**
간략한 형식: 해당 사항 없음
CloudWatch Logs의 `LogGroup` 이름입니다.
**--cw-log-region**
간략한 형식: 해당 사항 없음
CloudWatch Logs에 적용되는 AWS 리전입니다.
**--cw-log-stream**
간략한 형식: 해당 사항 없음
`console.log` 파일을 스트리밍할 AWSTOE 위치를 지정하는 CloudWatch Logs의 `LogStream` 이름입니다.
**--document-s3-bucket-owner**
간략한 형식: 해당 사항 없음
S3 URI 기반 문서에 대한 버킷 소유자의 계정 ID입니다.
**--documents *`./doc-1.yaml`,`./doc-n.yaml`***
Short form: -d *`./doc-1.yaml`*,*`./doc-n`*
구성 요소 문서*(조건부)* 이 매개 변수에는 실행할 YAML 구성 요소 문서의 쉼표로 구분된 파일 위치 목록이 포함됩니다. `--config` 매개 변수를 사용하여 **run** 명령에 대한 YAML 문서를 지정하는 경우, `--documents` 매개 변수를 지정하지 않아야 합니다.
유효한 위치에는 다음이 포함됩니다.
+ 로컬 파일 경로(*./component-doc-example.yaml*).
+ S3 URI(`s3://bucket/key`).
+ Image Builder 컴포넌트 빌드 버전 ARN(arn:aws:imagebuilder:us-west-*2:123456789012*:component/*my-example-component*/2021.12.02/1).
목록의 항목 사이에는 공백이 없고 쉼표만 있습니다.
**--execution-id**
간략한 형식: -i
현재 **run** 명령 실행에 적용되는 고유 ID입니다. 이 ID는 해당 파일을 고유하게 식별하고 현재 명령 실행에 연결하기 위해 출력 및 로그 파일 이름에 포함됩니다. 이 설정을 생략하면가 GUID를 AWSTOE 생성합니다.
**--log-directory**
간략한 형식: -l
가이 명령 실행의 모든 로그 파일을 AWSTOE 저장하는 대상 디렉터리입니다. 기본적으로 이 파일은 `TOE__` 디렉터리에 위치합니다. 로그 디렉터리를 지정하지 않으면는 현재 작업 디렉터리()를 AWSTOE 사용합니다`.`.
**--log-s3-bucket-name**
간략한 형식: -b
구성 요소 로그가 Amazon S3에 저장되는 경우(권장)는 구성 요소 애플리케이션 로그를이 파라미터에 이름이 지정된 S3 버킷에 AWSTOE 업로드합니다.
**--log-s3-bucket-owner**
간략한 형식: 해당 사항 없음
구성 요소 로그가 Amazon S3에 저장되는 경우(권장),가 로그 파일을 AWSTOE 작성하는 버킷의 소유자 계정 ID입니다.
**--log-s3-key-prefix**
간략한 형식: -k
구성 요소 로그가 Amazon S3에 저장되어 있는 경우(권장), 이 접두사는 버킷 내 로그 위치의 S3 객체 키 접두사입니다.
**--parameters *name1*=*value1*,*name2*=*value2*...**
간략한 형식: 해당 사항 없음
매개변수는 구성 요소 문서에 정의된 변경 가능한 변수로, 호출 애플케이션이 런타임에 제공할 수 있는 설정을 포함합니다.
**--phases**
간략한 형식: -p
YAML 구성 요소 문서에서 실행할 단계를 지정하는 쉼표로 구분된 목록입니다. 구성 요소 문서에 추가 단계가 포함된 경우, 해당 단계는 실행되지 않습니다.
**--state-directory**
간략한 형식: -s
상태 추적 파일이 저장되는 파일 경로입니다.
**--version**
간략한 형식: -v
구성 요소 애플케이션 버전을 지정합니다.옵션
**--help**
간략한 형식: -h
구성 요소 관리 애플케이션 옵션 사용에 대한 도움말 설명서를 표시합니다.
**--trace**
간략한 형식: -t
콘솔에 대한 자세한 로깅을 활성화합니다.
### awstoe 검증 명령
이 명령을 실행하면 `--documents` 매개 변수로 지정된 각 구성 요소 문서의 YAML 문서 구문을 검증합니다.
#### 구문
```
awstoe validate [--document-s3-bucket-owner ]
--documents [--help] [--trace]
```
#### 매개 변수 및 옵션
매개 변수
**--document-s3-bucket-owner**
간략한 형식: 해당 사항 없음
제공된 S3 URI 기반 문서의 소스 계정 ID
**--documents *`./doc-1.yaml`,`./doc-n.yaml`***
Short form: -d *`./doc-1.yaml`*,*`./doc-n`*
구성 요소 문서*(필수)* 이 매개 변수에는 실행할 YAML 구성 요소 문서의 쉼표로 구분된 파일 위치 목록이 포함됩니다. 유효한 위치에는 다음이 포함됩니다.
+ 로컬 파일 경로(*./component-doc-example.yaml*)
+ S3 URI(`s3://bucket/key`)
+ Image Builder 컴포넌트 빌드 버전 ARN(arn:aws:imagebuilder:us-west-*2:123456789012*:component/*my-example-component*/2021.12.02/1)
목록의 항목 사이에는 공백이 없고 쉼표만 있습니다.옵션
**--help**
간략한 형식: -h
구성 요소 관리 애플케이션 옵션 사용에 대한 도움말 설명서를 표시합니다.
**--trace**
간략한 형식: -t
콘솔에 대한 자세한 로깅을 활성화합니다.
# 를 사용하여 사용자 지정 구성 요소를 개발하도록 수동 설정 AWSTOE
AWS Task Orchestrator and Executor (AWSTOE) 애플리케이션은 구성 요소 정의 프레임워크 내에서 명령을 생성, 검증 및 실행하는 독립 실행형 애플리케이션입니다. AWS 서비스는 AWSTOE 를 사용하여 워크플로를 오케스트레이션하고, 소프트웨어를 설치하고, 시스템 구성을 수정하고, 이미지 빌드를 테스트할 수 있습니다.
다음 단계에 따라 AWSTOE 애플리케이션을 수동으로 설치하고 이를 독립형 애플리케이션으로 사용하여 사용자 지정 구성 요소를 개발합니다. Image Builder 콘솔 또는 AWS CLI 명령을 사용하여 사용자 지정 구성 요소를 생성하는 경우 Image Builder가 이러한 단계를 자동으로 처리합니다. 자세한 내용은 [Image Builder로 사용자 지정 구성 요소 생성](create-component.md) 단원을 참조하십시오.
# AWSTOE 설치 다운로드의 서명 확인
이 섹션에서는 AWSTOE Linux, macOS 및 Windows 기반 운영 체제에서에 대한 설치 다운로드의 유효성을 확인하기 위한 권장 프로세스를 설명합니다.
**Topics**
+ [Linux 또는 macOS에서 AWSTOE 설치 다운로드의 서명 확인](#awstoe-verify-sig-linux)
+ [Windows에서 AWSTOE 설치 다운로드의 서명 확인](#awstoe-verify-sig-win)
## Linux 또는 macOS에서 AWSTOE 설치 다운로드의 서명 확인
이 주제에서는 Linux 기반 또는 macOS 운영 체제에서에 대한 설치 다운로드의 유효성을 확인하기 위한 권장 프로세스에 AWSTOE 대해 설명합니다.
인터넷에서 애플리케이션을 다운로드할 때마다 소프트웨어 게시자의 자격 증명을 인증하는 것이 좋습니다. 또한 애플리케이션이 게시된 이후 변경되거나 손상되지 않았는지 확인하세요. 이를 통해 바이러스나 기타 악성 코드가 포함된 애플리케이션 버전을 설치하는 것을 방지할 수 있습니다.
이 단원의 절차를 수행한 후에 AWSTOE 애플리케이션의 소프트웨어가 변경되거나 손상된 것을 발견한 경우 설치 파일을 실행하지 마십시오. 대신에 문의하십시오. 지원 옵션에 대한 지원 자세한 내용은 섹션을 참조하세요[지원](https://aws.amazon.com/premiumsupport/).
AWSTOE Linux 기반 및 macOS 운영 체제용 파일은 안전한 디지털 서명을 위한 Pretty Good Privacy(OpenPGP) 표준의 오픈 소스 구현`GnuPG`인를 사용하여 서명됩니다. `GnuPG` (라고도 함`GPG`)는 디지털 서명을 통해 인증 및 무결성 검사를 제공합니다. Amazon EC2는 다운로드한 Amazon EC2 CLI 도구를 확인하는 데 사용할 수 있는 퍼블릭 키 및 서명을 게시합니다. `PGP` 및 `GnuPG`(`GPG`)에 대한 자세한 내용은 [http://www.gnupg.org](https://www.gnupg.org/)를 참조하세요.
첫 번째 단계는 소프트웨어 게시자와 신뢰를 구축하는 것입니다. 소프트웨어 게시자의 퍼블릭 키를 다운로드하고, 퍼블릭 키의 소유자가 정당한 소유자인지 확인한 다음, 퍼블릭 키를 *키링*에 추가합니다. 키링은 알려진 퍼블릭 키의 모음입니다. 퍼블릭 키의 신뢰성을 설정한 후, 이를 사용하여 애플리케이션의 서명을 확인할 수 있습니다.
**Topics**
+ [GPG 도구 설치](#awstoe-verify-signature-of-binary-download-install-tools)
+ [퍼블릭 키 인증 및 가져오기](#awstoe-verify-signature-of-binary-download-authenticate-import-public-key)
+ [패키지의 서명 확인](#awstoe-verify-signature-of-binary-package)
### GPG 도구 설치
Linux, Unix 또는 macOS 운영 체제를 사용하는 경우 일반적으로 GPG 도구가 이미 설치되어 있습니다. 시스템에 도구가 설치되어 있는지 테스트하려면 명령 프롬프트에 **gpg**(을)를 입력합니다. GPG 도구가 설치되어 있는 경우, GPG 명령 프롬프트가 표시됩니다. GPG 도구가 설치되어 있지 않은 경우, 명령을 찾을 수 없다는 오류 메시지가 표시됩니다. 리포지토리에서 GnuPG 패키지를 설치할 수 있습니다.
GPG 도구를 설치하려면 인스턴스와 일치하는 운영 체제를 선택합니다.
------
#### [ Debian-based Linux ]
터미널에서 다음 명령을 실행합니다.
```
apt-get install gnupg
```
------
#### [ Red Hat–based Linux ]
터미널에서 다음 명령을 실행합니다.
```
yum install gnupg
```
------
#### [ macOS ]
터미널에서 다음 명령을 실행합니다.
```
brew install gnupg
```
------
### 퍼블릭 키 인증 및 가져오기
프로세스의 다음 단계는 AWSTOE 퍼블릭 키를 인증하고 `GPG` 키링에 신뢰할 수 있는 키로 추가하는 것입니다.
**AWSTOE 퍼블릭 키를 인증하고 가져오려면**
1. 다음 중 하나를 수행하여 퍼블릭 `GPG` 빌드 키 사본을 가져옵니다.
+ 키를
https://awstoe-****.s3.****.amazonaws.com/assets/awstoe.gpg에서 다운로드하세요. 예를 들어 [https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/assets/awstoe.gpg](https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/assets/awstoe.gpg)입니다.
+ 다음 텍스트에서 키를 복사하여 `awstoe.gpg`라는 파일에 붙여 넣습니다. 다음의 모든 항목을 포함해야 합니다.
```
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v2
mQENBF8UqwsBCACdiRF2bkZYaFSDPFC+LIkWLwFvtUCRwAHtD8KIwTJ6LVn3fHAU
GhuK0ZH9mRrqRT2bq/xJjGsnF9VqTj2AJqndGJdDjz75YCZYM+ocZ+r5HSJaeW9i
S5dykHj7Txti2zHe0G5+W0v7v5bPi2sPHsN7XWQ7+G2AMEPTz8PjxY//I0DvMQns
Sle3l9hz6wCClz1l9LbBzTyHfSm5ucTXvNe88XX5Gmt37OCDM7vfli0Ctv8WFoLN
6jbxuA/sV71yIkPm9IYp3+GvaKeT870+sn8/JOOKE/U4sJV1ppbqmuUzDfhrZUaw
8eW8IN9A1FTIuWiZED/5L83UZuQs1S7s2PjlABEBAAG0GkFXU1RPRSA8YXdzdG9l
QGFtYXpvbi5jb20+iQE5BBMBCAAjBQJfFKsLAhsDBwsJCAcDAgEGFQgCCQoLBBYC
AwECHgECF4AACgkQ3r3BVvWuvFJGiwf9EVmrBR77+Qe/DUeXZJYoaFr7If/fVDZl
6V3TC6p0J0Veme7uXleRUTFOjzbh+7e5sDX19HrnPquzCnzfMiqbp4lSoeUuNdOf
FcpuTCQH+M+sIEIgPno4PLl0Uj2uE1o++mxmonBl/Krk+hly8hB2L/9n/vW3L7BN
OMb1Ll9PmgGPbWipcT8KRdz4SUex9TXGYzjlWb3jU3uXetdaQY1M3kVKE1siRsRN
YYDtpcjmwbhjpu4xm19aFqNoAHCDctEsXJA/mkU3erwIRocPyjAZE2dnlkL9ZkFZ
z9DQkcIarbCnybDM5lemBbdhXJ6hezJE/b17VA0t1fY04MoEkn6oJg==
=oyze
-----END PGP PUBLIC KEY BLOCK-----
```
1. **awstoe.gpg**를 저장한 디렉터리의 명령 프롬프트에서 다음 명령을 사용하여 AWSTOE 퍼블릭 키를 키링으로 가져옵니다.
```
gpg --import awstoe.gpg
```
이 명령은 다음과 같은 결과를 반환합니다.
```
gpg: key F5AEBC52: public key "AWSTOE " imported
gpg: Total number processed: 1
gpg: imported: 1 (RSA: 1)
```
다음 단계에서 필요하므로 키 값을 적어 둡니다. 이전 예제에서 키 값은 `F5AEBC52`입니다.
1. *키-값*을 이전 단계의 값으로 대체하고 다음 명령을 실행하여 지문을 확인합니다.
```
gpg --fingerprint key-value
```
이 명령에서 다음과 비슷한 결과를 반환합니다.
```
pub 2048R/F5AEBC52 2020-07-19
Key fingerprint = F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52
uid [ unknown] AWSTOE
```
또한 지문 문자열은 이전 예제에 표시된 `F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52`(와)과 동일해야 합니다. 반환된 키 지문을 이 페이지에 게시된 지문과 비교합니다. 두 지문이 일치해야 합니다. 일치하지 않는 경우 AWSTOE 설치 스크립트를 설치하지 말고에 문의하십시오 지원.
### 패키지의 서명 확인
`GPG` 도구를 설치하고, AWSTOE 퍼블릭 키를 인증 및 가져오고, 퍼블릭 키가 신뢰할 수 있는지 확인하면 설치 스크립트의 서명을 확인할 준비가 된 것입니다.
**설치 스크립트 서명을 확인하려면**
1. 명령 프롬프트에서 다음 명령을 실행하여 애플리케이션 바이너리를 다운로드합니다.
```
curl -O https://awstoe-.s3..amazonaws.com/latest/linux//awstoe
```
예제:
```
curl -O https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe
```
**architecture**의 지원되는 값은 `amd64`, `386`, `arm64`일 수 있습니다.
1. 명령 프롬프트에서 다음 명령을 실행하여 동일한 S3 키 접두사 경로에서 해당 애플리케이션 바이너리용 서명 파일을 다운로드합니다.
```
curl -O https://awstoe-.s3..amazonaws.com/latest/linux//awstoe.sig
```
예제:
```
curl -O https://awstoe-us-east-1.s3.us-east-1.amazonaws.com/latest/linux/amd64/awstoe.sig
```
**architecture**의 지원되는 값은 `amd64`, `386`, `arm64`일 수 있습니다.
1. 저장한 디렉터리의 명령 프롬프트`awstoe.sig`와 AWSTOE 설치 파일에서 다음 명령을 실행하여 서명을 확인합니다. 두 파일이 모두 있어야 합니다.
```
gpg --verify ./awstoe.sig ~/awstoe
```
출력은 다음과 같아야 합니다.
```
gpg: Signature made Mon 20 Jul 2020 08:54:55 AM IST using RSA key ID F5AEBC52
gpg: Good signature from "AWSTOE awstoe@amazon.com" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: F6DD E01C 869F D639 15E5 5742 DEBD C156 F5AE BC52
```
출력에 `Good signature from "AWSTOE "` 문구가 포함된 경우 서명을 확인했고, AWSTOE 설치 스크립트 실행을 계속할 수 있음을 의미합니다.
출력에 `BAD signature` 문구가 포함된 경우, 절차를 올바르게 수행했는지 확인합니다. 계속해서 이 응답을 받게 되면, 이전에 다운로드한 설치 파일을 실행하지 마시고 지원에 문의하세요.
다음은 표시될 수 있는 경고에 대한 세부 정보입니다.
+ **경고: 이 키는 신뢰할 수 있는 서명으로 인증되지 않았습니다. 서명이 소유자에게 속한다는 표시가 없습니다.** AWS 사무실을 방문하여 직접 키를 받는 것이 가장 좋습니다. 그러나 대부분의 경우 웹 사이트에서 다운로드합니다. 이 경우 웹 사이트는 AWS 웹 사이트입니다.
+ **gpg: 궁극적으로 신뢰할 수 있는 키를 찾을 수 없습니다.** 이는 사용자 또는 사용자가 신뢰하는 다른 사용자가 특정 키를 ‘궁극적으로 신뢰’하지 않음을 뜻합니다.
자세한 내용은 [http://www.gnupg.org](http://www.gnupg.org)를 참조하세요.
## Windows에서 AWSTOE 설치 다운로드의 서명 확인
이 주제에서는 Windows 기반 운영 체제에서 AWS Task Orchestrator and Executor 애플리케이션에 대한 설치 파일의 유효성을 확인하기 위한 권장 프로세스에 대해 설명합니다.
인터넷에서 애플리케이션을 다운로드할 때마다 소프트웨어 게시자의 자격 증명을 인증하고 애플리케이션이 게시된 이후 변경되거나 손상되지 않았는지 확인하는 것이 좋습니다. 이를 통해 바이러스나 기타 악성 코드가 포함된 애플리케이션 버전을 설치하는 것을 방지할 수 있습니다.
이 단원의 절차를 수행한 후에 AWSTOE 애플리케이션의 소프트웨어가 변경되거나 손상된 것을 발견한 경우 설치 파일을 실행하지 마십시오. 대신에 문의하세요 지원.
Windows 기반 운영 체제에서 다운로드된 awstoe 바이너리의 유효성을 확인하려면 Amazon Services LLC 서명자 인증서의 지문이 다음 값과 동일한지 확인해야 합니다.
**9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15**
**참고**
새 바이너리의 롤아웃 기간 동안 서명자 인증서가 새 지문과 일치하지 않을 수 있습니다. 서명자 인증서가 일치하지 않는 경우 지문 값이 다음과 같은지 확인하세요.
**BA 81 25 EE AC 64 2E A9 F3 C5 93 CA 6D 3E B7 93 7D 68 75 74**
이 값을 확인하려면 다음 절차를 수행합니다.
1. 다운로드한 `awstoe.exe`(을)를 마우스 오른쪽 버튼으로 클릭하고 **속성(Properties)** 창을 엽니다.
1. **디지털 서명(Digital Signatures)** 탭을 선택합니다.
1. **서명 목록(Signature List)**에서 **Amazon Services LLC**를 선택한 후 **세부 정보(Details)**를 선택합니다.
1. **일반** 탭이 선택되어 있지 않으면 이 탭을 선택한 후 **인증서 보기(View Certificate)**를 선택합니다.
1. **세부 정보** 탭을 선택한 다음, 선택되어 있지 않은 경우 **표시** 드롭다운 목록에서 **모두(All)**를 선택합니다.
1. **지문(Thumbprint)** 필드가 보일 때까지 아래로 스크롤한 후 **지문(Thumbprint)**을 선택합니다. 그러면 아래 창에 전체 지문 값이 표시됩니다.
+ 아래 창의 지문 값이 다음과 값과 동일한지 확인합니다.
**9D CA 72 17 DA FF B8 2F E4 C4 67 77 36 2F A4 AA C9 08 82 15**
그러면 다운로드한 AWSTOE 바이너리가 정품이며 안전하게 설치할 수 있습니다.
+ 아래 세부 정보 창의 지문 값이 이전 값과 동일하지 않을 경우 `awstoe.exe`(을)를 실행하지 마십시오.
**Topics**
+ [AWSTOE 설치 다운로드의 서명 확인](awstoe-verify-sig.md)
+ [1단계: 설치 AWSTOE](#toe-start-install)
+ [2단계: AWS 자격 증명 설정](#toe-start-credentials)
+ [3단계: 구성 요소 문서를 로컬로 개발](#toe-start-develop)
+ [4단계: AWSTOE 구성 요소 검증](#toe-start-validate)
+ [5단계: AWSTOE 구성 요소 실행](#toe-start-run)
## 1단계: 설치 AWSTOE
로컬에서 구성 요소를 개발하려면 AWSTOE 애플리케이션을 다운로드하여 설치합니다.
1.
**AWSTOE 애플리케이션 다운로드**
설치하려면 아키텍처 및 플랫폼에 적합한 다운로드 링크를 AWSTOE선택합니다. 애플리케이션 다운로드 링크의 전체 목록은 [AWSTOE 다운로드](toe-component-manager.md#toe-downloads) 섹션을 참조하세요.
**중요**
AWS 는 TLS 버전 1.0 및 1.1에 대한 지원을 단계적으로 중단합니다. AWSTOE 다운로드를 위해 S3 버킷에 액세스하려면 클라이언트 소프트웨어가 TLS 버전 1.2 이상을 사용해야 합니다. 자세한 내용은 [AWS 보안 블로그 게시물](https://aws.amazon.com/blogs/security/tls-1-2-required-for-aws-endpoints/)을 참조하세요.
1.
**서명 확인**
다운로드를 확인하는 단계는 AWSTOE 애플리케이션을 설치한 후 실행하는 서버 플랫폼에 따라 다릅니다. Linux 서버에서 다운로드를 확인하려면 [Linux 또는 macOS에서 서명 확인](awstoe-verify-sig.md#awstoe-verify-sig-linux) 섹션을 참조하세요. Windows 서버에서 다운로드를 확인하려면 [윈도우에서 서명 확인](awstoe-verify-sig.md#awstoe-verify-sig-win) 섹션을 참조하세요.
**참고**
AWSTOE 는 다운로드 위치에서 직접 호출됩니다. 별도의 설치 단계는 필요 없습니다. 또한는 로컬 환경을 변경할 AWSTOE 수 있습니다.
구성 요소 개발 중에 변경 사항을 격리하려면 EC2 인스턴스를 사용하여 AWSTOE 구성 요소를 개발하고 테스트하는 것이 좋습니다.
## 2단계: AWS 자격 증명 설정
AWSTOE 는 다음과 AWS 서비스같은 작업을 실행할 때 Amazon S3 및 Amazon CloudWatch와 같은 다른에 연결하기 위한 AWS 자격 증명이 필요합니다.
+ 사용자가 제공한 Amazon S3 경로에서 AWSTOE 문서 다운로드.
+ `S3Download` 또는 `S3Upload` 작업 모듈을 실행합니다.
+ 활성화된 경우 CloudWatch로 로그를 스트리밍합니다.
EC2 인스턴스 AWSTOE 에서를 실행하는 경우 실행은 EC2 인스턴스에 연결된 IAM 역할과 동일한 권한을 AWSTOE 사용합니다.
EC2용 IAM 역할에 대한 자세한 내용은 [Amazon EC2의 IAM 역할](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)을 참조하세요.
다음 예제에서는 `AWS_ACCESS_KEY_ID` 및 `AWS_SECRET_ACCESS_KEY` 환경 변수를 사용하여 AWS 자격 증명을 설정하는 방법을 보여줍니다.
Linux, macOS 또는 Unix에서 이러한 변수를 설정하려면 `export`를 사용합니다.
```
export AWS_ACCESS_KEY_ID=your_access_key_id
```
```
export AWS_SECRET_ACCESS_KEY=your_secret_access_key
```
PowerShell을 사용하여 Windows에서 이러한 변수를 설정하려면 `$env`(을)를 사용합니다.
```
$env:AWS_ACCESS_KEY_ID=your_access_key_id
```
```
$env:AWS_SECRET_ACCESS_KEY=your_secret_access_key
```
명령 프롬프트를 사용하여 Windows에서 이러한 변수를 설정하려면 `set`(을)를 사용합니다.
```
set AWS_ACCESS_KEY_ID=your_access_key_id
```
```
set AWS_SECRET_ACCESS_KEY=your_secret_access_key
```
## 3단계: 구성 요소 문서를 로컬로 개발
구성 요소는 일반 텍스트 YAML 문서를 사용하여 작성됩니다. 문서 구문에 대한 자세한 내용은 [사용자 지정 AWSTOE 구성 요소에 구성 요소 문서 프레임워크 사용](toe-use-documents.md) 섹션을 참조하세요.
다음은 시작하는 데 도움이 되는 *Hello World* 구성 요소 문서의 예입니다.
------
#### [ Linux ]
이 안내서의 Linux 구성 요소 예제 중 일부는 `hello-world-linux.yml`이라는 구성 요소 문서 파일을 참조합니다. 다음 문서를 사용하여 이러한 예제를 시작할 수 있습니다.
```
name: Hello World
description: This is hello world testing document for Linux.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the build phase.'
- name: validate
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the validate phase.'
- name: test
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the test phase.'
```
------
#### [ Windows ]
이 안내서의 Windows 구성 요소 예제 중 일부는 `hello-world-windows.yml`이라는 구성 요소 문서 파일을 참조합니다. 다음 문서를 사용하여 이러한 예제를 시작할 수 있습니다.
```
name: Hello World
description: This is Hello World testing document for Windows.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: HelloWorldStep
action: ExecutePowerShell
inputs:
commands:
- Write-Host 'Hello World from the build phase.'
- name: validate
steps:
- name: HelloWorldStep
action: ExecutePowerShell
inputs:
commands:
- Write-Host 'Hello World from the validate phase.'
- name: test
steps:
- name: HelloWorldStep
action: ExecutePowerShell
inputs:
commands:
- Write-Host 'Hello World from the test phase.'
```
------
#### [ macOS ]
이 안내서의 일부 macOS 구성 요소 예제는 `hello-world-macos.yml`이라는 구성 요소 문서 파일을 참조합니다. 다음 문서를 사용하여 이러한 예제를 시작할 수 있습니다.
```
name: Hello World
description: This is hello world testing document for macOS.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the build phase.'
- name: validate
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the validate phase.'
- name: test
steps:
- name: HelloWorldStep
action: ExecuteBash
inputs:
commands:
- echo 'Hello World from the test phase.'
```
------
## 4단계: AWSTOE 구성 요소 검증
애플리케이션을 사용하여 로컬에서 AWSTOE 구성 요소의 구문을 AWSTOE 검증할 수 있습니다. 다음 예제에서는 구성 요소를 실행하지 않고 구문을 검증하는 AWSTOE 애플리케이션 `validate` 명령을 보여줍니다.
**참고**
AWSTOE 애플리케이션은 현재 운영 체제의 구성 요소 구문만 검증할 수 있습니다. 예를 들어 Windows에서 `awstoe.exe`(을)를 실행하는 경우, `ExecuteBash` 작업 모듈을 사용하는 Linux 문서의 구문을 검증할 수 없습니다.
Linux 또는 macOS
```
awstoe validate --documents /home/user/hello-world.yml
```
Windows
```
awstoe.exe validate --documents C:\Users\user\Documents\hello-world.yml
```
## 5단계: AWSTOE 구성 요소 실행
AWSTOE 애플리케이션은 `--phases` 명령줄 인수를 사용하여 지정된 문서의 단계를 하나 이상 실행할 수 있습니다. `--phases`의 지원되는 값은 `build`, `validate` 및 `test`입니다. 여러 단계 값을 쉼표로 구분된 값으로 입력할 수 있습니다.
단계 목록을 제공하면 AWSTOE 애플리케이션이 각 문서의 지정된 단계를 순차적으로 실행합니다. 예를 들어,는의 `build` 및 `validate` 단계를 `document1.yaml`실행한 다음의 `build` 및 `validate` 단계를 AWSTOE 실행합니다`document2.yaml`.
로그를 안전하게 저장하고 문제 해결을 위해 보관하려면 Amazon S3에 로그 스토리지를 구성하는 것이 좋습니다. Image Builder에서 로그를 게시하기 위한 Amazon S3 위치는 인프라 구성에 지정됩니다. 이 인프라 구성에 대한 자세한 내용은 [Image Builder 인프라 구성 관리](manage-infra-config.md) 섹션을 참조하세요.
단계 목록이 제공되지 않은 경우 AWSTOE 애플리케이션은 YAML 문서에 나열된 순서대로 모든 단계를 실행합니다.
단일 또는 여러 문서에서 특정 단계를 실행하려면, 다음 명령을 사용합니다.
단일 단계
```
awstoe run --documents hello-world.yml --phases build
```
여러 단계
```
awstoe run --documents hello-world.yml --phases build,test
```
**문서 실행**
단일 문서에서 모든 단계를 실행합니다.
```
awstoe run --documents documentName.yaml
```
여러 문서의 모든 단계 실행
```
awstoe run --documents documentName1.yaml,documentName2.yaml
```
Amazon S3 정보를 입력하여 사용자 정의 로컬 경로에서 AWSTOE 로그 업로드(권장)
```
awstoe run --documents documentName.yaml --log-s3-bucket-name amzn-s3-demo-destination-bucket --log-s3-key-prefix S3KeyPrefix --log-s3-bucket-owner S3BucketOwner --log-directory local_path
```
단일 문서에서 모든 단계를 실행하고, 콘솔에 모든 로그를 표시합니다.
```
awstoe run --documents documentName.yaml --trace
```
명령 예
```
awstoe run --documents s3://bucket/key/doc.yaml --phases build,validate
```
고유 ID로 문서 실행
```
awstoe run --documents documentName.yaml --execution-id user-provided-id --phases build,test
```
에 대한 도움말 보기 AWSTOE
```
awstoe --help
```
# 사용자 지정 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 는 실패한 반복의 출력을 통합하지 않습니다.
# AWSTOE 구성 요소 관리자가 지원하는 작업 모듈
EC2 Image Builder와 같은 이미지 구축 서비스는 AWSTOE 작업 모듈을 사용하여 사용자 지정 머신 이미지를 구축하고 테스트하는 데 사용되는 EC2 인스턴스를 구성하는 데 도움이 됩니다. 이 섹션에서는 일반적으로 사용되는 AWSTOE 작업 모듈의 기능과 예제를 포함하여 이를 구성하는 방법을 설명합니다.
구성 요소는 일반 텍스트 YAML 문서를 사용하여 작성됩니다. 문서 구문에 대한 자세한 내용은 [사용자 지정 AWSTOE 구성 요소에 구성 요소 문서 프레임워크 사용](toe-use-documents.md) 섹션을 참조하세요.
**참고**
모든 작업 모듈은 실행할 때 Systems Manager 에이전트와 동일한 계정을 사용하며, Linux의 경우 `root`이고 Windows의 경우 `NT Authority\SYSTEM`입니다.
다음 상호 참조는 수행하는 작업 유형별로 작업 모듈을 분류합니다.
**일반 실행**
+ [Assert(Linux, Windows, macOS)](#action-modules-assertion)
+ [ExecuteBash(Linux, macOS)](#action-modules-executebash)
+ [ExecuteBinary(Linux, Windows, macOS)](#action-modules-executebinary)
+ [ExecuteDocument(Linux, Windows, macOS)](#action-modules-executedocument)
+ [ExecutePowerShell(Windows)](#action-modules-executepowershell)
**파일 다운로드 및 업로드**
+ [S3Download(Linux, Windows, macOS)](#action-modules-s3download)
+ [S3Upload(Linux, Windows, macOS)](#action-modules-s3upload)
+ [WebDownload(Linux, Windows, macOS)](#action-modules-webdownload)
**파일 시스템 작업**
+ [AppendFile(Linux, Windows, macOS)](#action-modules-appendfile)
+ [CopyFile(Linux, Windows, macOS)](#action-modules-copyfile)
+ [CopyFolder(Linux, Windows, macOS)](#action-modules-copyfolder)
+ [CreateFile(Linux, Windows, macOS)](#action-modules-createfile)
+ [CreateFolder(Linux, Windows, macOS)](#action-modules-createfolder)
+ [CreateSymlink(Linux, Windows, macOS)](#action-modules-createsymlink)
+ [DeleteFile(Linux, Windows, macOS)](#action-modules-deletefile)
+ [DeleteFolder(Linux, Windows, macOS)](#action-modules-deletefolder)
+ [ListFiles(Linux, Windows, macOS)](#action-modules-listfiles)
+ [MoveFile(Linux, Windows, macOS)](#action-modules-movefile)
+ [MoveFolder(Linux, Windows, macOS)](#action-modules-movefolder)
+ [ReadFile(Linux, Windows, macOS)](#action-modules-readfile)
+ [SetFileEncoding(Linux, Windows, macOS)](#action-modules-setfileencoding)
+ [SetFileOwner(Linux, Windows, macOS)](#action-modules-setfileowner)
+ [SetFolderOwner(Linux, Windows, macOS)](#action-modules-setfolderowner)
+ [SetFilePermissions(Linux, Windows, macOS)](#action-modules-setfilepermissions)
+ [SetFolderPermissions(Linux, Windows, macOS)](#action-modules-setfolderpermissions)
**소프트웨어 설치 작업**
+ [InstallMSI(Windows)](#action-modules-install-msi)
+ [UninstallMSI(Windows)](#action-modules-uninstall-msi)
**시스템 작업**
+ [Reboot(Linux, Windows)](#action-modules-reboot)
+ [SetRegistry(Windows)](#action-modules-setregistry)
+ [UpdateOS(Linux, Windows)](#action-modules-updateos)
## 일반 실행 모듈
다음 섹션에는 명령을 실행하고 실행 워크플로를 제어하는 작업 모듈에 대한 세부 정보가 포함되어 있습니다.
**Topics**
+ [Assert(Linux, Windows, macOS)](#action-modules-assertion)
+ [ExecuteBash(Linux, macOS)](#action-modules-executebash)
+ [ExecuteBinary(Linux, Windows, macOS)](#action-modules-executebinary)
+ [ExecuteDocument(Linux, Windows, macOS)](#action-modules-executedocument)
+ [ExecutePowerShell(Windows)](#action-modules-executepowershell)
### Assert(Linux, Windows, macOS)
**Assert** 작업 모듈은 [비교 연산자](toe-comparison-operators.md) 또는 [논리 연산자](toe-logical-operators.md)를 입력으로 사용하여 값 비교를 수행합니다. 연산자 표현식(true 또는 false)의 결과는 단계의 전체 성공 또는 실패 상태를 나타냅니다.
비교 또는 논리 연산자 표현식이 `true`로 평가되면 단계가 `Success`로 표시됩니다. 그렇지 않으면 단계가 `Failed`로 표시됩니다. 단계가 실패하면 `onFailure` 파라미터가 단계의 결과를 결정합니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 |
| --- | --- | --- | --- |
| input | 단일 비교 또는 논리 연산자를 포함합니다. 참고로 논리 연산자는 둘 이상의 비교 연산자를 포함할 수 있습니다. | 이는 연산자에 따라 가변적입니다. | 예 |
**입력 예제: `stringEquals` 비교 연산자를 사용한 간단한 비교**
이 예제는 `true`로 평가됩니다.
```
- name: StringComparison
action: Assert
inputs:
stringEquals: '2.1.1'
value: '{{ validate.ApplicationVersion.outputs.stdout }}'
```
**입력 예제: `patternMatches` 비교 연산자를 사용한 Regex 비교**
이 예제는 모두 `true`로 평가됩니다.
```
- name: Letters only
action: Assert
inputs:
patternMatches: '^[a-zA-Z]+$'
value: 'ThisIsOnlyLetters'
- name: Letters and spaces only
action: Assert
inputs:
patternMatches: '^[a-zA-Z\s]+$'
value: 'This text contains spaces'
- name: Numbers only
action: Assert
inputs:
patternMatches: '^[0-9]+$'
value: '1234567890'
```
**입력 예제: 논리 연산자 및 체인 변수를 사용한 중첩 비교**
다음 예제에서는 체인 변수와의 비교를 사용하는 논리 연산자와의 중첩 비교를 보여줍니다. 다음 중 하나가 true인 경우 `Assert`는 `true`로 평가됩니다.
+ `ApplicationVersion`은 `2.0`보다 크고 `CPUArchitecture`는 `arm64`와 같습니다.
+ `CPUArchitecture`는 `x86_64`와 같습니다.
```
- name: NestedComparisons
action: Assert
inputs:
or: # <- first level deep
- and: # <- second level deep
- numberGreaterThan: 2.0 # <- third level deep
value: '{{ validate.ApplicationVersion.outputs.stdout }}'
- stringEquals: 'arm64'
value: '{{ validate.CPUArchitecture.outputs.stdout }}'
- stringEquals: 'x86_64'
value: '{{ validate.CPUArchitecture.outputs.stdout }}'
```
**출력:**
`Assert`의 출력은 단계의 성공 또는 실패입니다.
### ExecuteBash(Linux, macOS)
**ExecuteBash** 작업 모듈을 사용하면 인라인 쉘 코드/명령을 사용하여 bash 스크립트를 실행할 수 있습니다. 이 모듈은 Linux를 지원합니다.
명령 블록에서 지정하는 모든 명령과 지침은 파일(예: `input.sh`)로 변환되고 bash 쉘과 함께 실행됩니다. 쉘 파일을 실행한 결과는 해당 단계의 종료 코드입니다.
**ExecuteBash** 모듈은 스크립트가 종료 코드 `194`(으)로 종료되는 경우 시스템 재시작을 처리합니다. 애플리케이션이 시작되면 다음 작업 중 하나를 수행합니다.
+ Systems Manager Agent에서 실행하는 경우, 애플리케이션은 종료 코드를 호출자에게 전달합니다. Systems Manager Agent는 [스크립트에서 관리형 인스턴스 재부팅](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)에 설명된 대로 시스템 재부팅을 처리하고 재시작을 시작한 것과 동일한 단계를 실행합니다.
+ 애플리케이션은 현재 `executionstate`(을)를 저장하고 애플리케이션을 다시 실행하도록 재시작 트리거를 구성한 다음 시스템을 다시 시작합니다.
시스템을 다시 시작한 후 애플리케이션은 재시작을 시작한 단계와 동일한 단계를 실행합니다. 이 기능이 필요한 경우 동일한 쉘 명령의 여러 호출을 처리할 수 있는 idempotent 스크립트를 작성해야 합니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 |
| --- | --- | --- | --- |
| commands | bash 구문에 따라 실행할 지침 또는 명령 목록이 포함되어 있습니다. 여러 줄의 YAML이 허용됩니다. | List | 예 |
**입력 예제: 재부팅 전과 재부팅 후**
```
name: ExitCode194Example
description: This shows how the exit code can be used to restart a system with ExecuteBash
schemaVersion: 1.0
phases:
- name: build
steps:
- name: RestartTrigger
action: ExecuteBash
inputs:
commands:
- |
REBOOT_INDICATOR=/var/tmp/reboot-indicator
if [ -f "${REBOOT_INDICATOR}" ]; then
echo 'The reboot file exists. Deleting it and exiting with success.'
rm "${REBOOT_INDICATOR}"
exit 0
fi
echo 'The reboot file does not exist. Creating it and triggering a restart.'
touch "${REBOOT_INDICATOR}"
exit 194
```
**출력**
| 필드 | 설명 | 형식 |
| --- | --- | --- |
| stdout | 명령 실행의 표준 출력. | 문자열 |
재부팅을 시작하고 작업 모듈의 일부로 종료 코드 `194`(을)를 반환하면 재부팅을 시작한 동일한 작업 모듈 단계에서 빌드가 재개됩니다. 종료 코드 없이 재부팅을 시작하면 빌드 프로세스가 실패할 수 있습니다.
**출력 예제: 재부팅 전(문서를 통해 처음으로)**
```
{
“stdout”: “The reboot file does not exist. Creating it and triggering a restart."
}
```
**출력 예제: 재부팅 후(문서를 통해 두 번째로)**
```
{
“stdout”: “The reboot file exists. Deleting it and exiting with success."
}
```
### ExecuteBinary(Linux, Windows, macOS)
**ExecuteBinary** 작업 모듈을 사용하면 명령줄 인수 목록을 사용하여 바이너리 파일을 실행할 수 있습니다.
**ExecuteBinary** 모듈은 바이너리 파일이 종료 코드 `194`(Linux) 또는 `3010`(Windows)으로 종료될 경우 시스템 재시작을 처리합니다. 이 경우 애플리케이션은 다음 작업 중 하나를 수행합니다.
+ Systems Manager Agent에서 실행하는 경우, 애플리케이션은 종료 코드를 호출자에게 전달합니다. Systems Manager Agent는 [스크립트에서 관리형 인스턴스 재부팅](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)에 설명된 대로 시스템 재시작을 처리하고 재시작을 시작한 것과 동일한 단계를 실행합니다.
+ 애플리케이션은 현재 `executionstate`(을)를 저장하고 애플리케이션을 다시 실행하도록 재시작 트리거를 구성한 다음 시스템을 다시 시작합니다.
시스템이 재시작된 후 애플리케이션은 재시작을 시작한 단계와 동일한 단계를 실행합니다. 이 기능이 필요한 경우 동일한 쉘 명령의 여러 호출을 처리할 수 있는 idempotent 스크립트를 작성해야 합니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 |
| --- | --- | --- | --- |
| path | 실행할 바이너리 파일 경로입니다. | 문자열 | 예 |
| arguments | 바이너리를 실행할 때 사용할 명령줄 인수 목록이 포함되어 있습니다. | 문자열 목록 | 아니요 |
**입력 예제: .NET 설치**
```
- name: "InstallDotnet"
action: ExecuteBinary
inputs:
path: C:\PathTo\dotnet_installer.exe
arguments:
- /qb
- /norestart
```
**출력**
| 필드 | 설명 | 형식 |
| --- | --- | --- |
| stdout | 명령 실행의 표준 출력. | 문자열 |
**출력 예제**
```
{
"stdout": "success"
}
```
### ExecuteDocument(Linux, Windows, macOS)
**ExecuteDocument** 작업 모듈은 한 문서에서 여러 구성 요소 문서를 실행하는 중첩된 구성 요소 문서에 대한 지원을 추가합니다. AWSTOE 는 런타임 시 입력 파라미터로 전달된 문서의 유효성을 검사합니다.
**제한 사항**
+ 이 작업 모듈은 한 번만 실행되고 재시도는 허용되지 않으며 제한 시간을 설정하는 옵션도 없습니다. **ExecuteDocument**는 다음과 같은 기본값을 설정하며, 기본값을 변경하려고 하면 오류를 반환합니다.
+ `timeoutSeconds`: -1
+ `maxAttempts`: 1
**참고**
이러한 값은 비워 둘 수 있으며 기본값을 AWSTOE 사용합니다.
+ 문서 중첩은 최대 세 개 수준까지 허용되지만, 그 이상은 허용되지 않습니다. 최상위 수준은 중첩되지 않으므로 세 개 수준의 중첩은 네 가지 문서 수준으로 변환됩니다. 이 시나리오에서는 최하위 수준 문서가 다른 문서를 호출해서는 안 됩니다.
+ 구성 요소 문서의 순환 실행은 허용되지 않습니다. 반복 구성 외부에서 자신을 호출하거나 현재 실행 체인의 상위에 있는 다른 문서를 호출하는 모든 문서는 사이클을 시작하여 무한 루프를 초래할 수 있습니다. AWSTOE 가 순환 실행을 감지하면 실행을 중지하고 실패를 기록합니다.
![\[ExecuteDocument 작업 모듈에 대한 중첩 수준 제한.\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/images/toe-component-document-nesting.png)
구성 요소 문서가 자체적으로 실행되거나 현재 실행 체인의 상위에 있는 구성 요소 문서를 실행하려고 하면 실행되지 않습니다.
**입력**
| 키 이름 | 설명 | 형식 | 필수 |
| --- | --- | --- | --- |
| document | 구성 요소 문서의 경로. 유효한 옵션은 다음과 같습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | 문자열 | 예 |
| document-s3-bucket-owner | 구성 요소 문서가 저장된 S3 버킷의 S3 버킷 소유자의 계정 ID입니다. *(구성 요소 문서에서 S3 URI를 사용하는 경우 권장합니다.)* | 문자열 | No |
| phases | 구성 요소 문서에서 실행할 수 있는 단계로, 쉼표로 구분된 목록으로 표시됩니다. 단계가 지정되지 않은 경우 모든 단계가 실행됩니다. | 문자열 | No |
| parameters | 런타임 시 구성 요소 문서에 키 값 페어로 전달되는 입력 파라미터입니다. | 파라미터 맵 목록 | 아니요 |
**파라미터 맵 입력**
| 키 이름 | 설명 | 형식 | 필수 |
| --- | --- | --- | --- |
| name | **ExecuteDocument** 작업 모듈이 실행 중인 구성 요소 문서에 전달할 입력 파라미터의 이름입니다. | 문자열 | 예 |
| value | 입력 파라미터의 값입니다. | 문자열 | 예 |
**입력 예제**
다음 예제는 설치 경로에 따른 구성 요소 문서 입력의 변형을 보여줍니다.
**입력 예제: 로컬 문서 경로**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
inputs:
document: Sample-1.yaml
phases: build
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**입력 예제: 문서 경로로서의 S3 URI**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
inputs:
document: s3://my-bucket/Sample-1.yaml
document-s3-bucket-owner: 123456789012
phases: build,validate
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**입력 예제: 문서 경로로서의 EC2 Image Builder 구성 요소 ARN**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
inputs:
document: arn:aws:imagebuilder:us-west-2:aws:component/Sample-Test/1.0.0
phases: test
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**ForEach 루프를 사용하여 문서 실행**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
loop:
name: 'myForEachLoop'
forEach:
- Sample-1.yaml
- Sample-2.yaml
inputs:
document: "{{myForEachLoop.value}}"
phases: test
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**For 루프를 사용하여 문서 실행**
```
# main.yaml
schemaVersion: 1.0
phases:
- name: build
steps:
- name: ExecuteNestedDocument
action: ExecuteDocument
loop:
name: 'myForLoop'
for:
start: 1
end: 2
updateBy: 1
inputs:
document: "Sample-{{myForLoop.value}}.yaml"
phases: test
parameters:
- name: parameter-1
value: value-1
- name: parameter-2
value: value-2
```
**출력**
AWSTOE 는 실행될 `detailedoutput.json` 때마다 라는 출력 파일을 생성합니다. 이 파일에는 실행 중에 호출되는 모든 구성 요소 문서의 모든 단계에 대한 세부 정보가 포함됩니다. **ExecuteDocument** 작업 모듈의 경우 `outputs` 필드에서 간략한 런타임 요약과 `detailedOutput`에서 실행되는 단계(phases), 단계(steps) 및 문서에 대한 세부 정보를 찾을 수 있습니다.
```
{
\"executedStepCount\":1,\"executionId\":\"97054e22-06cc-11ec-9b14-acde48001122\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\"
}",
```
각 구성 요소 문서의 출력 요약 개체에는 다음과 같은 세부 정보가 여기 나온 것처럼 샘플 값과 함께 포함되어 있습니다.
+ executedStepCount":1
+ "executionId":"12345a67-89bc-01de-2f34-abcd56789012"
+ "failedStepCount":0
+ "failureMessage":""
+ "ignoredFailedStepCount":0
+ "logUrl":""
+ "status":"success"
**출력 예시**
다음 예제에서는 중첩 실행이 발생할 때 **ExecuteDocument** 작업 모듈의 출력을 보여 줍니다. 이 예제에서 `main.yaml` 구성 요소 문서는 `Sample-1.yaml` 구성 요소 문서를 성공적으로 실행합니다.
```
{
"executionId": "12345a67-89bc-01de-2f34-abcd56789012",
"status": "success",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"documents": [
{
"name": "",
"filePath": "main.yaml",
"status": "success",
"description": "",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"phases": [
{
"name": "build",
"status": "success",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"steps": [
{
"name": "ExecuteNestedDocument",
"status": "success",
"failureMessage": "",
"timeoutSeconds": -1,
"onFailure": "Abort",
"maxAttempts": 1,
"action": "ExecuteDocument",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"inputs": "[{\"document\":\"Sample-1.yaml\",\"document-s3-bucket-owner\":\"\",\"phases\":\"\",\"parameters\":null}]",
"outputs": "[{\"executedStepCount\":1,\"executionId\":\"98765f43-21ed-09cb-8a76-fedc54321098\",\"failedStepCount\":0,\"failureMessage\":\"\",\"ignoredFailedStepCount\":0,\"logUrl\":\"\",\"status\":\"success\"}]",
"loop": null,
"detailedOutput": [
{
"executionId": "98765f43-21ed-09cb-8a76-fedc54321098",
"status": "success",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"documents": [
{
"name": "",
"filePath": "Sample-1.yaml",
"status": "success",
"description": "",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"phases": [
{
"name": "build",
"status": "success",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"failureMessage": "",
"steps": [
{
"name": "ExecuteBashStep",
"status": "success",
"failureMessage": "",
"timeoutSeconds": 7200,
"onFailure": "Abort",
"maxAttempts": 1,
"action": "ExecuteBash",
"startTime": "2021-08-26T17:20:31-07:00",
"endTime": "2021-08-26T17:20:31-07:00",
"inputs": "[{\"commands\":[\"echo \\\"Hello World!\\\"\"]}]",
"outputs": "[{\"stdout\":\"Hello World!\"}]",
"loop": null,
"detailedOutput": null
}]
}]
}]
}]
}]
}]
}]
}
```
### ExecutePowerShell(Windows)
**ExecutePowerShell** 작업 모듈을 사용하면 인라인 쉘 코드/명령을 사용하여 PowerShell 스크립트를 실행할 수 있습니다. 이 모듈은 Windows 플랫폼과 Windows PowerShell을 지원합니다.
명령 블록에 지정된 모든 명령/지침은 스크립트 파일(예: `input.ps1`)로 변환되며 Windows PowerShell을 사용하여 실행됩니다. 쉘 파일을 실행한 결과는 종료 코드입니다.
**ExecutePowerShell** 모듈은 쉘 명령이 종료 코드 `3010`(으)로 종료된 경우, 시스템 재시작을 처리합니다. 애플리케이션이 시작되면 다음 작업 중 하나를 수행합니다.
+ Systems Manager 에이전트가 실행하는 경우 종료 코드를 호출자에게 전달합니다. Systems Manager Agent는 [스크립트에서 관리형 인스턴스 재부팅](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)에 설명된 대로 시스템 재부팅을 처리하고 재시작을 시작한 것과 동일한 단계를 실행합니다.
+ 현재 `executionstate`(을)를 저장하고 애플리케이션을 다시 실행하도록 재시작 트리거를 구성한 다음 시스템을 재부팅합니다.
시스템을 다시 시작한 후 애플리케이션은 재시작을 시작한 단계와 동일한 단계를 실행합니다. 이 기능이 필요한 경우 동일한 쉘 명령의 여러 호출을 처리할 수 있는 idempotent 스크립트를 작성해야 합니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 |
| --- | --- | --- | --- |
| commands | PowerShell 구문에 따라 실행할 지침 또는 명령 목록이 포함됩니다. 여러 줄의 YAML이 허용됩니다. | 문자열 목록 | 예. `commands` 또는 `file`(을)를 지정해야 하며, 둘 다 지정하지는 않습니다. |
| file | PowerShell 스크립트 파일에 대한 경로를 포함합니다. PowerShell은 -file 명령줄 인수를 사용하여 이 파일에 대해 실행됩니다. 이 경로는 .ps1 파일을 가리켜야 합니다. | 문자열 | 예. `commands` 또는 `file`(을)를 지정해야 하며, 둘 다 지정하지는 않습니다. |
**입력 예제: 재부팅 전과 재부팅 후**
```
name: ExitCode3010Example
description: This shows how the exit code can be used to restart a system with ExecutePowerShell
schemaVersion: 1.0
phases:
- name: build
steps:
- name: RestartTrigger
action: ExecutePowerShell
inputs:
commands:
- |
$rebootIndicator = Join-Path -Path $env:SystemDrive -ChildPath 'reboot-indicator'
if (Test-Path -Path $rebootIndicator) {
Write-Host 'The reboot file exists. Deleting it and exiting with success.'
Remove-Item -Path $rebootIndicator -Force | Out-Null
[System.Environment]::Exit(0)
}
Write-Host 'The reboot file does not exist. Creating it and triggering a restart.'
New-Item -Path $rebootIndicator -ItemType File | Out-Null
[System.Environment]::Exit(3010)
```
**출력**
| 필드 | 설명 | 형식 |
| --- | --- | --- |
| stdout | 명령 실행의 표준 출력. | 문자열 |
재부팅을 실행하고 작업 모듈의 일부로 종료 코드 `3010`(을)를 반환하면, 재부팅을 시작한 동일한 작업 모듈 단계에서 빌드가 재개됩니다. 종료 코드 없이 재부팅을 실행하면, 빌드 프로세스가 실패할 수 있습니다.
**출력 예제: 재부팅 전(문서를 통해 처음으로)**
```
{
“stdout”: “The reboot file does not exist. Creating it and triggering a restart."
}
```
**출력 예제: 재부팅 후(문서를 통해 두 번째로)**
```
{
“stdout”: “The reboot file exists. Deleting it and exiting with success."
}
```
## 파일 다운로드 및 업로드 모듈
다음 섹션에는 파일을 업로드하거나 다운로드하는 작업 모듈에 대한 세부 정보가 포함되어 있습니다.
**Topics**
+ [S3Download(Linux, Windows, macOS)](#action-modules-s3download)
+ [S3Upload(Linux, Windows, macOS)](#action-modules-s3upload)
+ [WebDownload(Linux, Windows, macOS)](#action-modules-webdownload)
### S3Download(Linux, Windows, macOS)
`S3Download` 작업 모듈을 사용하면, Amazon S3 객체 또는 객체 집합을 `destination` 경로로 지정한 로컬 파일 또는 폴더에 다운로드할 수 있습니다. 지정된 위치에 파일이 이미 있고 `overwrite` 플래그가 true로 설정된 경우, `S3Download`(이)가 파일을 덮어씁니다.
`source` 위치는 Amazon S3의 특정 객체를 가리키거나 별표 와일드카드(`*`)와 함께 키 접두사를 사용하여 키 접두사 경로와 일치하는 객체 집합을 다운로드할 수 있습니다. `source` 위치에서 키 접두사를 지정하면 `S3Download` 작업 모듈이 접두사와 일치하는 모든 항목(파일 및 폴더 포함)을 다운로드합니다. 접두사와 일치하는 모든 항목을 다운로드할 수 있도록 키 접두사가 슬래시 뒤에 별표(`/*`)로 끝나는지 확인합니다. 예를 들어 `s3://my-bucket/my-folder/*`입니다.
다운로드 중에 지정된 키 접두사에 대한 `S3Download` 작업이 실패하는 경우, 폴더 콘텐츠는 실패 이전 상태로 롤백되지 않습니다. 대상 폴더는 장애 발생 시점의 상태로 유지됩니다.
**지원되는 사용 사례**
`S3Download` 작업 모듈은 다음 사용 사례를 지원합니다.
+ Amazon S3 객체는 다운로드 경로에 지정된 대로 로컬 폴더에 다운로드됩니다.
+ Amazon S3 파일 경로에 키 접두사가 있는 Amazon S3 객체는 지정된 로컬 폴더로 다운로드되며, 이 폴더는 키 접두사와 일치하는 모든 Amazon S3 객체를 로컬 폴더에 반복적으로 복사합니다.
**IAM 요구 사항**
인스턴스 프로파일에 연결하는 IAM 역할에는 `S3Download` 작업 모듈을 실행할 권한이 있어야 합니다. 다음 IAM 정책을 인스턴스 프로파일과 관련된 IAM 역할에 연결해야 합니다.
+ **단일 파일**: 버킷/객체에 대한 `s3:GetObject`(예: `arn:aws:s3:::BucketName/*`)
+ **다중 파일**: 버킷/객체에 대한 `s3:ListBucket`(예: `arn:aws:s3:::BucketName`) 및 버킷/객체에 대한 `s3:GetObject`(예: `arn:aws:s3:::BucketName/*`)
**Input**
| Key(키) | 설명 | 형식 | 필수 | 기본값 |
| --- | --- | --- | --- | --- |
| `source` | 다운로드의 소스가 되는 Amazon S3 버킷입니다. 특정 객체의 경로를 지정하거나, 슬래시 다음 별표 와일드카드(`/*`)로 끝나는 키 접두사를 사용하여 키 접두사와 일치하는 객체 집합을 다운로드할 수 있습니다. | 문자열 | 예 | 해당 사항 없음 |
| `destination` | Amazon S3 객체가 다운로드되는 로컬 경로입니다. 단일 파일을 다운로드하려면, 파일 이름을 경로의 일부로 지정해야 합니다. 예를 들어 `/myfolder/package.zip`입니다. | 문자열 | 예 | 해당 사항 없음 |
| `expectedBucketOwner` | `source` 경로에 제공된 버킷의 예상 소유자 계정 ID입니다. 원본에 지정된 Amazon S3 버킷의 소유권을 확인하는 것이 좋습니다. | 문자열 | No | 해당 사항 없음 |
| `overwrite` | true로 설정하면 지정된 로컬 경로의 대상 폴더에 같은 이름의 파일이 이미 있는 경우 다운로드 파일이 로컬 파일을 덮어씁니다. false로 설정하면 로컬 시스템의 기존 파일이 덮어써지지 않고, 작업 모듈이 실패하며 다운로드 오류가 발생합니다. 예: `Error: S3Download: File already exists and "overwrite" property for "destination" file is set to false. Cannot download.` | 불린(Boolean) | 아니요 | true |
**참고**
다음 예제에서는 Windows 폴더 경로를 Linux 경로로 바꿀 수 있습니다. 예를 들어, `C:\myfolder\package.zip`(을)를 `/myfolder/package.zip`(으)로 바꿀 수 있습니다.
**입력 예제: Amazon S3 객체를 로컬 파일에 복사**
다음 예제에서는 Amazon S3 객체를 로컬 파일에 복사하는 방법을 보여 줍니다.
```
- name: DownloadMyFile
action: S3Download
inputs:
- source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
destination: C:\myfolder\package.zip
expectedBucketOwner: 123456789022
overwrite: false
- source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
destination: C:\myfolder\package.zip
expectedBucketOwner: 123456789022
overwrite: true
- source: s3://amzn-s3-demo-source-bucket/path/to/package.zip
destination: C:\myfolder\package.zip
expectedBucketOwner: 123456789022
```
**입력 예제: 키 접두사가 있는 Amazon S3 버킷의 모든 Amazon S3 객체를 로컬 폴더에 복사**
다음 예제에서는 키 접두사가 있는 Amazon S3 버킷의 모든 Amazon S3 객체를 로컬 폴더로 복사하는 방법을 보여 줍니다. Amazon S3에는 폴더라는 개념이 없으므로, 키 접두사와 일치하는 모든 객체가 복사됩니다. 다운로드할 수 있는 최대 객체 수는 1,000개입니다.
```
- name: MyS3DownloadKeyprefix
action: S3Download
maxAttempts: 3
inputs:
- source: s3://amzn-s3-demo-source-bucket/path/to/*
destination: C:\myfolder\
expectedBucketOwner: 123456789022
overwrite: false
- source: s3://amzn-s3-demo-source-bucket/path/to/*
destination: C:\myfolder\
expectedBucketOwner: 123456789022
overwrite: true
- source: s3://amzn-s3-demo-source-bucket/path/to/*
destination: C:\myfolder\
expectedBucketOwner: 123456789022
```
**출력**
없음.
### S3Upload(Linux, Windows, macOS)
**S3Upload** 작업 모듈을 사용하면 원본 파일 또는 폴더에서 Amazon S3 위치로 파일을 업로드할 수 있습니다. 소스 위치에 지정된 경로에 와일드카드(`*`)를 사용하여 경로가 와일드카드 패턴과 일치하는 모든 파일을 업로드할 수 있습니다.
재귀 **S3Upload** 작업이 실패하는 경우 이미 업로드된 모든 파일은 대상 Amazon S3 버킷에 남아 있게 됩니다.
**지원되는 사용 사례**
+ 로컬 파일을 Amazon S3 객체로.
+ 폴더의 로컬 파일(와일드카드 포함)을 Amazon S3 키 접두사로.
+ 로컬 폴더(`recurse`를 `true`로 설정해야 함)를 Amazon S3 키 접두사로 복사합니다.
**IAM 요구 사항**
인스턴스 프로파일에 연결하는 IAM 역할에는 `S3Upload` 작업 모듈을 실행할 권한이 있어야 합니다. 다음 IAM 정책을 인스턴스 프로파일과 관련된 IAM 역할에 연결해야 합니다. 정책은 대상 Amazon S3 버킷에 `s3:PutObject` 권한을 부여해야 합니다. 예: `arn:aws:s3:::BucketName/*`).
**Input**
| Key(키) | 설명 | 형식 | 필수 | 기본값 |
| --- | --- | --- | --- | --- |
| `source` | 소스 파일/폴더가 시작되는 로컬 경로. `source`(은)는 별표 와일드카드(`*`)(을)를 지원합니다. | 문자열 | 예 | 해당 사항 없음 |
| `destination` | 원본 파일/폴더가 업로드되는 대상 Amazon S3 버킷의 경로입니다. | 문자열 | 예 | 해당 사항 없음 |
| `recurse` | `true`(으)로 설정하면 **S3Upload**(을)를 재귀적으로 수행합니다. | 문자열 | No | `false` |
| `expectedBucketOwner` | 대상 경로에 지정된 Amazon S3 버킷의 예상 소유자 계정 ID입니다. 대상에 지정된 Amazon S3 버킷의 소유권을 확인하는 것이 좋습니다. | 문자열 | No | 해당 사항 없음 |
**입력 예제: 로컬 파일을 Amazon S3 객체에 복사**
다음 예제에서는 로컬 파일을 Amazon S3 객체에 복사하는 방법을 보여 줍니다.
```
- name: MyS3UploadFile
action: S3Upload
onFailure: Abort
maxAttempts: 3
inputs:
- source: C:\myfolder\package.zip
destination: s3://amzn-s3-demo-destination-bucket/path/to/package.zip
expectedBucketOwner: 123456789022
```
**입력 예제: 키 접두사를 사용하여 로컬 폴더의 모든 파일을 Amazon S3 버킷으로 복사**
다음 예제에서는 키 접두사를 사용하여 로컬 폴더의 모든 파일을 Amazon S3 버킷으로 복사하는 방법을 보여 줍니다. `recurse`(이)가 지정되지 않았으므로 이 예제는 하위 폴더나 해당 콘텐츠를 복사하지 않으며 기본값은 `false`입니다.
```
- name: MyS3UploadMultipleFiles
action: S3Upload
onFailure: Abort
maxAttempts: 3
inputs:
- source: C:\myfolder\*
destination: s3://amzn-s3-demo-destination-bucket/path/to/
expectedBucketOwner: 123456789022
```
**입력 예제: 모든 파일 및 폴더를 로컬 폴더에서 Amazon S3 버킷으로 재귀적으로 복사**
다음 예제에서는 모든 파일 및 폴더를 로컬 폴더에서 키 접두사를 사용하여 Amazon S3 버킷으로 재귀적으로 복사하는 방법을 보여줍니다.
```
- name: MyS3UploadFolder
action: S3Upload
onFailure: Abort
maxAttempts: 3
inputs:
- source: C:\myfolder\*
destination: s3://amzn-s3-demo-destination-bucket/path/to/
recurse: true
expectedBucketOwner: 123456789022
```
**출력**
없음.
### WebDownload(Linux, Windows, macOS)
**WebDownload** 작업 모듈을 사용하면 HTTP/HTTPS 프로토콜을 통해 원격 위치에서 파일 및 리소스를 다운로드할 수 있습니다(*HTTPS 권장*). 다운로드 수나 크기에는 제한이 없습니다. 이 모듈은 재시도 및 지수 백오프 로직을 처리합니다.
사용자 입력에 따라 각 다운로드 작업의 성공 시도는 최대 5회까지 할당됩니다. 이러한 시도는 작업 모듈 오류와 관련된 문서 `steps`의 `maxAttempts` 필드에 지정된 시도와 다릅니다.
이 작업 모듈은 리디렉션을 묵시적으로 처리합니다. `200`을(를) 제외한 모든 HTTP 상태 코드에서 오류가 발생합니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 |
| --- | --- | --- | --- | --- |
| source | RFC 3986 표준을 따르는 유효한 HTTP/HTTPS URL(HTTPS 권장)입니다. chaining 표현식은 허용됩니다. | 문자열 | 예 | 해당 사항 없음 |
| destination | 로컬 시스템의 절대 또는 상대 파일이나 폴더 경로입니다. 폴더 경로는 /(으)로 끝나야 합니다. /(으)로 끝나지 않는 경우, 파일 경로로 취급됩니다. 모듈은 성공적인 다운로드를 위해 필요한 파일이나 폴더를 생성합니다. chaining 표현식은 허용됩니다. | 문자열 | 예 | 해당 사항 없음 |
| overwrite | 활성화하면 로컬 시스템의 기존 파일을 다운로드한 파일 또는 리소스로 덮어씁니다. 활성화하지 않으면 로컬 시스템의 기존 파일을 덮어쓰지 않고, 작업 모듈이 실패하며 오류가 발생합니다. 덮어쓰기가 활성화되고 체크섬과 알고리즘이 지정된 경우, 작업 모듈은 기존 파일의 체크섬과 해시가 일치하지 않는 경우에만 파일을 다운로드합니다. | 부울 | 아니요 | true |
| checksum | 체크섬을 지정하면, 제공된 알고리즘으로 생성된 다운로드한 파일의 해시와 비교하여 체크섬이 검사됩니다. 파일 검증을 활성화하려면, 체크섬과 알고리즘을 모두 제공해야 합니다. chaining 표현식은 허용됩니다. | 문자열 | No | 해당 사항 없음 |
| algorithm | 체크섬을 계산하는 데 사용되는 알고리즘입니다. 옵션은 MD5, SHA1, SHA256 및 SHA512입니다. 파일 검증을 활성화하려면, 체크섬과 알고리즘을 모두 제공해야 합니다. chaining 표현식은 허용됩니다. | 문자열 | No | 해당 사항 없음 |
| ignoreCertificateErrors | 활성화된 경우 SSL 인증서 검증이 무시됩니다. | 부울 | 아니요 | false |
**출력**
| 키 이름 | 설명 | 형식 |
| --- | --- | --- |
| destination | 다운로드한 파일 또는 리소스가 저장되는 대상 경로를 지정하는 줄 바꿈 문자로 구분된 문자열입니다. | 문자열 |
**입력 예제: 로컬 대상으로 원격 파일 다운로드**
```
- name: DownloadRemoteFile
action: WebDownload
maxAttempts: 3
inputs:
- source: https://testdomain/path/to/java14.zip
destination: C:\testfolder\package.zip
```
**출력:**
```
{
"destination": "C:\\testfolder\\package.zip"
}
```
**입력 예제: 둘 이상의 로컬 대상에 둘 이상의 원격 파일 다운로드**
```
- name: DownloadRemoteFiles
action: WebDownload
maxAttempts: 3
inputs:
- source: https://testdomain/path/to/java14.zip
destination: /tmp/java14_renamed.zip
- source: https://testdomain/path/to/java14.zip
destination: /tmp/create_new_folder_and_add_java14_as_zip/
```
**출력:**
```
{
"destination": "/tmp/create_new_folder/java14_renamed.zip\n/tmp/create_new_folder_and_add_java14_as_zip/java14.zip"
}
```
**입력 예제: 로컬 대상을 덮어쓰지 않고 원격 파일 하나를 다운로드하고 파일 확인을 통해 다른 원격 파일을 다운로드합니다.**
```
- name: DownloadRemoteMultipleProperties
action: WebDownload
maxAttempts: 3
inputs:
- source: https://testdomain/path/to/java14.zip
destination: C:\create_new_folder\java14_renamed.zip
overwrite: false
- source: https://testdomain/path/to/java14.zip
destination: C:\create_new_folder_and_add_java14_as_zip\
checksum: ac68bbf921d953d1cfab916cb6120864
algorithm: MD5
overwrite: true
```
**출력:**
```
{
"destination": "C:\\create_new_folder\\java14_renamed.zip\nC:\\create_new_folder_and_add_java14_as_zip\\java14.zip"
}
```
**입력 예제: 원격 파일 다운로드 및 SSL 인증 검증 무시**
```
- name: DownloadRemoteIgnoreValidation
action: WebDownload
maxAttempts: 3
inputs:
- source: https://www.bad-ssl.com/resource
destination: /tmp/downloads/
ignoreCertificateErrors: true
```
**출력:**
```
{
"destination": "/tmp/downloads/resource"
}
```
## 파일 시스템 작업 모듈
다음 섹션에는 파일 시스템 작업을 수행하는 작업 모듈에 대한 세부 정보가 포함되어 있습니다.
**Topics**
+ [AppendFile(Linux, Windows, macOS)](#action-modules-appendfile)
+ [CopyFile(Linux, Windows, macOS)](#action-modules-copyfile)
+ [CopyFolder(Linux, Windows, macOS)](#action-modules-copyfolder)
+ [CreateFile(Linux, Windows, macOS)](#action-modules-createfile)
+ [CreateFolder(Linux, Windows, macOS)](#action-modules-createfolder)
+ [CreateSymlink(Linux, Windows, macOS)](#action-modules-createsymlink)
+ [DeleteFile(Linux, Windows, macOS)](#action-modules-deletefile)
+ [DeleteFolder(Linux, Windows, macOS)](#action-modules-deletefolder)
+ [ListFiles(Linux, Windows, macOS)](#action-modules-listfiles)
+ [MoveFile(Linux, Windows, macOS)](#action-modules-movefile)
+ [MoveFolder(Linux, Windows, macOS)](#action-modules-movefolder)
+ [ReadFile(Linux, Windows, macOS)](#action-modules-readfile)
+ [SetFileEncoding(Linux, Windows, macOS)](#action-modules-setfileencoding)
+ [SetFileOwner(Linux, Windows, macOS)](#action-modules-setfileowner)
+ [SetFolderOwner(Linux, Windows, macOS)](#action-modules-setfolderowner)
+ [SetFilePermissions(Linux, Windows, macOS)](#action-modules-setfilepermissions)
+ [SetFolderPermissions(Linux, Windows, macOS)](#action-modules-setfolderpermissions)
### AppendFile(Linux, Windows, macOS)
**AppendFile** 작업 모듈은 지정된 콘텐츠를 파일의 기존 내용에 추가합니다.
파일 인코딩 값이 기본 인코딩(`utf-8`) 값과 다른 경우, `encoding` 옵션을 사용하여 파일 인코딩 값을 지정할 수 있습니다. 기본적으로 `utf-16` 및 `utf-32`(은)는 리틀 엔디안 인코딩을 사용하는 것으로 간주됩니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 파일이 런타임에 존재하지 않습니다.
+ 파일 내용을 수정할 수 있는 쓰기 권한이 없습니다.
+ 파일 작업 중에 모듈에서 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 파일 경로. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| content | 파일에 추가할 콘텐츠입니다. | 문자열 | No | 빈 문자열 | 해당 사항 없음 | 예 |
| encoding | 인코딩 표준입니다. | 문자열 | No | utf8 | utf8, utf-8, utf16, utf-16, utf16-LE, utf-16-LE, utf16-BE, utf-16-BE, utf32, utf-32, utf32-LE, utf-32-LE, utf32-BE 및 utf-32-BE. 인코딩 옵션 값은 대/소문자를 구분하지 않습니다. | 예 |
**입력 예제: 인코딩 없이 파일 추가(Linux)**
```
- name: AppendingFileWithOutEncodingLinux
action: AppendFile
inputs:
- path: ./Sample.txt
content: "The string to be appended to the file"
```
**입력 예제: 인코딩 없이 파일 추가(Windows)**
```
- name: AppendingFileWithOutEncodingWindows
action: AppendFile
inputs:
- path: C:\MyFolder\MyFile.txt
content: "The string to be appended to the file"
```
**입력 예제: 인코딩으로 파일 추가(Linux)**
```
- name: AppendingFileWithEncodingLinux
action: AppendFile
inputs:
- path: /FolderName/SampleFile.txt
content: "The string to be appended to the file"
encoding: UTF-32
```
**입력 예제: 인코딩으로 파일 추가(Windows)**
```
- name: AppendingFileWithEncodingWindows
action: AppendFile
inputs:
- path: C:\MyFolderName\SampleFile.txt
content: "The string to be appended to the file"
encoding: UTF-32
```
**입력 예제: 빈 문자열로 파일 추가(Linux)**
```
- name: AppendingEmptyStringLinux
action: AppendFile
inputs:
- path: /FolderName/SampleFile.txt
```
**입력 예제: 빈 문자열로 파일 추가(Windows)**
```
- name: AppendingEmptyStringWindows
action: AppendFile
inputs:
- path: C:\MyFolderName\SampleFile.txt
```
**출력**
없음.
### CopyFile(Linux, Windows, macOS)
**CopyFile** 작업 모듈은 지정된 소스의 파일을 지정된 대상으로 복사합니다. 기본적으로 모듈은 런타임 시 대상 폴더가 없는 경우 대상 폴더를 재귀적으로 만듭니다.
지정된 이름의 파일이 지정된 폴더에 이미 있는 경우, 작업 모듈은 기본적으로 기존 파일을 덮어씁니다. 덮어쓰기 옵션을 `false`(으)로 설정하여 이 기본 동작을 재정의할 수 있습니다. 덮어쓰기 옵션이 `false`(으)로 설정되어 있고 지정된 위치에 지정된 이름을 가진 파일이 이미 있는 경우, 작업 모듈은 오류를 반환합니다. 이 옵션은 기본적으로 덮어쓰는 Linux의 `cp` 명령과 동일하게 작동합니다.
소스 파일 이름에는 와일드카드(`*`)가 포함될 수 있습니다. 와일드카드 문자는 마지막 파일 경로 구분자(`/` 또는 `\`) 뒤에만 사용할 수 있습니다. 와일드카드 문자가 소스 파일 이름에 포함된 경우, 와일드카드와 일치하는 모든 파일이 대상 폴더에 복사됩니다. 와일드카드 문자를 사용하여 둘 이상의 파일을 이동하려는 경우, `destination` 옵션 입력 시 대상 입력이 폴더임을 나타내는 파일 경로 구분자(`/` 또는 `\`)로 끝나야 합니다.
대상 파일 이름이 원본 파일 이름과 다른 경우, `destination` 옵션을 사용하여 대상 파일 이름을 지정할 수 있습니다. 대상 파일 이름을 지정하지 않으면, 원본 파일의 이름이 대상 파일을 만드는 데 사용됩니다. 마지막 파일 경로 구분자(`/` 또는 `\`) 뒤에 오는 모든 텍스트는 파일 이름으로 취급됩니다. 소스 파일과 같은 파일 이름을 사용하려면, `destination` 옵션 입력 시 파일 경로 구분자(`/` 또는 `\`)로 끝나야 합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 폴더에 파일을 생성할 수 있는 권한이 없습니다.
+ 소스 파일이 런타임에 존재하지 않습니다.
+ 지정된 파일 이름을 가진 폴더가 이미 있으며 `overwrite` 옵션이 `false`(으)로 설정되어 있습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| source | 소스 파일 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| destination | 대상 파일 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| overwrite | false로 설정하면 지정된 위치에 지정된 이름을 가진 파일이 이미 있는 경우 대상 파일이 교체되지 않습니다. | 부울 | 아니요 | true | 해당 사항 없음 | 예 |
**입력 예제: 파일 복사(Linux)**
```
- name: CopyingAFileLinux
action: CopyFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/destinationFile.txt
```
**입력 예제: 파일 복사(Windows)**
```
- name: CopyingAFileWindows
action: CopyFile
inputs:
- source: C:\MyFolder\Sample.txt
destination: C:\MyFolder\destinationFile.txt
```
**입력 예제: 소스 파일 이름을 사용하여 파일 복사(Linux)**
```
- name: CopyingFileWithSourceFileNameLinux
action: CopyFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/
```
**입력 예제: 소스 파일 이름을 사용하여 파일 복사(Windows)**
```
- name: CopyingFileWithSourceFileNameWindows
action: CopyFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder\
```
**입력 예제: 와일드카드 문자를 사용하여 파일 복사(Linux)**
```
- name: CopyingFilesWithWildCardLinux
action: CopyFile
inputs:
- source: /Sample/MyFolder/Sample*
destination: /MyFolder/
```
**입력 예제: 와일드카드 문자를 사용하여 파일 복사(Windows)**
```
- name: CopyingFilesWithWildCardWindows
action: CopyFile
inputs:
- source: C:\Sample\MyFolder\Sample*
destination: C:\MyFolder\
```
**입력 예제: 덮어쓰지 않고 파일 복사(Linux)**
```
- name: CopyingFilesWithoutOverwriteLinux
action: CopyFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/destinationFile.txt
overwrite: false
```
**입력 예제: 덮어쓰지 않고 파일 복사(Windows)**
```
- name: CopyingFilesWithoutOverwriteWindows
action: CopyFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder\destinationFile.txt
overwrite: false
```
**출력**
없음.
### CopyFolder(Linux, Windows, macOS)
**CopyFolder** 작업 모듈은 지정된 소스의 폴더를 지정된 대상으로 복사합니다. `source` 옵션에 대한 입력은 복사할 폴더이고, `destination` 옵션에 대한 입력은 소스 폴더의 콘텐츠가 복사되는 폴더입니다. 기본적으로 모듈은 런타임 시 대상 폴더가 없는 경우 대상 폴더를 재귀적으로 만듭니다.
지정된 이름의 폴더가 지정된 폴더에 이미 있는 경우, 작업 모듈은 기본적으로 기존 폴더를 덮어씁니다. 덮어쓰기 옵션을 `false`(으)로 설정하여 이 기본 동작을 재정의할 수 있습니다. 덮어쓰기 옵션이 `false`(으)로 설정되어 있고 지정된 위치에 지정된 이름을 가진 폴더가 이미 있는 경우, 작업 모듈은 오류를 반환합니다.
소스 폴더 이름에는 와일드카드(`*`)가 포함될 수 있습니다. 와일드카드 문자는 마지막 파일 경로 구분자(`/` 또는 `\`) 뒤에만 사용할 수 있습니다. 와일드카드 문자가 소스 폴더 이름에 포함된 경우, 와일드카드와 일치하는 모든 폴더가 대상 폴더에 복사됩니다. 와일드카드 문자를 사용하여 폴더를 두 개 이상 복사하려는 경우, `destination` 옵션 입력 시 대상 입력이 폴더임을 나타내는 파일 경로 구분자(`/` 또는 `\`)로 끝나야 합니다.
대상 폴더 이름이 소스 폴더 이름과 다른 경우, `destination` 옵션을 사용하여 대상 폴더 이름을 지정할 수 있습니다. 대상 폴더 이름을 지정하지 않으면, 원본 폴더의 이름이 대상 폴더를 만드는 데 사용됩니다. 마지막 파일 경로 구분자(`/` 또는 `\`) 뒤에 오는 모든 텍스트는 폴더 이름으로 취급됩니다. 소스 폴더와 같은 폴더 이름을 사용하려면, `destination` 옵션 입력 시 파일 경로 구분자(`/` 또는 `\`)로 끝나야 합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 폴더에 폴더를 생성할 수 있는 권한이 없습니다.
+ 소스 폴더가 런타임에 존재하지 않습니다.
+ 지정된 폴더 이름을 가진 폴더가 이미 있으며 `overwrite` 옵션이 `false`(으)로 설정되어 있습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| source | 소스 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| destination | 대상 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| overwrite | false로 설정하면 지정된 위치에 지정된 이름을 가진 폴더가 이미 있는 경우 대상 폴더가 바뀌지 않습니다. | 부울 | 아니요 | true | 해당 사항 없음 | 예 |
**입력 예제: 폴더 복사(Linux)**
```
- name: CopyingAFolderLinux
action: CopyFolder
inputs:
- source: /Sample/MyFolder/SampleFolder
destination: /MyFolder/destinationFolder
```
**입력 예제: 폴더 복사(Windows)**
```
- name: CopyingAFolderWindows
action: CopyFolder
inputs:
- source: C:\Sample\MyFolder\SampleFolder
destination: C:\MyFolder\destinationFolder
```
**입력 예제: 소스 폴더 이름을 사용하여 폴더 복사(Linux)**
```
- name: CopyingFolderSourceFolderNameLinux
action: CopyFolder
inputs:
- source: /Sample/MyFolder/SourceFolder
destination: /MyFolder/
```
**입력 예제: 소스 폴더 이름을 사용하여 폴더 복사(Windows)**
```
- name: CopyingFolderSourceFolderNameWindows
action: CopyFolder
inputs:
- source: C:\Sample\MyFolder\SampleFolder
destination: C:\MyFolder\
```
**입력 예제: 와일드카드 문자를 사용하여 폴더 복사(Linux)**
```
- name: CopyingFoldersWithWildCardLinux
action: CopyFolder
inputs:
- source: /Sample/MyFolder/Sample*
destination: /MyFolder/
```
**입력 예제: 와일드카드 문자를 사용하여 폴더 복사(Windows)**
```
- name: CopyingFoldersWithWildCardWindows
action: CopyFolder
inputs:
- source: C:\Sample\MyFolder\Sample*
destination: C:\MyFolder\
```
**입력 예제: 덮어쓰지 않고 폴더 복사(Linux)**
```
- name: CopyingFoldersWithoutOverwriteLinux
action: CopyFolder
inputs:
- source: /Sample/MyFolder/SourceFolder
destination: /MyFolder/destinationFolder
overwrite: false
```
**입력 예제: 덮어쓰지 않고 폴더 복사(Windows)**
```
- name: CopyingFoldersWithoutOverwrite
action: CopyFolder
inputs:
- source: C:\Sample\MyFolder\SourceFolder
destination: C:\MyFolder\destinationFolder
overwrite: false
```
**출력**
없음.
### CreateFile(Linux, Windows, macOS)
**CreateFile** 작업 모듈은 지정된 위치에 파일을 만듭니다. 기본적으로 필요한 경우, 모듈은 상위 폴더를 반복적으로 생성하기도 합니다.
파일이 지정된 폴더에 이미 있는 경우, 작업 모듈은 기본적으로 기존 파일을 잘라내거나 덮어씁니다. 덮어쓰기 옵션을 `false`(으)로 설정하여 이 기본 동작을 재정의할 수 있습니다. 덮어쓰기 옵션이 `false`(으)로 설정되어 있고 지정된 위치에 지정된 이름을 가진 파일이 이미 있는 경우, 작업 모듈은 오류를 반환합니다.
파일 인코딩 값이 기본 인코딩(`utf-8`) 값과 다른 경우, `encoding` 옵션을 사용하여 파일 인코딩 값을 지정할 수 있습니다. 기본적으로 `utf-16` 및 `utf-32`(은)는 리틀 엔디안 인코딩을 사용하는 것으로 간주됩니다.
`owner`, `group` 및 `permissions`(은)는 선택적 입력 사항입니다. `permissions`의 입력은 문자열 값이어야 합니다. 제공하지 않을 경우 파일은 기본값으로 생성됩니다. Windows 플랫폼에서는 이러한 옵션이 지원되지 않습니다. 이 작업 모듈은 Windows 플랫폼에서 `owner`, `group` 및 `permissions` 옵션을 사용하는 경우 검증하고 오류를 반환합니다.
이 작업 모듈은 운영 체제의 `umask` 기본값으로 정의된 권한을 가진 파일을 만들 수 있습니다. 기본값을 재정의하려면 `umask` 값을 설정해야 합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 상위 폴더에 파일이나 폴더를 만들 권한이 없습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 파일 경로. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| content | 파일의 텍스트 콘텐츠입니다. | 문자열 | No | 해당 사항 없음 | 해당 사항 없음 | 예 |
| encoding | 인코딩 표준입니다. | 문자열 | No | utf8 | utf8, utf-8, utf16, utf-16, utf16-LE, utf-16-LE, utf16-BE, utf-16-BE, utf32, utf-32, utf32-LE, utf-32-LE, utf32-BE 및 utf-32-BE. 인코딩 옵션 값은 대/소문자를 구분하지 않습니다. | 예 |
| owner | 사용자 이름 또는 ID입니다. | 문자열 | No | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| group | 그룹 이름 또는 ID입니다. | 문자열 | No | 현재 사용자입니다. | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| permissions | 파일 권한입니다. | 문자열 | No | 0666 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| overwrite | 지정된 파일의 이름이 이미 있는 경우, 이 값을 false(으)로 설정하면 기본적으로 파일이 잘리거나 덮어쓰기 되지 않도록 할 수 있습니다. | 부울 | 아니요 | true | 해당 사항 없음 | 예 |
**입력 예제: 덮어쓰지 않고 파일 생성(Linux)**
```
- name: CreatingFileWithoutOverwriteLinux
action: CreateFile
inputs:
- path: /home/UserName/Sample.txt
content: The text content of the sample file.
overwrite: false
```
**입력 예제: 덮어쓰지 않고 파일 생성(Windows)**
```
- name: CreatingFileWithoutOverwriteWindows
action: CreateFile
inputs:
- path: C:\Temp\Sample.txt
content: The text content of the sample file.
overwrite: false
```
**입력 예제: 파일 속성이 있는 파일 생성**
```
- name: CreatingFileWithFileProperties
action: CreateFile
inputs:
- path: SampleFolder/Sample.txt
content: The text content of the sample file.
encoding: UTF-16
owner: Ubuntu
group: UbuntuGroup
permissions: 0777
- path: SampleFolder/SampleFile.txt
permissions: 755
- path: SampleFolder/TextFile.txt
encoding: UTF-16
owner: root
group: rootUserGroup
```
**입력 예제: 파일 속성이 없는 파일 생성**
```
- name: CreatingFileWithoutFileProperties
action: CreateFile
inputs:
- path: ./Sample.txt
- path: Sample1.txt
```
**입력 예제: Linux 정리 스크립트에서 섹션을 건너뛰기 위한 빈 파일 생성**
```
- name: CreateSkipCleanupfile
action: CreateFile
inputs:
- path:
```
자세한 내용은 [Linux 정리 스크립트를 오버라이드합니다.](security-best-practices.md#override-linux-cleanup-script) 섹션을 참조하세요.
**출력**
없음.
### CreateFolder(Linux, Windows, macOS)
**CreateFolder** 작업 모듈은 지정된 위치에 폴더를 생성합니다. 기본적으로 필요한 경우, 모듈은 상위 폴더를 반복적으로 생성하기도 합니다.
폴더가 지정된 폴더에 이미 있는 경우, 작업 모듈은 기본적으로 기존 폴더를 잘라내거나 덮어씁니다. 덮어쓰기 옵션을 `false`(으)로 설정하여 이 기본 동작을 재정의할 수 있습니다. 덮어쓰기 옵션이 `false`(으)로 설정되어 있고 지정된 위치에 지정된 이름을 가진 폴더가 이미 있는 경우, 작업 모듈은 오류를 반환합니다.
`owner`, `group` 및 `permissions`(은)는 선택적 입력 사항입니다. `permissions`의 입력은 문자열 값이어야 합니다. Windows 플랫폼에서는 이러한 옵션이 지원되지 않습니다. 이 작업 모듈은 Windows 플랫폼에서 `owner`, `group` 및 `permissions` 옵션을 사용하는 경우 검증하고 오류를 반환합니다.
이 작업 모듈은 운영 체제의 `umask` 기본값으로 정의된 권한을 가진 폴더를 만들 수 있습니다. 기본값을 재정의하려면 `umask` 값을 설정해야 합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 위치에 폴더를 생성할 수 있는 권한이 없습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| owner | 사용자 이름 또는 ID입니다. | 문자열 | No | 현재 사용자입니다. | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| group | 그룹 이름 또는 ID입니다. | 문자열 | No | 현재 사용자의 그룹입니다. | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| permissions | 폴더 권한입니다. | 문자열 | No | 0777 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| overwrite | 지정된 파일의 이름이 이미 있는 경우, 이 값을 false(으)로 설정하면 기본적으로 파일이 잘리거나 덮어쓰기 되지 않도록 할 수 있습니다. | 부울 | 아니요 | true | 해당 사항 없음 | 예 |
**입력 예제: 폴더 생성(Linux)**
```
- name: CreatingFolderLinux
action: CreateFolder
inputs:
- path: /Sample/MyFolder/
```
**입력 예제: 폴더 생성(Windows)**
```
- name: CreatingFolderWindows
action: CreateFolder
inputs:
- path: C:\MyFolder
```
**입력 예제: 폴더 속성을 지정하는 폴더 생성**
```
- name: CreatingFolderWithFolderProperties
action: CreateFolder
inputs:
- path: /Sample/MyFolder/Sample/
owner: SampleOwnerName
group: SampleGroupName
permissions: 0777
- path: /Sample/MyFolder/SampleFoler/
permissions: 777
```
**입력 예제: 기존 폴더를 덮어쓰는 폴더가 있는 경우 해당 폴더를 생성합니다.**
```
- name: CreatingFolderWithOverwrite
action: CreateFolder
inputs:
- path: /Sample/MyFolder/Sample/
overwrite: true
```
**출력**
없음.
### CreateSymlink(Linux, Windows, macOS)
**CreateSymlink** 작업 모듈은 심볼 링크 또는 다른 파일에 대한 참조가 포함된 파일을 생성합니다. 이 모듈은 Windows 플랫폼에서 지원되지 않습니다.
`path` 및 `target` 옵션의 입력은 절대 경로이거나 상대 경로일 수 있습니다. `path` 옵션의 입력이 상대 경로인 경우, 링크를 만들 때 절대 경로로 대체됩니다.
기본적으로 지정된 이름의 링크가 지정된 폴더에 이미 있는 경우, 작업 모듈은 오류를 반환합니다. `force` 옵션을 `true`(으)로 설정하여 이 기본 동작을 재정의할 수 있습니다. `force` 옵션을 `true`(으)로 설정하면 모듈이 기존 링크를 덮어씁니다.
상위 폴더가 없는 경우, 작업 모듈은 기본적으로 폴더를 반복적으로 만듭니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 대상 파일이 런타임에 존재하지 않습니다.
+ 지정된 이름을 가진 비 심볼 링크 파일이 이미 있습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 파일 경로. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| target | 심볼 링크가 가리키는 대상 파일 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| force | 같은 이름의 링크가 이미 있는 경우 링크를 강제로 생성합니다. | 부울 | 아니요 | false | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
**입력 예제: 링크 생성을 강제하는 심볼 링크 생성**
```
- name: CreatingSymbolicLinkWithForce
action: CreateSymlink
inputs:
- path: /Folder2/Symboliclink.txt
target: /Folder/Sample.txt
force: true
```
**입력 예제: 링크 생성을 강제하지 않는 심볼 링크 생성**
```
- name: CreatingSymbolicLinkWithOutForce
action: CreateSymlink
inputs:
- path: Symboliclink.txt
target: /Folder/Sample.txt
```
**출력**
없음.
### DeleteFile(Linux, Windows, macOS)
**DeleteFile** 작업 모듈은 지정된 위치에 있는 파일을 하나 또는 여러 개 삭제합니다.
`path`의 입력은 유효한 파일 경로이거나 파일 이름에 와일드카드 문자(`*`)가 포함된 파일 경로여야 합니다. 파일 이름에 와일드카드 문자를 지정하면 동일한 폴더 내에서 와일드카드와 일치하는 모든 파일이 삭제됩니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 삭제 작업을 수행할 수 있는 권한이 없습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 파일 경로. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
**입력 예제: 단일 파일 삭제(Linux)**
```
- name: DeletingSingleFileLinux
action: DeleteFile
inputs:
- path: /SampleFolder/MyFolder/Sample.txt
```
**입력 예제: 단일 파일 삭제(Windows)**
```
- name: DeletingSingleFileWindows
action: DeleteFile
inputs:
- path: C:\SampleFolder\MyFolder\Sample.txt
```
**입력 예제: ‘log’로 끝나는 파일 삭제(Linux)**
```
- name: DeletingFileEndingWithLogLinux
action: DeleteFile
inputs:
- path: /SampleFolder/MyFolder/*log
```
**입력 예제: ‘log’로 끝나는 파일 삭제(Windows)**
```
- name: DeletingFileEndingWithLogWindows
action: DeleteFile
inputs:
- path: C:\SampleFolder\MyFolder\*log
```
**입력 예제: 지정된 폴더의 모든 파일 삭제(Linux)**
```
- name: DeletingAllFilesInAFolderLinux
action: DeleteFile
inputs:
- path: /SampleFolder/MyFolder/*
```
**입력 예제: 지정된 폴더의 모든 파일 삭제(Windows)**
```
- name: DeletingAllFilesInAFolderWindows
action: DeleteFile
inputs:
- path: C:\SampleFolder\MyFolder\*
```
**출력**
없음.
### DeleteFolder(Linux, Windows, macOS)
**DeleteFolder** 작업 모듈은 폴더를 삭제합니다.
폴더가 비어 있지 않은 경우, 폴더와 해당 내용을 제거하려면 `force` 옵션을 `true`로 설정해야 합니다. `force` 옵션을 `true`(으)로 설정하지 않은 상태에서 삭제하려는 폴더가 비어 있지 않으면, 작업 모듈에서 오류를 반환합니다. `force` 옵션의 기본값은 `false`입니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 삭제 작업을 수행할 수 있는 권한이 없습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| force | 폴더가 비어 있는지 여부에 관계없이 폴더를 제거합니다. | 부울 | 아니요 | false | 해당 사항 없음 | 예 |
**입력 예제: `force` 옵션을 사용하여 비어 있지 않은 폴더 삭제(Linux)**
```
- name: DeletingFolderWithForceOptionLinux
action: DeleteFolder
inputs:
- path: /Sample/MyFolder/Sample/
force: true
```
**입력 예제: `force` 옵션을 사용하여 비어 있지 않은 폴더 삭제(Windows)**
```
- name: DeletingFolderWithForceOptionWindows
action: DeleteFolder
inputs:
- path: C:\Sample\MyFolder\Sample\
force: true
```
**입력 예제: 폴더 삭제(Linux)**
```
- name: DeletingFolderWithOutForceLinux
action: DeleteFolder
inputs:
- path: /Sample/MyFolder/Sample/
```
**입력 예제: 폴더 삭제(Windows)**
```
- name: DeletingFolderWithOutForce
action: DeleteFolder
inputs:
- path: C:\Sample\MyFolder\Sample\
```
**출력**
없음.
### ListFiles(Linux, Windows, macOS)
**ListFiles** 작업 모듈은 지정된 폴더의 파일을 나열합니다. 재귀 옵션을 `true`(으)로 설정하면, 하위 폴더의 파일이 나열됩니다. 이 모듈은 기본적으로 하위 폴더의 파일을 나열하지 않습니다.
지정된 패턴과 일치하는 이름을 가진 모든 파일을 나열하려면 `fileNamePattern` 옵션을 사용하여 패턴을 제공하십시오. `fileNamePattern` 옵션에는 와일드카드(`*`) 값을 적용할 수 있습니다. `fileNamePattern`(이)가 제공되면 지정된 파일 이름 형식과 일치하는 모든 파일이 반환됩니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 폴더가 런타임에 존재하지 않습니다.
+ 지정된 상위 폴더에 파일이나 폴더를 만들 권한이 없습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| fileNamePattern | 패턴과 일치하는 이름을 가진 모든 파일을 나열하기 위해 일치시킬 패턴입니다. | 문자열 | No | 해당 사항 없음 | 해당 사항 없음 | 예 |
| recursive | 폴더의 파일을 재귀적으로 나열합니다. | 부울 | 아니요 | false | 해당 사항 없음 | 예 |
**입력 예제: 지정된 폴더의 파일 나열(Linux)**
```
- name: ListingFilesInSampleFolderLinux
action: ListFiles
inputs:
- path: /Sample/MyFolder/Sample
```
**입력 예제: 지정된 폴더의 파일 나열(Windows)**
```
- name: ListingFilesInSampleFolderWindows
action: ListFiles
inputs:
- path: C:\Sample\MyFolder\Sample
```
**입력 예제: ‘log’로 끝나는 파일 나열(Linux)**
```
- name: ListingFilesWithEndingWithLogLinux
action: ListFiles
inputs:
- path: /Sample/MyFolder/
fileNamePattern: *log
```
**입력 예제: ‘log’로 끝나는 파일 나열(Windows)**
```
- name: ListingFilesWithEndingWithLogWindows
action: ListFiles
inputs:
- path: C:\Sample\MyFolder\
fileNamePattern: *log
```
**입력 예제: 파일을 재귀적으로 나열**
```
- name: ListingFilesRecursively
action: ListFiles
inputs:
- path: /Sample/MyFolder/
recursive: true
```
**출력**
| 키 이름 | 설명 | 형식 |
| --- | --- | --- |
| files | 파일 목록입니다. | 문자열 |
**출력 예제**
```
{
"files": "/sample1.txt,/sample2.txt,/sample3.txt"
}
```
### MoveFile(Linux, Windows, macOS)
**MoveFile** 작업 모듈은 파일을 지정된 소스에서 지정된 대상으로 이동합니다.
파일이 지정된 폴더에 이미 있는 경우, 작업 모듈은 기본적으로 기존 파일을 덮어씁니다. 덮어쓰기 옵션을 `false`(으)로 설정하여 이 기본 동작을 재정의할 수 있습니다. 덮어쓰기 옵션이 `false`(으)로 설정되어 있고 지정된 위치에 지정된 이름을 가진 파일이 이미 있는 경우, 작업 모듈은 오류를 반환합니다. 이 옵션은 기본적으로 덮어쓰는 Linux의 `mv` 명령과 동일하게 작동합니다.
소스 파일 이름에는 와일드카드(`*`)가 포함될 수 있습니다. 와일드카드 문자는 마지막 파일 경로 구분자(`/` 또는 `\`) 뒤에만 사용할 수 있습니다. 와일드카드 문자가 소스 파일 이름에 포함된 경우, 와일드카드와 일치하는 모든 파일이 대상 폴더에 복사됩니다. 와일드카드 문자를 사용하여 둘 이상의 파일을 이동하려는 경우, `destination` 옵션 입력 시 대상 입력이 폴더임을 나타내는 파일 경로 구분자(`/` 또는 `\`)로 끝나야 합니다.
대상 파일 이름이 원본 파일 이름과 다른 경우, `destination` 옵션을 사용하여 대상 파일 이름을 지정할 수 있습니다. 대상 파일 이름을 지정하지 않으면, 원본 파일의 이름이 대상 파일을 만드는 데 사용됩니다. 마지막 파일 경로 구분자(`/` 또는 `\`) 뒤에 오는 모든 텍스트는 파일 이름으로 취급됩니다. 소스 파일과 같은 파일 이름을 사용하려면, `destination` 옵션 입력 시 파일 경로 구분자(`/` 또는 `\`)로 끝나야 합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 폴더에 파일을 생성할 수 있는 권한이 없습니다.
+ 소스 파일이 런타임에 존재하지 않습니다.
+ 지정된 파일 이름을 가진 폴더가 이미 있으며 `overwrite` 옵션이 `false`(으)로 설정되어 있습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| source | 소스 파일 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| destination | 대상 파일 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| overwrite | false로 설정하면 지정된 위치에 지정된 이름을 가진 파일이 이미 있는 경우 대상 파일이 교체되지 않습니다. | 부울 | 아니요 | true | 해당 사항 없음 | 예 |
**입력 예제: 파일 이동(Linux)**
```
- name: MovingAFileLinux
action: MoveFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/destinationFile.txt
```
**입력 예제: 파일 이동(Windows)**
```
- name: MovingAFileWindows
action: MoveFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder\destinationFile.txt
```
**입력 예제: 소스 파일 이름을 사용하여 파일 이동(Linux)**
```
- name: MovingFileWithSourceFileNameLinux
action: MoveFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/
```
**입력 예제: 소스 파일 이름을 사용하여 파일 이동(Windows)**
```
- name: MovingFileWithSourceFileNameWindows
action: MoveFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder
```
**입력 예제: 와일드카드 문자를 사용하여 파일 이동(Linux)**
```
- name: MovingFilesWithWildCardLinux
action: MoveFile
inputs:
- source: /Sample/MyFolder/Sample*
destination: /MyFolder/
```
**입력 예제: 와일드카드 문자를 사용하여 파일 이동(Windows)**
```
- name: MovingFilesWithWildCardWindows
action: MoveFile
inputs:
- source: C:\Sample\MyFolder\Sample*
destination: C:\MyFolder
```
**입력 예제: 덮어쓰지 않고 파일 이동(Linux)**
```
- name: MovingFilesWithoutOverwriteLinux
action: MoveFile
inputs:
- source: /Sample/MyFolder/Sample.txt
destination: /MyFolder/destinationFile.txt
overwrite: false
```
**입력 예제: 덮어쓰지 않고 파일 이동(Windows)**
```
- name: MovingFilesWithoutOverwrite
action: MoveFile
inputs:
- source: C:\Sample\MyFolder\Sample.txt
destination: C:\MyFolder\destinationFile.txt
overwrite: false
```
**출력**
없음.
### MoveFolder(Linux, Windows, macOS)
**MoveFolder** 작업 모듈은 폴더를 지정된 소스에서 지정된 대상으로 이동합니다. `source` 옵션에 대한 입력은 이동할 폴더이고 `destination` 옵션에 대한 입력은 소스 폴더의 내용이 이동되는 폴더입니다.
런타임 시 대상 상위 폴더 또는 `destination` 옵션에 대한 입력이 없는 경우, 모듈의 기본 동작은 지정된 대상에 폴더를 반복적으로 생성하는 것입니다.
소스 폴더와 동일한 폴더가 대상 폴더에 이미 있는 경우, 작업 모듈은 기본적으로 기존 폴더를 덮어씁니다. 덮어쓰기 옵션을 `false`(으)로 설정하여 이 기본 동작을 재정의할 수 있습니다. 덮어쓰기 옵션이 `false`(으)로 설정되어 있고 지정된 위치에 지정된 이름을 가진 폴더가 이미 있는 경우, 작업 모듈은 오류를 반환합니다.
소스 폴더 이름에는 와일드카드(`*`)가 포함될 수 있습니다. 와일드카드 문자는 마지막 파일 경로 구분자(`/` 또는 `\`) 뒤에만 사용할 수 있습니다. 와일드카드 문자가 소스 폴더 이름에 포함된 경우, 와일드카드와 일치하는 모든 폴더가 대상 폴더에 복사됩니다. 와일드카드 문자를 사용하여 폴더를 두 개 이상 이동하려는 경우, `destination` 옵션 입력 시 대상 입력이 폴더임을 나타내는 파일 경로 구분자(`/` 또는 `\`)로 끝나야 합니다.
대상 폴더 이름이 소스 폴더 이름과 다른 경우, `destination` 옵션을 사용하여 대상 폴더 이름을 지정할 수 있습니다. 대상 폴더 이름을 지정하지 않으면, 원본 폴더의 이름이 대상 폴더를 만드는 데 사용됩니다. 마지막 파일 경로 구분자(`/` 또는 `\`) 뒤에 오는 모든 텍스트는 폴더 이름으로 취급됩니다. 소스 폴더와 같은 폴더 이름을 사용하려면, `destination` 옵션 입력 시 파일 경로 구분자(`/` 또는 `\`)로 끝나야 합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 대상 폴더에 폴더를 생성할 수 있는 권한이 없습니다.
+ 소스 폴더가 런타임에 존재하지 않습니다.
+ 지정된 이름을 가진 폴더가 이미 있으며 `overwrite` 옵션이 `false`로 설정되어 있습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| source | 소스 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| destination | 대상 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| overwrite | false로 설정하면 지정된 위치에 지정된 이름을 가진 폴더가 이미 있는 경우 대상 폴더가 바뀌지 않습니다. | 부울 | 아니요 | true | 해당 사항 없음 | 예 |
**입력 예제: 폴더 이동(Linux)**
```
- name: MovingAFolderLinux
action: MoveFolder
inputs:
- source: /Sample/MyFolder/SourceFolder
destination: /MyFolder/destinationFolder
```
**입력 예제: 폴더 이동(Windows)**
```
- name: MovingAFolderWindows
action: MoveFolder
inputs:
- source: C:\Sample\MyFolder\SourceFolder
destination: C:\MyFolder\destinationFolder
```
**입력 예제: 소스 폴더 이름을 사용하여 폴더 이동(Linux)**
```
- name: MovingFolderWithSourceFolderNameLinux
action: MoveFolder
inputs:
- source: /Sample/MyFolder/SampleFolder
destination: /MyFolder/
```
**입력 예제: 소스 폴더 이름을 사용하여 폴더 이동(Windows)**
```
- name: MovingFolderWithSourceFolderNameWindows
action: MoveFolder
inputs:
- source: C:\Sample\MyFolder\SampleFolder
destination: C:\MyFolder\
```
**입력 예제: 와일드카드 문자를 사용하여 폴더 이동(Linux)**
```
- name: MovingFoldersWithWildCardLinux
action: MoveFolder
inputs:
- source: /Sample/MyFolder/Sample*
destination: /MyFolder/
```
**입력 예제: 와일드카드 문자를 사용하여 폴더 이동(Windows)**
```
- name: MovingFoldersWithWildCardWindows
action: MoveFolder
inputs:
- source: C:\Sample\MyFolder\Sample*
destination: C:\MyFolder\
```
**입력 예제: 덮어쓰지 않고 폴더 이동(Linux)**
```
- name: MovingFoldersWithoutOverwriteLinux
action: MoveFolder
inputs:
- source: /Sample/MyFolder/SampleFolder
destination: /MyFolder/destinationFolder
overwrite: false
```
**입력 예제: 덮어쓰지 않고 폴더 이동(Windows)**
```
- name: MovingFoldersWithoutOverwriteWindows
action: MoveFolder
inputs:
- source: C:\Sample\MyFolder\SampleFolder
destination: C:\MyFolder\destinationFolder
overwrite: false
```
**출력**
없음.
### ReadFile(Linux, Windows, macOS)
**ReadFile** 작업 모듈은 문자열 형식의 텍스트 파일 내용을 읽습니다. 이 모듈은 체인을 통해 후속 단계에서 사용할 파일 내용을 읽거나 `console.log` 파일로 데이터를 읽는 데 사용할 수 있습니다. 지정된 경로가 심볼 링크인 경우, 이 모듈은 대상 파일의 내용을 반환합니다. 이 모듈은 텍스트 파일만 지원합니다.
파일 인코딩 값이 기본 인코딩(`utf-8`) 값과 다른 경우, `encoding` 옵션을 사용하여 파일 인코딩 값을 지정할 수 있습니다. 기본적으로 `utf-16` 및 `utf-32`(은)는 리틀 엔디안 인코딩을 사용하는 것으로 간주됩니다.
기본적으로 이 모듈은 파일 내용을 `console.log` 파일에 인쇄할 수 없습니다. `printFileContent` 속성을 `true`로 설정하여 이 설정을 재정의할 수 있습니다.
이 모듈은 파일 내용만 반환할 수 있습니다. Excel 또는 JSON 파일과 같은 파일은 구문 분석할 수 없습니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 파일이 런타임에 존재하지 않습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 파일 경로. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| encoding | 인코딩 표준입니다. | 문자열 | No | utf8 | utf8, utf-8, utf16, utf-16, utf16-LE, utf-16-LE, utf16-BE, utf-16-BE, utf32, utf-32, utf32-LE, utf-32-LE, utf32-BE 및 utf-32-BE. 인코딩 옵션 값은 대/소문자를 구분하지 않습니다. | 예 |
| printFileContent | 파일 내용을 console.log 파일에 인쇄합니다. | 부울 | 아니요 | false | 해당 사항 없음 | 예. |
**입력 예제: 파일 읽기(Linux)**
```
- name: ReadingFileLinux
action: ReadFile
inputs:
- path: /home/UserName/SampleFile.txt
```
**입력 예제: 파일 읽기(Windows)**
```
- name: ReadingFileWindows
action: ReadFile
inputs:
- path: C:\Windows\WindowsUpdate.log
```
**입력 예제: 파일 읽기 및 인코딩 표준 지정**
```
- name: ReadingFileWithFileEncoding
action: ReadFile
inputs:
- path: /FolderName/SampleFile.txt
encoding: UTF-32
```
**입력 예제: 파일 읽기 및 `console.log` 파일에 인쇄**
```
- name: ReadingFileToConsole
action: ReadFile
inputs:
- path: /home/UserName/SampleFile.txt
printFileContent: true
```
**출력**
| 필드 | 설명 | 형식 |
| --- | --- | --- |
| content | 파일 내용입니다. | 문자열 |
**출력 예제**
```
{
"content" : "The file content"
}
```
### SetFileEncoding(Linux, Windows, macOS)
**SetFileEncoding** 작업 모듈은 기존 파일의 인코딩 속성을 수정합니다. 이 모듈은 파일 인코딩을 `utf-8`에서 지정된 인코딩 표준으로 변환할 수 있습니다. 기본적으로 `utf-16` 및 `utf-32`(은)는 리틀 엔디안 인코딩으로 간주됩니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 수정을 수행할 수 있는 권한이 없습니다.
+ 파일이 런타임에 존재하지 않습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 파일 경로. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | 예 |
| encoding | 인코딩 표준입니다. | 문자열 | No | utf8 | utf8, utf-8, utf16, utf-16, utf16-LE, utf-16-LE, utf16-BE, utf-16-BE, utf32, utf-32, utf32-LE, utf-32-LE, utf32-BE 및 utf-32-BE. 인코딩 옵션 값은 대/소문자를 구분하지 않습니다. | 예 |
**입력 예제: 파일 인코딩 속성 설정**
```
- name: SettingFileEncodingProperty
action: SetFileEncoding
inputs:
- path: /home/UserName/SampleFile.txt
encoding: UTF-16
```
**출력**
없음.
### SetFileOwner(Linux, Windows, macOS)
**setFileOwner** 작업 모듈은 기존 파일의 `owner` 및 `group` 소유자 속성을 수정합니다. 지정된 파일이 심볼 링크인 경우, 모듈은 소스 파일의 `owner` 속성을 수정합니다. 이 모듈은 Windows 플랫폼에서 지원되지 않습니다.
이 모듈은 사용자 및 그룹 이름을 입력으로 수용합니다. 그룹 이름을 제공하지 않으면, 모듈은 사용자가 속한 그룹에 파일의 그룹 소유자를 할당합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 수정을 수행할 수 있는 권한이 없습니다.
+ 지정된 사용자 또는 그룹 이름이 런타임에 존재하지 않습니다.
+ 파일이 런타임에 존재하지 않습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 파일 경로. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| owner | 사용자 이름. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| group | 사용자 그룹의 이름입니다. | 문자열 | No | 사용자가 속한 그룹의 이름입니다. | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
**입력 예제: 사용자 그룹 이름을 지정하지 않고 파일 소유자 속성 설정**
```
- name: SettingFileOwnerPropertyNoGroup
action: SetFileOwner
inputs:
- path: /home/UserName/SampleText.txt
owner: LinuxUser
```
**입력 예제: 소유자 및 사용자 그룹을 지정하여 파일 소유자 속성 설정**
```
- name: SettingFileOwnerProperty
action: SetFileOwner
inputs:
- path: /home/UserName/SampleText.txt
owner: LinuxUser
group: LinuxUserGroup
```
**출력**
없음.
### SetFolderOwner(Linux, Windows, macOS)
**SetFolderOwner** 작업 모듈은 기존 폴더의 `owner` 및 `group` 소유자 및 속성을 재귀적으로 수정합니다. 기본적으로 모듈은 폴더의 모든 내용에 대한 소유권을 수정할 수 있습니다. `recursive` 옵션을 `false`(으)로 설정하여 이 동작을 재정의할 수 있습니다. 이 모듈은 Windows 플랫폼에서 지원되지 않습니다.
이 모듈은 사용자 및 그룹 이름을 입력으로 수용합니다. 그룹 이름을 제공하지 않으면, 모듈은 사용자가 속한 그룹에 파일의 그룹 소유자를 할당합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 수정을 수행할 수 있는 권한이 없습니다.
+ 지정된 사용자 또는 그룹 이름이 런타임에 존재하지 않습니다.
+ 폴더가 런타임에 존재하지 않습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| owner | 사용자 이름. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| group | 사용자 그룹의 이름입니다. | 문자열 | No | 사용자가 속한 그룹의 이름입니다. | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| recursive | false(으)로 설정하면 폴더의 모든 내용에 대한 소유권을 수정하는 기본 동작을 재정의합니다. | 부울 | 아니요 | true | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
**입력 예제: 사용자 그룹 이름을 지정하지 않고 폴더 소유자 속성 설정**
```
- name: SettingFolderPropertyWithOutGroup
action: SetFolderOwner
inputs:
- path: /SampleFolder/
owner: LinuxUser
```
**입력 예제: 폴더 내 모든 콘텐츠의 소유권을 재정의하지 않고 폴더 소유자 속성 설정**
```
- name: SettingFolderPropertyWithOutRecursively
action: SetFolderOwner
inputs:
- path: /SampleFolder/
owner: LinuxUser
recursive: false
```
**입력 예제: 사용자 그룹 이름을 지정하여 파일 소유권 속성 설정**
```
- name: SettingFolderPropertyWithGroup
action: SetFolderOwner
inputs:
- path: /SampleFolder/
owner: LinuxUser
group: LinuxUserGroup
```
**출력**
없음.
### SetFilePermissions(Linux, Windows, macOS)
**SetFilePermissions** 작업 모듈은 기존 파일의 `permissions`(을)를 수정합니다. 이 모듈은 Windows 플랫폼에서 지원되지 않습니다.
`permissions`의 입력은 문자열 값이어야 합니다.
이 작업 모듈은 운영 체제의 기본 umask 값으로 정의된 권한을 가진 파일을 만들 수 있습니다. 기본값을 재정의하려면 `umask` 값을 설정해야 합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 수정을 수행할 수 있는 권한이 없습니다.
+ 파일이 런타임에 존재하지 않습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 파일 경로. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| permissions | 파일 권한입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
**입력 예제: 파일 권한 수정**
```
- name: ModifyingFilePermissions
action: SetFilePermissions
inputs:
- path: /home/UserName/SampleFile.txt
permissions: 766
```
**출력**
없음.
### SetFolderPermissions(Linux, Windows, macOS)
**SetFolderPermissions** 작업 모듈은 기존 폴더와 모든 하위 파일 및 하위 폴더의 `permissions`을 재귀적으로 수정합니다. 기본적으로 이 모듈은 지정된 폴더의 모든 내용에 대한 권한을 수정할 수 있습니다. `recursive` 옵션을 `false`(으)로 설정하여 이 동작을 재정의할 수 있습니다. 이 모듈은 Windows 플랫폼에서 지원되지 않습니다.
`permissions`의 입력은 문자열 값이어야 합니다.
이 작업 모듈은 운영 체제의 기본 umask 값에 따라 권한을 수정할 수 있습니다. 기본값을 재정의하려면 `umask` 값을 설정해야 합니다.
다음과 같은 상황이 발생하면 작업 모듈이 오류를 반환합니다.
+ 지정된 수정을 수행할 수 있는 권한이 없습니다.
+ 폴더가 런타임에 존재하지 않습니다.
+ 작업 모듈에서 작업을 수행하는 동안 오류가 발생했습니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 | 모든 플랫폼에서 지원됩니다. |
| --- | --- | --- | --- | --- | --- | --- |
| path | 폴더 경로입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| permissions | 폴더 권한입니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
| recursive | false로 설정된 경우 폴더의 모든 내용에 대한 권한을 수정하는 기본 동작을 재정의합니다. | 부울 | 아니요 | true | 해당 사항 없음 | Windows에서 지원되지 않습니다. |
**입력 예제: 폴더 권한 설정**
```
- name: SettingFolderPermissions
action: SetFolderPermissions
inputs:
- path: SampleFolder/
permissions: 0777
```
**입력 예제: 폴더의 모든 콘텐츠에 대한 권한을 수정하지 않고 폴더 권한 설정**
```
- name: SettingFolderPermissionsNoRecursive
action: SetFolderPermissions
inputs:
- path: /home/UserName/SampleFolder/
permissions: 777
recursive: false
```
**출력**
없음.
## 소프트웨어 설치 작업
다음 섹션에서는 소프트웨어를 설치하거나 제거하는 작업 모듈에 대해 설명합니다.
**IAM 요구 사항**
설치 다운로드 경로가 S3 URI인 경우, 인스턴스 프로파일에 연결하는 IAM 역할에 `S3Download` 작업 모듈을 실행할 권한이 있어야 합니다. 필요한 권한을 부여하려면 `S3:GetObject` IAM 정책을 인스턴스 프로파일과 연결된 IAM 역할에 연결하고 버킷 경로를 지정하십시오. 예: `arn:aws:s3:::BucketName/*`).
**복합 MSI 입력**
입력 문자열에 큰따옴표(`"`)가 포함된 경우, 다음 방법 중 하나를 사용하여 올바르게 해석되도록 해야 합니다.
+ 다음 예제와 같이 문자열 외부에 작은따옴표(')를 사용하여 문자열을 포함하고, 문자열 안에는 큰따옴표(")를 사용할 수 있습니다.
```
properties:
COMPANYNAME: '"Acme ""Widgets"" and ""Gizmos."""'
```
이 경우 문자열 안에 아포스트로피를 사용해야 하는 경우에는 이스케이프해야 합니다. 즉, 아포스트로피 앞에 작은따옴표(')를 하나 더 사용해야 합니다.
+ 문자열 바깥쪽에 큰따옴표(")를 사용하여 문자열을 포함할 수 있습니다. 또한 다음 예제와 같이 백슬래시 문자(`\`)를 사용하여 문자열 내의 큰따옴표를 이스케이프할 수 있습니다.
```
properties:
COMPANYNAME: "\"Acme \"\"Widgets\"\" and \"\"Gizmos.\"\"\""
```
두 방법 모두 `COMPANYNAME="Acme ""Widgets"" and ""Gizmos."""` 값을 **msiexec** 명령에 전달합니다.
**Topics**
+ [InstallMSI(Windows)](#action-modules-install-msi)
+ [UninstallMSI(Windows)](#action-modules-uninstall-msi)
### InstallMSI(Windows)
`InstallMSI` 작업 모듈은 MSI 파일을 사용하여 Windows 애플리케이션을 설치합니다. 로컬 경로, S3 객체 URI 또는 웹 URL을 사용하여 MSI 파일을 지정할 수 있습니다. 재부팅 옵션은 시스템의 재부팅 동작을 구성합니다.
AWSTOE 는 작업 모듈의 입력 파라미터를 기반으로 **msiexec** 명령을 생성합니다. `path`(MSI 파일 위치) 및 `logFile`(로그 파일 위치) 입력 파라미터의 값은 따옴표(")로 묶어야 합니다.
다음 MSI 종료 코드는 성공한 것으로 간주됩니다.
+ 0(성공)
+ 1614(ERROR\$1PRODUCT\$1UNINSTALLED)
+ 1641(재부팅이 시작됨)
+ 3010(재부팅 필요)
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 |
| --- | --- | --- | --- | --- | --- |
| path | 다음 중 하나를 사용하여 MSI 파일 위치를 지정합니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) chaining 표현식이 허용됩니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 |
| reboot | 작업 모듈이 성공적으로 실행된 후 나타나는 시스템 재부팅 동작을 구성합니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | 문자열 | No | Allow | Allow, Force, Skip |
| logOptions | MSI 설치 로깅에 사용할 옵션을 지정합니다. 지정된 플래그는 `/L` 명령줄 파라미터와 함께 MSI 설치 관리자에 전달되어 로깅을 활성화합니다. 플래그가 지정되지 않은 경우 기본값을 AWSTOE 사용합니다. MSI의 로그 옵션에 대한 자세한 내용은 Microsoft *Windows 설치 프로그램* 제품 설명서의 [명령줄 옵션](https://learn.microsoft.com/en-us/windows/win32/msi/command-line-options)을 참조하세요. | 문자열 | No | \$1VX | i,w,e,a,r,u,c,m,o,p,v,x,\$1,\$1,\$1 |
| logFile | 로그 파일 위치의 절대 경로 또는 상대 경로입니다. 로그 파일 경로가 없으면 생성됩니다. 로그 파일 경로가 제공되지 않은 경우는 MSI 설치 로그를 저장하지 AWSTOE 않습니다. | 문자열 | No | 해당 사항 없음 | 해당 사항 없음 |
| properties | MSI 로깅 속성 키/값 페어, 예: `TARGETDIR: "C:\target\location"` 참고: 다음 속성은 수정할 수 없습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | Map[String]String | 아니요 | 해당 사항 없음 | 해당 사항 없음 |
| ignoreAuthenticodeSignatureErrors | 경로에 지정된 설치 프로그램의 Authenticode 서명 검증 오류를 무시하도록 설정하는 플래그입니다. **Get-AuthenticodeSignature** 명령은 설치 프로그램을 검증하는 데 사용됩니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | 부울 | 아니요 | false | true, false |
| allowUnsignedInstaller | 경로에 지정된 서명되지 않은 설치 프로그램을 실행할 수 있도록 하는 플래그입니다. **Get-AuthenticodeSignature** 명령은 설치 프로그램을 검증하는 데 사용됩니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | 부울 | 아니요 | false | true, false |
**예제**
다음 예제는 설치 경로에 따른 구성 요소 문서의 입력 섹션 변형을 보여줍니다.
**입력 예제: 로컬 문서 경로 설치**
```
- name: local-path-install
steps:
- name: LocalPathInstaller
action: InstallMSI
inputs:
path: C:\sample.msi
logFile: C:\msilogs\local-path-install.log
logOptions: '*VX'
reboot: Allow
properties:
COMPANYNAME: '"Amazon Web Services"'
ignoreAuthenticodeSignatureErrors: true
allowUnsignedInstaller: true
```
**입력 예제: Amazon S3 경로 설치**
```
- name: s3-path-install
steps:
- name: S3PathInstaller
action: InstallMSI
inputs:
path: s3:///sample.msi
logFile: s3-path-install.log
reboot: Force
ignoreAuthenticodeSignatureErrors: false
allowUnsignedInstaller: true
```
**입력 예제: 웹 경로 설치**
```
- name: web-path-install
steps:
- name: WebPathInstaller
action: InstallMSI
inputs:
path: https:///sample.msi
logFile: web-path-install.log
reboot: Skip
ignoreAuthenticodeSignatureErrors: true
allowUnsignedInstaller: false
```
**출력**
다음은 `InstallMSI` 작업 모듈의 출력 예제입니다.
```
{
"logFile": "web-path-install.log",
"msiExitCode": 0,
"stdout": ""
}
```
### UninstallMSI(Windows)
`UninstallMSI` 작업 모듈을 사용하면 MSI 파일을 사용하여 Windows 애플리케이션을 제거할 수 있습니다. 로컬 파일 경로, S3 객체 URI 또는 웹 URL을 사용하여 MSI 파일 위치를 지정할 수 있습니다. 재부팅 옵션은 시스템의 재부팅 동작을 구성합니다.
AWSTOE 는 작업 모듈의 입력 파라미터를 기반으로 **msiexec** 명령을 생성합니다. MSI 파일 위치(`path`)와 로그 파일 위치(`logFile`)는 **msiexec** 명령을 생성하는 동안 명시적으로 큰따옴표(")로 묶습니다.
다음 MSI 종료 코드는 성공한 것으로 간주됩니다.
+ 0(성공)
+ 1605(ERROR\$1UNKNOWN\$1PRODUCT)
+ 1614(ERROR\$1PRODUCT\$1UNINSTALLED)
+ 1641(재부팅이 시작됨)
+ 3010(재부팅 필요)
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 | 허용되는 값 |
| --- | --- | --- | --- | --- | --- |
| path | 다음 중 하나를 사용하여 MSI 파일 위치를 지정합니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) chaining 표현식이 허용됩니다. | 문자열 | 예 | 해당 사항 없음 | 해당 사항 없음 |
| reboot | 작업 모듈이 성공적으로 실행된 후 나타나는 시스템 재부팅 동작을 구성합니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | 문자열 | No | Allow | Allow, Force, Skip |
| logOptions | MSI 설치 로깅에 사용할 옵션을 지정합니다. 지정된 플래그는 `/L` 명령줄 파라미터와 함께 MSI 설치 관리자에 전달되어 로깅을 활성화합니다. 플래그가 지정되지 않은 경우 기본값을 AWSTOE 사용합니다. MSI의 로그 옵션에 대한 자세한 내용은 Microsoft *Windows 설치 프로그램* 제품 설명서의 [명령줄 옵션](https://docs.microsoft.com/en-us/windows/win32/msi/command-line-options)을 참조하세요. | 문자열 | No | \$1VX | i,w,e,a,r,u,c,m,o,p,v,x,\$1,\$1,\$1 |
| logFile | 로그 파일 위치의 절대 경로 또는 상대 경로입니다. 로그 파일 경로가 없으면 생성됩니다. 로그 파일 경로가 제공되지 않은 경우는 MSI 설치 로그를 저장하지 AWSTOE 않습니다. | 문자열 | No | 해당 사항 없음 | 해당 사항 없음 |
| properties | MSI 로깅 속성 키/값 페어, 예: `TARGETDIR: "C:\target\location"` 참고: 다음 속성은 수정할 수 없습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | Map[String]String | 아니요 | 해당 사항 없음 | 해당 사항 없음 |
| ignoreAuthenticodeSignatureErrors | 경로에 지정된 설치 프로그램의 Authenticode 서명 검증 오류를 무시하도록 설정하는 플래그입니다. **Get-AuthenticodeSignature** 명령은 설치 프로그램을 검증하는 데 사용됩니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | 부울 | 아니요 | false | true, false |
| allowUnsignedInstaller | 경로에 지정된 서명되지 않은 설치 프로그램을 실행할 수 있도록 하는 플래그입니다. **Get-AuthenticodeSignature** 명령은 설치 프로그램을 검증하는 데 사용됩니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) | 부울 | 아니요 | false | true, false |
**예제**
다음 예제는 설치 경로에 따른 구성 요소 문서의 입력 섹션 변형을 보여줍니다.
**입력 예제: 로컬 문서 경로 설치 제거**
```
- name: local-path-uninstall
steps:
- name: LocalPathUninstaller
action: UninstallMSI
inputs:
path: C:\sample.msi
logFile: C:\msilogs\local-path-uninstall.log
logOptions: '*VX'
reboot: Allow
properties:
COMPANYNAME: '"Amazon Web Services"'
ignoreAuthenticodeSignatureErrors: true
allowUnsignedInstaller: true
```
**입력 예제: Amazon S3 경로 설치 제거**
```
- name: s3-path-uninstall
steps:
- name: S3PathUninstaller
action: UninstallMSI
inputs:
path: s3:///sample.msi
logFile: s3-path-uninstall.log
reboot: Force
ignoreAuthenticodeSignatureErrors: false
allowUnsignedInstaller: true
```
**입력 예제: 웹 경로 설치 제거**
```
- name: web-path-uninstall
steps:
- name: WebPathUninstaller
action: UninstallMSI
inputs:
path: https:///sample.msi
logFile: web-path-uninstall.log
reboot: Skip
ignoreAuthenticodeSignatureErrors: true
allowUnsignedInstaller: false
```
**출력**
다음은 `UninstallMSI` 작업 모듈의 출력 예제입니다.
```
{
"logFile": "web-path-uninstall.log",
"msiExitCode": 0,
"stdout": ""
}
```
## 시스템 작업 모듈
다음 섹션에서는 시스템 작업을 수행하거나 시스템 설정을 업데이트하는 작업 모듈에 대해 설명합니다.
**Topics**
+ [Reboot(Linux, Windows)](#action-modules-reboot)
+ [SetRegistry(Windows)](#action-modules-setregistry)
+ [UpdateOS(Linux, Windows)](#action-modules-updateos)
### Reboot(Linux, Windows)
**재부팅** 작업 모듈은 인스턴스를 재부팅합니다. 재부팅 시작을 지연시킬 수 있는 구성 가능한 옵션이 포함되어 있습니다. 기본적으로 `delaySeconds`(은)는 `0`(으)로 설정되어 있으며, 이는 지연이 없음을 의미합니다. 재부팅 작업 모듈의 경우, 인스턴스 재부팅 시에는 적용되지 않기 때문에 단계 시간 초과가 지원되지 않습니다.
Systems Manager Agent가 애플리케이션을 호출하면, 종료 코드(Windows의 경우 `3010`, Linux의 경우 `194`)가 Systems Manager Agent에 전달됩니다. Systems Manager Agent는 [스크립트에서 관리형 인스턴스 재부팅](https://docs.aws.amazon.com/systems-manager/latest/userguide/send-commands-reboot.html)에 설명된 대로 시스템 재부팅을 처리합니다.
애플리케이션이 호스트에서 독립 실행형 프로세스로 호출되는 경우, 현재 실행 상태를 저장하고 재부팅 후 애플리케이션을 재실행하도록 재부팅 후 자동 실행 트리거를 구성한 다음 시스템을 재부팅합니다.
**재부팅 후 자동 실행 트리거:**
+ **Windows**. AWSTOE (은)는 `SystemStartup`에서 자동으로 실행되는 트리거가 포함된 Windows 작업 스케줄러 항목을 만듭니다.
+ **Linux**. AWSTOE (은)는 시스템 재부팅 후 자동으로 실행되는 작업을 crontab에 추가합니다.
```
@reboot /download/path/awstoe run --document s3://bucket/key/doc.yaml
```
이 트리거는 애플리케이션이 시작될 때 정리됩니다.
**재시도**
기본적으로 최대 재시도 횟수는 Systems Manager `CommandRetryLimit`으로 설정됩니다. 재부팅 횟수가 재시도 제한을 초과하면, 자동화가 실패합니다. Systems Manager 에이전트 구성 파일(`Mds.CommandRetryLimit`)을 편집하여 제한을 변경할 수 있습니다. Systems Manager 에이전트 오픈 소스의 [런타임 구성](https://github.com/aws/amazon-ssm-agent/blob/mainline/README.md#runtime-configuration)을 참조하세요.
**Reboot** 작업 모듈을 사용하려면, `exitcode` 재부팅이 포함된 단계(예: `3010`)의 경우 애플리케이션 바이너리를 `sudo user`(으)로 실행해야 합니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 | 기본값 |
| --- | --- | --- | --- | --- |
| delaySeconds | 재부팅을 시작하기 전에 특정 시간을 지연시킵니다. | Integer | 아니요 | `0` |
**입력 예제: 재부팅 단계**
```
- name: RebootStep
action: Reboot
onFailure: Abort
maxAttempts: 2
inputs:
delaySeconds: 60
```
**출력**
없음.
**Reboot** 모듈이 완료되면, Image Builder는 빌드의 다음 단계를 계속 진행합니다.
### SetRegistry(Windows)
**SetRegistry** 작업 모듈은 입력 목록을 허용하고 지정된 레지스트리 키의 값을 설정할 수 있도록 합니다. 레지스트리 키가 없으면, 정의된 경로에 새로 생성됩니다. 이 기능은 Windows에만 적용됩니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 |
| --- | --- | --- | --- |
| path | 레지스트리 키의 경로입니다. | 문자열 | 예 |
| name | 레지스트리 키의 이름입니다. | 문자열 | 예 |
| value | 레지스트리 키의 값입니다. | 문자열/숫자/배열 | 예 |
| type | 레지스트리 키의 값 유형입니다. | 문자열 | 예 |
**지원되는 경로 접두사**
+ `HKEY_CLASSES_ROOT / HKCR:`
+ `HKEY_USERS / HKU:`
+ `HKEY_LOCAL_MACHINE / HKLM:`
+ `HKEY_CURRENT_CONFIG / HKCC:`
+ `HKEY_CURRENT_USER / HKCU:`
**지원되는 유형**
+ `BINARY`
+ `DWORD`
+ `QWORD`
+ `SZ`
+ `EXPAND_SZ`
+ `MULTI_SZ`
**입력 예제: 레지스트리 키 값 설정**
```
- name: SetRegistryKeyValues
action: SetRegistry
maxAttempts: 3
inputs:
- path: HKLM:\SOFTWARE\MySoftWare
name: MyName
value: FirstVersionSoftware
type: SZ
- path: HKEY_CURRENT_USER\Software\Test
name: Version
value: 1.1
type: DWORD
```
**출력**
없음.
### UpdateOS(Linux, Windows)
**UpdateOS** 작업 모듈은 Windows 및 Linux 업데이트 설치에 대한 지원을 추가합니다. 기본적으로 사용 가능한 모든 업데이트가 설치됩니다. 또는 설치할 작업 모듈에 대한 하나 이상의 특정 업데이트 목록을 구성할 수 있습니다. 설치에서 제외할 업데이트를 지정할 수도 있습니다.
‘포함’ 목록과 ‘제외’ 목록을 모두 제공하는 경우 결과 업데이트 목록에는 ‘포함’ 목록에 나열되어 있지만 ‘제외’ 목록에 나열되지 않은 업데이트만 포함될 수 있습니다.
**참고**
**UpdateOS**는 Amazon Linux 2023(AL2023)을 지원하지 않습니다. 기본 AMI를 모든 릴리스와 함께 제공되는 새 버전으로 업데이트하는 것이 좋습니다. 다른 대안은 *Amazon Linux 2023 사용 설명서*의 [메이저 릴리스와 마이너 릴리스에서 받은 업데이트 제어](https://docs.aws.amazon.com/linux/al2023/ug/deterministic-upgrades.html#controlling-release-updates)를 참조하세요.
+ **Windows**. 업데이트는 대상 컴퓨터에 구성된 업데이트 소스에서 설치됩니다.
+ **Linux**. 애플리케이션은 Linux 플랫폼에서 지원되는 패키지 관리자를 확인하고 `yum` 또는 `apt-get` 패키지 관리자를 사용합니다. 둘 다 지원되지 않으면 오류가 반환됩니다. **UpdateOS** 작업 모듈을 실행할 `sudo` 권한이 있어야 합니다. `sudo` 권한이 없는 경우 `error.Input`(이)가 반환됩니다.
**Input**
| 키 이름 | 설명 | 형식 | 필수 |
| --- | --- | --- | --- |
| include | Windows의 경우, 다음을 지정할 수 있습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) Linux의 경우 설치용 업데이트 목록에 포함할 패키지를 하나 이상 지정할 수 있습니다. | 문자열 목록 | 아니요 |
| exclude | Windows의 경우, 다음을 지정할 수 있습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/imagebuilder/latest/userguide/toe-action-modules.html) Linux의 경우, 설치용 업데이트 목록에서 제외할 패키지를 하나 이상 지정할 수 있습니다. | 문자열 목록 | 아니요 |
**입력 예제: Linux 업데이트 설치에 대한 지원 추가**
```
- name: UpdateMyLinux
action: UpdateOS
onFailure: Abort
maxAttempts: 3
inputs:
exclude:
- ec2-hibinit-agent
```
**입력 예제: Windows 업데이트 설치에 대한 지원 추가**
```
- name: UpdateWindowsOperatingSystem
action: UpdateOS
onFailure: Abort
maxAttempts: 3
inputs:
include:
- KB1234567
- '*Security*'
```
**출력**
없음.
# AWSTOE run 명령에 대한 입력 구성
명령에 대한 명령줄 입력을 간소화하기 위해 `.json` 파일 확장자가 있는 JSON 형식 입력 구성 파일에 명령 파라미터 및 옵션에 대한 설정을 포함할 수 있습니다 AWSTOE **run**.는 다음 위치 중 하나에서 파일을 읽을 AWSTOE 수 있습니다.
+ 로컬 파일 경로(*./config.json*).
+ S3 버킷(*s3:////config.json*).
**run** 명령을 입력하면 **--config** 파라미터를 사용하여 입력 구성 파일을 지정할 수 있습니다. 예시:
```
awstoe run --config /config.json
```
**구성 파일**
입력 구성 JSON 파일에는 **run** 명령 파라미터 및 옵션을 통해 직접 제공할 수 있는 모든 설정에 대한 키-값 쌍이 포함되어 있습니다. 입력 구성 파일과 **run** 명령 모두에서 설정을 파라미터 또는 옵션으로 지정하는 경우, 다음과 같은 우선 순위 규칙이 적용됩니다.
**우선 순위 규칙**
1. 파라미터 또는 옵션을 AWS CLI통해의 **run** 명령에 직접 제공되는 설정은 동일한 설정에 대해 입력 구성 파일에 정의된 모든 값을 재정의합니다.
1. 입력 구성 파일의 설정이 구성 요소 기본값보다 우선합니다.
1. 구성 요소 문서에 다른 설정이 전달되지 않은 경우, 기본값이 있으면 기본값을 적용할 수 있습니다.
이 규칙에는 문서와 파라미터라는 두 가지 예외가 있습니다. 이러한 설정은 입력 구성과 명령 파라미터에서 다르게 작동합니다. 입력 구성 파일을 사용하는 경우, 이러한 파라미터를 **run** 명령에 직접 지정해서는 안 됩니다. 이렇게 하면 오류가 발생합니다.
**구성 요소 설정**
입력 구성 파일에는 다음 설정이 포함되어 있습니다. 파일을 간소화하기 위해, 필요하지 않은 선택적 설정은 생략할 수 있습니다. 달리 명시되지 않는 한 모든 설정은 선택 사항입니다.
+ **cwIgnoreFailures**(부울) - CloudWatch Logs의 로깅 실패를 무시합니다.
+ **cwLogGroup**(문자열) - CloudWatch Log의 `LogGroup` 이름입니다.
+ **cwLogRegion**(문자열) - CloudWatch Logs에 적용되는 AWS 리전입니다.
+ **cwLogStream**(문자열) - `console.log` 파일을 스트리밍할 AWSTOE 위치를 지정하는 CloudWatch Logs의 `LogStream` 이름입니다.
+ **documentS3BucketOwner**(문자열) - S3 URI 기반 문서에 대한 버킷 소유자의 계정 ID입니다.
+ **documents**(객체 배열, 필수) - AWSTOE **run** 명령이 실행 중인 YAML 구성 요소 문서를 나타내는 JSON 객체 배열입니다. 구성 요소 문서를 하나 이상 지정해야 합니다.
각 객체는 다음과 같은 필드로 구성됩니다.
+ **path**(문자열, 필수) - YAML 구성 요소 문서의 파일 위치입니다. 이 값은 다음 중 하나여야 합니다.
+ 로컬 파일 경로(*./component-doc-example.yaml*).
+ S3 URI(`s3://bucket/key`).
+ 이미지 빌더 컴포넌트 빌드 버전 ARN(arn:aws:imagebuilder:us-west-*2:123456789012*:component/*my-example-component*/2021.12.02/1).
+ **parameters**(객체 배열) - 키-값 쌍 객체의 배열로, 각 객체는 구성 요소 문서를 실행할 때 **run** 명령이 전달하는 구성 요소별 파라미터를 나타냅니다. 구성 요소의 경우 파라미터는 선택 사항입니다. 컴포넌트 문서에는 파라미터가 정의되어 있을 수도 있고 그렇지 않을 수도 있습니다.
각 객체는 다음과 같은 필드로 구성됩니다.
+ **name**(문자열, 필수) - 구성 요소 파라미터의 이름입니다.
+ **value**(문자열, 필수) - 명명된 파라미터에 대해 구성 요소 문서에 전달할 값입니다.
구성 요소 파라미터에 대한 자세한 내용은 [사용자 지정 구성 요소 문서에서 변수 사용](toe-user-defined-variables.md) 페이지의 **파라미터** 섹션을 참조하세요.
+ **executonId**(문자열) - 현재 **run** 명령 실행에 적용되는 고유 ID입니다. 이 ID는 해당 파일을 고유하게 식별하고 현재 명령 실행에 연결하기 위해 출력 및 로그 파일 이름에 포함됩니다. 이 설정을 생략하면 GUID가 AWSTOE 생성됩니다.
+ **logDirectory**(문자열) -가이 명령 실행의 모든 로그 파일을 AWSTOE 저장하는 대상 디렉터리입니다. 기본적으로 이 파일은 `TOE__` 디렉터리에 위치합니다. 로그 디렉터리를 지정하지 않으면는 현재 작업 디렉터리()를 AWSTOE 사용합니다`.`.
+ **logS3BucketName**(문자열) - 구성 요소 로그가 Amazon S3에 저장된 경우(권장)이 파라미터에 이름이 지정된 S3 버킷에 구성 요소 애플리케이션 로그를 AWSTOE 업로드합니다.
+ **logS3BucketOwner**(문자열) - 구성 요소 로그가 Amazon S3에 저장된 경우(권장),가 로그 파일을 AWSTOE 쓰는 버킷의 소유자 계정 ID입니다.
+ **logs3KeyPrefix**(문자열) - 구성 요소 로그가 Amazon S3에 저장되어 있는 경우(권장), 이 접두사는 버킷 내 로그 위치의 S3 객체 키 접두사입니다.
+ **parameters**(객체 배열) - 현재 **run** 명령 실행에 포함된 모든 구성 요소에 전체적으로 적용되는 파라미터를 나타내는 키-값 쌍 객체의 배열입니다.
+ **name**(문자열, 필수) - 글로벌 파라미터의 이름입니다.
+ **value**(문자열, 필수) - 명명된 파라미터에 대해 모든 구성 요소 문서에 전달할 값입니다.
+ **phase**(문자열) - YAML 구성 요소 문서에서 실행할 단계를 지정하는 쉼표로 구분된 목록입니다. 구성 요소 문서에 추가 단계가 포함된 경우, 해당 단계는 실행되지 않습니다.
+ **StateDirectory**(문자열) - 상태 추적 파일이 저장되는 파일 경로입니다.
+ **trace**(부울) - 콘솔에 대한 자세한 로깅을 활성화합니다.
**예시**
`sampledoc.yaml` 및 `conversation-intro.yaml` 예제는 두 구성 요소 문서, `build` 및 `test` 단계를 실행하는 입력 구성 파일을 보여줍니다. 각 구성 요소 문서에는 자체에만 적용되는 파라미터가 있으며 두 문서 모두 하나의 공유 파라미터를 사용합니다. `project` 파라미터는 두 컴포넌트 문서에 모두 적용됩니다.
```
{
"documents": [
{
"path": "/awstoe/sampledoc.yaml>",
"parameters": [
{
"name": "dayofweek",
"value": "Monday"
}
]
},
{
"path": "/awstoe/conversation-intro.yaml>",
"parameters": [
{
"name": "greeting",
"value": "Hello, HAL."
}
]
}
],
"phases": "build,test",
"parameters": [
{
"name": "project",
"value": "examples"
}
],
"cwLogGroup": "",
"cwLogStream": "",
"documentS3BucketOwner": "",
"executionId": "",
"logDirectory": "",
"logS3BucketName": "",
"logS3KeyPrefix": "",
"logS3BucketOwner": ""
}
```