Amazon ECS 서비스 정의 파라미터

서비스 정의는 Amazon ECS 서비스를 실행하는 방법을 정의해요. 다음 파라미터를 서비스 정의에 지정할 수 있습니다.

출처: 문서

본문

런치 타입(Launch type)

launchType

유형: String / 유효 값: EC2 | FARGATE | EXTERNAL / 필수: 아니요
서비스를 실행할 런치 타입. 런치 타입을 지정하지 않으면 기본적으로 기본 capacityProviderStrategy가 사용돼요. 서비스를 업데이트하면 이 파라미터가 새 서비스 배포를 트리거합니다. launchType이 지정되면 capacityProviderStrategy 파라미터는 생략해야 해요.

용량 공급자 전략(Capacity provider strategy)

capacityProviderStrategy

유형: 객체 배열 / 필수: 아니요
서비스에 사용할 용량 공급자 전략. 서비스를 업데이트할 때 이 파라미터는 새 서비스 배포를 트리거하지 않습니다. 용량 공급자 전략은 하나 이상의 용량 공급자와 그에 할당할 base와 weight로 구성됩니다. 용량 공급자 전략에서 사용하려면 용량 공급자가 클러스터와 연결되어 있어야 해요. PutClusterCapacityProviders API가 용량 공급자를 클러스터에 연결합니다. ACTIVE 또는 UPDATING 상태의 용량 공급자만 사용할 수 있습니다. capacityProviderStrategy가 지정되면 launchType 파라미터는 생략해야 합니다. capacityProviderStrategy나 launchType 모두 지정되지 않으면 클러스터의 defaultCapacityProviderStrategy가 사용됩니다. Auto Scaling 그룹을 사용하는 용량 공급자를 지정하려면 용량 공급자가 이미 만들어져 있어야 해요. 새 용량 공급자는 CreateCapacityProvider API 작업으로 만들 수 있습니다. AWS Fargate 용량 공급자를 사용하려면 FARGATE 또는 FARGATE_SPOT 용량 공급자를 지정하세요. Fargate 용량 공급자는 모든 계정에서 사용할 수 있으며 사용하려면 클러스터와 연결만 하면 됩니다. PutClusterCapacityProviders API 작업은 클러스터가 만들어진 후 클러스터의 사용 가능한 용량 공급자 목록을 업데이트하는 데 사용됩니다.

capacityProvider

유형: String / 필수: 예
용량 공급자의 짧은 이름 또는 전체 Amazon Resource Name(ARN).

weight

유형: Integer / 유효 범위: 0~1,000 사이 정수 / 필수: 아니요
weight 값은 시작된 총 태스크 수 중 지정된 용량 공급자를 사용하는 상대적 백분율을 지정해요. 예를 들어 두 용량 공급자를 포함하고 둘 다 weight가 1인 전략이 있다고 가정해 보세요. base가 충족되면 태스크는 두 용량 공급자에 균등하게 분할됩니다. 같은 논리로 capacityProviderA에 weight 1, capacityProviderB에 weight 4를 지정한다고 가정하면, capacityProviderA로 실행되는 태스크 1개마다 4개의 태스크가 capacityProviderB를 사용합니다.

base

유형: Integer / 유효 범위: 0~100,000 사이 정수 / 필수: 아니요
base 값은 지정된 용량 공급자에서 최소한으로 실행할 태스크 수를 지정합니다. 용량 공급자 전략에서 base를 정의할 수 있는 용량 공급자는 하나뿐이에요.

태스크 정의(Task definition)

taskDefinition

유형: String / 필수: 아니요
서비스에서 실행할 태스크 정의의 family:revision(패밀리와 리비전) 또는 전체 Amazon Resource Name(ARN). 리비전이 지정되지 않으면 지정된 패밀리의 최신 ACTIVE 리비전이 사용됩니다. 서비스를 업데이트하면 이 파라미터가 새 서비스 배포를 트리거합니다. 롤링 업데이트(ECS) 배포 컨트롤러를 사용할 때는 태스크 정의를 지정해야 해요.

플랫폼 운영 체제(Platform operating system)

platformFamily

유형: string / 필수: 조건부 / 기본값: Linux
이 파라미터는 Fargate에 호스팅된 Amazon ECS 서비스에 필수이며, Amazon EC2에 호스팅된 서비스에는 무시됩니다. 서비스를 실행하는 컨테이너의 운영 체제. 유효 값은 LINUX, WINDOWS_SERVER_2019_FULL, WINDOWS_SERVER_2019_CORE, WINDOWS_SERVER_2022_FULL, WINDOWS_SERVER_2022_CORE입니다. 서비스에 지정하는 모든 태스크의 platformFamily 값은 서비스 platformFamily 값과 일치해야 해요. 예를 들어 platformFamily를 WINDOWS_SERVER_2019_FULL로 설정하면 모든 태스크의 platformFamily 값도 WINDOWS_SERVER_2019_FULL이어야 합니다.

플랫폼 버전(Platform version)

platformVersion

유형: String / 필수: 아니요
서비스의 태스크가 실행되는 플랫폼 버전. 플랫폼 버전은 Fargate 런치 타입을 사용하는 태스크에만 지정됩니다. 지정하지 않으면 기본적으로 최신 버전(LATEST)이 사용됩니다. 서비스를 업데이트하면 이 파라미터가 새 서비스 배포를 트리거합니다. AWS Fargate 플랫폼 버전은 Fargate 태스크 인프라의 특정 런타임 환경을 나타내는 데 사용됩니다. 태스크를 실행하거나 서비스를 만들 때 LATEST 플랫폼 버전을 지정하면 태스크에 사용 가능한 가장 최신 플랫폼 버전을 얻게 됩니다. 서비스를 확장하면 그 태스크들은 서비스의 현재 배포에 지정된 플랫폼 버전을 받습니다. 자세한 내용은 Amazon ECS용 Fargate 플랫폼 버전(Fargate platform versions for Amazon ECS)을 참고하세요. 참고: EC2 런치 타입을 사용하는 태스크에는 플랫폼 버전이 지정되지 않습니다.

클러스터(Cluster)

cluster

유형: String / 필수: 아니요
서비스를 실행할 클러스터의 짧은 이름 또는 전체 Amazon Resource Name(ARN). 클러스터를 지정하지 않으면 기본 클러스터(default cluster)가 사용됩니다.

서비스 이름(Service name)

serviceName

유형: String / 필수: 예
서비스의 이름. 최대 255자의 문자(대문자·소문자), 숫자, 하이픈, 밑줄이 허용됩니다. 서비스 이름은 클러스터 내에서 고유해야 하지만, 리전 내 여러 클러스터 또는 여러 리전에 걸쳐 비슷한 이름을 가진 서비스를 가질 수 있어요.

스케줄링 전략(Scheduling strategy)

schedulingStrategy

유형: String / 유효 값: REPLICA | DAEMON / 필수: 아니요
사용할 스케줄링 전략. 스케줄링 전략을 지정하지 않으면 REPLICA 전략이 사용됩니다. 자세한 내용은 Amazon ECS 서비스(Amazon ECS services)를 참고하세요. 사용 가능한 서비스 스케줄러 전략은 두 가지입니다:
- REPLICA — replica 스케줄링 전략은 원하는 태스크 수를 클러스터 전체에 배치하고 유지합니다. 기본적으로 서비스 스케줄러는 태스크를 가용 영역 전체에 분산합니다. 태스크 배치 전략과 제약 조건을 사용해 태스크 배치 결정을 사용자 지정할 수 있어요. 자세한 내용은 Replica 스케줄링 전략(Replica scheduling strategy)을 참고하세요.
- DAEMON — daemon 스케줄링 전략은 클러스터에서 지정한 모든 태스크 배치 제약 조건을 충족하는 각 활성 컨테이너 인스턴스에 정확히 하나의 태스크를 배포합니다. 이 전략을 사용할 때는 원하는 태스크 수, 태스크 배치 전략을 지정하거나 Service Auto Scaling 정책을 사용할 필요가 없습니다. 자세한 내용은 Daemon 스케줄링 전략(Daemon scheduling strategy)을 참고하세요. 참고: Fargate 태스크는 DAEMON 스케줄링 전략을 지원하지 않습니다.

원하는 개수(Desired count)

desiredCount

유형: Integer / 필수: 아니요
서비스에서 배치하고 실행 상태로 유지할 지정된 태스크 정의의 인스턴스화 수. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다. REPLICA 스케줄링 전략을 사용하면 이 파라미터가 필수입니다. 서비스가 DAEMON 스케줄링 전략을 사용하면 이 파라미터는 선택 사항입니다. 서비스 자동 확장을 사용할 때, 현재 실행 중인 태스크 수보다 작은 desiredCount로 실행 중인 서비스를 업데이트하면 서비스는 지정된 desiredCount로 축소됩니다.

배포 구성(Deployment configuration)

deploymentConfiguration

유형: Object / 필수: 아니요
배포 중 실행할 태스크 수와 태스크 중지·시작 순서를 제어하는 선택적 배포 파라미터. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다.

maximumPercent

유형: Integer / 필수: 아니요
서비스가 롤링 업데이트(ECS) 배포 유형을 사용한다면, maximumPercent 파라미터는 배포 중 서비스 태스크 수 중 RUNNING, STOPPING 또는 PENDING 상태가 허용되는 상한을 나타냅니다. 이는 가장 가까운 정수로 내림한 desiredCount의 백분율로 표현됩니다. 이 파라미터로 배포 배치 크기를 정의할 수 있어요. 예를 들어 서비스가 REPLICA 서비스 스케줄러를 사용하고 desiredCount가 4개 태스크이고 maximumPercent 값이 200%라면, 스케줄러는 4개의 이전 태스크를 중지하기 전에 새 태스크 4개를 시작합니다. 이는 이를 수행하는 데 필요한 클러스터 리소스가 사용 가능한 경우입니다. REPLICA 서비스 스케줄러를 사용하는 서비스의 기본 maximumPercent 값은 200%입니다. Amazon ECS 스케줄러는 이 파라미터를 사용해 비정상 태스크를 교체합니다. 먼저 교체 태스크를 시작한 다음 대체 태스크 시작을 위한 클러스터 리소스가 사용 가능한 한 비정상 태스크를 중지합니다. DAEMON 서비스 스케줄러 유형을 사용하면 maximumPercent는 100%로 유지해야 합니다(기본값). 배포 중 최대 태스크 수는 desiredCount에 maximumPercent/100을 곱하고 가장 가까운 정수로 내림한 값입니다. 서비스가 blue/green(CODE_DEPLOY) 또는 EXTERNAL 배포 유형을 사용하고 EC2 런치 타입을 사용하는 태스크가 있다면, maximum percent 값은 기본값으로 설정됩니다.
- 참고: blue/green(CODE_DEPLOY) 또는 EXTERNAL 배포 유형을 사용하고 EC2 태스크가 있는 서비스에는 사용자 지정 maximumPercent 값을 지정할 수 없습니다.
- 서비스가 blue/green(CODE_DEPLOY) 또는 EXTERNAL 배포 유형을 사용하고 태스크가 Fargate를 사용한다면 maximum percent 값은 사용되지 않으며, 서비스를 describe할 때 값은 여전히 반환됩니다.

minimumHealthyPercent

유형: Integer / 필수: 아니요
서비스가 롤링 업데이트(ECS) 배포 유형을 사용한다면, minimumHealthyPercent는 배포 중 서비스 태스크 수 중 RUNNING 상태로 유지되어야 하는 하한을 나타냅니다. 이는 가장 가까운 정수로 올림한 desiredCount의 백분율로 표현됩니다. 이 파라미터를 사용하면 추가 클러스터 용량 없이 배포할 수 있어요. 예를 들어 서비스의 desiredCount가 4개 태스크, minimumHealthyPercent가 50%, maximumPercent가 100%라면, 서비스 스케줄러는 새 태스크 2개를 시작하기 전에 기존 태스크 2개를 중지해 클러스터 용량을 확보합니다. 태스크가 비정상이고 maximumPercent가 Amazon ECS 스케줄러가 대체 태스크를 시작하는 것을 허용하지 않으면, 스케줄러는 대체 태스크를 시작할 용량을 확보하기 위해 minimumHealthyPercent를 제약으로 사용해 비정상 태스크를 하나씩 중지합니다.
로드 밸런서를 사용하지 않는 서비스의 경우 다음을 고려하세요:
- 서비스의 태스크 내 모든 essential 컨테이너가 상태 확인을 통과하면 서비스는 정상으로 간주됩니다.
- 태스크에 상태 확인이 정의된 essential 컨테이너가 없으면, 태스크가 RUNNING 상태에 도달한 후 40초가 지나야 최소 정상 백분율 합계에 계산됩니다.
- 태스크에 상태 확인이 정의된 essential 컨테이너가 하나 이상 있으면, 태스크가 정상 상태에 도달한 후에 최소 정상 백분율 합계에 계산됩니다.
로드 밸런서를 사용하는 서비스의 경우:
- 태스크에 상태 확인이 정의된 essential 컨테이너가 없으면, 로드 밸런서 대상 그룹 상태 확인이 정상 상태를 반환할 때까지 기다린 후 최소 정상 백분율 합계에 계산됩니다.
- 태스크에 상태 확인이 정의된 essential 컨테이너가 있으면, 태스크가 정상 상태에 도달하고 로드 밸런서 대상 그룹 상태 확인이 정상 상태를 반환한 후에야 최소 정상 백분율 합계에 계산됩니다.
replica 서비스의 기본 minimumHealthyPercent는 100%입니다. DAEMON 서비스 스케줄을 사용하는 서비스의 기본값은 AWS CLI, AWS SDK, API에서 0%이고 AWS Management Console에서 50%입니다.
배포 중 최소 정상 태스크 수는 desiredCount에 minimumHealthyPercent/100을 곱하고 가장 가까운 정수로 올림한 값입니다. blue/green(CODE_DEPLOY) 또는 EXTERNAL 배포 유형을 사용하고 EC2 태스크를 실행한다면 minimum healthy percent 값은 기본값으로 설정됩니다.

earlySuccessCriteria

유형: Object / 필수: 아니요
Amazon ECS가 롤링 배포를 완료할 시점을 결정하는 조기 성공 기준(early success criteria). 조기 성공 기준을 사용하면 정의한 백분율의 태스크가 대상 서비스 리비전에서 실행되고 정상일 때 Amazon ECS가 배포를 완료합니다. 또한 Amazon ECS가 배포를 완료하기 전에 또는 후에 소스 서비스 리비전의 태스크를 정리할지 구성할 수 있어요. 자세한 내용은 조기 성공 기준으로 Amazon ECS 롤링 배포 조기 완료(Complete Amazon ECS rolling deployments early with early success criteria)를 참고하세요.
enable — 유형: Boolean / 필수: 아니요. 서비스에 조기 성공 기준이 켜져 있는지 여부. 기본값은 false.
healthyPercent — 유형: Integer / 필수: 아니요. Amazon ECS가 배포를 완료하기 전에 대상 서비스 리비전에서 실행되고 정상이어야 하는 desired count의 백분율(올림). 값은 서비스 minimumHealthyPercent와 100 사이여야 합니다(경계 포함). 기본값은 100.
sourceServiceRevisionCleanup — 유형: String / 유효 값: BLOCKING | DEFERRED / 필수: 아니요. Amazon ECS가 소스 서비스 리비전의 태스크를 정리하는 시점을 결정합니다. BLOCKING을 사용하면 Amazon ECS가 배포를 완료하기 전에 소스 서비스 리비전의 태스크를 정리합니다. DEFERRED를 사용하면 Amazon ECS가 먼저 배포를 완료한 다음 배포 외부에서 소스 서비스 리비전의 태스크를 정리해요. 기본값은 BLOCKING.

배포 컨트롤러(Deployment controller)

deploymentController

유형: Object / 필수: 아니요
서비스에 사용할 배포 컨트롤러. 배포 컨트롤러가 지정되지 않으면 ECS 컨트롤러가 사용됩니다. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다.
type — 유형: String / 유효 값: ECS | CODE_DEPLOY | EXTERNAL / 필수: 예. 사용할 배포 컨트롤러 유형. 세 가지 유형이 있습니다:
- ECS — Amazon ECS 배포 컨트롤러는 롤링 업데이트, blue/green, linear, canary를 포함한 여러 배포 전략을 지원합니다. 롤링 업데이트 배포 유형은 컨테이너의 현재 실행 버전을 최신 버전으로 교체하는 것입니다. blue/green 배포는 새 환경을 만들고 트래픽을 한 번에 이동합니다. linear 배포는 트래픽을 동일한 백분율 증가분으로 점진적으로 이동합니다. canary 배포는 먼저 작은 백분율의 트래픽을 이동한 다음 나머지 트래픽을 이동합니다. 롤링 업데이트 중 Amazon ECS가 서비스에서 추가하거나 제거하는 컨테이너 수는 deploymentConfiguration에 지정된 대로 서비스 배포 중 허용되는 최소·최대 정상 태스크 수를 조정해 제어됩니다.
- CODE_DEPLOY — blue/green(CODE_DEPLOY) 배포 유형은 CodeDeploy가 제공하는 blue/green 배포 모델을 사용합니다. 이는 프로덕션 트래픽을 보내기 전에 서비스의 새 배포를 검증할 수 있게 해줍니다.
- EXTERNAL — Amazon ECS 서비스의 배포 프로세스를 완전히 제어하기 위해 타사 배포 컨트롤러를 사용하려면 EXTERNAL 배포 유형을 사용합니다.

태스크 배치(Task placement)

placementConstraints

유형: 객체 배열 / 필수: 아니요
서비스의 태스크에 사용할 배치 제약 조건 객체 배열. 태스크당 최대 10개의 제약 조건을 지정할 수 있어요. 이 제한에는 태스크 정의의 제약 조건과 런타임에 지정된 제약 조건이 포함됩니다. Fargate를 사용하면 태스크 배치 제약 조건이 지원되지 않아요. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다.
type — 유형: String / 필수: 아니요. 제약 조건 유형. 특정 그룹의 각 태스크가 다른 컨테이너 인스턴스에서 실행되도록 하려면 distinctInstance를 사용하세요. 유효한 후보 그룹으로 선택을 제한하려면 memberOf를 사용합니다. distinctInstance 값은 태스크 정의에서 지원되지 않습니다.
expression — 유형: String / 필수: 아니요. 제약 조건에 적용할 클러스터 쿼리 언어 표현식. 제약 조건 유형이 distinctInstance이면 표현식을 지정할 수 없습니다. 자세한 내용은 Amazon ECS 태스크용 컨테이너 인스턴스 정의 표현식 만들기(Create expressions to define container instances for Amazon ECS tasks)를 참고하세요.

placementStrategy

유형: 객체 배열 / 필수: 아니요
서비스 태스크에 사용할 배치 전략 객체. 서비스당 최대 4개의 전략 규칙을 지정할 수 있어요. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다.
type — 유형: String / 유효 값: random | spread | binpack / 필수: 아니요. 배치 전략 유형. random 배치 전략은 사용 가능한 후보에 태스크를 무작위로 배치합니다. spread 배치 전략은 field 파라미터를 기준으로 사용 가능한 후보 전체에 균등하게 배치합니다. binpack 전략은 field 파라미터에 지정된 리소스의 사용 가능한 양이 가장 적은 사용 가능한 후보에 태스크를 배치합니다. 예를 들어 memory에서 binpack하면 태스크를 실행하기에 충분하면서 남은 메모리가 가장 적은 인스턴스에 배치합니다.
field — 유형: String / 필수: 아니요. 배치 전략을 적용할 필드. spread 배치 전략의 유효 값은 instanceId(또는 같은 효과인 host), 또는 attribute:ecs.availability-zone 같이 컨테이너 인스턴스에 적용된 플랫폼·사용자 지정 속성입니다. binpack 배치 전략의 유효 값은 cpu와 memory입니다. random 배치 전략에서는 이 필드가 사용되지 않습니다.

태그(Tags)

tags

유형: 객체 배열 / 필수: 아니요
서비스를 분류하고 구성하는 데 도움이 되는 메타데이터. 각 태그는 사용자가 정의하는 키와 선택적 값으로 구성됩니다. 서비스가 삭제되면 태그도 삭제됩니다. 서비스에 최대 50개의 태그를 적용할 수 있어요. 자세한 내용은 Amazon ECS 리소스 태깅(Tagging Amazon ECS resources)을 참고하세요. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다.
key — 유형: String / 길이 제약: 최소 1, 최대 128 / 필수: 아니요. 태그를 구성하는 키-값 쌍의 한 부분. 키는 더 구체적인 태그 값의 범주 역할을 하는 일반 레이블입니다.
value — 유형: String / 길이 제약: 최소 0, 최대 256 / 필수: 아니요. 태그를 구성하는 키-값 쌍의 선택적 부분. 값은 태그 범주(키) 내의 설명자 역할을 합니다.

enableECSManagedTags

유형: Boolean / 유효 값: true | false / 필수: 아니요
서비스 태스크에 Amazon ECS 관리형 태그를 사용할지 여부. 값이 지정되지 않으면 기본값은 false입니다. 자세한 내용은 청구용 태그 사용(Use tags for billing)을 참고하세요. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다.

propagateTags

유형: String / 유효 값: TASK_DEFINITION | SERVICE / 필수: 아니요
태스크 정의 또는 서비스에서 서비스 태스크로 태그를 복사할지 여부. 값이 지정되지 않으면 태그가 복사되지 않습니다. 태그는 서비스 생성 중에만 서비스 내 태스크로 복사할 수 있어요. 서비스 생성 후 또는 태스크 생성 후 태스크에 태그를 추가하려면 TagResource API 작업을 사용하세요. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다.

네트워크 구성(Network configuration)

networkConfiguration

유형: Object / 필수: 아니요
서비스의 네트워크 구성. 이 파라미터는 자체 탄력적 네트워크 인터페이스(ENI)를 받기 위해 awsvpc 네트워크 모드를 사용하는 태스크 정의에 필요하며, 다른 네트워크 모드에서는 지원되지 않습니다. Fargate를 사용하면 awsvpc 네트워크 모드가 필요해요. EC2 네트워킹에 대한 자세한 내용은 Amazon ECS 태스크 네트워킹 옵션(Amazon ECS task networking options for EC2), Fargate는 Amazon ECS 태스크 네트워킹 옵션(Amazon ECS task networking options for Fargate)을 참고하세요. 서비스를 업데이트하면 이 파라미터가 새 서비스 배포를 트리거합니다.
awsvpcConfiguration — 유형: Object / 필수: 아니요. 태스크 또는 서비스의 서브넷과 보안 그룹을 나타내는 객체.
- subnets — 유형: 문자열 배열 / 필수: 예. 태스크 또는 서비스와 연결된 서브넷. awsvpcConfiguration에 따라 최대 16개 서브넷을 지정할 수 있습니다.
- securityGroups — 유형: 문자열 배열 / 필수: 아니요. 태스크 또는 서비스와 연결된 보안 그룹. 보안 그룹을 지정하지 않으면 VPC의 기본 보안 그룹이 사용됩니다. awsvpcConfiguration에 따라 최대 5개 보안 그룹을 지정할 수 있습니다.
- assignPublicIP — 유형: String / 유효 값: ENABLED | DISABLED / 필수: 아니요. 태스크의 탄력적 네트워크 인터페이스가 퍼블릭 IP 주소를 받는지 여부. 값이 지정되지 않으면 기본값 DISABLED가 사용됩니다.

healthCheckGracePeriodSeconds

유형: Integer / 필수: 아니요
태스크가 처음 시작된 후 Amazon ECS 서비스 스케줄러가 비정상 Elastic Load Balancing, VPC Lattice, 컨테이너 상태 확인을 무시하는 시간(초). 상태 확인 유예 기간 값을 지정하지 않으면 기본값 0이 사용됩니다. 상태 확인을 사용하지 않는다면 healthCheckGracePeriodSeconds는 사용되지 않습니다. 서비스의 태스크가 시작되고 응답하는 데 시간이 걸린다면 최대 2,147,483,647초(약 69년)의 상태 확인 유예 기간을 지정할 수 있습니다. 그 시간 동안 Amazon ECS 서비스 스케줄러는 상태 확인 상태를 무시합니다. 이 유예 기간은 서비스 스케줄러가 태스크를 비정상으로 표시하고 살아나기 전에 중지하는 것을 방지할 수 있어요. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다.

로드 밸런서(Load balancers)

loadBalancers

유형: 객체 배열 / 필수: 아니요
서비스에 사용할 로드 밸런서를 나타내는 로드 밸런서 객체입니다. Application Load Balancer 또는 Network Load Balancer를 사용하는 서비스에는 서비스에 연결할 수 있는 대상 그룹이 최대 5개라는 제한이 있어요. 서비스를 업데이트하면 이 파라미터가 새 서비스 배포를 트리거합니다. 서비스를 만든 후에는 AWS Management Console에서 로드 밸런서 구성을 변경할 수 없습니다. ECS 롤링 배포 컨트롤러(CodeDeploy blue/green이나 external은 제외)의 로드 밸런서 구성을 수정하려면 AWS Copilot, AWS CloudFormation, AWS CLI 또는 SDK를 사용할 수 있어요. 로드 밸런서 구성을 추가, 업데이트 또는 제거하면 Amazon ECS가 업데이트된 Elastic Load Balancing 구성으로 새 배포를 시작합니다. 이로 인해 태스크가 로드 밸런서에 등록·등록 해제됩니다. Application Load Balancer와 Network Load Balancer의 경우 이 객체는 로드 밸런서 대상 그룹 ARN, 컨테이너 이름(컨테이너 정의에 나타나는 대로), 로드 밸런서에서 접근할 컨테이너 포트를 포함해야 합니다. 이 서비스의 태스크가 컨테이너 인스턴스에 배치되면 컨테이너 인스턴스와 포트 조합이 지정된 대상 그룹의 대상으로 등록됩니다.
targetGroupArn — 유형: String / 필수: 아니요. 서비스와 연결된 Elastic Load Balancing 대상 그룹의 전체 ARN. 대상 그룹 ARN은 Application Load Balancer나 Network Load Balancer를 사용할 때만 지정됩니다.
loadBalancerName — 유형: String / 필수: 아니요. 서비스와 연결할 로드 밸런서의 이름. Application Load Balancer나 Network Load Balancer를 사용한다면 load balancer name 파라미터를 생략하세요.
containerName — 유형: String / 필수: 아니요. 로드 밸런서와 연결할 컨테이너의 이름(컨테이너 정의에 나타나는 대로).
containerPort — 유형: Integer / 필수: 아니요. 로드 밸런서와 연결할 컨테이너의 포트. 이 포트는 서비스 태스크가 사용하는 태스크 정의의 containerPort와 일치해야 합니다. EC2를 사용하는 태스크의 경우 컨테이너 인스턴스가 포트 매핑의 hostPort에서 인바운드 트래픽을 허용해야 합니다.
role — 유형: String / 필수: 아니요. Amazon ECS가 사용자를 대신해 로드 밸런서를 호출할 수 있게 하는 IAM 역할의 짧은 이름 또는 전체 ARN. 이 파라미터는 서비스에 단일 대상 그룹이 있는 로드 밸런서를 사용하고 태스크 정의가 awsvpc 네트워크 모드를 사용하지 않는 경우에만 허용됩니다. role 파라미터를 지정하면 loadBalancers 파라미터로 로드 밸런서 객체도 지정해야 합니다. 지정된 역할에 /가 아닌 경로가 있으면 전체 역할 ARN을 지정(권장)하거나 역할 이름 앞에 경로를 붙여야 합니다.
- 중요: 계정이 이미 Amazon ECS 서비스 연결 역할을 만들었다면, 여기에 역할을 지정하지 않는 한 그 역할이 기본적으로 서비스에 사용됩니다. 태스크 정의가 awsvpc 네트워크 모드를 사용하면 서비스 연결 역할이 필요하며, 이 경우 여기에 역할을 지정해서는 안 됩니다.

Service Connect 구성

serviceConnectConfiguration

유형: Object / 필수: 아니요
이 서비스가 서비스를 발견하고 연결하며, 네임스페이스 내 다른 서비스에 의해 발견되고 연결되는 구성을 위한 설정. 서비스를 업데이트하면 이 파라미터가 새 서비스 배포를 트리거합니다. 자세한 내용은 짧은 이름으로 Amazon ECS 서비스를 연결하는 Service Connect 사용(Use Service Connect to connect Amazon ECS services with short names)을 참고하세요.
enabled — 유형: Boolean / 필수: 예. 이 서비스와 함께 Service Connect를 사용할지 여부.
namespace — 유형: String / 필수: 아니요. Service Connect에 사용할 AWS Cloud Map 네임스페이스의 짧은 이름 또는 전체 ARN. 네임스페이스는 Amazon ECS 서비스 및 클러스터와 같은 AWS 리전에 있어야 합니다. 네임스페이스 유형은 Service Connect에 영향을 주지 않습니다.
services — 유형: 객체 배열 / 필수: 아니요. Service Connect 서비스 객체 배열. 이는 다른 Amazon ECS 서비스가 이 서비스에 연결하는 데 사용하는 이름과 별칭(엔드포인트라고도 함)입니다. 이 필드는 네임스페이스의 "클라이언트" Amazon ECS 서비스(네임스페이스 내 다른 서비스에 연결하기 위한 멤버)에는 필요하지 않습니다. 예로는 서비스에 연결된 로드 밸런서나 다른 방법으로 인바운드 요청을 받는 프런트엔드 애플리케이션이 있습니다. 객체는 태스크 정의에서 포트를 선택하고, AWS Cloud Map 서비스의 이름을 할당하며, 클라이언트 애플리케이션이 이 서비스를 참조할 별칭(엔드포인트)과 포트 배열을 지정합니다.
- portName — 유형: String / 필수: 예. portName은 이 Amazon ECS 서비스의 태스크 정의에 있는 모든 컨테이너의 portMappings 중 하나의 이름과 일치해야 합니다.
- discoveryName — 유형: String / 필수: 아니요. discoveryName은 Amazon ECS가 이 서비스를 위해 만드는 새 AWS Cloud Map 서비스의 이름입니다. AWS Cloud Map 네임스페이스 내에서 고유해야 해요. 이 필드가 지정되지 않으면 portName이 사용됩니다.
- clientAliases — 유형: 객체 배열 / 필수: 아니요. 이 service connect 서비스의 클라이언트 별칭 목록. 이 목록의 최대 클라이언트 별칭 수는 1입니다. 각 별칭("엔드포인트")은 다른 Amazon ECS 서비스("클라이언트")가 이 서비스에 연결하는 데 사용할 수 있는 DNS 이름과 포트 번호입니다. 각 이름과 포트 조합은 네임스페이스 내에서 고유해야 합니다. 이러한 이름은 AWS Cloud Map이 아닌 클라이언트 서비스의 각 태스크 내에 구성됩니다. 이 이름을 해석하는 DNS 요청은 태스크를 떠나지 않으며, 탄력적 네트워크 인터페이스당 DNS 요청 초당 할당량에 계산되지 않습니다.
  - port — 유형: Integer / 필수: 예. service connect 프록시의 수신 포트 번호. 이 포트는 같은 네임스페이스의 모든 태스크 내에서 사용할 수 있습니다. 클라이언트 Amazon ECS 서비스의 애플리케이션을 변경하지 않으려면 클라이언트 애플리케이션이 기본으로 사용하는 포트와 같은 포트로 설정하세요.
  - dnsName — 유형: String / 필수: 아니요. dnsName은 클라이언트 태스크의 애플리케이션에서 이 서비스에 연결하는 데 사용하는 이름입니다. 이름은 유효한 DNS 레이블이어야 합니다. 이 필드가 지정되지 않으면 기본값은 discoveryName.namespace입니다. discoveryName이 지정되지 않으면 태스크 정의의 portName이 사용됩니다. 예를 들어 일반적인 이름으로 database, db, 또는 데이터베이스의 소문자 이름(예: mysql, redis)이 있습니다.
  - ingressPortOverride — 유형: Integer / 필수: 아니요. (선택 사항) Service Connect 프록시가 수신 대기할 포트 번호. 이 필드의 값을 사용해 이 애플리케이션의 태스크 정의에 있는 명명된 portMapping에 지정된 포트 번호의 트래픽에 대해 프록시를 우회한 다음, Amazon VPC 보안 그룹에서 이 서비스에 대한 트래픽이 프록시로 들어오도록 허용하는 데 사용합니다. awsvpc 모드에서 기본값은 이 애플리케이션의 태스크 정의에 있는 명명된 portMapping에 지정된 컨테이너 포트 번호입니다. bridge 모드에서 기본값은 Service Connect 프록시의 동적 임시 포트입니다.
- logConfiguration — 유형: LogConfiguration Object / 필수: 아니요. Service Connect 프록시 로그가 게시될 위치를 정의합니다. 예기치 않은 이벤트 중 디버깅에 로그를 사용하세요. 이 구성은 이 Amazon ECS 서비스의 각 태스크에 있는 Service Connect 프록시 컨테이너의 logConfiguration 파라미터를 설정합니다. 프록시 컨테이너는 태스크 정의에 지정되지 않습니다. 이 Amazon ECS 서비스의 태스크 정의 애플리케이션 컨테이너와 같은 로그 구성을 사용할 것을 권장합니다. FireLens의 경우 이는 애플리케이션 컨테이너의 로그 구성입니다. fluent-bit 또는 fluentd 컨테이너 이미지를 사용하는 FireLens 로그 라우터 컨테이너가 아닙니다.
- accessLogConfiguration — 유형: ServiceConnectAccessLogConfiguration Object / 필수: 아니요. 로그 형식과 로그에 쿼리 문자열을 포함할지 여부를 포함한 Service Connect 액세스 로깅 구성. 액세스 로그는 요청 패턴, 응답 코드, 타이밍 데이터를 포함해 서비스에 대한 요청에 대한 상세 정보를 캡처합니다. 액세스 로그를 활성화하려면 serviceConnectConfiguration에서 logConfiguration도 지정해야 합니다.

서비스 레지스트리(Service registries)

serviceRegistries

유형: 객체 배열 / 필수: 아니요
서비스의 서비스 검색 구성 세부 정보. 자세한 내용은 DNS 이름으로 Amazon ECS 서비스를 연결하는 서비스 검색 사용(Use service discovery to connect Amazon ECS services with DNS names)을 참고하세요. 서비스를 업데이트하면 이 파라미터가 새 서비스 배포를 트리거합니다.
registryArn — 유형: String / 필수: 아니요. 서비스 레지스트리의 ARN. 현재 지원되는 서비스 레지스트리는 AWS Cloud Map입니다.
port — 유형: Integer / 필수: 아니요. 서비스 검색 서비스가 SRV 레코드를 지정한 경우 사용되는 포트 값. awsvpc 네트워크 모드와 SRV 레코드를 모두 사용하면 이 필드가 필요합니다.
containerName — 유형: String / 필수: 아니요. 서비스 검색 서비스에 사용할 컨테이너 이름 값. 태스크 정의에 지정됩니다. 서비스 태스크가 지정하는 태스크 정의가 bridge 또는 host 네트워크 모드를 사용한다면 태스크 정의의 containerName과 containerPort 조합을 지정해야 해요. 태스크 정의가 awsvpc 네트워크 모드와 SRV DNS 레코드 유형을 사용한다면 containerName·containerPort 조합 또는 port 값 중 하나를 지정해야 하며 둘 다는 안 됩니다.
containerPort — 유형: Integer / 필수: 아니요. 서비스 검색 서비스에 사용할 포트 값. 태스크 정의에 지정됩니다.

클라이언트 토큰(Client token)

clientToken

유형: String / 필수: 아니요
요청의 멱등성(idempotency)을 보장하기 위해 제공하는 고유한 대소문자 구분 식별자. 최대 32개의 ASCII 문자까지 가능합니다.

가용 영역 리밸런싱(Availability Zone rebalancing)

availabilityZoneRebalancing

유형: String / 필수: 아니요
서비스가 가용 영역 리밸런싱을 사용하는지 여부. 유효 값은 ENABLED와 DISABLED입니다. 서비스를 업데이트하면 이 파라미터는 새 서비스 배포를 트리거하지 않습니다. 기본 동작: 새 서비스의 경우 값이 지정되지 않으면 기본값은 DISABLED입니다. 기존 서비스의 경우 값이 지정되지 않으면 Amazon ECS는 값을 기존 값으로 기본 설정합니다. 이전에 설정된 값이 없으면 Amazon ECS는 DISABLED로 설정합니다. 자세한 내용은 가용 영역 전체에 Amazon ECS 서비스 밸런싱(Balancing an Amazon ECS service across Availability Zones)을 참고하세요.

볼륨 구성(Volume configurations)

volumeConfigurations

유형: Object / 필수: 아니요
서비스가 관리하는 태스크용 볼륨을 만드는 데 사용될 구성. 태스크 정의에서 configuredAtLaunch로 표시된 볼륨만 이 객체로 구성할 수 있습니다. 서비스를 업데이트하면 이 파라미터가 새 서비스 배포를 트리거합니다. 이 객체는 서비스가 관리하는 태스크에 Amazon EBS 볼륨을 연결하는 데 필요합니다. 자세한 내용은 Amazon ECS와 함께 Amazon EBS 볼륨 사용(Use Amazon EBS volumes with Amazon ECS)을 참고하세요.
name — 유형: String / 필수: 예. 서비스를 만들거나 업데이트할 때 구성되는 볼륨의 이름. 최대 255자의 문자, 숫자, 밑줄(_), 하이픈(-)이 허용됩니다. 이 값은 태스크 정의에 지정된 볼륨 이름과 일치해야 합니다.
managedEBSVolume — 유형: Object / 필수: 아니요. 서비스가 만들어지거나 업데이트될 때 서비스가 유지하는 태스크에 연결되는 Amazon EBS 볼륨을 만드는 데 사용되는 볼륨 구성. 태스크당 볼륨 하나가 연결됩니다.
- encrypted — 유형: Boolean / 유효 값: true | false / 필수: 아니요. 각 생성 Amazon EBS 볼륨을 암호화할지 여부. AWS 계정의 특정 AWS 리전에서 기본으로 Amazon EBS 암호화를 켰지만 이 파라미터를 false로 설정했다면, 이 파라미터는 재정의되고 볼륨은 기본 암호화용으로 지정된 KMS 키로 암호화됩니다.
- kmsKeyId — 유형: String / 필수: 아니요. Amazon EBS 암호화에 사용할 AWS KMS 키의 식별자. kmsKeyId가 지정되면 encrypted 상태가 true여야 합니다. 이 파라미터로 지정한 키는 Amazon EBS 기본값이나 사용자가 지정했을 수 있는 Amazon ECS 관리형 스토리지 암호화용 클러스터 수준 KMS 키를 재정의합니다. 키 ID(예: 1234abcd-12ab-34cd-56ef-1234567890ab), 키 별칭(예: alias/ExampleAlias), 키 ARN(예: arn:aws:kms:us-east-1:012345678910:key/1234abcd-12ab-34cd-56ef-1234567890ab), 별칭 ARN(예: arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias)으로 지정할 수 있습니다.
  - 중요: AWS는 KMS 키를 비동기적으로 인증합니다. 따라서 ID, 별칭 또는 ARN이 유효하지 않으면 작업이 성공한 것처럼 보일 수 있지만 결국 실패합니다.
- volumeType — 유형: String / 유효 값: gp2 | gp3 | io1 | io2 | sc1 | st1 | standard / 필수: 아니요. Amazon EBS 볼륨 유형. 기본 볼륨 유형은 gp3입니다. 참고: standard 볼륨 유형은 Fargate 태스크에서 지원되지 않습니다.
- sizeInGiB — 유형: Integer / 유효 범위: 1~16,384 사이 정수 / 필수: 아니요. EBS 볼륨의 크기(GiB). 연결용 볼륨을 구성할 스냅샷 ID를 제공하지 않으면 크기 값을 제공해야 합니다. 스냅샷으로 볼륨을 구성하면 기본값은 스냅샷 크기입니다. 스냅샷 크기보다 크거나 같은 크기를 지정할 수 있어요. gp2와 gp3 볼륨 유형의 유효 범위는 1-16,384, io1과 io2는 4-16,384, st1과 sc1은 125-16,384, standard는 1-1,024입니다.
- snapshotId — 유형: String / 필수: 아니요. Amazon ECS가 연결용 새 볼륨을 만드는 데 사용하는 기존 Amazon EBS 볼륨 스냅샷의 ID. snapshotId 또는 sizeInGiB 중 하나를 지정해야 합니다.
- volumeInitializationRate — 유형: Integer / 필수: 아니요. 연결용 새 볼륨을 만들기 위해 기존 Amazon EBS 볼륨 스냅샷에서 데이터를 가져오는 속도(MiB/s). snapshotId를 지정한 경우에만 지정할 수 있습니다.
- iops — 유형: Integer / 필수: 아니요. 초당 I/O 작업 수(IOPS). gp3, io1, io2 볼륨의 경우 볼륨에 프로비저닝된 IOPS 수를 나타냅니다. gp2 볼륨의 경우 기준 성능과 볼륨이 버스팅용 I/O 크레딧을 축적하는 속도를 나타냅니다. io1과 io2에는 이 파라미터가 필요합니다. gp2, st1, sc1, standard 볼륨에서는 지원되지 않습니다. gp3의 유효 값 범위는 3,000~~16,000, io1과 io2는 100~~64,000입니다.
- throughput — 유형: Integer / 필수: 아니요. 서비스가 유지하는 태스크에 연결된 볼륨에 프로비저닝할 처리량. 중요: 이 파라미터는 gp3 볼륨에서만 지원됩니다.
- roleArn — 유형: String / 필수: 예. Amazon ECS가 태스크를 위한 Amazon EBS 리소스를 관리할 권한을 제공하는 인프라 AWS IAM 역할의 ARN. 자세한 내용은 Amazon ECS 인프라 IAM 역할(Amazon ECS infrastructure IAM role)을 참고하세요.
- tagSpecifications — 유형: Object / 필수: 아니요. 각 Amazon EBS 볼륨에 적용할 태그 사양.
  - resourceType — 유형: String / 필수: 예 / 유효 값: volume. 생성 시 태그할 리소스 유형.
  - tags — 유형: 객체 배열 / 필수: 아니요. 볼륨을 분류하고 구성하는 데 도움이 되는 메타데이터. 각 태그는 사용자가 정의하는 키와 선택적 값으로 구성됩니다. AmazonECSCreated와 AmazonECSManaged는 Amazon ECS가 대신 추가하는 예약 태그이므로 최대 48개의 사용자 태그를 지정할 수 있습니다. 볼륨이 삭제되면 태그도 삭제됩니다.
    - key — 유형: String / 길이 제약: 최소 1, 최대 128 / 필수: 아니요.
    - value — 유형: String / 길이 제약: 최소 0, 최대 256 / 필수: 아니요.
- propagateTags — 유형: String / 유효 값: TASK_DEFINITION | SERVICE | NONE / 필수: 아니요. 태스크 정의 또는 서비스의 태그를 볼륨으로 복사할지 여부. NONE이 지정되거나 값이 지정되지 않으면 태그가 복사되지 않습니다.
- fileSystemType — 유형: String / 유효 값: xfs | ext3 | ext4 | NTFS / 필수: 아니요. 볼륨의 파일 시스템 유형. 볼륨의 파일 시스템 유형은 볼륨에서 데이터가 저장되고 검색되는 방식을 결정합니다. 스냅샷에서 만든 볼륨의 경우 스냅샷이 만들어졌을 때 볼륨이 사용하고 있던 것과 같은 파일 시스템 유형을 지정해야 합니다. 파일 시스템 유형이 일치하지 않으면 태스크가 시작되지 않습니다. Linux의 유효 값은 xfs, ext3, ext4이며, Linux 태스크에 연결된 볼륨의 기본값은 XFS입니다. Windows의 유효 값은 NTFS이며, Windows 태스크에 연결된 볼륨의 기본값은 NTFS입니다.