EKS Auto Mode 문제 해결하기

EKS Auto Mode에서 발생할 수 있는 문제를 해결하는 방법을 알아봐요. EKS Auto Mode는 계정 내 EC2 인스턴스에 대해 AWS가 더 많은 책임을 지므로, 노드의 컨테이너 런타임과 운영체제, 그리고 특정 컨트롤러(블록 스토리지, 로드 밸런싱, 컴퓨트 컨트롤러)를 EKS가 관리해요.

출처: 문서

본문

EKS Auto Mode에서는 AWS와 Kubernetes API를 사용해 노드를 문제 해결해야 해요. 다음을 할 수 있어요:

Kubernetes NodeDiagnostic 리소스와 Node monitoring agent를 사용해 노드 로그를 검색해요. 자세한 단계는 Retrieve node logs for a managed node using kubectl and S3를 참고해 주세요.
Kubernetes NodeDiagnostic 리소스를 사용해 노드의 네트워크 트래픽을 캡처해요. 자세한 단계는 Capture network traffic on a managed node using kubectl and S3를 참고해 주세요.
AWS EC2 CLI의 get-console-output 명령으로 노드의 콘솔 출력을 검색해요. 자세한 단계는 Get console output from an EC2 managed instance by using the AWS EC2 CLI를 참고해 주세요.
Kubernetes 디버깅 컨테이너로 노드 로그를 검색해요. 자세한 단계는 Get node logs by using debug containers and the kubectl CLI를 참고해 주세요.

참고: EKS Auto Mode는 EC2 관리형 인스턴스를 사용해요. SSH를 포함해 EC2 관리형 인스턴스에 직접 접근할 수 없어요.

EKS Auto Mode 컴포넌트 특유의 해결책이 필요한 문제가 있을 수 있어요:

Auto Mode 노드에 스케줄링되지 않고 Pending 상태에 갇힌 파드. 해결책은 Troubleshoot Pod failing to schedule onto Auto Mode node를 참고해 주세요.
클러스터에 Kubernetes 노드로 조인하지 못하는 EC2 관리형 인스턴스. 해결책은 Troubleshoot node not joining the cluster를 참고해 주세요.
EKS Auto Mode에 포함된 컨트롤러를 사용하는 NodePools, PersistentVolumes, Services의 오류와 문제. 해결책은 Troubleshoot included controllers in Auto Mode를 참고해 주세요.
강화된 파드 보안으로 파드 간 볼륨 공유가 방지됨. 해결책은 Sharing Volumes Across Pods를 참고해 주세요.

EKS Auto Mode 컴포넌트를 문제 해결하는 데 다음 방법을 사용할 수 있어요:

AWS EC2 CLI로 EC2 관리형 인스턴스의 콘솔 출력 가져오기
디버그 컨테이너와 kubectl CLI로 노드 로그 가져오기
AWS 콘솔에서 EKS Auto Mode 관련 리소스 보기
AWS 계정의 IAM 오류 보기
VPC Reachability Analyzer로 노드 연결 문제 감지

노드 모니터링 에이전트 (Node monitoring agent)

EKS Auto Mode는 Amazon EKS node monitoring agent를 포함해요. 이 에이전트로 노드에 대한 문제 해결 및 디버깅 정보를 볼 수 있어요. node monitoring agent는 Kubernetes events와 노드 conditions를 게시해요. 자세한 내용은 Detect node health issues and enable automatic node repair를 참고해 주세요.

AWS EC2 CLI로 EC2 관리형 인스턴스의 콘솔 출력 가져오기 (Get console output from an EC2 managed instance by using the AWS EC2 CLI)

이 절차는 부팅 시점 또는 커널 수준 문제를 해결하는 데 도움을 줘요.

먼저 워크로드와 연결된 인스턴스의 EC2 Instance ID를 확인해야 해요. 둘째로 AWS CLI로 콘솔 출력을 검색해요.

kubectl이 설치되어 클러스터에 연결되어 있는지 확인해요.
(선택사항) Kubernetes Deployment의 이름으로 관련 파드를 나열해요.

kubectl get pods -l app=<app-name>

Kubernetes 파드의 이름으로 연결된 노드의 EC2 instance ID를 확인해요.

kubectl get pod <pod-name> -o wide

EC2 instance ID로 콘솔 출력을 검색해요.

aws ec2 get-console-output --instance-id <instance-id> --latest --output text

디버그 컨테이너와 `kubectl` CLI로 노드 로그 가져오기 (Get node logs by using debug containers and the kubectl CLI)

EKS Auto Mode 노드에서 로그를 검색하는 권장 방법은 NodeDiagnostic 리소스를 사용하는 거예요. 단계는 Retrieve node logs for a managed node using kubectl and S3를 참고해 주세요.

하지만 kubectl debug node 명령으로 인스턴스에서 라이브 로그를 스트리밍할 수 있어요. 이 명령은 디버그하려는 노드에 새 파드를 시작하며 대화형으로 사용할 수 있어요.

디버그 컨테이너를 시작해요. 다음 명령은 노드의 인스턴스 ID로 i-01234567890123456을 사용하고, -it는 tty를 할당하고 대화형 사용을 위해 stdin을 연결하며, kubeconfig 파일의 sysadmin 프로파일을 사용해요.

kubectl debug node/i-01234567890123456 -it --profile=sysadmin --image=public.ecr.aws/amazonlinux/amazonlinux:2023

예시 출력은 다음과 같아요:

Creating debugging pod node-debugger-i-01234567890123456-nxb9c with container debugger on node i-01234567890123456.
If you don't see a command prompt, try pressing enter.
bash-5.2#

셸에서 이제 nsenter 명령을 제공하는 util-linux-core를 설치할 수 있어요. nsenter로 호스트의 PID 1(init) 마운트 네임스페이스에 들어가고, journalctl 명령으로 kubelet의 로그를 스트리밍해요:

yum install -y util-linux-core
nsenter -t 1 -m journalctl -f -u kubelet

보안상 Amazon Linux 컨테이너 이미지는 기본적으로 많은 바이너리를 설치하지 않아요. yum whatprovides 명령으로 특정 바이너리를 제공하는 데 설치해야 하는 패키지를 식별할 수 있어요.

yum whatprovides ps

Last metadata expiration check: 0:03:36 ago on Thu Jan 16 14:49:17 2025.
procps-ng-3.3.17-1.amzn2023.0.2.x86_64 : System and process monitoring utilities
Repo        : @System
Matched from:
Filename    : /usr/bin/ps
Provide    : /bin/ps

procps-ng-3.3.17-1.amzn2023.0.2.x86_64 : System and process monitoring utilities
Repo        : amazonlinux
Matched from:
Filename    : /usr/bin/ps
Provide    : /bin/ps

AWS 콘솔에서 EKS Auto Mode 관련 리소스 보기 (View resources associated with EKS Auto Mode in the AWS Console)

AWS 콘솔로 EKS Auto Mode 클러스터와 연결된 리소스의 상태를 볼 수 있어요.

EBS 볼륨 — eks:eks-cluster-name 태그 키로 검색해 EKS Auto Mode 볼륨을 봐요.
로드 밸런서 — eks:eks-cluster-name 태그 키로 검색해 EKS Auto Mode 로드 밸런서를 봐요.
EC2 인스턴스 — EKS Auto Mode 인스턴스는 EC2 관리형 인스턴스예요. 2026년 4월 22일부터 새 관리형 인스턴스와 관련 리소스는 기본적으로 EC2 콘솔 보기와 API 목록 작업(예: DescribeInstances)에서 숨겨져요. EC2 콘솔에서 Auto Mode 인스턴스가 보이지 않으면 관리형 리소스 표시 여부(visibility) 설정을 확인해 주세요:
1. Amazon EC2 콘솔을 https://console.aws.amazon.com/ec2/ 에서 엽니다.
2. 탐색 창에서 Dashboard를 선택합니다.
3. Account attributes 카드의 Settings 아래에서 Managed resource visibility를 선택합니다.
4. Manage를 선택한 다음 관리형 인스턴스의 표시 토글을 선택합니다.
5. Save changes를 선택합니다.
표시를 활성화한 후 eks:eks-cluster-name 태그 키로 검색해 EKS Auto Mode 인스턴스를 볼 수 있어요.

또는 다음을 통해 Auto Mode 노드를 볼 수 있어요:
- Amazon EKS 콘솔의 클러스터 Compute 탭.
- 구성된 Kubernetes 클라이언트의 kubectl get nodes.
- 인스턴스 ID 또는 include-managed-resources 파라미터로 직접 EC2 API 쿼리.
자세한 내용은 Amazon EC2 사용자 안내서의 Managed resource visibility settings를 참고해 주세요.

AWS 계정의 IAM 오류 보기 (View IAM Errors in your AWS account)

CloudTrail 콘솔로 이동합니다.
왼쪽 탐색 창에서 Event history를 선택합니다.
Event history 테이블 오른쪽 위의 설정(톱니) 아이콘을 선택하고 Error code 열을 활성화합니다.
Error code 열을 검토해 AccessDenied, UnauthorizedOperation, InvalidClientTokenId 같은 권한 관련 오류를 찾습니다. 목록을 좁히려면 Event source(예: ec2.amazonaws.com 또는 eks.amazonaws.com)와 시간 범위로 필터링합니다.
더 넓은 시간 창에서 오류 코드로 더 정밀하게 필터링하려면 CloudTrail Lake 이벤트 데이터 저장소를 쿼리하거나 Athena 테이블을 만듭니다(Event history 페이지 상단의 Query in Lake 및 Create Athena table 옵션).
EKS 클러스터와 관련된 오류를 찾습니다. 오류 메시지를 사용해 EKS access entries, cluster IAM role, node IAM role을 업데이트합니다. EKS Auto Mode용 권한이 있는 새 정책을 이 역할들에 연결해야 할 수 있습니다.

Auto Mode 노드에 스케줄링되지 않는 파드 문제 해결 (Troubleshoot Pod failing to schedule onto Auto Mode node)

파드가 Pending 상태에 머물며 auto mode 노드에 스케줄링되지 않으면, 파드나 배포 매니페스트에 nodeSelector가 있는지 확인해 주세요. nodeSelector가 있다면 EKS Auto Mode가 만든 노드에 스케줄링되도록 eks.amazonaws.com/compute-type: auto를 사용하는지 확인해 주세요. EKS Auto Mode가 사용하는 노드 라벨에 대한 자세한 내용은 Control if a workload is deployed on EKS Auto Mode nodes를 참고해 주세요.

클러스터에 조인하지 않는 노드 문제 해결 (Troubleshoot node not joining the cluster)

EKS Auto Mode는 새 EC2 인스턴스를 클러스터 엔드포인트와 클러스터 인증 기관(CA)을 포함한 올바른 정보로 자동 구성해요. 하지만 이런 인스턴스도 EKS 클러스터에 노드로 조인하지 못할 수 있어요. 다음 명령으로 클러스터에 조인하지 않은 인스턴스를 식별해요:

kubectl get nodeclaim을 실행해 Ready = False인 NodeClaims를 확인해요.

kubectl get nodeclaim

kubectl describe nodeclaim <name>을 실행하고 Status 아래에서 노드가 클러스터에 조인하지 못하게 하는 문제를 찾아요.

kubectl describe nodeclaim <name>

일반적인 오류 메시지:

Error getting launch template configs — 기본 클러스터 IAM 역할 권한으로 NodeClass에 사용자 지정 태그를 설정하는 경우 이 오류가 발생할 수 있어요. Learn about identity and access in EKS Auto Mode를 참고해 주세요.
Error creating fleet — EC2 API의 RunInstances 호출에 권한 부여 문제가 있을 수 있어요. AWS CloudTrail에서 오류를 확인하고, 필요한 IAM 권한은 Amazon EKS Auto Mode cluster IAM role을 참고해 주세요.

`VPC Reachability Analyzer`로 노드 연결 문제 감지하기 (Detect node connectivity issues with the VPC Reachability Analyzer)

참고: VPC Reachability Analyzer가 실행하는 각 분석에 대해 요금이 부과돼요. 요금 세부 정보는 Amazon VPC Pricing을 참고해 주세요.

인스턴스가 클러스터에 조인하지 못하는 한 가지 이유는 API 서버에 도달하지 못하는 네트워크 연결 문제예요. 이 문제를 진단하려면 VPC Reachability Analyzer로 클러스터 조인에 실패하는 노드와 API 서버 간 연결 분석을 수행할 수 있어요. 두 가지 정보가 필요해요:

클러스터에 조인할 수 없는 노드의 instance ID
Kubernetes API 서버 엔드포인트의 IP 주소

instance ID를 얻으려면 클러스터에 워크로드를 만들어 EKS Auto Mode가 EC2 인스턴스를 시작하게 해야 해요. 이렇게 하면 cluster 안에 instance ID가 있는 NodeClaim 객체도 생성돼요. kubectl get nodeclaim -o yaml로 클러스터의 모든 NodeClaims를 출력해요. 각 NodeClaim은 필드와 providerID에 instance ID를 포함해요:

kubectl get nodeclaim -o yaml

예시 출력:

    nodeName: i-01234567890123456
    providerID: aws:///us-west-2a/i-01234567890123456

kubectl get endpoints kubernetes -o yaml로 Kubernetes API 서버 엔드포인트를 확인할 수 있어요. 주소는 addresses 필드에 있어요:

kubectl get endpoints kubernetes -o yaml

예시 출력:

apiVersion: v1
kind: Endpoints
metadata:
  name: kubernetes
  namespace: default
subsets:
- addresses:
  - ip: 10.0.143.233
  - ip: 10.0.152.17
  ports:
  - name: https
    port: 443
    protocol: TCP

이 두 정보로 분석을 수행할 수 있어요. 먼저 AWS Management Console에서 VPC Reachability Analyzer로 이동합니다.

Create and Analyze Path를 선택합니다.
분석 이름(예: "Node Join Failure")을 입력합니다.
Source Type에서 Instances를 선택합니다.
실패한 노드의 instance ID를 Source로 입력합니다.
Path Destination에서 IP Address를 선택합니다.
API 서버의 IP 주소 중 하나를 Destination Address로 입력합니다.
Additional Packet Header Configuration Section을 펼칩니다.
Destination Port에 443을 입력합니다.
아직 선택되지 않았다면 Protocol을 TCP로 선택합니다.
Create and Analyze Path를 선택합니다.

분석은 완료까지 몇 분이 걸릴 수 있어요. 분석 결과가 도달 불가능(reachability 실패)을 나타내면 네트워크 경로에서 어디가 실패했는지 알려주므로 문제를 해결할 수 있어요.

EKS Auto Mode 노드는 SELinux를 enforcing 모드로 구성해 같은 노드에서 실행되는 파드 간에 더 많은 격리를 제공해요. SELinux가 활성화되면 대부분의 비특권 파드에는 자동으로 자체 다중 카테고리 보안(MCS) 라벨이 적용돼요. 이 MCS 라벨은 파드마다 고유하며, 한 파드의 프로세스가 다른 파드나 호스트의 프로세스를 조작할 수 없도록 보장하도록 설계됐어요. 라벨이 지정된 파드가 root로 실행되고 호스트 파일시스템에 접근할 수 있어도, 호스트에서 파일을 조작하거나 민감한 시스템 콜을 하거나 컨테이너 런타임에 접근하거나 kubelet의 시크릿 키 자료를 얻을 수 없어요.

이 때문에 파드 간 데이터 공유를 시도할 때 문제가 발생할 수 있어요. 예를 들어 접근 모드가 ReadWriteOnce인 PersistentVolumeClaim은 여전히 여러 파드가 볼륨에 동시에 접근하는 것을 허용하지 않아요.

파드 간 공유를 활성화하려면 파드의 seLinuxOptions로 해당 파드들에 같은 MCS 라벨을 구성할 수 있어요. 이 예시에서는 파드에 c123,c456,c789 세 개의 카테고리를 할당해요. 노드의 파드에 자동으로 할당되는 카테고리와 충돌하지 않는데, 자동 할당은 두 개의 카테고리만 부여되기 때문이에요.

securityContext:
  seLinuxOptions:
    level: "s0:c123,c456,c789"

제어 플레인 로그에서 Karpenter 이벤트 보기 (View Karpenter events in control plane logs)

제어 플레인 로깅이 활성화된 EKS 클러스터에서 로그를 쿼리해 Karpenter의 동작과 의사 결정 과정에 대한 인사이트를 얻을 수 있어요. 이는 노드 프로비저닝, 스케일링, 종료와 관련된 EKS Auto Mode 문제를 해결하는 데 특히 유용해요. Karpenter 관련 이벤트를 보려면 다음 CloudWatch Logs Insights 쿼리를 사용해 주세요:

fields @timestamp, @message
| filter @logStream like /kube-apiserver-audit/
| filter @message like 'DisruptionBlocked'
or @message like 'DisruptionLaunching'
or @message like 'DisruptionTerminating'
or @message like 'DisruptionWaitingReadiness'
or @message like 'Unconsolidatable'
or @message like 'FailedScheduling'
or @message like 'NoCompatibleInstanceTypes'
or @message like 'NodeRepairBlocked'
or @message like 'Disrupted'
or @message like 'Evicted'
or @message like 'FailedDraining'
or @message like 'TerminationGracePeriodExpiring'
or @message like 'TerminationFailed'
or @message like 'FailedConsistencyCheck'
or @message like 'InsufficientCapacityError'
or @message like 'UnregisteredTaintMissing'
or @message like 'NodeClassNotReady'
| sort @timestamp desc

이 쿼리는 kube-apiserver 감사 로그에서 특정 Karpenter 관련 이벤트를 필터링해요. 이벤트에는 다양한 중단 상태, 스케줄링 실패, 용량 문제, 노드 관련 문제가 포함돼요. 이 로그를 분석하면 다음을 더 잘 이해할 수 있어요:

Karpenter가 특정 작업을 하는 이유.
적절한 노드 프로비저닝, 스케일링, 종료를 방해하는 문제.
인스턴스 유형의 잠재적 용량 또는 호환성 문제.
중단, 축출, 종료 같은 노드 수명주기 이벤트.

이 쿼리를 사용하려면:

CloudWatch 콘솔로 이동합니다.
왼쪽 탐색 창에서 Logs Insights를 선택합니다.
EKS 클러스터 제어 플레인 로그의 로그 그룹을 선택합니다.
쿼리를 쿼리 편집기에 붙여넣습니다.
필요에 따라 시간 범위를 조정합니다.
쿼리를 실행합니다.

결과는 Karpenter 관련 이벤트의 타임라인을 보여주며, 문제 해결과 클러스터에서 EKS Auto Mode 동작을 이해하는 데 도움을 줘요. 특정 노드의 Karpenter 작업을 검토하려면 쿼리에 instance ID를 지정하는 다음 라인 필터를 추가할 수 있어요:

|filter @message like /i-12345678910123456/

참고: 이 쿼리를 사용하려면 EKS 클러스터에서 제어 플레인 로깅이 활성화되어 있어야 해요. 아직 하지 않았다면 Send control plane logs to CloudWatch Logs를 참고해 주세요.

Auto Mode의 포함된 컨트롤러 문제 해결 (Troubleshoot included controllers in Auto Mode)

컨트롤러에 문제가 있다면 다음을 조사해야 해요:

해당 컨트롤러와 연결된 리소스가 올바르게 포맷되고 유효한지.
AWS IAM과 Kubernetes RBAC 리소스가 클러스터에 적절히 구성되었는지. 자세한 내용은 Learn about identity and access in EKS Auto Mode를 참고해 주세요.

고급 문제 해결 단계는 AWS re:Post의 다음 문서를 사용해 주세요:

How to troubleshoot common scaling issues in EKS Auto-Mode?
How do I troubleshoot custom nodepool and nodeclass provisioning issues in Amazon EKS Auto Mode?
How do I troubleshoot EKS Auto Mode built-in node pools with Unknown Status?

더 알아보기 (Learn more)

공식 문서

EKS Auto Mode 문제 해결하기