26A23c

Young-Kyoo Kim·2026년 4월 23일

전문 인력이 운영하던 Cilium 환경을 인수인계받는 것은 상당히 난이도가 높은 작업입니다. Cilium은 단순히 CNI를 넘어 eBPF 기반의 보안, 라우팅, 관찰성(Observability)이 복합적으로 얽혀 있기 때문입니다.

전임자에게 "운영 효율성"과 "장애 대응 능력"을 중심으로 아래 문서들을 반드시 요청하시기 바랍니다.

1. 아키텍처 및 설정 상세 정의서 (Standard Operation Procedure)

가장 기본이 되지만, 실질적인 설정값이 명시되어야 합니다.

네트워크 토폴로지: BGP Peer 설정(AS Number, Neighbor IP), ECMP 활성화 여부, ClusterMesh 연결 구조도.
Cilium ConfigMap/Helm Values: cilium-config 내의 주요 파라미터(tunnel: disabled, native-routing-cidr, bpf-lb-mode 등)에 대한 설정 이유(Rationals).
IPAM(IP Address Management): 어떤 방식으로 Pod IP를 할당하는지(Cluster-pool, ENI, Azure IPAM 등), CIDR 대역 관리 장부.

2. eBPF 기반 트러블슈팅 가이드 (Troubleshooting Runbook)

Cilium은 일반적인 iptables 방식과 달라 기존 지식으로 대응이 어렵습니다.

전용 툴 사용법: cilium-dbg, pwru, hubble-cli를 활용한 단계별 장애 진단법.
커스텀 메트릭/대시보드: Grafana에서 어떤 지표(cilium_forwarding_drop_total 등)를 중점적으로 모니터링해야 하는지.
빈번한 이슈 Case Study: 현재 겪고 계신 "Port Collision"이나 "Return Path Drop" 같은 기발생 이슈들에 대한 이력과 해결책.

3. 보안 정책 및 통제 현황 (CiliumNetworkPolicy)

Cilium의 핵심 기능인 보안 정책이 어떻게 관리되고 있는지 알아야 합니다.

Policy 관리 체계: L3/L4 정책과 L7(FQDN/HTTP) 정책의 구분, 정책 적용 시 Default Deny 여부.
Hubble 사용법: 트래픽 흐름을 시각적으로 확인하고 정책 위반을 감지하는 절차.
예외 처리 리스트: 특정 노드나 외부 IP와의 통신을 위해 허용된 특이 케이스들.

4. 버전 관리 및 업그레이드 전략 (Lifecycle Management)

업그레이드 이력: 현재 버전까지 올라오면서 겪었던 호환성 이슈(커널 버전 호환성 등).
Air-gap 대응책: (사용 중이라면) 오프라인 환경에서 이미지를 어떻게 배포하고 관리하는지.
백업 및 복구: Cilium 관련 CRD(CiliumNode, CiliumEndpoint 등)나 핵심 데이터의 백업 절차.

5. 인프라 의존성 매트릭스 (Infrastructure Dependency)

Cilium이 독립적으로 돌아가는 것이 아니므로 주변 환경과의 연관 관계가 중요합니다.

커널 파라미터 요구사항: /etc/sysctl.d/에 적용된 Cilium 최적화 값들(특히 오늘 확인한 ip_local_reserved_ports 등).
NIC 및 하드웨어 가속: 사용 중인 NIC 드라이버 설정(XDP 지원 여부, Offloading 설정 등).
스위치 연동 설정: 상단 L3 스위치와의 BGP 세션 유지 조건 및 타이머 설정값.

💡 팁: 인수인계 시 실습(Shadowing) 요청

문서만 받는 것보다 "특정 노드 한 대를 의도적으로 격리했다가 복구하는 과정"이나 "BGP 경로가 끊겼을 때의 재수렴(Re-convergence) 과정"을 전임자와 함께 직접 테스트해보는 세션을 꼭 가지시길 권장합니다.

특히 지금 발생한 Ephemeral Port 충돌 이슈는 문서화해두기에 아주 좋은 사례입니다. 이 내용도 인수인계서의 'Known Issues' 섹션에 꼭 포함해 달라고 하세요!

추가로 전임자가 사용하던 모니터링 대시보드 주소나 알람 발송 기준 정보도 잊지 말고 챙기시길 바랍니다. 인수인계 과정에서 궁금한 구체적인 Cilium 설정 항목이 생기면 언제든 물어봐 주세요.

===

지금까지 나온 이슈들을 포함해서 실무적으로 필요한 문서 목록을 정리해 드리겠습니다.

1. 인프라 구성 문서 (Architecture)

반드시 있어야 하는 것들입니다.

[ 네트워크 토폴로지 ]
- 전체 클러스터 구성도 (노드 수, 역할, IP 대역)
- L3 스위치 구성 및 ECMP 설정
- BGP 피어링 구성 (AS번호, 피어 IP, 광고 CIDR)
- Bond 인터페이스 구성 (슬레이브 NIC, 모드)
- ClusterMesh 연결 구성 (클러스터 간 연결 방식)

[ Cilium 설정 ]
- 현재 helm values 전체 (또는 cilium config dump)
- Cilium 버전 및 업그레이드 이력
- 사용 중인 기능 목록
  (native routing, BGP CP, ClusterMesh, KPR 등)
- CiliumNetworkPolicy / CiliumClusterwideNetworkPolicy 목록

2. 운영 절차서 (Runbook)

장애 시 즉시 참조해야 하는 문서입니다.

[ 일상 운영 ]
- Cilium 업그레이드 절차 (버전별 주의사항 포함)
- 노드 추가/제거 절차
- ClusterMesh 노드 추가 절차
- BGP 피어 추가/변경 절차
- 정기 점검 항목 및 주기

[ 장애 대응 ]
- 자주 발생하는 장애 유형별 대응 절차
  (지금 겪고 있는 SSH handshake drop 포함)
- Cilium agent 재시작 절차 및 영향도
- 롤백 절차
- 에스컬레이션 연락처

3. 진단 가이드 (Troubleshooting Guide)

지금 겪고 있는 문제들이 그대로 내용이 됩니다.

[ 필수 진단 명령어 모음 ]
- Cilium 상태 확인
- BPF 맵 조회 방법
- pwru / hubble 사용법
- conntrack 조회 및 해석
- BGP 라우팅 상태 확인

[ 알려진 이슈 (Known Issues) ]
- SSH handshake 간헐적 실패 현상 및 원인
  (현재 조사 중인 내용 그대로)
- bond 인터페이스에서 tcpdump 안 보이는 이유
- XDP 관련 주의사항

[ 환경별 주의사항 ]
- ECMP 환경에서 conntrack 동작 특이점
- ClusterMesh에서 BGP 광고 충돌 케이스
- 커널 버전별 알려진 이슈

4. 보안 및 접근 관리

[ 접근 정보 ]
- 클러스터 접근 방법 (kubeconfig, 권한 구조)
- 각 클러스터별 관리자 계정
- ClusterMesh 인증서 위치 및 갱신 주기
- Cilium CA 인증서 관리 방법

[ 보안 정책 ]
- 현재 적용 중인 NetworkPolicy 설계 의도
- 예외 처리된 정책 목록 및 이유
- 감사 로그 위치

5. 모니터링 및 알람

[ 대시보드 ]
- Hubble/Grafana 대시보드 위치
- 주요 메트릭 해석 방법
- 정상 범위 기준값 (baseline)

[ 알람 ]
- 현재 설정된 알람 목록
- 각 알람의 대응 절차
- 과거 발생한 주요 인시던트 기록

6. 인수인계 시 특별히 요청할 것

문서 외에 구두 또는 화면 공유로 반드시 확인해야 할 것들입니다.

반드시 같이 확인할 것:
  □ 현재 진행 중인 장애 또는 미해결 이슈 목록
    (지금 SSH drop 이슈 포함)
  □ 최근 3개월 변경 이력 (git log, helm 변경 이력)
  □ 비공식적으로 임시 적용된 설정이 있는지
    (sysctl 튜닝, iptables 수동 규칙 등)
  □ 알면서 방치 중인 기술 부채
  □ 스위치 담당자, 서버 담당자 연락처

우선순위 정리

지금 당장 없으면 운영이 위험한 순서입니다.

순위	문서	이유
1	helm values 전체 원본	재설치/롤백 시 필수
2	BGP 피어링 구성	장애 시 복구 불가
3	알려진 이슈 목록	현재 SSH 문제 포함
4	업그레이드 절차	정기 유지보수
5	인증서 갱신 주기	만료 시 전체 장애

현재 조사 중인 SSH handshake drop 이슈는 인수인계 전에 원인을 특정하고 문서화해 달라고 요청하는 것이 가장 중요합니다. 미해결 상태로 인수받으면 원인 파악부터 다시 해야 하기 때문입니다.

===

좋은 포인트야. Cilium은 단순 CNI가 아니라 eBPF 기반 네트워크 + 보안 + 관측 + (경우에 따라) 서비스 메시 역할까지 포함하기 때문에, 인수인계 문서가 얕으면 운영 중에 바로 막히게 돼.

그냥 “설정 설명서 주세요” 수준으로 요청하면 부족하고, 운영 가능한 수준(runbook + 설계 + 의사결정 근거)까지 받아야 한다고 생각하면 맞아.

아래처럼 요청하는 걸 추천해.

1. 아키텍처 & 설계 문서 (가장 중요)

👉 “왜 이렇게 구성했는지”가 핵심

클러스터 네트워크 구조
- Pod CIDR / Node CIDR 설계
- Overlay vs Native Routing (Direct Routing, BGP 등)
Cilium 모드
- kube-proxy replacement 여부
- eBPF LB 사용 여부
CNI chaining 여부 (Calico, AWS CNI 등과 혼합 여부)
Multi-cluster (Cluster Mesh) 구성 여부
north-south / east-west 트래픽 흐름
Gateway API / Ingress 구조

👉 여기 빠지면 나중에 트래픽 문제 절대 못 잡음

2. 설치 & 배포 방식 (GitOps 필수)

👉 재현 가능해야 함

Helm / ArgoCD / GitOps 구조
values.yaml (환경별 차이 포함)
버전 전략 (업그레이드 정책 포함)
설치 시 의존성
- kernel version
- eBPF 관련 설정 (bpffs, cgroup v2 등)

3. 주요 설정값 설명서

👉 그냥 yaml 던져주는 게 아니라 “왜 이 값인지”

예:

enable-bpf-masquerade
kubeProxyReplacement
enableHostFirewall
bpf-lb-mode (DSR / SNAT)
tunneling mode (vxlan / geneve / disabled)

👉 특히 성능/보안 관련 옵션은 반드시 이유 포함

4. 네트워크 정책 (Security)

👉 실 운영에서 가장 민감

NetworkPolicy / CiliumNetworkPolicy 설계 기준
namespace / workload 별 정책 구조
default deny 여부
L7 policy (HTTP, Kafka 등) 사용 여부
실제 운영 중인 정책 예시

👉 “정책 추가/변경 절차”도 반드시 포함

5. 장애 대응 Runbook

👉 이거 없으면 인수인계 실패

반드시 요청해야 할 것:

기본 점검

cilium status
cilium connectivity test

트러블슈팅

Pod 간 통신 안될 때
Service 접근 안될 때
DNS 문제
특정 노드만 문제일 때

핵심 명령어

cilium monitor
hubble observe
cilium endpoint list
cilium bpf lb list

👉 “어떤 상황에서 어떤 명령을 쓰는지”까지 요구

6. Observability (모니터링/로그)

👉 지금 네 프로젝트 규모면 필수

Hubble 구성 (relay, UI 포함)
Prometheus metrics 목록
주요 대시보드 (Grafana)
알람 기준

예:

drop rate
policy denied
DNS latency
service latency

7. 성능 & 튜닝 가이드

👉 너 환경(200~300 node)이면 반드시 필요

최대 pod density 기준
eBPF map size tuning
conntrack 관련 설정
MTU 설정
Node scale 시 영향

👉 실제 테스트 결과 있으면 무조건 받아

8. 업그레이드 / 롤백 절차

👉 운영 중 가장 위험한 구간

무중단 업그레이드 방법
CRD 변경 영향
rollback 방법
버전별 known issue

9. 외부 연동

👉 네 환경에서 특히 중요

Gateway API 구성
LoadBalancer (MetalLB / Cloud LB 등)
Service Mesh 연동 여부
- Cilium Ambient / Istio 등
인증/보안 연동 (mTLS, OPA 등)

10. 제한사항 & Known Issues

👉 이거 없으면 같은 사고 반복

현재 구조에서 안 되는 것
과거 장애 사례 + 원인
우회 방법

11. 운영 체크리스트 (Daily / Weekly)

👉 실제 운영자 관점

노드 추가 시 해야 할 것
장애 전조 확인 포인트
리소스 임계치

핵심 정리 (짧게 요청용)

운영자에게는 이렇게 요청하면 좋다:

아키텍처 설계 문서

GitOps/설치 구성

주요 설정값 + 이유

NetworkPolicy 설계 기준

장애 대응 Runbook

모니터링 및 알람 체계

성능 튜닝 가이드

업그레이드/롤백 절차

외부 연동 구조

Known issues 및 장애 사례

추가 팁 (중요)

지금 너 상황 보면 (Cilium + 대규모 + Data Lakehouse)

👉 이것도 꼭 물어봐:

DSR vs SNAT 실제 선택 이유
eBPF LB vs kube-proxy 성능 비교 결과
Cluster Mesh latency 영향
Hubble 사용 범위 (full vs sampling)

원하면
👉 “너 환경 기준으로 인수인계 체크리스트 (실제 템플릿)”
👉 “Runbook 샘플 (바로 운영 가능한 수준)”

이렇게 더 실전용으로 만들어 줄게.

Young-Kyoo Kim

engineer

이전 포스트

26A23b

다음 포스트