Fargate용 Amazon ECS 태스크 정의 파라미터

Fargate용 Amazon ECS 태스크 정의 파라미터

Fargate용 태스크 정의의 각 파라미터에 대한 자세한 설명을 알아봐요. family, 용량, 태스크 역할, 네트워크 모드, 런타임 플랫폼, 태스크 크기, 컨테이너 정의 등을 다뤄요.

출처: 문서

본문

태스크 정의는 태스크 family, AWS Identity and Access Management (IAM) 태스크 역할, 네트워크 모드, 컨테이너 정의, 볼륨, launch type의 여러 부분으로 나뉘어요. 태스크 정의에서 family와 컨테이너 정의는 필수예요. 반면 태스크 역할, 네트워크 모드, 볼륨, launch type은 선택 사항이에요. JSON 파일에서 이 파라미터들을 사용해 태스크 정의를 구성할 수 있어요. 다음은 Fargate용 각 태스크 정의 파라미터에 대한 더 자세한 설명이에요.

Family

family — Type: String, Required: Yes

태스크 정의를 등록할 때 family를 부여해요. 이는 리비전 번호로 지정되는 태스크 정의의 여러 버전에 대한 이름과 비슷해요. 특정 family에 처음 등록되는 태스크 정의는 리비전 1이 부여되고, 이후 등록되는 태스크 정의는 순차적인 리비전 번호가 부여돼요.

용량 (Capacity)

태스크 정의를 등록할 때 Amazon ECS가 태스크 정의를 검증해야 하는 용량을 지정할 수 있어요. 태스크 정의가 지정된 호환성에 대해 검증되지 않으면 클라이언트 예외가 반환돼요.

requiresCompatibilities — Type: String array, Required: No, Valid Values: FARGATE

태스크 정의를 검증할 용량. 태스크 정의에 사용된 모든 파라미터가 Fargate의 요구 사항을 충족하는지 확인하는 검사를 시작해요.

태스크 역할 (Task role)

taskRoleArn — Type: String, Required: No

태스크 정의를 등록할 때 태스크의 컨테이너가 연관된 정책에 지정된 AWS API를 사용자를 대신해 호출할 수 있는 권한을 부여하는 IAM 역할을 위한 태스크 역할을 제공할 수 있어요. 자세한 내용은 Amazon ECS task IAM role 참고.

태스크 실행 역할 (Task execution role)

executionRoleArn — Type: String, Required: Conditional

Amazon ECS container agent에게 사용자를 대신해 AWS API 호출을 할 수 있는 권한을 부여하는 태스크 실행 역할의 ARN(Amazon Resource Name).

참고 — 태스크 실행 IAM 역할은 태스크의 요구 사항에 따라 필요해요. 자세한 내용은 Amazon ECS task execution IAM role 참고.

네트워크 모드 (Network mode)

networkMode — Type: String, Required: Yes

태스크의 컨테이너에 사용할 Docker 네트워킹 모드. Fargate에서 호스팅되는 Amazon ECS 태스크의 경우 awsvpc 네트워크 모드가 필요해요.

런타임 플랫폼 (Runtime platform)

operatingSystemFamily — Type: String, Required: Conditional, Default: LINUX

이 파라미터는 Fargate에서 호스팅되는 Amazon ECS 태스크에 필요해요. 태스크 정의를 등록할 때 운영 체제 family를 지정해요. 유효한 값은 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 — Type: String, Required: Conditional, Default: X86_64

파라미터가 null로 남으면 Fargate에서 호스팅되는 태스크 시작 시 기본값이 자동으로 할당돼요. 태스크 정의를 등록할 때 CPU 아키텍처를 지정해요. 유효한 값은 X86_64와 ARM64예요. 서비스에서 사용되는 모든 태스크 정의는 이 파라미터에 대해 같은 값을 가져야 해요. Linux 태스크에서는 값을 ARM64로 설정할 수 있어요. 자세한 내용은 Amazon ECS task definitions for 64-bit ARM workloads 참고.

태스크 크기 (Task size)

태스크 정의를 등록할 때 태스크에 사용되는 총 CPU와 메모리를 지정할 수 있어요. 이는 컨테이너 정의 수준의 cpu와 memory 값과는 별개예요. Fargate(Windows 및 Linux 모두)에서 호스팅되는 태스크의 경우 이 필드들은 필수이며 지원되는 cpu와 memory 값이 특정돼 있어요.

cpu — Type: String, Required: Yes

참고 — 태스크 수준 CPU와 메모리 파라미터는 필수이며 태스크가 실행되는 인스턴스 유형과 크기를 결정하는 데 사용돼요. Windows 태스크의 경우 Windows에는 컨테이너 그룹에 집합적 리소스 한도를 쉽게 강제할 수 있는 네이티브 메커니즘이 없으므로 이러한 값은 런타임에 적용되지 않아요. 리소스 한도를 강제하려면 Windows 컨테이너에 컨테이너 수준 리소스를 사용할 것을 권장해요.

태스크에 제공할 CPU 단위의 하드 한도. JSON 파일에서 CPU 값을 CPU 단위 또는 가상 CPU(vCPU)의 문자열로 지정할 수 있어요. 예를 들어 CPU 값을 CPU 단위의 1024 또는 vCPU의 1 vCPU로 지정할 수 있어요. 태스크 정의가 등록되면 vCPU 값은 CPU 단위를 나타내는 정수로 변환돼요.

이 필드는 필수이며 memory 파라미터의 지원 값 범위를 결정하는 다음 값 중 하나를 사용해야 해요. 다음 표는 태스크 수준 CPU와 메모리의 유효한 조합을 보여줘요.

CPU 값 메모리 값 AWS Fargate 지원 OS
256 (.25 vCPU) 512 MiB, 1 GB, 2 GB Linux
512 (.5 vCPU) 1 GB, 2 GB, 3 GB, 4 GB Linux
1024 (1 vCPU) 2 GB, 3 GB, 4 GB, 5 GB, 6 GB, 7 GB, 8 GB Linux, Windows
2048 (2 vCPU) 4 GB ~ 16 GB (1 GB 단위) Linux, Windows
4096 (4 vCPU) 8 GB ~ 30 GB (1 GB 단위) Linux, Windows
8192 (8 vCPU) (Linux 플랫폼 1.4.0 이상 필요) 16 GB ~ 60 GB (4 GB 단위) Linux
16384 (16 vCPU) (Linux 플랫폼 1.4.0 이상 필요) 32 GB ~ 120 GB (8 GB 단위) Linux
32768 (32 vCPU) (Linux 플랫폼 1.4.0 이상 필요) 60 GB, 120 GB, 244 GB Linux

memory — Type: String, Required: Yes

참고 — 태스크 수준 CPU와 메모리 파라미터는 필수이며 태스크가 실행되는 인스턴스 유형과 크기를 결정하는 데 사용돼요. Windows 태스크의 경우 Windows에는 컨테이너 그룹에 집합적 리소스 한도를 쉽게 강제할 수 있는 네이티브 메커니즘이 없으므로 이러한 값은 런타임에 적용되지 않아요. 리소스 한도를 강제하려면 Windows 컨테이너에 컨테이너 수준 리소스를 사용할 것을 권장해요.

태스크에 제공할 메모리의 하드 한도. 태스크 정의에서 메모리 값을 mebibytes(MiB) 또는 gigabytes(GB)의 문자열로 지정할 수 있어요. 예를 들어 메모리 값을 MiB의 3072 또는 GB의 3 GB로 지정할 수 있어요. 태스크 정의가 등록되면 GB 값은 MiB를 나타내는 정수로 변환돼요.

이 필드는 필수이며 cpu 파라미터의 지원 값 범위를 결정하는 다음 값 중 하나를 사용해야 해요:

메모리 값 (MiB, GB 대략값) CPU 값 Fargate 지원 OS
512 (0.5 GB), 1024 (1 GB), 2048 (2 GB) 256 (.25 vCPU) Linux
1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB) 512 (.5 vCPU) Linux
2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB) 1024 (1 vCPU) Linux, Windows
4096 (4 GB) ~ 16384 (16 GB) (1024(1 GB) 단위) 2048 (2 vCPU) Linux, Windows
8192 (8 GB) ~ 30720 (30 GB) (1024(1 GB) 단위) 4096 (4 vCPU) Linux, Windows
16 GB ~ 60 GB (4 GB 단위) (Linux 플랫폼 1.4.0 이상 필요) 8192 (8 vCPU) Linux
32 GB ~ 120 GB (8 GB 단위) (Linux 플랫폼 1.4.0 이상 필요) 16384 (16 vCPU) Linux

컨테이너 정의 (Container definitions)

태스크 정의를 등록할 때 컨테이너 인스턴스의 Docker daemon에 전달되는 컨테이너 정의 목록을 지정해야 해요. 컨테이너 정의에서 허용되는 파라미터는 다음과 같아요.

  • 표준 컨테이너 정의 파라미터
  • 고급 컨테이너 정의 파라미터
  • 기타 컨테이너 정의 파라미터

표준 컨테이너 정의 파라미터 (Standard container definition parameters)

다음 태스크 정의 파라미터는 대부분의 컨테이너 정의에서 필수이거나 사용돼요.

  • Name
  • Image
  • Memory
  • Port mappings
  • Private Repository Credentials

name — Type: String, Required: Yes

컨테이너의 이름. 최대 255자의 문자(대소문자), 숫자, 하이픈, 밑줄이 허용돼요. 태스크 정의에서 여러 컨테이너를 연결(link)한다면 한 컨테이너의 이름을 다른 컨테이너의 links에 입력할 수 있어요. 이는 컨테이너들을 연결하기 위한 것이에요.

image — Type: String, Required: Yes

컨테이너를 시작하는 데 사용되는 이미지. 이 문자열은 Docker daemon에 직접 전달돼요. 기본적으로 Docker Hub 레지스트리의 이미지를 사용할 수 있어요. repository-url/image:tag 또는 repository-url/image@digest로 다른 리포지토리를 지정할 수도 있어요. 최대 255자의 문자(대소문자), 숫자, 하이픈, 밑줄, 콜론, 마침표, 슬래시, 숫자 기호가 허용돼요. 이 파라미터는 docker create-container 명령의 Image와 docker run 명령의 IMAGE 파라미터에 매핑돼요.

새 태스크가 시작되면 Amazon ECS container agent가 지정된 이미지와 태그의 최신 버전을 가져와 컨테이너가 사용하도록 해요. 그러나 리포지토리 이미지에 대한 이후 업데이트는 이미 실행 중인 태스크에는 전파되지 않아요.

태스크 정의의 이미지 경로에 태그나 다이제스트를 지정하지 않으면 Amazon ECS container agent는 latest 태그를 사용해 지정된 이미지를 가져와요.

프라이빗 레지스트리의 이미지가 지원돼요. 자세한 내용은 Using non-AWS container images in Amazon ECS 참고.

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 — Type: String, Valid values: enabled | disabled, Required: No

Amazon ECS가 컨테이너 정의에 제공된 컨테이너 이미지 태그를 이미지 다이제스트로 해석할지 여부를 지정해요. 기본적으로 이 동작은 enabled예요. 컨테이너의 값을 disabled로 설정하면 Amazon ECS는 컨테이너 이미지 태그를 다이제스트로 해석하지 않고 배포에 컨테이너 정의에 지정된 원래 이미지 URI를 사용해요.

더 알아보기 (Learn more)