Amazon ECS 작업에 환경 변수를 전달할 때 발생하는 문제를 해결하려면 어떻게 해야 합니까?

6분 분량

Amazon Elastic Container Service(Amazon ECS) 작업에 환경 변수를 전달할 때 발생하는 문제를 해결하고 싶습니다.

간략한 설명

작업 내에 환경 변수나 민감한 데이터를 전달하면 구성을 기반으로 다음 오류 중 하나가 발생할 수 있습니다.

AWS Secrets Manager

"ResourceInitializationError error" or "AccessDenied error on Amazon Elastic Compute Cloud (Amazon EC2)".

이러한 문제를 해결하려면 Amazon ECS의 AWS Secrets Manager 시크릿 데이터와 관련된 문제를 해결하려면 어떻게 해야 합니까?를 참조하십시오.

Amazon Elastic Block Store(Amazon EBS) 볼륨 또는 사이드카

"ECS was unable to assume the configured ECS Infrastructure Role 'arn:aws:iam::111122223333:role/ecsInfrastructureRole'. Please verify that the role being passed has the proper trust relationship with Amazon ECS" 또는 "ECS timed out while configuring the EBS volume attachment to your Task."

이러한 문제를 해결하려면 Amazon ECS 작업으로의 Amazon EBS 볼륨 연결에 대한 상태 이유를 참조하십시오.

Amazon Simple Storage Service(Amazon S3)

"ResourceInitializationError: failed to download env files: file download command: non empty error stream".

이 문제를 해결하려면 다음 해결 단계를 완료하십시오.

AWS Systems Manager의 기능인 Parameter Store

"Fetching secret data from SSM Parameter Store in region: AccessDeniedException(액세스 거부 예외): User: arn:aws:sts::123456789:assumed-role/ecsExecutionRole/f512996041234a63ac354214 is not authorized to perform: ssm:GetParameters on resource: arn:aws:ssm:ap-south-1:12345678:parameter/status code: 400, request id: e46b40ee-0a38-46da-aedd-05f23a41e861". Or, "ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed: unable to retrieve secrets from ssm: service call has been retried 5 time(s): RequestCanceled".

이러한 문제를 해결하려면 다음 해결 단계를 완료하십시오.

참고: 보안 모범 사례에 따르면 Secrets Manager 시크릿 또는 Parameter Store 파라미터에 민감한 데이터를 저장해야 합니다.

해결 방법

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하면 AWS CLI의 오류 해결을 참조하십시오. 또한 최신 AWS CLI 버전을 사용하고 있는지 확인하십시오.

문제의 원인 파악

Amazon ECS 클러스터 리소스가 위치한 AWS 리전과 동일한 리전에 AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용합니다. 또한 가장 최근에 실패한 작업 ID를 사용하십시오. 실패한 작업이 Amazon ECS 서비스의 일부인 경우, 서비스에서 가장 최근에 실패한 작업을 사용합니다. 실패한 작업은 자동화 중에 ECS:DescribeTasks에 표시되어야 합니다. 기본적으로 중지된 ECS 작업은 중지됨 상태가 된 후 1시간 동안 표시됩니다.

자동화 출력에 따라 다음 수동 문제 해결 단계 중 하나를 사용합니다.

사용자의 Amazon ECS 작업 실행 역할에 필요한 IAM 권한이 없습니다.

Parameter Store 또는 Secrets Manage에서 환경 변수를 사용하는 경우, 다음 API 호출에 대한 AWS CloudTrail 이벤트를 검토하십시오.

Parameter Store의 경우 GetParameters
Secrets Manager의 경우 GetSecretValue

작업 실행 역할에 대해 AccessDenied 오류가 발생하는 경우 필요한 권한을 역할에 인라인 정책으로 직접 추가해야 합니다. 사용자 지정 관리형 정책을 생성하여 Amazon ECS 작업 실행 역할에 추가할 수도 있습니다.

S3 버킷을 사용하여 환경 변수를 .env 파일로 저장하는 경우 Amazon S3에 대해 필요한 권한을 작업 실행 역할에 추가합니다.

네트워크 구성에 문제가 있음

작업이 프라이빗 서브넷에 있는 경우 다음 구성을 확인합니다.

작업 또는 서비스의 보안 그룹이 포트 443에서 아웃바운드 트래픽을 허용합니다.
NAT 게이트웨이를 사용하는 경우 작업에 NAT 게이트웨이에 대한 기본 경로가 있어야 합니다.
작업은 Secrets Manager, Parameter Store 또는 Amazon S3에 필요한 가상 프라이빗 클라우드(VPC) 엔드포인트를 사용합니다.

telnet 명령을 사용하여 Systems Manager, Secrets Manager 또는 Amazon S3 엔드포인트에 대한 연결을 확인합니다.

추가로 다음 VPC 엔드포인트 구성을 확인하십시오.

사용자 VPC 엔드포인트의 보안 그룹은 포트 443에서 작업 또는 서비스로부터의 아웃바운드 트래픽을 허용합니다.
네트워크 액세스 제어 목록(ACL)이 포트 443에서 아웃바운드 트래픽을 허용합니다.
VPC 엔드포인트를 올바른 VPC와 연결합니다.
DNS 호스트 이름과 DNS 확인 VPC 속성을 활성화했습니다.

Amazon ECS 작업이 퍼블릭 서브넷에 있는 경우 다음 구성을 확인합니다.

작업에 대해 퍼블릭 IP 주소를 활성화했습니다.
VPC의 보안 그룹이 포트 443에서 인터넷으로의 아웃바운드 액세스를 허용합니다.
네트워크 ACL이 서브넷과 인터넷 간의 모든 인바운드 및 아웃바운드 트래픽을 허용합니다.

애플리케이션에서 환경 변수를 읽을 수 없습니다.

작업 컨테이너에 올바른 환경 변수가 채워져 있는지 확인하려면 ECS Exec을 사용하여 컨테이너의 모든 환경 변수를 나열합니다. ECS Exec을 활성화한 후 다음 명령을 실행하여 컨테이너와 상호 작용합니다.

aws ecs execute-command --cluster cluster-name \
    --task task-id \
    --container container-name \
    --interactive \
    --command "/bin/sh"

참고: cluster-name을 클러스터 이름으로, task-id를 작업 ID로, container-name을 컨테이너 인스턴스 이름으로 바꾸십시오.

출력 예시:

The Session Manager plugin was installed successfully. Use the AWS CLI to start a session.


Starting session with SessionId: ecs-execute-command-hlei32fctyur2bn63rhe2uraaq
sh-5.2#

그런 다음 ** env ** 명령을 실행하여 모든 환경 변수를 나열합니다.

sh-5.2# env

출력 예시:

sh-5.2# env
AWS_EXECUTION_ENV=AWS_ECS_FARGATE
AWS_DEFAULT_REGION=us-east-1
AWS_REGION=us-east-1
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
_=/usr/bin/env

Amazon EC2 시작 유형을 사용하는 경우 Docker exec 명령을 사용하여 사용자의 컨테이너와 상호 작용할 수도 있습니다. Docker exec를 사용하려면 다음 단계를 완료합니다.

사용자의 작업이 실행 중인 컨테이너 인스턴스에 연결합니다.
다음 Docker 명령을 실행하여 컨테이너 ID를 찾습니다.
```
docker container ps
```
컨테이너를 열려면 다음 Docker 명령을 실행합니다.
```
docker exec -it example-container-id bash
```
참고: example-container-id를 컨테이너 ID로 바꾸십시오. 또한 컨테이너의 기본 셸을 기반으로 셸을 선택합니다.
컨테이너에서 env 명령을 실행하여 모든 환경 변수를 나열합니다.

작업 정의 또는 .env 파일에서 정의한 환경 변수가 변수 목록에 있는지 확인합니다.

컨테이너 정의에 있는 변수 형식이 잘못되었습니다.

컨테이너 정의에서 환경 변수를 정의할 때는 환경 변수를 키-값 쌍 개체로 정의해야 합니다.

"environment": [
    {
        "name": "variable",    
        "value": "value"
    }
]

.env 파일에서 환경 변수를 정의할 때에도 이 형식을 사용해야 합니다.

작업에서 환경 변수를 자동으로 새로 고치지 않음

.env 파일 또는 시크릿에서 업데이트한 실행 중인 컨테이너의 환경 변수는 작업에서 자동으로 새로 고쳐지지 않습니다.

업데이트된 환경 변수를 컨테이너 인스턴스에 추가하려면 다음 update-service 명령을 실행합니다.

aws ecs update-service --cluster example-cluster --service example-service --force-new-deployment

참고: example-cluster를 클러스터 이름으로, example-service를 서비스 이름으로 바꾸십시오.

컨테이너 정의에서 환경 변수를 사용하는 경우 새 작업 정의를 생성하여 환경 변수를 업데이트해야 합니다. 이후 다음 update-service 명령을 실행하고 새 작업 정의를 사용하여 새 작업을 생성하거나 Amazon ECS 서비스를 업데이트합니다.

aws ecs update-service --cluster example-cluster --service example-service --task-definition family:revision

참고: example-cluster를 클러스터 이름으로, example-service를 서비스 이름으로, family:revision을 새 작업 정의로 바꾸십시오.

작업에 환경 변수를 전달할 때 Amazon ECS는 다음 구성을 사용합니다.

컨테이너 정의에서 environment 파라미터를 사용하는 환경 변수는 환경 파일의 변수보다 우선합니다.
여러 환경 파일을 지정하고 해당 파일에서 같은 변수를 사용하는 경우 파일은 입력 순서대로 처리됩니다. Amazon ECS는 변수의 첫 번째 값을 사용하고, 중복된 변수의 후속 값은 무시합니다. 고유한 변수 이름을 사용하는 것이 가장 좋습니다.
환경 파일을 컨테이너 재정의로 지정하면 Amazon ECS는 해당 파일을 사용하고 컨테이너 정의에 있는 다른 환경 파일은 무시합니다.
환경 변수는 /proc/1/environ 파일에서 컨테이너의 PID 1 프로세스에 사용할 수 있습니다. 컨테이너가 여러 프로세스나 init 프로세스(예: 래퍼 스크립터 또는 수퍼바이저드)를 실행 중이면 PID 1이 아닌 프로세스에서는 환경 변수를 사용할 수 없습니다.