하이브리드 노드 문제 해결

하이브리드 노드 문제 해결 (Troubleshooting hybrid nodes)

이 주제는 Amazon EKS Hybrid Nodes를 사용하면서 볼 수 있는 몇 가지 흔한 오류와 그 해결 방법을 다뤄요. 다른 문제 해결 정보는 Amazon EKS 클러스터 및 노드 문제 해결하기와 AWS re:Post의 Amazon EKS용 Knowledge Center 태그를 참고하세요. 문제를 해결할 수 없다면 AWS Support에 문의하세요.

출처: 문서

본문

SSM 자격 증명 공급자에 필요한 nodeadm 버전

하이브리드 노드의 자격 증명 공급자로 AWS Systems Manager(SSM)를 사용한다면, 새 설치 및 업그레이드에 nodeadm 버전 1.0.19 이상을 사용해야 해요. 이전 버전의 nodeadm은 오래된 SSM 서명 키를 포함하고 있어 nodeadm install과 nodeadm upgrade 중 다음 서명 확인 오류로 실패해요.

"msg":"Command failed","error":"failed to install ssm installer: validating ssm-setup-cli signature: Signature Verification Error: No matching signature"

이 오류를 해결하려면 nodeadm install 또는 nodeadm upgrade를 실행하기 전에 최신 버전의 nodeadm을 다운로드하세요.

`nodeadm debug`로 노드 문제 해결

하이브리드 노드에서 nodeadm debug 명령을 실행해 네트워킹 및 자격 증명 요구 사항이 충족되는지 검증할 수 있어요. nodeadm debug 명령에 대한 자세한 내용은 하이브리드 노드 nodeadm 참조를 참고하세요.

cluster insights로 하이브리드 노드의 문제 감지

Amazon EKS cluster insights에는 클러스터의 EKS Hybrid Nodes 구성에서 흔한 문제를 감지하는 insight 검사가 포함돼 있어요. AWS Management Console, AWS CLI, AWS SDK에서 모든 insight 검사 결과를 볼 수 있어요. cluster insights에 대한 자세한 내용은 cluster insights로 Kubernetes 버전 업그레이드 준비 및 잘못된 구성 문제 해결하기를 참고하세요.

하이브리드 노드 설치 문제 해결

다음 문제 해결 주제는 nodeadm install 명령으로 호스트에 하이브리드 노드 종속성을 설치하는 것과 관련돼요.

nodeadm 명령 실패 must run as root

nodeadm install 명령은 호스트에서 root 또는 sudo 권한이 있는 사용자로 실행해야 해요. root 또는 sudo 권한이 없는 사용자로 nodeadm install을 실행하면 nodeadm 출력에 다음 오류가 표시돼요.

"msg":"Command failed","error":"must run as root"

종속성에 연결할 수 없음

nodeadm install 명령은 하이브리드 노드에 필요한 종속성을 설치해요. 하이브리드 노드 종속성에는 containerd, kubelet, kubectl, AWS SSM 또는 AWS IAM Roles Anywhere 구성 요소가 포함돼요. nodeadm install을 실행하는 위치에서 이러한 종속성을 다운로드할 수 있는 액세스 권한이 있어야 해요. 액세스해야 하는 위치 목록에 대한 자세한 내용은 하이브리드 노드용 네트워킹 준비하기를 참고하세요. 액세스 권한이 없으면 nodeadm install 출력에 다음과 유사한 오류가 표시돼요.

"msg":"Command failed","error":"failed reading file from url: ...: max retries achieved for http request"

패키지 관리자 업데이트 실패

nodeadm install 명령은 하이브리드 노드 종속성을 설치하기 전에 apt update 또는 yum update 또는 dnf update를 실행해요. 이 단계가 성공하지 않으면 다음과 유사한 오류가 표시될 수 있어요. 이를 해결하려면 nodeadm install을 실행하기 전에 apt update 또는 yum update 또는 dnf update를 실행하거나, nodeadm install을 다시 실행할 수 있어요.

failed to run update using package manager

시간 초과 또는 컨텍스트 마감 초과 (Timeout or context deadline exceeded)

nodeadm install을 실행할 때 설치 프로세스의 여러 단계에서 시간 초과 또는 컨텍스트 마감 초과를 나타내는 오류가 표시된다면, 느린 연결로 인해 하이브리드 노드 종속성이 시간 초과 전에 설치되지 못하고 있을 수 있어요. 이 문제를 해결하려면 nodeadm의 --timeout 플래그를 사용해 종속성 다운로드의 시간 초과 기간을 늘릴 수 있어요.

nodeadm install K8S_VERSION --credential-provider CREDS_PROVIDER --timeout 20m0s

하이브리드 노드 연결 문제 해결

이 섹션의 문제 해결 주제는 nodeadm init 명령으로 하이브리드 노드를 EKS 클러스터에 연결하는 프로세스와 관련돼요.

작업 오류 또는 지원되지 않는 구성표 (Operation errors or unsupported scheme)

nodeadm init을 실행할 때 operation error 또는 unsupported scheme 관련 오류가 표시되면 nodeConfig.yaml이 제대로 형식화되어 nodeadm에 전달되는지 확인하세요. nodeConfig.yaml의 형식과 옵션에 대한 자세한 내용은 하이브리드 노드 nodeadm 참조를 참고하세요.

"msg":"Command failed","error":"operation error ec2imds: GetRegion, request canceled, context deadline exceeded"

하이브리드 노드 IAM 역할에 eks:DescribeCluster 작업 권한 없음

nodeadm init을 실행하면 nodeadm이 EKS DescribeCluster 작업을 호출해 EKS 클러스터에 대한 정보를 수집하려 해요. 하이브리드 노드 IAM 역할에 eks:DescribeCluster 작업에 대한 권한이 없으면 nodeadm init을 실행할 때 nodeadm에 전달하는 노드 구성에 Kubernetes API 엔드포인트, 클러스터 CA 번들, 서비스 IPv4 CIDR을 전달해야 해요. 하이브리드 노드 IAM 역할에 필요한 권한에 대한 자세한 내용은 하이브리드 노드용 자격 증명 준비하기를 참고하세요.

"msg":"Command failed","error":"operation error EKS: DescribeCluster, https response error StatusCode: 403 ... AccessDeniedException"

하이브리드 노드 IAM 역할에 eks:ListAccessEntries 작업 권한 없음

nodeadm init을 실행하면 nodeadm이 EKS ListAccessEntries 작업을 호출해 EKS 클러스터에 하이브리드 노드 IAM 역할과 연결된 HYBRID_LINUX 유형의 액세스 항목이 있는지 검증하려 해요. 하이브리드 노드 IAM 역할에 eks:ListAccessEntries 작업에 대한 권한이 없으면 nodeadm init 명령을 실행할 때 --skip cluster-access-validation 플래그를 전달해야 해요. 하이브리드 노드 IAM 역할에 필요한 권한에 대한 자세한 내용은 하이브리드 노드용 자격 증명 준비하기를 참고하세요.

"msg":"Command failed","error":"operation error EKS: ListAccessEntries, https response error StatusCode: 403 ... AccessDeniedException"

노드 IP가 원격 노드 네트워크 CIDR에 없음

nodeadm init을 실행할 때 노드의 IP 주소가 지정된 원격 노드 네트워크 CIDR 내에 없으면 오류가 발생할 수 있어요. 오류는 다음 예시와 유사해요.

node IP 10.18.0.1 is not in any of the remote network CIDR blocks [10.0.0.0/16 192.168.0.0/16]

이 예시는 IP 10.18.0.1의 노드가 원격 네트워크 CIDR 10.0.0.0/16과 192.168.0.0/16의 클러스터에 가입하려는 모습을 보여줘요. 10.18.0.1이 두 범위에 모두 속하지 않기 때문에 오류가 발생해요.

RemoteNodeNetworks가 모든 노드 IP 주소를 포함하도록 제대로 구성되었는지 확인하세요. 네트워킹 구성에 대한 자세한 내용은 하이브리드 노드용 네트워킹 준비하기를 참고하세요.

클러스터가 있는 리전에서 다음 명령을 실행해 RemoteNodeNetwork 구성을 확인하세요. 출력에 나열된 CIDR 블록이 노드의 IP 범위를 포함하고 오류 메시지에 나열된 CIDR 블록과 동일한지 확인하세요. 일치하지 않으면 nodeConfig.yaml의 클러스터 이름과 리전이 의도한 클러스터와 일치하는지 확인하세요.

aws eks describe-cluster --name CLUSTER_NAME --region REGION_NAME --query cluster.remoteNetworkConfig.remoteNodeNetworks

의도한 노드로 작업 중인지 확인하세요.

호스트 이름과 IP 주소가 클러스터에 등록하려는 노드와 일치하는지 확인해 의도한 노드에 있는지 확인하세요.
이 노드가 올바른 온프레미스 네트워크(클러스터 설정 중 RemoteNodeNetwork로 등록된 CIDR 범위의 네트워크)에 있는지 확인하세요.

노드 IP가 여전히 예상과 다르다면 다음을 확인하세요.

IAM Roles Anywhere를 사용한다면 kubelet이 IAM Roles Anywhere nodeName에 대한 DNS 조회를 수행하고 사용 가능한 경우 노드 이름과 연결된 IP를 사용해요. 노드에 대한 DNS 항목을 유지한다면, 이러한 항목이 원격 노드 네트워크 CIDR 내의 IP를 가리키는지 확인하세요.
노드에 여러 네트워크 인터페이스가 있다면 kubelet이 원격 노드 네트워크 CIDR 밖의 IP 주소를 가진 인터페이스를 기본으로 선택할 수 있어요. 다른 인터페이스를 사용하려면 nodeConfig.yaml에서 --node-ip kubelet 플래그로 해당 IP 주소를 지정하세요. 자세한 내용은 하이브리드 노드 nodeadm 참조를 참고하세요. 노드에서 다음 명령을 실행해 노드의 네트워크 인터페이스와 IP 주소를 볼 수 있어요.

ip addr show

하이브리드 노드가 EKS 클러스터에 표시되지 않음

nodeadm init을 실행하고 완료했지만 하이브리드 노드가 클러스터에 표시되지 않는다면, 하이브리드 노드와 EKS 컨트롤 플레인 사이의 네트워크 연결에 문제가 있거나, 필요한 보안 그룹 권한이 구성되지 않았거나, 하이브리드 노드 IAM 역할의 Kubernetes RBAC(Role-Based Access Control) 매핑이 없을 수 있어요. 다음 명령으로 kubelet 상태와 kubelet 로그를 확인해 디버깅을 시작할 수 있어요. 클러스터 가입에 실패한 하이브리드 노드에서 다음 명령을 실행하세요.

systemctl status kubelet

journalctl -u kubelet -f

클러스터와 통신할 수 없음

하이브리드 노드가 클러스터 컨트롤 플레인과 통신할 수 없다면 다음 유사한 로그가 표시될 수 있어요.

"Failed to ensure lease exists, will retry" err="Get ..."

"Unable to register node with API server" err="Post ..."

Failed to contact API server when waiting for CSINode publishing ... dial tcp : i/o timeout

이 메시지가 표시되면 하이브리드 노드용 네트워킹 준비하기에 상세히 설명된 하이브리드 노드 요구 사항을 충족하는지 다음을 확인하세요.

EKS 클러스터에 전달된 VPC에 온프레미스 노드와 선택적으로 Pod CIDR에 대한 Transit Gateway(TGW) 또는 Virtual Private Gateway(VGW) 라우트가 있는지 확인하세요.
EKS 클러스터용 추가 보안 그룹에 온프레미스 노드 CIDR과 선택적으로 Pod CIDR에 대한 인바운드 규칙이 있는지 확인하세요.
온프레미스 라우터가 EKS 컨트롤 플레인과의 트래픽을 허용하도록 구성되었는지 확인하세요.

Unauthorized

하이브리드 노드가 EKS 컨트롤 플레인과 통신할 수 있었지만 등록하지 못했다면 다음 유사한 로그가 표시될 수 있어요. 아래 로그 메시지의 핵심 차이점은 Unauthorized 오류라는 점을 기억하세요. 이는 노드가 필요한 권한이 없어 작업을 수행하지 못했음을 나타내요.

"Failed to ensure lease exists, will retry" err="Unauthorized"

"Unable to register node with API server" err="Unauthorized"

Failed to contact API server when waiting for CSINode publishing: Unauthorized

이 메시지가 표시되면 하이브리드 노드용 자격 증명 준비하기 및 하이브리드 노드용 클러스터 액세스 준비하기에 상세히 설명된 하이브리드 노드 요구 사항을 충족하는지 다음을 확인하세요.

하이브리드 노드의 ID가 예상한 하이브리드 노드 IAM 역할과 일치하는지 확인하세요. 하이브리드 노드에서 sudo aws sts get-caller-identity를 실행해 확인할 수 있어요.
하이브리드 노드 IAM 역할에 필요한 권한이 있는지 확인하세요.
클러스터에 하이브리드 노드 IAM 역할에 대한 EKS 액세스 항목이 있는지, 또는 aws-auth ConfigMap에 하이브리드 노드 IAM 역할에 대한 항목이 있는지 확인하세요. EKS 액세스 항목을 사용한다면 하이브리드 노드 IAM 역할에 대한 액세스 항목에 HYBRID_LINUX 액세스 유형이 있는지 확인하세요. aws-auth ConfigMap을 사용한다면 하이브리드 노드 IAM 역할에 대한 항목이 하이브리드 노드용 클러스터 액세스 준비하기에 상세히 설명된 요구 사항과 형식을 충족하는지 확인하세요.

하이브리드 노드가 EKS 클러스터에 등록되었지만 `Not Ready` 상태 표시

하이브리드 노드가 EKS 클러스터에 성공적으로 등록되었지만 Not Ready 상태를 표시한다면, 가장 먼저 확인할 것은 CNI(Container Networking Interface) 상태예요. CNI를 설치하지 않았다면 하이브리드 노드가 Not Ready 상태인 것은 예상된 동작이에요. CNI가 설치되고 성공적으로 실행되면 노드가 Ready 상태로 업데이트돼요. CNI를 설치하려 시도했지만 성공적으로 실행되지 않았다면 이 페이지의 하이브리드 노드 CNI 문제 해결하기를 참고하세요.

CSR(Certificate Signing Requests)이 Pending 상태로 고정

하이브리드 노드를 EKS 클러스터에 연결한 후 하이브리드 노드에 대해 Pending 상태의 CSR이 표시된다면, 하이브리드 노드가 자동 승인 요구 사항을 충족하지 못한 거예요. 하이브리드 노드의 CSR은 eks.amazonaws.com/compute-type: hybrid 레이블이 있는 노드가 만든 경우, 그리고 CSR에 다음 SAN(Subject Alternative Names)이 있는 경우 자동으로 승인되고 발급돼요: 노드 이름과 동일한 DNS SAN이 하나 이상, 그리고 IP SAN이 원격 노드 네트워크 CIDR에 속해야 해요.

하이브리드 프로필이 이미 존재함

nodeadm 구성을 변경하고 새 구성으로 노드를 다시 등록하려 하면 하이브리드 프로필이 이미 존재하지만 내용이 변경되었다는 오류가 표시될 수 있어요. 구성 변경 사이에 nodeadm init을 실행하는 대신 nodeadm uninstall을 실행한 다음 nodeadm install과 nodeadm init을 실행하세요. 이렇게 하면 구성 변경과 함께 제대로 정리할 수 있어요.

"msg":"Command failed","error":"hybrid profile already exists at /etc/aws/hybrid/config but its contents do not align with the expected configuration"

하이브리드 노드가 프라이빗 API를 해석하지 못함

nodeadm init을 실행한 후 kubelet 로그에 no such host로 인해 EKS Kubernetes API 서버에 접촉하지 못하는 오류가 표시된다면, 온프레미스 네트워크 또는 호스트 수준에서 EKS Kubernetes API 엔드포인트의 DNS 항목을 변경해야 할 수 있어요. AWS Route53 문서의 VPC로 인바운드 DNS 쿼리 전달하기를 참고하세요.

Failed to contact API server when waiting for CSINode publishing: Get ... no such host

EKS 콘솔에서 하이브리드 노드를 볼 수 없음

하이브리드 노드를 등록했지만 EKS 콘솔에서 볼 수 없다면, 콘솔 보기에 사용 중인 IAM 보안 주체의 권한을 확인하세요. 사용 중인 IAM 보안 주체는 콘솔에서 리소스를 보기 위한 특정 최소 IAM 및 Kubernetes 권한이 있어야 해요. 자세한 내용은 AWS Management Console에서 Kubernetes 리소스 보기를 참고하세요.

하이브리드 노드 실행 문제 해결

하이브리드 노드가 EKS 클러스터에 등록되고 Ready 상태였다가 Not Ready 상태로 전환되었다면, CPU, 메모리, 사용 가능한 디스크 공간 등 노드에 충분한 리소스가 없거나 노드가 EKS 컨트롤 플레인에서 연결 해제되는 등 다양한 문제가 불건전한 상태에 기여했을 수 있어요. 아래 단계로 노드를 문제 해결할 수 있고, 문제를 해결할 수 없다면 AWS Support에 문의하세요.

하이브리드 노드에서 nodeadm debug를 실행해 네트워킹 및 자격 증명 요구 사항이 충족되는지 검증하세요. nodeadm debug 명령에 대한 자세한 내용은 하이브리드 노드 nodeadm 참조를 참고하세요.

노드 상태 가져오기

kubectl get nodes -o wide

노드 조건 및 이벤트 확인

kubectl describe node NODE_NAME

Pod 상태 가져오기

kubectl get pods -A -o wide

Pod 조건 및 이벤트 확인

kubectl describe pod POD_NAME

Pod 로그 확인

kubectl logs POD_NAME

kubelet 로그 확인

systemctl status kubelet

journalctl -u kubelet -f

Pod liveness 프로브 실패 또는 웹훅이 작동하지 않음

하이브리드 노드에서 실행 중인 애플리케이션, 애드온 또는 웹훅이 제대로 시작되지 않는다면, Pod와의 통신을 차단하는 네트워킹 문제가 있을 수 있어요. EKS 컨트롤 플레인이 하이브리드 노드에서 실행되는 웹훅에 접촉하려면, EKS 클러스터를 원격 Pod 네트워크로 구성하고 VPC 라우팅 테이블에 온프레미스 Pod CIDR에 대한 라우트를 대상이 Transit Gateway(TGW), virtual private gateway(VGW), 또는 VPC를 온프레미스 네트워크와 연결하는 데 사용하는 기타 게이트웨이로 구성해야 해요. 하이브리드 노드의 네트워킹 요구 사항에 대한 자세한 내용은 하이브리드 노드용 네트워킹 준비하기를 참고하세요. 또한 온프레미스 방화벽에서 이 트래픽을 허용하고 라우터가 Pod로 제대로 라우팅할 수 있는지 확인해야 해요. 하이브리드 노드에서 웹훅을 실행하기 위한 요구 사항은 하이브리드 노드용 웹훅 구성하기를 참고하세요.

이 시나리오의 흔한 Pod 로그 메시지는 아래와 같으며, 여기서 ip-address는 Kubernetes 서비스의 Cluster IP예요.

dial tcp :443: connect: no route to host

kubectl logs 또는 kubectl exec 명령이 작동하지 않음 (kubelet API 명령)

kubectl attach, kubectl cp, kubectl exec, kubectl logs, kubectl port-forward 명령이 시간 초과되는 동안 다른 kubectl 명령은 성공한다면, 문제는 원격 네트워크 구성과 관련될 가능성이 높아요. 이러한 명령은 클러스터를 통해 노드의 kubelet 엔드포인트에 연결해요. 자세한 내용은 kubelet 엔드포인트를 참고하세요.

노드 IP와 Pod IP가 클러스터에 구성된 원격 노드 네트워크 및 원격 Pod 네트워크 CIDR 내에 있는지 확인하세요. 아래 명령으로 IP 할당을 검사해요.

kubectl get nodes -o wide

kubectl get pods -A -o wide

이 IP들을 구성된 원격 네트워크 CIDR과 비교해 올바른 라우팅을 확인하세요. 네트워크 구성 요구 사항은 하이브리드 노드용 네트워킹 준비하기를 참고하세요.

하이브리드 노드 CNI 문제 해결

하이브리드 노드로 Cilium이나 Calico를 처음 시작할 때 문제가 발생한다면, 대부분 하이브리드 노드 사이 또는 하이브리드 노드에서 실행되는 CNI Pod와 EKS 컨트롤 플레인 사이의 네트워킹 문제 때문이에요. 환경이 하이브리드 노드용 네트워킹 준비하기의 요구 사항을 충족하는지 확인하세요. 문제를 부분으로 나누는 것이 유용해요.

EKS 클러스터 구성

RemoteNodeNetwork 및 RemotePodNetwork 구성이 올바른가요?

VPC 구성

VPC 라우팅 테이블에 RemoteNodeNetwork 및 RemotePodNetwork에 대한 라우트가 Transit Gateway 또는 Virtual Private Gateway를 대상으로 있나요?

보안 그룹 구성

RemoteNodeNetwork 및 RemotePodNetwork에 대한 인바운드 및 아웃바운드 규칙이 있나요?

온프레미스 네트워크

EKS 컨트롤 플레인과 하이브리드 노드 및 하이브리드 노드에서 실행되는 Pod로/로부터 라우트와 액세스가 있나요?

CNI 구성

오버레이 네트워크를 사용한다면 웹훅을 사용하는 경우 CNI의 IP 풀 구성이 EKS 클러스터에 구성된 RemotePodNetwork와 일치하나요?

CNI가 설치되지 않았는데 하이브리드 노드가 Ready 상태

하이브리드 노드가 Ready 상태를 표시하지만 클러스터에 CNI를 설치하지 않았다면, 하이브리드 노드에 오래된 CNI 아티팩트가 있을 수 있어요. 기본적으로 Helm 같은 도구로 Cilium과 Calico를 제거해도 물리적 또는 가상 머신에서 디스크의 리소스는 제거되지 않아요. 또한 이러한 CNI의 CRD(Custom Resource Definitions)가 이전 설치에서 여전히 클러스터에 존재할 수 있어요. 자세한 내용은 하이브리드 노드용 CNI 구성하기의 Cilium 삭제 및 Calico 삭제 섹션을 참고하세요.

Cilium 문제 해결

하이브리드 노드에서 Cilium을 실행하는 데 문제가 있다면 Cilium 문서의 문제 해결 단계를 참고하세요. 아래 섹션은 하이브리드 노드에 Cilium을 배포할 때 고유할 수 있는 문제를 다뤄요.

Cilium이 시작되지 않음

각 하이브리드 노드에서 실행되는 Cilium 에이전트가 시작되지 않는다면 오류에 대해 Cilium 에이전트 Pod의 로그를 확인하세요. Cilium 에이전트는 시작하려면 EKS Kubernetes API 엔드포인트에 대한 연결이 필요해요. 이 연결이 올바르게 구성되지 않으면 Cilium 에이전트 시작이 실패해요. 이 경우 Cilium 에이전트 Pod 로그에 다음과 유사한 로그 메시지가 표시돼요.

msg="Unable to contact k8s api-server"
level=fatal msg="failed to start: Get \"https://:443/api/v1/namespaces/kube-system\": dial tcp :443: i/o timeout"

Cilium 에이전트는 호스트 네트워크에서 실행돼요. EKS 클러스터가 Cilium 연결을 위해 RemoteNodeNetwork로 구성되어야 해요. EKS 클러스터용 추가 보안 그룹에 RemoteNodeNetwork에 대한 인바운드 규칙이 있고, VPC에 RemoteNodeNetwork에 대한 라우트가 있으며, 온프레미스 네트워크가 EKS 컨트롤 플레인에 대한 연결을 허용하도록 올바르게 구성되었는지 확인하세요.

Cilium operator가 실행 중인데 일부 Cilium 에이전트만 실행 중이라면, 클러스터의 모든 노드에 할당할 수 있는 Pod IP가 충분한지 확인하세요. Cilium 구성에서 clusterPoolIPv4PodCIDRList로 cluster pool IPAM을 사용할 때 할당 가능한 Pod CIDR의 크기를 구성해요. 노드별 CIDR 크기는 Cilium 구성의 clusterPoolIPv4MaskSize 설정으로 구성해요. 자세한 내용은 Cilium 문서의 클러스터 풀 확장하기를 참고하세요.

Cilium BGP가 작동하지 않음

Cilium BGP Control Plane을 사용해 Pod 또는 서비스 주소를 온프레미스 네트워크에 광고한다면, 다음 Cilium CLI 명령으로 BGP가 리소스에 라우트를 광고하는지 확인할 수 있어요. Cilium CLI 설치 단계는 Cilium 문서의 Cilium CLI 설치하기를 참고하세요.

BGP가 올바르게 작동한다면 출력에서 하이브리드 노드의 Session State가 established인 것을 볼 수 있어야 해요. 환경의 Local AS, Peer AS, Peer Address에 대한 올바른 값을 식별하려면 네트워킹 팀과 협력해야 할 수도 있어요.

cilium bgp peers

cilium bgp routes

Cilium BGP를 사용해 LoadBalancer 유형의 Service IP를 광고한다면, CiliumLoadBalancerIPPool과 Service에 동일한 레이블이 있어야 하며, 이 레이블을 CiliumBGPAdvertisement의 선택자에 사용해야 해요. 예시는 아래와 같아요. 참고로, Cilium BGP를 사용해 LoadBalancer 유형의 Service IP를 광고한다면 Cilium 에이전트 재시작 중 BGP 라우트가 중단될 수 있어요. 자세한 내용은 Cilium 문서의 장애 시나리오를 참고하세요.

Service

kind: Service
apiVersion: v1
metadata:
  name: guestbook
  labels:
    app: guestbook
spec:
  ports:
  - port: 3000
    targetPort: http-server
  selector:
    app: guestbook
  type: LoadBalancer

CiliumLoadBalancerIPPool

apiVersion: cilium.io/v2alpha1
kind: CiliumLoadBalancerIPPool
metadata:
  name: guestbook-pool
  labels:
    app: guestbook
spec:
  blocks:
  - cidr:
  serviceSelector:
    matchExpressions:
      - { key: app, operator: In, values: [ guestbook ] }

CiliumBGPAdvertisement

apiVersion: cilium.io/v2alpha1
kind: CiliumBGPAdvertisement
metadata:
  name: bgp-advertisements-guestbook
  labels:
    advertise: bgp
spec:
  advertisements:
    - advertisementType: "Service"
      service:
        addresses:
          - ExternalIP
          - LoadBalancerIP
      selector:
        matchExpressions:
          - { key: app, operator: In, values: [ guestbook ] }

Calico 문제 해결

하이브리드 노드에서 Calico를 실행하는 데 문제가 있다면 Calico 문서의 문제 해결 단계를 참고하세요. 아래 섹션은 하이브리드 노드에 Calico를 배포할 때 고유할 수 있는 문제를 다뤄요.

아래 표는 Calico 구성 요소와 기본적으로 노드 또는 Pod 네트워크에서 실행되는지 요약해요. 아웃바운드 Pod 트래픽에 NAT를 사용하도록 Calico를 구성했다면, 온프레미스 네트워크가 온프레미스 노드 CIDR로 트래픽을 라우팅하도록 구성되고, VPC 라우팅 테이블이 transit gateway(TGW) 또는 virtual private gateway(VGW)를 대상으로 온프레미스 노드 CIDR에 대한 라우트로 구성되어야 해요. 아웃바운드 Pod 트래픽에 NAT를 사용하도록 Calico를 구성하지 않는다면, 온프레미스 네트워크가 온프레미스 Pod CIDR로 트래픽을 라우팅하도록 구성되고, VPC 라우팅 테이블이 transit gateway(TGW) 또는 virtual private gateway(VGW)를 대상으로 온프레미스 Pod CIDR에 대한 라우트로 구성되어야 해요.

구성 요소	네트워크
Calico API server	Node
Calico Controllers for Kubernetes	Pod
Calico node agent	Node
Calico `typha`	Node
Calico CSI node driver	Pod
Calico operator	Node

Calico 리소스가 cordoned된 노드에 스케줄링 또는 실행 중

DaemonSet으로 실행되지 않는 Calico 리소스는 기본적으로 스케줄링이나 Pod 실행에 준비되지 않은 cordoned 노드에도 스케줄링될 수 있는 유연한 톨러레이션을 가져요. operator 설치를 변경해 다음을 포함하면 비-DaemonSet Calico 리소스의 톨러레이션을 더 엄격하게 만들 수 있어요.

installation:
  ...
  controlPlaneTolerations:
  - effect: NoExecute
    key: node.kubernetes.io/unreachable
    operator: Exists
    tolerationSeconds: 300
  - effect: NoExecute
    key: node.kubernetes.io/not-ready
    operator: Exists
    tolerationSeconds: 300
  calicoKubeControllersDeployment:
    spec:
      template:
        spec:
          tolerations:
          - effect: NoExecute
            key: node.kubernetes.io/unreachable
            operator: Exists
            tolerationSeconds: 300
          - effect: NoExecute
            key: node.kubernetes.io/not-ready
            operator: Exists
            tolerationSeconds: 300
  typhaDeployment:
    spec:
      template:
        spec:
          tolerations:
          - effect: NoExecute
            key: node.kubernetes.io/unreachable
            operator: Exists
            tolerationSeconds: 300
          - effect: NoExecute
            key: node.kubernetes.io/not-ready
            operator: Exists
            tolerationSeconds: 300

자격 증명 문제 해결

AWS SSM 하이브리드 활성화와 AWS IAM Roles Anywhere 모두에 대해, 하이브리드 노드에서 다음 명령을 실행해 하이브리드 노드 IAM 역할의 자격 증명이 하이브리드 노드에 올바르게 구성되었는지 검증할 수 있어요. 노드 이름과 하이브리드 노드 IAM 역할 이름이 예상한 것인지 확인하세요.

sudo aws sts get-caller-identity

{
    "UserId": "ABCDEFGHIJKLM12345678910:",
    "Account": "",
    "Arn": "arn:aws:sts:::assumed-role/"
}

AWS Systems Manager (SSM) 문제 해결

하이브리드 노드 자격 증명에 AWS SSM 하이브리드 활성화를 사용한다면, nodeadm이 하이브리드 노드에 설치하는 다음 SSM 디렉토리와 아티팩트를 알아두세요. SSM 에이전트에 대한 자세한 내용은 AWS Systems Manager 사용 설명서의 SSM 에이전트 사용하기를 참고하세요.

설명	위치
SSM agent	Ubuntu - `/snap/amazon-ssm-agent/current/amazon-ssm-agent` / RHEL & AL2023 - `/usr/bin/amazon-ssm-agent`
SSM agent logs	`/var/log/amazon/ssm`
AWS credentials	`/root/.aws/credentials`
SSM Setup CLI	`/opt/ssm/ssm-setup-cli`

SSM 에이전트 재시작

일부 문제는 SSM 에이전트를 재시작하면 해결될 수 있어요. 아래 명령으로 재시작할 수 있어요.

AL2023 및 기타 운영 체제

systemctl restart amazon-ssm-agent

Ubuntu

systemctl restart snap.amazon-ssm-agent.amazon-ssm-agent

SSM 엔드포인트에 대한 연결 확인

하이브리드 노드에서 SSM 엔드포인트에 연결할 수 있는지 확인하세요. SSM 엔드포인트 목록은 AWS Systems Manager 엔드포인트 및 할당량을 참고하세요. 아래 명령의 us-west-2를 AWS SSM 하이브리드 활성화의 AWS 리전으로 바꾸세요.

ping ssm.us-west-2.amazonaws.com

등록된 SSM 인스턴스의 연결 상태 보기

다음 AWS CLI 명령으로 SSM 하이브리드 활성화에 등록된 인스턴스의 연결 상태를 확인할 수 있어요. machine ID를 인스턴스의 machine ID로 바꾸세요.

aws ssm get-connection-status --target mi-012345678abcdefgh

SSM Setup CLI 체크섬 불일치

nodeadm install을 실행할 때 ssm-setup-cli 체크섬 불일치 문제가 표시되면 호스트에 오래된 기존 SSM 설치가 없는지 확인하세요. 호스트에 오래된 SSM 설치가 있다면 이를 제거하고 nodeadm install을 다시 실행해 문제를 해결하세요.

Failed to perform agent-installation/on-prem registration: error while verifying installed ssm-setup-cli checksum: checksum mismatch with latest ssm-setup-cli.

SSM InvalidActivation

AWS SSM에 인스턴스를 등록할 때 오류가 표시되면 nodeConfig.yaml의 region, activationCode, activationId가 올바른지 확인하세요. EKS 클러스터의 AWS 리전은 SSM 하이브리드 활성화의 리전과 일치해야 해요. 이러한 값이 잘못 구성되면 다음 유사한 오류가 표시될 수 있어요.

ERROR Registration failed due to error registering the instance with AWS SSM. InvalidActivation

SSM ExpiredTokenException: 요청에 포함된 보안 토큰이 만료됨

SSM 에이전트가 자격 증명을 갱신할 수 없다면 ExpiredTokenException이 표시될 수 있어요. 이 시나리오에서 하이브리드 노드에서 SSM 엔드포인트에 연결할 수 있다면, 자격 증명 갱신을 강제하기 위해 SSM 에이전트를 재시작해야 할 수 있어요.

"msg":"Command failed","error":"operation error SSM: DescribeInstanceInformation, https response error StatusCode: 400, RequestID: eee03a9e-f7cc-470a-9647-73d47e4cf0be, api error ExpiredTokenException: The security token included in the request is expired"

register machine 명령 실행 시 SSM 오류

SSM에 머신을 등록할 때 오류가 표시되면 모든 SSM 종속성이 제대로 설치되었는지 확인하기 위해 nodeadm install을 다시 실행해야 할 수 있어요.

"error":"running register machine command: , error: fork/exec /opt/aws/ssm-setup-cli: no such file or directory"

SSM ActivationExpired

nodeadm init을 실행할 때 만료된 활성화로 인해 인스턴스를 SSM에 등록하는 오류가 표시되면, 새 SSM 하이브리드 활성화를 만들고 nodeConfig.yaml을 새 SSM 하이브리드 활성화의 activationCode와 activationId로 업데이트한 다음 nodeadm init을 다시 실행해야 해요.

"msg":"Command failed","error":"SSM activation expired. Please use a valid activation"

ERROR Registration failed due to error registering the instance with AWS SSM. ActivationExpired

SSM이 캐시된 자격 증명을 갱신하지 못함

캐시된 자격 증명을 갱신하지 못하는 오류가 표시되면 호스트에서 /root/.aws/credentials 파일이 삭제되었을 수 있어요. 먼저 SSM 하이브리드 활성화를 확인해 활성이고 하이브리드 노드가 활성화를 사용하도록 올바르게 구성되었는지 확인하세요. /var/log/amazon/ssm에서 SSM 에이전트 로그를 확인하고, SSM 쪽 문제를 해결한 후 nodeadm init 명령을 다시 실행하세요.

"Command failed","error":"operation error SSM: DescribeInstanceInformation, get identity: get credentials: failed to refresh cached credentials"

SSM 정리

호스트에서 SSM 에이전트를 제거하려면 다음 명령을 실행할 수 있어요.

dnf remove -y amazon-ssm-agent
sudo apt remove --purge amazon-ssm-agent
snap remove amazon-ssm-agent
rm -rf /var/lib/amazon/ssm/Vault/Store/RegistrationKey

AWS IAM Roles Anywhere 문제 해결

하이브리드 노드 자격 증명에 AWS IAM Roles Anywhere를 사용한다면, nodeadm이 하이브리드 노드에 설치하는 다음 디렉토리와 아티팩트를 알아두세요. IAM Roles Anywhere 문제 해결에 대한 자세한 내용은 AWS IAM Roles Anywhere 사용 설명서의 AWS IAM Roles Anywhere ID 및 액세스 문제 해결하기를 참고하세요.

설명	위치
IAM Roles Anywhere CLI	`/usr/local/bin/aws_signing_helper`
기본 인증서 위치 및 이름	`/etc/iam/pki/server.pem`
기본 키 위치 및 이름	`/etc/iam/pki/server.key`

IAM Roles Anywhere가 캐시된 자격 증명을 갱신하지 못함

캐시된 자격 증명을 갱신하지 못하는 오류가 표시되면 /etc/aws/hybrid/config의 내용을 검토하고 IAM Roles Anywhere가 nodeadm 구성에 올바르게 구성되었는지 확인하세요. /etc/iam/pki가 존재하는지 확인하세요. 각 노드는 고유한 인증서와 키를 가져야 해요. 기본적으로 자격 증명 공급자로 IAM Roles Anywhere를 사용할 때 nodeadm은 인증서 위치 및 이름으로 /etc/iam/pki/server.pem을, 개인 키로 /etc/iam/pki/server.key를 사용해요. 인증서와 키를 디렉토리에 넣기 전에 sudo mkdir -p /etc/iam/pki로 디렉토리를 만들어야 할 수 있어요. 아래 명령으로 인증서의 내용을 검증할 수 있어요.

openssl x509 -text -noout -in server.pem

open /etc/iam/pki/server.pem: no such file or directory
could not parse PEM data
Command failed {"error": "... get identity: get credentials: failed to refresh cached credentials, process provider error: error in credential_process: exit status 1"}

IAM Roles Anywhere이 sts:AssumeRole을 수행할 권한이 없음

IAM Roles Anywhere를 사용할 때 kubelet 로그에서 sts:AssumeRole 작업에 대한 액세스 거부 문제가 표시되면, 하이브리드 노드 IAM 역할의 신뢰 정책을 확인해 IAM Roles Anywhere 서비스 보안 주체가 하이브리드 노드 IAM 역할을 수임할 수 있도록 허용하는지 확인하세요. 또한 트러스트 앵커 ARN이 하이브리드 노드 IAM 역할 신뢰 정책에 올바르게 구성되었고, 하이브리드 노드 IAM 역할이 IAM Roles Anywhere 프로필에 추가되었는지 확인하세요.

could not get token: AccessDenied: User: ... is not authorized to perform: sts:AssumeRole on resource: ...

IAM Roles Anywhere이 roleSessionName을 설정할 권한이 없음

IAM Roles Anywhere를 사용할 때 kubelet 로그에서 roleSessionName 설정에 대한 액세스 거부 문제가 표시되면, IAM Roles Anywhere 프로필에 대해 acceptRoleSessionName을 true로 설정했는지 확인하세요.

AccessDeniedException: Not authorized to set roleSessionName

운영 체제 문제 해결

RHEL: Entitlement 또는 subscription manager 등록 실패

nodeadm install을 실행할 때 entitlement 등록 문제로 인해 하이브리드 노드 종속성 설치가 실패한다면, 호스트에 Red Hat 사용자 이름과 암호를 제대로 설정했는지 확인하세요.

This system is not registered with an entitlement server

Ubuntu: GLIBC를 찾을 수 없음

운영 체제로 Ubuntu를 사용하고 하이브리드 노드의 자격 증명 공급자로 IAM Roles Anywhere를 사용하는데 GLIBC를 찾을 수 없다는 문제가 표시되면, 해당 종속성을 수동으로 설치해 문제를 해결할 수 있어요.

GLIBC_2.32 not found (required by /usr/local/bin/aws_signing_helper)

종속성을 설치하려면 다음 명령을 실행하세요.

ldd --version
sudo apt update && apt install libc6
sudo apt install glibc-source

Bottlerocket

Bottlerocket admin 컨테이너를 활성화했다면 SSH로 접속해 상승된 권한으로 고급 디버깅 및 문제 해결을 수행할 수 있어요. 다음 섹션에는 Bottlerocket 호스트 컨텍스트에서 실행해야 하는 명령이 포함돼 있어요. admin 컨테이너에 들어가면 sheltie를 실행해 Bottlerocket 호스트에서 전체 루트 셸을 얻을 수 있어요.

sheltie

admin 컨테이너 셸에서 각 명령 앞에 sudo chroot /.bottlerocket/rootfs를 붙여 다음 섹션의 명령을 실행할 수도 있어요.

sudo chroot /.bottlerocket/rootfs

로그 수집에 logdog 사용

Bottlerocket은 문제 해결 목적으로 로그와 시스템 정보를 효율적으로 수집하는 logdog 유틸리티를 제공해요.

logdog

logdog 유틸리티는 Bottlerocket 호스트의 여러 위치에서 로그를 수집해 tarball로 결합해요. 기본적으로 tarball은 /var/log/support/bottlerocket-logs.tar.gz에 생성되며, 호스트 컨테이너에서 /.bottlerocket/support/bottlerocket-logs.tar.gz로 접근할 수 있어요.

journalctl로 시스템 로그 접근

kubelet, containerd 등 다양한 시스템 서비스의 상태를 확인하고 다음 명령으로 로그를 볼 수 있어요. -f 플래그는 로그를 실시간으로 따릅니다.

kubelet 서비스 상태 확인 및 kubelet 로그 검색을 위해 다음을 실행할 수 있어요.

systemctl status kubelet
journalctl -u kubelet -f

containerd 서비스 상태 확인 및 오케스트레이션된 containerd 인스턴스의 로그 검색을 위해 다음을 실행할 수 있어요.

systemctl status containerd
journalctl -u containerd -f

host-containerd 서비스 상태 확인 및 호스트 containerd 인스턴스의 로그 검색을 위해 다음을 실행할 수 있어요.

systemctl status host-containerd
journalctl -u host-containerd -f

부트스트랩 컨테이너와 호스트 컨테이너의 로그를 검색하려면 다음을 실행할 수 있어요.

journalctl _COMM=host-ctr -f

더 알아보기 (Learn more)

하이브리드 노드 nodeadm
하이브리드 노드 gateway
공식 문서

하이브리드 노드 문제 해결