EP14 [ MinIO S3 + Cilium 기초 과정 ] 네트워크 기초 #2 | Docker Desktop에 Cilium 설치하기 - 기존 CNI 대체 방법

이 글에서는 Docker Desktop 환경에서 Cilium CNI(Container Network Interface)를 설치하고 기존 CNI를 대체하는 방법에 대해 알아보겠습니다. Docker Desktop의 특성을 고려한 Cilium 설치 과정과 주의사항을 상세히 설명합니다.

---

📌 Docker Desktop 환경 이해하기

✅ Docker Desktop의 특성

Docker Desktop은 macOS와 Windows에서 컨테이너와 쿠버네티스를 쉽게 사용할 수 있게 해주는 도구입니다. 그러나 가상화 계층이 있어 표준 리눅스 환경과는 다른 특성을 가집니다.

▶️ Docker Desktop의 주요 특징:

• 경량 가상 머신 위에서 실행 (macOS: HyperKit, Windows: Hyper-V/WSL2)
• 단일 노드 쿠버네티스 클러스터 제공
• 제한된 시스템 자원 (CPU, 메모리, 디스크)
• 기본 CNI로 kindnet 또는 docker-bridge 사용
• 호스트와 컨테이너 간 네트워크 격리

✅ Docker Desktop의 현재 CNI 확인

Cilium 설치 전에 현재 Docker Desktop에서 사용 중인 CNI를 확인해 봅시다.

# 쿠버네티스 노드 정보 확인
kubectl get nodes -o wide

# CNI 관련 Pod 확인
kubectl get pods -n kube-system | grep -i cni

# CNI 설정 확인 (권한 필요)
kubectl debug node/docker-desktop -it --image=ubuntu -- chroot /host ls -la /etc/cni/net.d/

📌 Cilium 설치 준비

✅ 필요 조건 확인

Docker Desktop에 Cilium을 설치하기 전에 몇 가지 필요 조건을 확인해야 합니다.

▶️ 설치 전 요구사항:

• Docker Desktop 최신 버전 (4.13.0 이상 권장)
• 쿠버네티스 활성화 (1.23 이상 권장)
• 충분한 리소스 할당 (최소 4GB 메모리, 2CPUs)
• Helm 설치 (Cilium 설치에 사용)

# 쿠버네티스 버전 확인
kubectl version --short

# 리소스 확인
kubectl describe node docker-desktop | grep -A 5 "Allocatable:"

# Helm 설치 확인
helm version

✅ Docker Desktop 설정 최적화

Cilium이 제대로 작동하도록 Docker Desktop 설정을 최적화합니다.

▶️ 권장 설정:

• 메모리: 최소 4GB (가능하면 6GB 이상)
• CPU: 최소 2코어 (가능하면 4코어 이상)
• 디스크 이미지 크기: 60GB 이상
• 고급 설정에서 Kubernetes 활성화

Docker Desktop 설정 조정 후에는 반드시 재시작하여 변경 사항을 적용해야 합니다.

📌 Cilium CLI 설치

✅ Cilium CLI 도구 설치

Cilium CLI는 Cilium 설치 및 관리를 위한 명령줄 도구입니다.

▶️ macOS에서 설치:

# Homebrew를 사용한 설치
brew install cilium-cli

# 직접 다운로드를 통한 설치
curl -L --remote-name-all https://github.com/cilium/cilium-cli/releases/latest/download/cilium-darwin-amd64.tar.gz
tar xzvf cilium-darwin-amd64.tar.gz
sudo mv cilium /usr/local/bin/

▶️ Windows에서 설치:

# PowerShell을 사용한 설치
$version = (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/cilium/cilium-cli/master/stable.txt" -UseBasicParsing).Content.Trim()
Invoke-WebRequest -Uri "https://github.com/cilium/cilium-cli/releases/download/$version/cilium-windows-amd64.zip" -OutFile "cilium.zip"
Expand-Archive -Path "cilium.zip" -DestinationPath "$Env:USERPROFILE\.cilium"
$Env:PATH += ";$Env:USERPROFILE\.cilium"

✅ Cilium CLI 설정 확인

Cilium CLI가 제대로 설치되었는지 확인합니다.

# Cilium CLI 버전 확인
cilium version

# 출력 예시:
# cilium-cli: v0.15.0 compiled with go1.20.4 on linux/amd64
# cilium image (default): v1.13.4
# cilium image (running): unknown

📌 기존 CNI 제거 방법

✅ 기존 CNI 구성 확인

Cilium을 설치하기 전에 기존 CNI 플러그인을 확인하고 제거해야 합니다.

# 현재 CNI 관련 리소스 확인
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl get daemonset -n kube-system

# CNI 설정 파일 확인 (디버그 Pod 사용)
kubectl debug node/docker-desktop -it --image=busybox -- chroot /host cat /etc/cni/net.d/10-kindnet.conflist

✅ 기존 CNI 제거

기존 CNI 리소스를 제거하여 Cilium 설치를 준비합니다.

# kindnet CNI 제거 (Docker Desktop 기본)
kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/kind/main/pkg/build/node/cni/kindnet.yaml

# 또는 DaemonSet 직접 삭제
kubectl delete daemonset kindnet -n kube-system

# CNI 설정 파일 백업 (디버그 Pod 사용)
kubectl debug node/docker-desktop -it --image=ubuntu -- /bin/bash
# 컨테이너 내에서:
mkdir -p /host/etc/cni/net.d.bak
cp /host/etc/cni/net.d/* /host/etc/cni/net.d.bak/
rm /host/etc/cni/net.d/*

📌 Helm을 사용한 Cilium 설치

✅ Helm 저장소 추가

Helm을 사용하여 Cilium 차트 저장소를 추가합니다.

# Cilium Helm 저장소 추가
helm repo add cilium https://helm.cilium.io/

# 저장소 업데이트
helm repo update

✅ Docker Desktop용 Cilium 구성

Docker Desktop 환경에 최적화된 Cilium 설정을 사용하여 설치합니다.

# Cilium 설치 (Docker Desktop 최적화 설정)
helm install cilium cilium/cilium --version 1.13.4 \
  --namespace kube-system \
  --set kubeProxyReplacement=disabled \
  --set hostServices.enabled=false \
  --set externalIPs.enabled=false \
  --set nodePort.enabled=false \
  --set hostPort.enabled=false \
  --set ipam.mode=kubernetes \
  --set tunnel=vxlan \
  --set bpf.masquerade=false \
  --set installIptablesRules=true \
  --set ipMasqAgent.enabled=false

각 설정 옵션에 대한 설명:

• kubeProxyReplacement=disabled: Docker Desktop에서는 kube-proxy 대체 비활성화
• hostServices.enabled=false: 호스트 서비스 기능 비활성화
• externalIPs.enabled=false: 외부 IP 기능 비활성화
• nodePort.enabled=false: NodePort 기능 비활성화
• hostPort.enabled=false: HostPort 기능 비활성화
• ipam.mode=kubernetes: 쿠버네티스 IPAM 모드 사용
• tunnel=vxlan: VXLAN 터널링 사용
• bpf.masquerade=false: BPF 기반 마스커레이딩 비활성화
• installIptablesRules=true: iptables 규칙 설치 활성화
• ipMasqAgent.enabled=false: IP 마스커레이드 에이전트 비활성화

📌 Cilium CLI를 사용한 설치

✅ Cilium CLI로 설치하기

Helm 대신 Cilium CLI를 사용하여 설치할 수도 있습니다.

# Cilium CLI로 설치
cilium install --version 1.13.4 \
  --set kubeProxyReplacement=disabled \
  --set tunnel=vxlan \
  --set ipam.mode=kubernetes \
  --set hostServices.enabled=false \
  --set externalIPs.enabled=false \
  --set nodePort.enabled=false \
  --set hostPort.enabled=false

✅ 설치 상태 확인

Cilium이 제대로 설치되었는지 확인합니다.

# 설치 상태 확인
cilium status

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

# Cilium 에이전트 로그 확인
kubectl logs -n kube-system -l k8s-app=cilium -c cilium-agent

성공적인 설치 시 출력 예시:

    /¯¯\
 /¯¯\__/¯¯\    Cilium:         OK
 \__/¯¯\__/    Operator:       OK
 /¯¯\__/¯¯\    Hubble Relay:   disabled
 \__/¯¯\__/    ClusterMesh:    disabled

DaemonSet         cilium             Desired: 1, Ready: 1/1, Available: 1/1
Deployment        cilium-operator    Desired: 1, Ready: 1/1, Available: 1/1

📌 Cilium 기능 확인 및 테스트

✅ 연결성 테스트

Cilium 설치 후 네트워크 연결성을 테스트합니다.

# Cilium 연결성 테스트
cilium connectivity test

✅ 테스트 애플리케이션 배포

Cilium 네트워킹을 테스트하기 위한 간단한 애플리케이션을 배포합니다.

apiVersion: v1                   # 쿠버네티스 API 버전
kind: Namespace                  # 리소스 종류
metadata:
  name: cilium-test              # 네임스페이스 이름
---
apiVersion: apps/v1              # 앱 API 그룹 버전
kind: Deployment                 # 리소스 종류
metadata:
  name: nginx                    # Deployment 이름
  namespace: cilium-test         # 네임스페이스
spec:
  selector:
    matchLabels:
      app: nginx                 # Pod 선택자
  replicas: 2                    # 복제본 수
  template:
    metadata:
      labels:
        app: nginx               # Pod 라벨
    spec:
      containers:
      - name: nginx              # 컨테이너 이름
        image: nginx:1.21        # Nginx 이미지
        ports:
        - containerPort: 80      # 컨테이너 포트
---
apiVersion: v1                   # 쿠버네티스 API 버전
kind: Service                    # 리소스 종류
metadata:
  name: nginx                    # Service 이름
  namespace: cilium-test         # 네임스페이스
spec:
  selector:
    app: nginx                   # 대상 Pod 선택자
  ports:
  - port: 80                     # Service 포트
    targetPort: 80               # 대상 Pod 포트
  type: ClusterIP                # Service 유형

# 테스트 애플리케이션 배포
kubectl apply -f nginx-test.yaml

# Pod 상태 확인
kubectl get pods -n cilium-test -o wide

✅ Pod 간 통신 확인

배포된 Pod 간의 통신을 확인합니다.

# 테스트용 임시 Pod 생성
kubectl run -n cilium-test tmp-shell --rm -i --tty --image nicolaka/netshoot -- /bin/bash

# Pod 내부에서 nginx 서비스 접근 테스트
curl nginx.cilium-test.svc.cluster.local

📌 Cilium 설정 사용자 정의

✅ 기본 설정 업그레이드

이미 설치된 Cilium의 설정을 변경하여 업그레이드할 수 있습니다.

# Helm을 사용한 업그레이드
helm upgrade cilium cilium/cilium --version 1.13.4 \
  --namespace kube-system \
  --reuse-values \
  --set hubble.relay.enabled=true \
  --set hubble.ui.enabled=true

✅ Hubble UI 활성화

Cilium의 네트워크 관찰성 도구인 Hubble UI를 활성화합니다.

# Hubble 활성화
cilium hubble enable --ui

# Hubble UI 포트 포워딩
cilium hubble ui

# 또는 kubectl 포트 포워딩
kubectl port-forward -n kube-system svc/hubble-ui 12000:80

Hubble UI는 http://localhost:12000 에서 접근할 수 있습니다.

📌 MinIO와 Cilium 통합

✅ MinIO 배포

Cilium을 사용하는 환경에 MinIO를 배포합니다.

apiVersion: v1                   # 쿠버네티스 API 버전
kind: Namespace                  # 리소스 종류
metadata:
  name: minio-system             # 네임스페이스 이름
---
apiVersion: apps/v1              # 앱 API 그룹 버전
kind: Deployment                 # 리소스 종류
metadata:
  name: minio                    # Deployment 이름
  namespace: minio-system        # 네임스페이스
spec:
  selector:
    matchLabels:
      app: minio                 # Pod 선택자
  replicas: 1                    # 복제본 수
  template:
    metadata:
      labels:
        app: minio               # Pod 라벨
    spec:
      containers:
      - name: minio              # 컨테이너 이름
        image: minio/minio:RELEASE.2023-07-21T21-12-44Z  # MinIO 이미지
        args:
        - server                 # 서버 모드
        - /data                  # 데이터 경로
        env:
        - name: MINIO_ROOT_USER
          value: "minioadmin"    # 루트 사용자
        - name: MINIO_ROOT_PASSWORD
          value: "minioadmin"    # 루트 비밀번호
        ports:
        - containerPort: 9000    # API 포트
          name: api              # 포트 이름
        - containerPort: 9001    # 콘솔 포트
          name: console          # 포트 이름
        volumeMounts:
        - name: data             # 볼륨 이름
          mountPath: /data       # 마운트 경로
      volumes:
      - name: data               # 볼륨 정의
        emptyDir: {}             # 임시 볼륨 (테스트용)
---
apiVersion: v1                   # 쿠버네티스 API 버전
kind: Service                    # 리소스 종류
metadata:
  name: minio                    # Service 이름
  namespace: minio-system        # 네임스페이스
spec:
  selector:
    app: minio                   # 대상 Pod 선택자
  ports:
  - name: api                    # API 포트 이름
    port: 9000                   # Service 포트
    targetPort: api              # 대상 Pod 포트
  - name: console                # 콘솔 포트 이름
    port: 9001                   # Service 포트
    targetPort: console          # 대상 Pod 포트
  type: ClusterIP                # Service 유형

# MinIO 배포
kubectl apply -f minio-deployment.yaml

# 배포 상태 확인
kubectl get pods -n minio-system
kubectl get svc -n minio-system

✅ 네트워크 정책 적용

Cilium을 사용하여 MinIO에 기본 네트워크 정책을 적용합니다.

apiVersion: "cilium.io/v2"       # Cilium API 그룹 버전
kind: CiliumNetworkPolicy        # Cilium 네트워크 정책
metadata:
  name: minio-policy             # 정책 이름
  namespace: minio-system        # 네임스페이스
spec:
  endpointSelector:              # 정책 적용 대상
    matchLabels:
      app: minio                 # MinIO Pod 선택
  ingress:                       # 인바운드 규칙
  - fromEndpoints:               # 소스 엔드포인트
    - matchLabels:               # 라벨 매칭
        io.kubernetes.pod.namespace: minio-system  # 같은 네임스페이스 허용
    toPorts:                     # 대상 포트 규칙
    - ports:                     # 허용할 포트
      - port: "9000"             # API 포트
        protocol: TCP            # TCP 프로토콜
      - port: "9001"             # 콘솔 포트
        protocol: TCP            # TCP 프로토콜
  - fromEndpoints:               # 다른 소스 그룹
    - matchLabels:               # 라벨 매칭
        io.kubernetes.pod.namespace: cilium-test  # 테스트 네임스페이스 허용
    toPorts:                     # 대상 포트 규칙
    - ports:                     # 허용할 포트
      - port: "9000"             # API 포트만 허용
        protocol: TCP            # TCP 프로토콜

# Cilium 네트워크 정책 적용
kubectl apply -f minio-cilium-policy.yaml

# 정책 확인
kubectl get ciliumnetworkpolicies -n minio-system

📌 문제 해결 및 디버깅

✅ 일반적인 문제 해결

Docker Desktop에 Cilium 설치 시 발생할 수 있는 일반적인 문제와 해결 방법입니다.

1. Pod가 Pending 상태에 머무는 경우:
   • 리소스 부족 확인 (메모리, CPU)
   • Docker Desktop 설정에서 리소스 할당 증가
2. Pod 간 통신 불가:
   • Cilium 에이전트 상태 확인
   • 네트워크 정책 설정 확인

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

1. DNS 해결 실패:
   • CoreDNS 상태 확인
   • Cilium과 CoreDNS 상호작용 확인

# CoreDNS 상태 확인
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns

✅ Cilium 디버깅 도구

Cilium 문제 해결을 위한 디버깅 도구를 사용합니다.

# Cilium 클러스터 상태 진단
cilium status --verbose

# Cilium 엔드포인트 확인
cilium endpoint list

# Cilium 서비스 목록 확인
cilium service list

# 특정 Pod의 Cilium 정보 확인
kubectl get pods -n minio-system -o wide
cilium endpoint get <pod-ip>

📌 Docker Desktop 재시작 후 복구

✅ 재시작 후 Cilium 상태 확인

Docker Desktop을 재시작한 후에는 Cilium의 상태를 확인하고 필요한 경우 복구 작업을 수행합니다.

# Docker Desktop 재시작 후 클러스터 상태 확인
kubectl get nodes
kubectl get pods -n kube-system

# Cilium 상태 확인
cilium status

✅ 재설치 또는 복구 과정

문제가 발생한 경우 Cilium을 재설치하거나 복구합니다.

# Cilium 삭제
helm uninstall cilium -n kube-system

# 또는 Cilium CLI 사용
cilium uninstall

# 설정 정리
kubectl debug node/docker-desktop -it --image=ubuntu -- chroot /host rm -rf /etc/cni/net.d/*

# Cilium 재설치
helm install cilium cilium/cilium --version 1.13.4 \
  --namespace kube-system \
  --set kubeProxyReplacement=disabled \
  --set tunnel=vxlan \
  --set ipam.mode=kubernetes

📌 Summary

• Docker Desktop은 경량 가상 머신 기반의 단일 노드 쿠버네티스 환경 제공
• Cilium 설치 전 기존 CNI 구성 확인 및 제거 필요
• Docker Desktop에 적합한 Cilium 설정 옵션 선택 중요
• Helm 또는 Cilium CLI를 통한 설치 가능
• 성공적인 설치 후 연결성 테스트로 네트워크 기능 확인
• Hubble UI 활성화로 네트워크 가시성 확보
• MinIO와 Cilium 통합을 통해 세밀한 네트워크 정책 적용 가능
• 문제 발생 시 Cilium 디버깅 도구를 활용한 신속한 문제 해결