You are using Amazon FSx for Windows File Server file system for persistent container storage.
' -Force"],
"cpu": 512,
"memory": 256,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"essential": false,
"name": "container1",
"mountPoints": [
{
"sourceVolume": "fsx-windows-dir",
"containerPath": "C:\\fsx-windows-dir",
"readOnly": false
}
]
},
{
"entryPoint": [
"powershell",
"-Command"
],
"portMappings": [
{
"hostPort": 443,
"protocol": "tcp",
"containerPort": 80
}
],
"command": ["Remove-Item -Recurse C:\\inetpub\\wwwroot\\* -Force; Start-Sleep -Seconds 120; Move-Item -Path C:\\fsx-windows-dir\\index.html -Destination C:\\inetpub\\wwwroot\\index.html -Force; C:\\ServiceMonitor.exe w3svc"],
"mountPoints": [
{
"sourceVolume": "fsx-windows-dir",
"containerPath": "C:\\fsx-windows-dir",
"readOnly": false
}
],
"cpu": 512,
"memory": 256,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"essential": true,
"name": "container2"
}
],
"family": "fsx-windows",
"executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
"volumes": [
{
"name": "fsx-windows-dir",
"fsxWindowsFileServerVolumeConfiguration": {
"fileSystemId": "fs-0eeb5730b2EXAMPLE",
"authorizationConfig": {
"domain": "example.com",
"credentialsParameter": "arn:arn-1234"
},
"rootDirectory": "share"
}
}
]
}
```
`FSxWindowsFileServerVolumeConfiguration`
유형: 객체
필수 여부: 아니요
이 파라미터는 태스크 저장에 [FSx for Windows File Server](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html) 파일 시스템을 사용할 때 지정됩니다.
`fileSystemId`
유형: 문자열
필수 항목 여부: 예
사용할 FSx for Windows File Server 파일 시스템 ID입니다.
`rootDirectory`
유형: 문자열
필수 항목 여부: 예
호스트 내의 루트 디렉터리로 탑재할 FSx for Windows File Server 파일 시스템 내 디렉터리입니다.
`authorizationConfig`
`credentialsParameter`
유형: 문자열
필수 항목 여부: 예
권한 부여 자격 증명 옵션:
+ [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 암호의 Amazon 리소스 이름(ARN).
+ [Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html) 파라미터의 Amazon 리소스 이름(ARN).
`domain`
유형: 문자열
필수 항목 여부: 예
셀프 호스팅된 EC2 Active Directory 또는 [AWS Directory Service for Microsoft Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/directory_microsoft_ad.html)(AWS Managed Microsoft AD) 디렉터리에서 호스팅하는 정규화된 도메인 이름입니다.
## FSx for Windows File Server 볼륨 자격 증명을 저장하는 방법
자격 증명 파라미터와 함께 사용할 자격 증명을 저장하는 방법에는 두 가지가 있습니다.
+ **AWS Secrets Manager 암호**
이 자격 증명은 *다른 암호 유형* 카테고리를 사용하여 AWS Secrets Manager 콘솔에서 생성할 수 있습니다. 각 키/값 쌍, 사용자 이름/관리자 및 암호/*암호*에 대한 열을 추가합니다.
+ **Systems Manager 파라미터**
이 자격 증명은 다음 예제 코드 조각에 표시된 형식으로 텍스트를 입력하여 Systems Manager 파라미터 콘솔에서 생성될 수 있습니다.
```
{
"username": "admin",
"password": "password"
}
```
태스크 정의 `FSxWindowsFileServerVolumeConfiguration` 파라미터의 `credentialsParameter`는 암호 ARN 또는 Systems Manager 파라미터 ARN을 보유합니다. 자세한 정보는 *Secrets Manager 사용 설명서*의 [AWS Secrets Manager란 무엇인가요?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 및 *Systems Manager 사용 설명서*의 [Systems Manager 파라미터 스토어](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)를 참조하세요.
# Amazon ECS에 대한 FSx for Windows File Server 파일 시스템을 구성하는 방법 알아보기
FSx for Windows File Server 파일 시스템과 파일 시스템에 액세스할 수 있는 컨테이너를 호스팅하는 Amazon ECS 최적화 Windows 인스턴스를 시작하는 방법에 대해 알아보세요. 이렇게 하려면 먼저 Directory Service AWS 관리형 Microsoft Active Directory를 생성합니다. 그런 다음 Amazon EC2 인스턴스 및 태스크 정의를 사용하여 FSx for Windows File Server 파일 시스템 및 클러스터를 생성합니다. FSx for Windows File Server 파일 시스템을 사용하도록 컨테이너에 대한 태스크 정의를 구성합니다. 마지막으로 파일 시스템을 테스트합니다.
이 태스크는 Active Directory 또는 FSx for Windows File Server 파일 시스템을 시작하거나 삭제할 때마다 20\$145분 정도 걸립니다. 자습서를 완료하거나 몇 세션 동안 자습서를 완료하기 위해 90분 이상 예약할 준비를 합니다.
## 자습서의 사전 조건
+ 관리 사용자입니다. [Amazon ECS 사용 설정](get-set-up-for-amazon-ecs.md)을(를) 참조하세요.
+ (선택 사항) RDP 액세스를 통해 EC2 Windows 인스턴스에 연결하기 위한 `PEM` 키 페어. 키 페어를 생성하는 방법에 대한 자세한 내용은 *Amazon EC2 사용 설명서*의 [Amazon EC2 키 페어 및 Amazon EC2 인스턴스](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)를 참조하세요.
+ 하나 이상의 퍼블릭 서브넷과 프라이빗 서브넷, 보안 그룹이 있는 VPC. 기본 VPC를 사용할 수 있습니다. NAT 게이트웨이 또는 장치가 필요하지 않습니다. Directory Service는 Active Directory에서 NAT(네트워크 주소 변환)를 지원하지 않습니다. 이 작업을 수행하려면 VPC 내에 Active Directory, FSx for Windows File Server 파일 시스템, ECS 클러스터 및 EC2 인스턴스가 있어야 합니다. VPC와 Active Directory에 대한 자세한 내용은 [VPC 생성](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) 및 [AWS 관리형 Microsoft AD 생성을 위한 사전 조건](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html#ms_ad_getting_started_prereqs)을 참조하세요.
+ IAM ecsInstanceRole 및 ecsTaskExecutionRole 권한은 계정과 연결됩니다. 이러한 서비스 연결 역할을 통해 서비스가 API 호출을 수행하고 사용자를 대신하여 컨테이너, 보안 암호, 디렉터리 및 파일 서버에 액세스할 수 있습니다.
## 1단계: IAM 액세스 역할 생성
**AWS Management Console을 사용하여 클러스터를 생성합니다.**
1. ecsInstanceRole이 있는지 확인하고 없는 경우 생성 방법을 확인하려면 [Amazon ECS 컨테이너 인스턴스 IAM 역할](instance_IAM_role.md) 섹션을 참조하세요.
1. 실제 프로덕션 환경에서는 최소 사용 권한에 맞게 역할 정책을 사용자 지정하는 것이 좋습니다. 이 자습서를 통해 작업하기 위해 다음 AWS 관리형 정책이 ecsInstanceRole에 연결되었는지 확인합니다. 아직 연결되어 있지 않은 경우 정책을 연결합니다.
+ AmazonEC2ContainerServiceforEC2Role
+ AmazonSSMManagedInstanceCore
+ AmazonSSMDirectoryServiceAccess
AWS 관리형 정책을 연결하려면
1. [IAM 콘솔(IAM console)](https://console.aws.amazon.com//iam/)을 엽니다.
1. 탐색 창에서 **역할**을 선택합니다.
1. **AWS 관리형 역할**을 선택합니다.
1. **권한, 정책 연결**을 선택합니다.
1. 연결에 사용할 수 있는 정책의 범위를 좁히려면 **필터(Filter)**를 사용합니다.
1. 적절한 정책을 선택하고 **정책 연결(Attach policy)**을 선택합니다.
1. ecsTaskExecutionRole이 있는지 확인하고 없는 경우 생성 방법을 확인하려면 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
실제 프로덕션 환경에서는 최소 사용 권한에 맞게 역할 정책을 사용자 지정하는 것이 좋습니다. 이 자습서를 통해 작업하기 위해 다음 AWS 관리형 정책이 ecsTaskExecutionRole에 연결되었는지 확인합니다. 정책이 아직 연결되어 있지 않은 경우 정책을 연결합니다. 이전 섹션에 제시한 절차를 통해 AWS 관리형 정책에 연결합니다.
+ SecretsManagerReadWrite
+ AmazonFSxReadOnlyAccess
+ AmazonSSMReadOnlyAccess
+ AmazonECSTaskExecutionRolePolicy
## 2단계: Windows Active Directory(AD) 생성
1. AWS *Directory Service 관리 안내서*의 [AWS 관리형 Microsoft AD 생성](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html#ms_ad_getting_started_create_directory)에 설명된 단계를 따릅니다. 이 자습서에서 지정한 VPC를 사용합니다. *AWS 관리형 Microsoft AD 생성*의 3단계에서 다음 단계에 사용할 사용자 이름과 관리자 암호를 저장합니다. 또한 향후 단계를 위해 정규화된 디렉터리 DNS 이름을 적어 둡니다. Active Directory를 생성하는 동안 다음 단계를 완료할 수 있습니다.
1. 다음 단계에서 사용할 AWS Secrets Manager 보안 암호를 생성합니다. AWS *Secrets Manager 사용 설명서*의 [Secrets Manager 시작하기](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html#get-started)를 참조하세요.
1. [Secrets Manager 콘솔](https://console.aws.amazon.com//secretsmanager/)을 엽니다.
1. **새 보안 암호 저장(Store a new secret)**을 클릭합니다.
1. **다른 유형의 보안 암호(Other type of secrets)**를 선택합니다.
1. 첫 번째 행의 **보안 암호 키/값(Secret key/value)**에서 값이 **admin**인 키 **username**를 생성합니다. **\$1행 추가(\$1 Add row)**를 클릭합니다.
1. 새 행에서 키 **password**를 생성합니다. 값에 *AWS 관리형 AD 디렉터리 생성*의 3단계에서 입력한 암호를 입력합니다.
1. **다음(Next)** 버튼을 클릭합니다.
1. 보안 암호 이름 및 설명을 입력합니다. **다음(Next)**을 클릭합니다.
1. **다음**을 클릭합니다. **저장(Store)**을 클릭합니다.
1. **보안 암호** 페이지에서 방금 생성한 보안 암호를 클릭합니다.
1. 다음 단계에서 사용할 새 보안 암호의 ARN을 저장합니다.
1. Active Directory를 생성하는 동안 다음 단계로 진행할 수 있습니다.
## 3단계: 보안 그룹 확인 및 업데이트
이 단계에서는 사용 중인 보안 그룹에 대한 규칙을 확인하고 업데이트합니다. 이를 위해 VPC에 대해 생성한 기본 보안 그룹을 사용할 수 있습니다.
**보안 그룹을 확인하고 업데이트합니다.**
포트 간에 데이터를 전송하려면 보안 그룹을 생성하거나 편집해야 합니다. 자세한 정보는 *FSx for Windows File Server 사용 설명서*의 [Amazon VPC 보안 그룹](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/limit-access-security-groups.html#fsx-vpc-security-groups)에서 설명합니다. 이 태스크는 다음 인바운드 규칙 표의 첫 번째 행에 표시된 보안 그룹 인바운드 규칙을 생성하여 수행할 수 있습니다. 이 규칙은 보안 그룹에 할당된 네트워크 인터페이스(및 연결된 인스턴스)로부터의 인바운드 트래픽을 허용합니다. 생성한 모든 클라우드 리소스는 동일한 VPC 내에 있으며 동일한 보안 그룹에 연결됩니다. 따라서 이 규칙을 사용하면 필요에 따라 FSx for Windows File Server 파일 시스템, Active Directory 및 ECS 인스턴스에서 트래픽을 주고받을 수 있습니다. 다른 인바운드 규칙은 트래픽이 웹사이트 및 ECS 인스턴스에 연결하기 위한 RDP 액세스를 제공하도록 허용합니다.
다음 표에서는 이 자습서에 필요한 보안 그룹 인바운드 규칙을 보여 줍니다.
| 유형 | 프로토콜 | 포트 범위 | 소스 |
| --- | --- | --- | --- |
| 모든 트래픽 | 모두 | 모두 | *보안 그룹(SG)* |
| HTTPS | TCP | 443 | 0.0.0.0/0 |
| RDP | TCP | 3389 | 랩톱 IP 주소 |
다음 표에서는 이 자습서에 필요한 보안 그룹 아웃바운드 규칙을 보여 줍니다.
| Type | 프로토콜 | 포트 범위 | 대상 |
| --- | --- | --- | --- |
| 모든 트래픽 | 모두 | 모두 | 0.0.0.0/0 |
1. [EC2 콘솔](https://console.aws.amazon.com//ec2/)을 열고 왼쪽 메뉴에서 **보안 그룹(Security Groups)**을 선택합니다.
1. 이제 표시된 보안 그룹 목록에서 이 자습서에서 사용하는 보안 그룹의 왼쪽에 있는 확인란을 선택합니다.
보안 그룹 정보가 표시됩니다.
1. **인바운드 규칙** 또는 **아웃바운드 규칙** 탭을 클릭하고 **인바운드 규칙 편집** 또는 **아웃바운드 규칙 편집** 버튼을 선택하여 인바운드 및 아웃바운드 규칙을 편집합니다. 이전 표에 표시된 규칙과 일치하도록 규칙을 편집합니다. 이 자습서의 뒷부분에서 EC2 인스턴스를 생성한 후, *Amazon EC2 사용 설명서*의 [RDP를 사용하여 Windows 인스턴스에 연결](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connecting_to_windows_instance.html)에서 설명한 것처럼 EC2 인스턴스의 퍼블릭 IP 주소로 인바운드 규칙 RDP 소스를 편집합니다.
## 4단계: Amazon FSx for Windows File Server 파일 시스템 생성
보안 그룹을 확인 및 업데이트하고 Active Directory를 생성하여 활성 상태가 되면 Active Directory와 동일한 VPC에 FSx for Windows File Server 파일 시스템을 생성합니다. 다음 단계에 따라 Windows File Server 파일 시스템을 Windows 작업에 사용할 FSx for Windows File Server 파일 시스템을 생성합니다.
**첫 파일 시스템을 생성합니다.**
1. [Amazon FSx 콘솔](https://console.aws.amazon.com//fsx/)을 엽니다.
1. 대시보드에서 **파일 시스템 생성(Create file system)**을 선택해 파일 시스템 생성 마법사를 시작합니다.
1. **파일 시스템 유형 선택** 페이지에서 **FSx for Windows File Server**를 선택한 다음 **다음**을 선택합니다. **파일 시스템 생성** 페이지가 표시됩니다.
1. **파일 시스템 정보(File system details)** 섹션에서 파일 시스템의 이름을 입력합니다. 파일 시스템의 이름을 지정하면 파일 시스템을 보다 쉽게 찾고 관리할 수 있습니다. 최대 256자의 유니코드 문자를 사용할 수 있습니다. 허용되는 문자는 문자, 숫자, 공백과 특수 문자 \$1기호(\$1), 빼기 기호(-), 등호(=), 마침표(.), 밑줄(\$1), 콜론(:) 및 슬래시(/)입니다.
1. **배포 유형(Deployment type)**에서 **단일 AZ(Single-AZ)**를 사용하여 단일 가용 영역에 배포되는 파일 시스템을 배포합니다. *단일 AZ 2*는 단일 가용 영역 파일 시스템의 최신 세대이며 SSD 및 HDD 스토리지를 지원합니다.
1. **스토리지 유형(Storage type)**에서 **HDD**를 선택합니다.
1. **스토리지 용량(Storage capacity)**에 최소 스토리지 용량을 입력합니다.
1. **용량 처리량(Throughput capacity)**을 기본 설정으로 유지합니다.
1. **네트워크 및 보안(Network & security)** 섹션에서 Directory Service 디렉터리에 선택한 것과 동일한 Amazon VPC를 선택합니다.
1. **VPC 보안 그룹(VPC Security Groups)**에서 *3단계: 보안 그룹 확인 및 업데이트*에서 확인한 보안 그룹을 선택합니다.
1. **Windows 인증(Windows authentication)**에서 **AWS 관리형 Microsoft Active Directory**를 선택한 다음 목록에서 Directory Service 디렉터리를 선택합니다.
1. **암호화(Encryption)**에서 기본 **암호화 키(Encryption key)** 설정을 **aws/fsx(기본값)**로 그대로 사용합니다.
1. **유지 관리 기본 설정(Maintenance preferences)**의 기본 설정을 유지합니다.
1. **다음(Next)** 버튼을 클릭합니다.
1. **파일 시스템 생성** 페이지에 표시된 파일 시스템 구성을 검토합니다. 참조할 수 있도록 파일 시스템을 생성한 후 수정할 수 있는 파일 시스템 설정을 확인합니다. **파일 시스템 생성**을 선택합니다.
1. 파일 시스템 ID를 기록합니다. 이후 단계에서 사용해야 합니다.
FSx for Windows File Server 시스템이 생성되는 동안 다음 단계로 이동하여 클러스터 및 EC2 인스턴스를 생성할 수 있습니다.
## 5단계: Amazon ECS 클러스터 생성
**Amazon ECS 콘솔을 사용하여 클러스터 생성**
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 모음에서 사용할 리전을 선택합니다.
1. 탐색 창에서 **클러스터**를 선택합니다.
1. **클러스터(Clusters)** 페이지에서 **클러스터 생성(Create cluster)**을 선택합니다.
1. **클러스터 구성**의 **클러스터 이름**에 **windows-fsx-cluster**를 입력합니다.
1. **인프라**에서 AWS Fargate(서버리스)를 선택 취소한 다음 **Amazon EC2 인스턴스**를 선택합니다.
1. Auto Scaling 그룹을 생성하려면 **Auto Scaling 그룹(ASG)(Auto Scaling group (ASG))**에서 **새 그룹 생성(Create new group)**을 선택한 후 그룹에 대한 다음 세부 정보를 제공합니다.
+ **운영 체제/아키텍처의**에서 **Windows Server 2019 Core**를 선택합니다.
+ **EC2 인스턴스 유형**에서 t2.medium 또는 t2.micro를 선택합니다.
1. **생성(Create)**을 선택합니다.
## 6단계: Amazon ECS 최적화 Amazon EC2 인스턴스 생성
Amazon ECS Windows 컨테이너 인스턴스를 생성합니다.
**Amazon ECS 인스턴스 생성**
1. `aws ssm get-parameters` 명령을 사용하여 VPC를 호스팅하는 리전에 대한 AMI 이름을 검색합니다. 자세한 내용은 [Amazon ECS 최적화 AMI 메타데이터 검색](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/retrieve-ecs-optimized_windows_AMI.html)을 참조하세요.
1. Amazon EC2 콘솔을 사용하여 인스턴스를 시작합니다.
1. [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)에서 Amazon EC2 콘솔을 엽니다.
1. 탐색 모음에서 사용할 리전을 선택합니다.
1. **EC2 대시보드**에서 **인스턴스 시작(Launch Instance)**을 선택합니다.
1. **Name**(이름)에 고유한 이름을 입력합니다.
1. **애플리케이션 및 OS 이미지(Amazon Machine Image)**에서 **검색** 필드에 첫 번째 단계에서 검색한 AMI 이름을 입력합니다.
1. **인스턴스 유형**에서 t2.medium 또는 t2.micro를 선택합니다.
1. **키 페어(로그인)**에서 키 페어를 선택합니다. 키 페어를 지정하지 않은 경우
1. **네트워크 설정**에서 **VPC** 및 **서브넷**에 대해 VPC 및 퍼블릭 서브넷을 선택합니다.
1. **Network settings**(네트워크 설정)의 **Security group**(보안 그룹)에서 기존 보안 그룹을 선택하거나 새 보안 그룹을 생성합니다. 선택한 보안 그룹에 [자습서의 사전 조건](#wfsx-prerequisites)에 정의된 인바운드 및 아웃바운드 규칙이 있는지 확인합니다.
1. **Network settings**(네트워크 설정)의 **Auto-assign Public IP**(퍼블릭 IP 자동 할당)에서 **Enable**(활성화)을 선택합니다.
1. **고급 세부 정보**를 확장하고 **도메인 조인 디렉터리**에서 생성한 Active Directory의 ID를 선택합니다. 이 옵션 도메인은 EC2 인스턴스가 시작될 때 AD에 조인합니다.
1. **Advanced details**(고급 세부 정보)의 **IAM instance profile**(IAM 인스턴스 프로파일)에서 **ecsInstanceRole**을 선택합니다.
1. 다음 사용자 데이터로 Amazon ECS 컨테이너 인스턴스를 구성합니다. **Advanced Details**(고급 세부 정보)에서 다음 스크립트를 **User data**(사용자 데이터) 필드에 붙여 넣고 *cluster\$1name*을 클러스터의 이름으로 바꿉니다.
```
```
1. 준비가 되었으면 승인 필드를 선택한 다음 **인스턴스 시작(Launch Instances)**을 선택합니다.
1. 확인 페이지에서 인스턴스가 실행 중인지 확인할 수 있습니다. **인스턴스 보기**를 선택하여 확인 페이지를 닫고 콘솔로 돌아갑니다.
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **클러스터**를 선택한 다음 **windows-fsx-cluster**를 선택합니다.
1. **인프라** 탭을 선택하고 인스턴스가 **windows-fsx-cluster** 클러스터에 등록되었는지 확인합니다.
## 7단계: Windows 태스크 정의 등록
Amazon ECS 클러스터에서 Windows 컨테이너를 실행하려면 먼저 태스크 정의를 등록해야 합니다. 다음 작업 정의 예제는 간단한 웹페이지를 보여 줍니다. 이 작업으로 FSx 파일 시스템에 액세스할 수 있는 두 개의 컨테이너가 시작됩니다. 첫 번째 컨테이너는 HTML 파일을 파일 시스템에 작성합니다. 두 번째 컨테이너는 파일 시스템에서 HTML 파일을 다운로드하고 웹페이지를 제공합니다.
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **작업 정의**를 선택합니다.
1. **새 태스크 정의 생성(Create new task definition)**, **JSON으로 새 태스크 정의 생성(Create new task definition with JSON)**을 선택합니다.
1. JSON 편집기 상자에서 작업 실행 역할의 값과 FSx 파일 시스템에 대한 세부 정보를 바꾼 다음 **저장**을 선택합니다.
```
{
"containerDefinitions": [
{
"entryPoint": [
"powershell",
"-Command"
],
"portMappings": [],
"command": ["New-Item -Path C:\\fsx-windows-dir\\index.html -ItemType file -Value '
Amazon ECS Sample App
It Works!
You are using Amazon FSx for Windows File Server file system for persistent container storage.
' -Force"],
"cpu": 512,
"memory": 256,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"essential": false,
"name": "container1",
"mountPoints": [
{
"sourceVolume": "fsx-windows-dir",
"containerPath": "C:\\fsx-windows-dir",
"readOnly": false
}
]
},
{
"entryPoint": [
"powershell",
"-Command"
],
"portMappings": [
{
"hostPort": 443,
"protocol": "tcp",
"containerPort": 80
}
],
"command": ["Remove-Item -Recurse C:\\inetpub\\wwwroot\\* -Force; Start-Sleep -Seconds 120; Move-Item -Path C:\\fsx-windows-dir\\index.html -Destination C:\\inetpub\\wwwroot\\index.html -Force; C:\\ServiceMonitor.exe w3svc"],
"mountPoints": [
{
"sourceVolume": "fsx-windows-dir",
"containerPath": "C:\\fsx-windows-dir",
"readOnly": false
}
],
"cpu": 512,
"memory": 256,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"essential": true,
"name": "container2"
}
],
"family": "fsx-windows",
"executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
"volumes": [
{
"name": "fsx-windows-dir",
"fsxWindowsFileServerVolumeConfiguration": {
"fileSystemId": "fs-0eeb5730b2EXAMPLE",
"authorizationConfig": {
"domain": "example.com",
"credentialsParameter": "arn:arn-1234"
},
"rootDirectory": "share"
}
}
]
}
```
## 8단계: 작업 실행 및 결과 보기
태스크를 실행하기 전에 FSx for Windows File Server 파일 시스템의 상태가 **사용 가능(Available)**인지 확인합니다. 사용 가능하면 생성한 태스크 정의를 사용하여 태스크를 실행할 수 있습니다. 파일 시스템을 사용하여 HTML 파일을 섞는 컨테이너를 생성하여 태스크를 시작합니다. 셔플 후, 웹 서버는 간단한 HTML 페이지를 제공합니다.
**참고**
VPN 내에서 웹사이트에 연결하지 못할 수도 있습니다.
**Amazon ECS 콘솔을 사용하여 작업을 실행하고 결과를 확인합니다.**
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **클러스터**를 선택한 다음 **windows-fsx-cluster**를 선택합니다.
1. **작업** 탭을 선택하고 **새 작업 실행**을 선택합니다.
1. **시작 유형(Launch Type)**을 **EC2**로 선택합니다.
1. 배포 구성에서 **작업 정의**에 대해 **fsx-windows**를 선택한 다음 **생성**을 선택합니다.
1. 작업 상태가 **RUNNING**이면 작업 ID를 선택합니다.
1. **컨테이너**에서 container1 상태가 **STOPPED**이면 container2를 선택하여 컨테이너의 세부 정보를 확인합니다.
1. **container2의 컨테이너 세부 정보**에서 **네트워크 바인딩**을 선택한 다음 컨테이너와 연결된 외부 IP 주소를 클릭합니다. 브라우저가 열리고 다음 메시지가 표시됩니다.
```
Amazon ECS Sample App
It Works!
You are using Amazon FSx for Windows File Server file system for persistent container storage.
```
**참고**
메시지가 표시되는 데 몇 분 정도 걸릴 수 있습니다. 몇 분 후 메시지가 표시되지 않는 경우 VPN에서 실행되고 있지 않은지 확인하고 컨테이너 인스턴스의 보안 그룹이 포트 443에서 인바운드 네트워크 HTTP 트래픽을 허용하는지 확인합니다.
## 9단계: 정리
**참고**
FSx for Windows File Server 파일 시스템 또는 AD를 삭제하는 데 20\$145분 정도 걸립니다. AD 삭제 태스크를 시작하기 전에 FSx for Windows File Server 파일 시스템의 삭제 작업이 완료될 때까지 기다려야 합니다.
**FSx for Windows File Server 파일 시스템을 삭제합니다.**
1. [Amazon FSx 콘솔](https://console.aws.amazon.com//fsx/)을 엽니다.
1. 방금 생성한 FSx for Windows File Server 파일 시스템의 왼쪽에 있는 라디오 버튼을 선택합니다.
1. **작업**을 선택합니다.
1. **파일 시스템 삭제(Delete file system)**를 선택합니다.
**AD를 삭제합니다.**
1. [Directory Service 콘솔](https://console.aws.amazon.com//directoryservicev2/)을 엽니다.
1. 방금 생성한 AD의 왼쪽에 있는 라디오 버튼을 선택합니다.
1. **작업**을 선택합니다.
1. **디렉터리 삭제(Delete directory)**를 선택합니다.
**클러스터를 삭제합니다.**
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **클러스터**를 선택한 다음 **windows-fsx-cluster**를 선택합니다.
1. **클러스터 삭제**를 선택합니다.
1. 상자에 구문을 입력한 다음, **삭제**를 선택합니다.
**EC2 인스턴스를 종료합니다.**
1. [Amazon EC2 콘솔](https://console.aws.amazon.com//ec2/)을 엽니다.
1. 왼쪽 메뉴에서 **인스턴스(Instances)**를 선택합니다.
1. 생성한 EC2 인스턴스의 왼쪽에 있는 상자를 선택합니다.
1. **인스턴스 상태**를 클릭하고 **인스턴스 종료**를 클릭합니다.
**보안 암호를 삭제합니다.**
1. [Secrets Manager 콘솔](https://console.aws.amazon.com//secretsmanager/)을 엽니다.
1. 이 시연을 위해 생성한 보안 암호를 선택합니다.
1. **작업(Actions)**을 클릭합니다.
1. **보안 암호 삭제(Delete secret)**를 선택합니다.
# Amazon ECS에서 Docker 볼륨 사용
Docker 볼륨을 사용할 때는 기본적으로 제공되는 `local` 드라이버 또는 타사 볼륨 드라이버를 사용할 수 있습니다. Docker 볼륨은 Docker에서 관리되며, 디렉터리는 볼륨 데이터가 포함되는 컨테이너 인스턴스의 `/var/lib/docker/volumes`에 생성됩니다.
도커 볼륨을 사용하려면 태스크 정의에서 `dockerVolumeConfiguration`을 지정합니다. 자세한 내용은 Docker 설명서 센터의 [볼륨](https://docs.docker.com/engine/storage/volumes/)을 참조하세요.
Docker 볼륨의 몇 가지 일반 사용 사례는 다음과 같습니다.
+ 컨테이너에 사용할 영구 데이터 볼륨 제공
+ 동일한 컨테이너 인스턴스의 컨테이너마다 다른 위치에서 정의된 데이터 볼륨 공유
+ 비어있는 비영구 데이터 볼륨을 정의한 후 동일 태스크에 속하는 다수의 컨테이너에 탑재
+ 타사 드라이버에서 관리하는 태스크에 데이터 볼륨을 제공하는 방법
## Docker 볼륨 사용 시 고려 사항
Docker 볼륨을 사용할 때는 다음 사항을 고려해야 합니다.
+ EC2 시작 유형 또는 외부 인스턴스를 사용하는 경우에는 Docker 볼륨만 지원됩니다.
+ Windows 컨테이너는 `local` 드라이버의 사용만 지원합니다.
+ 타사 드라이버를 사용하는 경우에는 컨테이너 에이전트를 시작하기 전에 해당 드라이버가 컨테이너 인스턴스에 설치되어 있고 활성 상태여야 합니다. 에이전트를 시작하기 전에 타사 드라이버가 활성 상태가 아니면 다음 명령 중 하나를 사용하여 컨테이너 에이전트를 다시 시작할 수 있습니다.
+ Amazon ECS 최적화 Amazon Linux 2 AMI의 경우:
```
sudo systemctl restart ecs
```
+ Amazon ECS 최적화 Amazon Linux AMI의 경우:
```
sudo stop ecs && sudo start ecs
```
작업 정의에서 Docker 볼륨을 지정하는 방법에 대한 자세한 내용은 [Amazon ECS 작업 정의에서 Docker 볼륨 지정](specify-volume-config.md) 섹션을 참조하세요.
# Amazon ECS 작업 정의에서 Docker 볼륨 지정
컨테이너가 데이터 볼륨을 사용할 수 있으려면 태스크 정의에서 볼륨 및 탑재 지점 구성을 지정해야 합니다. 이번 섹션에서는 컨테이너의 볼륨 구성에 대해 설명합니다. Docker 볼륨을 사용하는 태스크의 경우 `dockerVolumeConfiguration`을 지정합니다. 바인드 탑재 호스트 볼륨을 사용하는 태스크의 경우, `host`와 `sourcePath`(옵션)를 지정합니다.
다음 태스크 정의 JSON은 컨테이너에 사용할 `volumes` 및 `mountPoints` 객체의 구문을 나타냅니다.
```
{
"containerDefinitions": [
{
"mountPoints": [
{
"sourceVolume": "string",
"containerPath": "/path/to/mount_volume",
"readOnly": boolean
}
]
}
],
"volumes": [
{
"name": "string",
"dockerVolumeConfiguration": {
"scope": "string",
"autoprovision": boolean,
"driver": "string",
"driverOpts": {
"key": "value"
},
"labels": {
"key": "value"
}
}
}
]
}
```
`name`
유형: 문자열
필수 여부: 아니요
볼륨의 이름입니다. 최대 255자의 문자(대문자 및 소문자), 숫자, 하이(`-`) 및 밑줄(`_`)이 허용됩니다. 이 이름은 컨테이너 정의 `mountPoints` 객체의 `sourceVolume` 파라미터에서 참조됩니다.
`dockerVolumeConfiguration`
유형: [DockerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DockerVolumeConfiguration.html) 객체
필수 여부: 아니요
이 파라미터는 Docker 볼륨을 사용할 때 지정됩니다. Docker 볼륨은 EC2 인스턴스에서 작업을 실행하는 경우에만 지원됩니다. Windows 컨테이너는 `local` 드라이버의 사용만 지원합니다. 바인드 탑재를 사용하려면 대신에 `host`를 지정하세요.
`scope`
유형: 문자열
유효한 값: `task` \$1 `shared`
필수 여부: 아니요
수명 주기를 결정하는 Docker 볼륨의 범위입니다. 범위가 `task`로 지정된 Docker 볼륨은 태스크가 시작될 때 자동으로 프로비저닝되고, 태스크가 중단되면 삭제됩니다. 범위가 `shared`로 지정된 Docker 볼륨은 태스크 중단 후에도 유지됩니다.
`autoprovision`
유형: Boolean
기본값: `false`
필수 여부: 아니요
이 값이 `true`인 경우 도커 볼륨이 아직 없으면 도커 볼륨이 생성됩니다. 이 필드는 `scope`가 `shared`인 경우에만 사용됩니다. `scope`가 `task`인 경우 이 파라미터를 생략해야 합니다.
`driver`
유형: 문자열
필수 여부: 아니요
사용할 Docker 볼륨 드라이버입니다. Docker에서 제공하는 드라이버 이름이 작업 배치에 사용되므로 드라이버 값과 이 이름이 일치해야 합니다. Docker 플러그인 CLI를 사용하여 드라이버를 설치했다면 `docker plugin ls`를 사용하여 컨테이너 인스턴스에서 드라이버 이름을 검색합니다. 다른 방법을 사용하여 드라이버를 설치했다면 Docker 플러그인 검색을 사용하여 드라이버 이름을 검색합니다.
`driverOpts`
유형: 문자열
필수 여부: 아니요
전달할 Docker 드라이버에 특정한 옵션 맵입니다. 이 파라미터는 Docker의 볼륨 생성의 `DriverOpts`에 매핑됩니다.
`labels`
유형: 문자열
필수 여부: 아니요
Docker 볼륨에 추가할 사용자 지정 메타데이터입니다.
`mountPoints`
유형: 객체 배열
필수 여부: 아니요
컨테이너에서 데이터 볼륨의 탑재 지점입니다. 이 파라미터는 create-container Docker API의 `Volumes` 및 docker run에 대한 `--volume` 옵션에 매핑됩니다.
Windows 컨테이너는 전체 디렉터리를 동일한 드라이브에 `$env:ProgramData`로 마운트할 수 있습니다. Windows 컨테이너는 디렉터리를 다른 드라이브에 탑재할 수 없으며, 탑재 지점은 여러 드라이브에 걸쳐 사용할 수 없습니다. Amazon EBS 볼륨을 Amazon ECS 작업에 직접 연결하려면 탑재 지점을 지정해야 합니다.
`sourceVolume`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
탑재할 볼륨의 이름입니다.
`containerPath`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
볼륨을 탑재할 컨테이너의 경로입니다.
`readOnly`
유형: 부울
필수 여부: 아니요
이 값이 `true`일 경우 컨테이너에는 볼륨에 대한 읽기 전용 액세스가 부여됩니다. 이 값이 `false`일 경우 컨테이너는 볼륨에 쓸 수 있습니다. 기본값은 `false`입니다.
Windows 운영 체제를 실행하는 EC2 인스턴스에서 실행되는 태스크의 경우 값을 기본값인 `false`로 둡니다.
# Amazon ECS용 Docker 볼륨 예제
다음 예제에서는 컨테이너에 임시 스토리지를 제공하는 방법과 여러 컨테이너에 공유 볼륨을 제공하는 방법, 컨테이너에 NFS 영구 스토리지를 제공하는 방법을 보여줍니다.
**Docker 볼륨을 사용하여 컨테이너에 임시구 스토리지를 제공하는 방법**
이 예에서 컨테이너는 태스크가 완료된 후 폐기되는 빈 데이터 볼륨을 사용합니다. 사용 사례 중 한 예로, 태스크 도중 Scratch 파일 스토리지 위치에 액세스해야 하는 컨테이너가 있을 수 있습니다. Docker 볼륨을 사용하면 이러한 태스크를 수행할 수 있습니다.
1. 태스크 정의 `volumes` 섹션에서 `name` 및 `DockerVolumeConfiguration` 값을 사용하여 데이터 볼륨을 정의합니다. 이 예제에서는 태스크가 중단된 후 볼륨이 삭제되도록 범위를 `task`로 지정하고 기본 제공 `local` 드라이버를 사용합니다.
```
"volumes": [
{
"name": "scratch",
"dockerVolumeConfiguration" : {
"scope": "task",
"driver": "local",
"labels": {
"scratch": "space"
}
}
}
]
```
1. `containerDefinitions` 섹션에서 정의된 볼륨 이름과 컨테이너에서 볼륨을 탑재할 `mountPoints` 값을 참조하는 `containerPath` 값을 사용하여 컨테이너를 정의합니다.
```
"containerDefinitions": [
{
"name": "container-1",
"mountPoints": [
{
"sourceVolume": "scratch",
"containerPath": "/var/scratch"
}
]
}
]
```
**Docker 볼륨을 사용하여 여러 컨테이너에 영구 스토리지 제공**
이번 예제에서는 다수의 컨테이너에서 공유 볼륨을 사용하고, 이 볼륨을 사용하는 단일 태스크가 중단된 후에도 볼륨을 유지하려고 합니다. 내장 `local` 드라이버를 사용 중입니다. 또한 볼륨이 컨테이너 인스턴스의 수명 주기에 계속해서 연결되도록 합니다.
1. 태스크 정의 `volumes` 섹션에서 `name` 및 `DockerVolumeConfiguration` 값을 사용하여 데이터 볼륨을 정의합니다. 이 예제에서는 `shared` 범위를 지정하여 볼륨이 유지되도록 자동 프로비저닝을 `true`로 설정합니다. 이는 사용하기 위해 볼륨이 생성되도록 하기 위함입니다. 그런 다음 내장 `local` 드라이버도 사용합니다.
```
"volumes": [
{
"name": "database",
"dockerVolumeConfiguration" : {
"scope": "shared",
"autoprovision": true,
"driver": "local",
"labels": {
"database": "database_name"
}
}
}
]
```
1. `containerDefinitions` 섹션에서 정의된 볼륨 이름과 컨테이너에서 볼륨을 탑재할 `mountPoints` 값을 참조하는 `containerPath` 값을 사용하여 컨테이너를 정의합니다.
```
"containerDefinitions": [
{
"name": "container-1",
"mountPoints": [
{
"sourceVolume": "database",
"containerPath": "/var/database"
}
]
},
{
"name": "container-2",
"mountPoints": [
{
"sourceVolume": "database",
"containerPath": "/var/database"
}
]
}
]
```
**도커 볼륨을 사용하여 컨테이너에 NFS 영구 스토리지 제공**
이 예에서 컨테이너는 작업이 시작될 때 자동으로 탑재되고 작업이 중지될 때 탑재 해제되는 NFS 데이터 볼륨을 사용합니다. 도커 내장`local` 드라이버가 사용됩니다. 사용 사례 중 한 예로, ECS Anywhere 작업에서 해당 스토리지에 액세스해야 하는 경우가 있습니다. NFS 드라이버 옵션이 있는 도커 볼륨을 사용하면 이러한 작업을 수행할 수 있습니다.
1. 태스크 정의 `volumes` 섹션에서 `name` 및 `DockerVolumeConfiguration` 값을 사용하여 데이터 볼륨을 정의합니다. 이 예제에서는 작업이 중지된 후 볼륨이 탑재 해제되도록 `task` 범위를 지정합니다. `local` 드라이버를 사용하고 그에 따라 `type`, `device` 및 `o` 옵션으로 `driverOpts`를 구성합니다. `NFS_SERVER`를 NFS 서버 엔드포인트로 바꿉니다.
```
"volumes": [
{
"name": "NFS",
"dockerVolumeConfiguration" : {
"scope": "task",
"driver": "local",
"driverOpts": {
"type": "nfs",
"device": "$NFS_SERVER:/mnt/nfs",
"o": "addr=$NFS_SERVER"
}
}
}
]
```
1. `containerDefinitions` 섹션에서 정의된 볼륨 이름과 컨테이너에서 볼륨을 탑재할 `mountPoints` 값을 참조하는 `containerPath` 값을 사용하여 컨테이너를 정의합니다.
```
"containerDefinitions": [
{
"name": "container-1",
"mountPoints": [
{
"sourceVolume": "NFS",
"containerPath": "/var/nfsmount"
}
]
}
]
```
# Amazon ECS에서 바인드 탑재 사용
바인드 탑재로 호스트의 파일 또는 디렉터리(예: Amazon EC2 인스턴스)가 컨테이너에 탑재됩니다. 바인드 탑재는 Fargate와 Amazon EC2 인스턴스 모두에서 호스팅되는 태스크에 지원됩니다. 바인드 탑재는 이를 사용하는 컨테이너의 수명 주기에 연결됩니다. 바인드 탑재를 사용하는 모든 컨테이너가 중지되면(예: 태스크가 중지될 때) 데이터가 제거됩니다. Amazon EC2 인스턴스에서 호스팅되는 작업의 경우 작업 정의에 `host` 및 `sourcePath` 값(선택 사항)을 지정하여 호스트 Amazon EC2 인스턴스의 수명 주기에 데이터를 연결할 수 있습니다. 자세한 내용은 Docker 설명서에서 [바인드 탑재](https://docs.docker.com/engine/storage/bind-mounts/)를 참조하세요.
바인드 탑재의 일반 사용 사례는 다음과 같습니다.
+ 하나 이상의 컨테이너에 마운트할 빈 데이터 볼륨을 제공합니다.
+ 하나 이상의 컨테이너에 호스트 데이터 볼륨을 마운트합니다.
+ 동일한 태스크의 다른 컨테이너에 소스 컨테이너의 데이터 볼륨을 공유합니다.
+ Dockerfile의 경로와 콘텐츠를 하나 이상의 컨테이너에 노출합니다.
## 바인드 탑재 사용 시 고려 사항
바인드 탑재를 사용할 때는 다음 사항을 고려해야 합니다.
+ 플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0` 이상(Windows)을 사용하여 AWS Fargate에 호스팅되는 작업의 경우 기본적으로 바인드 탑재를 위해 최소 20GiB 이상의 임시 스토리지를 수신합니다. 임시 스토리지의 총량은 작업 정의에 `ephemeralStorage` 파라미터를 지정하여 최대 200GiB까지 늘릴 수 있습니다.
+ 태스크가 실행될 때 Dockerfile에서 데이터 볼륨으로 파일을 노출하기 위해 Amazon ECS 데이터 영역은 `VOLUME` 명령을 찾습니다. `VOLUME` 명령에 지정된 절대 경로가 태스크 정의에 지정된 `containerPath`와 동일한 경우 `VOLUME` 명령 경로의 데이터가 데이터 볼륨에 복사됩니다. 다음 Dockerfile 예제에서 `/var/log/exported` 디렉터리에 있는 `examplefile`이라는 파일이 호스트에 기록된 다음 컨테이너 내부에 마운트됩니다.
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN mkdir -p /var/log/exported
RUN touch /var/log/exported/examplefile
VOLUME ["/var/log/exported"]
```
기본적으로 볼륨 권한은 `0755`로 설정되고 소유자는 `root`로 설정됩니다. 이러한 권한은 Dockerfile에서 사용자 지정할 수 있습니다. 다음 예에서는 디렉터리의 소유자를 `node`로 정의합니다.
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN yum install -y shadow-utils && yum clean all
RUN useradd node
RUN mkdir -p /var/log/exported && chown node:node /var/log/exported
RUN touch /var/log/exported/examplefile
USER node
VOLUME ["/var/log/exported"]
```
+ Amazon EC2 인스턴스에서 호스팅되는 태스크의 경우 `host` 및 `sourcePath` 값이 지정되지 않으면 Docker 대몬이 바인드 탑재를 관리합니다. 컨테이너가 이 바인드 탑재를 참조하지 않으면, Amazon ECS 컨테이너 에이전트 태스크 정리 서비스가 결국 이를 삭제합니다. 기본적으로 이 작업은 컨테이너가 종료되고 3시간 후에 발생합니다. 하지만 이 기간을 `ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION` 에이전트 변수로 구성할 수 있습니다. 자세한 정보는 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md)을 참조하세요. 컨테이너의 수명 주기가 끝나더라도 이 데이터를 유지하려면 바인드 탑재에 `sourcePath` 값을 지정합니다.
+ Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크의 경우 루트 파일 시스템의 일부는 읽기 전용입니다. 읽기/쓰기 바인드 탑재는 영구 데이터를 위한 `/var` 또는 임시 데이터를 위한 `/tmp`와 같은 쓰기 가능한 디렉터리를 사용해야 합니다. 다른 디렉터리에 읽기/쓰기 바인드 탑재를 생성하려고 하면 다음과 유사한 오류와 함께 태스크 실행이 실패합니다.
```
error creating empty volume: error while creating volume path '/path': mkdir /path: read-only file system
```
읽기 전용 바인드 탑재(`mountPoints` 파라미터에서 `"readOnly": true`로 구성됨)는 호스트의 액세스 가능한 디렉터리 모두를 대상으로 지정할 수 있습니다.
쓰기 가능한 경로의 전체 목록을 확인하려면 Amazon ECS 관리형 인스턴스에서 태스크를 실행한 후 인스턴스의 탑재 테이블을 검사하면 됩니다. 호스트 파일 시스템에 액세스하려면 다음 설정을 사용하여 태스크 정의를 생성합니다.
```
{
"pidMode": "host",
"containerDefinitions": [{
"privileged": true,
...
}]
}
```
그런 다음 컨테이너 내부에서 다음 명령을 실행합니다.
```
# List writable mounts
cat /proc/1/root/proc/1/mounts | awk '$4 ~ /^rw,/ || $4 == "rw" {print $2}' | sort
# List read-only mounts
cat /proc/1/root/proc/1/mounts | awk '$4 ~ /^ro,/ || $4 == "ro" {print $2}' | sort
```
**중요**
`privileged` 설정은 컨테이너에 호스트에서의 루트 접근 권한과 동등한 확장된 권한을 부여합니다. 이 예제에서는 진단 목적으로 호스트의 탑재 테이블을 검사하는 데 사용됩니다. 자세한 내용은 [컨테이너를 privileged로 실행하지 않음(Amazon EC2)](security-tasks-containers.md#security-tasks-containers-recommendations-avoid-privileged-containers) 섹션을 참조하세요.
컨테이너에서 대화형으로 명령을 실행하는 방법에 대한 자세한 내용은 [ECS Exec를 사용하여 Amazon ECS 컨테이너 모니터링](ecs-exec.md) 섹션을 참조하세요.
# Amazon ECS 작업 정의에서 바인드 탑재 지정
Fargate 또는 Amazon EC2 인스턴스에 호스팅되는 Amazon ECS 작업의 경우 다음 작업 정의 JSON 코드 조각은 작업 정의에 대한 `volumes`, `mountPoints`, `ephemeralStorage` 객체 구문을 보여줍니다.
```
{
"family": "",
...
"containerDefinitions" : [
{
"mountPoints" : [
{
"containerPath" : "/path/to/mount_volume",
"sourceVolume" : "string"
}
],
"name" : "string"
}
],
...
"volumes" : [
{
"name" : "string"
}
],
"ephemeralStorage": {
"sizeInGiB": integer
}
}
```
Amazon EC2 인스턴스에서 호스팅되는 Amazon ECS 태스크의 경우, 태스크 볼륨 세부 정보를 지정할 때 `host` 파라미터 및 `sourcePath`를 선택 항목으로 사용할 수 있습니다. 지정된 경우, 바인드 탑재를 컨테이너가 아닌 태스크의 수명주기에 연결합니다.
```
"volumes" : [
{
"host" : {
"sourcePath" : "string"
},
"name" : "string"
}
]
```
다음은 각 태스크 정의 파라미터에 대해 자세한 설명입니다.
`name`
유형: 문자열
필수 여부: 아니요
볼륨의 이름입니다. 최대 255자의 문자(대문자 및 소문자), 숫자, 하이(`-`) 및 밑줄(`_`)이 허용됩니다. 이 이름은 컨테이너 정의 `mountPoints` 객체의 `sourceVolume` 파라미터에서 참조됩니다.
`host`
필수 여부: 아니요
`host` 파라미터는 바인드 탑재의 수명 주기를 태스크가 아니라 호스트 Amazon EC2 인스턴스와 연결하는 데 사용합니다. `host` 파라미터가 비어 있으면 Docker 대몬이 데이터 볼륨의 호스트 경로를 할당하지만 해당 볼륨과 연결된 컨테이너가 실행을 중지한 후 데이터 유지가 보장되지 않습니다.
Windows 컨테이너는 전체 디렉터리를 동일한 드라이브에 `$env:ProgramData`로 마운트할 수 있습니다.
`sourcePath` 파라미터는 Amazon EC2 인스턴스 또는 Amazon ECS 관리형 인스턴스에 호스팅된 태스크를 사용하는 경우에만 지원됩니다.
`sourcePath`
유형: 문자열
필수 여부: 아니요
`host` 파라미터가 사용되는 경우 `sourcePath`를 지정하여 컨테이너에 제시되는 호스트 Amazon EC2 인스턴스 상의 경로를 선언합니다. 이 파라미터가 비어 있으면 Docker 대몬이 사용자 대신 호스트 경로를 할당합니다. `host` 파라미터에 `sourcePath` 파일 위치가 들어 있으면, 사용자가 수동으로 삭제하지 않는 한 데이터 볼륨이 호스트 Amazon EC2 인스턴스 상에 지정된 위치를 유지합니다. `sourcePath` 값이 호스트 Amazon EC2 인스턴스에 없을 경우 Docker 대몬이 해당 경로를 생성합니다. 해당 위치가 있을 경우 소스 경로 폴더의 콘텐츠를 내보냅니다.
`mountPoints`
유형: 객체 배열
필수 여부: 아니요
컨테이너에서 데이터 볼륨의 탑재 지점입니다. 이 파라미터는 create-container Docker API의 `Volumes` 및 docker run에 대한 `--volume` 옵션에 매핑됩니다.
Windows 컨테이너는 전체 디렉터리를 동일한 드라이브에 `$env:ProgramData`로 마운트할 수 있습니다. Windows 컨테이너는 디렉터리를 다른 드라이브에 탑재할 수 없으며, 탑재 지점은 여러 드라이브에 걸쳐 사용할 수 없습니다. Amazon EBS 볼륨을 Amazon ECS 작업에 직접 연결하려면 탑재 지점을 지정해야 합니다.
`sourceVolume`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
탑재할 볼륨의 이름입니다.
`containerPath`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
볼륨을 탑재할 컨테이너의 경로입니다.
`readOnly`
유형: 부울
필수 여부: 아니요
이 값이 `true`일 경우 컨테이너에는 볼륨에 대한 읽기 전용 액세스가 부여됩니다. 이 값이 `false`일 경우 컨테이너는 볼륨에 쓸 수 있습니다. 기본값은 `false`입니다.
Windows 운영 체제를 실행하는 EC2 인스턴스에서 실행되는 태스크의 경우 값을 기본값인 `false`로 둡니다.
`ephemeralStorage`
유형: 객체
필수 여부: 아니요
태스크에 할당되는 임시 스토리지 용량(GB)입니다. 이 파라미터는 플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0` 이상(Windows)을 사용하는 AWS Fargate에서 호스팅되는 태스크에 대해 제공되는 임시 스토리지 총량을 기본 용량 이상으로 확장할 때 사용합니다.
Copilot CLI, CloudFormation,AWS SDK 또는 CLI를 사용하여 바인드 탑재에 대한 임시 스토리지를 지정할 수 있습니다.
# Amazon ECS에 대한 바인드 탑재 예제
다음 예제에서는 컨테이너에 바인드 탑재를 사용하는 일반적인 사용 사례를 다룹니다.
**Fargate 태스크를 위한 임시 스토리지 스페이스의 증가된 양을 할당하는 방법**
플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0` 이상(Windows)을 사용하여 Fargate에서 호스팅되는 Amazon ECS 태스크의 경우 태스크의 컨테이너에 사용할 임시 스토리지 공간의 기본 양 이상을 할당할 수 있습니다. 이 예제는 다른 예제에 포함하여 Fargate 태스크에 더 많은 임시 스토리지를 할당할 수 있습니다.
+ 태스크 정의에서 `ephemeralStorage` 객체를 정의합니다. `sizeInGiB`는 `21`과 `200` 값 사이의 정수여야 하며 GiB로 표현합니다.
```
"ephemeralStorage": {
"sizeInGiB": integer
}
```
**하나 이상의 컨테이너에 빈 데이터 볼륨을 제공하는 방법**
경우에 따라 태스크의 컨테이너에 스크래치 스페이스를 제공합니다. 예를 들어 태스크 도중 동일한 스크래치 파일 스토리지 위치에 액세스해야 하는 2개의 데이터베이스 컨테이너가 있을 수 있습니다. 이 태스크는 바인드 탑재를 사용하여 수행할 수 있습니다.
1. 태스크 정의 `volumes` 섹션에서 이름이 `database_scratch`인 바인드 탑재를 정의합니다.
```
"volumes": [
{
"name": "database_scratch"
}
]
```
1. `containerDefinitions` 섹션에서 데이터베이스 컨테이너 정의를 생성합니다. 이는 볼륨을 탑재하기 위함입니다.
```
"containerDefinitions": [
{
"name": "database1",
"image": "my-repo/database",
"cpu": 100,
"memory": 100,
"essential": true,
"mountPoints": [
{
"sourceVolume": "database_scratch",
"containerPath": "/var/scratch"
}
]
},
{
"name": "database2",
"image": "my-repo/database",
"cpu": 100,
"memory": 100,
"essential": true,
"mountPoints": [
{
"sourceVolume": "database_scratch",
"containerPath": "/var/scratch"
}
]
}
]
```
**Dockerfile의 경로와 콘텐츠를 컨테이너에 노출하는 방법**
이 예제에서는 컨테이너 내부에 탑재할 데이터를 쓰는 Dockerfile이 있습니다. 이 예제는 Fargate 또는 Amazon EC2 .인스턴스에서 호스팅되는 태스크에 적용됩니다.
1. Dockerfile을 생성합니다. 다음 예제에서는 퍼블릭 Amazon Linux 2 컨테이너 이미지를 사용하고 `/var/log/exported` 디렉토리에서 컨테이너 내부에 탑재하려는 `examplefile`이라는 파일을 생성합니다. `VOLUME` 명령은 절대 경로를 지정해야 합니다.
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN mkdir -p /var/log/exported
RUN touch /var/log/exported/examplefile
VOLUME ["/var/log/exported"]
```
기본적으로 볼륨 권한은 `0755`로 설정되고 소유자는 `root`로 설정됩니다. 이러한 권한은 Dockerfile에서 변경할 수 있습니다. 다음 예에서는 `/var/log/exported` 디렉터리의 소유자를 `node`로 정의합니다.
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN yum install -y shadow-utils && yum clean all
RUN useradd node
RUN mkdir -p /var/log/exported && chown node:node /var/log/exported
USER node
RUN touch /var/log/exported/examplefile
VOLUME ["/var/log/exported"]
```
1. 태스크 정의 `volumes` 섹션에서 이름이 `application_logs`인 볼륨을 정의합니다.
```
"volumes": [
{
"name": "application_logs"
}
]
```
1. `containerDefinitions` 섹션에서 애플리케이션 컨테이너 정의를 생성합니다. 이에 따라 스토리지를 탑재합니다. `containerPath` 값은 Dockerfile의 `VOLUME` 명령에서 지정한 절대 경로와 일치해야 합니다.
```
"containerDefinitions": [
{
"name": "application1",
"image": "my-repo/application",
"cpu": 100,
"memory": 100,
"essential": true,
"mountPoints": [
{
"sourceVolume": "application_logs",
"containerPath": "/var/log/exported"
}
]
},
{
"name": "application2",
"image": "my-repo/application",
"cpu": 100,
"memory": 100,
"essential": true,
"mountPoints": [
{
"sourceVolume": "application_logs",
"containerPath": "/var/log/exported"
}
]
}
]
```
**호스트 Amazon EC2 인스턴스의 수명 주기에 연결된 컨테이너에 빈 데이터 볼륨을 제공하는 방법**
Amazon EC2 인스턴스에서 호스팅되는 태스크의 경우 바인드 탑재를 사용하여 호스트 Amazon EC2 인스턴스의 수명 주기에 데이터를 연결할 수 있습니다. 이 태스크는 `host` 파라미터를 사용하고 `sourcePath` 값을 지정하여 수행할 수 있습니다. `sourcePath`에 있는 모든 파일의 `containerPath` 값이 컨테이너에 표시됩니다. `containerPath` 값으로 기록된 모든 파일은 호스트 Amazon EC2 인스턴스에서 `sourcePath` 값으로 기록됩니다.
**중요**
Amazon ECS는 Amazon EC2 인스턴스에 스토리지를 동기화하지 않습니다. 영구 스토리지를 사용하는 태스크는 클러스터에서 가용 용량이 있는 어떤 Amazon EC2 인스턴스에도 배치할 수 있습니다. 태스크 중단 및 재시작 후 영구 스토리지가 필요한 경우에는 항상 AWS CLI [start-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/start-task.html) 명령을 사용하여 태스크 시작 시 동일한 Amazon EC2 인스턴스를 지정합니다. 영구 스토리지용 Amazon EFS 볼륨을 사용할 수도 있습니다. 자세한 정보는 [Amazon ECS에서 Amazon EFS 볼륨 사용](efs-volumes.md) 섹션을 참조하세요.
1. 태스크 정의 `volumes` 섹션에서 `name` 및 `sourcePath` 값을 사용하여 바인드 탑재를 정의합니다. 다음 예에서 호스트 Amazon EC2 인스턴스에는 컨테이너 내부에 탑재하려는 `/ecs/webdata`의 데이터가 포함됩니다.
```
"volumes": [
{
"name": "webdata",
"host": {
"sourcePath": "/ecs/webdata"
}
}
]
```
1. `containerDefinitions` 섹션에서 바인드 탑재 이름과 컨테이너에서 바인드 탑재를 탑재할 `mountPoints` 값을 참조하는 `containerPath` 값을 사용하여 컨테이너를 정의합니다.
```
"containerDefinitions": [
{
"name": "web",
"image": "public.ecr.aws/docker/library/nginx:latest",
"cpu": 99,
"memory": 100,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"essential": true,
"mountPoints": [
{
"sourceVolume": "webdata",
"containerPath": "/usr/share/nginx/html"
}
]
}
]
```
**정의된 볼륨을 여러 위치에 있는 여러 컨테이너에 탑재하는 방법**
태스크 정의에서 데이터 볼륨을 정의하여 해당 볼륨을 여러 컨테이너의 여러 위치에 탑재할 수 있습니다. 예를 들어, 호스트 컨테이너의 `/data/webroot`에 웹 사이트 데이터 폴더가 있습니다. 문서 루트가 서로 다른 두 웹 서버에 해당 데이터 볼륨을 읽기 전용으로 탑재할 수 있습니다.
1. 태스크 정의 `volumes` 섹션에서 이름 `webroot` 및 소스 경로 `/data/webroot`를 사용하여 데이터 볼륨을 정의합니다.
```
"volumes": [
{
"name": "webroot",
"host": {
"sourcePath": "/data/webroot"
}
}
]
```
1. `containerDefinitions` 섹션에서 `mountPoints` 볼륨을 해당 컨테이너의 문서 루트를 가리키는 `webroot` 값과 연결하는 `containerPath` 값을 사용하여 각 웹 서버의 컨테이너를 정의합니다.
```
"containerDefinitions": [
{
"name": "web-server-1",
"image": "my-repo/ubuntu-apache",
"cpu": 100,
"memory": 100,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"essential": true,
"mountPoints": [
{
"sourceVolume": "webroot",
"containerPath": "/var/www/html",
"readOnly": true
}
]
},
{
"name": "web-server-2",
"image": "my-repo/sles11-apache",
"cpu": 100,
"memory": 100,
"portMappings": [
{
"containerPort": 8080,
"hostPort": 8080
}
],
"essential": true,
"mountPoints": [
{
"sourceVolume": "webroot",
"containerPath": "/srv/www/htdocs",
"readOnly": true
}
]
}
]
```
**`volumesFrom`을 사용하여 다른 컨테이너로부터 볼륨을 탑재하는 방법**
Amazon EC2 인스턴스에서 호스팅되는 태스크의 경우 컨테이너에 하나 이상의 볼륨을 정의한 후 다른 컨테이너 정의(동일한 태스크 내)의 `volumesFrom` 파라미터를 사용하여 원래 정의된 탑재 지점에서 `sourceContainer`로부터 모든 볼륨을 탑재할 수 있습니다. `volumesFrom` 파라미터는 태스크 정의에 정의된 볼륨과 Dockerfile을 사용하여 이미지에 내장된 볼륨에 적용됩니다.
1. (선택 사항) 이미지에 내장된 볼륨을 공유하려면 Dockerfile의 명령인 `VOLUME`을 사용합니다. 다음 예제 Dockerfile은 `httpd` 이미지를 사용한 후 볼륨을 추가하고 Apache 문서 루트에서 `dockerfile_volume`에 탑재합니다. 이 폴더는 `httpd` 웹 서버에서 사용하는 폴더입니다.
```
FROM httpd
VOLUME ["/usr/local/apache2/htdocs/dockerfile_volume"]
```
이 Dockerfile을 사용하여 이미지를 만들어 Docker Hub와 같은 리포지토리에 푸시한 후 태스크 정의에서 사용할 수 있습니다. 다음 단계에서 사용된 `my-repo/httpd_dockerfile_volume` 이미지 예제는 위의 Dockerfile을 사용하여 구축되었습니다.
1. 컨테이너에 다른 볼륨 및 탑재 지점을 정의하는 태스크 정의를 생성합니다. 이 예제 `volumes` 섹션에서는 `empty`라는 빈 볼륨을 생성하며, Docker 대몬이 이 볼륨을 관리합니다. `host_etc`라는 호스트 볼륨도 정의되어 있습니다. 호스트 컨테이너 인스턴스에서 `/etc` 폴더를 내보냅니다.
```
{
"family": "test-volumes-from",
"volumes": [
{
"name": "empty",
"host": {}
},
{
"name": "host_etc",
"host": {
"sourcePath": "/etc"
}
}
],
```
컨테이너 정의 섹션에서 앞서 정의한 볼륨을 탑재하는 컨테이너를 생성합니다. 이 예제에서 `web` 컨테이너는 `empty` 및 `host_etc` 볼륨을 탑재합니다. 이는 Dockerfile에서 볼륨으로 빌드된 이미지를 사용하는 컨테이너입니다.
```
"containerDefinitions": [
{
"name": "web",
"image": "my-repo/httpd_dockerfile_volume",
"cpu": 100,
"memory": 500,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"mountPoints": [
{
"sourceVolume": "empty",
"containerPath": "/usr/local/apache2/htdocs/empty_volume"
},
{
"sourceVolume": "host_etc",
"containerPath": "/usr/local/apache2/htdocs/host_etc"
}
],
"essential": true
},
```
`volumesFrom`을 사용하여 `web` 컨테이너와 연결된 모든 볼륨을 탑재하는 다른 컨테이너를 생성합니다. `web` 컨테이너에 있는 모든 볼륨도 마찬가지로 `busybox` 컨테이너에 탑재됩니다. 여기에는 `my-repo/httpd_dockerfile_volume` 이미지를 빌드하는 데 사용된 Dockerfile에 지정된 볼륨이 포함됩니다.
```
{
"name": "busybox",
"image": "busybox",
"volumesFrom": [
{
"sourceContainer": "web"
}
],
"cpu": 100,
"memory": 500,
"entryPoint": [
"sh",
"-c"
],
"command": [
"echo $(date) > /usr/local/apache2/htdocs/empty_volume/date && echo $(date) > /usr/local/apache2/htdocs/host_etc/date && echo $(date) > /usr/local/apache2/htdocs/dockerfile_volume/date"
],
"essential": false
}
]
}
```
이 태스크가 실행되면 두 컨테이너가 볼륨을 탑재하며, `busybox` 컨테이너의 `command`가 파일에 날짜 및 시간을 씁니다. 이 파일은 각 볼륨 폴더에서 `date`로 호출됩니다. 그러면 `web` 컨테이너가 표시하는 웹 사이트에 이 폴더가 표시됩니다.
**참고**
`busybox` 컨테이너는 빠른 명령을 실행한 후 종료하므로 컨테이너 정의에서 `"essential": false`를 설정해야 합니다. 그렇지 않으면 컨테이너 종료 후 전체 태스크가 중지됩니다.
# Amazon ECS에서 컨테이너 스왑 메모리 스페이스 관리
Amazon ECS를 사용하면 컨테이너 수준에서 Linux 기반 Amazon EC2 인스턴스의 스왑 메모리 스페이스 사용을 제어할 수 있습니다. 컨테이너별 스왑 구성을 사용하면 태스크 정의 내의 각 컨테이너에서 스왑을 사용 설정 또는 사용 중지할 수 있습니다. 이 기능을 사용 설정한 사용자의 경우, 사용되는 최대 스왑 스페이스를 제한할 수 있습니다. 예를 들어, 대기 시간이 중요한 컨테이너는 스왑을 사용 중지할 수 있습니다. 반면, 일시적인 메모리 요구가 높은 컨테이너는 스왑을 켜서 컨테이너가 로드될 때 메모리 부족 오류가 발생할 가능성을 줄일 수 있습니다.
컨테이너의 스왑 구성은 다음 컨테이너 정의 파라미터로 관리됩니다.
`maxSwap`
컨테이너가 사용할 수 있는 총 스왑 메모리 양(MiB) 이 파라미터는 docker run에 대한 `--memory-swap` 옵션으로 변환되며 컨테이너 메모리의 합계에 `maxSwap` 값을 더한 값이 됩니다.
`0`의 `maxSwap` 값이 지정되면 컨테이너는 스왑을 사용하지 않습니다. 허용되는 값은 `0` 또는 양수입니다. `maxSwap` 파라미터를 생략하면 컨테이너는 실행 중인 컨테이너 인스턴스에 대한 스왑 구성을 사용합니다. `swappiness` 매개 변수를 사용하려면 `maxSwap` 값을 설정해야 합니다.
`swappiness`
이를 통해 컨테이너의 메모리 스왑 동작을 조정할 수 있습니다. 필요한 경우가 아니면 `swappiness` 값이 `0`이 되어 스와핑이 발생하지 않도록 합니다. `100`의 `swappiness` 값은 페이지가 적극적으로 스와핑되도록 합니다. 허용되는 값은 `0`과 `100` 사이의 숫자입니다. `swappiness` 파라미터를 지정하지 않으면 `60`의 기본값이 사용됩니다. `maxSwap` 값이 지정되지 않은 경우 이 파라미터는 무시됩니다. 이 파라미터는 docker run에 대한 `--memory-swappiness` 옵션에 매핑됩니다.
다음 예에서는 JSON 구문이 제공됩니다.
```
"containerDefinitions": [{
...
"linuxParameters": {
"maxSwap": integer,
"swappiness": integer
},
...
}]
```
## 고려 사항
컨테이너별 스왑 구성을 사용하는 경우 다음을 고려하세요.
+ 컨테이너를 사용하려면 작업을 호스팅하는 Amazon EC2 인스턴스에서 스왑 스페이스를 사용 설정하고 할당해야 합니다. Amazon ECS에 최적화된 AMI에는 기본적으로 스왑이 사용 설정되어 있지 않습니다. 이 기능을 사용하려면 인스턴스에서 스왑을 활성화해야합니다. 자세한 내용은 *Amazon EC2 사용 설명서*의 [인스턴스 스토어 스왑 볼륨](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-store-swap-volumes.html) 또는 [Amazon EC2 인스턴스에서 스왑 스페이스로 작동하도록 메모리를 할당하려면 어떻게 해야 하나요?](https://repost.aws/knowledge-center/ec2-memory-swap-file)를 참조하세요.
+ 스왑 스페이스 컨테이너 정의 파라미터는 EC2를 지정하는 태스크 정의에 대해서만 지원됩니다. 이러한 파라미터는 Fargate의 Amazon ECS 사용 전용 작업 정의에는 지원되지 않습니다.
+ 이 기능은 Linux 컨테이너에서만 지원됩니다. 현재 Windows 컨테이너는 지원되지 않습니다.
+ 만약`maxSwap`과 `swappiness`컨테이너 정의 파라미터가 태스크 정의에서 생략되는 경우, 각 컨테이너는 `swappiness`의 기본값으로 `60`을 갖습니다. 또한 총 스왑 사용량은 컨테이너 메모리의 두 배로 제한됩니다.
+ Amazon Linux 2023에서 작업을 사용하는 경우에는 `swappiness` 파라미터가 지원되지 않습니다.
# Amazon ECS 관리형 인스턴스에 대한 Amazon ECS 태스크 정의 차이
Amazon ECS 관리형 인스턴스를 사용하려면 Amazon ECS 관리형 인스턴스 시작 유형을 사용하도록 태스크 정의를 구성해야 합니다. Amazon ECS 관리형 인스턴스를 사용할 경우 추가 고려 사항이 있습니다.
## 태스크 정의 파라미터
Amazon ECS 관리형 인스턴스를 사용하는 태스크는 사용 가능한 대부분의 Amazon ECS 태스크 정의 파라미터를 지원합니다. 그러나 일부 파라미터는 Amazon ECS 관리형 인스턴스 태스크와 함께 사용할 때 특정 동작 또는 제한 사항이 있습니다.
다음 태스크 정의 파라미터는 Amazon ECS 관리형 인스턴스 태스크에서 유효하지 않습니다.
+ `disableNetworking`
+ `dnsSearchDomains`
+ `dnsServers`
+ `dockerLabels`
+ `dockerSecurityOptions`
+ `dockerVolumeConfiguration`
+ `ephemeralStorage`
+ `extraHosts`
+ `fsxWindowsFileServerVolumeConfiguration`
+ `hostname`
+ `inferenceAccelerator`
+ `ipcMode`
+ `links`
+ `maxSwap`
+ `proxyConfiguration`
+ `sharedMemorySize`
+ `sourcepath` 볼륨
+ `swappiness`
+ `tmpfs`
다음 태스크 정의 파라미터는 Amazon ECS 관리형 인스턴스 태스크에서 유효하지만 유의해야 할 제한 사항이 있습니다.
+ `networkConfiguration` - Amazon ECS 관리형 인스턴스 태스크는 `awsvpc` 또는 `host` 네트워크 모드를 사용합니다.
+ `placementConstraints` - 다음 제약 조건 속성이 지원됩니다.
+ `ecs.subnet-id`
+ `ecs.availability-zone`
+ `ecs.instance-type`
+ `ecs.cpu-architecture`
+ `requiresCompatibilities` - 태스크 정의가 Amazon ECS 관리형 인스턴스와 호환되는지 확인하려면 `MANAGED_INSTANCES`를 포함해야 합니다.
+ `resourceRequirement` - `InferenceAccelerator`는 지원되지 않습니다.
+ `operatingSystemFamily` - Amazon ECS 관리형 인스턴스는 `LINUX`를 사용합니다.
+ `volumes` - `sourcePath`와 함께 바인드 탑재를 사용하는 경우 해당 경로는 호스트의 쓰기 가능한 디렉터리를 가리켜야 합니다. Amazon ECS 관리형 인스턴스 파일 시스템의 일부는 읽기 전용입니다. 쓰기 가능한 디렉터리에는 `/var` 및 `/tmp`가 포함됩니다. 자세한 내용은 [Amazon ECS에서 바인드 탑재 사용](bind-mounts.md) 섹션을 참조하세요.
Amazon ECS 관리형 인스턴스와 함께 사용하는 경우 태스크 정의를 검증하려면 태스크 정의를 등록할 때 다음을 지정할 수 있습니다.
+ AWS Management Console에서 **기능 필요** 필드에 `MANAGED_INSTANCES`를 지정합니다.
+ AWS CLI에서 `--requires-compatibilities` 옵션을 지정합니다.
+ Amazon ECS API에서 `requiresCompatibilities` 플래그를 지정합니다.
# Fargate에 대한 Amazon ECS 태스크 정의 차이
Fargate를 사용하려면 Fargate 시작 유형을 사용하도록 태스크 정의를 구성해야 합니다. Fargate를 사용할 때 추가 고려 사항이 있습니다.
## 태스크 정의 파라미터
Fargate를 사용하는 태스크는 사용 가능한 모든 Amazon ECS 태스크 정의 파라미터를 지원하지는 않습니다. 전혀 지원되지 않는 파라미터도 있고 Fargate 작업에 다르게 작동하는 파라미터도 있습니다.
다음 태스크 정의 파라미터는 Fargate 태스크에서 유효하지 않습니다.
+ `disableNetworking`
+ `dnsSearchDomains`
+ `dnsServers`
+ `dockerSecurityOptions`
+ `extraHosts`
+ `gpu`
+ `ipcMode`
+ `links`
+ `placementConstraints`
+ `privileged`
+ `maxSwap`
+ `swappiness`
다음 태스크 정의 파라미터는 Fargate 태스크에서 유효하지만 유의해야 할 제한이 있습니다.
+ `linuxParameters` – 컨테이너에 적용되는 Linux 전용 옵션을 지정할 때 `capabilities`에 추가할 수 있는 기능은 `CAP_SYS_PTRACE`뿐입니다. `devices`, `sharedMemorySize` 및 `tmpfs` 파라미터는 지원되지 않습니다. 자세한 내용은 [Linux 파라미터](task_definition_parameters.md#container_definition_linuxparameters) 섹션을 참조하세요.
+ `volumes` – Fargate 태스크는 바인드 탑재 호스트 볼륨만 지원하므로 `dockerVolumeConfiguration` 파라미터는 지원되지 않습니다. 자세한 내용은 [볼륨](task_definition_parameters.md#volumes) 섹션을 참조하세요.
+ `cpu` - AWS Fargate의 Windows 컨테이너의 경우 값은 1 vCPU보다 작을 수 없습니다.
+ `networkConfiguration` - Fargate 태스크에서는 항상 `awsvpc` 네트워크 모드가 사용됩니다.
태스크 정의가 Fargate으로 사용하는 데 유효한지 확인하려면 태스크 정의를 등록할 때 다음을 지정할 수 있습니다.
+ AWS Management Console에서 **기능 필요** 필드에 `FARGATE`를 지정합니다.
+ AWS CLI에서 `--requires-compatibilities` 옵션을 지정합니다.
+ Amazon ECS API에서 `requiresCompatibilities` 플래그를 지정합니다.
## 운영 체제 및 아키텍처
AWS Fargate에 대한 태스크 및 컨테이너 정의를 구성할 때 컨테이너가 실행하는 운영 체제를 지정해야 합니다. AWS Fargate에서 지원되는 운영 체제는 다음과 같습니다.
+ Amazon Linux 2
**참고**
Linux 컨테이너는 호스트 운영 체제의 커널 및 커널 구성만 사용합니다. 예를 들어 커널 구성에 `sysctl` 시스템 컨트롤이 포함됩니다. Linux 컨테이너 이미지는 모든 Linux 배포판의 파일 및 프로그램을 포함하는 기본 이미지로 만들 수 있습니다. CPU 아키텍처가 일치하면 모든 운영 체제의 모든 Linux 컨테이너 이미지에서 컨테이너를 실행할 수 있습니다.
+ Windows Server 2019 Full
+ Windows Server 2019 Core
+ Windows Server 2022 Full
+ Windows Server 2022 Core
AWS Fargate에서 Windows 컨테이너를 실행하는 경우 X86\$164 CPU 아키텍처가 있어야 합니다.
AWS Fargate에서 Linux 컨테이너를 실행할 때 X86\$164 CPU 아키텍처 또는 ARM 기반 애플리케이션용 ARM64 아키텍처를 사용할 수 있습니다. 자세한 내용은 [64비트 ARM 워크로드에 대한 Amazon ECS 작업 정의](ecs-arm64.md) 섹션을 참조하세요.
## 태스크 CPU 및 메모리
AWS Fargate용 Amazon ECS 태스크 정의를 사용하려면 태스크 수준에서 CPU와 메모리를 지정해야 합니다. 대부분의 사용 사례에서는 태스크 레벨에서 이러한 리소스를 지정해야 합니다. 유효한 태스크 레벨 CPU 및 메모리 조합은 아래 표와 같습니다. 작업 정의에서 메모리 값을 문자열(MiB 또는 GB 단위)로 지정할 수 있습니다. 예를 들어 메모리 값을 `3072`(MiB) 또는 `3 GB`(GB)로 지정할 수 있습니다. JSON 파일에서 CPU 값을 문자열(CPU 단위 또는 가상 CPU(vCPU))로 지정할 수 있습니다. 예를 들어 CPU 값을 `1024`(CPU 단위) 또는 `1 vCPU`(vCPU)로 지정할 수 있습니다.
| CPU 값 | 메모리 값 | AWS Fargate에 지원되는 운영 체제 |
| --- | --- | --- |
| 256(.25 vCPU) | 512MiB, 1GB, 2GB | Linux |
| 512(.5 vCPU) | 1GB, 2GB, 3GB, 4GB | Linux |
| 1024(1 vCPU) | 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB | Linux, Windows |
| 2048(2 vCPU) | 4\$116GB(1GB 증분) | Linux, Windows |
| 4096(4 vCPU) | 8\$130GB(1GB 증분) | Linux, Windows |
| 8192 (8 vCPU) 이 옵션은 Linux 플랫폼 `1.4.0` 이상이 필요합니다. | 16\$160GB(4GB 증분) | Linux |
| 16384 (16vCPU) 이 옵션은 Linux 플랫폼 `1.4.0` 이상이 필요합니다. | 32\$1120GB(8GB 증분) | Linux |
## 태스크 네트워킹
AWS Fargate용 Amazon ECS 태스크에는 탄력적 네트워크 인터페이스를 각 태스크에 제공하는 `awsvpc` 네트워크 모드가 필요합니다. 이 네트워크 모드를 사용하여 태스크를 실행하거나 서비스를 생성할 때는 네트워크 인터페이스를 연결할 하나 이상의 서브넷과 네트워크 인터페이스에 적용할 하나 이상의 보안 그룹을 지정해야 합니다.
퍼블릭 서브넷을 사용하는 경우에는 네트워크 인터페이스에 퍼블릭 IP 주소를 제공할지를 결정합니다. 퍼블릭 서브넷의 Fargate 태스크가 컨테이너 이미지를 풀링하려면 인터넷에 대한 경로 또는 인터넷으로 요청을 라우팅할 수 있는 NAT 게이트웨이를 사용하여 태스크의 탄력적 네트워크 인터페이스에 퍼블릭 IP 주소를 할당해야 합니다. 프라이빗 서브넷의 Fargate 태스크가 컨테이너 이미지를 풀링하려면 인터넷으로 요청을 라우팅할 수 있는 NAT 게이트웨이가 서브넷에 있어야 합니다. Amazon ECR에서 컨테이너 이미지를 호스팅하면 인터페이스 VPC 엔드포인트를 사용하도록 Amazon ECR을 구성할 수 있습니다. 이 경우 태스크의 프라이빗 IPv4 주소는 이미지 풀링에 사용됩니다. Amazon ECR 인터페이스 엔드포인트에 대한 자세한 정보는 *Amazon Elastic Container Registry 사용자 설명서*의 [Amazon ECR 인터페이스 VPC 엔드포인트(AWS PrivateLink)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/vpc-endpoints.html)를 참조하세요.
다음은 Fargate 서비스에 대한 `networkConfiguration` 섹션 예제입니다.
```
"networkConfiguration": {
"awsvpcConfiguration": {
"assignPublicIp": "ENABLED",
"securityGroups": [ "sg-12345678" ],
"subnets": [ "subnet-12345678" ]
}
}
```
## 태스크 리소스 제한
AWS Fargate의 Linux 컨테이너에 대한 Amazon ECS 태스크 정의는 `ulimits` 파라미터를 지원하여 컨테이너에 대해 설정할 리소스 제한을 정의합니다.
AWS Fargate의 Windows용 Amazon ECS 태스크 정의는 컨테이너에 대해 설정할 리소스 제한을 정의하는 `ulimits` 파라미터를 지원하지 않습니다.
Fargate에 호스팅되는 Amazon ECS 작업은 `nofile` 리소스 제한 파라미터를 제외하고 운영 체제에서 설정한 기본 리소스 제한 값을 사용합니다. `nofile` 리소스 제한은 컨테이너가 사용할 수 있는 열린 파일 수에 대한 제한을 설정합니다. Fargate에서 기본 `nofile` 소프트 제한은 ` 65535`이고 하드 제한은 `65535`입니다. 두 제한의 값을 모두 최대 `1048576`으로 설정할 수 있습니다.
두 배로 늘어난 사용자 지정 `nofile` 제한을 정의하는 방법을 나타내는 예제 태스크 정의 코드 조각은 다음과 같습니다.
```
"ulimits": [
{
"name": "nofile",
"softLimit": 2048,
"hardLimit": 8192
}
]
```
조정할 수 있는 다른 리소스 제한에 대한 자세한 정보는 [리소스 제한](task_definition_parameters.md#container_definition_limits) 섹션을 참조하세요.
## 로깅
### 이벤트 로깅
Amazon ECS는 수행한 작업을 EventBridge에 기록합니다. EventBridge용 Amazon ECS 이벤트를 사용하여 Amazon ECS 클러스터, 서비스 및 작업의 현재 상태에 관해 실시간에 가까운 알림을 받을 수 있습니다. 또한 이러한 이벤트에 응답하도록 작업을 자동화할 수 있습니다. 자세한 내용은 [EventBridge를 사용하여 Amazon ECS 오류에 대한 응답 자동화](cloudwatch_event_stream.md) 섹션을 참조하세요.
### 작업 수명 주기 로깅
Fargate에서 실행되는 작업은 타임스탬프를 게시하여 작업 수명 주기의 상태를 통해 작업을 추적합니다. AWS Management Console의 작업 세부 정보 및 AWS CLI 및 SDK의 작업 설명에서 타임스탬프를 확인할 수 있습니다. 예를 들어 타임스탬프를 사용하여 컨테이너 이미지를 다운로드하는 데 소요된 시간을 평가하고 컨테이너 이미지 크기를 최적화할지 아니면 Seekable OCI 인덱스를 사용할지 결정할 수 있습니다. 컨테이너 이미지 사례에 대한 자세한 내용은 [Amazon ECS 컨테이너 이미지 모범 사례](container-considerations.md)를 참조하세요.
### 애플리케이션 로깅
AWS Fargate용 Amazon ECS 태스크 정의는 로그 구성을 위해 `awslogs`, `splunk` 및 `awsfirelens` 로그 드라이버를 지원합니다.
`awslogs` 로그 드라이버는 Amazon CloudWatch Logs로 로그 정보를 보낼 Fargate 태스크를 구성합니다. 다음은 `awslogs` 로그 드라이버가 구성되는 태스크 정의 조각을 보여줍니다.
```
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group" : "/ecs/fargate-task-definition",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
}
```
태스크 정의에서 `awslogs` 로그 드라이버를 사용하여 컨테이너 로그를 CloudWatch Logs로 보내는 방법에 대한 자세한 정보는 [Amazon ECS 로그를 CloudWatch로 전송](using_awslogs.md) 섹션을 참조하세요.
태스크 정의의 `awsfirelens` 로그 드라이버에 대한 자세한 정보는 [Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송](using_firelens.md) 섹션을 참조하세요.
태스크 정의에서 `splunk` 로그 드라이버를 사용하는 방법에 대한 자세한 정보는 [`splunk` 로그 드라이버](example_task_definitions.md#example_task_definition-splunk) 섹션을 참조하세요.
## 태스크 스토리지
Fargate에서 호스팅되는 Amazon ECS 태스크의 경우 다음과 같은 스토리지 유형이 지원됩니다.
+ Amazon EBS 볼륨은 데이터 집약적인 컨테이너화된 워크로드에 대해 비용 효율적이며 내구성이 뛰어난 고성능 블록 스토리지를 제공합니다. 자세한 내용은 [Amazon ECS에서 Amazon EBS 볼륨 사용](ebs-volumes.md) 섹션을 참조하세요.
+ 영구 스토리지용 Amazon EFS 볼륨. 자세한 내용은 [Amazon ECS에서 Amazon EFS 볼륨 사용](efs-volumes.md) 섹션을 참조하세요.
+ 휘발성 스토리지용 바인드 마운트. 자세한 내용은 [Amazon ECS에서 바인드 탑재 사용](bind-mounts.md) 섹션을 참조하세요.
## Seekable OCI(SOCI)를 사용하여 컨테이너 이미지 지연 로딩
Linux 플랫폼 `1.4.0` 버전을 사용하는 Fargate 기반 Amazon ECS 작업은 Seekable OCI(SOCI)를 사용하여 작업을 더 빠르게 시작할 수 있습니다. SOCI를 사용하면 컨테이너가 이미지 풀에 몇 초만 소비하고 시작할 수 있으므로, 이미지가 백그라운드에서 다운로드되는 동안 환경 설정 및 애플리케이션 인스턴스화에 필요한 시간을 얻을 수 있습니다. 이를 지연 로딩이라고 합니다*.* Fargate가 Amazon ECS 작업을 시작하면 Fargate는 작업의 이미지에 대한 SOCI 인덱스가 있는지 자동으로 감지하여 전체 이미지가 다운로드될 때까지 기다리지 않고 컨테이너를 시작합니다.
SOCI 인덱스 없이 실행되는 컨테이너의 경우 컨테이너 이미지가 완전히 다운로드된 이후에 컨테이너가 시작됩니다. 이 동작은 Fargate의 다른 모든 플랫폼 버전과 Amazon EC2 인스턴스의 Amazon ECS 최적화 AMI에서 동일합니다.
Seekable OCI(SOCI)는 컨테이너 이미지를 느리게 로드하여 컨테이너를 더 빠르게 시작할 수 있는 AWS에서 개발된 오픈 소스 기술입니다. SOCI는 기존 컨테이너 이미지 내에 파일의 인덱스(SOCI 인덱스)를 생성하는 방식으로 작동합니다. 이 인덱스를 사용하면 전체 이미지를 다운로드하기 전에 컨테이너 이미지에서 개별 파일을 추출할 수 있으므로 컨테이너를 더 빠르게 시작할 수 있습니다. SOCI 인덱스는 컨테이너 레지스트리 내의 이미지와 동일한 리포지토리에 아티팩트로 저장되어야 합니다. 인덱스는 이미지 내용의 신뢰할 수 있는 출처이므로 신뢰할 수 있는 출처의 SOCI 인덱스만 사용해야 합니다. 자세한 내용은 [컨테이너 이미지 지연 로딩을 위한 Seekable OCI 소개](https://aws.amazon.com/about-aws/whats-new/2022/09/introducing-seekable-oci-lazy-loading-container-images/)를 참조하세요.
SOCI를 사용하려는 고객은 SOCI 인덱스 매니페스트 v2만 사용할 수 있습니다. 이전에 Fargate에서 SOCI를 사용한 기존 고객은 SOCI 인덱스 매니페스트 v1을 계속 사용할 수 있지만, SOCI 인덱스 매니페스트 v2로 마이그레이션하는 것이 좋습니다. SOCI 인덱스 매니페스트 v2는 컨테이너 이미지와 해당 SOCI 인덱스 간에 명시적 관계를 생성하여 일관된 배포를 보장합니다.
**고려 사항**
Fargate가 SOCI 인덱스를 사용하여 작업에서 컨테이너 이미지를 느리게 로드하도록 하려면 다음 사항을 고려합니다.
+ Linux 플랫폼 버전 `1.4.0`에서 실행되는 작업만 SOCI 인덱스를 사용할 수 있습니다. Fargate 기반 Windows 컨테이너를 실행하는 작업은 지원되지 않습니다.
+ X86\$164 또는 ARM64 CPU 아키텍처에서 실행되는 작업은 지원됩니다.
+ 작업 정의의 컨테이너 이미지는 호환 가능한 이미지 레지스트리에 저장되어야 합니다. 호환 가능한 레지스트리 목록은 다음과 같습니다.
+ Amazon ECR 프라이빗 레지스트리
+ gzip 압축을 사용하거나 압축되지 않은 컨테이너 이미지만 지원됩니다. zstd 압축을 사용하는 컨테이너 이미지는 지원되지 않습니다.
+ SOCI 인덱스 매니페스트 v2의 경우 SOCI 인덱스 매니페스트를 생성하면 SOCI 인덱스에 대한 주석을 추가할 때 컨테이너 이미지 매니페스트가 수정됩니다. 이를 통해 새 컨테이너 이미지 다이제스트가 생성됩니다. 컨테이너 이미지 파일 시스템 계층의 내용은 변경되지 않습니다.
+ SOCI 인덱스 매니페스트 v2의 경우 컨테이너 이미지가 컨테이너 이미지 리포지토리에 이미 저장된 경우 SOCI 인덱스가 생성된 후 컨테이너 이미지를 다시 푸시해야 합니다. 컨테이너 이미지를 다시 푸시하면 파일 시스템 계층을 복제하여 스토리지 비용이 증가하지 않고 새 매니페스트 파일만 업로드됩니다.
+ 250 MiB 압축된 크기보다 큰 컨테이너 이미지를 사용하여 지연 로딩을 시도하는 것이 좋습니다. 크기가 작은 이미지를 로드하는 데 걸리는 시간이 줄어들 가능성은 거의 없습니다.
+ 지연 로딩으로 인해 작업 시작 시간이 달라질 수 있으므로 Elastic Load Balancing의 상태 확인 유예 기간과 같은 다양한 제한 시간을 변경해야 할 수 있습니다.
+ 컨테이너 이미지가 지연 로드되지 않도록 하려면 SOCI 인덱스가 연결되지 않은 상태에서 컨테이너 이미지를 다시 푸시해야 합니다.
**Seekable OCI 인덱스 생성**
컨테이너 이미지 로드를 지연하려는 경우 SOCI 인덱스(메타데이터 파일)를 생성하여 컨테이너 이미지와 함께 컨테이너 이미지 리포지토리에 저장해야 합니다. SOCI 인덱스를 생성하고 푸시하기 위해 GitHub의 오픈 소스 [soci-snapshotter CLI 도구](https://github.com/awslabs/soci-snapshotter)를 사용할 수 있습니다. 또는 CloudFormation AWS SOCI Index Builder를 배포할 수 있습니다. 컨테이너 이미지가 Amazon ECR로 푸시될 때 SOCI 인덱스를 자동으로 생성하여 푸시하는 서버리스 솔루션입니다. 솔루션 및 설치 단계에 대한 자세한 내용은 GitHub의 [CFN AWS SOCI Index Builder](https://awslabs.github.io/cfn-ecr-aws-soci-index-builder/)를 참조하세요. CloudFormation AWS SOCI Index Builder는 SOCI 시작을 자동화하는 방법이며, 오픈 소스 soci 도구를 사용하면 인덱스 생성과 관련된 유연성이 향상되고 지속적 통합 및 지속적 배포(CI/CD) 파이프라인에 인덱스 생성을 통합할 수 있습니다.
**참고**
이미지에 대한 SOCI 인덱스를 생성하려면 `soci-snapshotter`를 실행 중인 컴퓨터의 containerd 이미지 저장소에 이미지가 있어야 합니다. 이미지가 Docker 이미지 저장소에 있는 경우 이미지를 찾을 수 없습니다.
**작업에서 지연 로딩을 사용했는지 확인**
SOCI를 사용하여 작업이 지연 로드되었는지 확인하려면 작업 내에서 작업 메타데이터 엔드포인트를 확인합니다. 작업 메타데이터 엔드포인트 버전 4를 쿼리하면 쿼리하는 컨테이너의 기본 경로에 `Snapshotter` 필드가 있습니다. 또한 `/task` 경로에 각 컨테이너에 대한 `Snapshotter` 필드가 있습니다. 이 필드의 기본값은 `overlayfs`이며, SOCI를 사용하는 경우 이 필드는 `soci`로 설정됩니다. 컨테이너 이미지에 SOCI 인덱스 매니페스트 v2가 연결되어 있는지 확인하려면 AWS CLI를 사용하여 Amazon ECR에서 이미지 인덱스를 검색하면 됩니다.
```
IMAGE_REPOSITORY=r
IMAGE_TAG=latest
aws ecr batch-get-image \
--repository-name=$IMAGE_REPOSITORY \
--image-ids imageTag=$IMAGE_TAG \
--query 'images[0].imageManifest' --output text | jq -r '.manifests[] | select(.artifactType=="application/vnd.amazon.soci.index.v2+json")'
```
컨테이너 이미지에 SOCI 인덱스 매니페스트 v1이 연결되어 있는지 확인하려면 OCI 참조 API를 사용하면 됩니다.
```
ACCOUNT_ID=111222333444
AWS_REGION=us-east-1
IMAGE_REPOSITORY=nginx-demo
IMAGE_TAG=latest
IMAGE_DIGEST=$(aws ecr describe-images --repository-name $IMAGE_REPOSITORY --image-ids imageTag=$IMAGE_TAG --query 'imageDetails[0].imageDigest' --output text)
ECR_PASSWORD=$(aws ecr get-login-password)
curl \
--silent \
--user AWS:$ECR_PASSWORD \
https://$ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/v2/$IMAGE_REPOSITORY/referrers/$IMAGE_DIGEST?artifactType=application%2Fvnd.amazon.soci.index.v1%2Bjson | jq -r '.'
```
# Windows를 실행하는 EC2 인스턴스에 대한 Amazon ECS 작업 정의 차이
EC2 Windows 인스턴스에서 실행되는 작업은 사용 가능한 모든 Amazon ECS 작업 정의 파라미터를 지원하지는 않습니다. 전혀 지원되지 않는 파라미터도 있고 일부는 다르게 작동합니다.
다음 작업 정의 파라미터는 Amazon EC2 Windows 작업 정의에서 지원되지 않습니다.
+ `containerDefinitions`
+ `disableNetworking`
+ `dnsServers`
+ `dnsSearchDomains`
+ `extraHosts`
+ `links`
+ `linuxParameters`
+ `privileged`
+ `readonlyRootFilesystem`
+ `user`
+ `ulimits`
+ `volumes`
+ `dockerVolumeConfiguration`
+ `cpu`
Windows 컨테이너에 대해서는 컨테이너 레벨 CPU를 지정할 것을 권장합니다.
+ `memory`
Windows 컨테이너에 대해서는 컨테이너 레벨 메모리를 지정할 것을 권장합니다.
+ `proxyConfiguration`
+ `ipcMode`
+ `pidMode`
+ `taskRoleArn`
EC2 Windows 인스턴스의 작업에 대한 IAM 역할에는 추가 구성이 필요하지만 이러한 구성의 대부분은 Linux 컨테이너 인스턴스에서의 작업에 대한 IAM 역할 구성과 비슷합니다. 자세한 내용은 [Amazon EC2 Windows 인스턴스 추가 구성](task-iam-roles.md#windows_task_IAM_roles)을 참조하세요.
# 콘솔을 사용하여 Amazon ECS 작업 정의 생성
태스크 또는 서비스로 실행하는 애플리케이션을 정의할 수 있도록 태스크 정의를 생성합니다.
외부 시작 유형에 대한 작업 정의를 생성할 때 JSON 편집기를 사용하여 태스크 정의를 생성하고 `requireCapabilities` 파라미터를 `EXTERNAL`로 설정해야 합니다.
콘솔 환경을 사용하거나 JSON 파일을 지정하여 태스크 정의를 생성할 수 있습니다. JSON 편집기를 사용할 경우 Amazon Q에서 권장 사항을 제공하도록 할 수 있습니다. 자세한 내용은 [Amazon Q Developer를 사용하여 Amazon ECS 콘솔에서 태스크 정의 권장 사항 제공](using-amazon-q.md) 섹션을 참조하세요.
## JSON 검사기
Amazon ECS 콘솔 JSON 편집기는 JSON 파일에서 다음 사항을 검사합니다.
+ 파일은 유효한 JSON 파일입니다.
+ 파일에 관련 없는 키는 없습니다.
+ 파일에 `familyName` 파라미터가 있습니다.
+ `containerDefinitions` 아래 하나 이상의 항목이 있습니다.
## CloudFormation 스택
다음 동작은 2023년 1월 12일 이전에 새 Amazon ECS 콘솔에서 생성된 작업 정의에 적용됩니다.
작업 정의를 생성하면 Amazon ECS 콘솔은 이름이 `ECS-Console-V2-TaskDefinition-`으로 시작하는 CloudFormation 스택을 자동으로 생성합니다. AWS CLI 또는 AWS SDK를 사용하여 작업 정의를 등록 취소한 경우 작업 정의 스택을 수동으로 삭제해야 합니다. 자세한 정보는 *CloudFormation 사용 설명서*의 [스택 삭제](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html)를 참조하세요.
2023년 1월 12일 이후에 생성된 작업 정의에서는 CloudFormation 스택이 자동으로 생성되지 않습니다.
## 절차
------
#### [ Amazon ECS console ]
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **작업 정의**를 선택합니다.
1. **새 작업 정의 생성** 메뉴에서 **새 작업 정의 생성**을 선택합니다.
1. **태스크 정의 패밀리(Task definition family)**에서 태스크 정의에 대해 고유한 이름을 지정합니다.
1. **시작 유형**에서 애플리케이션 환경을 선택합니다. 콘솔 기본값은 **AWS Fargate**(서버리스)입니다. Amazon ECS는 이 값으로 작업 정의 파라미터가 인프라 유형에 유효한지 검증을 수행합니다.
1. **운영 체제/아키텍처(Operating system/Architecture)**에서 태스크에 사용할 운영 체제와 CPU 아키텍처를 선택합니다.
64비트 ARM 아키텍처에서 작업을 실행하려면 **Linux/ARM64**를 선택합니다. 자세한 내용은 [런타임 플랫폼](task_definition_parameters.md#runtime-platform) 섹션을 참조하세요.
Windows 컨테이너에서 **AWS Fargate** 작업을 실행하려면 지원되는 Windows 운영 체제를 선택합니다. 자세한 내용은 [운영 체제 및 아키텍처](fargate-tasks-services.md#fargate-task-os) 섹션을 참조하세요.
1. **태스크 크기(Task size)**에서 태스크용으로 예약할 CPU 및 메모리 값을 선정합니다. CPU 값은 vCPU로 지정되고 메모리는 GB로 지정됩니다.
다음 표에서는 Fargate에서 호스팅되는 태스크에 대해 유효한 CPU와 메모리 조합을 보여줍니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/create-task-definition.html)
EC2 인스턴스 또는 외부 인스턴스를 사용하는 태스크의 경우 지원되는 태스크 CPU 값은 128 CPU 유닛(0.125 vCPU)에서 196,608 CPU 유닛(192 vCPU) 사이입니다.
메모리 값을 GB 단위로 지정하려면 값 뒤에 **GB**를 입력합니다. 예를 들어 **메모리 값**을 3GB로 설정하려면 **3GB**를 입력합니다.
**참고**
Windows 컨테이너에 대해서는 태스크 레벨 CPU와 메모리 파라미터가 무시됩니다.
1. **네트워크 모드(Network mode)**에서 사용할 네트워크 모드를 선택합니다. 기본값은 **awsvpc** 모드입니다. 자세한 내용은 [Amazon ECS 작업 배치](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html)를 참조하세요.
**브리지**를 선택하는 경우 **포트 매핑** 아래 **호스트 포트**에 컨테이너용으로 예약할 컨테이너 인스턴스의 포트 번호를 입력합니다.
1. (선택 사항) **작업 역할** 섹션을 확장하여 작업에 대한 AWS Identity and Access Management(IAM) 역할을 구성합니다.
1. **태스크 역할(Task role)**에서 태스크에 할당할 IAM 역할을 선택합니다. 작업 IAM 역할은 작업의 컨테이너에서 AWS API 작업을 직접 호출할 수 있는 권한을 제공합니다.
1. **작업 실행 역할**에서 역할을 선택합니다.
작업 실행 역할을 사용하는 경우에 대한 자세한 정보는 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md)을 참조하세요. 역할이 필요하지 않은 경우 **없음**을 선택합니다.
1. (선택 사항) **작업 배치** 섹션을 확장하여 배치 제약 조건을 추가합니다. 작업 배치 제약 조건으로 기본 제공 또는 사용자 지정 속성을 사용하여 작업 배치에 사용되는 컨테이너 인스턴스를 필터링할 수 있습니다.
1. (선택 사항) **결함 주입** 섹션을 확장하여 결함 주입을 활성화합니다. 결함 주입을 사용하면 애플리케이션이 특정 장애 시나리오에 어떻게 대응하는지 테스트할 수 있습니다.
1. 태스크 정의에서 정의할 각 컨테이너에 대해 다음 단계를 수행합니다.
1. **이름(Name)**에 컨테이너 이름을 입력합니다.
1. **이미지 URI(Image URI)**에서 컨테이너를 시작하는 데 사용할 이미지를 지정합니다. Amazon ECR 퍼블릭 갤러리 레지스트리의 이미지는 Amazon ECR 퍼블릭 레지스트리 이름만 사용하여 지정할 수 있습니다. 예를 들어 `public.ecr.aws/ecs/amazon-ecs-agent:latest`가 지정되면 Amazon ECR 퍼블릭 갤러리에 호스팅되는 Amazon Linux 컨테이너가 사용됩니다. 다른 모든 리포지토리의 경우 `repository-url/image:tag` 또는 `repository-url/image@digest` 형식을 사용하여 리포지토리를 지정합니다.
1. 이미지가 Amazon ECR 외부의 프라이빗 레지스트리에 있는 경우 **프라이빗 레지스트리**에서 **에서 프라이빗 레지스트리 인증**을 켭니다. 그런 다음 **Secrets Manager ARN 또는 이름**에 보안 암호의 Amazon 리소스 이름(ARN)을 입력합니다.
1. **필수 컨테이너**에서 작업 정의에 두 개 이상의 컨테이너가 정의되어 있으면 해당 컨테이너를 필수로 간주할지를 지정할 수 있습니다. 컨테이너가 **필수**로 표시된 경우 해당 컨테이너가 중지되면 작업도 중지됩니다. 각 태스크 정의에는 하나 이상의 필수 컨테이너가 포함되어야 합니다.
1. 포트 매핑을 통해 컨테이너는 호스트의 포트에 액세스하여 트래픽을 송수신할 수 있습니다. **포트 매핑(Port mappings)**에서 다음 중 하나를 수행합니다.
+ **awsvpc** 네트워크 모드를 사용하는 경우 **컨테이너 포트(Container port)**와 **프로토콜(Protocol)**에서 컨테이너에 사용할 포트 매핑을 선택합니다.
+ **bridge** 네트워크 모드를 사용하는 경우 **컨테이너 포트(Container port)**와 **프로토콜(Protocol)**에서 컨테이너에 사용할 포트 매핑을 선택합니다.
**포트 매핑 추가(Add more port mappings)**를 선택하여 추가 컨테이너 포트 매핑을 더 지정합니다.
1. 컨테이너에 루트 파일 시스템에 대한 읽기 전용 액세스를 부여하려면 **읽기 전용 루트 파일 시스템**에서 **읽기 전용**을 선택합니다.
1. (선택 사항) **리소스 할당 제한**의 작업 수준 값과 다른 컨테이너 수준 CPU, GPU 및 메모리 제한을 정의하려면 다음을 수행합니다.
+ **CPU**에 Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 CPU 단위 수를 입력합니다.
+ **GPU**에 컨테이너 인스턴스의 GPU 단위 수를 입력합니다.
GPU를 지원하는 Amazon EC2 인스턴스에는 GPU당 1개의 GPU 단위가 있습니다. 자세한 내용은 [GPU 워크로드에 대한 Amazon ECS 작업 정의](ecs-gpu.md) 섹션을 참조하세요.
+ **메모리 하드 제한**에 컨테이너에 표시할 메모리 크기를 GB 단위로 입력합니다. 컨테이너가 하드 제한 을 초과하려 하면 해당 컨테이너는 중지됩니다.
+ Docker 20.10.0 이상의 대몬은 컨테이너용으로 최소 6MiB의 메모리를 예약합니다. 그러므로 컨테이너에 대해 6MiB 미만의 메모리를 지정하지 마세요.
Docker 19.03.13-ce 이하의 대몬은 컨테이너용으로 최소 4MiB의 메모리를 예약합니다. 그러므로 컨테이너에 대해 4MiB 미만의 메모리를 지정하지 마세요.
+ **메모리 소프트 제한**에 컨테이너용으로 예약할 메모리의 소프트 제한(GB)을 입력합니다.
시스템 메모리가 경합하는 경우 Docker는 컨테이너 메모리를 이 소프트 제한으로 유지하려고 합니다. 작업 수준 메모리를 지정하지 않은 경우, **메모리 하드 제한** 및 **메모리 소프트 제한** 중 하나 또는 모두에 0이 아닌 정수를 지정해야 합니다. 둘 다 지정하는 경우 **메모리 하드 제한**은** 메모리 소프트 제한**보다 커야 합니다.
이 기능은 Windows 컨테이너에서 지원되지 않습니다.
1. (선택 사항)**환경 변수** 섹션을 확장하여 컨테이너에 삽입할 환경 변수를 지정합니다. 키-값 페어를 사용하여 개별적으로 환경 변수를 지정하거나 Amazon S3 버킷에서 호스팅되는 환경 변수 파일을 지정하여 배치 단위로 환경 변수를 지정할 수 있습니다. 환경 변수 파일의 형식을 지정하는 방법에 대한 자세한 내용은 [개별 환경 변수를 Amazon ECS 컨테이너로 전달](taskdef-envfiles.md) 섹션을 참조하세요.
비밀 스토리지에 대한 환경 변수를 지정할 때 **키**에 보안 암호 이름을 입력합니다. 그런 다음 **ValueFrom**에 Systems Manager Parameter Store 보안 암호 또는 Secrets Manager 보안 암호의 전체 ARN을 입력합니다.
1. (선택 사항) **로그 수집 사용(Use log collection)** 옵션을 선택하여 로그 구성을 지정합니다. 사용 가능한 로그 드라이버마다 지정할 로그 드라이버 옵션이 있습니다. 기본 옵션에서는 Amazon CloudWatch Logs로 컨테이너 로그를 전송합니다. 다른 로그 드라이버 옵션은 AWS FireLens를 사용하여 구성됩니다. 자세한 내용은 [Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송](using_firelens.md) 섹션을 참조하세요.
다음은 각 컨테이너 로그 대상에 대한 자세한 설명입니다.
+ **Amazon CloudWatch** - CloudWatch Logs로 컨테이너 로그를 전송하도록 작업을 구성합니다. 사용자를 대신하여 CloudWatch 로그 그룹을 생성하는 기본 로그 드라이버 옵션이 제공됩니다. 다른 로그 그룹 이름을 지정하려면 드라이버 옵션 값을 변경합니다.
+ **Splunk로 로그 내보내기** - 컨테이너 로그를 원격 서비스로 보내는 Splunk 드라이버로 전송하도록 작업을 구성합니다. Splunk 웹 서비스에 대한 URL을 입력해야 합니다. Splunk 토큰은 민감한 데이터로 취급될 수 있으므로 보안 암호 옵션으로 지정됩니다.
+ **Amazon Data Firehose로 로그 내보내기** - Firehose로 컨테이너 로그를 전송하도록 작업을 구성합니다. Firehose 전송 스트림으로 로그를 전송하는 기본 로그 드라이버 옵션이 제공됩니다. 다른 전송 스트림 이름을 지정하려면 드라이버 옵션 값을 변경합니다.
+ **Amazon Kinesis Data Streams로 로그 내보내기** - Kinesis Data Streams로 컨테이너 로그를 전송하도록 작업을 구성합니다. Kinesis Data Streams 스트림으로 로그를 전송하는 기본 로그 드라이버 옵션이 제공됩니다. 다른 스트림 이름을 지정하려면 드라이버 옵션 값을 변경합니다.
+ **Amazon OpenSearch Service로 로그 내보내기** - OpenSearch Service 도메인으로 컨테이너 로그를 전송하도록 작업을 구성합니다. 로그 드라이버 옵션이 제공되어야 합니다.
+ **Amazon S3로 로그 내보내기** - Amazon S3 버킷으로 컨테이너 로그를 전송하도록 작업을 구성합니다. 기본 로그 드라이버 옵션이 제공되지만 유효한 Amazon S3 버킷 이름을 지정해야 합니다.
1. (선택 사항) 추가 컨테이너 파라미터를 구성합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/create-task-definition.html)
1. (선택 사항) **컨테이너 추가(Add more containers)**를 선택하여 컨테이너를 태스크 정의에 더 추가합니다.
1. (선택 사항) **스토리지(Storage)** 섹션은 Fargate에 호스팅되는 작업에 대한 임시 스토리지 크기를 확장하는 데 사용됩니다. 이 섹션을 사용하여 작업에 대한 데이터 볼륨 구성을 추가할 수도 있습니다.
1. Fargate 태스크에 대한 20 gibibytes (GiB)의 기본값인 이상으로 사용 가능한 임시 스토리지를 확장하려면 **양(Amount)**에서 값을 최대 200 GiB으로 지정합니다.
1. (선택 사항) 작업 정의에 대한 데이터 볼륨 구성을 추가하려면 **볼륨 추가**를 선택하고 다음 단계를 수행합니다.
1. **볼륨 이름(Volume name)**에서 데이터 볼륨의 이름을 입력합니다. 데이터 볼륨 이름은 컨테이너 탑재 지점을 생성할 때 사용됩니다.
1. **볼륨 구성**의 경우 작업 정의를 생성할 때 볼륨을 구성할지 또는 배포 중에 볼륨을 구성할지 여부를 선택합니다.
**참고**
작업 정의를 생성할 때 구성할 수 있는 볼륨으로, 바인드 탑재, Docker, Amazon EFS 및 Amazon FSx for Windows File Server가 있습니다. 배포 시, 작업을 실행할 때 또는 서비스를 생성하거나 업데이트할 때 구성할 수 있는 볼륨으로, Amazon EBS가 있습니다.
1. **볼륨 유형**에서 선택한 구성 유형과 호환되는 볼륨 유형을 선택하고 볼륨 유형을 구성합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/create-task-definition.html)
1. 다른 컨테이너의 볼륨을 추가하려면 **다음 위치에서 볼륨 추가**를 선택하고 다음을 구성합니다.
+ **컨테이너**에서 컨테이너를 선택합니다.
+ **소스**에서 마운트하려는 볼륨이 있는 컨테이너를 선택합니다.
+ **읽기 전용**에서 컨테이너에 볼륨에 대한 읽기 전용 액세스가 부여되는지 선택합니다.
1. (선택 사항) AWS Distro for OpenTelemetry 통합을 사용하여 애플리케이션 추적 및 지표 수집 설정을 구성하려면 **모니터링**을 확장하고 **지표 수집 사용**을 선택하여 작업에 대한 지표를 수집하고 Amazon CloudWatch 또는 Amazon Managed Service for Prometheus로 전송합니다. 이 옵션을 선택하면 Amazon ECS는 애플리케이션 지표를 전송하도록 미리 구성된 AWS Distro for OpenTelemetry 컨테이너 사이드카를 생성합니다. 자세한 내용은 [애플리케이션 지표를 사용하여 Amazon ECS 애플리케이션 성능 상호 연관](metrics-data.md) 섹션을 참조하세요.
1. **Amazon CloudWatch**를 선택하면 사용자 정의 애플리케이션 지표가 CloudWatch에 사용자 정의 지표로 라우팅됩니다. 자세한 정보는 [Amazon CloudWatch로 애플리케이션 지표 내보내기](application-metrics-cloudwatch.md)을 참조하세요.
**중요**
Amazon CloudWatch로 애플리케이션 지표를 내보낼 때 필요한 권한이 있는 태스크 IAM 역할이 태스크 정의에 필요합니다. 자세한 정보는 [AWS Distro for OpenTelemetry와 Amazon CloudWatch 통합에 필요한 IAM 권한](application-metrics-cloudwatch.md#application-metrics-cloudwatch-iam)을 참조하세요.
1. **Amazon Managed Service for Prometheus(Prometheus 라이브러리 계측)(Amazon Managed Service for Prometheus (Prometheus libraries instrumentation))**를 선택하면 태스크 수준 CPU, 메모리, 네트워크 및 스토리지 지표와 사용자 정의 애플리케이션 지표가 Amazon Managed Service for Prometheus로 라우팅됩니다. **작업 스페이스 원격 쓰기 엔드포인트**에서 Prometheus 작업 영역에 대한 원격 쓰기 엔드포인트 URL을 입력합니다. **스크레이핑 대상**에서 AWS Distro for OpenTelemetry 수집기가 지표 데이터를 스크레이핑하는 데 사용할 수 있는 호스트와 포트를 입력합니다. 자세한 내용은 [Amazon Managed Service for Prometheus로 애플리케이션 지표 내보내기](application-metrics-prometheus.md) 섹션을 참조하세요.
**중요**
Amazon Managed Service for Prometheus로 애플리케이션 지표를 내보낼 때 필요한 권한이 있는 태스크 IAM 역할이 태스크 정의에 필요합니다. 자세한 내용은 [AWS Distro for OpenTelemetry와 Amazon Managed Service for Prometheus 통합에 필요한 IAM 권한](application-metrics-prometheus.md#application-metrics-prometheus-iam) 섹션을 참조하세요.
1. **Amazon Managed Service for Prometheus(OpenTelemetry 계측)**를 선택하면 작업 수준 CPU, 메모리, 네트워크 및 스토리지 지표와 사용자 정의 애플리케이션 지표가 Amazon Managed Service for Prometheus로 라우팅됩니다. **작업 스페이스 원격 쓰기 엔드포인트**에서 Prometheus 작업 영역에 대한 원격 쓰기 엔드포인트 URL을 입력합니다. 자세한 내용은 [Amazon Managed Service for Prometheus로 애플리케이션 지표 내보내기](application-metrics-prometheus.md) 섹션을 참조하세요.
**중요**
Amazon Managed Service for Prometheus로 애플리케이션 지표를 내보낼 때 필요한 권한이 있는 태스크 IAM 역할이 태스크 정의에 필요합니다. 자세한 정보는 [AWS Distro for OpenTelemetry와 Amazon Managed Service for Prometheus 통합에 필요한 IAM 권한](application-metrics-prometheus.md#application-metrics-prometheus-iam)을 참조하세요.
1. (선택 사항) **태그(Tags)** 섹션을 확장하여 태그를 키-값 페어로 태스크 정의에 추가합니다.
+ [태그 추가] **태그 추가**를 선택하고 다음을 수행합니다.
+ **키**에서 키 이름을 입력합니다.
+ **값**에 키 값을 입력합니다.
+ [태그 제거] 태그 옆에 있는 **태그 제거**를 선택합니다.
1. **생성**을 선택하여 작업 정의를 등록합니다.
------
#### [ Amazon ECS console JSON editor ]
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **작업 정의**를 선택합니다.
1. **새 작업 정의 생성** 메뉴에서 **JSON으로 새 작업 정의 생성**을 선택합니다.
1. JSON 편집기 상자에서 JSON 파일을 편집합니다.
JSON은 에 지정된 유효성 검사를 통과해야[JSON 검사기](#json-validate-for-create) 합니다.
1. **생성(Create)**을 선택합니다.
------
# Amazon Q Developer를 사용하여 Amazon ECS 콘솔에서 태스크 정의 권장 사항 제공
Amazon ECS 콘솔에서 JSON 편집기를 사용하여 태스크 정의를 생성할 때 Amazon Q Developer를 사용하여 태스크 정의에 대한 AI 생성 코드 제안을 제공할 수 있습니다.
인라인 채팅 기능을 사용하여 Amazon Q Developer에 대화형 인터페이스를 사용해 태스크 정의 JSON을 생성, 설명 또는 리팩터링하도록 요청할 수 있습니다. 태스크 정의의 어느 시점에서든 생성된 제안을 주입하고 제안된 변경 사항을 수락하거나 거부할 수 있습니다. 또한 Amazon ECS는 Amazon Q Developer를 활용하기 위해 기존 인라인 제안 기능도 개선했습니다.
JSON 편집기를 사용하여 태스크 정의를 생성할 때 Amazon Q Developer가 태스크 정의를 더 빠르게 생성하는 데 도움이 되는 권장 사항을 제공하도록 할 수 있습니다. 속성 기반 인라인 제안을 하거나 Amazon Q Developer 제안을 사용하여 샘플 코드의 전체 블록을 자동 완성할 수 있습니다.
Amazon Q Developer가 지원되는 리전에서 이 기능을 사용할 수 있습니다. 자세한 내용은 [AWS Services by Regions](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)를 참조하세요.
## 사전 조건
다음은 사전 조건입니다.
+ 콘솔 권한 외에도 콘솔에서 태스크 정의를 생성하는 사용자는 권장 사항에 대한 `codewhisperer:GenerateRecommendations` 권한과 인라인 채팅을 사용할 수 있는 `q:SendMessage`가 있어야 합니다. 자세한 내용은 [Amazon Q Developer를 사용하여 콘솔에서 권장 사항을 제공하는 데 필요한 권한](console-permissions.md#amazon-q-permission) 섹션을 참조하세요.
## 절차
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **작업 정의**를 선택합니다.
1. **새 작업 정의 생성** 메뉴에서 **JSON으로 새 작업 정의 생성**을 선택합니다.
**태스크 정의 생성** 페이지가 열립니다.
콘솔에서 다음과 같은 기본 템플릿을 제공합니다.
```
{
"requiresCompatibilities": [
"FARGATE"
],
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
"essential": true
}
],
"volumes": [],
"networkMode": "awsvpc",
"memory": "3 GB",
"cpu": "1 vCPU",
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
}
```
1. Amazon Q 인라인 제안 팝업에서 **허용**을 선택하세요.
팝업을 해제한 경우 톱니 아이콘에서 Amazon Q를 활성화할 수 있습니다.
1. JSON 편집기 상자에서 JSON 문서를 편집하세요.
Amazon Q가 파라미터를 생성하고 채우도록 하려면 추가하려는 내용이 포함된 설명을 입력하세요. 아래 예제에서 주석은 Amazon Q가 굵게 표시된 줄을 생성하도록 합니다.
```
{
"requiresCompatibilities": [
"FARGATE"
],
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
"essential": true
},
// add an nginx container using an image from Public ECR, with port 80 open, and send logs to CloudWatch log group "myproxy"
{
"name": "nginx",
"image": "public.ecr.aws/nginx/nginx:latest",
"essential": true,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80,
"protocol": "tcp"
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "myproxy",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "nginx"
}
}
}
],
"volumes": [],
"networkMode": "awsvpc",
"memory": "3 GB",
"cpu": "1 vCPU",
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
}
```
1. 인라인 채팅 기능을 사용하기 위해 줄을 강조 표시한 다음 별표 아이콘을 선택할 수 있습니다.
Amazon Q Developer 채팅 상자가 표시됩니다.
요청을 입력하세요.
Amazon Q Developer가 JSON을 생성한 다음 업데이트합니다.
변경 사항을 수락하려면 **모두 수락**을 선택하세요.
1. **생성(Create)**을 선택합니다.
# 콘솔을 사용하여 Amazon ECS 작업 정의 업데이트
*태스크 정의 개정*은 새 파라미터 값이 기존 파라미터 값을 대체하는 현재 태스크 정의의 복사본입니다. 수정하지 않는 모든 파라미터는 새 개정에 있습니다.
태스크 정의를 업데이트하려면 태스크 정의 개정을 생성합니다. 서비스에서 태스크 정의가 사용되는 경우 업데이트된 태스크 정의를 사용하도록 서비스를 업데이트해야 합니다.
개정을 생성할 때 다음 컨테이너 속성과 환경 속성을 수정할 수 있습니다.
+ 컨테이너 이미지 URI
+ 포트 매핑
+ 환경 변수
+ 인프라 요구 사항
+ 태스크 크기
+ 컨테이너 크기
+ 태스크 역할
+ 태스크 실행 역할
+ 볼륨 및 컨테이너 탑재 포인트
+ 프라이빗 레지스트리
JSON 편집기를 사용할 경우 Amazon Q에서 권장 사항을 제공하도록 할 수 있습니다. 자세한 내용은 [Amazon Q Developer를 사용하여 Amazon ECS 콘솔에서 태스크 정의 권장 사항 제공](using-amazon-q.md) 섹션을 참조하세요.
## JSON 검사기
Amazon ECS 콘솔 JSON 편집기는 JSON 파일에서 다음 사항을 검사합니다.
+ 파일은 유효한 JSON 파일입니다.
+ 파일에 관련 없는 키가 없습니다.
+ 파일에 `familyName` 파라미터가 있습니다.
+ `containerDefinitions`에 하나 이상의 항목이 있습니다.
## 절차
------
#### [ Amazon ECS console ]
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 모음에서 태스크 정의가 들어 있는 리전을 선택합니다.
1. 탐색 창에서 **태스크 정의**를 선택합니다.
1. 작업 정의를 선택합니다.
1. 태스크 정의 개정을 선택한 다음 **새 개정 생성**, **새 개정 생성**을 선택합니다.
1. **새 태스크 정의 개정 생성(Create new task definition revision)** 페이지에서 변경합니다. 예를 들어 기존 컨테이너 정의(컨테이너 이미지, 메모리 한계 또는 포트 매핑 등)를 변경하려면 컨테이너를 선택하고 변경합니다. 태스크 정의 호환성을 **AWS Fargate**, **관리형 인스턴스**, **Amazon EC2 인스턴스** 중 하나로 업데이트할 수 있습니다.
1. 정보를 확인하고 **업데이트**를 선택합니다.
1. 만약 태스크 정의가 서비스에서 사용되는 경우, 업데이트된 태스크 정의 서비스를 업데이트합니다. 자세한 내용은 [Amazon ECS 서비스 업데이트](update-service-console-v2.md) 섹션을 참조하세요.
------
#### [ Amazon ECS console JSON editor ]
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **작업 정의**를 선택합니다.
1. **새 개정 생성(Create new revision)**, **JSON으로 새 개정 생성(Create new revision with JSON)**을 선택합니다.
1. JSON 편집기 상자에서 JSON 파일을 편집합니다.
JSON은 에 지정된 유효성 검사를 통과해야[JSON 검사기](#json-validate-for-update) 합니다.
1. **생성(Create)**을 선택합니다.
------
# 콘솔을 사용하여 Amazon ECS 작업 정의 개정 등록 취소
작업을 실행하거나 서비스를 업데이트할 때 `ListTaskDefinition` API 호출 또는 콘솔에 더 이상 표시되지 않도록 태스크 정의 개정을 등록 취소할 수 있습니다.
태스크 정의 개정을 등록 취소하면 즉시 `INACTIVE`로 표시됩니다. `INACTIVE` 태스크 정의 개정을 참조하는 기존 태스크 및 서비스는 중단 없이 계속 실행됩니다. `INACTIVE` 태스크 정의 개정을 참조하는 기존 서비스는 서비스의 원하는 개수를 수정하여 확장하거나 수정할 수 있습니다.
`INACTIVE` 태스크 정의 개정을 사용하여 새 태스크를 실행하거나 새 서비스를 생성할 수 없습니다. 또한 `INACTIVE` 태스크 정의 개정을 참조하도록 기존 서비스를 업데이트할 수 없습니다(이러한 제한이 적용되기까지 등록 취소 후 최대 10분의 유예 기간이 있을 수 있음).
**참고**
작업 패밀리에서 모든 개정의 등록을 취소하면 작업 정의 패밀리가 `INACTIVE` 목록으로 이동합니다. `INACTIVE` 태스크 정의의 새로운 개정을 추가하면 태스크 정의 패밀리가 `ACTIVE` 리스트로 다시 돌아갑니다.
현재, `INACTIVE` 태스크 정의 개정은 계정에서 무기한 검색 가능한 상태로 유지됩니다. 그러나 이 동작은 향후 변경될 수 있습니다. 따라서 관련 태스크 및 서비스의 수명 주기 이상으로 지속되는 `INACTIVE` 태스크 정의 수정 버전에 의존해서는 안 됩니다.
## CloudFormation 스택
다음 동작은 2023년 1월 12일 이전에 새 Amazon ECS 콘솔에서 생성된 작업 정의에 적용됩니다.
작업 정의를 생성하면 Amazon ECS 콘솔은 이름이 `ECS-Console-V2-TaskDefinition-`으로 시작하는 CloudFormation 스택을 자동으로 생성합니다. AWS CLI 또는 AWS SDK를 사용하여 작업 정의를 등록 취소한 경우 작업 정의 스택을 수동으로 삭제해야 합니다. 자세한 정보는 *CloudFormation 사용 설명서*의 [스택 삭제](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html)를 참조하세요.
2023년 1월 12일 이후에 생성된 작업 정의에서는 CloudFormation 스택이 자동으로 생성되지 않습니다.
## 절차
**새 작업 정의 등록 취소 방법(Amazon ECS 콘솔)**
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 모음에서 태스크 정의가 들어 있는 리전을 선택합니다.
1. 탐색 창에서 **태스크 정의**를 선택합니다.
1. **Task definitions**(작업 정의) 페이지에서 등록 취소하려는 하나 이상의 개정을 포함하는 작업 정의 패밀리를 선택합니다.
1. **작업 정의 이름** 페이지에서 삭제할 수정 사항을 선택한 다음 **작업**, **등록 취소**를 선택합니다.
1. **등록 취소(Deregister)** 창에서 정보를 확인하고 **등록 취소(Deregister)**를 선택하여 완료합니다.
# 콘솔을 사용하여 Amazon ECS 작업 정의 개정 삭제
Amazon ECS에서 특정 작업 정의 개정이 더 이상 필요하지 않은 경우 작업 정의 개정을 삭제할 수 있습니다.
작업 정의 개정판을 삭제하면 즉시 `INACTIVE`에서 `DELETE_IN_PROGRESS`로 전환됩니다. `DELETE_IN_PROGRESS` 작업 정의 개정판을 참조하는 기존 작업 및 서비스는 중단 없이 계속 실행됩니다.
`DELETE_IN_PROGRESS` 작업 정의 개정판을 사용하여 새 작업을 실행하거나 새 서비스를 생성할 수 없습니다. 또한 `DELETE_IN_PROGRESS` 작업 정의 개정판을 참조하도록 기존 서비스를 업데이트할 수 없습니다.
모든 `INACTIVE` 작업 정의 개정을 삭제하면 작업 정의 이름이 콘솔에 표시되지 않고 API에도 반환되지 않습니다. 작업 정의 개정이 `DELETE_IN_PROGRESS` 상태인 경우 작업 정의 이름이 콘솔에 표시되고 API에서 반환됩니다. 작업 정의 이름은 Amazon ECS에서 유지되며 다음에 해당 이름으로 작업 정의를 생성하면 개정 번호가 증가합니다.
## 삭제를 차단할 수 있는 Amazon ECS 리소스
작업 정의 개정을 사용하는 Amazon ECS 리소스가 있는 경우 작업 정의 삭제 요청이 완료되지 않습니다. 다음 리소스는 작업 정의가 삭제되지 않도록 할 수 있습니다.
+ Amazon ECS 단독 작업 - 작업을 정상으로 유지하려면 작업 정의가 필요합니다.
+ Amazon ECS 서비스 작업 - 작업을 정상으로 유지하려면 작업 정의가 필요합니다.
+ Amazon ECS 서비스 배포 및 작업 세트 - Amazon ECS 배포 또는 작업 세트에 대한 조정 이벤트가 시작될 때 작업 정의가 필요합니다.
작업 정의가 `DELETE_IN_PROGRESS` 상태를 유지하는 경우 콘솔 또는 AWS CLI를 사용하여 작업 정의 삭제를 차단하는 리소스를 식별한 다음 중지할 수 있습니다.
### 차단된 리소스가 제거된 후 작업 정의 삭제
작업 정의 삭제를 차단하는 리소스를 제거하면 다음 규칙이 적용됩니다.
+ Amazon ECS 작업 - 작업이 중지된 후 작업 정의 삭제를 완료하는 데 최대 1시간이 걸릴 수 있습니다.
+ Amazon ECS 서비스 배포 및 작업 세트 - 배포 또는 작업 세트를 삭제한 후 작업 정의 삭제를 완료하는 데 최대 24시간이 걸릴 수 있습니다.
## 절차
**작업 정의를 등록 취소하는 방법(Amazon ECS 콘솔).**
작업 정의 개정판을 삭제하기 전에 작업 정의 개정판을 등록 취소해야 합니다. 자세한 내용은 [콘솔을 사용하여 Amazon ECS 작업 정의 개정 등록 취소](deregister-task-definition-v2.md) 섹션을 참조하세요.
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 모음에서 태스크 정의가 들어 있는 리전을 선택합니다.
1. 탐색 창에서 **태스크 정의**를 선택합니다.
1. **작업 정의** 페이지에서 삭제하려는 하나 이상의 개정판을 포함하는 작업 정의 패밀리를 선택합니다.
1. **작업 정의 이름** 페이지에서 삭제할 개정을 선택하고 **작업**, **삭제**를 선택합니다.
**삭제**를 사용할 수 없는 경우 작업 정의 등록을 취소해야 합니다.
1. **삭제** 확인 창에서 정보를 확인하고 **삭제**를 선택하여 완료합니다.
# Amazon ECS 작업 정의 사용 사례
다양한 AWS 서비스 및 기능에 대한 작업 정의를 작성하는 방법에 대해 자세히 알아봅니다.
워크로드에 따라 설정해야 하는 특정 작업 정의 파라미터가 있습니다. 또한 EC2의 경우 워크로드에 맞게 엔지니어링된 특정 인스턴스를 선택해야 합니다.
**Topics**
+ [GPU 워크로드에 대한 Amazon ECS 작업 정의](ecs-gpu.md)
+ [비디오 트랜스코딩 워크로드에 대한 Amazon ECS 태스크 정의](ecs-vt1.md)
+ [AWS Neuron 기계 학습 워크로드에 대한 Amazon ECS 작업 정의](ecs-inference.md)
+ [딥 러닝 인스턴스에 대한 Amazon ECS 작업 정의](ecs-dl1.md)
+ [64비트 ARM 워크로드에 대한 Amazon ECS 작업 정의](ecs-arm64.md)
+ [Amazon ECS 로그를 CloudWatch로 전송](using_awslogs.md)
+ [Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송](using_firelens.md)
+ [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md)
+ [컨테이너 재시작 정책이 있는 Amazon ECS 작업의 개별 컨테이너 재시작](container-restart-policy.md)
+ [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md)
# GPU 워크로드에 대한 Amazon ECS 작업 정의
GPU를 지원하는 컨테이너 인스턴스로 클러스터를 생성하는 경우 Amazon ECS는 GPU를 사용하는 워크로드를 지원합니다. p2, p3, p5, g3, g4 및 g5 인스턴스 유형을 사용하는 Amazon EC2 GPU 기반 컨테이너 인스턴스는 NVIDIA GPU에 대한 액세스를 제공합니다. 자세한 내용은 *Amazon EC2 인스턴스 유형 가이드*의 [Linux 가속 컴퓨팅 인스턴스](https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html)를 참조하세요.
Amazon ECS는 NVIDIA 커널 드라이버와 Docker GPU 실행 시간이 구성되어 있어 바로 사용할 수 있는 GPU 최적화 AMI를 제공합니다. 자세한 정보는 [Amazon ECS 최적화 Linux AMI](ecs-optimized_AMI.md)을 참조하세요.
컨테이너 수준에서 태스크 할당을 고려할 때 태스크 정의 내 GPU 개수를 지정할 수 있습니다. Amazon ECS는 GPU를 지원하는 사용 가능한 컨테이너 인스턴스로 예약하고 최적의 성능을 위해 물리적 GPU를 적절한 컨테이너에 고정합니다.
다음과 같은 Amazon EC2 GPU 기반 인스턴스 유형이 지원됩니다. 자세한 내용은 [Amazon EC2 P2 인스턴스](https://aws.amazon.com/ec2/instance-types/p2/), [Amazon EC2 P3 인스턴스](https://aws.amazon.com/ec2/instance-types/p3/), [Amazon EC2 P4d 인스턴스](https://aws.amazon.com/ec2/instance-types/p4/), [Amazon EC2 P5 인스턴스](https://aws.amazon.com/ec2/instance-types/p5/), [Amazon EC2 G3 인스턴스](https://aws.amazon.com/ec2/instance-types/g3/), [Amazon EC2 G4 인스턴스](https://aws.amazon.com/ec2/instance-types/g4/), [Amazon EC2 G5 인스턴스](https://aws.amazon.com/ec2/instance-types/g5/), [Amazon EC2 G6 인스턴스](https://aws.amazon.com/ec2/instance-types/g6/), [Amazon EC2 G6e 인스턴스](https://aws.amazon.com/ec2/instance-types/g6e/)를 참조하세요.
| 인스턴스 유형 | GPU | GPU 메모리(GiB) | vCPU | 메모리(GiB) |
| --- | --- | --- | --- | --- |
| p3.2xlarge | 1 | 16 | 8 | 61 |
| p3.8xlarge | 4 | 64 | 32 | 244 |
| p3.16xlarge | 8 | 128 | 64 | 488 |
| p3dn.24xlarge | 8 | 256 | 96 | 768 |
| p4d.24xlarge | 8 | 320 | 96 | 1152 |
| p5.48xlarge | 8 | 640 | 192 | 2048 |
| g3s.xlarge | 1 | 8 | 4 | 30.5 |
| g3.4xlarge | 1 | 8 | 16 | 122 |
| g3.8xlarge | 2 | 16 | 32 | 244 |
| g3.16xlarge | 4 | 32 | 64 | 488 |
| g4dn.xlarge | 1 | 16 | 4 | 16 |
| g4dn.2xlarge | 1 | 16 | 8 | 32 |
| g4dn.4xlarge | 1 | 16 | 16 | 64 |
| g4dn.8xlarge | 1 | 16 | 32 | 128 |
| g4dn.12xlarge | 4 | 64 | 48 | 192 |
| g4dn.16xlarge | 1 | 16 | 64 | 256 |
| g5.xlarge | 1 | 24 | 4 | 16 |
| g5.2xlarge | 1 | 24 | 8 | 32 |
| g5.4xlarge | 1 | 24 | 16 | 64 |
| g5.8xlarge | 1 | 24 | 32 | 128 |
| g5.16xlarge | 1 | 24 | 64 | 256 |
| g5.12xlarge | 4 | 96 | 48 | 192 |
| g5.24xlarge | 4 | 96 | 96 | 384 |
| g5.48xlarge | 8 | 192 | 192 | 768 |
| g6.xlarge | 1 | 24 | 4 | 16 |
| g6.2xlarge | 1 | 24 | 8 | 32 |
| g6.4xlarge | 1 | 24 | 16 | 64 |
| g6.8xlarge | 1 | 24 | 32 | 128 |
| g6.16.xlarge | 1 | 24 | 64 | 256 |
| g6.12xlarge | 4 | 96 | 48 | 192 |
| g6.24xlarge | 4 | 96 | 96 | 384 |
| g6.48xlarge | 8 | 192 | 192 | 768 |
| g6.metal | 8 | 192 | 192 | 768 |
| gr6.4xlarge | 1 | 24 | 16 | 128 |
| g6e.xlarge | 1 | 48 | 4 | 32 |
| g6e.2xlarge | 1 | 48 | 8 | 64 |
| g6e.4xlarge | 1 | 48 | 16 | 128 |
| g6e.8xlarge | 1 | 48 | 32 | 256 |
| g6e16.xlarge | 1 | 48 | 64 | 512 |
| g6e12.xlarge | 4 | 192 | 48 | 384 |
| g6e24.xlarge | 4 | 192 | 96 | 768 |
| g6e48.xlarge | 8 | 384 | 192 | 1536 |
| gr6.8xlarge | 1 | 24 | 32 | 256 |
AWS Systems Manager Parameter Store API를 쿼리하여 Amazon ECS 최적화 AMI의 Amazon Machine Image(AMI) ID를 검색할 수 있습니다. 이 파라미터를 사용하면 Amazon ECS 최적화 AMI ID를 수동으로 조회할 필요가 없습니다. Systems Manager 파라미터 스토어 API에 대한 자세한 내용은 [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html) 섹션을 참조하세요. Amazon ECS 최적화 AMI 메타데이터를 검색하려면 사용자에 `ssm:GetParameter` IAM 권한이 있어야 합니다.
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended --region us-east-1
```
# Amazon ECS 관리형 인스턴스에서 GPU 사용
Amazon ECS 관리형 인스턴스는 다음 Amazon EC2 인스턴스 유형을 통한 기계 학습, 고성능 컴퓨팅 및 비디오 처리와 같은 워크로드에 대해 GPU 가속 컴퓨팅을 지원합니다. Amazon ECS 관리형 인스턴스에서 지원하는 인스턴스 유형에 대한 자세한 내용은 [Amazon ECS 관리형 인스턴스의 인스턴스 유형](managed-instances-instance-types.md) 섹션을 참조하세요.
다음은 Amazon ECS 관리형 인스턴스에서 지원하는 GPU 기반 인스턴스 유형의 하위 세트입니다.
+ `g4dn`: NVIDIA T4 GPUs로 구동되며 기계 학습 추론, 컴퓨터 비전 및 그래픽 집약적인 애플리케이션에 적합합니다.
+ `g5`: NVIDIA A10G GPUs로 구동되며 그래픽 집약적인 애플리케이션 및 기계 학습 워크로드에 더 높은 성능을 제공합니다.
+ `p3`: NVIDIA V100 GPUs로 구동되며 고성능 컴퓨팅 및 딥 러닝 훈련을 위해 설계되었습니다.
+ `p4d`: NVIDIA A100 GPUs로 구동되며 기계 학습 훈련 및 고성능 컴퓨팅을 위한 최고의 성능을 제공합니다.
Amazon ECS 관리형 인스턴스에서 GPU 지원 인스턴스 유형을 사용하는 경우 NVIDIA 드라이버와 CUDA 툴킷은 인스턴스에 사전 설치되어 GPU 가속 워크로드를 더 쉽게 실행할 수 있습니다.
## GPU 지원 인스턴스 선택
Amazon ECS 관리형 인스턴스 워크로드에 대해 GPU 지원 인스턴스 유형을 선택하려면 용량 공급자의 시작 템플릿에 있는 `instanceRequirements` 객체를 사용합니다. 다음 코드 조각에서는 GPU 지원 인스턴스를 선택하는 데 사용할 수 있는 속성을 보여줍니다.
```
{
"instanceRequirements": {
"acceleratorTypes": "gpu",
"acceleratorCount": 1,
"acceleratorManufacturers": ["nvidia"]
}
}
```
다음 코드 조각에서는 시작 템플릿에서 GPU 지원 인스턴스 유형을 지정하는 데 사용할 수 있는 속성을 보여줍니다.
```
{
"instanceRequirements": {
"allowedInstanceTypes": ["g4dn.xlarge", "p4de.24xlarge"]
}
}
```
## GPU 지원 컨테이너 이미지
컨테이너에서 GPU를 사용하려면 필요한 GPU 라이브러리 및 도구가 포함된 컨테이너 이미지를 사용해야 합니다. NVIDIA는 다음을 포함하여 GPU 워크로드의 기반으로 사용할 수 있는 몇 가지 사전 빌드된 컨테이너 이미지를 제공합니다.
+ `nvidia:cuda`: GPU 컴퓨팅용 CUDA 툴킷이 포함된 기본 이미지.
+ `tensorflow/tensorflow:latest-gpu`: TensorFlow(GPU지원 포함).
+ `pytorch/pytorch:latest-cuda`: PyTorch(GPU지원 포함).
GPU 사용과 관련된 Amazon ECS 관리형 인스턴스의 Amazon ECS에 대한 태스크 정의 예제는 [Amazon ECS 작업 정의에서 GPU 지정](ecs-gpu-specifying.md) 섹션을 참조하세요.
## 고려 사항
**참고**
g2 인스턴스 패밀리 유형에 대한 지원은 더 이상 사용되지 않습니다.
p2 인스턴스 유형 패밀리는 `20230912` 이전 버전의 Amazon ECS GPU 최적화 AMI에서만 지원됩니다. p2 인스턴스를 계속 사용해야 하는 경우 [P2 인스턴스가 필요한 경우 수행할 작업](#p2-instance)를 참조하세요.
이 두 인스턴스 패밀리 유형에서 NVIDIA/CUDA 드라이버를 현재 위치 업데이트하면 잠재적인 GPU 워크로드 실패가 발생합니다.
Amazon ECS에서 GPU 작업을 시작하기 전에 다음 사항을 고려하는 것이 좋습니다.
+ 클러스터에 GPU와 비-GPU 컨테이너 인스턴스가 혼재되어 있을 수 있습니다.
+ 외부 인스턴스에서 GPU 워크로드를 실행할 수 있습니다. 클러스터에 외부 인스턴스를 등록할 때 `--enable-gpu` 플래그가 설치 스크립트에 포함되어 있는지 확인합니다. 자세한 정보는 [Amazon ECS 클러스터에 외부 인스턴스 등록](ecs-anywhere-registration.md)을 참조하세요.
+ 에이전트 구성 파일에서 `ECS_ENABLE_GPU_SUPPORT`를 `true`로 설정해야 합니다. 자세한 정보는 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md)을 참조하세요.
+ 태스크를 실행하거나 서비스를 생성할 경우 작업 배치 제약 조건을 구성할 때 인스턴스 유형 속성을 사용하여 태스크가 시작될 컨테이너 인스턴스를 결정할 수 있습니다. 이렇게 하면 리소스를 더욱 효과적으로 사용할 수 있습니다. 자세한 정보는 [Amazon ECS가 컨테이너 인스턴스에 작업을 배치하는 방법](task-placement.md) 섹션을 참조하세요.
다음 예제는 기본 클러스터의 `g4dn.xlarge` 컨테이너 인스턴스에서 태스크를 시작합니다.
```
aws ecs run-task --cluster default --task-definition ecs-gpu-task-def \
--placement-constraints type=memberOf,expression="attribute:ecs.instance-type == g4dn.xlarge" --region us-east-2
```
+ 컨테이너 정의에 지정된 GPU 리소스 요구 사항이 있는 각 컨테이너에 대해 Amazon ECS는 컨테이너 런타임을 NVIDIA 컨테이너 런타임으로 설정합니다.
+ NVIDIA 컨테이너 런타임이 제대로 작동하려면 컨테이너에 일부 환경 변수를 설정해야 합니다. 이러한 환경 변수 목록은 [Specialized Configurations with Docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html?highlight=environment%20variable)를 참조하세요. Amazon ECS는 Amazon ECS가 컨테이너에 할당하는 GPU 디바이스 ID의 목록이 될 `NVIDIA_VISIBLE_DEVICES` 환경 변수 값을 설정합니다. 다른 필수 환경 변수의 경우, Amazon ECS가 이러한 변수를 설정하지 않습니다. 따라서 컨테이너 이미지가 해당 변수를 설정하거나 컨테이너 정의에 설정되어 있어야 합니다.
+ p5 인스턴스 유형 패밀리는 `20230929` 이상 버전의 Amazon ECS GPU 최적화 AMI에서 지원됩니다.
+ g4 인스턴스 유형 패밀리는 `20230913` 이상 버전의 Amazon ECS GPU 최적화 AMI에서 지원됩니다. 자세한 내용은 [Amazon ECS 최적화 Linux AMI](ecs-optimized_AMI.md) 섹션을 참조하세요. Amazon ECS 콘솔의 클러스터 생성 워크플로에서는 지원되지 않습니다. 이러한 인스턴스 유형을 사용하려면 Amazon EC2 콘솔, AWS CLI 또는 API를 사용하고 클러스터에 인스턴스를 수동으로 등록해야 합니다.
+ p4d.24xlarge 인스턴스 유형은 CUDA 11 이상에서만 작동합니다.
+ Amazon ECS GPU 최적화 AMI는 IPv6가 활성화되어 있어서 `yum`을 사용할 때 문제가 발생합니다. 다음 명령으로 IPv4를 사용하도록 `yum`을 구성하면 문제가 해결됩니다.
```
echo "ip_resolve=4" >> /etc/yum.conf
```
+ NVIDIA/CUDA 기본 이미지를 사용하지 않는 컨테이너 이미지를 구축할 때는 `NVIDIA_DRIVER_CAPABILITIES` 컨테이너 런타임 변수를 다음 값 중 하나로 설정해야 합니다.
+ `utility,compute`
+ `all`
변수를 설정하는 방법에 대한 자세한 정보는 NVIDIA 웹사이트에서 [NVIDIA Container Runtime 제어](https://sarus.readthedocs.io/en/stable/user/custom-cuda-images.html#controlling-the-nvidia-container-runtime)를 참조하세요.
+ GPU는 Windows 컨테이너에서 지원되지 않습니다.
# Amazon ECS에 대한 GPU 컨테이너 인스턴스 시작
Amazon EC2 기반 Amazon ECS에서 GPU 인스턴스를 사용하려면 시작 템플릿과 사용자 데이터 파일을 생성하고 인스턴스를 시작해야 합니다.
그런 다음, GPU용으로 구성된 작업 정의를 사용하는 작업을 실행할 수 있습니다.
## 시작 템플릿 사용
시작 템플릿을 생성할 수 있습니다.
+ AMI에 대해 Amazon ECS 최적화 GPU AMI ID를 사용하는 시작 템플릿을 생성합니다. 시작 템플릿을 생성하는 방법에 대한 자세한 내용은 **Amazon EC2 사용 설명서의 [정의한 파라미터를 사용하여 새 시작 템플릿 생성](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-launch-template.html#create-launch-template-define-parameters)을 참조하세요.
**Amazon 머신 이미지**에 대해 이전 단계의 AMI ID를 사용합니다. Systems Manager 파라미터를 사용하여 AMI ID를 지정하는 방법에 대한 자세한 내용은 Amazon EC2 사용 설명서의 [시작 템플릿에 Systems Manager 파라미터 지정](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-launch-template.html#use-an-ssm-parameter-instead-of-an-ami-id)을 참조하세요.**
시작 템플릿의 **사용자 데이터**에 다음을 추가합니다. *cluster-name*을 해당 클러스터의 이름으로 바꿉니다.
```
#!/bin/bash
echo ECS_CLUSTER=cluster-name >> /etc/ecs/ecs.config;
echo ECS_ENABLE_GPU_SUPPORT=true >> /etc/ecs/ecs.config
```
## AWS CLI 사용
AWS CLI를 사용하여 컨테이너 인스턴스를 시작할 수 있습니다.
1. `userdata.toml`이라는 파일을 생성합니다. 이 파일은 인스턴스 사용자 데이터로 사용됩니다. *cluster-name*을 해당 클러스터의 이름으로 바꿉니다.
```
#!/bin/bash
echo ECS_CLUSTER=cluster-name >> /etc/ecs/ecs.config;
echo ECS_ENABLE_GPU_SUPPORT=true >> /etc/ecs/ecs.config
```
1. 다음 명령을 실행하여 GPU AMI ID를 가져옵니다. 다음 단계에서 이 정보를 사용합니다.
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended --region us-east-1
```
1. 다음 명령을 실행하여 GPU 인스턴스를 시작합니다. 다음 파라미터를 대체해야 합니다.
+ *subnet*을 인스턴스가 시작될 프라이빗 또는 퍼블릭 서브넷의 ID로 바꿉니다.
+ *gpu\$1ami*를 이전 단계의 AMI ID로 바꿉니다.
+ *t3.large*를 사용하려는 인스턴스 유형으로 바꿉니다.
+ *region*을 리전 코드로 바꿉니다.
```
aws ec2 run-instances --key-name ecs-gpu-example \
--subnet-id subnet \
--image-id gpu_ami \
--instance-type t3.large \
--region region \
--tag-specifications 'ResourceType=instance,Tags=[{Key=GPU,Value=example}]' \
--user-data file://userdata.toml \
--iam-instance-profile Name=ecsInstanceRole
```
1. 다음 명령을 실행하여 컨테이너 인스턴스가 클러스터에 등록되었는지 확인합니다. 이 명령을 실행할 때 다음 파라미터를 바꿔야 합니다.
+ *cluster*를 클러스터 이름으로 바꿉니다.
+ *region*을 리전 코드로 바꿉니다.
```
aws ecs list-container-instances --cluster cluster-name --region region
```
# Amazon ECS 작업 정의에서 GPU 지정
Docker GPU 실행 시간과 컨테이너 인스턴스의 GPU를 이용하려면 태스크 정의 시 컨테이너에 필요한 GPU 수를 지정해야 합니다. GPU를 지원하는 컨테이너가 배치되면 Amazon ECS 컨테이너 에이전트가 원하는 수의 물리적 GPU를 적절한 컨테이너에 고정합니다. 태스크의 모든 컨테이너에 예약된 GPU 수가 태스크가 실행되는 컨테이너 인스턴스에서 사용할 수 있는 GPU 수를 초과할 수 없습니다. 자세한 정보는 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md)을 참조하세요.
**중요**
태스크 정의 때 GPU 조건을 지정하지 않으면 해당 태스크에서 기본 Docker 실행 시간이 사용됩니다.
다음은 태스크 정의 시 GPU 조건의 JSON 형식입니다.
```
{
"containerDefinitions": [
{
...
"resourceRequirements" : [
{
"type" : "GPU",
"value" : "2"
}
],
},
...
}
```
다음 예제는 GPU 조건을 지정하는 Docker 컨테이너용 구문을 보여줍니다. 이 컨테이너는 GPU 2개를 사용하고, `nvidia-smi` 유틸리티를 실행한 후 종료합니다.
```
{
"containerDefinitions": [
{
"memory": 80,
"essential": true,
"name": "gpu",
"image": "nvidia/cuda:11.0.3-base",
"resourceRequirements": [
{
"type":"GPU",
"value": "2"
}
],
"command": [
"sh",
"-c",
"nvidia-smi"
],
"cpu": 100
}
],
"family": "example-ecs-gpu"
}
```
다음 태스크 정의 예제에서는 사용 가능한 GPU 수를 인쇄하는 TensorFlow 컨테이너를 보여줍니다. 태스크는 Amazon ECS 관리형 인스턴스에서 실행되고, 하나의 GPU가 필요하며, `g4dn.xlarge` 인스턴스를 사용합니다.
```
{
"family": "tensorflow-gpu",
"networkMode": "awsvpc",
"executionRoleArn": "arn:aws:iam::account-id:role/ecsTaskExecutionRole",
"containerDefinitions": [
{
"name": "tensorflow",
"image": "tensorflow/tensorflow:latest-gpu",
"essential": true,
"command": [
"python",
"-c",
"import tensorflow as tf; print('Num GPUs Available: ', len(tf.config.list_physical_devices('GPU')))"
],
"resourceRequirements": [
{
"type": "GPU",
"value": "1"
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/tensorflow-gpu",
"awslogs-region": "region",
"awslogs-stream-prefix": "ecs"
}
}
}
],
"requiresCompatibilities": [
"MANAGED_INSTANCES"
],
"cpu": "4096",
"memory": "8192",
}
```
## GPU 공유
GPU를 공유하려면 다음을 구성해야 합니다.
1. 공유되어야 하는 GPU를 Amazon ECS가 예약하지 않도록 태스크 정의에서 GPU 리소스 요구 사항을 제거합니다.
1. GPU를 공유하려면 다음과 같은 사용자 데이터를 인스턴스에 추가합니다. 이렇게 하면 nvidia가 컨테이너 인스턴스의 기본 Docker 컨테이너 런타임이 되므로 모든 Amazon ECS 컨테이너가 GPU를 사용할 수 있습니다. 자세한 내용은 *Amazon EC2 사용 설명서*의 [사용자 데이터 입력을 사용하여 EC2 인스턴스를 시작할 때 명령 실행](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html)을 참조하세요.
```
const userData = ec2.UserData.forLinux();
userData.addCommands(
'sudo rm /etc/sysconfig/docker',
'echo DAEMON_MAXFILES=1048576 | sudo tee -a /etc/sysconfig/docker',
'echo OPTIONS="--default-ulimit nofile=32768:65536 --default-runtime nvidia" | sudo tee -a /etc/sysconfig/docker',
'echo DAEMON_PIDFILE_TIMEOUT=10 | sudo tee -a /etc/sysconfig/docker',
'sudo systemctl restart docker',
);
```
1. 컨테이너에서 `NVIDIA_VISIBLE_DEVICES` 환경 변수를 설정합니다. 태스크 정의에서 환경 변수를 지정하면 됩니다. 유효한 값에 대한 자세한 내용은 NVIDIA 설명서 사이트의 [GPU Enumeration](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html#gpu-enumeration)을 참조하세요.
## P2 인스턴스가 필요한 경우 수행할 작업
P2 인스턴스를 사용해야 하는 경우 다음 옵션 중 하나를 사용하여 인스턴스를 계속 사용할 수 있습니다.
두 옵션 모두 인스턴스 사용자 데이터를 수정해야 합니다. 자세한 내용은 *Amazon EC2 사용 설명서*의 [사용자 데이터 입력을 사용하여 EC2 인스턴스를 시작할 때 명령 실행](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html)을 참조하세요.
**마지막으로 지원되는 GPU 최적화 AMI 사용**
GPU 최적화 AMI `20230906` 버전을 사용하고 인스턴스 사용자 데이터에 다음을 추가할 수 있습니다.
cluster-name을 해당 클러스터의 이름으로 바꿉니다.
```
#!/bin/bash
echo "exclude=*nvidia* *cuda*" >> /etc/yum.conf
echo "ECS_CLUSTER=cluster-name" >> /etc/ecs/ecs.config
```
**최신 GPU 최적화 AMI 사용 및 사용자 데이터 업데이트**
인스턴스 사용자 데이터에 다음을 추가할 수 있습니다. 이렇게 하면 Nvidia 535/Cuda12.2 드라이버가 제거되고 Nvidia 470/Cuda11.4 드라이버가 설치되고 버전이 수정됩니다.
```
#!/bin/bash
yum remove -y cuda-toolkit* nvidia-driver-latest-dkms*
tmpfile=$(mktemp)
cat >$tmpfile <
> /etc/yum.conf
nvidia-smi
```
**자체 P2 호환 GPU 최적화 AMI 생성**
P2 인스턴스와 호환되는 사용자 지정 Amazon ECS GPU 최적화 AMI를 생성한 다음 AMI를 사용하여 P2 인스턴스를 시작할 수 있습니다.
1. 다음 명령을 실행하여 `amazon-ecs-ami repo`를 복제합니다.
```
git clone https://github.com/aws/amazon-ecs-ami
```
1. `release.auto.pkrvars.hcl` 또는 `overrides.auto.pkrvars.hcl`에서 필요한 Amazon ECS 에이전트 및 소스 Amazon Linux AMI 버전을 설정합니다.
1. 다음 명령을 실행하여 프라이빗 P2 호환 EC2 AMI를 빌드합니다.
region을 인스턴스 리전이 리전으로 바꿉니다.
```
REGION=region make al2keplergpu
```
1. AMI에서 다음 인스턴스 사용자 데이터를 사용하여 Amazon ECS 클러스터에 연결합니다.
cluster-name을 해당 클러스터의 이름으로 바꿉니다.
```
#!/bin/bash
echo "ECS_CLUSTER=cluster-name" >> /etc/ecs/ecs.config
```
# 비디오 트랜스코딩 워크로드에 대한 Amazon ECS 태스크 정의
Amazon ECS에서 비디오 트랜스코딩 워크로드를 사용하려면 [Amazon EC2 VT1](https://aws.amazon.com/ec2/instance-types/vt1/) 인스턴스를 등록합니다. 이러한 인스턴스를 등록한 후, 라이브 및 사전 렌더링된 비디오 트랜스코딩 워크로드를 Amazon ECS에서 태스크로 실행할 수 있습니다. Amazon EC2 VT1 인스턴스는 Xilinx U30 미디어 트랜스코딩 카드를 사용하여 라이브 및 사전 렌더링된 비디오 트랜스코딩 워크로드 속도를 향상합니다.
**참고**
Amazon ECS가 아닌 컨테이너에서 비디오 트랜스코딩 워크로드를 실행하는 방법에 대한 지침은 [Xilinx 설명서](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#working-with-docker-vt1)를 참조하세요.
## 고려 사항
Amazon ECS에 VT1 배포를 시작하기 전에 다음에 주의하세요.
+ 클러스터에 VT1과 VT1이 아닌 인스턴스가 혼재되어 있을 수 있습니다.
+ 가속 AVC(H.264) 및 HEVC(H.265) 코덱으로 Xilinx U30 미디어 트랜스코딩 카드를 사용하는 Linux 애플리케이션이 필요합니다.
**중요**
다른 코덱을 사용하는 애플리케이션은 VT1 인스턴스에서 성능이 향상되지 않을 수 있습니다.
+ U30 카드에서 트랜스코딩 태스크는 하나만 실행할 수 있습니다. 각 카드에는 연결된 두 개의 디바이스가 있습니다. 각 VT1 인스턴스 카드만큼 트랜스코딩 태스크를 실행할 수 있습니다.
+ 서비스를 생성하거나 독립적 태스크를 실행할 경우 작업 배치 제약 조건을 구성할 때 인스턴스 유형 속성을 사용할 수 있습니다. 이렇게 하면 지정한 컨테이너 인스턴스에서 태스크가 시작됩니다. 또한, 리소스를 효과적으로 사용하고 비디오 트랜스코딩 워크로드에 대한 태스크가 VT1 인스턴스에 있는지 확인할 수 있습니다. 자세한 정보는 [Amazon ECS가 컨테이너 인스턴스에 작업을 배치하는 방법](task-placement.md)을 참조하세요.
다음의 예제에서는 `default` 클러스터에 있는 `vt1.3xlarge` 인스턴스에서 태스크를 실행합니다.
```
aws ecs run-task \
--cluster default \
--task-definition vt1-3xlarge-xffmpeg-processor \
--placement-constraints type=memberOf,expression="attribute:ecs.instance-type == vt1.3xlarge"
```
+ 호스트 컨테이너 인스턴스에서 특정 U30 카드를 사용하도록 컨테이너를 구성합니다. `linuxParameters` 파라미터 및 지정한 디바이스 세부 정보를 사용하여 이 작업을 수행할 수 있습니다. 자세한 정보는 [태스크 정의 요구 사항](#ecs-vt1-requirements)을 참조하세요.
## VT1 AMI 사용
Amazon ECS 컨테이너 인스턴스용 Amazon EC2에서 AMI를 실행하는 두 가지 옵션이 있습니다. 첫 번째 옵션은 AWS Marketplace에서 Xilinx 공식 AMI를 사용하는 것입니다. 두 번째 옵션은 샘플 저장소에서 자체 AMI를 빌드하는 것입니다.
+ [Xilinx는 AWS Marketplace에서 AMI를 제공합니다](https://aws.amazon.com/marketplace/pp/prodview-phvk6d4mq3hh6).
+ Amazon ECS는 비디오 트랜스코딩 워크로드에 대한 AMI를 빌드하는 데 사용할 수 있는 샘플 리포지토리를 제공합니다. 이 AMI는 Xilinx U30 드라이버와 함께 제공됩니다. [GitHub](https://github.com/aws-samples/aws-vt-baseami-pipeline)에서 Packer 스크립트가 포함된 리포지토리를 찾을 수 있습니다. Packer에 대한 자세한 정보는 [Packer 설명서](https://developer.hashicorp.com/packer/docs)를 참조하세요.
## 태스크 정의 요구 사항
Amazon ECS에서 비디오 트랜스코딩 컨테이너를 실행하려면, 태스크 정의에 가속화된 H.264/AVC 및 H.265/HEVC 코덱을 사용하는 비디오 트랜스코딩 애플리케이션이 포함되어야 합니다. 컨테이너 이미지를 빌드하려면 [Xilinx GitHub](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#creating-a-docker-image-for-vt1-usage)에서 다음 단계를 수행합니다.
태스크 정의는 인스턴스 유형에 고유해야 합니다. 인스턴스 유형은 3xlarge, 6xlarge 및 24xlarge입니다. 호스트 컨테이너 인스턴스에서 특정 Xilinx U30 디바이스를 사용하도록 컨테이너를 구성해야 합니다. `linuxParameters` 파라미터를 사용해 이 작업을 수행할 수 있습니다. 다음 표에는 각 인스턴스 유형에 해당하는 카드 및 디바이스 SoC가 자세히 나와 있습니다.
| 인스턴스 유형 | vCPU | RAM(GiB) | U30 액셀러레이터 카드 | 주소 지정 가능한 XCU30 SoC 디바이스 | 디바이스 경로 |
| --- | --- | --- | --- | --- | --- |
| vt1.3xlarge | 12 | 24 | 1 | 2 | /dev/dri/renderD128,/dev/dri/renderD129 |
| vt1.6xlarge | 24 | 48 | 2 | 4 | /dev/dri/renderD128,/dev/dri/renderD129,/dev/dri/renderD130,/dev/dri/renderD131 |
| vt1.24xlarge | 96 | 182 | 8 | 16 | /dev/dri/renderD128,/dev/dri/renderD129,/dev/dri/renderD130,/dev/dri/renderD131,/dev/dri/renderD132,/dev/dri/renderD133,/dev/dri/renderD134,/dev/dri/renderD135,/dev/dri/renderD136,/dev/dri/renderD137,/dev/dri/renderD138,/dev/dri/renderD139,/dev/dri/renderD140,/dev/dri/renderD141,/dev/dri/renderD142,/dev/dri/renderD143 |
**중요**
작업 정의에 EC2 인스턴스에 없는 디바이스가 나열되면 태스크가 실행되지 않습니다. 태스크가 실패하면 다음과 같이 오류 메시지가 표시됩니다. `stoppedReason`: `CannotStartContainerError: Error response from daemon: error gathering device information while adding custom device "/dev/dri/renderD130": no such file or directory`
# Amazon ECS 작업 정의에서 비디오 트랜스코딩 지정
다음 예에서는 Amazon EC2에서 Linux 컨테이너의 태스크 정의에 사용되는 구문이 제공됩니다. 이 태스크 정의는 [Xilinx 설명서](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#creating-a-docker-image-for-vt1-usage)에서 제공하는 절차에 따라 빌드된 컨테이너 이미지용입니다. 이 예제를 사용하는 경우, 자체 이미지를 사용하여 `image`를 대체하고 비디오 파일을 `/home/ec2-user` 디렉터리의 인스턴스로 복사합니다.
------
#### [ vt1.3xlarge ]
1. 다음 콘텐츠가 포함된 `vt1-3xlarge-ffmpeg-linux.json`이라는 텍스트 파일을 생성합니다.
```
{
"family": "vt1-3xlarge-xffmpeg-processor",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == vt1.3xlarge"
}
],
"containerDefinitions": [
{
"entryPoint": [
"/bin/bash",
"-c"
],
"command": ["/video/ecs_ffmpeg_wrapper.sh"],
"linuxParameters": {
"devices": [
{
"containerPath": "/dev/dri/renderD128",
"hostPath": "/dev/dri/renderD128",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD129",
"hostPath": "/dev/dri/renderD129",
"permissions": [
"read",
"write"
]
}
]
},
"mountPoints": [
{
"containerPath": "/video",
"sourceVolume": "video_file"
}
],
"cpu": 0,
"memory": 12000,
"image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
"essential": true,
"name": "xilinix-xffmpeg"
}
],
"volumes": [
{
"name": "video_file",
"host": {"sourcePath": "/home/ec2-user"}
}
]
}
```
1. 작업 정의를 등록합니다.
```
aws ecs register-task-definition --family vt1-3xlarge-xffmpeg-processor --cli-input-json file://vt1-3xlarge-xffmpeg-linux.json --region us-east-1
```
------
#### [ vt1.6xlarge ]
1. 다음 콘텐츠가 포함된 `vt1-6xlarge-ffmpeg-linux.json`이라는 텍스트 파일을 생성합니다.
```
{
"family": "vt1-6xlarge-xffmpeg-processor",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == vt1.6xlarge"
}
],
"containerDefinitions": [
{
"entryPoint": [
"/bin/bash",
"-c"
],
"command": ["/video/ecs_ffmpeg_wrapper.sh"],
"linuxParameters": {
"devices": [
{
"containerPath": "/dev/dri/renderD128",
"hostPath": "/dev/dri/renderD128",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD129",
"hostPath": "/dev/dri/renderD129",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD130",
"hostPath": "/dev/dri/renderD130",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD131",
"hostPath": "/dev/dri/renderD131",
"permissions": [
"read",
"write"
]
}
]
},
"mountPoints": [
{
"containerPath": "/video",
"sourceVolume": "video_file"
}
],
"cpu": 0,
"memory": 12000,
"image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
"essential": true,
"name": "xilinix-xffmpeg"
}
],
"volumes": [
{
"name": "video_file",
"host": {"sourcePath": "/home/ec2-user"}
}
]
}
```
1. 작업 정의를 등록합니다.
```
aws ecs register-task-definition --family vt1-6xlarge-xffmpeg-processor --cli-input-json file://vt1-6xlarge-xffmpeg-linux.json --region us-east-1
```
------
#### [ vt1.24xlarge ]
1. 다음 콘텐츠가 포함된 `vt1-24xlarge-ffmpeg-linux.json`이라는 텍스트 파일을 생성합니다.
```
{
"family": "vt1-24xlarge-xffmpeg-processor",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == vt1.24xlarge"
}
],
"containerDefinitions": [
{
"entryPoint": [
"/bin/bash",
"-c"
],
"command": ["/video/ecs_ffmpeg_wrapper.sh"],
"linuxParameters": {
"devices": [
{
"containerPath": "/dev/dri/renderD128",
"hostPath": "/dev/dri/renderD128",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD129",
"hostPath": "/dev/dri/renderD129",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD130",
"hostPath": "/dev/dri/renderD130",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD131",
"hostPath": "/dev/dri/renderD131",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD132",
"hostPath": "/dev/dri/renderD132",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD133",
"hostPath": "/dev/dri/renderD133",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD134",
"hostPath": "/dev/dri/renderD134",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD135",
"hostPath": "/dev/dri/renderD135",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD136",
"hostPath": "/dev/dri/renderD136",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD137",
"hostPath": "/dev/dri/renderD137",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD138",
"hostPath": "/dev/dri/renderD138",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD139",
"hostPath": "/dev/dri/renderD139",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD140",
"hostPath": "/dev/dri/renderD140",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD141",
"hostPath": "/dev/dri/renderD141",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD142",
"hostPath": "/dev/dri/renderD142",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD143",
"hostPath": "/dev/dri/renderD143",
"permissions": [
"read",
"write"
]
}
]
},
"mountPoints": [
{
"containerPath": "/video",
"sourceVolume": "video_file"
}
],
"cpu": 0,
"memory": 12000,
"image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
"essential": true,
"name": "xilinix-xffmpeg"
}
],
"volumes": [
{
"name": "video_file",
"host": {"sourcePath": "/home/ec2-user"}
}
]
}
```
1. 작업 정의를 등록합니다.
```
aws ecs register-task-definition --family vt1-24xlarge-xffmpeg-processor --cli-input-json file://vt1-24xlarge-xffmpeg-linux.json --region us-east-1
```
------
# AWS Neuron 기계 학습 워크로드에 대한 Amazon ECS 작업 정의
기계 학습 워크로드를 위해 [Amazon EC2 Trn1](https://aws.amazon.com/ec2/instance-types/trn1/), [Amazon EC2 Trn2](https://aws.amazon.com/ec2/instance-types/trn2/), [Amazon EC2 Inf1](https://aws.amazon.com/ec2/instance-types/inf1/), [Amazon EC2 Inf2](https://aws.amazon.com/ec2/instance-types/inf2/) 인스턴스를 클러스터에 등록할 수 있습니다.
Amazon EC2 Trn1, Trn2 인스턴스는 [AWS Trainium](https://aws.amazon.com/ai/machine-learning/trainium/) 칩으로 구동됩니다. 이러한 인스턴스는 클라우드에서의 기계 학습을 위한 고성능 및 저비용 교육을 제공합니다. Trn1 또는 Trn2 인스턴스에서 AWS Neuron과 함께 기계 학습 프레임워크를 사용하여 기계 학습 추론 모델을 교육시킬 수 있습니다. 그런 다음 Inf1 인스턴스 또는 Inf2 인스턴스에서 모델을 실행하여 AWS Inferentia 칩의 가속을 사용할 수 있습니다.
Amazon EC2 Inf1 인스턴스 및 Inf2 인스턴스는 [AWS Inferentia](https://aws.amazon.com/ai/machine-learning/inferentia/) 칩으로 구동됩니다. 이 칩은 클라우드에서 고성능의 가장 저렴한 추론을 제공합니다.
기계 학습 모델은 특화된 소프트웨어 개발 키트(SDK) [AWS Neuron](https://aws.amazon.com/ai/machine-learning/neuron/)을 사용하여 컨테이너에 배포됩니다. SDK는 AWS 기계 학습 칩의 추론 성능을 최적화하는 컴파일러, 런타임 및 프로파일링 도구로 구성됩니다. AWS Neuron은 TensorFlow, PyTorch, Apache MXNet과 같은 인기 있는 기계 학습 프레임워크를 지원합니다.
## 고려 사항
Amazon ECS에 Neuron 배포를 시작하기 전에 다음에 주의하세요.
+ 클러스터에 Trn1, Trn2, Inf1, Inf2 및 그 외 인스턴스가 혼재되어 있을 수 있습니다.
+ AWS Neuron을 지원하는 기계 학습 프레임워크를 사용하는 컨테이너에 Linux 애플리케이션이 필요합니다.
**중요**
다른 프레임워크를 사용하는 애플리케이션은 Trn1, Trn2, Inf1 및 Inf2 인스턴스에서 성능이 향상되지 않을 수 있습니다.
+ 각 [AWSTrainium](https://aws.amazon.com/ai/machine-learning/trainium/) 또는 [AWSInferentia](https://aws.amazon.com/ai/machine-learning/inferentia/) 칩에서 단 하나의 추론 또는 추론 교육 태스크만 실행할 수 있습니다. Inf1의 경우 각 칩에는 4개의 NeuronCore가 있습니다. Trn1, Trn2, Inf2의 경우 각 칩에는 2개의 NeuronCore가 있습니다. 각 Trn1, Trn2, Inf1, Inf2 인스턴스의 칩이 존재하는 만큼 많은 태스크를 실행할 수 있습니다.
+ 서비스를 생성하거나 독립적 태스크를 실행할 경우 작업 배치 제약 조건을 구성할 때 인스턴스 유형 속성을 사용할 수 있습니다. 이렇게 하면 지정한 컨테이너 인스턴스에서 태스크가 시작됩니다. 이렇게 하면 전체 리소스 사용률을 최적화하고 추론 워크로드에 대한 태스크가 Trn1, Trn2, Inf1, Inf2 인스턴스에 있는지 확인할 수 있습니다. 자세한 내용은 [Amazon ECS가 컨테이너 인스턴스에 작업을 배치하는 방법](task-placement.md) 섹션을 참조하세요.
다음의 예제에서는 `default` 클러스터에 있는 `Inf1.xlarge` 인스턴스에서 태스크를 실행합니다.
```
aws ecs run-task \
--cluster default \
--task-definition ecs-inference-task-def \
--placement-constraints type=memberOf,expression="attribute:ecs.instance-type == Inf1.xlarge"
```
+ Neuron 리소스 요구 사항은 태스크 정의에서 정의할 수 없습니다. 그 대신에 호스트 컨테이너 인스턴스에서 특정 AWS Trainium 또는 AWS Inferentia 칩을 사용하도록 컨테이너를 구성합니다. `linuxParameters` 파라미터 및 지정한 디바이스 세부 정보를 사용하여 이 작업을 수행할 수 있습니다. 자세한 내용은 [태스크 정의 요구 사항](#ecs-inference-requirements) 섹션을 참조하세요.
## Amazon ECS 최적화 Amazon Linux 2023(Neuron) AMI 사용
Amazon ECS는 AWS Trainium 및 AWS Inferentia 워크로드용 Amazon Linux 2023을 기반으로 하는 Amazon ECS에 최적화된 AMI를 제공합니다. 이는 Docker용 AWS Neuron 드라이버 및 런타임과 함께 제공됩니다. 이 AMI를 사용하면 Amazon ECS에서 더욱 쉽게 기계 학습 인퍼런스 워크로드를 실행할 수 있습니다.
Amazon EC2 Trn1, Inf1, Inf2 인스턴스를 시작할 때 Amazon ECS 최적화 Amazon Linux 2023(Neuron) AMI를 사용하는 것을 권장합니다.
다음 명령으로 AWS CLI를 사용하여 현재 Amazon ECS에 최적화된 Amazon Linux 2023(Neuron) AMI를 검색할 수 있습니다.
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/neuron/recommended
```
## 태스크 정의 요구 사항
Amazon ECS에 Neuron을 배포하려면 태스크 정의에 TensorFlow용 추론 모델을 제공하는 사전 구축된 컨테이너에 대한 컨테이너 정의를 포함해야 합니다. AWS 딥 러닝 컨테이너에 의해 제공됩니다. 이 컨테이너에는 AWS Neuron 런타임과 TensorFlow Serving 애플리케이션이 포함됩니다. 시작 시 이 컨테이너는 Amazon S3에서 모델을 가져오고, 저장된 모델로 Neuron TensorFlow Serving을 시작하고, 예측 요청을 기다립니다. 다음 예의 컨테이너 이미지에는 TensorFlow 1.15와 Ubuntu 18.04가 있습니다. Neuron에 최적화된 사전 구축된 Deep Learning Containers의 전체 목록은 GitHub에서 관리됩니다. 자세한 내용은 [Using AWS Neuron TensorFlow Serving](https://docs.aws.amazon.com/dlami/latest/devguide/tutorial-inferentia-tf-neuron-serving.html)을 참조하세요.
```
763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-inference-neuron:1.15.4-neuron-py37-ubuntu18.04
```
또는, 자체 Neuron 사이드카 컨테이너 이미지를 구축할 수 있습니다. 자세한 내용은 *AWS Deep Learning AMIs 개발자 안내서*의 [Tutorial: Neuron TensorFlow Serving](https://github.com/aws-neuron/aws-neuron-sdk/blob/master/frameworks/tensorflow/tensorflow-neuron/tutorials/tutorials-tensorflow-utilizing-neuron-capabilities.rst)을 참조하세요.
작업 정의는 단일 인스턴스 유형에만 고유해야 합니다. 호스트 컨테이너 인스턴스에서 특정 AWS Trainium 또는 AWS Inferentia 디바이스를 사용하도록 컨테이너를 구성해야 합니다. `linuxParameters` 파라미터를 사용해 이 작업을 수행할 수 있습니다. 예제 태스크 정의는 [Amazon ECS 작업 정의에서 AWS Neuron 기계 학습 지정](ecs-inference-task-def.md) 섹션을 참조하세요. 다음 표에는 각 인스턴스 유형에 해당하는 칩이 자세히 나와 있습니다.
| 인스턴스 유형 | vCPU | RAM(GiB) | AWS ML 액셀러레이터 칩 | 디바이스 경로 |
| --- | --- | --- | --- | --- |
| trn1.2xlarge | 8 | 32 | 1 | /dev/neuron0 |
| trn1.32xlarge | 128 | 512 | 16 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15 |
| trn2.48xlarge | 192 | 1536 | 16 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15 |
| inf1.xlarge | 4 | 8 | 1 | /dev/neuron0 |
| inf1.2xlarge | 8 | 16 | 1 | /dev/neuron0 |
| inf1.6xlarge | 24 | 48 | 4 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3 |
| inf1.24xlarge | 96 | 192 | 16 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15 |
| inf2.xlarge | 8 | 16 | 1 | /dev/neuron0 |
| inf2.8xlarge | 32 | 64 | 1 | /dev/neuron0 |
| inf2.24xlarge | 96 | 384 | 6 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, |
| inf2.48xlarge | 192 | 768 | 12 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11 |
# Amazon ECS 작업 정의에서 AWS Neuron 기계 학습 지정
다음은 사용할 구문을 표시한 `inf1.xlarge`에 대한 Linux 태스크 정의의 예입니다.
```
{
"family": "ecs-neuron",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == inf1.xlarge"
}
],
"executionRoleArn": "${YOUR_EXECUTION_ROLE}",
"containerDefinitions": [
{
"entryPoint": [
"/usr/local/bin/entrypoint.sh",
"--port=8500",
"--rest_api_port=9000",
"--model_name=resnet50_neuron",
"--model_base_path=s3://amzn-s3-demo-bucket/resnet50_neuron/"
],
"portMappings": [
{
"hostPort": 8500,
"protocol": "tcp",
"containerPort": 8500
},
{
"hostPort": 8501,
"protocol": "tcp",
"containerPort": 8501
},
{
"hostPort": 0,
"protocol": "tcp",
"containerPort": 80
}
],
"linuxParameters": {
"devices": [
{
"containerPath": "/dev/neuron0",
"hostPath": "/dev/neuron0",
"permissions": [
"read",
"write"
]
}
],
"capabilities": {
"add": [
"IPC_LOCK"
]
}
},
"cpu": 0,
"memoryReservation": 1000,
"image": "763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-inference-neuron:1.15.4-neuron-py37-ubuntu18.04",
"essential": true,
"name": "resnet50"
}
]
}
```
# 딥 러닝 인스턴스에 대한 Amazon ECS 작업 정의
Amazon ECS에서 딥 러닝 워크로드를 사용하려면 [Amazon EC2 DL1](https://aws.amazon.com/ec2/instance-types/dl1/) 인스턴스를 클러스터에 등록합니다. Amazon EC2 DL1 인스턴스는 Habana Labs(Intel 회사)의 Gaudi 액셀러레이터로 구동됩니다. Habana SynapseAI SDK를 사용하여 Habana Gaudi 액셀러레이터에 연결합니다. SDK는 TensorFlow, PyTorch와 같은 인기 있는 기계 학습 프레임워크를 지원합니다.
## 고려 사항
Amazon ECS에 DL1 배포를 시작하기 전에 다음에 주의하세요.
+ 클러스터에 DL1과 DL1이 아닌 인스턴스가 혼재되어 있을 수 있습니다.
+ 서비스를 생성하거나 독립적 태스크를 실행할 경우 작업 배치 제약 조건을 구성할 때 인스턴스 유형 속성을 사용하여 태스크가 시작되는 지정 컨테이너 인스턴스를 확인할 수 있습니다. 또한, 리소스를 효과적으로 사용하고 딥 러닝 워크로드에 대한 태스크가 DL1 인스턴스에 있는지 확인할 수 있습니다. 자세한 정보는 [Amazon ECS가 컨테이너 인스턴스에 작업을 배치하는 방법](task-placement.md)을 참조하세요.
다음의 예제에서는 `default` 클러스터에 있는 `dl1.24xlarge` 인스턴스에서 태스크를 실행합니다.
```
aws ecs run-task \
--cluster default \
--task-definition ecs-dl1-task-def \
--placement-constraints type=memberOf,expression="attribute:ecs.instance-type == dl1.24xlarge"
```
## DL1 AMI 사용
Amazon ECS용 Amazon EC2 DL1 인스턴스에서 AMI를 실행하는 세 가지 옵션이 있습니다.
+ Habana에서 제공하는 AWS Marketplace AMI를 사용합니다([링크](https://aws.amazon.com/marketplace/pp/prodview-h24gzbgqu75zq)).
+ Amazon Web Services에서 제공하는 Habana 딥 러닝 AMI를 사용합니다. 이 AMI는 포함되어 있지 않으므로 Amazon ECS 컨테이너 에이전트를 별도로 설치해야 합니다.
+ Packer를 사용하여 [GitHub 리포지토리](https://github.com/aws-samples/aws-habana-baseami-pipeline)에서 제공하는 사용자 지정 AMI를 빌드합니다. 자세한 정보는 [Packer 설명서](https://developer.hashicorp.com/packer/docs)를 참조하세요.
# Amazon ECS 작업 정의에서 딥 러닝 지정
Amazon ECS에서 Habana Gaudi 가속 딥 러닝 컨테이너를 실행하려면, 태스크 정의는 AWS 딥 러닝 컨테이너에서 제공하는 Habana SynapseAI를 사용하여 TensorFlow 또는 PyTorch용 딥 러닝 모델을 제공하는 사전 구축 컨테이너에 대한 컨테이너 정의를 포함해야 합니다.
다음의 컨테이너 이미지에는 TensorFlow 2.7.0과 Ubuntu 20.04가 있습니다. Habana Gaudi 엑셀러레이터에 최적화된 사전 구축된 Deep Learning Containers의 전체 목록은 GitHub에서 관리됩니다. 자세한 정보는 [abana Training Containers](https://github.com/aws/deep-learning-containers/blob/master/available_images.md#habana-training-containers)를 참조하세요.
```
763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-training-habana:2.7.0-hpu-py38-synapseai1.2.0-ubuntu20.04
```
다음은 사용할 구문을 표시하는 Amazon EC2의 Linux 컨테이너용 태스크 정의 예입니다. 이 예제에서는 여기(`vault.habana.ai/gaudi-docker/1.1.0/ubuntu20.04/habanalabs/tensorflow-installer-tf-cpu-2.6.0:1.1.0-614`)서 찾은 Habana Labs System Management Interface Tool(HL-SMI)을 포함하는 이미지를 사용합니다.
```
{
"family": "dl-test",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == dl1.24xlarge"
}
],
"networkMode": "host",
"cpu": "10240",
"memory": "1024",
"containerDefinitions": [
{
"entryPoint": [
"sh",
"-c"
],
"command": ["hl-smi"],
"cpu": 8192,
"environment": [
{
"name": "HABANA_VISIBLE_DEVICES",
"value": "all"
}
],
"image": "vault.habana.ai/gaudi-docker/1.1.0/ubuntu20.04/habanalabs/tensorflow-installer-tf-cpu-2.6.0:1.1.0-614",
"essential": true,
"name": "tensorflow-installer-tf-hpu"
}
]
}
```
# 64비트 ARM 워크로드에 대한 Amazon ECS 작업 정의
Amazon ECS는 64비트 ARM 애플리케이션 사용을 지원합니다. [AWS Graviton 프로세서](https://aws.amazon.com/ec2/graviton/)로 구동되는 플랫폼에서 애플리케이션을 실행할 수 있습니다. 다양한 워크로드에 적합합니다. 여기에는 애플리케이션 서버, 마이크로 서비스, 고성능 컴퓨팅, CPU 기반 기계 학습 추론, 비디오 인코딩, 전자 설계 자동화, 게임, 오픈 소스 데이터베이스, 인 메모리 캐시 등의 워크로드가 포함됩니다.
## 고려 사항
64비트 ARM 아키텍처를 사용하는 태스크 정의 배포를 시작하기 전에 다음에 유의합니다.
+ 애플리케이션에서 Fargate 또는 EC2를 사용할 수 있습니다.
+ 애플리케이션에서 Linux 운영 체제만 사용할 수 있습니다.
+ Fargate 유형의 경우 애플리케이션은 Fargate 플랫폼 버전 `1.4.0` 이상을 사용해야 합니다.
+ 애플리케이션은 모니터링을 위해 Fluent Bit 또는 CloudWatch를 사용할 수 있습니다.
+ Fargate의 경우 다음 AWS 리전에서는 64비트 ARM 워크로드를 지원하지 않습니다.
+ 미국 동부(버지니아 북부), `use1-az3` 가용 영역
+ EC2의 경우 다음을 참조하여 사용하려는 인스턴스 유형을 사용자의 리전에서 지원하는지 확인합니다.
+ [Amazon EC2 M6g 인스턴스](https://aws.amazon.com/ec2/instance-types/m6)
+ [Amazon EC2 T4g 인스턴스](https://aws.amazon.com/ec2/instance-types/t4/)
+ [Amazon EC2 C6g 인스턴스](https://aws.amazon.com/ec2/instance-types/c6g/)
+ [Amazon EC2 R6gd 인스턴스](https://aws.amazon.com/ec2/instance-types/r6/)
+ [Amazon EC2 X2gd 인스턴스](https://aws.amazon.com/ec2/instance-types/x2/)
필터와 함께 Amazon EC2 `describe-instance-type-offerings` 명령을 사용하여 해당 리전에 대한 인스턴스 상품을 볼 수도 있습니다.
```
aws ec2 describe-instance-type-offerings --filters Name=instance-type,Values=instance-type --region region
```
다음 예에서는 미국 동부(버지니아 북부)(us-east-1) 리전의 M6 인스턴스 유형 가용성을 확인합니다.
```
aws ec2 describe-instance-type-offerings --filters "Name=instance-type,Values=m6*" --region us-east-1
```
자세한 정보는 *Amazon EC2 Command Line Reference*(Amazon EC2 명령줄 레퍼런스)의 [describe-instance-type-offerings](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-type-offerings.html)를 참조하세요.
# Amazon ECS 작업 정의에서 ARM 아키텍처 지정
ARM 아키텍처를 활용하려면 `cpuArchitecture` 태스크 정의 파라미터에 `ARM64`를 지정합니다.
다음 예에서, ARM 아키텍처는 태스크 정의에 지정됩니다. JSON 형식입니다.
```
{
"runtimePlatform": {
"operatingSystemFamily": "LINUX",
"cpuArchitecture": "ARM64"
},
...
}
```
다음 예는 "hello world"를 표시하는 ARM 아키텍처에 대한 태스크 정의입니다.
```
{
"family": "arm64-testapp",
"networkMode": "awsvpc",
"containerDefinitions": [
{
"name": "arm-container",
"image": "public.ecr.aws/docker/library/busybox:latest",
"cpu": 100,
"memory": 100,
"essential": true,
"command": [ "echo hello world" ],
"entryPoint": [ "sh", "-c" ]
}
],
"requiresCompatibilities": [ "EC2" ],
"cpu": "256",
"memory": "512",
"runtimePlatform": {
"operatingSystemFamily": "LINUX",
"cpuArchitecture": "ARM64"
},
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
}
```
# Amazon ECS 로그를 CloudWatch로 전송
CloudWatch Logs로 로그 정보를 전송하도록 태스크의 컨테이너를 구성할 수 있습니다. 태스크에 대해 Fargate를 사용하는 경우 컨테이너에서 로그를 볼 수 있습니다. EC2를 사용하고 있다면 한 곳의 편리한 위치에서 컨테이너의 다양한 로그를 볼 수 있으며 컨테이너 로그가 컨테이너 인스턴스에서 디스크 스페이스를 차지하지 못하도록 방지합니다.
**참고**
태스크의 컨테이너에서 기록되는 정보 유형은 대부분 `ENTRYPOINT` 명령에 따라 결정됩니다. 기본적으로 수집되는 로그는 컨테이너를 로컬에서 실행했을 때 일반적으로 대화식 터미널에 표시되는 명령 출력(`STDOUT` 및 `STDERR` I/O 스트림)을 나타냅니다. `awslogs` 로그 드라이버는 이러한 로그를 Docker에서 CloudWatch Logs로 전달하는 역할만 합니다. 다른 파일 데이터 또는 스트림을 수집할 수 있는 대체 방법을 포함해 Docker 로그가 처리되는 방식에 대한 자세한 정보는 Docker 설명서에서 [컨테이너 또는 서비스 로그 보기](https://docs.docker.com/engine/logging/) 섹션을 참조하세요.
Amazon ECS 컨테이너 인스턴스에서 CloudWatch Logs로 시스템 로그를 보내려면 *Amazon CloudWatch Logs 사용 설명서*의 [로그 파일 모니터링](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchLogs.html) 및 [CloudWatch Logs 할당량](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch_limits_cwl.html)을 참조하세요.
## Fargate
태스크에 Fargate를 사용하는 경우 태스크 정의에 필요한 `logConfiguration` 파라미터를 추가하여 `awslogs` 로그 드라이버를 켜야 합니다. 자세한 내용은 [Amazon ECS 태스크 정의 예제: 로그를 CloudWatch로 라우팅](specify-log-config.md) 섹션을 참조하세요.
Fargate의 Windows 컨테이너의 경우 태스크 정의 파라미터에 특수 문자(예: `& \ < > ^ |`)가 있는 경우 다음 옵션 중 하나를 수행합니다.
+ 전체 파라미터 문자열 주위에 큰따옴표가 포함된 이스케이프(`\`) 추가
예제
```
"awslogs-multiline-pattern": "\"^[|DEBUG|INFO|WARNING|ERROR\"",
```
+ 각 특수 문자 주위에 이스케이프(`^`) 문자 추가
예제
```
"awslogs-multiline-pattern": "^^[^|DEBUG^|INFO^|WARNING^|ERROR",
```
## EC2
해당 태스크에 EC2를 사용하는 경우 `awslogs` 로그 드라이버를 설정하려면 Amazon ECS 컨테이너 인스턴스에 버전 1.9.0 이상의 컨테이너 에이전트가 필요합니다. 에이전트 버전을 확인하고 최신 버전으로 업데이트하는 방법에 대한 자세한 정보는 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요.
**참고**
Amazon ECS 최적화 AMI 또는 `ecs-init` 패키지의 최소 버전 `1.9.0-1`이 포함된 사용자 지정 AMI를 사용해야 합니다. 사용자 지정 AMI를 사용하는 경우 **docker run** 문 또는 환경 변수 파일에서 다음 환경 변수를 사용하여 에이전트를 시작할 때 Amazon EC2 인스턴스에서 `awslogs` 로깅 드라이버를 사용할 수 있도록 지정해야 합니다.
```
ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","awslogs"]
```
또한 Amazon ECS 컨테이너 인스턴스는 컨테이너 인스턴스를 시작할 때 사용하는 IAM 역할에 `logs:CreateLogStream` 및 `logs:PutLogEvents` 권한도 요구합니다. Amazon ECS에서 `awslogs` 로그 드라이버를 사용 설정하기 전에 Amazon ECS 컨테이너 인스턴스 역할을 생성한 경우 이 권한을 추가해야 할 수 있습니다. `ecsTaskExecutionRole`은 태스크에 할당되고 올바른 권한이 포함되어 있을 때 사용됩니다. 작업 실행 역할에 대한 자세한 내용은 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요. 컨테이너 인스턴스가 컨테이너 인스턴스에 대해 관리형 IAM 정책을 사용하는 경우 컨테이너 인스턴스에 올바른 권한이 부여될 수 있습니다. 컨테이너 인스턴스의 관리형 IAM 정책에 대한 자세한 내용은 [Amazon ECS 컨테이너 인스턴스 IAM 역할](instance_IAM_role.md) 섹션을 참조하세요.
# Amazon ECS 태스크 정의 예제: 로그를 CloudWatch로 라우팅
컨테이너가 `awslogs`로 로그를 전송할 수 있으려면 태스크 정의에서 컨테이너에 대한 CloudWatch 로그 드라이버를 지정해야 합니다. 로그 파라미터에 대한 자세한 내용은 [스토리지 및 로깅](task_definition_parameters.md#container_definition_storage) 섹션을 참조하세요.
다음의 작업 정의 JSON에는 각 컨테이너에 대해 지정된 `logConfiguration` 개체가 있습니다. 하나는 `awslogs-wordpress`라는 로그 그룹에 로그를 보내는 WordPress 컨테이너용입니다. 다른 하나는 `awslogs-mysql`이라는 로그 그룹에 로그를 보내는 MySQL 컨테이너용입니다. 두 컨테이너 모두 `awslogs-example` 로그 스트림 접두사를 사용합니다.
```
{
"containerDefinitions": [
{
"name": "wordpress",
"links": [
"mysql"
],
"image": "public.ecr.aws/docker/library/wordpress:latest",
"essential": true,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "true",
"awslogs-group": "awslogs-wordpress",
"awslogs-region": "us-west-2",
"awslogs-stream-prefix": "awslogs-example"
}
},
"memory": 500,
"cpu": 10
},
{
"environment": [
{
"name": "MYSQL_ROOT_PASSWORD",
"value": "password"
}
],
"name": "mysql",
"image": "public.ecr.aws/docker/library/mysql:latest",
"cpu": 10,
"memory": 500,
"essential": true,
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "true",
"awslogs-group": "awslogs-mysql",
"awslogs-region": "us-west-2",
"awslogs-stream-prefix": "awslogs-example",
"mode": "non-blocking",
"max-buffer-size": "25m"
}
}
}
],
"family": "awslogs-example"
}
```
## 다음 단계
+ CloudWatch AWS CLI 또는 API를 사용하여 로그 그룹에 대한 보존 정책을 선택적으로 설정할 수 있습니다. 자세한 내용은 *AWS Command Line Interface 참조*의 [put-retention-policy](https://docs.aws.amazon.com/cli/latest/reference/logs/put-retention-policy.html)를 참조하세요.
+ 컨테이너 정의 로그 구성에서 `awslogs` 로그 드라이버로 태스크 정의를 등록한 후 사용하여 태스크를 실행하거나 해당 태스크 정의를 사용하여 CloudWatch Logs로 로그 전송을 시작할 수 있습니다. 자세한 내용은 [애플리케이션을 Amazon ECS 태스크로 실행](standalone-task-create.md) 및 [Amazon ECS 롤링 업데이트 배포 생성](create-service-console-v2.md)(을)를 참조하세요.
# Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송
Amazon ECS용 FireLens를 사용하면 작업 정의 파라미터를 사용하여 로그 스토리지 및 분석을 위해 AWS 서비스 또는 AWS Partner Network(APN) 대상으로 로그를 라우팅할 수 있습니다. AWS Partner Network는 프로그램, 전문 지식 및 리소스를 활용하여 고객 제품을 구축, 마케팅 및 판매하는 글로벌 파트너 커뮤니티입니다. 자세한 내용은 [AWS Partner](https://aws.amazon.com/partners/work-with-partners/)를 참조하세요. FireLens는 [Fluentd](https://www.fluentd.org/) 및 [Fluent Bit](https://fluentbit.io/)와 함께 작동합니다. AWS for Fluent Bit 이미지가 제공되거나 자체 Fluentd 또는 Fluent Bit 이미지를 사용할 수 있습니다.
기본적으로 Amazon ECS는 FireLens 컨테이너가 해당 컨테이너를 사용하는 다른 컨테이너보다 먼저 시작되도록 컨테이너 종속성을 구성합니다. 또한 FireLens 컨테이너는 해당 컨테이너를 사용하는 모든 컨테이너가 중지된 후에 중지됩니다.
이 기능을 사용하려면 태스크에 필요한 AWS 서비스 사용에 필수적인 권한을 제공하는 태스크에 IAM 역할을 생성해야 합니다. 예를 들어, 컨테이너가 로그를 Firehose로 라우팅하는 경우 작업에 `firehose:PutRecordBatch` API를 직접 호출할 수 있는 권한이 필요합니다. 자세한 정보는 *IAM 사용 설명서*의 [IAM 자격 증명 권한 추가 및 제거](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) 섹션을 참조하세요.
다음 조건에서는 태스크 수행 시 Amazon ECS 태스크 실행 역할이 필요할 수도 있습니다. 자세한 내용은 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
+ 태스크가 Fargate에 호스팅되고 Amazon ECR에서 컨테이너 이미지를 가져오거나 로그 구성의 AWS Secrets Manager에서 민감한 데이터를 참조하는 경우, 태스크 실행 IAM 역할을 포함하고 있어야 합니다.
+ Amazon S3에서 호스팅되는 사용자 지정 구성 파일을 사용하는 경우에는 작업 실행 IAM 역할에 `s3:GetObject` 권한이 포함되어야 합니다.
Amazon ECS용 FireLens를 사용할 때는 다음 사항을 고려해야 합니다.
+ 콘솔에서 컨테이너 이름을 쉽게 구분할 수 있도록 로그 컨테이너 이름에 `my_service_`를 추가하는 것이 좋습니다.
+ Amazon ECS는 기본적으로 애플리케이션 컨테이너와 FireLens 컨테이너 사이에서 시작 컨테이너 순서 종속성을 추가합니다. 애플리케이션 컨테이너와 FireLens 컨테이너 사이에서 컨테이너 순서를 지정하면 기본 시작 컨테이너 순서가 재정의됩니다.
+ Amazon ECS용 FireLens는 Linux의 AWS Fargate와 Linux의 Amazon EC2 모두에서 호스팅되는 작업에 대해 지원됩니다. Windows 컨테이너는 FireLens를 지원하지 않습니다.
Windows 컨테이너에 대한 중앙 집중식 로깅을 구성하는 방법에 대한 자세한 내용은 [Centralized logging for Windows containers on Amazon ECS using Fluent Bit](https://aws.amazon.com/blogs/containers/centralized-logging-for-windows-containers-on-amazon-ecs-using-fluent-bit/)(Fluent Bit를 사용하여 Amazon ECS에서 Windows 컨테이너에 대한 중앙 집중식 로깅)를 참조하세요.
+ CloudFormation 템플릿을 사용하여 Amazon ECS를 위한 FireLens를 구성할 수 있습니다. 자세한 정보는 *AWS CloudFormation 사용 설명서*의 [::ECS::TaskDefinition FirelensConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-firelensconfiguration.html)을 참조하세요.
+ FireLens의 수신 포트는 `24224`이므로 FireLens 로그 라우터가 태스크 범위를 벗어나지 않도록 하기 위해, 태스크에서 사용하는 보안 그룹의 포트 `24224`에서 인바운드 트래픽을 허용해서는 안 됩니다. `awsvpc` 네트워크 모드를 사용하는 작업의 경우 이것은 태스크와 연결된 보안 그룹입니다. `host` 네트워크 모드를 사용하는 태스크의 경우 이것은 태스크를 호스팅하는 Amazon EC2 인스턴스와 연결된 보안 그룹입니다. `bridge` 네트워크 모드를 사용하는 태스크의 경우 포트 `24224`를 사용하는 포트 매핑을 생성하지 마세요.
+ `bridge` 네트워크 모드를 사용하는 작업의 경우 FireLens 구성이 포함된 컨테이너는 해당 컨테이너를 사용하는 모든 애플리케이션 컨테이너가 시작되기 전에 시작해야 합니다. 컨테이너의 시작 순서를 제어하려면 태스크 정의에서 종속성 조건을 사용하세요. 자세한 정보는 [컨테이너 종속성](task_definition_parameters.md#container_definition_dependson) 섹션을 참조하세요.
**참고**
FireLens 구성과 함께 컨테이너 정의에서 종속성 조건 파라미터를 사용하는 경우 각 컨테이너에 `START` 또는 `HEALTHY` 조건 요구 사항이 있는지 확인하세요.
+ 기본적으로 FireLens는 클러스터 및 태스크 정의 이름을 추가하고 클러스터의 Amazon 리소스 이름(ARN)을 stdout/stderr 컨테이너 로그에 메타데이터 키로 추가합니다. 다음은 메타데이터 형식의 예입니다.
```
"ecs_cluster": "cluster-name",
"ecs_task_arn": "arn:aws:ecs:region:111122223333:task/cluster-name/f2ad7dba413f45ddb4EXAMPLE",
"ecs_task_definition": "task-def-name:revision",
```
로그에 메타데이터를 포함시키지 않으려면 태스크 정의의 `firelensConfiguration` 섹션에서 `enable-ecs-log-metadata`를 `false`로 설정합니다.
```
"firelensConfiguration":{
"type":"fluentbit",
"options":{
"enable-ecs-log-metadata":"false",
"config-file-type":"file",
"config-file-value":"/extra.conf"
}
```
루트가 아닌 사용자로 실행하도록 FireLens 컨테이너를 구성할 수 있습니다. 다음을 고려하세요.
+ 루트가 아닌 사용자로 실행하도록 FireLens 컨테이너를 구성하려면 다음 형식 중 하나로 사용자를 지정해야 합니다.
+ `uid`
+ `uid:gid`
+ `uid:group`
컨테이너 정의에서 사용자 지정 방법에 대한 자세한 내용은 *Amazon Elastic Container Service API 참조*의 [ContainerDefinition](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html)을 참조하세요.
FireLens 컨테이너는 UNIX 소켓을 통해 애플리케이션 로그를 수신합니다. Amazon ECS 에이전트는 `uid`를 사용하여 소켓 디렉터리의 소유권을 FireLens 컨테이너에 할당합니다.
+ 루트가 아닌 사용자로 실행하도록 FireLens 컨테이너를 구성하는 방법은 Amazon ECS 에이전트 버전 `1.96.0` 이상 및 Amazon ECS 최적화 AMI 버전 `v20250716` 이상에서 지원됩니다.
+ FireLens 컨테이너에 사용자를 지정할 때 `uid`는 고유해야 하며 태스크 또는 컨테이너 인스턴스의 다른 컨테이너에 속하는 다른 프로세스에는 사용되지 않아야 합니다.
호스팅하는 파일 또는 Amazon S3에 있는 파일을 포함하여 Amazon ECS에서 여러 구성 파일을 사용하는 방법에 대한 자세한 내용은 [Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/tree/mainline/use_cases/init-process-for-fluent-bit)를 참조하세요.
구성 예제에 대한 자세한 내용은 [Amazon ECS 태스크 정의 예제: 로그를 FireLens로 라우팅](firelens-taskdef.md) 섹션을 참조하세요.
높은 처리량을 위해 로그를 구성하는 방법에 대한 자세한 내용은 [높은 처리량을 위한 Amazon ECS 로그 구성](firelens-docker-buffer-limit.md) 섹션을 참조하세요.
# 높은 처리량을 위한 Amazon ECS 로그 구성
로그 처리량이 많은 시나리오의 경우, FireLens 및 Fluent Bit와(과) 함께 `awsfirelens` 로그 드라이버를 사용하는 것이 좋습니다. Fluent Bit은(는) 리소스를 효율적으로 사용하며 수백만 개의 로그 레코드를 처리할 수 있는 경량 로그 프로세서입니다. 하지만 대규모 환경에서 최적의 성능을 달성하려면 구성을 조정해야 합니다.
이 섹션에서는 시스템 안정성을 유지하고 데이터 손실이 없도록 보장하면서 높은 로그 처리량을 처리하기 위한 고급 Fluent Bit 최적화 기술을 다룹니다.
FireLens에서 사용자 지정 구성 파일을 사용하는 방법에 대한 자세한 내용은 [사용자 지정 구성 파일 사용](firelens-taskdef.md#firelens-taskdef-customconfig)을(를) 참고하세요. 추가 예제는 GitHub의 [Amazon ECS FireLens 예제](https://github.com/aws-samples/amazon-ecs-firelens-examples)를 확인하세요.
**참고**
`workers` 및 `threaded`와(과) 같은 이 섹션의 일부 구성 옵션에는 Fluent Bit 버전 3 이상을 위한 AWS이(가) 필요합니다. 사용 가능한 버전에 대한 자세한 내용은 [Fluent Bit 릴리스에 대한 AWS](https://github.com/aws/aws-for-fluent-bit/releases)을(를) 참고하세요.
## 파일 시스템 버퍼링 사용
기본적으로 Fluent Bit은(는) 모든 데이터를 메모리에 버퍼링합니다. 데이터가 출력으로 플러시되는 속도보다 빠르게 수집되면 버퍼가 가득 찹니다. 버퍼가 가득 차면 버퍼 스페이스가 확보될 때까지 입력 플러그인이 일시 중지되며, 이로 인해 백프레셔가 발생하고 애플리케이션 속도가 느려질 수 있습니다.
처리량이 많은 시나리오의 경우 파일 시스템 버퍼링을 사용하는 것이 좋습니다. Fluent Bit이(가) 버퍼링과 스토리지를 관리하는 방법에 대한 자세한 내용은 Fluent Bit 문서의 [버퍼링 및 스토리지](https://docs.fluentbit.io/manual/administration/buffering-and-storage) 섹션을 참고하세요.
파일 시스템 버퍼링은 다음과 같은 장점을 제공합니다:
+ **더 큰 버퍼 용량** – 일반적으로 디스크 스페이스를 메모리보다 훨씬 여유가 있습니다.
+ **지속성** - 버퍼링된 데이터는 Fluent Bit(이)가 재시작되어도 유지됩니다.
+ **점진적 성능 저하** - 출력 오류가 발생해도 데이터가 메모리를 고갈시키는 대신 디스크에 축적됩니다.
파일 시스템 버퍼링을 활성화하려면 사용자 지정 Fluent Bit 구성 파일을 제공하세요. 다음 예시는 권장 구성을 보여줍니다:
```
[SERVICE]
# Flush logs every 1 second
Flush 1
# Wait 120 seconds during shutdown to flush remaining logs
Grace 120
# Directory for filesystem buffering
storage.path /var/log/flb-storage/
# Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
storage.max_chunks_up 32
# Flush backlog chunks to destinations during shutdown (prevents log loss)
storage.backlog.flush_on_shutdown On
[INPUT]
Name forward
unix_path /var/run/fluent.sock
# Run input in separate thread to prevent blocking
threaded true
# Enable filesystem buffering for persistence
storage.type filesystem
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
# Use multiple workers for parallel processing
workers 2
# Retry failed flushes up to 15 times
retry_limit 15
# Maximum disk space for buffered data for this output
storage.total_limit_size 10G
```
주요 구성 파라미터:
`storage.path`
Fluent Bit이(가) 디스크에 버퍼링된 청크를 저장하는 디렉터리입니다.
`storage.backlog.flush_on_shutdown`
이 기능이 활성화되면 Fluent Bit은(는) 종료 시 백로그에 있는 모든 파일 시스템 청크를 대상지로 플러시하려고 시도합니다. 이는 Fluent Bit이(가) 중지되기 전에 데이터 전달을 보장하는 데 도움이 되지만, 종료 시간이 늘어날 수 있습니다.
`storage.max_chunks_up`
메모리에 남아 있는 청크의 수입니다. 기본값은 128개 청크이며, 각 청크가 최대 4\$15MB를 사용할 수 있기 때문에 500MB 이상의 메모리를 소비할 수 있습니다. 메모리가 제한된 환경에서는 이 값을 낮추세요. 예를 들어 버퍼링에 사용할 수 있는 공간이 50MB라면, 이 값을 8\$110개 청크로 설정합니다.
`storage.type filesystem`
입력 플러그인에 대해 파일 시스템 스토리지를 활성화합니다. 이름과 달리 Fluent Bit은(는) `mmap`을(를) 사용하여 청크를 메모리와 디스크 모두에 매핑하며, 성능 저하 없이 지속성을 제공합니다.
`threaded true`
Fluent Bit의 메인 이벤트 루프와 별개로 입력을 자체 스레드에서 실행합니다. 이렇게 하면 느린 입력이 전체 파이프라인을 차단하는 것을 방지합니다.
## 출력 구성 최적화
네트워크 문제, 서비스 중단, 대상지의 스로틀링 등으로 인해 로그가 전달되지 않을 수 있습니다. 적절한 출력 구성은 데이터 손실 없는 복원력을 보장합니다.
출력 플러시가 실패하면 Fluent Bit은(는) 해당 작업을 재시도할 수 있습니다. 다음 파라미터는 재시도 동작을 제어합니다:
`retry_limit`
레코드를 삭제하기 전까지의 최대 재시도 횟수입니다. 기본값은 1입니다. 프로덕션 환경의 경우 15회 이상으로 설정하는 것을 권장하며, 이는 지수 백오프를 통해 몇 분간의 장애 상황을 커버할 수 있습니다.
`scheduler.base`
재시도 간의 최소 초 단위 시간입니다. 10초를 권장합니다.
`scheduler.cap`
지수 백오프 사용 시 재시도 간의 최대 초 단위 시간입니다. 60초를 권장합니다.
`workers`
병렬 출력 처리를 위한 스레드 수입니다. 여러 워커를 사용하면 플러시를 동시에 수행할 수 있어, 많은 청크를 처리할 때 처리량이 향상됩니다.
`[SERVICE]` 섹션의 `Grace` 파라미터는 종료 시 버퍼링된 데이터를 플러시하기 위해 Fluent Bit이(가) 대기하는 시간을 설정합니다. `Grace` 기간은 컨테이너의 `stopTimeout`와(과) 연계하여 조정해야 합니다. Fluent Bit이(가) `SIGKILL`을(를) 받기 전에 플러시를 완료할 수 있도록 `stopTimeout`이(가) `Grace` 기간을 초과하도록 설정하세요. 예를 들어 `Grace`이(가) 120초라면, `stopTimeout`은(는) 150초로 설정합니다.
다음 예시는 높은 처리량 시나리오를 위해 권장되는 모든 설정이 포함된 전체 Fluent Bit 구성을 보여줍니다.
```
[SERVICE]
# Flush logs every 1 second
Flush 1
# Wait 120 seconds during shutdown to flush remaining logs
Grace 120
# Directory for filesystem buffering
storage.path /var/log/flb-storage/
# Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
storage.max_chunks_up 32
# Flush backlog chunks to destinations during shutdown (prevents log loss)
storage.backlog.flush_on_shutdown On
# Minimum seconds between retries
scheduler.base 10
# Maximum seconds between retries (exponential backoff cap)
scheduler.cap 60
[INPUT]
Name forward
unix_path /var/run/fluent.sock
# Run input in separate thread to prevent blocking
threaded true
# Enable filesystem buffering for persistence
storage.type filesystem
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
# Use multiple workers for parallel processing
workers 2
# Retry failed flushes up to 15 times
retry_limit 15
# Maximum disk space for buffered data for this output
storage.total_limit_size 10G
```
## 안전성을 위해 다중 대상 로깅 사용
로그를 여러 대상으로 전송하면 단일 장애점을 제거할 수 있습니다. 예를 들어 CloudWatch Logs에 장애가 발생하더라도 로그는 여전히 Amazon S3에 도달합니다.
다중 대상 로깅은 다음과 같은 이점을 제공합니다. Amazon S3 출력 플러그인은 gzip 및 Parquet 형식과 같은 압축 옵션도 지원하여 스토리지 비용을 절감할 수 있습니다. 자세한 내용은 Fluent Bit 문서의 [S3 압축](https://docs.fluentbit.io/manual/pipeline/outputs/s3#compression) 섹션을 참고하세요.
다중 대상 로깅은 다음과 같은 이점을 제공할 수 있습니다:
+ **중복성** - 한 곳의 대상지에 장애가 발생해도 로그는 다른 곳에 도달합니다.
+ **복구** - 한 시스템의 데이터 공백을 다른 시스템을 통해 재구성합니다.
+ **내구성** - 장기 보관을 위해 Amazon S3에 로그를 아카이빙합니다.
+ **비용 최적화** - .최근 로그는 보관 주기가 짧고 쿼리가 빠른 CloudWatch Logs에 보관하고, 모든 로그는 장기 보관을 위해 비용이 저렴한 Amazon S3 스토리지에 아카이빙합니다.
다음 Fluent Bit 구성은 CloudWatch Logs와 Amazon S3 모두에 로그를 전송합니다.
```
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
workers 2
retry_limit 15
[OUTPUT]
Name s3
Match *
bucket my-logs-bucket
region us-west-2
total_file_size 100M
s3_key_format /fluent-bit-logs/$(ecs_task_id)/%Y%m%d/%H/%M/$UUID
upload_timeout 10m
# Maximum disk space for buffered data for this output
storage.total_limit_size 5G
```
두 출력 모두 동일한 `Match *` 패턴을 사용하므로, 모든 레코드가 두 대상지에 각각 독립적으로 전송됩니다. 한 곳의 대상지에 장애가 발생하더라도 로그는 다른 곳으로 계속 흐르며, 실패한 플러시는 나중에 재시도할 수 있도록 파일 시스템 버퍼에 축적됩니다.
## tail 입력 플러그인을 사용한 파일 기반 로깅 사용
로그 손실이 중요한 문제인 높은 처리량 시나리오에서는 대안적인 접근 방식을 사용할 수 있습니다. 애플리케이션이 로그를 디스크 파일에 쓰고, Fluent Bit이(가) `tail` 입력 플러그인을 사용하여 해당 파일을 읽도록 구성하는 방식입니다. 이 방식은 Docker 로깅 드라이버 레이어를 완전히 우회합니다.
tail 플러그인을 사용한 파일 기반 로깅은 다음과 같은 이점을 제공합니다:
+ **오프셋 추적** - tail 플러그인은 (`DB` 옵션을 사용하여) 데이터베이스 파일에 파일 오프셋을 저장할 수 있어, Fluent Bit 재시작 시에도 내구성을 제공합니다. 컨테이너 재시작 시 로그 손실이 발생하는 것을 방지하는 데 도움이 됩니다.
+ **입력 수준 버퍼링** - `Mem_Buf_Limit`을(를) 사용하여 입력 플러그인에서 직접 메모리 버퍼 제한을 구성할 수 있으며, 이를 통해 메모리 사용량을 더욱 세밀하게 제어할 수 있습니다.
+ **Docker 오버헤드 방지** – 로그가 Docker의 로그 버퍼를 거치지 않고 파일에서 Fluent Bit(으)로 직접 전달됩니다.
이 방식을 사용하려면 애플리케이션이 `stdout` 대신 파일에 로그를 기록해야 합니다. 애플리케이션 컨테이너와 Fluent Bit 컨테이너 모두 로그 파일이 저장된 공유 볼륨을 마운트합니다.
다음 예시는 모범 사례가 적용된 tail 입력 구성을 보여줍니다.
```
[INPUT]
Name tail
# File path or glob pattern to tail
Path /var/log/app.log
# Database file for storing file offsets (enables resuming after restart)
DB /var/log/flb_tail.db
# when true, controls that only fluent-bit will access the database (improves performance)
DB.locking true
# Skip long lines instead of skipping the entire file
Skip_Long_Lines On
# How often (in seconds) to check for new files matching the glob pattern
Refresh_Interval 10
# Extra seconds to monitor a file after rotation to account for pending flush
Rotate_Wait 30
# Maximum size of the buffer for a single line
Buffer_Max_Size 10MB
# Initial allocation size for reading file data
Buffer_Chunk_Size 1MB
# Maximum memory buffer size (tail pauses when full)
Mem_Buf_Limit 75MB
```
tail 입력 플러그인을 사용할 때는 다음 사항을 고려하세요:
+ 디스크 소진을 방지하기 위해 애플리케이션 로그에 대한 로그 로테이션을 구현하세요. 성능을 측정하기 위해 기본 볼륨 메트릭을 모니터링합니다.
+ 로그 형식에 따라 `Ignore_Older`, `Read_from_Head` 및 멀티라인 파서와 같은 설정을 고려하세요.
자세한 내용은 Fluent Bit 문서의 [Tail](https://docs.fluentbit.io/manual/pipeline/inputs/tail) 섹션을 참고하세요. 모범 사례는 AWS을(를) 위한 Fluent Bit 문제 해결 가이드의 [Tail config with best practices](https://github.com/aws/aws-for-fluent-bit/blob/mainline/troubleshooting/debugging.md#tail-config-with-best-practices)를 참고하세요.
## FireLens로 직접 로깅
`awsfirelens` 로그 드라이버가 태스크 정의에 지정되어 있으면 Amazon ECS 컨테이너 에이전트는 다음 환경 변수를 컨테이너에 주입합니다.
`FLUENT_HOST`
FireLens 컨테이너에 할당된 IP 주소입니다.
`bridge` 네트워크 모드에서 EC2를 사용하는 경우 FireLens 로그 라우터 컨테이너(컨테이너 정의에 `firelensConfiguration` 객체가 있는 컨테이너)를 다시 시작한 후 애플리케이션 컨테이너의 `FLUENT_HOST` 환경 변수가 부정확해질 수 있습니다. 이는 `FLUENT_HOST`가 동적 IP 주소이며 재시작 후 변경될 수 있기 때문입니다. 애플리케이션 컨테이너에서 `FLUENT_HOST` IP 주소로 직접 로깅하면 주소가 변경된 후 실패하기 시작할 수 있습니다. 개별 컨테이너를 재시작하는 방법에 대한 자세한 내용은 [컨테이너 재시작 정책이 있는 Amazon ECS 작업의 개별 컨테이너 재시작](container-restart-policy.md) 섹션을 참조하세요.
`FLUENT_PORT`
Fluent Forward 프로토콜이 수신 대기 중인 포트입니다.
이 환경 변수들을 사용하면 `stdout`에 기록하는 대신 Fluent Forward 프로토콜을 사용하여 애플리케이션 코드에서 Fluent Bit 로그 라우터로 직접 로그를 보낼 수 있습니다. 이 방식은 Docker 로깅 드라이버 레이어를 우회하며 다음과 같은 이점을 제공합니다:
+ **낮은 대기 시간** – 로그가 Docker의 로깅 인프라를 거치지 않고 Fluent Bit(으)로 직접 전달됩니다.
+ **구조화된 로깅** - JSON 인코딩 오버헤드 없이 구조화된 로그 데이터를 기본적으로 전송합니다.
+ **제어력 향상** - 애플리케이션이 자체적인 버퍼링 및 오류 처리 로직을 구현할 수 있습니다.
다음 Fluent 로거 라이브러리는 Fluent Forward 프로토콜을 지원하며 Fluent Bit(으)로 로그를 직접 보내는 데 사용할 수 있습니다.
+ **Go** – [fluent-logger-golang](https://github.com/fluent/fluent-logger-golang)
+ **Python** – [fluent-logger-python](https://github.com/fluent/fluent-logger-python)
+ **Java** – [fluent-logger-java](https://github.com/fluent/fluent-logger-java)
+ **Node.js** – [fluent-logger-node](https://github.com/fluent/fluent-logger-node)
+ **Ruby** – [fluent-logger-ruby](https://github.com/fluent/fluent-logger-ruby)
## Docker 버퍼 제한 구성
태스크 정의를 생성할 때 `log-driver-buffer-limit`에 값을 지정하여 메모리에 버퍼링되는 로그 라인의 수를 지정할 수 있습니다. 이는 Docker와 Fluent Bit 사이의 버퍼를 제어합니다. 자세한 정보는 Docker 설명서의 [Fluentd logging driver](https://docs.docker.com/engine/logging/drivers/fluentd/)(Fluentd 로깅 드라이버)를 참조하세요.
Docker에서 버퍼 메모리가 부족하여 새 메시지를 추가할 수 있도록 버퍼 메시지를 삭제할 수 있으므로 처리량이 많을 때 이 옵션을 사용합니다.
이 옵션을 사용할 때 다음 사항을 고려하세요:
+ 이 옵션은 플랫폼 버전 `1.4.0` 이상의 EC2 및 Fargate 유형에서 지원됩니다.
+ 이 옵션은 `logDriver`가 `awsfirelens`로 설정된 경우에만 유효합니다.
+ 기본 버퍼 제한은 `1048576`개의 로그 줄입니다.
+ 버퍼 제한은 로그 라인 `0`줄 이상, `536870912`줄 미만이어야 합니다.
+ 이 버퍼에 사용되는 최대 메모리 양은 각 로그 줄의 크기와 버퍼 크기를 곱한 값입니다. 예를 들어 애플리케이션의 로그 라인이 평균 `2`KiB라면, 버퍼 제한을 4096으로 설정했을 때 최대 `8`MiB를 사용합니다. 작업 수준에서 할당된 총 메모리 양은 로그 드라이버 메모리 버퍼 외에도 모든 컨테이너에 할당된 메모리 양보다 커야 합니다.
다음 태스크 정의는 `log-driver-buffer-limit`을(를) 구성하는 방법을 보여줍니다.
```
{
"containerDefinitions": [
{
"name": "my_service_log_router",
"image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
"cpu": 0,
"memoryReservation": 51,
"essential": true,
"firelensConfiguration": {
"type": "fluentbit"
}
},
{
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:latest",
"name": "app",
"logConfiguration": {
"logDriver": "awsfirelens",
"options": {
"Name": "firehose",
"region": "us-west-2",
"delivery_stream": "my-stream",
"log-driver-buffer-limit": "52428800"
}
},
"dependsOn": [
{
"containerName": "my_service_log_router",
"condition": "START"
}
],
"memoryReservation": 100
}
]
}
```
# Amazon ECS용 Fluent Bit 이미지 리포지토리에 대한 AWS
AWS는 CloudWatch Logs 및 Firehose 모두에 대해 플러그인과 함께 Fluent Bit 이미지를 제공합니다. Fluent Bit가 Fluentd보다 리소스 사용률이 낮으므로 Fluent Bit를 로그 라우터로 사용하는 것이 좋습니다. 자세한 정보는 [Fluent Bit용 CloudWatch Logs](https://github.com/aws/amazon-cloudwatch-logs-for-fluent-bit) 및 [Fluent Bit용 Amazon Kinesis Firehose](https://github.com/aws/amazon-kinesis-firehose-for-fluent-bit)를 참조하세요.
**AWS for Fluent Bit** 이미지는 고가용성을 위해 Amazon ECR 퍼블릭 갤러리와 Amazon ECR 리포지토리에 있는 Amazon ECR에 사용할 수 있습니다.
## Amazon ECR 퍼블릭 갤러리
AWS for Fluent Bit 이미지는 Amazon ECR 퍼블릭 갤러리에서 사용할 수 있습니다. Amazon ECR 퍼블릭 갤러리는 퍼블릭 리포지토리이며 모든 AWS 리전에서 사용할 수 있으므로 여기에 AWS for Fluent Bit 이미지를 다운로드하는 것이 좋습니다. 자세한 정보는 Amazon ECR 퍼블릭 갤러리의 [aws-for-fluent-bit](https://gallery.ecr.aws/aws-observability/aws-for-fluent-bit)를 참조하세요.
### Linux
Amazon ECR 퍼블릭 갤러리의 AWS for Fluent Bit 이미지는 `ARM64` 또는 `x86-64` 아키텍처가 있는 Amazon Linux 운영 체제를 지원합니다.
원하는 이미지 태그로 리포지토리 URL을 지정하여 Amazon ECR 퍼블릭 갤러리에서 AWS for Fluent Bit 이미지를 가져올 수 있습니다. 사용 가능한 이미지 태그는 Amazon ECR 퍼블릭 갤러리의 **이미지 태그(Image tags)** 탭에서 확인할 수 있습니다.
Docker CLI에 사용할 구문은 다음과 같습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```
예를 들어, 이 Docker CLI 명령을 사용하여 Fluent Bit 릴리스를 위한 AWS의 "3.x" 제품군 최신 이미지를 가져올 수 있습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```
**참고**
인증되지 않은 풀은 허용되지만 인증된 가져오기보다 속도 제한이 낮습니다. 가져오기 전 AWS 계정을 인증하려면 다음 명령을 사용합니다.
```
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```
#### Fluent Bit 3.0.0에 대한 AWS
기존의 AWS for Fluent Bit 버전 `2.x` 외에도, AWS for Fluent Bit는 새 주 버전 `3.x`을 지원합니다. 새 주 버전에는 Amazon Linux 2에서 Amazon Linux 2023으로 이미지를 업그레이드하고 Fluent Bit 버전 `1.9.10`을 `4.1.1`로 업그레이드하는 작업이 포함되어 있습니다. 자세한 내용은 GitHub의 [AWS for Fluent Bit repository](https://github.com/aws/aws-for-fluent-bit/blob/mainline/VERSIONS.md)를 참조하세요.
다음 예제에서는 AWS for Fluent Bit `3.x` 이미지에 대한 업데이트된 태그를 보여줍니다.
AWS for Fluent Bit 이미지에 대해 다중 아키텍처 태그를 사용할 수 있습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```
### Windows
Amazon ECR 퍼블릭 갤러리의 AWS for Fluent Bit 이미지는 다음 운영 체제를 사용하는 `AMD64` 아키텍처를 지원합니다.
+ Windows Server 2022 Full
+ Windows Server 2022 Core
+ Windows Server 2019 Full
+ Windows Server 2019 Core
AWS Fargate에 있는 Windows 컨테이너는 FireLens를 지원하지 않습니다.
원하는 이미지 태그로 리포지토리 URL을 지정하여 Amazon ECR 퍼블릭 갤러리에서 AWS for Fluent Bit 이미지를 가져올 수 있습니다. 사용 가능한 이미지 태그는 Amazon ECR 퍼블릭 갤러리의 **이미지 태그(Image tags)** 탭에서 확인할 수 있습니다.
Docker CLI에 사용할 구문은 다음과 같습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```
예를 들어 이 Docker CLI 명령을 사용하여 안정적인 최신 AWS for Fluent Bit 이미지를 가져올 수 있습니다.
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:windowsservercore-stable
```
**참고**
인증되지 않은 풀은 허용되지만 인증된 가져오기보다 속도 제한이 낮습니다. 가져오기 전 AWS 계정을 인증하려면 다음 명령을 사용합니다.
```
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```
## Amazon ECR
Fluent Bit용 AWS 이미지는 고가용성을 위해 Amazon ECR에서 사용할 수 있습니다. 다음 명령을 사용하여 지정된 AWS 리전에서 이미지 URI를 검색하고 이미지 가용성을 설정할 수 있습니다.
### Linux
다음 명령을 사용하여 안정적인 AWS for Fluent Bit 이미지 URI를 검색할 수 있습니다.
```
aws ssm get-parameters \
--names /aws/service/aws-for-fluent-bit/stable \
--region us-east-1
```
다음 명령을 사용하여 모든 버전의 Fluent Bit용 AWS 이미지를 나열하고 Systems Manager 파라미터 스토어 파라미터를 쿼리할 수 있습니다.
```
aws ssm get-parameters-by-path \
--path /aws/service/aws-for-fluent-bit \
--region us-east-1
```
안정적인 최신 AWS for Fluent Bit 이미지는 Systems Manager Parameter Store 이름을 참조하여 CloudFormation 템플릿에서 참조할 수 있습니다. 다음은 예제입니다.
```
Parameters:
FireLensImage:
Description: Fluent Bit image for the FireLens Container
Type: AWS::SSM::Parameter::Value
Default: /aws/service/aws-for-fluent-bit/stable
```
**참고**
명령이 실패하거나 출력이 없는 경우 명령이 직접 호출되는 AWS 리전에서 이미지를 사용할 수 없습니다.
### Windows
다음 명령을 사용하여 안정적인 AWS for Fluent Bit 이미지 URI를 검색할 수 있습니다.
```
aws ssm get-parameters \
--names /aws/service/aws-for-fluent-bit/windowsservercore-stable \
--region us-east-1
```
다음 명령을 사용하여 모든 버전의 Fluent Bit용 AWS 이미지를 나열하고 Systems Manager 파라미터 스토어 파라미터를 쿼리할 수 있습니다.
```
aws ssm get-parameters-by-path \
--path /aws/service/aws-for-fluent-bit/windowsservercore \
--region us-east-1
```
안정적인 최신 AWS for Fluent Bit 이미지는 Systems Manager 파라미터 스토어 이름을 참조하여 CloudFormation 템플릿에서 참조할 수 있습니다. 다음은 예제입니다.
```
Parameters:
FireLensImage:
Description: Fluent Bit image for the FireLens Container
Type: AWS::SSM::Parameter::Value
Default: /aws/service/aws-for-fluent-bit/windowsservercore-stable
```
# Amazon ECS 태스크 정의 예제: 로그를 FireLens로 라우팅
FireLens에서 사용자 정의 로그 라우팅을 사용하려면 태스크 정의에 다음 사항을 지정해야 합니다.
+ FireLens 구성을 포함하는 로그 라우터 컨테이너. 컨테이너는 `essential`로 표시하는 것이 좋습니다.
+ `awsfirelens` 로그 드라이버를 지정하는 로그 구성이 포함된 하나 이상의 애플리케이션 컨테이너.
+ 태스크가 로그를 라우팅하는 데 필요한 권한이 포함된 태스크 IAM 역할 Amazon 리소스 이름(ARN).
AWS Management Console을 사용하여 새로운 태스크 정의를 생성할 때 로그 라우터 컨테이너를 쉽게 추가할 수 있는 FireLens 통합 섹션이 있습니다. 자세한 정보는 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 섹션을 참조하세요.
Amazon ECS는 로그 구성을 변환하고 Fluentd 또는 Fluent Bit 출력 구성을 생성합니다. 출력 구성은 Fluent Bit의 경우 `/fluent-bit/etc/fluent-bit.conf`, Fluentd의 경우 `/fluentd/etc/fluent.conf`에서 로그 라우팅 컨테이너에 마운트됩니다.
**중요**
FireLens의 수신 포트는 `24224`입니다. 그러므로 FireLens 로그 라우터가 태스크 범위를 벗어나지 않도록 태스크에서 사용하는 보안 그룹의 포트 `24224`에서 수신 트래픽을 허용해서는 안 됩니다. `awsvpc` 네트워크 모드를 사용하는 작업의 경우 이것은 태스크와 연결된 보안 그룹입니다. `host` 네트워크 모드를 사용하는 태스크의 경우 이것은 태스크를 호스팅하는 Amazon EC2 인스턴스와 연결된 보안 그룹입니다. `bridge` 네트워크 모드를 사용하는 태스크의 경우 포트 `24224`를 사용하는 포트 매핑을 생성하지 마세요.
기본적으로 Amazon ECS는 로그 원본을 식별하는 데 도움이 되는 추가 필드를 로그 항목에 추가합니다.
+ `ecs_cluster` - 태스크가 속한 클러스터의 이름입니다.
+ `ecs_task_arn` – 컨테이너가 속한 태스크의 전체 Amazon 리소스 이름(ARN)
+ `ecs_task_definition` - 태스크에서 사용 중인 태스크 정의 이름 및 개정입니다.
+ `ec2_instance_id` – 컨테이너가 호스팅되는 Amazon EC2 인스턴스 ID입니다. 이 필드는 EC2 시작 유형을 사용하는 태스크에서만 유효합니다.
메타데이터를 원하지 않는 경우 `enable-ecs-log-metadata`를 `false`로 설정할 수 있습니다.
다음 태스크 정의 예에서는 Fluent Bit를 사용하여 로그를 CloudWatch Logs로 라우팅하는 로그 라우터 컨테이너를 정의합니다. 또한 로그 구성을 사용하여 Amazon Data Firehose로 로그를 라우팅하고 이벤트를 버퍼링하는 데 사용되는 메모리를 2MiB로 설정하는 애플리케이션 컨테이너를 정의합니다.
**참고**
자세한 작업 정의 예제는 GitHub의 [Amazon ECS FireLens examples](https://github.com/aws-samples/amazon-ecs-firelens-examples)를 참조하세요.
```
{
"family": "firelens-example-firehose",
"taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
"containerDefinitions": [
{
"name": "log_router",
"image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
"cpu": 0,
"memoryReservation": 51,
"portMappings": [],
"essential": true,
"environment": [],
"mountPoints": [],
"volumesFrom": [],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/ecs-aws-firelens-sidecar-container",
"mode": "non-blocking",
"awslogs-create-group": "true",
"max-buffer-size": "25m",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "firelens"
},
"secretOptions": []
},
"systemControls": [],
"firelensConfiguration": {
"type": "fluentbit"
}
},
{
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:latest",
"name": "app",
"logConfiguration": {
"logDriver": "awsfirelens",
"options": {
"Name": "firehose",
"region": "us-west-2",
"delivery_stream": "my-stream",
"log-driver-buffer-limit": "1048576"
}
},
"memoryReservation": 100
}
]
}
```
`logConfiguration` 객체에 옵션으로 지정된 키 값 페어는 Fluentd 또는 Fluent Bit 출력 구성을 생성하는 데 사용됩니다. 다음은 Fluent Bit 출력 정의의 코드 예시입니다.
```
[OUTPUT]
Name firehose
Match app-firelens*
region us-west-2
delivery_stream my-stream
```
**참고**
FireLens는 `match` 구성을 관리합니다. 태스크 정의에서 `match` 구성을 지정하지 않습니다.
## 사용자 지정 구성 파일 사용
사용자 지정 구성 파일을 지정할 수 있습니다. 구성 파일 형식은 사용 중인 로그 라우터의 기본 형식입니다. 자세한 정보는 [Fluentd Config 파일 구문](https://docs.fluentd.org/configuration/config-file)과 [YAML 구성](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/yaml)을 참조하세요.
사용자 정의 구성 파일에서 `bridge` 또는 `awsvpc` 네트워크 모드를 사용하는 태스크의 경우 FireLens가 입력 구성에 Fluentd나 Fluent Bit를 추가하기 때문에 TCP를 통해 Fluentd 또는 Fluent Bit 전달 입력을 설정하지 않습니다.
사용자 정의 구성 파일을 지정하려면 FireLens 구성에 다음 옵션이 포함되어야 합니다.
`config-file-type`
사용자 정의 구성 파일의 원본 위치입니다. 사용할 수 있는 옵션은 `s3` 또는 `file`입니다.
AWS Fargate에 호스팅된 태스크는 `file` 구성 파일 유형만을 지원합니다. 하지만 AWS for Fluent Bit 초기화(init) 컨테이너를 사용하면 AWS Fargate에서 Amazon S3에 호스팅된 구성 파일을 사용할 수 있습니다. 자세한 내용은 GitHub의 [Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)를 참고하세요.
`config-file-value`
사용자 정의 구성 파일의 원본입니다. `s3` 구성 파일 유형을 사용하는 경우 구성 파일 값은 Amazon S3 버킷 및 파일의 전체 ARN입니다. `file` 구성 파일 유형을 사용하는 경우 구성 파일 값은 컨테이너 이미지 또는 컨테이너에 마운트된 볼륨에 있는 구성 파일의 전체 경로입니다.
사용자 정의 구성 파일을 사용할 때는 FireLens가 사용하는 경로가 아닌 다른 경로를 지정해야 합니다. Amazon ECS는 Fluent Bit의 경우 `/fluent-bit/etc/fluent-bit.conf` 파일 경로를, Fluentd의 경우 `/fluentd/etc/fluent.conf` 파일 경로를 예약합니다.
다음 예에는 사용자 정의 구성을 지정할 때 필요한 구문이 나와 있습니다.
**중요**
Amazon S3에서 호스팅되는 사용자 정의 구성 파일을 지정하려면 적절한 권한이 있는 태스크 실행 IAM 역할을 생성했는지 확인하세요.
다음은 사용자 정의 구성을 지정할 때 필요한 구문입니다.
```
{
"containerDefinitions": [
{
"essential": true,
"image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:3",
"name": "log_router",
"firelensConfiguration": {
"type": "fluentbit",
"options": {
"config-file-type": "s3 | file",
"config-file-value": "arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf | filepath"
}
}
}
]
}
```
**참고**
AWS Fargate에 호스팅된 태스크는 `file` 구성 파일 유형만을 지원합니다. 하지만 AWS for Fluent Bit 초기화(init) 컨테이너를 사용하면 AWS Fargate에서 Amazon S3에 호스팅된 구성 파일을 사용할 수 있습니다. 자세한 내용은 GitHub의 [Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)를 참고하세요.
# Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용
프라이빗 레지스트리를 사용하여 AWS Secrets Manager에 자격 증명을 저장한 후 작업 정의에서 참조합니다. 이는 태스크 정의에서 인증이 필요한 AWS 외부의 프라이빗 레지스트리에 있는 컨테이너 이미지를 참조하는 방법을 제공합니다. 이 기능은 Fargate, Amazon EC2 인스턴스 및 Amazon ECS Anywhere를 사용하는 외부 인스턴스에서 호스팅되는 태스크에서 지원됩니다.
**중요**
태스크 정의가 Amazon ECR에 저장된 이미지를 참조하는 경우 이 주제가 적용되지 않습니다. 자세한 정보는 *Amazon Elastic Container Registry 사용 설명서*의 [Amazon ECS에서 Amazon ECR 이미지 사용](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_ECS.html)을 참조하세요.
Amazon EC2 인스턴스에서 호스팅되는 태스크의 경우 이 기능을 사용하려면 버전 `1.19.0` 이상의 컨테이너 에이전트가 있어야 합니다. 그러나 최신 버전의 컨테이너 에이전트를 사용하는 것이 좋습니다. 에이전트 버전을 확인하고 최신 버전으로 업데이트하는 방법에 대한 자세한 정보는 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요.
Fargate에서 호스팅되는 태스크의 경우 이 기능을 사용하려면 플랫폼 버전 `1.2.0` 이상이 필요합니다. 자세한 내용은 [Amazon ECS에 대한 Fargate 플랫폼 버전](platform-fargate.md) 섹션을 참조하세요.
컨테이너 정의에서 자신이 생성한 암호의 세부 정보와 함께 `repositoryCredentials` 객체를 지정합니다. 참조하는 보안 암호는 다른 AWS 리전 또는 이를 사용하는 태스크와 다른 계정에서 가져온 것일 수 있습니다.
**참고**
Amazon ECS API, AWS CLI 또는 AWS SDK를 사용할 때 시작하는 태스크와 같은 AWS 리전에 암호가 존재할 경우, 암호의 전체 ARN 또는 이름을 사용할 수 있습니다. 암호가 다른 계정에 있는 경우 암호의 전체 ARN을 지정해야 합니다. AWS Management Console을 사용할 때는 항상 암호의 전체 ARN을 지정해야 합니다.
다음은 필요한 파라미터를 나타낸 태스크 정의의 예제 조각입니다.
다음 파라미터를 대체합니다.
+ *private-repo*를 프라이빗 리포지토리 호스트 이름으로 대체
+ *private-image*를 이미지 이름으로 대체
+ *arn:aws:secretsmanager:region:aws\$1account\$1id:secret:secret\$1name*을 보안 암호의 Amazon 리소스 이름(ARN)으로 대체
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
**참고**
프라이빗 레지스트리 인증을 활성화할 수 있는 또 한 가지 방법은 Amazon ECS 컨테이너 에이전트 환경 변수를 사용해 프라이빗 레지스트리를 인증하는 것입니다. 이 방법은 Amazon EC2 인스턴스에서 호스팅되는 태스크에만 지원됩니다. 자세한 내용은 [프라이빗 Docker 이미지를 위한 Amazon ECS 컨테이너 인스턴스 구성](private-auth-container-instances.md) 섹션을 참조하세요.
**프라이빗 레지스트리를 사용하는 방법**
1. 태스크 정의에는 태스크 실행 역할이 있어야 합니다. 컨테이너 에이전트는 이 기능을 통해 컨테이너 이미지를 가져올 수 있습니다. 자세한 내용은 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
프라이빗 레지스트리 인증을 사용하면 Amazon ECS 태스크가 인증 자격 증명이 필요한 AWS 외부의 프라이빗 레지스트리(예: Docker Hub, Quay.io 또는 자체 프라이빗 레지스트리)에서 컨테이너 이미지를 가져올 수 있습니다. 이 기능은 Secrets Manager를 사용하여 레지스트리 자격 증명을 안전하게 저장한 다음, `repositoryCredentials` 파라미터를 사용하여 태스크 정의에서 참조합니다.
프라이빗 레지스트리 인증 구성에 대한 자세한 내용은 [Amazon ECS에서 AWS 외의 컨테이너 이미지 사용](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)을 참조하세요.
프라이빗 레지스트리 자격 증명이 포함된 암호에 액세스 권한을 부여하려면 다음 권한을 인라인 정책으로 태스크 실행 역할에 추가합니다. 자세한 정보는 [IAM 정책 추가 및 제거](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) 섹션을 참조하세요.
+ `secretsmanager:GetSecretValue` - Secrets Manager에서 프라이빗 레지스트리 자격 증명을 검색하는 데 필요합니다.
+ `kms:Decrypt` ― 암호가 사용자 지정 KMS 키를 사용하고 기본 키를 사용하지 않는 경우에 필요합니다. 사용자 지정 키의 Amazon 리소스 이름(ARN)을 리소스로 추가해야 합니다.
다음 예제에서는 인라인 정책이 권한을 추가합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:111122223333:secret:secret_name",
"arn:aws:kms:us-east-1:111122223333:key/key_id"
]
}
]
}
```
------
1. AWS Secrets Manager에서 프라이빗 레지스트리 자격 증명에 사용할 암호를 생성합니다. 보안 암호 생성 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)을 참조하세요.
다음 형식을 사용하여 프라이빗 레지스트리 자격 증명을 입력합니다.
```
{
"username" : "privateRegistryUsername",
"password" : "privateRegistryPassword"
}
```
1. 태스크 정의 등록. 자세한 내용은 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 섹션을 참조하세요.
# 컨테이너 재시작 정책이 있는 Amazon ECS 작업의 개별 컨테이너 재시작
태스크 정의에 정의된 각 필수 및 비필수 컨테이너에 대한 재시작 정책을 사용하여 일시적 장애를 더 빠르게 극복하고 태스크 가용성을 유지할 수 있습니다. 컨테이너의 재시작 정책을 활성화하면 Amazon ECS에서 컨테이너가 종료되면 작업을 교체할 필요 없이 컨테이너를 다시 시작할 수 있습니다.
컨테이너에는 기본적으로 재시작 정책이 활성화되어 있지 않습니다. 컨테이너에 대한 재시작 정책을 활성화하면 컨테이너를 다시 시작하지 않을 종료 코드를 지정할 수 있습니다. 이는 성공을 나타내는 종료 코드일 수 있으며(예: 종료 코드 `0`), 이는 다시 시작할 필요가 없습니다. 컨테이너를 성공적으로 실행해야 재시작을 시도할 수 있는 기간도 지정할 수 있습니다. 이런 파라미터에 대한 자세한 내용은 [재시작 정책](task_definition_parameters.md#container_definition_restart_policy) 섹션을 참조하세요. 이러한 값을 지정하는 작업 정의의 예는 [Amazon ECS 작업 정의에서 컨테이너 재시작 정책 지정](container-restart-policy-example.md) 섹션을 참조하세요.
Amazon ECS 작업 메타데이터 엔드포인트 또는 CloudWatch 컨테이너 인사이트를 사용하여 컨테이너가 재시작된 횟수를 모니터링할 수 있습니다. 태스크 메타데이터 엔드포인트에 관한 자세한 내용은 [Amazon ECS 작업 메타데이터 엔드포인트 버전 4](task-metadata-endpoint-v4.md) 및 [Fargate의 작업에 대한 Amazon ECS 작업 메타데이터 엔드포인트 버전 4](task-metadata-endpoint-v4-fargate.md) 섹션을 참조하세요. Amazon ECS의 Container Insights 지표에 관한 자세한 내용은 *Amazon CloudWatch 사용자 설명서*의 [Amazon ECS Container Insights 지표](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-metrics-ECS.html)를 참조하세요.
컨테이너 재시작 정책은 Fargate, Amazon EC2 인스턴스 및 Amazon ECS Anywhere를 사용하는 외부 인스턴스에서 호스팅되는 태스크에서 지원됩니다.
## 고려 사항
컨테이너에 대해 재시작 정책을 활성화하기 전에 다음 사항을 고려합니다.
+ Fargate에서 Windows 컨테이너에는 재시작 정책이 지원되지 않습니다.
+ Amazon EC2 인스턴스에서 호스팅되는 태스크의 경우 이 기능을 사용하려면 버전 `1.86.0` 이상의 컨테이너 에이전트가 있어야 합니다. 그러나 최신 버전의 컨테이너 에이전트를 사용하는 것이 좋습니다. 에이전트 버전을 확인하고 최신 버전으로 업데이트하는 방법에 대한 자세한 정보는 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요.
+ `bridge` 네트워크 모드에서 EC2를 사용하는 경우 FireLens 로그 라우터 컨테이너(컨테이너 정의에 `firelensConfiguration` 객체가 있는 컨테이너)를 다시 시작한 후 애플리케이션 컨테이너의 `FLUENT_HOST` 환경 변수가 부정확해질 수 있습니다. 이는 `FLUENT_HOST`가 동적 IP 주소이며 재시작 후 변경될 수 있기 때문입니다. 애플리케이션 컨테이너에서 `FLUENT_HOST` IP 주소로 직접 로깅하면 주소가 변경된 후 실패하기 시작할 수 있습니다. `FLUENT_HOST`에 대한 자세한 정보는 [높은 처리량을 위한 Amazon ECS 로그 구성](firelens-docker-buffer-limit.md) 섹션을 참조하세요.
+ Amazon ECS 에이전트는 컨테이너 재시작 정책을 처리합니다. 예상치 못한 이유로 Amazon ECS 에이전트가 실패하거나 더 이상 실행되지 않는 경우 컨테이너가 재시작되지 않습니다.
+ 정책에 정의된 재시작 시도 기간에 따라 Amazon ECS가 컨테이너를 재시작하기 전에 컨테이너가 실행되어야 하는 시간(초)이 결정됩니다.
# Amazon ECS 작업 정의에서 컨테이너 재시작 정책 지정
작업 정의에서 컨테이너의 재시작 정책을 지정하려면 컨테이너 정의 내에서 `restartPolicy` 객체를 지정합니다. `restartPolicy` 객체에 대한 자세한 정보는 [재시작 정책](task_definition_parameters.md#container_definition_restart_policy) 섹션을 참조하세요.
다음은 웹 서버를 설정하는 Fargate에서 Linux 컨테이너를 사용하는 태스크 정의입니다. 컨테이너 정의에는 `restartPolicy` 객체가 포함되며, 컨테이너의 재시작 정책을 활성화하려면 true로 `enabled`가 설정됩니다. 컨테이너를 180초 동안 실행해야 다시 시작할 수 있으며, 성공했음을 나타내는 종료 코드 `0`과 함께 종료되면 다시 시작되지 않습니다.
```
{
"containerDefinitions": [
{
"command": [
"/bin/sh -c \"echo ' Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
' > /usr/local/apache2/htdocs/index.html && httpd-foreground\""
],
"entryPoint": ["sh", "-c"],
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:2.4",
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/fargate-task-definition",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
},
"name": "sample-fargate-app",
"portMappings": [
{
"containerPort": 80,
"hostPort": 80,
"protocol": "tcp"
}
],
"restartPolicy": {
"enabled": true,
"ignoredExitCodes": [0],
"restartAttemptPeriod": 180
}
}
],
"cpu": "256",
"executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
"family": "fargate-task-definition",
"memory": "512",
"networkMode": "awsvpc",
"runtimePlatform": {
"operatingSystemFamily": "LINUX"
},
"requiresCompatibilities": ["FARGATE"]
}
```
컨테이너 정의에서 `restartPolicy` 객체로 작업 정의를 등록한 후 해당 작업 정의를 사용하여 작업을 실행하거나 서비스를 생성할 수 있습니다. 자세한 내용은 [애플리케이션을 Amazon ECS 태스크로 실행](standalone-task-create.md) 및 [Amazon ECS 롤링 업데이트 배포 생성](create-service-console-v2.md)(을)를 참조하세요.
# Amazon ECS 컨테이너로 민감한 데이터 전달
데이터베이스의 보안 인증과 같은 중요 데이터를 컨테이너로 안전하게 전달할 수 있습니다.
API 키 및 데이터베이스 보안 인증과 같은 보안 암호는 애플리케이션이 다른 시스템에 액세스하는 데 자주 사용됩니다. 일반적으로 보안 암호는 사용자 이름과 암호, 인증서 또는 API 키로 구성됩니다. 이러한 보안 암호는 IAM을 사용하는 특정 IAM 보안 주체로 액세스를 제한하고 런타임 시 컨테이너에 주입해야 합니다.
AWS Secrets Manager 및 Amazon EC2 Systems Manager Parameter Store에서 컨테이너에 보안 암호를 원활하게 주입할 수 있습니다. 이러한 보안 암호는 작업에서 다음 중 하나로 참조할 수 있습니다.
1. `secrets` 컨테이너 정의 파라미터를 사용하는 환경 변수로 참조합니다.
1. 로깅 플랫폼에 인증이 필요한 경우 `secretOptions`로 참조합니다. 자세한 내용은 [logging configuration options](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html#API_LogConfiguration_Contents)를 참조하세요.
1. 컨테이너가 풀되는 레지스트리에 인증이 필요한 경우 `repositoryCredentials` 컨테이너 정의 파라미터를 사용하여 이미지에 의해 풀되는 보안 암호로 참조합니다. Amazon ECR 퍼블릭 갤러리에서 이미지를 풀할 때 이 방법을 사용합니다. 자세한 내용은 [Private registry authentication for tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)를 참조하세요.
보안 암호 관리를 설정할 때 다음을 수행하는 것이 좋습니다.
## AWS Secrets Manager 또는 AWS Systems Manager Parameter Store를 사용하여 보안 암호 자료 저장
API 키, 데이터베이스 자격 증명 및 기타 보안 암호 자료를 안전하게 Secrets Manager에 저장하거나 Systems Manager Parameter Store에 암호화된 파라미터로 저장해야 합니다. 두 서비스 모두 민감한 데이터를 암호화하는 AWS KMS를 사용하는 관리형 키-값 저장소라는 점에서 유사합니다. 하지만 Secrets Manager는 보안 암호를 자동으로 교체하고, 보안 암호를 무작위로 생성하고, 계정 간에 보안 암호를 공유하는 기능도 포함합니다. 이러한 기능을 활용하려면 Secrets Manager를 사용합니다. 그렇지 않으면 Systems Manager Parameter Store에서 암호화된 파라미터를 사용합니다.
**중요**
보안 암호가 변경되면 새 배포를 강제로 적용하고 새 작업을 시작하여 최신 보안 암호 값을 검색해야 합니다. 자세한 내용은 다음 항목을 참조하세요.
태스크 - 태스크를 중지했다가 시작합니다. 자세한 내용은 [Amazon ECS 태스크 중지](standalone-task-stop.md) 및 [애플리케이션을 Amazon ECS 태스크로 실행](standalone-task-create.md)(을)를 참조하세요.
서비스 - 서비스를 업데이트하고 새 배포 강제 적용 옵션을 사용합니다. 자세한 내용은 [Amazon ECS 서비스 업데이트](update-service-console-v2.md) 섹션을 참조하세요.
## 암호화된 Amazon S3 버킷에서 데이터 검색
보안 암호를 암호화된 Amazon S3 버킷에 저장하고 작업 역할을 사용하여 이러한 보안 암호에 대한 액세스를 제한해야 합니다. 이렇게 하면 환경 변수 값이 실수로 로그에 누출되어 `docker inspect`를 실행할 때 표시되는 문제를 방지할 수 있습니다. 이렇게 하는 경우, Amazon S3 버킷에서 보안 암호를 읽도록 애플리케이션을 작성해야 합니다. 자세한 내용은 [Amazon S3 버킷에 대한 기본 서버 측 암호화 동작 설정](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-encryption.html)을 참조하세요.
## 사이드카 컨테이너를 사용하여 보안 암호를 볼륨에 마운트
환경 변수를 사용하면 데이터 누출 위험이 높아지므로 보안 암호를 AWS Secrets Manager에서 읽고 공유 볼륨에 쓰는 사이드카 컨테이너를 실행해야 합니다. [Amazon ECS 컨테이너 순서](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html)를 사용하면 이 컨테이너를 애플리케이션 컨테이너보다 먼저 실행하고 종료할 수 있습니다. 이렇게 하면 이후 애플리케이션 컨테이너는 보안 암호가 기록된 볼륨을 마운트합니다. Amazon S3 버킷 방법과 마찬가지로 공유 볼륨에서 보안 암호를 읽도록 애플리케이션을 작성해야 합니다. 이 볼륨은 범위가 작업으로 지정되므로 작업이 중지되면 자동으로 삭제됩니다. 예제는 [task-def.json](https://github.com/aws-samples/aws-secret-sidecar-injector/blob/master/ecs-task-def/task-def.json) 프로젝트를 참조하세요.
Amazon EC2에서는 보안 암호가 기록되는 볼륨을 AWS KMS 고객 관리형 키로 암호화할 수 있습니다. AWS Fargate에서는 서비스 관리형 키를 사용하여 볼륨 스토리지를 자동으로 암호화합니다.
# 개별 환경 변수를 Amazon ECS 컨테이너로 전달
**중요**
민감한 데이터는 AWS Secrets Manager 암호 또는 AWS Systems Manager 파라미터 스토어 파라미터에 저장하는 것이 좋습니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
작업 정의에 지정된 환경 변수는 작업 정의에 대해 `DescribeTaskDefinition` 작업이 허용된 모든 사용자 및 역할에서 읽을 수 있습니다.
환경 변수는 다음과 같은 방법으로 컨테이너에 전달할 수 있습니다.
+ `environment` 컨테이너 정의 파라미터를 개별적으로 사용합니다. 이것은 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/)에 대한 `--env` 옵션에 매핑됩니다.
+ 대량으로 `environmentFiles` 컨테이너 정의 파라미터를 사용하여 환경 변수를 포함하는 하나 이상의 파일을 나열합니다. 파일은 Amazon S3에서 호스팅되어야 합니다. 이것은 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/)에 대한 `--env-file` 옵션에 매핑됩니다.
다음은 개별 환경 변수를 지정하는 방법을 보여주는 태스크 정의의 조각입니다.
```
{
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
...
"environment": [
{
"name": "variable",
"value": "value"
}
],
...
}
],
...
}
```
# 환경 변수를 Amazon ECS 컨테이너로 전달
**중요**
민감한 데이터는 AWS Secrets Manager 암호 또는 AWS Systems Manager 파라미터 스토어 파라미터에 저장하는 것이 좋습니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
환경 변수 파일은 Amazon S3의 객체이며 모든 Amazon S3 보안 고려 사항이 적용됩니다.
Windows 컨테이너와 Fargate의 Windows 컨테이너에서는 `environmentFiles` 파라미터를 사용할 수 없습니다.
환경 변수 파일을 생성하고 Amazon S3에 저장하여 컨테이너로 환경 변수를 전달할 수 있습니다.
파일에 환경 변수를 지정하여 환경 변수를 대량으로 주입할 수 있습니다. 컨테이너 정의 내에서 환경 변수 파일이 포함된 Amazon S3 버킷 목록을 이용해 `environmentFiles` 객체를 지정합니다.
Amazon ECS는 환경 변수에 크기 제한을 적용하지 않지만 용량이 큰 환경 변수 파일로 인해 디스크 스페이스가 가득 찰 수도 있습니다. 환경 변수 파일을 사용하는 각 태스크는 해당 파일 사본을 디스크에 다운로드합니다. Amazon ECS에서는 작업 정리의 일부로 파일을 제거합니다.
지원되는 환경 변수에 대한 자세한 내용은 [Advanced container definition parameters- Environment](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_environment)를 참조하세요.
컨테이너 정의에서 환경 변수 파일을 지정할 때는 다음 사항을 고려합니다.
+ Amazon EC2에 있는 Amazon ECS 태스크의 경우 이 기능을 사용하기 위해 컨테이너 인스턴스에 버전 `1.39.0` 이상의 컨테이너 에이전트가 필요합니다. 에이전트 버전을 확인하고 최신 버전으로 업데이트하는 방법에 대한 자세한 정보는 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요.
+ AWS Fargate에 있는 Amazon ECS 태스크의 경우 이 기능을 사용하기 위해 플랫폼 버전 `1.4.0` 이상(Linux)을 사용해야 합니다. 자세한 내용은 [Amazon ECS에 대한 Fargate 플랫폼 버전](platform-fargate.md) 섹션을 참조하세요.
변수가 운영 체제 플랫폼에 대해 지원되는지 확인합니다. 자세한 내용은 [컨테이너 정의](task_definition_parameters.md#container_definitions) 및 [기타 태스크 정의 파라미터](task_definition_parameters.md#other_task_definition_params) 단원을 참조하세요.
+ 파일은 `.env` 파일 확장명과 UTF-8 인코딩을 사용해야 합니다.
+ 태스크 실행 역할은 Amazon S3에 대한 추가 권한과 함께 이 기능을 사용해야 합니다. 이렇게 하면 컨테이너 에이전트가 Amazon S3에서 환경 변수 파일을 가져올 수 있습니다. 자세한 내용은 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
+ 작업 정의당 파일 수는 10개로 제한됩니다.
+ 환경 파일의 각 줄에는 `VARIABLE=VALUE` 형식의 환경 변수를 포함합니다. 공백이나 인용 부호는 Amazon ECS 파일 값의 일부로 **포함됩니다**. `#`으로 시작하는 줄은 주석으로 처리되며 무시됩니다. 환경 변수 파일 구문에 대한 자세한 내용은 Docker 설명서의 [환경 변수 설정(-e, --env, --env-file)](https://docs.docker.com/reference/cli/docker/container/run/#env)을 참조하세요.
다음은 적절한 구문입니다.
```
#This is a comment and will be ignored
VARIABLE=VALUE
ENVIRONMENT=PRODUCTION
```
+ 컨테이너 정의에서 `environment` 파라미터를 사용하여 지정된 환경 변수가 있는 경우 환경 파일 내에 포함된 변수보다 우선합니다.
+ 여러 환경 파일이 지정되고 동일한 변수를 포함하는 경우 입력 순서대로 처리됩니다. 즉, 변수의 첫 번째 값이 사용되고 중복 변수의 후속 값은 무시됩니다. 고유한 변수 이름을 사용하는 것이 좋습니다.
+ 환경 파일이 컨테이너 재정의로 지정된 경우 해당 파일이 사용됩니다. 또한 컨테이너 정의에 지정된 다른 환경 파일은 무시됩니다.
+ Fargate에는 다음 규칙이 적용됩니다.
+ 파일은 네이티브 Docker env 파일과 유사하게 처리됩니다.
+ 비어 있는 상태로 Amazon S3에 저장된 환경 변수를 참조하는 컨테이너 정의는 컨테이너에 표시되지 않습니다.
+ 셸 이스케이프 처리는 지원되지 않습니다.
+ 컨테이너 진입점은 `VARIABLE` 값을 해석합니다.
## 예제
다음은 환경 변수 파일을 지정하는 방법을 보여주는 태스크 정의의 조각입니다.
```
{
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
...
"environmentFiles": [
{
"value": "arn:aws:s3:::amzn-s3-demo-bucket/envfile_object_name.env",
"type": "s3"
}
],
...
}
],
...
}
```
# Amazon ECS에서 프로그래밍 방식으로 Secrets Manager 보안 암호 전달
애플리케이션에서 민감한 정보를 일반 텍스트로 하드 코딩하는 대신, Secrets Manager를 사용하여 민감한 데이터를 저장할 수 있습니다.
중요 데이터를 검색할 때 이 방법을 권장하는 이유는 이후에 Secrets Manager 보안 암호가 업데이트되면 애플리케이션이 자동으로 최신 버전의 보안 암호를 검색하기 때문입니다.
Secrets Manager에서 보안 암호를 생성합니다. Secrets Manager 보안 암호를 생성한 후 애플리케이션 코드를 업데이트하여 보안 암호를 검색하세요.
Secrets Manager에서 중요 데이터를 보호하기 전에 다음 고려 사항을 검토하세요.
+ [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) API의 `SecretString` 파라미터로 생성된 암호이며 텍스트 데이터를 저장하는 암호만이 지원됩니다. 이진 데이터를 저장하는 보안 암호([CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) API의 `SecretBinary` 파라미터로 생성된 보안 암호임)는 지원되지 않습니다.
+ 인터페이스 VPC 엔드포인트를 사용하여 보안 제어를 강화합니다. Secrets Manager용 인터페이스 VPC 엔드포인트를 생성해야 합니다. VPC 엔드포인트에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [VPC 종단점 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/setup-create-vpc.html)을 참조하세요.
+ 작업에서 사용하는 VPC는 DNS 확인을 사용해야 합니다.
+ 태스크 정의에서 Secrets Manager에 대한 추가 권한을 보유한 태스크 역할을 사용해야 합니다. 자세한 내용은 [Amazon ECS 작업 IAM 역할](task-iam-roles.md) 섹션을 참조하세요.
## Secrets Manager 보안 암호 생성
Secrets Manager 콘솔을 사용하여 민감한 데이터에 대한 암호를 생성할 수 있습니다. 보안 암호 생성 방법에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [AWS Secrets Manager 보안 암호 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)을 참조하세요.
## 애플리케이션을 업데이트하여 프로그래밍 방식으로 Secrets Manager 보안 암호 검색
애플리케이션에서 직접 Secrets Manager API를 호출하여 보안 암호를 검색할 수 있습니다. 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [Retrieve secrets from AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)를 참조하세요.
AWS Secrets Manager에 저장된 민감한 데이터를 검색하려면 *AWS SDK 코드 예제 코드 라이브러리*의 [Code examples for AWS Secrets Manager using AWS SDKs](https://docs.aws.amazon.com/code-library/latest/ug/secrets-manager_code_examples.html)를 참조하세요.
# Amazon ECS에서 프로그래밍 방식으로 Systems Manager Parameter Store 보안 암호 전달
Systems Manager Parameter Store는 보안 저장 및 보안 암호 관리 기능을 제공합니다. 애플리케이션에 이 정보를 하드 코딩하는 대신 암호, 데이터베이스 문자열, EC2 인스턴스 ID, AMI ID, 라이선스 코드와 같은 데이터를 파라미터 값으로 저장할 수 있습니다. 값을 일반 텍스트 또는 암호화된 데이터로 저장할 수 있습니다.
민감한 데이터를 검색할 때 이 방법을 권장하는 이유는 이후에 Secrets Manager Parameter Store 파라미터가 업데이트되면 애플리케이션이 자동으로 최신 버전을 검색하기 때문입니다.
Systems Manager Parameter Store에서 중요 데이터를 보호하기 전에 다음 고려 사항을 검토하세요.
+ 텍스트 데이터를 저장하는 보안 암호만 지원됩니다. 이진 데이터를 저장하는 보안 암호는 지원되지 않습니다.
+ 인터페이스 VPC 엔드포인트를 사용하여 보안 제어를 강화합니다.
+ 작업에서 사용하는 VPC는 DNS 확인을 사용해야 합니다.
+ EC2를 사용하는 태스크의 경우 이 기능을 사용하려면 Amazon ECS 에이전트 구성 변수인 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true`를 사용해야 합니다. 컨테이너 인스턴스를 생성할 때 이를 `/etc/ecs/ecs.config` 파일에 추가하거나 기존 인스턴스에 추가한 다음 ECS 에이전트를 다시 시작할 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) 섹션을 참조하세요.
+ 태스크 정의에서 Systems Manager Parameter Store에 대한 추가 권한을 보유한 태스크 역할을 사용해야 합니다. 자세한 내용은 [Amazon ECS 작업 IAM 역할](task-iam-roles.md) 섹션을 참조하세요.
## 파라미터 생성
Systems Manager 콘솔을 사용하면 중요 데이터에 대한 Systems Manager Parameter Store 파라미터를 생성할 수 있습니다. 자세한 내용은 *AWS Systems Manager 사용 설명서*의 [Systems Manager 파라미터 생성(콘솔)](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-create-console.html) 또는 [Systems Manager 파라미터 생성(AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html)을 참조하세요.
## 애플리케이션을 업데이트하여 프로그래밍 방식으로 Systems Manager Parameter Store 보안 암호 검색
Systems Manager Parameter Store 파라미터에 저장된 민감한 데이터를 검색하려면 *AWS SDK 코드 예제 코드 라이브러리*의 [Code examples for Systems Manager using AWS SDKs](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html)를 참조하세요.
# Amazon ECS 환경 변수를 통해 Secrets Manager 보안 암호 전달
암호를 환경 변수로 주입하는 경우 암호의 전체 내용, 암호 내 특정 JSON 키를 지정할 수 있습니다. 이는 컨테이너에 노출되는 민감한 데이터를 제어하는 데 도움이 됩니다. 암호 버전 관리에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [Secrets Manager에는 무엇이 있습니까?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/whats-in-a-secret.html#term_version)를 참조하세요.
환경 변수를 사용하여 컨테이너에 Secrets Manager 보안 암호를 삽입할 때 다음을 고려해야 합니다.
+ 컨테이너가 처음 시작될 때 해당 컨테이너에 중요한 정보가 주입됩니다. 암호가 이후에 업데이트되거나 교체되면 컨테이너가 업데이트된 값을 자동으로 받지 않습니다. 새 태스크를 시작해야 하거나 작업이 서비스의 일부인 경우 서비스를 업데이트하고 **새 배포 강제 적용**을 사용하여 서비스에서 새 태스크를 시작하도록 강제로 지정할 수 있습니다.
+ 컨테이너에서 실행되는 애플리케이션, 컨테이너 로그 및 디버깅 도구는 환경 변수에 액세스할 수 있습니다.
+ AWS Fargate에서의 Amazon ECS 태스크의 경우 다음 사항을 고려합니다.
+ 암호의 전체 내용을 환경 변수 또는 로그 구성으로 주입하려면 플랫폼 버전 `1.3.0` 이상을 사용해야 합니다. 자세한 내용은 [Amazon ECS에 대한 Fargate 플랫폼 버전](platform-fargate.md) 섹션을 참조하세요.
+ 암호의 JSON 키 또는 버전을 환경 변수 또는 로그 구성으로 주입하려면 플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0`(Windows)을 사용해야 합니다. 자세한 내용은 [Amazon ECS에 대한 Fargate 플랫폼 버전](platform-fargate.md) 섹션을 참조하세요.
+ EC2에서의 Amazon ECS 태스크의 경우 다음 사항을 고려해야 합니다.
+ 암호의 특정 JSON 키 또는 버전을 사용하여 암호를 주입하려면 컨테이너 인스턴스에 컨테이너 에이전트 버전 `1.37.0` 이상이 있어야 합니다. 그러나 최신 버전의 컨테이너 에이전트를 사용하는 것이 좋습니다. 에이전트 버전을 확인하고 최신 버전으로 업데이트하는 방법에 대한 자세한 내용은 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요.
암호의 전체 내용을 환경 변수로 주입하거나 로그 구성에 암호를 주입하려면 컨테이너 인스턴스에 컨테이너 에이전트 버전 `1.22.0` 이상이 있어야 합니다.
+ 인터페이스 VPC 엔드포인트를 사용하여 보안 제어를 향상하고 프라이빗 서브넷을 통해 Secrets Manager에 연결합니다. Secrets Manager용 인터페이스 VPC 엔드포인트를 생성해야 합니다. VPC 엔드포인트에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [VPC 종단점 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/setup-create-vpc.html)을 참조하세요. Secrets Manager 및 Amazon VPC 사용에 대한 자세한 내용은 [How to connect to Secrets Manager service within a Amazon VPC](https://aws.amazon.com/blogs//security/how-to-connect-to-aws-secrets-manager-service-within-a-virtual-private-cloud/)를 참조하세요.
+ `awslogs` 로깅 드라이버를 사용하도록 구성된 Windows 태스크의 경우 컨테이너 인스턴스에 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` 환경 변수도 설정해야 합니다. 다음 구문을 사용합니다.
```
[Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
Initialize-ECSAgent -Cluster -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
```
+ 태스크 정의에서 Secrets Manager에 대한 추가 권한을 보유한 작업 실행 역할을 사용해야 합니다. 자세한 내용은 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
## AWS Secrets Manager 보안 암호 생성
Secrets Manager 콘솔을 사용하여 민감한 데이터에 대한 암호를 생성할 수 있습니다. 자세한 정보는 *AWS Secrets Manager 사용 설명서*의 [AWS Secrets Manager 보안 암호 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)을 참조하세요.
## 컨테이너 정의에 환경 변수 추가
컨테이너 정의 내에서 다음을 지정할 수 있습니다.
+ 컨테이너에 설정할 환경 변수의 이름을 포함하는 `secrets` 객체
+ Secrets Manager 암호의 Amazon 리소스 이름(ARN)
+ 컨테이너에 제공할 중요한 데이터를 포함하는 추가 파라미터
다음 예제에서는 Secrets Manager 암호에 대해 지정해야 하는 전체 구문을 보여 줍니다.
```
arn:aws:secretsmanager:region:aws_account_id:secret:secret-name:json-key:version-stage:version-id
```
다음 섹션에서는 추가 파라미터에 대해 설명합니다. 이러한 파라미터는 선택 사항이지만 사용하지 않는 경우 기본값을 사용하려면 콜론(`:`)을 포함시켜야 합니다. 추가 컨텍스트에 대한 예제가 아래에 나와 있습니다.
`json-key`
환경 변수 값으로 설정할 값과 함께 키-값 쌍의 키 이름을 지정합니다. JSON 형식의 값만 지원됩니다. JSON 키를 지정하지 않으면 암호의 전체 내용이 사용됩니다.
`version-stage`
사용할 암호 버전의 스테이징 레이블을 지정합니다. 버전 스테이징 레이블이 지정된 경우 버전 ID를 지정할 수 없습니다. 버전 단계가 지정되지 않은 경우 기본 동작은 `AWSCURRENT` 스테이징 레이블을 사용하여 암호를 검색하는 것입니다.
스테이징 레이블은 암호가 업데이트되거나 교체되는 경우 암호의 여러 버전을 추적하는 데 사용됩니다. 암호의 각 버전에는 하나 이상의 스테이징 레이블과 ID가 있습니다.
`version-id`
사용하고자 하는 암호 버전의 고유 식별자를 지정합니다. 버전 ID가 지정된 경우 버전 스테이징 레이블을 지정할 수 없습니다. 버전 ID가 지정되지 않은 경우 기본 동작은 `AWSCURRENT` 스테이징 레이블을 사용하여 암호를 검색하는 것입니다.
버전 ID는 암호가 업데이트되거나 교체되는 경우 암호의 여러 버전을 추적하는 데 사용됩니다. 암호의 각 버전에는 ID가 있습니다. 자세한 정보는 *AWS Secrets Manager 사용 설명서*의 [AWS Secrets Manager의 주요 개념 및 용어](https://docs.aws.amazon.com/secretsmanager/latest/userguide/terms-concepts.html#term_secret)를 참조하세요.
### 컨테이너 정의 예제
다음 예제에서는 컨테이너 정의에서 Secretes Manager 암호를 참조할 수 있는 방법을 보여 줍니다.
**Example 전체 암호 참조**
다음은 Secret Manager 암호의 전체 텍스트를 참조할 때 형식을 나타내는 태스크 정의의 조각입니다.
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
}]
}]
}
```
컨테이너 내에서 이 보안 암호의 값에 액세스하려면 `$environment_variable_name` 변수를 호출해야 합니다.
**Example 전체 시크릿 참조**
다음은 여러 Secret Manager 시크릿의 전체 텍스트를 참조할 때 형식을 나타내는 태스크 정의의 조각입니다.
```
{
"containerDefinitions": [{
"secrets": [
{
"name": "environment_variable_name1",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
},
{
"name": "environment_variable_name2",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-abcdef"
},
{
"name": "environment_variable_name3",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-ABCDEF"
}
]
}]
}
```
컨테이너 내에서 이 시크릿의 값에 액세스하려면 `$environment_variable_name1`, `$environment_variable_name2`, `$environment_variable_name3`을 직접적으로 호출해야 합니다.
**Example 암호 내에서 특정 키 참조**
다음은 암호의 내용을 관련 버전 스테이징 레이블 및 버전 ID와 함께 표시하는 [get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html) 명령의 출력 예를 보여 줍니다.
```
{
"ARN": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf",
"Name": "appauthexample",
"VersionId": "871d9eca-18aa-46a9-8785-981ddEXAMPLE",
"SecretString": "{\"username1\":\"password1\",\"username2\":\"password2\",\"username3\":\"password3\"}",
"VersionStages": [
"AWSCURRENT"
],
"CreatedDate": 1581968848.921
}
```
ARN 끝에 키 이름을 지정하여 컨테이너 정의에서 이전 출력의 특정 키를 참조합니다.
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1::"
}]
}]
}
```
**Example 특정 비밀 버전 참조**
다음은 암호의 암호화되지 않은 내용을 모든 버전의 암호에 대한 메타데이터와 함께 표시하는 [describe-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/describe-secret.html) 명령의 출력 예입니다.
```
{
"ARN": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf",
"Name": "appauthexample",
"Description": "Example of a secret containing application authorization data.",
"RotationEnabled": false,
"LastChangedDate": 1581968848.926,
"LastAccessedDate": 1581897600.0,
"Tags": [],
"VersionIdsToStages": {
"871d9eca-18aa-46a9-8785-981ddEXAMPLE": [
"AWSCURRENT"
],
"9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE": [
"AWSPREVIOUS"
]
}
}
```
ARN 끝에 키 이름을 지정하여 컨테이너 정의에서 이전 출력의 특정 버전 스테이징 레이블을 참조합니다.
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf::AWSPREVIOUS:"
}]
}]
}
```
ARN 끝에 키 이름을 지정하여 컨테이너 정의에서 이전 출력의 특정 버전 ID를 참조합니다.
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:::9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE"
}]
}]
}
```
**Example 암호의 특정 키 및 버전 스테이징 레이블 참조**
다음은 암호 내 특정 키와 특정 버전 스테이징 레이블을 모두 참조하는 방법을 보여줍니다.
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1:AWSPREVIOUS:"
}]
}]
}
```
특정 키 및 버전 ID를 지정하려면 다음 구문을 사용합니다.
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1::9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE"
}]
}]
}
```
환경 변수에 지정된 보안 암호를 사용하여 태스크 정의를 생성하는 방법에 대한 자세한 내용은 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 섹션을 참조하세요.
# Amazon ECS 환경 변수를 통해 Systems Manager 파라미터 전달
Amazon ECS를 사용하면 AWS Systems Manager Parameter Store 파라미터에 민감한 데이터를 저장한 후 컨테이너 정의에서 참조하여 컨테이너에 민감한 데이터를 주입할 수 있습니다.
환경 변수를 사용하여 Systems Manager 보안 암호를 컨테이너에 주입할 때 다음을 고려하세요.
+ 컨테이너가 처음 시작될 때 해당 컨테이너에 중요한 정보가 주입됩니다. 암호가 이후에 업데이트되거나 교체되면 컨테이너가 업데이트된 값을 자동으로 받지 않습니다. 새 태스크를 시작해야 하거나 작업이 서비스의 일부인 경우 서비스를 업데이트하고 **새 배포 강제 적용**을 사용하여 서비스에서 새 태스크를 시작하도록 강제로 지정할 수 있습니다.
+ AWS Fargate에서의 Amazon ECS 태스크의 경우 다음 사항을 고려해야 합니다.
+ 암호의 전체 내용을 환경 변수 또는 로그 구성으로 주입하려면 플랫폼 버전 `1.3.0` 이상을 사용해야 합니다. 자세한 내용은 [Amazon ECS에 대한 Fargate 플랫폼 버전](platform-fargate.md) 섹션을 참조하세요.
+ 암호의 JSON 키 또는 버전을 환경 변수 또는 로그 구성으로 주입하려면 플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0`(Windows)을 사용해야 합니다. 자세한 내용은 [Amazon ECS에 대한 Fargate 플랫폼 버전](platform-fargate.md) 섹션을 참조하세요.
+ EC2에서의 Amazon ECS 태스크의 경우 다음 사항을 고려해야 합니다.
+ 암호의 특정 JSON 키 또는 버전을 사용하여 암호를 주입하려면 컨테이너 인스턴스에 컨테이너 에이전트 버전 `1.37.0` 이상이 있어야 합니다. 그러나 최신 버전의 컨테이너 에이전트를 사용하는 것이 좋습니다. 에이전트 버전을 확인하고 최신 버전으로 업데이트하는 방법에 대한 자세한 내용은 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요.
암호의 전체 내용을 환경 변수로 주입하거나 로그 구성에 암호를 주입하려면 컨테이너 인스턴스에 컨테이너 에이전트 버전 `1.22.0` 이상이 있어야 합니다.
+ 인터페이스 VPC 엔드포인트를 사용하여 보안 제어를 강화합니다. Systems Manager용 인터페이스 VPC 엔드포인트를 생성해야 합니다. VPC 엔드포인트에 대한 자세한 내용은 *AWS Systems Manager 사용 설명서*의 [Systems Manager용 VPC 엔드포인트를 사용하여 EC2 인스턴스의 보안 개선](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-create-vpc.html)을 참조하세요.
+ 태스크 정의에서는 Systems Manager Parameter Store에 대한 추가 권한을 보유한 태스크 실행 역할을 사용해야 합니다. 자세한 내용은 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
+ `awslogs` 로깅 드라이버를 사용하도록 구성된 Windows 태스크의 경우 컨테이너 인스턴스에 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` 환경 변수도 설정해야 합니다. 다음 구문을 사용합니다.
```
[Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
Initialize-ECSAgent -Cluster -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
```
## Systems Manager 파라미터 생성
Systems Manager 콘솔을 사용하면 중요 데이터에 대한 Systems Manager Parameter Store 파라미터를 생성할 수 있습니다. 자세한 내용은 **AWS Systems Manager 사용 설명서의 [Systems Manager 파라미터 생성(콘솔)](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-create-console.html) 또는 [Systems Manager 파라미터 생성(AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html)을 참조하세요.
## 컨테이너 정의에 환경 변수 추가
태스크 정의의 컨테이너 정의 내에서 컨테이너에 설정할 환경 변수의 이름으로 `secrets`를 지정하여 컨테이너에 제공할 민감한 데이터가 들어있는 Systems Manager Parameter Store 파라미터의 전체 ARN을 지정합니다. 자세한 내용은 [secrets](task_definition_parameters.md#ContainerDefinition-secrets) 섹션을 참조하세요.
다음은 Systems Manager 파라미터 스토어 파라미터를 참조할 때 형식을 나타내는 태스크 정의의 조각입니다. Systems Manager 파라미터 스토어 파라미터가 현재 실행 중인 태스크와 동일한 리전에 있는 경우, 파라미터의 전체 ARN 또는 이름을 사용할 수 있습니다. 파라미터가 다른 리전에 있다면 전체 ARN을 지정합니다.
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}]
}]
}
```
환경 변수에 지정된 보안 암호를 사용하여 태스크 정의를 생성하는 방법에 대한 자세한 내용은 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 섹션을 참조하세요.
## 애플리케이션을 업데이트하여 프로그래밍 방식으로 Systems Manager Parameter Store 보안 암호 검색
Systems Manager Parameter Store 파라미터에 저장된 민감한 데이터를 검색하려면 *AWS SDK 코드 예제 코드 라이브러리*의 [Code examples for Systems Manager using AWS SDKs](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html)를 참조하세요.
# Amazon ECS 로깅 구성에 대한 보안 암호 전달
`logConfiguration`에서 `secretOptions` 파라미터를 사용하여 로깅에 사용되는 민감한 데이터를 전달할 수 있습니다.
Secrets Manager 또는 Systems Manager에 보안 암호를 저장할 수 있습니다.
## Secrets Manager 사용
컨테이너 정의 내에서, `logConfiguration`을 지정할 때 컨테이너에 설정할 로그 드라이버 옵션의 이름과 컨테이너에 제공할 민감한 데이터가 들어있는 Secret Manager 암호의 전체 ARN을 사용하여 `secretOptions`를 지정할 수 있습니다. 시크릿 생성에 대한 자세한 내용은 [Create an AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)를 참조하세요.
다음은 Secrets Manager 암호를 참조할 때 형식을 나타내는 태스크 태스크의 조각입니다.
```
{
"containerDefinitions": [{
"logConfiguration": [{
"logDriver": "splunk",
"options": {
"splunk-url": "https://your_splunk_instance:8088"
},
"secretOptions": [{
"name": "splunk-token",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
}]
}]
}]
}
```
## 컨테이너 정의에 환경 변수 추가
컨테이너 정의 내에서 컨테이너에 설정할 환경 변수의 이름으로 `secrets`(을)를 지정하여 컨테이너에 제공할 민감한 데이터가 들어있는 Systems Manager 파라미터 스토어 파라미터의 전체 ARN을 지정합니다. 자세한 내용은 [secrets](task_definition_parameters.md#ContainerDefinition-secrets) 섹션을 참조하세요.
다음은 Systems Manager 파라미터 스토어 파라미터를 참조할 때 형식을 나타내는 태스크 정의의 조각입니다. Systems Manager 파라미터 스토어 파라미터가 현재 실행 중인 태스크와 동일한 리전에 있는 경우, 파라미터의 전체 ARN 또는 이름을 사용할 수 있습니다. 파라미터가 다른 리전에 있다면 전체 ARN을 지정합니다.
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}]
}]
}
```
환경 변수에 지정된 보안 암호를 사용하여 태스크 정의를 생성하는 방법에 대한 자세한 내용은 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 섹션을 참조하세요.
## Systems Manager 사용
로그 구성에 중요 데이터를 삽입할 수 있습니다. 컨테이너 정의 내에서, `logConfiguration`을 정의할 때 컨테이너에 설정할 로그 드라이버 옵션의 이름과 컨테이너에 제공할 민감한 데이터가 들어있는 Systems Manager 파라미터 스토어 파라미터의 전체 ARN을 사용하여 `secretOptions`를 지정할 수 있습니다.
**중요**
Systems Manager 파라미터 스토어 파라미터가 현재 실행 중인 태스크와 동일한 리전에 있는 경우, 파라미터의 전체 ARN 또는 이름을 사용할 수 있습니다. 파라미터가 다른 리전에 있다면 전체 ARN을 지정합니다.
다음은 Systems Manager 파라미터 스토어 파라미터를 참조할 때 형식을 나타내는 태스크 정의의 조각입니다.
```
{
"containerDefinitions": [{
"logConfiguration": [{
"logDriver": "fluentd",
"options": {
"tag": "fluentd demo"
},
"secretOptions": [{
"name": "fluentd-address",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter:/parameter_name"
}]
}]
}]
}
```
# Amazon ECS에서 Secrets Manager 암호를 사용하여 민감한 데이터 지정
Amazon ECS에서는 AWS Secrets Manager 암호에 민감한 데이터를 저장하고 컨테이너 정의에서 참조하는 방식으로 컨테이너에 민감한 데이터를 삽입할 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
Secrets Manager 보안 암호를 생성하고, Amazon ECS 태스크 정의에서 보안 암호를 참조한 다음, 보안 암호 내용을 표시하는 컨테이너 내부의 환경 변수를 쿼리하여 작동하는지 확인하는 방법을 알아보세요.
## 사전 조건
이 자습서에서는 다음 사전 조건이 충족되었다고 가정합니다.
+ [Amazon ECS 사용 설정](get-set-up-for-amazon-ecs.md)의 단계가 완료되었습니다.
+ 사용자에게는 Secrets Manager 및 Amazon ECS 리소스를 생성하는 데 필요한 IAM 권한이 있습니다.
## 1단계: Secrets Manager 보안 암호 생성
Secrets Manager 콘솔을 사용하여 민감한 데이터에 대한 암호를 생성할 수 있습니다. 이 자습서에서는 이후 컨테이너에서 참조할 기본 사용자 이름 및 암호를 저장하는 기본 보안을 생성합니다. 자세한 정보는 *AWS Secrets Manager 사용 설명서*의 [AWS Secrets Manager 보안 암호 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)을 참조하세요.
**이 보안 암호에 저장되는 키/값 페어**는 자습서 마지막에 있는 컨테이너의 환경 변수 값입니다.
**Secret ARN**(보안 암호 ARN)을 저장하여 이후 단계의 작업 실행 IAM 정책 및 작업 정의에 참조합니다.
## 2단계: 태스크 실행 역할에 보안 암호 권한 추가
Amazon ECS가 Secrets Manager 보안 암호에서 민감한 데이터를 가져오려면 작업 실행 역할에 대한 보안 암호 권한을 보유해야 합니다. 자세한 내용은 [Secrets Manager 또는 Systems Manager 권한](task_execution_IAM_role.md#task-execution-secrets) 섹션을 참조하세요.
## 3단계: 태스크 정의 생성
Amazon ECS 콘솔을 사용하면 Secrets Manager 암호를 참조하는 태스크 정의를 생성할 수 있습니다.
**암호를 지정하는 태스크 정의를 생성하려면**
IAM 콘솔을 사용해 작업 실행 역할에 필요한 권한을 업데이트합니다.
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **작업 정의**를 선택합니다.
1. **새 태스크 정의 생성(Create new task definition)**, **JSON으로 새 태스크 정의 생성(Create new task definition with JSON)**을 선택합니다.
1. JSON 편집기 상자에 다음 태스크 정의 JSON 문자열을 입력하여 1단계에서 생성한 Secrets Manager 보안 암호의 전체 ARN과 2단계에서 업데이트한 작업 실행 역할을 지정했는지 확인합니다. **저장**을 선택합니다.
1.
```
{
"executionRoleArn": "arn:aws:iam::aws_account_id:role/ecsTaskExecutionRole",
"containerDefinitions": [
{
"entryPoint": [
"sh",
"-c"
],
"portMappings": [
{
"hostPort": 80,
"protocol": "tcp",
"containerPort": 80
}
],
"command": [
"/bin/sh -c \"echo ' Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
' > /usr/local/apache2/htdocs/index.html && httpd-foreground\""
],
"cpu": 10,
"secrets": [
{
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:username_value",
"name": "username_value"
}
],
"memory": 300,
"image": "public.ecr.aws/docker/library/httpd:2.4",
"essential": true,
"name": "ecs-secrets-container"
}
],
"family": "ecs-secrets-tutorial"
}
```
1. **생성(Create)**을 선택합니다.
## 4단계: 클러스터 생성
Amazon ECS 콘솔을 사용해 태스크를 실행할 컨테이너 인스턴스가 있는 클러스터를 생성합니다. 기존 클러스터에 자습서를 위한 태스크 정의 인스턴스를 실행할 수 있는 가용 리소스가 있는 컨테이너 인스턴스가 적어도 하나 등록된 경우에는 다음 단계로 이동합니다.
이 자습서에서는 Amazon ECS 최적화 Amazon Linux 2 AMI를 사용하여 하나의 `t2.micro` 컨테이너 인스턴스로 클러스터를 생성합니다.
EC2에 대한 클러스터를 생성하는 방법에 대한 자세한 내용은 [Amazon EC2 워크로드에 대한 Amazon ECS 클러스터 생성](create-ec2-cluster-console-v2.md) 섹션을 참조하세요.
## 5단계: 태스크 실행
Amazon ECS 콘솔을 사용해 생성한 태스크 정의로 태스크를 실행할 수 있습니다. 이 자습서에서는 이전 단계에서 생성한 클러스터에서 EC2를 사용해 태스크를 실행합니다.
작업을 실행하는 방법에 대한 정보는 [애플리케이션을 Amazon ECS 태스크로 실행](standalone-task-create.md) 섹션을 참조하세요.
## 6단계: 확인
모든 단계가 성공적으로 완료되었으며 다음 단계를 따라 컨테이너 내에서 생성한 환경 변수가 잘 생성되었는지 확인합니다.
**생성한 환경 변수 확인**
1. 컨테이너 인스턴스의 퍼블릭 IP 또는 DNS 주소를 찾습니다.
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **클러스터**를 선택한 다음, 생성한 클러스터를 선택합니다.
1. **Infrastructure**(인프라)를 선택한 다음 컨테이너 인스턴스를 선택합니다.
1. 인스턴스로 인스턴스의 **Public IP**(퍼블릭 IP) 또는 **Public DNS**(퍼블릭 DNS)를 기록합니다.
1. Mac OS 또는 Linux 컴퓨터를 사용 중인 경우, 다음 명령을 사용하여 인스턴스에 연결해 프라이빗 키 경로와 인스턴스의 퍼블릭 주소를 대체합니다.
```
$ ssh -i /path/to/my-key-pair.pem ec2-user@ec2-198-51-100-1.compute-1.amazonaws.com
```
Windows 컴퓨터 사용에 대한 자세한 내용은 *Amazon EC2 사용 설명서*의 [PuTTY를 사용하여 Linux 인스턴스에 연결](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-linux-inst-from-windows.html)을 참조하세요.
**중요**
인스턴스 연결 문제에 대한 자세한 내용은 **Amazon EC2 사용 설명서의 [인스턴스에 연결 문제 해결](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html)을 참조하세요.
1. 인스턴스에서 실행되는 컨테이너 목록을 표시합니다. `ecs-secrets-tutorial` 컨테이너의 컨테이너 ID를 기록합니다.
```
docker ps
```
1. 이전 단계의 결과로 얻은 컨테이너 ID를 사용해 `ecs-secrets-tutorial` 컨테이너에 연결합니다.
```
docker exec -it container_ID /bin/bash
```
1. `echo` 명령을 사용해 환경 변수 값을 프린트합니다.
```
echo $username_value
```
자습서가 성공했다면 다음 결과가 표시되어야 합니다.
```
password_value
```
**참고**
또한 `env`(또는 `printenv`) 명령을 사용해 컨테이너 내의 모든 환경 변수 목록을 표시할 수 있습니다.
## 7단계: 정리
이 자습서로 완료를 한 후에 사용하지 않는 리소스에 대해 요금이 발생하는 것을 방지하기 위해 연결된 리소스를 정리해야 합니다.
**리소스 정리**
1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다.
1. 탐색 창에서 **클러스터**를 선택합니다.
1. **클러스터(Clusters)** 페이지에서 클러스터를 선택합니다.
1. **클러스터 삭제(Delete Cluster)**를 선택합니다.
1. 확인 상자에 **delete *cluster name***을 입력한 다음 **삭제**를 선택합니다.
1. IAM 콘솔([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/))을 엽니다.
1. 탐색 창에서 **역할**을 선택합니다.
1. 역할 목록에서 `ecsTaskExecutionRole`을 검색하고 선택합니다.
1. **Permissions**(권한)를 선택한 다음 **ECSSecretsTutorial** 옆에 있는 **X**를 선택합니다. **** 제거를 선택합니다.
1. [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)에서 Secrets Manager 콘솔을 엽니다.
1. 생성한 **username\$1value** 보안 암호를 선택하고 **작업(Actions)**, **보안 암호 삭제(Delete secret)**를 선택합니다.
# Amazon ECS 관리형 인스턴스에 대한 Amazon ECS 태스크 정의 파라미터
태스크 정의는 태스크 패밀리, AWS Identity and Access Management(IAM) 태스크 역할, 네트워크 모드, 컨테이너 정의, 볼륨, 용량과 같은 개별 부분으로 분할됩니다. 태스크 정의에는 패밀리 및 컨테이너 정의가 필요합니다. 하지만 태스크 역할, 네트워크 모드, 볼륨 및 용량은 선택 사항입니다.
JSON 파일에서 이러한 파라미터를 사용하여 태스크 정의를 구성할 수 있습니다.
다음은 Amazon ECS 관리형 인스턴스의 각 태스크 정의 파라미터에 대한 자세한 설명입니다.
## Family
`family`
유형: 문자열
필수 항목 여부: 예
태스크 정의를 등록할 때 패밀리를 지정합니다. 패밀리는 개정 번호를 사용하여 지정된 태스크 정의의 여러 버전에 대한 이름과 비슷합니다. 특정 패밀리에 등록된 첫 번째 태스크 정의에는 개정 번호 1이 부여되고 그 이후 등록된 태스크 정의에는 순차적으로 개정 번호가 부여됩니다.
## Capacity
태스크 정의를 등록할 때 Amazon ECS가 태스크 정의를 검증할 용량을 지정할 수 있습니다. 태스크 정의가 유효성을 지정한 호환성에 대해 검사하지 않으면 클라이언트 예외가 반환됩니다. 자세한 내용은 [Amazon ECS 시작 유형](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html)을 참조하세요.
태스크 정의에서 다음 파라미터가 허용됩니다.
`requiresCompatibilities`
유형: 문자열 배열
필수 여부: 아니요
유효한 값: `MANAGED_INSTANCES`
태스크 정의를 검증할 용량. 이를 통해 태스크 정의에 사용되는 모든 파라미터가 Amazon ECS 관리형 인스턴스의 요구 사항을 충족하는지 확인할 수 있습니다.
## 태스크 역할
`taskRoleArn`
유형: 문자열
필수 여부: 아니요
태스크 정의를 등록할 때 태스크 권한의 컨테이너가 사용자 대신 연결된 정책에 지정된 AWS API를 호출하도록 허용하는 IAM 역할에 태스크 역할을 제공할 수 있습니다. 자세한 내용은 [Amazon ECS 작업 IAM 역할](task-iam-roles.md) 섹션을 참조하세요.
## 태스크 실행 역할
`executionRoleArn`
유형: 문자열
필수 항목 여부: 조건부
Amazon ECS 컨테이너 에이전트에 사용자를 대신하여 AWS API를 호출할 권한을 부여하는 태스크 실행 역할의 Amazon 리소스 이름(ARN)입니다. 자세한 내용은 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
태스크의 요구 사항에 따라 태스크 실행 IAM 역할이 필요합니다. 역할은 `awslogs` 로그 드라이버를 사용하며 프라이빗 ECR 이미지 가져오기에 필요합니다.
## 네트워크 모드
`networkMode`
유형: 문자열
필수 항목 여부: 아니요
기본값: `awsvpc`
태스크의 컨테이너에 사용할 네트워킹 모드. Amazon ECS 관리형 인스턴스에서 호스팅되는 Amazon ECS 태스크의 경우, 유효한 값은 `awsvpc` 및 `host`입니다. 네트워크 모드를 지정하지 않으면 기본 네트워크 모드는 `awsvpc`입니다.
네트워크 모드가 `host`인 경우 태스크는 네트워크 격리를 우회하고 컨테이너는 호스트의 네트워크 스택을 직접 사용합니다.
`host` 네트워크 모드를 사용하여 태스크를 실행할 때는 더 나은 보안을 위해 루트 사용자(UID 0)를 사용하여 컨테이너를 실행해서는 안 됩니다. 보안상 항상 루트가 아닌 사용자를 사용합니다.
네트워크 모드가 `awsvpc`인 경우 해당 태스크에 탄력적 네트워크 인터페이스가 할당되므로 서비스를 생성하거나 태스크 정의로 태스크를 실행하려면 `NetworkConfiguration`을 지정해야 합니다. 자세한 내용은 [Amazon ECS 관리형 인스턴스에 대한 Amazon ECS 태스크 네트워킹](managed-instance-networking.md) 섹션을 참조하세요.
`host` 및 `awsvpc` 네트워크 모드는 Amazon EC2 네트워크 스택을 사용하는 컨테이너에 가장 높은 수준의 네트워킹 성능을 제공합니다. `host` 및 `awsvpc` 네트워크 모드에서는 노출된 컨테이너 포트가 해당 호스트 포트(`host` 네트워크 모드의 경우) 또는 연결된 탄력적 네트워크 인터페이스 포트(`awsvpc` 네트워크 의 경우)에 직접 매핑됩니다. 이 때문에 동적 호스트 포트 매핑을 사용할 수 없습니다.
## 런타임 플랫폼
`operatingSystemFamily`
유형: 문자열
필수 여부: 아니요
기본값: LINUX
태스크 정의를 등록할 때 운영 체제 제품군을 지정합니다.
이 필드의 유효한 값은 `LINUX`입니다.
서비스에서 사용되는 모든 태스크 정의는 이 파라미터에 대해 동일한 값을 가져야 합니다.
태스크 정의가 서비스의 일부인 경우 이 값은 서비스 `platformFamily` 값과 일치해야 합니다.
`cpuArchitecture`
유형: 문자열
필수 항목 여부: 조건부
태스크 정의를 등록할 때 CPU 아키텍처를 지정합니다. 유효 값은 `X86_64` 및 `ARM64`입니다.
값을 지정하지 않으면 Amazon ECS는 용량 공급자 구성을 기반으로 사용 가능한 CPU 아키텍처에 태스크를 배치하려고 시도합니다. 태스크를 특정 CPU 아키텍처에 배치하게 하려면 태스크 정의에서 `cpuArchitecture`의 값을 지정합니다.
서비스에서 사용되는 모든 태스크 정의는 이 파라미터에 대해 동일한 값을 가져야 합니다.
`ARM64`에 대한 자세한 정보는 [64비트 ARM 워크로드에 대한 Amazon ECS 작업 정의](ecs-arm64.md) 섹션을 참조하세요.
## 태스크 크기
태스크 정의를 등록할 때 태스크에 대해 사용할 CPU 및 메모리 총량을 지정할 수 있습니다. 이것은 컨테이너 정의 수준의 `cpu` 및 `memory` 값과는 구분됩니다. Amazon EC2 인스턴스에서 호스팅되는 태스크의 경우, 이 필드는 선택 사항입니다.
**참고**
Windows 컨테이너에 대해서는 태스크 레벨 CPU와 메모리 파라미터가 무시됩니다. Windows 컨테이너에 대해서는 컨테이너 레벨 리소스를 지정할 것을 권장합니다.
`cpu`
유형: 문자열
필수 항목 여부: 조건부
태스크에 대해 표시되는 CPU 단위의 하드 제한입니다. JSON 파일에서 CPU 값을 문자열(CPU 단위 또는 가상 CPU(vCPU))로 지정할 수 있습니다. 예를 들어 CPU 값을 `1024`(CPU 단위) 또는 `1 vCPU`(vCPU)로 지정할 수 있습니다. 태스크 정의를 등록할 때는 vCPU 값이 CPU 단위를 나타내는 정수로 변환됩니다.
이 필드는 선택 사항입니다. 클러스터에 요청된 CPU 단위가 사용 가능한 등록된 컨테이너 인스턴스가 없는 경우 태스크가 실패합니다. 지원되는 값은 `0.125` vCPU에서 `10` vCPU 사이입니다.
`memory`
유형: 문자열
필수 항목 여부: 조건부
작업에 표시할 메모리의 하드 제한. 작업 정의에서 메모리 값을 문자열(메비바이트(MiB) 또는 기가바이트(GB) 단위)로 지정할 수 있습니다. 예를 들어 메모리 값을 `3072`(MiB) 또는 `3 GB`(GB)로 지정할 수 있습니다. 태스크 정의를 등록할 때는 GB 값이 MiB를 나타내는 정수로 변환됩니다.
이 필드는 선택 사항이며 아무 값이나 사용할 수 있습니다. 태스크 수준 메모리 값이 지정된 경우 컨테이너 수준 메모리 값은 선택 사항입니다. 클러스터에 요청된 메모리에 사용 가능한 등록된 컨테이너 인스턴스가 없는 경우 태스크가 실패합니다. 특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화할 수 있습니다. 자세한 내용은 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요.
## 기타 태스크 정의 파라미터
다음의 태스크 정의 파라미터는 **JSON을 통한 구성(Configure via JSON)** 옵션을 사용하여 Amazon ECS 콘솔에 태스크 정의를 등록할 때 사용할 수 있습니다. 자세한 정보는 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md)을 참조하세요.
**Topics**
+ [임시 스토리지](#task_definition_ephemeralStorage-managed-instances)
+ [IPC 모드](#task_definition_ipcmode-managed-instances)
+ [PID 모드](#task_definition_pidmode-managed-instances)
+ [프록시 구성](#proxyConfiguration-managed-instances)
+ [Tags](#tags-managed-instances)
+ [Elastic Inference 액셀러레이터(폐기됨)](#elastic-Inference-accelerator-managed-instances)
+ [배치 제약 조건](#constraints-managed-instances)
+ [볼륨](#volumes-managed-instances)
### 임시 스토리지
`ephemeralStorage`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: [EphemeralStorage](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EphemeralStorage.html) 객체
필수 여부: 아니요
태스크에 할당되는 임시 스토리지 용량(GB)입니다. 이 파라미터는 AWS Fargate에서 호스팅되는 태스크에 대해 제공되는 임시 스토리지 총량을 기본 용량 이상으로 확장할 때 사용합니다. 자세한 내용은 [Amazon ECS에서 바인드 탑재 사용](bind-mounts.md) 섹션을 참조하세요.
### IPC 모드
`ipcMode`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 문자열
필수 여부: 아니요
해당 태스크의 컨테이너에 사용할 IPC 리소스 네임스페이스입니다. 유효한 값은 `host`, `task` 또는 `none`입니다. `host`를 지정하면 동일한 컨테이너 인스턴스에서 `host` IPC 모드를 지정한 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 호스트 Amazon EC2 인스턴스와 공유합니다. `task`를 지정하면 지정된 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 공유합니다. `none`이 지정된 경우, 태스크 컨테이너 내에 있는 IPC 리소스는 프라이빗이며, 태스크 또는 컨테이너 인스턴스의 다른 컨테이너와 공유되지 않습니다. 값을 지정하지 않으면 IPC 리소스 네임스페이스 공유는 컨테이너 런타임 구성에 따라 달라집니다.
### PID 모드
`pidMode`
유형: 문자열
필수 여부: 아니요
해당 태스크의 컨테이너에 사용할 프로세스 네임스페이스입니다. 유효한 값은 `host` 또는 `task`입니다. `host`를 지정하면 동일한 컨테이너 인스턴스에서 `host` PID 모드를 지정한 태스크 내 모든 컨테이너가 동일한 프로세스 네임스페이스를 호스트 Amazon EC2 인스턴스와 공유합니다. `task`를 지정하면 지정된 태스크 내 모든 컨테이너가 동일한 프로세스 네임스페이스를 공유합니다. 값을 지정하지 않을 경우, 기본값은 프라이빗 네임스페이스입니다.
`host` PID 모드를 사용하는 경우, 원치 않는 프로세스 네임스페이스 노출이 발생할 위험이 커집니다.
### 프록시 구성
`proxyConfiguration`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: [ProxyConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ProxyConfiguration.html) 객체
필수 여부: 아니요
App Mesh 프록시에 대한 구성 세부 정보입니다.
### Tags
태스크 정의를 분류하고 구성하는 데 도움이 되도록 태스크 정의에 적용하는 메타데이터. 각 태그는 키와 값(선택사항)으로 구성됩니다. 두 가지를 모두 정의합니다.
태그에 적용되는 기본 제한은 다음과 같습니다.
+ 리소스 당 최대 태그 수 - 50개
+ 각 리소스에 대해 각 태그 키는 고유하며 하나의 값만 가질 수 있습니다.
+ 최대 키 길이 - UTF-8의 유니코드 문자 128자
+ 최대 값 길이 - UTF-8의 유니코드 문자 256자
+ 태깅 스키마를 여러 서비스와 리소스에서 사용하는 경우 다른 서비스 또한 허용되는 문자에 대한 제한이 있을 수 있음을 유의합니다. 일반적으로 허용되는 문자는 UTF-8로 표현할 수 있는 문자, 숫자 및 공백과 특수 문자 \$1 - = . \$1 : / @.
+ 태그 키와 값은 대/소문자를 구분합니다.
+ AWS 사용을 위해 예약된 키 또는 값에는 `aws:`, `AWS:` 또는 이러한 접두사의 어떤 대문자 또는 소문자 조합도 사용하지 않습니다. 이 접두사가 지정된 태그 키나 값은 편집하거나 삭제할 수 없습니다. 이 접두사가 지정된 태그는 리소스당 태그 수 제한에 포함되지 않습니다.
`key`
유형: 문자열
필수 여부: 아니요
하나의 태그를 구성하는 키-값 쌍의 일부분입니다. 키는 더 구체적인 태그 값에 대해 범주와 같은 역할을 하는 일반적인 레이블입니다.
`value`
유형: 문자열
필수 여부: 아니요
하나의 태그를 구성하는 키-값 쌍의 선택적 부분입니다. 하나의 값은 태그 범주(키) 내에서 서술자 역할을 수행합니다.
### Elastic Inference 액셀러레이터(폐기됨)
**참고**
Amazon Elastic Inference(EI)는 더 이상 고객에게 제공되지 않습니다.
`inferenceAccelerator`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: [InferenceAccelerator](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_InferenceAccelerator.html) 객체
필수 여부: 아니요
작업의 컨테이너에서 사용할 Elastic Inference 액셀러레이터입니다.
### 배치 제약 조건
`placementConstraints`
유형: [TaskDefinitionPlacementConstraint](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_TaskDefinitionPlacementConstraint.html) 객체 배열
필수 여부: 아니요
태스크에 사용할 배치 제약 객체의 배열입니다. 작업당 최대 10개의 제약을 지정할 수 있습니다(이 제한에는 작업 정의 내 제약과 런타임 시 지정되는 제약이 포함됨).
Amazon ECS는 Amazon ECS 관리형 인스턴스에서 실행되는 태스크에 대해 `distinctInstace` 및 `memberOf` 배치 제약 조건을 지원합니다. `memberOf` 배치 제약 조건을 사용하는 태스크에 대해 다음 속성이 지원됩니다.
+ `ecs.subnet-id`
+ `ecs.availability-zone`
+ `ecs.cpu-architecture`
+ `ecs.instance-type`
배치 제약 조건에 대한 자세한 내용은 [Amazon ECS가 작업에 사용하는 컨테이너 인스턴스 정의](task-placement-constraints.md) 섹션을 참조하세요.
### 볼륨
태스크 정의를 등록할 때 선택적으로 태스크에 대한 볼륨 목록을 지정할 수 있습니다. 그러면 태스크에서 데이터 볼륨을 사용할 수 있습니다.
볼륨 유형 및 기타 파라미터에 대한 자세한 내용은 [Amazon ECS 작업에 대한 스토리지 옵션](using_data_volumes.md) 섹션을 참조하세요.
`name`
유형: 문자열
필수 항목 여부: 예
볼륨의 이름입니다. 최대 255자의 문자(대문자 및 소문자), 숫자, 하이픈을 사용할 수 있습니다. 이 이름은 컨테이너 정의 `mountPoints`의 `sourceVolume` 파라미터에서 참조됩니다.
`host`
유형: [HostVolumeProperties](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_HostVolumeProperties.html) 객체
필수 여부: 아니요
이 파라미터는 바인드 탑재 호스트 볼륨을 사용할 때 지정됩니다. `host` 파라미터의 내용에 따라 바인드 마운트 호스트 볼륨이 호스트 컨테이너 인스턴스에서 유지되는지 여부와 저장되는 위치가 결정됩니다. `host` 파라미터가 비어 있으면 시스템에서 데이터 볼륨의 호스트 경로를 할당합니다. 그러나 연결된 컨테이너의 실행이 중지된 후에는 데이터 유지가 보장되지 않습니다.
`sourcePath`
유형: 문자열
필수 여부: 아니요
`host` 파라미터를 사용하는 경우 컨테이너에 제공될 호스트 인스턴스의 경로를 지정하기 위해 `sourcePath`를 설정하세요. 이 파라미터가 비어 있으면 시스템이 호스트 경로를 자동으로 할당합니다. `host` 파라미터에 `sourcePath` 파일 위치가 들어 있으면, 데이터 볼륨은 수동으로 삭제할 때까지 호스트 인스턴스 상에 지정된 위치를 유지합니다. `sourcePath` 값이 호스트 인스턴스에 없을 경우 시스템이 해당 경로를 생성합니다. 해당 위치가 있을 경우 소스 경로 폴더의 콘텐츠를 내보냅니다.
Amazon ECS 관리형 인스턴스에서는 호스트 파일 시스템의 일부가 읽기 전용입니다. `sourcePath`는 `/var` 또는 `/tmp`와 같은 쓰기 가능한 디렉터리를 가리켜야 합니다. 자세한 내용은 [Amazon ECS에서 바인드 탑재 사용](bind-mounts.md) 섹션을 참조하세요.
`dockerVolumeConfiguration`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: [DockerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DockerVolumeConfiguration.html) 객체
필수 여부: 아니요
이 파라미터는 Docker 볼륨을 사용할 때 지정됩니다.
`efsVolumeConfiguration`
유형: [EFSVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSVolumeConfiguration.html) 객체
필수 여부: 아니요
이 파라미터는 태스크 스토리지를 위해 Amazon EFS 파일 시스템을 사용할 때 지정됩니다.
`fsxWindowsFileServerVolumeConfiguration`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: [FSxWindowsFileServerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FSxWindowsFileServerVolumeConfiguration.html) 객체
필수 여부: 아니요
이 파라미터는 태스크 스토리지를 위해 Amazon FSx for Windows File Server 파일 시스템을 사용할 때 지정됩니다.
`configuredAtLaunch`
유형: 부울
필수 여부: 아니요
시작 시 볼륨을 구성해야 하는지를 나타냅니다. 이는 독립 실행형 태스크 또는 서비스의 일부로 생성된 태스크에 대한 Amazon EBS 볼륨을 생성하는 데 사용됩니다. 각 태스크 정의 개정의 경우 볼륨 구성에서 시작 시 하나의 볼륨만 구성될 수 있습니다.
## 컨테이너 정의
작업 정의를 등록할 때 컨테이너 인스턴스의 Docker 대몬(daemon)으로 전달되는 컨테이너 정의의 목록을 지정해야 합니다. 컨테이너 정의에서 다음 파라미터가 허용됩니다.
**Topics**
+ [이름](#container_definition_name-managed-instances)
+ [이미지](#container_definition_image-managed-instances)
+ [Memory](#container_definition_memory-managed-instances)
+ [CPU](#container_definition_cpu-managed-instances)
+ [포트 매핑](#container_definition_portmappings-managed-instances)
+ [프라이빗 리포지토리 보안 인증](#container_definition_repositoryCredentials-managed-instances)
+ [Essential](#container_definition_essential-managed-instances)
+ [진입점](#container_definition_entrypoint-managed-instances)
+ [Command](#container_definition_command-managed-instances)
+ [작업 디렉터리](#container_definition_workingdirectory-managed-instances)
+ [고급 컨테이너 정의 파라미터](#advanced_container_definition_params-managed-instances)
+ [Linux 파라미터](#container_definition_linuxparameters-managed-instances)
### 이름
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너의 이름. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈 및 밑줄이 허용됩니다. 여러 컨테이너를 한 태스크 정의에 연결하는 경우, 한 컨테이너의 `name`을 다른 컨테이너의 `links`에 입력할 수 있습니다. 이는 컨테이너를 연결하기 위한 것입니다.
### 이미지
`image`
유형: 문자열
필수 항목 여부: 예
컨테이너를 시작하는 데 사용되는 이미지입니다. 이 문자열은 Docker 대몬(daemon)으로 직접 전달됩니다. 기본적으로 Docker Hub 레지스트리 내 이미지는 사용 가능합니다. `repository-url/image:tag` 또는 `repository-url/image@digest`를 사용하여 다른 리포지토리를 지정할 수도 있습니다. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈, 밑줄, 콜론, 마침표, 슬래시 및 부호가 허용됩니다. 이 파라미터는 Docker 컨테이너 생성 명령에 있는 `Image` 및 docker run 명령의 `IMAGE` 파라미터에 매핑됩니다.
+ 새 태스크가 시작될 때 Amazon ECS 컨테이너 에이전트가 컨테이너에서 사용할 지정 이미지와 태그의 최신 버전을 끌어옵니다. 그러나 이미 실행 중인 태스크에는 추후 리포지토리 이미지 업데이트가 전파되지 않습니다.
+ 태스크 정의의 이미지 경로에 태그 또는 다이제스트를 지정하지 않으면 Amazon ECS 컨테이너 에이전트가 지정된 이미지를 가져오기 위해 `latest` 태그를 사용합니다.
+ 그러나 이미 실행 중인 태스크에는 리포지토리 이미지에 대한 후속 업데이트가 전파되지 않습니다.
+ 프라이빗 리포지토리의 이미지는 지원되지 않습니다. 자세한 정보는 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md)을 참조하세요.
+ Amazon ECR 리포지토리의 이미지는 전체 `registry/repository:tag` 또는 `registry/repository@digest` 명명 규칙(예: `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app:latest` 또는 `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app@sha256:94afd1f2e64d908bc90dbca0035a5b567EXAMPLE`)을 사용하여 지정할 수 있습니다.
+ Docker Hub 공식 리포지토리 안의 이미지는 단일 이름을 사용합니다(예: `ubuntu` 또는 `mongo`).
+ Docker Hub 다른 리포지토리에 저장된 이미지는 조직 이름으로 한정됩니다(예: `amazon/amazon-ecs-agent`).
+ 다른 온라인 리포지토리 안의 이미지는 도메인 이름을 사용하여 추가로 한정됩니다(예: `quay.io/assemblyline/ubuntu`).
`versionConsistency`
유형: 문자열
유효한 값: `enabled`\$1`disabled`
필수 여부: 아니요
컨테이너 정의에 제공된 컨테이너 이미지 태그가 Amazon ECS에서 이미지 다이제스트로 확인되는지 여부를 지정합니다. 기본적으로 이 동작은 `enabled`입니다. 컨테이너의 값을 `disabled`로 설정하면 Amazon ECS에서는 컨테이너 이미지 태그가 다이제스트로 확인되지 않고 컨테이너 정의에 지정된 원본 이미지 URI가 배포에 사용됩니다. 컨테이너 이미지 확인에 대한 자세한 내용은 [컨테이너 이미지 확인](deployment-type-ecs.md#deployment-container-image-stability) 섹션을 참조하세요.
### Memory
`memory`
유형: 정수
필수 여부: 아니요
컨테이너에 표시할 메모리의 양(MiB)입니다. 컨테이너가 여기서 지정된 메모리를 초과하려 하면 해당 컨테이너가 중지됩니다. 태스크 내 모든 컨테이너에 대해 예약된 총 메모리 양은 태스크 `memory` 값(지정된 경우)보다 작아야 합니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Memory` 및 docker run에 대한 `--memory` 옵션에 매핑됩니다.
Docker 20.10.0 이상의 대몬(daemon)은 컨테이너용으로 최소 6MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 6MiB 미만의 메모리를 지정하지 마세요.
Docker 19.03.13-ce 이하의 대몬(daemon)은 컨테이너용으로 최소 4MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 4MiB 미만의 메모리를 지정하지 마세요.
특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화하려는 경우 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요.
`memoryReservation`
유형: 정수
필수 여부: 아니요
컨테이너용으로 예약할 메모리의 소프트 제한(MiB)입니다. 시스템 메모리가 경합하는 경우 Docker는 컨테이너 메모리를 이 소프트 제한으로 유지하려고 합니다. 하지만 필요한 경우 컨테이너에서 더 많은 메모리를 사용할 수 있습니다. 컨테이너는 `memory` 파라미터에 지정된 하드 한도까지(해당하는 경우) 또는 컨테이너 인스턴스의 모든 가용 메모리(둘 중 먼저 발생하는 것)를 사용할 수 있습니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `MemoryReservation` 및 docker run에 대한 `--memory-reservation` 옵션에 매핑됩니다.
태스크 레벨 메모리 값이 지정되지 않은 경우 컨테이너 정의의 `memory` 또는 `memoryReservation`에 대해 하나 또는 둘 다에 0이 아닌 정수를 지정해야 합니다. 둘 모두 지정하는 경우 `memory`가 `memoryReservation`보다 커야 합니다. `memoryReservation`을 지정하는 경우 컨테이너가 배치된 컨테이너 인스턴스의 가용 메모리 리소스에서 해당 값이 차감됩니다. 그렇지 않으면 `memory` 값이 사용됩니다.
예를 들어 컨테이너가 통상적으로 128MiB의 메모리를 사용하지만 경우에 따라 잠깐 동안 사용량이 256MiB까지 급증한다고 가정합니다. 이 경우 `memoryReservation`을 128MiB로 설정하고 `memory` 하드 제한을 300MiB로 설정할 수 있습니다. 이 구성은 컨테이너가 컨테이너 인스턴스의 잔여 리소스 중 128MiB의 메모리만 예약하도록 허용합니다. 동시에, 이 구성을 사용하여 필요할 때 컨테이너가 더 많은 메모리 리소스를 사용하도록 허용할 수도 있습니다.
Docker 20.10.0 이상의 대몬(daemon)은 컨테이너용으로 최소 6MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 6MiB 미만의 메모리를 지정하지 마세요.
Docker 19.03.13-ce 이하의 대몬(daemon)은 컨테이너용으로 최소 4MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 4MiB 미만의 메모리를 지정하지 마세요.
특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화하려는 경우 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요.
### CPU
`cpu`
유형: 정수
필수 여부: 아니요
컨테이너용으로 예약된 `cpu` 유닛의 수입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `CpuShares` 및 docker run에 대한 `--cpu-shares` 옵션에 매핑됩니다.
EC2 용량 공급자를 사용하는 태스크의 경우 이 필드는 선택 사항이며, 한 가지 요구 사항은 태스크 내 모든 컨테이너에 예약된 CPU 총량이 태스크 레벨의 `cpu` 값보다 작아야 합니다.
[Amazon EC2 인스턴스](https://aws.amazon.com/ec2/instance-types/) 세부 정보 페이지에서 해당 인스턴스 유형에 대해 나열된 vCPU에 1,024를 곱해 EC2 인스턴스 유형당 사용 가능한 CPU 단위 수를 계산할 수 있습니다.
Linux 컨테이너는 할당된 양과 동일한 비율로, 컨테이너 인스턴스의 다른 컨테이너와 할당되지 않은 CPU 단위를 공유합니다. 예를 들어, 컨테이너에 512개 CPU 단위가 지정된 상태로 싱글 코어 인스턴스 유형에서 단일 컨테이너 태스크를 실행하고 이 태스크가 컨테이너 인스턴스에서 실행되는 유일한 태스크일 경우 해당 컨테이너는 언제라도 1,024개 CPU 단위 전부를 사용할 수 있습니다. 그러나 해당 컨테이너 인스턴스에서 동일한 태스크의 다른 사본을 시작한 경우 각 태스크에 필요 시 최소 512개의 CPU 단위가 보증됩니다. 또한 다른 컨테이너가 사용하지 않을 경우 모든 컨테이너의 CPU 사용량이 높아질 수 있습니다. 두 태스크가 항상 100% 활성 상태인 경우 CPU 단위는 512개로 제한됩니다.
Linux 컨테이너 인스턴스에서, 컨테이너 인스턴스의 Docker 대몬은 CPU 값을 사용하여 실행 컨테이너의 CPU 공유 비율을 계산합니다. 자세한 정보는 Docker 설명서의 [CPU 공유 제약](https://docs.docker.com/engine/reference/run/#cpu-share-constraint) 섹션을 참조하세요. Linux 커널이 허용하는 최소 유효 CPU 공유 값은 2입니다. 하지만 CPU 파라미터는 필수 항목이 아니며 컨테이너 정의에서 2 미만의 CPU 값을 사용할 수 있습니다. CPU 값이 2 미만일 경우(null 포함)의 동작은 Amazon ECS 컨테이너 에이전트 버전에 따라 달라집니다.
+ **에이전트 버전 1.1.0 이하:** null 및 0의 CPU 값이 Docker에 0으로 전달되고, Docker는 이를 1,024개 CPU 공유로 변환합니다. 1의 CPU 값이 Docker에 1로 전달되고, Linux 커널이 이를 2개 CPU 공유로 변환합니다.
+ **에이전트 버전 1.2.0 이상:** Null, 0, CPU 값 1은 Docker에 2로 전달됩니다.
Windows 컨테이너 인스턴스에서 CPU 한도는 절대 한도(할당량)로 적용됩니다. Windows 컨테이너는 태스크 정의에 기술된 해당 CPU 용량만 액세스할 수 있습니다. Null 또는 0 CPU 값은 Docker에 `0`으로 전달되며, Windows는 이를 한 CPU의 1%로 해석합니다.
### 포트 매핑
`portMappings`
유형: 객체 배열
필수 여부: 아니요
포트 매핑은 컨테이너의 네트워크 포트를 외부에 노출시켜 클라이언트가 애플리케이션에 액세스할 수 있도록 합니다. 이 파라미터는 동일한 태스크 내에서 컨테이너 간 통신에도 사용됩니다.
`awsvpc` 네트워크 모드를 사용하는 태스크 정의의 경우 `containerPort`만 지정합니다. `hostPort`는 항상 무시되며 컨테이너 포트는 호스트에서 임의의 높은 번호의 포트에 자동으로 매핑됩니다.
이 파라미터의 필드 대부분(`containerPort`, `hostPort`, `protocol` 포함)은 Docker 컨테이너 생성 명령에 있는 `PortBindings`와 docker run에 대한 `--publish` 옵션에 매핑됩니다. 태스크 정의의 네트워크 모드가 `host`로 설정되어 있으면 호스트 포트가 정의되지 않은 상태이거나 호스트 포트가 포트 매핑의 컨테이너 포트와 일치해야 합니다.
태스크가 `RUNNING` 상태에 도달한 후에는 다음 위치에서 수동 및 자동 호스트/컨테이너 포트 할당을 확인할 수 있습니다.
+ 콘솔: 선택한 태스크에 대한 컨테이너 설명의 **네트워크 바인딩** 섹션.
+ AWS CLI: **describe-tasks** 명령 출력의 `networkBindings` 섹션.
+ API: `DescribeTasks` 응답.
+ 메타데이터: 작업 메타데이터 엔드포인트.
`appProtocol`
유형: 문자열
필수 여부: 아니요
포트 매핑에 사용되는 애플리케이션 프로토콜입니다. 이 파라미터는 Service Connect에만 적용됩니다. 애플리케이션에서 사용하는 프로토콜과 일치하도록 이 파라미터를 설정하는 것이 좋습니다. 이 파라미터를 설정하면 Amazon ECS가 서비스 연결 프록시에 프로토콜별 연결 처리를 추가합니다. 이 파라미터를 설정하면 Amazon ECS가 Amazon ECS 콘솔과 CloudWatch에 프로토콜별 원격 분석을 추가합니다.
이 파라미터의 값을 설정하지 않으면 TCP가 사용됩니다. 그러나 Amazon ECS는 TCP에 대한 프로토콜별 원격 측정을 추가하지 않습니다.
자세한 내용은 [Service Connect를 사용하여 짧은 이름으로 Amazon ECS 서비스 연결](service-connect.md) 섹션을 참조하세요.
유효한 프로토콜 값: `"HTTP" | "HTTP2" | "GRPC" `
`containerPort`
유형: 정수
필수 항목 여부: 예(`portMappings` 사용 시)
사용자 지정 또는 자동 할당된 호스트 포트에 바인딩되는 컨테이너 포트 번호입니다.
`awsvpc` 네트워크 모드를 사용하는 태스크의 경우 `containerPort`를 사용하여 노출된 포트를 지정합니다.
`containerPortRange`
유형: 문자열
필수 여부: 아니요
동적으로 매핑된 호스트 포트 범위에 바인딩된 컨테이너의 포트 번호 범위입니다.
이 파라미터는 `register-task-definition` API를 사용해서만 설정할 수 있습니다. 옵션은 `portMappings` 파라미터에서 사용할 수 있습니다. 자세한 정보는 *AWS Command Line Interface 참조*의 [register-task-definition](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html)을 참조하세요.
`containerPortRange` 지정 시 다음 규칙이 적용됩니다.
+ `awsvpc` 네트워크 모드를 사용해야 합니다.
+ 컨테이너 인스턴스의 컨테이너 에이전트 버전은 1.67.0 이상이어야 하고 `ecs-init` 패키지의 버전은 1.67.0-1 이상이어야 합니다.
+ 컨테이너당 최대 100개의 포트 범위를 지정할 수 있습니다.
+ `hostPortRange`는 지정하지 않습니다. `hostPortRange`의 값은 다음과 같이 설정됩니다.
+ `awsvpc` 네트워크 모드를 사용하는 작업에 있는 컨테이너의 경우 `hostPort`는 `containerPort`와 동일한 값으로 설정됩니다. 이는 정적 매핑 전략입니다.
+ `containerPortRange`의 유효한 값은 1\$165,535입니다.
+ 포트는 컨테이너당 하나의 포트 매핑에만 포함될 수 있습니다.
+ 중첩되는 포트 범위는 지정할 수 없습니다.
+ 범위의 첫 번째 포트는 범위의 마지막 포트보다 작아야 합니다.
+ Docker에서는 포트 수가 많을 때 Docker 대몬(daemon) 구성 파일에서 docker-proxy를 끌 것을 권장합니다.
자세한 내용은 GitHub의 [Issue \$111185](https://github.com/moby/moby/issues/11185)를 참조하세요.
Docker 대몬(daemon) 구성 파일에서 docker-proxy를 끄는 방법에 대한 자세한 내용은 *Amazon ECS 개발자 안내서*의 [Docker daemon](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/bootstrap_container_instance.html#bootstrap_docker_daemon)을 참조하세요.
[DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html)를 직접적으로 호출하여 컨테이너 포트에 바인딩된 호스트 포트인 `hostPortRange`를 볼 수 있습니다.
포트 범위는 EventBridge로 전송되는 Amazon ECS 작업 이벤트에 포함되지 않습니다. 자세한 내용은 [EventBridge를 사용하여 Amazon ECS 오류에 대한 응답 자동화](cloudwatch_event_stream.md) 섹션을 참조하세요.
`hostPortRange`
유형: 문자열
필수 여부: 아니요
네트워크 바인딩에 사용되는 호스트의 포트 번호 범위입니다. 이 값은 Docker가 할당하고 Amazon ECS 에이전트가 전달합니다.
`hostPort`
유형: 정수
필수 여부: 아니요
컨테이너용으로 예약할 컨테이너 인스턴스 포트 번호입니다.
`hostPort`는 비워 두거나 `containerPort`와 같은 값을 지정할 수 있습니다.
기본 임시 포트 범위 Docker 1.6.0 버전 이상은 인스턴스의 `/proc/sys/net/ipv4/ip_local_port_range`에 나열됩니다. 이 커널 파라미터를 사용할 수 없을 경우 기본 휘발성 포트 범위 `49153–65535`가 사용됩니다. 휘발성 포트 범위에서 호스트 포트를 지정하지 마세요. 자동 할당을 위해 예약되어 있기 때문입니다. 일반적으로 `32768` 미만의 포트는 임시 포트 범위를 벗어납니다.
기본 예약 포트는 SSH용 `22`, Docker 포트 `2375` 및 `2376`, Amazon ECS 컨테이너 에이전트 포트 `51678-51680`입니다. 실행 중인 작업에 대해 기존에 사용자 지정된 호스트 포트도 해당 작업이 실행되는 동안 예약됩니다. 작업이 중지하면 호스트 포트는 해제됩니다. 현재 예약된 포트는 **describe-container-instances** 출력의 `remainingResources`에 표시됩니다. 하나의 컨테이너 인스턴스는 한 번에 최대 100개의 예약 포트(기본 예약 포트 포함)를 가질 수 있습니다. 자동 할당된 포트는 예약 포트 할당량 100개에 포함되지 않습니다.
`name`
유형: 문자열
필수: 아니요, 서비스에서 Service Connect와 VPC Lattice를 구성하는 데 필요
포트 매핑에 사용되는 이름입니다. 이 파라미터는 Service Connect와 VPC Lattice에만 적용됩니다. 이 파라미터는 서비스의 Service Connect와 VPC Lattice 구성에서 사용하는 이름입니다.
자세한 내용은 [Service Connect를 사용하여 짧은 이름으로 Amazon ECS 서비스 연결](service-connect.md) 섹션을 참조하세요.
다음 예제에서는 Service Connect와 VPC Lattice의 필수 필드를 모두 사용합니다.
```
"portMappings": [
{
"name": string,
"containerPort": integer
}
]
```
`protocol`
유형: 문자열
필수 여부: 아니요
포트 매핑에 사용되는 프로토콜입니다. 유효 값은 `tcp` 및 `udp`입니다. 기본값은 `tcp`입니다.
Service Connect에는 `tcp`만 지원됩니다. 이 필드가 설정되지 않은 경우 `tcp`로 암시됩니다.
호스트 포트를 지정하는 경우 다음 구문을 사용합니다.
```
"portMappings": [
{
"containerPort": integer,
"hostPort": integer
}
...
]
```
호스트 포트가 자동 할당되도록 하려면 다음 구문을 사용합니다.
```
"portMappings": [
{
"containerPort": integer
}
...
]
```
### 프라이빗 리포지토리 보안 인증
`repositoryCredentials`
유형: [RepositoryCredentials](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RepositoryCredentials.html) 객체
필수 여부: 아니요
프라이빗 레지스트리 인증을 위한 리포지토리 보안 인증입니다.
자세한 내용은 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md) 섹션을 참조하세요.
`credentialsParameter`
유형: 문자열
필수 항목 여부: 예(`repositoryCredentials` 사용 시)
프라이빗 리포지토리 자격 증명이 포함된 암호의 Amazon 리소스 이름(ARN)입니다.
자세한 내용은 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md) 섹션을 참조하세요.
Amazon ECS API, AWS CLI 또는 AWS SDK를 사용할 때 시작하는 작업과 같은 리전에 보안 암호가 있는 경우 보안 암호의 전체 ARN 또는 이름을 사용할 수 있습니다. AWS Management Console을 사용하는 경우 보안 암호의 전체 ARN을 지정해야 합니다.
다음은 필요한 파라미터를 나타낸 태스크 정의의 예제 조각입니다.
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
### Essential
`essential`
유형: 부울
필수 여부: 아니요
컨테이너의 `essential` 파라미터가 `true`로 표시된 경우 해당 컨테이너가 어떤 이유로든 실패 또는 중지하는 경우 태스크의 일부인 다른 모든 컨테이너도 중지합니다. 컨테이너의 `essential` 파라미터가 `false`로 표시된 경우에는 해당 컨테이너의 실패가 태스크의 나머지 컨테이너에 영향을 주지 않습니다. 이 파라미터가 생략된 경우 컨테이너가 필수로 간주됩니다.
모든 태스크에는 하나 이상의 필수 컨테이너가 있어야 합니다. 애플리케이션이 여러 컨테이너로 구성되는 경우 동일한 용도로 사용되는 컨테이너를 구성 요소로 그룹화하고 각 구성 요소를 서로 다른 태스크 정의로 분리합니다. 자세한 내용은 [Amazon ECS에 대한 애플리케이션 설계](application_architecture.md) 섹션을 참조하세요.
### 진입점
`entryPoint`
유형: 문자열 배열
필수 여부: 아니요
컨테이너로 전달되는 진입점입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Entrypoint` 및 docker run에 대한 `--entrypoint` 옵션에 매핑됩니다.
```
"entryPoint": ["string", ...]
```
### Command
`command`
유형: 문자열 배열
필수 여부: 아니요
컨테이너로 전달되는 명령입니다. 이 파라미터는 docker create-container 명령의 `Cmd` 및 docker run에 대한 `COMMAND` 파라미터에 매핑됩니다. 여러 인수가 있는 경우 각 인수는 배열에서 각각 분리된 문자열입니다.
```
"command": ["string", ...]
```
### 작업 디렉터리
`workingDirectory`
유형: 문자열
필수 여부: 아니요
컨테이너에서 명령을 실행할 태스크 디렉터리입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `WorkingDir` 및 docker run에 대한 `--workdir` 옵션에 매핑됩니다.
### 고급 컨테이너 정의 파라미터
다음의 고급 컨테이너 정의 파라미터는 Amazon ECS 컨테이너 인스턴스에서 컨테이너를 시작하는 데 사용된 docker run 명령에 확장된 기능을 제공합니다.
**Topics**
+ [재시작 정책](#container_definition_restart_policy-managed-instances)
+ [상태 확인](#container_definition_healthcheck-managed-instances)
+ [환경](#container_definition_environment-managed-instances)
+ [보안](#container_definition_security-managed-instances)
+ [네트워크 설정](#container_definition_network-managed-instances)
+ [스토리지 및 로깅](#container_definition_storage-managed-instances)
+ [리소스 요구 사항](#container_definition_resourcerequirements-managed-instances)
+ [컨테이너 제한 시간](#container_definition_timeout-managed-instances)
+ [컨테이너 종속성](#container_definition_dependency-managed-instances)
+ [System Controls](#container_definition_systemcontrols-managed-instances)
+ [대화형](#container_definition_interactive-managed-instances)
+ [의사 터미널](#container_definition_pseudoterminal-managed-instances)
#### 재시작 정책
`restartPolicy`
컨테이너 재시작 정책 및 관련 구성 파라미터. 컨테이너의 재시작 정책을 설정하면 작업을 교체할 필요 없이 Amazon ECS에서 컨테이너를 다시 시작할 수 있습니다. 자세한 내용은 [컨테이너 재시작 정책이 있는 Amazon ECS 작업의 개별 컨테이너 재시작](container-restart-policy.md) 섹션을 참조하세요.
`enabled`
유형: Boolean
필수 여부: 예
재시작 정책이 컨테이너에 대해 활성화되는지 여부를 지정합니다.
`ignoredExitCodes`
유형: 정수 배열
필수 여부: 아니요
Amazon ECS가 재시작을 시도하지 않고 무시하는 종료 코드 목록입니다. 최대 50개의 컨테이너 종료 코드를 지정할 수 있습니다. 기본적으로 Amazon ECS는 종료 코드를 무시하지 않습니다.
`restartAttemptPeriod`
유형: 정수
필수 여부: 아니요
재시작을 시도하기 전에 컨테이너를 실행해야 하는 시간(초)입니다. 컨테이너는 `restartAttemptPeriod`초 당 한 번만 재시작할 수 있습니다. 이 기간 동안 컨테이너를 실행할 수 없고 일찍 종료되면 다시 시작되지 않습니다. 최소 60초의 `restartAttemptPeriod`와 최대 1,800초의 `restartAttemptPeriod`를 설정할 수 있습니다. 기본적으로 컨테이너는 300초 동안 실행되어야 재시작할 수 있습니다.
#### 상태 확인
`healthCheck`
해당 컨테이너에 대한 컨테이너 상태 확인 명령 및 연결된 구성 파라미터. 자세한 내용은 [컨테이너 상태 확인을 사용하여 Amazon ECS 작업 상태 확인](healthcheck.md) 섹션을 참조하세요.
`command`
상태가 정상인지를 확인하기 위해 컨테이너가 실행하는 명령을 나타내는 문자열 배열입니다. 명령 인수를 직접 실행하려면 문자열 어레이가 `CMD`으로 시작하면 되고, 컨테이너의 기본 셸에서 명령을 실행하려면 `CMD-SHELL`로 시작하면 됩니다. 둘 다 지정하지 않으면 `CMD`가 사용됩니다.
AWS Management Console에서 작업 정의를 등록할 때는 쉼표로 구분된 명령 목록을 사용합니다. 이러한 명령은 작업 정의가 생성된 후 문자열로 변환됩니다. 다음은 상태 확인에 대한 입력 예제입니다.
```
CMD-SHELL, curl -f http://localhost/ || exit 1
```
AWS Management Console JSON 패널, AWS CLI 또는 API를 사용하여 작업 정의를 등록할 때는 명령 목록을 괄호로 묶어야 합니다. 다음은 상태 확인에 대한 입력 예제입니다.
```
[ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]
```
`stderr` 출력이 없는 종료 코드 0은 성공을 나타내고, 0이 아닌 종료 코드는 실패를 나타냅니다.
`interval`
각 상태 확인 간의 시간(초). 5초에서 300초 사이를 지정할 수 있습니다. 기본값은 30초입니다.
`timeout`
실패로 간주되기 전에 상태 확인이 성공하기까지의 대기 시간(초)입니다. 2초에서 60초 사이를 지정할 수 있습니다. 기본값은 5초입니다.
`retries`
컨테이너 상태가 비정상이라고 간주되기 전에 실패한 상태 확인을 재시도하는 횟수입니다. 1에서 10 사이의 재시도 횟수를 지정할 수 있습니다. 기본값은 3회 재시도입니다.
`startPeriod`
실패한 상태 확인이 최대 재시도 횟수에 포함되기 전에 컨테이너에 부트스트랩 시간이 제공되는 유예 기간 옵션입니다. 0\$1300초 범위의 값을 지정할 수 있습니다. 기본적으로 `startPeriod`는 비활성화되어 있습니다.
상태 검사가 `startPeriod` 내에 성공한 경우 컨테이너는 정상으로 간주되고 모든 후속 실패는 최대 재시도 횟수에 포함됩니다.
#### 환경
`cpu`
유형: 정수
필수 여부: 아니요
Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 `cpu` 단위입니다. Linux에서 이 파라미터는 [컨테이너 만들기](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate) 섹션의 `CpuShares`에 매핑됩니다.
이 필드는 Amazon ECS 관리형 인스턴스에서 실행되는 태스크의 경우 선택 사항입니다. 태스크 내 모든 컨테이너에 대해 예약된 총 CPU 양은 태스크 수준 `cpu` 값보다 작아야 합니다.
Linux 컨테이너는 할당된 양과 동일한 비율로, 컨테이너 인스턴스의 다른 컨테이너와 할당되지 않은 CPU 단위를 공유합니다. 예를 들어 싱글 코어 인스턴스 유형에서 단일 컨테이너 작업을 컨테이너에 512개 CPU 단위를 지정하고 실행한다고 가정해 보겠습니다. 또한 이 작업은 컨테이너 인스턴스에서 실행되는 유일한 작업입니다. 이 예에서 컨테이너는 언제라도 1,024 CPU 단위 전부를 사용할 수 있습니다. 하지만, 해당 컨테이너 인스턴스에서 동일한 태스크의 다른 사본을 시작했다고 가정합니다. 각 작업에는 필요한 경우 최소 512개의 CPU 단위가 보장됩니다. 마찬가지로 다른 컨테이너가 나머지 CPU를 사용하지 않을 경우 각 컨테이너의 CPU 사용량이 높아질 수 있습니다. 하지만 두 작업이 항상 100% 활성 상태인 경우 CPU 단위는 512개로 제한됩니다.
Linux 컨테이너 인스턴스에서, 컨테이너 인스턴스의 Docker 대몬(daemon)은 CPU 값을 사용하여 실행 컨테이너의 상대적인 CPU 공유 비율을 계산합니다. Linux 커널이 허용하는 최소 유효 CPU 공유 값은 2이고, Linux 커널이 허용하는 최대 유효 CPU 공유 값은 262144입니다. 하지만 CPU 파라미터는 필수 항목이 아니며 컨테이너 정의에서 2 미만이나 262144를 초과하는 CPU 값을 사용할 수 있습니다. CPU 값이 2 미만(null 포함)이거나 262144를 초과하는 경우 동작은 Amazon ECS 컨테이너 에이전트 버전에 따라 달라집니다.
추가 예제는 [How Amazon ECS manages CPU and memory resources](https://aws.amazon.com/blogs/containers/how-amazon-ecs-manages-cpu-and-memory-resources/)를 참조하세요.
`gpu`
유형: [ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 객체
필수 여부: 아니요
Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 실제 `GPUs` 수입니다. 태스크의 모든 컨테이너에 예약된 GPU 수가 태스크가 실행되는 컨테이너 인스턴스에서 사용할 수 있는 GPU 수를 초과하면 안 됩니다. 자세한 내용은 [GPU 워크로드에 대한 Amazon ECS 작업 정의](ecs-gpu.md) 섹션을 참조하세요.
`Elastic Inference accelerator`
이 파라미터는 Amazon ECS 관리형 인스턴스에서 호스팅되는 컨테이너에 대해 지원되지 않습니다.
유형: [ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 객체
필수 여부: 아니요
`InferenceAccelerator` 유형의 경우 `value`는 태스크 정의에 지정된 `InferenceAccelerator`의 `deviceName`과 일치합니다. 자세한 내용은 [Elastic Inference 액셀러레이터 이름(폐기됨)](task_definition_parameters.md#elastic-Inference-accelerator) 섹션을 참조하세요.
`essential`
유형: 부울
필수 여부: 아니요
컨테이너의 `essential` 파라미터가 `true`로 표시되어 있고 해당 컨테이너가 어떤 이유로든 실패 또는 중지하는 경우를 가정해 보겠습니다. 이 경우 작업에 포함된 다른 모든 컨테이너도 중지합니다. 컨테이너의 `essential` 파라미터가 `false`로 표시된 경우에는 해당 컨테이너의 실패가 태스크의 나머지 컨테이너에 영향을 주지 않습니다. 이 파라미터가 생략된 경우 컨테이너가 필수로 간주됩니다.
모든 태스크에는 하나 이상의 필수 컨테이너가 있어야 합니다. 여러 컨테이너로 구성된 애플리케이션이 있다고 가정해 보겠습니다. 이 경우, 공통 용도로 사용되는 컨테이너를 구성 요소로 그룹화하고, 다른 구성 요소를 여러 작업 정의로 분리합니다. 자세한 내용은 [Amazon ECS에 대한 애플리케이션 설계](application_architecture.md) 섹션을 참조하세요.
```
"essential": true|false
```
`entryPoint`
초기 버전의 Amazon ECS 컨테이너 에이전트는 `entryPoint` 파라미터를 적절히 처리하지 못합니다. `entryPoint`를 사용하는 데 문제가 있을 경우 컨테이너 에이전트를 업데이트하거나 명령 및 인수를 `command` 배열 항목으로 입력하세요.
유형: 문자열 배열
필수 여부: 아니요
컨테이너로 전달되는 진입점입니다.
```
"entryPoint": ["string", ...]
```
`command`
유형: 문자열 배열
필수 여부: 아니요
컨테이너로 전달되는 명령입니다. 이 파라미터는 컨테이너 생성 명령의 `Cmd` 및 docker run에 대한 `COMMAND` 파라미터에 매핑됩니다. 여러 인수가 있는 경우 각 인수는 배열에서 각각 분리된 문자열이어야 합니다.
```
"command": ["string", ...]
```
`workingDirectory`
유형: 문자열
필수 여부: 아니요
컨테이너에서 명령을 실행할 태스크 디렉터리입니다. 이 파라미터는 [Docker 원격 API](https://docs.docker.com/reference/api/engine/version/v1.38/)의 [컨테이너 생성](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate) 섹션에 있는 `WorkingDir`와 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/)에 대한 `--workdir` 옵션에 매핑됩니다.
```
"workingDirectory": "string"
```
`environmentFiles`
유형: 객체 배열
필수 여부: 아니요
컨테이너로 전달할 환경 변수를 포함하는 파일 목록입니다. 이 파라미터는 docker run 명령에 대한 `--env-file` 옵션에 매핑됩니다.
최대 10개의 환경 파일을 지정할 수 있습니다. 파일의 확장명은 `.env`여야 합니다. 환경 파일의 각 줄에는 `VARIABLE=VALUE` 형식의 환경 변수를 포함합니다. `#`으로 시작하는 줄은 주석으로 처리되며 무시됩니다.
컨테이너 정의에 지정된 개별 환경 변수가 있는 경우 환경 파일 내에 포함된 변수보다 우선합니다. 동일한 변수를 포함하는 여러 환경 파일이 지정된 경우 위에서 아래로 처리됩니다. 고유한 변수 이름을 사용하는 것이 좋습니다. 자세한 정보는 [개별 환경 변수를 Amazon ECS 컨테이너로 전달](taskdef-envfiles.md)을 참조하세요.
`value`
유형: 문자열
필수 항목 여부: 예
환경 변수 파일을 포함하는 Amazon S3 객체의 Amazon 리소스 이름(ARN)입니다.
`type`
유형: 문자열
필수 항목 여부: 예
사용할 파일 유형입니다. 지원되는 유일한 값은 `s3`입니다.
`environment`
유형: 객체 배열
필수 여부: 아니요
컨테이너로 전달할 환경 변수입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Env` 및 docker run 명령에 대한 `--env` 옵션에 매핑됩니다.
자격 증명 데이터와 같은 민감한 정보에 대해서는 일반 텍스트 환경 변수를 사용하지 않는 것이 좋습니다.
`name`
유형: 문자열
필수 항목 여부: `environment` 사용 시, 예
환경 변수의 이름입니다.
`value`
유형: 문자열
필수 항목 여부: `environment` 사용 시, 예
환경 변수의 값입니다.
```
"environment" : [
{ "name" : "string", "value" : "string" },
{ "name" : "string", "value" : "string" }
]
```
`secrets`
유형: 객체 배열
필수 여부: 아니요
컨테이너에 공개할 보안 암호를 나타내는 객체입니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너에서 환경 변수로 설정할 값입니다.
`valueFrom`
유형: 문자열
필수 항목 여부: 예
컨테이너에 노출될 암호입니다. 지원되는 값은 AWS Secrets Manager 암호의 전체 ARN이거나 혹은 AWS Systems Manager 파라미터 스토어 내 파라미터의 전체 Amazon 리소스 이름(ARN)입니다.
Systems Manager Parameter Store 파라미터 또는 Secrets Manager 파라미터가 현재 실행 중인 작업과 동일한 AWS 리전에 있을 경우 해당 암호의 전체 ARN 또는 이름을 사용할 수 있습니다. 파라미터가 다른 리전에 있다면 전체 ARN을 지정해야 합니다.
```
"secrets": [
{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}
]
```
#### 보안
`privileged`
유형: 부울
필수 여부: 아니요
이 파라미터가 `true`인 경우 컨테이너에는 호스트 컨테이너 인스턴스에 대한 승격된 권한을 부여받습니다(`root` 사용자와 비슷함). 이 파라미터는 Docker 컨테이너 생성 명령의 `Privileged` 및 docker run에 대한 `--privileged` 옵션에 매핑됩니다.
`user`
유형: 문자열
필수 여부: 아니요
컨테이너 내부에서 사용할 사용자입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `User` 및 docker run에 대한 `--user` 옵션에 매핑됩니다.
`host` 네트워크 모드를 사용하여 태스크를 실행할 때는 루트 사용자(UID 0)를 사용하여 컨테이너를 실행하지 마세요. 보안 강화를 위해 루트가 아닌 사용자를 사용하는 것이 좋습니다.
다음 형식을 사용하여 `user`를 지정할 수 있습니다. UID 또는 GID를 지정하는 경우 이를 양의 정수로 지정해야 합니다.
+ `user`
+ `user:group`
+ `uid`
+ `uid:gid`
+ `user:gid`
+ `uid:group`
`readonlyRootFilesystem`
유형: 부울
필수 여부: 아니요
이 파라미터가 `true`인 경우 컨테이너에는 루트 파일 시스템에 대한 읽기 전용 액세스가 부여됩니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `ReadonlyRootfs` 및 docker run에 대한 `--read-only` 옵션에 매핑됩니다.
`dockerSecurityOptions`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 문자열 배열
필수 여부: 아니요
SELinux 및 AppArmor 다중 수준 보안 시스템에 사용자 지정 레이블을 제공할 문자열 목록입니다. 이 필드는 Fargate를 사용하는 태스크의 컨테이너에서 유효하지 않습니다.
`ulimits`
유형: [Ulimit](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Ulimit.html) 객체 배열
필수 여부: 아니요
컨테이너에 설정할 `ulimits`의 목록입니다. 태스크 정의에 ulimit 값이 지정된 경우 Docker에서 설정한 기본값을 재정의합니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Ulimits` 및 docker run에 대한 `--ulimit` 옵션에 매핑됩니다. 유효한 이름 지정 값이 [Ulimit](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Ulimit.html) 데이터 형식에 표시됩니다.
Fargate에 호스팅되는 Amazon ECS 태스크는 Fargate가 재정의하는 `nofile` 리소스 제한 파라미터를 제외하고 운영 체제에서 설정한 기본 리소스 제한 값을 사용합니다. `nofile` 리소스 제한은 컨테이너가 사용할 수 있는 열린 파일 수에 대한 제한을 설정합니다. 기본 `nofile` 소프트 제한은 `1024`이고 기본 하드 제한은 `65535`입니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다. 컨테이너 인스턴스의 도커 원격 API 버전을 확인하려면, 컨테이너 인스턴스에 로그인한 후 `sudo docker version --format '{{.Server.APIVersion}}'` 명령을 실행합니다.
`dockerLabels`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
컨테이너에 추가할 레이블의 키/값 맵입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Labels` 및 docker run에 대한 `--label` 옵션에 매핑됩니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다.
```
"dockerLabels": {"string": "string"
...}
```
#### 네트워크 설정
`disableNetworking`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 부울
필수 여부: 아니요
이 파라미터가 true일 경우 컨테이너 내에서 네트워킹이 해제됩니다.
기본값은 `false`입니다.
```
"disableNetworking": true|false
```
`links`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 문자열 배열
필수 여부: 아니요
`link` 파라미터는 포트 매핑 필요 없이 컨테이너가 서로 통신하도록 허용합니다. 이 파라미터는 작업 정의의 네트워크 모드가 `bridge`로 설정된 경우에만 지원됩니다. `name:internalName` 구성은 Docker 링크의 `name:alias`와 유사합니다. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈 및 밑줄이 허용됩니다.
동일한 컨테이너 인스턴스에 배치된 컨테이너는 링크 또는 호스트 포트 매핑 없이도 서로 통신할 수 있습니다. 컨테이너 인스턴스에서 네트워크 격리는 보안 그룹 및 VPC 설정에 의해 제어됩니다.
```
"links": ["name:internalName", ...]
```
`hostname`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 문자열
필수 여부: 아니요
컨테이너에 사용할 호스트 이름입니다. 이 파라미터는 Docker 컨테이너 생성의 `Hostname` 및 docker run에 대한 `--hostname` 옵션에 매핑됩니다.
```
"hostname": "string"
```
`dnsServers`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 문자열 배열
필수 여부: 아니요
컨테이너에 제공되는 DNS 서버의 목록입니다.
```
"dnsServers": ["string", ...]
```
`extraHosts`
이 파라미터는 `awsvpc` 네트워크 모드를 사용하는 작업에 대해서는 지원되지 않습니다.
유형: 객체 배열
필수 여부: 아니요
컨테이너의 `/etc/hosts` 파일에 추가할 호스트 이름 및 IP 주소 매핑의 목록입니다.
이 파라미터는 Docker 컨테이너 생성 명령의 `ExtraHosts` 및 docker run에 대한 `--add-host` 옵션에 매핑됩니다.
```
"extraHosts": [
{
"hostname": "string",
"ipAddress": "string"
}
...
]
```
`hostname`
유형: 문자열
필수 항목 여부: 예(`extraHosts` 사용 시)
`/etc/hosts` 항목에 사용할 호스트 이름입니다.
`ipAddress`
유형: 문자열
필수 항목 여부: 예(`extraHosts` 사용 시)
`/etc/hosts` 항목에 사용할 IP 주소입니다.
#### 스토리지 및 로깅
`readonlyRootFilesystem`
유형: 부울
필수 여부: 아니요
이 파라미터가 true일 경우 컨테이너에는 루트 파일 시스템에 대한 읽기 전용 액세스가 부여됩니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `ReadonlyRootfs` 및 docker run에 대한 `--read-only` 옵션에 매핑됩니다.
기본값은 `false`입니다.
```
"readonlyRootFilesystem": true|false
```
`mountPoints`
유형: 객체 배열
필수 여부: 아니요
컨테이너에서 데이터 볼륨의 탑재 지점입니다. 이 파라미터는 create-container Docker API의 `Volumes` 및 docker run에 대한 `--volume` 옵션에 매핑됩니다.
Windows 컨테이너는 전체 디렉터리를 동일한 드라이브에 `$env:ProgramData`로 마운트할 수 있습니다. Windows 컨테이너는 디렉터리를 다른 드라이브에 탑재할 수 없으며, 탑재 지점은 여러 드라이브에 걸쳐 사용할 수 없습니다. Amazon EBS 볼륨을 Amazon ECS 작업에 직접 연결하려면 탑재 지점을 지정해야 합니다.
`sourceVolume`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
탑재할 볼륨의 이름입니다.
`containerPath`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
볼륨을 탑재할 컨테이너의 경로입니다.
`readOnly`
유형: 부울
필수 여부: 아니요
이 값이 `true`일 경우 컨테이너에는 볼륨에 대한 읽기 전용 액세스가 부여됩니다. 이 값이 `false`일 경우 컨테이너는 볼륨에 쓸 수 있습니다. 기본값은 `false`입니다.
Windows 운영 체제를 실행하는 EC2 인스턴스에서 실행되는 태스크의 경우 값을 기본값인 `false`로 둡니다.
`volumesFrom`
유형: 객체 배열
필수 여부: 아니요
다른 컨테이너로부터 탑재할 데이터 볼륨입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `VolumesFrom` 및 docker run에 대한 `--volumes-from` 옵션에 매핑됩니다.
`sourceContainer`
유형: 문자열
필수 항목 여부: `volumesFrom` 사용 시, 예
탑재할 볼륨이 위치한 컨테이너의 이름입니다.
`readOnly`
유형: 부울
필수 여부: 아니요
이 값이 `true`일 경우 컨테이너에는 볼륨에 대한 읽기 전용 액세스가 부여됩니다. 이 값이 `false`일 경우 컨테이너는 볼륨에 쓸 수 있습니다. 기본값은 `false`입니다.
```
"volumesFrom": [
{
"sourceContainer": "string",
"readOnly": true|false
}
]
```
`logConfiguration`
유형: [LogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) 객체
필수 여부: 아니요
컨테이너의 로그 구성 사양입니다.
로그 구성을 사용하는 태스크 정의에 대한 자세한 정보는 [Amazon ECS 작업 정의 예제](example_task_definitions.md) 섹션을 참조하세요.
이 파라미터는 Docker 컨테이너 생성 명령의 `LogConfig` 및 docker run에 대한 `--log-driver` 옵션에 매핑됩니다. 기본적으로 컨테이너는 Docker 대몬(daemon)이 사용하는 것과 동일한 로깅 드라이버를 사용합니다. 하지만 컨테이너는 이 파라미터를 사용하여 컨테이너 정의에 로그 드라이버를 지정함으로써 Docker 대몬(daemon)과 다른 로깅 드라이버를 사용할 수 있습니다. 컨테이너에 다른 로깅 드라이버를 사용하려면 컨테이너 인스턴스에서(또는 원격 로깅 옵션의 다른 로그 서버에서) 로그 시스템이 올바르게 구성되어야 합니다.
컨테이너에 대한 로그 구성을 지정할 때 다음 사항에 유의해야 합니다.
+ Amazon ECS는 Docker 대몬(daemon)에 사용 가능한 로깅 드라이버의 하위 집합을 지원합니다.
+ 이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker Remote API 버전 1.18 이상을 사용해야 합니다.
```
"logConfiguration": {
"logDriver": "awslogs",""splunk", "awsfirelens",
"options": {"string": "string"
...},
"secretOptions": [{
"name": "string",
"valueFrom": "string"
}]
}
```
`logDriver`
타입: 문자열
유효한 값: `"awslogs","splunk","awsfirelens"`
필수 항목 여부: `logConfiguration` 사용 시, 예
컨테이너에 사용할 로드 드라이버입니다. 앞에 나열된 유효한 값은 Amazon ECS 컨테이너 에이전트가 기본적으로 통신할 수 있는 로그 드라이버입니다.
지원되는 로그 드라이버는 `awslogs`, `splunk` 및 `awsfirelens`입니다.
태스크 정의에서 `awslogs` 로그 드라이버를 사용하여 컨테이너 로그를 CloudWatch Logs로 보내는 방법에 대한 자세한 정보는 [Amazon ECS 로그를 CloudWatch로 전송](using_awslogs.md) 섹션을 참조하세요.
`awsfirelens` 로그 드라이버에 대한 자세한 내용은 [Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송](using_firelens.md) 섹션을 참조하세요.
목록에 포함되지 않은 사용자 지정 드라이버가 있는 경우, [GitHub에서 사용 가능한](https://github.com/aws/amazon-ecs-agent) Amazon ECS 컨테이너 에이전트 프로젝트를 포킹하여 해당 드라이버와 함께 작동하도록 사용자 지정할 수 있습니다. 포함하고 싶은 변경에 대해서는 풀 요청을 제출할 것을 권장합니다. 단, 현재 이 소프트웨어의 수정된 사본 실행은 지원되지 않습니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다.
`options`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
로그 드라이버로 보낼 구성 옵션의 키/값 맵입니다.
지정할 수 있는 옵션은 로그 드라이버에 따라 달라집니다. 다음은 `awslogs` 라우터를 사용하여 로그를 Amazon CloudWatch로 라우팅할 때 지정할 수 있는 몇 가지 옵션입니다.
`awslogs-create-group`
필수 여부: 아니요
로그 그룹을 자동으로 생성할지를 지정합니다. 이 옵션이 지정되지 않은 경우 기본적으로 `false`로 설정됩니다.
`awslogs-create-group`을 사용하기 전에 IAM 정책이 `logs:CreateLogGroup` 권한을 포함해야 합니다.
`awslogs-region`
필수 여부: 예
`awslogs` 로그 드라이버가 Docker 로그를 보낼 AWS 리전을 지정합니다. 여러 리전의 클러스터로부터 모든 로그를 CloudWatch Logs 내 단일 리전으로 전송하도록 선택할 수 있습니다. 이는 로그를 모두 한 곳에서 볼 수 있도록 하기 위함입니다. 또는, 리전별로 구분하여 세분화할 수 있습니다. 지정한 로그 그룹이 이 옵션으로 지정한 리전에 위치하는지 확인하세요.
`awslogs-group`
필수 여부: 예
`awslogs` 로그 드라이버가 로그 스트림을 전송할 로그 그룹을 지정해야 합니다.
`awslogs-stream-prefix`
필수 여부: 예
`awslogs-stream-prefix` 옵션을 사용하여 로그 스트림을 지정한 접두사, 컨테이너 이름 및 컨테이너가 속하는 Amazon ECS 태스크의 ID와 연결할 수 있습니다. 이 옵션을 사용하여 접두사를 지정하는 경우 로그 스트림은 다음 형식을 취합니다.
```
prefix-name/container-name/ecs-task-id
```
이 옵션을 사용하여 접두사를 지정하지 않는 경우 로그 스트림 이름이 컨테이너 인스턴스의 Docker 대몬에 의해 할당된 컨테이너 ID를 따서 지정됩니다. Docker 컨테이너 ID(컨테이너 인스턴스에서만 사용 가능)만으로는 로그를 전송한 컨테이너로 역추적하기 어려우므로 이 옵션에서 접두사를 지정하는 것이 좋습니다.
Amazon ECS 서비스의 경우 서비스 이름을 접두사로 사용할 수 있습니다. 이렇게 하면 로그 스트림을 컨테이너가 속하는 서비스, 로그를 전송한 컨테이너의 이름, 컨테이너가 속하는 작업의 ID로 추적할 수 있습니다.
Amazon ECS 콘솔을 사용할 때 로그 창에 로그가 표시되도록 하기 위해서는 해당 로그에 스트림 접두사를 지정해야 합니다.
`awslogs-datetime-format`
필수 여부: 아니요
이 옵션은 Python `strftime` 형식의 여러 줄 시작 패턴을 정의합니다. 로그 메시지는 패턴과 일치하는 하나의 줄과 패턴과 일치하지 않는 나머지 줄들로 이루어져 있습니다. 일치하는 줄은 로그 메시지 간의 구분 기호입니다.
이 형식을 사용하는 사용 사례의 한 예는 스택 덤프와 같은 출력을 구문 분석하는 것이며, 그렇지 않으면 여러 항목에 기록될 수 있습니다. 올바른 패턴을 통해 단일 항목으로 캡처할 수 있습니다.
자세한 내용은 [awslogs-datetime-format](https://docs.docker.com/engine/logging/drivers/awslogs/#awslogs-datetime-format)을 참조하세요.
`awslogs-datetime-format` 및 `awslogs-multiline-pattern` 옵션을 모두 구성할 수는 없습니다.
여러 줄 로깅은 모든 로그 메시지의 정규식 구문 분석 및 일치 태스크를 수행합니다. 이는 로깅 성능에 부정적인 영향을 줄 수 있습니다.
`awslogs-multiline-pattern`
필수 여부: 아니요
이 옵션은 정규식을 사용하여 여러 줄 시작 패턴을 정의합니다. 로그 메시지는 패턴과 일치하는 하나의 줄과 패턴과 일치하지 않는 나머지 줄들로 이루어져 있습니다. 일치하는 줄은 로그 메시지 간의 구분 기호입니다.
자세한 정보는 [awslogs-multiline-pattern](https://docs.docker.com/engine/logging/drivers/awslogs/#awslogs-multiline-pattern)을 참조하세요.
이 옵션은 `awslogs-datetime-format`을 구성하는 경우에 무시됩니다.
`awslogs-datetime-format` 및 `awslogs-multiline-pattern` 옵션을 모두 구성할 수는 없습니다.
여러 줄 로깅은 모든 로그 메시지의 정규식 구문 분석 및 일치 태스크를 수행합니다. 이는 로깅 성능에 부정적인 영향을 줄 수 있습니다.
`mode`
필수 여부: 아니요
유효한 값: `non-blocking` \$1 `blocking`
이 옵션은 컨테이너에서 `awslogs` 로그 드라이버로 로그 메시지를 전송하는 모드를 정의합니다. 선택한 전송 모드는 컨테이너에서 나오는 로그 흐름이 중단될 때 애플리케이션 가용성에 영향을 줍니다.
`blocking` 모드를 사용하는 경우 CloudWatch로의 로그 흐름이 중단되면 `stdout` 및 `stderr` 스트림에 쓰기 위한 컨테이너 코드의 호출이 차단됩니다. 결과적으로 애플리케이션의 로깅 스레드가 차단됩니다. 이로 인해 애플리케이션이 응답하지 않고 컨테이너 상태 확인에 실패할 수 있습니다.
`non-blocking` 모드를 사용하는 경우 컨테이너의 로그는 `max-buffer-size` 옵션으로 구성된 인 메모리 중간 버퍼에 대신 저장됩니다. 이렇게 하면 로그를 CloudWatch로 전송할 수 없을 때 애플리케이션이 응답하지 않게 되는 것을 방지할 수 있습니다. 서비스 가용성을 보장하고 일부 로그 손실이 괜찮다면 이 모드를 사용하는 것이 좋습니다. 자세한 내용은 [Preventing log loss with non-blocking mode in the `awslogs` container log driver](https://aws.amazon.com/blogs/containers/preventing-log-loss-with-non-blocking-mode-in-the-awslogs-container-log-driver/)를 참조하세요.
`max-buffer-size`
필수 여부: 아니요
기본값: `1m`
`non-blocking` 모드를 사용하면 `max-buffer-size` 로그 옵션은 중간 메시지 스토리지에 사용되는 버퍼의 크기를 제어합니다. 애플리케이션에 따라 적절한 버퍼 크기를 지정해야 합니다. 버퍼가 가득 차면 로그를 더 이상 저장할 수 없습니다. 저장할 수 없는 로그는 손실됩니다.
`splunk` 로그 라우터를 사용하여 로그를 라우팅하려면 `splunk-token`과 `splunk-url`을 지정해야 합니다.
`awsfirelens` 로그 라우터를 사용하여 로그 스토리지 및 분석을 위해 AWS Partner Network 또는 AWS 서비스 대상으로 로그를 라우팅하는 경우 `log-driver-buffer-limit` 옵션을 설정하여 메모리에 버퍼링되는 이벤트 수를 제한한 후 로그 라우터 컨테이너로 전송할 수 있습니다. 처리량이 많으면 Docker 내부 버퍼의 메모리가 부족해질 수 있으므로 잠재적인 로그 손실 문제를 해결하는 데 도움이 될 수 있습니다. 자세한 내용은 [높은 처리량을 위한 Amazon ECS 로그 구성](firelens-docker-buffer-limit.md) 섹션을 참조하세요.
`awsfirelens`를 사용하여 로그를 라우팅할 때 지정할 수 있는 다른 옵션은 대상에 따라 다릅니다. 로그를 Amazon Data Firehose로 내보낼 때 AWS 리전으로 `region`을 지정하고 `delivery_stream`으로 로그 스트림의 이름을 지정할 수 있습니다.
로그를 Amazon Kinesis Data Streams로 내보낼 때 `region`으로 AWS 리전을 지정하고 `stream`으로 데이터 스트림 이름을 지정할 수 있습니다.
로그를 Amazon OpenSearch Service로 내보낼 때 `Name`, `Host`(프로토콜이 없는 OpenSearch Service 엔드포인트), `Port`, `Index`, `Type`, `Aws_auth`, `Aws_region`, `Suppress_Type_Name`, `tls` 등의 옵션을 지정할 수 있습니다.
로그를 Amazon S3로 내보내는 경우 `bucket` 옵션을 사용하여 버킷을 지정할 수 있습니다. `region`, `total_file_size`, `upload_timeout` 및 `use_put_object`도 옵션으로 지정할 수 있습니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.19 이상을 사용해야 합니다.
`secretOptions`
유형: 객체 배열
필수 여부: 아니요
로그 구성에 전달할 암호를 나타내는 객체입니다. 로그 구성에 사용되는 보안 암호에는 인증 토큰, 인증서 또는 암호화 키가 포함될 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너에서 환경 변수로 설정할 값입니다.
`valueFrom`
유형: 문자열
필수 항목 여부: 예
컨테이너의 로그 구성에 노출할 암호.
```
"logConfiguration": {
"logDriver": "splunk",
"options": {
"splunk-url": "https://cloud.splunk.com:8080",
"splunk-token": "...",
"tag": "...",
...
},
"secretOptions": [{
"name": "splunk-token",
"valueFrom": "/ecs/logconfig/splunkcred"
}]
}
```
`firelensConfiguration`
유형: [FirelensConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FirelensConfiguration.html) 객체
필수 여부: 아니요
컨테이너의 FireLens 구성입니다. 컨테이너 로그에 대한 로그 라우터를 지정하고 구성하는 데 사용됩니다. 자세한 정보는 [Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송](using_firelens.md) 섹션을 참조하세요.
```
{
"firelensConfiguration": {
"type": "fluentd",
"options": {
"KeyName": ""
}
}
}
```
`options`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
로그 라우터를 구성할 때 사용할 옵션의 키/값 맵입니다. 이 필드는 선택 사항이며, 사용자 지정 구성 파일을 지정하거나 태스크, 태스크 정의, 클러스터 및 컨테이너 인스턴스 세부 정보와 같은 추가 메타데이터를 로그 이벤트에 추가하는 데 사용할 수 있습니다. 이 필드를 지정할 경우 사용할 구문은 `"options":{"enable-ecs-log-metadata":"true|false","config-file-type:"s3|file","config-file-value":"arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf|filepath"}`입니다. 자세한 정보는 [Amazon ECS 태스크 정의 예제: 로그를 FireLens로 라우팅](firelens-taskdef.md) 섹션을 참조하세요.
`type`
유형: 문자열
필수 항목 여부: 예
사용할 로그 라우터입니다. 유효한 값은 `fluentd` 또는 `fluentbit`입니다.
#### 리소스 요구 사항
`resourceRequirements`
유형: [ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 객체 배열
필수 여부: 아니요
컨테이너에 할당할 리소스의 유형 및 양입니다. 현재 지원되는 리소스는 GPU뿐입니다.
`type`
유형: 문자열
필수 항목 여부: 예
컨테이너에 할당할 리소스 유형입니다. 지원되는 값은 `GPU`입니다.
`value`
유형: 문자열
필수 항목 여부: 예
지정된 리소스 유형의 값입니다.
`GPU` 유형이 사용되는 경우 이 값은 Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 실제 `GPUs` 수입니다. 태스크의 모든 컨테이너에 예약된 GPU 수가 태스크가 실행되는 컨테이너 인스턴스에서 사용할 수 있는 GPU 수를 초과할 수 없습니다.
Fargate에서 실행되는 태스크에 대해 GPU를 사용할 수 없습니다.
#### 컨테이너 제한 시간
`startTimeout`
유형: 정수
필수 여부: 아니요
예제 값: `120`
컨테이너에 대한 종속성 해결을 포기하기 전에 대기할 시간(초)입니다.
예를 들어 `containerA`에 대한 태스크 정의에서 `containerB`에 대한 종속성이 `COMPLETE`, `SUCCESS` 또는 `HEALTHY` 상태인 두 개의 컨테이너를 지정합니다. `containerB`에 대해 `startTimeout` 값이 지정되고 그 시간 내에 원하는 상태에 도달하지 않으면 `containerA`는 시작하지 않습니다.
컨테이너가 종속성 제약을 충족하지 못하거나 제약을 충족하기 전에 시간이 초과되면 Amazon ECS는 종속된 컨테이너를 다음 상태로 진행시키지 못합니다.
최대값은 600초(10분)입니다.
`stopTimeout`
유형: 정수
필수 여부: 아니요
예제 값: `120`
자체적으로 정상적으로 종료하지 않을 경우 컨테이너를 강제 종료하기까지 대기할 시간(초)입니다.
파라미터를 지정하지 않으면 기본값인 30초가 사용됩니다. 최대값은 86400초(24시간)입니다.
#### 컨테이너 종속성
`dependsOn`
유형: [ContainerDependency](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html) 객체의 배열
필수 여부: 아니요
컨테이너 시작 및 종료에 대해 정의된 종속성입니다. 컨테이너는 여러 종속성을 포함할 수 있습니다. 컨테이너가 시작될 때 종속성이 정의되면 컨테이너를 종료할 때 종속성이 취소됩니다. 문제 해결 예는 [컨테이너 종속성](example_task_definitions.md#example_task_definition-containerdependency) 섹션을 참조하세요.
컨테이너가 종속성 제약을 충족하지 못하거나 제약을 충족하기 전에 시간이 초과되면 Amazon ECS는 종속된 컨테이너를 다음 상태로 진행시키지 못합니다.
이 파라미터를 사용하려면 태스크 또는 서비스에서 플랫폼 버전 `1.3.0` 이상(Linux) 또는 `1.0.0`(Windows)을 사용해야 합니다.
```
"dependsOn": [
{
"containerName": "string",
"condition": "string"
}
]
```
`containerName`
유형: 문자열
필수 항목 여부: 예
지정된 조건을 충족해야 하는 컨테이너 이름입니다.
`condition`
유형: 문자열
필수 항목 여부: 예
컨테이너의 종속성 조건입니다. 다음은 사용 가능한 조건과 그 동작입니다.
+ `START` - 이 조건은 오늘의 링크와 볼륨의 동작을 에뮬레이션합니다. 이 조건은 종속 컨테이너가 시작되었는지 확인한 다음에 다른 컨테이너 시작을 허용합니다.
+ `COMPLETE` - 이 조건은 다른 컨테이너를 시작하기 전에 종속 컨테이너 실행이 완료(종료)되었는지 확인합니다. 이는 스크립트를 실행한 후 종료하는 필수적이지 않은 컨테이너에 유용할 수 있습니다. 필수 컨테이너에는 이 조건을 설정할 수 없습니다.
+ `SUCCESS` - 이 조건은 `COMPLETE`와 동일하지만 컨테이너가 `zero` 상태로 종료되어야 합니다. 필수 컨테이너에는 이 조건을 설정할 수 없습니다.
+ `HEALTHY` - 이 조건은 다른 컨테이너를 시작하기 전에 종속 컨테이너가 컨테이너 상태 확인을 통과하는지 확인합니다. 이렇게 하려면 태스크 정의에서 종속 컨테이너에 상태 확인이 구성되어 있어야 합니다. 이 조건은 태스크 시작 시에만 확인됩니다.
#### System Controls
`systemControls`
유형: [SystemControl](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_SystemControl.html) 객체
필수 여부: 아니요
컨테이너에서 설정할 네임스페이스 커널 파라미터의 목록입니다. 이 파라미터는 Docker 컨테이너 생성 명령에 있는 `Sysctls` 및 docker run에 대한 `--sysctl` 옵션에 매핑됩니다. 예를 들어 `net.ipv4.tcp_keepalive_time` 설정을 구성하여 연결을 더 오래 유지할 수 있습니다.
`awsvpc` 또는 `host` 네트워크 모드도 사용하는 단일 작업에서 여러 컨테이너에 네트워크 관련 `systemControls` 파라미터를 지정하지 않는 것이 좋습니다. 이렇게 하면 다음과 같은 단점이 있습니다.
+ 컨테이너에 `systemControls`를 설정할 경우 태스크의 모든 컨테이너에 적용됩니다. 단일 작업의 여러 컨테이너에 서로 다른 `systemControls`를 설정할 경우 마지막으로 시작되는 컨테이너에 따라 적용될 `systemControls`가 결정됩니다.
태스크 내 컨테이너에 사용할 IPC 리소스 네임스페이스를 설정하는 경우, 시스템 제어에 다음 사항이 적용됩니다. 자세한 정보는 [IPC 모드](task_definition_parameters.md#task_definition_ipcmode)을 참조하세요.
+ `host` IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 `systemControls`는 지원되지 않습니다.
+ `task` IPC 모드를 사용하는 작업의 경우, IPC 네임스페이스 `systemControls` 값은 작업 내 모든 컨테이너에 적용됩니다.
```
"systemControls": [
{
"namespace":"string",
"value":"string"
}
]
```
`namespace`
유형: 문자열
필수 여부: 아니요
`value`를 설정할 네임스페이스 커널 파라미터입니다.
유효한 IPC 네임스페이스 값:`"kernel.msgmax" | "kernel.msgmnb" | "kernel.msgmni" | "kernel.sem" | "kernel.shmall" | "kernel.shmmax" | "kernel.shmmni" | "kernel.shm_rmid_forced"` 및 `"fs.mqueue.*"`로 시작하는 `Sysctls`
유효한 네트워크 네임스페이스 값: `"net.*"`로 시작하는 `Sysctls`. Fargate에서는 컨테이너 내에 있는 네임스페이스 `Sysctls`만 허용됩니다.
이러한 값은 모두 Fargate에서 지원됩니다.
`value`
유형: 문자열
필수 여부: 아니요
`namespace`에 지정된 네임스페이스 커널 파라미터의 값입니다.
#### 대화형
`interactive`
유형: 부울
필수 여부: 아니요
이 파라미터가 `true`일 경우 이것을 사용하여 `stdin` 또는 `tty`를 할당해야 하는 컨테이너화된 애플리케이션을 배포할 수 있습니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `OpenStdin` 및 docker run에 대한 `--interactive` 옵션에 매핑됩니다.
기본값은 `false`입니다.
#### 의사 터미널
`pseudoTerminal`
유형: 부울
필수 여부: 아니요
이 파라미터가 `true`일 경우 TTY가 할당됩니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Tty` 및 docker run에 대한 `--tty` 옵션에 매핑됩니다.
기본값은 `false`입니다.
### Linux 파라미터
`linuxParameters`
유형: [LinuxParameters](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LinuxParameters.html) 객체
필수 여부: 아니요
컨테이너에 적용되는 Linux 수정(예: Linux 커널 기능)입니다.
`capabilities`
유형: [KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html) 객체
필수 여부: 아니요
컨테이너에 대해 Docker에서 제공하는 기본 구성에 추가되거나 삭제되는 Linux 기능.
`devices`
유형: [Device](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Device.html) 객체 배열
필수 여부: 아니요
컨테이너에 노출될 모든 호스트 디바이스. 이 파라미터는 Docker 컨테이너 생성 명령의 `Devices` 및 docker run에 대한 `--device` 옵션에 매핑됩니다.
`initProcessEnabled`
유형: 부울
필수 여부: 아니요
신호를 전달하고 프로세스의 결과를 받아들이는 컨테이너 내에서 `init` 프로세스를 실행합니다. 이 파라미터는 docker run에 대한 `--init` 옵션에 매핑됩니다.
`maxSwap`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 정수
필수 여부: 아니요
컨테이너가 사용할 수 있는 총 스왑 메모리 양(MiB) 이 파라미터는 docker run에 대한 `--memory-swap` 옵션으로 변환되며 컨테이너 메모리의 합계에 `maxSwap` 값을 더한 값이 됩니다.
`swappiness`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 정수
필수 여부: 아니요
이를 통해 컨테이너의 메모리 스왑 동작을 조정할 수 있습니다. `0`의 `swappiness` 값은 절대적으로 필요한 경우가 아니면 스왑이 일어나지 않도록 합니다. `100`의 `swappiness` 값은 페이지가 매우 적극적으로 스와핑되도록 합니다. 유효한 값은 `0`과 `100` 사이의 숫자입니다. `swappiness` 파라미터를 지정하지 않으면 `60`의 기본값이 사용됩니다. `maxSwap` 값이 지정되지 않은 경우 이 파라미터는 무시됩니다. 이 파라미터는 docker run에 대한 `--memory-swappiness` 옵션에 매핑됩니다.
`sharedMemorySize`
Amazon ECS 관리형 인스턴스에서 호스팅되는 태스크에 대해 이 파라미터가 지원되지 않습니다.
유형: 정수
필수 여부: 아니요
`/dev/shm` 볼륨의 크기(MiB)입니다. 이 파라미터는 docker run에 대한 `--shm-size` 옵션에 매핑됩니다.
`tmpfs`
유형: [Tmpfs](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Tmpfs.html) 객체 배열
필수 여부: 아니요
컨테이너 경로, 마운트 옵션 및 tmpfs 마운트의 크기(MiB)입니다. 이 파라미터는 docker run에 대한 `--tmpfs` 옵션에 매핑됩니다.
# Fargate에 대한 Amazon ECS 태스크 정의 파라미터
태스크 정의는 태스크 패밀리, AWS Identity and Access Management(IAM) 태스크 역할, 네트워크 모드, 컨테이너 정의, 볼륨, 시작 유형 등의 개별 부분으로 분할됩니다. 태스크 정의에는 패밀리 및 컨테이너 정의가 필요합니다. 하지만 태스크 역할, 네트워크 모드, 볼륨 및 시작 유형은 선택 사항입니다.
JSON 파일에서 이러한 파라미터를 사용하여 태스크 정의를 구성할 수 있습니다.
다음은 Fargate의 각 태스크 정의 파라미터에 대한 자세한 설명입니다.
## Family
`family`
유형: 문자열
필수 항목 여부: 예
태스크 정의를 등록할 때 패밀리를 지정합니다. 패밀리는 개정 번호를 사용하여 지정된 태스크 정의의 여러 버전에 대한 이름과 비슷합니다. 특정 패밀리에 등록된 첫 번째 태스크 정의에는 개정 번호 1이 부여되고 그 이후 등록된 태스크 정의에는 순차적으로 개정 번호가 부여됩니다.
## Capacity
태스크 정의를 등록할 때 Amazon ECS가 태스크 정의를 검증할 용량을 지정할 수 있습니다. 태스크 정의가 유효성을 지정한 호환성에 대해 검사하지 않으면 클라이언트 예외가 반환됩니다.
태스크 정의에서 다음 파라미터가 허용됩니다.
`requiresCompatibilities`
유형: 문자열 배열
필수 여부: 아니요
유효한 값: `FARGATE`
태스크 정의를 검증할 용량. 이를 통해 태스크 정의에 사용되는 모든 파라미터가 Fargate의 요구 사항을 충족하는지 확인할 수 있습니다.
## 태스크 역할
`taskRoleArn`
유형: 문자열
필수 여부: 아니요
태스크 정의를 등록할 때 태스크 권한의 컨테이너가 사용자 대신 연결된 정책에 지정된 AWS API를 호출하도록 허용하는 IAM 역할에 태스크 역할을 제공할 수 있습니다. 자세한 내용은 [Amazon ECS 작업 IAM 역할](task-iam-roles.md) 섹션을 참조하세요.
## 태스크 실행 역할
`executionRoleArn`
유형: 문자열
필수 항목 여부: 조건부
Amazon ECS 컨테이너 에이전트에 사용자를 대신하여 AWS API를 호출할 권한을 부여하는 태스크 실행 역할의 Amazon 리소스 이름(ARN)입니다.
태스크의 요구 사항에 따라 태스크 실행 IAM 역할이 필요합니다. 자세한 정보는 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
## 네트워크 모드
`networkMode`
유형: 문자열
필수 항목 여부: 예
태스크의 컨테이너에 사용할 Docker 네트워킹 모드. Fargate에서 호스팅되는 Amazon ECS 작업의 경우 `awsvpc` 네트워크 모드가 필요합니다.
## 런타임 플랫폼
`operatingSystemFamily`
유형: 문자열
필수 항목 여부: 조건부
기본값: LINUX
이 파라미터는 Fargate에서 호스팅되는 Amazon ECS 태스크에 필요합니다.
태스크 정의를 등록할 때 운영 체제 제품군을 지정합니다.
유효한 값은 `LINUX`, `WINDOWS_SERVER_2025_FULL`, `WINDOWS_SERVER_2025_CORE`, `WINDOWS_SERVER_2022_FULL`, `WINDOWS_SERVER_2022_CORE`, `WINDOWS_SERVER_2019_FULL`, `WINDOWS_SERVER_2019_CORE`입니다.
서비스에서 사용되는 모든 태스크 정의는 이 파라미터에 대해 동일한 값을 가져야 합니다.
태스크 정의가 서비스의 일부인 경우 이 값은 서비스 `platformFamily` 값과 일치해야 합니다.
`cpuArchitecture`
유형: 문자열
필수 항목 여부: 조건부
기본값: X86\$164
이 파라미터를 `null`로 두면 Fargate에 호스팅된 작업을 시작할 때 기본값이 자동으로 할당됩니다.
태스크 정의를 등록할 때 CPU 아키텍처를 지정합니다. 유효 값은 `X86_64` 및 `ARM64`입니다.
서비스에서 사용되는 모든 태스크 정의는 이 파라미터에 대해 동일한 값을 가져야 합니다.
Linux 태스크가 있는 경우 값을 `ARM64`로 설정할 수 있습니다. 자세한 내용은 [64비트 ARM 워크로드에 대한 Amazon ECS 작업 정의](ecs-arm64.md) 섹션을 참조하세요.
## 태스크 크기
태스크 정의를 등록할 때 태스크에 대해 사용할 CPU 및 메모리 총량을 지정할 수 있습니다. 이것은 컨테이너 정의 수준의 `cpu` 및 `memory` 값과는 구분됩니다. Fargate(Linux와 Windows 모두)에서 호스팅되는 태스크의 경우 이 필드는 필수이고 지원되는 `cpu`와 `memory` 모두에 대한 특정 값이 있습니다.
태스크 정의에서 다음 파라미터가 허용됩니다.
`cpu`
유형: 문자열
필수 항목 여부: 예
태스크 수준 CPU 및 메모리 파라미터는 필수이며 태스크가 실행되는 인스턴스 유형과 크기를 결정하는 데 사용됩니다. Windows 태스크의 경우 Windows에는 컨테이너 그룹에 집합 리소스 제한을 쉽게 적용할 수 있는 기본 메커니즘이 없으므로 런타임 시 이러한 값이 적용되지 않습니다. 리소스 제한을 적용하려면 Windows 컨테이너에 대한 컨테이너 수준 리소스를 사용하는 것이 좋습니다.
태스크에 대해 표시되는 CPU 단위의 하드 제한입니다. JSON 파일에서 CPU 값을 문자열(CPU 단위 또는 가상 CPU(vCPU))로 지정할 수 있습니다. 예를 들어 CPU 값을 `1024`(CPU 단위) 또는 `1 vCPU`(vCPU)로 지정할 수 있습니다. 태스크 정의를 등록할 때는 vCPU 값이 CPU 단위를 나타내는 정수로 변환됩니다.
이 필드는 필수이며 다음 값 중 하나를 사용해야 합니다. 이 필드에 따라 `memory` 파라미터에 지원되는 값의 범위가 결정됩니다. 유효한 태스크 레벨 CPU 및 메모리 조합은 아래 표와 같습니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/task_definition_parameters.html)
`memory`
유형: 문자열
필수 항목 여부: 예
태스크 수준 CPU 및 메모리 파라미터는 필수이며 태스크가 실행되는 인스턴스 유형과 크기를 결정하는 데 사용됩니다. Windows 태스크의 경우 Windows에는 컨테이너 그룹에 집합 리소스 제한을 쉽게 적용할 수 있는 기본 메커니즘이 없으므로 런타임 시 이러한 값이 적용되지 않습니다. 리소스 제한을 적용하려면 Windows 컨테이너에 대한 컨테이너 수준 리소스를 사용하는 것이 좋습니다.
작업에 표시할 메모리의 하드 제한. 작업 정의에서 메모리 값을 문자열(메비바이트(MiB) 또는 기가바이트(GB) 단위)로 지정할 수 있습니다. 예를 들어 메모리 값을 `3072`(MiB) 또는 `3 GB`(GB)로 지정할 수 있습니다. 태스크 정의를 등록할 때는 GB 값이 MiB를 나타내는 정수로 변환됩니다.
이 필드는 필수이며 다음 값 중 하나를 사용해야 합니다. 이 필드에 따라 `cpu` 파라미터에 지원되는 값의 범위가 결정됩니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/task_definition_parameters.html)
## 컨테이너 정의
작업 정의를 등록할 때 컨테이너 인스턴스의 Docker 대몬(daemon)으로 전달되는 컨테이너 정의의 목록을 지정해야 합니다. 컨테이너 정의에서 다음 파라미터가 허용됩니다.
**Topics**
+ [스탠다드 컨테이너 정의 파라미터](#standard_container_definition_params)
+ [고급 컨테이너 정의 파라미터](#advanced_container_definition_params)
+ [기타 컨테이너 정의 파라미터](#other_container_definition_params)
### 스탠다드 컨테이너 정의 파라미터
다음 태스크 정의 파라미터는 대부분의 컨테이너 정의에서 필요하거나 사용됩니다.
**Topics**
+ [이름](#container_definition_name)
+ [이미지](#container_definition_image)
+ [Memory](#container_definition_memory)
+ [포트 매핑](#container_definition_portmappings)
+ [프라이빗 리포지토리 보안 인증](#container_definition_repositoryCredentials)
#### 이름
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너의 이름. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈 및 밑줄이 허용됩니다. 여러 컨테이너를 한 태스크 정의에 연결하는 경우, 한 컨테이너의 `name`을 다른 컨테이너의 `links`에 입력할 수 있습니다. 이는 컨테이너를 연결하기 위한 것입니다.
#### 이미지
`image`
유형: 문자열
필수 항목 여부: 예
컨테이너를 시작하는 데 사용되는 이미지입니다. 이 문자열은 Docker 대몬(daemon)으로 직접 전달됩니다. 기본적으로 Docker Hub 레지스트리 내 이미지는 사용 가능합니다. `repository-url/image:tag` 또는 `repository-url/image@digest`를 사용하여 다른 리포지토리를 지정할 수도 있습니다. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈, 밑줄, 콜론, 마침표, 슬래시 및 부호가 허용됩니다. 이 파라미터는 Docker 컨테이너 생성 명령에 있는 `Image` 및 docker run 명령의 `IMAGE` 파라미터에 매핑됩니다.
+ 새 태스크가 시작될 때 Amazon ECS 컨테이너 에이전트가 컨테이너에서 사용할 지정 이미지와 태그의 최신 버전을 끌어옵니다. 그러나 이미 실행 중인 태스크에는 추후 리포지토리 이미지 업데이트가 전파되지 않습니다.
+ 태스크 정의의 이미지 경로에 태그 또는 다이제스트를 지정하지 않으면 Amazon ECS 컨테이너 에이전트가 지정된 이미지를 가져오기 위해 `latest` 태그를 사용합니다.
+ 그러나 이미 실행 중인 태스크에는 리포지토리 이미지에 대한 후속 업데이트가 전파되지 않습니다.
+ 프라이빗 리포지토리의 이미지는 지원되지 않습니다. 자세한 정보는 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md)을 참조하세요.
+ Amazon ECR 리포지토리의 이미지는 전체 `registry/repository:tag` 또는 `registry/repository@digest` 명명 규칙(예: `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app:latest` 또는 `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app@sha256:94afd1f2e64d908bc90dbca0035a5b567EXAMPLE`)을 사용하여 지정할 수 있습니다.
+ Docker Hub 공식 리포지토리 안의 이미지는 단일 이름을 사용합니다(예: `ubuntu` 또는 `mongo`).
+ Docker Hub 다른 리포지토리에 저장된 이미지는 조직 이름으로 한정됩니다(예: `amazon/amazon-ecs-agent`).
+ 다른 온라인 리포지토리 안의 이미지는 도메인 이름을 사용하여 추가로 한정됩니다(예: `quay.io/assemblyline/ubuntu`).
`versionConsistency`
유형: 문자열
유효한 값: `enabled`\$1`disabled`
필수 여부: 아니요
컨테이너 정의에 제공된 컨테이너 이미지 태그가 Amazon ECS에서 이미지 다이제스트로 확인되는지 여부를 지정합니다. 기본적으로 이 동작은 `enabled`입니다. 컨테이너의 값을 `disabled`로 설정하면 Amazon ECS에서는 컨테이너 이미지 태그가 다이제스트로 확인되지 않고 컨테이너 정의에 지정된 원본 이미지 URI가 배포에 사용됩니다. 컨테이너 이미지 확인에 대한 자세한 내용은 [컨테이너 이미지 확인](deployment-type-ecs.md#deployment-container-image-stability) 섹션을 참조하세요.
#### Memory
`memory`
유형: 정수
필수 여부: 아니요
컨테이너에 표시할 메모리의 양(MiB)입니다. 컨테이너가 여기서 지정된 메모리를 초과하려 하면 해당 컨테이너가 중지됩니다. 태스크 내 모든 컨테이너에 대해 예약된 총 메모리 양은 태스크 `memory` 값(지정된 경우)보다 작아야 합니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Memory` 및 docker run에 대한 `--memory` 옵션에 매핑됩니다.
Docker 20.10.0 이상의 대몬(daemon)은 컨테이너용으로 최소 6MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 6MiB 미만의 메모리를 지정하지 마세요.
Docker 19.03.13-ce 이하의 대몬(daemon)은 컨테이너용으로 최소 4MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 4MiB 미만의 메모리를 지정하지 마세요.
특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화하려는 경우 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요.
`memoryReservation`
유형: 정수
필수 여부: 아니요
컨테이너용으로 예약할 메모리의 소프트 제한(MiB)입니다. 시스템 메모리가 경합하는 경우 Docker는 컨테이너 메모리를 이 소프트 제한으로 유지하려고 합니다. 하지만 필요한 경우 컨테이너에서 더 많은 메모리를 사용할 수 있습니다. 컨테이너는 `memory` 파라미터에 지정된 하드 한도까지(해당하는 경우) 또는 컨테이너 인스턴스의 모든 가용 메모리(둘 중 먼저 발생하는 것)를 사용할 수 있습니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `MemoryReservation` 및 docker run에 대한 `--memory-reservation` 옵션에 매핑됩니다.
태스크 레벨 메모리 값이 지정되지 않은 경우 컨테이너 정의의 `memory` 또는 `memoryReservation`에 대해 하나 또는 둘 다에 0이 아닌 정수를 지정해야 합니다. 둘 모두 지정하는 경우 `memory`가 `memoryReservation`보다 커야 합니다. `memoryReservation`을 지정하는 경우 컨테이너가 배치된 컨테이너 인스턴스의 가용 메모리 리소스에서 해당 값이 차감됩니다. 그렇지 않으면 `memory` 값이 사용됩니다.
예를 들어 컨테이너가 통상적으로 128MiB의 메모리를 사용하지만 경우에 따라 잠깐 동안 사용량이 256MiB까지 급증한다고 가정합니다. 이 경우 `memoryReservation`을 128MiB로 설정하고 `memory` 하드 제한을 300MiB로 설정할 수 있습니다. 이 구성은 컨테이너가 컨테이너 인스턴스의 잔여 리소스 중 128MiB의 메모리만 예약하도록 허용합니다. 동시에, 이 구성을 사용하여 필요할 때 컨테이너가 더 많은 메모리 리소스를 사용하도록 허용할 수도 있습니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
Docker 20.10.0 이상의 대몬(daemon)은 컨테이너용으로 최소 6MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 6MiB 미만의 메모리를 지정하지 마세요.
Docker 19.03.13-ce 이하의 대몬(daemon)은 컨테이너용으로 최소 4MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 4MiB 미만의 메모리를 지정하지 마세요.
특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화하려는 경우 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요.
#### 포트 매핑
`portMappings`
유형: 객체 배열
필수 여부: 아니요
포트 매핑은 컨테이너의 네트워크 포트를 외부에 노출시켜 클라이언트가 애플리케이션에 액세스할 수 있도록 합니다. 이 파라미터는 동일한 태스크 내에서 컨테이너 간 통신에도 사용됩니다.
`awsvpc` 네트워크 모드를 사용하는 태스크 정의의 경우 `containerPort`만 지정합니다. `hostPort`는 항상 무시되며 컨테이너 포트는 호스트에서 임의의 높은 번호의 포트에 자동으로 매핑됩니다.
Windows에서의 포트 매핑은 `localhost`가 아니라 `NetNAT` 게이트웨이 주소를 사용합니다. Windows에서의 포트 매핑에는 루프백이 없으므로 호스트 자체에서 컨테이너의 매핑된 포트에 액세스할 수 없습니다.
이 파라미터의 필드 대부분(`containerPort`, `hostPort`, `protocol` 포함)은 Docker 컨테이너 생성 명령에 있는 `PortBindings`와 docker run에 대한 `--publish` 옵션에 매핑됩니다. 태스크 정의의 네트워크 모드가 `host`로 설정되어 있으면 호스트 포트가 정의되지 않은 상태이거나 호스트 포트가 포트 매핑의 컨테이너 포트와 일치해야 합니다.
태스크가 `RUNNING` 상태에 도달한 후에는 다음 위치에서 수동 및 자동 호스트/컨테이너 포트 할당을 확인할 수 있습니다.
+ 콘솔: 선택한 태스크에 대한 컨테이너 설명의 **네트워크 바인딩** 섹션.
+ AWS CLI: **describe-tasks** 명령 출력의 `networkBindings` 섹션.
+ API: `DescribeTasks` 응답.
+ 메타데이터: 작업 메타데이터 엔드포인트.
`appProtocol`
유형: 문자열
필수 여부: 아니요
포트 매핑에 사용되는 애플리케이션 프로토콜입니다. 이 파라미터는 Service Connect에만 적용됩니다. 애플리케이션에서 사용하는 프로토콜과 일치하도록 이 파라미터를 설정하는 것이 좋습니다. 이 파라미터를 설정하면 Amazon ECS가 서비스 연결 프록시에 프로토콜별 연결 처리를 추가합니다. 이 파라미터를 설정하면 Amazon ECS가 Amazon ECS 콘솔과 CloudWatch에 프로토콜별 원격 분석을 추가합니다.
이 파라미터의 값을 설정하지 않으면 TCP가 사용됩니다. 그러나 Amazon ECS는 TCP에 대한 프로토콜별 원격 측정을 추가하지 않습니다.
자세한 내용은 [Service Connect를 사용하여 짧은 이름으로 Amazon ECS 서비스 연결](service-connect.md) 섹션을 참조하세요.
유효한 프로토콜 값: `"http" | "http2" | "grpc" `
`containerPort`
유형: 정수
필수 항목 여부: 예(`portMappings` 사용 시)
사용자 지정 또는 자동 할당된 호스트 포트에 바인딩되는 컨테이너 포트 번호입니다.
`awsvpc` 네트워크 모드를 사용하는 태스크의 경우 `containerPort`를 사용하여 노출된 포트를 지정합니다.
Fargate의 Windows 컨테이너의 경우 포트 3150은 `containerPort`에 사용할 수 없습니다. 이 포트는 예약되어 있기 때문입니다.
`containerPortRange`
유형: 문자열
필수 여부: 아니요
동적으로 매핑된 호스트 포트 범위에 바인딩된 컨테이너의 포트 번호 범위입니다.
이 파라미터는 `register-task-definition` API를 사용해서만 설정할 수 있습니다. 옵션은 `portMappings` 파라미터에서 사용할 수 있습니다. 자세한 정보는 *AWS Command Line Interface 참조*의 [register-task-definition](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html)을 참조하세요.
`containerPortRange` 지정 시 다음 규칙이 적용됩니다.
+ `awsvpc` 네트워크 모드를 사용해야 합니다.
+ 이 파라미터는 Linux 및 Windows 운영 체제 모두에서 사용할 수 있습니다.
+ 컨테이너 인스턴스의 컨테이너 에이전트 버전은 1.67.0 이상이어야 하고 `ecs-init` 패키지의 버전은 1.67.0-1 이상이어야 합니다.
+ 컨테이너당 최대 100개의 포트 범위를 지정할 수 있습니다.
+ `hostPortRange`는 지정하지 않습니다. `hostPortRange`의 값은 다음과 같이 설정됩니다.
+ `awsvpc` 네트워크 모드를 사용하는 작업에 있는 컨테이너의 경우 `hostPort`는 `containerPort`와 동일한 값으로 설정됩니다. 이는 정적 매핑 전략입니다.
+ `containerPortRange`의 유효한 값은 1\$165,535입니다.
+ 포트는 컨테이너당 하나의 포트 매핑에만 포함될 수 있습니다.
+ 중첩되는 포트 범위는 지정할 수 없습니다.
+ 범위의 첫 번째 포트는 범위의 마지막 포트보다 작아야 합니다.
+ Docker에서는 포트 수가 많을 때 Docker 대몬(daemon) 구성 파일에서 docker-proxy를 끌 것을 권장합니다.
자세한 내용은 GitHub의 [Issue \$111185](https://github.com/moby/moby/issues/11185)를 참조하세요.
Docker 대몬(daemon) 구성 파일에서 docker-proxy를 끄는 방법에 대한 자세한 내용은 *Amazon ECS 개발자 안내서*의 [Docker daemon](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/bootstrap_container_instance.html#bootstrap_docker_daemon)을 참조하세요.
[DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html)를 직접적으로 호출하여 컨테이너 포트에 바인딩된 호스트 포트인 `hostPortRange`를 볼 수 있습니다.
포트 범위는 EventBridge로 전송되는 Amazon ECS 작업 이벤트에 포함되지 않습니다. 자세한 내용은 [EventBridge를 사용하여 Amazon ECS 오류에 대한 응답 자동화](cloudwatch_event_stream.md) 섹션을 참조하세요.
`hostPortRange`
유형: 문자열
필수 여부: 아니요
네트워크 바인딩에 사용되는 호스트의 포트 번호 범위입니다. 이 값은 Docker가 할당하고 Amazon ECS 에이전트가 전달합니다.
`hostPort`
유형: 정수
필수 여부: 아니요
컨테이너용으로 예약할 컨테이너 인스턴스 포트 번호입니다.
`hostPort`는 비워 두거나 `containerPort`와 같은 값을 지정할 수 있습니다.
기본 임시 포트 범위 Docker 1.6.0 버전 이상은 인스턴스의 `/proc/sys/net/ipv4/ip_local_port_range`에 나열됩니다. 이 커널 파라미터를 사용할 수 없을 경우 기본 휘발성 포트 범위 `49153–65535`가 사용됩니다. 휘발성 포트 범위에서 호스트 포트를 지정하지 마세요. 자동 할당을 위해 예약되어 있기 때문입니다. 일반적으로 `32768` 미만의 포트는 임시 포트 범위를 벗어납니다.
기본 예약 포트는 SSH용 `22`, Docker 포트 `2375` 및 `2376`, Amazon ECS 컨테이너 에이전트 포트 `51678-51680`입니다. 실행 중인 작업에 대해 기존에 사용자 지정된 호스트 포트도 해당 작업이 실행되는 동안 예약됩니다. 작업이 중지하면 호스트 포트는 해제됩니다. 현재 예약된 포트는 **describe-container-instances** 출력의 `remainingResources`에 표시됩니다. 하나의 컨테이너 인스턴스는 한 번에 최대 100개의 예약 포트(기본 예약 포트 포함)를 가질 수 있습니다. 자동 할당된 포트는 예약 포트 할당량 100개에 포함되지 않습니다.
`name`
유형: 문자열
필수: 아니요, 서비스에서 Service Connect와 VPC Lattice를 구성하는 데 필요
포트 매핑에 사용되는 이름입니다. 이 파라미터는 Service Connect와 VPC Lattice에만 적용됩니다. 이 파라미터는 서비스의 Service Connect와 VPC Lattice 구성에서 사용하는 이름입니다.
자세한 내용은 [Service Connect를 사용하여 짧은 이름으로 Amazon ECS 서비스 연결](service-connect.md) 섹션을 참조하세요.
다음 예제에서는 Service Connect와 VPC Lattice의 필수 필드를 모두 사용합니다.
```
"portMappings": [
{
"name": string,
"containerPort": integer
}
]
```
`protocol`
유형: 문자열
필수 여부: 아니요
포트 매핑에 사용되는 프로토콜입니다. 유효 값은 `tcp` 및 `udp`입니다. 기본값은 `tcp`입니다.
Service Connect에는 `tcp`만 지원됩니다. 이 필드가 설정되지 않은 경우 `tcp`로 암시됩니다.
호스트 포트를 지정하는 경우 다음 구문을 사용합니다.
```
"portMappings": [
{
"containerPort": integer,
"hostPort": integer
}
...
]
```
호스트 포트가 자동 할당되도록 하려면 다음 구문을 사용합니다.
```
"portMappings": [
{
"containerPort": integer
}
...
]
```
#### 프라이빗 리포지토리 보안 인증
`repositoryCredentials`
유형: [RepositoryCredentials](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RepositoryCredentials.html) 객체
필수 여부: 아니요
프라이빗 레지스트리 인증을 위한 리포지토리 보안 인증입니다.
자세한 내용은 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md) 섹션을 참조하세요.
`credentialsParameter`
유형: 문자열
필수 항목 여부: 예(`repositoryCredentials` 사용 시)
프라이빗 리포지토리 자격 증명이 포함된 암호의 Amazon 리소스 이름(ARN)입니다.
자세한 내용은 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md) 섹션을 참조하세요.
Amazon ECS API, AWS CLI 또는 AWS SDK를 사용할 때 시작하는 작업과 같은 리전에 보안 암호가 있는 경우 보안 암호의 전체 ARN 또는 이름을 사용할 수 있습니다. AWS Management Console을 사용하는 경우 보안 암호의 전체 ARN을 지정해야 합니다.
다음은 필요한 파라미터를 나타낸 태스크 정의의 예제 조각입니다.
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
### 고급 컨테이너 정의 파라미터
다음의 고급 컨테이너 정의 파라미터는 Amazon ECS 컨테이너 인스턴스에서 컨테이너를 시작하는 데 사용된 docker run 명령에 확장된 기능을 제공합니다.
**Topics**
+ [재시작 정책](#container_definition_restart_policy)
+ [상태 확인](#container_definition_healthcheck)
+ [환경](#container_definition_environment)
+ [네트워크 설정](#container_definition_network)
+ [스토리지 및 로깅](#container_definition_storage)
+ [보안](#container_definition_security)
+ [리소스 제한](#container_definition_limits)
+ [Docker 레이블](#container_definition_labels)
#### 재시작 정책
`restartPolicy`
컨테이너 재시작 정책 및 관련 구성 파라미터. 컨테이너의 재시작 정책을 설정하면 작업을 교체할 필요 없이 Amazon ECS에서 컨테이너를 다시 시작할 수 있습니다. 자세한 내용은 [컨테이너 재시작 정책이 있는 Amazon ECS 작업의 개별 컨테이너 재시작](container-restart-policy.md) 섹션을 참조하세요.
`enabled`
유형: Boolean
필수 여부: 예
재시작 정책이 컨테이너에 대해 활성화되는지 여부를 지정합니다.
`ignoredExitCodes`
유형: 정수 배열
필수 여부: 아니요
Amazon ECS가 재시작을 시도하지 않고 무시하는 종료 코드 목록입니다. 최대 50개의 컨테이너 종료 코드를 지정할 수 있습니다. 기본적으로 Amazon ECS는 종료 코드를 무시하지 않습니다.
`restartAttemptPeriod`
유형: 정수
필수 여부: 아니요
재시작을 시도하기 전에 컨테이너를 실행해야 하는 시간(초)입니다. 컨테이너는 `restartAttemptPeriod`초 당 한 번만 재시작할 수 있습니다. 이 기간 동안 컨테이너를 실행할 수 없고 일찍 종료되면 다시 시작되지 않습니다. 최소 60초의 `restartAttemptPeriod`와 최대 1,800초의 `restartAttemptPeriod`를 설정할 수 있습니다. 기본적으로 컨테이너는 300초 동안 실행되어야 재시작할 수 있습니다.
#### 상태 확인
`healthCheck`
해당 컨테이너에 대한 컨테이너 상태 확인 명령 및 연결된 구성 파라미터. 자세한 내용은 [컨테이너 상태 확인을 사용하여 Amazon ECS 작업 상태 확인](healthcheck.md) 섹션을 참조하세요.
`command`
상태가 정상인지를 확인하기 위해 컨테이너가 실행하는 명령을 나타내는 문자열 배열입니다. 명령 인수를 직접 실행하려면 문자열 어레이가 `CMD`으로 시작하면 되고, 컨테이너의 기본 셸에서 명령을 실행하려면 `CMD-SHELL`로 시작하면 됩니다. 둘 다 지정하지 않으면 `CMD`가 사용됩니다.
AWS Management Console에서 작업 정의를 등록할 때는 쉼표로 구분된 명령 목록을 사용합니다. 이러한 명령은 작업 정의가 생성된 후 문자열로 변환됩니다. 다음은 상태 확인에 대한 입력 예제입니다.
```
CMD-SHELL, curl -f http://localhost/ || exit 1
```
AWS Management Console JSON 패널, AWS CLI 또는 API를 사용하여 작업 정의를 등록할 때는 명령 목록을 괄호로 묶어야 합니다. 다음은 상태 확인에 대한 입력 예제입니다.
```
[ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]
```
`stderr` 출력이 없는 종료 코드 0은 성공을 나타내고, 0이 아닌 종료 코드는 실패를 나타냅니다.
`interval`
각 상태 확인 간의 시간(초). 5초에서 300초 사이를 지정할 수 있습니다. 기본값은 30초입니다.
`timeout`
실패로 간주되기 전에 상태 확인이 성공하기까지의 대기 시간(초)입니다. 2초에서 60초 사이를 지정할 수 있습니다. 기본값은 5초입니다.
`retries`
컨테이너 상태가 비정상이라고 간주되기 전에 실패한 상태 확인을 재시도하는 횟수입니다. 1에서 10 사이의 재시도 횟수를 지정할 수 있습니다. 기본값은 3회 재시도입니다.
`startPeriod`
실패한 상태 확인이 최대 재시도 횟수에 포함되기 전에 컨테이너에 부트스트랩 시간이 제공되는 유예 기간 옵션입니다. 0\$1300초 범위의 값을 지정할 수 있습니다. 기본적으로 `startPeriod`는 비활성화되어 있습니다.
상태 검사가 `startPeriod` 내에 성공한 경우 컨테이너는 정상으로 간주되고 모든 후속 실패는 최대 재시도 횟수에 포함됩니다.
#### 환경
`cpu`
유형: 정수
필수 여부: 아니요
Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 `cpu` 단위입니다. Linux에서 이 파라미터는 [컨테이너 만들기](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate) 섹션의 `CpuShares`에 매핑됩니다.
이 필드는 Fargate를 사용하는 태스크의 경우 선택 사항입니다. 태스크 내 모든 컨테이너에 대해 예약된 총 CPU 양은 태스크 수준 `cpu` 값보다 작아야 합니다.
Linux 컨테이너는 할당된 양과 동일한 비율로, 컨테이너 인스턴스의 다른 컨테이너와 할당되지 않은 CPU 단위를 공유합니다. 예를 들어 싱글 코어 인스턴스 유형에서 단일 컨테이너 작업을 컨테이너에 512개 CPU 단위를 지정하고 실행한다고 가정해 보겠습니다. 또한 이 작업은 컨테이너 인스턴스에서 실행되는 유일한 작업입니다. 이 예에서 컨테이너는 언제라도 1,024 CPU 단위 전부를 사용할 수 있습니다. 하지만, 해당 컨테이너 인스턴스에서 동일한 태스크의 다른 사본을 시작했다고 가정합니다. 각 작업에는 필요한 경우 최소 512개의 CPU 단위가 보장됩니다. 마찬가지로 다른 컨테이너가 나머지 CPU를 사용하지 않을 경우 각 컨테이너의 CPU 사용량이 높아질 수 있습니다. 하지만 두 작업이 항상 100% 활성 상태인 경우 CPU 단위는 512개로 제한됩니다.
Linux 컨테이너 인스턴스에서, 컨테이너 인스턴스의 Docker 대몬(daemon)은 CPU 값을 사용하여 실행 컨테이너의 상대적인 CPU 공유 비율을 계산합니다. Linux 커널이 허용하는 최소 유효 CPU 공유 값은 2이고, Linux 커널이 허용하는 최대 유효 CPU 공유 값은 262144입니다. 하지만 CPU 파라미터는 필수 항목이 아니며 컨테이너 정의에서 2 미만이나 262144를 초과하는 CPU 값을 사용할 수 있습니다. CPU 값이 2 미만(null 포함)이거나 262144를 초과하는 경우 동작은 Amazon ECS 컨테이너 에이전트 버전에 따라 달라집니다.
Windows 컨테이너 인스턴스에서 CPU 할당량은 절대 할당량으로 적용됩니다. Windows 컨테이너는 작업 정의에 정의된 지정된 양의 CPU에만 액세스할 수 있습니다. Null 또는 0의 CPU 값이 Docker에 `0`으로 전달되고, Windows는 이 값을 1개 CPU의 1%로 해석합니다.
추가 예제는 [How Amazon ECS manages CPU and memory resources](https://aws.amazon.com/blogs/containers/how-amazon-ecs-manages-cpu-and-memory-resources/)를 참조하세요.
`gpu`
이 파라미터는 Fargate에서 호스팅되는 컨테이너에 대해서는 지원되지 않습니다.
유형: [ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 객체
필수 여부: 아니요
Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 실제 `GPUs` 수입니다. 태스크의 모든 컨테이너에 예약된 GPU 수가 태스크가 실행되는 컨테이너 인스턴스에서 사용할 수 있는 GPU 수를 초과하면 안 됩니다. 자세한 내용은 [GPU 워크로드에 대한 Amazon ECS 작업 정의](ecs-gpu.md) 섹션을 참조하세요.
`Elastic Inference accelerator`
이 파라미터는 Fargate에서 호스팅되는 컨테이너에 대해서는 지원되지 않습니다.
유형: [ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 객체
필수 여부: 아니요
`InferenceAccelerator` 유형의 경우 `value`는 태스크 정의에 지정된 `InferenceAccelerator`의 `deviceName`과 일치합니다. 자세한 내용은 [Elastic Inference 액셀러레이터 이름(폐기됨)](#elastic-Inference-accelerator) 섹션을 참조하세요.
`essential`
유형: 부울
필수 여부: 아니요
컨테이너의 `essential` 파라미터가 `true`로 표시되어 있고 해당 컨테이너가 어떤 이유로든 실패 또는 중지하는 경우를 가정해 보겠습니다. 이 경우 작업에 포함된 다른 모든 컨테이너도 중지합니다. 컨테이너의 `essential` 파라미터가 `false`로 표시된 경우에는 해당 컨테이너의 실패가 태스크의 나머지 컨테이너에 영향을 주지 않습니다. 이 파라미터가 생략된 경우 컨테이너가 필수로 간주됩니다.
모든 태스크에는 하나 이상의 필수 컨테이너가 있어야 합니다. 여러 컨테이너로 구성된 애플리케이션이 있다고 가정해 보겠습니다. 이 경우, 공통 용도로 사용되는 컨테이너를 구성 요소로 그룹화하고, 다른 구성 요소를 여러 작업 정의로 분리합니다. 자세한 내용은 [Amazon ECS에 대한 애플리케이션 설계](application_architecture.md) 섹션을 참조하세요.
```
"essential": true|false
```
`entryPoint`
초기 버전의 Amazon ECS 컨테이너 에이전트는 `entryPoint` 파라미터를 적절히 처리하지 못합니다. `entryPoint`를 사용하는 데 문제가 있을 경우 컨테이너 에이전트를 업데이트하거나 명령 및 인수를 `command` 배열 항목으로 입력하세요.
유형: 문자열 배열
필수 여부: 아니요
컨테이너로 전달되는 진입점입니다.
```
"entryPoint": ["string", ...]
```
`command`
유형: 문자열 배열
필수 여부: 아니요
컨테이너로 전달되는 명령입니다. 이 파라미터는 컨테이너 생성 명령의 `Cmd` 및 docker run에 대한 `COMMAND` 파라미터에 매핑됩니다. 여러 인수가 있는 경우 각 인수는 배열에서 각각 분리된 문자열이어야 합니다.
```
"command": ["string", ...]
```
`workingDirectory`
유형: 문자열
필수 여부: 아니요
컨테이너에서 명령을 실행할 태스크 디렉터리입니다. 이 파라미터는 [Docker 원격 API(Docker Remote API)](https://docs.docker.com/reference/api/engine/version/v1.38/)의 [컨테이너 생성(Create a container)](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate) 섹션에 있는 `WorkingDir`(와)과 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/)에 대한 `--workdir` 옵션에 매핑됩니다.
```
"workingDirectory": "string"
```
`environmentFiles`
Fargate의 Windows 컨테이너에서는 사용할 수 없습니다.
유형: 객체 배열
필수 여부: 아니요
컨테이너로 전달할 환경 변수를 포함하는 파일 목록입니다. 이 파라미터는 docker run 명령에 대한 `--env-file` 옵션에 매핑됩니다.
최대 10개의 환경 파일을 지정할 수 있습니다. 파일의 확장명은 `.env`여야 합니다. 환경 파일의 각 줄에는 `VARIABLE=VALUE` 형식의 환경 변수를 포함합니다. `#`으로 시작하는 줄은 주석으로 처리되며 무시됩니다.
컨테이너 정의에 지정된 개별 환경 변수가 있는 경우 환경 파일 내에 포함된 변수보다 우선합니다. 동일한 변수를 포함하는 여러 환경 파일이 지정된 경우 위에서 아래로 처리됩니다. 고유한 변수 이름을 사용하는 것이 좋습니다. 자세한 정보는 [개별 환경 변수를 Amazon ECS 컨테이너로 전달](taskdef-envfiles.md)을 참조하세요.
`value`
유형: 문자열
필수 항목 여부: 예
환경 변수 파일을 포함하는 Amazon S3 객체의 Amazon 리소스 이름(ARN)입니다.
`type`
유형: 문자열
필수 항목 여부: 예
사용할 파일 유형입니다. 지원되는 유일한 값은 `s3`입니다.
`environment`
유형: 객체 배열
필수 여부: 아니요
컨테이너로 전달할 환경 변수입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Env` 및 docker run 명령에 대한 `--env` 옵션에 매핑됩니다.
자격 증명 데이터와 같은 민감한 정보에 대해서는 일반 텍스트 환경 변수를 사용하지 않는 것이 좋습니다.
`name`
유형: 문자열
필수 항목 여부: `environment` 사용 시, 예
환경 변수의 이름입니다.
`value`
유형: 문자열
필수 항목 여부: `environment` 사용 시, 예
환경 변수의 값입니다.
```
"environment" : [
{ "name" : "string", "value" : "string" },
{ "name" : "string", "value" : "string" }
]
```
`secrets`
유형: 객체 배열
필수 여부: 아니요
컨테이너에 공개할 보안 암호를 나타내는 객체입니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너에서 환경 변수로 설정할 값입니다.
`valueFrom`
유형: 문자열
필수 항목 여부: 예
컨테이너에 노출될 암호입니다. 지원되는 값은 AWS Secrets Manager 암호의 전체 ARN이거나 혹은 AWS Systems Manager 파라미터 스토어 내 파라미터의 전체 Amazon 리소스 이름(ARN)입니다.
Systems Manager Parameter Store 파라미터 또는 Secrets Manager 파라미터가 현재 실행 중인 작업과 동일한 AWS 리전에 있을 경우 해당 암호의 전체 ARN 또는 이름을 사용할 수 있습니다. 파라미터가 다른 리전에 있다면 전체 ARN을 지정해야 합니다.
```
"secrets": [
{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}
]
```
#### 네트워크 설정
`disableNetworking`
Fargate에서 실행되는 태스크에는 이 파라미터가 지원되지 않습니다.
유형: 부울
필수 여부: 아니요
이 파라미터가 true일 경우 컨테이너 내에서 네트워킹이 해제됩니다.
기본값은 `false`입니다.
```
"disableNetworking": true|false
```
`links`
이 파라미터는 `awsvpc` 네트워크 모드를 사용하는 작업에 대해서는 지원되지 않습니다.
유형: 문자열 배열
필수 여부: 아니요
`link` 파라미터는 포트 매핑 필요 없이 컨테이너가 서로 통신하도록 허용합니다. 이 파라미터는 작업 정의의 네트워크 모드가 `bridge`로 설정된 경우에만 지원됩니다. `name:internalName` 구성은 Docker 링크의 `name:alias`와 유사합니다. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈 및 밑줄이 허용됩니다.
동일한 컨테이너 인스턴스에 배치된 컨테이너는 링크 또는 호스트 포트 매핑 없이도 서로 통신할 수 있습니다. 컨테이너 인스턴스에서 네트워크 격리는 보안 그룹 및 VPC 설정에 의해 제어됩니다.
```
"links": ["name:internalName", ...]
```
`hostname`
유형: 문자열
필수 여부: 아니요
컨테이너에 사용할 호스트 이름입니다. 이 파라미터는 Docker 컨테이너 생성의 `Hostname` 및 docker run에 대한 `--hostname` 옵션에 매핑됩니다.
`awsvpc` 네트워크 모드를 사용 중인 경우에는 `hostname` 파라미터가 지원되지 않습니다.
```
"hostname": "string"
```
`dnsServers`
Fargate에서 실행되는 태스크에는 지원되지 않습니다.
유형: 문자열 배열
필수 여부: 아니요
컨테이너에 제공되는 DNS 서버의 목록입니다.
```
"dnsServers": ["string", ...]
```
`extraHosts`
이 파라미터는 `awsvpc` 네트워크 모드를 사용하는 작업에 대해서는 지원되지 않습니다.
유형: 객체 배열
필수 여부: 아니요
컨테이너의 `/etc/hosts` 파일에 추가할 호스트 이름 및 IP 주소 매핑의 목록입니다.
이 파라미터는 Docker 컨테이너 생성 명령의 `ExtraHosts` 및 docker run에 대한 `--add-host` 옵션에 매핑됩니다.
```
"extraHosts": [
{
"hostname": "string",
"ipAddress": "string"
}
...
]
```
`hostname`
유형: 문자열
필수 항목 여부: 예(`extraHosts` 사용 시)
`/etc/hosts` 항목에 사용할 호스트 이름입니다.
`ipAddress`
유형: 문자열
필수 항목 여부: 예(`extraHosts` 사용 시)
`/etc/hosts` 항목에 사용할 IP 주소입니다.
#### 스토리지 및 로깅
`readonlyRootFilesystem`
유형: 부울
필수 여부: 아니요
이 파라미터가 true일 경우 컨테이너에는 루트 파일 시스템에 대한 읽기 전용 액세스가 부여됩니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `ReadonlyRootfs` 및 docker run에 대한 `--read-only` 옵션에 매핑됩니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
기본값은 `false`입니다.
```
"readonlyRootFilesystem": true|false
```
`mountPoints`
유형: 객체 배열
필수 여부: 아니요
컨테이너에서 데이터 볼륨의 탑재 지점입니다. 이 파라미터는 create-container Docker API의 `Volumes` 및 docker run에 대한 `--volume` 옵션에 매핑됩니다.
Windows 컨테이너는 전체 디렉터리를 동일한 드라이브에 `$env:ProgramData`로 마운트할 수 있습니다. Windows 컨테이너는 디렉터리를 다른 드라이브에 탑재할 수 없으며, 탑재 지점은 여러 드라이브에 걸쳐 사용할 수 없습니다. Amazon EBS 볼륨을 Amazon ECS 작업에 직접 연결하려면 탑재 지점을 지정해야 합니다.
`sourceVolume`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
탑재할 볼륨의 이름입니다.
`containerPath`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
볼륨을 탑재할 컨테이너의 경로입니다.
`readOnly`
유형: 부울
필수 여부: 아니요
이 값이 `true`일 경우 컨테이너에는 볼륨에 대한 읽기 전용 액세스가 부여됩니다. 이 값이 `false`일 경우 컨테이너는 볼륨에 쓸 수 있습니다. 기본값은 `false`입니다.
Windows 운영 체제를 실행하는 EC2 인스턴스에서 실행되는 태스크의 경우 값을 기본값인 `false`로 둡니다.
`volumesFrom`
유형: 객체 배열
필수 여부: 아니요
다른 컨테이너로부터 탑재할 데이터 볼륨입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `VolumesFrom` 및 docker run에 대한 `--volumes-from` 옵션에 매핑됩니다.
`sourceContainer`
유형: 문자열
필수 항목 여부: `volumesFrom` 사용 시, 예
탑재할 볼륨이 위치한 컨테이너의 이름입니다.
`readOnly`
유형: 부울
필수 여부: 아니요
이 값이 `true`일 경우 컨테이너에는 볼륨에 대한 읽기 전용 액세스가 부여됩니다. 이 값이 `false`일 경우 컨테이너는 볼륨에 쓸 수 있습니다. 기본값은 `false`입니다.
```
"volumesFrom": [
{
"sourceContainer": "string",
"readOnly": true|false
}
]
```
`logConfiguration`
유형: [LogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) 객체
필수 여부: 아니요
컨테이너의 로그 구성 사양입니다.
로그 구성을 사용하는 태스크 정의에 대한 자세한 정보는 [Amazon ECS 작업 정의 예제](example_task_definitions.md) 섹션을 참조하세요.
이 파라미터는 Docker 컨테이너 생성 명령의 `LogConfig` 및 docker run에 대한 `--log-driver` 옵션에 매핑됩니다. 기본적으로 컨테이너는 Docker 대몬(daemon)이 사용하는 것과 동일한 로깅 드라이버를 사용합니다. 하지만 컨테이너는 이 파라미터를 사용하여 컨테이너 정의에 로그 드라이버를 지정함으로써 Docker 대몬(daemon)과 다른 로깅 드라이버를 사용할 수 있습니다. 컨테이너에 다른 로깅 드라이버를 사용하려면 컨테이너 인스턴스에서(또는 원격 로깅 옵션의 다른 로그 서버에서) 로그 시스템이 올바르게 구성되어야 합니다.
컨테이너에 대한 로그 구성을 지정할 때 다음 사항에 유의해야 합니다.
+ Amazon ECS는 Docker 대몬(daemon)에 사용 가능한 로깅 드라이버의 하위 집합을 지원합니다.
+ 이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker Remote API 버전 1.18 이상을 사용해야 합니다.
+ 태스크 외부에서 추가 소프트웨어를 설치해야 합니다. Fluentd 출력 집계자 또는 Gelf 로그를 보내기 위해 Logstash를 실행 중인 원격 호스트를 예로 들 수 있습니다.
```
"logConfiguration": {
"logDriver": "awslogs","fluentd","gelf","json-file","journald","splunk","syslog","awsfirelens",
"options": {"string": "string"
...},
"secretOptions": [{
"name": "string",
"valueFrom": "string"
}]
}
```
`logDriver`
타입: 문자열
유효한 값: `"awslogs","fluentd","gelf","json-file","journald","splunk","syslog","awsfirelens"`
필수 항목 여부: `logConfiguration` 사용 시, 예
컨테이너에 사용할 로드 드라이버입니다. 앞에 나열된 유효한 값은 Amazon ECS 컨테이너 에이전트가 기본적으로 통신할 수 있는 로그 드라이버입니다.
지원되는 로그 드라이버는 `awslogs`, `splunk` 및 `awsfirelens`입니다.
태스크 정의에서 `awslogs` 로그 드라이버를 사용하여 컨테이너 로그를 CloudWatch Logs로 보내는 방법에 대한 자세한 정보는 [Amazon ECS 로그를 CloudWatch로 전송](using_awslogs.md) 섹션을 참조하세요.
`awsfirelens` 로그 드라이버 사용에 대한 자세한 정보는 [사용자 지정 로그 라우팅](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_firelens.html)을 참조하세요.
목록에 포함되지 않은 사용자 지정 드라이버가 있는 경우, [GitHub에서 사용 가능한](https://github.com/aws/amazon-ecs-agent) Amazon ECS 컨테이너 에이전트 프로젝트를 포킹하여 해당 드라이버와 함께 작동하도록 사용자 지정할 수 있습니다. 포함하고 싶은 변경에 대해서는 풀 요청을 제출할 것을 권장합니다. 단, 현재 이 소프트웨어의 수정된 사본 실행은 지원되지 않습니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다.
`options`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
로그 드라이버로 보낼 구성 옵션의 키/값 맵입니다.
지정할 수 있는 옵션은 로그 드라이버에 따라 달라집니다. 다음은 `awslogs` 라우터를 사용하여 로그를 Amazon CloudWatch로 라우팅할 때 지정할 수 있는 몇 가지 옵션입니다.
`awslogs-create-group`
필수 여부: 아니요
로그 그룹을 자동으로 생성할지를 지정합니다. 이 옵션이 지정되지 않은 경우 기본적으로 `false`로 설정됩니다.
`awslogs-create-group`을 사용하기 전에 IAM 정책이 `logs:CreateLogGroup` 권한을 포함해야 합니다.
`awslogs-region`
필수 여부: 예
`awslogs` 로그 드라이버가 Docker 로그를 보낼 AWS 리전을 지정합니다. 여러 리전의 클러스터로부터 모든 로그를 CloudWatch Logs 내 단일 리전으로 전송하도록 선택할 수 있습니다. 이는 로그를 모두 한 곳에서 볼 수 있도록 하기 위함입니다. 또는, 리전별로 구분하여 세분화할 수 있습니다. 지정한 로그 그룹이 이 옵션으로 지정한 리전에 위치하는지 확인하세요.
`awslogs-group`
필수 여부: 예
`awslogs` 로그 드라이버가 로그 스트림을 전송할 로그 그룹을 지정해야 합니다.
`awslogs-stream-prefix`
필수 여부: 예
`awslogs-stream-prefix` 옵션을 사용하여 로그 스트림을 지정한 접두사, 컨테이너 이름 및 컨테이너가 속하는 Amazon ECS 태스크의 ID와 연결할 수 있습니다. 이 옵션을 사용하여 접두사를 지정하는 경우 로그 스트림은 다음 형식을 취합니다.
```
prefix-name/container-name/ecs-task-id
```
이 옵션을 사용하여 접두사를 지정하지 않는 경우 로그 스트림 이름이 컨테이너 인스턴스의 Docker 대몬에 의해 할당된 컨테이너 ID를 따서 지정됩니다. Docker 컨테이너 ID(컨테이너 인스턴스에서만 사용 가능)만으로는 로그를 전송한 컨테이너로 역추적하기 어려우므로 이 옵션에서 접두사를 지정하는 것이 좋습니다.
Amazon ECS 서비스의 경우 서비스 이름을 접두사로 사용할 수 있습니다. 이렇게 하면 로그 스트림을 컨테이너가 속하는 서비스, 로그를 전송한 컨테이너의 이름, 컨테이너가 속하는 작업의 ID로 추적할 수 있습니다.
Amazon ECS 콘솔을 사용할 때 로그 창에 로그가 표시되도록 하기 위해서는 해당 로그에 스트림 접두사를 지정해야 합니다.
`awslogs-datetime-format`
필수 여부: 아니요
이 옵션은 Python `strftime` 형식의 여러 줄 시작 패턴을 정의합니다. 로그 메시지는 패턴과 일치하는 하나의 줄과 패턴과 일치하지 않는 나머지 줄들로 이루어져 있습니다. 일치하는 줄은 로그 메시지 간의 구분 기호입니다.
이 형식을 사용하는 사용 사례의 한 예는 스택 덤프와 같은 출력을 구문 분석하는 것이며, 그렇지 않으면 여러 항목에 기록될 수 있습니다. 올바른 패턴을 통해 단일 항목으로 캡처할 수 있습니다.
자세한 내용은 [awslogs-datetime-format](https://docs.docker.com/engine/logging/drivers/awslogs/#awslogs-datetime-format)을 참조하세요.
`awslogs-datetime-format` 및 `awslogs-multiline-pattern` 옵션을 모두 구성할 수는 없습니다.
여러 줄 로깅은 모든 로그 메시지의 정규식 구문 분석 및 일치 태스크를 수행합니다. 이는 로깅 성능에 부정적인 영향을 줄 수 있습니다.
`awslogs-multiline-pattern`
필수 여부: 아니요
이 옵션은 정규식을 사용하여 여러 줄 시작 패턴을 정의합니다. 로그 메시지는 패턴과 일치하는 하나의 줄과 패턴과 일치하지 않는 나머지 줄들로 이루어져 있습니다. 일치하는 줄은 로그 메시지 간의 구분 기호입니다.
자세한 정보는 [awslogs-multiline-pattern](https://docs.docker.com/engine/logging/drivers/awslogs/#awslogs-multiline-pattern)을 참조하세요.
이 옵션은 `awslogs-datetime-format`을 구성하는 경우에 무시됩니다.
`awslogs-datetime-format` 및 `awslogs-multiline-pattern` 옵션을 모두 구성할 수는 없습니다.
여러 줄 로깅은 모든 로그 메시지의 정규식 구문 분석 및 일치 태스크를 수행합니다. 이는 로깅 성능에 부정적인 영향을 줄 수 있습니다.
다음 옵션은 지원되는 모든 로그 드라이버에 적용됩니다.
`mode`
필수 여부: 아니요
유효한 값: `non-blocking` \$1 `blocking`
이 옵션은 컨테이너에서 `logDriver`를 사용하여 지정된 로그 드라이버로 로그 메시지를 전송하는 모드를 정의합니다. 선택한 전송 모드는 컨테이너에서 나오는 로그 흐름이 중단될 때 애플리케이션 가용성에 영향을 줍니다.
`blocking` 모드를 사용하는 경우 로그 흐름이 중단되면 `stdout` 및 `stderr` 스트림에 쓰기 위한 컨테이너 코드의 호출이 차단됩니다. 결과적으로 애플리케이션의 로깅 스레드가 차단됩니다. 이로 인해 애플리케이션이 응답하지 않고 컨테이너 상태 확인에 실패할 수 있습니다.
`non-blocking` 모드를 사용하는 경우 컨테이너의 로그는 `max-buffer-size` 옵션으로 구성된 인 메모리 중간 버퍼에 대신 저장됩니다. 이렇게 하면 로그를 전송할 수 없을 때 애플리케이션이 응답하지 않게 되는 것을 방지할 수 있습니다. 서비스 가용성을 보장하고 일부 로그 손실이 괜찮다면 이 모드를 사용하는 것이 좋습니다. 자세한 내용은 [Preventing log loss with non-blocking mode in the `awslogs` container log driver](https://aws.amazon.com/blogs/containers/preventing-log-loss-with-non-blocking-mode-in-the-awslogs-container-log-driver/)를 참조하세요.
`defaultLogDriverMode` 계정 설정을 사용하여 특정 AWS 리전의 모든 컨테이너에 대해 기본 `mode`를 설정할 수 있습니다. `logConfiguration`에서 `mode` 옵션을 지정하지 않거나 계정 설정을 구성하지 않으면 Amazon ECS는 기본적으로 `non-blocking` 모드로 설정됩니다. 계정 설정에 대한 자세한 내용은 [기본 로그 드라이버 모드](ecs-account-settings.md#default-log-driver-mode) 섹션을 참조하세요.
`non-blocking` 모드를 사용하면 `max-buffer-size` 로그 옵션은 중간 메시지 스토리지에 사용되는 버퍼의 크기를 제어합니다. 애플리케이션에 따라 적절한 버퍼 크기를 지정해야 합니다. 작업 수준에서 할당된 총 메모리 양은 로그 드라이버 메모리 버퍼 외에도 모든 컨테이너에 할당된 메모리 양보다 커야 합니다.
2025년 6월 25일 Amazon ECS는 태스크 가용성을 로깅보다 우선시하기 위해 기본 로그 드라이버 모드를 `blocking`에서 `non-blocking`으로 변경했습니다. 이 변경 후에도 `blocking` 모드를 계속 사용하려면 다음 중 하나를 수행합니다.
+ 컨테이너 정의의 `logConfiguration`에서 `mode` 옵션을 `blocking`로 설정합니다.
+ `defaultLogDriverMode` 계정 설정을 `blocking`로 설정합니다.
`max-buffer-size`
필수 여부: 아니요
기본값: `10m`
`non-blocking` 모드를 사용하면 `max-buffer-size` 로그 옵션은 중간 메시지 스토리지에 사용되는 버퍼의 크기를 제어합니다. 애플리케이션에 따라 적절한 버퍼 크기를 지정해야 합니다. 버퍼가 가득 차면 로그를 더 이상 저장할 수 없습니다. 저장할 수 없는 로그는 손실됩니다.
`splunk` 로그 라우터를 사용하여 로그를 라우팅하려면 `splunk-token`과 `splunk-url`을 지정해야 합니다.
`awsfirelens` 로그 라우터를 사용하여 로그 스토리지 및 분석을 위해 AWS Partner Network 또는 AWS 서비스 대상으로 로그를 라우팅하는 경우 `log-driver-buffer-limit` 옵션을 설정하여 메모리에 버퍼링되는 로그 줄 수를 제한한 후 로그 라우터 컨테이너로 전송할 수 있습니다. 처리량이 많으면 Docker 내부 버퍼의 메모리가 부족해질 수 있으므로 잠재적인 로그 손실 문제를 해결하는 데 도움이 될 수 있습니다. 자세한 내용은 [높은 처리량을 위한 Amazon ECS 로그 구성](firelens-docker-buffer-limit.md) 섹션을 참조하세요.
`awsfirelens`를 사용하여 로그를 라우팅할 때 지정할 수 있는 다른 옵션은 대상에 따라 다릅니다. 로그를 Amazon Data Firehose로 내보낼 때 AWS 리전으로 `region`을 지정하고 `delivery_stream`으로 로그 스트림의 이름을 지정할 수 있습니다.
로그를 Amazon Kinesis Data Streams로 내보낼 때 `region`으로 AWS 리전을 지정하고 `stream`으로 데이터 스트림 이름을 지정할 수 있습니다.
로그를 Amazon OpenSearch Service로 내보낼 때 `Name`, `Host`(프로토콜이 없는 OpenSearch Service 엔드포인트), `Port`, `Index`, `Type`, `Aws_auth`, `Aws_region`, `Suppress_Type_Name`, `tls` 등의 옵션을 지정할 수 있습니다.
로그를 Amazon S3로 내보내는 경우 `bucket` 옵션을 사용하여 버킷을 지정할 수 있습니다. `region`, `total_file_size`, `upload_timeout` 및 `use_put_object`도 옵션으로 지정할 수 있습니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.19 이상을 사용해야 합니다.
`secretOptions`
유형: 객체 배열
필수 여부: 아니요
로그 구성에 전달할 암호를 나타내는 객체입니다. 로그 구성에 사용되는 보안 암호에는 인증 토큰, 인증서 또는 암호화 키가 포함될 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너에서 환경 변수로 설정할 값입니다.
`valueFrom`
유형: 문자열
필수 항목 여부: 예
컨테이너의 로그 구성에 노출할 암호.
```
"logConfiguration": {
"logDriver": "splunk",
"options": {
"splunk-url": "https://cloud.splunk.com:8080",
"splunk-token": "...",
"tag": "...",
...
},
"secretOptions": [{
"name": "splunk-token",
"valueFrom": "/ecs/logconfig/splunkcred"
}]
}
```
`firelensConfiguration`
유형: [FirelensConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FirelensConfiguration.html) 객체
필수 여부: 아니요
컨테이너의 FireLens 구성입니다. 컨테이너 로그에 대한 로그 라우터를 지정하고 구성하는 데 사용됩니다. 자세한 정보는 [Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송](using_firelens.md) 섹션을 참조하세요.
```
{
"firelensConfiguration": {
"type": "fluentd",
"options": {
"KeyName": ""
}
}
}
```
`options`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
로그 라우터를 구성할 때 사용할 옵션의 키/값 맵입니다. 이 필드는 선택 사항이며, 사용자 지정 구성 파일을 지정하거나 태스크, 태스크 정의, 클러스터 및 컨테이너 인스턴스 세부 정보와 같은 추가 메타데이터를 로그 이벤트에 추가하는 데 사용할 수 있습니다. 이 필드를 지정할 경우 사용할 구문은 `"options":{"enable-ecs-log-metadata":"true|false","config-file-type:"s3|file","config-file-value":"arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf|filepath"}`입니다. 자세한 정보는 [Amazon ECS 태스크 정의 예제: 로그를 FireLens로 라우팅](firelens-taskdef.md) 섹션을 참조하세요.
`type`
유형: 문자열
필수 항목 여부: 예
사용할 로그 라우터입니다. 유효한 값은 `fluentd` 또는 `fluentbit`입니다.
#### 보안
컨테이너 보안에 대한 자세한 내용은 [Amazon ECS 태스크 및 컨테이너 보안 모범 사례](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-tasks-containers.html)를 참조하세요.
`credentialSpecs`
유형: 문자열 배열
필수 여부: 아니요
Active Directory 인증을 위한 컨테이너를 구성하는 보안 인증 사양(`CredSpec`) 파일에 대한 SSM 또는 Amazon S3의 ARN 목록입니다. 이 파라미터를 `dockerSecurityOptions` 대신 사용하는 것이 좋습니다. 최대 ARN 수는 1개입니다.
각 ARN의 형식은 두 가지입니다.
credentialspecdomainless:MyARN
Secrets Manager에서 보안 암호에 대한 추가 섹션에 `credentialspecdomainless:MyARN`을 사용하여 `CredSpec`를 제공합니다. 보안 암호에 도메인에 대한 로그인 보안 인증을 제공합니다.
컨테이너 인스턴스에서 실행되는 각 작업을 서로 다른 도메인에 조인할 수 있습니다.
컨테이너 인스턴스를 도메인에 조인하지 않고도 이 형식을 사용할 수 있습니다.
credentialspec:MyARN
`credentialspec:MyARN`을 사용하여 단일 도메인에 대한 `CredSpec`를 제공합니다.
이 작업 정의를 사용하는 작업을 시작하려면 먼저 컨테이너 인스턴스를 도메인에 조인해야 합니다.
두 형식 모두에서 `MyARN`을 SSM 또는 Amazon S3의 ARN으로 바꿉니다.
`credspec`에서는 사용자 이름, 암호 및 연결할 도메인을 포함하는 보안 암호에 대한 Secrets Manager의 ARN을 제공해야 합니다. 보안을 강화하기 위해 도메인 없는 인증의 경우 인스턴스가 도메인에 조인되지 않습니다. 인스턴스의 다른 애플리케이션은 도메인 없는 보안 인증을 사용할 수 없습니다. 작업을 다른 도메인에 조인해야 하는 경우에도 이 파라미터를 사용하여 동일한 인스턴스에서 작업을 실행할 수 있습니다. 자세한 내용은 [Using gMSAs for Windows Containers](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/windows-gmsa.html) 및 [Using gMSAs for Linux Containers](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/linux-gmsa.html)를 참조하세요.
`user`
유형: 문자열
필수 여부: 아니요
컨테이너 내부에서 사용할 사용자입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `User` 및 docker run에 대한 `--user` 옵션에 매핑됩니다.
`host` 네트워크 모드를 사용하는 작업을 실행할 때는 루트 사용자(UID 0)를 사용하여 컨테이너를 실행해서는 안 됩니다. 보안상 항상 루트가 아닌 사용자를 사용합니다.
다음 형식을 사용하여 `user`를 지정할 수 있습니다. UID 또는 GID를 지정하는 경우 이를 양의 정수로 지정해야 합니다.
+ `user`
+ `user:group`
+ `uid`
+ `uid:gid`
+ `user:gid`
+ `uid:group`
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
```
"user": "string"
```
#### 리소스 제한
`ulimits`
유형: 객체 배열
필수 여부: 아니요
컨테이너에 정의할 `ulimit` 값 목록. 이 값은 운영 체제에 설정된 기본 리소스 할당량 설정을 다시 정의합니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Ulimits` 및 docker run에 대한 `--ulimit` 옵션에 매핑됩니다.
Fargate에 호스팅되는 Amazon ECS 작업은 `nofile` 리소스 제한 파라미터를 제외하고 운영 체제에서 설정한 기본 리소스 제한 값을 사용합니다. `nofile` 리소스 제한은 컨테이너가 사용할 수 있는 열린 파일 수에 대한 제한을 설정합니다. Fargate에서 기본 `nofile` 소프트 제한은 ` 65535`이고 하드 제한은 `65535`입니다. 두 제한의 값을 모두 최대 `1048576`으로 설정할 수 있습니다. 자세한 내용은 [태스크 리소스 제한](fargate-tasks-services.md#fargate-resource-limits) 섹션을 참조하세요.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
```
"ulimits": [
{
"name": "core"|"cpu"|"data"|"fsize"|"locks"|"memlock"|"msgqueue"|"nice"|"nofile"|"nproc"|"rss"|"rtprio"|"rttime"|"sigpending"|"stack",
"softLimit": integer,
"hardLimit": integer
}
...
]
```
`name`
타입: 문자열
유효한 값: `"core" | "cpu" | "data" | "fsize" | "locks" | "memlock" | "msgqueue" | "nice" | "nofile" | "nproc" | "rss" | "rtprio" | "rttime" | "sigpending" | "stack"`
필수 항목 여부: 예(`ulimits` 사용 시)
`ulimit`의 `type`입니다.
`hardLimit`
유형: 정수
필수 항목 여부: 예(`ulimits` 사용 시)
`ulimit` 유형의 하드 제한입니다. 값은 `ulimit`의 `type`에 따라 바이트, 초 또는 개수로 지정할 수 있습니다.
`softLimit`
유형: 정수
필수 항목 여부: 예(`ulimits` 사용 시)
`ulimit` 유형의 소프트 제한입니다. 값은 `ulimit`의 `type`에 따라 바이트, 초 또는 개수로 지정할 수 있습니다.
#### Docker 레이블
`dockerLabels`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
컨테이너에 추가할 레이블의 키/값 맵입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Labels` 및 docker run에 대한 `--label` 옵션에 매핑됩니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다.
```
"dockerLabels": {"string": "string"
...}
```
### 기타 컨테이너 정의 파라미터
다음 컨테이너 정의 파라미터는 **JSON을 통해 구성(Configure via JSON)** 옵션을 사용하여 Amazon ECS 콘솔에서 태스크 정의를 등록할 때 사용할 수 있습니다. 자세한 정보는 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md)을 참조하세요.
**Topics**
+ [Linux 파라미터](#container_definition_linuxparameters)
+ [컨테이너 종속성](#container_definition_dependson)
+ [컨테이너 제한 시간](#container_definition_timeout)
+ [System Controls](#container_definition_systemcontrols)
+ [대화형](#container_definition_interactive)
+ [의사 터미널](#container_definition_pseudoterminal)
#### Linux 파라미터
`linuxParameters`
유형: [LinuxParameters](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LinuxParameters.html) 객체
필수 여부: 아니요
컨테이너에 적용되는 Linux 관련 옵션(예: [KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html))
이 파라미터는 Windows 컨테이너에서는 지원되지 않습니다.
```
"linuxParameters": {
"capabilities": {
"add": ["string", ...],
"drop": ["string", ...]
}
}
```
`capabilities`
유형: [KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html) 객체
필수 여부: 아니요
컨테이너에 대해 Docker에서 제공하는 기본 구성에서 제거할 Linux 기능입니다. 이러한 Linux 기능에 대한 자세한 정보는 [capabilities(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) Linux 매뉴얼 페이지를 참조하세요.
`add`
유형: 문자열 배열
유효한 값: `"SYS_PTRACE"`
필수 여부: 아니요
컨테이너에 대해 Docker에서 제공하는 기본 구성에 추가할 Linux 기능입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `CapAdd` 및 docker run에 대한 `--cap-add` 옵션에 매핑됩니다.
`drop`
유형: 문자열 배열
유효한 값: `"ALL" | "AUDIT_CONTROL" | "AUDIT_WRITE" | "BLOCK_SUSPEND" | "CHOWN" | "DAC_OVERRIDE" | "DAC_READ_SEARCH" | "FOWNER" | "FSETID" | "IPC_LOCK" | "IPC_OWNER" | "KILL" | "LEASE" | "LINUX_IMMUTABLE" | "MAC_ADMIN" | "MAC_OVERRIDE" | "MKNOD" | "NET_ADMIN" | "NET_BIND_SERVICE" | "NET_BROADCAST" | "NET_RAW" | "SETFCAP" | "SETGID" | "SETPCAP" | "SETUID" | "SYS_ADMIN" | "SYS_BOOT" | "SYS_CHROOT" | "SYS_MODULE" | "SYS_NICE" | "SYS_PACCT" | "SYS_PTRACE" | "SYS_RAWIO" | "SYS_RESOURCE" | "SYS_TIME" | "SYS_TTY_CONFIG" | "SYSLOG" | "WAKE_ALARM"`
필수 여부: 아니요
컨테이너에 대해 Docker에서 제공하는 기본 구성에서 제거할 Linux 기능입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `CapDrop` 및 docker run에 대한 `--cap-drop` 옵션에 매핑됩니다.
`devices`
컨테이너에 노출될 모든 호스트 디바이스. 이 파라미터는 Docker 컨테이너 생성 명령의 `Devices` 및 docker run에 대한 `--device` 옵션에 매핑됩니다.
이 `devices` 파라미터는 Fargate 시작 유형을 사용하는 경우 지원되지 않습니다.
유형: [Device](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Device.html) 객체 배열
필수 여부: 아니요
`hostPath`
호스트 컨테이너 인스턴스의 디바이스 경로.
유형: 문자열
필수 항목 여부: 예
`containerPath`
호스트 디바이스를 노출할 컨테이너 내 경로.
유형: 문자열
필수 여부: 아니요
`permissions`
디바이스를 위해 컨테이너에 제공할 명시적 권한. 컨테이너는 기본적으로 디바이스에서 `read`, `write` 및 `mknod`에 대한 권한이 있습니다.
유형: 문자열 배열
유효한 값: `read` \$1 `write` \$1 `mknod`
`initProcessEnabled`
신호를 전달하고 프로세스의 결과를 받아들이는 컨테이너 내에서 `init` 프로세스를 실행합니다. 이 파라미터는 docker run에 대한 `--init` 옵션에 매핑됩니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.25 이상을 사용해야 합니다.
`maxSwap`
Fargate에서 실행되는 태스크에는 지원되지 않습니다.
컨테이너가 사용할 수 있는 총 스왑 메모리 양(MiB) 이 파라미터는 docker run에 대한 `--memory-swap` 옵션으로 변환되며 컨테이너 메모리의 합계에 `maxSwap` 값을 더한 값이 됩니다.
`0`의 `maxSwap` 값이 지정되면 컨테이너는 스왑을 사용하지 않습니다. 허용되는 값은 `0` 또는 양수입니다. `maxSwap` 파라미터를 생략하면 컨테이너는 실행 중인 컨테이너 인스턴스에 대한 스왑 구성을 사용합니다. `swappiness` 매개 변수를 사용하려면 `maxSwap` 값을 설정해야 합니다.
`sharedMemorySize`
`/dev/shm` 볼륨의 크기 값(MiB)입니다. 이 파라미터는 docker run에 대한 `--shm-size` 옵션에 매핑됩니다.
Fargate를 사용하는 태스크를 사용하는 경우 `sharedMemorySize` 파라미터는 지원되지 않습니다.
유형: 정수
`tmpfs`
컨테이너 경로, 마운트 옵션 및 tmpfs 마운트의 최대 크기(MiB)입니다. 이 파라미터는 docker run에 대한 `--tmpfs` 옵션에 매핑됩니다.
유형: [Tmpfs](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Tmpfs.html) 객체 배열
필수 여부: 아니요
`containerPath`
tmpfs 볼륨을 마운트할 절대 파일 경로입니다.
유형: 문자열
필수 항목 여부: 예
`mountOptions`
tmpfs 볼륨 마운트 옵션의 목록입니다.
유형: 문자열 배열
필수 여부: 아니요
유효한 값: `"defaults" | "ro" | "rw" | "suid" | "nosuid" | "dev" | "nodev" | "exec" | "noexec" | "sync" | "async" | "dirsync" | "remount" | "mand" | "nomand" | "atime" | "noatime" | "diratime" | "nodiratime" | "bind" | "rbind" | "unbindable" | "runbindable" | "private" | "rprivate" | "shared" | "rshared" | "slave" | "rslave" | "relatime" | "norelatime" | "strictatime" | "nostrictatime" | "mode" | "uid" | "gid" | "nr_inodes" | "nr_blocks" | "mpol"`
`size`
tmpfs 볼륨의 최대 크기(MiB) 입니다.
유형: 정수
필수 여부: 예
#### 컨테이너 종속성
`dependsOn`
유형: [ContainerDependency](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html) 객체의 배열
필수 여부: 아니요
컨테이너 시작 및 종료에 대해 정의된 종속성입니다. 컨테이너는 여러 종속성을 포함할 수 있습니다. 컨테이너가 시작될 때 종속성이 정의되면 컨테이너를 종료할 때 종속성이 취소됩니다. 문제 해결 예는 [컨테이너 종속성](example_task_definitions.md#example_task_definition-containerdependency) 섹션을 참조하세요.
컨테이너가 종속성 제약을 충족하지 못하거나 제약을 충족하기 전에 시간이 초과되면 Amazon ECS는 종속된 컨테이너를 다음 상태로 진행시키지 못합니다.
이 파라미터를 사용하려면 태스크 또는 서비스에서 플랫폼 버전 `1.3.0` 이상(Linux) 또는 `1.0.0`(Windows)을 사용해야 합니다.
```
"dependsOn": [
{
"containerName": "string",
"condition": "string"
}
]
```
`containerName`
유형: 문자열
필수 항목 여부: 예
지정된 조건을 충족해야 하는 컨테이너 이름입니다.
`condition`
유형: 문자열
필수 항목 여부: 예
컨테이너의 종속성 조건입니다. 다음은 사용 가능한 조건과 그 동작입니다.
+ `START` - 이 조건은 오늘의 링크와 볼륨의 동작을 에뮬레이션합니다. 이 조건은 종속 컨테이너가 시작되었는지 확인한 다음에 다른 컨테이너 시작을 허용합니다.
+ `COMPLETE` - 이 조건은 다른 컨테이너를 시작하기 전에 종속 컨테이너 실행이 완료(종료)되었는지 확인합니다. 이는 스크립트를 실행한 후 종료하는 필수적이지 않은 컨테이너에 유용할 수 있습니다. 필수 컨테이너에는 이 조건을 설정할 수 없습니다.
+ `SUCCESS` - 이 조건은 `COMPLETE`와 동일하지만 컨테이너가 `zero` 상태로 종료되어야 합니다. 필수 컨테이너에는 이 조건을 설정할 수 없습니다.
+ `HEALTHY` - 이 조건은 다른 컨테이너를 시작하기 전에 종속 컨테이너가 컨테이너 상태 확인을 통과하는지 확인합니다. 이렇게 하려면 태스크 정의에서 종속 컨테이너에 상태 확인이 구성되어 있어야 합니다. 이 조건은 태스크 시작 시에만 확인됩니다.
#### 컨테이너 제한 시간
`startTimeout`
유형: 정수
필수 여부: 아니요
예제 값: `120`
컨테이너에 대한 종속성 해결을 포기하기 전에 대기할 시간(초)입니다.
예를 들어 `containerA`에 대한 태스크 정의에서 `containerB`에 대한 종속성이 `COMPLETE`, `SUCCESS` 또는 `HEALTHY` 상태인 두 개의 컨테이너를 지정합니다. `containerB`에 대해 `startTimeout` 값이 지정되고 그 시간 내에 원하는 상태에 도달하지 않으면 `containerA`는 시작하지 않습니다.
컨테이너가 종속성 제약을 충족하지 못하거나 제약을 충족하기 전에 시간이 초과되면 Amazon ECS는 종속된 컨테이너를 다음 상태로 진행시키지 못합니다.
이 파라미터를 사용하려면 태스크 또는 서비스에서 플랫폼 버전 `1.3.0` 이상(Linux)을 사용해야 합니다. 최대값은 120초입니다.
`stopTimeout`
유형: 정수
필수 여부: 아니요
예제 값: `120`
자체적으로 정상적으로 종료하지 않을 경우 컨테이너를 강제 종료하기까지 대기할 시간(초)입니다.
이 파라미터를 사용하려면 태스크 또는 서비스에서 플랫폼 버전 `1.3.0` 이상(Linux)을 사용해야 합니다. 파라미터를 지정하지 않으면 기본값인 30초가 사용됩니다. 최대값은 120초입니다.
#### System Controls
`systemControls`
유형: [SystemControl](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_SystemControl.html) 객체
필수 여부: 아니요
컨테이너에서 설정할 네임스페이스 커널 파라미터의 목록입니다. 이 파라미터는 Docker 컨테이너 생성 명령에 있는 `Sysctls` 및 docker run에 대한 `--sysctl` 옵션에 매핑됩니다. 예를 들어 `net.ipv4.tcp_keepalive_time` 설정을 구성하여 연결을 더 오래 유지할 수 있습니다.
`awsvpc` 또는 `host` 네트워크 모드도 사용하는 단일 작업에서 여러 컨테이너에 네트워크 관련 `systemControls` 파라미터를 지정하지 않는 것이 좋습니다. 이렇게 하면 다음과 같은 단점이 있습니다.
+ 컨테이너에 `systemControls`를 설정할 경우 태스크의 모든 컨테이너에 적용됩니다. 단일 작업의 여러 컨테이너에 서로 다른 `systemControls`를 설정할 경우 마지막으로 시작되는 컨테이너에 따라 적용될 `systemControls`가 결정됩니다.
태스크 내 컨테이너에 사용할 IPC 리소스 네임스페이스를 설정하는 경우, 시스템 제어에 다음 사항이 적용됩니다. 자세한 정보는 [IPC 모드](#task_definition_ipcmode)을 참조하세요.
+ `host` IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 `systemControls`는 지원되지 않습니다.
+ `task` IPC 모드를 사용하는 작업의 경우, IPC 네임스페이스 `systemControls` 값은 작업 내 모든 컨테이너에 적용됩니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
이 파라미터는 플랫폼 버전 `1.4.0` 이상(Linux)을 사용 중인 경우 AWS Fargate에서 호스팅되는 작업에 대해서만 지원됩니다. Fargate의 Windows 컨테이너에서는 지원되지 않습니다.
```
"systemControls": [
{
"namespace":"string",
"value":"string"
}
]
```
`namespace`
유형: 문자열
필수 여부: 아니요
`value`를 설정할 네임스페이스 커널 파라미터입니다.
유효한 IPC 네임스페이스 값:`"kernel.msgmax" | "kernel.msgmnb" | "kernel.msgmni" | "kernel.sem" | "kernel.shmall" | "kernel.shmmax" | "kernel.shmmni" | "kernel.shm_rmid_forced"` 및 `"fs.mqueue.*"`로 시작하는 `Sysctls`
유효한 네트워크 네임스페이스 값: `"net.*"`로 시작하는 `Sysctls`. Fargate에서는 컨테이너 내에 있는 네임스페이스 `Sysctls`만 허용됩니다.
이러한 값은 모두 Fargate에서 지원됩니다.
`value`
유형: 문자열
필수 여부: 아니요
`namespace`에 지정된 네임스페이스 커널 파라미터의 값입니다.
#### 대화형
`interactive`
유형: 부울
필수 여부: 아니요
이 파라미터가 `true`일 경우 이것을 사용하여 `stdin` 또는 `tty`를 할당해야 하는 컨테이너화된 애플리케이션을 배포할 수 있습니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `OpenStdin` 및 docker run에 대한 `--interactive` 옵션에 매핑됩니다.
기본값은 `false`입니다.
#### 의사 터미널
`pseudoTerminal`
유형: 부울
필수 여부: 아니요
이 파라미터가 `true`일 경우 TTY가 할당됩니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Tty` 및 docker run에 대한 `--tty` 옵션에 매핑됩니다.
기본값은 `false`입니다.
## Elastic Inference 액셀러레이터 이름(폐기됨)
태스크 정의에 대한 Elastic Inference 액셀러레이터 리소스 요구 사항.
**참고**
Amazon Elastic Inference(EI)는 더 이상 고객에게 제공되지 않습니다.
태스크 정의에는 다음 파라미터가 허용됩니다.
`deviceName`
유형: 문자열
필수 항목 여부: 예
Amazon Elastic Inference 액셀러레이터 디바이스 이름입니다. `deviceName`은 컨테이너 정의에서도 참조해야 합니다. [Elastic Inference accelerator](#ContainerDefinition-elastic-inference)를 참조하세요.
`deviceType`
유형: 문자열
필수 항목 여부: 예
사용할 Elastic Inference 액셀러레이터입니다.
## 프록시 구성
`proxyConfiguration`
유형: [ProxyConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ProxyConfiguration.html) 객체
필수 여부: 아니요
App Mesh 프록시에 대한 구성 세부 정보입니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
```
"proxyConfiguration": {
"type": "APPMESH",
"containerName": "string",
"properties": [
{
"name": "string",
"value": "string"
}
]
}
```
`type`
유형: 문자열
유효한 값: `APPMESH`
필수 여부: 아니요
프록시 유형입니다. 지원되는 유일한 값은 `APPMESH`입니다.
`containerName`
유형: 문자열
필수 항목 여부: 예
App Mesh 프록시로 사용할 컨테이너의 이름입니다.
`properties`
형식: [KeyValuePair](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KeyValuePair.html) 객체 배열
필수 여부: 아니요
키-값 쌍으로 지정된 CNI(Container Network Interface) 플러그인을 제공하는 네트워크 구성 파라미터 세트입니다.
+ `IgnoredUID` - (필수) 컨테이너 정의의 `user` 파라미터에 정의된 프록시 컨테이너의 사용자 ID(UID)입니다. 프록시가 트래픽을 무시하는 데 사용됩니다. `IgnoredGID`를 지정한 경우 이 필드를 비워둘 수 있습니다.
+ `IgnoredGID` - (필수) 컨테이너 정의의 `user` 파라미터에 정의된 프록시 컨테이너의 그룹 ID(GID)입니다. 프록시가 트래픽을 무시하는 데 사용됩니다. `IgnoredUID`를 지정한 경우 이 필드를 비워둘 수 있습니다.
+ `AppPorts` - (필수) 애플리케이션이 사용하는 포트 목록입니다. 이러한 포트에 대한 네트워크 트래픽은 `ProxyIngressPort` 및 `ProxyEgressPort`로 전달됩니다.
+ `ProxyIngressPort` - (필수) `AppPorts`로 들어오는 트래픽을 보낼 포트를 지정합니다.
+ `ProxyEgressPort` - (필수) `AppPorts`에서 나가는 트래픽을 보낼 포트를 지정합니다.
+ `EgressIgnoredPorts` - (필수) 지정된 포트로 가는 아웃바운드 트래픽은 무시되고 `ProxyEgressPort`로 리디렉션되지 않습니다. 값은 빈 목록일 수 있습니다.
+ `EgressIgnoredIPs` - (필수) 지정된 IP 주소로 가는 아웃바운드 트래픽은 무시되고 `ProxyEgressPort`로 리디렉션되지 않습니다. 값은 빈 목록일 수 있습니다.
`name`
유형: 문자열
필수 여부: 아니요
키-값 쌍의 이름입니다.
`value`
유형: 문자열
필수 여부: 아니요
키-값 쌍의 값입니다.
## 볼륨
작업 정의를 등록할 때 선택적으로 볼륨 목록이 컨테이너 인스턴스의 Docker 대몬에 전달되도록 지정할 수 있습니다. 그러면 동일한 컨테이너 인스턴스에 속하는 다른 컨테이너가 액세스하는 데 전달된 볼륨 목록을 사용할 수 있습니다.
사용할 수 있는 데이터 볼륨의 유형은 다음과 같습니다.
+ Amazon EBS 볼륨 - 데이터 집약적인 컨테이너화된 워크로드에 대해 비용 효율적이며 내구성이 뛰어난 고성능 블록 스토리지를 제공합니다. 독립 실행형 작업을 실행하거나 서비스를 생성 또는 업데이트할 때 Amazon ECS 작업당 1개의 Amazon EBS 볼륨을 연결할 수 있습니다. Amazon EBS 볼륨은 Fargate에서 호스팅되는 Linux 태스크에 지원됩니다. 자세한 내용은 [Amazon ECS에서 Amazon EBS 볼륨 사용](ebs-volumes.md) 섹션을 참조하세요.
+ Amazon EFS 볼륨 — Amazon ECS 태스크에 사용할 수 있는 간단하고 영구적인 확장형 파일 스토리지를 제공합니다. Amazon EFS를 사용하면 스토리지 용량이 탄력적입니다. 파일을 추가 및 제거하면 스토리지 용량이 자동으로 확장 및 축소됩니다. 애플리케이션에서 스토리지가 필요할 때 필요한 만큼 확보할 수 있습니다. Amazon EFS 볼륨은 Fargate에서 호스팅되는 태스크에 지원됩니다. 자세한 내용은 [Amazon ECS에서 Amazon EFS 볼륨 사용](efs-volumes.md) 섹션을 참조하세요.
+ FSx for Windows File Server 볼륨 - 완전 관리형 Microsoft Windows 파일 서버를 제공합니다. 이러한 파일 서버는 Windows 파일 시스템으로 지원됩니다. FSx for Windows File Server와 Amazon ECS를 함께 사용하면 영구적이고 분산, 공유된 고정 파일 스토리지로 Windows 태스크를 프로비저닝할 수 있습니다. 자세한 정보는 [Amazon ECS에서 FSx for Windows File Server 볼륨 사용](wfsx-volumes.md)을 참조하세요.
Fargate의 Windows 컨테이너는 이 옵션을 지원하지 않습니다.
+ 바인드 탑재 – 컨테이너에 탑재된 호스트 컴퓨터의 파일 또는 디렉터리입니다. 바인드 탑재 호스트 볼륨은 태스크를 실행할 때 지원됩니다. 바인드 탑재 호스트 볼륨을 사용하려면 태스크 정의에서 `host`와 `sourcePath`(옵션) 값을 지정합니다.
자세한 내용은 [Amazon ECS 작업에 대한 스토리지 옵션](using_data_volumes.md) 섹션을 참조하세요.
컨테이너 정의에서 다음 파라미터가 허용됩니다.
`name`
유형: 문자열
필수 여부: 아니요
볼륨의 이름입니다. 최대 255자의 문자(대문자 및 소문자), 숫자, 하이(`-`) 및 밑줄(`_`)이 허용됩니다. 이 이름은 컨테이너 정의 `mountPoints` 객체의 `sourceVolume` 파라미터에서 참조됩니다.
`host`
필수 여부: 아니요
`host` 파라미터는 바인드 탑재의 수명 주기를 태스크가 아니라 호스트 Amazon EC2 인스턴스와 연결하는 데 사용합니다. `host` 파라미터가 비어 있으면 Docker 대몬이 데이터 볼륨의 호스트 경로를 할당하지만 해당 볼륨과 연결된 컨테이너가 실행을 중지한 후 데이터 유지가 보장되지 않습니다.
Windows 컨테이너는 전체 디렉터리를 동일한 드라이브에 `$env:ProgramData`로 마운트할 수 있습니다.
`sourcePath` 파라미터는 Amazon EC2 인스턴스 또는 Amazon ECS 관리형 인스턴스에 호스팅된 태스크를 사용하는 경우에만 지원됩니다.
`sourcePath`
유형: 문자열
필수 여부: 아니요
`host` 파라미터가 사용되는 경우 `sourcePath`를 지정하여 컨테이너에 제시되는 호스트 Amazon EC2 인스턴스 상의 경로를 선언합니다. 이 파라미터가 비어 있으면 Docker 대몬이 사용자 대신 호스트 경로를 할당합니다. `host` 파라미터에 `sourcePath` 파일 위치가 들어 있으면, 사용자가 수동으로 삭제하지 않는 한 데이터 볼륨이 호스트 Amazon EC2 인스턴스 상에 지정된 위치를 유지합니다. `sourcePath` 값이 호스트 Amazon EC2 인스턴스에 없을 경우 Docker 대몬이 해당 경로를 생성합니다. 해당 위치가 있을 경우 소스 경로 폴더의 콘텐츠를 내보냅니다.
`configuredAtLaunch`
유형: 부울
필수 여부: 아니요
시작 시 볼륨을 구성할 수 있는지 여부를 지정합니다. `true`로 설정하면 독립 실행형 작업을 실행하거나 서비스를 생성 또는 업데이트할 때 볼륨을 구성할 수 있습니다. `true`로 설정하면 작업 정의에서 다른 볼륨 구성을 제공할 수 없습니다. 작업에 연결하도록 Amazon EBS 볼륨을 구성하려면 이 파라미터를 `true`로 설정해야 합니다. `configuredAtLaunch`를 `true`로 설정하고 볼륨 구성을 시작 단계로 연기하면 볼륨 유형이나 특정 볼륨 설정으로 제한되지 않는 작업 정의를 생성할 수 있습니다. 그러면 여러 실행 환경에서 작업 정의를 재사용할 수 있습니다. 자세한 내용은 [Amazon EBS volumes](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ebs-volumes.html)를 참조하세요.
`dockerVolumeConfiguration`
유형: [DockerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DockerVolumeConfiguration.html) 객체
필수 여부: 아니요
이 파라미터는 Docker 볼륨을 사용할 때 지정됩니다. Docker 볼륨은 EC2 인스턴스에서 작업을 실행하는 경우에만 지원됩니다. Windows 컨테이너는 `local` 드라이버의 사용만 지원합니다. 바인드 탑재를 사용하려면 대신에 `host`를 지정하세요.
`scope`
유형: 문자열
유효한 값: `task` \$1 `shared`
필수 여부: 아니요
수명 주기를 결정하는 Docker 볼륨의 범위입니다. 범위가 `task`로 지정된 Docker 볼륨은 태스크가 시작될 때 자동으로 프로비저닝되고, 태스크가 중단되면 삭제됩니다. 범위가 `shared`로 지정된 Docker 볼륨은 태스크 중단 후에도 유지됩니다.
`autoprovision`
유형: Boolean
기본값: `false`
필수 여부: 아니요
이 값이 `true`인 경우 도커 볼륨이 아직 없으면 도커 볼륨이 생성됩니다. 이 필드는 `scope`가 `shared`인 경우에만 사용됩니다. `scope`가 `task`인 경우 이 파라미터를 생략해야 합니다.
`driver`
유형: 문자열
필수 여부: 아니요
사용할 Docker 볼륨 드라이버입니다. Docker에서 제공하는 드라이버 이름이 작업 배치에 사용되므로 드라이버 값과 이 이름이 일치해야 합니다. Docker 플러그인 CLI를 사용하여 드라이버를 설치했다면 `docker plugin ls`를 사용하여 컨테이너 인스턴스에서 드라이버 이름을 검색합니다. 다른 방법을 사용하여 드라이버를 설치했다면 Docker 플러그인 검색을 사용하여 드라이버 이름을 검색합니다.
`driverOpts`
유형: 문자열
필수 여부: 아니요
전달할 Docker 드라이버에 특정한 옵션 맵입니다. 이 파라미터는 Docker의 볼륨 생성의 `DriverOpts`에 매핑됩니다.
`labels`
유형: 문자열
필수 여부: 아니요
Docker 볼륨에 추가할 사용자 지정 메타데이터입니다.
`efsVolumeConfiguration`
유형: [EFSVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSVolumeConfiguration.html) 객체
필수 여부: 아니요
이 파라미터는 Amazon EFS 볼륨을 사용할 때 지정됩니다.
`fileSystemId`
유형: 문자열
필수 항목 여부: 예
사용할 Amazon EFS 파일 시스템 ID입니다.
`rootDirectory`
유형: 문자열
필수 여부: 아니요
호스트 내의 루트 디렉터리로 탑재할 Amazon EFS 파일 시스템 내 디렉터리입니다. 이 파라미터가 생략되면 Amazon EFS 볼륨의 루트가 사용됩니다. `/`를 지정하면 이 파라미터를 생략하는 것과 동일한 효과가 있습니다.
`authorizationConfig`에 EFS 액세스 포인트가 지정된 경우 루트 디렉터리 파라미터를 생략하거나 `/`로 설정해야 합니다. 그러면 EFS 액세스 포인트에 설정된 경로가 적용됩니다.
`transitEncryption`
유형: 문자열
유효한 값: `ENABLED` \$1 `DISABLED`
필수 여부: 아니요
Amazon ECS 호스트와 Amazon EFS 서버 간에 전송 중인 Amazon EFS 데이터에 대해 암호화를 사용 설정할지 여부를 지정합니다. Amazon EFS IAM 권한 부여를 사용하는 경우 전송 중 데이터 암호화를 사용 설정해야 합니다. 이 파라미터가 누락되면 `DISABLED`의 기본값이 사용됩니다. 자세한 내용은 *Amazon Elastic File System 사용 설명서*의 [전송 중 데이터 암호화(Encrypting Data in Transit)](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)를 참조하세요.
`transitEncryptionPort`
유형: 정수
필수 여부: 아니요
Amazon ECS 호스트와 Amazon EFS 서버 간에 암호화된 데이터를 전송할 때 사용할 포트입니다. 전송 중 데이터 암호화 포트를 지정하지 않으면 작업에서는 Amazon EFS 탑재 헬퍼가 사용하는 포트 선택 전략을 사용합니다. 자세한 내용은 *Amazon Elastic File System 사용 설명서*의 [EFS 탑재 헬퍼](https://docs.aws.amazon.com/efs/latest/ug/efs-mount-helper.html)를 참조하세요.
`authorizationConfig`
유형: [EFSAuthorizationConfig](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSAuthorizationConfig.html) 객체
필수 여부: 아니요
Amazon EFS 파일 시스템에 대한 권한 부여 구성 세부 정보입니다.
`accessPointId`
유형: 문자열
필수 여부: 아니요
사용할 액세스 포인트 ID입니다. 액세스 포인트가 지정된 경우 `efsVolumeConfiguration`에서 루트 디렉터리 값을 생략하거나 `/`로 설정해야 합니다. 그러면 EFS 액세스 포인트에 설정된 경로가 적용됩니다. 액세스 포인트를 사용하는 경우 `EFSVolumeConfiguration`에서 전송 중 데이터 암호화를 활성화해야 합니다. 자세한 내용은 *Amazon Elastic File System 사용 설명서*의 [Amazon EFS 액세스 포인트 태스크](https://docs.aws.amazon.com/efs/latest/ug/efs-access-points.html)를 참조세요.
`iam`
유형: 문자열
유효한 값: `ENABLED` \$1 `DISABLED`
필수 여부: 아니요
Amazon EFS 파일 시스템을 탑재할 때 작업 정의에 정의된 Amazon ECS 작업 IAM 역할을 사용할지 여부를 지정합니다. 활성화된 경우 `EFSVolumeConfiguration`에서 전송 중 데이터 암호화를 활성화해야 합니다. 이 파라미터가 누락되면 `DISABLED`의 기본값이 사용됩니다. 자세한 정보는 [태스크의 IAM 역할](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)을 참조하세요.
`FSxWindowsFileServerVolumeConfiguration`
유형: [FSxWindowsFileServerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FSxWindowsFileServerVolumeConfiguration.html) 객체
필수 여부: 예
이 파라미터는 작업을 저장할 [Amazon FSx for Windows File Server](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html) 파일 시스템을 사용할 때 지정됩니다.
`fileSystemId`
유형: 문자열
필수 항목 여부: 예
사용할 FSx for Windows File Server 파일 시스템 ID입니다.
`rootDirectory`
유형: 문자열
필수 항목 여부: 예
호스트 내의 루트 디렉터리로 탑재할 FSx for Windows File Server 파일 시스템 내 디렉터리입니다.
`authorizationConfig`
`credentialsParameter`
유형: 문자열
필수 항목 여부: 예
권한 부여 자격 증명 옵션입니다.
**옵션:**
+ [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 보안 암호의 Amazon 리소스 이름(ARN)입니다.
+ [AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html) 파라미터의 ARN입니다.
`domain`
유형: 문자열
필수 항목 여부: 예
셀프 호스팅된 EC2 Active Directory 또는 [AWS Directory Service for Microsoft Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/directory_microsoft_ad.html)(AWS Managed Microsoft AD) 디렉터리에서 호스팅하는 정규화된 도메인 이름입니다.
## Tags
태스크 정의를 등록할 때 태스크 정의에 적용되는 메타데이터 태그를 선택적으로 지정할 수 있습니다. 태그는 태스크 정의를 분류하고 정리하는 데 도움을 줍니다. 각 태그는 키와 값(선택사항)으로 구성됩니다. 두 가지를 모두 정의합니다. 자세한 정보는 [Amazon ECS 리소스 태그 지정](ecs-using-tags.md)을 참조하세요.
**중요**
개인 식별 정보나 기타 기밀 정보 또는 민감한 정보를 태그에 추가하지 않습니다. 청구를 비롯한 여러 AWS 서비스에서 태그에 액세스할 수 있습니다. 태그는 개인 데이터나 민감한 데이터에 사용하기 위한 것이 아닙니다.
태그 개체에서 허용되는 파라미터는 다음과 같습니다.
`key`
유형: 문자열
필수 여부: 아니요
하나의 태그를 구성하는 키-값 쌍의 일부분입니다. 키는 더 구체적인 태그 값에 대해 범주와 같은 역할을 하는 일반적인 레이블입니다.
`value`
유형: 문자열
필수 여부: 아니요
하나의 태그를 구성하는 키-값 쌍의 선택적 부분입니다. 하나의 값은 태그 범주(키) 내에서 서술자 역할을 수행합니다.
## 기타 태스크 정의 파라미터
다음의 태스크 정의 파라미터는 **JSON을 통한 구성(Configure via JSON)** 옵션을 사용하여 Amazon ECS 콘솔에 태스크 정의를 등록할 때 사용할 수 있습니다. 자세한 정보는 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md)을 참조하세요.
**Topics**
+ [임시 스토리지](#task_definition_ephemeralStorage)
+ [IPC 모드](#task_definition_ipcmode)
+ [PID 모드](#task_definition_pidmode)
+ [결함 주입](#task_definition_faultInjection)
### 임시 스토리지
`ephemeralStorage`
유형: [EphemeralStorage](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EphemeralStorage.html) 객체
필수 여부: 아니요
태스크에 할당되는 임시 스토리지 용량(GB)입니다. 이 파라미터는 AWS Fargate에서 호스팅되는 태스크에 대해 제공되는 임시 스토리지 총량을 기본 용량 이상으로 확장할 때 사용합니다. 자세한 내용은 [Amazon ECS에서 바인드 탑재 사용](bind-mounts.md) 섹션을 참조하세요.
이 파라미터는 플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0` 이상(Windows)에서만 지원됩니다.
### IPC 모드
`ipcMode`
Fargate에서 실행되는 태스크에는 지원되지 않습니다.
유형: 문자열
필수 여부: 아니요
해당 태스크의 컨테이너에 사용할 IPC 리소스 네임스페이스입니다. 유효한 값은 `host`, `task` 또는 `none`입니다. `host`를 지정하면 동일한 컨테이너 인스턴스에서 `host` IPC 모드를 지정한 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 호스트 Amazon EC2 인스턴스와 공유합니다. `task`를 지정하면 지정된 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 공유합니다. `none`이 지정된 경우, 태스크 컨테이너 내에 있는 IPC 리소스는 프라이빗이며, 태스크 또는 컨테이너 인스턴스의 다른 컨테이너와 공유되지 않습니다. 값을 지정하지 않을 경우, IPC 리소스 네임스페이스 공유는 컨테이너 인스턴스의 Docker 대몬 설정에 따라 달라집니다.
`host` IPC 모드를 사용하는 경우, 원치 않는 IPC 네임스페이스 노출이 발생할 위험이 커집니다.
해당 태스크 내 컨테이너에 대해 `systemControls`를 사용하여 네임스페이스가 있는 커널 파라미터를 설정하는 경우, IPC 리소스 네임스페이스에 다음 사항이 적용됩니다.
+ `host` IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 관련 `systemControls`는 지원되지 않습니다.
+ `task` IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 관련 `systemControls`가 태스크 내 모든 컨테이너에 적용됩니다.
**참고**
이 파라미터는 Windows 컨테이너 또는 Fargate 시작 유형을 사용하는 태스크에 대해서는 지원되지 않습니다.
### PID 모드
`pidMode`
유형: 문자열
유효한 값: `host` \$1 `task`
필수 여부: 아니요
해당 태스크의 컨테이너에 사용할 프로세스 네임스페이스입니다. 유효한 값은 `host` 또는 `task`입니다. Linux 컨테이너에서 유효한 값은 `task`뿐입니다. 예를 들어 사이드카 모니터링에서는 동일한 작업에서 실행 중인 다른 컨테이너에 대한 정보에 액세스하기 위해 `pidMode`가 필요할 수 있습니다.
`task`을 지정하면 지정된 태스크 내 모든 컨테이너가 동일한 프로세스 네임스페이스를 공유합니다.
값을 지정하지 않을 경우, 기본값은 각 컨테이너의 프라이빗 네임스페이스입니다.
**참고**
이 파라미터는 플랫폼 버전 `1.4.0` 이상(Linux)을 사용 중인 경우 AWS Fargate에서 호스팅되는 작업에 대해서만 지원됩니다. Fargate의 Windows 컨테이너에서는 지원되지 않습니다.
### 결함 주입
`enableFaultInjection`
유형: Boolean
유효한 값: `true` \$1 `false`
필수 여부: 아니요
이 파라미터가 `true`로 설정된 경우 작업의 페이로드에서 Amazon ECS와 Fargate는 작업 컨테이너의 결함 주입 요청을 수락합니다. 이 파라미터는 기본적으로 `false`로 설정되어 있습니다.
# Amazon EC2에 대한 Amazon ECS 태스크 정의 파라미터
태스크 정의는 태스크 패밀리, AWS Identity and Access Management(IAM) 태스크 역할, 네트워크 모드, 컨테이너 정의, 볼륨, 태스크 배치 제약 조건, 시작 유형과 같은 개별 부분으로 분할됩니다. 태스크 정의에는 패밀리 및 컨테이너 정의가 필요합니다. 하지만 태스크 역할, 네트워크 모드, 볼륨, 작업 배치 제약 및 시작 유형은 선택 사항입니다.
JSON 파일에서 이러한 파라미터를 사용하여 태스크 정의를 구성할 수 있습니다.
다음은 Amazon EC2의 각 태스크 정의 파라미터에 대한 자세한 설명입니다.
## Family
`family`
유형: 문자열
필수 항목 여부: 예
태스크 정의를 등록할 때 패밀리를 지정합니다. 패밀리는 개정 번호를 사용하여 지정된 태스크 정의의 여러 버전에 대한 이름과 비슷합니다. 특정 패밀리에 등록된 첫 번째 태스크 정의에는 개정 번호 1이 부여되고 그 이후 등록된 태스크 정의에는 순차적으로 개정 번호가 부여됩니다.
## Capacity
태스크 정의를 등록할 때 Amazon ECS가 태스크 정의를 검증할 용량을 지정할 수 있습니다. 태스크 정의가 유효성을 지정한 호환성에 대해 검사하지 않으면 클라이언트 예외가 반환됩니다.
태스크 정의에서 다음 파라미터가 허용됩니다.
`requiresCompatibilities`
유형: 문자열 배열
필수 여부: 아니요
유효한 값: `EC2`
태스크 정의를 검증할 용량. 이를 통해 태스크 정의에 사용되는 모든 파라미터가 Amazon EC2의 요구 사항을 충족하는지 확인할 수 있습니다.
## 태스크 역할
`taskRoleArn`
유형: 문자열
필수 여부: 아니요
태스크 정의를 등록할 때 태스크 권한의 컨테이너가 사용자 대신 연결된 정책에 지정된 AWS API를 호출하도록 허용하는 IAM 역할에 태스크 역할을 제공할 수 있습니다. 자세한 정보는 [Amazon ECS 작업 IAM 역할](task-iam-roles.md)을 참조하세요.
Amazon ECS 최적화 Windows Server AMI를 시작하려면 Windows에서 태스크를 위한 IAM 역할에 `-EnableTaskIAMRole` 옵션을 설정해야 합니다. 이 기능을 활용하려면 컨테이너가 일부 구성 코드도 실행해야 합니다. 자세한 정보는 [Amazon EC2 Windows 인스턴스 추가 구성](task-iam-roles.md#windows_task_IAM_roles)을 참조하세요.
## 태스크 실행 역할
`executionRoleArn`
유형: 문자열
필수 항목 여부: 조건부
Amazon ECS 컨테이너 에이전트에 사용자를 대신하여 AWS API를 호출할 권한을 부여하는 태스크 실행 역할의 Amazon 리소스 이름(ARN)입니다.
태스크의 요구 사항에 따라 태스크 실행 IAM 역할이 필요합니다. 자세한 정보는 [Amazon ECS 태스크 실행 IAM 역할](task_execution_IAM_role.md) 섹션을 참조하세요.
## 네트워크 모드
`networkMode`
유형: 문자열
필수 여부: 아니요
태스크의 컨테이너에 사용할 Docker 네트워킹 모드. Amazon EC2 Linux 인스턴스에서 호스팅되는 Amazon ECS의 경우, 유효한 값은 `none`, `bridge`, `awsvpc` 및 `host`입니다. 네트워크 모드를 지정하지 않으면 기본 네트워크 모드는 `bridge`입니다. Amazon EC2 Windows 인스턴스에서 호스팅되는 Amazon ECS 태스크의 경우, 유효한 값은 `default` 및 `awsvpc`입니다. 네트워크 모드가 지정되지 않으면 `default` 네트워크 모드를 사용합니다.
네트워크 모드가 `none`으로 설정된 경우에는 태스크의 컨테이너가 외부 네트워크와 연결되지 않고 컨테이너 정의에서 포트 매핑을 지정할 수 없습니다.
네트워크 모드가 `bridge`인 경우, 태스크는 태스크를 호스팅하는 각 Amazon EC2 인스턴스 내부에서 실행되는 Linux에서의 Docker 기본 가상 네트워크를 사용합니다. Linux의 기본 가상 네트워크는 `bridge` Docker 네트워크 드라이버를 사용합니다.
네트워크 모드가 `host`인 경우, 태스크는 해당 태스크를 호스팅하는 Amazon EC2 인스턴스의 ENI에 컨테이너 포트를 직접 매핑하여 Docker의 기본 가상 네트워크를 우회하는 호스트 네트워크를 사용합니다. 이 네트워크 모드에서는 동적 포트 매핑을 사용할 수 없습니다. 이 모드를 사용하는 작업 정의의 컨테이너는 특정`hostPort` 숫자를 지정해야 합니다. 호스트의 포트 번호는 여러 작업에서 사용할 수 없습니다. 따라서 단일 Amazon EC2 인스턴스에서 같은 태스크 정의를 가진 여러 태스크를 실행할 수 없습니다.
`host` 네트워크 모드를 사용하여 태스크를 실행할 때는 더 나은 보안을 위해 루트 사용자(UID 0)를 사용하여 컨테이너를 실행해서는 안 됩니다. 보안상 항상 루트가 아닌 사용자를 사용합니다.
네트워크 모드가 `awsvpc`인 경우 해당 태스크에 탄력적 네트워크 인터페이스가 할당되므로 서비스를 생성하거나 태스크 정의로 태스크를 실행하려면 `NetworkConfiguration`을 지정해야 합니다. 자세한 내용은 [EC2에 대한 Amazon ECS 태스크 네트워킹 옵션](task-networking.md) 섹션을 참조하세요.
네트워크 모드가 `default`인 경우, 태스크는 태스크를 호스팅하는 각 Amazon EC2 인스턴스 내부에서 실행되는 Windows에서의 Docker 기본 가상 네트워크를 이용합니다. Windows의 기본 가상 네트워크는`nat` Docker 네트워크 드라이버를 사용합니다.
`host` 및 `awsvpc` 네트워크 모드는 Amazon EC2 네트워크 스택을 사용하는 컨테이너에 가장 높은 수준의 네트워킹 성능을 제공합니다. `host` 및 `awsvpc` 네트워크 모드에서는 노출된 컨테이너 포트가 해당 호스트 포트(`host` 네트워크 모드의 경우) 또는 연결된 탄력적 네트워크 인터페이스 포트(`awsvpc` 네트워크 의 경우)에 직접 매핑됩니다. 이 때문에 동적 호스트 포트 매핑을 사용할 수 없습니다.
기본 EC2 인스턴스의 운영 체제에 따라 네트워크 모드가 허용됩니다. 운영 체제가 Linux일 경우에는 모든 네트워크 모드를 사용할 수 있습니다. Windows의 경우, `default` 및 `awsvpc` 모드를 사용할 수 있습니다.
## 런타임 플랫폼
`operatingSystemFamily`
유형: 문자열
필수 항목 여부: 조건부
기본값: LINUX
태스크 정의를 등록할 때 운영 체제 제품군을 지정합니다.
유효한 값은`LINUX`, `WINDOWS_SERVER_2025_FULL`, `WINDOWS_SERVER_2025_CORE`, `WINDOWS_SERVER_2022_CORE`, `WINDOWS_SERVER_2022_FULL`, `WINDOWS_SERVER_2019_FULL`, `WINDOWS_SERVER_2019_CORE`, `WINDOWS_SERVER_2016_FULL`, `WINDOWS_SERVER_2004_CORE`, `WINDOWS_SERVER_20H2_CORE`입니다.
서비스에서 사용되는 모든 태스크 정의는 이 파라미터에 대해 동일한 값을 가져야 합니다.
태스크 정의가 서비스의 일부인 경우 이 값은 서비스 `platformFamily` 값과 일치해야 합니다.
`cpuArchitecture`
유형: 문자열
필수 항목 여부: 조건부
태스크 정의를 등록할 때 CPU 아키텍처를 지정할 수 있습니다. 유효 값은 `X86_64` 및 `ARM64`입니다. 값을 지정하지 않으면 Amazon ECS는 용량 공급자 구성을 기반으로 사용 가능한 CPU 아키텍처에 태스크를 배치하려고 시도합니다. 태스크를 특정 CPU 아키텍처에 배치하게 하려면 태스크 정의에서 `cpuArchitecture`의 값을 지정합니다.
서비스에서 사용되는 모든 태스크 정의는 이 파라미터에 대해 동일한 값을 가져야 합니다.
Linux 태스크가 있는 경우 값을 `ARM64`로 설정할 수 있습니다. 자세한 내용은 [64비트 ARM 워크로드에 대한 Amazon ECS 작업 정의](ecs-arm64.md) 섹션을 참조하세요.
## 태스크 크기
태스크 정의를 등록할 때 태스크에 대해 사용할 CPU 및 메모리 총량을 지정할 수 있습니다. 이것은 컨테이너 정의 수준의 `cpu` 및 `memory` 값과는 구분됩니다. Amazon EC2 인스턴스에서 호스팅되는 태스크의 경우, 이 필드는 선택 사항입니다.
**참고**
Windows 컨테이너에 대해서는 태스크 레벨 CPU와 메모리 파라미터가 무시됩니다. Windows 컨테이너에 대해서는 컨테이너 레벨 리소스를 지정할 것을 권장합니다.
`cpu`
유형: 문자열
필수 항목 여부: 조건부
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
태스크에 대해 표시되는 CPU 단위의 하드 제한입니다. JSON 파일에서 CPU 값을 문자열(CPU 단위 또는 가상 CPU(vCPU))로 지정할 수 있습니다. 예를 들어 CPU 값을 `1024`(CPU 단위) 또는 `1 vCPU`(vCPU)로 지정할 수 있습니다. 태스크 정의를 등록할 때는 vCPU 값이 CPU 단위를 나타내는 정수로 변환됩니다.
이 필드는 선택 사항입니다. 클러스터에 요청된 CPU 단위가 사용 가능한 등록된 컨테이너 인스턴스가 없는 경우 태스크가 실패합니다. 지원되는 값은 `0.125` vCPU에서 `192` vCPU 사이입니다.
`memory`
유형: 문자열
필수 항목 여부: 조건부
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
작업에 표시할 메모리의 하드 제한. 작업 정의에서 메모리 값을 문자열(메비바이트(MiB) 또는 기가바이트(GB) 단위)로 지정할 수 있습니다. 예를 들어 메모리 값을 `3072`(MiB) 또는 `3 GB`(GB)로 지정할 수 있습니다. 태스크 정의를 등록할 때는 GB 값이 MiB를 나타내는 정수로 변환됩니다.
이 필드는 선택 사항이며 아무 값이나 사용할 수 있습니다. 태스크 수준 메모리 값이 지정된 경우 컨테이너 수준 메모리 값은 선택 사항입니다. 클러스터에 요청된 메모리에 사용 가능한 등록된 컨테이너 인스턴스가 없는 경우 태스크가 실패합니다. 특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화할 수 있습니다. 자세한 내용은 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요.
## 컨테이너 정의
작업 정의를 등록할 때 컨테이너 인스턴스의 Docker 대몬(daemon)으로 전달되는 컨테이너 정의의 목록을 지정해야 합니다. 컨테이너 정의에서 다음 파라미터가 허용됩니다.
**Topics**
+ [스탠다드 컨테이너 정의 파라미터](#standard_container_definition_params_ec2)
+ [고급 컨테이너 정의 파라미터](#advanced_container_definition_params_ec2)
+ [기타 컨테이너 정의 파라미터](#other_container_definition_params_ec2)
### 스탠다드 컨테이너 정의 파라미터
다음 태스크 정의 파라미터는 대부분의 컨테이너 정의에서 필요하거나 사용됩니다.
**Topics**
+ [이름](#container_definition_name_ec2)
+ [이미지](#container_definition_image_ec2)
+ [Memory](#container_definition_memory_ec2)
+ [포트 매핑](#container_definition_portmappings_ec2)
+ [프라이빗 리포지토리 보안 인증](#container_definition_repositoryCredentials_ec2)
#### 이름
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너의 이름. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈 및 밑줄이 허용됩니다. 여러 컨테이너를 한 태스크 정의에 연결하는 경우, 한 컨테이너의 `name`을 다른 컨테이너의 `links`에 입력할 수 있습니다. 이는 컨테이너를 연결하기 위한 것입니다.
#### 이미지
`image`
유형: 문자열
필수 항목 여부: 예
컨테이너를 시작하는 데 사용되는 이미지입니다. 이 문자열은 Docker 대몬(daemon)으로 직접 전달됩니다. 기본적으로 Docker Hub 레지스트리 내 이미지는 사용 가능합니다. `repository-url/image:tag` 또는 `repository-url/image@digest`를 사용하여 다른 리포지토리를 지정할 수도 있습니다. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈, 밑줄, 콜론, 마침표, 슬래시 및 부호가 허용됩니다. 이 파라미터는 Docker 컨테이너 생성 명령에 있는 `Image` 및 docker run 명령의 `IMAGE` 파라미터에 매핑됩니다.
+ 새 태스크가 시작될 때 Amazon ECS 컨테이너 에이전트가 컨테이너에서 사용할 지정 이미지와 태그의 최신 버전을 끌어옵니다. 그러나 이미 실행 중인 태스크에는 추후 리포지토리 이미지 업데이트가 전파되지 않습니다.
+ 태스크 정의의 이미지 경로에 태그 또는 다이제스트를 지정하지 않으면 Amazon ECS 컨테이너 에이전트가 지정된 이미지를 가져오기 위해 `latest` 태그를 사용합니다.
+ 그러나 이미 실행 중인 태스크에는 리포지토리 이미지에 대한 후속 업데이트가 전파되지 않습니다.
+ 프라이빗 리포지토리의 이미지는 지원되지 않습니다. 자세한 정보는 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md)을 참조하세요.
+ Amazon ECR 리포지토리의 이미지는 전체 `registry/repository:tag` 또는 `registry/repository@digest` 명명 규칙(예: `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app:latest` 또는 `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app@sha256:94afd1f2e64d908bc90dbca0035a5b567EXAMPLE`)을 사용하여 지정할 수 있습니다.
+ Docker Hub 공식 리포지토리 안의 이미지는 단일 이름을 사용합니다(예: `ubuntu` 또는 `mongo`).
+ Docker Hub 다른 리포지토리에 저장된 이미지는 조직 이름으로 한정됩니다(예: `amazon/amazon-ecs-agent`).
+ 다른 온라인 리포지토리 안의 이미지는 도메인 이름을 사용하여 추가로 한정됩니다(예: `quay.io/assemblyline/ubuntu`).
`versionConsistency`
유형: 문자열
유효한 값: `enabled`\$1`disabled`
필수 여부: 아니요
컨테이너 정의에 제공된 컨테이너 이미지 태그가 Amazon ECS에서 이미지 다이제스트로 확인되는지 여부를 지정합니다. 기본적으로 이 동작은 `enabled`입니다. 컨테이너의 값을 `disabled`로 설정하면 Amazon ECS에서는 컨테이너 이미지 태그가 다이제스트로 확인되지 않고 컨테이너 정의에 지정된 원본 이미지 URI가 배포에 사용됩니다. 컨테이너 이미지 확인에 대한 자세한 내용은 [컨테이너 이미지 확인](deployment-type-ecs.md#deployment-container-image-stability) 섹션을 참조하세요.
#### Memory
`memory`
유형: 정수
필수 여부: 아니요
컨테이너에 표시할 메모리의 양(MiB)입니다. 컨테이너가 여기서 지정된 메모리를 초과하려 하면 해당 컨테이너가 중지됩니다. 태스크 내 모든 컨테이너에 대해 예약된 총 메모리 양은 태스크 `memory` 값(지정된 경우)보다 작아야 합니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Memory` 및 docker run에 대한 `--memory` 옵션에 매핑됩니다.
작업 레벨 메모리 값 또는 컨테이너 레벨 메모리 값을 지정해야 합니다. 컨테이너 수준 `memory` 및 `memoryReservation` 값을 모두 지정하는 경우 `memory` 값이 `memoryReservation` 값보다 커야 합니다. `memoryReservation`을 지정하는 경우 컨테이너가 배치된 컨테이너 인스턴스의 가용 메모리 리소스에서 해당 값이 차감됩니다. 그렇지 않으면 `memory` 값이 사용됩니다.
Docker 20.10.0 이상의 대몬(daemon)은 컨테이너용으로 최소 6MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 6MiB 미만의 메모리를 지정하지 마세요.
Docker 19.03.13-ce 이하의 대몬(daemon)은 컨테이너용으로 최소 4MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 4MiB 미만의 메모리를 지정하지 마세요.
특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화하려는 경우 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요.
`memoryReservation`
유형: 정수
필수 여부: 아니요
컨테이너용으로 예약할 메모리의 소프트 제한(MiB)입니다. 시스템 메모리가 경합하는 경우 Docker는 컨테이너 메모리를 이 소프트 제한으로 유지하려고 합니다. 하지만 필요한 경우 컨테이너에서 더 많은 메모리를 사용할 수 있습니다. 컨테이너는 `memory` 파라미터에 지정된 하드 한도까지(해당하는 경우) 또는 컨테이너 인스턴스의 모든 가용 메모리(둘 중 먼저 발생하는 것)를 사용할 수 있습니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `MemoryReservation` 및 docker run에 대한 `--memory-reservation` 옵션에 매핑됩니다.
태스크 레벨 메모리 값이 지정되지 않은 경우 컨테이너 정의의 `memory` 또는 `memoryReservation`에 대해 하나 또는 둘 다에 0이 아닌 정수를 지정해야 합니다. 둘 모두 지정하는 경우 `memory`가 `memoryReservation`보다 커야 합니다. `memoryReservation`을 지정하는 경우 컨테이너가 배치된 컨테이너 인스턴스의 가용 메모리 리소스에서 해당 값이 차감됩니다. 그렇지 않으면 `memory` 값이 사용됩니다.
예를 들어 컨테이너가 통상적으로 128MiB의 메모리를 사용하지만 경우에 따라 잠깐 동안 사용량이 256MiB까지 급증한다고 가정합니다. 이 경우 `memoryReservation`을 128MiB로 설정하고 `memory` 하드 제한을 300MiB로 설정할 수 있습니다. 이 구성은 컨테이너가 컨테이너 인스턴스의 잔여 리소스 중 128MiB의 메모리만 예약하도록 허용합니다. 동시에, 이 구성을 사용하여 필요할 때 컨테이너가 더 많은 메모리 리소스를 사용하도록 허용할 수도 있습니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
Docker 20.10.0 이상의 대몬(daemon)은 컨테이너용으로 최소 6MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 6MiB 미만의 메모리를 지정하지 마세요.
Docker 19.03.13-ce 이하의 대몬(daemon)은 컨테이너용으로 최소 4MiB의 메모리를 남겨둡니다. 따라서 컨테이너에 4MiB 미만의 메모리를 지정하지 마세요.
특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화하려는 경우 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요.
#### 포트 매핑
`portMappings`
유형: 객체 배열
필수 여부: 아니요
포트 매핑은 컨테이너의 네트워크 포트를 외부에 노출시켜 클라이언트가 애플리케이션에 액세스할 수 있도록 합니다. 이 파라미터는 동일한 태스크 내에서 컨테이너 간 통신에도 사용됩니다.
`awsvpc` 네트워크 모드를 사용하는 태스크 정의의 경우 `containerPort`만 지정합니다. `hostPort`는 항상 무시되며 컨테이너 포트는 호스트에서 임의의 높은 번호의 포트에 자동으로 매핑됩니다.
Windows에서의 포트 매핑은 `localhost`가 아니라 `NetNAT` 게이트웨이 주소를 사용합니다. Windows에서의 포트 매핑에는 루프백이 없으므로 호스트 자체에서 컨테이너의 매핑된 포트에 액세스할 수 없습니다.
이 파라미터의 필드 대부분(`containerPort`, `hostPort`, `protocol` 포함)은 Docker 컨테이너 생성 명령에 있는 `PortBindings`와 docker run에 대한 `--publish` 옵션에 매핑됩니다. 태스크 정의의 네트워크 모드가 `host`로 설정되어 있으면 호스트 포트가 정의되지 않은 상태이거나 호스트 포트가 포트 매핑의 컨테이너 포트와 일치해야 합니다.
태스크가 `RUNNING` 상태에 도달한 후에는 다음 위치에서 수동 및 자동 호스트/컨테이너 포트 할당을 확인할 수 있습니다.
+ 콘솔: 선택한 태스크에 대한 컨테이너 설명의 **네트워크 바인딩** 섹션.
+ AWS CLI: **describe-tasks** 명령 출력의 `networkBindings` 섹션.
+ API: `DescribeTasks` 응답.
+ 메타데이터: 작업 메타데이터 엔드포인트.
`appProtocol`
유형: 문자열
필수 여부: 아니요
포트 매핑에 사용되는 애플리케이션 프로토콜입니다. 이 파라미터는 Service Connect에만 적용됩니다. 애플리케이션에서 사용하는 프로토콜과 일치하도록 이 파라미터를 설정하는 것이 좋습니다. 이 파라미터를 설정하면 Amazon ECS가 서비스 연결 프록시에 프로토콜별 연결 처리를 추가합니다. 이 파라미터를 설정하면 Amazon ECS가 Amazon ECS 콘솔과 CloudWatch에 프로토콜별 원격 분석을 추가합니다.
이 파라미터의 값을 설정하지 않으면 TCP가 사용됩니다. 그러나 Amazon ECS는 TCP에 대한 프로토콜별 원격 측정을 추가하지 않습니다.
자세한 내용은 [Service Connect를 사용하여 짧은 이름으로 Amazon ECS 서비스 연결](service-connect.md) 섹션을 참조하세요.
유효한 프로토콜 값: `"http" | "http2" | "grpc" `
`containerPort`
유형: 정수
필수 항목 여부: 예(`portMappings` 사용 시)
사용자 지정 또는 자동 할당된 호스트 포트에 바인딩되는 컨테이너 포트 번호입니다.
`awsvpc` 네트워크 모드를 사용하는 태스크의 경우 `containerPort`를 사용하여 노출된 포트를 지정합니다.
EC2 용량 공급자의 태스크에서 컨테이너를 사용하고 컨테이너 포트는 지정하고 호스트 포트는 지정하지 않는다고 가정합니다. 그러면 컨테이너는 자동으로 임시 포트 범위의 호스트 포트를 수신합니다. 자세한 내용은 `hostPort` 섹션을 참조하세요. 이렇게 자동 할당된 포트 매핑은 컨테이너 인스턴스의 예약 포트 할당량 100개에 포함되지 않습니다.
`containerPortRange`
유형: 문자열
필수 여부: 아니요
동적으로 매핑된 호스트 포트 범위에 바인딩된 컨테이너의 포트 번호 범위입니다.
이 파라미터는 `register-task-definition` API를 사용해서만 설정할 수 있습니다. 옵션은 `portMappings` 파라미터에서 사용할 수 있습니다. 자세한 정보는 *AWS Command Line Interface 참조*의 [register-task-definition](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html)을 참조하세요.
`containerPortRange` 지정 시 다음 규칙이 적용됩니다.
+ `bridge` 네트워크 모드 또는 `awsvpc` 네트워크 모드를 사용해야 합니다.
+ 이 파라미터는 Linux 및 Windows 운영 체제 모두에서 사용할 수 있습니다.
+ 컨테이너 인스턴스의 컨테이너 에이전트 버전은 1.67.0 이상이어야 하고 `ecs-init` 패키지의 버전은 1.67.0-1 이상이어야 합니다.
+ 컨테이너당 최대 100개의 포트 범위를 지정할 수 있습니다.
+ `hostPortRange`는 지정하지 않습니다. `hostPortRange`의 값은 다음과 같이 설정됩니다.
+ `awsvpc` 네트워크 모드를 사용하는 작업에 있는 컨테이너의 경우 `hostPort`는 `containerPort`와 동일한 값으로 설정됩니다. 이는 정적 매핑 전략입니다.
+ `bridge` 네트워크 모드를 사용하는 작업에 있는 컨테이너의 경우 Amazon ECS 에이전트는 기본 임시 범위에서 열린 호스트 포트를 찾고 이를 도커로 전달하여 컨테이너 포트에 바인딩합니다.
+ `containerPortRange`의 유효한 값은 1\$165,535입니다.
+ 포트는 컨테이너당 하나의 포트 매핑에만 포함될 수 있습니다.
+ 중첩되는 포트 범위는 지정할 수 없습니다.
+ 범위의 첫 번째 포트는 범위의 마지막 포트보다 작아야 합니다.
+ Docker에서는 포트 수가 많을 때 Docker 대몬(daemon) 구성 파일에서 docker-proxy를 끌 것을 권장합니다.
자세한 내용은 GitHub의 [Issue \$111185](https://github.com/moby/moby/issues/11185)를 참조하세요.
Docker 대몬(daemon) 구성 파일에서 docker-proxy를 끄는 방법에 대한 자세한 내용은 *Amazon ECS 개발자 안내서*의 [Docker daemon](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/bootstrap_container_instance.html#bootstrap_docker_daemon)을 참조하세요.
[DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html)를 직접적으로 호출하여 컨테이너 포트에 바인딩된 호스트 포트인 `hostPortRange`를 볼 수 있습니다.
포트 범위는 EventBridge로 전송되는 Amazon ECS 작업 이벤트에 포함되지 않습니다. 자세한 내용은 [EventBridge를 사용하여 Amazon ECS 오류에 대한 응답 자동화](cloudwatch_event_stream.md) 섹션을 참조하세요.
`hostPortRange`
유형: 문자열
필수 여부: 아니요
네트워크 바인딩에 사용되는 호스트의 포트 번호 범위입니다. 이 값은 Docker가 할당하고 Amazon ECS 에이전트가 전달합니다.
`hostPort`
유형: 정수
필수 여부: 아니요
컨테이너용으로 예약할 컨테이너 인스턴스 포트 번호입니다.
이 경우 컨테이너 포트 매핑을 위해 예약되지 않은 호스트 포트를 지정할 수 있습니다. 이를* *정적 호스트 포트 매핑이라고 합니다. 또는 `hostPort`는 생략(또는 `0`으로 설정)하고 `containerPort`는 지정할 수 있습니다. 컨테이너에서는 컨테이너 인스턴스 운영 체제 및 Docker 버전에 대한 임시 포트 범위의 포트를 자동으로 수신합니다. 이를* *동적 호스트 포트 매핑이라고 합니다.
기본 임시 포트 범위 Docker 1.6.0 버전 이상은 인스턴스의 `/proc/sys/net/ipv4/ip_local_port_range`에 나열됩니다. 이 커널 파라미터를 사용할 수 없을 경우 기본 휘발성 포트 범위 `49153–65535`가 사용됩니다. 휘발성 포트 범위에서 호스트 포트를 지정하지 마세요. 자동 할당을 위해 예약되어 있기 때문입니다. 일반적으로 `32768` 미만의 포트는 임시 포트 범위를 벗어납니다. ECS 컨테이너 에이전트 구성에서 `ECS_DYNAMIC_HOST_PORT_RANGE` 설정을 사용하여 동적으로 할당되는 호스트 포트에 대한 사용자 지정 범위를 지정할 수 있습니다. 이는 태스크가 컨테이너 인스턴스의 다른 프로세스와의 포트 충돌로 인해 시작되지 못하는 경우에 유용할 수 있습니다. 예를 들어, 외부 연결이 임시 포트 범위의 포트를 사용하고 있는 경우가 해당됩니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) 섹션을 참조하세요.
기본 예약 포트는 SSH용 `22`, Docker 포트 `2375` 및 `2376`, Amazon ECS 컨테이너 에이전트 포트 `51678-51680`입니다. 실행 중인 작업에 대해 기존에 사용자 지정된 호스트 포트도 해당 작업이 실행되는 동안 예약됩니다. 작업이 중지하면 호스트 포트는 해제됩니다. 현재 예약된 포트는 **describe-container-instances** 출력의 `remainingResources`에 표시됩니다. 하나의 컨테이너 인스턴스는 한 번에 최대 100개의 예약 포트(기본 예약 포트 포함)를 가질 수 있습니다. 자동 할당된 포트는 예약 포트 할당량 100개에 포함되지 않습니다.
`name`
유형: 문자열
필수: 아니요, 서비스에서 Service Connect와 VPC Lattice를 구성하는 데 필요
포트 매핑에 사용되는 이름입니다. 이 파라미터는 Service Connect와 VPC Lattice에만 적용됩니다. 이 파라미터는 서비스의 Service Connect와 VPC Lattice 구성에서 사용하는 이름입니다.
자세한 내용은 [Service Connect를 사용하여 짧은 이름으로 Amazon ECS 서비스 연결](service-connect.md) 섹션을 참조하세요.
다음 예제에서는 Service Connect와 VPC Lattice의 필수 필드를 모두 사용합니다.
```
"portMappings": [
{
"name": string,
"containerPort": integer
}
]
```
`protocol`
유형: 문자열
필수 여부: 아니요
포트 매핑에 사용되는 프로토콜입니다. 유효 값은 `tcp` 및 `udp`입니다. 기본값은 `tcp`입니다.
Service Connect에는 `tcp`만 지원됩니다. 이 필드가 설정되지 않은 경우 `tcp`로 암시됩니다.
UDP 지원은 버전 1.2.0 이상의 Amazon ECS 컨테이너 에이전트(예: `amzn-ami-2015.03.c-amazon-ecs-optimized` AMI) 또는 버전 1.3.0 이상으로 업데이트된 컨테이너 에이전트를 사용하여 시작된 컨테이너 인스턴스에서만 가능합니다. 컨테이너 에이전트를 최신 버전으로 업데이트하려면 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요.
호스트 포트를 지정하는 경우 다음 구문을 사용합니다.
```
"portMappings": [
{
"containerPort": integer,
"hostPort": integer
}
...
]
```
호스트 포트가 자동 할당되도록 하려면 다음 구문을 사용합니다.
```
"portMappings": [
{
"containerPort": integer
}
...
]
```
#### 프라이빗 리포지토리 보안 인증
`repositoryCredentials`
유형: [RepositoryCredentials](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RepositoryCredentials.html) 객체
필수 여부: 아니요
프라이빗 레지스트리 인증을 위한 리포지토리 보안 인증입니다.
자세한 내용은 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md) 섹션을 참조하세요.
`credentialsParameter`
유형: 문자열
필수 항목 여부: 예(`repositoryCredentials` 사용 시)
프라이빗 리포지토리 자격 증명이 포함된 암호의 Amazon 리소스 이름(ARN)입니다.
자세한 내용은 [Amazon ECS에서 AWS 컨테이너가 아닌 이미지 사용](private-auth.md) 섹션을 참조하세요.
Amazon ECS API, AWS CLI 또는 AWS SDK를 사용할 때 시작하는 작업과 같은 리전에 보안 암호가 있는 경우 보안 암호의 전체 ARN 또는 이름을 사용할 수 있습니다. AWS Management Console을 사용하는 경우 보안 암호의 전체 ARN을 지정해야 합니다.
다음은 필요한 파라미터를 나타낸 태스크 정의의 예제 조각입니다.
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
### 고급 컨테이너 정의 파라미터
다음의 고급 컨테이너 정의 파라미터는 Amazon ECS 컨테이너 인스턴스에서 컨테이너를 시작하는 데 사용된 docker run 명령에 확장된 기능을 제공합니다.
**Topics**
+ [재시작 정책](#container_definition_restart_policy_ec2)
+ [상태 확인](#container_definition_healthcheck_ec2)
+ [환경](#container_definition_environment_ec2)
+ [네트워크 설정](#container_definition_network_ec2)
+ [스토리지 및 로깅](#container_definition_storage_ec2)
+ [보안](#container_definition_security_ec2)
+ [리소스 제한](#container_definition_limits_ec2)
+ [Docker 레이블](#container_definition_labels_ec2)
#### 재시작 정책
`restartPolicy`
컨테이너 재시작 정책 및 관련 구성 파라미터. 컨테이너의 재시작 정책을 설정하면 작업을 교체할 필요 없이 Amazon ECS에서 컨테이너를 다시 시작할 수 있습니다. 자세한 내용은 [컨테이너 재시작 정책이 있는 Amazon ECS 작업의 개별 컨테이너 재시작](container-restart-policy.md) 섹션을 참조하세요.
`enabled`
유형: Boolean
필수 여부: 예
재시작 정책이 컨테이너에 대해 활성화되는지 여부를 지정합니다.
`ignoredExitCodes`
유형: 정수 배열
필수 여부: 아니요
Amazon ECS가 재시작을 시도하지 않고 무시하는 종료 코드 목록입니다. 최대 50개의 컨테이너 종료 코드를 지정할 수 있습니다. 기본적으로 Amazon ECS는 종료 코드를 무시하지 않습니다.
`restartAttemptPeriod`
유형: 정수
필수 여부: 아니요
재시작을 시도하기 전에 컨테이너를 실행해야 하는 시간(초)입니다. 컨테이너는 `restartAttemptPeriod`초 당 한 번만 재시작할 수 있습니다. 이 기간 동안 컨테이너를 실행할 수 없고 일찍 종료되면 다시 시작되지 않습니다. 최소 60초의 `restartAttemptPeriod`와 최대 1,800초의 `restartAttemptPeriod`를 설정할 수 있습니다. 기본적으로 컨테이너는 300초 동안 실행되어야 재시작할 수 있습니다.
#### 상태 확인
`healthCheck`
해당 컨테이너에 대한 컨테이너 상태 확인 명령 및 연결된 구성 파라미터. 자세한 내용은 [컨테이너 상태 확인을 사용하여 Amazon ECS 작업 상태 확인](healthcheck.md) 섹션을 참조하세요.
`command`
상태가 정상인지를 확인하기 위해 컨테이너가 실행하는 명령을 나타내는 문자열 배열입니다. 명령 인수를 직접 실행하려면 문자열 어레이가 `CMD`으로 시작하면 되고, 컨테이너의 기본 셸에서 명령을 실행하려면 `CMD-SHELL`로 시작하면 됩니다. 둘 다 지정하지 않으면 `CMD`가 사용됩니다.
AWS Management Console에서 작업 정의를 등록할 때는 쉼표로 구분된 명령 목록을 사용합니다. 이러한 명령은 작업 정의가 생성된 후 문자열로 변환됩니다. 다음은 상태 확인에 대한 입력 예제입니다.
```
CMD-SHELL, curl -f http://localhost/ || exit 1
```
AWS Management Console JSON 패널, AWS CLI 또는 API를 사용하여 작업 정의를 등록할 때는 명령 목록을 괄호로 묶어야 합니다. 다음은 상태 확인에 대한 입력 예제입니다.
```
[ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]
```
`stderr` 출력이 없는 종료 코드 0은 성공을 나타내고, 0이 아닌 종료 코드는 실패를 나타냅니다.
`interval`
각 상태 확인 간의 시간(초). 5초에서 300초 사이를 지정할 수 있습니다. 기본값은 30초입니다.
`timeout`
실패로 간주되기 전에 상태 확인이 성공하기까지의 대기 시간(초)입니다. 2초에서 60초 사이를 지정할 수 있습니다. 기본값은 5초입니다.
`retries`
컨테이너 상태가 비정상이라고 간주되기 전에 실패한 상태 확인을 재시도하는 횟수입니다. 1에서 10 사이의 재시도 횟수를 지정할 수 있습니다. 기본값은 3회 재시도입니다.
`startPeriod`
실패한 상태 확인이 최대 재시도 횟수에 포함되기 전에 컨테이너에 부트스트랩 시간이 제공되는 유예 기간 옵션입니다. 0초부터 300초까지 지정할 수 있습니다. 기본적으로 `startPeriod`는 비활성화되어 있습니다.
상태 검사가 `startPeriod` 내에 성공한 경우 컨테이너는 정상으로 간주되고 모든 후속 실패는 최대 재시도 횟수에 포함됩니다.
#### 환경
`cpu`
유형: 정수
필수 여부: 아니요
Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 `cpu` 단위입니다. Linux에서 이 파라미터는 [컨테이너 만들기](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate) 섹션의 `CpuShares`에 매핑됩니다.
각 Amazon EC2 인스턴스 유형에 사용 가능한 CPU 단위 수를 결정할 수 있습니다. 이렇게 하려면[ Amazon EC2 인스턴스](https://aws.amazon.com/ec2/instance-types/) 세부 정보 페이지에서 해당 인스턴스 유형에 대해 나열된 vCPU 수에 1,024를 곱합니다.
Linux 컨테이너는 할당된 양과 동일한 비율로, 컨테이너 인스턴스의 다른 컨테이너와 할당되지 않은 CPU 단위를 공유합니다. 예를 들어 싱글 코어 인스턴스 유형에서 단일 컨테이너 작업을 컨테이너에 512개 CPU 단위를 지정하고 실행한다고 가정해 보겠습니다. 또한 이 작업은 컨테이너 인스턴스에서 실행되는 유일한 작업입니다. 이 예에서 컨테이너는 언제라도 1,024 CPU 단위 전부를 사용할 수 있습니다. 하지만, 해당 컨테이너 인스턴스에서 동일한 태스크의 다른 사본을 시작했다고 가정합니다. 각 작업에는 필요한 경우 최소 512개의 CPU 단위가 보장됩니다. 마찬가지로 다른 컨테이너가 나머지 CPU를 사용하지 않을 경우 각 컨테이너의 CPU 사용량이 높아질 수 있습니다. 하지만 두 작업이 항상 100% 활성 상태인 경우 CPU 단위는 512개로 제한됩니다.
Linux 컨테이너 인스턴스에서, 컨테이너 인스턴스의 Docker 대몬(daemon)은 CPU 값을 사용하여 실행 컨테이너의 상대적인 CPU 공유 비율을 계산합니다. Linux 커널이 허용하는 최소 유효 CPU 공유 값은 2이고, Linux 커널이 허용하는 최대 유효 CPU 공유 값은 262144입니다. 하지만 CPU 파라미터는 필수 항목이 아니며 컨테이너 정의에서 2 미만이나 262144를 초과하는 CPU 값을 사용할 수 있습니다. CPU 값이 2 미만(null 포함)이거나 262144를 초과하는 경우 동작은 Amazon ECS 컨테이너 에이전트 버전에 따라 달라집니다.
+ **에이전트 버전 <= 1.1.0:** Null 및 0의 CPU 값이 Docker에 0으로 전달되고, Docker는 이를 1,024개 CPU 공유로 변환합니다. 1의 CPU 값이 Docker에 1로 전달되고, Linux 커널이 이를 2개 CPU 공유로 변환합니다.
+ **에이전트 버전 >= 1.2.0:** Null, 0 및 1의 CPU 값이 Docker에 2개 CPU 공유로 전달됩니다.
+ **에이전트 버전 >= 1.84.0:** 256 vCPU보다 큰 CPU 값은 Docker에 256으로 전달되며, 이는 262144개의 CPU 공유에 해당합니다.
Windows 컨테이너 인스턴스에서 CPU 할당량은 절대 할당량으로 적용됩니다. Windows 컨테이너는 작업 정의에 정의된 지정된 양의 CPU에만 액세스할 수 있습니다. Null 또는 0의 CPU 값이 Docker에 `0`으로 전달되고, Windows는 이 값을 1개 CPU의 1%로 해석합니다.
추가 예제는 [How Amazon ECS manages CPU and memory resources](https://aws.amazon.com/blogs/containers/how-amazon-ecs-manages-cpu-and-memory-resources/)를 참조하세요.
`gpu`
유형: [ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 객체
필수 여부: 아니요
Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 실제 `GPUs` 수입니다. 태스크의 모든 컨테이너에 예약된 GPU 수가 태스크가 실행되는 컨테이너 인스턴스에서 사용할 수 있는 GPU 수를 초과하면 안 됩니다. 자세한 내용은 [GPU 워크로드에 대한 Amazon ECS 작업 정의](ecs-gpu.md) 섹션을 참조하세요.
이 파라미터는 Windows 컨테이너에서는 지원되지 않습니다.
`Elastic Inference accelerator`
유형: [ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 객체
필수 여부: 아니요
`InferenceAccelerator` 유형의 경우 `value`는 태스크 정의에 지정된 `InferenceAccelerator`의 `deviceName`과 일치합니다. 자세한 내용은 [Elastic Inference 액셀러레이터 이름(폐기됨)](task_definition_parameters.md#elastic-Inference-accelerator) 섹션을 참조하세요.
이 파라미터는 Windows 컨테이너에서는 지원되지 않습니다.
`essential`
유형: 부울
필수 여부: 아니요
컨테이너의 `essential` 파라미터가 `true`로 표시되어 있고 해당 컨테이너가 어떤 이유로든 실패 또는 중지하는 경우를 가정해 보겠습니다. 이 경우 작업에 포함된 다른 모든 컨테이너도 중지합니다. 컨테이너의 `essential` 파라미터가 `false`로 표시된 경우에는 해당 컨테이너의 실패가 태스크의 나머지 컨테이너에 영향을 주지 않습니다. 이 파라미터가 생략된 경우 컨테이너가 필수로 간주됩니다.
모든 태스크에는 하나 이상의 필수 컨테이너가 있어야 합니다. 여러 컨테이너로 구성된 애플리케이션이 있다고 가정해 보겠습니다. 이 경우, 공통 용도로 사용되는 컨테이너를 구성 요소로 그룹화하고, 다른 구성 요소를 여러 작업 정의로 분리합니다. 자세한 내용은 [Amazon ECS에 대한 애플리케이션 설계](application_architecture.md) 섹션을 참조하세요.
```
"essential": true|false
```
`entryPoint`
초기 버전의 Amazon ECS 컨테이너 에이전트는 `entryPoint` 파라미터를 적절히 처리하지 못합니다. `entryPoint`를 사용하는 데 문제가 있을 경우 컨테이너 에이전트를 업데이트하거나 명령 및 인수를 `command` 배열 항목으로 입력하세요.
유형: 문자열 배열
필수 여부: 아니요
컨테이너로 전달되는 진입점입니다.
```
"entryPoint": ["string", ...]
```
`command`
유형: 문자열 배열
필수 여부: 아니요
컨테이너로 전달되는 명령입니다. 이 파라미터는 컨테이너 생성 명령의 `Cmd` 및 docker run에 대한 `COMMAND` 파라미터에 매핑됩니다. 여러 인수가 있는 경우 각 인수는 배열에서 각각 분리된 문자열이어야 합니다.
```
"command": ["string", ...]
```
`workingDirectory`
유형: 문자열
필수 여부: 아니요
컨테이너에서 명령을 실행할 태스크 디렉터리입니다. 이 파라미터는 [Docker 원격 API](https://docs.docker.com/reference/api/engine/version/v1.38/)의 [컨테이너 생성](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate) 섹션에 있는 `WorkingDir`와 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/)에 대한 `--workdir` 옵션에 매핑됩니다.
```
"workingDirectory": "string"
```
`environmentFiles`
유형: 객체 배열
필수 여부: 아니요
컨테이너로 전달할 환경 변수를 포함하는 파일 목록입니다. 이 파라미터는 docker run 명령에 대한 `--env-file` 옵션에 매핑됩니다.
FIPS가 활성화된 경우 마침표(.)가 포함된 버킷 이름(예: amzn-s3-demo-bucket1.name.example)은 지원되지 않습니다. 버킷 이름에 마침표(.)가 있으면 에이전트가 Amazon S3에서 환경 변수 파일을 가져올 수 없기 때문에 태스크가 시작되지 않습니다.
Windows 컨테이너에는 이 파라미터를 사용할 수 없습니다.
최대 10개의 환경 파일을 지정할 수 있습니다. 파일의 확장명은 `.env`여야 합니다. 환경 파일의 각 줄에는 `VARIABLE=VALUE` 형식의 환경 변수를 포함합니다. `#`으로 시작하는 줄은 주석으로 처리되며 무시됩니다.
컨테이너 정의에 지정된 개별 환경 변수가 있는 경우 환경 파일 내에 포함된 변수보다 우선합니다. 동일한 변수를 포함하는 여러 환경 파일이 지정된 경우 위에서 아래로 처리됩니다. 고유한 변수 이름을 사용하는 것이 좋습니다. 자세한 정보는 [개별 환경 변수를 Amazon ECS 컨테이너로 전달](taskdef-envfiles.md)을 참조하세요.
`value`
유형: 문자열
필수 항목 여부: 예
환경 변수 파일을 포함하는 Amazon S3 객체의 Amazon 리소스 이름(ARN)입니다.
`type`
유형: 문자열
필수 항목 여부: 예
사용할 파일 유형입니다. 지원되는 유일한 값은 `s3`입니다.
`environment`
유형: 객체 배열
필수 여부: 아니요
컨테이너로 전달할 환경 변수입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Env` 및 docker run 명령에 대한 `--env` 옵션에 매핑됩니다.
자격 증명 데이터와 같은 민감한 정보에 대해서는 일반 텍스트 환경 변수를 사용하지 않는 것이 좋습니다.
`name`
유형: 문자열
필수 항목 여부: `environment` 사용 시, 예
환경 변수의 이름입니다.
`value`
유형: 문자열
필수 항목 여부: `environment` 사용 시, 예
환경 변수의 값입니다.
```
"environment" : [
{ "name" : "string", "value" : "string" },
{ "name" : "string", "value" : "string" }
]
```
`secrets`
유형: 객체 배열
필수 여부: 아니요
컨테이너에 공개할 보안 암호를 나타내는 객체입니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너에서 환경 변수로 설정할 값입니다.
`valueFrom`
유형: 문자열
필수 항목 여부: 예
컨테이너에 노출될 암호입니다. 지원되는 값은 AWS Secrets Manager 암호의 전체 ARN이거나 혹은 AWS Systems Manager 파라미터 스토어 내 파라미터의 전체 Amazon 리소스 이름(ARN)입니다.
Systems Manager Parameter Store 파라미터 또는 Secrets Manager 파라미터가 현재 실행 중인 작업과 동일한 AWS 리전에 있을 경우 해당 암호의 전체 ARN 또는 이름을 사용할 수 있습니다. 파라미터가 다른 리전에 있다면 전체 ARN을 지정해야 합니다.
```
"secrets": [
{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}
]
```
#### 네트워크 설정
`disableNetworking`
유형: 부울
필수 여부: 아니요
이 파라미터가 true일 경우 컨테이너 내에서 네트워킹이 해제됩니다.
이 파라미터는 Windows 컨테이너 또는 `awsvpc` 네트워크 모드를 사용하는 작업에 대해서는 지원되지 않습니다.
기본값은 `false`입니다.
```
"disableNetworking": true|false
```
`links`
유형: 문자열 배열
필수 여부: 아니요
`link` 파라미터는 포트 매핑 필요 없이 컨테이너가 서로 통신하도록 허용합니다. 이 파라미터는 작업 정의의 네트워크 모드가 `bridge`로 설정된 경우에만 지원됩니다. `name:internalName` 구성은 Docker 링크의 `name:alias`와 유사합니다. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈 및 밑줄이 허용됩니다.
이 파라미터는 Windows 컨테이너 또는 `awsvpc` 네트워크 모드를 사용하는 작업에 대해서는 지원되지 않습니다.
동일한 컨테이너 인스턴스에 배치된 컨테이너는 링크 또는 호스트 포트 매핑 없이도 서로 통신할 수 있습니다. 컨테이너 인스턴스에서 네트워크 격리는 보안 그룹 및 VPC 설정에 의해 제어됩니다.
```
"links": ["name:internalName", ...]
```
`hostname`
유형: 문자열
필수 여부: 아니요
컨테이너에 사용할 호스트 이름입니다. 이 파라미터는 Docker 컨테이너 생성의 `Hostname` 및 docker run에 대한 `--hostname` 옵션에 매핑됩니다.
`awsvpc` 네트워크 모드를 사용 중인 경우에는 `hostname` 파라미터가 지원되지 않습니다.
```
"hostname": "string"
```
`dnsServers`
유형: 문자열 배열
필수 여부: 아니요
컨테이너에 제공되는 DNS 서버의 목록입니다.
이 파라미터는 Windows 컨테이너 또는 `awsvpc` 네트워크 모드를 사용하는 작업에 대해서는 지원되지 않습니다.
```
"dnsServers": ["string", ...]
```
`dnsSearchDomains`
유형: 문자열 배열
필수 여부: 아니요
패턴: ^[a-zA-Z0-9-.]\$10,253\$1[a-zA-Z0-9]\$1
컨테이너에 제공되는 DNS 검색 도메인의 목록입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `DnsSearch` 및 docker run에 대한 `--dns-search` 옵션에 매핑됩니다.
이 파라미터는 Windows 컨테이너 또는 `awsvpc` 네트워크 모드를 사용하는 태스크에 대해서는 지원되지 않습니다.
```
"dnsSearchDomains": ["string", ...]
```
`extraHosts`
유형: 객체 배열
필수 여부: 아니요
컨테이너의 `/etc/hosts` 파일에 추가할 호스트 이름 및 IP 주소 매핑의 목록입니다.
이 파라미터는 Docker 컨테이너 생성 명령의 `ExtraHosts` 및 docker run에 대한 `--add-host` 옵션에 매핑됩니다.
이 파라미터는 Windows 컨테이너 또는 `awsvpc` 네트워크 모드를 사용하는 태스크에 대해서는 지원되지 않습니다.
```
"extraHosts": [
{
"hostname": "string",
"ipAddress": "string"
}
...
]
```
`hostname`
유형: 문자열
필수 항목 여부: 예(`extraHosts` 사용 시)
`/etc/hosts` 항목에 사용할 호스트 이름입니다.
`ipAddress`
유형: 문자열
필수 항목 여부: 예(`extraHosts` 사용 시)
`/etc/hosts` 항목에 사용할 IP 주소입니다.
#### 스토리지 및 로깅
`readonlyRootFilesystem`
유형: 부울
필수 여부: 아니요
이 파라미터가 true일 경우 컨테이너에는 루트 파일 시스템에 대한 읽기 전용 액세스가 부여됩니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `ReadonlyRootfs` 및 docker run에 대한 `--read-only` 옵션에 매핑됩니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
기본값은 `false`입니다.
```
"readonlyRootFilesystem": true|false
```
`mountPoints`
유형: 객체 배열
필수 여부: 아니요
컨테이너에서 데이터 볼륨의 탑재 지점입니다. 이 파라미터는 create-container Docker API의 `Volumes` 및 docker run에 대한 `--volume` 옵션에 매핑됩니다.
Windows 컨테이너는 전체 디렉터리를 동일한 드라이브에 `$env:ProgramData`로 마운트할 수 있습니다. Windows 컨테이너는 디렉터리를 다른 드라이브에 탑재할 수 없으며, 탑재 지점은 여러 드라이브에 걸쳐 사용할 수 없습니다. Amazon EBS 볼륨을 Amazon ECS 작업에 직접 연결하려면 탑재 지점을 지정해야 합니다.
`sourceVolume`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
탑재할 볼륨의 이름입니다.
`containerPath`
유형: 문자열
필수 항목 여부: 예(`mountPoints` 사용 시)
볼륨을 탑재할 컨테이너의 경로입니다.
`readOnly`
유형: 부울
필수 여부: 아니요
이 값이 `true`일 경우 컨테이너에는 볼륨에 대한 읽기 전용 액세스가 부여됩니다. 이 값이 `false`일 경우 컨테이너는 볼륨에 쓸 수 있습니다. 기본값은 `false`입니다.
Windows 운영 체제를 실행하는 태스크의 경우 값을 기본값인 `false`로 둡니다.
`volumesFrom`
유형: 객체 배열
필수 여부: 아니요
다른 컨테이너로부터 탑재할 데이터 볼륨입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `VolumesFrom` 및 docker run에 대한 `--volumes-from` 옵션에 매핑됩니다.
`sourceContainer`
유형: 문자열
필수 항목 여부: `volumesFrom` 사용 시, 예
탑재할 볼륨이 위치한 컨테이너의 이름입니다.
`readOnly`
유형: 부울
필수 여부: 아니요
이 값이 `true`일 경우 컨테이너에는 볼륨에 대한 읽기 전용 액세스가 부여됩니다. 이 값이 `false`일 경우 컨테이너는 볼륨에 쓸 수 있습니다. 기본값은 `false`입니다.
```
"volumesFrom": [
{
"sourceContainer": "string",
"readOnly": true|false
}
]
```
`logConfiguration`
유형: [LogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) 객체
필수 여부: 아니요
컨테이너의 로그 구성 사양입니다.
로그 구성을 사용하는 태스크 정의에 대한 자세한 정보는 [Amazon ECS 작업 정의 예제](example_task_definitions.md) 섹션을 참조하세요.
이 파라미터는 Docker 컨테이너 생성 명령의 `LogConfig` 및 docker run에 대한 `--log-driver` 옵션에 매핑됩니다. 기본적으로 컨테이너는 Docker 대몬(daemon)이 사용하는 것과 동일한 로깅 드라이버를 사용합니다. 하지만 컨테이너는 이 파라미터를 사용하여 컨테이너 정의에 로그 드라이버를 지정함으로써 Docker 대몬(daemon)과 다른 로깅 드라이버를 사용할 수 있습니다. 컨테이너에 다른 로깅 드라이버를 사용하려면 컨테이너 인스턴스에서(또는 원격 로깅 옵션의 다른 로그 서버에서) 로그 시스템이 올바르게 구성되어야 합니다.
컨테이너에 대한 로그 구성을 지정할 때 다음 사항에 유의해야 합니다.
+ Amazon ECS는 Docker 대몬(daemon)에 사용 가능한 로깅 드라이버의 하위 집합을 지원합니다.
+ 이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker Remote API 버전 1.18 이상을 사용해야 합니다.
+ 컨테이너 인스턴스에서 실행되는 Amazon ECS 컨테이너 에이전트는 `ECS_AVAILABLE_LOGGING_DRIVERS` 환경 변수를 사용하여 해당 인스턴스에서 사용 가능한 로깅 드라이버를 등록해야 해당 인스턴스에 배치된 컨테이너가 이들 로그 구성 옵션을 사용할 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) 섹션을 참조하세요.
```
"logConfiguration": {
"logDriver": "awslogs","fluentd","gelf","json-file","journald","splunk","syslog","awsfirelens",
"options": {"string": "string"
...},
"secretOptions": [{
"name": "string",
"valueFrom": "string"
}]
}
```
`logDriver`
타입: 문자열
유효한 값: `"awslogs","fluentd","gelf","json-file","journald","splunk","syslog","awsfirelens"`
필수 항목 여부: `logConfiguration` 사용 시, 예
컨테이너에 사용할 로드 드라이버입니다. 앞에 나열된 유효한 값은 Amazon ECS 컨테이너 에이전트가 기본적으로 통신할 수 있는 로그 드라이버입니다.
지원되는 로그 드라이버는 `awslogs`, `fluentd`, `gelf`, `json-file`, `journald`, `syslog`, `splunk`, `awsfirelens`입니다.
태스크 정의에서 `awslogs` 로그 드라이버를 사용하여 컨테이너 로그를 CloudWatch Logs로 보내는 방법에 대한 자세한 정보는 [Amazon ECS 로그를 CloudWatch로 전송](using_awslogs.md) 섹션을 참조하세요.
`awsfirelens` 로그 드라이버 사용에 대한 자세한 정보는 [사용자 지정 로그 라우팅](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_firelens.html)을 참조하세요.
목록에 포함되지 않은 사용자 지정 드라이버가 있는 경우, [GitHub에서 사용 가능한](https://github.com/aws/amazon-ecs-agent) Amazon ECS 컨테이너 에이전트 프로젝트를 포킹하여 해당 드라이버와 함께 작동하도록 사용자 지정할 수 있습니다. 포함하고 싶은 변경에 대해서는 풀 요청을 제출할 것을 권장합니다. 단, 현재 이 소프트웨어의 수정된 사본 실행은 지원되지 않습니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다.
`options`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
로그 드라이버로 보낼 구성 옵션의 키/값 맵입니다.
지정할 수 있는 옵션은 로그 드라이버에 따라 달라집니다. 다음은 `awslogs` 라우터를 사용하여 로그를 Amazon CloudWatch로 라우팅할 때 지정할 수 있는 몇 가지 옵션입니다.
`awslogs-create-group`
필수 여부: 아니요
로그 그룹을 자동으로 생성할지를 지정합니다. 이 옵션이 지정되지 않은 경우 기본적으로 `false`로 설정됩니다.
`awslogs-create-group`을 사용하기 전에 IAM 정책이 `logs:CreateLogGroup` 권한을 포함해야 합니다.
`awslogs-region`
필수 여부: 예
`awslogs` 로그 드라이버가 Docker 로그를 보낼 AWS 리전을 지정합니다. 여러 리전의 클러스터로부터 모든 로그를 CloudWatch Logs 내 단일 리전으로 전송하도록 선택할 수 있습니다. 이는 로그를 모두 한 곳에서 볼 수 있도록 하기 위함입니다. 또는, 리전별로 구분하여 세분화할 수 있습니다. 지정한 로그 그룹이 이 옵션으로 지정한 리전에 위치하는지 확인하세요.
`awslogs-group`
필수 여부: 예
`awslogs` 로그 드라이버가 로그 스트림을 전송할 로그 그룹을 지정해야 합니다.
`awslogs-stream-prefix`
필수 항목 여부: 선택 사항
`awslogs-stream-prefix` 옵션을 사용하여 로그 스트림을 지정한 접두사, 컨테이너 이름 및 컨테이너가 속하는 Amazon ECS 태스크의 ID와 연결할 수 있습니다. 이 옵션을 사용하여 접두사를 지정하는 경우 로그 스트림은 다음 형식을 취합니다.
```
prefix-name/container-name/ecs-task-id
```
이 옵션을 사용하여 접두사를 지정하지 않는 경우 로그 스트림 이름이 컨테이너 인스턴스의 Docker 대몬에 의해 할당된 컨테이너 ID를 따서 지정됩니다. Docker 컨테이너 ID(컨테이너 인스턴스에서만 사용 가능)만으로는 로그를 전송한 컨테이너로 역추적하기 어려우므로 이 옵션에서 접두사를 지정하는 것이 좋습니다.
Amazon ECS 서비스의 경우 서비스 이름을 접두사로 사용할 수 있습니다. 이렇게 하면 로그 스트림을 컨테이너가 속하는 서비스, 로그를 전송한 컨테이너의 이름, 컨테이너가 속하는 작업의 ID로 추적할 수 있습니다.
Amazon ECS 콘솔을 사용할 때 로그 창에 로그가 표시되도록 하기 위해서는 해당 로그에 스트림 접두사를 지정해야 합니다.
`awslogs-datetime-format`
필수 여부: 아니요
이 옵션은 Python `strftime` 형식의 여러 줄 시작 패턴을 정의합니다. 로그 메시지는 패턴과 일치하는 하나의 줄과 패턴과 일치하지 않는 나머지 줄들로 이루어져 있습니다. 일치하는 줄은 로그 메시지 간의 구분 기호입니다.
이 형식을 사용하는 사용 사례의 한 예는 스택 덤프와 같은 출력을 구문 분석하는 것이며, 그렇지 않으면 여러 항목에 기록될 수 있습니다. 올바른 패턴을 통해 단일 항목으로 캡처할 수 있습니다.
자세한 내용은 [awslogs-datetime-format](https://docs.docker.com/engine/logging/drivers/awslogs/#awslogs-datetime-format)을 참조하세요.
`awslogs-datetime-format` 및 `awslogs-multiline-pattern` 옵션을 모두 구성할 수는 없습니다.
여러 줄 로깅은 모든 로그 메시지의 정규식 구문 분석 및 일치 태스크를 수행합니다. 이는 로깅 성능에 부정적인 영향을 줄 수 있습니다.
`awslogs-multiline-pattern`
필수 여부: 아니요
이 옵션은 정규식을 사용하여 여러 줄 시작 패턴을 정의합니다. 로그 메시지는 패턴과 일치하는 하나의 줄과 패턴과 일치하지 않는 나머지 줄들로 이루어져 있습니다. 일치하는 줄은 로그 메시지 간의 구분 기호입니다.
자세한 정보는 [awslogs-multiline-pattern](https://docs.docker.com/engine/logging/drivers/awslogs/#awslogs-multiline-pattern)을 참조하세요.
이 옵션은 `awslogs-datetime-format`을 구성하는 경우에 무시됩니다.
`awslogs-datetime-format` 및 `awslogs-multiline-pattern` 옵션을 모두 구성할 수는 없습니다.
여러 줄 로깅은 모든 로그 메시지의 정규식 구문 분석 및 일치 태스크를 수행합니다. 이는 로깅 성능에 부정적인 영향을 줄 수 있습니다.
다음 옵션은 지원되는 모든 로그 드라이버에 적용됩니다.
`mode`
필수 여부: 아니요
유효한 값: `non-blocking` \$1 `blocking`
이 옵션은 컨테이너에서 `logDriver`를 사용하여 지정된 로그 드라이버로 로그 메시지를 전송하는 모드를 정의합니다. 선택한 전송 모드는 컨테이너에서 나오는 로그 흐름이 중단될 때 애플리케이션 가용성에 영향을 줍니다.
`blocking` 모드를 사용하는 경우 로그 흐름이 중단되면 `stdout` 및 `stderr` 스트림에 쓰기 위한 컨테이너 코드의 호출이 차단됩니다. 결과적으로 애플리케이션의 로깅 스레드가 차단됩니다. 이로 인해 애플리케이션이 응답하지 않고 컨테이너 상태 확인에 실패할 수 있습니다.
`non-blocking` 모드를 사용하는 경우 컨테이너의 로그는 `max-buffer-size` 옵션으로 구성된 인 메모리 중간 버퍼에 대신 저장됩니다. 이렇게 하면 로그를 전송할 수 없을 때 애플리케이션이 응답하지 않게 되는 것을 방지할 수 있습니다. 서비스 가용성을 보장하고 일부 로그 손실이 괜찮다면 이 모드를 사용하는 것이 좋습니다. 자세한 내용은 [Preventing log loss with non-blocking mode in the `awslogs` container log driver](https://aws.amazon.com/blogs/containers/preventing-log-loss-with-non-blocking-mode-in-the-awslogs-container-log-driver/)를 참조하세요.
`defaultLogDriverMode` 계정 설정을 사용하여 특정 AWS 리전의 모든 컨테이너에 대해 기본 `mode`를 설정할 수 있습니다. `logConfiguration`에서 `mode` 옵션을 지정하지 않거나 계정 설정을 구성하지 않으면 Amazon ECS는 기본적으로 `non-blocking` 모드로 설정됩니다. 계정 설정에 대한 자세한 내용은 [기본 로그 드라이버 모드](ecs-account-settings.md#default-log-driver-mode) 섹션을 참조하세요.
`non-blocking` 모드를 사용하면 `max-buffer-size` 로그 옵션은 중간 메시지 스토리지에 사용되는 버퍼의 크기를 제어합니다. 애플리케이션에 따라 적절한 버퍼 크기를 지정해야 합니다. 작업 수준에서 할당된 총 메모리 양은 로그 드라이버 메모리 버퍼 외에도 모든 컨테이너에 할당된 메모리 양보다 커야 합니다.
2025년 6월 25일 Amazon ECS는 태스크 가용성을 로깅보다 우선시하기 위해 기본 로그 드라이버 모드를 `blocking`에서 `non-blocking`으로 변경했습니다. 이 변경 후에도 `blocking` 모드를 계속 사용하려면 다음 중 하나를 수행합니다.
+ 컨테이너 정의의 `logConfiguration`에서 `mode` 옵션을 `blocking`로 설정합니다.
+ `defaultLogDriverMode` 계정 설정을 `blocking`로 설정합니다.
`max-buffer-size`
필수 여부: 아니요
기본값: `10 m`
`non-blocking` 모드를 사용하면 `max-buffer-size` 로그 옵션은 중간 메시지 스토리지에 사용되는 버퍼의 크기를 제어합니다. 애플리케이션에 따라 적절한 버퍼 크기를 지정해야 합니다. 버퍼가 가득 차면 로그를 더 이상 저장할 수 없습니다. 저장할 수 없는 로그는 손실됩니다.
`splunk` 로그 라우터를 사용하여 로그를 라우팅하려면 `splunk-token`과 `splunk-url`을 지정해야 합니다.
`awsfirelens` 로그 라우터를 사용하여 로그 스토리지 및 분석을 위해 AWS Partner Network 또는 AWS 서비스 대상으로 로그를 라우팅하는 경우 `log-driver-buffer-limit` 옵션을 설정하여 메모리에 버퍼링되는 로그 줄 수를 제한한 후 로그 라우터 컨테이너로 전송할 수 있습니다. 처리량이 많으면 Docker 내부 버퍼의 메모리가 부족해질 수 있으므로 잠재적인 로그 손실 문제를 해결하는 데 도움이 될 수 있습니다. 자세한 내용은 [높은 처리량을 위한 Amazon ECS 로그 구성](firelens-docker-buffer-limit.md) 섹션을 참조하세요.
`awsfirelens`를 사용하여 로그를 라우팅할 때 지정할 수 있는 다른 옵션은 대상에 따라 다릅니다. 로그를 Amazon Data Firehose로 내보낼 때 AWS 리전으로 `region`을 지정하고 `delivery_stream`으로 로그 스트림의 이름을 지정할 수 있습니다.
로그를 Amazon Kinesis Data Streams로 내보낼 때 `region`으로 AWS 리전을 지정하고 `stream`으로 데이터 스트림 이름을 지정할 수 있습니다.
로그를 Amazon OpenSearch Service로 내보낼 때 `Name`, `Host`(프로토콜이 없는 OpenSearch Service 엔드포인트), `Port`, `Index`, `Type`, `Aws_auth`, `Aws_region`, `Suppress_Type_Name`, `tls` 등의 옵션을 지정할 수 있습니다.
로그를 Amazon S3로 내보내는 경우 `bucket` 옵션을 사용하여 버킷을 지정할 수 있습니다. `region`, `total_file_size`, `upload_timeout` 및 `use_put_object`도 옵션으로 지정할 수 있습니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.19 이상을 사용해야 합니다.
`secretOptions`
유형: 객체 배열
필수 여부: 아니요
로그 구성에 전달할 암호를 나타내는 객체입니다. 로그 구성에 사용되는 보안 암호에는 인증 토큰, 인증서 또는 암호화 키가 포함될 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
`name`
유형: 문자열
필수 항목 여부: 예
컨테이너에서 환경 변수로 설정할 값입니다.
`valueFrom`
유형: 문자열
필수 항목 여부: 예
컨테이너의 로그 구성에 노출할 암호.
```
"logConfiguration": {
"logDriver": "splunk",
"options": {
"splunk-url": "https://cloud.splunk.com:8080",
"splunk-token": "...",
"tag": "...",
...
},
"secretOptions": [{
"name": "splunk-token",
"valueFrom": "/ecs/logconfig/splunkcred"
}]
}
```
`firelensConfiguration`
유형: [FirelensConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FirelensConfiguration.html) 객체
필수 여부: 아니요
컨테이너의 FireLens 구성입니다. 컨테이너 로그에 대한 로그 라우터를 지정하고 구성하는 데 사용됩니다. 자세한 정보는 [Amazon ECS 로그를 AWS 서비스 또는 AWS Partner로 전송](using_firelens.md) 섹션을 참조하세요.
```
{
"firelensConfiguration": {
"type": "fluentd",
"options": {
"KeyName": ""
}
}
}
```
`options`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
로그 라우터를 구성할 때 사용할 옵션의 키/값 맵입니다. 이 필드는 선택 사항이며, 사용자 지정 구성 파일을 지정하거나 태스크, 태스크 정의, 클러스터 및 컨테이너 인스턴스 세부 정보와 같은 추가 메타데이터를 로그 이벤트에 추가하는 데 사용할 수 있습니다. 이 필드를 지정할 경우 사용할 구문은 `"options":{"enable-ecs-log-metadata":"true|false","config-file-type:"s3|file","config-file-value":"arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf|filepath"}`입니다. 자세한 정보는 [Amazon ECS 태스크 정의 예제: 로그를 FireLens로 라우팅](firelens-taskdef.md) 섹션을 참조하세요.
`type`
유형: 문자열
필수 항목 여부: 예
사용할 로그 라우터입니다. 유효한 값은 `fluentd` 또는 `fluentbit`입니다.
#### 보안
컨테이너 보안에 대한 자세한 내용은 [Amazon ECS 태스크 및 컨테이너 보안 모범 사례](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-tasks-containers.html)를 참조하세요.
`credentialSpecs`
유형: 문자열 배열
필수 여부: 아니요
Active Directory 인증을 위한 컨테이너를 구성하는 보안 인증 사양(`CredSpec`) 파일에 대한 SSM 또는 Amazon S3의 ARN 목록입니다. 이 파라미터를 `dockerSecurityOptions` 대신 사용하는 것이 좋습니다. 최대 ARN 수는 1개입니다.
각 ARN의 형식은 두 가지입니다.
credentialspecdomainless:MyARN
Secrets Manager에서 보안 암호에 대한 추가 섹션에 `credentialspecdomainless:MyARN`을 사용하여 `CredSpec`를 제공합니다. 보안 암호에 도메인에 대한 로그인 보안 인증을 제공합니다.
컨테이너 인스턴스에서 실행되는 각 작업을 서로 다른 도메인에 조인할 수 있습니다.
컨테이너 인스턴스를 도메인에 조인하지 않고도 이 형식을 사용할 수 있습니다.
credentialspec:MyARN
`credentialspec:MyARN`을 사용하여 단일 도메인에 대한 `CredSpec`를 제공합니다.
이 작업 정의를 사용하는 작업을 시작하려면 먼저 컨테이너 인스턴스를 도메인에 조인해야 합니다.
두 형식 모두에서 `MyARN`을 SSM 또는 Amazon S3의 ARN으로 바꿉니다.
`credspec`에서는 사용자 이름, 암호 및 연결할 도메인을 포함하는 보안 암호에 대한 Secrets Manager의 ARN을 제공해야 합니다. 보안을 강화하기 위해 도메인 없는 인증의 경우 인스턴스가 도메인에 조인되지 않습니다. 인스턴스의 다른 애플리케이션은 도메인 없는 보안 인증을 사용할 수 없습니다. 작업을 다른 도메인에 조인해야 하는 경우에도 이 파라미터를 사용하여 동일한 인스턴스에서 작업을 실행할 수 있습니다. 자세한 내용은 [Using gMSAs for Windows Containers](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/windows-gmsa.html) 및 [Using gMSAs for Linux Containers](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/linux-gmsa.html)를 참조하세요.
`privileged`
유형: 부울
필수 여부: 아니요
이 파라미터가 true일 경우 컨테이너에는 호스트 컨테이너 인스턴스에 대한 승격된 권한을 부여받습니다(`root` 사용자와 비슷함). `privileged`로 컨테이너를 실행하는 것이 좋습니다. 대부분의 경우, `privileged`를 사용하는 대신 특정 파라미터를 사용하여 정확히 필요한 권한을 지정할 수 있습니다.
이 파라미터는 Docker 컨테이너 생성 명령의 `Privileged` 및 docker run에 대한 `--privileged` 옵션에 매핑됩니다.
이 파라미터는 Windows 컨테이너 또는 Fargate 시작 유형을 사용하는 태스크에 대해서는 지원되지 않습니다.
기본값은 `false`입니다.
```
"privileged": true|false
```
`user`
유형: 문자열
필수 여부: 아니요
컨테이너 내부에서 사용할 사용자입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `User` 및 docker run에 대한 `--user` 옵션에 매핑됩니다.
`host` 네트워크 모드를 사용하는 작업을 실행할 때는 루트 사용자(UID 0)를 사용하여 컨테이너를 실행해서는 안 됩니다. 보안상 항상 루트가 아닌 사용자를 사용합니다.
다음 형식을 사용하여 `user`를 지정할 수 있습니다. UID 또는 GID를 지정하는 경우 이를 양의 정수로 지정해야 합니다.
+ `user`
+ `user:group`
+ `uid`
+ `uid:gid`
+ `user:gid`
+ `uid:group`
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
```
"user": "string"
```
`dockerSecurityOptions`
유형: 문자열 배열
유효한 값: "no-new-privileges" \$1 "apparmor:PROFILE" \$1 "label:*value*" \$1 "credentialspec:*CredentialSpecFilePath*"
필수 여부: 아니요
여러 보안 시스템에 대한 사용자 지정 구성을 제공하는 문자열 목록입니다.
Linux 태스크의 경우 이 파라미터를 사용하여 SELinux 및 AppArmor 다단계 보안 시스템의 사용자 지정 레이블을 참조할 수 있습니다.
이 파라미터를 사용하여 Active Directory 인증을 위한 컨테이너를 구성하는 보안 인증 사양 파일을 참조할 수 있습니다. 자세한 내용은 [Amazon ECS의 EC2 Windows 컨테이너에 대해 gMSA를 사용하는 방법 알아보기](windows-gmsa.md) 및 [Amazon ECS에서 EC2 Linux 컨테이너에 대해 gMSA 사용](linux-gmsa.md)(을)를 참조하세요.
이 파라미터는 Docker 컨테이너 생성 명령의 `SecurityOpt` 및 docker run에 대한 `--security-opt` 옵션에 매핑됩니다.
```
"dockerSecurityOptions": ["string", ...]
```
컨테이너 인스턴스에서 실행되는 Amazon ECS 컨테이너 에이전트는 `ECS_SELINUX_CAPABLE=true` 또는 `ECS_APPARMOR_CAPABLE=true` 환경 변수를 사용하여 해당 인스턴스에서 사용 가능한 로깅 드라이버를 등록해야 해당 인스턴스에 배치된 컨테이너가 이들 보안 옵션을 사용할 수 있습니다. 자세한 정보는 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md)을 참조하세요.
#### 리소스 제한
`ulimits`
유형: 객체 배열
필수 여부: 아니요
컨테이너에 정의할 `ulimit` 값 목록. 이 값은 운영 체제에 설정된 기본 리소스 할당량 설정을 다시 정의합니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Ulimits` 및 docker run에 대한 `--ulimit` 옵션에 매핑됩니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
```
"ulimits": [
{
"name": "core"|"cpu"|"data"|"fsize"|"locks"|"memlock"|"msgqueue"|"nice"|"nofile"|"nproc"|"rss"|"rtprio"|"rttime"|"sigpending"|"stack",
"softLimit": integer,
"hardLimit": integer
}
...
]
```
`name`
타입: 문자열
유효한 값: `"core" | "cpu" | "data" | "fsize" | "locks" | "memlock" | "msgqueue" | "nice" | "nofile" | "nproc" | "rss" | "rtprio" | "rttime" | "sigpending" | "stack"`
필수 항목 여부: 예(`ulimits` 사용 시)
`ulimit`의 `type`입니다.
`hardLimit`
유형: 정수
필수 항목 여부: 예(`ulimits` 사용 시)
`ulimit` 유형의 하드 제한입니다. 값은 `ulimit`의 `type`에 따라 바이트, 초 또는 개수로 지정할 수 있습니다.
`softLimit`
유형: 정수
필수 항목 여부: 예(`ulimits` 사용 시)
`ulimit` 유형의 소프트 제한입니다. 값은 `ulimit`의 `type`에 따라 바이트, 초 또는 개수로 지정할 수 있습니다.
#### Docker 레이블
`dockerLabels`
유형: 문자열 대 문자열 맵
필수 여부: 아니요
컨테이너에 추가할 레이블의 키/값 맵입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Labels` 및 docker run에 대한 `--label` 옵션에 매핑됩니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.18 이상을 사용해야 합니다.
```
"dockerLabels": {"string": "string"
...}
```
### 기타 컨테이너 정의 파라미터
다음 컨테이너 정의 파라미터는 **JSON을 통해 구성(Configure via JSON)** 옵션을 사용하여 Amazon ECS 콘솔에서 태스크 정의를 등록할 때 사용할 수 있습니다. 자세한 정보는 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md)을 참조하세요.
**Topics**
+ [Linux 파라미터](#container_definition_linuxparameters_ec2)
+ [컨테이너 종속성](#container_definition_dependson_ec2)
+ [컨테이너 제한 시간](#container_definition_timeout_ec2)
+ [System Controls](#container_definition_systemcontrols_ec2)
+ [대화형](#container_definition_interactive_ec2)
+ [의사 터미널](#container_definition_pseudoterminal_ec2)
#### Linux 파라미터
`linuxParameters`
유형: [LinuxParameters](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LinuxParameters.html) 객체
필수 여부: 아니요
컨테이너에 적용되는 Linux 관련 옵션(예: [KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html))
이 파라미터는 Windows 컨테이너에서는 지원되지 않습니다.
```
"linuxParameters": {
"capabilities": {
"add": ["string", ...],
"drop": ["string", ...]
}
}
```
`capabilities`
유형: [KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities_ec2.html) 객체
필수 여부: 아니요
컨테이너에 대해 Docker에서 제공하는 기본 구성에 추가하거나 제거할 Linux 기능입니다. 이러한 Linux 기능에 대한 자세한 정보는 [capabilities(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) Linux 매뉴얼 페이지를 참조하세요.
`add`
유형: 문자열 배열
유효한 값: `"ALL" | "AUDIT_CONTROL" | "AUDIT_READ" | "AUDIT_WRITE" | "BLOCK_SUSPEND" | "CHOWN" | "DAC_OVERRIDE" | "DAC_READ_SEARCH" | "FOWNER" | "FSETID" | "IPC_LOCK" | "IPC_OWNER" | "KILL" | "LEASE" | "LINUX_IMMUTABLE" | "MAC_ADMIN" | "MAC_OVERRIDE" | "MKNOD" | "NET_ADMIN" | "NET_BIND_SERVICE" | "NET_BROADCAST" | "NET_RAW" | "SETFCAP" | "SETGID" | "SETPCAP" | "SETUID" | "SYS_ADMIN" | "SYS_BOOT" | "SYS_CHROOT" | "SYS_MODULE" | "SYS_NICE" | "SYS_PACCT" | "SYS_PTRACE" | "SYS_RAWIO" | "SYS_RESOURCE" | "SYS_TIME" | "SYS_TTY_CONFIG" | "SYSLOG" | "WAKE_ALARM"`
필수 여부: 아니요
컨테이너에 대해 Docker에서 제공하는 기본 구성에 추가할 Linux 기능입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `CapAdd` 및 docker run에 대한 `--cap-add` 옵션에 매핑됩니다.
`add`
유형: 문자열 배열
유효한 값: `"SYS_PTRACE"`
필수 여부: 아니요
컨테이너에 대해 Docker에서 제공하는 기본 구성에 추가할 Linux 기능입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `CapAdd` 및 docker run에 대한 `--cap-add` 옵션에 매핑됩니다.
`drop`
유형: 문자열 배열
유효한 값: `"ALL" | "AUDIT_CONTROL" | "AUDIT_WRITE" | "BLOCK_SUSPEND" | "CHOWN" | "DAC_OVERRIDE" | "DAC_READ_SEARCH" | "FOWNER" | "FSETID" | "IPC_LOCK" | "IPC_OWNER" | "KILL" | "LEASE" | "LINUX_IMMUTABLE" | "MAC_ADMIN" | "MAC_OVERRIDE" | "MKNOD" | "NET_ADMIN" | "NET_BIND_SERVICE" | "NET_BROADCAST" | "NET_RAW" | "SETFCAP" | "SETGID" | "SETPCAP" | "SETUID" | "SYS_ADMIN" | "SYS_BOOT" | "SYS_CHROOT" | "SYS_MODULE" | "SYS_NICE" | "SYS_PACCT" | "SYS_PTRACE" | "SYS_RAWIO" | "SYS_RESOURCE" | "SYS_TIME" | "SYS_TTY_CONFIG" | "SYSLOG" | "WAKE_ALARM"`
필수 여부: 아니요
컨테이너에 대해 Docker에서 제공하는 기본 구성에서 제거할 Linux 기능입니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `CapDrop` 및 docker run에 대한 `--cap-drop` 옵션에 매핑됩니다.
`devices`
컨테이너에 노출될 모든 호스트 디바이스. 이 파라미터는 Docker 컨테이너 생성 명령의 `Devices` 및 docker run에 대한 `--device` 옵션에 매핑됩니다.
유형: [Device](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Device.html) 객체 배열
필수 여부: 아니요
`hostPath`
호스트 컨테이너 인스턴스의 디바이스 경로.
유형: 문자열
필수 항목 여부: 예
`containerPath`
호스트 디바이스를 노출할 컨테이너 내 경로.
유형: 문자열
필수 여부: 아니요
`permissions`
디바이스를 위해 컨테이너에 제공할 명시적 권한. 컨테이너는 기본적으로 디바이스에서 `read`, `write` 및 `mknod`에 대한 권한이 있습니다.
유형: 문자열 배열
유효한 값: `read` \$1 `write` \$1 `mknod`
`initProcessEnabled`
신호를 전달하고 프로세스의 결과를 받아들이는 컨테이너 내에서 `init` 프로세스를 실행합니다. 이 파라미터는 docker run에 대한 `--init` 옵션에 매핑됩니다.
이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.25 이상을 사용해야 합니다.
`maxSwap`
컨테이너가 사용할 수 있는 총 스왑 메모리 양(MiB) 이 파라미터는 docker run에 대한 `--memory-swap` 옵션으로 변환되며 컨테이너 메모리의 합계에 `maxSwap` 값을 더한 값이 됩니다.
`0`의 `maxSwap` 값이 지정되면 컨테이너는 스왑을 사용하지 않습니다. 허용되는 값은 `0` 또는 양수입니다. `maxSwap` 파라미터를 생략하면 컨테이너는 실행 중인 컨테이너 인스턴스에 대한 스왑 구성을 사용합니다. `swappiness` 매개 변수를 사용하려면 `maxSwap` 값을 설정해야 합니다.
`sharedMemorySize`
`/dev/shm` 볼륨의 크기 값(MiB)입니다. 이 파라미터는 docker run에 대한 `--shm-size` 옵션에 매핑됩니다.
유형: 정수
`swappiness`
이 파라미터를 통해 컨테이너의 메모리 스왑 동작을 조정할 수 있습니다. `swappiness` 값이 `0`이면 필요하지 않은 경우 스와핑이 발생하지 않도록 합니다. `swappiness` 값이 `100`이면 페이지가 자주 스와핑되도록 합니다. 허용되는 값은 `0`과 `100` 사이의 숫자입니다. 값을 지정하지 않으면 기본값 `60`이 사용됩니다. 또한, `maxSwap` 값이 지정되지 않은 경우 이 파라미터는 무시됩니다. 이 파라미터는 docker run에 대한 `--memory-swappiness` 옵션에 매핑됩니다.
Amazon Linux 2023에서 작업을 사용하는 경우에는 `swappiness` 파라미터가 지원되지 않습니다.
`tmpfs`
컨테이너 경로, 마운트 옵션 및 tmpfs 마운트의 최대 크기(MiB)입니다. 이 파라미터는 docker run에 대한 `--tmpfs` 옵션에 매핑됩니다.
유형: [Tmpfs](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Tmpfs.html) 객체 배열
필수 여부: 아니요
`containerPath`
tmpfs 볼륨을 마운트할 절대 파일 경로입니다.
유형: 문자열
필수 항목 여부: 예
`mountOptions`
tmpfs 볼륨 마운트 옵션의 목록입니다.
유형: 문자열 배열
필수 여부: 아니요
유효한 값: `"defaults" | "ro" | "rw" | "suid" | "nosuid" | "dev" | "nodev" | "exec" | "noexec" | "sync" | "async" | "dirsync" | "remount" | "mand" | "nomand" | "atime" | "noatime" | "diratime" | "nodiratime" | "bind" | "rbind" | "unbindable" | "runbindable" | "private" | "rprivate" | "shared" | "rshared" | "slave" | "rslave" | "relatime" | "norelatime" | "strictatime" | "nostrictatime" | "mode" | "uid" | "gid" | "nr_inodes" | "nr_blocks" | "mpol"`
`size`
tmpfs 볼륨의 최대 크기(MiB) 입니다.
유형: 정수
필수 여부: 예
#### 컨테이너 종속성
`dependsOn`
유형: [ContainerDependency](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html) 객체의 배열
필수 여부: 아니요
컨테이너 시작 및 종료에 대해 정의된 종속성입니다. 컨테이너는 여러 종속성을 포함할 수 있습니다. 컨테이너가 시작될 때 종속성이 정의되면 컨테이너를 종료할 때 종속성이 취소됩니다. 문제 해결 예는 [컨테이너 종속성](example_task_definitions.md#example_task_definition-containerdependency) 섹션을 참조하세요.
컨테이너가 종속성 제약을 충족하지 못하거나 제약을 충족하기 전에 시간이 초과되면 Amazon ECS는 종속된 컨테이너를 다음 상태로 진행시키지 못합니다.
컨테이너 종속성을 사용하려면 컨테이너 인스턴스에 버전 `1.26.0` 이상의 컨테이너 에이전트가 필요합니다. 그러나 최신 버전의 컨테이너 에이전트를 사용하는 것이 좋습니다. 에이전트 버전을 확인하고 최신 버전으로 업데이트하는 방법에 대한 자세한 정보는 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요. Amazon ECS 최적화 Amazon Linux AMI를 사용하는 경우 해당 인스턴스에는 `1.26.0-1` 이상 버전의 `ecs-init` 패키지가 필요합니다. 컨테이너 인스턴스가 버전 `20190301` 이상에서 시작된 경우 필요한 버전의 컨테이너 에이전트 및 `ecs-init`이 포함되어 있습니다. 자세한 내용은 [Amazon ECS 최적화 Linux AMI](ecs-optimized_AMI.md) 섹션을 참조하세요.
```
"dependsOn": [
{
"containerName": "string",
"condition": "string"
}
]
```
`containerName`
유형: 문자열
필수 항목 여부: 예
지정된 조건을 충족해야 하는 컨테이너 이름입니다.
`condition`
유형: 문자열
필수 항목 여부: 예
컨테이너의 종속성 조건입니다. 다음은 사용 가능한 조건과 그 동작입니다.
+ `START` - 이 조건은 오늘의 링크와 볼륨의 동작을 에뮬레이션합니다. 이 조건은 종속 컨테이너가 시작되었는지 확인한 다음에 다른 컨테이너 시작을 허용합니다.
+ `COMPLETE` - 이 조건은 다른 컨테이너를 시작하기 전에 종속 컨테이너 실행이 완료(종료)되었는지 확인합니다. 이는 스크립트를 실행한 후 종료하는 필수적이지 않은 컨테이너에 유용할 수 있습니다. 필수 컨테이너에는 이 조건을 설정할 수 없습니다.
+ `SUCCESS` - 이 조건은 `COMPLETE`와 동일하지만 컨테이너가 `zero` 상태로 종료되어야 합니다. 필수 컨테이너에는 이 조건을 설정할 수 없습니다.
+ `HEALTHY` - 이 조건은 다른 컨테이너를 시작하기 전에 종속 컨테이너가 컨테이너 상태 확인을 통과하는지 확인합니다. 이렇게 하려면 태스크 정의에서 종속 컨테이너에 상태 확인이 구성되어 있어야 합니다. 이 조건은 태스크 시작 시에만 확인됩니다.
#### 컨테이너 제한 시간
`startTimeout`
유형: 정수
필수 여부: 아니요
예제 값: `120`
컨테이너에 대한 종속성 해결을 포기하기 전에 대기할 시간(초)입니다.
예를 들어 `containerA`에 대한 태스크 정의에서 `containerB`에 대한 종속성이 `COMPLETE`, `SUCCESS` 또는 `HEALTHY` 상태인 두 개의 컨테이너를 지정합니다. `containerB`에 대해 `startTimeout` 값이 지정되고 그 시간 내에 원하는 상태에 도달하지 않으면 `containerA`는 시작하지 않습니다.
컨테이너가 종속성 제약을 충족하지 못하거나 제약을 충족하기 전에 시간이 초과되면 Amazon ECS는 종속된 컨테이너를 다음 상태로 진행시키지 못합니다.
최대값은 120초입니다.
`stopTimeout`
유형: 정수
필수 여부: 아니요
예제 값: `120`
자체적으로 정상적으로 종료하지 않을 경우 컨테이너를 강제 종료하기까지 대기할 시간(초)입니다.
`stopTimeout` 파라미터를 지정하지 않으면 Amazon ECS 컨테이너 에이전트 구성 변수 `ECS_CONTAINER_STOP_TIMEOUT`에 대해 설정된 값이 사용됩니다. `stopTimeout` 파라미터 또는 `ECS_CONTAINER_STOP_TIMEOUT` 에이전트 구성 변수를 모두 설정하지 않은 경우 Linux 컨테이너의 경우 30초(기본값)가 사용되고 Windows 컨테이너의 경우 30초(기본값)가 사용됩니다. 컨테이너 중지 제한 시간 값을 활성화하려면 컨테이너 인스턴스에 버전 1.26.0 이상의 컨테이너 에이전트가 필요합니다. 그러나 최신 버전의 컨테이너 에이전트를 사용하는 것이 좋습니다. 에이전트 버전을 확인하고 최신 버전으로 업데이트하는 방법에 대한 자세한 정보는 [Amazon ECS 컨테이너 에이전트 업데이트](ecs-agent-update.md) 섹션을 참조하세요. Amazon ECS 최적화 Amazon Linux AMI를 사용하는 경우 해당 인스턴스에는 1.26.0-1 이상 버전의 `ecs-init` 패키지가 필요합니다. 컨테이너 인스턴스가 버전 `20190301` 이상에서 시작된 경우 필요한 버전의 컨테이너 에이전트 및 `ecs-init`이 포함되어 있습니다. 자세한 정보는 [Amazon ECS 최적화 Linux AMI](ecs-optimized_AMI.md)을 참조하세요.
#### System Controls
`systemControls`
유형: [SystemControl](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_SystemControl.html) 객체
필수 여부: 아니요
컨테이너에서 설정할 네임스페이스 커널 파라미터의 목록입니다. 이 파라미터는 Docker 컨테이너 생성 명령에 있는 `Sysctls` 및 docker run에 대한 `--sysctl` 옵션에 매핑됩니다. 예를 들어 `net.ipv4.tcp_keepalive_time` 설정을 구성하여 연결을 더 오래 유지할 수 있습니다.
`awsvpc` 또는 `host` 네트워크 모드도 사용하는 단일 작업에서 여러 컨테이너에 네트워크 관련 `systemControls` 파라미터를 지정하지 않는 것이 좋습니다. 이렇게 하면 다음과 같은 단점이 있습니다.
+ `awsvpc` 네트워크 모드를 사용하는 작업의 경우 컨테이너에 `systemControls`을 설정할 경우 작업의 모든 컨테이너에 적용됩니다. 단일 작업의 여러 컨테이너에 서로 다른 `systemControls`를 설정할 경우 마지막으로 시작되는 컨테이너에 따라 적용될 `systemControls`가 결정됩니다.
+ `host` 네트워크 모드를 사용하는 태스크의 경우, 네트워크 네임스페이스 `systemControls`는 지원되지 않습니다.
태스크 내 컨테이너에 사용할 IPC 리소스 네임스페이스를 설정하는 경우, 시스템 제어에 다음 사항이 적용됩니다. 자세한 정보는 [IPC 모드](task_definition_parameters.md#task_definition_ipcmode)을 참조하세요.
+ `host` IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 `systemControls`는 지원되지 않습니다.
+ `task` IPC 모드를 사용하는 작업의 경우, IPC 네임스페이스 `systemControls` 값은 작업 내 모든 컨테이너에 적용됩니다.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
```
"systemControls": [
{
"namespace":"string",
"value":"string"
}
]
```
`namespace`
유형: 문자열
필수 여부: 아니요
`value`를 설정할 네임스페이스 커널 파라미터입니다.
유효한 IPC 네임스페이스 값:`"kernel.msgmax" | "kernel.msgmnb" | "kernel.msgmni" | "kernel.sem" | "kernel.shmall" | "kernel.shmmax" | "kernel.shmmni" | "kernel.shm_rmid_forced"` 및 `"fs.mqueue.*"`로 시작하는 `Sysctls`
유효한 네트워크 네임스페이스 값: `"net.*"`로 시작하는 `Sysctls`
`value`
유형: 문자열
필수 여부: 아니요
`namespace`에 지정된 네임스페이스 커널 파라미터의 값입니다.
#### 대화형
`interactive`
유형: 부울
필수 여부: 아니요
이 파라미터가 `true`일 경우 이것을 사용하여 `stdin` 또는 `tty`를 할당해야 하는 컨테이너화된 애플리케이션을 배포할 수 있습니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `OpenStdin` 및 docker run에 대한 `--interactive` 옵션에 매핑됩니다.
기본값은 `false`입니다.
#### 의사 터미널
`pseudoTerminal`
유형: 부울
필수 여부: 아니요
이 파라미터가 `true`일 경우 TTY가 할당됩니다. 이 파라미터는 Docker 컨테이너 생성 명령의 `Tty` 및 docker run에 대한 `--tty` 옵션에 매핑됩니다.
기본값은 `false`입니다.
## Elastic Inference 액셀러레이터 이름(폐기됨)
태스크 정의에 대한 Elastic Inference 액셀러레이터 리소스 요구 사항.
**참고**
Amazon Elastic Inference(EI)는 더 이상 고객에게 제공되지 않습니다.
태스크 정의에는 다음 파라미터가 허용됩니다.
`deviceName`
유형: 문자열
필수 항목 여부: 예
Amazon Elastic Inference 액셀러레이터 디바이스 이름입니다. `deviceName`은 컨테이너 정의에서도 참조해야 합니다. [Elastic Inference accelerator](task_definition_parameters.md#ContainerDefinition-elastic-inference)를 참조하세요.
`deviceType`
유형: 문자열
필수 항목 여부: 예
사용할 Elastic Inference 액셀러레이터입니다.
## 작업 배치 제약
태스크 정의를 등록할 때 Amazon ECS가 태스크를 배치하는 방식을 사용자 지정하는 작업 배치 제약을 제공할 수 있습니다.
제약을 사용하여 가용 영역, 인스턴스 유형 또는 사용자 지정 속성에 따라 작업을 배치할 수 있습니다. 자세한 내용은 [Amazon ECS가 작업에 사용하는 컨테이너 인스턴스 정의](task-placement-constraints.md) 섹션을 참조하세요.
컨테이너 정의에서 다음 파라미터가 허용됩니다.
`expression`
유형: 문자열
필수 여부: 아니요
제약에 적용할 클러스터 쿼리 언어 표현식입니다. 자세한 정보는 [Amazon ECS 작업에 대한 컨테이너 인스턴스를 정의하도록 표현식 생성](cluster-query-language.md) 섹션을 참조하세요.
`type`
유형: 문자열
필수 항목 여부: 예
제약의 유형입니다. `memberOf`를 사용하여 선택을 유효한 후보 그룹으로 제한합니다.
## 프록시 구성
`proxyConfiguration`
유형: [ProxyConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ProxyConfiguration.html) 객체
필수 여부: 아니요
App Mesh 프록시에 대한 구성 세부 정보입니다.
EC2를 사용하는 태스크의 경우 프록시 구성을 사용하려면 컨테이너 인스턴스에 컨테이너 에이전트 버전 1.26.0 이상과 `ecs-init` 패키지의 버전 1.26.0-1 이상이 필요합니다. 컨테이너 인스턴스가 Amazon ECS 최적화 AMI 버전 `20190301` 이상에서 시작된 경우 필요한 버전의 컨테이너 에이전트 및 `ecs-init`가 포함되어 있습니다. 자세한 내용은 [Amazon ECS 최적화 Linux AMI](ecs-optimized_AMI.md) 섹션을 참조하세요.
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
```
"proxyConfiguration": {
"type": "APPMESH",
"containerName": "string",
"properties": [
{
"name": "string",
"value": "string"
}
]
}
```
`type`
유형: 문자열
유효한 값: `APPMESH`
필수 여부: 아니요
프록시 유형입니다. 지원되는 유일한 값은 `APPMESH`입니다.
`containerName`
유형: 문자열
필수 항목 여부: 예
App Mesh 프록시로 사용할 컨테이너의 이름입니다.
`properties`
형식: [KeyValuePair](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KeyValuePair.html) 객체 배열
필수 여부: 아니요
키-값 쌍으로 지정된 CNI(Container Network Interface) 플러그인을 제공하는 네트워크 구성 파라미터 세트입니다.
+ `IgnoredUID` - (필수) 컨테이너 정의의 `user` 파라미터에 정의된 프록시 컨테이너의 사용자 ID(UID)입니다. 프록시가 트래픽을 무시하는 데 사용됩니다. `IgnoredGID`를 지정한 경우 이 필드를 비워둘 수 있습니다.
+ `IgnoredGID` - (필수) 컨테이너 정의의 `user` 파라미터에 정의된 프록시 컨테이너의 그룹 ID(GID)입니다. 프록시가 트래픽을 무시하는 데 사용됩니다. `IgnoredUID`를 지정한 경우 이 필드를 비워둘 수 있습니다.
+ `AppPorts` - (필수) 애플리케이션이 사용하는 포트 목록입니다. 이러한 포트에 대한 네트워크 트래픽은 `ProxyIngressPort` 및 `ProxyEgressPort`로 전달됩니다.
+ `ProxyIngressPort` - (필수) `AppPorts`로 들어오는 트래픽을 보낼 포트를 지정합니다.
+ `ProxyEgressPort` - (필수) `AppPorts`에서 나가는 트래픽을 보낼 포트를 지정합니다.
+ `EgressIgnoredPorts` - (필수) 지정된 포트로 가는 아웃바운드 트래픽은 무시되고 `ProxyEgressPort`로 리디렉션되지 않습니다. 값은 빈 목록일 수 있습니다.
+ `EgressIgnoredIPs` - (필수) 지정된 IP 주소로 가는 아웃바운드 트래픽은 무시되고 `ProxyEgressPort`로 리디렉션되지 않습니다. 값은 빈 목록일 수 있습니다.
`name`
유형: 문자열
필수 여부: 아니요
키-값 쌍의 이름입니다.
`value`
유형: 문자열
필수 여부: 아니요
키-값 쌍의 값입니다.
## 볼륨
작업 정의를 등록할 때 선택적으로 볼륨 목록이 컨테이너 인스턴스의 Docker 대몬에 전달되도록 지정할 수 있습니다. 그러면 동일한 컨테이너 인스턴스에 속하는 다른 컨테이너가 액세스하는 데 전달된 볼륨 목록을 사용할 수 있습니다.
사용할 수 있는 데이터 볼륨의 유형은 다음과 같습니다.
+ Amazon EBS 볼륨 - 데이터 집약적인 컨테이너화된 워크로드에 대해 비용 효율적이며 내구성이 뛰어난 고성능 블록 스토리지를 제공합니다. 독립 실행형 작업을 실행하거나 서비스를 생성 또는 업데이트할 때 Amazon ECS 작업당 1개의 Amazon EBS 볼륨을 연결할 수 있습니다. Amazon EBS 볼륨은 Linux 태스크에 지원됩니다. 자세한 내용은 [Amazon ECS에서 Amazon EBS 볼륨 사용](ebs-volumes.md) 섹션을 참조하세요.
+ Amazon EFS 볼륨 — Amazon ECS 태스크에 사용할 수 있는 간단하고 영구적인 확장형 파일 스토리지를 제공합니다. Amazon EFS를 사용하면 스토리지 용량이 탄력적입니다. 파일을 추가 및 제거하면 스토리지 용량이 자동으로 확장 및 축소됩니다. 애플리케이션에서 스토리지가 필요할 때 필요한 만큼 확보할 수 있습니다. Amazon EFS 볼륨이 지원됩니다. 자세한 내용은 [Amazon ECS에서 Amazon EFS 볼륨 사용](efs-volumes.md) 섹션을 참조하세요.
+ FSx for Windows File Server 볼륨 - 완전 관리형 Microsoft Windows 파일 서버를 제공합니다. 이러한 파일 서버는 Windows 파일 시스템으로 지원됩니다. FSx for Windows File Server와 Amazon ECS를 함께 사용하면 영구적이고 분산, 공유된 고정 파일 스토리지로 Windows 태스크를 프로비저닝할 수 있습니다. 자세한 정보는 [Amazon ECS에서 FSx for Windows File Server 볼륨 사용](wfsx-volumes.md)을 참조하세요.
Fargate의 Windows 컨테이너는 이 옵션을 지원하지 않습니다.
+ Docker 볼륨 – 호스트 Amazon EC2 인스턴스의 `/var/lib/docker/volumes` 아래에 생성되는 Docker 관리형 볼륨입니다. Docker 볼륨 드라이버(플러그인이라고도 함)는 볼륨을 Amazon EBS와 같은 외부 스토리지 시스템과 통합하는 데 사용됩니다. 내장형 `local` 볼륨 드라이버 또는 타사 볼륨 드라이버를 사용할 수 있습니다. Docker 볼륨은 Amazon EC2 인스턴스에서 작업을 실행하는 경우에만 지원됩니다. Windows 컨테이너는 `local` 드라이버의 사용만 지원합니다. Docker 볼륨을 사용하려면 태스크 정의에서 `dockerVolumeConfiguration`을 지정합니다.
+ 바인드 탑재 – 컨테이너에 탑재된 호스트 컴퓨터의 파일 또는 디렉터리입니다. 바인드 탑재 호스트 볼륨이 지원됩니다. 바인드 탑재 호스트 볼륨을 사용하려면 태스크 정의에서 `host`와 `sourcePath`(옵션) 값을 지정합니다.
자세한 내용은 [Amazon ECS 작업에 대한 스토리지 옵션](using_data_volumes.md) 섹션을 참조하세요.
컨테이너 정의에서 다음 파라미터가 허용됩니다.
`name`
유형: 문자열
필수 여부: 아니요
볼륨의 이름입니다. 최대 255자의 문자(대문자 및 소문자), 숫자, 하이(`-`) 및 밑줄(`_`)이 허용됩니다. 이 이름은 컨테이너 정의 `mountPoints` 객체의 `sourceVolume` 파라미터에서 참조됩니다.
`host`
필수 여부: 아니요
`host` 파라미터는 바인드 탑재의 수명 주기를 태스크가 아니라 호스트 Amazon EC2 인스턴스와 연결하는 데 사용합니다. `host` 파라미터가 비어 있으면 Docker 대몬이 데이터 볼륨의 호스트 경로를 할당하지만 해당 볼륨과 연결된 컨테이너가 실행을 중지한 후 데이터 유지가 보장되지 않습니다.
Windows 컨테이너는 전체 디렉터리를 동일한 드라이브에 `$env:ProgramData`로 마운트할 수 있습니다.
`sourcePath` 파라미터는 Amazon EC2 인스턴스 또는 Amazon ECS 관리형 인스턴스에 호스팅된 태스크를 사용하는 경우에만 지원됩니다.
`sourcePath`
유형: 문자열
필수 여부: 아니요
`host` 파라미터가 사용되는 경우 `sourcePath`를 지정하여 컨테이너에 제시되는 호스트 Amazon EC2 인스턴스 상의 경로를 선언합니다. 이 파라미터가 비어 있으면 Docker 대몬이 사용자 대신 호스트 경로를 할당합니다. `host` 파라미터에 `sourcePath` 파일 위치가 들어 있으면, 사용자가 수동으로 삭제하지 않는 한 데이터 볼륨이 호스트 Amazon EC2 인스턴스 상에 지정된 위치를 유지합니다. `sourcePath` 값이 호스트 Amazon EC2 인스턴스에 없을 경우 Docker 대몬이 해당 경로를 생성합니다. 해당 위치가 있을 경우 소스 경로 폴더의 콘텐츠를 내보냅니다.
`configuredAtLaunch`
유형: 부울
필수 여부: 아니요
시작 시 볼륨을 구성할 수 있는지 여부를 지정합니다. `true`로 설정하면 독립 실행형 작업을 실행하거나 서비스를 생성 또는 업데이트할 때 볼륨을 구성할 수 있습니다. `true`로 설정하면 작업 정의에서 다른 볼륨 구성을 제공할 수 없습니다. 작업에 연결하도록 Amazon EBS 볼륨을 구성하려면 이 파라미터를 `true`로 설정해야 합니다. `configuredAtLaunch`를 `true`로 설정하고 볼륨 구성을 시작 단계로 연기하면 볼륨 유형이나 특정 볼륨 설정으로 제한되지 않는 작업 정의를 생성할 수 있습니다. 그러면 여러 실행 환경에서 작업 정의를 재사용할 수 있습니다. 자세한 내용은 [Amazon EBS volumes](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ebs-volumes.html)를 참조하세요.
`dockerVolumeConfiguration`
유형: [DockerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DockerVolumeConfiguration.html) 객체
필수 여부: 아니요
이 파라미터는 Docker 볼륨을 사용할 때 지정됩니다. Docker 볼륨은 EC2 인스턴스에서 작업을 실행하는 경우에만 지원됩니다. Windows 컨테이너는 `local` 드라이버의 사용만 지원합니다. 바인드 탑재를 사용하려면 대신에 `host`를 지정하세요.
`scope`
유형: 문자열
유효한 값: `task` \$1 `shared`
필수 여부: 아니요
수명 주기를 결정하는 Docker 볼륨의 범위입니다. 범위가 `task`로 지정된 Docker 볼륨은 태스크가 시작될 때 자동으로 프로비저닝되고, 태스크가 중단되면 삭제됩니다. 범위가 `shared`로 지정된 Docker 볼륨은 태스크 중단 후에도 유지됩니다.
`autoprovision`
유형: Boolean
기본값: `false`
필수 여부: 아니요
이 값이 `true`인 경우 도커 볼륨이 아직 없으면 도커 볼륨이 생성됩니다. 이 필드는 `scope`가 `shared`인 경우에만 사용됩니다. `scope`가 `task`인 경우 이 파라미터를 생략해야 합니다.
`driver`
유형: 문자열
필수 여부: 아니요
사용할 Docker 볼륨 드라이버입니다. Docker에서 제공하는 드라이버 이름이 작업 배치에 사용되므로 드라이버 값과 이 이름이 일치해야 합니다. Docker 플러그인 CLI를 사용하여 드라이버를 설치했다면 `docker plugin ls`를 사용하여 컨테이너 인스턴스에서 드라이버 이름을 검색합니다. 다른 방법을 사용하여 드라이버를 설치했다면 Docker 플러그인 검색을 사용하여 드라이버 이름을 검색합니다.
`driverOpts`
유형: 문자열
필수 여부: 아니요
전달할 Docker 드라이버에 특정한 옵션 맵입니다. 이 파라미터는 Docker의 볼륨 생성의 `DriverOpts`에 매핑됩니다.
`labels`
유형: 문자열
필수 여부: 아니요
Docker 볼륨에 추가할 사용자 지정 메타데이터입니다.
`efsVolumeConfiguration`
유형: [EFSVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSVolumeConfiguration.html) 객체
필수 여부: 아니요
이 파라미터는 Amazon EFS 볼륨을 사용할 때 지정됩니다.
`fileSystemId`
유형: 문자열
필수 항목 여부: 예
사용할 Amazon EFS 파일 시스템 ID입니다.
`rootDirectory`
유형: 문자열
필수 여부: 아니요
호스트 내의 루트 디렉터리로 탑재할 Amazon EFS 파일 시스템 내 디렉터리입니다. 이 파라미터가 생략되면 Amazon EFS 볼륨의 루트가 사용됩니다. `/`를 지정하면 이 파라미터를 생략하는 것과 동일한 효과가 있습니다.
`authorizationConfig`에 EFS 액세스 포인트가 지정된 경우 루트 디렉터리 파라미터를 생략하거나 `/`로 설정해야 합니다. 그러면 EFS 액세스 포인트에 설정된 경로가 적용됩니다.
`transitEncryption`
유형: 문자열
유효한 값: `ENABLED` \$1 `DISABLED`
필수 여부: 아니요
Amazon ECS 호스트와 Amazon EFS 서버 간에 전송 중인 Amazon EFS 데이터에 대해 암호화를 사용 설정할지 여부를 지정합니다. Amazon EFS IAM 권한 부여를 사용하는 경우 전송 중 데이터 암호화를 사용 설정해야 합니다. 이 파라미터가 누락되면 `DISABLED`의 기본값이 사용됩니다. 자세한 내용은 *Amazon Elastic File System 사용 설명서*의 [전송 중 데이터 암호화(Encrypting Data in Transit)](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)를 참조하세요.
`transitEncryptionPort`
유형: 정수
필수 여부: 아니요
Amazon ECS 호스트와 Amazon EFS 서버 간에 암호화된 데이터를 전송할 때 사용할 포트입니다. 전송 중 데이터 암호화 포트를 지정하지 않으면 작업에서는 Amazon EFS 탑재 헬퍼가 사용하는 포트 선택 전략을 사용합니다. 자세한 내용은 *Amazon Elastic File System 사용 설명서*의 [EFS 탑재 헬퍼](https://docs.aws.amazon.com/efs/latest/ug/efs-mount-helper.html)를 참조하세요.
`authorizationConfig`
유형: [EFSAuthorizationConfig](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSAuthorizationConfig.html) 객체
필수 여부: 아니요
Amazon EFS 파일 시스템에 대한 권한 부여 구성 세부 정보입니다.
`accessPointId`
유형: 문자열
필수 여부: 아니요
사용할 액세스 포인트 ID입니다. 액세스 포인트가 지정된 경우 `efsVolumeConfiguration`에서 루트 디렉터리 값을 생략하거나 `/`로 설정해야 합니다. 그러면 EFS 액세스 포인트에 설정된 경로가 적용됩니다. 액세스 포인트를 사용하는 경우 `EFSVolumeConfiguration`에서 전송 중 데이터 암호화를 활성화해야 합니다. 자세한 내용은 *Amazon Elastic File System 사용 설명서*의 [Amazon EFS 액세스 포인트 태스크](https://docs.aws.amazon.com/efs/latest/ug/efs-access-points.html)를 참조세요.
`iam`
유형: 문자열
유효한 값: `ENABLED` \$1 `DISABLED`
필수 여부: 아니요
Amazon EFS 파일 시스템을 탑재할 때 작업 정의에 정의된 Amazon ECS 작업 IAM 역할을 사용할지 여부를 지정합니다. 활성화된 경우 `EFSVolumeConfiguration`에서 전송 중 데이터 암호화를 활성화해야 합니다. 이 파라미터가 누락되면 `DISABLED`의 기본값이 사용됩니다. 자세한 정보는 [태스크의 IAM 역할](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)을 참조하세요.
`FSxWindowsFileServerVolumeConfiguration`
유형: [FSxWindowsFileServerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FSxWindowsFileServerVolumeConfiguration.html) 객체
필수 여부: 예
이 파라미터는 작업을 저장할 [Amazon FSx for Windows File Server](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html) 파일 시스템을 사용할 때 지정됩니다.
`fileSystemId`
유형: 문자열
필수 항목 여부: 예
사용할 FSx for Windows File Server 파일 시스템 ID입니다.
`rootDirectory`
유형: 문자열
필수 항목 여부: 예
호스트 내의 루트 디렉터리로 탑재할 FSx for Windows File Server 파일 시스템 내 디렉터리입니다.
`authorizationConfig`
`credentialsParameter`
유형: 문자열
필수 항목 여부: 예
권한 부여 자격 증명 옵션입니다.
**옵션:**
+ [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 보안 암호의 Amazon 리소스 이름(ARN)입니다.
+ [AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html) 파라미터의 ARN입니다.
`domain`
유형: 문자열
필수 항목 여부: 예
셀프 호스팅된 EC2 Active Directory 또는 [AWS Directory Service for Microsoft Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/directory_microsoft_ad.html)(AWS Managed Microsoft AD) 디렉터리에서 호스팅하는 정규화된 도메인 이름입니다.
## Tags
태스크 정의를 등록할 때 태스크 정의에 적용되는 메타데이터 태그를 선택적으로 지정할 수 있습니다. 태그는 태스크 정의를 분류하고 정리하는 데 도움을 줍니다. 각 태그는 키와 값(선택사항)으로 구성됩니다. 두 가지를 모두 정의합니다. 자세한 정보는 [Amazon ECS 리소스 태그 지정](ecs-using-tags.md)을 참조하세요.
**중요**
개인 식별 정보나 기타 기밀 정보 또는 민감한 정보를 태그에 추가하지 않습니다. 청구를 비롯한 여러 AWS 서비스에서 태그에 액세스할 수 있습니다. 태그는 개인 데이터나 민감한 데이터에 사용하기 위한 것이 아닙니다.
태그 개체에서 허용되는 파라미터는 다음과 같습니다.
`key`
유형: 문자열
필수 여부: 아니요
하나의 태그를 구성하는 키-값 쌍의 일부분입니다. 키는 더 구체적인 태그 값에 대해 범주와 같은 역할을 하는 일반적인 레이블입니다.
`value`
유형: 문자열
필수 여부: 아니요
하나의 태그를 구성하는 키-값 쌍의 선택적 부분입니다. 하나의 값은 태그 범주(키) 내에서 서술자 역할을 수행합니다.
## 기타 태스크 정의 파라미터
다음의 태스크 정의 파라미터는 **JSON을 통한 구성(Configure via JSON)** 옵션을 사용하여 Amazon ECS 콘솔에 태스크 정의를 등록할 때 사용할 수 있습니다. 자세한 내용은 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 섹션을 참조하세요.
**Topics**
+ [IPC 모드](#task_definition_ipcmode_ec2)
+ [PID 모드](#task_definition_pidmode_ec2)
+ [결함 주입](#task_definition_faultInjection_ec2)
### IPC 모드
`ipcMode`
유형: 문자열
필수 여부: 아니요
해당 태스크의 컨테이너에 사용할 IPC 리소스 네임스페이스입니다. 유효한 값은 `host`, `task` 또는 `none`입니다. `host`를 지정하면 동일한 컨테이너 인스턴스에서 `host` IPC 모드를 지정한 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 호스트 Amazon EC2 인스턴스와 공유합니다. `task`를 지정하면 지정된 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 공유합니다. `none`이 지정된 경우, 태스크 컨테이너 내에 있는 IPC 리소스는 프라이빗이며, 태스크 또는 컨테이너 인스턴스의 다른 컨테이너와 공유되지 않습니다. 값을 지정하지 않을 경우, IPC 리소스 네임스페이스 공유는 컨테이너 인스턴스의 Docker 대몬 설정에 따라 달라집니다.
`host` IPC 모드를 사용하는 경우, 원치 않는 IPC 네임스페이스 노출이 발생할 위험이 커집니다.
해당 태스크 내 컨테이너에 대해 `systemControls`를 사용하여 네임스페이스가 있는 커널 파라미터를 설정하는 경우, IPC 리소스 네임스페이스에 다음 사항이 적용됩니다.
+ `host` IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 관련 `systemControls`는 지원되지 않습니다.
+ `task` IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 관련 `systemControls`가 태스크 내 모든 컨테이너에 적용됩니다.
### PID 모드
`pidMode`
유형: 문자열
유효한 값: `host` \$1 `task`
필수 여부: 아니요
해당 태스크의 컨테이너에 사용할 프로세스 네임스페이스입니다. 유효한 값은 `host` 또는 `task`입니다. 예를 들어 사이드카 모니터링에서는 동일한 작업에서 실행 중인 다른 컨테이너에 대한 정보에 액세스하기 위해 `pidMode`가 필요할 수 있습니다.
`host`를 지정하면 동일한 컨테이너 인스턴스에서 `host` PID 모드를 지정한 태스크 내 모든 컨테이너가 동일한 프로세스 네임스페이스를 호스트 Amazon EC2 인스턴스와 공유합니다.
`task`을 지정하면 지정된 태스크 내 모든 컨테이너가 동일한 프로세스 네임스페이스를 공유합니다.
값을 지정하지 않을 경우, 기본값은 각 컨테이너의 프라이빗 네임스페이스입니다.
`host` PID 모드를 사용하는 경우, 원치 않는 프로세스 네임스페이스 노출이 발생할 위험이 커집니다.
**참고**
이 파라미터는 Windows 컨테이너에서 지원되지 않습니다.
### 결함 주입
`enableFaultInjection`
유형: Boolean
유효한 값: `true` \$1 `false`
필수 여부: 아니요
이 파라미터가 `true`로 설정된 경우 작업의 페이로드에서 Amazon ECS는 작업 컨테이너의 결함 주입 요청을 수락합니다. 이 파라미터는 기본적으로 `false`로 설정되어 있습니다.
# Amazon ECS 태스크 정의 템플릿
빈 태스크 정의 템플릿은 아래와 같습니다. 이 템플릿을 사용하여 태스크 정의를 생성한 다음 AWS CLI `--cli-input-json` 옵션을 사용하여 콘솔 JSON 입력 영역으로 붙여 넣거나 파일로 저장하고 사용할 수 있습니다. 자세한 내용은 [Fargate에 대한 Amazon ECS 태스크 정의 파라미터](task_definition_parameters.md) 섹션을 참조하세요.
**EC2 템플릿**
```
{
"family": "",
"taskRoleArn": "",
"executionRoleArn": "",
"networkMode": "none",
"containerDefinitions": [
{
"name": "",
"image": "",
"repositoryCredentials": {
"credentialsParameter": ""
},
"cpu": 0,
"memory": 0,
"memoryReservation": 0,
"links": [""],
"portMappings": [
{
"containerPort": 0,
"hostPort": 0,
"protocol": "tcp"
}
],
"restartPolicy": {
"enabled": true,
"ignoredExitCodes": [0],
"restartAttemptPeriod": 180
},
"essential": true,
"entryPoint": [""],
"command": [""],
"environment": [
{
"name": "",
"value": ""
}
],
"environmentFiles": [
{
"value": "",
"type": "s3"
}
],
"mountPoints": [
{
"sourceVolume": "",
"containerPath": "",
"readOnly": true
}
],
"volumesFrom": [
{
"sourceContainer": "",
"readOnly": true
}
],
"linuxParameters": {
"capabilities": {
"add": [""],
"drop": [""]
},
"devices": [
{
"hostPath": "",
"containerPath": "",
"permissions": ["read"]
}
],
"initProcessEnabled": true,
"sharedMemorySize": 0,
"tmpfs": [
{
"containerPath": "",
"size": 0,
"mountOptions": [""]
}
],
"maxSwap": 0,
"swappiness": 0
},
"secrets": [
{
"name": "",
"valueFrom": ""
}
],
"dependsOn": [
{
"containerName": "",
"condition": "COMPLETE"
}
],
"startTimeout": 0,
"stopTimeout": 0,
"hostname": "",
"user": "",
"workingDirectory": "",
"disableNetworking": true,
"privileged": true,
"readonlyRootFilesystem": true,
"dnsServers": [""],
"dnsSearchDomains": [""],
"extraHosts": [
{
"hostname": "",
"ipAddress": ""
}
],
"dockerSecurityOptions": [""],
"interactive": true,
"pseudoTerminal": true,
"dockerLabels": {
"KeyName": ""
},
"ulimits": [
{
"name": "nofile",
"softLimit": 0,
"hardLimit": 0
}
],
"logConfiguration": {
"logDriver": "splunk",
"options": {
"KeyName": ""
},
"secretOptions": [
{
"name": "",
"valueFrom": ""
}
]
},
"healthCheck": {
"command": [""],
"interval": 0,
"timeout": 0,
"retries": 0,
"startPeriod": 0
},
"systemControls": [
{
"namespace": "",
"value": ""
}
],
"resourceRequirements": [
{
"value": "",
"type": "InferenceAccelerator"
}
],
"firelensConfiguration": {
"type": "fluentbit",
"options": {
"KeyName": ""
}
}
}
],
"volumes": [
{
"name": "",
"host": {
"sourcePath": ""
},
"configuredAtLaunch": true,
"dockerVolumeConfiguration": {
"scope": "shared",
"autoprovision": true,
"driver": "",
"driverOpts": {
"KeyName": ""
},
"labels": {
"KeyName": ""
}
},
"efsVolumeConfiguration": {
"fileSystemId": "",
"rootDirectory": "",
"transitEncryption": "DISABLED",
"transitEncryptionPort": 0,
"authorizationConfig": {
"accessPointId": "",
"iam": "ENABLED"
}
},
"fsxWindowsFileServerVolumeConfiguration": {
"fileSystemId": "",
"rootDirectory": "",
"authorizationConfig": {
"credentialsParameter": "",
"domain": ""
}
}
}
],
"placementConstraints": [
{
"type": "memberOf",
"expression": ""
}
],
"requiresCompatibilities": ["EC2"],
"cpu": "",
"memory": "",
"tags": [
{
"key": "",
"value": ""
}
],
"pidMode": "task",
"ipcMode": "task",
"proxyConfiguration": {
"type": "APPMESH",
"containerName": "",
"properties": [
{
"name": "",
"value": ""
}
]
},
"inferenceAccelerators": [
{
"deviceName": "",
"deviceType": ""
}
],
"ephemeralStorage": {
"sizeInGiB": 0
},
"runtimePlatform": {
"cpuArchitecture": "X86_64",
"operatingSystemFamily": "WINDOWS_SERVER_20H2_CORE"
}
}
```
**Fargate 템플릿**
**중요**
Fargate의 경우 다음 값 중 하나와 함께 `operatingSystemFamily` 파라미터를 포함해야 합니다.
`LINUX`
`WINDOWS_SERVER_2019_FULL`
`WINDOWS_SERVER_2019_CORE`
`WINDOWS_SERVER_2022_FULL`
`WINDOWS_SERVER_2022_CORE`
```
{
"family": "",
"runtimePlatform": {"operatingSystemFamily": ""},
"taskRoleArn": "",
"executionRoleArn": "",
"networkMode": "awsvpc",
"platformFamily": "",
"containerDefinitions": [
{
"name": "",
"image": "",
"repositoryCredentials": {"credentialsParameter": ""},
"cpu": 0,
"memory": 0,
"memoryReservation": 0,
"links": [""],
"portMappings": [
{
"containerPort": 0,
"hostPort": 0,
"protocol": "tcp"
}
],
"essential": true,
"entryPoint": [""],
"command": [""],
"environment": [
{
"name": "",
"value": ""
}
],
"environmentFiles": [
{
"value": "",
"type": "s3"
}
],
"mountPoints": [
{
"sourceVolume": "",
"containerPath": "",
"readOnly": true
}
],
"volumesFrom": [
{
"sourceContainer": "",
"readOnly": true
}
],
"linuxParameters": {
"capabilities": {
"add": [""],
"drop": [""]
},
"devices": [
{
"hostPath": "",
"containerPath": "",
"permissions": ["read"]
}
],
"initProcessEnabled": true,
"sharedMemorySize": 0,
"tmpfs": [
{
"containerPath": "",
"size": 0,
"mountOptions": [""]
}
],
"maxSwap": 0,
"swappiness": 0
},
"secrets": [
{
"name": "",
"valueFrom": ""
}
],
"dependsOn": [
{
"containerName": "",
"condition": "HEALTHY"
}
],
"startTimeout": 0,
"stopTimeout": 0,
"hostname": "",
"user": "",
"workingDirectory": "",
"disableNetworking": true,
"privileged": true,
"readonlyRootFilesystem": true,
"dnsServers": [""],
"dnsSearchDomains": [""],
"extraHosts": [
{
"hostname": "",
"ipAddress": ""
}
],
"dockerSecurityOptions": [""],
"interactive": true,
"pseudoTerminal": true,
"dockerLabels": {"KeyName": ""},
"ulimits": [
{
"name": "msgqueue",
"softLimit": 0,
"hardLimit": 0
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {"KeyName": ""},
"secretOptions": [
{
"name": "",
"valueFrom": ""
}
]
},
"healthCheck": {
"command": [""],
"interval": 0,
"timeout": 0,
"retries": 0,
"startPeriod": 0
},
"systemControls": [
{
"namespace": "",
"value": ""
}
],
"resourceRequirements": [
{
"value": "",
"type": "GPU"
}
],
"firelensConfiguration": {
"type": "fluentd",
"options": {"KeyName": ""}
}
}
],
"volumes": [
{
"name": "",
"host": {"sourcePath": ""},
"configuredAtLaunch":true,
"dockerVolumeConfiguration": {
"scope": "task",
"autoprovision": true,
"driver": "",
"driverOpts": {"KeyName": ""},
"labels": {"KeyName": ""}
},
"efsVolumeConfiguration": {
"fileSystemId": "",
"rootDirectory": "",
"transitEncryption": "ENABLED",
"transitEncryptionPort": 0,
"authorizationConfig": {
"accessPointId": "",
"iam": "ENABLED"
}
}
}
],
"requiresCompatibilities": ["FARGATE"],
"cpu": "",
"memory": "",
"tags": [
{
"key": "",
"value": ""
}
],
"ephemeralStorage": {"sizeInGiB": 0},
"pidMode": "task",
"ipcMode": "none",
"proxyConfiguration": {
"type": "APPMESH",
"containerName": "",
"properties": [
{
"name": "",
"value": ""
}
]
},
"inferenceAccelerators": [
{
"deviceName": "",
"deviceType": ""
}
]
}
```
다음 AWS CLI 명령을 사용하여 이 태스크 정의 템플릿을 생성할 수 있습니다.
```
aws ecs register-task-definition --generate-cli-skeleton
```
# Amazon ECS 작업 정의 예제
예제와 코드 조각을 복사하여 고유한 작업 정의를 생성할 수 있습니다.
예제를 복사한 다음 클래식 콘솔에서 **JSON을 통한 구성** 옵션을 사용할 때 붙여넣을 수 있습니다. 계정 ID 사용과 같은 예제를 사용자 지정해야 합니다. 이 코드 조각을 작업 정의 JSON에 포함할 수 있습니다. 자세한 내용은 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 및 [Fargate에 대한 Amazon ECS 태스크 정의 파라미터](task_definition_parameters.md)(을)를 참조하세요.
태스크 정의에 대한 추가 예제는 GitHub의 [AWS 샘플 태스크 정의](https://github.com/aws-samples/aws-containers-task-definitions)를 참조하세요.
**Topics**
+ [웹 서버](#example_task_definition-webserver)
+ [`splunk` 로그 드라이버](#example_task_definition-splunk)
+ [`fluentd` 로그 드라이버](#example_task_definition-fluentd)
+ [`gelf` 로그 드라이버](#example_task_definition-gelf)
+ [외부 인스턴스의 워크로드](#ecs-anywhere-runtask)
+ [Amazon ECR 이미지 및 작업 정의 IAM 역할](#example_task_definition-iam)
+ [명령의 진입점](#example_task_definition-ping)
+ [컨테이너 종속성](#example_task_definition-containerdependency)
+ [작업 정의의 볼륨](#volume_sample_task_defs)
+ [Windows 샘플 태스크 정의](#windows_sample_task_defs)
## 웹 서버
다음은 웹 서버를 설정하는 Fargate에서 Linux 컨테이너를 사용하는 태스크 정의 예제입니다.
```
{
"containerDefinitions": [
{
"command": [
"/bin/sh -c \"echo ' Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
' > /usr/local/apache2/htdocs/index.html && httpd-foreground\""
],
"entryPoint": [
"sh",
"-c"
],
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:2.4",
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group" : "/ecs/fargate-task-definition",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
},
"name": "sample-fargate-app",
"portMappings": [
{
"containerPort": 80,
"hostPort": 80,
"protocol": "tcp"
}
]
}
],
"cpu": "256",
"executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
"family": "fargate-task-definition",
"memory": "512",
"networkMode": "awsvpc",
"runtimePlatform": {
"operatingSystemFamily": "LINUX"
},
"requiresCompatibilities": [
"FARGATE"
]
}
```
다음은 웹 서버를 설정하는 Fargate에서 Windows 컨테이너를 사용하는 태스크 정의 예제입니다.
```
{
"containerDefinitions": [
{
"command": ["New-Item -Path C:\\inetpub\\wwwroot\\index.html -Type file -Value ' Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
'; C:\\ServiceMonitor.exe w3svc"],
"entryPoint": [
"powershell",
"-Command"
],
"essential": true,
"cpu": 2048,
"memory": 4096,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"name": "sample_windows_app",
"portMappings": [
{
"hostPort": 80,
"containerPort": 80,
"protocol": "tcp"
}
]
}
],
"memory": "4096",
"cpu": "2048",
"networkMode": "awsvpc",
"family": "windows-simple-iis-2019-core",
"executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
"runtimePlatform": {"operatingSystemFamily": "WINDOWS_SERVER_2019_CORE"},
"requiresCompatibilities": ["FARGATE"]
}
```
## `splunk` 로그 드라이버
다음 코드 조각에서는 로그를 원격 서비스로 보내는 작업 정의에서 `splunk` 로그 드라이버를 사용하는 방법을 보여줍니다. Splunk 토큰 파라미터는 민감한 데이터로 취급될 수 있으므로 암호 옵션으로 지정됩니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
```
"containerDefinitions": [{
"logConfiguration": {
"logDriver": "splunk",
"options": {
"splunk-url": "https://cloud.splunk.com:8080",
"tag": "tag_name",
},
"secretOptions": [{
"name": "splunk-token",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:splunk-token-KnrBkD"
}],
```
## `fluentd` 로그 드라이버
다음 코드 조각에서는 로그를 원격 서비스로 보내는 작업 정의에서 `fluentd` 로그 드라이버를 사용하는 방법을 보여줍니다. `fluentd-address` 값은 민감한 데이터로 취급될 수 있으므로 암호 옵션으로 지정됩니다. 자세한 내용은 [Amazon ECS 컨테이너로 민감한 데이터 전달](specifying-sensitive-data.md) 섹션을 참조하세요.
```
"containerDefinitions": [{
"logConfiguration": {
"logDriver": "fluentd",
"options": {
"tag": "fluentd demo"
},
"secretOptions": [{
"name": "fluentd-address",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:fluentd-address-KnrBkD"
}]
},
"entryPoint": [],
"portMappings": [{
"hostPort": 80,
"protocol": "tcp",
"containerPort": 80
},
{
"hostPort": 24224,
"protocol": "tcp",
"containerPort": 24224
}]
}],
```
## `gelf` 로그 드라이버
다음 코드 조각에서는 Gelf 로그를 입력으로 사용해 Logstash를 실행 중인 원격 호스트로 로그를 보내는 작업 정의에서 `gelf` 로그 드라이버를 사용하는 방법을 보여줍니다. 자세한 내용은 [logConfiguration](task_definition_parameters.md#ContainerDefinition-logConfiguration) 섹션을 참조하세요.
```
"containerDefinitions": [{
"logConfiguration": {
"logDriver": "gelf",
"options": {
"gelf-address": "udp://logstash-service-address:5000",
"tag": "gelf task demo"
}
},
"entryPoint": [],
"portMappings": [{
"hostPort": 5000,
"protocol": "udp",
"containerPort": 5000
},
{
"hostPort": 5000,
"protocol": "tcp",
"containerPort": 5000
}
]
}],
```
## 외부 인스턴스의 워크로드
Amazon ECS 태스크 정의를 등록할 때는 `requiresCompatibilities` 파라미터를 사용하고 태스크 정의가 호환되는지 확인하는 `EXTERNAL`을 지정하여 외부 인스턴스에서 Amazon ECS 워크로드를 실행할 때 사용합니다. 콘솔을 사용하여 작업 정의를 등록하는 경우 JSON 편집기를 사용해야 합니다. 자세한 내용은 [콘솔을 사용하여 Amazon ECS 작업 정의 생성](create-task-definition.md) 섹션을 참조하세요.
**중요**
태스크에 태스크 실행 IAM 역할이 필요한 경우 해당 역할이 태스크 정의에 지정되어 있는지 확인합니다.
워크로드를 배포할 때 서비스를 생성하거나 독립 실행형 태스크를 실행하는 경우 `EXTERNAL` 시작 유형을 사용합니다.
다음은 예제 태스크 정의입니다.
------
#### [ Linux ]
```
{
"requiresCompatibilities": [
"EXTERNAL"
],
"containerDefinitions": [{
"name": "nginx",
"image": "public.ecr.aws/nginx/nginx:latest",
"memory": 256,
"cpu": 256,
"essential": true,
"portMappings": [{
"containerPort": 80,
"hostPort": 8080,
"protocol": "tcp"
}]
}],
"networkMode": "bridge",
"family": "nginx"
}
```
------
#### [ Windows ]
```
{
"requiresCompatibilities": [
"EXTERNAL"
],
"containerDefinitions": [{
"name": "windows-container",
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"memory": 256,
"cpu": 512,
"essential": true,
"portMappings": [{
"containerPort": 80,
"hostPort": 8080,
"protocol": "tcp"
}]
}],
"networkMode": "bridge",
"family": "windows-container"
}
```
------
## Amazon ECR 이미지 및 작업 정의 IAM 역할
다음 코드 조각에서는 `123456789012.dkr.ecr.us-west-2.amazonaws.com` 레지스트리의 `v1` 태그를 포함하는 `aws-nodejs-sample`이라는 Amazon ECR 이미지를 사용합니다. 이 태스크의 컨테이너는 IAM 역할로부터 `arn:aws:iam::123456789012:role/AmazonECSTaskS3BucketRole` 권한을 상속합니다. 자세한 내용은 [Amazon ECS 작업 IAM 역할](task-iam-roles.md) 섹션을 참조하세요.
```
{
"containerDefinitions": [
{
"name": "sample-app",
"image": "123456789012.dkr.ecr.us-west-2.amazonaws.com/aws-nodejs-sample:v1",
"memory": 200,
"cpu": 10,
"essential": true
}
],
"family": "example_task_3",
"taskRoleArn": "arn:aws:iam::123456789012:role/AmazonECSTaskS3BucketRole"
}
```
## 명령의 진입점
다음 코드 조각에서는 진입점과 명령 인수를 사용하는 Docker 컨테이너용 구문을 보여줍니다. 이 컨테이너는 `example.com`을 네 번 ping한 후 종료합니다.
```
{
"containerDefinitions": [
{
"memory": 32,
"essential": true,
"entryPoint": ["ping"],
"name": "alpine_ping",
"readonlyRootFilesystem": true,
"image": "alpine:3.4",
"command": [
"-c",
"4",
"example.com"
],
"cpu": 16
}
],
"family": "example_task_2"
}
```
## 컨테이너 종속성
이 코드 조각에서는 컨테이너 종속성이 지정된 여러 컨테이너가 있는 작업 정의의 구문을 보여줍니다. 다음 태스크 정의에서 `envoy` 컨테이너를 시작하기 전에 `app` 컨테이너가 필요한 컨테이너 상태 확인 파라미터에 의해 정상 상태에 도달해야 합니다. 자세한 내용은 [컨테이너 종속성](task_definition_parameters.md#container_definition_dependson) 섹션을 참조하세요.
```
{
"family": "appmesh-gateway",
"runtimePlatform": {
"operatingSystemFamily": "LINUX"
},
"proxyConfiguration":{
"type": "APPMESH",
"containerName": "envoy",
"properties": [
{
"name": "IgnoredUID",
"value": "1337"
},
{
"name": "ProxyIngressPort",
"value": "15000"
},
{
"name": "ProxyEgressPort",
"value": "15001"
},
{
"name": "AppPorts",
"value": "9080"
},
{
"name": "EgressIgnoredIPs",
"value": "169.254.170.2,169.254.169.254"
}
]
},
"containerDefinitions": [
{
"name": "app",
"image": "application_image",
"portMappings": [
{
"containerPort": 9080,
"hostPort": 9080,
"protocol": "tcp"
}
],
"essential": true,
"dependsOn": [
{
"containerName": "envoy",
"condition": "HEALTHY"
}
]
},
{
"name": "envoy",
"image": "840364872350.dkr.ecr.region-code.amazonaws.com/aws-appmesh-envoy:v1.15.1.0-prod",
"essential": true,
"environment": [
{
"name": "APPMESH_VIRTUAL_NODE_NAME",
"value": "mesh/meshName/virtualNode/virtualNodeName"
},
{
"name": "ENVOY_LOG_LEVEL",
"value": "info"
}
],
"healthCheck": {
"command": [
"CMD-SHELL",
"echo hello"
],
"interval": 5,
"timeout": 2,
"retries": 3
}
}
],
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
"networkMode": "awsvpc"
}
```
## 작업 정의의 볼륨
다음을 사용하여 작업에서 볼륨을 지정하는 방법을 이해합니다.
+ Amazon EBS 볼륨을 구성하는 방법에 대한 자세한 내용은 [Amazon ECS 배포 시 Amazon EBS 볼륨 구성 지정](configure-ebs-volume.md) 섹션을 참조하세요.
+ Amazon EFS 볼륨을 구성하는 방법에 대한 자세한 내용은 [콘솔을 사용하여 Amazon ECS에 대한 Amazon EFS 파일 시스템 구성](tutorial-efs-volumes.md) 섹션을 참조하세요.
+ FSx for Windows File Server 볼륨을 구성하는 방법에 대한 자세한 내용은 [Amazon ECS에 대한 FSx for Windows File Server 파일 시스템을 구성하는 방법 알아보기](tutorial-wfsx-volumes.md) 섹션을 참조하세요.
+ Docker 볼륨을 구성하는 방법에 대한 자세한 내용은 [Amazon ECS용 Docker 볼륨 예제](docker-volume-examples.md) 섹션을 참조하세요.
+ 바인드 탑재를 구성하는 방법에 대한 자세한 내용은 [Amazon ECS에 대한 바인드 탑재 예제](bind-mount-examples.md) 섹션을 참조하세요.
## Windows 샘플 태스크 정의
Amazon ECS에서 Windows 컨테이너를 시작하는 데 도움을 줄 샘플 태스크 정의는 아래와 같습니다.
**Example Windows용 Amazon ECS 콘솔 샘플 애플리케이션**
다음 태스크 정의는 Amazon ECS 처음 실행 마법사에서 생성되는 Amazon ECS 콘솔 샘플 애플리케이션으로서 `microsoft/iis` Windows 컨테이너 이미지를 사용하도록 이식되었습니다.
```
{
"family": "windows-simple-iis",
"containerDefinitions": [
{
"name": "windows_sample_app",
"image": "mcr.microsoft.com/windows/servercore/iis",
"cpu": 1024,
"entryPoint":["powershell", "-Command"],
"command":["New-Item -Path C:\\inetpub\\wwwroot\\index.html -Type file -Value '
Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
'; C:\\ServiceMonitor.exe w3svc"],
"portMappings": [
{
"protocol": "tcp",
"containerPort": 80
}
],
"memory": 1024,
"essential": true
}
],
"networkMode": "awsvpc",
"memory": "1024",
"cpu": "1024"
}
```