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

6분 분량
0

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

간단한 설명

다음 방법 중 하나를 사용하여 사용자의 Amazon ECS 작업 내부에 환경 변수를 전달할 수 있습니다.

  • Amazon Simple Storage Service(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 error"

-또는-

"AccessDenied error on Amazon Elastic Compute Cloud (Amazon EC2)"

이러한 오류를 해결하려면 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 작업의 오류를 해결하려면, AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용하세요. 그런 다음, 사용자의 문제에 대한 관련 문제 해결 단계를 참조하세요.

해결 방법

중요:

  • AWSSupport-TroubleshootECSTaskFailedToStart 런북을 사용자의 ECS 클러스터 자원이 위치한 동일한 AWS 리전에서 사용하세요.
  • 런북을 사용할 때는 가장 최근에 실패한 작업 ID를 사용해야 합니다. 실패한 작업이 Amazon ECS 서비스의 한 부분인 경우, 해당 서비스에서 가장 최근에 실패한 작업을 사용하세요. 실패한 작업은 자동화 중에 ECS:DescribeTask에 표시되어야 합니다. 기본적으로 중지된 ECS 작업은 중지됨 상태로 전환된 후 1시간 동안 표시됩니다. 가장 최근에 실패한 작업 ID를 사용하면 작업 상태 정리에 의해 자동화 중에 분석이 중단되는 것을 방지할 수 있습니다.

런북을 시작하는 방법에 대한 지침은 AWSSupport-TroubleshootECSTaskFailedToStart를 참조하세요. 자동화 결과에 따라 다음 수동 문제 해결 단계 중 하나를 사용하세요.

사용자의 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에서 송신 트래픽을 허용해야 합니다.
  • Systems Manager/Secrets Manager 및 Amazon S3 엔드포인트와의 연결을 확인하세요. 이 작업을 수행하려면, telnet 명령을 사용하세요.
  • NAT 게이트웨이를 사용하는 경우, 사용자의 작업에는 NAT 게이트웨이에 대한 기본 경로가 있어야 합니다.
  • 사용자의 작업에 사용할 VPC 엔드포인트를 정의하세요. Secrets Manager/Systems Manager Parameter StoreAmazon S3에 필요한 VPC 엔드포인트가 있는지 확인하세요.

VPC 엔드포인트를 사용하는 경우, 다음 사항을 확인하세요.

  • 사용자 VPC 엔드포인트의 보안 그룹은 포트 443에서 작업 또는 서비스로부터의 송신 트래픽을 허용합니다.
  • VPC 엔드포인트를 올바른 VPC와 연결하세요.
  • VPC 속성인 enableDnsHostnamesenableDnsSupport를 활성화하세요.

사용자의 ECS 작업이 퍼블릭 서브넷에 있는 경우, 다음 사항을 확인하세요.

  • 작업에 필요한 퍼블릭 IP 주소를 활성화해야 합니다.
  • 사용자 VPC의 보안 그룹은 포트 443에서 인터넷에 아웃바운드 액세스해야 합니다.
  • 네트워크 ACL 구성에서는 모든 트래픽이 서브넷에서 인터넷으로 들어오고 나가는 것을 허용합니다.

사용자의 애플리케이션에서 환경 변수를 읽을 수 없습니다

사용자의 작업 컨테이너에 올바른 환경 변수가 채워져 있는지 확인하려면, 다음을 수행하세요.

  1. 컨테이너 내부에 노출되는 모든 환경 변수를 나열하세요.
  2. 이 목록에 태스크 정의 또는 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이 아닌 프로세스에서는 환경 변수를 사용할 수 없습니다.

관련 정보

컨테이너에 환경 변수 전달

댓글 없음