**이 페이지 개선에 도움 주기** 

이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **GitHub에서 이 페이지 편집** 링크를 선택합니다.

# Amazon EKS Hybrid Nodes 게이트웨이 문제 해결
<a name="hybrid-nodes-gateway-troubleshooting"></a>

이 페이지에서는 Amazon EKS Hybrid Nodes 게이트웨이와 관련된 일반적인 문제를 진단하고 해결하기 위한 지침을 제공합니다. 각 섹션에서는 증상, 가능한 원인, 진단 단계 및 해결 방법을 설명합니다. 작업에 대한 자세한 내용은 [Amazon EKS Hybrid Nodes 게이트웨이 작업](hybrid-nodes-gateway-operations.md) 섹션을 참조하세요.

## VPC에서 도달할 수 없는 하이브리드 노드의 포드
<a name="hybrid-nodes-gateway-ts-unreachable"></a>

하이브리드 노드에서 실행되는 포드에 EC2 인스턴스, 로드 밸런서 또는 Kubernetes 컨트롤 플레인과 같은 VPC의 리소스에서 도달할 수 없습니다.

 **가능한 원인:** 
+ VPC 라우팅 테이블 항목이 누락되었거나 잘못된 ENI를 가리킵니다.
+ 게이트웨이 리더 포드가 실행 중이 아니거나 설정을 완료하지 않았습니다.
+ Cilium VTEP가 하이브리드 노드에서 활성화되거나 구성되지 않았습니다.
+ 소스/대상 확인이 게이트웨이 EC2 인스턴스에서 활성화됩니다.

 **진단 단계:** 

1.  **VPC 라우팅 테이블 항목을 확인하세요.** 하이브리드 포드 CIDR에 대한 경로가 있으며, 활성 게이트웨이 인스턴스의 프라이머리 ENI를 가리키는지 확인하세요.

   ```
   aws ec2 describe-route-tables \
     --route-table-ids {{ROUTE_TABLE_ID}} \
     --query "RouteTables[].Routes[?DestinationCidrBlock=='POD_CIDR']"
   ```

   경로가 누락된 경우 게이트웨이 로그에서 라우팅 테이블 오류가 있는지 확인하세요. 경로가 잘못된 ENI를 가리키는 경우 장애 조치가 성공적으로 완료되지 않았을 수 있습니다.

1.  **게이트웨이 포드 상태 및 리더 선정을 확인하세요.** 두 게이트웨이 포드가 실행 중이고 한 게이트웨이 포드가 리더 리스를 보유하는지 확인하세요.

   ```
   kubectl get pods -n eks-hybrid-nodes-gateway
   kubectl get lease -n eks-hybrid-nodes-gateway
   ```

   리스를 보유한 포드가 없는 경우 [리더 선정 관련 문제](#hybrid-nodes-gateway-ts-leader) 섹션을 참조하세요.

1.  **하이브리드 노드에서 Cilium VTEP 구성을 확인하세요.** `CiliumVTEPConfig` 리소스가 있고, 리더의 노드 IP가 포함되어 있는지 확인하세요.

   ```
   kubectl get ciliumvtepconfig hybrid-gateway -o yaml
   ```

   `spec.endpoints[0].tunnelEndpoint`는 리더 게이트웨이 노드의 IP 주소와 일치해야 합니다. 리소스가 누락되었거나 오래된 IP를 보유하는 경우 게이트웨이에서 리더 설정이 완료되지 않았을 수 있습니다.

1.  **소스/대상 확인을 확인하세요.** 게이트웨이 EC2 인스턴스에서 소스/대상 확인이 비활성화되어 있는지 확인하세요.

   ```
   aws ec2 describe-instance-attribute \
     --instance-id {{GATEWAY_INSTANCE_ID}} \
     --attribute sourceDestCheck
   ```

   `sourceDestCheck`가 `true`이면 비활성화하세요. [EKS Hybrid Nodes 게이트웨이 시작하기](hybrid-nodes-gateway-getting-started.md)을(를) 참조하세요.

## 하이브리드 노드에 대한 웹후크 직접 호출 실패
<a name="hybrid-nodes-gateway-ts-webhooks"></a>

Kubernetes API 서버가 하이브리드 노드에서 실행되는 웹후크 엔드포인트에 도달할 수 없습니다. 웹후크 승인 요청에서 제한 시간을 초과하거나 연결 오류를 반환합니다.

 **가능한 원인:** 
+ 게이트웨이가 컨트롤 플레인에서 하이브리드 포드로 트래픽을 라우팅하지 않습니다.
+ `CiliumVTEPConfig` 리소스가 누락되었거나 오래된 엔드포인트 IP를 보유하고 있습니다.

 **진단 단계:** 

1.  **컨트롤 플레인이 게이트웨이 노드 IP에 도달할 수 있는지 확인하세요.** 컨트롤 플레인은 트래픽을 VPC 라우팅 테이블로 전송하고, 여기서 이를 게이트웨이의 ENI로 전달합니다. [VPC에서 도달할 수 없는 하이브리드 노드의 포드](#hybrid-nodes-gateway-ts-unreachable)의 단계를 사용하여 VPC 라우팅 테이블 항목이 올바른지 확인하세요.

1.  **CiliumVTEPConfig 리소스를 확인하세요.** 리소스가 존재하고 `tunnelEndpoint`가 현재 리더의 노드 IP와 일치하는지 확인하세요.

   ```
   kubectl get ciliumvtepconfig hybrid-gateway -o yaml
   ```

   터널 엔드포인트가 오래된 경우(이전 리더를 가리킴) 게이트웨이에서 리더 설정 시퀀스를 완료하지 않았을 수 있습니다. `CiliumVTEPConfig` 업서트 중에 게이트웨이 로그에 오류가 있는지 확인하세요.

## VPC 라우팅 테이블 업데이트 실패
<a name="hybrid-nodes-gateway-ts-routes"></a>

게이트웨이 로그에는 VPC 라우팅 테이블 작업과 관련된 오류가 표시되며, 하이브리드 포드 CIDR에 대한 경로는 생성되거나 업데이트되지 않습니다.

 **가능한 원인:** 
+ 게이트웨이의 IAM 역할에 필요한 EC2 권한이 없습니다.
+ 구성의 라우팅 테이블 ID가 잘못되었거나 라우팅 테이블이 존재하지 않습니다.
+ 게이트웨이가 EC2 API 엔드포인트에 도달할 수 없습니다.

 **진단 단계:** 

1.  **IAM 권한을 확인하세요.** 게이트웨이에는 다음 IAM 작업이 필요합니다.
   +  `ec2:DescribeRouteTables` 
   +  `ec2:CreateRoute` 
   +  `ec2:ReplaceRoute` 
   +  `ec2:DescribeInstances` 

     게이트웨이 노드의 인스턴스 프로파일 또는 Pod Identity 구성에 연결된 IAM 역할을 확인하세요.

1.  **구성에서 라우팅 테이블 ID를 확인하세요.** 게이트웨이 배포에서 `ROUTE_TABLE_IDS` 환경 변수에 유효한 라우팅 테이블 ID가 포함되어 있는지 확인하세요.

   ```
   kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].env}' | jq .
   ```

   VPC에 라우팅 테이블 ID가 있는지 확인하세요.

   ```
   aws ec2 describe-route-tables --route-table-ids {{ROUTE_TABLE_ID}}
   ```

1.  **게이트웨이 로그에서 라우팅 테이블 오류를 확인하세요.** 라우팅 테이블 작업과 관련된 오류 메시지를 찾아보세요.

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}} | grep -i "route table"
   ```

   일반적인 오류 메시지로 다음이 포함됩니다.
   +  `Failed to verify route table access` - 게이트웨이가 라우팅 테이블을 설명할 수 없습니다. IAM 권한 및 라우팅 테이블 ID를 확인하세요.
   +  `Failed to update route tables` - 게이트웨이에서 경로를 생성하거나 대체할 수 없습니다. IAM 권한을 확인하세요.
   +  `failed to access route table` - 라우팅 테이블 ID가 잘못되었거나 IAM 역할에 `ec2:DescribeRouteTables`가 없습니다.

## 게이트웨이 포드가 시작되지 않거나 비정상 상태임
<a name="hybrid-nodes-gateway-ts-pods"></a>

게이트웨이 포드가 `CrashLoopBackOff`, `Error` 또는 `Pending` 상태이거나 상태 엔드포인트에서 오류를 반환합니다.

 **가능한 원인:** 
+ 필수 환경 변수(`VPC_CIDR`, `POD_CIDRS`, `ROUTE_TABLE_IDS`)가 설정되지 않았습니다.
+ IP 전달이 게이트웨이 노드에서 활성화되지 않았습니다.
+ 노드 레이블 또는 비선호도 제약 조건으로 예약되지 않습니다.

 **진단 단계:** 

1.  **포드 로그를 확인하세요.** 장애가 발생한 포드의 로그를 보고 오류를 식별하세요.

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}}
   ```

1.  **필수 환경 변수를 확인하세요.** 게이트웨이에 `NODE_IP`, `VPC_CIDR` 및 `POD_CIDRS`가 필요합니다. 누락된 항목이 있으면 게이트웨이가 즉시 종료됩니다. 포드 사양을 확인하세요.

   ```
   kubectl get pod -n eks-hybrid-nodes-gateway {{LEADER_POD}} -o jsonpath='{.spec.containers[0].env}' | jq .
   ```
   +  `NODE_IP`는 포드 사양의 `status.hostIP`에서 자동으로 설정됩니다. 비어 있는 경우 포드가 아직 노드에서 예약되지 않았을 수 있습니다.
   +  `VPC_CIDR` 및 `POD_CIDRS`는 헬름 값에서 가져옵니다. 올바르게 설정되었는지 확인하세요.

1.  **IP 전달을 확인하세요.** 게이트웨이는 시작 시 IP 전달이 활성화되었는지 확인하고 활성화되지 않은 경우 종료됩니다. 포드 로그에서 오류 메시지 `IP forwarding is not enabled`를 찾아보세요. 노드에서 IP 전달을 활성화하세요.

   ```
   # Check current setting
   cat /proc/sys/net/ipv4/ip_forward
   
   # Enable if not set
   sudo sysctl -w net.ipv4.ip_forward=1
   ```

   영구 설정의 경우 kubelet을 통해 IP 전달을 구성하거나 `net.ipv4.ip_forward=1`을 `/etc/sysctl.d/`에 추가하세요.

1.  **노드 레이블 및 예약 제약 조건을 확인하세요.** 게이트웨이 포드에는 `hybrid-gateway-node=true` 레이블이 있는 노드가 필요합니다. 포드 비선호도는 각 포드가 별도의 노드에서 실행되도록 보장합니다. 포드가 `Pending`인 경우 예약 문제가 있는지 확인하세요.

   ```
   kubectl describe pod -n eks-hybrid-nodes-gateway {{LEADER_POD}}
   ```

   노드 부족, 레이블 누락 또는 비선호도 충돌을 나타내는 이벤트가 있는지 찾아보세요.

## 리더 선정 관련 문제
<a name="hybrid-nodes-gateway-ts-leader"></a>

게이트웨이 포드가 실행 중이지만 리더 리스를 획득하는 포드가 없거나 리더십 전환이 빈번하게 발생합니다.

 **가능한 원인:** 
+ 객체 리스에 대한 RBAC 권한이 누락되었습니다.
+ 게이트웨이 포드 및 Kubernetes API 서버 간 네트워크 연결은 신뢰할 수 없습니다.
+ 리더 선정 파라미터가 잘못 구성되었습니다.

 **진단 단계:** 

1.  **리스 객체를 확인하세요.** 리스가 존재하는지 확인하고 현재 보유자를 검사하세요.

   ```
   kubectl get lease -n eks-hybrid-nodes-gateway hybrid-gateway-leader -o yaml
   ```

   `spec.holderIdentity` 필드는 현재 리더를 표시합니다. `spec.renewTime`은 리스가 마지막으로 갱신된 시점을 보여줍니다. `renewTime`이 오래된 경우 리더에서 API 서버에 대한 연결이 끊어졌을 수 있습니다.

1.  **RBAC 권한을 확인하세요.** 게이트웨이 서비스 계정에는 게이트웨이 네임스페이스에서 리스 객체를 가져오고 생성하며 업데이트하기 위한 권한이 필요합니다. 역할 및 RoleBinding을 확인하세요.

   ```
   kubectl get role -n eks-hybrid-nodes-gateway
   kubectl get rolebinding -n eks-hybrid-nodes-gateway
   ```

   역할에는 `coordination.k8s.io` API 그룹의 `leases` 리소스에 대한 `get`, `create` 및 `update` 동사가 포함되어야 합니다.

1.  **포드 로그에서 리스 오류를 확인하세요.** 포드 로그에서 리더 선정 오류를 찾아보세요.

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}} | grep -i "leader\|lease"
   ```

   일반적인 문제:
   +  `Failed to acquire lease` - 포드에서 리스 객체를 생성하거나 업데이트할 수 없습니다. RBAC 권한을 확인하세요.
   + `Leadership ended` 메시지 뒤에 `Leader setup complete`가 빈번하게 나오는 경우 - 리더가 리스를 상실한 후 다시 획득하는 것입니다. 포드 및 API 서버 간 네트워크 불안정성을 나타낼 수 있습니다. `--leader-election-lease-duration`을 늘리는 방법을 고려합니다.

1.  **리더 선정 파라미터를 확인하세요.** 구성된 값을 확인하세요.

   ```
   kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].args}'
   ```

   `--leader-election-renew-deadline`이 `--leader-election-lease-duration`보다 작아야 합니다. 갱신 기한이 리스 기간을 초과하는 경우 리더는 갱신하기 전에 리스를 잃습니다. 자세한 내용은 [리더 선정 조정](hybrid-nodes-gateway-configuration.md#hybrid-nodes-gateway-leader-tuning) 섹션을 참조하세요.

## 일반적인 오류 메시지
<a name="hybrid-nodes-gateway-ts-errors"></a>

다음 표에는 게이트웨이 포드 로그에 표시될 수 있는 오류 메시지와 관련 해결 방법이 나와 있습니다.


| 오류 메시지 | 원인 | 해결 방법 | 
| --- | --- | --- | 
|  `IP forwarding is not enabled`  | 커널 파라미터 `net.ipv4.ip_forward`가 게이트웨이 노드에서 `1`로 설정되지 않았습니다. | kubelet 구성을 통해 또는 `sysctl -w net.ipv4.ip_forward=1`을 실행하여 IP 전달을 활성화하세요. | 
|  `Failed to setup VXLAN`  | 게이트웨이에서 VXLAN 네트워크 인터페이스를 생성할 수 없습니다. 일반적으로 포드에 `NET_ADMIN` 기능이 없는 경우에 발생합니다. | 배포 사양에서 `securityContext.capabilities.add`에 `NET_ADMIN`이 포함되어 있는지 확인하세요. 헬름 차트가 올바르게 배포되었는지 확인하세요. | 
|  `Failed to verify route table access`  | 게이트웨이에서 시작 시 하나 이상의 VPC 라우팅 테이블을 설명할 수 없습니다. | IAM 역할에 `ec2:DescribeRouteTables` 권한이 있고 구성의 라우팅 테이블 ID가 올바른지 확인하세요. | 
|  `Failed to update route tables`  | 게이트웨이가 VPC 라우팅 테이블에서 경로를 생성하거나 대체할 수 없습니다. | IAM 역할에 `ec2:CreateRoute` 및 `ec2:ReplaceRoute` 권한이 있는지 확인하세요. | 
|  `Failed to create route table manager`  | 게이트웨이에서 AWS EC2 클라이언트를 초기화하거나 인스턴스의 프라이머리 ENI를 검색할 수 없습니다. | IAM 역할에 `ec2:DescribeInstances` 권한이 있고 인스턴스 메타데이터 서비스(IMDS)에 액세스할 수 있는지 확인하세요. | 
|  `NODE_IP is required`  | `NODE_IP` 환경 변수 또는 `--node-ip` 플래그가 설정되지 않았습니다. | 포드 사양에서 `fieldRef`를 사용하여 `status.hostIP`에서 `NODE_IP`를 설정하는지 확인하세요. 헬름 차트가 올바르게 배포되었는지 확인하세요. | 
|  `Invalid NODE_IP`  | `NODE_IP`에 제공된 값이 유효한 IP 주소가 아닙니다. | 포드 사양에서 `NODE_IP` 환경 변수 값을 확인하세요. | 
|  `pod-cidrs and vpc-cidr are required`  | `POD_CIDRS` 또는 `VPC_CIDR` 환경 변수가 비어 있습니다. | 설치 중에 `podCIDRs` 및 `vpcCIDR` 헬름 값을 설정하세요. | 
|  `No valid route table IDs provided`  | `ROUTE_TABLE_IDS` 값이 설정되었지만 구문 분석 후 유효한 라우팅 테이블 ID를 포함하지 않습니다. | `routeTableIDs` 헬름 값에서 형식 지정 오류가 있는지 확인하세요. 라우팅 테이블 ID는 쉼표로 구분해야 합니다(예: `rtb-abc123,rtb-def456`). | 
|  `Failed to auto-detect AWS region`  | 게이트웨이가 EC2 인스턴스 메타데이터에서 AWS 리전을 검색할 수 없습니다. | 인스턴스 메타데이터 서비스(IMDS)에 액세스할 수 있는지 확인하세요. 또는 `--aws-region` 플래그 또는 `AWS_REGION` 환경 변수를 명시적으로 설정하세요. | 
|  `Failed to auto-detect AWS instance ID`  | 게이트웨이가 EC2 인스턴스 메타데이터에서 인스턴스 ID를 검색할 수 없습니다. | 인스턴스 메타데이터 서비스(IMDS)에 액세스할 수 있는지 확인하세요. 또는 `--aws-instance-id` 플래그 또는 `AWS_INSTANCE_ID` 환경 변수를 명시적으로 설정하세요. | 
|  `CiliumNode has no internal IP`  | 하이브리드 노드의 `CiliumNode` 객체에서 해당 사양에 내부 IP 주소가 없습니다. | 하이브리드 노드가 올바르게 등록되었고 Cilium 에이전트가 실행 중인지 확인하세요. 노드의 `CiliumNode` 리소스를 확인하세요. | 
|  `CiliumNode <name> has no pod CIDRs allocated`  | 하이브리드 노드의 `CiliumNode` 객체에 Cilium IPAM에서 할당한 포드 CIDR이 없습니다. | Cilium IPAM이 하이브리드 노드에서 올바르게 구성되었는지 확인하세요. `CiliumNode` 리소스에서 노드의 IPAM 상태를 확인하세요. | 
|  `Failed to upsert CiliumVTEPConfig`  | 게이트웨이에서 `CiliumVTEPConfig` 사용자 지정 리소스를 생성하거나 업데이트할 수 없습니다. | CRD가 클러스터에 설치되어 있고 게이트웨이 서비스 계정에 `CiliumVTEPConfig` 리소스를 관리할 권한이 있는지 확인하세요. | 
|  `Unable to create manager`  | 컨트롤러-런타임 관리자가 초기화되지 않았습니다. | 포드 로그에서 추가 컨텍스트를 확인하세요. 일반적인 원인으로 잘못된 kubeconfig 또는 Kubernetes API 서버에 도달할 수 없는 경우가 포함됩니다. | 
|  `Failed to add gateway setup`  | 리더 선정 실행 가능 항목을 컨트롤러 관리자에 등록할 수 없습니다. | 일반적으로 내부 오류입니다. 전체 포드 로그에서 추가 컨텍스트를 확인하고 [GitHub 리포지토리](https://github.com/aws/eks-hybrid-nodes-gateway)에 문제를 보고하세요. | 
|  `Unable to create Node controller`  | CiliumNode 조정자를 컨트롤러 관리자에 등록할 수 없습니다. | 포드 로그에서 추가 컨텍스트를 확인하세요. CiliumNode CRD가 클러스터에 설치되어 있는지 확인하세요. | 
|  `Problem running manager`  | 컨트롤러 관리자가 예기치 않게 종료되었습니다. | 포드 로그에서 기본 오류를 확인하세요. 일반적인 원인으로 Kubernetes API 서버에 대한 연결 끊어짐 또는 지표나 상태 프로브 바인드 주소의 포트 충돌이 포함됩니다. | 
|  `failed to access route table <id>`  | 게이트웨이에서 시작 확인 검사 중에 특정 VPC 라우팅 테이블을 설명할 수 없습니다. | IAM 역할에 `ec2:DescribeRouteTables` 권한이 있고 라우팅 테이블 ID가 올바른지 확인하세요. 라우팅 테이블이 게이트웨이 인스턴스와 같은 리전에 있어야 합니다. | 

## 관련 주제
<a name="hybrid-nodes-gateway-ts-related"></a>
+  [Amazon EKS Hybrid Nodes 게이트웨이](hybrid-nodes-gateway-overview.md) - 게이트웨이 아키텍처 및 사용 사례에 대한 개요.
+  [EKS Hybrid Nodes 게이트웨이 시작하기](hybrid-nodes-gateway-getting-started.md) - 사전 조건 및 설치 지침.
+  [Amazon EKS Hybrid Nodes 게이트웨이 구성 참조](hybrid-nodes-gateway-configuration.md) - 헬름 값, CLI 플래그 및 환경 변수에 대한 전체 참조.
+  [Amazon EKS Hybrid Nodes 게이트웨이 작업](hybrid-nodes-gateway-operations.md) - 모니터링, 장애 조치 동작 및 조정 지침.