# EKS VPC CNI 트러블슈팅 가이드
> 참고: [AWS VPC CNI 공식 트러블슈팅 문서](https://github.com/aws/amazon-vpc-cni-k8s/blob/master/docs/troubleshooting.md)
## VPC CNI 동작 원리
AWS VPC CNI는 Pod에 VPC의 실제 IP를 직접 할당:
- ENI(Elastic Network Interface)에 secondary IP 할당
- Pod가 VPC 네이티브 IP 사용 → VPC 내 직접 통신 가능
- ipamd 데몬이 IP pool 관리
**IP 용량 계산:**
```
최대 Pod IP = min((N * (M - 1)), 서브넷 가용 IP)
- N: 인스턴스가 지원하는 최대 ENI 수
- M: ENI당 최대 IP 수
- -1: 각 ENI가 attach시 1개 IP 사용
```
## 클러스터 레벨 트러블슈팅
### 1. 서브넷 IP 부족
**증상:** Pod가 `ContainerCreating` 상태로 멈춤
**확인:**
- AWS 콘솔에서 서브넷 Available IP 확인
- `ipamd/metrics.json`에서 IP 할당 상태
**주의:** [ENI 누수](https://github.com/aws/amazon-vpc-cni-k8s/issues/69)로 IP 고갈 가능
### 2. 대규모 클러스터 (500+ 노드)
**증상:** Pod 스케일업 시 일부 노드에서 `ContainerCreating` 지연
**원인:** EC2 API 제한으로 ipamD가 throttle되어 exponential backoff
**해결:** `WARM_ENI_TARGET` 값 증가
**확인:** cni-metrics-helper의 `ipamdActionInProgress` 메트릭
### 3. cni-metrics-helper 메트릭
| 메트릭 | 설명 |
|--------|------|
| `maxIPAddress` | 클러스터 최대 Pod IP 용량 |
| `totalIPAddresses` | 할당된 총 secondary IP |
| `assignIPAddresses` | Pod에 할당된 IP |
| `ipamdActionInProgress` | ENI 작업 중인 노드 수 |
## 노드 레벨 트러블슈팅
### 로그 위치
```
/var/log/aws-routed-eni/
├── ipamd.log # IP 할당 데몬 로그
├── plugin.log # CNI 플러그인 로그
├── egress-v6-plugin.log
└── network-policy-agent.log
```
### ipamD 디버깅 명령어
```bash
# ENI 정보
curl http://localhost:61679/v1/enis | python -m json.tool
# Pod IP 할당 정보
curl http://localhost:61679/v1/pods | python -m json.tool
# ipamD 메트릭
curl http://localhost:61678/metrics
```
## 핵심 점검 포인트
### 1. iptables 규칙 검증
```bash
# NAT 테이블 - SNAT 규칙 확인
iptables-save | grep -i snat
# 예상: -A POSTROUTING -m comment --comment "AWS SNAT" -j AWS-SNAT-CHAIN
```
**정상 상태:**
- `AWS-SNAT-CHAIN` 존재
- `CONNMARK` 규칙으로 외부 트래픽 마킹
- `SNAT --to-source <노드IP>` 규칙
### 2. IP Rule 검증
```bash
ip rule list
# 예상:
# 0: from all lookup local
# 512: from all to <pod-cidr> lookup main
# 1024: from all fwmark 0x80/0x80 lookup main
```
### 3. ENI/IP 할당 상태 (ipamd)
`ipamd/enis.json`:
```json
{
"TotalIPs": 10,
"AssignedIPs": 5,
"ENIs": { ... }
}
```
## Known Issues
### 1. Non-EKS AMI에서 Pod 간 ping 실패
**원인:** iptables FORWARD 정책이 DROP으로 설정됨
**해결:** `iptables -P FORWARD ACCEPT`
### 2. systemd-udev MAC 주소 문제 (Ubuntu 22.04+)
**해결:** `/usr/lib/systemd/network/99-default.link`에서 `MACAddressPolicy=none`
### 3. nftables 호환성 (RHEL 8.x+, Ubuntu 21.x+)
**해결:** v1.12.1+에서 `ENABLE_NFTABLES=true` 설정
## 흔한 문제 패턴
| 증상 | 원인 | 확인 위치 |
|------|------|-----------|
| Pod 외부 통신 불가 | SNAT 규칙 누락 | iptables-nat.txt |
| Pod 간 통신 불가 | ip rule 누락 | iprule.txt |
| Pod IP 할당 실패 | IP pool 고갈 | ipamd/metrics.json |
| ContainerCreating 멈춤 | 서브넷 IP 부족 | ipamd.log |
## EKS Log Collector 파일 매핑
| 점검 항목 | 파일 위치 |
|-----------|-----------|
| iptables 규칙 | networking/iptables-save.txt |
| ip rule | networking/iprule.txt |
| ip route | networking/iproute.txt |
| ENI 정보 | ipamd/enis.json |
| Pod IP 할당 | ipamd/pods.json |
| VPC CNI 로그 | var_log/aws-routed-eni/ipamd.log |
