Amazon ECS 파라미터 사용 - Amazon Elastic Container Service

Amazon ECS 파라미터 사용

ecs-cli compose 또는 ecs-cli compose service 명령을 사용해 Amazon ECS 태스크 및 서비스를 관리할 경우, Amazon ECS 태스크 정의에는 Docker compose 파일의 필드와 일치하지 않는 필드도 있습니다. --ecs-params 플래그가 있는 ECS 파라미터 파일을 사용하면 해당 값을 지정할 수 있습니다. 기본적으로 이 명령은 현재 디렉터리에서 ecs-params.yml이라는 ECS 파라미터 파일을 찾습니다. 하지만 --ecs-params 옵션을 사용하여 다른 파일 이름 또는 ECS 파라미터 파일 경로를 지정할 수도 있습니다.

현재 이 파일은 다음 스키마를 지원합니다.

version: 1 task_definition: ecs_network_mode: string task_role_arn: string task_execution_role: string task_size: cpu_limit: string mem_limit: string pid_mode: string ipc_mode: string services: <service_name>: essential: boolean depends_on: - container_name: string condition: string repository_credentials: credentials_parameter: string cpu_shares: integer mem_limit: string mem_reservation: string gpu: string init_process_enabled: boolean healthcheck: test: ["CMD", "curl -f http://localhost"] interval: string timeout: string retries: integer start_period: string firelens_configuration: type: string options: enable-ecs-log-metadata: boolean secrets: - value_from: string name: string docker_volumes: - name: string scope: string autoprovision: boolean driver: string driver_opts: string string: string labels: string: string efs_volumes: - name: string filesystem_id: string root_directory: string transit_encryption: string transit_encryption_port: int64 access_point: string iam: string placement_constraints: - type: string expression: string run_params: network_configuration: awsvpc_configuration: subnets: - subnet_id1 - subnet_id2 security_groups: - secgroup_id1 - secgroup_id2 assign_public_ip: ENABLED task_placement: strategy: - type: string field: string constraints: - type: string expression: string service_discovery: container_name: string container_port: integer private_dns_namespace: vpc: string id: string name: string description: string public_dns_namespace: id: string name: string service_discovery_service: name: string description: string dns_config: type: string ttl: integer healthcheck_custom_config: failure_threshold: integer

task_definition 아래에 나열된 필드가 Amazon ECS 태스크 정의에 포함할 필드에 해당합니다.

  • ecs_network_mode - ECS 태스크 정의의 networkMode에 해당합니다. 지원되는 값은 none, bridge, host 또는 awsvpc입니다. 기본값은 bridge입니다. 태스크 네트워킹을 사용하는 경우에는 이 필드를 awsvpc로 설정해야 합니다. 자세한 내용은 네트워크 모드 섹션을 참조하세요.

  • task_role_arn - 태스크와 연결할 IAM 역할의 이름 또는 정식 ARN입니다. 자세한 내용은 태스크 역할 섹션을 참조하세요.

  • task_execution_role - 태스크 실행 역할의 이름 또는 정식 ARN입니다. 태스크에서 CloudWatch에 컨테이너 애플리케이션 로그를 저장할 수 있게 하거나 Amazon ECR에서 컨테이너 이미지를 가져올 수 있게 하려는 경우에 필수 필드입니다. 자세한 내용은 Amazon ECS 태스크 실행 IAM 역할 섹션을 참조하세요.

  • task_size - 태스크의 CPU 및 메모리 값입니다. EC2 시작 유형을 사용할 경우, 이 필드는 선택 사항이며 아무 값이나 사용할 수 있습니다. cpu Fargate 시작 유형을 사용하는 경우 이 필드는 필수 사항이며, 및 memory 파라미터에 대해 다음 값 중 하나를 사용해야 합니다.

    CPU 값 메모리 값(MiB)
    256(.25 vCPU) 512(0.5GB), 1,024(1GB), 2,048(2GB)
    512(.5 vCPU) 1,024(1GB), 2,048(2GB), 3,072(3GB), 4,096(4GB)
    1024(1 vCPU) 2,048(2GB), 3,072(3GB), 4,096(4GB), 5,120(5GB), 6,144(6GB), 7,168(7GB), 8,192(8GB)
    2048(2 vCPU) 4,096(4GB)~16,384(16 GB)(1,024(1GB) 증분)
    4096(4 vCPU) 8,192(8GB)~30,720(30GB)(1,024(1GB) 증분)

    자세한 내용은 태스크 크기 섹션을 참조하세요.

  • pid_mode - 해당 태스크의 컨테이너에 사용할 프로세스 네임스페이스입니다. 유효한 값은 host 또는 task입니다. host를 지정하면 동일한 컨테이너 인스턴스에서 host PID 모드를 지정한 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 호스트 Amazon EC2 인스턴스와 공유합니다. task을 지정하면 지정된 태스크 내 모든 컨테이너가 동일한 프로세스 네임스페이스를 공유합니다. 값을 지정하지 않을 경우, 기본값은 프라이빗 네임스페이스입니다. 자세한 내용은 Docker 실행 참조PID 설정을 확인하세요.

    host PID 모드를 사용하는 경우, 원치 않는 프로세스 네임스페이스 노출이 발생할 위험이 커진다는 점에 유의하세요. 자세한 내용은 Docker 보안을 참조하세요.

    참고

    이 파라미터는 Windows 컨테이너 또는 Fargate 시작 유형을 사용하는 태스크에 대해서는 지원되지 않습니다.

  • ipc_mode - 해당 태스크의 컨테이너에 사용할 IPC 리소스 네임스페이스입니다. 유효한 값은 host, task 또는 none입니다. host를 지정하면 동일한 컨테이너 인스턴스에서 host IPC 모드를 지정한 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 호스트 Amazon EC2 인스턴스와 공유합니다. task을 지정하면 지정된 태스크 내 모든 컨테이너가 동일한 IPC 리소스를 공유합니다. none이 지정된 경우, 태스크 컨테이너 내에 있는 IPC 리소스는 프라이빗이며, 태스크 또는 컨테이너 인스턴스의 다른 컨테이너와 공유되지 않습니다. 값을 지정하지 않을 경우, IPC 리소스 네임스페이스 공유는 컨테이너 인스턴스의 Docker 데몬 설정에 따라 달라집니다. 자세한 내용은 Docker 실행 참조IPC 설정을 확인하세요.

    host IPC 모드를 사용하는 경우, 원치 않는 IPC 네임스페이스 노출이 발생할 위험이 커진다는 점에 유의하세요. 자세한 내용은 도커 보안을 참조하세요.

    해당 태스크 내 컨테이너에 대해 systemControls을 사용하여 네임스페이스가 있는 커널 파라미터를 설정하는 경우, IPC 리소스 네임스페이스에 다음 사항이 적용됩니다. 자세한 내용은 Amazon Elastic Container Service 개발자 안내서에서 시스템 제어 섹션을 참조하세요.

    • host IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 관련 systemControls는 지원되지 않습니다.

    • task IPC 모드를 사용하는 태스크의 경우, IPC 네임스페이스 관련 systemControls가 태스크 내 모든 컨테이너에 적용됩니다.

    참고

    이 파라미터는 Windows 컨테이너 또는 Fargate 시작 유형을 사용하는 태스크에 대해서는 지원되지 않습니다.

  • services - Docker compose 파일에 나열된 서비스에 해당합니다. service_name은 실행할 컨테이너 이름과 일치합니다. 필드는 컨테이너 정의에 병합됩니다.

    • essential - 컨테이너의 essential 파라미터가 true로 표시된 경우 해당 컨테이너가 어떤 이유로든 실패 또는 중지하는 경우 태스크의 일부인 다른 모든 컨테이너도 중지합니다. 컨테이너의 essential 파라미터가 false로 표시된 경우에는 해당 컨테이너의 실패가 태스크의 나머지 컨테이너에 영향을 주지 않습니다. 기본값은 true입니다.

      모든 태스크에는 하나 이상의 필수 컨테이너가 있어야 합니다. 애플리케이션이 여러 컨테이너로 구성되는 경우 동일한 용도로 사용되는 컨테이너를 구성 요소로 그룹화하고 각 구성 요소를 서로 다른 태스크 정의로 분리해야 합니다.

    • depends_on – 이 파라미터는 dependsOn 태스크 정의 파라미터에 매핑됩니다. 컨테이너 종속성 목록을 지정하는 데 사용하며, 이 목록은 종속된 컨테이너를 조건에 따라 시작하거나 여러 컨테이너 사용 시 시작 순서를 정할 때 사용할 수 있습니다. 태스크 정의 예제는 예: 컨테이너 종속성 섹션을 참조하세요.

    • repository_credentials - 프라이빗 리포지토리를 사용하여 이미지를 풀링할 경우 repository_credentials을 사용하여 프라이빗 리포지토리 자격 증명이 있는 암호 이름의 AWS Secrets Manager 암호 ARN을 credential_parameter로 지정할 수 있습니다. 자세한 내용은 태스크에 대한 프라이빗 레지스트리 인증 섹션을 참조하세요.

    • cpu_shares – 이 파라미터는 Docker compose 파일 참조cpu_shares에 매핑됩니다. Docker compose 버전 3을 사용하는 경우 이 필드는 선택 사항이며 compose 파일 대신에 ECS 파라미터 파일에 지정해야 합니다. Docker compose 버전 2에서는 이 필드를 compose 파일 또는 ECS 파라미터 파일에 지정할 수 있습니다. ECS 파라미터 파일에 지정하면 이 값이 compose 파일에 있는 값을 재정의합니다.

    • mem_limit – 이 파라미터는 Docker compose 파일 참조mem_limit에 매핑됩니다. Docker compose 버전 3을 사용하는 경우 이 필드는 선택 사항이며 compose 파일 대신에 ECS 파라미터 파일에 지정해야 합니다. Docker compose 버전 2에서는 이 필드를 compose 파일 또는 ECS 파라미터 파일에 지정할 수 있습니다. ECS 파라미터 파일에 지정하면 이 값이 compose 파일에 있는 값을 재정의합니다.

    • mem_reservation – 이 파라미터는 Docker compose 파일 참조mem_reservation에 매핑됩니다. Docker compose 버전 3을 사용하는 경우 이 필드는 선택 사항이며 compose 파일 대신에 ECS 파라미터 파일에 지정해야 합니다. Docker compose 버전 2에서는 이 필드를 compose 파일 또는 ECS 파라미터 파일에 지정할 수 있습니다. ECS 파라미터 파일에 지정하면 이 값이 compose 파일에 있는 값을 재정의합니다.

    • gpu - Amazon ECS 컨테이너 에이전트가 컨테이너에 대해 예약하는 실제 GPU 수입니다. 이 파라미터는 태스크 정의의 resourceRequirements 필드에 매핑됩니다. 자세한 내용은 Amazon ECS에서 GPU 사용 섹션을 참조하세요.

    • init_process_enabled 이 파라미터를 사용하면 신호를 전달하고 프로세스의 결과를 받아들이는 컨테이너 내에서 init 프로세스를 실행할지를 지정합니다. 이 파라미터는 docker run에 대한 --init 옵션에 매핑됩니다.

      이 파라미터를 사용하려면 컨테이너 인스턴스에서 Docker 원격 API 버전 1.25 이상을 사용해야 합니다.

    • healthcheck – 이 파라미터는 Docker compose 파일 참조healthcheck에 매핑됩니다. test 필드는 command로 지정될 수도 있으며 문자열 또는 목록이어야 합니다. 목록인 경우 첫 번째 항목은 NONE, CMD 또는 CMD-SHELL이어야 합니다. 문자열인 경우 CMD-SHELL 다음에 해당 문자열을 지정하는 것과 동일합니다. interval, timeoutstart_period 필드는 문자열 형식의 기간으로 지정됩니다. 예: 2.5s, 10s, 1m30s, 2h23m 또는 5h34m56s.

      참고

      단위를 지정하지 않으면 초가 사용됩니다. 예를 들어, 10s 또는 10을 지정할 수 있습니다.

    • firelens_configuration - 이 파라미터를 사용하면 awsfirelens 로그 드라이버를 사용하여 로그 구성을 정의할 수 있습니다. 이 파라미터는 로그 스토리지 및 분석을 위해 AWS 서비스 또는 파트너 대상으로 로그를 라우팅하는 데 사용됩니다. 자세한 내용은 사용자 지정 로그 라우팅 섹션을 참조하세요.

      • type - 사용할 로그 라우터 유형입니다. 지원되는 옵션은 fluentbitfluentd입니다.

      • options - 사용할 로그 라우터 옵션입니다. 이 옵션은 로그를 라우팅하는 대상에 따라 달라집니다. 자세한 내용은 사용자 지정 로그 라우팅 섹션을 참조하세요.

    • secrets - 이 파라미터를 사용하면 중요한 데이터를 AWS Systems Manager 파라미터 스토어 파라미터에 저장한 다음, 컨테이너 정의에서 해당 파라미터를 참조하여 컨테이너에 중요한 데이터를 주입할 수 있습니다. 자세한 내용은 민감한 데이터를 컨테이너에 전달 섹션을 참조하세요.

      • value_from - 이것은 컨테이너에 노출되는 AWS Systems Manager 파라미터 스토어 ARN 또는 이름입니다. Systems Manager 파라미터 스토어 파라미터가 현재 실행 중인 태스크와 동일한 리전에 있을 경우, 해당 암호의 전체 ARN 또는 이름을 사용할 수 있습니다. 파라미터가 다른 리전에 있다면 전체 ARN을 지정해야 합니다.

      • name - 컨테이너에서 환경 변수로 설정할 값입니다.

  • docker_volumes - 이 파라미터를 사용해 Docker 볼륨을 생성할 수 있습니다. name 키가 필요하며, scope, autoprovision, driver, driver_optslabels는 태스크 정의의 Docker 볼륨 구성 필드에 해당합니다. 자세한 내용은 Amazon Elastic Container Service API 참조DockerVolumeConfiguration을 참조하세요. docker_volumes 키로 정의된 볼륨은 compose 파일에 지정되어 있지 않아도 이름으로 compose 파일에서 참조할 수 있습니다.

  • efs_volumes - 이 파라미터를 사용하면 Amazon EFS 파일 시스템을 탑재할 수 있습니다. namefilesystem_id 키가 필요합니다.

    • name - 볼륨의 이름입니다. 최대 255개의 문자(대문자 및 소문자), 숫자, 하이픈 및 밑줄이 허용됩니다. 이 이름은 컨테이너 정의 mountPoints의 sourceVolume 파라미터에서 참조됩니다.

    • filesystem_id - 탑재 대상을 생성할 파일 시스템의 ID입니다.

    • root_directory - 호스트 내의 루트 디렉터리로 탑재할 Amazon EFS 파일 시스템 내 디렉터리입니다. 이 파라미터가 생략되면 Amazon EFS 볼륨의 루트가 사용됩니다. /를 지정하면 이 파라미터를 생략하는 것과 동일한 효과가 있습니다.

    • transit_encryption - Amazon ECS 호스트와 Amazon EFS 서버 간에 전송 중인 Amazon EFS 데이터에 대해 암호화를 활성화할지 여부입니다. 이 파라미터는 IAM이 활성화되어 있거나 액세스 포인트 ID가 지정된 경우에 필요합니다. 유효한 값은 ENABLED or DISABLED. DISABLED가 기본값입니다.

    • transit_encryption_port - Amazon ECS 호스트와 Amazon EFS 서버 간에 암호화된 데이터를 전송할 때 사용할 포트입니다. 전송 중 데이터 암호화 포트를 지정하지 않으면 Amazon EFS 탑재 헬퍼가 사용하는 포트 선택 전략이 사용됩니다. 이 파라미터는 transit_encryption이 지정된 경우에[만 필요합니다.

    • access_point - 사용할 Amazon EFS 액세스 포인트 ID입니다. 액세스 포인트가 지정된 경우 루트 디렉터리 값은 액세스 포인트에 대해 설정된 디렉터리를 기준으로 합니다. 지정된 경우 transit_encryption이 활성화되어야 합니다.

    • iam - Amazon EFS 파일 시스템을 탑재할 때 태스크 정의에 정의된 Amazon ECS 태스크 IAM 역할을 사용할지 여부입니다. 활성화된 경우 EFSVolumeConfiguration에서 transit encryption이 활성화되어야 합니다. 유효한 값은 ENABLED or DISABLED. DISABLED가 기본값입니다.

  • placement_constraints - 이 파라미터를 이용해 태스크 정의 내에서 태스크 배치에 대한 제약 목록을 지정할 수 있습니다. 자세한 내용은 Amazon Elastic Container Service API 참조TaskDefinitionPlacementConstraint를 참조하세요. EC2 시작 유형을 사용하는 경우에는 이 필드가 선택사항입니다. Fargate 시작 유형을 사용하는 경우 지원되지 않습니다.

run_params 아래에 나열된 필드에는 compose up(RunTask) 및 compose service up(CreateService)과 같이 태스크 정의와 구체적으로 연결되지 않은 API 호출에서 선택적으로 필요한 값을 입력합니다.

  • network_configuration - ecs_network_modeawsvpc를 지정한 경우 필수 필드입니다. 다음과 같은 하위 필드가 있는 중첩 파라미터 awsvpc_configuration을 사용합니다.

    • subnets - 태스크와 연결하는 데 사용되는 서브넷 ID의 목록입니다. 여기 나열된 서브넷이 태스크를 시작할 인스턴스와 동일한 VPC 및 동일한 가용 영역에 있어야 합니다.

    • security_groups - 태스크와 연결할 보안 그룹 ID의 목록입니다. 여기 나열된 보안 그룹이 태스크를 시작할 인스턴스와 동일한 VPC에 있어야 합니다.

    • assign_public_ip - 이 필드에 사용할 수 있는 값은 ENABLED 또는 DISABLED입니다. 이 필드는 Fargate 시작 유형을 사용하는 태스크에서만 사용됩니다. EC2 시작 유형이고 태스크 네트워킹을 사용하는 태스크에 이 필드가 있는 경우, 요청은 실패합니다.

  • task_placement - 이 파라미터를 사용하여 태스크 배치 옵션을 지정할 수 있습니다. EC2 시작 유형을 사용하는 경우에는 이 필드가 선택사항입니다. Fargate 시작 유형을 사용하는 경우 지원되지 않습니다. 자세한 내용은 Amazon ECS 작업 배치 섹션을 참조하세요.

    그 하위 필드는 다음과 같습니다.

    • strategy - 키가 두 개인 객체 목록입니다. 유효한 키는 typefield입니다.

      • type - 유효한 값은 random, binpack 또는 spread입니다. random가 지정되지 않은 경우, field 키는 제공하면 안 됩니다.

      • field - 유효 값은 전략 유형에 따라 다릅니다.

        • spread는 유효한 값이 instanceId, host 또는 속성 키-값 쌍(예: attribute:ecs.instance-type =~ t2.*)입니다.

        • binpack은 유효 값이 cpu 또는 memory입니다.

    • constraints - 키가 두 개인 객체 목록입니다. 유효한 키는 typeexpression입니다.

      • type - 유효 값은 distinctInstancememberOf입니다. distinctInstance가 지정되지 않은 경우, expression 키는 제공하면 안 됩니다.

      • expression - 유형이 memberOf일 경우, 유효한 값은 속성 또는 태스크 그룹의 키-값 쌍(예: task:group == databases 또는 attribute:color =~ green)입니다.

  • service_discovery - 이 파라미터를 사용하면 서비스 태스크에 대한 DNS 항목을 관리하기 위해 Amazon Route 53 자동 이름 지정 API 태스크를 사용하여 Amazon ECS 서비스 검색을 구성할 수 있습니다. 자세한 내용은 자습서: Amazon ECS CLI로 서비스 검색을 사용하는 Amazon ECS 서비스 생성 섹션을 참조하세요.