Fargate 작업에서 ECS Exec을 사용할 때 발생하는 오류를 해결하려면 어떻게 해야 합니까?

해결 방법

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

Fargate 기반 ECS Exec 작업을사용할 때 다음 오류 메시지 중 하나가 표시될 수 있습니다.

• "An error occurred (InvalidParameterException) when calling the ExecuteCommand operation: The execute command failed because execute command was not enabled when the task was run or the execute command agent isn't running. Wait and try again or run a new task with execute command enabled and try again."
• "An error occurred (TargetNotConnectedException) when calling the ExecuteCommand operation: The execute command failed due to an internal error. Try again later."

AWS CloudShell을 사용하여 Fargate 기반 ECS Exec 작업의 문제를 해결하는 것이 가장 좋습니다. CloudShell에는 AWS Systems Manager Agent(SSM Agent) 및 AWS CLI가 사전 설치되어 있습니다.

InvalidParameterException 오류

Fargate 작업에 ExecuteCommand 옵션이 비활성화된 경우 InvalidParameterException 오류가 발생합니다.

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

1. enableExecuteCommand 파라미터가 true 또는 false로 설정되었는지 확인하려면 describe-tasks 명령을 실행하십시오.

   aws ecs describe-tasks --cluster example-cluster-name --tasks example-task-id| grep enableExecuteCommand

   참고: example-cluster-name을 클러스터로, example-task-id를 작업 ID로 바꾸십시오.

2. enableExecuteCommand 파라미터가 false인 경우 다음 update-service 명령을 실행하여 파라미터를 true로 업데이트하십시오.

   aws ecs update-service --cluster example-cluster-name --service example-service --region example-region --enable-execute-command --force-new-deployment

   참고: example-cluster-name을 클러스터로, example-service를 서비스로, example-region을 AWS 리전으로 바꾸십시오. force-new-deployment 옵션은 서비스의 배포 구성에 따라 새 작업을 시작하고 이전 작업을 중지하는 새로운 배포를 생성합니다. 서비스가 AWS CodeDeploy 블루/그린 배포를 사용하는 경우 force-new-deployment 대신 CODE_DEPLOY 배포를 시작하십시오. 강제 배포는 롤링 업데이트를 시작하므로 블루/그린 배포에는 force-new-deployment를 사용할 수 없습니다.

3. ExecuteCommandAgent의 상태를 확인하려면 다음 describe-tasks 명령을 실행하십시오.

   aws ecs describe-tasks --cluster example-cluster-name --tasks example-task-id | grep -A 6 managedAgents

   참고: example-cluster-name을 클러스터로, example-task-id를 작업 ID로 바꾸십시오.

4. 명령의 출력에서 ExecuteCommand 에이전트의 상태를 확인합니다. ExecuteCommandAgent의 lastStatus가 RUNNING이 아닌 경우 ExecuteCommandAgent 에이전트 로그를 확인하여 근본 원인을 파악하십시오. ECS Exec에 대한 로그를 생성하여 문제 파악 문제 해결 단계를 진행하여 ExecuteCommandAgent 로그를 생성하십시오.

   컨테이너에 프록시를 구성했기 때문에 ExecuteCommandAgent가 자격 증명을 검색할 수 없는 경우 컨테이너 인스턴스 구성 파일에 다음 NO_PROXY 옵션을 추가하십시오.

   env no_proxy=169.254.169.254,169.254.170.2

TargetNotConnectedException 오류

TargetNotConnectionException 오류를 해결하려면 다음 작업을 수행하십시오.

필요한 권한을 추가하고 네트워킹 구성 검증

다음 단계를 완료하십시오.

1. Amazon ECS 작업 AWS Identity and Access Management(IAM) 역할에 필요한 권한을 추가합니다. 작업의 IAM 역할에 필요한 권한이 이미 있는 경우 서비스 제어 정책(SCP)으로 인해 작업의 SSM Agent에 대한 연결이 차단되고 있지 않은지 확인하십시오.
2. Amazon ECS에서 Amazon Virtual Private Cloud(Amazon VPC) 인터페이스 엔드포인트를 사용하는 경우 다음 엔드포인트를 생성하십시오.
   ec2messages.region.amazonaws.com
   ssm.region.amazonaws.com
   ssmmessages.region.amazonaws.com
   참고: region을 사용자의 리전으로 바꾸십시오.
3. AWS CLI 환경과 Amazon ECS 클러스터 또는 작업이 ECS Exec을 사용할 준비가 되었는지 확인하려면 check-ecs-exec.sh 스크립트를 실행합니다. check-ecs-exec.sh 스크립트의 출력은 ECS Exec을 사용하기 전에 해결해야 하는 사항을 보여줍니다. 사전 요구 사항 및 사용에 대한 자세한 내용은 GitHub 웹 사이트의 Amazon ECS Exec Checker를 참조하십시오.
   다음 예제 출력은 해당 작업에 대해 ECS Exec이 활성화되지 않았고 필요한 Systems Manager 권한이 작업 역할에 없음을 보여줍니다.

   Prerequisites for check-ecs-exec.sh v0.7
   -------------------------------------------------------------
     jq      | OK (/usr/bin/jq)
     AWS CLI | OK (/usr/local/bin/aws)
   
   -------------------------------------------------------------
   Prerequisites for the AWS CLI to use ECS Exec
   -------------------------------------------------------------
     AWS CLI Version        | OK (aws-cli/2.11.0 Python/3.11.2 Linux/4.14.255-291-231.527.amzn2.x86_64 exec-env/CloudShell exe/x86_64.amzn.2 prompt/off)
     Session Manager Plugin | OK (1.2.398.0)
   
   -------------------------------------------------------------
   Checks on ECS task and other resources
   -------------------------------------------------------------
   Region : us-east-1
   Cluster: Fargate-Testing
   Task   : ca27e41ea3f54fd1804ca00feffa178d
   -------------------------------------------------------------
     Cluster Configuration  | Audit Logging Not Configured
     Can I ExecuteCommand?  | arn:aws:iam::12345678:role/Admin
       ecs:ExecuteCommand: allowed
       ssm:StartSession denied?: allowed
     Task Status            | RUNNING
     Launch Type            | Fargate
     Platform Version       | 1.4.0
     Exec Enabled for Task  | NO
     Container-Level Checks |
      ----------
        Managed Agent Status - SKIPPED
      ----------
      ----------
        Init Process Enabled (Exec-check:2)
      ----------
         1. Disabled - "nginx"
      ----------
        Read-Only Root Filesystem (Exec-check:2)
      ----------
         1. Disabled - "nginx"
     Task Role Permissions  | arn:aws:iam::12345678:role/L3-session
       ssmmessages:CreateControlChannel: implicitDeny
       ssmmessages:CreateDataChannel: implicitDeny
       ssmmessages:OpenControlChannel: implicitDeny
       ssmmessages:OpenDataChannel: implicitDeny
     VPC Endpoints          | SKIPPED (vpc-abcd - No additional VPC endpoints required)
     Environment Variables  | (Exec-check:2)
         1. container "nginx"
         - AWS_ACCESS_KEY: not defined
         - AWS_ACCESS_KEY_ID: not defined
         - AWS_SECRET_ACCESS_KEY: not defined

   참고: ECS Exec을 실행하려면 작업 정의에서 ReadonlyRootFilesystem 파라미터를 false로 설정해야 합니다. ReadonlyRootFileSystem이 true인 경우 SSM Agent가 필요한 디렉터리를 생성할 수 없습니다.
4. 액세스 키 또는 시크릿 액세스 키 등 컨테이너 수준에서 IAM 사용자 자격 증명을 구성했는지 확인합니다.
   참고: SSM Agent는 AWS SDK for Java를 사용하여 인증을 확인합니다. 컨테이너 인스턴스의 액세스 키 또는 시크릿 액세스 키를 환경 변수로 구성하는 경우 작업 수준 권한을 재정의합니다. ECS Exec을 사용하려면 컨테이너 수준의 IAM 자격 증명이 SSM Agent에 권한을 제공해야 합니다.
5. 작업 정의에서 pidMode가 task로 설정되지 않았는지 확인합니다.
   참고: ECS Exec 세션은 각 프로세스 ID(PID) 네임스페이스마다 하나만 사용할 수 있습니다. 작업에서 PID 네임스페이스를 공유하는 경우 하나의 컨테이너에서만 ECS Exec 세션을 시작할 수 있습니다.

ECS Exec을 사용하여 올바른 쉘이 있는 컨테이너에 들어가기

기본 이미지마다 쉘이 다를 수 있습니다. 잘못된 쉘을 사용하면 오류가 발생합니다. 애플리케이션 이미지를 기반으로 올바른 쉘을 사용하고 있는지 확인하십시오.

ECS Exec을 사용하여 컨테이너로 들어가려면 execute-command 명령을 실행하십시오.

aws ecs execute-command --region example-region --cluster example-cluster --container example-container --task example-task --command "example_shell" --interactive

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

ECS Exec에 대한 로그를 생성하여 문제 파악

ECS Exec이 작동하지 않는 이유에 대한 정보가 포함된 SSM Agent 로그를 생성하려면 컨테이너 정의의 환경 섹션에서 다음 명령을 실행하십시오.

콘솔 명령:

bin/bash,-c,sleep 2m && cat /var/log/amazon/ssm/amazon-ssm-agent.log

JSON 명령:

"/bin/bash","-c","sleep 2m && cat /var/log/amazon/ssm/amazon-ssm-agent.log"

참고: 애플리케이션에 따라 쉘과 편집기가 다릅니다. 애플리케이션의 요구 사항에 따라 위의 명령 파라미터를 수정하십시오.

awslogs 로그 드라이버를 사용하는 경우, 위의 명령은 SSM 에이전트 로그를 생성하고 이를 Amazon CloudWatch 로그 그룹으로 전송합니다. 다른 로그 드라이버를 사용하거나 엔드포인트를 로깅하는 경우 해당 위치로 SSM Agent 로그가 전송됩니다.

JSON 예시:

"entryPoint": [],
"portMappings": [],
"command": [
        "bin/bash",
        "-c",
        "sleep 2m && cat /var/log/amazon/ssm/amazon-ssm-agent.log"
    ],