Amazon ECS 태스크에 환경 변수를 전달할 때 발생하는 문제를 해결하려면 어떻게 해야 합니까?
Amazon Elastic Container Service(Amazon ECS) 태스크에 환경 변수를 전달할 때 발생하는 문제를 해결하고 싶습니다.
간략한 설명
다음 방법 중 하나를 사용하여 Amazon ECS 태스크 내에 환경 변수를 전달할 수 있습니다.
- 변수를 Amazon Simple Storage Service(Amazon S3) 버킷 내에 environmentFiles 객체로 전달합니다.
- 변수를 AWS Systems Manager Parameter Store에 저장합니다.
- ECS 태스크 정의에 변수를 저장합니다.
- 변수를 AWS Secrets Manager 내에 저장합니다.
참고: Parameter Store 또는 Secrets 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
-또는-
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:
ResourceInitializationError 오류
-또는-
Amazon Elastic Compute Cloud(Amazon EC2)에서 AccessDenied 오류
이러한 오류를 해결하려면 Amazon ECS에서 AWS Secrets Manager 보안 정보와 관련된 문제를 해결하려면 어떻게 해야 합니까?를 참조하세요.
Amazon S3:
ResourceInitializationError: failed to download env files: file download command: non empty error stream
환경 변수를 Amazon ECS 태스크에 전달할 때 다음과 같은 이유로 인해 문제가 발생할 수 있습니다.
- Amazon ECS 태스크 실행 역할에 필요한 AWS Identity and Management(IAM) 권한이 없습니다.
- 네트워크 구성에 문제가 있습니다.
- 애플리케이션이 환경 변수를 읽을 수 없습니다.
- 컨테이너 정의의 변수 형식이 올바르지 않습니다.
- 환경 변수가 자동으로 새로 고쳐지지 않습니다.
해결 방법
Amazon ECS 태스크 실행 역할에 필요한 IAM 권한이 없는 경우
Parameter Store 또는 Secrets Manage 내에서 환경 변수를 사용하는 경우 다음 API 호출 중 하나에 대한 AWS CloudTrail 이벤트를 검토합니다.
Parameter Store의 GetParameters
-또는-
Secrets Manager의 GetSecretValue
CloudTrail 이벤트에서 태스크 실행 역할에 대한 AccessDenied 오류가 발견되면 필요한 권한을 ECS 태스크 실행 IAM 역할에 인라인 정책으로 수동으로 추가합니다. 고객 관리형 정책을 생성하고 ECS 태스크 실행 역할에 정책을 추가할 수도 있습니다.
Secrets Manager를 사용하는 경우 태스크 실행 역할에 다음 권한을 포함시킵니다.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "kms:Decrypt" ], "Resource": [ "arn:aws:secretsmanager:example-region:11112222333344445555:secret:example-secret", "arn:aws:kms:example-region:1111222233334444:key/example-key-id" ] } ] }
Parameter Store를 사용하는 경우 태스크 실행 역할에 다음 권한을 포함시킵니다.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetParameters", "secretsmanager:GetSecretValue", "kms:Decrypt" ], "Resource": [ "arn:aws:ssm:example-region:1111222233334444:parameter/example-parameter", "arn:aws:secretsmanager:example-region:1111222233334444:secret:example-secret", "arn:aws:kms:example-region:1111222233334444:key/example-key-id" ] } ] }
S3 버킷을 사용하여 환경 변수를 .env 파일로 저장하려면 태스크 실행 역할에 인라인 정책으로 다음 권한을 수동으로 추가합니다.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::example-bucket/example-folder/example-env-file" ] }, { "Effect": "Allow", "Action": [ "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::example-bucket" ] } ] }
네트워크 구성에 문제가 있는 경우
ECS 태스크가 프라이빗 서브넷에 있는 경우 다음을 확인합니다.
- 태스크 또는 서비스의 보안 그룹이 포트 443에서 송신 트래픽을 허용하는지 확인합니다.
- VPC 엔드포인트를 사용하는 경우 네트워크 ACL이 포트 443에서 송신 트래픽을 허용하는지 확인합니다.
- telnet 명령을 사용하여 Systems Manager/Secrets Manager 및 Amazon S3 엔드포인트에 대한 연결을 확인합니다.
- NAT 게이트웨이를 사용하는 경우 태스크에 NAT 게이트웨이에 대한 기본 경로가 있는지 확인합니다.
- 태스크에 대한 VPC 엔드포인트를 정의했는지 확인합니다. VPC 엔드포인트를 정의한 경우 Secrets Manager/Systems Manager Parameter Store 및 S3에 필요한 VPC 엔드포인트가 있는지 확인합니다.
- VPC 엔드포인트를 사용하는 경우 다음 사항을 확인합니다.
- VPC 엔드포인트의 보안 그룹은 포트 443에서 태스크 또는 서비스의 송신 트래픽을 허용합니다.
- VPC 엔드포인트가 올바른 VPC와 연결되어 있습니다.
- VPC 속성 enableDnsHostnames 및 enableDnsSupport가 활성화되어 있습니다.
ECS 태스크가 퍼블릭 서브넷에 있는 경우 다음을 확인합니다.
- 태스크에 퍼블릭 IP 주소가 활성화되어 있는지 확인합니다.
- VPC의 보안 그룹이 포트 443에서 인터넷으로 나가는 아웃바운드 액세스 권한이 있는지 확인합니다.
- 네트워크 ACL 구성에서는 모든 트래픽이 서브넷에서 인터넷으로 들어오고 나가는 것을 허용해야 합니다.
애플리케이션이 환경 변수를 읽을 수 없는 경우
태스크 컨테이너 내에 올바른 환경 변수가 채워져 있는지 확인하려면 다음을 수행합니다.
- 컨테이너 내부에 노출된 모든 환경 변수를 나열합니다.
- 이 목록에 태스크 정의 또는 S3의 .env 파일에 정의한 환경 변수가 포함되어 있는지 확인합니다.
Amazon EC2 또는 AWS Fargate 시작 유형을 사용하는 경우 ECS Exec 기능을 사용하는 것이 가장 좋습니다. 이 기능을 사용하여 Amazon EC2 인스턴스 또는 Fargate에서 실행 중인 컨테이너로 명령을 실행하거나 셸을 가져올 수 있습니다. 이 기능을 활성화한 후 다음 명령을 실행하여 컨테이너와 상호 작용합니다.
aws ecs execute-command --cluster example-cluster \ --task example-task-id \ --container example-container \ --interactive \ --command "/bin/sh"
Amazon EC2 시작 유형을 사용하는 경우 Docker exec 명령을 사용하여 컨테이너와 상호 작용할 수도 있습니다. 이 경우 다음을 수행합니다.
태스크가 실행되는 컨테이너 인스턴스에 연결합니다. 그리고 나서 다음 Docker 명령을 실행하여 태스크 컨테이너의 컨테이너 ID를 찾습니다.
docker container ps
다음 명령을 실행하여 컨테이너와 상호 작용합니다.
docker exec -it example-container-id bash
참고: 컨테이너 기본 셸에 따라 셸을 선택합니다.
컨테이너와의 연결을 설정한 후 컨테이너에서 env 명령을 실행하여 환경 변수의 전체 목록을 가져옵니다. 이 목록을 검토하여 태스크 정의 또는 .env 파일에 정의한 환경 변수가 있는지 확인합니다.
컨테이너 정의의 변수 형식이 잘못된 경우
컨테이너 정의 내에서 환경 변수를 정의할 때 환경 변수를 다음과 유사한 KeyValuePair 객체로 정의해야 합니다.
"environment": [{ "name": "foo", "value": "bar" }]
.env 파일에서 환경 변수를 정의할 때도 이 형식을 사용해야 합니다.
환경 변수가 자동으로 새로 고쳐지지 않는 경우
.env 파일에서 환경 변수를 업데이트하면 실행 중인 컨테이너에서 변수가 자동으로 새로 고쳐지지 않습니다.
업데이트된 환경 변수 값을 태스크에 삽입하려면 다음 명령을 실행하여 서비스를 업데이트합니다.
aws ecs update-service --cluster example-cluster --service example-service --force-new-deployment
컨테이너 정의에서 환경 변수를 사용하는 경우 새 태스크 정의를 생성하여 업데이트된 환경 변수를 새로 고쳐야 합니다. 이 새 태스크 정의를 사용하여 새 태스크를 생성하거나 ECS 서비스를 업데이트할 수 있습니다.
aws ecs update-service --cluster example-cluster --service example-service --task-definition <family:revision>
참고:
태스크에 환경 변수를 전달할 때는 다음 사항에 유의하세요.
- 컨테이너 정의에 환경 파라미터를 사용하여 지정된 환경 변수가 있으면 환경 파일에 포함된 변수보다 우선합니다.
- 여러 환경 파일이 지정되고 동일한 변수가 포함된 경우 이러한 파일은 입력 순서대로 처리됩니다. 변수의 첫 번째 값이 사용되며 중복 변수의 후속 값은 무시됩니다. 고유한 변수 이름을 사용하는 것이 가장 좋습니다.
- 환경 파일이 컨테이너 재정의로 지정된 경우 해당 파일이 사용됩니다. 컨테이너 정의에 지정된 다른 환경 파일은 무시됩니다.
- 환경 변수는 /proc/1/envion 파일에서 컨테이너의 PID 1 프로세스에 사용할 수 있습니다. 컨테이너에서 여러 프로세스 또는 init 프로세스(예: 래퍼 스크립트, 시작 스크립트 또는 supervisord)를 실행 중이면 비 PID 1 프로세스에 이 환경 변수를 사용할 수 없습니다.
관련 정보
관련 콘텐츠
- AWS 공식업데이트됨 일 년 전
- AWS 공식업데이트됨 2년 전
- AWS 공식업데이트됨 2년 전
- AWS 공식업데이트됨 2년 전
