**이 페이지 개선에 도움 주기**
이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **GitHub에서 이 페이지 편집** 링크를 선택합니다.
# 하이브리드 노드 문제 해결
이 주제에서는 Amazon EKS Hybrid Nodes를 사용하는 동안 발생할 수 있는 몇 가지 일반적 오류와 이를 해결하는 방법을 다룹니다. 기타 문제 해결 정보는 [Amazon EKS 클러스터 및 노드 관련 문제 해결](troubleshooting.md) 및 *AWS re:Post*의 [Amazon EKS용 지식 센터 태그](https://repost.aws/tags/knowledge-center/TA4IvCeWI1TE66q4jEj4Z9zg/amazon-elastic-kubernetes-service)를 참조하세요. 문제를 해결할 수 없는 경우 AWS Support에 문의하세요.
**`nodeadm debug`로 노드 문제 해결** 하이브리드 노드에서 `nodeadm debug` 명령을 실행하여 네트워킹 및 자격 증명 요구 사항이 충족되는지 확인할 수 있습니다. `nodeadm debug` 명령에 대한 자세한 내용은 [하이브리드 노드 `nodeadm` 참조](hybrid-nodes-nodeadm.md) 섹션을 참조하세요.
**클러스터 인사이트를 통해 하이브리드 노드 관련 문제 탐지** Amazon EKS 클러스터 인사이트에는 클러스터의 EKS 하이브리드 노드 구성과 관련된 일반적인 문제를 탐지하는 *인사이트 검사*가 포함됩니다. AWS Management Console, AWS CLI, AWS SDK에서 모든 인사이트 검사의 결과를 볼 수 있습니다. 클러스터 인사이트에 대한 자세한 내용은 [클러스터 인사이트를 사용한 Kubernetes 버전 업그레이드 준비 및 잘못된 구성 문제 해결](cluster-insights.md) 섹션을 참조하세요.
## 하이브리드 노드 설치 문제 해결
다음 문제 해결 주제는 `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`을 실행하는 위치에서 액세스할 수 있어야 합니다. 액세스가 가능해야 하는 위치 목록에 대한 자세한 내용은 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.md) 섹션을 참조하세요. 액세스 권한이 없는 경우 `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
```
**제한 시간 또는 컨텍스트 기한 초과**
`nodeadm install`을 실행할 때 설치 프로세스의 다양한 단계에서 제한 시간 또는 컨텍스트 기한을 초과했음을 나타내는 오류가 발생하는 경우, 연결이 느려져 제한 시간이 충족되기 전에 하이브리드 노드 종속성의 설치를 방해할 수 있습니다. 이러한 문제를 해결하려면 `nodeadm`에서 `--timeout` 플래그를 사용하여 종속성을 다운로드하는 제한 시간을 연장할 수 있습니다.
```
nodeadm install K8S_VERSION --credential-provider CREDS_PROVIDER --timeout 20m0s
```
## 하이브리드 노드 연결 문제 해결
이 섹션의 문제 해결 주제는 `nodeadm init` 명령을 사용하여 하이브리드 노드를 EKS 클러스터에 연결하는 프로세스와 관련이 있습니다.
**작업 오류 또는 지원되지 않는 체계**
`nodeadm init`를 실행할 때 `operation error` 또는 `unsupported scheme`와 관련된 오류가 표시되면 `nodeConfig.yaml`을 확인하여 형식이 올바르게 지정되어 있고 `nodeadm`에 전달되었는지 확인합니다. `nodeConfig.yaml` 형식 및 옵션에 대한 자세한 내용은 [하이브리드 노드 `nodeadm` 참조](hybrid-nodes-nodeadm.md) 섹션을 참조하세요.
```
"msg":"Command failed","error":"operation error ec2imds: GetRegion, request canceled, context deadline exceeded"
```
**`eks:DescribeCluster` 작업에 대한 하이브리드 노드 IAM 역할 권한 누락**
`nodeadm init`를 실행할 때 `nodeadm`은 EKS `DescribeCluster` 작업을 직접 호출하여 EKS 클러스터에 대한 정보를 수집하려고 시도합니다. 하이브리드 노드 IAM 역할에 `eks:DescribeCluster` 작업에 대한 권한이 없으면 `nodeadm init`를 실행할 때 `nodeadm`에 전달하는 노드 구성에서 Kubernetes API 엔드포인트, 클러스터 CA 번들, 서비스 IPv4 CIDR을 전달해야 합니다. 하이브리드 노드 IAM 역할에 필요한 권한에 대한 자세한 내용은 [하이브리드 노드에 대한 자격 증명 준비](hybrid-nodes-creds.md) 섹션을 참조하세요.
```
"msg":"Command failed","error":"operation error EKS: DescribeCluster, https response error StatusCode: 403 ... AccessDeniedException"
```
**`eks:ListAccessEntries` 작업에 대한 하이브리드 노드 IAM 역할 권한 누락**
`nodeadm init`를 실행할 때 `nodeadm`은 EKS `ListAccessEntries` 작업을 직접 호출하여 하이브리드 노드 IAM 역할에 연결된 `HYBRID_LINUX` 유형의 액세스 항목이 EKS 클러스터에 있는지 검증하려고 시도합니다. 하이브리드 노드 IAM 역할에 `eks:ListAccessEntries` 작업에 대한 권한이 없는 경우 `nodeadm init` 명령을 실행할 때 `--skip cluster-access-validation` 플래그를 전달해야 합니다. 하이브리드 노드 IAM 역할에 필요한 권한에 대한 자세한 내용은 [하이브리드 노드에 대한 자격 증명 준비](hybrid-nodes-creds.md) 섹션을 참조하세요.
```
"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]
```
이 예는 원격 네트워크 CIDR가 10.0.0.0/16 및 192.168.0.0/16인 클러스터에 조인하려고 시도하는 IP 주소가 10.18.0.1인 노드를 보여줍니다. 10.18.0.1이 두 범위 중 하나에 속하지 않기 때문에 오류가 발생합니다.
모든 노드 IP 주소를 포함하도록 `RemoteNodeNetworks`를 올바르게 구성했는지 확인합니다. 네트워킹 구성에 대한 자세한 내용은 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.md) 섹션을 참조하세요.
+ `RemoteNodeNetwork` 구성을 확인하려면 클러스터가 위치한 리전에서 다음 명령을 실행합니다. 출력에 나열된 CIDR 블록에 노드의 IP 범위가 포함되어 있고 오류 메시지에 나열된 CIDR 블록과 동일한지 확인합니다. 일치하지 않는 경우 `nodeConfig.yaml`의 클러스터 이름 및 리전이 의도한 클러스터와 일치하는지 확인합니다.
```
aws eks describe-cluster --name CLUSTER_NAME --region REGION_NAME --query cluster.remoteNetworkConfig.remoteNodeNetworks
```
+ 의도한 노드로 작업하고 있는지 확인합니다.
+ 호스트 이름 및 IP 주소가 클러스터에 등록하려는 주소와 일치하는지 확인하여 올바른 노드에 있는지 확인합니다.
+ 이 노드가 올바른 온프레미스 네트워크(클러스터 설정 중에 CIDR 범위가 `RemoteNodeNetwork`로 등록된 네트워크)에 있는지 확인합니다.
노드 IP가 여전히 예상과 다를 경우 다음을 확인하세요.
+ IAM Roles Anywhere를 사용하는 경우 `kubelet`은 IAM Roles Anywhere `nodeName`에서 DNS 조회를 수행하고 사용 가능한 경우 노드 이름과 연결된 IP를 사용합니다. 노드의 DNS 항목을 유지 관리하는 경우 이러한 항목이 원격 노드 네트워크 CIDR 내의 IP를 가리키는지 확인합니다.
+ 노드에 여러 네트워크 인터페이스가 있는 경우 `kubelet`이 원격 노드 네트워크 CIDR 외부의 IP 주소가 있는 인터페이스를 기본값으로 선택할 수도 있습니다. 다른 인터페이스를 사용하려면 `nodeConfig.yaml`의 `--node-ip` `kubelet` 플래그를 사용하여 IP 주소를 지정합니다. 자세한 내용은 [하이브리드 노드 `nodeadm` 참조](hybrid-nodes-nodeadm.md) 섹션을 참조하세요. 노드에서 다음 명령을 실행하여 노드의 네트워크 인터페이스 및 해당 IP 주소를 볼 수 있습니다.
```
ip addr show
```
**하이브리드 노드가 EKS 클러스터에 표시되지 않음**
`nodeadm init`를 실행했지만 하이브리드 노드가 클러스터에 표시되지 않는 경우 하이브리드 노드와 EKS 컨트롤 플레인 간의 네트워크 연결에 문제가 있거나, 필요한 보안 그룹 권한이 구성되지 않았거나, Kubernetes 역할 기반 액세스 제어(RBAC)에 필요한 하이브리드 노드 IAM 역할을 매핑하지 않았을 수 있습니다. 다음 명령으로 `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
```
이러한 메시지가 표시되면 다음을 확인하여 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.md)에 자세히 설명된 하이브리드 노드 요구 사항을 충족하는지 확인합니다.
+ EKS 클러스터에 전달된 VPC에 온프레미스 노드 및 선택적으로 포드 CIDR에 대한 전송 게이트웨이(TGW) 또는 가상 프라이빗 게이트웨이(VGW)에 대한 경로가 있는지 확인합니다.
+ EKS 클러스터에 대한 추가 보안 그룹에 온프레미스 노드 CIDR 및 선택적으로 포드 CIDR에 대한 인바운드 규칙이 있는지 확인합니다.
+ 온프레미스 라우터가 EKS 컨트롤 플레인으로의 트래픽과 EKS 컨트롤 플레인으로부터의 트래픽을 허용하도록 구성되어 있는지 확인합니다.
**권한이 없음**
하이브리드 노드가 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
```
이러한 메시지가 표시되면 다음을 확인하여 [하이브리드 노드에 대한 자격 증명 준비](hybrid-nodes-creds.md) 및 [하이브리드 노드에 대한 클러스터 액세스 준비](hybrid-nodes-cluster-prep.md)의 하이브리드 노드 요구 사항 세부 정보를 충족하는지 확인합니다.
+ 하이브리드 노드의 ID가 예상 하이브리드 노드 IAM 역할과 일치하는지 확인합니다. 하이브리드 노드에서 `sudo aws sts get-caller-identity`를 실행하여 이 작업을 수행할 수 있습니다.
+ 하이브리드 노드 IAM 역할에 필요한 권한이 있는지 확인합니다.
+ 클러스터에 하이브리드 노드 IAM 역할에 대한 EKS 액세스 항목이 있는지 확인하거나 `aws-auth` ConfigMap에 하이브리드 노드 IAM 역할에 대한 항목이 있는지 확인합니다. EKS 액세스 항목을 사용하는 경우 하이브리드 노드 IAM 역할에 대한 액세스 항목이 `HYBRID_LINUX` 액세스 유형인지 확인합니다. `aws-auth` ConfigMap을 사용하는 경우 하이브리드 노드 IAM 역할에 대한 항목이 [하이브리드 노드에 대한 클러스터 액세스 준비](hybrid-nodes-cluster-prep.md)에 설명된 요구 사항 및 형식을 충족하는지 확인합니다.
### EKS 클러스터에 등록되었지만 `Not Ready` 상태로 표시되는 하이브리드 노드
하이브리드 노드가 EKS 클러스터에 성공적으로 등록되었지만 하이브리드 노드에 `Not Ready` 상태가 표시되는 경우 가장 먼저 확인해야 할 것은 컨테이너 네트워킹 인터페이스(CNI) 상태입니다. CNI를 설치하지 않은 경우 하이브리드 노드의 상태가 `Not Ready`일 것으로 예상됩니다. CNI가 성공적으로 설치되고 실행되면 노드가 `Ready` 상태로 전환됩니다. CNI를 설치하려고 했지만 성공적으로 실행되지 않는 경우 이 페이지의 [하이브리드 노드 CNI 문제 해결](#hybrid-nodes-troubleshooting-cni) 섹션을 참조하세요.
**인증서 서명 요청(CSR) 보류 중**
하이브리드 노드를 EKS 클러스터에 연결한 후 하이브리드 노드에 대해 보류 중인 CSR이 있는 경우 하이브리드 노드가 자동 승인 요구 사항을 충족하지 않습니다. 하이브리드 노드에 대한 CSR은 `eks.amazonaws.com/compute-type: hybrid` 레이블이 있는 노드에서 하이브리드 노드용 CSR을 생성하고, CSR에 다음과 같은 주제 대체 이름(SAN)이 포함된 경우 자동으로 승인 및 발급됩니다. 노드 이름과 동일한 DNS SAN이 1개 이상이며 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`를 실행한 후 `no such host`가 있어 `kubelet` 로그에 EKS Kubernetes API 서버에 연결하지 못하는 오류가 표시되는 경우 온프레미스 네트워크 또는 호스트 수준에서 EKS Kubernetes API 엔드포인트의 DNS 항목을 변경해야 할 수 있습니다. *AWS Route53 설명서*의 [Forwarding inbound DNS queries to your VPC](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-forwarding-inbound-queries.html)를 참조하세요.
```
Failed to contact API server when waiting for CSINode publishing: Get ... no such host
```
**EKS 콘솔에서 하이브리드 노드를 볼 수 없음**
하이브리드 노드를 등록했지만 EKS 콘솔에서 볼 수 없는 경우 콘솔을 보는 데 사용 중인 IAM 보안 주체의 권한을 확인합니다. 사용 중인 IAM 보안 주체는 콘솔에서 리소스를 볼 수 있는 특정 최소 IAM 및 Kubernetes 권한이 있어야 합니다. 자세한 내용은 [AWS Management Console에서 Kubernetes 리소스 보기](view-kubernetes-resources.md) 섹션을 참조하세요.
## 하이브리드 노드 실행 문제 해결
EKS 클러스터에 등록된 하이브리드 노드가 `Ready` 상태였다가 `Not Ready` 상태로 전환된 경우 CPU, 메모리 또는 사용 가능한 디스크 공간에 대한 리소스가 부족하거나 노드가 EKS 컨트롤 플레인에서 연결 해제되는 등 상태가 비정상일 수 있는 다양한 문제가 있습니다. 아래 단계를 사용하여 노드 문제를 해결할 수 있으며, 문제를 해결할 수 없는 경우 AWS Support에 문의하세요.
하이브리드 노드에서 `nodeadm debug`를 실행하여 네트워킹 및 자격 증명 요구 사항이 충족되는지 확인합니다. `nodeadm debug` 명령에 대한 자세한 내용은 [하이브리드 노드 `nodeadm` 참조](hybrid-nodes-nodeadm.md) 섹션을 참조하세요.
**노드 상태 가져오기**
```
kubectl get nodes -o wide
```
**노드 조건 및 이벤트 확인**
```
kubectl describe node NODE_NAME
```
**포드 상태 가져오기**
```
kubectl get pods -A -o wide
```
**포드 조건 및 이벤트 확인**
```
kubectl describe pod POD_NAME
```
**포드 로그 확인**
```
kubectl logs POD_NAME
```
**`kubectl` 로그 확인**
```
systemctl status kubelet
```
```
journalctl -u kubelet -f
```
**포드 활성 프로브가 실패하거나 웹후크가 작동하지 않음**
하이브리드 노드에서 실행되는 애플리케이션, 추가 기능 또는 웹후크가 제대로 시작되지 않는 경우 포드에 대한 통신을 차단하는 네트워킹 문제가 있을 수 있습니다. EKS 컨트롤 플레인이 하이브리드 노드에서 실행되는 웹후크와 접촉하려면 원격 포드 네트워크로 EKS 클러스터를 구성하고 전송 게이트웨이(TGW), 가상 프라이빗 게이트웨이(VPW) 또는 VPC를 온프레미스 네트워크와 연결하는 데 사용하는 기타 게이트웨이를 대상으로 하는 VPC 라우팅 테이블의 온프레미스 포드 CIDR에 대한 경로가 있어야 합니다. 하이브리드 노드의 네트워킹 요구 사항에 대한 자세한 내용은 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.md) 섹션을 참조하세요. 또한 온프레미스 방화벽에서 이 트래픽을 허용하고 라우터가 포드로 올바르게 라우팅될 수 있도록 해야 합니다. 하이브리드 노드에서의 웹후크 실행 요구 사항에 대한 자세한 내용은 [하이브리드 노드용 웹후크 구성](hybrid-nodes-webhooks.md) 섹션을 참조하세요.
이 시나리오에 대한 일반적인 포드 로그 메시지는 아래에 나와 있습니다. 여기서 ip-address는 Kubernetes 서비스의 클러스터 IP입니다.
```
dial tcp :443: connect: no route to host
```
**`kubectl logs` 또는 `kubectl exec` 명령이 작동하지 않음(`kubelet` API 명령)**
다른 `kubectl` 명령은 성공하지만 `kubectl attach`, `kubectl cp`, `kubectl exec`, `kubectl logs` 또는 `kubectl port-forward` 명령이 제한 시간을 초과하면 원격 네트워크 구성과 관련된 문제일 수 있습니다. 이러한 명령은 클러스터를 통해 노드의 `kubelet` 엔드포인트에 연결됩니다. 자세한 내용은 [`kubelet` 엔드포인트](hybrid-nodes-concepts-kubernetes.md#hybrid-nodes-concepts-k8s-kubelet-api)을 참조하세요.
노드 IP 및 포드 IP가 클러스터에 대해 구성된 원격 노드 네트워크 및 원격 포드 네트워크 CIDR 내에 속하는지 확인합니다. 아래 명령을 사용하여 IP 할당을 검사합니다.
```
kubectl get nodes -o wide
```
```
kubectl get pods -A -o wide
```
이러한 IP를 구성된 원격 네트워크 CIDR과 비교하여 적절한 라우팅을 보장합니다. 네트워크 구성 요구 사항에 대한 자세한 내용은 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.md) 섹션을 참조하세요.
## 하이브리드 노드 CNI 문제 해결
하이브리드 노드로 Cilium 또는 Calico를 처음 시작하는 데 문제가 발생하는 경우 하이브리드 노드 또는 하이브리드 노드에서 실행되는 CNI 포드와 EKS 컨트롤 플레인 간의 네트워킹 문제로 인해 가장 자주 발생합니다. 환경이 하이브리드 노드용 네트워킹 준비의 요구 사항을 충족하는지 확인합니다. 문제를 세분화하면 도움이 됩니다.
EKS 클러스터 구성
RemoteNodeNetwork 및 RemotePodNetwork 구성이 정확합니까?
VPC 구성
전송 게이트웨이 또는 가상 프라이빗 게이트웨이가 대상인 VPC 라우팅 테이블에 RemoteNodeNetwork 및 RemotePodNetwork에 대한 경로가 있습니까?
보안 그룹 구성
RemoteNodeNetwork 및 RemotePodNetwork에 대한 인바운드 및 아웃바운드 규칙이 있습니까?
온프레미스 네트워크
EKS 컨트롤 플레인과 하이브리드 노드 및 하이브리드 노드에서 실행되는 포드 간에 경로 및 액세스 권한이 있습니까?
CNI 구성
오버레이 네트워크를 사용하는 경우 웹후크를 사용할 때 CNI의 IP 풀 구성이 EKS 클러스터에 대해 구성된 RemotePodNetwork와 일치합니까?
**하이브리드 노드에 CNI가 설치되지 않고 `Ready` 상태임**
하이브리드 노드에 `Ready` 상태가 표시되지만 클러스터에 CNI를 설치하지 않은 경우 하이브리드 노드에 이전 CNI 아티팩트가 있을 수 있습니다. 기본적으로 Helm과 같은 도구를 사용하여 Cilium 및 Calico를 제거하면 물리적 머신이나 가상 머신에서 온디스크 리소스가 제거되지 않습니다. 또한 이러한 CNI에 대한 사용자 지정 리소스 정의(CRD)가 이전 설치에서 클러스터에 계속 존재할 수 있습니다. 자세한 내용은 [하이브리드 노드에 대한 CNI 구성](hybrid-nodes-cni.md)의 Cilium 삭제 및 Calico 삭제 섹션을 참조하세요.
**Cilium 문제 해결**
하이브리드 노드에서 Cilium을 실행하는 데 문제가 있는 경우 Cilium 설명서의 [the troubleshooting steps](https://docs.cilium.io/en/stable/operations/troubleshooting/)를 참조하세요. 아래 섹션에서는 하이브리드 노드에 Cilium을 배포하는 작업과 관련된 문제를 다룹니다.
**Cilium이 시작되지 않음**
각 하이브리드 노드에서 실행되는 Cilium 에이전트가 시작되지 않는 경우 Cilium 에이전트 포드의 로그에 오류가 있는지 확인합니다. Cilium 에이전트를 시작하려면 EKS Kubernetes API 엔드포인트에 연결해야 합니다. 이 연결이 올바르게 구성되지 않으면 Cilium 에이전트 시작이 실패합니다. 이 경우 Cilium 에이전트 포드 로그에 다음과 유사한 로그 메시지가 표시됩니다.
```
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 에이전트는 호스트 네트워크에서 실행됩니다. Cilium 연결을 위해 EKS 클러스터를 `RemoteNodeNetwork`로 구성해야 합니다. `RemoteNodeNetwork`에 대한 인바운드 규칙을 적용한 EKS 클러스터에 대한 추가 보안 그룹이 있고, `RemoteNodeNetwork`에 대한 VPC에 경로가 있으며 온프레미스 네트워크가 EKS 컨트롤 플레인에 연결할 수 있도록 올바르게 구성되어 있는지 확인합니다.
Cilium 연산자가 실행 중이고 전부가 아닌 일부 Cilium 에이전트가 실행 중인 경우 클러스터의 모든 노드에 할당할 수 있는 포드 IP가 있는지 확인합니다. Cilium 구성에서 `clusterPoolIPv4PodCIDRList`와 함께 클러스터 풀 IPAM을 사용할 때 할당 가능한 포드 CIDR의 크기를 구성합니다. 노드별 CIDR 크기는 Cilium 구성의 `clusterPoolIPv4MaskSize` 설정으로 구성됩니다. 자세한 내용은 Cilium 설명서의 [클러스터 풀 확장](https://docs.cilium.io/en/stable/network/concepts/ipam/cluster-pool/#expanding-the-cluster-pool)을 참조하세요.
**Cilium BGP가 작동하지 않음**
Cilium BGP 컨트롤 플레인을 사용하여 포드 또는 서비스 주소를 온프레미스 네트워크에 알리는 경우 다음 Cilium CLI 명령을 사용하여 BGP가 리소스에 경로를 알리는지 확인할 수 있습니다. Cilium CLI를 설치하는 단계는Cilium 설명서의 [Install the Cilium CLI](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-default/#install-the-cilium-cli)를 참조하세요.
BGP가 올바르게 작동하는 경우 출력에 세션 상태가 `established`인 하이브리드 노드가 있어야 합니다. 네트워킹 팀과 협력하여 환경의 로컬 AS, 피어 AS, 피어 주소에 대한 올바른 값을 식별해야 할 수 있습니다.
```
cilium bgp peers
```
```
cilium bgp routes
```
Cilium BGP를 사용하여 유형이 `LoadBalancer`인 서비스의 IP를 알리는 경우 `CiliumLoadBalancerIPPool` 및 서비스 모두에 동일한 레이블이 있어야 하며, 이는 `CiliumBGPAdvertisement`의 선택기에 사용해야 합니다. 예를 들면 다음과 같습니다. 참고로 Cilium BGP를 사용하여 LoadBalancer 유형의 서비스 IP를 알리는 경우 Cilium 에이전트를 다시 시작하는 동안 BGP 경로가 중단될 수 있습니다. 자세한 내용은 Cilium 설명서의 [Failure Scenarios](https://docs.cilium.io/en/latest/network/bgp-control-plane/bgp-control-plane-operation/#failure-scenarios)를 참조하세요.
**서비스**
```
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 설명서의 [the troubleshooting steps](https://docs.tigera.io/calico/latest/operations/troubleshoot/)를 참조하세요. 아래 섹션에서는 하이브리드 노드에 Calico를 배포하는 작업과 관련된 문제를 다룹니다.
아래 표에는 Calico 구성 요소와 기본적으로 노드 또는 포드 네트워크에서 실행되는지 여부가 요약되어 있습니다. 발신 포드 트래픽에 NAT를 사용하도록 Calico를 구성한 경우 온프레미스 네트워크를 구성하여 온프레미스 노드 CIDR로 트래픽을 라우팅하고 VPC 라우팅 테이블을 전송 게이트웨이(TGW) 또는 가상 프라이빗 게이트웨이(VGW)를 대상으로 하는 온프레미스 노드 CIDR의 경로로 구성해야 합니다. 발신 포드 트래픽에 NAT를 사용하도록 Calico를 구성하지 않은 경우 온프레미스 네트워크를 구성하여 온프레미스 포드 CIDR로 트래픽을 라우팅하고 VPC 라우팅 테이블을 전송 게이트웨이(TGW) 또는 가상 프라이빗 게이트웨이(VGW)를 대상으로 하는 온프레미스 포드 CIDR의 경로로 구성해야 합니다.
| 구성 요소 | Network |
| --- | --- |
| Calico API 서버 | 노드 |
| Kubernetes용 Calico 컨트롤러 | 포드 |
| Calico 노드 에이전트 | 노드 |
| Calico `typha` | 노드 |
| Calico CSI 노드 드라이버 | 포드 |
| Calico 연산자 | 노드 |
**Calico 리소스가 차단된 노드에서 예약 또는 실행됨**
DaemonSet로 실행되지 않는 Calico 리소스에는 기본적으로 유연한 허용 오차가 있어 포드를 예약하거나 실행할 준비가 되지 않은 차단된 노드에서 예약할 수 있습니다. 다음을 포함하도록 연산자 설치를 변경하여 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 사용 설명서*의 [Working with the SSM agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html)을 참조하세요.
| 설명 | 위치 |
| --- | --- |
| SSM 에이전트 | Ubuntu-`/snap/amazon-ssm-agent/current/amazon-ssm-agent` RHEL & AL2023-`/usr/bin/amazon-ssm-agent` |
| SSM Agent 로그 | `/var/log/amazon/ssm` |
| AWS 보안 인증 | `/root/.aws/credentials` |
| SSM 설정 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 endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html)을 참조하세요. 아래 명령에서 `us-west-2`를 AWS SSM 하이브리드 활성화를 위한 AWS 리전으로 바꿉니다.
```
ping ssm.us-west-2.amazonaws.com
```
**등록된 SSM 인스턴스의 연결 상태 보기**
다음 AWS CLI 명령을 사용하여 SSM 하이브리드 활성화에 등록된 인스턴스의 연결 상태를 확인할 수 있습니다. 시스템 ID를 인스턴스의 시스템 ID로 바꿉니다.
```
aws ssm get-connection-status --target mi-012345678abcdefgh
```
**SSM 설정 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"
```
**시스템 등록 명령을 실행하는 중 SSM 오류 발생**
시스템을 SSM에 등록하는 동안 오류가 발생하면 `nodeadm install`을 다시 실행하여 모든 SSM 종속성이 올바르게 설치되었는지 확인해야 할 수 있습니다.
```
"error":"running register machine command: , error: fork/exec /opt/aws/ssm-setup-cli: no such file or directory"
```
**SSM `ActivationExpired`**
`nodeadm init`를 실행할 때 만료된 활성화로 인해 인스턴스를 SSM에 등록하는 동안 오류가 발생하면 새 SSM 하이브리드 활성화를 생성하고, 새 SSM 하이브리드 활성화의 `activationCode` 및 `activationId`로 `nodeConfig.yaml`을 업데이트하고, `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
```
** AWSIAM Roles Anywhere 문제 해결**
하이브리드 노드 자격 증명에 AWS IAM Roles Anywhere를 사용하는 경우 `nodeadm`에서 하이브리드 노드에 설치하는 다음 디렉터리 및 아티팩트에 유의합니다. IAM Roles Anywhere 문제 해결에 대한 자세한 내용은 *AWS IAM Roles Anywhere 사용 설명서*의 [Troubleshooting AWS IAM Roles Anywhere identity and access](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/security_iam_troubleshoot.html)을 참조하세요.
| 설명 | 위치 |
| --- | --- |
| 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`의 내용을 검토하고 `nodeadm` 구성에서 IAM Roles Anywhere가 올바르게 구성되었는지 확인합니다. `/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` 수행 권한 없음**
`kubelet` 로그에서 IAM Roles Anywhere를 사용할 때 `sts:AssumeRole` 작업에 대한 액세스 거부 문제가 표시되면 하이브리드 노드 IAM 역할의 신뢰 정책을 확인하여 IAM Roles Anywhere 서비스 보안 주체가 하이브리드 노드 IAM 역할을 수임할 수 있는지 확인합니다. 또한 하이브리드 노드 IAM 역할 신뢰 정책에서 트러스트 앵커 ARN이 올바르게 구성되었는지 그리고 하이브리드 노드 IAM 역할이 IAM Roles Anywhere 프로필에 추가되었는지 확인합니다.
```
could not get token: AccessDenied: User: ... is not authorized to perform: sts:AssumeRole on resource: ...
```
**IAM Roles Anywhere에 `roleSessionName` 설정 권한 없음**
`kubelet` 로그에서 `roleSessionName` 설정을 위한 액세스 거부 문제가 표시되면 IAM Roles Anywhere 프로필에 대해 `acceptRoleSessionName`을 true로 설정했는지 확인합니다.
```
AccessDeniedException: Not authorized to set roleSessionName
```
## 운영 체제 문제 해결
### RHEL
**권한 또는 구독 관리자 등록 실패**
`nodeadm install`을 실행 중이고 권한 등록 문제로 인해 하이브리드 노드 종속성을 설치하지 못한 경우 호스트에 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 관리자 컨테이너를 활성화한 경우 SSH로 해당 컨테이너에 액세스하여 승격된 권한으로 고급 디버깅 및 문제 해결을 수행할 수 있습니다. 다음 섹션에는 Bottlerocket 호스트의 컨텍스트에서 실행해야 하는 명령이 포함되어 있습니다. 관리자 컨테이너에 있으면 `sheltie`를 실행하여 Bottlerocket 호스트에 전체 루트 쉘을 가져올 수 있습니다.
```
sheltie
```
각 명령에 `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
```
호스트 `containerd` 인스턴스에 대한 `host-containerd` 서비스 상태를 확인하고 로그를 검색하기 위해 다음을 실행할 수 있습니다.
```
systemctl status host-containerd
journalctl -u host-containerd -f
```
부트스트랩 컨테이너 및 호스트 컨테이너에 대한 로그를 검색하기 위해 다음을 실행할 수 있습니다.
```
journalctl _COMM=host-ctr -f
```