EP04. Cilium 설치하기 | Docker Desktop 기반 실습 환경 구성

이 글에서는 Cilium을 실제로 설치하고 구성하는 방법에 대해 알아보겠습니다. 특히 개발자들이 쉽게 접근할 수 있는 Docker Desktop 기반의 쿠버네티스 환경에서 Cilium을 설치하는 과정을 상세히 다룹니다. Cilium CLI, Helm, YAML 등 다양한 설치 방법을 비교하고, 설치 후 올바르게 구성되었는지 확인하는 방법까지 알아보겠습니다.

---

📌 Cilium 설치 옵션 비교

Cilium을 설치하는 방법은 크게 세 가지가 있습니다. 각 방법의 특징과 장단점을 이해하면 여러분의 환경에 가장 적합한 설치 방법을 선택할 수 있습니다.

✅ Cilium CLI

Cilium CLI는 Cilium 프로젝트에서 공식적으로 제공하는 명령줄 도구로, 설치와 운영을 간소화합니다.

 

▶️ 장점:

• 가장 간단한 설치 방법
• 자동 환경 감지 및 최적화 설정 제공
• 자체 진단 기능 내장

▶️ 단점:

• 세밀한 커스터마이징이 필요한 경우 제한적
• 툴 자체의 추가 설치 필요

✅ Helm 차트

Helm은 쿠버네티스 패키지 관리자로, 복잡한 애플리케이션도 간단하게 설치할 수 있게 해줍니다.

 

▶️ 장점:

• 세밀한 구성 옵션 제공
• 버전 관리 및 롤백 용이
• GitOps 파이프라인과 통합 쉬움

▶️ 단점:

• Helm 사전 지식 필요
• 구성 옵션이 많아 초기 설정이 복잡할 수 있음

✅ YAML 매니페스트

직접 YAML 파일을 적용하는 방식으로, 쿠버네티스의 기본적인 배포 방식입니다.

 

▶️ 장점:

• 쿠버네티스 네이티브 방식
• 배포 과정의 완전한 통제 가능
• 추가 도구 불필요

▶️ 단점:

• 가장 많은 수작업 필요
• 업그레이드 복잡성
• 구성 변경 시 추적 어려움

---

📌 Docker Desktop 환경 준비하기

Cilium을 설치하기 전에 Docker Desktop에서 쿠버네티스 클러스터가 올바르게 구성되어 있어야 합니다.

✅ Docker Desktop 설정 확인

# Docker Desktop 버전 확인
docker --version

# 쿠버네티스 활성화 상태 확인
kubectl cluster-info

✅ 설치 전 필수 체크리스트

1. Docker Desktop의 쿠버네티스 기능이 활성화되어 있는지 확인
2. 쿠버네티스 버전이 v1.19 이상인지 확인
3. 기존 CNI 플러그인이 있다면 제거
4. 충분한 리소스(CPU/메모리) 할당 확인

▶️ Docker Desktop 리소스 권장 설정:

• CPU: 최소 2코어 (4코어 권장)
• 메모리: 최소 4GB (8GB 권장)
• 디스크: 최소 20GB 여유 공간

---

📌 Cilium CLI로 설치하기

Cilium CLI는 가장 간편하게 Cilium을 설치할 수 있는 방법입니다. 개발 환경이나 빠른 테스트를 위해 권장됩니다.

✅ Cilium CLI 설치

Linux/macOS:

# Cilium CLI 다운로드 및 설치
curl -L --remote-name-all https://github.com/cilium/cilium-cli/releases/latest/download/cilium-linux-amd64.tar.gz
sudo tar xzvfC cilium-linux-amd64.tar.gz /usr/local/bin
rm cilium-linux-amd64.tar.gz

macOS (Homebrew):

brew install cilium-cli

Windows:

# PowerShell에서 실행
$ErrorActionPreference = 'Stop'
$ProgressPreference = 'SilentlyContinue'
$version = (Invoke-RestMethod -Uri "https://raw.githubusercontent.com/cilium/cilium-cli/master/stable.txt").Trim()
Invoke-WebRequest -Uri "https://github.com/cilium/cilium-cli/releases/download/$version/cilium-windows-amd64.tar.gz" -OutFile "cilium.tar.gz"
tar -xvzf cilium.tar.gz
Move-Item -Force cilium.exe $Env:USERPROFILE\Documents\WindowsPowerShell
rm cilium.tar.gz

✅ Cilium 설치 실행

# 기본 설치
cilium install

# 설치 상태 확인
cilium status

▶️ 추가 설치 옵션:

# Hubble 활성화 (네트워크 가시성 도구)
cilium install --enable-hubble

# IPv6 활성화
cilium install --ipv6-support=true

# 특정 버전 설치
cilium install --version 1.13.0

✅ 설치 검증

# 상태 확인
cilium status

# Cilium 동작 테스트
cilium connectivity test

성공적인 설치 시 출력:

✅ Cilium is installed and running correctly
✅ All Cilium pods are ready
✅ Cilium is using native routing mode
✅ Cilium is using direct-routing mode
✅ eBPF datapath is enabled

---

📌 Helm으로 Cilium 설치하기

Helm을 통한 설치는 프로덕션 환경이나 세밀한 구성이 필요한 경우에 적합합니다.

✅ Helm 설치 확인

# Helm 버전 확인
helm version

# Helm이 설치되지 않은 경우 설치
curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash

✅ Cilium Helm 리포지토리 추가

# Cilium 리포지토리 추가
helm repo add cilium https://helm.cilium.io/

# 리포지토리 업데이트
helm repo update

✅ Helm 차트로 Cilium 설치

# 기본 설치
helm install cilium cilium/cilium --namespace kube-system

# 값 커스터마이징
helm install cilium cilium/cilium --namespace kube-system \
  --set ipam.mode=kubernetes \
  --set hubble.relay.enabled=true \
  --set hubble.ui.enabled=true

✅ values.yaml 파일 사용하기

복잡한 구성의 경우 values.yaml 파일을 사용하는 것이 좋습니다.

# cilium-values.yaml
kubeProxyReplacement: "strict"  # kube-proxy 완전 대체
ipam:
  mode: "kubernetes"  # 쿠버네티스 IPAM 사용
hubble:
  enabled: true  # Hubble 활성화
  relay:
    enabled: true  # Hubble Relay 활성화
  ui:
    enabled: true  # Hubble UI 활성화
nodePort:
  enabled: true  # NodePort 지원 활성화
externalIPs:
  enabled: true  # ExternalIP 지원 활성화
hostServices:
  enabled: true  # HostPort 지원 활성화

# values.yaml 적용
helm install cilium cilium/cilium --namespace kube-system -f cilium-values.yaml

---

📌 YAML 매니페스트로 설치하기

YAML 매니페스트를 사용한 설치는 가장 세밀한 제어가 필요한 경우나 특수 환경에서 유용합니다.

✅ 매니페스트 다운로드

# 최신 버전 매니페스트 다운로드
curl -LO https://raw.githubusercontent.com/cilium/cilium/v1.13/install/kubernetes/quick-install.yaml

✅ 매니페스트 수정 (선택사항)

필요에 따라 YAML 파일을 열어 설정을 수정할 수 있습니다. 주요 수정 포인트:

• ConfigMap 부분에서 Cilium 동작 모드 설정
• Deployment 부분에서 리소스 할당량 조정
• 특정 환경에 맞는 네트워크 인터페이스 설정

✅ YAML 적용하기

# 매니페스트 적용
kubectl apply -f quick-install.yaml

✅ 배포 상태 확인

# Pod 상태 확인
kubectl get pods -n kube-system -l k8s-app=cilium

# DaemonSet 상태 확인
kubectl get ds -n kube-system cilium

---

📌 설치 후 구성 요소 확인

Cilium이 제대로 설치되었는지 확인하기 위해 주요 구성 요소를 점검해 보겠습니다.

✅ Cilium 에이전트 확인

# Cilium 에이전트 Pod 확인
kubectl get pods -n kube-system -l k8s-app=cilium

정상 출력 예시:

NAME           READY   STATUS    RESTARTS   AGE
cilium-5s2nk   1/1     Running   0          5m
cilium-m7q9z   1/1     Running   0          5m
cilium-x7zv8   1/1     Running   0          5m

✅ Cilium Operator 확인

# Cilium Operator 확인
kubectl get pods -n kube-system -l io.cilium/app=operator

정상 출력 예시:

NAME                               READY   STATUS    RESTARTS   AGE
cilium-operator-6d5fdcdf8f-9c5lh   1/1     Running   0          5m
cilium-operator-6d5fdcdf8f-vpw4s   1/1     Running   0          5m

✅ Cilium 에이전트 로그 확인

# 첫 번째 Cilium 에이전트의 로그 확인
kubectl logs -n kube-system -l k8s-app=cilium --tail=20

정상 로그에는 오류 메시지가 없어야 하며, eBPF 프로그램이 성공적으로 로드되었다는 메시지가 포함되어야 합니다.

✅ CRD 확인

# Cilium 관련 CRD 확인
kubectl get crds | grep cilium

주요 CRD 목록:

ciliumclusterwidenetworkpolicies.cilium.io
ciliumendpoints.cilium.io
ciliumidentities.cilium.io
ciliumnetworkpolicies.cilium.io
ciliumnodes.cilium.io

---

📌 클러스터 내 상태 확인 및 문제 점검

Cilium의 전반적인 상태를 확인하고, 발생할 수 있는 일반적인 문제를 해결하는 방법을 알아보겠습니다.

✅ Cilium CLI로 상태 확인

# 상세 상태 확인
cilium status --wait

# 연결성 테스트
cilium connectivity test

✅ 데이터 경로 확인

# eBPF 맵 확인
cilium bpf endpoints list

# NAT 테이블 확인
cilium bpf nat list

✅ 일반적인 문제 해결

1. Pod가 Pending 상태인 경우:
2. # 노드 상태 확인 kubectl get nodes # 이벤트 확인 kubectl get events -n kube-system
3. 네트워크 정책이 적용되지 않는 경우:
4. # Cilium 엔드포인트 확인 cilium endpoint list # 정책 추적 활성화 cilium config set debug=true
5. CNI 충돌 문제: 기존 CNI 플러그인과 Cilium 간의 충돌이 발생할 수 있습니다.
6. # CNI 설정 확인 ls -la /etc/cni/net.d/
7. 리소스 부족 문제:
8. # 리소스 사용량 확인 kubectl top nodes kubectl top pods -n kube-system

---

📌 Cilium 구성 최적화

Docker Desktop 환경에서 Cilium의 성능을 최적화하는 몇 가지 설정을 살펴보겠습니다.

✅ 리소스 할당 최적화

# Cilium DaemonSet 리소스 요청 및 제한 조정
resources:
  requests:
    cpu: 100m
    memory: 512Mi
  limits:
    cpu: 500m
    memory: 1Gi

✅ 핵심 기능 선택적 활성화

# kube-proxy 대체 모드 활성화
cilium install --kube-proxy-replacement=strict

# 엔드포인트 라우팅 모드 설정
cilium install --tunnel=disabled --routing-mode=native

✅ 모니터링 설정

# Prometheus 메트릭 활성화
cilium install --prometheus-serve-addr=:9090

---

📌 간단한 동작 테스트

Cilium이 제대로 설치되었는지 간단한 테스트를 통해 확인해 보겠습니다.

✅ 기본 연결성 테스트

# 테스트용 Pod 배포
kubectl create ns cilium-test
kubectl run -n cilium-test nginx --image=nginx
kubectl expose -n cilium-test pod nginx --port=80

# 테스트용 클라이언트 Pod 생성 및 연결 테스트
kubectl run -n cilium-test client --rm -ti --image=busybox -- wget -O - nginx

✅ 네트워크 정책 테스트

# 테스트용 네트워크 정책 - deny-all.yaml
apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
  name: "deny-all"
  namespace: cilium-test
spec:
  endpointSelector:
    matchLabels:
      run: nginx
  ingress:
  - fromEndpoints:
    - matchLabels:
        run: client  # client Pod에서만 접근 허용

# 정책 적용
kubectl apply -f deny-all.yaml

# 접근 테스트 (성공해야 함)
kubectl run -n cilium-test client --rm -ti --image=busybox -- wget -O - nginx

# 다른 이름의 Pod로 테스트 (실패해야 함)
kubectl run -n cilium-test attacker --rm -ti --image=busybox -- wget -O - nginx

---

📌 Summary

이번 글에서는 Docker Desktop 환경에서 Cilium을 설치하고 구성하는 방법에 대해 알아보았습니다. 주요 내용을 정리하면 다음과 같습니다:

• Cilium 설치 방법은 Cilium CLI, Helm, YAML 매니페스트 세 가지가 있으며, 각각 사용 목적에 따라 선택할 수 있습니다.
• Docker Desktop 환경에서는 리소스 설정이 중요하며, 최소 요구사항을 충족해야 합니다.
• Cilium CLI는 가장 간편한 설치 방법으로, 개발 환경이나 테스트에 적합합니다.
• Helm은 프로덕션 환경에서 세밀한 구성이 필요할 때 권장됩니다.
• YAML 매니페스트는 가장 높은 수준의 제어가 필요한 경우에 사용합니다.
• 설치 후에는 Cilium 에이전트, Operator, CRD 등 주요 구성 요소를 확인해야 합니다.
• 연결성 테스트와 간단한 네트워크 정책 테스트를 통해 Cilium이 제대로 동작하는지 확인할 수 있습니다.