# Amazon ECS 문제 해결 로드 밸런서, 작업, 서비스 또는 컨테이너 인스턴스의 문제를 해결해야 하는 경우가 있을 수 있습니다. 이 장은 Amazon ECS 컨테이너 에이전트, 컨테이너 인스턴스의 Docker 대몬, Amazon ECS 콘솔의 서비스 이벤트 로그에서 진단 정보를 찾는 데 도움이 됩니다. 중지된 작업에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | 중지된 작업 오류를 해결합니다. | [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) | | 중지된 작업 오류를 봅니다. | [Amazon ECS 중지된 작업 오류 해결](resolve-stopped-errors.md) | | 중지된 작업 오류 코드를 검토합니다. | [Amazon ECS 중지된 작업 오류 메시지](stopped-task-error-codes.md) | | CannotPullContainer 작업 오류를 검토합니다. | [Amazon ECS에서 CannotPullContainer 작업 오류](task_cannot_pull_image.md) | | 작업 IAM 역할 요청을 봅니다. | [Amazon ECS 태스크에 대한 IAM 역할 요청 보기](task_iam_roles-logs.md) | | 태스크 이벤트 사용 관련 문제를 해결합니다. | [콘솔에서 Amazon ECS 이벤트 캡처](task-lifecycle-events.md) | 서비스 오류에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | 서비스 이벤트 메시지를 봅니다. | [Amazon ECS 서비스 이벤트 메시지 보기](service-event-messages.md) | | 서비스 이벤트 메시지를 검토합니다. | [Amazon ECS 서비스 이벤트 메시지](service-event-messages-list.md) | | 로드 밸런서 문제를 검토합니다. | [Amazon ECS의 서비스 로드 밸런서 문제 해결](troubleshoot-service-load-balancers.md) | | 서비스 Auto Scaling 문제를 검토합니다. | [Amazon ECS에서 서비스 Auto Scaling 문제 해결](troubleshoot-service-auto-scaling.md) | 작업 정의 오류에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | 작업 정의 메모리 오류를 해결합니다. | [Amazon ECS 작업 정의 잘못된 CPU 또는 메모리 오류 문제 해결](task-cpu-memory-error.md) | Amazon ECS 에이전트 오류에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | Amazon ECS 컨테이너 에이전트 로그를 봅니다. | [Amazon ECS 컨테이너 에이전트 로그 보기](logs.md) | | Amazon ECS 로그를 수집하는 방법을 알아봅니다. | [Amazon ECS 로그 수집기를 사용하여 컨테이너 로그 수집](ecs-logs-collector.md) | | Amazon ECS 에이전트를 사용하여 진단 세부 정보를 검색합니다. | [에이전트 내부 검사를 통해 Amazon ECS 진단 세부 정보 검색](introspection-diag.md) | Docker 오류에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | Docker 진단을 사용합니다. | [Amazon ECS의 Docker 진단](docker-diags.md) | | Docker 디버그 모드를 켭니다. | [Amazon ECS에서 Docker 대몬의 자세한 출력 구성](docker-debug-mode.md) | | Docker API 오류 500 문제를 해결합니다. | [Amazon ECS의 Docker `API error (500): devmapper` 문제 해결](CannotCreateContainerError.md) | ECS Exec 및 Amazon ECS Anywhere 오류에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | ECS Exec 관련 문제를 해결합니다. | [Amazon ECS Exec 문제 해결](ecs-exec-troubleshooting.md) | | Amazon ECS Anywhere 관련 문제를 해결합니다. | [Amazon ECS Anywhere 문제 해결](ecs-anywhere-troubleshooting.md) | Amazon ECS 태스크에 Amazon EBS 볼륨을 연결하는 문제에 대한 자세한 내용은 다음을 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | Amazon ECS 태스크에 Amazon EBS 볼륨 연결 관련 문제 해결 | [Amazon ECS 작업에 Amazon EBS 볼륨 연결 관련 문제 해결](troubleshoot-ebs-volumes.md) | | Amazon ECS 태스크에 대한 Amazon EBS 볼륨 연결의 상태 이유 | [Amazon ECS 태스크에 대한 Amazon EBS 볼륨 연결의 상태 이유](troubleshoot-ebs-volumes-scenarios.md) | Amazon ECS Service Connect에서 공유 AWS Cloud Map 네임스페이스를 사용하는 문제에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | 공유 AWS Cloud Map 네임스페이스를 사용하여 Amazon ECS Service Connect 문제 해결. | [공유 AWS Cloud Map 네임스페이스를 사용한 Amazon ECS Service Connect 문제 해결](service-connect-shared-namespaces-troubleshooting.md) | 제한 문제에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | Fargate 제한 할당량에 대해 알아봅니다. | [AWS Fargate 제한 할당량](throttling.md) | | Amazon ECS 제한 모범 사례에 대해 알아봅니다. | [Amazon ECS 제한 문제 처리](operating-at-scale-dealing-with-throttles.md) | API 오류에 대한 자세한 내용은 다음 중 하나를 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | API 오류를 해결합니다. | [Amazon ECS의 API 실패 이유](api_failures_messages.md) | AI 기반 문제 해결에 대한 자세한 내용은 다음을 참조하세요. | 작업 | 자세히 알아보기 | | --- | --- | | 콘솔에서 Amazon Q Developer로 문제를 해결합니다. | [Amazon Q Developer로 문제 해결](troubleshooting-with-Q.md) | | Amazon ECS MCP 서버를 사용하여 AI 어시스턴트로 문제를 해결합니다. | [Amazon ECS MCP 서버](ecs-mcp-introduction.md) | # Amazon ECS 중지된 작업 오류 해결 작업이 시작되지 않으면 콘솔과 `describe-tasks` 출력 파라미터(`stoppedReason` 및 `stopCode`)에 오류 메시지가 표시됩니다. 1시간 동안 콘솔에서 중지된 작업을 볼 수 있습니다. 중지된 작업을 보려면 필터 옵션을 변경해야 합니다. 자세한 내용은 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. 다음 페이지에서는 중지된 작업에 대한 정보를 제공합니다. + 중지된 작업 오류 메시지의 변경사항에 대해 알아봅니다. [Amazon ECS 중지된 작업 오류 메시지 업데이트](stopped-tasks-error-messages-updates.md) + 중지된 작업을 확인하여 원인에 대한 정보를 얻을 수 있습니다. [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) + 중지된 작업 오류 메시지와 오류의 가능한 원인에 대해 알아봅니다. [Amazon ECS 중지된 작업 오류 메시지](stopped-task-error-codes.md) + 중지된 작업 연결을 확인하고 오류를 수정하는 방법을 알아봅니다. [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) # Amazon ECS 중지된 작업 오류 메시지 업데이트 2024년 6월 14일부터 Amazon ECS 팀은 다음 테이블에 설명된 대로 중지된 작업 오류 메시지를 변경하고 있습니다. `stopCode`는 변경되지 않습니다. 애플리케이션이 정확한 오류 메시지 문자열을 사용하는 경우 애플리케이션을 새 문자열로 업데이트해야 합니다. 질문이나 문제에 대한 도움이 필요하면 AWS Support에 문의하세요. **참고** 오류 메시지는 변경될 수 있으므로 자동화에서 오류 메시지에 의존하지 않는 것이 좋습니다. ## CannotPullContainerError | 오래된 오류 메시지입니다. | 새 오류 메시지 | | --- | --- | | CannotPullContainerError: Error response from daemon: pull access denied for repository, repository does not exist or may require 'docker login': denied: User: roleARN | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/stopped-tasks-error-messages-updates.html) | | CannotPullContainerError: Error response from daemon: Get imageURI: net/http: request canceled while waiting for connection | CannotPullContainerError: The task can’t pull the image. Check your network configuration. Error response from daemon: Get image: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers) | | CannotPullContainerError: ref pull has been retried 5 time(s): failed to copy: httpReadSeeker: failed open: failed to do request: Get registry-uri: dial tcp : i/o timeout | CannotPullContainerError: The task cannot pull image-uri from the registry registry-uri. There is a connection issue between the task and the registry. Check your task network configuration. : failed to copy: httpReadSeeker: failed open: failed to do request: Get registry-uri: dial tcp : i/o timeout | ## ResourceNotFoundException | 오래된 오류 메시지입니다. | 새 오류 메시지 | | --- | --- | | Fetching secret data from AWS Secrets Manager in region region: secret sercretARN: ResourceNotFoundException: Secrets Manager can't find the specified secret. | ResourceNotFoundException: The task can't retrieve the secret with ARN 'sercretARN' from AWS Secrets Manager. Check whether the secret exists in the specified Region. ResourceNotFoundException: Fetching secret data from AWS Secrets Manager in region region: secret sercretARN: ResourceNotFoundException: Secrets Manager can't find the specified secret. | ## ResourceInitializationError | 오래된 오류 메시지입니다. | 새 오류 메시지 | | --- | --- | | ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed: unable to retrieve ecr registry auth: service call has been retried 3 time(s): RequestError: send request failed caused by: Post "https://api.ecr.us-east-1.amazonaws.com/": dial tcp :: i/o timeout. Please check your task network configuration. | ResourceInitializationError: unable to pull secrets or registry auth: The task cannot pull registry auth from Amazon ECR: There is a connection issue between the task and Amazon ECR. Check your task network configuration. RequestError: send request failed caused by: Post "https://api.ecr.us-east-1.amazonaws.com": dial tcp :: i/o timeout | | 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: request context canceled caused by: context deadline exceeded | ResourceInitializationError: unable to pull secrets or registry auth: unable to retrieve secrets from ssm: The task cannot pull secrets from AWS Systems Manager. There is a connection issue between the task and AWS Systems Manager Parameter Store. Check your task network configuration. RequestCanceled: request context canceled caused by: context deadline exceeded | | ResourceInitializationError: failed to download env files: file download command: non empty error stream: RequestCanceled: request context canceled caused by: context deadline exceeded | ResourceInitializationError: failed to download env files: The task can't download the environment variable files from Amazon S3. There is a connection issue between the task and Amazon S3. Check your task network configuration. service call has been retried 5 time(s): RequestCanceled: request context canceled caused by: context deadline exceeded | | ResourceInitializationError: failed to validate logger args::signal:killed | ResourceInitializationError: failed to validate logger args: The task cannot find the Amazon CloudWatch log group defined in the task definition. There is a connection issue between the task and Amazon CloudWatch. Check your network configuration. : signal: killed | | ResourceInitializationError: unable to pull secrets or registry auth: pull command failed: : signal: killed | ResourceInitializationError: unable to pull secrets or registry auth: Check your task network configuration. : signal: killed | # Amazon ECS 중지된 작업 오류 보기 작업을 시작하는 데 문제가 있는 경우, 오류 때문에 작업이 중지된 것일 수 있습니다. 예를 들면, 작업 실행 시 작업이 `PENDING` 상태를 표시한 후 사라지는 경우입니다. 작업이 Amazon ECS 서비스에서 생성된 경우 Amazon ECS가 서비스를 유지하기 위해 수행하는 작업은 서비스 이벤트에 게시됩니다. AWS Management Console, AWS CLI, AWS SDK, Amazon ECS API 또는 SDK 및 API를 사용하는 도구에서 이벤트를 볼 수 있습니다. 이러한 이벤트에는 작업의 컨테이너가 실행을 중지했거나 Elastic Load Balancing에서 너무 많은 상태 확인에 실패했기 때문에 작업을 중지하고 교체하는 Amazon ECS가 포함됩니다. Amazon EC2 또는 외부 컴퓨터의 컨테이너 인스턴스에서 작업이 실행된 경우 컨테이너 런타임 및 Amazon ECS Agent의 로그도 볼 수 있습니다. 이 로그는 호스트 Amazon EC2 인스턴스 또는 외부 컴퓨터에 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 로그 보기](logs.md) 섹션을 참조하세요. ## 절차 ------ #### [ Console ] **AWS Management Console** 콘솔을 사용하여 오류로 인해 중단된 작업을 확인하려면 다음의 단계를 사용할 수 있습니다. 중지된 작업을 보려면 필터 옵션을 변경해야 합니다. 중지된 태스크는 1시간 동안만 콘솔에 나타납니다. 1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다. 1. 탐색 창에서 **클러스터**를 선택합니다. 1. **클러스터(Clusters)** 페이지에서 클러스터를 선택합니다. 1. **클러스터: *name*(Cluster : name)** 페이지에서 **태스크(Tasks)** 탭을 선택합니다. 1. 중지된 작업을 표시하도록 필터를 구성합니다. **원하는 상태 필터링**에서 **중지됨**을 선택합니다. **중지됨** 옵션에는 중지된 작업이 표시되고 **원하는 상태**에는 모든 작업이 표시됩니다. 1. 검사할 중지된 태스크를 선택합니다. 1. 중지된 작업 행의 **마지막 상태** 열에서 **중지됨**을 선택합니다. 팝업 창에 중지된 이유가 표시됩니다. ------ #### [ AWS CLI ] 1. 클러스터의 태스크를 나열합니다. 결과에는 작업의 Amazon 리소스 이름(ARN)이 포함되어 있으며 이를 통해 태스크를 설명해야 합니다. ``` aws ecs list-tasks \ --cluster cluster_name \ --desired-status STOPPED \ --region region ``` 1. 중지된 작업을 설명하여 정보를 검색합니다. 자세한 내용은 *AWS Command Line Interface 참조*의 [describe-tasks](https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-tasks.html)를 참조하세요. ``` aws ecs describe-tasks \ --cluster cluster_name \ --tasks arn:aws:ecs:region:account_id:task/cluster_name/task_ID \ --region region ``` 다음 출력 파라미터를 사용합니다. + `stopCode` - 중지 코드는 작업이 중지된 이유를 나타냅니다(예: ResourceInitializationError). + `StoppedReason` - 작업이 중지된 이유입니다. + `reason`(`containers` 구조 내) - 이유에서는 중지된 컨테이너에 대한 추가 세부 정보를 제공합니다. ------ ## 다음 단계 중지된 작업을 확인하여 원인에 대한 정보를 얻을 수 있습니다. 자세한 내용은 [Amazon ECS 중지된 작업 오류 메시지](stopped-task-error-codes.md) 섹션을 참조하세요. # Amazon ECS 중지된 작업 오류 메시지 다음은 작업이 예기치 않게 중지될 때 나타날 수 있는 가능한 오류 메시지입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. **작은 정보** [Amazon ECS MCP 서버](ecs-mcp-introduction.md)를 AI 어시스턴트와 함께 사용하여 자연어로 작업 실패 및 컨테이너 로그를 분석할 수 있습니다. 중지된 태스크 오류 코드에는 이와 연결된 카테고리가 있습니다(예: 'ResourceInitializationError'). 각 카테고리에 대한 자세한 내용은 다음을 참조하세요. | 카테고리 | 자세히 알아보기 | | --- | --- | | TaskFailedToStart | [Amazon ECS TaskFailedToStart 오류 문제 해결](failed-to-start-error.md) | | ResourceInitializationError | [Amazon ECS ResourceInitializationError 오류 문제 해결](resource-initialization-error.md) | | ResourceNotFoundException | [Amazon ECS ResourceNotFoundException 오류 문제 해결](resource-not-found-error.md) | | SpotInterruptionError | [Amazon ECS SpotInterruption 오류 문제 해결](spot-interruption-errors.md) | | InternalError | [Amazon ECS InternalError 오류 문제 해결](internal-error.md) | | OutOfMemoryError | [Amazon ECS OutOfMemoryError 오류 문제 해결](out-of-memory.md) | | ContainerRuntimeError | [Amazon ECS ContainerRuntimeError 오류 문제 해결](container-runtime-error.md) | | ContainerRuntimeTimeoutError | [Amazon ECS ContainerRuntimeTimeoutError 오류 문제 해결](container-runtime-timeout-error.md) | | CannotStartContainerError | [Amazon ECS CannotStartContainerError 오류 문제 해결](cannot-start-container.md) | | CannotStopContainerError | [Amazon ECS CannotStopContainerError 오류 문제 해결](cannot-stop-container.md) | | CannotInspectContainerError | [Amazon ECS CannotInspectContainerError 오류 문제 해결](cannot-inspect-container.md) | | CannotCreateVolumeError | [Amazon ECS CannotCreateVolumeError 오류 문제 해결](cannot-create-volume.md) | | CannotPullContainer | [Amazon ECS에서 CannotPullContainer 작업 오류](task_cannot_pull_image.md) | # Amazon ECS TaskFailedToStart 오류 문제 해결 다음은 몇 가지 `TaskFailedToStart` 오류 메시지와 오류를 수정하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## Unexpected EC2 error while attempting to Create Network Interface with public IP assignment enabled in subnet '*subnet-id* 이 오류는 Fargate 작업이 `awsvpc` 네트워크 모드를 사용하고 퍼블릭 IP 주소가 있는 서브넷에서 실행되지만 서브넷에 충분한 IP 주소가 없는 경우에 발생합니다. Amazon EC2 콘솔의 서브넷 세부 정보 페이지나 `[describe-subnets](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-subnets.html)`를 사용하여 가용 IP 주소 개수가 표시됩니다. 자세한 내용은 *Amazon VPC 사용 설명서*의 [View your subnet](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#view-subnet)을 참조하세요. 이 문제를 해결하기 위해 작업을 실행할 새 서브넷을 생성할 수 있습니다. ## InternalError: ** 이 오류는 ENI 연결을 요청할 때 발생합니다. Amazon EC2는 ENI의 프로비저닝을 비동기식으로 처리합니다. 프로비저닝 프로세스는 시간이 소요됩니다. 대기 시간이 길거나 보고되지 않은 실패가 있을 경우 Amazon ECS에 시간 초과가 발생합니다. ENI가 프로비저닝되는 시간이 있지만, 실패 시간 초과 이후에 보고서가 Amazon ECS로 전달됩니다. 이 경우, Amazon ECS에 사용 중인 ENI와 함께 보고된 태스크 실패가 표시됩니다. ## The selected task definition is not compatible with the selected compute strategy 이 오류는 시작 유형이 클러스터 용량 유형과 일치하지 않는 작업 정의를 선택한 경우에 발생합니다. 클러스터에 할당된 용량 공급자와 일치하는 태스크 정의를 선택해야 합니다. ## 사용하지 않는 디바이스 인덱스에 네트워크 인터페이스를 연결할 수 없음 이 오류는 `awsvpc` 네트워킹 유형을 사용할 때 작업에 필요한 CPU/메모리가 충분하지 않을 때 발생합니다. 먼저 CPU에서 인스턴스를 확인합니다. 자세한 내용은 *Amazon EC2 인스턴스 유형*의 [Amazon EC2 인스턴스 유형 사양](https://docs.aws.amazon.com/ec2/latest/instancetypes/ec2-instance-type-specifications.html)을 참조하세요. 인스턴스의 CPU 값을 가져와 해당 인스턴스의 ENI 수를 곱합니다. 이 값을 태스크 정의에서 사용하세요. ## AGENT 태스크를 시작하려고 시도한 컨테이너 인스턴스에 현재 연결이 끊긴 에이전트가 있습니다. 작업 배치를 위한 대기 시간이 길어지는 것을 방지하기 위해 요청이 거부되었습니다. 연결이 끊어진 에이전트 문제 해결 방법에 대한 자세한 내용은 [연결이 끊어진 Amazon ECS 에이전트 문제를 해결하려면 어떻게 해야 하나요?](https://repost.aws/knowledge-center/ecs-agent-disconnected-linux2-ami)를 참조하세요. # Amazon ECS ResourceInitializationError 오류 문제 해결 다음은 몇 가지 `ResourceInitialization` 오류 메시지와 오류를 수정하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. **Topics** + [The task cannot pull registry authentication from Amazon ECR. There is a connection issue between the task and Amazon ECR. Check your task network configuration.](#unable-to-pull-secrets-ecr) + [The task can't download the environment variable files from Amazon S3. There is a connection issue between the task and Amazon S3. Check your task network configuration.](#failed-to-download-env-files) + [The task cannot pull secrets from AWS Systems Manager Parameter Store. Check your network connection between the task and AWS Systems Manager.](#unable-to-pull-secrets-sys-manager) + [The task can’t pull secrets from AWS Secrets Manager. There is a connection issue between the task and Secrets Manager. Check your task network configuration.](#unable-to-pull-secrets-asm-no-arn) + [The task can’t pull the secret from Secrets Manager. The task can't retrieve the secret with ARN ‘*secretARN*' from Secrets Manager. Check whether the secret exists in the specified Region.](#unable-to-pull-secrets-asm) + [pull command failed: unable to pull secrets or registry auth Check your task network configuration.](#pull-command-failed) + [The task cannot find the Amazon CloudWatch log group defined in the task definition. There is a connection issue between the task and Amazon CloudWatch. Check your network configuration.](#failed-to-initialize-logging-network) + [failed to initialize logging driver](#failed-to-initialize-logging) + [failed to invoke EFS utils commands to set up EFS volumes](#efs-utils-failed) ## The task cannot pull registry authentication from Amazon ECR. There is a connection issue between the task and Amazon ECR. Check your task network configuration. 이 오류는 작업을 Amazon ECR에 연결할 수 없음을 나타냅니다. 태스크와 Amazon ECR 간의 연결을 확인하세요. 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## The task can't download the environment variable files from Amazon S3. There is a connection issue between the task and Amazon S3. Check your task network configuration. 이 오류는 작업이 Amazon S3에서 환경 파일을 다운로드할 수 없는 경우에 발생합니다. 태스크와 Amazon S3 VPC 엔드포인트 간의 연결을 확인하세요. 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## The task cannot pull secrets from AWS Systems Manager Parameter Store. Check your network connection between the task and AWS Systems Manager. 이 오류는 작업이 Systems Manager의 자격 증명을 사용하여 작업 정의에서 정의한 이미지를 가져올 수 없는 경우에 발생합니다. 태스크와 Systems Manager VPC 엔드포인트 간의 연결을 확인하세요. 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## The task can’t pull secrets from AWS Secrets Manager. There is a connection issue between the task and Secrets Manager. Check your task network configuration. 이 오류는 작업이 Secrets Manager의 자격 증명을 사용하여 작업 정의에서 정의한 이미지를 가져올 수 없는 경우에 발생합니다. 이 오류는 Systems Manager VPC 엔드포인트 및 작업 간 네트워크 연결 문제가 있음을 나타냅니다. 작업 및 엔드포인트 간 연결을 확인하는 방법에 대한 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## The task can’t pull the secret from Secrets Manager. The task can't retrieve the secret with ARN ‘*secretARN*' from Secrets Manager. Check whether the secret exists in the specified Region. 이 오류는 작업이 Secrets Manager의 자격 증명을 사용하여 작업 정의에서 정의한 이미지를 가져올 수 없는 경우에 발생합니다. 이 문제의 가능한 원인은 다음 중 하나입니다. | 오류 원인 | 수행할 작업 | | --- | --- | | Secrets Manager VPC 엔드포인트 및 작업 간 네트워크 연결 문제입니다. 오류 메시지에 다음 문자열 중 하나가 표시되는 경우 네트워크 문제에 해당합니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/resource-initialization-error.html) | 작업 및 Secrets Manager 엔드포인트 간 연결을 확인합니다. 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. | | 작업 정의에 정의된 작업 실행 역할에서 Secrets Manager에 대한 권한을 보유하지 않습니다. | 작업 실행 역할에 필요한 Secrets Manager 권한을 추가합니다. 자세한 내용은 [Secrets Manager 또는 Systems Manager 권한](task_execution_IAM_role.md#task-execution-secrets) 섹션을 참조하세요. | | 암호 ARN이 존재하지 않음 | Secrets Manager에 ARN이 있는지 확인합니다. 이미지를 보는 방법에 대한 자세한 내용은 Secrets Manager 개발자 안내서의 [Find secrets in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_search-secret.html)를 참조하세요. | ## pull command failed: unable to pull secrets or registry auth Check your task network configuration. 이 오류는 태스크가 Amazon ECR, Systems Manager 또는 Secrets Manager에 연결할 수 없을 때 발생합니다. 이는 네트워크의 잘못된 구성 때문입니다. 이 문제를 해결하려면 태스크와 Amazon ECR 간의 연결을 확인하세요. 또한 태스크와 보안 암호를 저장하는 서비스(Systems Manager 또는 Secrets Manager) 간의 연결도 확인해야 합니다. 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## The task cannot find the Amazon CloudWatch log group defined in the task definition. There is a connection issue between the task and Amazon CloudWatch. Check your network configuration. 이 오류는 작업에서 작업 정의에 정의한 CloudWatch 로그 그룹을 찾지 못하는 경우에 발생합니다. 이 오류는 CloudWatch VPC 엔드포인트와 작업 간에 네트워크 연결 문제가 있음을 나타냅니다. 작업 및 엔드포인트 간 연결을 확인하는 방법에 대한 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## failed to initialize logging driver 이 오류는 작업에서 작업 정의에 정의한 CloudWatch 로그 그룹을 찾지 못하는 경우에 발생합니다. 이 오류는 작업 정의에 CloudWatch 그룹이 없음을 나타냅니다. 다음 단계에 따라 누락된 CloudWatch를 찾으세요. 1. 다음 명령을 실행하여 태스크 정의 정보를 가져옵니다. ``` aws ecs describe-task-definition \ --task-definition task-def-name ``` 각 컨테이너의 출력을 확인하여 `awslogs-group` 값을 기록해 둡니다. ``` "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/ecs/example-group", "awslogs-create-group": "true", "awslogs-region": "us-east-1", "awslogs-stream-prefix": "ecs" }, ``` 1. 그룹이 CloudWatch에 있는지 확인합니다. 자세한 내용은 Amazon CloudWatch Logs 사용 설명서의 [로그 그룹 및 로그 스트림 작업](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)을 참조하세요.** 문제는 태스크 정의에 지정된 그룹이 잘못되었거나 로그 그룹이 존재하지 않는 것입니다. 1. 문제를 해결합니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/resource-initialization-error.html) ## failed to invoke EFS utils commands to set up EFS volumes 다음 문제로 인해 작업에 Amazon EFS 볼륨을 탑재하지 못할 수 있습니다. + Amazon EFS 파일 시스템이 올바르게 구성되지 않았습니다. + 작업에 필요한 권한이 없습니다. + 네트워크 및 VPC 구성과 관련된 문제가 있습니다. 이 문제를 디버깅하고 해결하는 방법에 대한 자세한 내용은 AWS re:Post의 [Amazon EFS 볼륨을 AWS Fargate 작업에 마운트할 수 없는 이유는 무엇인가요?](https://repost.aws/knowledge-center/fargate-unable-to-mount-efs)를 참조하세요. # Amazon ECS ResourceNotFoundException 오류 문제 해결 다음은 몇 가지 ` ResourceNotFoundException` 오류 메시지와 오류를 수정하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## The task can't retrieve the secret with ARN '*sercretARN*' from AWS Secrets Manager. Check whether the secret exists in the specified Region. 이 오류는 작업이 Secrets Manager에서 암호를 검색할 수 없는 경우에 발생합니다. 즉, 작업 정의에 지정되고 암호(오류 메시지에 포함된 암호)가 Secrets Manager에 없습니다. 리전은 오류 메시지에 있습니다. Fetching secret data from AWS Secrets Manager in region *region*: secret *sercretARN*: ResourceNotFoundException: Secrets Manager can't find the specified secret. 암호에 대한 자세한 내용은 *AWS Secrets Manager 사용 설명서*의 [Find secrets in AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_search-secret.html)를 참조하세요. 다음 테이블을 사용하여 오류를 확인하고 해결합니다. | 문제 | 작업 | | --- | --- | | 암호는 작업 정의와 다른 리전에 있습니다. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/resource-not-found-error.html) | | 작업 정의에 잘못된 암호 ARN이 있습니다. 올바른 암호는 Secrets Manager에 있습니다. | 올바른 암호로 작업 정의를 업데이트합니다. 자세한 내용은 Amazon Elastic Container Service API 참조의 [RegisterTaskDefinition](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html) 또는 [콘솔을 사용하여 Amazon ECS 작업 정의 업데이트](update-task-definition-console-v2.md) 섹션을 참조하세요. | | 암호가 더 이상 존재하지 않습니다. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/resource-not-found-error.html) | # Amazon ECS SpotInterruption 오류 문제 해결 `SpotInterruption` 오류의 원인은 Fargate 및 EC2마다 다릅니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## Fargate `SpotInterruption` 오류는 Fargate 스팟 용량이 없거나 Fargate에서 스팟 용량을 회수하는 경우에 발생합니다. 여러 가용 영역에서 작업을 실행하여 더 많은 용량을 확보할 수 있습니다. ## EC2 이 오류는 사용 가능한 스팟 인스턴스가 없거나 EC2가 스팟 인스턴스 용량을 회수하는 경우에 발생합니다. 여러 가용 영역에서 인스턴스를 실행하여 더 많은 용량을 확보할 수 있습니다. # Amazon ECS InternalError 오류 문제 해결 **적용 대상**: Fargate AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. 이 `InternalError` 오류는 에이전트에서 예기치 않은 비런타임 관련 내부 오류가 발생하는 경우에 나타납니다. 이 오류는 버전이 `1.4` 이상인 플랫폼을 사용하는 경우에만 발생합니다. 이 문제를 디버깅하고 해결하는 방법에 대한 자세한 내용은 [Amazon ECS 중지된 작업 오류 메시지](stopped-task-error-codes.md) 섹션을 참조하세요. # Amazon ECS OutOfMemoryError 오류 문제 해결 다음은 몇 가지 OutOfMemoryError 오류 메시지와 오류를 해결하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## container killed due to memory usage 이 오류는 컨테이너의 프로세스가 태스크 정의에 할당된 것보다 많은 메모리를 소비하거나 호스트 또는 운영 체제 제약 조건에 따라 컨테이너가 종료될 때 발생합니다. # Amazon ECS ContainerRuntimeError 오류 문제 해결 다음은 몇 가지 ContainerRuntimeError 오류 메시지와 오류를 해결하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## ContainerRuntimeError 이 오류는 에이전트가 런타임별 작업에 대해 `containerd`에서 예기치 않은 오류를 수신할 때 발생합니다. 이 오류는 일반적으로 에이전트 또는 `containerd` 런타임의 내부 오류로 인해 발생합니다. 이 오류는 플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0` 이상(Windows)을 사용하는 경우에만 발생합니다. 이 문제를 디버깅하고 해결하는 방법에 대한 자세한 내용은 AWS re:Post에서 [Amazon ECS 태스크가 중지되었는데 이유가 무엇인가요?](https://repost.aws/knowledge-center/ecs-task-stopped)를 참조하세요. # Amazon ECS ContainerRuntimeTimeoutError 오류 문제 해결 다음은 몇 가지 ContainerRuntimeTimeoutError 오류 메시지와 오류를 해결하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## Could not transition to running; timed out after waiting 1m or Docker timeout error 이 오류는 컨테이너가 제한 시간 내에 `RUNNING` 또는 `STOPPED` 상태로 전환 할 수 없을 때 발생합니다. 오류 메시지에 원인 및 제한 시간 값이 제공됩니다. # Amazon ECS CannotStartContainerError 오류 문제 해결 다음은 몇 가지 CannotStartContainerError 오류 메시지와 오류를 해결하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## failed to get container status: ** 이 오류는 컨테이너를 시작할 수 없을 때 발생합니다. 컨테이너가 여기에 지정된 메모리를 초과하려 하면 해당 컨테이너가 중지됩니다. 컨테이너에 제공되는 메모리를 늘립니다. 태스크 정의에서 `memory` 파라미터를 사용하면 됩니다. 자세한 내용은 [Memory](task_definition_parameters.md#container_definition_memory) 섹션을 참조하세요. # Amazon ECS CannotStopContainerError 오류 문제 해결 다음은 몇 가지 CannotStopContainerError 오류 메시지와 오류를 해결하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## CannotStopContainerError 이 오류는 컨테이너가 중지되었을 때 발생합니다. 이 문제를 디버깅하고 해결하는 방법에 대한 자세한 내용은 AWS re:Post에서 [Amazon ECS 태스크가 중지되었는데 이유가 무엇인가요?](https://repost.aws/knowledge-center/ecs-task-stopped)를 참조하세요. # Amazon ECS CannotInspectContainerError 오류 문제 해결 다음은 몇 가지 CannotInspectContainerError 오류 메시지와 오류를 해결하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## CannotInspectContainerError 이 오류는 컨테이너 에이전트가 컨테이너 런타임을 통해 컨테이너를 설명할 수 없을 때 발생합니다. 플랫폼 버전 `1.3` 이하를 사용하면 Amazon ECS 에이전트가 Docker에서 이유를 반환합니다. 플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0` 이상(Windows)을 사용하는 경우 Fargate 에이전트는 `containerd`에서 이유를 반환합니다. 이 문제를 디버깅하고 해결하는 방법에 대한 자세한 내용은 AWS re:Post에서 [Amazon ECS 태스크가 중지되었는데 이유가 무엇인가요?](https://repost.aws/knowledge-center/ecs-task-stopped)를 참조하세요. # Amazon ECS CannotCreateVolumeError 오류 문제 해결 다음은 몇 가지 CannotCreateVolumeError 오류 메시지와 오류를 해결하기 위해 수행할 수 있는 작업입니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. ## CannotCreateVolumeError 이 오류는 에이전트가 태스크 정의에 지정된 볼륨 마운트를 생성할 수 없는 경우에 발생합니다. 이 오류는 플랫폼 버전 `1.4.0` 이상(Linux) 또는 `1.0.0` 이상(Windows)을 사용하는 경우에만 발생합니다. 이 문제를 디버깅하고 해결하는 방법에 대한 자세한 내용은 AWS re:Post에서 [Amazon ECS 태스크가 중지되었는데 이유가 무엇인가요?](https://repost.aws/knowledge-center/ecs-task-stopped)를 참조하세요. # Amazon ECS에서 CannotPullContainer 작업 오류 다음 오류는 Amazon ECS가 지정된 컨테이너 이미지를 검색할 수 없어 작업을 시작하지 못했음을 나타냅니다. **참고** 1.4 Fargate 플랫폼 버전은 긴 오류 메시지를 자릅니다. AWS Management Console을 사용하여 중지된 작업에서 오류 메시지를 확인하려면 [Amazon ECS 중지된 작업 오류 보기](stopped-task-errors.md) 섹션을 참조하세요. **작은 정보** [Amazon ECS MCP 서버](ecs-mcp-introduction.md)를 AI 어시스턴트와 함께 사용하여 자연어로 이미지 풀 오류를 조사할 수 있습니다. **Topics** + [The task can’t pull the image. Check that the role has the permissions to pull images from the registry.](#pull-request-image-not-found) + [The task cannot pull ‘*image-name*’ from the Amazon ECR repository ‘*repository URI*’. There is a connection issue between the task and Amazon ECR. Check your task network configuration.](#pull-image-io-timeout) + [The task can’t pull the image. Check your network configuration](#pull-request-image-not-found-network) + [CannotPullContainerError: 풀 이미지 매니페스트가 5회 재시도됨: 참조를 확인하지 못함](#pull-request-image-tag) + [API error (500): Get https://111122223333.dkr.ecr.us-east-1.amazonaws.com/v2/: net/http: request canceled while waiting for connection](#request-canceled) + [API 오류](#pull-request-api-error) + [write /var/lib/docker/tmp/*GetImageBlob111111111*: no space left on device](#pull-request-write-error) + [ERROR: toomanyrequests: Too Many Requests or You have reached your pull rate limit.](#container-pull-too-many-requests) + [Error response from daemon: Get *url*: net/http: request canceled while waiting for connection](#container-pull-request-canceled-connection) + [ref pull has been retried 1 time(s): failed to copy: httpReaderSeeker: failed open: unexpected status code](#container-pull-failed-open) + [pull access denied](#container-pull-access-denied.title) + [pull command failed: panic: runtime error: invalid memory address or nil pointer dereference](#container-pull-runtime-error.title) + [error pulling image conf/error pulling image configuration](#container-pull-pulling-image.title) + [컨텍스트 취소됨](#container-pull-context-canceled) ## The task can’t pull the image. Check that the role has the permissions to pull images from the registry. 이 오류는 권한 문제 때문에 작업이 작업 정의에 지정된 이미지를 가져올 수 없음을 나타냅니다. 이 문제를 해결하려면: 1. *Rrepository*에 이미지가 있는지 확인합니다. 이미지 보기에 대한 자세한 내용은 *Amazon Elastic Container Registry 사용 설명서*의 [Viewing image details in Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-info.html)을 참조하세요. 1. *role-arn*에 이미지를 가져올 수 있는 올바른 권한이 있는지 확인합니다. 역할을 업데이트하는 방법에 대한 자세한 내용은 *AWS Identity and Access Management 사용 설명서*의 [역할에 대한 권한 업데이트](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-permissions.html)를 참조하세요. 작업은 다음 역할 중 하나를 사용합니다. + Fargate에서의 태스크인 경우 태스크 실행 역할입니다. Amazon ECR의 추가 권한에 대한 자세한 내용은 [인터페이스 엔드포인트 권한을 통해 Amazon ECR 이미지를 가져오는 Fargate 작업](task_execution_IAM_role.md#task-execution-ecr-conditionkeys) 섹션을 참조하세요. + EC2를 사용하는 태스크의 경우 이는 컨테이너 인스턴스 역할입니다. Amazon ECR의 추가 권한에 대한 자세한 내용은 [Amazon ECR 권한](instance_IAM_role.md#container-instance-role-ecr) 섹션을 참조하세요. ## The task cannot pull ‘*image-name*’ from the Amazon ECR repository ‘*repository URI*’. There is a connection issue between the task and Amazon ECR. Check your task network configuration. 이 오류는 작업을 Amazon ECR에 연결할 수 없음을 나타냅니다. *repository URI* 리포지토리에 대한 연결을 확인하세요. 이 문제를 확인하고 해결하는 방법에 대한 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## The task can’t pull the image. Check your network configuration 이 오류는 작업을 Amazon ECR에 연결할 수 없음을 나타냅니다. 이 문제를 확인하고 해결하는 방법에 대한 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## CannotPullContainerError: 풀 이미지 매니페스트가 5회 재시도됨: 참조를 확인하지 못함 이 오류는 태스크가 이미지를 가져올 수 없음을 나타냅니다. 이 문제는 다음과 같은 방법으로 해결할 수 있습니다. + 태스크 정의에 지정된 이미지가 리포지토리의 이미지와 일치하는지 확인하세요. + Amazon ECS는 이미지 버전 안정성을 강화합니다. 원본 이미지를 더 이상 사용할 수 없는 경우 이 오류가 발생합니다. 이미지 태그는 이 동작을 적용하는 데 포함됩니다. 태스크 정의의 이미지를 태그로 :latest를 사용하는 것에서 특정 버전으로 변경합니다. 자세한 내용은 [컨테이너 이미지 확인](deployment-type-ecs.md#deployment-container-image-stability) 섹션을 참조하세요. 이 문제를 확인하고 해결하는 방법에 대한 자세한 내용은 [Amazon ECS 중지된 작업 오류 연결 확인](verify-connectivity.md) 섹션을 참조하세요. ## API error (500): Get https://111122223333.dkr.ecr.us-east-1.amazonaws.com/v2/: net/http: request canceled while waiting for connection 이 오류는 인터넷 경로가 존재하지 않아 연결 제한 시간이 초과되었음을 나타냅니다. 다음과 같은 방법으로 이 문제를 해결할 수 있습니다. + 퍼블릭 서브넷에 있는 작업의 경우 태스크를 시작할 때 **퍼블릭 IP 자동 할당(Auto-assign public IP)**을 **활성화됨(ENABLED)**으로 지정합니다. 자세한 내용은 [애플리케이션을 Amazon ECS 태스크로 실행](standalone-task-create.md) 섹션을 참조하세요. + 프라이빗 서브넷에 있는 작업의 경우 태스크를 시작할 때 **퍼블릭 IP 자동 할당(Auto-assign public IP)**을 **비활성화됨(DISABLED)**으로 지정하고 요청을 인터넷으로 라우팅하도록 VPC에 NAT 게이트웨이를 구성합니다. 자세한 내용은 *Amazon VPC 사용 설명서*의 [NAT 게이트웨이](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) 섹션을 참조하세요. ## API 오류 이 오류는 Amazon ECR 엔드포인트에 연결 문제가 있음을 나타냅니다. 이 문제를 해결하는 방법에 대한 자세한 내용은 지원 웹 사이트의 [Amazon ECS에서 Amazon ECR 오류 'CannotPullContainerError: API error'를 해결하려면 어떻게 해야 하나요?](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-api-error-ecr/)를 참조하세요. ## write /var/lib/docker/tmp/*GetImageBlob111111111*: no space left on device 이 오류는 디스크 스페이스가 부족함을 나타냅니다. 이 문제를 해결하려면 디스크 스페이스를 늘리세요. Amazon ECS 최적화 AMI를 사용하는 경우, 다음 명령을 사용하여 파일 시스템에서 가장 큰 파일 20개를 검색할 수 있습니다. ``` du -Sh / | sort -rh | head -20 ``` 출력 예시: ``` 5.7G /var/lib/docker/containers/50501b5f4cbf90b406e0ca60bf4e6d4ec8f773a6c1d2b451ed8e0195418ad0d2 1.2G /var/log/ecs 594M /var/lib/docker/devicemapper/mnt/c8e3010e36ce4c089bf286a623699f5233097ca126ebd5a700af023a5127633d/rootfs/data/logs ... ``` 일부 경우에 실행 중인 컨테이너로 루트 볼륨을 채울 수 있습니다. 컨테이너에서 기본 `json-file` 로그 드라이브를 `max-size` 제한 없이 사용하는 경우, 로그 파일이 스페이스의 대부분을 사용하는 것일 수 있습니다. `docker ps` 명령으로 위 출력의 디렉토리 이름을 컨테이너 ID로 매핑하여 스페이스를 사용하는 컨테이너를 확인할 수 있습니다. 예: ``` CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 50501b5f4cbf amazon/amazon-ecs-agent:latest "/agent" 4 days ago Up 4 days ecs-agent ``` 기본적으로 `json-file` 로그 드라이버를 사용할 때 Docker는 전체 컨테이너의 표준 출력(및 표준 오류)를 캡처하고 이것을 JSON 형식으로 파일에 작성합니다. 로그 파일이 스페이스를 너무 많이 차지하는 것을 방지하는 로그 드라이버 옵션으로 `max-size`를 설정할 수 있습니다. 자세한 내용은 Docker 설명서의 [JSON 파일 로깅 드라이버](https://docs.docker.com/engine/logging/drivers/json-file/)를 참조하세요. 다음은 이 옵션을 사용하는 방법을 보여주는 컨테이너 정의 조각입니다. ``` { "log-driver": "json-file", "log-opts": { "max-size": "256m" } } ``` 또는 컨테이너 로그가 디스크 스페이스를 너무 많이 차지할 경우 `awslogs` 로그 드라이버를 사용하는 방법도 있습니다. `awslogs` 로그 드라이버는 CloudWatch로 로그를 전송하기 때문에 컨테이너 인스턴스에서 컨테이너 로그용으로 사용되는 만큼의 디스크 스페이스가 생깁니다. 자세한 내용은 [Amazon ECS 로그를 CloudWatch로 전송](using_awslogs.md) 섹션을 참조하세요. Docker에서 액세스할 수 있는 디스크 크기를 업데이트해야 할 수 있습니다. 자세한 내용은 [CannotPullContainerError: no space left on device](https://repost.aws/questions/QUx6Ix1R1SSNisYSs1Sw8EBA/cannotpullcontainererror-no-space-left-on-device)를 참조하세요. ## ERROR: toomanyrequests: Too Many Requests or You have reached your pull rate limit. 이 오류는 Docker Hub 속도 제한이 있음을 나타냅니다. 다음 오류 중 하나가 발생하는 경우 Docker Hub 속도 제한에 도달했을 가능성이 있습니다. Docker Hub 속도 제한에 대한 자세한 내용은 [Docker Hub 속도 제한 이해](https://www.docker.com/increase-rate-limits) 섹션을 참조하세요. Docker Hub 속도 제한을 늘리고 컨테이너 인스턴스에 대한 Docker 가져오기를 인증해야 하는 경우 [Private registry authentication for container instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth-container-instances.html)를 참조하세요. ## Error response from daemon: Get *url*: net/http: request canceled while waiting for connection 이 오류는 인터넷 경로가 존재하지 않아 연결 제한 시간이 초과되었음을 나타냅니다. 다음과 같은 방법으로 이 문제를 해결할 수 있습니다. + 퍼블릭 서브넷에 있는 작업의 경우 태스크를 시작할 때 **퍼블릭 IP 자동 할당(Auto-assign public IP)**을 **활성화됨(ENABLED)**으로 지정합니다. 자세한 내용은 [애플리케이션을 Amazon ECS 태스크로 실행](standalone-task-create.md) 섹션을 참조하세요. + 프라이빗 서브넷에 있는 작업의 경우 태스크를 시작할 때 **퍼블릭 IP 자동 할당(Auto-assign public IP)**을 **비활성화됨(DISABLED)**으로 지정하고 요청을 인터넷으로 라우팅하도록 VPC에 NAT 게이트웨이를 구성합니다. 자세한 내용은 *Amazon VPC 사용 설명서*의 [NAT 게이트웨이](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) 섹션을 참조하세요. ## ref pull has been retried 1 time(s): failed to copy: httpReaderSeeker: failed open: unexpected status code 이 오류는 이미지를 복사할 때 실패했음을 나타냅니다. 이 문제를 해결하려면 다음 문서 중 하나를 검토합니다. + Fargate 작업에 대한 자세한 내용은 [Fargate의 내 Amazon ECS 작업에 대한 "cannotpullcontainererror" 오류를 해결하는 방법](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-fargate-pull-container-error/)을 참조하세요. + 기타 작업에 대한 자세한 내용은 [내 Amazon ECS 작업에 대한 "cannotpullcontainererror" 오류를 해결하는 방법](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-error/)을 참조하세요. ## pull access denied 이 오류는 이미지에 대한 액세스 권한이 없음을 나타냅니다. 이 문제를 해결하려면 Amazon ECR을 사용하여 Docker 클라이언트를 인증해야 할 수 있습니다. 자세한 내용은 *Amazon ECR 사용 설명서*의 [프라이빗 레지스트리 인증](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html)을 참조하세요. ## pull command failed: panic: runtime error: invalid memory address or nil pointer dereference 이 오류는 잘못된 메모리 주소 또는 nil 포인터 역참조로 인해 이미지에 액세스할 수 없음을 나타냅니다. 이 문제를 해결하려면: + Amazon S3에 접속하기 위한 보안 그룹 규칙이 있는지 확인합니다. + 게이트웨이 엔드포인트를 사용하는 경우, 엔드포인트에 액세스하려면 라우팅 테이블에 경로를 추가해야 합니다. ## error pulling image conf/error pulling image configuration 이 오류는 속도 제한에 도달했거나 네트워크 오류가 있음을 나타냅니다. 이 문제를 해결하려면 [How can I resolve the "CannotPullContainerError" error in my Amazon ECS EC2 Launch Type Task](https://repost.aws/knowledge-center/ecs-pull-container-error)를 참조하세요. ## 컨텍스트 취소됨 이 오류는 컨텍스트가 취소되었음을 나타냅니다. 이 오류의 일반적인 원인은 작업에서 사용 중인 VPC에 Amazon ECR에서 컨테이너 이미지를 가져오기 위한 경로가 없기 때문입니다. # Amazon ECS 중지된 작업 오류 연결 확인 네트워크 연결 문제로 인해 작업이 중지되는 경우가 있습니다. 간헐적으로 발생하는 문제일 수 있지만 대부분의 경우 작업을 엔드포인트에 연결할 수 없기 때문에 발생합니다. ## 작업 연결 테스트 `AWSSupport-TroubleshootECSTaskFailedToStart` 런북을 사용하여 작업 연결을 테스트할 수 있습니다. 런북을 사용하는 경우 다음 리소스 정보가 필요합니다. + 작업 ID 최근 실패한 작업을 사용합니다. + 작업이 있는 클러스터 런북을 사용하는 방법에 대한 자세한 내용은 AWS Systems Manager 자동화 런북 참조의 [https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-aws-troubleshootecstaskfailedtostart.html](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-aws-troubleshootecstaskfailedtostart.html) 섹션을 참조하세요.** 런북에서 작업을 분석합니다. 작업 시작을 방해할 수 있는 다음 문제에 대한 결과는 **출력** 섹션에서 볼 수 있습니다. + 구성된 컨테이너 레지스트리에 대한 네트워크 연결 + VPC 엔드포인트 연결 + 보안 그룹 규칙 구성 ## VPC 엔드포인트 문제 해결 `AWSSupport-TroubleshootECSTaskFailedToStart` 런북 결과에 VPC 엔드포인트 문제가 표시되면 다음 구성을 확인합니다. + 엔드포인트 및 VPC 엔드포인트를 생성하는 VPC는 프라이빗 DNS를 사용해야 합니다. + 서비스에서 작업과 동일한 VPC에 작업을 연결할 수 없는 AWS PrivateLink 엔드포인트가 있는지 확인합니다. 자세한 내용은 다음 중 하나를 참조하세요. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/verify-connectivity.html) + 포트 443 DNS(TCP) 트래픽에서 HTTPS를 허용하는 작업 서브넷의 아웃바운드 규칙을 구성합니다. 자세한 내용은 *Amazon Elastic Compute Cloud 사용 설명서*의 [보안 그룹 규칙 구성](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/changing-security-group.html#add-remove-security-group-rules)을 참조하세요. + 사용자 지정 이름 도메인 서버를 사용하는 경우 DNS 쿼리의 설정을 확인합니다. 쿼리는 포트 53에 아웃바운드 액세스 권한이 있어야 하며 UDP 및 TCP 프로토콜을 사용해야 합니다. 또한 포트 443에 HTTPS 액세스 권한이 있어야 합니다. 자세한 내용은 *Amazon Elastic Compute Cloud 사용 설명서*에서 [보안 그룹 규칙 구성](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/changing-security-group.html#add-remove-security-group-rules)을 참조하세요. + 서브넷에 네트워크 ACL이 있는 경우 다음 ACL 규칙이 필요합니다. + 포트 1024\$165535의 트래픽을 허용하는 아웃바운드 규칙. + 포트 443의 TCP 트래픽을 허용하는 인바운드 규칙. 규칙을 구성하는 방법에 대한 자세한 내용은 **Amazon Virtual Private Cloud 사용 설명서의 [네트워크 ACL을 사용하여 서브넷에 대한 트래픽 제어](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html)를 참조하세요. ## 네트워크 문제 해결 `AWSSupport-TroubleshootECSTaskFailedToStart` 런북 결과에 네트워크 문제가 표시되면 다음 구성을 확인합니다. ### 퍼블릭 서브넷에서 awsvpc 네트워크 모드를 사용하는 작업 런북을 기반으로 다음 구성을 수행합니다. + 퍼블릭 서브넷에 있는 작업의 경우 태스크를 시작할 때 **퍼블릭 IP 자동 할당(Auto-assign public IP)**을 **활성화됨(ENABLED)**으로 지정합니다. 자세한 내용은 [애플리케이션을 Amazon ECS 태스크로 실행](standalone-task-create.md) 섹션을 참조하세요. + 인터넷 트래픽을 처리하려면 게이트웨이가 필요합니다. 작업 서브넷의 라우팅 테이블에는 게이트웨이로 향하는 트래픽의 경로가 있어야 합니다. 자세한 내용은 *Amazon Virtual Private Cloud 사용 설명서*의 [라우팅 테이블에서 경로 추가 및 제거](https://docs.aws.amazon.com/vpc/latest/userguide/WorkWithRouteTables.html#AddRemoveRoutes)를 참조하세요. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/verify-connectivity.html) + 작업 서브넷에 네트워크 ACL이 있는 경우 다음 ACL 규칙이 필요합니다. + 포트 1024\$165535의 트래픽을 허용하는 아웃바운드 규칙. + 포트 443의 TCP 트래픽을 허용하는 인바운드 규칙. 규칙을 구성하는 방법에 대한 자세한 내용은 *Amazon Virtual Private Cloud 사용 설명서*의 [네트워크 ACL을 사용하여 서브넷에 대한 트래픽 제어](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html)를 참조하세요. ### 프라이빗 서브넷에서 awsvpc 네트워크 모드를 사용하는 작업 런북을 기반으로 다음 구성을 수행합니다. + 작업을 시작할 때 **퍼블릭 IP 자동 할당**을 수행하려면 **비활성화됨**을 선택합니다. + 요청을 인터넷으로 라우팅하도록 VPC에서 NAT 게이트웨이를 구성합니다. 자세한 내용은 *Amazon Virtual Private Cloud 사용 설명서*의 [NAT 게이트웨이](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)를 참조하세요. + 작업 서브넷의 라우팅 테이블에는 NAT 게이트웨이로 향하는 트래픽의 경로가 있어야 합니다. 자세한 내용은 **Amazon Virtual Private Cloud 사용 설명서의 [라우팅 테이블에서 경로 추가 및 제거](https://docs.aws.amazon.com/vpc/latest/userguide/WorkWithRouteTables.html#AddRemoveRoutes)를 참조하세요. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/verify-connectivity.html) + 작업 서브넷에 네트워크 ACL이 있는 경우 다음 ACL 규칙이 필요합니다. + 포트 1024\$165535의 트래픽을 허용하는 아웃바운드 규칙. + 포트 443의 TCP 트래픽을 허용하는 인바운드 규칙. 규칙을 구성하는 방법에 대한 자세한 내용은 **Amazon Virtual Private Cloud 사용 설명서의 [네트워크 ACL을 사용하여 서브넷에 대한 트래픽 제어](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html)를 참조하세요. ### 퍼블릭 서브넷에서 awsvpc 네트워크 모드를 사용하지 않는 작업 런북을 기반으로 다음 구성을 수행합니다. + 클러스터를 생성할 때 **Amazon EC2 인스턴스를 위한 네트워킹** 아래 **IP 자동 할당**에서 **켜기**를 선택합니다. 이 옵션은 인스턴스의 기본 네트워크 인터페이스에 퍼블릭 IP 주소를 할당합니다. + 인터넷 트래픽을 처리하려면 게이트웨이가 필요합니다. 인스턴스 서브넷의 라우팅 테이블에는 게이트웨이로 향하는 트래픽의 경로가 있어야 합니다. 자세한 내용은 **Amazon Virtual Private Cloud 사용 설명서의 [라우팅 테이블에서 경로 추가 및 제거](https://docs.aws.amazon.com/vpc/latest/userguide/WorkWithRouteTables.html#AddRemoveRoutes)를 참조하세요. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/verify-connectivity.html) + 인스턴스 서브넷에 네트워크 ACL이 있는 경우 다음 ACL 규칙이 필요합니다. + 포트 1024\$165535의 트래픽을 허용하는 아웃바운드 규칙. + 포트 443의 TCP 트래픽을 허용하는 인바운드 규칙. 규칙을 구성하는 방법에 대한 자세한 내용은 *Amazon Virtual Private Cloud 사용 설명서*의 [네트워크 ACL을 사용하여 서브넷에 대한 트래픽 제어](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html)를 참조하세요. ### 프라이빗 서브넷에서 awsvpc 네트워크 모드를 사용하지 않는 태스크 런북을 기반으로 다음 구성을 수행합니다. + 클러스터를 생성할 때 **Amazon EC2 인스턴스를 위한 네트워킹** 아래 **IP 자동 할당**에서 **끄기**를 선택합니다. + 요청을 인터넷으로 라우팅하도록 VPC에서 NAT 게이트웨이를 구성합니다. 자세한 정보는 *Amazon VPC 사용 설명서*의 [NAT 게이트웨이](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html) 섹션을 참조하세요. + 인스턴스 서브넷의 라우팅 테이블에는 NAT 게이트웨이로 향하는 트래픽의 경로가 있어야 합니다. 자세한 내용은 **Amazon Virtual Private Cloud 사용 설명서의 [라우팅 테이블에서 경로 추가 및 제거](https://docs.aws.amazon.com/vpc/latest/userguide/WorkWithRouteTables.html#AddRemoveRoutes)를 참조하세요. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/verify-connectivity.html) + 작업 서브넷에 네트워크 ACL이 있는 경우 다음 ACL 규칙이 필요합니다. + 포트 1024\$165535의 트래픽을 허용하는 아웃바운드 규칙. + 포트 443의 TCP 트래픽을 허용하는 인바운드 규칙. 규칙을 구성하는 방법에 대한 자세한 내용은 **Amazon Virtual Private Cloud 사용 설명서의 [네트워크 ACL을 사용하여 서브넷에 대한 트래픽 제어](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html)를 참조하세요. # Amazon ECS 태스크에 대한 IAM 역할 요청 보기 IAM 역할에서 태스크 자격 증명으로 공급자를 사용하면 공급자 요청이 감사 로그에 저장됩니다. 감사 로그는 컨테이너 에이전트 로그와 동일한 로그 교체 설정을 상속합니다. `ECS_LOG_ROLLOVER_TYPE`, `ECS_LOG_MAX_FILE_SIZE_MB` 및 `ECS_LOG_MAX_ROLL_COUNT` 컨테이너 에이전트 구성 변수는 감사 로그의 동작에 영향을 미치도록 설정할 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 로그 구성 파라미터](ecs-agent-versions.md#agent-logs) 섹션을 참조하세요. 컨테이너 에이전트 버전 1.36.0 이상에서는 감사 로그가 `/var/log/ecs/audit.log`에 있습니다. 로그가 교체되면 `YYYY-MM-DD-HH` 형식의 타임스탬프가 로그 파일 이름의 끝에 추가됩니다. 컨테이너 에이전트 버전 1.35.0 및 이전 버전의 경우 감사 로그는 `/var/log/ecs/audit.log.YYYY-MM-DD-HH`에 있습니다. 로그 항목 형식은 다음과 같습니다. + 타임스탬프 + HTTP 응답 코드 + 요청 오리진의 IP 주소와 포트 번호 + 자격 증명 공급자의 상대 URI + 요청을 한 사용자 에이전트 + 요청 컨테이너가 속한 작업의 ARN + `GetCredentials` API 이름 및 버전 번호 + 컨테이너 인스턴스가 등록된 Amazon ECS 클러스터의 이름 + 컨테이너 인스턴스 ARN 다음 명령을 사용하여 로그 파일을 볼 수 있습니다. ``` cat /var/log/ecs/audit.log.2016-07-13-16 ``` 출력: ``` 2016-07-13T16:11:53Z 200 172.17.0.5:52444 "/v1/credentials" "python-requests/2.7.0 CPython/2.7.6 Linux/4.4.14-24.50.amzn1.x86_64" TASK_ARN GetCredentials 1 CLUSTER_NAME CONTAINER_INSTANCE_ARN ``` # Amazon ECS 서비스 이벤트 메시지 보기 서비스 문제를 해결하려는 경우, 제일 먼저 진단 정보를 확인할 곳은 서비스 이벤트 로그입니다. `DescribeServices` API, AWS CLI 또는 AWS Management Console을 사용하여 서비스 이벤트를 볼 수 있습니다. Amazon ECS API를 사용하여 서비스 이벤트 메시지를 보는 경우 서비스 스케줄러의 이벤트만 반환됩니다. 여기에는 가장 최근의 작업 배치 및 인스턴스 상태 이벤트가 포함됩니다. 그러나 Amazon ECS 콘솔에는 다음 소스의 서비스 이벤트가 표시됩니다. + Amazon ECS 서비스 스케줄러의 작업 배치 및 인스턴스 상태 이벤트. 이러한 이벤트의 접두사는 **service *(service-name)***입니다. 이 이벤트 보기가 도움이 되도록 `100`개의 최신 이벤트만 표시합니다. 원인이 해결되거나 6시간이 경과할 때까지 중복 이벤트 메시지가 생략됩니다. 6시간 이내에 원인이 해결되지 않으면 해당 원인에 대한 다른 서비스 이벤트 메시지를 수신합니다. + 서비스 Auto Scaling 이벤트. 이러한 이벤트는 **Message** 접두사가 있고 서비스가 Application Auto Scaling 오토 스케일링 정책을 사용하여 구성된 경우에만 발생합니다. **작은 정보** [Amazon ECS MCP 서버](ecs-mcp-introduction.md)를 AI 어시스턴트와 함께 사용하여 자연어로 서비스 이벤트를 분석할 수 있습니다. 다음 단계에 따라 현재 서비스 이벤트 메시지를 확인합니다. ------ #### [ Console ] 1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다. 1. 탐색 창에서 **클러스터**를 선택합니다. 1. **클러스터(Clusters)** 페이지에서 클러스터를 선택합니다. 1. 검사할 서비스를 선택합니다. 1. **이벤트** 탭에서 메시지를 확인하세요. ------ #### [ AWS CLI ] [describe-services](https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-services.html) 명령을 사용하여 지정된 서비스에 대한 서비스 이벤트 메시지를 확인합니다. 다음 AWS CLI 예제에서 설명하는 *기본* 클러스터의 *service-name* 서비스는 최신 서비스 이벤트 메시지를 제공합니다. ``` aws ecs describe-services \ --cluster default \ --services service-name \ --region us-west-2 ``` ------ # Amazon ECS 서비스 이벤트 메시지 다음은 Amazon ECS 콘솔에서 볼 수 있는 서비스 이벤트 메시지의 예제입니다. ## 서비스(*service-name*)가 안정적인 상태에 도달했습니다. 서비스 스케줄러는 `service (service-name) has reached a steady state.` 서비스가 정상이고 원하는 수의 작업에 도달하면 서비스 이벤트를 보내 안정적인 상태에 도달합니다. 서비스 스케줄러는 주기적으로 상태를 보고하므로 이 메시지를 여러 번 받을 수 있습니다. ## 모든 요구 사항을 충족하는 컨테이너 인스턴스가 없기 때문에 서비스(*service-name*)가 태스크를 배치할 수 없습니다. 서비스 스케줄러는 다른 작업을 추가하는 데 사용 가능한 리소스를 찾을 수 없을 때 이 이벤트 메시지를 보냅니다. 가능한 원인은 다음과 같습니다. 용량 공급자를 사용하여 자동으로 EC2 인스턴스 규모를 조정합니다. 자세한 내용은 [EC2 워크로드를 위한 Amazon ECS 용량 공급자](asg-capacity-providers.md) 섹션을 참조하세요. 용량 공급자를 사용하려는 경우 용량 공급자 전략을 전달하거나 클러스터와 연결된 기본 용량 공급자 전략이 있고 시작 유형 및 용량 공급자 전략을 입력으로 전달하지 않아야 합니다. 클러스터에서 컨테이너 인스턴스를 찾을 수 없음 작업을 실행하려는 클러스터에 등록된 컨테이너 인스턴스가 없는 경우 이 오류가 발생합니다. 클러스터에 컨테이너 인스턴스를 추가해야 합니다. 자세한 내용은 [Amazon ECS Linux 컨테이너 인스턴스 시작](launch_container_instance.md) 섹션을 참조하세요. 포트가 충분하지 않음 작업에서 고정된 호스트 포트 매핑을 사용하는 경우(예를 들어 작업이 웹 서버 호스트에서 포트 80을 사용하는 경우), 하나의 컨테이너만 한 번에 하나의 호스트 포트를 사용할 수 있기 때문에 작업당 하나 이상의 컨테이너 인스턴스가 있어야 합니다. 클러스터에 컨테이너 인스턴스를 추가하거나 원하는 작업 수를 줄여야 합니다. 너무 많은 포트가 등록되었습니다. 작업 배치에 가장 근접하게 일치하는 컨테이너 인스턴스는 컨테이너 인스턴스당 허용되는 최대 예약 포트 제한인 100개의 호스트 포트를 초과할 수 없습니다. 동적 호스트 포트 매핑을 사용하면 문제가 해결될 수 있습니다. 포트 이미 사용 중 이 작업의 작업 정의는 선택된 컨테이너 인스턴스에서 이미 실행 중인 작업과 동일한 포트를 포트 매핑에 사용합니다. 서비스 이벤트 메시지에는 아래 메시지의 일부로 선택된 컨테이너 인스턴스 ID가 있습니다. ``` The closest matching container-instance is already using a port required by your task. ``` 메모리가 충분하지 않음 태스크 정의에서 지정된 메모리가 1000MiB이고 클러스터의 컨테이너 인스턴스 각각의 메모리가 1024MiB이라면 컨테이너 인스턴스당 이 작업의 사본 하나만 실행할 수 있습니다. 컨테이너 인스턴스당 2개 이상의 태스크를 시작하거나 보다 많은 컨테이너 인스턴스를 클러스터로 시작할 수 있도록 태스크 정의에서 이보다 적은 메모리를 실험할 수 있습니다. 특정 인스턴스 유형에 대해 태스크에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화하려는 경우 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요. CPU가 충분하지 않음 하나의 컨테이너 인스턴스에는 CPU 코어마다 1,024개의 CPU 단위가 있습니다. 태스크 정의에서 지정된 CPU 단위가 1,000이고 클러스터의 컨테이너 인스턴스 각각의 CPU 단위가 1,024라면 컨테이너 인스턴스당 이 작업의 사본 하나만 실행할 수 있습니다. 컨테이너 인스턴스당 2개 이상의 태스크를 시작하거나 보다 많은 컨테이너 인스턴스를 클러스터로 시작할 수 있도록 태스크 정의에서 이보다 적은 CPU 단위를 시험해 볼 수 있습니다. 사용 가능한 ENI 연결 지점이 충분하지 않음 `awsvpc` 네트워크 모드를 사용하는 태스크는 각각 고유한 탄력적 네트워크 인터페이스(ENI)를 받습니다. 이 ENI는 이를 호스팅하는 컨테이너 인스턴스에 연결되어 있습니다. Amazon EC2 인스턴스는 연결할 수 있는 ENI 개수에 대한 제한이 있고 클러스터에 사용 가능한 ENI 용량이 있는 컨테이너 인스턴스가 없습니다. 개별 컨테이너 인스턴스에 대한 ENI 제한은 다음 조건에 따라 다릅니다. + `awsvpcTrunking` 계정 설정에 옵트인**하지 않은** 경우 각 컨테이너 인스턴스에 대한 ENI 제한은 인스턴스 유형에 따라 다릅니다. 자세한 내용은 *Amazon EC2 사용 설명서*의 [인스턴스 유형별/네트워크 인터페이스당 IP 주소](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)를 참조하세요. + `awsvpcTrunking` 계정 설정에 옵트인**했지만** 옵트인 후 지원되는 인스턴스 유형을 사용하여 새로운 컨테이너 인스턴스를 시작하지 **않은** 경우 각 컨테이너 인스턴스에 대한 ENI 제한은 여전히 기본값으로 설정됩니다. 자세한 내용은 *Amazon EC2 사용 설명서*의 [인스턴스 유형별/네트워크 인터페이스당 IP 주소](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)를 참조하세요. + `awsvpcTrunking` 계정 설정에 옵트인**했으며** 옵트인 후 지원되는 인스턴스 유형을 사용하여 새 컨테이너 인스턴스를 **시작한** 경우 추가 ENI를 사용할 수 있습니다. 자세한 내용은 [증가한 Amazon ECS 컨테이너 네트워크 인터페이스에 대해 지원되는 인스턴스](eni-trunking-supported-instance-types.md) 섹션을 참조하세요. `awsvpcTrunking` 계정 설정 옵트인에 대한 자세한 내용은 [Amazon ECS Linux 컨테이너 인스턴스 네트워크 인터페이스 증가](container-instance-eni.md) 섹션을 참조하세요. 클러스터에 컨테이너 인스턴스를 추가하여 가용 네트워크 어댑터를 더 많이 제공할 수 있습니다. 필요한 속성이 누락된 컨테이너 인스턴스 일부 태스크 정의 파라미터의 경우, 특정 도커 원격 API 버전을 컨테이너 인스턴스에 설치해야 합니다. 로깅 드라이버 옵션 등 다른 태스크 정의 파라미터의 경우, 컨테이너 인스턴스가 `ECS_AVAILABLE_LOGGING_DRIVERS` 에이전트 구성 변수를 사용하여 이러한 로깅 드라이버를 등록해야 합니다. 태스크 정의에 특정 컨테이너 인스턴스 속성을 필요로 하는 파라미터가 포함되어 있고 이 요구 사항을 충족할 수 있는 사용 가능한 컨테이너 인스턴스가 없는 경우, 해당 작업을 배치할 수 없습니다. 서비스에서 `awsvpc` 네트워크 모드 및 EC2를 사용하는 태스크를 사용하고 있는 경우가 이 오류의 일반적인 원인입니다. 서비스를 생성할 때 `awsvpcConfiguration`에 지정된 동일한 서브넷에서 지정한 클러스터에 컨테이너 인스턴스가 등록되어 있지 않습니다. AWSSupport-TroubleshootECSContainerInstance 런북을 사용하여 문제를 해결할 수 있습니다. 런북에서는 인스턴스의 사용자 데이터에 올바른 클러스터 정보가 포함되어 있는지 여부, 인스턴스 프로파일에 필요한 권한이 포함되어 있는지 여부, 그리고 네트워크 구성 문제를 검토합니다. 자세한 내용은 *AWS Systems Manager 자동화 런북 레퍼런스 사용 설명서*의 [AWSSupport-TroubleshootECSContainerInstance](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-aws-troubleshoot-ecs-container-instance.html)를 참조하세요. 특정 태스크 정의 파라미터와 에이전트 구성 변수에 어떤 속성이 필요한지에 대한 자세한 내용은 [Fargate에 대한 Amazon ECS 태스크 정의 파라미터](task_definition_parameters.md) 및 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) 섹션을 참조하세요. ## 모든 요구 사항을 충족하는 컨테이너 인스턴스가 없기 때문에 서비스(*service-name*)가 태스크를 배치할 수 없습니다. 가장 가깝게 일치하는 컨테이너 인스턴스 *container-instance-id*에 가용 CPU 단위가 부족합니다. 작업 배치를 위해 가장 가깝게 일치하는 컨테이너 인스턴스에는 CPU 단위가 부족하여 작업 정의의 요구 사항을 충족할 수 없습니다. 태스크 정의의 작업 크기 및 컨테이너 정의 파라미터 모두의 CPU 요구 사항을 검토합니다. ## 모든 요구 사항을 충족하는 컨테이너 인스턴스가 없기 때문에 서비스(*service-name*)가 태스크를 배치할 수 없습니다. 가장 가깝게 일치하는 컨테이너 인스턴스 *container-instance-id*에 오류 "AGENT"가 발생했습니다. 작업 배치에 가장 가깝게 일치하는 컨테이너 인스턴스 상의 Amazon ECS 컨테이너 에이전트 연결이 끊겼습니다. SSH를 사용해 컨테이너 인스턴스에 연결할 수 있는 경우, 에이전트 로그를 검사할 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 로그 구성 파라미터](ecs-agent-versions.md#agent-logs) 섹션을 참조하세요. 인스턴스에서 에이전트가 실행 중인지도 확인해야 합니다. Amazon ECS 최적화 AMI를 사용하는 경우 다음 명령을 사용하여 에이전트를 중지하고 다시 시작해 볼 수 있습니다. + Amazon ECS 최적화 Amazon Linux 2 AMI 및 Amazon ECS 최적화 Amazon Linux 2023 AMI의 경우 ``` sudo systemctl restart ecs ``` + Amazon ECS 최적화 Amazon Linux AMI의 경우 ``` sudo stop ecs && sudo start ecs ``` ## service (*service-name*) (task *task-id*) (instance *instance-id*) is unhealthy in (elb *elb-name*) due to (reason Instance has failed at least the UnhealthyThreshold number of health checks consecutively.) 이 서비스가 로드 밸런서에 등록되어 있고 로드 밸런서 상태 확인이 실패합니다. 해당 메시지에는 상태 확인에 실패한 특정 태스크를 식별하는 데 도움이 되는 태스크 ID가 포함되어 있습니다. 자세한 내용은 [Amazon ECS의 서비스 로드 밸런서 문제 해결](troubleshoot-service-load-balancers.md) 섹션을 참조하세요. ## 서비스(*service-name*)는 일부 태스크를 시작할 수 없습니다. 이 서비스에는 연속 시도 후 시작에 실패한 작업이 포함되어 있습니다. 이 지점에서 서비스 스케줄러는 재시도 간격을 점차적으로 증가시키기 시작합니다. 작업 시작이 왜 실패하는지 문제를 해결해야 합니다. 자세한 내용은 [Amazon ECS 서비스 제한 로직](service-throttle-logic.md) 섹션을 참조하세요. 서비스가 업데이트되면 업데이트된 태스크 정의 등을 사용하여 서비스 스케줄러가 정상적인 동작을 다시 시작합니다. ## 서비스(*service-name*) 작업이 제한되고 있습니다. 나중에 다시 시도합니다. 이 서비스는 API 조절 제한으로 인해 더 많은 태스크를 시작할 수 없습니다. 서비스 스케줄러가 더 많은 태스크를 시작할 수 있게 되면 재개됩니다. API 속도 제한 할당량 증가를 요청하려면 [AWS Support 센터](https://console.aws.amazon.com/support/home#/) 페이지를 열고 필요한 경우 로그인한 후 **사례 생성(Create case)**을 선택합니다. **서비스 한도 증가(Service Limit increase)**를 선택합니다. 양식을 작성하고 제출합니다. ## 서비스 배포 구성으로 인해 배포 중에 서비스(*service-name*)에서 태스크를 중지하거나 시작할 수 없습니다. minimumHealthyPercent 또는 maximumPercent 값을 업데이트하고 다시 시도하세요. 배포 구성으로 인해 서비스 배포 중에 이 서비스에서 태스크를 중지하거나 시작할 수 없습니다. 배포 구성은 `minimumHealthyPercent` 및 `maximumPercent` 값으로 구성되며, 이 값은 서비스가 생성될 때 정의됩니다. 이 값은 기존 서비스에서도 업데이트할 수 있습니다. `minimumHealthyPercent`는 배포 중 또는 컨테이너 인스턴스가 드레이닝될 때 서비스에 대해 실행되어야 하는 작업 수의 하한을 나타냅니다. 이는 서비스에서 원하는 작업 수의 비율입니다. 이 값은 반올림됩니다. 예를 들어, 최소 정상 상태 백분율이 `50`이고 원하는 작업 수가 4개인 경우 스케줄러는 두 개의 새 작업을 시작하기 전에 두 개의 기존 작업을 중지할 수 있습니다. 마찬가지로 최소 정상 상태 백분율이 75%이고 원하는 작업 수가 2이면 결과 값이 2이기 때문에 스케줄러는 태스크를 중지 할 수 없습니다. `maximumPercent`는 배포 중 또는 컨테이너 인스턴스가 드레이닝될 때 서비스에 대해 실행되어야 하는 작업 수의 상한을 나타냅니다. 이는 서비스에서 원하는 작업 수의 비율입니다. 이 값은 내림됩니다. 예를 들어, 최대 백분율이 `200`이고 원하는 작업 수가 4개인 경우 스케줄러는 4개의 기존 작업을 중지하기 전에 4개의 새 작업을 시작할 수 있습니다. 마찬가지로 최대 백분율이 `125`이고 원하는 작업 수가 3이면 결과 값이 3이기 때문에 스케줄러는 태스크를 시작할 수 없습니다. 최소 정상 상태 백분율 또는 최대 백분율을 설정할 때는 배포가 트리거될 때 스케줄러가 하나 이상의 태스크를 중지하거나 시작할 수 있는지 확인해야 합니다. ## 서비스(*service-name*)에서 태스크를 배치할 수 없습니다. 이유: 동시에 실행할 수 있는 작업 수가 제한에 도달했습니다. 오류를 일으킨 리소스에 대한 할당량 증가를 요청할 수 있습니다. 자세한 내용은 [Amazon ECS 서비스 할당량](service-quotas.md) 섹션을 참조하세요. 할당량 증가를 요청하려면 *Service Quotas 사용 설명서*의 [할당량 증가 요청](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)을 참조하세요. ## 서비스(*service-name*)에서 태스크를 배치할 수 없습니다. 이유: 내부 오류. 이 오류의 잠재적 원인은 다음과 같습니다. 서브넷이 지원되지 않는 가용 영역에 있기 때문에 서비스가 태스크를 시작할 수 없습니다. 지원되는 Fargate 리전 및 가용 영역에 대한 자세한 내용은 [AWS Fargate의 Amazon ECS에 대해 지원되는 리전](AWS_Fargate-Regions.md) 섹션을 참조하세요. 서브넷 가용 영역을 보는 방법에 대한 자세한 내용은 *Amazon VPC 사용 설명서*의 [서브넷 보기](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#view-subnet)를 참조하세요. ## 서비스(*service-name*)에서 태스크를 배치할 수 없습니다. 이유: 요청된 CPU 구성이 제한을 초과합니다. 오류를 일으킨 리소스에 대한 할당량 증가를 요청할 수 있습니다. 자세한 내용은 [Amazon ECS 서비스 할당량](service-quotas.md) 섹션을 참조하세요. 할당량 증가를 요청하려면 *Service Quotas 사용 설명서*의 [할당량 증가 요청](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)을 참조하세요. ## 서비스(*service-name*)에서 태스크를 배치할 수 없습니다. 이유: 요청된 메모리 구성이 제한을 초과합니다. 오류를 일으킨 리소스에 대한 할당량 증가를 요청할 수 있습니다. 자세한 내용은 [Amazon ECS 서비스 할당량](service-quotas.md) 섹션을 참조하세요. 할당량 증가를 요청하려면 *Service Quotas 사용 설명서*의 [할당량 증가 요청](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)을 참조하세요. ## 서비스(*service-name*)에서 태스크를 배치할 수 없습니다. 이유: 동시에 실행할 수 있는 vCPU 수가 제한에 도달했습니다. AWS Fargate은 태스크 수 기반 할당량에서 vCPU 기반 할당량으로 전환하고 있습니다. Fargate vCPU 기반 할당량에 대한 할당량 증가를 요청할 수 있습니다. 자세한 내용은 [Amazon ECS 서비스 할당량](service-quotas.md) 섹션을 참조하세요. Fargate 할당량 증가를 요청하려면 *Service Quotas 사용 설명서*의 [할당량 증가 요청](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)을 참조하세요. ## 작업 세트(*taskSet-ID*)를 스케일 인할 수 없기 때문에 서비스(*service-name*)가 안정 상태에 도달할 수 없습니다. 사유: 보호된 태스크 수가 원하는 태스크 수보다 많음 이 서비스에는 원하는 태스크 수보다 많은 보호된 태스크가 있습니다. 다음 중 하나를 수행할 수 있습니다. + 현재 작업에 대한 보호가 만료될 때까지 기다리면 작업이 종료됩니다. + 중지할 수 있는 작업을 결정하고 `protectionEnabled` 옵션을 `false`로 설정한 상태에서 `UpdateTaskProtection` API를 사용하여 이러한 작업에 대한 보호를 해제합니다. + 서비스의 바람직한 작업 수를 보호되는 작업 수 이상으로 늘립니다. ## 서비스(*service-name*)가 안정 상태에 도달할 수 없습니다. 원인: 용량 공급자에서 컨테이너 인스턴스를 찾을 수 없습니다. 서비스 스케줄러는 다른 작업을 추가하는 데 사용 가능한 리소스를 찾을 수 없을 때 이 이벤트 메시지를 보냅니다. 가능한 원인은 다음과 같습니다. 클러스터에 연결된 용량 공급자가 없음 `describe-services`를 사용하여 클러스터와 연결된 용량 공급자가 있는지 확인합니다. 서비스에 대한 용량 공급자 전략을 업데이트할 수 있습니다. 용량 공급자에서 사용 가능한 용량이 있는지 확인합니다. EC2의 경우 컨테이너 인스턴스가 태스크 정의 요구 사항을 충족하는지 확인합니다. 클러스터에서 컨테이너 인스턴스를 찾을 수 없음 작업을 실행하려는 클러스터에 등록된 컨테이너 인스턴스가 없는 경우 이 오류가 발생합니다. 클러스터에 컨테이너 인스턴스를 추가해야 합니다. 자세한 내용은 [Amazon ECS Linux 컨테이너 인스턴스 시작](launch_container_instance.md) 섹션을 참조하세요. 포트가 충분하지 않음 작업에서 고정된 호스트 포트 매핑을 사용하는 경우(예를 들어 작업이 웹 서버 호스트에서 포트 80을 사용하는 경우) 작업당 하나 이상의 컨테이너 인스턴스가 있어야 합니다. 한 번에 하나의 컨테이너만 단일 호스트 포트를 사용할 수 있습니다. 클러스터에 컨테이너 인스턴스를 추가하거나 원하는 작업 수를 줄여야 합니다. 너무 많은 포트가 등록되었습니다. 작업 배치에 가장 근접하게 일치하는 컨테이너 인스턴스는 컨테이너 인스턴스당 허용되는 최대 예약 포트 제한인 100개의 호스트 포트를 초과할 수 없습니다. 동적 호스트 포트 매핑을 사용하면 문제가 해결될 수 있습니다. 포트 이미 사용 중 이 작업의 작업 정의는 선택된 컨테이너 인스턴스에서 이미 실행 중인 작업과 동일한 포트를 포트 매핑에 사용합니다. 서비스 이벤트 메시지에는 아래 메시지의 일부로 선택된 컨테이너 인스턴스 ID가 있습니다. ``` The closest matching container-instance is already using a port required by your task. ``` 메모리가 충분하지 않음 태스크 정의에서 지정된 메모리가 1000MiB이고 클러스터의 컨테이너 인스턴스 각각의 메모리가 1024MiB이라면 컨테이너 인스턴스당 이 작업의 사본 하나만 실행할 수 있습니다. 컨테이너 인스턴스당 2개 이상의 태스크를 시작하거나 보다 많은 컨테이너 인스턴스를 클러스터로 시작할 수 있도록 태스크 정의에서 이보다 적은 메모리를 실험할 수 있습니다. 특정 인스턴스 유형에 대해 작업에 가능한 한 많은 메모리를 제공하여 리소스 사용률을 최대화하려는 경우 [Amazon ECS Linux 컨테이너 인스턴스 메모리 예약](memory-management.md) 섹션을 참조하세요. 사용 가능한 ENI 연결 지점이 충분하지 않음 `awsvpc` 네트워크 모드를 사용하는 태스크는 각각 고유한 탄력적 네트워크 인터페이스(ENI)를 받습니다. 이 ENI는 이를 호스팅하는 컨테이너 인스턴스에 연결되어 있습니다. Amazon EC2 인스턴스는 연결할 수 있는 ENI 개수에 대한 제한이 있고 클러스터에 사용 가능한 ENI 용량이 있는 컨테이너 인스턴스가 없습니다. 개별 컨테이너 인스턴스에 대한 ENI 제한은 다음 조건에 따라 다릅니다. + `awsvpcTrunking` 계정 설정에 옵트인**하지 않은** 경우 각 컨테이너 인스턴스에 대한 ENI 제한은 인스턴스 유형에 따라 다릅니다. 자세한 내용은 *Amazon EC2 사용 설명서*의 [인스턴스 유형별/네트워크 인터페이스당 IP 주소](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)를 참조하세요. + `awsvpcTrunking` 계정 설정에 옵트인**했지만** 옵트인 후 지원되는 인스턴스 유형을 사용하여 새로운 컨테이너 인스턴스를 시작하지 **않은** 경우 각 컨테이너 인스턴스에 대한 ENI 제한은 여전히 기본값으로 설정됩니다. 자세한 내용은 *Amazon EC2 사용 설명서*의 [인스턴스 유형별/네트워크 인터페이스당 IP 주소](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html)를 참조하세요. + `awsvpcTrunking` 계정 설정에 옵트인**했으며** 옵트인 후 지원되는 인스턴스 유형을 사용하여 새 컨테이너 인스턴스를 **시작한** 경우 추가 ENI를 사용할 수 있습니다. 자세한 내용은 [증가한 Amazon ECS 컨테이너 네트워크 인터페이스에 대해 지원되는 인스턴스](eni-trunking-supported-instance-types.md) 섹션을 참조하세요. `awsvpcTrunking` 계정 설정 옵트인에 대한 자세한 내용은 [Amazon ECS Linux 컨테이너 인스턴스 네트워크 인터페이스 증가](container-instance-eni.md) 섹션을 참조하세요. 클러스터에 컨테이너 인스턴스를 추가하여 가용 네트워크 어댑터를 더 많이 제공할 수 있습니다. 필요한 속성이 누락된 컨테이너 인스턴스 일부 태스크 정의 파라미터의 경우, 특정 도커 원격 API 버전을 컨테이너 인스턴스에 설치해야 합니다. 로깅 드라이버 옵션 등 다른 태스크 정의 파라미터의 경우, 컨테이너 인스턴스가 `ECS_AVAILABLE_LOGGING_DRIVERS` 에이전트 구성 변수를 사용하여 이러한 로깅 드라이버를 등록해야 합니다. 태스크 정의에 특정 컨테이너 인스턴스 속성을 필요로 하는 파라미터가 포함되어 있고 이 요구 사항을 충족할 수 있는 사용 가능한 컨테이너 인스턴스가 없는 경우, 해당 작업을 배치할 수 없습니다. 이 오류의 일반적인 원인은 서비스에서 `awsvpc` 네트워크 모드 및 EC2를 사용하는 태스크를 사용하고 지정한 클러스터에 서비스를 생성할 때 `awsvpcConfiguration`에서 지정한 것과 동일한 서브넷에 컨테이너 인스턴스가 등록되어 있지 않은 경우입니다. AWSSupport-TroubleshootECSContainerInstance 런북을 사용하여 문제를 해결할 수 있습니다. 런북에서는 인스턴스의 사용자 데이터에 올바른 클러스터 정보가 포함되어 있는지 여부, 인스턴스 프로파일에 필요한 권한이 포함되어 있는지 여부, 그리고 네트워크 구성 문제를 검토합니다. 자세한 내용은 *AWS Systems Manager 자동화 런북 레퍼런스 사용 설명서*의 [AWSSupport-TroubleshootECSContainerInstance](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-aws-troubleshoot-ecs-container-instance.html)를 참조하세요. 특정 태스크 정의 파라미터와 에이전트 구성 변수에 어떤 속성이 필요한지에 대한 자세한 내용은 [Fargate에 대한 Amazon ECS 태스크 정의 파라미터](task_definition_parameters.md) 및 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) 섹션을 참조하세요. ## 서비스(*service-name*)에서 태스크를 배치할 수 없습니다. 원인: 지금은 용량을 사용할 수 없습니다. 나중에 다시 시도하거나 다른 가용 영역에서 시도하세요. 현재 서비스를 실행할 수 있는 가용 용량이 없습니다. 다음 중 하나를 수행할 수 있습니다. + Fargate 용량 또는 EC2 컨테이너 인스턴스를 사용할 수 있을 때까지 기다리세요. + 서비스를 다시 시작하고 추가 서브넷을 지정하세요. ## 서비스(*service-name*) 배포 실패: 작업을 시작하지 못했습니다. 서비스의 작업을 시작하지 못했습니다. 중지된 작업을 디버깅하는 방법에 대한 자세한 내용은 [Amazon ECS 중지된 작업 오류 메시지](stopped-task-error-codes.md) 섹션을 참조하세요. ## 서비스(*service-name*) Amazon ECS Agent가 시작되길 기다리는 중 제한 시간을 초과했습니다. /var/log/ecs/ecs-agent.log에서 로그를 확인하세요. 작업 배치에 가장 가깝게 일치하는 컨테이너 인스턴스 상의 Amazon ECS 컨테이너 에이전트 연결이 끊겼습니다. SSH를 사용해 컨테이너 인스턴스에 연결할 수 있는 경우, 에이전트 로그를 검사할 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 로그 구성 파라미터](ecs-agent-versions.md#agent-logs) 섹션을 참조하세요. 인스턴스에서 에이전트가 실행 중인지도 확인해야 합니다. Amazon ECS 최적화 AMI를 사용하는 경우 다음 명령을 사용하여 에이전트를 중지하고 다시 시작해 볼 수 있습니다. + Amazon ECS 최적화 Amazon Linux 2 AMI의 경우 ``` sudo systemctl restart ecs ``` + Amazon ECS 최적화 Amazon Linux AMI의 경우 ``` sudo stop ecs && sudo start ecs ``` ## `TARGET GROUP IS NOT FOUND`로 인해 서비스(*service-name*) 태스크 세트(*taskSet-ID*)(태스크 *task-id*)가 대상 그룹(*targetGroup-ARN)*)에서 비정상 상태입니다. 대상 그룹을 찾을 수 없으므로 서비스에 설정된 작업의 상태 확인에 실패합니다. 해당 메시지에는 상태 확인에 실패한 특정 태스크를 식별하는 데 도움이 되는 태스크 ID가 포함되어 있습니다. 서비스를 삭제하고 다시 생성해야 합니다. 해당 Amazon ECS 서비스가 이미 삭제된 경우가 아니면 Elastic Load Balancing 대상 그룹을 삭제하지 않습니다. ## `TARGET IS NOT FOUND`로 인해 서비스(*service-name*) 태스크 세트(*taskSet-ID*)(태스크 *task-id*)가 대상 그룹(*targetGroup-ARN)*)에서 비정상 상태입니다. 대상을 찾을 수 없으므로 서비스에 설정된 작업의 상태 확인에 실패합니다. 해당 메시지에는 상태 확인에 실패한 특정 태스크를 식별하는 데 도움이 되는 태스크 ID가 포함되어 있습니다. ## IAM 권한 정책이 잘못 구성되거나 변경되었으며 ECS가 더 이상 서비스를 유지 관리할 수 없음 잘못 구성되거나 변경된 IAM 권한 정책으로 인해 서비스가 태스크를 유지할 수 없습니다. ECS 서비스 또는 태스크와 연결된 IAM 역할에 필요한 권한이 없을 수 있습니다. 이 문제를 해결하려면 IAM 역할에 필요한 권한을 추가합니다. IAM 권한 정책 관리에 대한 자세한 내용은 *IAM 사용 설명서*의 [IAM 자격 증명 권한 추가 및 제거](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)를 참조하세요. ## IAM 신뢰 관계가 잘못 구성되거나 변경되었으며 ECS가 더 이상 서비스를 유지 관리할 수 없음 잘못 구성되거나 변경된 IAM 신뢰 관계로 인해 서비스가 태스크를 유지할 수 없습니다. ECS 서비스 또는 태스크와 연결된 IAM 역할에 잘못된 신뢰 정책이 있을 수 있습니다. 이 문제를 해결하려면 태스크 정의에 사용되는 역할에 대한 신뢰 정책을 구성합니다. 사용자 지정 역할에 대한 신뢰 정책 생성에 대한 자세한 내용은 *IAM 사용자 설명서*의 [사용자 지정 사용 사례에 대한 역할 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)을 참조하세요. ## service (*service-name*) could not launch *number* tasks for deployment *deployment-id*. 배포 워크플로가 일부 태스크를 성공적으로 시작하지만 용량 부족 오류로 인해 요청된 모든 태스크를 시작하지 못하면 서비스 스케줄러가 이 이벤트 메시지를 보냅니다. 이는 일반적으로 회로 차단기가 활성화되어 있고 배포가 실패하거나 롤백될 수 있는 이유에 대한 가시성을 제공할 때 발생합니다. 메시지에는 CPU, 메모리 또는 기타 리소스 제약 조건 부족과 같은 특정 실패 이유가 포함됩니다. 이를 통해 배포 문제를 해결하기 위해 해결해야 할 리소스를 이해할 수 있습니다. 자세한 내용은 [모든 요구 사항을 충족하는 컨테이너 인스턴스가 없기 때문에 서비스(*service-name*)가 태스크를 배치할 수 없습니다.](#service-event-messages-1) 섹션을 참조하세요. ## service (*service-name*) was unable to place tasks in your cluster because the tasks provisioning capacity limit was exceeded. 클러스터가 동시에 `PROVISIONING` 상태에 있을 수 있는 500개의 태스크 한도에 도달하면 서비스 스케줄러가 이 이벤트 메시지를 보냅니다. 이는 클러스터 수준 한도이며 서비스에 특정한 문제가 아닙니다. 이는 일반적으로 사전 프로비저닝된 용량이 제한된 원하는 태스크 수가 많은 서비스를 시작하거나 여러 서비스가 동시에 시작되어 태스크 이탈이 높을 때 발생합니다. 이 문제를 해결하려면: + 기존 태스크가 프로비저닝을 완료하고 `RUNNING` 상태로 전환될 때까지 기다립니다. + 프로비저닝 한도에 도달하지 않도록 서비스를 더 점진적으로 조정하는 방법을 고려합니다. + 클러스터의 용량 공급자 구성을 검토하여 적절한 리소스를 사용할 수 있는지 확인합니다. Amazon ECS 서비스 할당량에 대한 자세한 내용은 *Amazon Web Services 일반 참조*의 [Amazon Elastic Container Service 엔드포인트 및 할당량](https://docs.aws.amazon.com/general/latest/gr/ecs-service.html)을 참조하세요. # Amazon ECS 서비스 비정상 이벤트 메시지 다음은 서비스 비정상 이벤트 메시지의 예제입니다. ## EC2: (이유 *failure-reason*)로 인해 (서비스 *service-name*)(태스크 *task-id*)(인스턴스 *instance-id*)(포트 *port-number*)가 (대상 그룹 *target-group-name*)에서 비정상 상태임 이 메시지는 EC2 인스턴스에서 실행 중인 태스크가 상태 확인에 실패했음을 나타냅니다. 자세한 내용은 다음을 참조하세요. + [EC2를 사용하여 Application Load Balancer 상태 확인을 전달하는 Amazon ECS 태스크를 가져오려면 어떻게 해야 합니까?](https://repost.aws/knowledge-center/troubleshoot-unhealthy-checks-ecs) ## 태스크 세트가 있는 EC2: (이유 *failure-reason*)로 인해 (서비스 *service-name*, 태스크 세트 *taskSet-id*)(태스크 *task-id*)(인스턴스 *instance-id*)(포트 *port-number*)가 (대상 그룹 *target-group-name*)에서 비정상 상태임 이 메시지는 EC2 인스턴스에서 실행 중인 태스크 세트의 태스크가 상태 확인에 실패했음을 나타냅니다. 자세한 내용은 다음을 참조하세요. + [EC2를 사용하여 Application Load Balancer 상태 확인을 전달하는 Amazon ECS 태스크를 가져오려면 어떻게 해야 합니까?](https://repost.aws/knowledge-center/troubleshoot-unhealthy-checks-ecs) ## Fargate: (이유 *failure-reason*)로 인해 (서비스 *service-name*)(태스크 *task-id*)(포트 *port-number*)가 (대상 그룹 *target-group-name*)에서 비정상 상태임 이 메시지는 Fargate 태스크가 상태 확인에 실패했음을 나타냅니다. Fargate 태스크의 상태 확인 실패 문제 해결에 대한 자세한 내용은 [Fargate의 Amazon ECS 태스크에 대한 상태 확인 실패 문제를 해결하려면 어떻게 해야 합니까?](https://repost.aws/knowledge-center/ecs-fargate-health-check-failures)를 참조하세요. ## 태스크 세트가 있는 Fargate: (이유 *failure-reason*)로 인해 (서비스 *service-name*, 태스크 세트 *taskSet-id*)(태스크 *task-id*)(포트 *port-number*)가 (대상 그룹 *target-group-name*)에서 비정상 상태임 이 메시지는 Fargate에서 실행되는 태스크 세트의 태스크가 상태 확인에 실패했음을 나타냅니다. Fargate 태스크의 상태 확인 실패 문제 해결에 대한 자세한 내용은 [Fargate의 Amazon ECS 태스크에 대한 상태 확인 실패 문제를 해결하려면 어떻게 해야 합니까?](https://repost.aws/knowledge-center/ecs-fargate-health-check-failures)를 참조하세요. # Amazon ECS 가용 영역 서비스 리밸런싱 서비스 이벤트 메시지 다음은 참조할 수 있는 서비스 이벤트 메시지 예제입니다. ## 서비스(*service-name*)는 *가용 영역 1*의 *number-tasks* 태스크, *가용 영역 2*의 *number-tasks* 및 *가용 영역 3*의 *number-tasks*로 밸런싱된 AZ가 아닙니다. AZ 리밸런싱이 진행 중입니다. 서비스 스케줄러에서는 태스크 수가 가용 영역에 균등하게 분산되지 않을 때 `service (service-name) is not AZ balanced` 서비스 이벤트를 보냅니다. 취할 조치는 없습니다. 이는 정보 이벤트입니다. ## 서비스(*service-name*)는 *가용 영역 1*의 *number-tasks* 태스크, *가용 영역 2*의 *number-tasks* 태스크 및 *가용 영역 3*의 *number-tasks* 태스크로 밸런싱된 AZ입니다. 서비스 스케줄러에서는 가용 영역 서비스 리밸런싱이 완료되면 `service (service-name) is AZ balanced` 서비스 이벤트를 보냅니다. 취할 조치는 없습니다. 이는 정보 이벤트입니다. ## *service-name*이 AZ 리밸런싱에 대한 *가용 영역*의 *number-tasks* 태스크를 시작했습니다(*task-ids*). 서비스 스케줄러에서는 서비스 리밸런싱 때문에 가용 영역에서 태스크가 시작될 때 *가용 영역* 서비스 이벤트에서 *number*개의 태스크를 시작한 *service-name*/*task-set-name*을 보냅니다. 취할 조치는 없습니다. 이는 정보 이벤트입니다. ## *service-name*이 AZ 리밸런싱으로 인해 *가용 영역*에서 실행 중인 태스크 *number-tasks*를 중지했습니다(*task-id*). 서비스 스케줄러에서는 서비스 리밸런싱 때문에 가용 영역에서 태스크가 중지될 때 *가용 영역* 서비스 이벤트에서 *number*개의 태스크를 중지한 *service-name*/*task-set-name*을 보냅니다. 취할 조치는 없습니다. 이는 정보 이벤트입니다. ## 모든 요구 사항을 충족하는 컨테이너 인스턴스가 없기 때문에 서비스(*service-name*)가 태스크를 *가용 영역*에 배치할 수 없습니다. 서비스 스케줄러에서는 모든 요구 사항을 충족하는 컨테이너 인스턴스가 없기 때문에 *service-name*에서 태스크를 *가용 영역* 배치할 수 없다는 서비스 이벤트를 보냅니다. 문제를 해결하려면 가용 영역에서 인스턴스를 시작합니다. ## 서비스(*service-name*)가 태스크를 *가용 영역*에 배치할 수 없습니다. Fargate를 사용하고 사용 가능한 용량이 없으면 서비스 스케줄러에서는 *service-name*에서 *가용 영역*에 태스크를 배치할 수 없다는 서비스 이벤트를 보냅니다. 오류 메시지의 가용 영역에 추가 서브넷을 추가하거나 지원에 문의하여 추가 용량을 얻을 수 있습니다. ## *reason* 사유로 인해 *task-set-name* 태스크가 스케일 인될 수 없어서 서비스(*service-name*)가 AZ 리밸런싱할 수 없었습니다. 서비스 스케줄러에서는 Task scale-in protection 사용 시 서비스 스케줄러에서는 *reason*(으)로 인해 *task-set-name*이(가) 스케일 인될 수 없어서 *service-name*이(가) AZ 리밸런싱할 수 없다는 서비스 이벤트를 보냅니다. 다음 중 하나를 수행할 수 있습니다. + 현재 작업에 대한 보호가 만료될 때까지 기다리면 작업이 종료됩니다. + 중지할 수 있는 작업을 결정하고 `protectionEnabled` 옵션을 `false`로 설정한 상태에서 `UpdateTaskProtection` API를 사용하여 이러한 작업에 대한 보호를 해제합니다. + 서비스의 바람직한 작업 수를 보호되는 작업 수 이상으로 늘립니다. ## 서비스(*service-name*)가 AZ 리밸런싱을 중지했습니다. 가용 영역 리밸런싱 작업이 중지되면 서비스 스케줄러에서는 *service-name* 서비스가 AZ 리밸런싱을 중지했다는 서비스 이벤트를 보냅니다. 이는 정보 이벤트입니다. Amazon ECS에서는 자세한 내용이 제공되는 추가 이벤트를 보냅니다. # Amazon ECS의 서비스 로드 밸런서 문제 해결 Amazon ECS 서비스는 Elastic Load Balancing 로드 밸런서에 태스크를 등록할 수 있습니다. 로드 밸런서 구성 오류는 중지된 작업의 일반적 원인입니다. 중지된 작업이 로드 밸런서를 사용하는 서비스에 의해 시작된 경우, 가능한 다음 원인을 고려하세요. **Amazon ECS 서비스 연결 역할이 없음** Amazon ECS 서비스 연결 역할을 사용하면 Amazon ECS 서비스가 Elastic Load Balancing 로드 밸런서에 컨테이너 인스턴스를 등록할 수 있습니다. 계정에서 서비스 연결 역할이 생성되어야 합니다. 자세한 내용은 [Amazon ECS에 대해 서비스 연결 역할 사용](using-service-linked-roles.md) 섹션을 참조하세요. **컨테이너 인스턴스 보안 그룹** 컨테이너가 컨테이너 인스턴스에서 포트 80에 매핑된 경우, 로드 밸런서 상태 확인에 통과하려면 컨테이너 인스턴스 보안 그룹이 포트 80에서 인바운드 트래픽을 허용해야 합니다. **모든 가용 영역에 대해 Elastic Load Balancing 로드 밸런서가 구성되지 않음** 리전 내의 모든 가용 영역 또는 적어도 컨테이너 인스턴스가 상주하는 모든 가용 영역을 사용하도록 로드 밸런서를 구성해야 합니다. 서비스가 로드 밸런서를 사용하고 로드 밸런서가 사용하도록 구성되지 않은 가용 영역에 상주하는 컨테이너 인스턴스에서 작업을 시작하는 경우, 해당 태스크는 절대로 상태 확인을 통과하지 못합니다. 그 결과 작업이 종료됩니다. **Elastic Load Balancing 로드 밸런서 상태 확인이 잘못 구성됨** 로드 밸런서 상태 확인 파라미터가 지나치게 제한적이거나 존재하지 않는 리소스를 가리키고 있을 수 있습니다. 컨테이너 인스턴스 상태가 비정상이라고 판단되면 로드 밸런서에서 제거됩니다. 서비스 로드 밸런서에 대해 다음 파라미터가 올바로 구성되어 있는지 확인해야 합니다. Ping Port 로드 밸런서 상태 확인의 **Ping Port** 값은 컨테이너 인스턴스 상의 포트로서 정상 여부는 로드 밸런서가 확인합니다. 이 포트가 잘못 구성되면 로드 밸런서가 이 포트에서 컨테이너 인스턴스 등록을 취소할 수도 있습니다. 이 포트는 상태 확인에 사용하는 서비스의 태스크 정의에서 컨테이너에 `hostPort` 값을 사용하도록 구성되어야 합니다. Ping Path 로드 밸런서 상태 확인의 일부입니다. 애플리케이션이 정상일 때 성공 상태 코드(예: 200)를 반환할 수 있는 애플리케이션의 엔드포인트입니다. 이 값은 흔히 `index.html`로 설정되지만 서비스가 해당 요청에 응답하지 않는 경우에는 상태 확인에 실패합니다. 컨테이너에 `index.html` 파일이 없는 경우, 이를 `/`로 설정하여 컨테이너 인스턴스의 기본 URL을 대상으로 지정할 수 있습니다. Response Timeout 상태 확인 ping에 대해 응답을 반환해야 하는 시간입니다. 이 값이 응답에 필요한 시간보다 낮으면 상태 확인이 실패합니다. Health Check Interval 상태 확인 ping 사이의 시간입니다. 상태 확인 간격이 짧을수록 컨테이너 인스턴스가 **비정상 임계값(Unhealthy Threshold)**에 빠르게 도달할 수 있습니다. Unhealthy Threshold 컨테이너 인스턴스 상태가 비정상이라고 간주될 때까지 허용되는 상태 확인 실패 횟수입니다. 비정상 임계값이 2이고 상태 확인 간격이 30초인 경우, 작업이 60초 동안 상태 확인 ping에 응답하지 않으면 비정상으로 간주됩니다. 비정상 임계값 또는 상태 확인 간격을 늘리면 작업의 응답 시간을 늘릴 수 있습니다. *servicename* **서비스를 업데이트할 수 없음****: 작업 정의에서 로드 밸런서 컨테이너 이름 또는 포트가 변경됨** 서비스에서 로드 밸런서를 사용하는 경우 AWS CLI 또는 SDK를 사용하여 로드 밸런서 구성을 수정할 수 있습니다. 구성을 변경하는 방법에 대한 자세한 정보는 *Amazon Elastic Container Service API Reference*(Amazon Elastic Container Service API 레퍼런스)의 [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html)를 참조하세요. 서비스에 대한 작업 정의를 업데이트하는 경우, 로드 밸런서 구성에서 지정한 컨테이너 이름 및 컨테이너 포트는 작업 정의에서 그대로 유지해야 합니다. **동시에 실행할 수 있는 작업 수의 제한에 도달했습니다.** 새 계정의 경우 할당량이 서비스 할당량보다 낮을 수 있습니다. 계정의 서비스 할당량은 Service Quotas 콘솔에서 볼 수 있습니다. 할당량 증가를 요청하려면 *Service Quotas 사용 설명서*의 [할당량 증가 요청](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)을 참조하세요. # Amazon ECS에서 서비스 Auto Scaling 문제 해결 Application Auto Scaling은 Amazon ECS 배포가 진행 중인 동안 스케일 인 프로세스를 끄고 배포가 완료되면 다시 시작합니다. 그러나 배포 중에 일시 중단되지 않는 한 확장 프로세스는 계속 발생합니다. 자세한 내용은 [Application Auto Scaling의 조정 일시 중지 및 재개](https://docs.aws.amazon.com/autoscaling/application/userguide/application-auto-scaling-suspend-resume-scaling.html)를 참조하세요. # 콘솔에서 Amazon ECS 이벤트 캡처 Amazon ECS 콘솔은 서비스 작업 및 태스크 상태 변경과 같은 Amazon ECS 생성 이벤트를 EventBridge를 통해 Amazon CloudWatch Logs에 저장하는 이벤트 캡처 기능을 제공합니다. 이 기능에는 모니터링 및 문제 해결을 위한 필터링 기능이 있는 쿼리 인터페이스가 포함되어 있습니다. 이벤트는 서비스 배포, 서비스, 태스크 및 인스턴스의 작동 방식에 대한 자세한 정보를 제공합니다. 이 정보를 사용하여 태스크 또는 서비스 배포 장애 문제를 해결할 수 있습니다. 이벤트 캡처를 켜면 Amazon ECS가 선택한 보존 기간에 생성하는 모든 이벤트에 액세스할 수 있으며, 필터링되지 않은 마지막 이벤트 100개 또는 단 1시간 동안 표시되는 중지된 태스크의 기본 제한 이상으로 확장됩니다. ## 작동 방식 이벤트 캡처는 EventBridge를 사용하여 사전 정의된 Amazon CloudWatch Logs 로그 그룹에 이벤트를 저장합니다. Amazon ECS 콘솔은 사전 빌드된 쿼리 및 필터링 옵션을 제공하고 이벤트를 상호 연관시켜 직관적인 형식으로 태스크 수명 주기를 제공합니다. 다음 유형의 이벤트를 쿼리하고 검색할 수 있습니다. + **서비스 작업 이벤트** - 프로비저닝 또는 리소스 할당 문제를 식별하는 데 도움이 됩니다. + **태스크 수명 주기 이벤트** - 태스크 또는 컨테이너가 시작되지 않거나 실행이 중지되는 이유를 식별하는 데 도움이 됩니다. Amazon ECS 콘솔을 사용하면 클릭 한 번으로 이벤트 캡처를 설정할 수 있으며 쿼리 언어를 배우거나 여러 콘솔 간에 이동할 필요 없이 일반적으로 사용되는 쿼리 및 필터링을 제공합니다. ## 이벤트 유형 이벤트 캡처는 모든 Amazon ECS 생성 이벤트를 다음 범주로 저장합니다. 태스크 상태 변경 이벤트 문제 해결 또는 태스크 수명 주기 타임라인 모니터링에 사용할 수 있는 컨테이너 중지 및 기타 종료 이벤트. 서비스 작업 안정 상태 도달, 태스크 배치 실패 또는 리소스 제약과 같은 이벤트. 서비스 배포 상태 변경 사항 서비스 배포의 상태를 모니터링하기 위해 회로 차단기 및 롤백 설정에 의해 트리거되는 진행 중, 완료 또는 실패한 배포와 같은 이벤트. 컨테이너 인스턴스 상태 변경 사항 EC2 및 Amazon ECS 관리형 인스턴스의 워크로드인 경우 이벤트에 연결 및 연결 해제 상태가 표시됩니다. ## 로그 그룹 구성 이벤트 캡처를 켜면 Amazon ECS는 다음 리소스를 자동으로 생성합니다. + Amazon CloudWatch Logs 로그 그룹(`/aws/events/ecs/containerinsights/${clusterName}/performance`) + `aws.ecs` 소스에서 모든 이벤트를 수집하여 로그 그룹으로 전달하는 EventBridge 규칙 로그 그룹의 보존 기간을 1일에서 10년까지 지정할 수 있습니다. 기본 보존 기간은 7일입니다. ## 고려 사항 용량 공급자를 사용할 경우 다음을 고려합니다. + 이벤트 캡처는 단순성을 위해 모든 이벤트를 저장합니다. Amazon ECS 콘솔에서는 특정 이벤트만 캡처하도록 규칙을 구성할 수 없습니다. + Amazon ECS 콘솔은 사전 정의된 쿼리 기준을 제공합니다. 고급 쿼리의 경우 Amazon CloudWatch Logs의 Logs Insights를 사용하여 로그 그룹을 직접 쿼리합니다. + Amazon ECS 콘솔에서는 라이브 테일 기능을 사용할 수 없습니다. 라이브 테일을 사용하려면 Amazon CloudWatch Logs를 직접 사용합니다. + 이벤트 캡처를 비활성화하면 EventBridge 규칙이 삭제됩니다. + 이벤트 캡처에는 EventBridge 데이터 수집, Amazon CloudWatch Logs 스토리지 및 쿼리 실행에 대한 추가 비용이 발생합니다. EventBridge 요금에 대한 자세한 내용은 [EventBridge 요금](https://aws.amazon.com/eventbridge/pricing/)을 참조하세요. CloudWatch 요금에 대한 자세한 내용은 [CloudWatch 요금](https://aws.amazon.com/cloudwatch/pricing/)을 참조하세요. ## 이벤트 기반 문제 해결 Amazon ECS 생성 이벤트를 사용하여 일반적인 문제 해결 질문에 답변합니다. ### 태스크 장애 분석 `STOPPED` 태스크 상태 변경 이벤트, 중지 코드 및 컨테이너 종료 코드를 검토하여 태스크가 시작되지 않거나 실행 중에 실패한 이유를 확인할 수 있습니다. 배치 장애에 대한 서비스 작업 이벤트 및 리소스 제약 정보를 검토하여 리소스 제약 조건으로 인해 태스크가 배치되지 않은 이유를 확인할 수 있습니다. ### 일반적인 태스크 장애 시나리오 가장 일반적인 비정상 태스크 장애는 다음 문제와 관련이 있습니다. + CI/CD 서비스 배포 장애 + 오토 스케일링 장애 + 태스크 리밸런싱 장애 + 메모리 부족(OOM) 오류와 같은 비정상적인 컨테이너 종료 비정상 태스크 장애는 `EssentialContainerExited` 또는 `TaskFailedToStart` 중지 코드와 함께 `STOPPED` 태스크 상태 변경 이벤트를 생성합니다. 이러한 중지 코드를 기준으로 필터링하여 컨테이너 실행 및 중지 동작을 검사할 수 있습니다. # 기존 Amazon ECS 클러스터에 대한 이벤트 캡처 켜기 기존 Amazon ECS 클러스터에서 이벤트 캡처를 활성화하여 EventBridge를 통해 Amazon ECS 생성 이벤트를 Amazon CloudWatch Logs에 저장할 수 있습니다. 이 기능은 태스크 장애, 서비스 배포 및 기타 클러스터 활동을 모니터링하고 문제를 해결하는 데 도움이 됩니다. 이벤트 캡처를 활성화하면 Amazon ECS는 다음 리소스를 생성합니다. + Amazon CloudWatch Logs 로그 그룹(`/aws/events/ecs/containerinsights/${clusterName}/performance`) + `aws.ecs` 소스에서 모든 이벤트를 캡처하는 EventBridge 규칙 클러스터 보기에 **기록** 탭이 표시되고 이를 통해 태스크 수명 주기 이벤트 및 서비스 작업을 쿼리할 수 있습니다. 이벤트 캡처는 즉시 시작되며 지정된 보존 기간에 따라 모든 Amazon ECS 생성 이벤트를 저장합니다. ## 사전 조건 + 기존 Amazon ECS 클러스터. + 클러스터 설정을 수정하고 Amazon CloudWatch Logs 리소스를 생성하기 위한 적절한 IAM 권한 ## 콘솔을 사용하여 이벤트 캡처 켜기 1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다. 1. 탐색 창에서 **클러스터**를 선택합니다. 1. 이벤트 캡처를 활성화할 클러스터를 선택하세요. 클러스터 세부 정보 페이지가 표시됩니다. 1. **구성**을 선택합니다. 1. **ECS 이벤트** 섹션에서 **이벤트 캡처 켜기**를 선택하세요. **이벤트 캡처 켜기** 대화 상자가 표시됩니다. 1. **만료 이벤트**에서 Amazon CloudWatch Logs 로그 그룹의 보존 기간을 선택하세요. 기본값은 7일입니다. 1. **켜기**를 선택합니다. # Amazon ECS 서비스 및 태스크 상태 변경 이벤트 보기 Amazon ECS 콘솔은 서비스 작업 및 태스크 상태 변경과 같은 Amazon ECS 생성 이벤트를 EventBridge를 통해 Amazon CloudWatch Logs에 저장하는 이벤트 캡처 기능을 제공합니다. 이 기능에는 모니터링 및 문제 해결을 개선하기 위한 필터링 기능이 있는 쿼리 인터페이스가 포함되어 있습니다. 이벤트는 서비스 배포, 서비스, 태스크 및 인스턴스의 작동 방식에 대한 자세한 정보를 제공합니다. 이 정보를 사용하여 태스크 또는 서비스 배포 장애 문제를 해결할 수 있습니다. 다음 기준 중 하나를 사용하여 이벤트를 필터링할 수 있습니다. + 배포 ID(서비스 세부 정보 페이지에서만 사용 가능) + 시작 시간 + 종료 시간 + 서비스 이름(클러스터 세부 정보 페이지에서만 해당됨, 서비스 세부 정보 페이지에서 현재 서비스가 기본값으로 설정됨) + 태스크 ID + 태스크 마지막 상태 + 태스크 정의 패밀리 + 태스크 정의 개정 ## 클러스터 수준에서 이벤트 보기 1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다. 1. **클러스터**를 선택하세요. 클러스터 목록 페이지가 표시됩니다. 1. 클러스터를 선택합니다. 클러스터 세부 정보 페이지가 표시됩니다. 1. **기록**에서 보려는 이벤트를 결정하세요. 1. 서비스 작업 이벤트를 보려면 **서비스 작업 이벤트**를 선택하세요. 1. 작업 상태 변경 이벤트를 보려면 **작업 상태 변경 이벤트**를 선택하세요. 1. (선택 사항) **쿼리 기준**에 보려는 이벤트의 필터를 입력하세요. 1. **쿼리 실행**을 선택합니다. 이벤트가 목록에 표시됩니다. 1. 이벤트의 전체 세부 정보를 보려면 이벤트를 선택합니다. ## 서비스 수준에서 보기 1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다. 1. **클러스터(Clusters)** 페이지에서 클러스터를 선택합니다. 1. 클러스터 세부 정보 페이지의 **서비스** 섹션에서 서비스를 선택합니다. 서비스 세부 정보 페이지가 표시됩니다. 1. **기록**에서 보려는 이벤트를 결정하세요. 1. 서비스 작업 이벤트를 보려면 **서비스 작업 이벤트**를 선택하세요. 1. 작업 상태 변경 이벤트를 보려면 **작업 상태 변경 이벤트**를 선택하세요. 1. (선택 사항) **쿼리 기준**에 보려는 이벤트의 필터를 입력하세요. 1. **쿼리 실행**을 선택합니다. 이벤트가 목록에 표시됩니다. 1. 이벤트의 전체 세부 정보를 보려면 이벤트를 선택합니다. # Amazon ECS 작업 정의 잘못된 CPU 또는 메모리 오류 문제 해결 Amazon ECS API 또는 AWS CLI를 사용하여 태스크 정의를 등록할 때 잘못된 `cpu` 또는 `memory` 값을 지정하면 다음 오류가 반환됩니다. ``` An error occurred (ClientException) when calling the RegisterTaskDefinition operation: Invalid 'cpu' setting for task. ``` **참고** Terraform을 사용할 때 다음 오류가 반환될 수 있습니다. ``` Error: ClientException: No Fargate configuration exists for given values. ``` 이 문제를 해결하려면 태스크 정의에서 작업 CPU 및 메모리에 지원되는 값을 지정해야 합니다. `cpu` 값은 작업 정의에서 CPU 단위 또는 vCPU로 표현될 수 있습니다. 작업 정의를 등록할 때 CPU 단위를 나타내는 정수로 변환됩니다. `memory` 값은 작업 정의에서 MiB 또는 GB로 표현될 수 있습니다. 태스크 정의를 등록할 때 MiB를 나타내는 정수로 변환됩니다. `requiresCompatibilities` 파라미터에 `FARGATE`를 지정하는 작업 정의의 경우(`EC2`도 함께 지정되는 경우라도) 다음 테이블에 나오는 값 중 하나를 사용해야 합니다. 이 값에 따라 CPU 및 메모리 파라미터에 대해 지원되는 값의 범위가 결정됩니다. 다음 표에서는 Fargate에서 호스팅되는 태스크에 대해 유효한 CPU와 메모리 조합을 보여줍니다. JSON 파일의 메모리 값은 MiB 단위로 지정됩니다. 값에 1024를 곱하여 GB 값을 MiB로 변환할 수 있습니다. 예를 들어 1GB는 1024MiB입니다. | CPU 값 | 메모리 값 | AWS Fargate에 지원되는 운영 체제 | | --- | --- | --- | | 256(.25 vCPU) | 512MiB, 1GB, 2GB | Linux | | 512(.5 vCPU) | 1GB, 2GB, 3GB, 4GB | Linux | | 1024(1 vCPU) | 2GB, 3GB, 4GB, 5GB, 6GB, 7GB, 8GB | Linux, Windows | | 2048(2 vCPU) | 4\$116GB(1GB 증분) | Linux, Windows | | 4096(4 vCPU) | 8\$130GB(1GB 증분) | Linux, Windows | | 8192 (8 vCPU) 이 옵션은 Linux 플랫폼 `1.4.0` 이상이 필요합니다. | 16\$160GB(4GB 증분) | Linux | | 16384 (16vCPU) 이 옵션은 Linux 플랫폼 `1.4.0` 이상이 필요합니다. | 32\$1120GB(8GB 증분) | Linux | Amazon EC2에서 호스팅되는 작업의 경우 지원되는 작업 CPU 값은 0.25 vCPU에서 192 vCPU 사이입니다. CPU 제어 메커니즘은 EC2 및 Fargate 사이에서 다릅니다. + Amazon EC2에서 호스팅되는 태스크의 경우: Amazon ECS에서는 CPU 기간과 CPU 할당량을 사용하여 태스크 크기 CPU 하드 제한을 제어합니다. 태스크 정의에서 vCPU를 지정하면 Amazon ECS에서는 값을 `cgroup`에 적용되는 CPU 기간 및 CPU 할당량 설정으로 변환합니다. + Fargate에서 호스팅되는 태스크의 경우: Amazon ECS는 CPU 공유를 사용하여 CPU 할당을 제어합니다. CPU 할당량 및 기간 값은 Fargate 태스크의 CPU 제한에 사용되지 않습니다. Amazon EC2 태스크의 경우 CPU 할당량은 주어진 CPU 기간 중 `cgroup`에 부여된 CPU 시간을 제어합니다. 두 가지 설정은 모두 마이크로초 단위로 표시됩니다. CPU 할당량이 CPU 기간과 같으면 `cgroup`에서는 하나의 vCPU에서 최대 100%(또는 여러 vCPU의 경우 합계가 100%인 다른 모든 비율)까지 실행할 수 있다는 것을 의미합니다. CPU 할당량은 최대 1,000,000us이고 CPU 기간은 최소 1ms입니다. 이러한 값을 사용하여 CPU 수 한도를 설정할 수 있습니다. CPU 할당량을 변경하지 않고 CPU 기간을 변경하면 태스크 정의에 지정한 것과 다른 유효 한도가 있습니다. 100ms 기간에서는 0.125\$110 범위의 vCPU가 허용됩니다. **참고** Windows 컨테이너에 대해서는 태스크 레벨 CPU와 메모리 파라미터가 무시됩니다. # Amazon ECS 컨테이너 에이전트 로그 보기 Amazon ECS는 컨테이너 인스턴스의 `/var/log/ecs` 폴더에 로그를 저장합니다. 컨테이너 인스턴스에는 Amazon ECS 컨테이너 에이전트에서 사용할 수 있는 로그와 에이전트 상태(시작/중지)를 제어하는 `ecs-init` 서비스에서 사용할 수 있는 로그가 있습니다. 이러한 로그 파일은 SSH를 사용하여 컨테이너 인스턴스에 연결하면 볼 수 있습니다. **참고** 컨테이너 인스턴스에서 모든 로그를 수집하는 방법을 잘 모르는 경우 Amazon ECS 로그 수집기를 사용하면 됩니다. 자세한 내용은 [Amazon ECS 로그 수집기를 사용하여 컨테이너 로그 수집](ecs-logs-collector.md) 섹션을 참조하세요. ## Linux 운영 체제 `ecs-init` 프로세스는 `/var/log/ecs/ecs-init.log`에 로그를 저장합니다. `ecs-init.log` 파일에는 컨테이너 에이전트 수명 주기 관리, 구성, 부트스트래핑에 대한 정보가 포함되어 있습니다. 다음 명령을 사용하여 로그 파일을 볼 수 있습니다. ``` cat /var/log/ecs/ecs-init.log ``` 출력: ``` 2018-02-16T18:13:54Z [INFO] pre-start 2018-02-16T18:13:56Z [INFO] start 2018-02-16T18:13:56Z [INFO] No existing agent container to remove. 2018-02-16T18:13:56Z [INFO] Starting Amazon Elastic Container Service Agent ``` ## Windows 운영 체제 Windows용 Amazon ECS 로그 수집기를 사용할 수 있습니다. 자세한 내용은 Github의 [Amazon ECS Logs Collector For Windows](https://github.com/awslabs/aws-ecs-logs-collector-for-windows?tab=readme-ov-file#aws-ecs-logs-collector-for-windows)를 참조하세요. 1. 인스턴스에 연결합니다. 1. PowerShell을 열고 관리자 권한으로 다음 명령을 실행합니다. 명령은 스크립트를 다운로드하고 로그를 수집합니다. ``` Invoke-WebRequest -OutFile ecs-logs-collector.ps1 https://raw.githubusercontent.com/awslabs/aws-ecs-logs-collector-for-windows/master/ecs-logs-collector.ps1 .\ecs-logs-collector.ps1 ``` Amazon ECS 에이전트 및 Docker 대몬에 대한 디버그 로깅을 켤 수 있습니다. 이 옵션을 사용하면 디버그 모드를 켜기 전에 스크립트에서 로그를 수집할 수 있습니다. 스크립트는 Docker 대몬 및 Amazon ECS 에이전트를 다시 시작한 다음, 인스턴스에서 실행 중인 모든 컨테이너를 종료합니다. 다음 명령을 실행하기 전에 컨테이너 인스턴스를 드레이닝하고 중요한 작업을 다른 컨테이너 인스턴스로 이동합니다. 다음 명령을 실행하여 로깅을 켭니다. ``` .\ecs-logs-collector.ps1 -RunMode debug ``` # Amazon ECS 로그 수집기를 사용하여 컨테이너 로그 수집 **참고** Amazon ECS 관리형 인스턴스에서는 Amazon ECS 로그 수집기를 사용할 수 없습니다. 컨테이너 인스턴스에서 다양한 로그를 모두 수집하는 방법을 잘 모르겠다면 Amazon ECS 로그 수집기를 사용하면 됩니다. 이것은 [Linux](https://github.com/awslabs/ecs-logs-collector) 및 [Windows](https://github.com/awslabs/aws-ecs-logs-collector-for-windows)용 GitHub에서 모두 사용할 수 있습니다. 스크립트는 일반적인 운영 체제 로그와 AWS Support 사례 문제 해결에 도움이 될 수 있는 Docker 및 Amazon ECS 컨테이너 에이전트 로그를 수집합니다. 그런 다음 수집된 정보를 진단 목적을 위해 쉽게 공유할 수 있는 단일 파일로 압축해 보관합니다. 또한 Amazon ECS 최적화 AMI와 같은 Amazon Linux 변형에서 Docker 대몬과 Amazon ECS 컨테이너 에이전트의 디버그 모드 활성화도 지원합니다. **참고** Amazon Linux Amazon ECS 최적화 AMI 버전 20250909 이상에서는 Amazon ECS 로그 수집기가 `/opt/amazon/ecs/ecs-logs-collector.sh`에 사전 설치되어 있으며, GitHub에서 별도로 다운로드하지 않아도 바로 사용할 수 있습니다. 자세한 내용은 ECS 최적화 AMI 설명서의 [ECS 로그 수집기](https://github.com/aws/amazon-ecs-ami?tab=readme-ov-file#ecs-logs-collector)를 참조하세요. 현재 Amazon ECS 로그 수집기가 지원하는 운영 체제는 다음과 같습니다. + Amazon Linux + Red Hat Enterprise Linux + Ubuntu + Windows Server **Linux용 Amazon ECS 로그 수집기(ECS 최적화 AMI)를 실행하려면** 1. 컨테이너 인스턴스에 연결합니다. 1. 스크립트를 실행해 로그를 수집하고 아카이브를 생성합니다. **참고** Docker 대몬과 Amazon ECS 컨테이너 에이전트에 대해 디버그 모드를 활성화하려면 `--mode=enable-debug` 옵션을 다음 명령에 추가합니다. 인스턴스에서 실행 중인 모든 컨테이너를 종료하는 Docker 대몬이 다시 시작될 수 있습니다. 디버그 모드를 활성화하기 전에 컨테이너 인스턴스 드레이닝과 다른 컨테이너 인스턴스로의 중요한 작업 이동을 고려합니다. 자세한 내용은 [Amazon ECS 컨테이너 인스턴스 드레이닝](container-instance-draining.md) 섹션을 참조하세요. ``` [ec2-user ~]$ sudo /opt/amazon/ecs/ecs-logs-collector.sh ``` 스크립트를 실행한 후 스크립트가 생성한 `collect` 폴더에서 수집된 로그를 검사할 수 있습니다. `collect.tgz` 파일은 모든 로그가 압축된 아카이브로서 진단 지원을 위해 AWS Support와 공유할 수 있습니다. **Linux용 Amazon ECS 로그 수집기를 다운로드하고 실행하려면** 1. 컨테이너 인스턴스에 연결합니다. 1. Amazon ECS 로그 수집기 스크립트를 다운로드합니다. ``` curl -O https://raw.githubusercontent.com/awslabs/ecs-logs-collector/master/ecs-logs-collector.sh ``` 1. 스크립트를 실행해 로그를 수집하고 아카이브를 생성합니다. ``` $ sudo bash ./ecs-logs-collector.sh ``` **Windows용 Amazon ECS 로그 수집기를 다운로드하고 실행하려면** 1. 컨테이너 인스턴스에 연결합니다. 자세한 내용은 *Amazon EC2 사용 설명서*의 [RDP를 사용하여 Windows 인스턴스에 연결](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connecting_to_windows_instance.html)을 참조하세요. 1. PowerShell을 사용하여 Amazon ECS 로그 수집기 스크립트를 다운로드합니다. ``` Invoke-WebRequest -OutFile ecs-logs-collector.ps1 https://raw.githubusercontent.com/awslabs/aws-ecs-logs-collector-for-windows/master/ecs-logs-collector.ps1 ``` 1. 스크립트를 실행해 로그를 수집하고 아카이브를 생성합니다. **참고** Docker 대몬과 Amazon ECS 컨테이너 에이전트에 대해 디버그 모드를 활성화하려면 `-RunMode debug` 옵션을 다음 명령에 추가합니다. 인스턴스에서 실행 중인 모든 컨테이너를 종료하는 Docker 대몬이 다시 시작됩니다. 디버그 모드를 활성화하기 전에 컨테이너 인스턴스 드레이닝과 다른 컨테이너 인스턴스로의 중요한 작업 이동을 고려합니다. 자세한 내용은 [Amazon ECS 컨테이너 인스턴스 드레이닝](container-instance-draining.md) 섹션을 참조하세요. ``` .\ecs-logs-collector.ps1 ``` 스크립트를 실행한 후 스크립트가 생성한 `collect` 폴더에서 수집된 로그를 검사할 수 있습니다. `collect.tgz` 파일은 모든 로그가 압축된 아카이브로서 진단 지원을 위해 AWS Support와 공유할 수 있습니다. # 에이전트 내부 검사를 통해 Amazon ECS 진단 세부 정보 검색 Amazon ECS 에이전트 내부 검사 API는 Amazon ECS 에이전트 및 컨테이너 인스턴스의 전체 상태에 대한 정보를 제공합니다. 에이전트 내부 검사 API를 사용해 작업에서 컨테이너의 Docker ID를 가져올 수 있습니다. SSH를 사용하여 컨테이너 인스턴스에 연결하면 에이전트 내부 검사 API를 사용할 수 있습니다. **중요** 내부 검사 API에 접근하려면 Amazon ECS에 대한 액세스가 가능한 IAM 역할이 컨테이너 인스턴스에 필요합니다. 자세한 내용은 [Amazon ECS 컨테이너 인스턴스 IAM 역할](instance_IAM_role.md) 섹션을 참조하세요. 다음 예제는 2개의 작업(현재 실행 중인 작업 및 중지된 작업)을 보여줍니다. **참고** 다음 명령은 가독성 향상을 위해 **python -mjson.tool**을 통해 파이프됩니다. ``` curl http://localhost:51678/v1/tasks | python -mjson.tool ``` 출력: ``` % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 1095 100 1095 0 0 117k 0 --:--:-- --:--:-- --:--:-- 133k { "Tasks": [ { "Arn": "arn:aws:ecs:us-west-2:aws_account_id:task/090eff9b-1ce3-4db6-848a-a8d14064fd24", "Containers": [ { "DockerId": "189a8ff4b5f04affe40e5160a5ffadca395136eb5faf4950c57963c06f82c76d", "DockerName": "ecs-console-sample-app-static-6-simple-app-86caf9bcabe3e9c61600", "Name": "simple-app" }, { "DockerId": "f7f1f8a7a245c5da83aa92729bd28c6bcb004d1f6a35409e4207e1d34030e966", "DockerName": "ecs-console-sample-app-static-6-busybox-ce83ce978a87a890ab01", "Name": "busybox" } ], "Family": "console-sample-app-static", "KnownStatus": "STOPPED", "Version": "6" }, { "Arn": "arn:aws:ecs:us-west-2:aws_account_id:task/1810e302-eaea-4da9-a638-097bea534740", "Containers": [ { "DockerId": "dc7240fe892ab233dbbcee5044d95e1456c120dba9a6b56ec513da45c38e3aeb", "DockerName": "ecs-console-sample-app-static-6-simple-app-f0e5859699a7aecfb101", "Name": "simple-app" }, { "DockerId": "096d685fb85a1ff3e021c8254672ab8497e3c13986b9cf005cbae9460b7b901e", "DockerName": "ecs-console-sample-app-static-6-busybox-92e4b8d0ecd0cce69a01", "Name": "busybox" } ], "DesiredStatus": "RUNNING", "Family": "console-sample-app-static", "KnownStatus": "RUNNING", "Version": "6" } ] } ``` 위의 예제에서 중지된 작업(*090eff9b-1ce3-4db6-848a-a8d14064fd24*)에는 2개의 컨테이너가 있습니다. **docker inspect *container-ID***를 사용하여 각 컨테이너의 세부 정보를 볼 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 내부 검사](ecs-agent-introspection.md) 섹션을 참조하세요. # Amazon ECS의 Docker 진단 Docker는 컨테이너 및 작업 문제 해결에 도움이 되는 몇 가지 진단 도구를 제공합니다. 사용 가능한 모든 Docker 명령줄 유틸리티에 대한 자세한 내용은 Docker 설명서의 [Docker CLI 참조](https://docs.docker.com/reference/cli/docker/)를 참조하세요. SSH를 사용하여 컨테이너 인스턴스에 연결하면 Docker 명령줄 유틸리티에 액세스할 수 있습니다. Docker 컨테이너가 보고하는 종료 코드도 일부 진단 정보를 제공할 수 있습니다(예를 들어 종료 코드 137은 컨테이너가 `SIGKILL` 신호를 수신했음을 뜻합니다). 자세한 내용은 도커 설명서의 [종료 상태](https://docs.docker.com/reference/cli/docker/container/run/#exit-status)를 참조하세요. ## Amazon ECS에 Docker 컨테이너 나열 컨테이너 인스턴스에서 **docker ps** 명령을 사용하여 실행 중인 컨테이너를 나열할 수 있습니다. 다음 예제에서는 Amazon ECS 컨테이너 에이전트만 실행 중입니다. 자세한 내용은 도커 설명서의 [docker ps](https://docs.docker.com/reference/cli/docker/#ps)를 참조하세요. ``` docker ps ``` 출력: ``` CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES cee0d6986de0 amazon/amazon-ecs-agent:latest "/agent" 22 hours ago Up 22 hours 127.0.0.1:51678->51678/tcp ecs-agent ``` **docker ps -a** 명령을 사용하면 모든 컨테이너를(심지어 중지됐거나 사망한 컨테이너도) 볼 수 있습니다. 이것은 예기치 않게 중지되는 컨테이너를 나열하는 데 유용합니다. 다음 예제에서 컨테이너 `f7f1f8a7a245`는 9초 전에 종료됐기 때문에 `-a` 플래그 없이 **docker ps** 출력에 나타나지 않습니다. ``` docker ps -a ``` 출력: ``` CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES db4d48e411b1 amazon/ecs-emptyvolume-base:autogenerated "not-applicable" 19 seconds ago ecs-console-sample-app-static-6-internalecs-emptyvolume-source-c09288a6b0cba8a53700 f7f1f8a7a245 busybox:buildroot-2014.02 "\"sh -c '/bin/sh -c 22 hours ago Exited (137) 9 seconds ago ecs-console-sample-app-static-6-busybox-ce83ce978a87a890ab01 189a8ff4b5f0 httpd:2 "httpd-foreground" 22 hours ago Exited (137) 40 seconds ago ecs-console-sample-app-static-6-simple-app-86caf9bcabe3e9c61600 0c7dca9321e3 amazon/ecs-emptyvolume-base:autogenerated "not-applicable" 22 hours ago ecs-console-sample-app-static-6-internalecs-emptyvolume-source-90fefaa68498a8a80700 cee0d6986de0 amazon/amazon-ecs-agent:latest "/agent" 22 hours ago Up 22 hours 127.0.0.1:51678->51678/tcp ecs-agent ``` ## Amazon ECS에서 Docker 로그 보기 **docker logs** 명령을 사용하여 컨테이너의 `STDOUT` 및 `STDERR` 스트림을 볼 수 있습니다. 이 예제에서 로그는 *dc7240fe892a* 컨테이너에 대해 표시되고 간결성을 위해 **head** 명령을 통해 파이프됩니다. 자세한 내용은 Docker 설명서의 [docker logs](https://docs.docker.com/reference/cli/docker/#logs)를 참조하세요. **참고** 기본 `json` 로그 드라이버를 사용 중인 경우에는 Docker 로그를 컨테이너 인스턴스에서만 사용할 수 있습니다. `awslogs` 로그 드라이버를 사용하도록 태스크를 구성한 경우에는 컨테이너 로그를 CloudWatch Logs에서 사용할 수 있습니다. 자세한 내용은 [Amazon ECS 로그를 CloudWatch로 전송](using_awslogs.md) 섹션을 참조하세요. ``` docker logs dc7240fe892a | head ``` 출력: ``` AH00558: httpd: Could not reliably determine the server's fully qualified domain name, using 172.17.0.11. Set the 'ServerName' directive globally to suppress this message AH00558: httpd: Could not reliably determine the server's fully qualified domain name, using 172.17.0.11. Set the 'ServerName' directive globally to suppress this message [Thu Apr 23 19:48:36.956682 2015] [mpm_event:notice] [pid 1:tid 140327115417472] AH00489: Apache/2.4.12 (Unix) configured -- resuming normal operations [Thu Apr 23 19:48:36.956827 2015] [core:notice] [pid 1:tid 140327115417472] AH00094: Command line: 'httpd -D FOREGROUND' 10.0.1.86 - - [23/Apr/2015:19:48:59 +0000] "GET / HTTP/1.1" 200 348 10.0.0.154 - - [23/Apr/2015:19:48:59 +0000] "GET / HTTP/1.1" 200 348 10.0.1.86 - - [23/Apr/2015:19:49:28 +0000] "GET / HTTP/1.1" 200 348 10.0.0.154 - - [23/Apr/2015:19:49:29 +0000] "GET / HTTP/1.1" 200 348 10.0.1.86 - - [23/Apr/2015:19:49:50 +0000] "-" 408 - 10.0.0.154 - - [23/Apr/2015:19:49:50 +0000] "-" 408 - 10.0.1.86 - - [23/Apr/2015:19:49:58 +0000] "GET / HTTP/1.1" 200 348 10.0.0.154 - - [23/Apr/2015:19:49:59 +0000] "GET / HTTP/1.1" 200 348 10.0.1.86 - - [23/Apr/2015:19:50:28 +0000] "GET / HTTP/1.1" 200 348 10.0.0.154 - - [23/Apr/2015:19:50:29 +0000] "GET / HTTP/1.1" 200 348 time="2015-04-23T20:11:20Z" level="fatal" msg="write /dev/stdout: broken pipe" ``` ## Amazon ECS에서 Docker 컨테이너 검사 컨테이너의 Docker ID가 있다면 **docker inspect** 명령을 사용하여 검사할 수 있습니다. 컨테이너 검사는 컨테이너가 시작된 환경에 대한 가장 상세한 보기를 제공합니다. 자세한 내용은 도커 설명서의 [docker inspect](https://docs.docker.com/reference/cli/docker/#inspect)를 참조하세요. ``` docker inspect dc7240fe892a ``` 출력: ``` [{ "AppArmorProfile": "", "Args": [], "Config": { "AttachStderr": false, "AttachStdin": false, "AttachStdout": false, "Cmd": [ "httpd-foreground" ], "CpuShares": 10, "Cpuset": "", "Domainname": "", "Entrypoint": null, "Env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/apache2/bin", "HTTPD_PREFIX=/usr/local/apache2", "HTTPD_VERSION=2.4.12", "HTTPD_BZ2_URL=https://www.apache.org/dist/httpd/httpd-2.4.12.tar.bz2" ], "ExposedPorts": { "80/tcp": {} }, "Hostname": "dc7240fe892a", ... ``` # Amazon ECS에서 Docker 대몬의 자세한 출력 구성 Docker 컨테이너나 이미지에 문제가 있는 경우, Docker 대몬에서 디버그 모드를 켤 수 있습니다. 디버깅을 사용하면 대몬에서 더 자세한 출력이 제공됩니다. 이를 사용하여 Amazon ECR과 같은 컨테이너 레지스트리에서 전송된 오류 메시지를 검색할 수 있습니다. **중요** 이 절차는 Amazon ECS 최적화 Amazon Linux AMI용으로 작성되었습니다. 다른 운영 체제의 경우 Docker 설명서의 [Enable debugging](https://docs.docker.com/engine/admin/#enable-debugging) 및 [Control and configure Docker with systemd]()를 참조하세요. **Amazon ECS 최적화 Amazon Linux AMI에서 Docker 대몬 디버그 모드를 사용하려면** 1. 컨테이너 인스턴스에 연결합니다. 1. 텍스트 편집기로 Docker 옵션 파일을 엽니다(예: **vi**). Amazon ECS 최적화 Amazon Linux AMI의 경우 Docker 옵션 파일은 `/etc/sysconfig/docker`에 있습니다. 1. Docker 옵션 문장을 찾아 문자열 따옴표 안에 `-D` 옵션을 추가합니다. **참고** Docker 옵션 구문이 `#`로 시작하는 경우, 해당 문자를 제거해 문장의 주석 처리를 해제하고 옵션을 활성화해야 합니다. Amazon ECS 최적화 Amazon Linux AMI의 경우 Docker 옵션 문장을 일컬어 `OPTIONS`라고 합니다. 예: ``` # Additional startup options for the Docker daemon, for example: # OPTIONS="--ip-forward=true --iptables=true" # By default we limit the number of open files per container OPTIONS="-D --default-ulimit nofile=1024:4096" ``` 1. 파일을 저장하고 텍스트 편집기를 종료합니다. 1. Docker 대몬을 다시 시작합니다. ``` sudo service docker restart ``` 출력값은 다음과 같습니다. ``` Stopping docker: [ OK ] Starting docker: . [ OK ] ``` 1. Amazon ECS 에이전트를 다시 시작합니다. ``` sudo service ecs restart ``` 이제 Docker 로그에 더 상세한 출력이 표시됩니다. ``` time="2015-12-30T21:48:21.907640838Z" level=debug msg="Unexpected response from server: \"{\\\"errors\\\":[{\\\"code\\\":\\\"DENIED\\\",\\\"message\\\":\\\"User: arn:aws:sts::1111:assumed-role/ecrReadOnly/i-abcdefg is not authorized to perform: ecr:InitiateLayerUpload on resource: arn:aws:ecr:us-east-1:1111:repository/nginx_test\\\"}]}\\n\" http.Header{\"Connection\":[]string{\"keep-alive\"}, \"Content-Type\":[]string{\"application/json; charset=utf-8\"}, \"Date\":[]string{\"Wed, 30 Dec 2015 21:48:21 GMT\"}, \"Docker-Distribution-Api-Version\":[]string{\"registry/2.0\"}, \"Content-Length\":[]string{\"235\"}}" ``` # Amazon ECS의 Docker `API error (500): devmapper` 문제 해결 다음 Docker 오류는 컨테이너 인스턴스의 씬(thin) 풀 스토리지가 꽉 찼으며 Docker 대몬이 새 컨테이너를 만들 수 없음을 나타냅니다. ``` CannotCreateContainerError: API error (500): devmapper: Thin Pool has 4350 free data blocks which is less than minimum required 4454 free data blocks. Create more free space in thin pool or use dm.min_free_space option to change behavior ``` 기본적으로 버전 `2015.09.d` 이상의 Amazon ECS 최적화 Amazon Linux AMI는 `/dev/xvda`에서 연결되고 파일 시스템의 루트로 마운트되는 운영 체제를 위한 8GiB 볼륨으로 시작됩니다. 여기에 Docker가 이미지 및 메타데이터 저장에 사용하는 `/dev/xvdcz`에서 연결된 22GiB의 볼륨이 추가됩니다. 이 스토리지 스페이스가 가득 찬 경우 Docker 대몬은 새 컨테이너를 생성할 수 없습니다. 컨테이너 인스턴스에 스토리지를 추가하는 가장 쉬운 방법은 기존 인스턴스를 종료하고 데이터 스토리지 볼륨이 더 큰 새 인스턴스를 시작하는 것입니다. 하지만 이것이 불가능한 경우, [Amazon ECS 최적화 Linux AMI](ecs-optimized_AMI.md)의 절차에 따라 Docker가 사용하는 볼륨 그룹에 스토리지를 추가하여 논리 볼륨을 확장할 수 있습니다. 컨테이너 인스턴스 스토리지가 너무 빨리 채워지는 경우, 몇 가지 조치로 이를 완화할 수 있습니다. + 씬 폴링 정보를 보려면 컨테이너 인스턴스에서 다음 명령을 실행합니다. ``` docker info ``` + (Amazon ECS 컨테이너 에이전트 1.8.0 이상) 중지되거나 종료된 컨테이너가 컨테이너 인스턴스에 남아 있는 시간을 줄일 수 있습니다. `ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION` 에이전트 구성 변수는 작업이 중지된 때부터 Docker 컨테이너가 제거될 때까지 기다리는 시간을 설정합니다(기본값: 3시간). 이때 Docker 컨테이너 데이터가 제거되므로 이 값을 너무 낮게 설정할 경우 데이터가 제거되기 전에 중지된 컨테이너를 검사하거나 로그를 볼 수 없을 수 있습니다. 자세한 내용은 [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) 섹션을 참조하세요. + 컨테이너 인스턴스에서 실행되고 있지 않은 컨테이너와 사용되지 않는 이미지를 제거할 수 있습니다. 다음 예제 명령을 사용하여 중지된 컨테이너와 사용하지 않은 이미지를 수동으로 제거할 수 있습니다. 삭제된 컨테이너는 나중에 검사할 수 없으며, 삭제된 이미지는 이미지에서 새 컨테이너를 시작하기 전에 다시 가져와야 합니다. 실행되고 있지 않은 컨테이너를 제거하려면 컨테이너 인스턴스에서 다음 명령을 실행합니다. ``` docker rm $(docker ps -aq) ``` 사용하지 않은 이미지를 제거하려면 컨테이너 인스턴스에서 다음 명령을 실행합니다. ``` docker rmi $(docker images -q) ``` + 컨테이너 내에서 사용하지 않은 데이터 블록을 제거할 수 있습니다. 다음 명령을 사용하여 실행 중인 컨테이너에서 **fstrim**을 실행하고 컨테이너 파일 시스템에서 사용하지 않은 데이터 블록을 삭제할 수 있습니다. ``` sudo sh -c "docker ps -q | xargs docker inspect --format='{{ .State.Pid }}' | xargs -IZ fstrim /proc/Z/root/" ``` # Amazon ECS Exec 문제 해결 다음은 ECS Exec을 사용할 때 오류가 발생할 수 있는 이유를 진단하는 데 도움이 되는 문제 해결 정보입니다. ## Exec Checker를 사용하여 확인 ECS Exec 검사기 스크립트는 Amazon ECS 클러스터와 작업이 ECS Exec 기능을 사용하기 위한 필수 조건을 충족했는지 확인하고 검증하는 방법을 제공합니다. ECS Exec 검사기 스크립트는 사용자를 대신하여 다양한 API를 호출하여 AWS CLI 환경과 클러스터 및 작업이 ECS Exec에 대해 모두 준비되었는지 확인합니다. 이 도구에는 AWS CLI의 최신 버전이 필요하며 `jq`를 사용할 수 있습니다. 자세한 내용은 GitHub의 [ECS Exec Checker](https://github.com/aws-containers/amazon-ecs-exec-checker)를 참조하세요. ## `execute-command` 호출 중 오류 발생 `The execute command failed` 오류가 발생하는 경우 가능한 원인은 다음과 같습니다. + 작업에 필요한 권한이 없습니다. 태스크를 시작하는 데 사용되는 태스크 정의에 작업 IAM 역할이 정의되어 있고 역할에 필요한 권한이 있는지 확인합니다. 자세한 내용은 [ECS Exec 권한](task-iam-roles.md#ecs-exec-required-iam-permissions) 섹션을 참조하세요. + SSM 에이전트가 설치되지 않았거나 실행 중이 아닙니다. + Amazon ECS용 인터페이스 Amazon VPC 엔드포인트가 있지만 Systems Manager Session Manager용 인터페이스 Amazon VPC 엔드포인트는 없습니다. # Amazon ECS Anywhere 문제 해결 Amazon ECS Anywhere는 *외부 인스턴스*(예: 온프레미스 서버 또는 가상 머신(VM))을 Amazon ECS 클러스터에 등록하도록 지원합니다. 발생할 수 있는 일반적인 문제와 이에 대한 일반적인 문제 해결 권장 사항은 다음과 같습니다. **Topics** + [외부 인스턴스 등록 문제](#ecs-anywhere-troubleshooting-registration) + [외부 인스턴스 네트워크 문제](#ecs-anywhere-troubleshooting-networking) + [외부 인스턴스에서의 작업 실행 문제](#ecs-anywhere-troubleshooting-runtask) ## 외부 인스턴스 등록 문제 Amazon ECS 클러스터에 외부 인스턴스를 등록할 때 다음 요구 사항을 충족해야 합니다. + AWS Systems Manager 활성화(활성화 ID** 및 활성화 코드**로 구성됨)를 검색해야 합니다. 외부 인스턴스를 Systems Manager 관리형 인스턴스로 등록하는 데 사용합니다. Systems Manager 활성화를 요청하면 등록 제한 및 만료 날짜를 지정합니다. 등록 제한은 정품 인증을 사용하여 등록할 수 있는 인스턴스의 최대 수를 지정합니다. 등록 제한의 기본값은 `1`개의 인스턴스입니다. 만료 날짜는 정품 인증이 만료되는 시기를 지정합니다. 기본값은 24시간입니다. 외부 인스턴스를 등록하는 데 사용하는 Systems Manager 정품 인증이 유효하지 않은 경우 새 인스턴스를 요청합니다. 자세한 내용은 [Amazon ECS 클러스터에 외부 인스턴스 등록](ecs-anywhere-registration.md) 섹션을 참조하세요. + IAM 정책은 AWS API 작업과 통신하는 데 필요한 권한을 외부 인스턴스에 제공하는 데 사용됩니다. 이 관리형 정책이 제대로 생성되지 않고 필요한 권한이 포함되어 있지 않으면 외부 인스턴스 등록이 실패합니다. 자세한 내용은 [Amazon ECS Anywhere IAM 역할](iam-role-ecsanywhere.md) 섹션을 참조하세요. + Amazon ECS는 Docker, Amazon ECS 컨테이너 에이전트 및 Systems Manager Agent를 외부 인스턴스에 설치하는 설치 스크립트를 제공합니다. 설치 스크립트가 실패하면 오류가 발생하지 않고 동일한 인스턴스에서 스크립트를 다시 실행할 수 없습니다. 이 경우 정리 프로세스에 따라 인스턴스에서 AWS 리소스를 지우고 설치 스크립트를 다시 실행할 수 있습니다. 자세한 내용은 [Amazon ECS 외부 인스턴스 등록 취소](ecs-anywhere-deregistration.md) 섹션을 참조하세요. **참고** 설치 스크립트가 Systems Manager 정품 인증을 성공적으로 요청하여 사용한 경우 설치 스크립트를 다시 실행하면 Systems Manager 정품 인증이 다시 사용됩니다. 이로 인해 해당 정품 인증에 대한 등록 제한에 도달하게 될 수 있습니다. 이 제한에 도달하면 새 정품 인증을 생성해야 합니다. + GPU 워크로드용 외부 인스턴스에서 설치 스크립트를 실행할 때 NVIDIA 드라이버가 제대로 감지되지 않거나 구성되지 않으면 오류가 발생합니다. 설치 스크립트는 `nvidia-smi` 명령을 사용하여 NVIDIA 드라이버의 존재를 확인합니다. ## 외부 인스턴스 네트워크 문제 변경 사항을 전달하려면 외부 인스턴스에 AWS에 대한 네트워크 연결이 필요합니다. 외부 인스턴스에 AWS에 대한 네트워크 연결이 끊긴 경우 수동으로 중지하지 않는 한 인스턴스에서 실행 중인 작업이 계속 실행됩니다. AWS에 대한 연결이 복원되면 외부 인스턴스의 Amazon ECS 컨테이너 에이전트 및 Systems Manager Agent에서 사용하는 AWS 자격 증명이 자동으로 갱신됩니다. 외부 인스턴스와 AWS 간의 통신에 사용되는 AWS 도메인에 관한 자세한 내용은 [네트워킹](ecs-anywhere.md#ecs-anywhere-networking) 섹션을 참조하세요. ## 외부 인스턴스에서의 작업 실행 문제 외부 인스턴스에서 작업 또는 컨테이너가 실행되지 않는 경우 가장 일반적인 원인은 네트워크 또는 권한과 관련이 있습니다. 컨테이너가 Amazon ECR에서 이미지를 가져오거나 컨테이너 로그를 CloudWatch Logs로 보내도록 구성된 경우 태스크 정의에서 유효한 작업 실행 IAM 역할을 지정해야 합니다. 유효한 작업 실행 IAM 역할이 없으면 컨테이너가 시작되지 않습니다. 네트워크 관련 문제에 대한 자세한 내용은 [외부 인스턴스 네트워크 문제](#ecs-anywhere-troubleshooting-networking) 섹션을 참조하세요. **중요** Amazon ECS는 Amazon ECS 로그 수집 도구를 제공합니다. 문제 해결을 위해 외부 인스턴스에서 로그를 수집하는 데 사용할 수 있습니다. 자세한 내용은 [Amazon ECS 로그 수집기를 사용하여 컨테이너 로그 수집](ecs-logs-collector.md) 섹션을 참조하세요. # Fargate에서 Java 클래스 로드 문제 해결 Fargate에서 실행되는 Java 애플리케이션은 플랫폼 업데이트 후, 특히 애플리케이션이 비결정적 클래스 로드 동작에 의존하는 경우 클래스 로드 문제가 발생할 수 있습니다. 이는 이전 배포에서 존재하지 않았던 종속성 주입 오류, Spring Boot 실패 또는 기타 런타임 예외로 나타날 수 있습니다. ## 증상 다음과 같은 증상이 나타날 수 있습니다. + Spring Boot 종속성 주입 오류 + ClassNotFoundException 또는 NoClassDefFoundError 예외 + 이전에 Fargate에서 작업한 애플리케이션이 간헐적으로 실패함 + 동일한 컨테이너 이미지가 Amazon EC2에서 작동하지만 Fargate에서는 실패함 + 동일한 컨테이너 이미지가 있는 배포에서 동작이 일관되지 않음 ## 원인 이러한 문제는 보통 다음과 같은 이유로 발생합니다. + **비결정적 클래스 로드:** 기본 플랫폼이 파일에 액세스하거나 캐시하는 방법을 변경하는 경우 JAR 파일에서 클래스가 로드되는 순서에 따라 달라지는 Java 애플리케이션이 실패할 수 있습니다. + **플랫폼 업데이트:** Fargate 플랫폼 버전 업데이트가 기본 파일 시스템 동작을 변경하여 클래스를 검색하고 로드하는 순서에 영향을 미칠 수 있습니다. + **JAR 파일 순서 종속성:** 명시적 종속성 관리 없이 특정 JAR 로드 시퀀스에 암시적으로 의존하는 애플리케이션입니다. ## 해결 방법 Fargate에서 Java 클래스 로드 문제를 해결하려면 다음과 같이 결정적 클래스 로드 관행을 구현합니다. ### 즉시 수정 즉각적인 해결 방법이 필요한 경우: 1. **JAR 로드 순서 적용:** 애플리케이션의 클래스 경로 구성에서 JAR 파일을 로드해야 하는 순서를 명시적으로 지정합니다. 1. **명시적 종속성 관리 사용:** 전이적 종속성에 의존하지 않고 빌드 구성(Maven, Gradle 등)에서 모든 종속성이 명시적으로 선언되었는지 확인합니다. ### 장기 모범 사례 향후 클래스 로드 문제를 방지하려면 다음 사례를 구현합니다. 1. **클래스 로딩을 결정적으로 만들기:** + 빌드 파일에서 명시적 종속성 선언 사용 + 클래스 경로 스캔 순서에 의존하지 않기 + 종속성 관리 도구를 사용하여 버전 충돌 해결 + `-verbose:class`와 같은 Java 가상 머신(JVM) 옵션을 사용하여 JVM에서 로드한 클래스에 대한 정보를 가져옵니다. 1. **Spring Boot 애플리케이션:** + 명시적 기본 패키지와 함께 `@ComponentScan` 사용 + Bean을 명시적으로 구성하여 자동 구성 충돌 방지 + `@DependsOn` 주석을 사용하여 Bean 초기화 순서 제어 1. **빌드 구성:** + Maven 또는 Gradle에서 종속성 관리 섹션 사용 + 충돌을 일으키는 전이적 종속성 제외 + Maven Enforcer 플러그인과 같은 도구를 사용하여 종속성 문제 감지 1. **테스트:** + 다양한 JVM 구현으로 애플리케이션 테스트 + 다양한 배포 환경을 시뮬레이션하는 통합 테스트 실행 + 도구를 사용하여 개발 중에 클래스 경로 충돌 분석 ## 예방책 향후 배포에서 Java 클래스 로드 문제를 방지하려면 다음을 수행합니다. + **결정적 클래스 로드 관행 준수:** 클래스 경로에서 클래스가 로드되는 순서에 종속되지 않도록 애플리케이션을 설계합니다. + **명시적 종속성 관리 사용:** 빌드 구성에서 필요한 모든 종속성과 해당 버전을 항상 명시적으로 선언합니다. + **교차 환경 테스트:** 다양한 환경 및 플랫폼 버전에서 애플리케이션을 정기적으로 테스트하여 잠재적 문제를 조기에 식별합니다. + **플랫폼 업데이트 모니터링:** Fargate 플랫폼 업데이트에 대한 최신 정보를 확인하고 프로덕션 워크로드에 영향을 미치기 전에 새 플랫폼 버전으로 애플리케이션을 테스트합니다. # AWS Fargate 제한 할당량 AWS Fargate은(는) 리전별로 각 AWS 계정에 대한 [토큰 버킷 알고리즘](https://en.wikipedia.org/wiki/Token_bucket)을 사용하여 Amazon ECS 작업 및 Amazon EKS 포드 시작률을 할당량(이전에는 한도로 지칭)으로 제한합니다. 이 알고리즘을 사용하면 계정에 특정 수의 토큰을 보관하는 버킷이 있습니다. 버킷의 토큰 수는 지정된 초당 비율 할당량을 나타냅니다. 각 고객 계정에는 작업 및 포드 토큰 버킷이 있고, 이는 고객 계정에서 실행된 작업 및 포드의 수에 따라 고갈됩니다. 이 토큰 버킷에는 주기적으로 더 많은 수의 요청을 할 수 있는 최대 버킷과 필요한 기간 동안 꾸준한 요청률을 유지할 수 있는 리필률이 있습니다. 예를 들어, Fargate 고객 계정의 작업 및 포드 토큰 버킷 크기는 100토큰이고 리필률은 초당 20토큰입니다. 따라서 고객 계정당 최대 100개의 Amazon ECS 작업 및 Amazon EKS 포드를 즉시 시작할 수 있으며, 초당 20개의 Amazon ECS 작업 및 Amazon EKS 포드의 지속적인 시작률을 제공합니다. | 작업 | 버킷 최대 용량(또는 버스트율) | 버킷 리필률(또는 지속률) | | --- | --- | --- | | On Demand Amazon ECS 작업 및 Amazon EKS 포드에 대한 Fargate 리소스 비율 할당량[1](#fargate-throttling-note-1) | 100 | 20 | | Spot Amazon ECS 작업에 대한 Fargate 리소스 비율 할당량 | 100 | 20 | 1Amazon EKS 포드만 시작하는 계정은 [Amazon EKS 플랫폼 버전](https://docs.aws.amazon.com/eks/latest/userguide/platform-versions.html)에서 불러온 플랫폼 버전을 사용할 때 초당 20의 포드 시작의 지속적인 포드 시작률로 20의 버스트율을 가집니다. ## Fargate에서 `RunTask` API 제한 또한 Fargate는 별도의 할당량을 사용하는 Amazon ECS `RunTask` API를 사용하여 작업을 시작할 때 요청률을 제한합니다. Fargate는 리전별로 각 AWS 계정에 대한 Amazon ECS `RunTask` API 요청을 제한합니다. 제출한 각 요청은 버킷에서 하나의 토큰을 제거합니다. 당사는 서비스 수행을 돕고 모든 Fargate 고객에게 공정한 사용을 보장하기 위해 이를 수행합니다. API 호출은 Amazon Elastic Container Service 콘솔, 명령줄 도구 또는 서드 파티 애플리케이션에서 발생했는지와 관계없이 요청 할당량이 적용됩니다. Amazon ECS `RunTask` API에 대한 호출에 대한 비율 할당량은 초당 20개의 호출(버스트 및 지속)입니다. 그러나 이 API를 호출할 때마다 최대 10개의 작업을 시작할 수 있습니다. 즉, 이 API를 10번 호출하여 각 호출마다 10개의 작업을 시작하도록 요청하여 1초에 100개의 작업을 시작할 수 있습니다. 마찬가지로 이 API를 20번 호출하여 각 호출마다 5개의 작업을 시작하도록 요청할 수도 있습니다. Amazon ECS `RunTask` API의 API 제한에 대한 자세한 내용은 Amazon ECS API 참조의 [API request throttling](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/request-throttling.html)을 참조하세요. 실제로 작업 및 포드 시작률은 다운로드 및 압축 해제할 컨테이너 이미지, 상태 확인 및 로드 밸런서에 작업 또는 포드 등록과 같은 활성화된 기타 통합과 같은 다른 고려 사항에 따라 달라집니다. 고객에 대해 활성화한 기능에 따라 위에 표시된 할당량과 비교하여 작업 및 포드 시작률이 달라질 수 있습니다. ## Fargate에서 요금 할당량 조정 AWS 계정에 대한 Fargate 비율 제한 할당량 증가를 요청할 수 있습니다. 자세한 설명은 *Service Quotas 사용 설명서*에서 [할당량 증가 요청](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html)을 참조하세요. # Amazon ECS 관리형 인스턴스 드레이닝 문제 해결 다음 절차에 따라 일반적인 문제, 진단 기법 및 해결 단계를 포함하여 Amazon ECS 관리형 인스턴스 문제를 해결합니다. ## 사전 조건 Amazon ECS 관리형 인스턴스 문제를 해결하기 전에 다음 요구 사항을 이행하고 있는지 확인합니다. + 적절한 권한으로 AWS CLI가 설치 및 구성됨 자세한 내용은 *AWS Command Line Interface 사용 설명서*의 [AWS Command Line Interface 최신 버전의 설치 또는 업데이트](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)를 참조하세요. + Amazon ECS 관리형 인스턴스 용량 공급자를 사용하여 클러스터에 액세스합니다. 자세한 내용은 [Amazon ECS 관리형 인스턴스용 클러스터 생성](create-cluster-managed-instances.md) 섹션을 참조하세요. ## 일반적인 문제 해결 시나리오 ### Amazon ECS 관리형 인스턴스 컨테이너 에이전트 로그 보기 인스턴스에서 실행되는 권한 있는 컨테이너에 연결하여 Amazon ECS 관리형 인스턴스에서 이러한 Amazon ECS 로그 파일을 볼 수 있습니다. #### 진단 단계 **권한과 Linux 기능을 Amazon ECS 태스크로 사용하여 디버그 컨테이너를 배포합니다.** 다음 환경 변수를 설정합니다. 모든 *사용자 입력*을 사용자의 값으로 바꿉니다. ``` export ECS_CLUSTER_NAME="your-cluster-name" export AWS_REGION="your-region" export ACCOUNT_ID="your-account-id" ``` `node-debugger.json`이라는 CLI JSON 파일을 사용하여 태스크 정의를 생성합니다. ``` cat << EOF > node-debugger.json { "family": "node-debugger", "taskRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/ecsTaskExecutionRole", "executionRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/ecsTaskExecutionRole", "cpu": "256", "memory": "1024", "networkMode": "host", "pidMode": "host", "requiresCompatibilities": ["MANAGED_INSTANCES", "EC2"], "containerDefinitions": [ { "name": "node-debugger", "image": "public.ecr.aws/amazonlinux/amazonlinux:2023", "essential": true, "privileged": true, "command": ["sleep", "infinity"], "healthCheck": { "command": ["CMD-SHELL", "echo debugger || exit 1"], "interval": 30, "retries": 3, "timeout": 5 }, "linuxParameters": { "initProcessEnabled": true }, "mountPoints": [ { "sourceVolume": "host-root", "containerPath": "/host", "readOnly": false } ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/aws/ecs/node-debugger", "awslogs-create-group": "true", "awslogs-region": "${AWS_REGION}", "awslogs-stream-prefix": "ecs" } } } ], "volumes": [ { "name": "host-root", "host": { "sourcePath": "/" } } ] } EOF ``` 등록한 다음 작업을 실행합니다. 다음 명령을 실행합니다. ``` aws ecs register-task-definition --cli-input-json file://node-debugger.json TASK_ARN=$(aws ecs run-task \ --cluster $ECS_CLUSTER_NAME \ --task-definition node-debugger \ --enable-execute-command \ --capacity-provider-strategy capacityProvider=managed-instances-default,weight=1 \ --query 'tasks[0].taskArn' --output text) # Wait for task to be running aws ecs wait tasks-running --cluster $ECS_CLUSTER_NAME --tasks $TASK_ARN ``` 컨테이너에 연결합니다. 다음 명령을 실행합니다. ``` aws ecs execute-command \ --cluster $ECS_CLUSTER_NAME \ --task $TASK_ARN \ --container node-debugger \ --interactive \ --command "/bin/sh" ``` **Amazon ECS 에이전트 로그를 확인합니다.** 컨테이너의 대화형 세션에서 다음 명령을 실행합니다. ``` # Install required tools yum install -y util-linux-core # View ECS agent logs nsenter -t 1 -m -p cat /var/log/ecs/ecs-agent.log | tail -50 # Check agent registration nsenter -t 1 -m -p grep "Registered container instance" /var/log/ecs/ecs-agent.log Example Output: {"level":"info","time":"2025-10-16T12:39:37.665","msg":"Registered container instance with cluster!"} # Verify capabilities nsenter -t 1 -m -p grep "Response contained expected value for attribute" /var/log/ecs/ecs-agent.log ``` **에이전트 지표 확인:** 다음 명령을 실행하여 로그를 확인합니다. ``` # View metrics logs nsenter -t 1 -m -p cat /var/log/ecs/metrics.log | tail -20 ``` ### 태스크 배치 문제 다음은 태스크 배치 문제의 증상입니다. + 태스크가 보류 중 상태에서 멈춤 + Amazon ECS 관리형 인스턴스에서 태스크가 시작되지 않음 + 리소스 부족 오류 #### 진단 단계 다음 명령을 실행하여 태스크 배치 문제를 진단하고 클러스터 용량, 컨테이너 인스턴스 및 시스템 서비스에 대한 정보를 수집합니다. ``` # Check cluster capacity aws ecs describe-clusters --clusters cluster-name --include STATISTICS # Check cluster capacity providers aws ecs describe-clusters --clusters cluster-name --include STATISTICS --query 'clusters[].capacityProviders' # List container instances aws ecs list-container-instances --cluster cluster-name # Check container instance details aws ecs describe-container-instances --cluster cluster-name --container-instances container-instance-arn # Check container instance remaining resources CPU/Mem aws ecs describe-container-instances --cluster $ECS_CLUSTER_NAME --container-instances container-instance-arn --query 'containerInstances[].remainingResources' # Check container instance Security Group aws ecs describe-container-instances --cluster $ECS_CLUSTER_NAME --container-instances container-instance-arn --query 'containerInstances[].ec2InstanceId' --output text aws ec2 describe-instances --instance-ids instance-id --query 'Reservations[0].Instances[0].SecurityGroups' aws ec2 describe-security-groups --group-ids security-group-id ``` **시스템 서비스 모니터링:** ``` # Check Containerd status nsenter -t 1 -m -p systemctl status containerd.service # Check Amazon ECS container agent status nsenter -t 1 -m -p systemctl status ecs ``` #### 해결 방법 태스크 배치 문제를 해결하려면 다음 단계에 따라 적절한 구성과 용량을 확인합니다. + 작업 리소스 요구 사항과 사용 가능한 용량 확인 + 배치 제약 조건 및 전략 확인 + Amazon ECS 관리형 인스턴스 용량 공급자가 구성되어 있는지 확인 + 태스크 및 컨테이너 인스턴스 보안 그룹에 Amazon ECS 에이전트 관리 엔드포인트에 대한 트래픽을 허용하는 아웃바운드 규칙이 있는지 확인합니다. ### 네트워킹 문제 다음은 네트워킹 문제의 증상입니다. + 태스크가 외부 서비스에 도달할 수 없음 + DNS 확인 문제 #### 진단 단계 **네트워크 연결성 테스트:** 디버그 컨테이너에서 다음 명령을 실행합니다. **참고** 용량 공급자 또는 Amazon ECS 태스크에 연결된 보안 그룹이 트래픽을 허용하는지 확인합니다. ``` # Install DNS Utility yum install bind-utils -y # Test DNS resolution nslookup amazon.com # Test external connectivity curl -I https://amazon.com ``` ### 리소스 제약 조건 다음은 네트워킹 문제의 증상입니다. + 메모리 제한으로 인해 태스크가 종료됨 + CPU 스로틀링 + 디스크 스페이스 문제 #### 진단 단계 명령을 실행하여 리소스 및 컨테이너 제한을 모니터링합니다. **리소스 모니터링:** ``` # Check memory usage nsenter -t 1 -m -p free -h # Check disk usage nsenter -t 1 -m -p lsblk # Check disk usage nsenter -t 1 -m -p df -h ``` **컨테이너 제한:** ``` # Check OOM kills nsenter -t 1 -m -p dmesg | grep -i "killed process" ``` ### 컨테이너 인스턴스 에이전트 연결 해제 문제 다음은 컨테이너 인스턴스 에이전트 연결 해제 문제의 증상입니다. + Amazon ECS 콘솔에서 연결 해제된 상태로 표시되는 컨테이너 인스턴스 + 태스크가 특정 인스턴스에 배치되지 않음 + 로그의 에이전트 등록 장애 #### 진단 단계 ECS Exec가 액세스할 수 있는 호스트에서 실행 중인 기존 권한 태스크가 있는 경우 다음 명령을 실행하여 에이전트 연결 문제를 진단합니다. ``` # check service status nsenter -t 1 -m -p systemctl restart ecs nsenter -t 1 -m -p systemctl restart containerd # restart stopped services nsenter -t 1 -m -p systemctl restart ecs nsenter -t 1 -m -p systemctl restart containerd ``` 그렇지 않으면 Amazon ECS 관리형 인스턴스의 등록을 강제로 취소합니다. 다음 명령을 실행합니다. ``` # list ECS Managed Instance container aws ecs list-container-instances --cluster managed-instances-cluster --query 'containerInstanceArns' --output text # deregister the specific container instance aws ecs deregister-container-instance \ --cluster $ECS_CLUSTER_NAME \ --container-instance container-instance-arn \ --force ``` #### 해결 방법 에이전트 연결 해제 문제를 해결하려면 다음 단계를 따릅니다. + 컨테이너 인스턴스에 대한 IAM 역할 권한 확인 + 보안 그룹 규칙이 ECS 엔드포인트로의 아웃바운드 HTTPS 트래픽을 허용하는지 확인 + AWS 서비스에 대한 네트워크 연결성 확인 + 필요한 경우 ECS 에이전트 서비스 다시 시작: `nsenter -t 1 -m -p systemctl restart ecs` + /etc/ecs/ecs.config의 ECS\$1CLUSTER 구성이 클러스터 이름과 일치하는지 확인 ## Amazon ECS 관리형 인스턴스에서 로그 분석 ### 시스템 로그 다음 명령을 사용하여 시스템 로그를 검사하고 관리형 인스턴스의 잠재적 문제를 식별합니다. ``` # Check system messages nsenter -t 1 -m -p journalctl --no-pager -n 50 # Check kernel logs nsenter -t 1 -m -p dmesg | tail -20 # Check for disk space errors nsenter -t 1 -m -p journalctl --no-pager | grep -i "no space\|disk full\|enospc" ``` ## EC2 AWS CLI를 사용하여 Amazon ECS 관리형 인스턴스에서 콘솔 출력 가져오기 EC2 인스턴스 ID를 사용하여 콘솔 출력을 검색합니다. 모든 *사용자 입력*을 사용자의 값으로 바꿉니다. ``` aws ec2 get-console-output --instance-id instance-id --latest --output text ``` ## 정리 다음을 실행하여 Deug 태스크를 중지하고 태스크 정의를 등록 취소합니다. ``` # Stop debug task aws ecs stop-task --cluster $ECS_CLUSTER_NAME --task $TASK_ARN # Deregister task definition (optional) aws ecs deregister-task-definition --task-definition node-debugger ``` ## 추가 리소스 Amazon ECS 관리형 인스턴스 문제 해결에 대한 자세한 내용은 다음 리소스를 참조하세요. + [Amazon ECS 기반 Amazon ECS 관리형 인스턴스 오류 문제 해결](managed-instances-errors.md) + [Amazon ECS 문제 해결](troubleshooting.md) + [Amazon ECS 컨테이너 에이전트 구성](ecs-agent-config.md) + [ECS Exec를 사용하여 Amazon ECS 컨테이너 모니터링](ecs-exec.md) # Amazon ECS 관리형 인스턴스 드레이닝 문제 해결 Amazon ECS 관리형 인스턴스에서 태스크를 시작할 때 Amazon ECS는 먼저 기존 용량에 태스크를 배치하려고 시도하고 배치할 수 없는 태스크에 대한 추가 용량을 요청합니다. 인스턴스 프로비저닝이 실패하면 Amazon EC2 요청 ID가 태스크 장애 메시지에 포함됩니다. 이 요청 ID를 사용하여 추가 문제 해결을 위해 CloudTrail에서 실패한 요청의 세부 정보를 조회할 수 있습니다. **참고** `AmazonECSInstanceRolePolicyForManagedInstances` 관리형 정책을 사용하는 대신 최소 권한을 적용하고 인스턴스 프로파일에 대한 자체 권한을 지정하도록 선택한 경우 Amazon ECS 관리형 인스턴스의 태스크 관련 문제를 해결하는 데 도움이 되는 다음 권한을 추가할 수 있습니다. `ecs:StartTelemetrySession` `ecs:PutSystemLogEvents` ## 태스크 정의가 Amazon ECS 관리형 인스턴스와 호환되지 않음 ### 일반적인 원인 이 오류는 태스크 정의에 Amazon ECS 관리형 인스턴스에서 지원되지 않는 파라미터 또는 구성이 포함되어 있을 때 발생합니다. 일반적인 비호환성으로, 지원되지 않는 네트워크 모드, 태스크 역할 또는 리소스 요구 사항이 포함됩니다. ### 해결 방법 1. 태스크 정의에서 `MANAGED_INSTANCES`로 설정된 `requiresCompatibilities`를 사용하는지 확인합니다. 1. 태스크 정의가 `awsvpc` 네트워크 모드를 사용하는지 확인합니다. 1. CPU 및 메모리 값이 Amazon ECS 관리형 인스턴스에 대해 지원되는 범위에 있는지 확인합니다. 1. 특정 비호환성 세부 정보는 자세한 오류 메시지를 검토하세요. ## 클러스터와 연결되지 않은 용량 공급자 ### 일반적인 원인 이 오류는 용량 공급자 전략에 지정된 용량 공급자가 클러스터와 연결되지 않았거나 존재하지 않을 때 발생합니다. ### 해결 방법 1. 용량 공급자가 계정 및 리전에 있는지 확인합니다. 1. Amazon ECS 콘솔 또는 CLI를 사용하여 용량 공급자를 클러스터에 연결합니다. 1. 용량 공급자를 사용하기 전에 용량 공급자가 `ACTIVE` 상태인지 확인합니다. ## 인프라 역할 권한 오류 ### 일반적인 원인 이 오류는 Amazon ECS 인프라 역할에 사용자를 대신해 Amazon EC2 작업을 수행하는 데 필요한 권한이 없거나 신뢰 관계 문제로 인해 역할을 수임할 수 없을 때 발생합니다. ### 해결 방법 1. 인프라 역할이 Amazon ECS와 적절한 신뢰 관계를 맺고 있는지 확인합니다. 1. `ec2:RunInstances`, `ec2:DescribeInstances`, `iam:PassRole`을 포함하여 역할에 필요한 Amazon EC2 권한이 있는지 확인합니다. 1. 특정 권한 세부 정보는 CloudTrail에서 인코딩된 권한 부여 실패 메시지를 확인하세요. 1. 오류 메시지에서 식별된 누락된 권한을 포함하도록 역할 정책을 업데이트합니다. ## VcpuLimitExceeded 오류 ### 일반적인 원인 이 오류는 현재 리전의 인스턴스 유형 패밀리에 대한 vCPU 서비스 할당량에 도달했을 때 발생합니다. Amazon ECS 관리형 인스턴스는 용량을 사용할 수 있을 때까지 추가 인스턴스를 시작할 수 없습니다. ### 해결 방법 1. AWS 지원 센터를 통해 영향을 받는 인스턴스 유형 패밀리에 대한 서비스 할당량 증가를 요청합니다. 1. 다른 vCPU 할당량 범주에 속하는 다른 인스턴스 유형을 사용하는 방법을 고려합니다. 1. 사용하지 않는 Amazon EC2 인스턴스를 종료하여 vCPU 용량을 확보합니다. 1. 용량 공급자 구성을 검토하여 vCPU 요구 사항이 낮은 인스턴스 유형을 사용합니다. ## InsufficientCapacity 및 관련 용량 오류 ### 일반적인 원인 이러한 오류는 AWS에 인스턴스 요청을 이행하기에 충분한 용량이 없을 때 발생합니다. 여기에는 요청된 가용 영역의 인스턴스 용량 부족, 주소 용량 또는 볼륨 용량이 포함될 수 있습니다. ### 해결 방법 1. 용량 공급자에서 여러 서브넷을 구성하여 서로 다른 가용 영역에서 인스턴스를 시작해 보세요. 1. 사용 가능한 용량이 더 많을 수 있는 다양한 인스턴스 유형을 사용하는 방법을 고려합니다. 1. 용량 가용성이 자주 변경되면 작업을 기다렸다가 다시 시도하세요. 1. 영구 용량 요구 사항에 대해서는 예약 인스턴스 또는 절감형 플랜 사용을 고려합니다. ## UnauthorizedOperation error ### 일반적인 원인 이 오류는 Amazon ECS 서비스에 Amazon EC2 작업을 수행하거나 IAM 역할을 전달하는 데 필요한 권한이 없을 때 발생합니다. 일반적인 시나리오로, `ec2:RunInstances` 권한 누락 또는 인스턴스 프로파일에 대한 `iam:PassRole` 권한 누락이 포함됩니다. ### 해결 방법 1. Amazon ECS 인프라 역할에 Amazon EC2 인스턴스를 시작하는 데 필요한 권한이 있는지 확인합니다. 1. 인프라 역할에 Amazon ECS 관리형 인스턴스에서 사용하는 인스턴스 프로파일에 대한 `iam:PassRole` 권한이 있는지 확인합니다. 1. 특정 권한 세부 정보는 CloudTrail에서 인코딩된 권한 부여 실패 메시지를 확인하세요. 1. 오류 메시지에서 식별된 누락된 권한을 포함하도록 역할 정책을 업데이트합니다. ## 용량 대기 중 태스크 제한 시간 초과됨 ### 일반적인 원인 이 오류는 인스턴스가 클러스터를 시작하고 등록하는 데 예상보다 오래 걸릴 때 발생합니다. Amazon EC2 용량 제약, 인스턴스 시작 실패 또는 네트워크 연결 문제로 인해 발생할 수 있습니다. ### 해결 방법 1. 리전의 Amazon EC2 서비스 상태를 확인하여 진행 중인 문제가 있는지 확인합니다. 1. 서브넷에 사용 가능한 IP 주소가 충분한지 확인합니다. 1. 보안 그룹이 Amazon ECS 에이전트 통신에 필요한 트래픽을 허용하는지 확인합니다. 1. 여러 가용 영역을 사용하여 용량 가용성을 개선하는 방법을 고려합니다. 1. 용량 제약 조건은 종종 일시적이므로 태스크 시작 작업을 재시도하세요. ## 네트워크 구성 오류 ### 일반적인 원인 이러한 오류는 VPC 불일치 또는 누락된 네트워크 구성과 같이 작업의 네트워크 요구 사항과 용량 공급자의 네트워크 구성 간에 불일치가 있을 때 발생합니다. ### 해결 방법 1. 용량 공급자가 올바른 VPC 및 서브넷으로 구성되었는지 확인합니다. 1. 보안 그룹과 서브넷이 동일한 VPC에 속하는지 확인합니다. 1. 태스크 정의의 네트워크 구성이 용량 공급자와 호환되는지 확인합니다. 1. 용량 공급자 구성을 올바른 네트워크 설정으로 업데이트합니다. ## 멈춘 인스턴스로 인해 용량 공급자를 삭제할 수 없음 ### 일반적인 원인 이러한 오류는 Amazon ECS 관리형 인스턴스가 `ACTIVE` 또는 `DRAINING` 상태에서 멈춰 있지만 인스턴스에서 실행 중인 태스크가 없는 경우에 발생합니다. ### 해결 방법 용량 공급자 삭제를 계속하려면 다음 명령을 사용하여 멈춘 인스턴스의 등록을 강제로 취소할 수 있습니다. ``` aws ecs deregister-container-instance \ --cluster arn:aws:ecs:us-east-1:111122223333:cluster/MyCluster \ --container-instance arn:aws:ecs:us-east-1:111122223333:container-instance/a1b2c3d4-5678-90ab-cdef-11111EXAMPLE \ --force ``` # Amazon ECS 기반 Amazon ECS 관리형 인스턴스 오류 문제 해결 다음은 몇 가지 CannotInspectContainerError 오류 메시지와 오류를 해결하기 위해 수행할 수 있는 작업입니다. ## Amazon ECS 관리형 인스턴스 공급자는 클러스터 이름 없이 지원되지 않음 이 오류는 Amazon ECS 관리형 인스턴스 공급자 파라미터가 있지만 클러스터 필드가 없는 용량 공급자를 생성하려고 할 때 발생합니다. 이 문제를 해결하려면 용량 공급자를 생성할 때 유효한 클러스터 이름을 지정합니다. ## Amazon ECS 관리형 인스턴스 용량 공급자를 생성할 때 Amazon ECS 관리형 인스턴스 공급자 세부 정보가 필요함 이 오류는 Amazon ECS 관리형 인스턴스 공급자로 용량 공급자를 생성하려고 하지만 실제 객체를 제공하지 않을 때 나타납니다. 이 문제를 해결하려면 유효한 Amazon ECS 관리형 인스턴스 공급자 세부 정보를 지정하고 다시 시도하세요. ## Amazon ECS 관리형 인스턴스 용량 공급자에서 인스턴스 프로파일을 지정해야 함 Amazon ECS 관리형 인스턴스 공급자를 사용하여 용량 공급자를 생성하려고 하지만 Ec2InstanceProfile을 제공하지 않으면 이 오류가 표시됩니다. 이 문제를 해결하려면 Amazon ECS 관리형 인스턴스 용량 공급자에 유효한 EC2 인스턴스 프로파일을 지정합니다. 자세한 내용은 [Amazon ECS 관리형 인스턴스의 인스턴스 프로파일](managed-instances-instance-profile.md) 섹션을 참조하세요. ## Amazon ECS 관리형 인스턴스 용량 공급자에서 InfrastructureRole을 지정해야 함 이 메시지는 Amazon ECS 관리형 인스턴스 공급자를 사용하여 용량 공급자를 생성하려고 하지만 InfrastructureRole을 제공하지 않을 때 나타납니다. 이를 해결하려면 Amazon ECS 관리형 인스턴스 용량 공급자에 유효한 인프라 역할을 지정합니다. 자세한 내용은 [Amazon ECS 인프라 IAM 역할](infrastructure_IAM_role.md) 섹션을 참조하세요. ## Amazon ECS 관리형 인스턴스 용량 공급자에서 네트워크 구성을 지정해야 함 Amazon ECS 관리형 인스턴스 공급자를 사용하여 용량 공급자를 생성하려고 하지만 네트워크 구성을 제공하지 않으면 이 오류가 발생합니다. 이를 해결하려면 Amazon ECS 관리형 인스턴스 용량 공급자의 서브넷이 비어 있지 않은 유효한 네트워크 구성을 지정합니다. 자세한 내용은 [Amazon ECS 관리형 인스턴스에 대한 Amazon ECS 태스크 네트워킹](managed-instance-networking.md) 섹션을 참조하세요. ## Amazon ECS 관리형 인스턴스 용량 공급자에 지정된 인스턴스 요구 사항을 충족하는 인스턴스 유형 없음 이는 Amazon ECS 관리형 인스턴스 공급자를 사용하여 용량 공급자를 생성하려고 하지만 EC2 인스턴스 유형이 인스턴스 요구 사항을 충족하지 않는 경우에 발생합니다. 이를 해결하려면 사용 가능한 EC2 인스턴스 유형에 맞게 인스턴스 요구 사항을 검토하고 조정합니다. ## 지정된 인프라 역할 ARN이 유효하지 않음 이 오류는 InfrastructureRole이 특정 ARN 형식을 따르지 않을 때 발생합니다. 예상 형식: `arn:partition:iam::account-id:role/role-name` 유효한 역할 ARN을 지정하고 다시 시도하세요. 자세한 내용은 [Amazon ECS 인프라 IAM 역할](infrastructure_IAM_role.md) 섹션을 참조하세요. ## 지정된 인스턴스 프로파일 역할 ARN이 유효하지 않음 이 오류는 인스턴스 프로파일이 특정 ARN 형식을 따르지 않을 때 발생합니다. 예상 형식: `arn:partition:iam::account-id:instance-profile/profile-name` 유효한 역할 ARN을 지정하고 다시 시도하세요. 자세한 내용은 [Amazon ECS 관리형 인스턴스의 인스턴스 프로파일](managed-instances-instance-profile.md) 섹션을 참조하세요. ## 지정된 보안 그룹 ID가 유효하지 않음 이 오류는 보안 그룹 ID가 특정 형식을 따르지 않을 때 발생합니다. 예상 형식: `sg-xxxxxxxx` 또는 `sg-xxxxxxxxxxxxxxxxxx`(문자(소문자) 및 'sg-' 뒤의 숫자를 포함하여 8자 또는 17자). 보안 그룹 ID를 지정하고 다시 시도하세요. ## 지정된 서브넷 ID가 유효하지 않음 이 오류는 서브넷 ID가 특정 형식을 따르지 않을 때 발생합니다. 예상 형식: `subnet-xxxxxxxx` 또는 `subnet-xxxxxxxxxxxxxxxxxx`(문자(소문자) 및 'subnet-' 뒤의 숫자를 포함하여 8자 또는 17자). 서브넷 ID를 지정하고 다시 시도하세요. ## Amazon ECS 관리형 인스턴스 용량 공급자는 빈 서브넷이 아닌 네트워크 구성을 지정해야 합니다. 이 오류는 빈 서브넷을 포함하는 네트워크 구성과 Amazon ECS 관리형 인스턴스 공급자를 사용하여 용량 공급자를 생성하려고 할 때 발생합니다. 이를 해결하려면 Amazon ECS 관리형 인스턴스 용량 공급자의 서브넷이 비어 있지 않은 유효한 네트워크 구성을 지정합니다. ## Amazon ECS 관리형 인스턴스 용량 공급자는 최대 허용 값을 초과하는 태그 수를 보유할 수 없습니다. 이 오류는 허용되는 최대 태그 수(45개)를 초과하는 용량 공급자를 생성하려고 할 때 발생합니다. 이 문제를 해결하려면 태그 수를 45개 이하로 줄이고 다시 시도하세요. ## propagateTags에 대한 값이 유효하지 않음 이 오류는 유효하지 않은 propagateTags 값으로 용량 공급자를 생성하려고 할 때 발생합니다. 값은 유효한 propagateTags 값 중 하나여야 합니다. 유효한 값을 지정하고 다시 시도하세요. ## 지정된 용량 공급자에 이미 클러스터 범위가 있음 이 오류는 클러스터 이름 없이 Amazon ECS 관리형 인스턴스 용량 공급자를 생성, 업데이트 또는 삭제하려고 하지만 기존 클러스터 범위의 용량 공급자가 있을 때 발생합니다. 용량 공급자의 구성을 변경하거나 삭제하려면 클러스터 파라미터로 용량 공급자를 업데이트하거나 삭제합니다. ## 지정된 용량 공급자가 계정 또는 다른 클러스터에 이미 있음 이 오류는 다른 클러스터에 대한 기존 계정 범위의 용량 공급자 또는 기존 클러스터 범위의 용량 공급자가 있는 경우 클러스터 필드를 사용하여 Amazon ECS 관리형 인스턴스 용량 공급자를 생성, 업데이트 또는 삭제하려고 할 때 발생합니다. 이를 해결하려면 다른 용량 공급자 이름을 사용하거나 기존 용량 공급자와 협력합니다. ## 용량 공급자 활성 클러스터 이름이 요청의 클러스터 이름과 일치하지 않음 이 오류는 용량 공급자의 활성 클러스터 이름이 요청에 지정된 클러스터 이름과 일치하지 않을 때 발생합니다. 요청의 클러스터 이름이 용량 공급자의 연결된 클러스터와 일치하는지 확인합니다. ## 용량 공급자가 Amazon ECS 관리형 인스턴스 용량 공급자가 아님 이 오류는 Amazon ECS 관리형 인스턴스 용량 공급자가 필요한 컨텍스트에서 해당 용량 공급자가 아닌 다른 항목을 사용하려고 할 때 발생합니다. 요청에 유효한 Amazon ECS 관리형 인스턴스 용량 공급자를 사용하고 있는지 확인합니다. ## CapacityProvider 이름은 비워둘 수 없음 이 오류는 용량 공급자 이름을 지정하지 않고 용량 공급자를 생성하려고 할 때 발생합니다. 유효한 용량 공급자 이름을 지정하고 다시 시도하세요. ## 용량 공급자를 업데이트할 때 이름이 필요함 이 오류는 용량 공급자 이름을 지정하지 않고 용량 공급자를 업데이트하려고 할 때 발생합니다. 다른 이름을 지정하고 다시 시도하세요. ## 태그는 null이거나 null 요소를 가질 수 음 이 오류는 Null 값으로 용량 공급자에 태그를 지정하려고 할 때 발생합니다. 모든 태그 값이 올바르게 지정되고 null이 아닌지 확인합니다. # Amazon ECS의 API 실패 이유 Amazon ECS API, 콘솔 또는 AWS CLI를 통해 트리거한 API 작업이 종료되고 `failures` 오류 메시지가 나타나면 다음을 통해 원인 해결에 도움을 줄 수 있습니다. 실패로 인해 실패와 연관된 리소스의 이유 및 Amazon 리소스 이름(ARN)이 반환됩니다. 대부분의 리소스는 리전 전용이므로 콘솔을 사용할 때에는 해당 리소스에 대한 올바른 리전을 설정했는지 확인해야 합니다. AWS CLI를 사용할 때에는 AWS CLI 명령이 `--region region` 파라미터가 포함된 올바른 리전으로 전송되고 있는지 확인합니다. `Failure` 데이터 형식의 구조에 대한 자세한 내용은 *Amazon Elastic Container Service API 참조*의 [실패](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Failure.html)를 참조하세요. 다음은 API 명령을 실행할 때 수신할 수 있는 실패 메시지 예제입니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/api_failures_messages.html) **참고** 여기에 설명된 실패 시나리오 외에도 API 작업은 예외로 인해 실패하여 오류 응답이 발생할 수도 있습니다. 이러한 예외 목록은 [일반 오류](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/CommonErrors.html)를 참조하세요. # Amazon Q Developer로 문제 해결 Amazon ECS 콘솔에서 [Amazon Q Developer](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/what-is.html)를 사용하여 Amazon ECS 리소스 문제를 진단하고 해결할 수 있습니다. 컨테이너, 태스크, 서비스, 배포 및 태스크 정의에 대한 특정 오류 및 상태 메시지의 경우 콘솔에 **Amazon Q Developer로 검사** 옵션이 표시됩니다. 이 옵션을 선택하면 Amazon Q Developer에서 컨텍스트를 기반으로 문제를 분석하고 가능한 원인과 해결 단계를 제안합니다. ## 필수 권한 + 클러스터, 서비스, 태스크 및 태스크 정의와 같이 문제를 해결하려는 Amazon ECS 리소스를 볼 수 있는 권한. + 콘솔에서 [Amazon Q Developer를 사용할 권한](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/security_iam_permissions.html). + (권장) 다음과 같은 관련 로그 및 지표를 볼 수 있는 권한: + CloudWatch Logs + CloudWatch ## 절차 1. [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)에서 콘솔을 엽니다. 1. 문제를 해결하려는 리소스를 결정하세요. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonECS/latest/developerguide/troubleshooting-with-Q.html) 1. 리소스 세부 정보 페이지에서 문제를 설명하는 상태 또는 상태 이유를 찾으세요. 1. 상태 이유를 클릭하여 팝오버를 여세요. 1. 사용 가능한 경우 **Amazon Q Developer로 검사**를 선택하세요. 1. Amazon Q Developer가 제공하는 설명 및 제안된 수정 단계를 검토하세요. 환경에 맞게 구성 또는 운영 변경 사항을 적용하세요. ## 고려 사항 Amazon ECS에서 Amazon Q Developer를 사용할 경우 다음을 고려합니다. + **버튼 가용성** - 'Amazon Q Developer로 검사' 버튼은 잠재적 문제가 발생한 리소스에만 표시됩니다. 정상 리소스에 대해서는 이 옵션을 사용할 수 없습니다. + **읽기 전용 작업** - Amazon Q Developer 통합은 읽기 작업만 수행합니다. 변경 또는 쓰기 작업은 수행하지 않습니다. + **교차 리전 처리** - Amazon Q Developer는 AI 기반 분석을 제공하기 위해 여러 AWS 리전에서 데이터를 처리할 수 있습니다. 교차 리전 처리에 대한 자세한 내용은 [Cross-region processing in Amazon Q Developer](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/cross-region-processing.html)를 참조하세요. + **콘솔 전용** - 이 통합은 콘솔을 통해서만 사용할 수 있습니다. AWS CLI, AWS API 또는 코드형 인프라를 통해 사용할 수 없습니다. ## 자세히 알아보기 Amazon Q Developer 사용에 대한 자세한 내용은 [Chatting with Amazon Q Developer about AWS](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/chat-with-q.html)를 참조하세요.