"AWSSupport-TroubleshootEKSWorkerNode" 런북을 사용하여 Amazon EKS 클러스터의 워커 노드에 발생한 문제를 확인하고 해결하는 방법

Amazon Elastic Kubernetes Service (EKS) 서비스는 Amazon Web Services (AWS) 환경에 Kubernetes 컨트롤 플레인을 설치, 운영 및 유지 관리할 필요가 없는 관리형 서비스입니다.

그러나 EKS 클러스터를 사용하는 중에 종종 다양한 이유로 Amazon Elastic Compute Cloud (EC2) 워커 노드 (인스턴스)가 클러스터에 연결 (Join)되지 못하거나 연결이 해제 ('Ready' 상태에서 'NotReady' 상태로 전환 등)되는 상황이 발생할 수 있습니다.

그림 1: EKS 클러스터의 워커 노드 (EC2 인스턴스)가 'NotReady'로 전환되는 현상 발생

이러한 경우 이슈 해결을 위해 AWS Premium Support에서 서포트 케이스를 생성하여 문제 해결에 지원을 받거나, AWS 지원 자동화 워크플로우 (Support Automation Workflow) 런북을 활용하여 AWS Premium Support의 지원을 기다리지 않고 직접 빠르게 이슈를 진단하고 해결할 수도 있습니다.

AWS 지원 자동화 워크플로우는 AWS Systems Manager 셀프 서비스 자동화 런북 모음입니다. 이러한 런북은 AWS Support Engineering 팀에서 고객 문제를 해결하며 배운 모범 사례를 바탕으로 작성되었습니다. 이를 통해 AWS 고객은 AWS 리소스의 일반적인 문제를 진단, 수정, 해결할 수 있습니다. 또한 네트워크 문제를 사전에 식별하고 로그 수집 및 분석의 다양한 작업을 수행할 수 있습니다. AWS 지원 자동화 워크플로우 런북은 AWS 모범 사례에 따라 수동 작업 및 관리 오버헤드, 인적 오류를 줄일 수 있습니다.

AWS 지원 자동화 워크플로우에서 제공되는 "AWSSupport-TroubleshootEKSWorkerNode" 런북을 이용하면 Amazon EKS 클러스터의 EC2 워커 노드에 발생한 문제를 직접 빠르게 진단하고 해결할 수 있습니다.

단, 본 런북의 자동화 도구를 성공적으로 실행하려면 EC2 워커 노드의 상태가 running (실행 중)이고 EKS 클러스터의 상태가 ACTIVE (활성)이어야 합니다. 더불어, 본 런북은 클러스터나 워커 노드에 대하여 수정을 가하지는 않으며, Windows 및 Bottlerocket OS의 워커 노드는 지원하지 않습니다.

"AWSSupport-TroubleshootEKSWorkerNode" 런북은 사용자를 대신하여 아래와 같은 자원에 대하여 확인합니다.

• EKS 클러스터 관점의 확인 사항:
  1. 클러스터 보안 그룹이 워커 노드로부터의 트래픽을 허용하는 지 확인합니다.
  2. 클러스터 VPC의 DHCP 옵션 및 필수 DNS 특성 (required DNS attributes)을 확인합니다.
  3. 클러스터의 IAM 역할이 필수적인 권한을 가지고 있는 지 확인합니다.
  4. 컨트롤 플레인 (CP - Control Plane)의 ENI 존재 여부를 확인합니다.
• EC2 워커 노드에 대하여 확인 사항:
  1. EC2 워커 노드의 인스턴스 유형이 EKS 서비스에 지원되는 유형인 지 확인합니다.
  2. 워커 노드의 네트워크 구성, ENI와 사설 IP 주소, 보안 그룹 및 NACL의 규칙이 적절한 지 확인합니다.
  3. 클러스터의 퍼블릭/프라이빗 엔드포인트와 워커 노드 간의 통신 가능 여부를 확인합니다.
  4. 워커 노드의 인스턴스 프로파일 (필요 권한 여부, 신뢰 관계 정책 적합성 등)을 확인합니다.
  5. 워커 노드의 태그, AMI, UserData, Metadata 등이 적절한 지 확인합니다.
  6. 워커 노드에 SSM agent 동작 시 Containerd, kubelet 등의 상태를 확인합니다.

본 기사에서는 "AWSSupport-TroubleshootEKSWorkerNode" 런북을 이용하여 Amazon EKS 클러스터에 EC2 워커 노드가 연결되지 않는 현상을 진단하고 해결하는 예시를 제공합니다.

EC2 워커 노드에 발생한 문제 해결을 위해 런북을 사용한 예시

그림 1: EKS 클러스터의 워커 노드 (EC2 인스턴스)가 'NotReady'로 전환되는 현상 발생

예를 들어, 위와 같이 EC2 워커 노드의 상태가 'Ready'에서 'NotReady' 상태로 전환되며 클러스터에 Join하지 못하는 경우 그 원인을 진단하고 해결할 방법을 찾기 위해 본 런북에서 제공하는 자동화 (Automation) 도구를 콘솔에서 실행할 수 있습니다.

런북 자동화 도구 실행 절차:

1. AWS Systems Manager 콘솔로 이동하여 왼편의 네비게이션 메뉴에서 '자동화 (Automation)' 메뉴를 선택합니다. 그림 2: AWS systems Manager 콘솔의 왼편에서 '자동화 (Automation)' 메뉴를 선택

2. '자동화 (Automation)' 화면에서 '자동화 실행 (Execute automation)' 버튼을 선택합니다. 그림 3: '자동화 실행 (Execute automation)' 버튼를 선택하여 자동화 런북 찾기

3. 중앙의 자동화 런북에서 "AWSSupport-TroubleshootEKSWorkerNode"을 검색하고 선택한 뒤 하단에서 다음(Next)를 클릭합니다. 그림 4: AWSSupport-TroubleshootEKSWorkerNode 런북 검색

그림 5: AWSSupport-TroubleshootEKSWorkerNode 런북 탐색 결과

그림 6: AWSSupport-TroubleshootEKSWorkerNode 런북 선택 - '다음 (Next)' 버튼 클릭

4. 단순 실행 (Simple execution) 모드로 런북을 실행하며 입력 파라미터 섹션에서 진단 대상 EC2 워커 노드 선택하고 EKS 클러스터의 이름 (ClusterName)을 입력한 후 하단의 '실행 (Execute)' 버튼을 클릭합니다. 그림 7: 단순 실행 (Simple execution) 모드로 런북 실행

그림 8: 진단을 희망하는 EC2 워커 노드 선택, EKS 클러스터 이름 입력

그림 9: 정보 입력 완료 이후 '실행 (Execute)' 버튼을 클릭하여 런북 실행

5. 런북 자동화 도구가 실행을 마치면 EKS 클러스터 및 워커 노드에 대한 진단 작업 수행 결과를 확인합니다.

그림 10: 런북 자동화 도구 실행 시작

그림 11: 런북 실행 완료 후 마지막 단계 'TroubleshootWorkerNode'의 실행 결과를 확인

그림 12: 워커 노드 내 'kubelet' 데몬의 상태를 살펴보라는 메시지를 확인

그림 13: 런북 자동화 도구의 EKS 클러스터 진단 결과

그림 14: 런북 자동화 도구의 워커 노드 진단 결과 - 'kubelet' 데몬 상태 이상을 발견

6. 런북을 통해 확인한 문제의 원인을 해결하여 EC2 워커 노드가 클러스터에 다시 연결되는 것을 확인합니다. 그림 15: 문제가 발생한 EC2 인스턴스 (워커 노드)에 접속

그림 16: kubelet 데몬 상태 확인 - kubelet이 정지되었음을 확인

그림 17: kubelet 시작 후 다시 상태 확인 - kubelet이 다시 시작된 것을 확인

그림 18: kubelet 재시작 이후 EKS 클러스터에 워커 노드가 정상적으로 연결됨을 확인

만약, 위와 같이 AWS 지원 자동화 워크플로우 (Support Automation Workflow) 런북을 진행하였음에도 불구 이슈가 해결되지 않거나 이슈 해결에 보다 전문적인 도움이 필요한 경우 EKS 클러스터 및 EC2 워커 노드의 정보와 더불어 위와 같이 실행한 런북 실행 ID 및 실행 결과 등의 정보를 함께 공유해주시며 AWS Premium Support의 도움을 요청해 주시길 바랍니다.