디버깅에 Amazon ECS Exec 사용 - Amazon Elastic Container Service

디버깅에 Amazon ECS Exec 사용

Amazon ECS Exec을 사용하면 먼저 호스트 컨테이너 운영 체제와 상호 작용하거나 인바운드 포트를 열거나 SSH 키를 관리할 필요 없이 컨테이너와 직접 상호 작용할 수 있습니다. ECS Exec을 사용하여 명령을 실행하거나 Amazon EC2 인스턴스 또는 AWS Fargate에서 실행하는 컨테이너에 셸을 가져올 수 있습니다. 이를 통해 진단 정보를 쉽게 수집하고 오류를 신속하게 해결할 수 있습니다. 예를 들어 개발 컨텍스트에서 ECS Exec을 사용하여 컨테이너의 다양한 프로세스와 쉽게 상호 작용하고 애플리케이션 문제를 해결할 수 있습니다. 또한 프로덕션 시나리오에서 이를 사용하여 컨테이너에 대한 중단 없이 액세스하고 문제를 디버깅 할 수 있습니다.

Amazon ECS API, AWS Command Line Interface(AWS CLI), AWS SDK 또는 AWS Copilot CLI에서 ECS Exec을 사용하여 실행 중인 Linux 또는 Windows 컨테이너에서 명령을 실행할 수 있습니다. AWS Copilot CLI에서의 ECS Exec 사용과 비디오 시연에 대한 자세한 내용은 Copilot Github 설명서를 참조하세요.

ECS Exec을 사용하여 보다 엄격한 액세스 제어 정책을 유지하고 컨테이너 액세스를 감사할 수도 있습니다. 이 기능을 선택적으로 설정하여 명령을 실행할 수 있는 사용자와 해당 명령을 실행할 수 있는 태스크를 제어할 수 있습니다. 각 명령의 로그와 그 출력을 통해 ECS Exec을 사용하여 실행된 태스크를 감사하고 CloudTrail을 사용하여 컨테이너에 액세스한 사용자를 감사할 수 있습니다.

아키텍처

ECS Exec은 AWS Systems Manager(SSM) Session Manager를 사용하여 실행 중인 컨테이너와의 연결을 설정하고 AWS Identity and Access Management(IAM) 정책을 사용하여 실행 중인 컨테이너에서 실행 중인 명령에 대한 액세스를 제어할 수 있습니다. 이는 필요한 SSM 에이전트 바이너리를 컨테이너에 바인드 탑재하여 수행할 수 있습니다. Amazon ECS 또는 AWS Fargate 에이전트는 애플리케이션 코드와 함께 컨테이너 내부의 SSM 핵심 에이전트를 시작합니다. 자세한 내용은 Systems Manager Session Manager를 참조하세요.

AWS CloudTrail를 사용하여 컨테이너에 액세스한 사용자를 감사할 수 있으며 각 명령(및 출력)을 Amazon S3 또는 Amazon CloudWatch Logs에 로그할 수 있습니다. 사용자 고유의 암호화 키를 사용하여 로컬 클라이언트와 컨테이너 간의 데이터를 암호화하려면 AWS Key Management Service(AWS KMS) 키를 제공해야 합니다.

ECS Exec 사용에 대한 고려 사항

이 항목에서는 ECS Exec 사용과 관련된 다음 측면을 익혀야 합니다.

  • ECS Exec은 AWS Fargate, 외부 인스턴스(ECS Anywhere), Amazon EC2에서 호스팅되는 Linux 컨테이너 및 다음 Windows Amazon ECS 최적화 AMI(컨테이너 에이전트 버전 1.56 이상)에 대해 지원됩니다.

    • Amazon ECS 최적화 Windows Server 2022 Full AMI

    • Amazon ECS 최적화 Windows Server 2022 Core AMI

    • Amazon ECS 최적화 Windows Server 2019 Full AMI

    • Amazon ECS 최적화 Windows Server 2019 Core AMI

    • Amazon ECS 최적화 Windows Server 20H2 Core AMI

  • ECS Exec은 현재 AWS Management Console 사용을 지원하지 않습니다.

  • ECS Exec은 현재 오토 스케일링 용량 공급자를 사용하여 시작된 태스크에 대해 지원되지 않습니다.

  • Amazon ECS와 인터페이스 Amazon VPC 엔드포인트를 사용하는 경우 Systems Manager Session Manager용 인터페이스 Amazon VPC 엔드포인트를 생성해야 합니다. 자세한 내용은 ECS Exec 기능을 사용할 때 Systems Manager Session Manager VPC 엔드포인트 생성 섹션을 참조하세요.

  • 기존 작업에 대해 ECS Exec을 활성화할 수 없습니다. 새 작업에 대해서만 활성화할 수 있습니다.

  • 사용자가 ECS Exec을 사용하여 컨테이너에서 명령을 실행하면 이러한 명령은 root 사용자로 실행됩니다. SSM 에이전트와 하위 프로세스는 컨테이너에 대한 사용자 ID를 지정하는 경우에도 루트로 실행됩니다.

  • ECS Exec 세션의 유휴 제한 시간은 20분입니다. 이 값은 변경할 수 없습니다.

  • SSM 에이전트는 필요한 디렉터리 및 파일을 생성하기 위해 컨테이너 파일 시스템을 기록할 수 있어야 합니다. 따라서 readonlyRootFilesystem 태스크 정의 파라미터 또는 다른 메서드를 사용해 루트 파일 시스템을 읽기 전용으로 만드는 것은 지원되지 않습니다.

  • 사용자는 컨테이너 컨텍스트 내에서 사용할 수 있는 모든 명령을 실행할 수 있습니다. 컨테이너의 주 프로세스 종료, 명령 에이전트 종료 및 종속성 삭제와 같은 태스크를 수행하면 분리된 좀비 프로세스가 발생할 수 있습니다. 좀비 프로세스를 정리하려면 initProcessEnabled 플래그를 태스크 정의에 추가하는 것이 좋습니다.

  • execute-command 작업 외부에서 SSM 세션을 시작하는 것은 가능하지만, 세션이 로깅되지 않고 세션 제한에 대해 계산됩니다. IAM 정책을 사용하여 ssm:start-session 태스크를 거부함으로써 이 액세스를 제한하는 것이 좋습니다. 자세한 내용은 세션 시작 작업에 대한 액세스 제한 섹션을 참조하세요.

  • ECS Exec은 CPU와 메모리를 사용합니다. 태스크 정의에서 CPU 및 메모리 리소스 할당을 지정할 때 이를 수용하고 싶을 것입니다.

  • AWS CLI 버전 1.22.3 이상 또는 AWS CLI 버전 2.3.6 이상을 사용해야 합니다. AWS CLI 업데이트 방법에 대한 자세한 내용은 AWS Command Line Interface 버전 2 사용 설명서최신 버전의 AWS CLI 설치 또는 업데이트를 참조하세요.

  • run-task을(를) 사용하여 비동기식 배치로 관리형 크기 조정을 사용하는 클러스터에서 작업을 시작하는 경우(인스턴스가 없는 작업 시작) ECS Exec을 사용할 수 없습니다.

  • Microsoft Nano Server 컨테이너에 대해서는 ECS Exec을 실행할 수 없습니다. Nano Server 컨테이너에 대한 자세한 내용은 Docker 웹 사이트의 Nano Server를 참조하세요.

ECS Exec 사용을 위한 사전 조건

ECS Exec을 사용하기 전에 다음 태스크를 완료했는지 확인합니다.

  • AWS CLI를 설치하고 구성합니다. 자세한 정보는 AWS CLI을 참조하세요.

  • AWS CLI에 대한 Session Manager 플러그인을 설치합니다. 자세한 내용은 AWS CLI에 대한 Session Manager 플러그인 설치를 참조하세요.

  • ECS Exec은 작업이 Amazon EC2 또는 AWS Fargate에 호스팅되는지 여부에 따라 버전 요구 사항이 있습니다.

    • Amazon EC2를 사용하는 경우 2021년 1월 20일 이후에 출시된 Amazon ECS 최적화 AMI를 에이전트 버전 1.50.2 이상으로 사용해야 합니다. 자세한 내용은 Amazon ECS 최적화 AMI를 참조하세요.

    • AWS Fargate을(를) 사용하는 경우 플랫폼 버전 1.4.0 이상(Linux) 또는 1.0.0(Windows)을(를) 사용해야 합니다. 자세한 내용은 AWS Fargate 플랫폼 버전을 참조하세요.

ECS Exec 활성화 및 사용

ECS Exec에 필요한 IAM 권한

ECS Exec 기능을 사용하려면 관리형 SSM 에이전트(execute-command 에이전트)와 SSM 서비스 간의 통신에 필요한 권한을 컨테이너에 부여하기 위한 작업 IAM 역할이 필요합니다. 자세한 내용은 Amazon ECS 태스크 IAM 역할을 참조하세요. 작업 IAM 역할에 다음 권한을 추가하고 태스크 정의에 작업 IAM 역할을 포함해야 합니다. 자세한 내용은 IAM 정책 추가 및 제거 섹션을 참조하세요.

작업 IAM 역할에 대해 다음 정책을 사용하여 필수 SSM 권한을 추가합니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel" ], "Resource": "*" } ] }

선택적 태스크 정의 변경 사항

태스크 정의 파라미터 initProcessEnabledtrue로 설정하면 컨테이너 내부에서 init 프로세스가 시작되어 발견된 좀비 SSM 에이전트 하위 프로세스가 제거됩니다. 다음은 예제를 제공합니다.

{ "taskRoleArn": "ecsTaskRole", "networkMode": "awsvpc", "requiresCompatibilities": [ "EC2", "FARGATE" ], "executionRoleArn": "ecsTaskExecutionRole", "memory": ".5 gb", "cpu": ".25 vcpu", "containerDefinitions": [ { "name": "amazon-linux", "image": "amazonlinux:latest", "essential": true, "command": ["sleep","3600"], "linuxParameters": { "initProcessEnabled": true } } ], "family": "ecs-exec-task" }

작업 및 서비스에 대한 ECS Exec 활성화

AWS CLI 명령 create-service, update-service, start-task 또는 run-task 중 하나를 사용할 때 --enable-execute-command 플래그를 지정하여 서비스 및 독립 실행형 작업에 대해 ECS Exec 기능을 활성화할 수 있습니다.

예를 들어 다음 명령을 실행하면 새로 생성된 서비스에 대해 ECS Exec 기능이 활성화됩니다. 서비스 생성에 대한 자세한 내용은 create-service 섹션을 참조하세요.

aws ecs create-service \ --cluster cluster-name \ --task-definition task-definition-name \ --enable-execute-command \ --service-name service-name \ --desired-count 1

작업에 대해 ECS Exec을 활성화한 후 다음 명령을 실행하여 태스크를 사용할 준비가 되었는지 확인할 수 있습니다. ExecuteCommandAgentlastStatus 속성이 RUNNING으로 나열되고 enableExecuteCommand 속성이 true로 설정되면 작업이 준비가 된 것입니다.

aws ecs describe-tasks \ --cluster cluster-name \ --tasks task-id

볼 수 있는 출력 조각의 예는 다음과 같습니다.

{ "tasks": [ { ... "containers": [ { ... "managedAgents": [ { "lastStartedAt": "2021-03-01T14:49:44.574000-06:00", "name": "ExecuteCommandAgent", "lastStatus": "RUNNING" } ] } ], ... "enableExecuteCommand": true, ... } ] }

ECS Exec을 사용하여 명령 실행

ExecuteCommandAgent가 실행 중임을 확인한 후 다음 명령을 사용하여 컨테이너에서 대화형 셸을 열 수 있습니다. 작업에 컨테이너가 여러 개 포함되어 있는 경우 --container 플래그를 사용하여 컨테이너 이름을 지정해야 합니다. Amazon ECS는 대화형 세션 시작만 지원하므로 --interactive 플래그를 사용해야 합니다.

다음 명령은 ID가 task-id인 작업에 대해 container-name이라는 컨테이너에 대화형 /bin/sh 명령을 실행합니다.

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

ECS Exec을 사용한 로깅 및 감사

작업 및 서비스에서 로깅 및 감사 활성화

Amazon ECS는 태스크 정의에 구성된 awslogs 로그 드라이버를 사용하여 CloudWatch Logs에 로그를 전송함으로써 ECS Exec을 사용하여 실행되는 명령 로깅을 위한 기본 구성을 제공합니다. 사용자 지정 구성을 제공하려는 경우 AWS CLI는 create-clusterupdate-cluster 명령 모두에 대해 --configuration 플래그를 지원합니다. 또한 컨테이너 이미지에 scriptcat을 설치하여 명령 로그가 Amazon S3 또는 CloudWatch Logs에 올바르게 업로드되도록 하는 것이 중요합니다. 클러스터 생성에 대한 자세한 내용은 create-cluster를 참조하세요.

참고

이 구성은 execute-command 세션의 로깅만을 처리합니다. 애플리케이션의 로깅에는 영향을 미치지 않습니다.

다음 예제에서는 서비스를 생성한 다음 출력을 cloudwatch-log-group-name이라는 CloudWatch Logs LogGroup과 s3-bucket-name이라는 Amazon S3 버킷에 로그합니다.

CloudWatchEncryptionEnabled 옵션을 true로 설정할 때 AWS KMS 고객 관리형 키를 사용하여 로그 그룹을 암호화해야 합니다. 로그 그룹을 암호화하는 방법에 대한 자세한 내용은Amazon CloudWatch Logs 사용 설명서AWS Key Management Service를 사용하여 CloudWatch Logs의 로그 데이터 암호화를 참조하세요.

aws ecs create-cluster \ --cluster-name cluster-name \ --configuration executeCommandConfiguration="{ \ kmsKeyId=string, \ logging=OVERRIDE, \ logConfiguration={ \ cloudWatchLogGroupName=cloudwatch-log-group-name, \ cloudWatchEncryptionEnabled=true, \ s3BucketName=s3-bucket-name, \ s3EncryptionEnabled=true, \ s3KeyPrefix=demo \ } \ }"

logging 속성은 ECS Exec의 로깅 기능 동작을 결정합니다.

  • NONE: 로깅이 비활성화됩니다.

  • DEFAULT: 로그가 구성된 awslogs 드라이버로 전송됩니다(드라이버가 구성되지 않은 경우 로그가 저장되지 않습니다).

  • OVERRIDE: 제공된 Amazon CloudWatch Logs LogGroup이나 Amazon S3 버킷 또는 둘 다에 로그가 전송됩니다.

Amazon CloudWatch Logs 또는 Amazon S3 로깅에 필요한 IAM 권한

로깅을 활성화하려면 태스크 정의에서 참조되는 Amazon ECS 작업 역할에 추가 권한이 있어야 합니다. 이러한 추가 권한은 작업 역할에 인라인 정책으로 추가할 수 있습니다. 추가 권한은 로그를 Amazon CloudWatch Logs 또는 Amazon S3에 전달하는지 여부에 따라 다릅니다.

Amazon CloudWatch Logs

다음 예제에서는 인라인 정책이 필수 Amazon CloudWatch Logs 권한을 추가합니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:DescribeLogGroups" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogStream", "logs:DescribeLogStreams", "logs:PutLogEvents" ], "Resource": "arn:aws:logs:region:account-id:log-group:/aws/ecs/cloudwatch-log-group-name:*" } ] }
Amazon S3

다음 예제에서는 인라인 정책이 필수 Amazon S3 권한을 추가합니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetBucketLocation" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:GetEncryptionConfiguration" ], "Resource": "arn:aws:s3:::s3-bucket-name" }, { "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": "arn:aws:s3:::s3-bucket-name/*" } ] }

자체 AWS KMS key(KMS 키)를 사용한 암호화에 필요한 IAM 권한

기본적으로 로컬 클라이언트와 컨테이너 간에 전송되는 데이터는 AWS에서 제공하는 TLS 1.2 암호화를 사용합니다. 자체 KMS 키를 사용하여 데이터를 추가로 암호화하려면 KMS 키를 생성하고 kms:Decrypt 권한을 작업 IAM 역할에 추가해야 합니다. 이 권한은 데이터를 복호화하기 위해 컨테이너에서 사용됩니다. KMS 키 생성에 대한 자세한 내용은 키 생성을 참조하세요.

AWS KMS 권한이 필요한 작업 IAM 역할에 다음과 같은 인라인 정책을 추가합니다. 자세한 내용은 ECS Exec에 필요한 IAM 권한 섹션을 참조하세요.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": "kms-key-arn" } ] }

자체 KMS 키를 사용하여 데이터를 암호화하려면 execute-command 태스크를 사용하는 사용자 또는 그룹에 kms:GenerateDataKey 권한을 부여해야 합니다.

사용자 또는 그룹에 대한 다음 예제 정책에는 자체 KMS 키를 사용하는 데 필요한 권한이 포함되어 있습니다. KMS 키의 Amazon 리소스 이름(ARN)을 지정해야 합니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:GenerateDataKey" ], "Resource": "kms-key-arn" } ] }

IAM 정책을 사용하여 ECS Exec에 대한 액세스 제한

다음 IAM 정책 조건 키 중 하나 이상을 사용하여 execute-command API 작업에 대한 사용자 액세스를 제한할 수 있습니다.

  • aws:ResourceTag/clusterTagKey

  • ecs:ResourceTag/clusterTagKey

  • aws:ResourceTag/taskTagKey

  • ecs:ResourceTag/taskTagKey

  • ecs:container-name

  • ecs:cluster

  • ecs:task

  • ecs:enable-execute-command

사용자는 다음 예제 IAM 정책을 사용하여 environment 키와 development 값이 있는 태그가 포함된 작업 내에서 실행 중인 컨테이너와 cluster-name이라는 클러스터에서 명령을 실행할 수 있습니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecs:ExecuteCommand", "ecs:DescribeTasks" ], "Resource": "arn:aws:ecs:region:aws-account-id:task/cluster-name/*", "Condition": { "StringEquals": { "ecs:ResourceTag/environment": "development" } } } ] }

다음 IAM 정책 예제에서 사용자는 컨테이너 이름이 production-app일 때 execute-command API를 사용할 수 없습니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "ecs:ExecuteCommand" ], "Resource": "*", "Condition": { "StringEquals": { "ecs:container-name": "production-app" } } } ] }

다음 IAM 정책을 사용하면 ECS Exec이 비활성화된 경우에만 태스크를 시작할 수 있습니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecs:RunTask", "ecs:StartTask", "ecs:CreateService", "ecs:UpdateService" ], "Resource": "*", "Condition": { "StringEquals": { "ecs:enable-execute-command": "false" } } } ] }
참고

왜냐하면 execute-command API 작업에는 요청의 작업 및 클러스터 리소스만 포함되며 클러스터 및 태스크 태그만 평가되기 때문입니다.

IAM 정책 조건 키에 대한 자세한 내용은 서비스 승인 참조Amazon Elastic Container Service에 사용되는 작업, 리소스 및 조건 키를 참조하세요.

세션 시작 작업에 대한 액세스 제한

ECS Exec 외부의 컨테이너에서 SSM 세션을 시작할 수 있지만 이로 인해 세션이 로깅되지 않을 수 있습니다. ECS Exec 외부에서 시작된 세션도 세션 할당량에 대해 계산됩니다. IAM 정책을 사용하여 Amazon ECS 작업에 대한 ssm:start-session 태스크를 직접 거부함으로써 이 액세스를 제한하는 것이 좋습니다. 모든 Amazon ECS 작업 또는 사용된 태그를 기반으로 특정 작업에 대한 액세스를 거부할 수 있습니다.

다음은 클러스터 이름이 지정된 모든 리전의 작업에서 ssm:start-session 작업에 대한 액세스를 거부하는 IAM 정책 예제입니다. 선택적으로 cluster-name이 있는 와일드카드를 포함할 수 있습니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "ssm:StartSession", "Resource": "arn:aws:ecs:*:111122223333:task/cluster-name/*" } ] }

다음은 태그 키 Task-Tag-Key, 태그 값 Exec-Task로 태그가 지정된 모든 리전의 리소스에서 ssm:start-session 작업에 대한 액세스를 거부하는 IAM 정책 예제입니다.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "ssm:StartSession", "Resource": "*", "Condition": { "StringEquals": { "aws:ResourceTag/Task-Tag-Key": "Exec-Task" } } } ] }

ECS Exec 관련 문제 해결

다음은 ECS Exec을 사용할 때 오류가 발생할 수 있는 이유를 진단하는 데 도움이 되는 문제 해결 정보입니다.

Amazon ECS Exec 검사기를 사용하여 확인

Amazon ECS Exec 검사기 스크립트는 Amazon ECS 클러스터와 작업이 ECS Exec 기능을 사용하기 위한 사전 요구 사항을 충족했는지 확인하고 검증하는 방법을 제공합니다. Exec 검사기 스크립트는 사용자를 대신하여 다양한 API를 호출하여 AWS CLI 환경과 클러스터 및 태스크가 ECS Exec에 대해 모두 준비되었는지 확인합니다. 이 도구에는 AWS CLI의 최신 버전이 필요하며 jq를 사용할 수 있습니다. 자세한 내용은 GitHub의 Amazon ECS Exec 검사기를 참조하세요.

execute-command 호출 중 오류 발생

The execute command failed 오류가 발생하는 경우 가능한 원인은 다음과 같습니다.

  • 작업에 필요한 권한이 없습니다. 태스크를 시작하는 데 사용되는 태스크 정의에 작업 IAM 역할이 정의되어 있고 역할에 필요한 권한이 있는지 확인합니다. 자세한 정보는 ECS Exec에 필요한 IAM 권한을 참조하세요.

  • SSM Agent가 설치되지 않았거나 실행되고 있지 않습니다.

  • Amazon ECS용 인터페이스 Amazon VPC 엔드포인트가 있지만 Systems Manager Session Manager용 인터페이스 Amazon VPC 엔드포인트는 없습니다.