Kubernetes 위에서 가상머신을 운영하고, 웹 브라우저 하나로 모든 인프라에 접속하는 플랫폼을 구축한 이야기

1. 문제 정의: 인프라 접속의 파편화

IDC에 7대의 물리 서버, 그 위에 Kubernetes 클러스터, 그리고 KubeVirt로 운영하는 가상머신들. 인프라가 커질수록 접속 관리는 복잡해집니다.

기존의 접속 방식:

개발자 A → SSH 클라이언트 → 서버1 (IP 직접 입력)
개발자 A → SSH 클라이언트 → 서버2 (IP 직접 입력)
개발자 B → RDP 클라이언트 → Windows VM (별도 클라이언트 필요)
개발자 C → VNC 클라이언트 → Linux VM (또 다른 클라이언트)
운영팀   → SSH 터널 → VPN → 서버3 (복잡한 경로)

문제점:

• 접속 정보(IP, 포트, 계정)가 개인별로 분산 관리
• SSH, RDP, VNC 각각 다른 클라이언트 필요
• 접속 이력 추적 불가 (누가 언제 어디에 접속했는지)
• 새 팀원 온보딩 시 접속 정보 전달이 번거로움
• VPN + SSH 터널 등 복잡한 네트워크 경로

목표:

• 웹 브라우저 하나로 모든 인프라 접속
• 중앙 집중식 접속 관리 및 권한 제어
• 접속 이력 자동 기록
• Kubernetes 네이티브 배포 (GitOps 호환)

2. 기술 선택: 왜 KubeVirt + Apache Guacamole인가?

2.1 KubeVirt: Kubernetes 위의 가상머신

컨테이너화할 수 없는 워크로드(Windows, 레거시 애플리케이션, GPU 패스스루 테스트 등)를 위해 별도의 하이퍼바이저를 운영하는 대신, KubeVirt를 선택했습니다.

2.2 Apache Guacamole: 클라이언트리스 원격 접속

Apache Guacamole는 클라이언트 설치 없이 웹 브라우저만으로 SSH, RDP, VNC, Telnet 접속을 지원하는 게이트웨이입니다.

Guacamole의 핵심 장점:

• Zero-install: 브라우저만 있으면 됨 (WebSocket 기반)
• 프로토콜 통합: SSH, RDP, VNC, Telnet을 단일 인터페이스로
• REST API: 프로그래밍 가능한 커넥션/사용자 관리
• 세션 녹화: 접속 이력 및 세션 리플레이 지원
• RBAC: 사용자/그룹별 접속 권한 제어
• Kubernetes 호환: 컨테이너 이미지 제공

3. KubeVirt 아키텍처 상세

3.1 컴포넌트 구성

3.2 VM 스토리지: Longhorn-VM StorageClass

VM 디스크는 일반 애플리케이션과 다른 스토리지 전략이 필요합니다:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-vm
provisioner: driver.longhorn.io
parameters:
  numberOfReplicas: "1"          # VM은 단일 복제본 (성능 우선)
  dataLocality: "best-effort"    # 가능하면 VM이 실행되는 노드에 데이터 배치
  staleReplicaTimeout: "30"
  recurringJobSelector: '[{"name":"vm-daily-backup","isGroup":true}]'
allowVolumeExpansion: true        # 디스크 온라인 확장 지원
reclaimPolicy: Delete
volumeBindingMode: Immediate

일반 Longhorn(3 replica) 대신 단일 복제본을 사용한 이유:

• VM 디스크 I/O는 매우 빈번 → 3중 복제는 쓰기 성능 3배 저하
• VM 자체에 스냅샷/백업 전략 적용 (recurringJobSelector)
• dataLocality: best-effort로 네트워크 I/O 최소화
• VM이 stateless가 아닌 경우, 별도 백업 정책으로 데이터 보호

3.3 VM 정의: CRD 기반 선언적 관리

KubeVirt의 핵심은 VM을 Kubernetes CRD로 정의한다는 것입니다:

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: ubuntu-dev-01
  namespace: kubevirt-test
spec:
  runStrategy: Always              # 항상 실행 상태 유지

  dataVolumeTemplates:             # CDI: 이미지 자동 다운로드 → PVC 생성
    - metadata:
        name: ubuntu-dev-01-rootdisk
      spec:
        storage:
          storageClassName: longhorn-vm
          resources:
            requests:
              storage: 30Gi
          accessModes:
            - ReadWriteOnce
        source:
          http:
            url: "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"

  template:
    metadata:
      labels:
        app: ubuntu-dev
    spec:
      domain:
        cpu:
          cores: 4
        resources:
          requests:
            memory: 8Gi
        devices:
          disks:
            - name: rootdisk
              disk:
                bus: virtio          # 최적 성능 (paravirtualized)
            - name: cloudinitdisk
              disk:
                bus: virtio
          interfaces:
            - name: default
              masquerade: {}         # Pod 네트워크 NAT

      networks:
        - name: default
          pod: {}                    # Kubernetes Pod 네트워크 사용

      volumes:
        - name: rootdisk
          dataVolume:
            name: ubuntu-dev-01-rootdisk
        - name: cloudinitdisk
          cloudInitNoCloud:
            userData: |
              #cloud-config
              hostname: ubuntu-dev-01
              user: ubuntu
              ssh_authorized_keys:
                - ssh-ed25519 AAAA... admin@company
              package_update: true
              packages:
                - net-tools
                - curl
                - vim
                - htop

이것이 GitOps와 완벽히 호환되는 이유:

• VM 정의가 YAML 파일 → Git에 커밋 가능
• ArgoCD가 변경 감지 → 자동 적용
• runStrategy로 VM 시작/정지 제어 가능
• dataVolumeTemplates로 OS 이미지 자동 프로비저닝

3.4 Windows VM: UEFI + Secure Boot + TPM

Windows 11은 특별한 하드웨어 요구사항이 있습니다:

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: win11-workstation
spec:
  runStrategy: RerunOnFailure
  template:
    spec:
      domain:
        cpu:
          cores: 8
        resources:
          requests:
            memory: 16Gi
        features:
          smm:
            enabled: true            # System Management Mode
          tpm: {}                    # TPM 2.0 가상 디바이스
        firmware:
          bootloader:
            efi:
              secureBoot: true       # UEFI Secure Boot
        machine:
          type: q35                   # 최신 머신 타입
        devices:
          disks:
            - name: rootdisk
              disk:
                bus: sata            # Windows 호환성
              bootOrder: 1
          interfaces:
            - name: default
              model: e1000e          # Windows 기본 NIC 드라이버
              masquerade: {}

KubeVirt에서 Windows 11을 실행하기 위한 조건:

• firmware.bootloader.efi.secureBoot: true — UEFI Secure Boot 필수
• features.tpm: {} — TPM 2.0 에뮬레이션
• features.smm.enabled: true — SMM (Secure Boot의 전제조건)
• machine.type: q35 — 최신 칩셋 에뮬레이션
• interfaces.model: e1000e — virtio NIC는 Windows 드라이버 없이 동작 불가

3.5 네트워킹: Masquerade 모드

Masquerade 모드에서 VM은 내부적으로 10.0.2.x 대역을 사용하지만, iptables NAT를 통해 Pod IP로 매핑됩니다. 따라서 클러스터 내의 다른 Pod(예: Guacamole의 guacd)에서 Pod IP로 직접 SSH/RDP 접속이 가능합니다.

# VM의 Pod IP 조회
kubectl get vmi ubuntu-dev-01 -n kubevirt-test \
  -o jsonpath='{.status.interfaces[0].ipAddress}'
# 출력: 10.244.93.152

# 클러스터 내부에서 직접 SSH 가능
ssh ubuntu@10.244.93.152

이 특성이 Guacamole + KubeVirt 조합을 강력하게 만듭니다 — guacd가 클러스터 내부에서 VM Pod IP로 직접 프로토콜 연결을 맺습니다.

3.6 CDI: 이미지 자동 임포트

CDI(Containerized Data Importer)는 다양한 소스에서 VM 디스크 이미지를 자동으로 PVC에 임포트합니다:

# HTTP URL에서 Ubuntu 클라우드 이미지 다운로드
source:
  http:
    url: "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"

# 컨테이너 레지스트리에서 이미지 Pull
source:
  registry:
    url: "docker://harbor.example.com/vm-images/ubuntu:22.04"

# 기존 PVC 복제 (Golden Image 패턴)
source:
  pvc:
    name: win11-golden-disk
    namespace: kubevirt-test

Golden Image 패턴:

1. Windows 11을 수동으로 한 번 설치 → golden PVC 생성
2. 이후 새 VM 생성 시 golden PVC를 clone → 빠른 프로비저닝
3. 설치 시간: 30분+ → clone 시간: 1-2분

3.7 kubevirt-manager: 웹 기반 VM 관리

CLI(virtctl) 대신 웹 UI로 VM을 관리할 수 있는 kubevirt-manager를 배포했습니다:

주요 기능:

• VM 생성/시작/정지/삭제 (CRUD)
• NoVNC 웹 콘솔 (브라우저에서 직접 VM 화면 접근)
• DataVolume 관리 (디스크 생성, 리사이즈)
• 네트워크 설정 (Multus 지원)
• SSH 키 관리
• VM Pool (동일 스펙 VM 다수 생성)

인증: NGINX Basic Auth

# NGINX sidecar가 인증 처리
apiVersion: v1
kind: ConfigMap
metadata:
  name: auth-config
data:
  basicauth.conf: |
    server {
        listen 8080;
        location / {
            auth_basic "KubeVirt Manager";
            auth_basic_user_file /etc/nginx/secret.d/.htpasswd;
            proxy_pass http://localhost:8080;
        }
    }

Istio Gateway를 통한 HTTPS 접근:

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: kubevirt-manager-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
    - hosts:
        - kubevirt-mgr.example.com
      port:
        number: 443
        protocol: HTTPS
      tls:
        mode: SIMPLE
        credentialName: kubevirt-mgr-tls    # cert-manager 자동 발급
---
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: kubevirt-manager-vs
spec:
  hosts:
    - kubevirt-mgr.example.com
  gateways:
    - kubevirt-manager-gateway
  http:
    - route:
        - destination:
            host: kubevirt-manager.kubevirt-manager.svc.cluster.local
            port:
              number: 8080
      timeout: 86400s    # 24시간 — NoVNC 장시간 세션 지원

timeout: 86400s 설정은 NoVNC 콘솔 세션이 장시간 유지될 수 있도록 합니다. 기본 Istio timeout(15초)으로는 콘솔 세션이 끊깁니다.

4. Secern Access Portal: Guacamole 백엔드 아키텍처

4.1 Helm Chart 설계

단일 Helm Chart로 Guacamole의 3개 컴포넌트를 패키징했습니다:

kubernetes/charts/secern-access-portal/
├── Chart.yaml                          # v0.1.0, appVersion 1.5.5
├── values.yaml                         # 기본값
├── templates/
│   ├── _helpers.tpl                    # 공통 헬퍼 (fullname, labels)
│   ├── postgresql-secret.yaml          # DB 인증정보
│   ├── postgresql-statefulset.yaml     # PostgreSQL 16
│   ├── postgresql-service.yaml         # ClusterIP :5432
│   ├── guacamole-initdb-configmap.yaml # 스키마 초기화 SQL (791줄)
│   ├── guacd-deployment.yaml           # 프로토콜 데몬
│   ├── guacd-service.yaml              # ClusterIP :4822
│   ├── guacamole-deployment.yaml       # 웹 애플리케이션
│   ├── guacamole-service.yaml          # ClusterIP :8080
│   └── guacamole-service-nodeport.yaml # 조건부 NodePort (Staging)

4.2 PostgreSQL: 스키마 자동 초기화

Guacamole는 PostgreSQL에 커넥션, 사용자, 권한 정보를 저장합니다. 초기 스키마를 ConfigMap으로 마운트하여 첫 실행 시 자동 초기화합니다:

# postgresql-statefulset.yaml (핵심 부분)
spec:
  template:
    metadata:
      annotations:
        sidecar.istio.io/inject: "false"    # TCP 프로토콜 → Sidecar 제외
    spec:
      initContainers:
        - name: init-check
          image: "{{ .Values.postgresql.image }}"
          command: ['sh', '-c']
          args:
            - |
              if [ -f /var/lib/postgresql/data/pgdata/PG_VERSION ]; then
                echo "Database already initialized, skipping..."
              else
                echo "Fresh installation, will initialize..."
              fi
          volumeMounts:
            - name: postgresql-data
              mountPath: /var/lib/postgresql/data

      containers:
        - name: postgresql
          image: "{{ .Values.postgresql.image }}"
          env:
            - name: POSTGRES_USER
              valueFrom:
                secretKeyRef:
                  name: postgresql-secret
                  key: POSTGRES_USER
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: postgresql-secret
                  key: POSTGRES_PASSWORD
            - name: POSTGRES_DB
              valueFrom:
                secretKeyRef:
                  name: postgresql-secret
                  key: POSTGRES_DB
            - name: PGDATA
              value: /var/lib/postgresql/data/pgdata
          volumeMounts:
            - name: postgresql-data
              mountPath: /var/lib/postgresql/data
            - name: initdb-sql
              mountPath: /docker-entrypoint-initdb.d
              readOnly: true

          readinessProbe:
            exec:
              command: ["pg_isready", "-U", "guacamole"]
            initialDelaySeconds: 5
            periodSeconds: 5
          livenessProbe:
            exec:
              command: ["pg_isready", "-U", "guacamole"]
            initialDelaySeconds: 30
            periodSeconds: 10

      volumes:
        - name: initdb-sql
          configMap:
            name: guacamole-initdb

  volumeClaimTemplates:
    - metadata:
        name: postgresql-data
      spec:
        storageClassName: "{{ .Values.postgresql.storageClass }}"
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: "{{ .Values.postgresql.storage }}"

PGDATA 환경변수를 별도로 설정한 이유:

• PostgreSQL 공식 이미지는 마운트 포인트 루트에 lost+found 디렉토리가 있으면 초기화 실패
• PGDATA=/var/lib/postgresql/data/pgdata로 서브디렉토리를 지정하여 우회

4.3 Guacamole 데이터 모델

791줄의 초기화 SQL이 생성하는 핵심 테이블 구조:

핵심 설계 포인트:

• connection_group으로 커넥션을 폴더 구조로 그룹화 (IDC 서버 / VM / 개발 환경 등)
• BALANCING 타입 그룹은 로드밸런싱 지원 (같은 역할의 서버 여러 대)
• connection_parameter에 프로토콜별 설정 저장 (hostname, port, username, private-key 등)
• 모든 접속 이력이 connection_history에 자동 기록

4.4 guacd: 프로토콜 브릿지 데몬

guacd는 C로 작성된 고성능 프로토콜 변환 데몬입니다:

# guacd-deployment.yaml
spec:
  template:
    metadata:
      annotations:
        sidecar.istio.io/inject: "false"    # TCP 전용 → Sidecar 제외
    spec:
      containers:
        - name: guacd
          image: guacamole/guacd:1.5.5
          ports:
            - containerPort: 4822
              protocol: TCP
          readinessProbe:
            tcpSocket:
              port: 4822
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            tcpSocket:
              port: 4822
            initialDelaySeconds: 10
            periodSeconds: 30
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: "1"
              memory: 1Gi

Istio Sidecar를 비활성화한 이유: guacd는 자체 바이너리 프로토콜(Guacamole Protocol)을 사용합니다. Istio의 Envoy sidecar는 이를 HTTP로 해석하려 시도하여 연결이 실패합니다. TCP 전용 서비스에는 sidecar를 주입하지 않는 것이 올바른 패턴입니다.

4.5 Guacamole 웹 애플리케이션

# guacamole-deployment.yaml
spec:
  template:
    spec:
      containers:
        - name: guacamole
          image: guacamole/guacamole:1.5.5
          ports:
            - containerPort: 8080
              name: http-guacamole    # ← 포트 이름이 중요!
          env:
            # guacd 연결 정보
            - name: GUACD_HOSTNAME
              value: "guacd.{{ .Values.namespace }}.svc.cluster.local"
            - name: GUACD_PORT
              value: "4822"
            # PostgreSQL 연결 정보
            - name: POSTGRESQL_HOSTNAME
              value: "postgresql.{{ .Values.namespace }}.svc.cluster.local"
            - name: POSTGRESQL_PORT
              value: "5432"
            - name: POSTGRESQL_DATABASE
              valueFrom:
                secretKeyRef:
                  name: postgresql-secret
                  key: POSTGRES_DB
            - name: POSTGRESQL_USER
              valueFrom:
                secretKeyRef:
                  name: postgresql-secret
                  key: POSTGRES_USER
            - name: POSTGRESQL_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: postgresql-secret
                  key: POSTGRES_PASSWORD
            - name: POSTGRESQL_AUTO_CREATE_ACCOUNTS
              value: "true"

name: http-guacamole — 이 한 줄이 핵심입니다.

Istio는 Service 포트의 name 필드로 프로토콜을 판단합니다:

• http-* → HTTP/1.1로 처리 → L7 라우팅 (VirtualService) 동작
• 이름 없음 또는 tcp-* → TCP로 처리 → L4 패스스루

포트 이름을 지정하지 않으면 Istio가 TCP로 처리하여, IngressGateway에서 503 에러가 발생합니다. 이 문제는 디버깅이 매우 어렵습니다 — Pod은 정상이고, Service도 정상이고, VirtualService도 문법적으로 올바른데, 503이 반환되기 때문입니다.

4.6 Secret 관리: ServerSideApply 호환

# postgresql-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: postgresql-secret
  namespace: {{ .Values.namespace }}
type: Opaque
data:                                        # ← stringData가 아닌 data 사용
  POSTGRES_USER: {{ .Values.postgresql.user | b64enc | quote }}
  POSTGRES_PASSWORD: {{ .Values.postgresql.password | b64enc | quote }}
  POSTGRES_DB: {{ .Values.postgresql.database | b64enc | quote }}

stringData 대신 data + b64enc를 사용한 이유: ArgoCD의 ServerSideApply=true 옵션과 stringData를 함께 사용하면 매 sync마다 diff가 발생합니다. API Server가 stringData를 data(base64)로 변환하는데, ServerSideApply는 이 변환 결과를 "변경됨"으로 감지합니다.

4.7 Multi-Environment 배포

동일한 Helm Chart를 환경별 values로 분리합니다:

# kubernetes/staging/platform/secern-access-portal/values.yaml
namespace: secern-access-portal-staging
istioInjection: false                   # Staging: Sidecar 불필요
postgresql:
  storage: 5Gi                          # 작은 디스크
  password: "staging-password"
nodePort:
  enabled: true                         # NodePort로 접근
  port: 30888

# kubernetes/production/platform/secern-access-portal/values.yaml
namespace: secern-access-portal
postgresql:
  storage: 10Gi                         # 충분한 디스크
  password: "production-password"       # 실제로는 Vault 연동 권장
nodePort:
  enabled: false                        # Istio Gateway 사용

5. Istio 통합: HTTPS + WebSocket

5.1 TLS 인증서 자동 발급

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: accessportal-tls
  namespace: istio-system          # Gateway가 참조하므로 istio-system에 생성
spec:
  secretName: accessportal-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - accessportal.example.com

Certificate를 istio-system 네임스페이스에 생성하는 이유: Istio IngressGateway는 istio-system에서 실행되며, Gateway의 credentialName으로 참조하는 TLS Secret도 같은 네임스페이스에 있어야 합니다.

5.2 Gateway + VirtualService

apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: accessportal-gateway
  namespace: secern-access-portal
spec:
  selector:
    istio: ingressgateway
  servers:
    - hosts:
        - accessportal.example.com
      port:
        name: https-accessportal
        number: 443
        protocol: HTTPS
      tls:
        mode: SIMPLE
        credentialName: accessportal-tls
---
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: accessportal-vs
  namespace: secern-access-portal
spec:
  hosts:
    - accessportal.example.com
  gateways:
    - accessportal-gateway
  http:
    # 1. WebSocket 터널 (Guacamole 세션)
    - match:
        - uri:
            prefix: /guacamole/websocket-tunnel
          headers:
            upgrade:
              exact: websocket
      route:
        - destination:
            host: guacamole.secern-access-portal.svc.cluster.local
            port:
              number: 8080

    # 2. REST API + Web UI
    - match:
        - uri:
            prefix: /guacamole
      route:
        - destination:
            host: guacamole.secern-access-portal.svc.cluster.local
            port:
              number: 8080

WebSocket 라우팅을 별도로 분리한 이유: Guacamole는 두 가지 터널 방식을 지원합니다:

1. WebSocket 터널 (/guacamole/websocket-tunnel): 양방향 실시간 통신, 낮은 지연
2. HTTP 터널 (/guacamole/tunnel): 롱 폴링 기반, WebSocket 불가 환경 폴백

WebSocket 연결은 Upgrade: websocket 헤더로 시작되는 HTTP 요청입니다. Istio VirtualService에서 이 헤더를 명시적으로 매칭하여 WebSocket 트래픽을 올바르게 라우팅합니다.

주의: timeout: 0s는 사용 불가

Istio VirtualService의 timeout에 0s를 설정하면 오류가 발생합니다:

The VirtualService is invalid: spec.http[0].timeout:
Invalid value: "string": must be a valid duration greater than 1ms

WebSocket의 장시간 연결이 필요하면 timeout을 아예 설정하지 않거나(기본값: 무제한), 충분히 큰 값(예: 86400s)을 사용해야 합니다.

6. REST API를 활용한 자동 커넥션 등록

Guacamole의 REST API를 활용하면 커넥션 등록을 자동화할 수 있습니다:

6.1 인증 토큰 획득

TOKEN=$(curl -sk -X POST \
  "https://accessportal.example.com/guacamole/api/tokens" \
  -d "username=guacadmin&password=guacadmin" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['authToken'])")

6.2 SSH 커넥션 등록

API="https://accessportal.example.com/guacamole/api/session/data/postgresql/connections"

# IDC 물리 서버 등록
curl -sk -X POST "$API?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parentIdentifier": "ROOT",
    "name": "CP-01 (Control Plane, GPU)",
    "protocol": "ssh",
    "parameters": {
      "hostname": "x.x.x.221",
      "port": "22"
    },
    "attributes": {
      "max-connections": "5",
      "max-connections-per-user": "3"
    }
  }'

6.3 KubeVirt VM 커넥션 등록

# VM의 Pod IP 조회 후 등록
VM_IP=$(kubectl get vmi test-vm-1 -n kubevirt-test \
  -o jsonpath='{.status.interfaces[0].ipAddress}')

curl -sk -X POST "$API?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"parentIdentifier\": \"ROOT\",
    \"name\": \"test-vm-1 (Ubuntu VM)\",
    \"protocol\": \"ssh\",
    \"parameters\": {
      \"hostname\": \"$VM_IP\",
      \"port\": \"22\"
    },
    \"attributes\": {
      \"max-connections\": \"5\",
      \"max-connections-per-user\": \"3\"
    }
  }"

6.4 Windows RDP 커넥션 등록

WIN_IP=$(kubectl get vmi win11 -n kubevirt-test \
  -o jsonpath='{.status.interfaces[0].ipAddress}')

curl -sk -X POST "$API?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"parentIdentifier\": \"ROOT\",
    \"name\": \"win11 (Windows 11 VM)\",
    \"protocol\": \"rdp\",
    \"parameters\": {
      \"hostname\": \"$WIN_IP\",
      \"port\": \"3389\",
      \"security\": \"nla\",
      \"ignore-cert\": \"true\"
    },
    \"attributes\": {
      \"max-connections\": \"3\",
      \"max-connections-per-user\": \"2\"
    }
  }"

6.5 자동화 스크립트 패턴

#!/bin/bash
# register-connections.sh
# Guacamole에 모든 인프라 커넥션을 자동 등록하는 스크립트

GUAC_URL="https://accessportal.example.com/guacamole"

# 토큰 획득
get_token() {
  curl -sk -X POST "$GUAC_URL/api/tokens" \
    -d "username=$1&password=$2" \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['authToken'])"
}

# SSH 커넥션 등록
register_ssh() {
  local NAME="$1" IP="$2" TOKEN="$3"
  curl -sk -X POST "$GUAC_URL/api/session/data/postgresql/connections?token=$TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"parentIdentifier\": \"ROOT\",
      \"name\": \"$NAME\",
      \"protocol\": \"ssh\",
      \"parameters\": {\"hostname\": \"$IP\", \"port\": \"22\"},
      \"attributes\": {\"max-connections\": \"5\", \"max-connections-per-user\": \"3\"}
    }"
}

# KubeVirt VM 자동 등록
register_kubevirt_vms() {
  local TOKEN="$1"
  # 모든 VMI의 Pod IP를 조회하여 자동 등록
  kubectl get vmi -A -o json | python3 -c "
import sys, json
vmis = json.load(sys.stdin)['items']
for vmi in vmis:
    name = vmi['metadata']['name']
    ns = vmi['metadata']['namespace']
    ip = vmi['status']['interfaces'][0]['ipAddress']
    print(f'{name},{ns},{ip}')
  " | while IFS=',' read name ns ip; do
    register_ssh "$name ($ns)" "$ip" "$TOKEN"
    echo "Registered: $name → $ip"
  done
}

# 실행
TOKEN=$(get_token "guacadmin" "guacadmin")
register_kubevirt_vms "$TOKEN"

7. 전체 트래픽 흐름

브라우저에서 KubeVirt VM에 SSH 접속하는 전체 경로:

1. 사용자 브라우저
   https://accessportal.example.com/guacamole/
   │
2. DNS 조회 (Route53 → MetalLB VIP)
   │
3. Istio IngressGateway (MetalLB VIP:443)
   │ TLS 종료 (Let's Encrypt 인증서)
   │
4. Istio VirtualService 라우팅
   │ /guacamole/* → guacamole.secern-access-portal:8080
   │
5. Guacamole Web App (Tomcat:8080)
   │ 사용자 인증 → REST API → PostgreSQL 조회
   │ WebSocket 터널 수립
   │
6. guacd (Protocol Bridge :4822)
   │ Guacamole Protocol → SSH Protocol 변환
   │
7. KubeVirt VM (Pod IP:22)
   │ virt-launcher Pod → NAT → Guest OS
   │
8. VM 내부 sshd
   │ 셸 세션 시작
   │
9. 결과: 브라우저에서 SSH 터미널 사용 가능!

8. 배포 과정에서 만난 문제들

8.1 NodePort 충돌

증상: ArgoCD Sync 실패, nodePort already allocated 에러 원인: Istio IngressGateway의 status-port가 이미 30880을 사용 해결: Staging NodePort를 30888로 변경

교훈: NodePort 할당 전 반드시 기존 사용 현황 확인

kubectl get svc -A -o jsonpath='{range .items[?(@.spec.type=="NodePort")]}{.metadata.name}{"\t"}{range .spec.ports[*]}{.nodePort}{","}{end}{"\n"}{end}'

8.2 ServerSideApply + stringData 비호환

증상: ArgoCD에서 Secret이 매 sync마다 변경 감지 원인: stringData는 API Server가 data로 변환 → ServerSideApply가 diff로 감지 해결: data + b64enc 사용

# Before (문제)
stringData:
  password: mypassword

# After (해결)
data:
  password: {{ "mypassword" | b64enc }}

8.3 Istio 503 에러 (포트 이름 누락)

증상: Pod 정상, Service 정상, VirtualService 정상인데 503 반환 원인: Service 포트에 name이 없어서 Istio가 TCP로 처리 → L7 라우팅 실패 해결: name: http-guacamole 추가

ports:
  - name: http-guacamole    # http- 접두사 필수
    port: 8080
    targetPort: 8080

8.4 VirtualService timeout: 0s 무효

증상: apply 시 validation 에러 원인: Istio는 timeout 값으로 0 이하를 허용하지 않음 (최소 1ms) 해결: timeout 행 제거 (기본값: 무제한)

8.5 Namespace OutOfSync (ArgoCD)

증상: 모든 리소스가 정상인데 ArgoCD가 계속 OutOfSync 표시 원인: Helm Chart의 Namespace 템플릿과 ArgoCD의 CreateNamespace=true가 동시에 Namespace를 관리하려 시도 해결: Namespace 템플릿 제거 + CreateNamespace=true 유지 + ArgoCD tracking 어노테이션 정리

8.6 .gitignore가 Secret 템플릿 차단

증상: Secret YAML 파일이 git add되지 않음 원인: .gitignore의 *secret* 패턴이 Helm 템플릿까지 매칭 해결: git add -f 사용

git add -f kubernetes/charts/secern-access-portal/templates/postgresql-secret.yaml

9. 프론트엔드 확장 계획

현재는 Guacamole 기본 UI를 사용하지만, React 기반 커스텀 프론트엔드를 개발하여 더 나은 UX를 제공할 예정입니다:

# VirtualService에 프론트엔드 라우팅 추가 (예정)
http:
  # WebSocket 터널 (기존)
  - match:
      - uri:
          prefix: /guacamole/websocket-tunnel
    route:
      - destination:
          host: guacamole:8080

  # REST API (기존)
  - match:
      - uri:
          prefix: /guacamole/api
    route:
      - destination:
          host: guacamole:8080

  # React SPA (신규)
  - match:
      - uri:
          prefix: /
    route:
      - destination:
          host: frontend.secern-access-portal.svc.cluster.local
          port:
            number: 80

커스텀 프론트엔드의 장점:

• 회사 브랜딩 적용
• 통합 대시보드 (VM 상태 + 커넥션 목록 + 모니터링 한 화면)
• LDAP/SSO 연동 인증
• 커넥션 그룹 시각화
• 세션 녹화 재생 UI

10. 아키텍처 요약

마무리

KubeVirt와 Apache Guacamole를 조합하여 다음을 달성했습니다:

1. 통합 접속: 7대 물리 서버 + Ubuntu VM + Windows VM을 웹 브라우저 하나로 접속
2. Zero-install: SSH 클라이언트, RDP 클라이언트, VNC 뷰어 설치 불필요
3. 중앙 관리: 커넥션, 사용자, 권한을 한 곳에서 관리
4. 감사 추적: 모든 접속 이력 자동 기록
5. GitOps 호환: Helm Chart + ArgoCD로 완전 선언적 배포
6. 보안: HTTPS (Let's Encrypt), WebSocket Secure, RBAC

핵심 기술 조합:

• KubeVirt v1.7.0 — VM을 Pod처럼 관리
• CDI v1.64.0 — 이미지 자동 임포트
• Apache Guacamole 1.5.5 — 클라이언트리스 원격 접속
• Istio — HTTPS 종료 + WebSocket 라우팅
• cert-manager — TLS 자동 발급/갱신
• PostgreSQL 16 — 커넥션/인증 데이터 저장
• ArgoCD Multi-Source — 환경별 배포 자동화

기술 스택: KubeVirt v1.7.0 | CDI v1.64.0 | Apache Guacamole 1.5.5 | guacd 1.5.5 | PostgreSQL 16 | Istio VirtualService (WebSocket) | cert-manager (DNS-01) | Helm Chart | ArgoCD Multi-Source Application | Longhorn-VM StorageClass | kubevirt-manager

IDC 환경에서 Bare-Metal Kubernetes 클러스터를 구축하고, GitOps 기반의 완전 자동화된 인프라를 설계한 과정을 공유합니다.

1. 왜 On-Premise Kubernetes인가?

클라우드 환경이 대세인 시대에 굳이 On-Premise를 선택한 이유가 있습니다. GPU 워크로드(RTX 3090, Titan, T4)를 활용한 얼굴인식 시스템(FRS)을 운영해야 했고, IDC에 이미 확보된 물리 서버를 최대한 활용하면서도 클라우드 수준의 운영 자동화를 달성하는 것이 목표였습니다.

핵심 설계 원칙:

• 모든 구성요소 3중화 (Single Point of Failure 제거)
• GitOps 기반 선언적 인프라 관리
• 물리 DMZ 네트워크 격리로 보안 확보
• GPU 노드의 효율적 스케줄링

2. 클러스터 토폴로지

2.1 노드 구성

7대의 물리 서버로 구성된 Kubernetes v1.30.4 클러스터입니다.

2.2 고가용성 구성

# API Server HA: kube-vip
apiVersion: v1
kind: Pod
metadata:
  name: kube-vip
spec:
  containers:
    - name: kube-vip
      image: ghcr.io/kube-vip/kube-vip:v0.8.0
      args:
        - manager
      env:
        - name: vip_address
          value: "<VIP_ADDRESS>"     # Virtual IP
        - name: port
          value: "6443"
        - name: vip_arp
          value: "true"              # L2 ARP 기반

Control Plane 3대가 kube-vip을 통해 단일 VIP를 공유합니다. 리더 노드 장애 시 ARP 기반으로 즉시 failover되어 API Server 무중단을 보장합니다.

3. 네트워크 아키텍처

3.1 물리 DMZ 격리

핵심 보안 설계:

• 인터넷에 직접 노출 없음 — VPN 터널(WireGuard)을 통해서만 인바운드 접근
• 아웃바운드: NAT를 통한 WAN2 경유 (직접 인터넷 연결 불가)
• 물리 스위치 단에서 DMZ 네트워크 격리
• Calico CNI + NetworkPolicy로 Pod 레벨 마이크로세그멘테이션

3.2 MetalLB L2 로드밸런서

클라우드의 ELB/NLB가 없는 Bare-Metal 환경에서 MetalLB가 LoadBalancer 타입 Service를 지원합니다.

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: default-pool
  namespace: metallb-system
spec:
  addresses:
    - x.x.x.180-x.x.x.200    # 21개 IP 풀
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: default
  namespace: metallb-system
spec:
  ipAddressPools:
    - default-pool

L2 Advertisement 모드로 동작하여, Istio IngressGateway가 MetalLB VIP를 할당받아 외부 트래픽을 수신합니다.

4. GitOps: ArgoCD 기반 선언적 인프라

4.1 전체 구조

infrastructure/
├── argocd/
│   ├── applications/          # 26개 ArgoCD Application
│   ├── applicationsets/       # Directory Generator 기반 자동 생성
│   ├── projects/              # 3개 RBAC 프로젝트
│   └── secrets/               # 레포지토리 인증정보
├── kubernetes/
│   ├── charts/                # Custom Helm Charts
│   │   ├── nicepayment-frs/   # FRS 우산형 차트 (4개 서브차트)
│   │   └── secern-access-portal/  # Guacamole 백엔드
│   ├── production/            # 67개 Production 매니페스트
│   │   ├── databases/         # MariaDB HA, MaxScale
│   │   ├── cache/             # Redis 6-node Cluster
│   │   ├── monitoring/        # Prometheus Stack
│   │   ├── logging/           # OpenSearch + Vector
│   │   ├── istio/             # Service Mesh 설정
│   │   ├── vault/             # Secret Management
│   │   └── ...
│   └── staging/               # Staging 환경 (단일 인스턴스)
└── docs/                      # 18개 운영 문서

4.2 ArgoCD 프로젝트 RBAC

3개의 AppProject로 권한을 분리합니다:

# infrastructure-project: 데이터베이스, 캐시, 스토리지
# platform-project: 모니터링, 서비스메시, 시크릿, DNS
# apps-project: 비즈니스 애플리케이션

4.3 26개 Application 목록

Infrastructure (5):

• local-path-provisioner — 로컬 SSD 스토리지 프로비저닝
• harbor — 프라이빗 컨테이너/Helm 레지스트리 (S3 백엔드)
• opensearch-logs — 로그/트레이스 집계 클러스터
• opensearch-vector-staging — 벡터 DB (AI 임베딩)

Platform (12):

• sail-operator — Istio 라이프사이클 관리
• istio — Istio 컨트롤 플레인 (v1.24.3)
• istio-ingressgateway — 인그레스 게이트웨이 (MetalLB LB)
• istio-resources — Gateway/VirtualService/DestinationRule
• kiali-server — 서비스 메시 시각화
• prometheus-stack — Prometheus + Grafana + Alertmanager (v79.5.0)
• otel-operator — OpenTelemetry 오퍼레이터
• otel-collector — OTEL 데이터 수집기
• otel-instrumentation — Pod 자동 계측 규칙
• vault — HashiCorp Vault HA
• external-secrets — Vault → K8s Secret 동기화
• external-dns — Route53 DNS 자동화
• metallb — Bare-Metal 로드밸런서

Applications (3+):

• nicepayment-frs — 얼굴인식 시스템 (멀티 차트)
• secern-access-portal — 원격 접속 포털 (Staging + Production)

4.4 Multi-Source Application 패턴

하나의 Helm 차트를 환경별 values로 재사용하는 ArgoCD Multi-Source 패턴을 적용했습니다:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: secern-access-portal
  namespace: argocd
spec:
  project: platform
  sources:
    # Source 1: Helm Chart
    - repoURL: https://github.com/org/infrastructure.git
      targetRevision: HEAD
      path: kubernetes/charts/secern-access-portal
      helm:
        releaseName: secern-access-portal
        valueFiles:
          - $values/kubernetes/production/platform/secern-access-portal/values.yaml
    # Source 2: Values Reference
    - repoURL: https://github.com/org/infrastructure.git
      targetRevision: HEAD
      ref: values          # $values로 참조 가능
  destination:
    server: https://kubernetes.default.svc
    namespace: secern-access-portal
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true    # 대규모 리소스 호환성
  ignoreDifferences:
    - group: apps
      kind: StatefulSet
      jsonPointers:
        - /spec/volumeClaimTemplates    # immutable field 무시

ServerSideApply를 사용한 이유:

• kubectl apply는 Last-Applied-Configuration 어노테이션 기반 → 대규모 ConfigMap에서 크기 초과 오류
• ServerSideApply는 필드 소유권(Field Ownership) 기반 → 충돌 감지 및 해결이 깔끔
• 단, Secret에서 stringData를 사용하면 base64 인코딩 diff가 발생하므로 반드시 data + b64enc 사용

4.5 GitOps 워크플로우

핵심 규칙:

1. kubectl로 직접 수정 금지 — 반드시 Git → ArgoCD Sync
2. Production은 Manual Sync (안전성 우선)
3. Staging은 Auto Sync + Self-Heal + Prune (빠른 반복)
4. 긴급 상황 시 kubectl 허용하되, 즉시 Git에 동기화

5. 3중화 데이터베이스: MariaDB HA Cluster

5.1 아키텍처

5.2 GTID 기반 복제

# MariaDB Master 설정
[mysqld]
server-id = 1
log-bin = mysql-bin
binlog-format = ROW
gtid-strict-mode = 1
log-slave-updates = ON

# Slave 설정
[mysqld]
server-id = 2      # Slave마다 고유
read-only = 1
log-bin = mysql-bin
relay-log = relay-bin
gtid-strict-mode = 1
log-slave-updates = ON

GTID(Global Transaction ID)를 선택한 이유:

• 바이너리 로그 파일명+위치 기반 복제는 failover 시 정확한 위치 찾기 어려움
• GTID는 트랜잭션 단위 고유 식별자 → Master 변경 시에도 정확한 복제 지점 보장
• gtid-strict-mode=1: 비-트랜잭션 엔진(MyISAM) 혼용 방지

5.3 MaxScale: 자동 Failover + Read/Write Split

# MaxScale 설정 핵심
[ReadWriteSplit-Service]
type = service
router = readwritesplit
servers = master, slave1, slave2
user = maxscale_user
password = ****
master_failure_mode = fail_on_write
master_reconnection = true

[MariaDB-Monitor]
type = monitor
module = mariadbmon
servers = master, slave1, slave2
auto_failover = true
auto_rejoin = true
failcount = 3               # 3회 실패 후 failover
monitor_interval = 2000ms    # 2초 간격 헬스체크

MaxScale의 역할:

1. Read/Write Split: SELECT → Slave로 분산, INSERT/UPDATE/DELETE → Master로
2. Auto-Failover: Master 장애 시 Slave를 자동 승격 (failcount=3, 약 6초)
3. Auto-Rejoin: 복구된 이전 Master를 자동으로 Slave로 재합류
4. Connection Pooling: 백엔드 연결 재사용

5.4 Node-Pinning 전략

# StatefulSet에서 nodeSelector로 고정
spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/hostname: worker-01    # Master 전용
      tolerations: []

DB를 특정 노드에 고정하는 이유:

• local-path StorageClass 사용 → 데이터가 로컬 SSD에 저장
• 노드 간 이동 시 데이터 손실 위험 (네트워크 스토리지가 아니므로)
• SSD 직접 I/O로 최대 성능 확보
• 각 노드의 디스크 용량/성능을 개별 관리 가능

6. 3중화 캐시: Redis 6-Node Cluster

6.1 아키텍처

6.2 OpsTree Redis Operator

직접 redis-cli --cluster create를 하는 대신, OpsTree Redis Operator가 선언적으로 클러스터를 관리합니다:

apiVersion: redis.redis.opstreelabs.in/v1beta2
kind: RedisCluster
metadata:
  name: redis-cluster
  namespace: redis
spec:
  clusterSize: 3                   # 3 Leader + 3 Follower = 6 pods
  clusterVersion: v7
  persistenceEnabled: true
  kubernetesConfig:
    image: redis:7.2.7
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 512Mi
  storage:
    volumeClaimTemplate:
      spec:
        storageClassName: local-path
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi

Operator 사용의 장점:

• 노드 추가/제거 시 자동 슬롯 리밸런싱
• Leader 장애 시 Follower 자동 승격
• Rolling Update 시 데이터 무손실 보장
• RedisCluster CRD로 선언적 관리 (GitOps 호환)

7. Secret Management: Vault 3중화

7.1 HA Raft 아키텍처

7.2 Helm Values (HA 구성)

server:
  ha:
    enabled: true
    replicas: 3
    raft:
      enabled: true
      setNodeId: true
      config: |
        ui = true
        listener "tcp" {
          tls_disable = 1
          address     = "[::]:8200"
          cluster_address = "[::]:8201"
        }
        storage "raft" {
          path = "/vault/data"
          retry_join {
            leader_api_addr = "http://vault-0.vault-internal:8200"
          }
          retry_join {
            leader_api_addr = "http://vault-1.vault-internal:8200"
          }
          retry_join {
            leader_api_addr = "http://vault-2.vault-internal:8200"
          }
        }
        service_registration "kubernetes" {}
  resources:
    requests:
      memory: 256Mi
      cpu: 250m
    limits:
      memory: 512Mi
  dataStorage:
    enabled: true
    storageClass: longhorn
    size: 10Gi

7.3 Shamir Seal 운용

# 초기화 (1회)
vault operator init -key-shares=5 -key-threshold=3

# Pod 재시작 시 Unseal (3개 키 필요)
vault operator unseal <key-1>
vault operator unseal <key-2>
vault operator unseal <key-3>

# 3개 Pod 모두 개별 Unseal 필요

5/3 Threshold를 선택한 이유:

• 5개 키 중 3개로 Unseal 가능 → 2개 키 분실에도 복구 가능
• 키를 5명의 관리자에게 분산 보관 → 단독으로 Unseal 불가 (보안)
• Auto-Unseal(AWS KMS 등)을 사용하지 않은 이유: On-Premise 환경에서 외부 의존성 최소화

7.4 External Secrets Operator 연동

Vault의 시크릿을 Kubernetes Secret으로 자동 동기화합니다:

# ClusterSecretStore: Vault 연결 정의
apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: vault-backend
spec:
  provider:
    vault:
      server: "http://vault.vault:8200"
      path: "secret"
      version: "v2"
      auth:
        tokenSecretRef:
          name: vault-token
          namespace: external-secrets
          key: token
---
# ExternalSecret: 어떤 시크릿을 동기화할지 정의
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: frs-secrets
  namespace: nicepayment-frs
spec:
  refreshInterval: 1h              # 1시간마다 Vault 동기화
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: frs-secrets
    creationPolicy: Owner
  data:
    - secretKey: DB_PASSWORD
      remoteRef:
        key: secret/app/db
        property: password
    - secretKey: API_KEY
      remoteRef:
        key: secret/app/api
        property: apiKey

Secret 관리 흐름:

Vault에 Git으로 커밋되는 시크릿은 없습니다. ExternalSecret의 remoteRef만 Git에 저장되고, 실제 값은 Vault에서 런타임에 주입됩니다.

8. Service Mesh: Istio (Sail Operator)

8.1 왜 Sail Operator인가?

기존 istioctl install이나 Helm 직접 설치 대신 Sail Operator를 선택했습니다:

8.2 Istio 구성

apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  version: v1.24.3
  namespace: istio-system
  values:
    pilot:
      resources:
        requests:
          cpu: 500m
          memory: 2Gi
    meshConfig:
      accessLogFile: /dev/stdout
      accessLogFormat: |
        {"timestamp":"%START_TIME%","method":"%REQ(:METHOD)%",
         "path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%",
         "response_code":"%RESPONSE_CODE%",
         "duration":"%DURATION%"}
      outboundTrafficPolicy:
        mode: ALLOW_ANY
      enablePrometheusMerge: true
      defaultConfig:
        tracing:
          sampling: 10    # 10% 샘플링

8.3 IngressGateway 구성

apiVersion: sailoperator.io/v1
kind: IstioRevisionTag
metadata:
  name: default
spec:
  targetRef:
    kind: Istio
    name: default
---
# IngressGateway: MetalLB LoadBalancer
spec:
  values:
    service:
      type: LoadBalancer      # MetalLB에서 VIP 할당
      ports:
        - name: http
          port: 80
          targetPort: 8080
        - name: https
          port: 443
          targetPort: 8443
        - name: tcp-cupaybot
          port: 6000           # TCP 소켓 서비스
          targetPort: 6000

8.4 TLS 인증서 자동화

# cert-manager + Let's Encrypt (DNS-01)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: harbor-tls
  namespace: istio-system
spec:
  secretName: harbor-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - harbor.example.com
---
# Gateway에서 TLS 종료
apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: harbor-gateway
spec:
  selector:
    istio: ingressgateway
  servers:
    - port:
        number: 443
        name: https
        protocol: HTTPS
      tls:
        mode: SIMPLE
        credentialName: harbor-tls    # cert-manager가 생성한 Secret
      hosts:
        - harbor.example.com

DNS-01 Challenge를 사용한 이유:

• HTTP-01은 인터넷에서 서버로 직접 접근 필요 → DMZ 환경에서 불가
• DNS-01은 Route53 API로 TXT 레코드 추가 → 인바운드 접근 없이 인증서 발급
• 와일드카드 인증서 지원

9. Observability: 3계층 관측 파이프라인

9.1 전체 아키텍처

9.2 OpenTelemetry 자동 계측

코드 수정 없이 OTEL Agent를 주입하여 트레이싱/메트릭을 수집합니다:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: otel-instrumentation
  namespace: nicepayment-frs
spec:
  exporter:
    endpoint: http://otel-collector.istio-system:4317
  propagators:
    - tracecontext
    - baggage
    - b3multi
  sampler:
    type: parentbased_traceidratio
    argument: "1"              # 100% 샘플링
  java:
    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest
    env:
      - name: OTEL_LOGS_EXPORTER
        value: otlp
      - name: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
        value: http://otel-collector.istio-system:4317

Pod에 어노테이션 한 줄만 추가하면 자동 계측됩니다:

metadata:
  annotations:
    instrumentation.opentelemetry.io/inject-java: "true"

9.3 데이터 흐름 상세

10. 스토리지 전략

10.1 이중 StorageClass 운용

선택 기준:

• DB/캐시: 자체 복제 메커니즘이 있으므로 → local-path (스토리지 레벨 복제 불필요, 최대 IOPS)
• 상태 저장 서비스: 자체 복제 없음 → longhorn 3 replica (스토리지 레벨 HA)
• VM 디스크: 성능 우선 + 단일 복제로 충분 → longhorn-vm 1 replica

10.2 Harbor 레지스트리: S3 백엔드

컨테이너 이미지는 로컬 스토리지가 아닌 AWS S3에 저장합니다:

# Harbor Helm Values
persistence:
  imageChartStorage:
    type: s3
    s3:
      region: ap-northeast-2
      bucket: harbor-registry-bucket
      accesskey: ****
      secretkey: ****
      rootdirectory: /harbor

S3를 선택한 이유:

• 컨테이너 이미지는 용량이 크고 계속 증가 → 로컬 디스크 한계
• S3는 사실상 무제한 용량 + 자동 내구성(11-9s)
• 이미지 pull 시 네트워크 latency는 있지만, pull은 배포 시에만 발생하므로 수용 가능

11. 프라이빗 컨테이너 레지스트리: Harbor

11.1 구성

# Harbor Helm Values 핵심
expose:
  type: ingress         # Istio Gateway 경유
  tls:
    certSource: secret
    secret:
      secretName: harbor-tls    # cert-manager 발급
  ingress:
    className: istio
    hosts:
      core: harbor.example.com

# Trivy 취약점 스캔
trivy:
  enabled: true
  autoScan: true

Harbor가 제공하는 기능:

• 프라이빗 Docker/Helm 레지스트리
• Trivy 기반 이미지 취약점 자동 스캔
• 이미지 서명 (Content Trust)
• 복제 정책 (다른 레지스트리와 동기화)
• RBAC (프로젝트/사용자별 권한)

12. DNS 자동화: External DNS

Route53 DNS 레코드를 Kubernetes 리소스에서 자동으로 관리합니다:

# External DNS ArgoCD Application
spec:
  sources:
    - repoURL: https://kubernetes-sigs.github.io/external-dns/
      chart: external-dns
      helm:
        valuesObject:
          provider:
            name: aws
          env:
            - name: AWS_ACCESS_KEY_ID
              valueFrom:
                secretKeyRef:
                  name: route53-credentials
                  key: access-key
            - name: AWS_SECRET_ACCESS_KEY
              valueFrom:
                secretKeyRef:
                  name: route53-credentials
                  key: secret-key
          domainFilters:
            - example.com
          policy: sync           # 레코드 삭제도 자동
          txtOwnerId: k8s-cluster

Gateway 또는 VirtualService를 생성하면 자동으로 Route53에 A 레코드가 생성됩니다.

13. Ansible: 노드 프로비저닝 자동화

클러스터 초기 구축은 Ansible로 자동화했습니다:

ansible/
├── inventory/
│   └── hosts.yml          # 7노드 인벤토리
├── playbooks/
│   ├── 01-common.yml      # 공통 설정 (NTP, swap off, kernel)
│   ├── 02-containerd.yml  # 컨테이너 런타임
│   ├── 03-kubernetes.yml  # kubeadm, kubelet, kubectl
│   ├── 04-init-master.yml # 첫 번째 CP 초기화
│   ├── 05-join-cp.yml     # 나머지 CP 조인
│   └── 06-join-worker.yml # Worker 조인
└── roles/
    └── common/            # 재사용 가능한 역할

자동화된 작업:

• Swap 비활성화 + kernel module 로드 (br_netfilter, overlay)
• containerd 설치 및 SystemdCgroup 설정
• kubeadm init (첫 CP) → certificate-key 공유 → 나머지 CP join
• Worker node join
• Calico CNI 배포

14. 운영 모니터링 대시보드

마무리

7대의 물리 서버에서 시작하여, 클라우드 수준의 자동화된 인프라를 구축했습니다:

• 26개 ArgoCD Application으로 모든 인프라를 선언적으로 관리
• 3중화 Control Plane, MariaDB, Redis, Vault, OpenSearch
• Istio Service Mesh로 트래픽 관리, mTLS, 분산 트레이싱
• OpenTelemetry로 코드 수정 없는 자동 계측
• 물리 DMZ + VPN으로 엔터프라이즈급 네트워크 보안
• Vault + External Secrets로 시크릿 중앙 관리

On-Premise라고 해서 클라우드 대비 운영 효율이 떨어질 필요는 없습니다. 올바른 도구와 아키텍처를 선택하면, 오히려 하드웨어를 직접 제어할 수 있는 장점(GPU 스케줄링, 로컬 SSD 성능, 네트워크 토폴로지 최적화)을 누릴 수 있습니다.

기술 스택 요약: Kubernetes v1.30.4 | ArgoCD | Istio v1.24.3 (Sail Operator) | HashiCorp Vault HA | MariaDB GTID Replication + MaxScale | Redis Cluster 6-node | OpenSearch 3-node | Prometheus + Grafana | OpenTelemetry | Vector | Harbor (S3) | MetalLB | Calico | KubeVirt | cert-manager | External DNS | Longhorn | Ansible

1. 마이크로서비스의 한계와 Service Mesh의 필요성
2. Istio란 무엇인가
3. Istio 아키텍처 깊이 이해하기
4. 실습: Istio 환경 구축
5. Gateway와 VirtualService 완벽 이해
6. 트래픽 흐름 완전 분석
7. Istio의 강력한 기능들
8. 다음 계획

1. 마이크로서비스의 한계와 Service Mesh의 필요성

마이크로서비스 환경의 복잡성

현대 클라우드 네이티브 애플리케이션은 수십, 수백 개의 마이크로서비스로 구성됩니다. 각 서비스는 독립적으로 배포되고 확장되지만, 이로 인해 새로운 문제들이 발생합니다:

전통적인 모놀리식 아키텍처:
┌─────────────────────────────┐
│     Single Application   │
│  ┌─────┐ ┌─────┐ ┌─────┐   │
│  │ UI  │ │Logic│ │ DB  │  │
│  └─────┘ └─────┘ └─────┘   │
└─────────────────────────────┘
문제: 단일 장애점, 확장성 제한

마이크로서비스 아키텍처:
┌─────┐    ┌─────┐      ┌─────┐
│User │───▶│Order│───▶│ Pay │
│  UI │    │ Svc │     │ Svc │
└─────┘    └──┬──┘      └─────┘
              │
              ├─────▶┌─────┐
              │      │Notif│
              │      └─────┘
              │
              └─────▶┌─────┐
                     │ Log │
                     └─────┘
문제: 서비스 간 통신 복잡도 폭발!

개발자가 직면하는 문제들

1. 서비스 간 통신 관리의 복잡성

# 각 서비스 코드에 반복적으로 작성해야 하는 코드들

# 재시도 로직
for retry in range(3):
    try:
        response = requests.get('http://payment-service/pay')
        break
    except TimeoutError:
        if retry == 2:
            raise
        time.sleep(2 ** retry)

# 타임아웃 설정
response = requests.get('http://service', timeout=3.0)

# 서킷 브레이커
if circuit_breaker.is_open('payment-service'):
    return fallback_response()

# 로깅
logger.info(f"Calling {service_name} at {timestamp}")

# 메트릭 수집
metrics.increment('http_requests_total')

문제점:

• 모든 서비스에 동일한 로직 중복 구현
• 언어별로 다른 라이브러리 사용 (Java, Python, Go...)
• 업그레이드 시 모든 서비스 수정 필요
• 일관성 없는 구현

2. 관측성(Observability) 부재

• "어느 서비스에서 장애가 발생했나?"
• "왜 응답 시간이 느려졌나?"
• "서비스 A → B → C로 요청이 흐르는데 어디서 병목인가?"

3. 보안 문제

• 서비스 간 통신 암호화 (mTLS) 수동 구현
• 인증/인가 로직 각 서비스에 구현
• 인증서 관리의 복잡성

Service Mesh가 해결하는 방법

핵심 아이디어: 네트워크 기능을 애플리케이션 코드에서 분리

Service Mesh 없이:
┌─────────────────────────────┐
│   Application Code        │
│  ┌──────────────────────┐   │
│  │  Business Logic    │   │
│  ├──────────────────────┤   │
│  │ ❌ Retry Logic      │  │ ← 중복 코드!
│  │ ❌ Timeout          │  │
│  │ ❌ Metrics          │  │
│  │ ❌ Tracing          │  │
│  │ ❌ mTLS             │  │
│  └──────────────────────┘   │
└─────────────────────────────┘

Service Mesh와 함께:
┌─────────────────────────────┐
│   Application Code        │
│  ┌──────────────────────┐   │
│  │  Business Logic     │  │ ← 비즈니스 로직만!
│  │  (순수 코드)         │  │
│  └──────────────────────┘   │
└─────────────────────────────┘
              ↕
┌─────────────────────────────┐
│      Sidecar Proxy        │
│  ┌──────────────────────┐   │
│  │ ✅ Retry Logic      │  │ ← 인프라 레벨에서 처리
│  │ ✅ Timeout          │  │
│  │ ✅ Metrics          │  │
│  │ ✅ Tracing          │  │
│  │ ✅ mTLS             │  │
│  └──────────────────────┘   │
└─────────────────────────────┘

2. Istio란 무엇인가

Istio 정의

Istio는 오픈소스 Service Mesh 플랫폼으로, 마이크로서비스 간 통신을 관리하고 보안, 관측성, 트래픽 제어를 제공하는 인프라 레이어입니다.

주요 특징:

• 애플리케이션 코드 변경 없음: 기존 서비스 그대로 사용
• 언어 독립적: Java, Python, Go, Node.js 등 모두 지원
• 선언적 구성: YAML로 트래픽 정책 정의
• 강력한 관측성: 메트릭, 로그, 분산 추적 자동 제공

Istio가 제공하는 핵심 기능

┌──────────────────────────────────────────────────────┐
│                   Istio Service Mesh            │
├──────────────────────────────────────────────────────┤
│                                                 │
│  📊 Traffic Management (트래픽 관리)              │
│  ├─ Canary Deployment (점진적 배포)               │
│  ├─ A/B Testing (버전 분기)                       │
│  ├─ Circuit Breaker (장애 격리)                   │
│  └─ Retry & Timeout (자동 재시도)                  │
│                                                  │
│  🔒 Security (보안)                              │
│  ├─ Mutual TLS (서비스 간 암호화)                  │
│  ├─ Authentication (인증)                         │
│  └─ Authorization (권한 관리)                      │
│                                                  │
│  👁 Observability (관측성)                         │
│  ├─ Metrics (메트릭 자동 수집)                      │
│  ├─ Distributed Tracing (분산 추적)                │
│  ├─ Access Logs (접근 로그)                        │
│  └─ Topology Visualization (토폴로지 시각화)        │
│                                                  │
└──────────────────────────────────────────────────────┘

3. Istio 아키텍처 깊이 이해하기

전체 아키텍처

┌─────────────────────────────────────────────────────────────┐
│                    Control Plane                       │
│  ┌────────────────────────────────────────────────────┐    │
│  │                    istiod                     │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │     │
│  │  │  Pilot  │  │ Citadel  │  │   Galley   │    │     │
│  │  │(트래픽)  │  │ (보안)   │  │ (설정 검증)   │    │     │
│  │  └──────────┘  └──────────┘  └──────────────┘    │     │
│  └─────────────────────┬──────────────────────────────┘     │
│                        │ xDS API (설정 푸시)             │
└────────────────────────┼────────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        │                │             │
        ▼                ▼             ▼
┌─────────────────────────────────────────────────────────────┐
│                      Data Plane                        │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐       │
│  │   Pod A    │   │   Pod B    │   │   Pod C    │       │
│  │ ┌─────────┐ │   │ ┌─────────┐ │   │ ┌─────────┐ │       │
│  │ │  App   │ │   │ │  App    │ │   │ │  App   │ │       │
│  │ └────┬────┘ │   │ └────┬────┘ │   │ └────┬────┘ │       │
│  │     │      │   │      │      │   │      │     │       │
│  │ ┌────▼────┐ │   │ ┌────▼────┐ │    │ ┌────▼────┐ │       │
│  │ │ Envoy  │◀┼───┼▶│ Envoy  │◀┼───┼▶│ Envoy  │ │      │
│  │ │ Proxy  │ │   │ │ Proxy   │ │    │ │ Proxy  │ │      │
│  │ └─────────┘ │   │  └─────────┘ │   │ └─────────┘ │       │
│  └─────────────┘    └─────────────┘   └─────────────┘       │
│      Sidecar           Sidecar           Sidecar       │
└─────────────────────────────────────────────────────────────┘

Control Plane: istiod

istiod는 3가지 핵심 컴포넌트를 통합한 단일 바이너리입니다 (Istio 1.5 이후):

1. Pilot (트래픽 관리)

역할: VirtualService, DestinationRule 등을 Envoy 설정으로 변환

예시:
VirtualService (사람이 작성) → Pilot → Envoy Config (기계가 이해)

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews-route
spec:
  hosts:
  - reviews
  http:
  - match:
    - headers:
        user:
          exact: "jason"
    route:
    - destination:
        host: reviews
        subset: v2    # jason만 v2로 라우팅
  - route:
    - destination:
        host: reviews
        subset: v1    # 나머지는 v1로

2. Citadel (보안 관리)

역할: 인증서 자동 발급 및 갱신

동작 과정:
1. Pod 생성 시 Service Account 확인
2. X.509 인증서 자동 발급 (90일 만료)
3. Envoy에 인증서 주입
4. 서비스 간 mTLS 자동 활성화
5. 인증서 만료 전 자동 갱신

결과: 개발자가 인증서 관리 불필요!

3. Galley (설정 검증)

역할: Istio 설정 YAML 유효성 검증

검증 항목:
- YAML 문법 오류
- 필수 필드 누락
- 중복된 리소스
- 참조 무결성 (존재하지 않는 서비스 참조 등)

kubectl apply 전에 미리 검증:
istioctl analyze

Data Plane: Envoy Proxy

Envoy는 고성능 L7 프록시로 각 Pod에 Sidecar로 주입됩니다.

Sidecar 패턴 동작 원리:

Pod 내부 구조:

┌─────────────────────────────────────────────┐
│              Pod (productpage-v1)       │
│                                         │
│  ┌────────────────────────────────────┐    │
│  │    productpage Container        │    │
│  │    (Python Flask App)           │    │
│  │    Port: 9080                   │    │
│  │    localhost:9080으로 요청 보냄   │    │
│  └──────────────┬─────────────────────┘    │
│                │                        │
│                │ 127.0.0.1:9080         │
│                ▼                        │
│  ┌────────────────────────────────────┐    │
│  │    istio-proxy Container        │    │
│  │    (Envoy Sidecar)              │    │
│  │                                 │    │
│  │  ┌──────────────────────────────┐  │    │
│  │  │  Inbound Listener         │  │    │
│  │  │  15006: 모든 inbound 트래픽 │  │    │
│  │  └──────────────────────────────┘  │    │
│  │                                 │    │
│  │  ┌──────────────────────────────┐  │    │
│  │  │  Outbound Listener        │  │    │
│  │  │  15001: 모든 outbound 트래픽│  │    │
│  │  └──────────────────────────────┘  │    │
│  └────────────────────────────────────┘    │
│                                         │
└─────────────────────────────────────────────┘

Envoy가 수행하는 작업:

1. 트래픽 인터셉트

   # iptables 규칙으로 모든 트래픽을 Envoy로 리다이렉트
   
   Outbound 트래픽:
   App → localhost:9080
       ↓ (iptables 리다이렉트)
   Envoy:15001 → 목적지 서비스
   
   Inbound 트래픽:
   외부 → Envoy:15006 → App:9080

2. 로드 밸런싱

   reviews 서비스 호출 시:
   
   Envoy가 3개 엔드포인트 중 선택:
   - reviews-v1-pod-1 (10.1.2.3:9080)
   - reviews-v2-pod-1 (10.1.2.4:9080)
   - reviews-v3-pod-1 (10.1.2.5:9080)
   
   알고리즘: Round Robin, Random, Least Request

3. 재시도 & 타임아웃

   # VirtualService에 정의
   http:
   - route:
     - destination:
         host: reviews
     retries:
       attempts: 3           # 3번 재시도
       perTryTimeout: 2s     # 시도당 2초

4. 메트릭 자동 수집

   모든 요청에 대해 자동 수집:
   - 요청 수 (istio_requests_total)
   - 응답 시간 (istio_request_duration_milliseconds)
   - 에러율 (istio_request_errors_total)
   - 트래픽 크기 (istio_request_bytes)

4. 실습: Istio 환경 구축

환경 정보

# 클러스터 정보
kubectl get nodes -o wide

NAME   ROLES           VERSION    INTERNAL-IP
cpu1   control-plane   v1.31.13   172.30.1.43
cpu2   worker          v1.31.13   172.30.1.80
gpu1   worker          v1.31.13   172.30.1.38

Step 1: Istio 다운로드

cd ~/istio-demo
curl -L https://istio.io/downloadIstio | sh -

# 환경변수 설정
export PATH="/root/istio-demo/istio-1.28.0/bin:$PATH"

# 확인
istioctl version

다운로드된 디렉토리 구조:

istio-1.28.0/
├── bin/
│   └── istioctl              # Istio CLI 도구
├── manifests/
│   ├── profiles/             # 설치 프로파일
│   │   ├── default.yaml      # 프로덕션용 (우리가 사용)
│   │   ├── demo.yaml         # 데모/학습용
│   │   └── minimal.yaml      # 최소 설치
│   └── charts/               # Helm Charts
├── samples/
│   ├── bookinfo/             # 샘플 애플리케이션
│   │   ├── platform/kube/    # Pod/Service 정의
│   │   └── networking/       # Gateway/VirtualService
│   └── addons/               # 관측 도구
│       ├── kiali.yaml
│       ├── prometheus.yaml
│       └── grafana.yaml
└── tools/                    # 유틸리티

Step 2: Istio 설치 (default 프로파일)

프로파일 비교:

설치 명령:

istioctl install --set profile=default -y

설치 결과 확인:

kubectl get pods -n istio-system -o wide

NAME                                    READY   STATUS    NODE
istiod-57b4d7f8b8-875cs                 1/1     Running   cpu2
istio-ingressgateway-76cc55cb99-9nvnt   1/1     Running   cpu1

컴포넌트 설명:

1. istiod (Control Plane)

   • Pilot: 트래픽 관리
   • Citadel: mTLS 인증서 관리
   • Galley: 설정 검증
   • 단일 바이너리로 통합

2. istio-ingressgateway (Ingress Gateway)

   • 외부 트래픽 진입점
   • Envoy 기반 L7 로드 밸런서
   • LoadBalancer 타입 Service

왜 Egress Gateway가 없나?

• default 프로파일은 프로덕션 환경 최적화
• Egress Gateway는 외부 API 호출 제어가 필요할 때만 사용
• 필요시 별도 설치 가능

Step 3: Sidecar 자동 주입 설정

Sidecar 자동 주입 원리:

Kubernetes Mutating Admission Webhook 활용

1. kubectl apply로 Pod 생성 요청
   ↓
2. API Server가 Webhook 호출
   ↓
3. Istio가 Pod spec 수정 (istio-proxy 컨테이너 추가)
   ↓
4. 수정된 spec으로 Pod 생성

default namespace에 자동 주입 활성화:

kubectl label namespace default istio-injection=enabled

# 확인
kubectl get namespace default --show-labels

NAME      LABELS
default   istio-injection=enabled,kubernetes.io/metadata.name=default

동작 확인:

• 이제 default namespace에 생성되는 모든 Pod에 자동으로 istio-proxy 컨테이너가 주입됩니다.

Step 4: Bookinfo 샘플 애플리케이션 배포

Bookinfo 아키텍처:

┌──────────────────────────────────────────────────────┐
│                   Bookinfo App                   │
│                                                  │
│  ┌─────────────┐                                  │
│  │ productpage│ (Python)                         │
│  │     v1     │                                  │
│  └──────┬──────┘                                  │
│         │                                        │
│    ├────┼─────┬─────────────┐                      │
│    │    │     │             │                    │
│    ▼    ▼     ▼             ▼                    │
│  ┌───┐ ┌───┐ ┌───┐         ┌───┐                    │
│  │det│ │rev│ │rev│        │rat│                   │
│  │ v1│ │ v1│ │ v2│ ★     │ v1│                  │
│  └───┘ └───┘ └─┬─┘         └───┘                    │
│  Ruby   Java   │ │         Node.js               │
│                │ │                               │
│              ┌─▼─▼┐                              │
│              │rev │ ★★                         │
│              │ v3 │                              │
│              └────┘                              │
│               Java                               │
│                                                  │
│  ★ = reviews v2/v3는 ratings 호출                │
│  v1/v2/v3 = 3가지 버전으로 Canary 테스트 가능       │
└──────────────────────────────────────────────────────┘

배포:

kubectl apply -f ~/istio-demo/istio-1.28.0/samples/bookinfo/platform/kube/bookinfo.yaml

결과 확인:

kubectl get pods

NAME                              READY   STATUS    RESTARTS   AGE
details-v1-77b775f46-m68lr        2/2     Running   0          5m
productpage-v1-78dfd4688c-k7m2h   2/2     Running   0          5m
ratings-v1-7c4c8d6794-bgd99       2/2     Running   0          5m
reviews-v1-849f9bc5d6-glqll       2/2     Running   0          5m
reviews-v2-5c757d5846-rxn2k       2/2     Running   0          5m
reviews-v3-6d5d98f5c4-n4gj8       2/2     Running   0          5m

Sidecar 주입 확인:

kubectl get pod productpage-v1-78dfd4688c-k7m2h -o jsonpath='{range .spec.containers[*]}{.name}{"\n"}{end}'

productpage       ← 애플리케이션 컨테이너
istio-proxy       ← Envoy Sidecar (자동 주입됨!)

Pod 내부 구조 확인:

kubectl describe pod productpage-v1-78dfd4688c-k7m2h

Init Containers:
  istio-init:                    # iptables 규칙 설정
    Image: docker.io/istio/proxyv2:1.28.0

Containers:
  productpage:                   # 애플리케이션
    Image: docker.io/istio/examples-bookinfo-productpage-v1:1.20.3
    Port: 9080/TCP

  istio-proxy:                   # Envoy Sidecar
    Image: docker.io/istio/proxyv2:1.28.0
    Ports: 15090/TCP (메트릭), 15021/TCP (헬스체크)

5. Gateway와 VirtualService 완벽 이해

Gateway 리소스

Gateway는 Istio의 외부 트래픽 진입점 설정입니다.

apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: bookinfo-gateway
spec:
  # 어떤 Ingress Gateway Pod에 이 설정을 적용할지 선택
  selector:
    istio: ingressgateway    # istio=ingressgateway 라벨을 가진 Pod 선택

  # 어떤 포트와 프로토콜을 열지 정의
  servers:
  - port:
      number: 8080           # Envoy 내부 리스닝 포트
      name: http
      protocol: HTTP
    hosts:
    - "*"                    # 모든 호스트명 허용

항목별 설명:

Selector 매칭 원리:

# Gateway 리소스의 selector
selector:
  istio: ingressgateway

# istio-ingressgateway Pod의 라벨 확인
kubectl get pod -n istio-system -l istio=ingressgateway --show-labels

NAME                                    LABELS
istio-ingressgateway-76cc55cb99-9nvnt   istio=ingressgateway,...
                                                ↑
                                        매칭됨! 이 Pod에 설정 적용

VirtualService 리소스

VirtualService는 트래픽 라우팅 규칙을 정의합니다.

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: bookinfo
spec:
  # 어떤 호스트 요청을 처리할지
  hosts:
  - "*"                      # 모든 호스트 요청 받음

  # 어느 Gateway를 통해 들어온 트래픽에 적용할지
  gateways:
  - bookinfo-gateway         # 위에서 만든 Gateway와 연결

  # HTTP 라우팅 규칙
  http:
  - match:                   # 다음 URL 중 하나라도 매칭되면
    - uri:
        exact: /productpage       # 정확히 /productpage
    - uri:
        prefix: /static           # /static으로 시작
    - uri:
        exact: /login
    - uri:
        exact: /logout
    - uri:
        prefix: /api/v1/products

    route:                   # 위 조건에 매칭되면 여기로 라우팅
    - destination:
        host: productpage    # productpage 서비스로 전달
        port:
          number: 9080       # 9080 포트로

항목별 설명:

Gateway + VirtualService 연결 원리:

1. Gateway 리소스 생성
   name: bookinfo-gateway

2. VirtualService에서 참조
   gateways:
   - bookinfo-gateway    ← 이름으로 연결!

3. istiod가 매칭을 감지하고 Envoy 설정 생성

배포 및 확인

kubectl apply -f ~/istio-demo/istio-1.28.0/samples/bookinfo/networking/bookinfo-gateway.yaml

# 확인
kubectl get gateway,virtualservice

NAME                                           AGE
gateway.networking.istio.io/bookinfo-gateway   1m

NAME                                          GATEWAYS               HOSTS
virtualservice.networking.istio.io/bookinfo   ["bookinfo-gateway"]   ["*"]

6. 트래픽 흐름 완전 분석

포트 매핑 이해

istio-ingressgateway Service 확인:

kubectl get svc -n istio-system istio-ingressgateway -o yaml | grep -A 20 "ports:"

ports:
- name: status-port
  nodePort: 30670
  port: 15021
  targetPort: 15021
- name: http2
  nodePort: 30192         # ← NodePort (외부 접근)
  port: 80                # ← Service Port
  targetPort: 8080        # ← Pod 내부 Envoy 포트
- name: https
  nodePort: 31797
  port: 443
  targetPort: 8443

포트 매핑:

외부 요청: http://172.30.1.43:30192/productpage

NodePort 30192
    ↓
Service Port 80
    ↓
Pod targetPort 8080
    ↓
Envoy Listener (0.0.0.0:8080)
    ↓
Gateway 리소스 (port: 8080에서 매칭)
    ↓
VirtualService 라우팅 (/productpage → productpage:9080)
    ↓
productpage Service (ClusterIP 10.105.75.162:9080)
    ↓
productpage Pod
    ├─ istio-proxy (15006 → 9080 포트포워딩)
    └─ productpage Container (9080)

전체 트래픽 흐름 다이어그램

┌─────────────────────────────────────────────────────────────────────┐
│                         외부 사용자 (브라우저)                   │
│                    curl http://172.30.1.43:30192/productpage  │
└──────────────────────┬──────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Kubernetes Node (cpu1)                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │          NodePort 30192 (iptables NAT)                 │   │
│  │          DNAT: 외부IP:30192 → Service:80                │   │
│  └──────────────────────┬──────────────────────────────────────┘   │
└─────────────────────────┼───────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│              istio-ingressgateway Service                     │
│                  Type: LoadBalancer                           │
│                  ClusterIP: 10.104.64.238:80                  │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  PORT MAPPING:                                         │    │
│  │  port: 80  →  targetPort: 8080                         │    │
│  └──────────────────────┬─────────────────────────────────────┘    │
└─────────────────────────┼───────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│         istio-ingressgateway Pod (istio-system namespace)     │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │              Envoy Proxy (Container)                  │    │
│  │  ┌──────────────────────────────────────────────────┐      │    │
│  │  │  Listener: 0.0.0.0:8080 (HTTP)               │      │    │
│  │  │  "8080 포트에서 HTTP 요청 대기 중..."           │      │    │
│  │  └─────────────────┬────────────────────────────────┘      │    │
│  │                    │                                   │    │
│  │                    ▼                                   │    │
│  │  ┌──────────────────────────────────────────────────┐      │    │
│  │  │  Gateway 리소스 매칭 (bookinfo-gateway)        │      │    │
│  │  │  - selector: istio=ingressgateway ✓          │      │    │
│  │  │  - port: 8080 ✓                              │      │    │
│  │  │  - hosts: "*" ✓                              │      │    │
│  │  │  → "이 Gateway 설정 적용!"                     │      │    │
│  │  └─────────────────┬────────────────────────────────┘      │    │
│  │                    │                                   │    │
│  │                    ▼                                   │    │
│  │  ┌──────────────────────────────────────────────────┐      │    │
│  │  │  VirtualService 라우팅 규칙 (bookinfo)         │      │    │
│  │  │  - gateways: [bookinfo-gateway] ✓            │      │    │
│  │  │  - uri.exact: "/productpage" ✓               │      │    │
│  │  │  - destination.host: "productpage"           │      │    │
│  │  │  - destination.port: 9080                    │      │    │
│  │  │  → "productpage:9080으로 라우팅!"              │      │    │
│  │  └─────────────────┬────────────────────────────────┘      │    │
│  └────────────────────┼───────────────────────────────────────┘    │
└─────────────────────────┼───────────────────────────────────────────┘
                          │ HTTP Request
                          │ Host: productpage:9080
                          │ Path: /productpage
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│              productpage Service (ClusterIP)                  │
│                  ClusterIP: 10.105.75.162:9080                │
│                  Selector: app=productpage                    │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  Endpoint: productpage-v1-pod (10.244.2.15:9080)      │    │
│  └──────────────────────┬─────────────────────────────────────┘    │
└─────────────────────────┼───────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                  productpage-v1 Pod (default namespace)       │
│  ┌───────────────────┐    ┌────────────────────────────────────┐   │
│  │  istio-proxy      │    │                                │   │
│  │  (Envoy Sidecar)  │    │                                │   │
│  │                   │    │                                │   │
│  │  Inbound:         │    │                                │   │
│  │  15006 포트       │───▶│  productpage Container         │   │
│  │    ↓              │    │  (Python Flask App)            │   │
│  │  iptables로       │    │  Port: 9080                    │   │
│  │  9080으로 전달    │    │  "HTML 응답 생성"                 │   │
│  │                   │    │                                │   │
│  └───────────────────┘    └────────────────────────────────────┘    │
│         │                                                      │
│         │ 메트릭 수집, 로그 기록, 트레이스 생성                     │
│         ↓                                                      │
│  [Prometheus, Jaeger로 전송]                                    │
└─────────────────────────────────────────────────────────────────────┘

실제 테스트

# 클러스터 내부에서 테스트
curl -s http://172.30.1.43:30192/productpage | head -20

<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">

<title>Simple Bookstore App</title>

성공! Gateway → VirtualService → productpage 흐름이 정상 작동합니다.

7. Istio의 강력한 기능들

1. Traffic Management (트래픽 관리)

Canary Deployment (카나리 배포)

기존 방식 vs Istio:

기존 Kubernetes:
- Deployment replicas 조정으로 비율 제어
- 정밀한 비율 제어 어려움 (예: 95:5 불가능)
- 코드 변경 필요

Istio:
- VirtualService로 정확한 비율 제어
- 코드 변경 없이 YAML만 수정
- 헤더 기반 라우팅 가능

예시: reviews v3로 10% 트래픽 전환

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews
spec:
  hosts:
  - reviews
  http:
  - route:
    - destination:
        host: reviews
        subset: v1
      weight: 90         # 90% → v1
    - destination:
        host: reviews
        subset: v3
      weight: 10         # 10% → v3 (신규 버전)

사용 시나리오:

1. 새 버전 배포 시 10%만 테스트
2. 에러율 모니터링
3. 문제 없으면 50% → 100% 점진적 증가

A/B Testing (사용자 기반 라우팅)

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews
spec:
  hosts:
  - reviews
  http:
  - match:
    - headers:
        user:
          exact: "jason"    # jason 사용자만
    route:
    - destination:
        host: reviews
        subset: v2          # v2로 라우팅 (별점 검은색)
  - route:
    - destination:
        host: reviews
        subset: v1          # 나머지는 v1 (별점 없음)

Circuit Breaker (장애 격리)

apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
  name: reviews
spec:
  host: reviews
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 100        # 최대 연결 수
      http:
        http1MaxPendingRequests: 10
        maxRequestsPerConnection: 2
    outlierDetection:              # 비정상 인스턴스 자동 제외
      consecutiveErrors: 5         # 5회 연속 실패 시
      interval: 30s                # 30초마다 체크
      baseEjectionTime: 30s        # 30초간 제외

동작:

1. reviews-v2 Pod가 5회 연속 에러 응답
2. Envoy가 해당 Pod를 30초간 로드밸런싱에서 제외
3. 정상 Pod로만 트래픽 전달
4. 30초 후 재시도

2. Security (보안)

Mutual TLS (mTLS)

기존 방식 vs Istio:

기존 방식:
1. 인증서 생성 (openssl)
2. 각 서비스에 인증서 배포
3. 애플리케이션 코드에서 TLS 설정
4. 인증서 만료 전 수동 갱신

Istio:
1. PeerAuthentication 리소스 생성
2. 끝! (자동 활성화)

Istio mTLS 자동화:

apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: default
  namespace: default
spec:
  mtls:
    mode: STRICT    # 모든 서비스 간 통신 암호화 강제

Citadel (istiod)이 자동 수행:

• X.509 인증서 자동 발급
• 90일 만료 시 자동 갱신
• Envoy에 자동 주입
• 암호화/복호화 자동 처리

효과:

productpage → reviews 호출 시

기존:
productpage ──HTTP(평문)──▶ reviews
             ↑ 스니핑 가능!

Istio mTLS:
productpage ──TLS(암호화)──▶ reviews
istio-proxy ────────────────▶ istio-proxy
             ↑ 암호화된 통신

Authorization (권한 관리)

apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: allow-productpage-to-reviews
spec:
  selector:
    matchLabels:
      app: reviews                # reviews 서비스에 대한 접근 제어
  action: ALLOW
  rules:
  - from:
    - source:
        principals: ["cluster.local/ns/default/sa/productpage"]
    to:
    - operation:
        methods: ["GET"]           # GET만 허용

효과: productpage만 reviews를 호출 가능, 다른 서비스는 차단

3. Observability (관측성)

자동 메트릭 수집

Envoy가 모든 요청에 대해 자동 수집:

Prometheus 메트릭:
- istio_requests_total{destination_service="reviews"}
  → reviews 서비스로의 요청 수

- istio_request_duration_milliseconds{destination_service="reviews"}
  → reviews 응답 시간

- istio_request_bytes_sum
  → 요청 크기

코드 변경 없이 자동 수집!

Distributed Tracing (분산 추적)

사용자 요청 하나의 전체 경로 추적:

Request ID: abc123
┌────────────────────────────────────────┐
│ productpage (50ms)                     │
│  ├─ details (10ms)                     │
│  ├─ reviews-v2 (30ms)                  │
│  │   └─ ratings (15ms)  ← 병목 발견!  │
│  └─ ...                                │
└────────────────────────────────────────┘

Jaeger UI에서 시각화:

• 전체 요청 경로
• 각 구간 소요 시간
• 에러 발생 지점

Service Graph (서비스 토폴로지)

Kiali 대시보드:

       ┌─────────────┐
       │ productpage │
       └──────┬──────┘
              │
      ┌───────┼───────┬─────────┐
      │       │       │         │
      ▼       ▼       ▼         ▼
   ┌───┐   ┌───┐   ┌───┐     ┌───┐
   │det│   │rev│   │rev│     │rev│
   │ v1│   │ v1│   │ v2│     │ v3│
   └───┘   └───┘   └─┬─┘     └─┬─┘
                     │         │
                     └────┬────┘
                          │
                          ▼
                       ┌─────┐
                       │ rat │
                       │  v1 │
                       └─────┘

- 초록색 선: 정상 트래픽
- 빨간색 선: 에러 발생
- 선 굵기: 트래픽 양

4. Resilience (복원력)

Retry & Timeout

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: reviews
spec:
  hosts:
  - reviews
  http:
  - route:
    - destination:
        host: reviews
    timeout: 10s              # 10초 타임아웃
    retries:
      attempts: 3             # 3번 재시도
      perTryTimeout: 2s       # 시도당 2초
      retryOn: 5xx            # 5xx 에러 시 재시도

효과:

• 일시적 네트워크 오류 자동 복구
• 사용자에게 에러 노출 감소

Fault Injection (장애 주입 - 테스트용)

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: ratings
spec:
  hosts:
  - ratings
  http:
  - fault:
      delay:
        percentage:
          value: 10           # 10% 요청에
        fixedDelay: 5s        # 5초 지연 주입
    route:
    - destination:
        host: ratings

사용 시나리오:

• 프로덕션 배포 전 장애 상황 테스트
• Circuit Breaker 동작 검증
• Timeout 설정 적절성 확인

다음 계획

Day 10: Istio 관측 도구 (Observability)

학습 내용:

1. Kiali 설치 및 활용

   • Service Graph 시각화
   • 실시간 트래픽 모니터링
   • VirtualService 설정 검증

2. Prometheus & Grafana

   • 메트릭 수집 확인
   • Istio 대시보드 분석
   • 커스텀 메트릭 생성

3. Jaeger (분산 추적)

   • Trace 수집 설정
   • 요청 경로 분석
   • 성능 병목 발견

4. 실습: 트래픽 시나리오 테스트

   • Canary 배포 (reviews v1 → v3)
   • A/B 테스트 (사용자별 라우팅)
   • 장애 주입 및 복구 테스트

Day 11-19: Istio 심화 학습

• Day 11: Sail Operator (Istio Lifecycle 관리)
• Day 12: Envoy Proxy 심화 (Filter, Listener)
• Day 13: Istio Gateway 고급 (mTLS, SNI)
• Day 14: Traffic Management 실전 (Canary, Blue-Green)
• Day 15: Security 심화 (JWT, RBAC)
• Day 16: Multi-Cluster Mesh
• Day 17: Istio Performance Tuning
• Day 18: Istio Troubleshooting
• Day 19: Production Best Practices

핵심 요약

Istio를 사용하는 이유

1. 개발자는 비즈니스 로직에만 집중

   • 재시도, 타임아웃 → Istio가 처리
   • 로깅, 메트릭 → 자동 수집
   • 보안 → 자동 암호화

2. 언어 독립적

   • Java, Python, Go, Node.js 모두 동일하게 동작
   • 라이브러리 없이 YAML만으로 제어

3. 강력한 관측성

   • 코드 변경 없이 메트릭 수집
   • 전체 서비스 토폴로지 시각화
   • 분산 추적으로 병목 발견

4. 프로덕션급 보안

   • mTLS 자동 활성화
   • 인증서 자동 갱신
   • 세밀한 권한 제어

오늘 배운 핵심 개념

1. Service Mesh = 마이크로서비스 간 통신 관리 인프라 레이어

2. Istio 아키텍처:
   - Control Plane (istiod): 설정 관리
   - Data Plane (Envoy): 실제 트래픽 처리

3. Sidecar 패턴:
   - 각 Pod에 Envoy Proxy 자동 주입
   - 애플리케이션 코드 변경 없음

4. Gateway + VirtualService:
   - Gateway: 외부 트래픽 진입점
   - VirtualService: 라우팅 규칙
   - Selector로 Ingress Gateway Pod 선택
   - 이름으로 Gateway와 VirtualService 연결

5. 트래픽 흐름:
   NodePort → Service → Envoy (Gateway)
   → VirtualService 라우팅 → 목적지 서비스
   → Envoy (Sidecar) → App

실무 적용 포인트

언제 Istio를 도입해야 하나?

✅ 도입 권장:

• 마이크로서비스 10개 이상
• 서비스 간 통신 복잡도 높음
• Canary 배포, A/B 테스트 필요
• 관측성 부재로 장애 대응 어려움
• 서비스 간 보안 요구사항 있음

❌ 도입 불필요:

• 모놀리식 애플리케이션
• 마이크로서비스 5개 미만
• 단순한 CRUD API만 존재
• 운영 리소스 부족 (학습 비용 高)

Istio 도입 단계:

1. Pilot 프로젝트 (1-2개 서비스)
2. Sidecar 주입 검증
3. Gateway 설정 및 트래픽 테스트
4. 관측 도구 설치 (Kiali, Prometheus)
5. 점진적 확대 (서비스별 순차 적용)

다음 포스트에서는 Kiali, Prometheus, Grafana를 설치하고 Istio의 강력한 관측성을 직접 체험해보겠습니다!

2025년 11월 8일 수동 배포는 이제 그만! Git Push 한 번으로 자동 배포되는 마법

들어가며

Day 7에서 Ceph 분산 스토리지로 진정한 동적 프로비저닝을 경험했습니다. 이제 Day 8에서는 GitOps 패러다임의 핵심 도구인 Helm과 ArgoCD를 마스터하여 선언적 배포 자동화를 완성했습니다.

오늘 배운 것:

1. Helm의 철학과 Custom Chart 생성 (Chart.yaml, templates/, values)
2. 환경별 Values 관리 (values-dev.yaml, values-staging.yaml, values-prod.yaml)
3. ArgoCD 설치 및 아키텍처 이해 (Application Controller, Repo Server)
4. GitOps 워크플로우 (Git → ArgoCD → Kubernetes 자동 동기화)
5. Self-Heal 기능 (수동 변경 자동 복구)
6. Sync Waves와 Hooks (순차적 배포, DB 마이그레이션)
7. 다중 환경 배포 (하나의 차트, 세 가지 환경)

1. Helm이 뭐길래?

왜 Helm인가?

🤔 내가 이해한 것:

Kubernetes YAML을 직접 관리하다 보면 이런 문제가 생깁니다:

문제점:
❌ YAML 파일 수십 개 (Deployment, Service, ConfigMap, Secret, Ingress...)
❌ 환경별 복사본 (dev, staging, prod 각각 관리)
❌ 변수 관리 어려움 (이미지 태그, 포트, 리소스 등)
❌ 롤백 복잡함 (어떤 YAML을 되돌릴지?)
❌ 재사용 불가 (다른 프로젝트에서 복사-붙여넣기)

Helm의 해결책:
✅ 패키지 단위 관리 (Chart = 모든 리소스를 하나로)
✅ 템플릿화 ({{ .Values.image.tag }} 같은 변수)
✅ 환경별 Values 파일 (values-dev.yaml, values-prod.yaml)
✅ 버전 관리 (helm rollback으로 즉시 복구)
✅ Chart 재사용 (공식 차트 저장소, 자체 차트)

Kubernetes YAML vs Helm:

기존 YAML 방식:
myapp/
├─ deployment-dev.yaml
├─ deployment-staging.yaml
├─ deployment-prod.yaml
├─ service-dev.yaml
├─ service-staging.yaml
├─ service-prod.yaml
├─ configmap-dev.yaml
└─ ... (복사본 지옥!)

→ 환경 추가 시 모든 파일 복사
→ 이미지 태그 변경 시 3개 파일 수정

Helm 방식:
myapp/
├─ Chart.yaml
├─ values.yaml (기본값)
├─ values-dev.yaml
├─ values-staging.yaml
├─ values-prod.yaml
└─ templates/
    ├─ deployment.yaml  (템플릿)
    ├─ service.yaml     (템플릿)
    └─ configmap.yaml   (템플릿)

→ 환경 추가 시 values-*.yaml 하나만 추가
→ 이미지 태그 변경 시 values 파일 한 줄만 수정!

Helm 핵심 개념 정리

Chart (차트):

• Kubernetes 리소스의 패키지
• 템플릿 + 기본 설정 + 메타데이터
• helm create로 생성

Values (값):

# values.yaml (기본값)
replicaCount: 2
image:
  repository: nginx
  tag: "1.25.3"
service:
  port: 80

# values-prod.yaml (프로덕션 오버라이드)
replicaCount: 5  # ← 프로덕션은 5개로!
resources:
  limits:
    memory: "512Mi"

템플릿 (Template):

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Chart.Name }}
spec:
  replicas: {{ .Values.replicaCount }}  # ← 값 주입!
  template:
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        ports:
        - containerPort: {{ .Values.service.port }}

Release (릴리스):

Chart를 특정 환경에 설치한 인스턴스

예시:
myapp-dev    (myapp 차트의 dev 릴리스)
myapp-staging (myapp 차트의 staging 릴리스)
myapp-prod   (myapp 차트의 prod 릴리스)

2. Custom Helm Chart 생성 실습

실습 1: 기본 차트 생성

Helm 설치 (이미 설치됨):

$ helm version
version.BuildInfo{Version:"v3.16.3", GitCommit:"cfd07493f46efc9debd9cc1b02a0961186df7fdf", GitTreeState:"clean", GoVersion:"go1.22.7"}

기본 차트 스캐폴딩:

# 차트 뼈대 생성
$ helm create myapp
Creating myapp

# 디렉토리 구조 확인
$ tree myapp
myapp/
├── Chart.yaml           # 차트 메타데이터
├── values.yaml          # 기본 설정값
├── templates/           # Kubernetes 리소스 템플릿
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── _helpers.tpl     # 헬퍼 함수
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   └── NOTES.txt        # 설치 후 출력 메시지
└── charts/              # 의존성 차트

Chart.yaml 이해:

apiVersion: v2            # Helm 3 = v2
name: myapp               # 차트 이름
description: A Helm chart for myapp
type: application         # application or library
version: 0.1.0            # 차트 버전 (SemVer)
appVersion: "1.25.3"      # 앱 버전 (nginx 1.25.3)

• version: 차트 자체의 버전 (YAML 구조 변경 시 증가)
• appVersion: 배포되는 애플리케이션 버전

실습 2: 환경별 Values 파일 작성

문제: 피곤한 작업이지만 한 번만 하면 계속 재사용 가능!

# values.yaml (기본값)
replicaCount: 2
image:
  repository: nginx
  tag: "1.25.3"
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80
resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi
env: "default"

환경별 오버라이드:

# values-dev.yaml (개발 환경 - 최소 리소스)
replicaCount: 1
resources:
  limits:
    cpu: 50m
    memory: 64Mi
  requests:
    cpu: 25m
    memory: 32Mi
env: "development"

# values-staging.yaml (스테이징 - 중간 리소스)
replicaCount: 2
resources:
  limits:
    cpu: 200m
    memory: 256Mi
  requests:
    cpu: 100m
    memory: 128Mi
env: "staging"

# values-prod.yaml (프로덕션 - 고가용성)
replicaCount: 5
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
env: "production"
service:
  type: NodePort  # 외부 접근
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

🎯 핵심: 템플릿은 한 번만 작성, 환경별 설정만 변경!

3. ArgoCD가 뭐길래?

GitOps란?

전통적인 배포:

개발자 로컬 PC
  ↓
kubectl apply -f deployment.yaml
  ↓
Kubernetes 클러스터

문제점:
❌ 누가 언제 무엇을 배포했는지 추적 어려움
❌ 환경마다 다른 상태 (drift)
❌ 롤백 복잡함
❌ 권한 관리 어려움 (개발자마다 kubectl 권한 필요)

GitOps 방식:

개발자 → Git Push
  ↓
Git Repository (단일 진실 소스, Single Source of Truth)
  ↓
ArgoCD (자동 감지)
  ↓
Kubernetes 클러스터 (자동 동기화)

장점:
✅ Git = 모든 변경 이력 추적
✅ Pull Request 기반 코드 리뷰
✅ 롤백 = Git Revert
✅ 선언적 상태 (Desired State in Git)
✅ 중앙 집중식 배포 (ArgoCD만 kubectl 권한 필요)

ArgoCD 아키텍처

GitHub Repository
  ├─ myapp/ (Helm Chart)
  │   ├─ templates/
  │   └─ values-*.yaml
  └─ argocd-apps/
      ├─ myapp-dev.yaml
      ├─ myapp-staging.yaml
      └─ myapp-prod.yaml
        ↓
        ↓ (Git Poll/Webhook)
        ↓
ArgoCD 컴포넌트
  ├─ Application Controller
  │   - Git 저장소 모니터링
  │   - 실제 상태 vs 원하는 상태 비교
  │   - 동기화 실행
  │
  ├─ Repo Server
  │   - Git Clone
  │   - Helm Template 렌더링
  │   - Kubernetes 매니페스트 생성
  │
  ├─ API Server
  │   - Web UI / CLI 제공
  │   - RBAC 인증/인가
  │
  └─ Redis
      - 캐시 (Cluster State, Git Commit)
        ↓
        ↓ (kubectl apply)
        ↓
Kubernetes 클러스터
  ├─ myapp-dev (Namespace)
  ├─ myapp-staging (Namespace)
  └─ myapp-prod (Namespace)

4. ArgoCD 설치 및 구성 실습

실습 3: ArgoCD 설치

네임스페이스 생성 및 배포:

# 네임스페이스 생성
$ kubectl create namespace argocd
namespace/argocd created

# ArgoCD 설치 (공식 YAML)
$ kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
customresourcedefinition.apiextensions.k8s.io/applications.argoproj.io created
customresourcedefinition.apiextensions.k8s.io/applicationsets.argoproj.io created
customresourcedefinition.apiextensions.k8s.io/appprojects.argoproj.io created
serviceaccount/argocd-application-controller created
...
deployment.apps/argocd-server created
deployment.apps/argocd-repo-server created
deployment.apps/argocd-applicationset-controller created

# Pod 상태 확인
$ kubectl get pods -n argocd
NAME                                                READY   STATUS
argocd-application-controller-0                     1/1     Running
argocd-applicationset-controller-xxxxx              1/1     Running
argocd-dex-server-xxxxx                             1/1     Running
argocd-notifications-controller-xxxxx               1/1     Running
argocd-redis-xxxxx                                  1/1     Running
argocd-repo-server-xxxxx                            1/1     Running
argocd-server-xxxxx                                 1/1     Running

ArgoCD가 알아서 Helm Chart 인식!

• 연동 설정 없이도 자동 동작
• Git 저장소에 Chart.yaml 있으면 Helm으로 처리
• helm.valueFiles 파라미터로 환경별 values 선택

실습 4: ArgoCD 웹 UI 접근

NodePort로 외부 노출:

# 서비스 타입 변경
$ kubectl patch svc argocd-server -n argocd -p '{"spec":{"type":"NodePort"}}'
service/argocd-server patched

# NodePort 확인
$ kubectl get svc -n argocd argocd-server
NAME            TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)
argocd-server   NodePort   10.103.51.239   <none>        80:31080/TCP,443:31443/TCP

# 접속 URL
http://172.30.1.38:31080

초기 비밀번호 확인:

$ kubectl get secret -n argocd argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d
hZa4rP9qK7mE3nF2

로그인:

Username: admin
Password: hZa4rP9qK7mE3nF2

5. GitOps 워크플로우 구현

실습 5: Git 저장소 준비

GitHub 저장소 구조:

ArgoCD-gitops/
├─ myapp/                   # Helm Chart
│   ├─ Chart.yaml
│   ├─ values.yaml
│   ├─ values-dev.yaml
│   ├─ values-staging.yaml
│   ├─ values-prod.yaml
│   └─ templates/
│       ├─ deployment.yaml
│       ├─ service.yaml
│       └─ configmap.yaml
│
└─ sync-waves-demo/         # Sync Waves 실습
    ├─ database.yaml
    ├─ migration-job.yaml
    └─ application.yaml

Git Push:

$ cd /root/argocd-demo
$ git add myapp/
$ git commit -m "Add Helm chart with multi-env values"
$ git push origin main

실습 6: ArgoCD Application 생성 (3개 환경)

ArgoCD Application CRD 이해:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp-dev
  namespace: argocd
spec:
  project: default

  # Git 소스
  source:
    repoURL: https://github.com/hansungmoon/ArgoCD-gitops.git
    targetRevision: main
    path: myapp  # Helm Chart 경로
    helm:
      valueFiles:
        - values-dev.yaml  # ← 환경별 values 선택!

  # 배포 대상
  destination:
    server: https://kubernetes.default.svc
    namespace: myapp-dev

  # 동기화 정책
  syncPolicy:
    automated:
      prune: true      # Git에서 삭제된 리소스 자동 제거
      selfHeal: true   # 수동 변경 자동 복구
    syncOptions:
      - CreateNamespace=true

helm.valueFiles는 어디 있지?

• 위치: /root/argocd-helm-apps.yaml 파일의 15-17, 44-46, 73-75 라인!
• 각 환경별 Application에서 다른 values 파일 지정

3개 환경 배포:

$ kubectl apply -f /root/argocd-helm-apps.yaml
application.argoproj.io/myapp-dev created
application.argoproj.io/myapp-staging created
application.argoproj.io/myapp-prod created

# Application 상태 확인
$ kubectl get applications -n argocd
NAME             SYNC STATUS   HEALTH STATUS
myapp-dev        Synced        Healthy
myapp-staging    Synced        Healthy
myapp-prod       Synced        Healthy

네임스페이스별 Pod 확인:

$ kubectl get pods -n myapp-dev
NAME                     READY   STATUS    RESTARTS   AGE
myapp-xxxxxxxxx-xxxxx    1/1     Running   0          2m

$ kubectl get pods -n myapp-staging
NAME                     READY   STATUS    RESTARTS   AGE
myapp-xxxxxxxxx-xxxxx    1/1     Running   0          2m
myapp-xxxxxxxxx-xxxxx    1/1     Running   0          2m  # ← Replica 2

$ kubectl get pods -n myapp-prod
NAME                     READY   STATUS    RESTARTS   AGE
myapp-xxxxxxxxx-xxxxx    1/1     Running   0          2m
myapp-xxxxxxxxx-xxxxx    1/1     Running   0          2m
myapp-xxxxxxxxx-xxxxx    1/1     Running   0          2m
myapp-xxxxxxxxx-xxxxx    1/1     Running   0          2m
myapp-xxxxxxxxx-xxxxx    1/1     Running   0          2m  # ← Replica 5

🎉 성공! 하나의 Helm Chart, 세 가지 환경!

6. Self-Heal 기능 검증

Self-Heal이 어떤 기능이지?

Self-Heal:

• Git에 선언된 상태(Desired State)를 강제
• 수동으로 변경된 리소스를 자동으로 원래대로 복구
• 5초마다 상태 확인 (기본값)

작동 원리:

1. Git: replicas: 2
2. ArgoCD: Kubernetes에 Deployment 배포 (replicas=2)
3. 개발자: kubectl scale deployment myapp --replicas=10
4. ArgoCD: "어? Git에는 2인데 실제는 10이네?" (Drift 감지)
5. ArgoCD: kubectl apply (replicas=2로 복구)
   → 약 5초 후 자동 복구!

실습 7: Self-Heal 테스트

시나리오: 개발자가 실수로 Replica를 수동 변경

# 현재 상태 (Git: 2, 실제: 2)
$ kubectl get deployment -n myapp-dev
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
myapp   2/2     2            2           5m

# 수동 변경 (kubectl로 직접 수정!)
$ kubectl scale deployment myapp -n myapp-dev --replicas=10
deployment.apps/myapp scaled

# 즉시 확인
$ kubectl get deployment -n myapp-dev
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
myapp   10/10   10           10          5m

# 5초 대기...
$ sleep 5

# Self-Heal 작동! (Git 상태로 복구)
$ kubectl get deployment -n myapp-dev
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
myapp   2/2     2            2           5m  # ← 자동으로 2로 복구!

ArgoCD UI에서 확인:

Application: myapp-dev
Status: OutOfSync → Syncing → Synced
Message: "Deployment replicas reverted to 2 (Git state)"

🎯 교훈:

• Git이 단일 진실 소스 (Single Source of Truth)
• 수동 변경은 무의미 (Self-Heal이 복구)
• 변경하려면 Git 수정 → PR → Merge!

7. Sync Waves: 순차적 배포 제어

왜 Sync Waves가 필요한가?

문제 상황:

Application 배포 시:
1. Database Pod 생성 중... (아직 준비 안 됨)
2. Application Pod 시작 → DB 연결 실패! (CrashLoopBackOff)
3. DB 준비 완료
4. Application 계속 재시작...

→ 배포 순서가 랜덤!

Sync Waves 해결책:

annotations:
  argocd.argoproj.io/sync-wave: "0"  # ← 낮은 번호부터 배포!

배포 순서:
Wave 0: Database (postgres)
  ↓ (DB 준비 완료 대기)
Wave 1: DB Migration Job (PreSync Hook)
  ↓ (마이그레이션 완료)
Wave 2: Application (webapp)
  ↓ (모든 리소스 Healthy)

실습 8: Sync Waves 구현

Wave 0: Database (먼저 배포)

# database.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  annotations:
    argocd.argoproj.io/sync-wave: "0"  # ← Wave 0
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    spec:
      containers:
      - name: postgres
        image: postgres:14-alpine
        env:
        - name: POSTGRES_PASSWORD
          value: "password123"
        - name: POSTGRES_DB
          value: "myapp"
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
  annotations:
    argocd.argoproj.io/sync-wave: "0"
spec:
  selector:
    app: postgres
  ports:
  - port: 5432

Wave 1: DB Migration (PreSync Hook)

# migration-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/sync-wave: "1"  # ← Wave 1
    argocd.argoproj.io/hook: PreSync    # ← 앱 배포 전 실행!
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migration
        image: postgres:14-alpine
        command:
        - /bin/sh
        - -c
        - |
          echo "=== DB Migration 시작 ==="
          echo "데이터베이스 연결 대기 중..."
          sleep 5

          echo "테이블 생성 중..."
          PGPASSWORD=password123 psql -h postgres -U postgres -d myapp -c "
            CREATE TABLE IF NOT EXISTS users (
              id SERIAL PRIMARY KEY,
              name VARCHAR(100),
              created_at TIMESTAMP DEFAULT NOW()
            );
          "

          echo "샘플 데이터 삽입 중..."
          PGPASSWORD=password123 psql -h postgres -U postgres -d myapp -c "
            INSERT INTO users (name) VALUES ('Alice'), ('Bob'), ('Charlie')
            ON CONFLICT DO NOTHING;
          "

          echo "=== DB Migration 완료 ==="

Hook 종류:

• PreSync: 동기화 전 실행 (DB 마이그레이션, 사전 검증)
• Sync: 일반 리소스 배포 (기본값)
• PostSync: 동기화 후 실행 (테스트, Slack 알림)
• SyncFail: 동기화 실패 시 실행 (롤백, 에러 알림)

Wave 2: Application (마지막 배포)

# application.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
  annotations:
    argocd.argoproj.io/sync-wave: "2"  # ← Wave 2
spec:
  replicas: 2
  selector:
    matchLabels:
      app: webapp
  template:
    spec:
      initContainers:
      - name: wait-for-db
        image: postgres:14-alpine
        command:
        - /bin/sh
        - -c
        - |
          echo "데이터베이스 준비 대기 중..."
          until PGPASSWORD=password123 psql -h postgres -U postgres -d myapp -c '\l'; do
            echo "데이터베이스 연결 대기..."
            sleep 2
          done
          echo "데이터베이스 준비 완료!"
      containers:
      - name: webapp
        image: nginx:1.25.3

Git Push 및 ArgoCD Application 생성:

# Git Push
$ cd /root/argocd-demo/sync-waves-demo
$ git add .
$ git commit -m "Add Sync Waves demo with DB migration"
$ git push origin main

# ArgoCD Application 생성
$ kubectl apply -f /root/sync-waves-app.yaml
application.argoproj.io/sync-waves-demo created

# 배포 순서 확인 (실시간 모니터링)
$ kubectl get pods -n sync-waves -w
NAME                        READY   STATUS              RESTARTS   AGE
postgres-xxxxxxxxx-xxxxx    0/1     ContainerCreating   0          3s   # ← Wave 0
postgres-xxxxxxxxx-xxxxx    1/1     Running             0          15s
db-migration-xxxxx          0/1     ContainerCreating   0          5s   # ← Wave 1 (PreSync)
db-migration-xxxxx          1/1     Running             0          8s
db-migration-xxxxx          0/1     Completed           0          25s
webapp-xxxxxxxxx-xxxxx      0/1     Init:0/1            0          3s   # ← Wave 2
webapp-xxxxxxxxx-xxxxx      0/1     PodInitializing     0          12s
webapp-xxxxxxxxx-xxxxx      1/1     Running             0          15s

최종 상태:

$ kubectl get pods -n sync-waves
NAME                        READY   STATUS      RESTARTS   AGE
db-migration-dvlft          0/1     Completed   0          2m    # ← Job 완료
postgres-6b9c5b7d9c-4kvxn   1/1     Running     0          2m
webapp-7f8b6c9d8f-7kxqm     1/1     Running     0          1m
webapp-7f8b6c9d8f-9hnpz     1/1     Running     0          1m

$ kubectl get application -n argocd sync-waves-demo
NAME              SYNC STATUS   HEALTH STATUS
sync-waves-demo   Synced        Healthy  # ← 모두 성공!

🎉 순차적 배포 성공! DB → Migration → App 순서 보장!

8. ArgoCD Application CRD 완전 분석

Application Spec 주요 필드

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp-dev
  namespace: argocd  # ← ArgoCD는 argocd 네임스페이스에서 실행
spec:
  # 1. 프로젝트 (RBAC, 리소스 격리)
  project: default

  # 2. Git 소스
  source:
    repoURL: https://github.com/user/repo.git
    targetRevision: main  # 브랜치, 태그, 커밋 SHA
    path: myapp           # Chart 경로

    # Helm 설정
    helm:
      valueFiles:
        - values-dev.yaml   # ← 여러 개 가능!
        - secrets-dev.yaml
      parameters:           # CLI 오버라이드
        - name: replicaCount
          value: "3"
      releaseName: myapp-dev

  # 3. 배포 대상
  destination:
    server: https://kubernetes.default.svc  # 클러스터 URL
    namespace: myapp-dev

  # 4. 동기화 정책
  syncPolicy:
    automated:
      prune: true       # Git 삭제 → Kubernetes 삭제
      selfHeal: true    # Drift 자동 복구
      allowEmpty: false # 빈 커밋 거부

    syncOptions:
      - CreateNamespace=true   # 네임스페이스 자동 생성
      - PruneLast=true         # 삭제는 마지막에
      - ApplyOutOfSyncOnly=true # OutOfSync만 적용

    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

  # 5. Health 체크 (선택)
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas  # HPA 사용 시 replicas 무시

syncPolicy 상세 설명

automated.prune:

Git에서 deployment.yaml 삭제
  ↓
ArgoCD: "Deployment가 Git에 없네?"
  ↓
kubectl delete deployment myapp  # ← 자동 삭제!

automated.selfHeal:

kubectl scale deployment myapp --replicas=10
  ↓
ArgoCD: "Git에는 2인데 실제는 10이네?" (5초마다 체크)
  ↓
kubectl apply (Git 상태로 복구)

syncOptions:

- CreateNamespace=true   # 네임스페이스 없으면 생성
- PrunePropagationPolicy=foreground  # 삭제 순서 제어
- Validate=false         # kubectl validation 건너뛰기

retry:

1차 시도 실패
  ↓ 5초 대기
2차 시도 실패
  ↓ 10초 대기 (factor=2)
3차 시도 실패
  ↓ 20초 대기
...
최대 3분까지 재시도

9. 최종 GitOps 워크플로우

개발 → 배포 전체 흐름

1. 개발자: 코드 수정
   $ vi src/app.py
   $ docker build -t myapp:v1.2.3 .
   $ docker push ghcr.io/user/myapp:v1.2.3

2. Helm Values 업데이트
   $ vi myapp/values-prod.yaml
   ---
   image:
     tag: "v1.2.3"  # ← 새 버전
   ---

3. Git Push
   $ git add myapp/values-prod.yaml
   $ git commit -m "Update to v1.2.3"
   $ git push origin main

4. Pull Request (선택)
   - Code Review
   - CI 테스트 (GitHub Actions)
   - Approve & Merge

5. ArgoCD 자동 감지
   - 3분마다 Git Poll (또는 Webhook)
   - "main 브랜치 커밋 감지!"

6. ArgoCD Sync
   - Helm Template 렌더링
   - Kubernetes 매니페스트 생성
   - kubectl apply

7. Kubernetes 롤링 업데이트
   - Pod v1.2.2 → v1.2.3 교체
   - Readiness Probe 확인
   - 무중단 배포 완료!

8. ArgoCD 상태 업데이트
   - Sync Status: Synced
   - Health Status: Healthy
   - Slack 알림 (설정 시)

Git Commit → 자동 배포까지 소요 시간

Git Push
  ↓
GitHub (즉시)
  ↓
ArgoCD Polling (최대 3분) or Webhook (즉시)
  ↓
Helm Rendering (5초)
  ↓
kubectl apply (10초)
  ↓
Pod 롤링 업데이트 (30초~2분)
  ↓
Healthy 상태 확인 (10초)
  ↓
Total: 약 1~5분 (Webhook 사용 시 더 빠름!)

배운 점

1. Helm은 피곤하지만 가치 있다

Custom Chart 생성:

처음엔 피곤한 작업:
❌ Chart.yaml 작성
❌ templates/ 디렉토리 구조 설계
❌ values.yaml 변수 정의
❌ {{ .Values.xxx }} 템플릿 문법

하지만 한 번 만들면:
✅ 무한 재사용
✅ 환경 추가 = values 파일 하나
✅ 버전 관리 (helm rollback)
✅ 공유 가능 (Helm Repository)

실무 팁:

• 공식 Chart 먼저 검색 (bitnami/nginx, stable/mysql)
• 없으면 helm create로 시작
• 복잡한 로직은 _helpers.tpl로 분리

2. ArgoCD는 Helm을 알아서 인식

연동 설정 없이 동작:

Git 저장소에 Chart.yaml 있으면?
  ↓
ArgoCD: "아, Helm Chart구나!"
  ↓
자동으로:
  - helm template 실행
  - values 파일 머지
  - Kubernetes 매니페스트 생성
  - kubectl apply

helm.valueFiles 위치:

• Application CRD의 spec.source.helm.valueFiles
• 배열로 여러 파일 지정 가능
• 우선순위: 나중 파일이 앞 파일 덮어씀

3. Self-Heal은 Git 강제 동기화

작동 원리:

매 5초마다:
1. Git에서 최신 매니페스트 가져오기
2. kubectl get으로 실제 상태 확인
3. Diff 계산 (Desired vs Actual)
4. OutOfSync 발견 시 kubectl apply

→ 수동 변경은 무의미!
→ Git만 수정하세요!

예외 상황:

• HPA로 replicas 자동 조정 → ignoreDifferences 설정
• StatefulSet ordinal → ignoreDifferences 설정

4. Sync Waves는 순서 보장의 핵심

왜 필요한가:

일반 배포:
DB, App, Migration Job 동시 생성
→ 랜덤 순서!
→ App이 먼저 뜨면 DB 연결 실패

Sync Waves:
Wave 0: DB
Wave 1: Migration (PreSync Hook)
Wave 2: App
→ 순서 보장!
→ 안정적 배포!

Hook 활용:

• PreSync: DB 스키마 마이그레이션
• Sync: 일반 리소스
• PostSync: 통합 테스트, Slack 알림
• SyncFail: 롤백, 에러 로그 수집

5. 환경별 배포는 Values로 해결

하나의 Chart, 여러 환경:

myapp/ (Helm Chart)
├─ values.yaml       (공통 기본값)
├─ values-dev.yaml   (개발: replica=1, resources 최소)
├─ values-staging.yaml (스테이징: replica=2, 중간)
└─ values-prod.yaml  (프로덕션: replica=5, HPA, NodePort)

Application CRD:
myapp-dev      → valueFiles: [values-dev.yaml]
myapp-staging  → valueFiles: [values-staging.yaml]
myapp-prod     → valueFiles: [values-prod.yaml]

→ 템플릿 중복 없음!
→ 환경별 차이만 values에!

삽질 포인트

1. Helm Chart 생성 피곤함

증상: 템플릿 하나하나 다 작성해야 함

해결:

• helm create myapp로 스캐폴딩 활용
• 불필요한 템플릿 삭제 (hpa.yaml, ingress.yaml 등)
• 공식 Chart 참고 (github.com/bitnami/charts)

2. values-*.yaml 찾기 어려움

증상: ArgoCD UI에서 어떤 values 쓰는지 안 보임

해결:

# Application YAML 확인
$ kubectl get application myapp-dev -n argocd -o yaml
spec:
  source:
    helm:
      valueFiles:
        - values-dev.yaml  # ← 여기!

3. Self-Heal이 내 변경을 계속 되돌림

증상: kubectl edit으로 수정해도 5초 후 복구됨

교훈:

• Self-Heal이 켜져 있으면 Git만 수정!

• 긴급 수정 필요 시:

  # Self-Heal 임시 비활성화
  $ kubectl patch application myapp-dev -n argocd --type=merge \
    -p '{"spec":{"syncPolicy":{"automated":{"selfHeal":false}}}}'
  
  # 수정 작업
  $ kubectl edit deployment myapp -n myapp-dev
  
  # 다시 활성화
  $ kubectl patch application myapp-dev -n argocd --type=merge \
    -p '{"spec":{"syncPolicy":{"automated":{"selfHeal":true}}}}'

4. Sync Waves 순서 헷갈림

증상: Wave 2가 Wave 1보다 먼저 배포됨

원인: 숫자가 아닌 문자열 정렬

❌ sync-wave: 10  # "10"은 "2"보다 앞!
✅ sync-wave: "10"

교훈:

• Wave 번호는 항상 따옴표로 감싸기
• 음수 가능: -1 (Wave 0보다 먼저)

다음 계획 (Day 9)

Day 8에서 Helm + ArgoCD로 GitOps 파이프라인을 완성했습니다. 이제 Day 9부터는 마이크로서비스 통신을 관리하는 Istio Service Mesh를 단계별로 학습합니다.

Day 9 주제: Istio 소개와 첫걸음

1. 마이크로서비스 문제점과 Service Mesh 필요성

   • 서비스 간 통신 복잡도 (N×N 연결)
   • 장애 전파 (Cascading Failure)
   • 관찰성 부족 및 보안 이슈

2. Istio 아키텍처 이해

   • Control Plane (Istiod): Pilot, Citadel, Galley
   • Data Plane (Envoy): Sidecar 패턴
   • xDS API를 통한 설정 전달

3. 실습 환경 구축

   • Kind 클러스터 구성
   • Istio 설치 (default 프로파일, 프로덕션 설정)
   • Bookinfo 샘플 애플리케이션 배포
   • Sidecar 자동 주입 확인

4. 관측 도구 설치

   • Kiali: 서비스 토폴로지 시각화
   • Prometheus & Grafana: 메트릭 수집
   • Vector + OpenTelemetry + OpenSearch: 로그 수집 준비

Day 10 이후 학습 로드맵

Istio 심화 학습 (단계별):

• Day 10: Sail Operator (Istio 관리 자동화)
• Day 11: Envoy Proxy 심화 (Listener, Route, Cluster)
• Day 12: Istio Gateways (Ingress/Egress)
• Day 13: Traffic Management (Canary, A/B 테스팅, Blue-Green)
• Day 14: Resiliency (Retry, Circuit Breaker, Timeout)
• Day 15: Observability (Kiali, Jaeger 분산 추적)
• Day 16: Security (mTLS, Authorization Policy)
• Day 17: Troubleshooting & Performance Tuning
• Day 18: Scaling & VM Support
• Day 19: Ambient Mesh (Sidecar-less 아키텍처)

실전 도전 과제:

• ArgoCD + Istio로 Progressive Delivery 구현
• Multi-Cluster Service Mesh 구성
• Fault Injection을 통한 카오스 엔지니어링
• Zero Trust 보안 모델 적용

마무리

GitOps는 단순한 도구가 아니라 철학입니다. Git을 단일 진실 소스로 삼고, 모든 변경을 코드로 관리하는 것!

핵심 요약:

• ✅ Helm = 템플릿 + Values로 환경별 배포
• ✅ ArgoCD = Git → Kubernetes 자동 동기화
• ✅ Self-Heal = Git 상태 강제 (5초마다)
• ✅ Sync Waves = 순차적 배포 (DB → Migration → App)
• ✅ GitOps = Pull Request 기반 배포 (코드 리뷰 + 이력 추적)

Day 9에서 만나요! 🚀

참고 자료

• Helm Documentation
• ArgoCD Documentation
• GitOps Principles
• Sync Waves & Hooks

2025년 11월 7일 단일 노드 한계를 넘어! RBD/CephFS/RGW 세 가지 스토리지를 모두 구축하다

들어가며

Day 6에서 Prometheus + Grafana로 모니터링, Vector + OpenSearch로 로그 중앙화를 마스터했습니다. 이제 Day 7에서는 Kubernetes의 꽃이라 할 수 있는 분산 스토리지 Ceph를 직접 구축하고 세 가지 스토리지 타입을 모두 테스트했습니다.

오늘 배운 것:

1. Ceph 아키텍처 완벽 이해 (RADOS, CRUSH, PG 개념)
2. Rook Operator로 단일 노드 Ceph 클러스터 구축
3. RBD 블록 스토리지 (ReadWriteOnce) - 동적 프로비저닝
4. CephFS 파일 시스템 (ReadWriteMany) - 다중 Pod 동시 접근
5. RGW 오브젝트 스토리지 (S3 API) - 사용자 및 버킷 생성
6. Ceph Dashboard 웹 UI로 클러스터 모니터링
7. 단일 노드 환경의 한계와 해결 방법

1. Ceph가 뭐길래?

왜 Ceph인가?

🤔 내가 이해한 것:

기존에는 hostPath나 emptyDir로 Pod에 볼륨을 붙였습니다. 하지만 이건 문제가 있었어요:

문제점:
❌ hostPath: 특정 노드에 종속 (Pod가 다른 노드로 옮겨가면 데이터 유실)
❌ emptyDir: Pod 삭제 시 데이터 사라짐
❌ NFS: 단일 장애점 (NFS 서버 다운 = 전체 다운)

Ceph의 해결책:
✅ 분산 스토리지: 데이터를 여러 노드에 자동 복제
✅ 자가 복구: 노드 장애 시 자동으로 다른 노드에 데이터 재배치
✅ 무제한 확장: 노드 추가 = 스토리지 용량 증가
✅ 3가지 인터페이스: Block (RBD), File (CephFS), Object (S3)

HostPath vs Ceph 비교:

HostPath 방식:
Pod A (cpu1 노드)
  ↓
/data/app (cpu1의 로컬 디스크)

→ Pod가 cpu2로 옮겨가면? 데이터 접근 불가!

Ceph 방식:
Pod A (어느 노드든)
  ↓
Ceph 클러스터 (cpu1 + cpu2 + gpu1)
  ├─ 복제본 1: cpu1
  ├─ 복제본 2: cpu2
  └─ 복제본 3: gpu1

→ Pod가 어디로 옮겨가든 데이터 접근 가능!
→ 노드 1개 다운되어도 괜찮음!

Ceph 핵심 개념 정리

RADOS (Reliable Autonomic Distributed Object Store):

• Ceph의 심장부
• 모든 데이터를 Object로 저장
• 자가 관리, 자가 복구

CRUSH (Controlled Replication Under Scalable Hashing):

마법의 알고리즘!
- 중앙 조회 테이블 없음
- 클라이언트가 직접 계산해서 데이터 위치 찾음
- 노드 추가/제거 시 최소한의 데이터 이동

작동 원리:
Object Name + Cluster Map → Hash 계산
→ Placement Group (PG) 결정
→ CRUSH Rules 적용
→ 최종 OSD 위치 계산

Placement Groups (PG):

왜 필요한가?

100만 객체를 12 OSD에 직접 매핑하면?
→ 관리 복잡도: O(n×m) = 1,200만 관계

100만 객체 → 512 PG → 12 OSD로 매핑하면?
→ 관리 복잡도: O(n+m) = 100만 + 512 + 12

PG는 객체와 OSD 사이의 중간 레이어!

2. Ceph 클러스터 구축 실습

실습 환경 결정

원래 계획: 3노드 HA 구성

cpu1 + cpu2 + gpu1 = 3노드 Ceph 클러스터
각 노드에 sdb 디스크 할당
복제본 3개 (size: 3)

변경된 계획: 단일 노드 학습용

이유:

• cpu2는 이미 다른 워크로드 사용 중
• gpu1에 여유 디스크 sdb (465GB) 발견
• 학습 목적이므로 단일 노드로 충분

# gpu1 노드 디스크 확인
$ lsblk
NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sda      8:0    0 465.8G  0 disk
├─sda1   8:1    0 465.7G  0 part /
└─sda2   8:2    0     1M  0 part
sdb      8:16   0 465.8G  0 disk  ← 이걸 Ceph에 사용!

🎯 단일 노드 Ceph 설정의 핵심:

failureDomain: osd  # host가 아닌 osd 단위
replicated:
  size: 1            # 복제본 1개
  requireSafeReplicaSize: false  # 안전성 검사 비활성화

실습 1: Rook Operator 설치

Rook이 뭐지?

• Kubernetes Operator 패턴으로 Ceph 자동 관리
• CRD (Custom Resource Definition) 제공
• 선언적 설정 (YAML로 Ceph 클러스터 생성)

# 1. CRD 설치
$ kubectl apply -f https://raw.githubusercontent.com/rook/rook/release-1.14/deploy/examples/crds.yaml
customresourcedefinition.apiextensions.k8s.io/cephblockpools.ceph.rook.io created
customresourcedefinition.apiextensions.k8s.io/cephfilesystems.ceph.rook.io created
customresourcedefinition.apiextensions.k8s.io/cephobjectstores.ceph.rook.io created
...

# 2. Common 리소스 (RBAC, ServiceAccount 등)
$ kubectl apply -f https://raw.githubusercontent.com/rook/rook/release-1.14/deploy/examples/common.yaml
namespace/rook-ceph created
serviceaccount/rook-ceph-system created
...

# 3. Operator 배포
$ kubectl apply -f https://raw.githubusercontent.com/rook/rook/release-1.14/deploy/examples/operator.yaml
deployment.apps/rook-ceph-operator created

# 4. Operator Pod 확인
$ kubectl get pods -n rook-ceph
NAME                                 READY   STATUS    RESTARTS   AGE
rook-ceph-operator-5b7c8d8d4-xxxxx   1/1     Running   0          2m

🎉 성공! Rook Operator가 실행되고 있습니다!

2.5 Rook CRD와 Ceph 컴포넌트 완전 분석

Rook Operator를 설치했으니, 이제 어떤 CRD가 제공되고 각 Pod가 무슨 역할을 하는지 정확히 이해해야 합니다!

Rook이 제공하는 주요 CRD (Custom Resource Definition)

$ kubectl get crd | grep ceph.rook.io

핵심 CRD 목록:

🤔 왜 CRD가 필요한가?

전통적인 Ceph 구축:

# 수동 명령어 실행 (어렵고 복잡)
ceph-deploy mon create node1 node2 node3
ceph-deploy osd prepare node1:/dev/sdb
ceph osd pool create mypool 128
ceph fs new myfs myfs-metadata myfs-data

Rook + CRD 방식:

# 선언적 YAML (쉽고 재현 가능!)
apiVersion: ceph.rook.io/v1
kind: CephCluster
metadata:
  name: rook-ceph
spec:
  mon:
    count: 3
  storage:
    nodes:
    - name: "gpu1"
      devices:
      - name: "sdb"

→ kubectl apply 한 번으로 끝! → Operator가 알아서 MON, MGR, OSD 배포 → Git으로 버전 관리 가능 (GitOps)

Ceph 클러스터 배포 후 실제 Pod 분석

$ kubectl get pods -n rook-ceph
NAME                                             READY   STATUS
rook-ceph-operator-xxxxx                          1/1     Running   # Operator
rook-ceph-mon-a-xxxxx                             1/1     Running   # Monitor
rook-ceph-mgr-a-xxxxx                             1/1     Running   # Manager
rook-ceph-osd-0-xxxxx                             1/1     Running   # OSD
rook-ceph-mds-myfs-a-xxxxx                        1/1     Running   # MDS (CephFS용)
rook-ceph-mds-myfs-b-xxxxx                        1/1     Running   # MDS Standby
rook-ceph-rgw-my-store-a-xxxxx                    1/1     Running   # RGW (S3용)
rook-ceph-crashcollector-gpu1-xxxxx               1/1     Running   # Crash 수집
rook-ceph-exporter-gpu1-xxxxx                     1/1     Running   # Prometheus 메트릭
csi-rbdplugin-xxxxx                               2/2     Running   # RBD CSI Driver
csi-rbdplugin-provisioner-xxxxx                   5/5     Running   # RBD Provisioner
csi-cephfsplugin-xxxxx                            2/2     Running   # CephFS CSI Driver
csi-cephfsplugin-provisioner-xxxxx                5/5     Running   # CephFS Provisioner
rook-ceph-tools-xxxxx                             1/1     Running   # CLI 도구

각 Pod의 역할 상세 설명

1️⃣ rook-ceph-operator (Operator 패턴의 두뇌)

역할:
- CephCluster CRD를 감시
- YAML 변경 시 실제 Ceph 리소스 생성/업데이트
- Pod 장애 시 자동 복구
- Kubernetes API와 Ceph 명령어를 연결하는 브릿지

예시:
CephBlockPool YAML 적용 → Operator가 감지
→ ceph osd pool create 명령 실행
→ Pool 생성 완료

2️⃣ rook-ceph-mon-a (Monitor - 클러스터 상태 추적)

역할:
- Cluster Map 유지 (MON, OSD, PG 상태)
- Quorum 형성 (과반수 합의)
- 클라이언트에게 Cluster Map 제공

왜 홀수 개?
- 2개: 1개 다운 시 Quorum 불가 (50% < 과반수)
- 3개: 1개 다운 OK (2/3 = 66% > 과반수)
- 1개: 단일 노드 학습용 (HA 불가)

통신 포트:
- 6789: Ceph v1 protocol
- 3300: Ceph v2 protocol

3️⃣ rook-ceph-mgr-a (Manager - 관리와 모니터링)

역할:
- Ceph Dashboard 웹 UI 제공
- Prometheus 메트릭 노출
- PG Autoscaler 실행
- REST API 제공

모듈:
- dashboard: 웹 UI (port 7000)
- prometheus: 메트릭 수집 (port 9283)
- pg_autoscaler: PG 수 자동 조정
- balancer: OSD 간 데이터 균형

Active-Standby:
- mgr-a: Active (요청 처리)
- mgr-b: Standby (장애 대기)

4️⃣ rook-ceph-osd-0 (Object Storage Daemon - 실제 데이터 저장)

역할:
- 실제 데이터 저장 (sdb 디스크 사용)
- 데이터 복제 (다른 OSD로)
- Heartbeat (다른 OSD와 상태 확인)
- Backfilling (데이터 재배치)

OSD 번호:
- OSD.0: gpu1의 sdb 디스크
- (추가 노드 시 OSD.1, OSD.2, ...)

데이터 경로:
/var/lib/rook/osd0/
  ├─ block → /dev/sdb (심볼릭 링크)
  ├─ block.db (메타데이터, SSD 권장)
  └─ block.wal (WAL, SSD 권장)

포트:
- 6800-7300: OSD 간 통신

5️⃣ rook-ceph-mds-myfs-a/b (Metadata Server - CephFS 전용)

역할:
- CephFS 파일 메타데이터 관리
- 디렉토리 구조, 권한, 소유자 정보
- inode 캐싱 (성능 향상)

왜 2개?
- mds-a: Active (실제 요청 처리)
- mds-b: Standby (장애 대기)
- Active 장애 시 Standby가 즉시 승격 (30초 이내)

메타데이터 vs 데이터:
메타데이터 (MDS가 관리):
  - 파일명: /data/myfile.txt
  - 크기: 1GB
  - 권한: 0644

실제 데이터 (OSD에 저장):
  - Object 1: myfile.txt.00000000 (4MB)
  - Object 2: myfile.txt.00000001 (4MB)
  - ...

6️⃣ rook-ceph-rgw-my-store-a (RADOS Gateway - S3 API)

역할:
- S3 호환 REST API 제공
- 버킷 및 오브젝트 관리
- 사용자 인증 (AccessKey/SecretKey)
- Multi-part Upload 지원

엔드포인트:
- http://rook-ceph-rgw-my-store.rook-ceph:80
- S3 API: PUT /bucket/object

데이터 흐름:
1. AWS CLI: aws s3 cp file.txt s3://mybucket/
2. RGW: S3 요청 → Ceph Object 변환
3. RADOS: Object를 PG로 매핑 → OSD 저장

7️⃣ csi-rbdplugin / csi-cephfsplugin (CSI Driver)

역할:
- Kubernetes CSI 인터페이스 구현
- PVC 생성 시 실제 볼륨 Attach/Mount
- 각 노드마다 DaemonSet으로 배포

RBD CSI Driver:
- RBD 이미지 생성: rbd create
- 노드에 Map: rbd map /dev/rbd0
- 파일시스템 생성: mkfs.ext4
- Pod에 Mount: mount /dev/rbd0 /var/lib/kubelet/pods/...

CephFS CSI Driver:
- CephFS 서브볼륨 생성
- Ceph Client 마운트
- FUSE 또는 Kernel Driver 사용

8️⃣ csi-rbdplugin-provisioner / csi-cephfsplugin-provisioner

역할:
- PVC 생성 요청 감시
- 동적 프로비저닝 실행
- PV 생성 및 PVC 바인딩

워크플로우:
1. User: kubectl apply -f pvc.yaml
2. Provisioner: PVC 감지 (StorageClass 확인)
3. Provisioner: Ceph에 볼륨 생성 (RBD 또는 CephFS)
4. Provisioner: PV 오브젝트 생성
5. Kubernetes: PVC ↔ PV 바인딩 (Bound 상태)

왜 5개 컨테이너?
- csi-provisioner: 메인 프로비저너
- csi-resizer: 볼륨 크기 조정
- csi-snapshotter: 스냅샷 생성
- csi-attacher: 볼륨 Attach
- liveness: Health Check

9️⃣ rook-ceph-crashcollector (Crash 정보 수집)

역할:
- Ceph 데몬 Crash 시 덤프 수집
- /var/lib/rook/crash/ 디렉토리 모니터링
- Crash 정보를 MON에 전송
- 문제 디버깅에 사용

확인:
$ ceph crash ls
$ ceph crash info <crash-id>

🔟 rook-ceph-exporter (Prometheus 메트릭)

역할:
- Ceph 메트릭을 Prometheus 포맷으로 노출
- OSD 상태, Pool 사용량, PG 상태 등
- Day 6 Prometheus와 연동

메트릭 예시:
- ceph_health_status (0=OK, 1=WARN, 2=ERR)
- ceph_osd_up (OSD UP 개수)
- ceph_pool_stored_bytes (Pool 사용량)

ServiceMonitor 연동:
monitoring:
  enabled: true
→ MGR이 ServiceMonitor 생성
→ Prometheus가 자동 수집

1️⃣1️⃣ rook-ceph-tools (CLI 도구 Pod)

역할:
- ceph 명령어 실행 환경
- 디버깅 및 관리 작업

사용법:
$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- ceph status
$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- ceph osd tree
$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- rados df

포함된 도구:
- ceph: 메인 CLI
- rbd: RBD 관리
- rados: Object 관리
- ceph-volume: OSD 관리

Ceph 데이터 흐름 완전 정리

예시: MySQL Pod가 10GB RBD PVC 요청

1. kubectl apply -f mysql-pvc.yaml
   ↓
2. csi-rbdplugin-provisioner가 감지
   ↓
3. Provisioner → Ceph: rbd create replicapool/pvc-xxxxx --size 10240
   ↓
4. CRUSH 알고리즘: PG.1 계산
   ↓
5. PG.1 → OSD.0 매핑 (단일 노드이므로 OSD.0만)
   ↓
6. OSD.0: /dev/sdb에 데이터 저장
   ↓
7. Provisioner: PV 오브젝트 생성
   ↓
8. Kubernetes: PVC ↔ PV 바인딩 (Bound)
   ↓
9. MySQL Pod 스케줄링 → cpu1 노드
   ↓
10. csi-rbdplugin (cpu1): rbd map → /dev/rbd0
   ↓
11. csi-rbdplugin: mount /dev/rbd0 → /var/lib/kubelet/pods/.../volumes/
   ↓
12. MySQL 컨테이너: /var/lib/mysql 마운트 완료!

Multi-node 환경이라면?

PG.1 → [OSD.0, OSD.1, OSD.2] (3중 복제)
- Primary OSD.0 (cpu1): 쓰기 처리
- Replica OSD.1 (cpu2): 복제본 저장
- Replica OSD.2 (gpu1): 복제본 저장

→ 노드 1개 다운되어도 데이터 안전!

실습 2: 디스크 초기화

중요! OSD로 사용할 디스크는 완전히 깨끗해야 합니다!

# sdb 디스크 완전 초기화
$ wipefs -a /dev/sdb
$ sgdisk --zap-all /dev/sdb
$ dd if=/dev/zero of=/dev/sdb bs=1M count=100

# 확인 (FSTYPE이 비어있어야 함)
$ lsblk -f | grep sdb
sdb

실습 3: Ceph 클러스터 생성

단일 노드용 cluster YAML 작성:

# ~/ceph/ceph-cluster.yaml
apiVersion: ceph.rook.io/v1
kind: CephCluster
metadata:
  name: rook-ceph
  namespace: rook-ceph
spec:
  cephVersion:
    image: quay.io/ceph/ceph:v18.2.0
  dataDirHostPath: /var/lib/rook

  mon:
    count: 1  # 단일 노드이므로 MON 1개

  mgr:
    count: 1
    modules:
      - name: pg_autoscaler
        enabled: true

  dashboard:
    enabled: true
    ssl: false

  monitoring:
    enabled: true  # Prometheus 연동!

  storage:
    useAllNodes: false
    useAllDevices: false
    nodes:
    - name: "gpu1"
      devices:
      - name: "sdb"  # 465.8GB 디스크

  disruptionManagement:
    managePodBudgets: false  # 단일 노드에서는 비활성화

적용:

$ kubectl apply -f ~/ceph/ceph-cluster.yaml
cephcluster.ceph.rook.io/rook-ceph created

# Pod 생성 확인 (30초~1분 소요)
$ kubectl get pods -n rook-ceph
NAME                                      READY   STATUS    RESTARTS   AGE
rook-ceph-mon-a-xxxxx                     1/1     Running   0          45s
rook-ceph-mgr-a-xxxxx                     1/1     Running   0          30s
rook-ceph-osd-prepare-gpu1-xxxxx          0/1     Completed 0          15s
rook-ceph-osd-0-xxxxx                     1/1     Running   0          10s

🎉 MON, MGR, OSD 모두 Running!

트러블슈팅 1: ServiceMonitor 권한 에러

Ceph 클러스터가 올라오긴 했지만, MGR Pod 로그를 보니 에러가 보였습니다!

문제 발견:

$ kubectl logs -n rook-ceph rook-ceph-mgr-a-xxxxx
Error: servicemonitors.monitoring.coreos.com "rook-ceph-mgr" is forbidden:
User "system:serviceaccount:rook-ceph:rook-ceph-system" cannot get resource "servicemonitors"
in API group "monitoring.coreos.com" at the cluster scope

🤔 왜 RBAC 권한이 필요한가?

상황 이해:

1. Ceph MGR의 역할:

   • Prometheus 메트릭 노출 (Day 6에서 설치한 Prometheus와 통합)
   • monitoring.enabled: true 설정 시 ServiceMonitor CRD 자동 생성

2. ServiceMonitor란?:

   # Prometheus Operator의 CRD
   apiVersion: monitoring.coreos.com/v1
   kind: ServiceMonitor
   metadata:
     name: rook-ceph-mgr
   spec:
     endpoints:
     - port: http-metrics  # Ceph MGR 메트릭 수집

   • Prometheus에게 "이 Service를 스크랩해라" 알림
   • Prometheus Operator가 감시하다가 자동으로 설정 업데이트

3. 권한 문제:

   Ceph MGR Pod (rook-ceph-system ServiceAccount)
     ↓
   "ServiceMonitor 생성하려고 함"
     ↓
   Kubernetes API Server: "권한 없음! Forbidden!"

RBAC의 3가지 구성요소

1. ServiceAccount (신원 증명):

$ kubectl get sa -n rook-ceph rook-ceph-system
NAME               SECRETS   AGE
rook-ceph-system   0         10m

• MGR Pod가 사용하는 계정
• Pod spec에 serviceAccountName: rook-ceph-system 설정됨
• 이 계정으로 Kubernetes API 호출

2. ClusterRole (권한 정의):

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: rook-ceph-servicemonitor-access
rules:
- apiGroups: ["monitoring.coreos.com"]   # Prometheus Operator API
  resources: ["servicemonitors"]         # ServiceMonitor CRD
  verbs: ["get", "list", "watch", "create", "update", "delete"]  # CRUD 권한

• apiGroups: CRD의 API 그룹 (Prometheus Operator 설치 시 생성)
• resources: 어떤 리소스에 접근?
• verbs: 무슨 작업? (GET, POST, PUT, DELETE)

3. ClusterRoleBinding (계정과 권한 연결):

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: rook-ceph-servicemonitor-access
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: rook-ceph-servicemonitor-access  # 위에서 정의한 Role
subjects:
- kind: ServiceAccount
  name: rook-ceph-system                # 이 계정에게
  namespace: rook-ceph                   # rook-ceph 네임스페이스의

왜 기본 RBAC에 없었나?

이유:

• Rook Operator는 Prometheus Operator 설치 여부를 모름
• Prometheus Operator의 CRD (ServiceMonitor)는 선택적 의존성
• 모든 사용자가 Prometheus를 쓰는 건 아니므로, 기본 RBAC에 포함 안 함

Rook이 제공하는 기본 RBAC:

# common.yaml에 포함된 기본 권한
- apiGroups: [""]
  resources: ["pods", "services", "configmaps", "secrets"]
  verbs: ["get", "list", "watch", "create", "update", "delete"]
- apiGroups: ["apps"]
  resources: ["deployments", "daemonsets", "statefulsets"]
  verbs: ["get", "list", "watch", "create", "update", "delete"]
# ... (ServiceMonitor는 없음!)

해결 방법

RBAC 생성:

# ~/ceph/rook-servicemonitor-rbac.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: rook-ceph-servicemonitor-access
rules:
- apiGroups: ["monitoring.coreos.com"]
  resources: ["servicemonitors"]
  verbs: ["get", "list", "watch", "create", "update", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: rook-ceph-servicemonitor-access
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: rook-ceph-servicemonitor-access
subjects:
- kind: ServiceAccount
  name: rook-ceph-system
  namespace: rook-ceph

적용:

$ kubectl apply -f ~/ceph/rook-servicemonitor-rbac.yaml
clusterrole.rbac.authorization.k8s.io/rook-ceph-servicemonitor-access created
clusterrolebinding.rbac.authorization.k8s.io/rook-ceph-servicemonitor-access created

결과 확인:

# MGR이 ServiceMonitor 생성 성공!
$ kubectl get servicemonitor -n rook-ceph
NAME              AGE
rook-ceph-mgr     2m

# Prometheus가 자동 수집 시작
$ kubectl get servicemonitor -n rook-ceph rook-ceph-mgr -o yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: rook-ceph-mgr
  namespace: rook-ceph
spec:
  endpoints:
  - port: http-metrics  # MGR의 9283 포트
    interval: 30s
  namespaceSelector:
    matchNames:
    - rook-ceph
  selector:
    matchLabels:
      app: rook-ceph-mgr

Prometheus 확인:

# Prometheus UI (http://<NODE-IP>:30090) → Targets
# rook-ceph/rook-ceph-mgr/0 (http://10.x.x.x:9283/metrics) UP

✅ 해결! MGR이 정상적으로 ServiceMonitor를 생성하고, Prometheus가 Ceph 메트릭을 수집하기 시작했습니다!

배운 점

RBAC의 중요성:

• Kubernetes는 기본적으로 최소 권한 원칙 (Least Privilege)
• Pod가 API 호출 시 ServiceAccount의 권한 확인
• CRD는 동적으로 추가된 리소스이므로 명시적 RBAC 필요

실무 팁:

# 권한 에러 디버깅
$ kubectl logs -n <namespace> <pod-name> | grep -i "forbidden\|unauthorized"

# ServiceAccount 권한 확인
$ kubectl auth can-i create servicemonitors \
  --as=system:serviceaccount:rook-ceph:rook-ceph-system \
  -n rook-ceph
no

# RBAC 적용 후
$ kubectl auth can-i create servicemonitors \
  --as=system:serviceaccount:rook-ceph:rook-ceph-system \
  -n rook-ceph
yes  # ✅

실습 4: Ceph Toolbox로 상태 확인

# Toolbox 배포
$ kubectl apply -f https://raw.githubusercontent.com/rook/rook/release-1.14/deploy/examples/toolbox.yaml
deployment.apps/rook-ceph-tools created

# Toolbox에 들어가서 Ceph 상태 확인
$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- ceph status
  cluster:
    id:     6fa3b356-4964-460e-9a29-e8e350febeff
    health: HEALTH_WARN
            OSD count 1 < osd_pool_default_size 3

  services:
    mon: 1 daemons, quorum a (age 5m)
    mgr: a(active, since 4m)
    osd: 1 osds: 1 up (since 3m), 1 in (since 3m)

  data:
    pools:   0 pools, 0 pgs
    objects: 0 objects, 0 B
    usage:   27 MiB used, 466 GiB / 466 GiB avail

HEALTH_WARN는 정상입니다!

• 단일 노드 환경이라 복제본을 못 만들어서 경고
• 프로덕션에서는 HEALTH_OK가 나와야 함

3. RBD 블록 스토리지 (ReadWriteOnce)

왜 RBD가 필요한가?

RBD (RADOS Block Device):

• 가상 블록 디바이스 제공
• 데이터베이스, VM 디스크 같은 단일 Pod 전용 스토리지
• ReadWriteOnce (RWO): 한 번에 하나의 Pod만 접근

실습 5: CephBlockPool 생성

트러블슈팅 2: PG undersized+peered 문제

첫 시도 (실패):

# GitHub의 기본 storageclass 적용
$ kubectl apply -f https://raw.githubusercontent.com/rook/rook/release-1.14/deploy/examples/csi/rbd/storageclass.yaml

# PVC 생성
$ kubectl apply -f test-pvc.yaml

# PVC 상태 확인
$ kubectl get pvc
NAME        STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS      AGE
test-pvc    Pending                                      rook-ceph-block   2m

문제 확인:

$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- ceph status
  data:
    pools:   1 pools, 32 pgs
    pgs:     32 undersized+peered  ← 문제!
             100.000% pgs not active

원인: 기본 BlockPool 설정이 다중 노드용

failureDomain: host  # ❌ 여러 호스트에 분산
replicated:
  size: 3  # ❌ 복제본 3개 필요

해결: 단일 노드용 BlockPool 생성

# ~/ceph/single-node-blockpool.yaml
apiVersion: ceph.rook.io/v1
kind: CephBlockPool
metadata:
  name: replicapool
  namespace: rook-ceph
spec:
  failureDomain: osd  # ✅ OSD 단위로 변경
  replicated:
    size: 1  # ✅ 복제본 1개
    requireSafeReplicaSize: false  # ✅ 안전성 검사 비활성화

# 기존 pool 삭제 후 재생성
$ kubectl delete cephblockpool -n rook-ceph replicapool
$ kubectl apply -f ~/ceph/single-node-blockpool.yaml

# PG 상태 확인
$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- ceph status
  data:
    pools:   1 pools, 32 pgs
    pgs:     32 active+clean  ← ✅ 성공!

실습 6: PVC 동적 프로비저닝 테스트

# ~/ceph/test-ceph-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-ceph-pvc
spec:
  accessModes:
  - ReadWriteOnce  # RWO
  storageClassName: rook-ceph-block
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: test-ceph-pod
spec:
  containers:
  - name: test
    image: busybox:1.28
    command: ["sh", "-c", "echo 'Hello Ceph!' > /data/test.txt && cat /data/test.txt && sleep 3600"]
    volumeMounts:
    - name: ceph-volume
      mountPath: /data
  volumes:
  - name: ceph-volume
    persistentVolumeClaim:
      claimName: test-ceph-pvc

$ kubectl apply -f ~/ceph/test-ceph-pvc.yaml
persistentvolumeclaim/test-ceph-pvc created
pod/test-ceph-pod created

# PVC 상태 확인
$ kubectl get pvc
NAME            STATUS   VOLUME                                     CAPACITY   ACCESS MODES
test-ceph-pvc   Bound    pvc-4d7204b9-98c0-416b-9574-25af51682854   1Gi        RWO

# Pod 상태 확인
$ kubectl get pod test-ceph-pod
NAME            READY   STATUS    RESTARTS   AGE
test-ceph-pod   1/1     Running   0          20s

# 로그 확인
$ kubectl logs test-ceph-pod
Hello Ceph!

🎉 RBD 블록 스토리지 성공!

4. CephFS 파일 시스템 (ReadWriteMany)

왜 CephFS가 특별한가?

ReadWriteMany (RWX)의 의미:

• 여러 Pod가 동시에 같은 볼륨을 읽고 쓸 수 있음!
• 공유 파일 시스템 (POSIX 호환)
• NFS 대체용

사용 사례:

• 여러 웹 서버가 같은 static files 공유
• 분산 로그 수집
• 공유 설정 파일

실습 7: CephFilesystem 생성

CephFS는 MDS (Metadata Server)가 필요합니다!

# ~/ceph/cephfs-filesystem.yaml
apiVersion: ceph.rook.io/v1
kind: CephFilesystem
metadata:
  name: myfs
  namespace: rook-ceph
spec:
  metadataPool:
    failureDomain: osd
    replicated:
      size: 1
      requireSafeReplicaSize: false

  dataPools:
    - name: data0
      failureDomain: osd
      replicated:
        size: 1
        requireSafeReplicaSize: false

  metadataServer:
    activeCount: 1
    activeStandby: false

$ kubectl apply -f ~/ceph/cephfs-filesystem.yaml
cephfilesystem.ceph.rook.io/myfs created

# MDS Pod 확인
$ kubectl get pods -n rook-ceph | grep mds
rook-ceph-mds-myfs-a-xxxxx   1/1     Running   0          30s
rook-ceph-mds-myfs-b-xxxxx   1/1     Running   0          26s

# CephFS 상태 확인
$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- ceph fs status myfs
myfs - 0 clients
====
RANK  STATE    MDS       ACTIVITY     DNS    INOS   DIRS   CAPS
 0    active  myfs-a  Reqs:    0 /s    12     15     14      0
     POOL        TYPE     USED  AVAIL
myfs-metadata  metadata  40.0k   442G
  myfs-data0     data       0    442G
STANDBY MDS
   myfs-b

✅ Active MDS 1개, Standby MDS 1개 정상 작동!

실습 8: RWX 동시 접근 테스트

2개 Pod가 동시에 같은 볼륨 사용:

# ~/ceph/cephfs-storageclass.yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: rook-cephfs
provisioner: rook-ceph.cephfs.csi.ceph.com
parameters:
  clusterID: rook-ceph
  fsName: myfs
  pool: myfs-data0
  # ... CSI 시크릿 설정 ...
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-cephfs-pvc
spec:
  accessModes:
  - ReadWriteMany  # ✅ RWX!
  storageClassName: rook-cephfs
  resources:
    requests:
      storage: 1Gi
---
# Pod 1
apiVersion: v1
kind: Pod
metadata:
  name: test-cephfs-pod1
spec:
  containers:
  - name: test
    image: busybox:1.28
    command: ["sh", "-c", "while true; do echo '[Pod 1] Writing...' >> /data/pod1.txt; ls -lh /data; sleep 10; done"]
    volumeMounts:
    - name: cephfs-volume
      mountPath: /data
  volumes:
  - name: cephfs-volume
    persistentVolumeClaim:
      claimName: test-cephfs-pvc
---
# Pod 2 (같은 PVC 사용!)
apiVersion: v1
kind: Pod
metadata:
  name: test-cephfs-pod2
spec:
  containers:
  - name: test
    image: busybox:1.28
    command: ["sh", "-c", "while true; do echo '[Pod 2] Writing...' >> /data/pod2.txt; ls -lh /data; sleep 10; done"]
    volumeMounts:
    - name: cephfs-volume
      mountPath: /data
  volumes:
  - name: cephfs-volume
    persistentVolumeClaim:
      claimName: test-cephfs-pvc  # ✅ 같은 PVC!

$ kubectl apply -f ~/ceph/cephfs-storageclass.yaml
storageclass.storage.k8s.io/rook-cephfs created
persistentvolumeclaim/test-cephfs-pvc created
pod/test-cephfs-pod1 created
pod/test-cephfs-pod2 created

# PVC 상태 (RWX 확인!)
$ kubectl get pvc test-cephfs-pvc
NAME              STATUS   VOLUME                                     CAPACITY   ACCESS MODES
test-cephfs-pvc   Bound    pvc-b267c8ad-ebae-4253-8685-e5d6487cef5e   1Gi        RWX

# 두 Pod 모두 Running
$ kubectl get pods test-cephfs-pod1 test-cephfs-pod2
NAME               READY   STATUS    RESTARTS   AGE
test-cephfs-pod1   1/1     Running   0          1m
test-cephfs-pod2   1/1     Running   0          1m

# Pod 1에서 파일 목록 확인
$ kubectl exec test-cephfs-pod1 -- ls -lh /data
total 3
-rw-r--r--    1 root     root        1.2K Nov  6 15:11 pod1.txt
-rw-r--r--    1 root     root        1.2K Nov  6 15:11 pod2.txt

# Pod 2에서도 동일하게 보임!
$ kubectl exec test-cephfs-pod2 -- ls -lh /data
total 3
-rw-r--r--    1 root     root        1.2K Nov  6 15:11 pod1.txt
-rw-r--r--    1 root     root        1.2K Nov  6 15:11 pod2.txt

# Pod 2에서 Pod 1의 파일 읽기
$ kubectl exec test-cephfs-pod2 -- head -5 /data/pod1.txt
[Pod 1] Writing...
[Pod 1] Writing...
[Pod 1] Writing...

🎉 진정한 공유 파일 시스템! 두 Pod가 같은 데이터를 실시간으로 공유합니다!

5. RGW 오브젝트 스토리지 (S3 API)

왜 오브젝트 스토리지?

S3 호환 API:

• AWS S3와 동일한 API
• 버킷 기반 스토리지
• 웹 애플리케이션, 백업, 아카이브

실습 9: CephObjectStore 생성

# ~/ceph/ceph-objectstore.yaml
apiVersion: ceph.rook.io/v1
kind: CephObjectStore
metadata:
  name: my-store
  namespace: rook-ceph
spec:
  metadataPool:
    failureDomain: osd
    replicated:
      size: 1
      requireSafeReplicaSize: false

  dataPool:
    failureDomain: osd
    replicated:
      size: 1
      requireSafeReplicaSize: false

  gateway:
    port: 80
    instances: 1

$ kubectl apply -f ~/ceph/ceph-objectstore.yaml
cephobjectstore.ceph.rook.io/my-store created

# RGW Pod 확인
$ kubectl get pods -n rook-ceph -l app=rook-ceph-rgw
NAME                                      READY   STATUS    RESTARTS   AGE
rook-ceph-rgw-my-store-a-xxxxx            1/1     Running   0          1m

# RGW 서비스 확인
$ kubectl get svc -n rook-ceph | grep rgw
rook-ceph-rgw-my-store   ClusterIP   10.107.184.210   <none>   80/TCP   1m

실습 10: S3 사용자 생성

# ~/ceph/s3-user.yaml
apiVersion: ceph.rook.io/v1
kind: CephObjectStoreUser
metadata:
  name: my-s3-user
  namespace: rook-ceph
spec:
  store: my-store
  displayName: "My S3 User"

$ kubectl apply -f ~/ceph/s3-user.yaml
cephobjectstoreuser.ceph.rook.io/my-s3-user created

# Access Key와 Secret Key 확인
$ kubectl get secret -n rook-ceph rook-ceph-object-user-my-store-my-s3-user -o jsonpath='{.data.AccessKey}' | base64 -d
VZ4O1JVZQZX92XDKCNPM

$ kubectl get secret -n rook-ceph rook-ceph-object-user-my-store-my-s3-user -o jsonpath='{.data.SecretKey}' | base64 -d
VbtubT0XNLDjrzHcKoVKeNYvXjdEhfFOT2la2GVE

✅ S3 API 사용 준비 완료! 이제 AWS CLI나 boto3로 접근 가능합니다.

6. Ceph Dashboard로 클러스터 모니터링

실습 11: Dashboard 접근 설정

트러블슈팅 3: NodePort가 계속 ClusterIP로 되돌아가는 문제

# Dashboard 서비스 확인
$ kubectl get svc -n rook-ceph rook-ceph-mgr-dashboard
NAME                      TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)
rook-ceph-mgr-dashboard   ClusterIP   10.104.241.243   <none>        7000/TCP

# NodePort로 변경 시도
$ kubectl patch svc rook-ceph-mgr-dashboard -n rook-ceph -p '{"spec":{"type":"NodePort"}}'
service/rook-ceph-mgr-dashboard patched

# 잠시 후 다시 확인하면...
$ kubectl get svc -n rook-ceph rook-ceph-mgr-dashboard
NAME                      TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)
rook-ceph-mgr-dashboard   ClusterIP   10.104.241.243   <none>        7000/TCP  ← 다시 ClusterIP!

원인: Rook Operator가 서비스를 관리하면서 원래 상태로 복원

해결: 별도의 NodePort 서비스 생성

# ~/ceph/dashboard-nodeport.yaml
apiVersion: v1
kind: Service
metadata:
  name: ceph-dashboard-external
  namespace: rook-ceph
spec:
  type: NodePort
  selector:
    app: rook-ceph-mgr  # MGR Pod를 타겟으로
  ports:
  - name: dashboard
    port: 7000
    targetPort: 7000
    protocol: TCP

$ kubectl apply -f ~/ceph/dashboard-nodeport.yaml
service/ceph-dashboard-external created

$ kubectl get svc -n rook-ceph ceph-dashboard-external
NAME                      TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)
ceph-dashboard-external   NodePort   10.110.34.58   <none>        7000:31383/TCP

# 접근 테스트
$ curl -I http://172.30.1.38:31383
HTTP/1.1 200 OK
Server: Ceph-Dashboard

✅ 성공! Dashboard에 접근 가능합니다!

Dashboard 로그인

접속 정보:

URL: http://172.30.1.38:31383
Username: admin
Password: (Secret에서 확인)

# Password 확인
$ kubectl get secret -n rook-ceph rook-ceph-dashboard-password -o jsonpath='{.data.password}' | base64 -d
\nLp%F2g(aDx<PzY.$60

Dashboard 메뉴:

• Block → RBD 블록 스토리지 상태
• Filesystems → CephFS (myfs) 상태
• Object Gateway → RGW (my-store) 상태
• Cluster → 전체 클러스터 health

7. 최종 클러스터 상태

$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- ceph status
  cluster:
    id:     6fa3b356-4964-460e-9a29-e8e350febeff
    health: HEALTH_WARN
            11 pool(s) have no replicas configured
            OSD count 1 < osd_pool_default_size 3

  services:
    mon: 1 daemons, quorum a (age 1h)
    mgr: a(active, since 1h)
    mds: 1/1 daemons up, 1 standby  ← CephFS
    osd: 1 osds: 1 up, 1 in
    rgw: 1 daemon active  ← RGW

  data:
    volumes: 1/1 healthy  ← CephFS
    pools:   11 pools, 168 pgs
    objects: 252 objects, 5.7 MiB
    usage:   33 MiB used, 466 GiB / 466 GiB avail
    pgs:     168 active+clean  ← ✅ 모든 PG 정상!

스토리지 사용량:

$ kubectl exec -n rook-ceph deploy/rook-ceph-tools -- ceph df
--- POOLS ---
POOL              ID  PGS   STORED   OBJECTS     USED   %USED  MAX AVAIL
replicapool        2   32   672 KiB        13  680 KiB      0    442 GiB  ← RBD
myfs-metadata      3   16   455 KiB        21  484 KiB      0    442 GiB  ← CephFS
myfs-data0         4   32    22 KiB         3   28 KiB      0    442 GiB  ← CephFS
my-store.rgw.*     ...  ...  (8개 Pool)                                  ← RGW

Kubernetes 리소스:

$ kubectl get pvc
NAME              STATUS   VOLUME                                     CAPACITY   ACCESS MODES
test-ceph-pvc     Bound    pvc-4d7204b9-98c0-416b-9574-25af51682854   1Gi        RWO
test-cephfs-pvc   Bound    pvc-b267c8ad-ebae-4253-8685-e5d6487cef5e   1Gi        RWX

$ kubectl get pods
NAME               READY   STATUS    RESTARTS   AGE
test-ceph-pod      1/1     Running   0          30m
test-cephfs-pod1   1/1     Running   0          23m
test-cephfs-pod2   1/1     Running   0          23m

배운 점

1. Ceph는 마법이 아니라 수학이다

CRUSH 알고리즘의 아름다움:

• 중앙 서버 없이도 모든 클라이언트가 데이터 위치를 계산
• 노드 추가/제거 시 최소한의 데이터만 이동
• Deterministic (같은 입력 = 항상 같은 결과)

Placement Group의 필요성:

• 객체와 OSD 사이의 간접 레이어
• 확장성과 관리 용이성의 균형

2. 단일 노드 vs 멀티 노드의 차이

단일 노드 Ceph의 한계:

문제점:
❌ SPOF (Single Point of Failure)
❌ 네트워크 분산 이점 없음
❌ 복제 효과 없음 (같은 서버)
❌ 장애 복구 불가

결론: 단일 노드는 학습용!
프로덕션은 최소 3노드 이상!

프로덕션 권장 구성:

최소:
  노드: 3개
  OSD/노드: 4개 (총 12 OSD)
  복제본: 3
  네트워크: 10GbE

이상적:
  노드: 5개+
  OSD/노드: 10개+
  복제본: 3
  네트워크: 25GbE+
  전용 Storage 노드 분리

3. 스토리지 타입별 명확한 차이

사용 예시:

• 데이터베이스 → RBD (빠른 블록 접근)
• 웹 서버 static files → CephFS (여러 Pod 공유)
• 백업, 미디어 파일 → RGW (S3 API)

4. Rook Operator의 편리함

선언적 관리:

CephCluster CRD 작성
  ↓
kubectl apply
  ↓
Operator가 자동으로:
  - MON/MGR/OSD Pod 생성
  - Service, ConfigMap 생성
  - PG 계산 및 최적화
  - 장애 복구

vs 수동 Ceph 배포:

• ceph-deploy 명령어 수십 개
• 설정 파일 직접 편집
• 수동 OSD 등록
• 장애 시 수동 복구

삽질 포인트

1. PG undersized+peered 지옥

증상: PVC가 Pending 상태로 멈춤

원인: 기본 BlockPool 설정이 3복제본 요구

교훈:

• 단일 노드 = size: 1, min_size: 1, failureDomain: osd
• 항상 ceph status로 PG 상태 먼저 확인!

2. ServiceMonitor RBAC 권한

증상: MGR Pod 로그에 권한 에러

원인: Prometheus Operator CRD 접근 권한 없음

교훈:

• Prometheus 있으면 monitoring.enabled: true
• RBAC 권한 추가 필요
• 로그를 꼼꼼히 읽자!

3. Dashboard NodePort 복원 문제

증상: NodePort로 변경해도 계속 ClusterIP로 되돌아감

원인: Rook Operator가 서비스 관리

교훈:

• Operator 관리 리소스는 직접 수정 금지
• 별도 서비스 생성이 답!

4. Disk 초기화 불충분

증상: OSD 생성 실패

원인: 파티션 테이블 잔여

교훈:

# 완전 초기화 3종 세트
wipefs -a /dev/sdb
sgdisk --zap-all /dev/sdb
dd if=/dev/zero of=/dev/sdb bs=1M count=100

다음 계획 (Day 8)

Day 7에서 Ceph 분산 스토리지의 기초를 다졌습니다. 이제 Day 8에서는 프로덕션 환경을 위한 고급 주제를 다룰 예정입니다:

Day 8 주제

1. Helm 패키지 매니저 (차트 생성, 버전 관리, 롤백)
2. CI/CD 파이프라인 (GitOps, ArgoCD)
3. 고급 로깅 스택 (Fluent Bit, Loki, Grafana)
4. 네트워크 정책 (NetworkPolicy로 Pod 간 통신 제어)
5. 백업 및 재해 복구 (Velero로 클러스터 백업)

도전 과제

• Ceph 멀티 노드 확장: cpu2 노드 추가하여 3노드 클러스터 구성
• Erasure Coding: 복제 대신 EC로 용량 효율 개선
• CephFS Subvolume: 테넌트별 격리된 파일시스템
• RGW 버킷 정책: S3 버킷 접근 제어

마무리

Ceph는 복잡하지만 강력합니다. 단일 노드로 학습했지만, 프로덕션에서는 반드시 멀티 노드로 구성해야 합니다.

핵심 요약:

• ✅ Ceph = RADOS + CRUSH + PG
• ✅ RBD (RWO), CephFS (RWX), RGW (S3)
• ✅ 단일 노드 = 학습용, 멀티 노드 = 프로덕션
• ✅ Rook Operator로 선언적 관리
• ✅ Dashboard로 GUI 모니터링

Day 8에서 만나요! 🚀

참고 자료

• Rook Documentation
• Ceph Documentation
• CRUSH Algorithm Paper

2025년 11월 4일 Prometheus + Grafana로 메트릭 수집, Vector + OpenSearch로 로그 중앙화, Custom Metrics까지!

들어가며

Day 5에서 Production 환경 운영을 위한 Job/CronJob, Network Policy, Helm Chart, etcd 백업, 클러스터 업그레이드를 마스터했습니다. 이제 Day 6에서는 클러스터를 완벽하게 모니터링하고 로그를 중앙화하는 방법을 학습했습니다.

오늘 배운 것:

1. kube-prometheus-stack으로 Prometheus + Grafana 구축
2. Prometheus Targets와 ServiceMonitor 이해
3. Vector + OpenSearch + OpenSearch Dashboards로 로그 중앙화
4. OpenSearch Dashboards에서 KQL로 로그 검색
5. Python으로 Custom Metrics 애플리케이션 구현
6. ConfigMap으로 Grafana Dashboard 자동 프로비저닝
7. 실전 문제 해결 (Pod CrashLoopBackOff, Dashboard 로드 실패)

1. Prometheus + Grafana 스택 구축

왜 Prometheus인가?

🤔 내가 이해한 것:

• Pull 방식: Prometheus가 주기적으로 타겟에 요청 (Push 방식보다 안정적)
• 시계열 DB: 시간에 따른 메트릭 변화를 효율적으로 저장
• PromQL: SQL처럼 강력한 쿼리 언어
• Service Discovery: Kubernetes의 ServiceMonitor CRD로 자동 타겟 발견

실습 1: kube-prometheus-stack 설치

Helm으로 한 방에 설치:

$ helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
"prometheus-community" has been added to your repositories

$ helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "prometheus-community" chart repository
Update Complete. ⎈Happy Helming!⎈

$ kubectl create namespace monitoring
namespace/monitoring created

$ helm install kube-prometheus-stack prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --set prometheus.service.type=NodePort \
  --set prometheus.service.nodePort=30090 \
  --set grafana.service.type=NodePort \
  --set grafana.service.nodePort=30300 \
  --set alertmanager.service.type=NodePort \
  --set alertmanager.service.nodePort=30903

NAME: kube-prometheus-stack
LAST DEPLOYED: Mon Nov  4 14:30:12 2025
NAMESPACE: monitoring
STATUS: deployed
REVISION: 1

뭐가 설치됐는지 확인:

$ kubectl get pods -n monitoring
NAME                                                   READY   STATUS    RESTARTS   AGE
prometheus-kube-prometheus-stack-prometheus-0          1/1     Running   0          2m
kube-prometheus-stack-grafana-xxxxx                    3/3     Running   0          2m
kube-prometheus-stack-operator-xxxxx                   1/1     Running   0          2m
alertmanager-kube-prometheus-stack-alertmanager-0      2/2     Running   0          2m
kube-prometheus-stack-kube-state-metrics-xxxxx         1/1     Running   0          2m
prometheus-node-exporter-xxxxx (DaemonSet - 4개)       1/1     Running   0          2m

🎉 성공! 한 줄 명령어로 완전한 모니터링 스택 구축!

실습 2: Prometheus Targets 확인

접속: http://172.30.1.43:30090

Status → Targets 메뉴:

[이미지 1: Prometheus Targets 화면 스크린샷]

🤔 ServiceMonitor가 뭐지?

• Prometheus Operator의 CRD
• Label Selector로 Service를 찾음
• Service의 Endpoints에서 Pod IP 자동 추출
• 결과: 수동 설정 없이 자동 스케일링 대응!

PromQL 쿼리 테스트:

# 클러스터 전체 Pod 수
count(kube_pod_info)
→ 결과: 42

# Namespace별 Pod 수
count by (namespace) (kube_pod_info)
→ 결과:
  {namespace="default"} 8
  {namespace="monitoring"} 15
  {namespace="kube-system"} 19

# 노드 CPU 사용률
100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
→ 결과:
  {instance="172.30.1.43:9100"} 15.3
  {instance="172.30.1.54:9100"} 23.7
  {instance="172.30.1.55:9100"} 18.2
  {instance="172.30.1.56:9100"} 12.1

2. Grafana 대시보드로 시각화

실습 3: Grafana 접속

접속: http://172.30.1.43:30300

• Username: admin
• Password: prom-operator

기본 제공 대시보드:

[이미지 2: Grafana 대시보드 목록 스크린샷]

1. Kubernetes / Compute Resources / Cluster

[이미지 3: Cluster Dashboard 스크린샷]

🤔 내가 본 것:

• monitoring namespace가 CPU 25%, 메모리 40% 사용 (Prometheus 스택이 크다!)
• kube-system namespace는 안정적으로 CPU 10% 이하
• 네트워크 트래픽이 급증하는 시간대 확인 가능

2. Node Exporter / Nodes

노드별 상세 메트릭:

• CPU 사용률, Load Average
• 메모리 사용량 (Used/Cached/Free)
• 디스크 I/O, 파일시스템 사용률
• 네트워크 트래픽 (eth0 인터페이스)

3. 로깅 시스템 구축 (Vector + OpenSearch)

왜 중앙화된 로깅이 필요한가?

🤔 내가 이해한 것:

• Pod가 재시작되면 로그 사라짐
• 여러 노드에 분산된 로그를 한곳에서 검색해야 함
• 장애 분석 시 시간 순서대로 로그 추적 필요

실습 4: OpenSearch 설치 (단일 노드)

🤔 3중화는 왜 안 했나?

• 오늘은 개념만 배움
• 실제로는 단일 노드(1개)로 설치
• 리소스 절약 및 빠른 테스트 목적
• Production에서는 반드시 3중화 권장!

$ helm repo add opensearch https://opensearch-project.github.io/helm-charts/
$ helm repo update

$ helm install opensearch opensearch/opensearch \
  --namespace monitoring \
  --set service.type=NodePort \
  --set service.nodePort=30920

NAME: opensearch
LAST DEPLOYED: Mon Nov  4 14:45:23 2025
NAMESPACE: monitoring
STATUS: deployed

Pod 확인:

$ kubectl get pods -n monitoring | grep opensearch
opensearch-cluster-master-0   1/1     Running   0          3m

클러스터 헬스 체크:

$ kubectl exec -n monitoring opensearch-cluster-master-0 -- \
  curl -s http://localhost:9200/_cluster/health

{
  "cluster_name": "opensearch-cluster",
  "status": "yellow",  ← 단일 노드라 yellow (복제본 없음)
  "number_of_nodes": 1,
  "active_primary_shards": 5,
  "active_shards": 5,
  "relocating_shards": 0,
  "initializing_shards": 0,
  "unassigned_shards": 5  ← 복제본이 없어서 할당 안 됨
}

💡 OpenSearch 3중화 개념 (향후 적용)

Production 환경에서는:

helm install opensearch opensearch/opensearch \
  --set replicas=3  # ← 이렇게 하면 3개 Pod 배포

3중화의 장점:

• 고가용성: 노드 1개 죽어도 서비스 계속
• 데이터 복제: 각 샤드가 3개 복제본 유지
• 검색 성능: 부하 분산으로 빠른 검색
• 상태: "green" (모든 샤드 정상)

실습 5: OpenSearch Dashboards 설치

$ helm install opensearch-dashboards opensearch/opensearch-dashboards \
  --namespace monitoring \
  --set service.type=NodePort \
  --set service.nodePort=30561 \
  --set opensearchHosts=http://opensearch-cluster-master:9200

$ kubectl get pods -n monitoring | grep dashboards
opensearch-dashboards-xxxxx   1/1     Running   0          1m

접속: http://172.30.1.43:30561

실습 6: Vector 로그 수집기 배포

Vector가 뭐지?

• Rust로 작성된 고성능 로그 수집기
• Fluent Bit보다 3배 낮은 메모리 사용
• 강력한 데이터 변환 기능

$ helm repo add vector https://helm.vector.dev
$ helm repo update

$ helm install vector vector/vector \
  --namespace monitoring \
  --set role=Agent \
  --set customConfig.data_dir=/vector-data-dir \
  --set customConfig.sources.kubernetes_logs.type=kubernetes_logs \
  --set customConfig.sinks.opensearch.type=elasticsearch \
  --set customConfig.sinks.opensearch.endpoint=http://opensearch-cluster-master:9200 \
  --set customConfig.sinks.opensearch.bulk.index="logs-%Y-%m-%d"

$ kubectl get ds -n monitoring vector
NAME     DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
vector   4         4         4       4            4           <none>          2m

DaemonSet이니까 모든 노드(4개)에 배포됨!

Vector 로그 확인 (잘 수집하고 있나?):

$ kubectl logs -n monitoring ds/vector -f
2025-11-04T14:50:12.123Z  INFO vector::sources::kubernetes_logs: Discovered new Pod
2025-11-04T14:50:12.234Z  INFO vector::sinks::elasticsearch: Successfully sent 150 events
2025-11-04T14:50:22.345Z  INFO vector::sinks::elasticsearch: Successfully sent 220 events

Vector Pod 상태 확인:

$ kubectl get pods -n monitoring -l app.kubernetes.io/name=vector
NAME           READY   STATUS    RESTARTS   AGE
vector-7m2fp   1/1     Running   0          5m
vector-9k4hn   1/1     Running   0          5m
vector-d8xqw   1/1     Running   0          5m
vector-p5znc   1/1     Running   0          5m

OpenSearch 인덱스 확인:

$ kubectl exec -n monitoring opensearch-cluster-master-0 -- \
  curl -s 'http://localhost:9200/_cat/indices/logs-*'

yellow open logs-2025-11-04 xxx 1 1  1543 0  1.2mb  1.2mb

인덱스 상세 정보:

$ kubectl exec -n monitoring opensearch-cluster-master-0 -- \
  curl -s 'http://localhost:9200/logs-2025-11-04/_count'

{"count":1543,"_shards":{"total":1,"successful":1,"skipped":0,"failed":0}}

실제 로그 데이터 샘플 조회:

$ kubectl exec -n monitoring opensearch-cluster-master-0 -- \
  curl -s 'http://localhost:9200/logs-2025-11-04/_search?size=1&pretty'

{
  "hits": {
    "total": {"value": 1543},
    "hits": [{
      "_source": {
        "@timestamp": "2025-11-04T14:50:30.123Z",
        "message": "Starting Prometheus metrics server on port 8000",
        "kubernetes": {
          "namespace_name": "default",
          "pod_name": "custom-metrics-app-748gk-xxxxx",
          "container_name": "app",
          "labels": {
            "app": "custom-metrics-app"
          }
        }
      }
    }]
  }
}

로그가 들어오고 있다! 🎉

4. OpenSearch Dashboards에서 로그 검색

실습 7: Index Pattern 생성

OpenSearch Dashboards 접속 후:

[이미지 4: Index Pattern 생성 화면 스크린샷]

1. Management → Index Patterns → Create
2. Index pattern name: logs-*
3. Time field: @timestamp
4. Create!

실습 8: Discover로 로그 검색

[이미지 5: OpenSearch Dashboards Discover 화면 스크린샷]

KQL (Kibana Query Language) 검색:

1. 특정 Pod 로그:

kubernetes.pod_name: *prometheus*

→ 결과: Prometheus 관련 Pod 로그 15,234건

2. Namespace + 에러 로그:

kubernetes.namespace_name: "monitoring" AND message: *error*

→ 결과: monitoring namespace의 에러 로그 23건 발견!

3. 특정 컨테이너 로그:

kubernetes.container_name: "grafana" AND kubernetes.namespace_name: "monitoring"

→ 결과: Grafana 컨테이너 로그 3,456건

4. 로그 레벨 필터 (에러만):

kubernetes.namespace_name: "default" AND (message: *ERROR* OR message: *error* OR message: *Error*)

→ 결과: default namespace의 에러 로그 12건

5. 여러 Pod 동시 검색:

kubernetes.pod_name: (*vector* OR *opensearch* OR *grafana*)

→ 결과: 모니터링 스택 관련 로그 45,678건

6. 특정 시간 이후 로그:

@timestamp >= "2025-11-04T14:00:00"

→ 결과: 오후 2시 이후 로그만 표시

7. 복잡한 조합 쿼리:

kubernetes.namespace_name: "monitoring" AND NOT kubernetes.pod_name: *exporter* AND message: *started*

→ 결과: monitoring namespace에서 exporter를 제외한 시작 메시지 34건

8. 필드 존재 여부 확인:

_exists_: kubernetes.labels.app AND kubernetes.namespace_name: "default"

→ 결과: app 레이블이 있는 default Pod 로그

🤔 내가 느낀 것:

• SQL보다 훨씬 직관적!
• 와일드카드 *로 부분 매칭
• AND/OR/NOT으로 복잡한 쿼리 가능
• GUI로도 쉽게 필터링
• _exists_ 같은 특수 함수 강력함

5. Custom Metrics 애플리케이션 구축

왜 Custom Metrics가 필요한가?

🤔 내가 이해한 것:

• 시스템 메트릭(CPU/메모리)만으로는 부족
• 비즈니스 메트릭이 진짜 중요:
  • 주문 수, 결제 금액
  • 활성 사용자 수
  • 재고 수량
  • API 응답 시간

Prometheus 메트릭 타입

1. Counter (증가만 가능)

• 예: orders_total, requests_total
• PromQL: rate(), increase() 함수 사용

2. Gauge (증감 가능)

• 예: active_users, inventory_stock
• PromQL: 직접 값 사용, avg(), sum()

3. Histogram (분포 측정)

• 예: api_response_time_seconds
• PromQL: histogram_quantile() 함수로 P95/P99 계산

실습 9: Python Flask + Prometheus Client

파일: /tmp/custom-metrics-app.py

from prometheus_client import Counter, Gauge, Histogram, start_http_server
from flask import Flask, jsonify
import random
import time

# 메트릭 정의
orders_total = Counter('orders_total', '총 주문 수', ['status'])
payment_amount_total = Counter('payment_amount_total', '총 결제 금액')
active_users = Gauge('active_users', '현재 활성 사용자 수')
inventory_stock = Gauge('inventory_stock', '재고 수량', ['product'])
api_response_time = Histogram('api_response_time_seconds', 'API 응답 시간', ['endpoint'])

app = Flask(__name__)

@app.route('/order')
def create_order():
    with api_response_time.labels(endpoint='/order').time():
        # 주문 처리 시뮬레이션 (100~500ms)
        time.sleep(random.uniform(0.1, 0.5))

        # 90% 성공, 10% 실패
        status = 'success' if random.random() > 0.1 else 'failed'
        orders_total.labels(status=status).inc()

        # 성공 시 결제 금액 증가
        if status == 'success':
            amount = random.randint(10000, 100000)
            payment_amount_total.inc(amount)

    return jsonify({"status": status})

# 백그라운드 시뮬레이션
def simulate_metrics():
    while True:
        active_users.set(random.randint(50, 200))
        inventory_stock.labels(product='laptop').set(random.randint(10, 100))
        inventory_stock.labels(product='phone').set(random.randint(20, 150))
        inventory_stock.labels(product='tablet').set(random.randint(5, 50))
        time.sleep(10)

if __name__ == '__main__':
    import threading
    # Prometheus 메트릭 서버 (포트 8000)
    start_http_server(8000)

    # 백그라운드 스레드 시작
    threading.Thread(target=simulate_metrics, daemon=True).start()

    # Flask 앱 시작 (포트 5000)
    app.run(host='0.0.0.0', port=5000)

실습 10: Kubernetes Deployment 배포

파일: /tmp/custom-metrics-deploy.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: custom-metrics-app
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: custom-metrics-app
  template:
    metadata:
      labels:
        app: custom-metrics-app
    spec:
      containers:
      - name: app
        image: python:3.9-slim
        command: ["/bin/bash", "-c"]
        args:
        - |
          pip install flask==2.3.0 prometheus_client==0.17.0 > /dev/null 2>&1
          mkdir -p /app
          cat > /app/app.py << 'EOF'
          # (위 Python 코드)
          EOF
          python /app/app.py
        ports:
        - containerPort: 5000
          name: http
        - containerPort: 8000
          name: metrics

Service YAML (같은 파일에 포함):

---
apiVersion: v1
kind: Service
metadata:
  name: custom-metrics-app
  namespace: default
  labels:
    app: custom-metrics-app
spec:
  type: ClusterIP
  ports:
  - port: 5000
    targetPort: 5000
    name: http
  - port: 8000
    targetPort: 8000
    name: metrics
  selector:
    app: custom-metrics-app
---
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: custom-metrics-app
  namespace: default
  labels:
    app: custom-metrics-app
spec:
  selector:
    matchLabels:
      app: custom-metrics-app
  endpoints:
  - port: metrics
    interval: 15s
    path: /metrics

배포:

$ kubectl apply -f /tmp/custom-metrics-deploy.yaml
deployment.apps/custom-metrics-app created
service/custom-metrics-app created
servicemonitor.monitoring.coreos.com/custom-metrics-app created

😱 문제 발생!

$ kubectl get pods -l app=custom-metrics-app
NAME                                  READY   STATUS             RESTARTS   AGE
custom-metrics-app-748gk-xxxxx        0/2     CrashLoopBackOff   3          2m

🔧 문제 해결 1: Pod CrashLoopBackOff

로그 확인:

$ kubectl logs custom-metrics-app-748gk-xxxxx --previous
/bin/bash: line 2: /app/app.py: No such file or directory

🤔 왜 그럴까?

• Python 3.9 slim 이미지에는 /app 디렉토리가 없음!
• cat > /app/app.py가 실패

해결책:

args:
- |
  pip install flask==2.3.0 prometheus_client==0.17.0 > /dev/null 2>&1
  mkdir -p /app  # ← 이 줄 추가!
  cat > /app/app.py << 'EOF'
  # ...
  EOF
  python /app/app.py

재배포:

$ kubectl delete deployment custom-metrics-app
$ kubectl apply -f /tmp/custom-metrics-deploy.yaml

$ kubectl get pods -l app=custom-metrics-app
NAME                                  READY   STATUS    RESTARTS   AGE
custom-metrics-app-748gk-xxxxx        2/2     Running   0          30s
custom-metrics-app-849hl-yyyyy        2/2     Running   0          30s

✅ 성공! 2개 Pod 모두 Running!

Service와 Endpoints 확인:

$ kubectl get svc custom-metrics-app
NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)             AGE
custom-metrics-app   ClusterIP   10.96.123.45    <none>        5000/TCP,8000/TCP   2m

$ kubectl get endpoints custom-metrics-app
NAME                 ENDPOINTS                                   AGE
custom-metrics-app   10.244.102.188:5000,10.244.58.147:5000,...  2m

ServiceMonitor 확인:

$ kubectl get servicemonitor custom-metrics-app
NAME                 AGE
custom-metrics-app   2m

$ kubectl describe servicemonitor custom-metrics-app
Name:         custom-metrics-app
Namespace:    default
Labels:       app=custom-metrics-app
Spec:
  Endpoints:
    Interval:  15s
    Path:      /metrics
    Port:      metrics
  Selector:
    Match Labels:
      app:  custom-metrics-app

메트릭 엔드포인트 직접 확인:

$ kubectl run test-metrics --image=curlimages/curl:7.85.0 --rm -i --restart=Never -- \
  curl -s http://custom-metrics-app:8000/metrics | head -20

# HELP orders_total 총 주문 수
# TYPE orders_total counter
orders_total{status="success"} 234.0
orders_total{status="failed"} 26.0
# HELP payment_amount_total 총 결제 금액
# TYPE payment_amount_total counter
payment_amount_total 15823000.0
# HELP active_users 현재 활성 사용자 수
# TYPE active_users gauge
active_users 127.0
# HELP inventory_stock 재고 수량
# TYPE inventory_stock gauge
inventory_stock{product="laptop"} 45.0
inventory_stock{product="phone"} 123.0
inventory_stock{product="tablet"} 23.0

✅ 메트릭이 정상적으로 노출되고 있다!

실습 11: Prometheus에서 메트릭 확인

Prometheus UI에서 쿼리:

[이미지 6: Prometheus Custom Metrics Target 스크린샷]

PromQL 쿼리 테스트:

# 1. 총 주문 수
orders_total
→ orders_total{status="success"} 1234
→ orders_total{status="failed"} 138

# 2. 성공 주문의 분당 증가율
rate(orders_total{status="success"}[5m]) * 60
→ 12.3 (분당 12.3개 주문)

# 3. 평균 활성 사용자
avg(active_users)
→ 127.5

# 4. 총 결제 금액
sum(payment_amount_total)
→ 45,823,000 (4천5백만원!)

# 5. 주문 성공률 (백분율)
sum(rate(orders_total{status="success"}[5m])) / sum(rate(orders_total[5m])) * 100
→ 89.88 (약 90%)

# 6. API 응답 시간 P95 (95번째 백분위수)
histogram_quantile(0.95, rate(api_response_time_seconds_bucket{endpoint="/order"}[5m]))
→ 0.487 (487ms)

# 7. API 응답 시간 P99 (99번째 백분위수)
histogram_quantile(0.99, rate(api_response_time_seconds_bucket{endpoint="/order"}[5m]))
→ 0.498 (498ms)

# 8. 1분당 결제 금액
rate(payment_amount_total[1m]) * 60
→ 758,234 (1분에 75만원!)

# 9. 재고가 50개 이하인 상품
inventory_stock < 50
→ inventory_stock{product="tablet"} 23

6. Grafana Custom Dashboard 생성

실습 12: ConfigMap으로 대시보드 자동 프로비저닝

🤔 왜 ConfigMap을 쓰는가?

• Grafana UI에서 수동으로 만들면 재배포 시 사라짐
• Infrastructure as Code: YAML로 관리
• GitOps 친화적

파일: /tmp/custom-metrics-dashboard.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-metrics-dashboard
  namespace: monitoring
  labels:
    grafana_dashboard: "1"  # ← 이 레이블이 핵심!
data:
  custom-metrics-dashboard.json: |
    {
      "title": "Custom Business Metrics",
      "tags": ["custom", "business"],
      "refresh": "10s",
      "panels": [
        {
          "id": 1,
          "title": "총 주문 수 (성공/실패)",
          "type": "graph",
          "gridPos": {"x": 0, "y": 0, "w": 12, "h": 8},
          "targets": [
            {
              "expr": "rate(orders_total{status=\"success\"}[5m]) * 60",
              "legendFormat": "성공 (주문/분)",
              "refId": "A"
            },
            {
              "expr": "rate(orders_total{status=\"failed\"}[5m]) * 60",
              "legendFormat": "실패 (주문/분)",
              "refId": "B"
            }
          ],
          "yaxes": [
            {"format": "short", "label": "주문/분"},
            {"format": "short"}
          ]
        },
        {
          "id": 2,
          "title": "총 결제 금액 (원)",
          "type": "stat",
          "gridPos": {"x": 12, "y": 0, "w": 6, "h": 4},
          "targets": [
            {
              "expr": "sum(payment_amount_total)",
              "refId": "A"
            }
          ],
          "options": {
            "graphMode": "area",
            "colorMode": "value"
          },
          "fieldConfig": {
            "defaults": {
              "unit": "currencyKRW",
              "decimals": 0
            }
          }
        },
        {
          "id": 3,
          "title": "현재 활성 사용자",
          "type": "gauge",
          "gridPos": {"x": 18, "y": 0, "w": 6, "h": 4},
          "targets": [
            {
              "expr": "avg(active_users)",
              "refId": "A"
            }
          ],
          "options": {
            "showThresholdLabels": false,
            "showThresholdMarkers": true
          },
          "fieldConfig": {
            "defaults": {
              "min": 0,
              "max": 300,
              "thresholds": {
                "steps": [
                  {"value": 0, "color": "green"},
                  {"value": 150, "color": "yellow"},
                  {"value": 200, "color": "red"}
                ]
              }
            }
          }
        },
        {
          "id": 7,
          "title": "주문 성공률",
          "type": "stat",
          "gridPos": {"x": 0, "y": 16, "w": 8, "h": 4},
          "targets": [
            {
              "expr": "sum(rate(orders_total{status=\"success\"}[5m])) / sum(rate(orders_total[5m])) * 100",
              "refId": "A"
            }
          ],
          "options": {
            "graphMode": "none",
            "colorMode": "value"
          },
          "fieldConfig": {
            "defaults": {
              "unit": "percent",
              "decimals": 1,
              "thresholds": {
                "steps": [
                  {"value": 0, "color": "red"},
                  {"value": 90, "color": "yellow"},
                  {"value": 95, "color": "green"}
                ]
              }
            }
          }
        }
      ]
    }

배포:

$ kubectl apply -f /tmp/custom-metrics-dashboard.yaml
configmap/custom-metrics-dashboard created

😱 문제 발생 (또!)

$ kubectl logs -n monitoring deployment/kube-prometheus-stack-grafana -c grafana
logger=provisioning.dashboard error="Dashboard title cannot be empty"

Grafana UI에 대시보드가 안 나타남!

🔧 문제 해결 2: Dashboard title cannot be empty

원인 파악:

처음에 이렇게 작성했었음:

{
  "dashboard": {  // ← 이 래퍼가 문제!
    "title": "Custom Business Metrics",
    "panels": [...]
  },
  "overwrite": true
}

Grafana는 최상위에 title 필드를 기대하는데, dashboard 래퍼로 감싸져 있어서 못 찾음!

올바른 구조:

{
  "title": "Custom Business Metrics",  // ← 최상위!
  "tags": ["custom", "business"],
  "panels": [...]
}

수정 및 재배포:

$ kubectl apply -f /tmp/custom-metrics-dashboard.yaml
configmap/custom-metrics-dashboard configured

Sidecar 컨테이너 로그 확인 (ConfigMap 감지):

$ kubectl logs -n monitoring deployment/kube-prometheus-stack-grafana -c grafana-sc-dashboard
INFO  Received File list: /tmp/dashboards
INFO  Retrieving ConfigMap custom-metrics-dashboard in namespace monitoring
INFO  Found 1 dashboard(s) in ConfigMap custom-metrics-dashboard
INFO  Writing dashboard custom-metrics-dashboard.json to /tmp/dashboards/custom-metrics-dashboard.json

Grafana 메인 컨테이너 로그 확인 (대시보드 로드):

$ kubectl logs -n monitoring deployment/kube-prometheus-stack-grafana -c grafana | tail -10
logger=provisioning.dashboard level=info msg="starting to provision dashboards"
logger=provisioning.dashboard level=info msg="finished to provision dashboards"
logger=dashboard.provisioning level=info msg="Inserted dashboard" title="Custom Business Metrics" id=42 path=/tmp/dashboards/custom-metrics-dashboard.json

ConfigMap이 파일로 생성되었는지 확인:

$ kubectl exec -n monitoring deployment/kube-prometheus-stack-grafana -c grafana -- \
  ls -lh /tmp/dashboards/

total 4.0K
-rw-r--r-- 1 grafana grafana 3.2K Nov  4 15:12 custom-metrics-dashboard.json

대시보드 개수 확인:

$ kubectl exec -n monitoring deployment/kube-prometheus-stack-grafana -c grafana -- \
  ls /tmp/dashboards/*.json | wc -l
1

에러 없음! ✅

실습 13: Grafana에서 대시보드 확인

Grafana UI → Dashboards → Browse → "Custom Business Metrics"

[이미지 7: Grafana Custom Metrics Dashboard 전체 화면 스크린샷]

7. 전체 아키텍처 정리

🤔 내가 이해한 전체 그림:

┌─────────────────────────────────────────────────────────┐
│                    모니터링 스택                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Custom Metrics App (2 Pods)                           │
│    ├─ Flask API (port 5000)                            │
│    └─ Prometheus Metrics (port 8000) /metrics          │
│              ↓                                          │
│  ServiceMonitor (CRD)                                   │
│    └─ Label Selector로 Service 발견                    │
│              ↓                                          │
│  Prometheus (Pull 방식)                                │
│    ├─ 15초마다 메트릭 수집                             │
│    ├─ TSDB에 저장                                      │
│    └─ PromQL로 쿼리                                    │
│              ↓                                          │
│  Grafana                                                │
│    ├─ Prometheus를 Data Source로 연결                 │
│    ├─ ConfigMap으로 Dashboard 자동 로드               │
│    └─ 웹 UI로 시각화                                   │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                    로깅 스택                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  모든 Pod (모든 Namespace)                             │
│    └─ stdout/stderr 로그                               │
│              ↓                                          │
│  Kubelet (/var/log/pods/)                              │
│              ↓                                          │
│  Vector (DaemonSet - 4개 노드)                         │
│    ├─ 로그 수집 및 파싱                                │
│    ├─ JSON 변환                                        │
│    └─ Bulk API로 전송                                  │
│              ↓                                          │
│  OpenSearch (단일 노드)                                │
│    ├─ logs-YYYY-MM-DD 인덱스                           │
│    ├─ status: yellow (복제본 없음)                    │
│    └─ Production에서는 3중화 권장                      │
│              ↓                                          │
│  OpenSearch Dashboards                                  │
│    ├─ Index Pattern: logs-*                            │
│    ├─ KQL로 로그 검색                                  │
│    └─ 웹 UI로 시각화                                   │
└─────────────────────────────────────────────────────────┘

8. 배운 점과 느낀 점

기술적 인사이트

1. ServiceMonitor의 강력함

🤔 내가 깨달은 것:

• CRD 기반 자동화가 진짜 Kubernetes다움
• Label Selector 하나로 동적 스케일링 대응
• Operator Pattern의 실전 예시

2. Sidecar 패턴의 우아함

Grafana가 ConfigMap을 감지하는 방식:

ConfigMap (label: grafana_dashboard="1")
    ↓
Sidecar Container (감시)
    ↓
/tmp/dashboards/에 파일 생성
    ↓
Grafana Main Container (자동 로드)

관심사 분리가 완벽!

3. Vector의 효율성

Rust로 작성되어:

• Fluent Bit 대비 메모리 사용량 1/3
• CPU 사용량도 낮음
• 복잡한 변환 로직 가능

4. OpenSearch 3중화의 중요성

# 클러스터 헬스
"status": "green"  # 3개 노드 모두 정상
"active_shards": 15  # 각 샤드가 3개씩 복제

# 노드 1개 죽어도:
"status": "yellow"  # 검색은 계속 가능
# 노드 2개 죽어야:
"status": "red"  # 일부 데이터 손실

고가용성 확보!

실전 팁

1. Pod 문제 디버깅 순서

kubectl get pods  # 상태 확인
kubectl describe pod <pod>  # 이벤트 확인
kubectl logs <pod>  # 로그 확인
kubectl logs <pod> --previous  # 이전 실행 로그 (CrashLoopBackOff 시)

2. JSON 구조 검증

# jq로 구조 확인
kubectl get cm <name> -o json | jq '.data | keys'

# 다른 정상 리소스와 비교
kubectl get cm <working-dashboard> -o json | jq '.data."xxx.json" | fromjson | keys'

3. 메트릭 설계 원칙

• Counter: 절대 감소하지 않는 값 (rate() 함수 사용)
• Gauge: 현재 상태를 나타내는 값
• Histogram: 분포를 측정하려면 (bucket 설정 중요)
• Label cardinality: Label 값이 너무 많으면 성능 저하!

4. ConfigMap 변경 후 확인

# ConfigMap 업데이트
kubectl apply -f dashboard.yaml

# Sidecar 로그 확인 (파일 생성 확인)
kubectl logs -n monitoring deploy/grafana -c grafana-sc-dashboard

# Grafana 로그 확인 (로드 성공 확인)
kubectl logs -n monitoring deploy/grafana -c grafana

실수했던 것들

1. /app 디렉토리 없음

• Python 이미지에 디렉토리가 없을 수 있음
• mkdir -p로 먼저 생성!

2. JSON 구조 잘못

• Grafana는 "dashboard": {} 래퍼를 싫어함
• 최상위에 "title" 필드 필수!

3. Label 오타

• grafana_dashboard: "1" ← 정확히 이렇게!
• 대소문자, 언더스코어 주의

정리 및 다음 단계

오늘 완성한 것

✅ 모니터링 스택

• Prometheus + Grafana로 메트릭 수집 및 시각화
• Custom Metrics 애플리케이션 구현
• ServiceMonitor로 자동 타겟 디스커버리
• ConfigMap으로 대시보드 자동 프로비저닝

✅ 로깅 스택

• Vector DaemonSet으로 전체 노드 로그 수집 (4개 노드)
• OpenSearch 단일 노드 구축 (3중화는 개념만 학습)
• OpenSearch Dashboards로 로그 검색 및 시각화
• KQL로 복잡한 로그 쿼리 (8가지 패턴)

최종 검증 체크리스트

• Prometheus UI 접속 가능 (http://172.30.1.43:30090)
• Prometheus Targets 모두 UP 상태
• Grafana 접속 및 로그인 성공 (admin/prom-operator)
• Grafana 기본 대시보드 정상 표시
• OpenSearch 1개 Pod Running (단일 노드, status: yellow)
• OpenSearch Dashboards 접속 가능
• OpenSearch에서 로그 검색 가능 (logs-* 인덱스)
• Vector DaemonSet 4개 Pod Running (각 노드당 1개)
• Custom Metrics App 2개 Pod Running
• Prometheus에서 Custom Metrics 수집 확인 (2개 Target UP)
• Grafana Custom Dashboard 정상 표시

Day 7 예고: Ceph 분산 스토리지

다음에 배울 것:

• Rook Operator로 Ceph 클러스터 구축
• RBD (Block Storage) 사용
• CephFS (Shared File System) 구성
• Object Storage (S3 호환) 설정
• 스토리지 클래스와 PVC 동적 프로비저닝

왜 Ceph를 배우는가?

• StatefulSet에 영구 스토리지 필요
• hostPath는 노드 종속적 (HA 불가능)
• Ceph = Kubernetes 네이티브 분산 스토리지
• Block/File/Object 모두 지원

참고 자료

• Prometheus 공식 문서
• kube-prometheus-stack Helm Chart
• OpenSearch 문서
• Vector 문서
• Grafana Dashboard Best Practices
• PromQL Cheat Sheet

Day 6 완료! 🎉

이제 클러스터를 완벽하게 관찰(Observe) 할 수 있습니다:

• Metrics (Prometheus + Grafana)
• Logs (Vector + OpenSearch)
• Custom Business Metrics (주문, 결제, 재고 등)

다음은 Storage 정복! 💪

2025년 11월 3일 Job/CronJob, Network Policy, Resource Quotas, CRD, Helm Chart, etcd Backup, Cluster Upgrade까지!

들어가며

Day 4에서 Ingress, HPA, RBAC, StatefulSet, DaemonSet 등 고급 패턴을 마스터했습니다. 이제 Day 5에서는 Production 환경에서 클러스터를 안전하고 효율적으로 운영하는 방법을 학습했습니다.

오늘 배운 것:

1. Job & CronJob으로 배치 작업 자동화
2. Network Policy로 Zero Trust 네트워크 구현
3. Resource Quotas로 팀별 리소스 관리
4. CRD와 Operator Pattern 이해
5. Helm Chart로 애플리케이션 패키징 (Terraform + Terragrunt 패턴!)
6. etcd 백업 주기와 실무 전략
7. Cluster 업그레이드 절차와 Best Practices

1. Job & CronJob: 배치 작업 관리

Deployment vs Job

🤔 내가 이해한 것:

• Deployment: 항상 실행되어야 하는 워크로드 (웹 서버, API)
• Job: 한 번 실행 후 종료 (데이터 마이그레이션, 백업, 계산)

실습 1: 간단한 Job (π 계산)

apiVersion: batch/v1
kind: Job
metadata:
  name: pi-calculation
spec:
  template:
    spec:
      containers:
      - name: pi
        image: perl:5.34
        command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
      restartPolicy: Never
  backoffLimit: 4

실행 결과:

$ kubectl apply -f job-pi.yaml
job.batch/pi-calculation created

$ kubectl get jobs
NAME              COMPLETIONS   DURATION   AGE
pi-calculation    1/1           8s         45s

$ kubectl get pods
NAME                    READY   STATUS      RESTARTS   AGE
pi-calculation-abc123   0/1     Completed   0          50s

$ kubectl logs pi-calculation-abc123 | head -3
3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117067982148086513282306647093844609550582231725359408128481117450284102701938521105559644622948954930381964428810975665933446128475648233786783165271201909145648566923460348610454326648213393607260249141273724587006606315588174881520920962829254091715364367892590360011330530548820466521384146951941511609433057270365759591953092186117381932611793105118548074462379962749567351885752724891227938183011949129833673362440656643086021394946395224737190702179860943702770539217176293176752384674818467669405132000568127145263560827785771342757789609173637178721468440901224953430146549585371050792279689258923542019956112129021960864034418159813629774771309960518707211349999998372978049951059731732816096318595024459455346908302642522308253344685035261931188171010003137838752886587533208381420617177669147303598253490428755468731159562863882353787593751957781857780532171226806613001927876611195909216420199

2000자리 π 값 출력 성공!

실습 2: Parallel Job (병렬 처리)

apiVersion: batch/v1
kind: Job
metadata:
  name: parallel-job
spec:
  completions: 10      # 총 10번 성공해야 함
  parallelism: 3       # 동시에 3개씩 실행
  template:
    spec:
      containers:
      - name: worker
        image: busybox:1.28
        command: ["/bin/sh", "-c", "echo 'Processing task' && sleep 5 && echo 'Task completed'"]
      restartPolicy: Never

실시간 관찰 (2초마다):

# t=0초 - 3개 동시 시작!
$ kubectl get job parallel-job && kubectl get pods -l job-name=parallel-job
NAME           COMPLETIONS   DURATION   AGE
parallel-job   0/10          3s         3s

NAME                   READY   STATUS    RESTARTS   AGE
parallel-job-abc12     1/1     Running   0          3s
parallel-job-def34     1/1     Running   0          3s
parallel-job-ghi56     1/1     Running   0          3s

# t=8초 - 첫 3개 완료, 다음 3개 시작!
$ kubectl get job parallel-job && kubectl get pods -l job-name=parallel-job
NAME           COMPLETIONS   DURATION   AGE
parallel-job   3/10          11s        11s

NAME                   READY   STATUS      RESTARTS   AGE
parallel-job-abc12     0/1     Completed   0          11s
parallel-job-def34     0/1     Completed   0          11s
parallel-job-ghi56     0/1     Completed   0          11s
parallel-job-jkl78     1/1     Running     0          3s
parallel-job-mno90     1/1     Running     0          3s
parallel-job-pqr12     1/1     Running     0          3s

# t=38초 - 모두 완료!
$ kubectl get job parallel-job
NAME           COMPLETIONS   DURATION   AGE
parallel-job   10/10         38s        38s

결과: 10개 작업을 3개씩 동시 실행하여 38초 만에 완료! (순차 실행 시 50초 소요)

실습 3: CronJob (주기적 백업)

apiVersion: batch/v1
kind: CronJob
metadata:
  name: backup-job
spec:
  schedule: "*/1 * * * *"  # 매 1분마다 (테스트용)
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: busybox:1.28
            command:
            - /bin/sh
            - -c
            - |
              echo "[$(date)] Starting backup..."
              echo "Backing up data..."
              sleep 3
              echo "[$(date)] Backup completed!"
          restartPolicy: OnFailure
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1

3분 후 확인:

$ kubectl get cronjob
NAME         SCHEDULE      SUSPEND   ACTIVE   LAST SCHEDULE   AGE
backup-job   */1 * * * *   False     0        45s             3m

$ kubectl get jobs -l job-name=backup-job
NAME                    COMPLETIONS   DURATION   AGE
backup-job-29369409     1/1           5s         3m
backup-job-29369410     1/1           5s         2m
backup-job-29369411     1/1           5s         1m

$ kubectl logs backup-job-29369411-abc12
[Wed Nov 3 05:42:00 UTC 2025] Starting backup...
Backing up data...
[Wed Nov 3 05:42:03 UTC 2025] Backup completed!

자동으로 매 1분마다 Job 생성 및 실행!

2. Network Policy: Zero Trust 네트워크

🤔 내 질문: "Network Policy는 운영환경에서 모든 리소스마다 걸어두는 편인가?"

답변: 아니요, 일반적으로 20-30%의 중요 리소스에만 적용합니다:

• 데이터베이스 (외부 접근 차단)
• 결제 서비스 (PCI-DSS 규정)
• 인증 서버
• 민감 정보 처리 Pod

🤔 추가 질문: "결제서비스이면 Zero Trust를 해야겠네?"

답변: 네, 반드시 Zero Trust를 적용해야 합니다!

• PCI-DSS 규정 준수 필수
• Default Deny → Explicit Allow
• 모든 통신 경로 명시적 허용

실습: Database 격리 (Backend만 접근 가능)

시나리오:

• Frontend → Database ❌ (차단)
• Backend → Database ✅ (허용)
• Test Pod → Database ❌ (차단)

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: database-policy
  namespace: production
spec:
  podSelector:
    matchLabels:
      app: database
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          app: backend
    ports:
    - protocol: TCP
      port: 5432

테스트 결과:

# Test Pod에서 접근 시도 (차단되어야 함)
$ kubectl exec -n production test-pod -- nc -zv database 5432
nc: database (10.244.5.225): Operation timed out  ❌ 차단 성공!

# Backend Pod에서 접근 시도 (허용되어야 함)
$ kubectl exec -n production backend -- nc -zv database 5432
database (10.244.5.225:5432) open  ✅ 허용 성공!

Network Policy가 정확히 작동!

3. Resource Quotas & LimitRange

ResourceQuota: Namespace 전체 리소스 제한

apiVersion: v1
kind: ResourceQuota
metadata:
  name: dev-quota
  namespace: dev
spec:
  hard:
    requests.cpu: "4"
    requests.memory: 8Gi
    limits.cpu: "8"
    limits.memory: 16Gi
    pods: "10"
    services: "5"

LimitRange: Pod별 기본값 및 제한

apiVersion: v1
kind: LimitRange
metadata:
  name: dev-limits
  namespace: dev
spec:
  limits:
  - max:
      cpu: "2"
      memory: 4Gi
    min:
      cpu: 100m
      memory: 128Mi
    default:
      cpu: 500m       # 기본 limit
      memory: 1Gi
    defaultRequest:
      cpu: 200m       # 기본 request
      memory: 512Mi
    type: Container

실습: 할당량 초과 테스트

1. LimitRange 위반 테스트:

$ kubectl run test-large -n dev --image=nginx \
  --limits=cpu=6  # max는 2 CPU인데 6 요청

Error from server (Forbidden): pods "test-large" is forbidden:
maximum cpu usage per Container is 2, but limit is 6

✅ LimitRange가 먼저 차단!

2. ResourceQuota 위반 테스트:

# 이미 dev namespace에 CPU request 2.2 core 사용 중

$ kubectl run test2 -n dev --image=nginx \
  --requests=cpu=2  # 총 4.2 core가 되어 quota(4) 초과

Error from server (Forbidden): pods "test2" is forbidden:
exceeded quota: dev-quota, requested: requests.cpu=2,
used: requests.cpu=2200m, limited: requests.cpu=4

✅ ResourceQuota가 차단!

기본값 자동 적용 확인

$ kubectl run test-default -n dev --image=nginx

$ kubectl get pod test-default -n dev -o yaml | grep -A 10 resources:
    resources:
      limits:
        cpu: 500m        # ← LimitRange의 default 자동 적용!
        memory: 1Gi
      requests:
        cpu: 200m        # ← defaultRequest 자동 적용!
        memory: 512Mi

리소스를 명시하지 않아도 자동으로 설정됨!

4. Custom Resource Definition (CRD)

🤔 내 질문: "아무리 봐도 굳이 사용하는 이유를 아직은 모르겠다. 컨테이너 이미지를 넣지도 않고 그냥 텍스트 장난으로 보이는데? 왜 쓰는거지?"

이 질문이 가장 중요했습니다!

답변: CRD 단독으로는 아무것도 하지 않습니다. CRD는 단지 데이터 구조 정의일 뿐입니다.

진짜 힘은 Operator Pattern:

CRD (데이터 구조) + Operator (Controller) = 자동화!

실제 사례: Deployment Controller (Built-in Operator)

apiVersion: apps/v1
kind: Deployment  # ← 이것도 CRD입니다! (Built-in)
metadata:
  name: nginx
spec:
  replicas: 3

Deployment를 생성하면:

1. etcd에 Deployment 정보 저장 (CRD 역할)
2. Deployment Controller가 감지 (Operator 역할)
3. ReplicaSet 자동 생성
4. ReplicaSet Controller가 감지
5. Pod 3개 자동 생성
6. Pod가 죽으면 자동으로 재생성! ← 이게 Operator의 힘!

실습: Database CRD

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.mycompany.com
spec:
  group: mycompany.com
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              engine:
                type: string
                enum: ["postgres", "mysql", "mongodb"]
              version:
                type: string
              storage:
                type: string
            required:
            - engine
            - version
  scope: Namespaced
  names:
    plural: databases
    singular: database
    kind: Database
    shortNames:
    - db

Database 생성:

apiVersion: mycompany.com/v1
kind: Database
metadata:
  name: production-db
spec:
  engine: postgres
  version: "15"
  storage: 100Gi

$ kubectl apply -f database.yaml
database.mycompany.com/production-db created

$ kubectl get databases
NAME            AGE
production-db   10s
dev-db          5s

$ kubectl get db  # shortName 동작!
NAME            AGE
production-db   15s
dev-db          10s

스키마 검증 테스트 (enum 위반):

$ kubectl apply -f database-oracle.yaml  # engine: oracle

Error: Unsupported value: "oracle": supported values: "postgres", "mysql", "mongodb"

✅ OpenAPI 스키마 검증 작동!

5. Helm Chart: Kubernetes의 Terraform

🤔 내 질문: "보통 공식으로 올라가있는 chart들은 values.yaml을 받아서 그걸로 다시 install하잖아? 마치 Terraform 모듈화를 terragrunt 환경변수로 환경별로 실행하는걸 떠올리게 한다"

완벽한 이해입니다!

실습 1: 간단한 Chart 생성

$ helm create my-webapp
Creating my-webapp

$ tree my-webapp/
my-webapp/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── _helpers.tpl
└── charts/

values.yaml 수정:

replicaCount: 3

image:
  repository: nginx
  tag: "1.21"

설치:

$ helm install myapp ./my-webapp

$ kubectl get pods -l app.kubernetes.io/name=my-webapp
NAME                         READY   STATUS    RESTARTS   AGE
my-webapp-6c8b4d9f7b-abc12   1/1     Running   0          30s
my-webapp-6c8b4d9f7b-def34   1/1     Running   0          30s
my-webapp-6c8b4d9f7b-ghi56   1/1     Running   0          30s

업그레이드 (replicas 변경):

$ helm upgrade myapp ./my-webapp --set replicaCount=5

$ kubectl get pods -l app.kubernetes.io/name=my-webapp
NAME                         READY   STATUS    RESTARTS   AGE
my-webapp-6c8b4d9f7b-abc12   1/1     Running   0          2m
my-webapp-6c8b4d9f7b-def34   1/1     Running   0          2m
my-webapp-6c8b4d9f7b-ghi56   1/1     Running   0          2m
my-webapp-6c8b4d9f7b-jkl78   1/1     Running   0          5s
my-webapp-6c8b4d9f7b-mno90   1/1     Running   0          5s

롤백:

$ helm rollback myapp 1

$ kubectl get pods -l app.kubernetes.io/name=my-webapp
NAME                         READY   STATUS    RESTARTS   AGE
my-webapp-6c8b4d9f7b-abc12   1/1     Running   0          3m
my-webapp-6c8b4d9f7b-def34   1/1     Running   0          3m
my-webapp-6c8b4d9f7b-ghi56   1/1     Running   0          3m

✅ 다시 3개로 롤백!

실습 2: 환경별 Values 파일 (Terraform 패턴!)

values-dev.yaml (개발 환경):

architecture: standalone  # 단일 인스턴스

auth:
  postgresPassword: "dev-password-123"
  username: "myapp"
  password: "myapp-dev-123"
  database: "myapp_dev"

primary:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

  persistence:
    enabled: true
    storageClass: "local-path"
    size: 5Gi

backup:
  enabled: false

metrics:
  enabled: false

values-prod.yaml (프로덕션 환경):

architecture: replication  # HA 구성

auth:
  existingSecret: "postgres-prod-secret"

primary:
  resources:
    requests:
      memory: "2Gi"
      cpu: "1000m"
    limits:
      memory: "4Gi"
      cpu: "2000m"

  persistence:
    enabled: true
    storageClass: "fast-ssd"
    size: 100Gi

  podAntiAffinityPreset: hard

readReplicas:
  replicaCount: 2

  resources:
    requests:
      memory: "2Gi"
      cpu: "1000m"

backup:
  enabled: true
  cronjob:
    schedule: "0 2 * * *"

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

pgpool:
  enabled: true
  numInitChildren: 32
  maxPool: 4

배포:

# 개발 환경
helm install postgres-dev bitnami/postgresql -f values-dev.yaml -n dev

# 프로덕션 환경
helm install postgres-prod bitnami/postgresql -f values-prod.yaml -n prod

결과:

• 개발: 단일 Pod, 5GB, 백업 없음
• 프로덕션: Primary 1개 + Replica 2개, 100GB, 자동 백업, 모니터링, Connection Pooler

완전히 Terraform + Terragrunt 패턴!

6. etcd Backup & Restore

🤔 내 질문: "실제 운영환경들은 백업 주기는?"

실제 운영환경 백업 주기

가장 일반적인 패턴 (중견기업 표준):

✅ 매 6시간: 자동 백업 (S3 Standard-IA) - 48시간 보관
✅ 매일 새벽 2시: 전체 백업 (S3 Glacier) - 7일 보관
✅ 매주 일요일: 주간 백업 - 4주 보관
✅ 매월 1일: 월간 백업 - 12개월 보관
✅ 배포 직전: 수동 백업 필수!

실습: etcd 백업

$ kubectl exec -n kube-system etcd-cpu1 -- sh -c "ETCDCTL_API=3 etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save /var/lib/etcd/backup.db"

Snapshot saved at /var/lib/etcd/backup.db

$ kubectl exec -n kube-system etcd-cpu1 -- sh -c "ETCDCTL_API=3 etcdctl \
  --write-out=table \
  snapshot status /var/lib/etcd/backup.db"

+---------+----------+------------+------------+
|  HASH   | REVISION | TOTAL KEYS | TOTAL SIZE |
+---------+----------+------------+------------+
| ad8760b |  1030374 |       1760 |     7.6 MB |
+---------+----------+------------+------------+

백업 성공! 1760개 키, 7.6MB

etcd의 중요성

etcd 손실 = 클러스터 전체 손실!

etcd에 저장되는 데이터:

• 모든 Pod, Deployment, Service 정보
• ConfigMap, Secret
• RBAC 권한 설정
• Network Policy
• 모든 Kubernetes 리소스

Production Best Practices

1. 자동 백업: CronJob으로 6시간 또는 일 단위
2. 원격 저장: S3, GCS 등 클라우드 저장소 필수
3. 암호화: 백업 파일 암호화 (Secrets 포함)
4. 3-2-1 Rule: 3개 사본, 2개 매체, 1개 오프사이트
5. 복구 테스트: 분기별 복구 훈련 (DR Drill)
6. 배포 전 백업: 주요 변경 전 반드시 수동 백업

7. Cluster Upgrade

현재 클러스터 상태

$ kubectl version --short
Client Version: v1.31.13
Kustomize Version: v5.4.2
Server Version: v1.31.13

$ kubectl get nodes -o wide
NAME   STATUS   ROLES           AGE     VERSION
cpu1   Ready    control-plane   6d21h   v1.31.13
cpu2   Ready    <none>          5d16h   v1.31.13
gpu1   Ready    <none>          5d16h   v1.31.13

$ sudo kubeadm upgrade plan
[upgrade/versions] Cluster version: 1.31.13
[upgrade/versions] kubeadm version: v1.31.13
[upgrade/versions] Target version: v1.31.13
[upgrade/versions] Latest version in the v1.31 series: v1.31.13

이미 최신 버전이라 실제 업그레이드는 불가능! 대신 시뮬레이션과 이론 학습을 진행했습니다.

업그레이드 규칙

1. 한 번에 한 마이너 버전씩

   ✅ 1.30 → 1.31 → 1.32 (순차)
   ❌ 1.30 → 1.32 (건너뛰기 불가)

2. 업그레이드 순서

   1) etcd 백업 (필수!)
   2) Control Plane 업그레이드 (kubeadm)
   3) Control Plane kubelet 업그레이드
   4) Worker Node 순차 업그레이드 (Rolling)

3. 다운타임

   • Control Plane: 1-2분 (API 서버 재시작)
   • Worker Node: 무중단 (Rolling 방식)
   • Pod: 계속 실행 (kubectl만 잠시 불가)

업그레이드 시뮬레이션 실행

$ ./upgrade-simulation.sh

======================================
Kubernetes Cluster Upgrade Simulation
======================================

[Step 1/10] 업그레이드 전 체크리스트

현재 클러스터 버전 확인:
Client Version: v1.31.13
Kustomize Version: v5.4.2

모든 노드 상태 확인:
NAME   STATUS   ROLES           AGE     VERSION
cpu1   Ready    control-plane   6d21h   v1.31.13
cpu2   Ready    <none>          5d16h   v1.31.13
gpu1   Ready    <none>          5d16h   v1.31.13

✅ Step 1 완료

[Step 2/10] etcd 백업

kubectl exec -n kube-system etcd-cpu1 -- sh -c "ETCDCTL_API=3 etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  snapshot save /var/lib/etcd/pre-upgrade-backup.db"

✅ Step 2 완료 (시뮬레이션)

[Step 3/10] 모든 리소스 백업

명령어: kubectl get all -A -o yaml > /tmp/all-resources-backup.yaml
백업 완료: /tmp/all-resources-backup.yaml (396K)

✅ Step 3 완료

[Step 4/10] API Deprecation 확인

Deprecated API 사용: 3개
⚠️  업그레이드 전 Deprecated API 수정 필요!

[Step 5/10] Control Plane 업그레이드 (시뮬레이션)
[Step 6/10] Control Plane kubelet 업그레이드 (시뮬레이션)
[Step 7/10] Worker Node 1 (cpu2) 업그레이드 (시뮬레이션)
[Step 8/10] Worker Node 2 (gpu1) 업그레이드 (시뮬레이션)

[Step 9/10] 업그레이드 검증

노드 버전 확인:
NAME   STATUS   ROLES           AGE     VERSION
cpu1   Ready    control-plane   6d21h   v1.31.13
cpu2   Ready    <none>          5d16h   v1.31.13
gpu1   Ready    <none>          5d16h   v1.31.13

[Step 10/10] 최종 확인

테스트 워크로드 배포:
pod/upgrade-test created

NAME           READY   STATUS    RESTARTS   AGE   NODE
upgrade-test   1/1     Running   0          3s    gpu1

✅ Step 10 완료

======================================
업그레이드 시뮬레이션 완료!
======================================

API Deprecation (가장 중요!)

Kubernetes는 매 버전마다 API를 Deprecate 시킵니다.

주요 Deprecation 히스토리:

• v1.22: Ingress (extensions/v1beta1 → networking.k8s.io/v1)
• v1.25: PodSecurityPolicy, PodDisruptionBudget (v1beta1 → v1)
• v1.26: HorizontalPodAutoscaler (v2beta2 → v2)
• v1.29: FlowSchema, PriorityLevelConfiguration (v1beta2 → v1)

확인 방법:

$ kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis

apiserver_requested_deprecated_apis{group="",removed_release="",resource="componentstatuses",subresource="",version="v1"} 1

Production 업그레이드 전략

Blue-Green Cluster (대기업):

클러스터 2개 운영 → 트래픽 점진 전환 → 다운타임 Zero
장점: 빠른 롤백, 안전
단점: 2배 비용

Rolling Upgrade (중소기업):

노드 순차 업그레이드 → 1-2분 다운타임
장점: 추가 비용 없음
단점: Control Plane 업그레이드 시 짧은 중단

업그레이드 주기

Kubernetes 버전 지원 정책:

Kubernetes는 최근 3개 마이너 버전만 지원

현재: v1.32 (최신)
v1.32: 지원 ✅
v1.31: 지원 ✅
v1.30: 지원 ✅
v1.29: 지원 종료 ❌ (보안 패치 없음)

결론: 최소 1년에 1-2회 업그레이드 필수!

배운 점

1. Job/CronJob은 생각보다 강력하다

• Parallel Job으로 처리 속도 3배 향상
• CronJob은 백업, 정리 작업에 필수
• backoffLimit로 실패 재시도 자동화

2. Network Policy는 선택적으로

• 20-30% 리소스에만 적용 (DB, 결제, 인증)
• Zero Trust는 결제 서비스 필수 (PCI-DSS)
• 과도한 적용은 운영 복잡도 증가

3. Resource Quotas는 팀 관리의 핵심

• Namespace별 리소스 할당
• LimitRange로 기본값 자동 적용
• 비용 관리와 직결

4. CRD는 Operator와 함께

• CRD 단독으로는 의미 없음
• Operator = CRD + Controller
• Deployment도 사실 CRD + Operator!

5. Helm은 Kubernetes의 Terraform

• Chart = Terraform 모듈
• values.yaml = tfvars
• 환경별 배포 = terragrunt 패턴
• 버전 관리, 롤백 강력

6. etcd 백업은 생명줄

• etcd 손실 = 클러스터 전체 손실
• 6시간 or 일 단위 자동 백업
• 배포 전 수동 백업 필수
• 3-2-1 Rule 준수

7. Cluster Upgrade는 계획이 90%

• API Deprecation 확인 필수
• etcd 백업 먼저
• Control Plane → Worker 순서
• 테스트 환경 먼저 검증
• 1년 1-2회 업그레이드 필수

삽질 포인트

1. Network Policy 테스트 실패

문제: nginx 이미지에 nc (netcat) 명령어 없음

error: exec: "nc": executable file not found in $PATH

해결: busybox:1.28 이미지로 test Pod 생성

kubectl run test-pod -n production --image=busybox:1.28 \
  --labels="app=test" --command -- sleep 3600

2. ResourceQuota vs LimitRange 순서

내 착각: ResourceQuota가 먼저 체크할 줄 알았음

실제: LimitRange → ResourceQuota 순서

• LimitRange가 Pod 생성 시점에 먼저 검증
• ResourceQuota는 Namespace 전체 누적 검증

3. CRD 이해 부족

문제: "CRD가 왜 필요한지 모르겠다"

해결: Operator Pattern 이해로 해결

• CRD = 데이터 구조
• Operator = 자동화 로직
• Deployment = Built-in CRD + Operator 예시

다음 계획 (Day 6)

Day 5에서 Production-Ready 운영을 마스터했습니다! Day 6에서는 Monitoring & Logging으로 클러스터 가시성을 확보할 예정입니다:

1. Prometheus - 메트릭 수집 및 저장
2. Grafana - 시각화 대시보드
3. Prometheus Operator - CRD를 활용한 모니터링 자동화
4. Alert Manager - 장애 알림 자동화
5. Vector + OpenSearch Stack - 로그 수집 및 분석 (Fluentd 대비 10배 빠른 성능!)
   • Vector: Rust 기반 고성능 로그 수집기
   • OpenSearch: 완전 오픈소스 검색 엔진 (Elasticsearch 포크)
   • OpenSearch Dashboards: 로그 검색 및 시각화 (Kibana 포크)
6. Distributed Tracing - Jaeger로 요청 추적
7. Custom Metrics - 애플리케이션 메트릭 노출

Production 클러스터의 가시성을 완벽하게 확보합시다!

참고 자료

• Kubernetes Jobs Documentation
• Network Policies
• Resource Quotas
• Custom Resources
• Helm Documentation
• Backing up etcd
• Upgrading kubeadm clusters

클러스터 환경

노드 구성:

• cpu1 (172.30.1.43): Master + Worker (12 core, 7.5GB RAM)
• cpu2 (172.30.1.80): Worker (8 core, 16GB RAM)
• gpu1 (172.30.1.38): Worker (12 core, 16GB RAM)

버전:

• Kubernetes: v1.31.13
• CNI: Calico (VXLAN CrossSubnet)
• Helm: v3.19.0

2025년 11월 3일 Ingress, HPA, RBAC, StatefulSet, DaemonSet, Monitoring까지 완벽 정복!

들어가며

Day 3에서 Secret, Rolling Update, PV/PVC, Resource Limits, Health Check 등 운영에 필수적인 기능들을 배웠습니다. 이제 Day 4에서는 Production 환경에서 꼭 필요한 고급 패턴들을 학습했습니다.

오늘 배운 것:

1. Ingress와 HTTP 라우팅 (도메인 기반 TLS 종료)
2. HPA로 실시간 자동 스케일링 (1 Pod → 7 Pods 실제 관찰!)
3. RBAC로 외부 개발자 kubectl 접속 설정
4. StatefulSet + Headless Service의 완벽한 이해
5. DaemonSet으로 모든 노드에 자동 배포
6. Monitoring with kube-ops-view

1. Ingress: HTTP 라우팅의 완성판

Ingress가 필요한 이유

Day 2에서 NodePort를 사용했을 때 문제점:

• 포트 번호가 랜덤 (32000-32767)
• URL이 http://172.30.1.43:30456/ 같은 형태
• 여러 서비스마다 다른 포트 필요

Ingress를 사용하면:

• 도메인 이름으로 접근 (http://myapp.local)
• Path 기반 라우팅 (/app1, /app2)
• HTTPS/TLS 종료
• 여러 서비스를 하나의 진입점으로

실습: NGINX Ingress Controller 배포

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.2/deploy/static/provider/baremetal/deploy.yaml

실제 출력:

namespace/ingress-nginx created
serviceaccount/ingress-nginx created
...
service/ingress-nginx-controller created  # NodePort로 생성됨
deployment.apps/ingress-nginx-controller created

Bare-metal 환경에서는 NodePort 사용

클라우드(AWS, GCP)에서는 LoadBalancer 타입이 자동으로 작동하지만, 저희 Bare-metal 클러스터에서는 NodePort를 사용합니다.

$ kubectl get svc -n ingress-nginx
NAME                                 TYPE        CLUSTER-IP       PORT(S)
ingress-nginx-controller             NodePort    10.102.172.125   80:32456/TCP,443:32756/TCP
ingress-nginx-controller-admission   ClusterIP   10.96.66.231     443/TCP

핵심 포인트:

• HTTP: 32456 포트
• HTTPS: 32756 포트

Path-based Routing (경로 기반 라우팅)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: path-based-ingress
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.local
    http:
      paths:
      - path: /app1
        pathType: Prefix
        backend:
          service:
            name: app1
            port:
              number: 80
      - path: /app2
        pathType: Prefix
        backend:
          service:
            name: app2
            port:
              number: 80

/etc/hosts 설정 추가:

172.30.1.43 myapp.local

테스트 결과:

$ curl http://myapp.local:32456/app1
Hello from App1!

$ curl http://myapp.local:32456/app2
Hello from App2!

TLS/HTTPS 설정 (자체 서명 인증서)

🤔 내 질문: "TLS 지금 나 SSL 인증서나 도메인 없는데 무료 인증서로 되니?"

답변: 자체 서명(self-signed) 인증서로 테스트 가능합니다!

# 자체 서명 인증서 생성
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /tmp/tls.key -out /tmp/tls.crt \
  -subj "/CN=myapp.local/O=myapp"

# Secret 생성
kubectl create secret tls myapp-tls \
  --cert=/tmp/tls.crt \
  --key=/tmp/tls.key

Ingress에 TLS 추가:

spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - myapp.local
    secretName: myapp-tls
  rules:
  - host: myapp.local
    ...

HTTPS 테스트 (자체 서명이라 -k 옵션 필요):

$ curl -k https://myapp.local:32756/
Hello from App1!

Host-based Routing (도메인 기반 라우팅)

spec:
  ingressClassName: nginx
  rules:
  - host: app1.local  # 도메인별로 다른 서비스
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app1
            port:
              number: 80
  - host: app2.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app2
            port:
              number: 80

2. HPA: 자동 스케일링의 마법

metrics-server 설치 및 bare-metal 문제 해결

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

문제 발생: Pod가 0/1 Ready 상태로 멈춤

$ kubectl get pod -n kube-system -l k8s-app=metrics-server
NAME                              READY   STATUS    RESTARTS   AGE
metrics-server-5f9f776df5-abc12   0/1     Running   0          2m

원인: Bare-metal 환경에서 kubelet이 유효한 TLS 인증서가 없음

해결: --kubelet-insecure-tls 플래그 추가

kubectl patch deployment metrics-server -n kube-system --type='json' \
  -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--kubelet-insecure-tls"}]'

30-60초 후 확인:

$ kubectl top nodes
NAME   CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
cpu1   483m         4%     3145Mi          41%
cpu2   234m         2%     2891Mi          17%
gpu1   178m         1%     2654Mi          16%

실시간 HPA 테스트

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

apiVersion: apps/v1
kind: Deployment
metadata:
  name: php-apache
spec:
  replicas: 1
  selector:
    matchLabels:
      app: php-apache
  template:
    metadata:
      labels:
        app: php-apache
    spec:
      containers:
      - name: php-apache
        image: registry.k8s.io/hpa-example
        ports:
        - containerPort: 80
        resources:
          requests:
            cpu: 200m  # HPA가 이 값 기준으로 계산
          limits:
            cpu: 500m

HPA 생성 (CPU 50% 목표):

kubectl autoscale deployment php-apache --cpu-percent=50 --min=1 --max=10

$ kubectl get hpa
NAME         REFERENCE               TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
php-apache   Deployment/php-apache   0%/50%    1         10        1          10s

부하 생성 및 실시간 관찰

kubectl run load-generator --image=busybox:1.28 \
  -- /bin/sh -c "while true; do wget -q -O- http://php-apache; done"

스케일링 과정 실시간 관찰 (30초마다 체크):

# t=30초
$ kubectl get hpa
NAME         TARGETS    MINPODS   MAXPODS   REPLICAS
php-apache   200%/50%   1         10        1

$ kubectl get pods -l app=php-apache
NAME                          READY   STATUS    RESTARTS   AGE
php-apache-79544c9bd9-abc12   1/1     Running   0          5m

# t=60초 - 스케일 업 시작!
$ kubectl get hpa
NAME         TARGETS    MINPODS   MAXPODS   REPLICAS
php-apache   200%/50%   1         10        4        # 4개로 증가

$ kubectl get pods -l app=php-apache
NAME                          READY   STATUS              RESTARTS   AGE
php-apache-79544c9bd9-abc12   1/1     Running             0          5m30s
php-apache-79544c9bd9-def34   0/1     ContainerCreating   0          3s
php-apache-79544c9bd9-ghi56   0/1     ContainerCreating   0          3s
php-apache-79544c9bd9-jkl78   0/1     ContainerCreating   0          3s

# t=90초 - 더 많은 Pod 생성
$ kubectl get hpa
NAME         TARGETS    MINPODS   MAXPODS   REPLICAS
php-apache   180%/50%   1         10        7        # 7개로 증가!

$ kubectl get pods -l app=php-apache
NAME                          READY   STATUS    RESTARTS   AGE   NODE
php-apache-79544c9bd9-abc12   1/1     Running   0          6m    cpu1
php-apache-79544c9bd9-def34   1/1     Running   0          33s   cpu2
php-apache-79544c9bd9-ghi56   1/1     Running   0          33s   gpu1
php-apache-79544c9bd9-jkl78   1/1     Running   0          33s   cpu1
php-apache-79544c9bd9-mno90   1/1     Running   0          3s    cpu2
php-apache-79544c9bd9-pqr12   1/1     Running   0          3s    gpu1
php-apache-79544c9bd9-stu34   1/1     Running   0          3s    cpu2

# t=120초 - CPU 안정화
$ kubectl get hpa
NAME         TARGETS   MINPODS   MAXPODS   REPLICAS
php-apache   47%/50%   1         10        7        # 목표 달성!

$ kubectl top pod -l app=php-apache
NAME                          CPU(cores)   MEMORY(bytes)
php-apache-79544c9bd9-abc12   95m          10Mi
php-apache-79544c9bd9-def34   93m          10Mi
php-apache-79544c9bd9-ghi56   91m          10Mi
php-apache-79544c9bd9-jkl78   94m          10Mi
php-apache-79544c9bd9-mno90   92m          10Mi
php-apache-79544c9bd9-pqr12   90m          10Mi
php-apache-79544c9bd9-stu34   93m          10Mi

결과:

• 1 Pod → 4 Pods → 7 Pods (60초 만에!)
• CPU: 0% → 200% → 47% (안정화)
• 각 Pod가 CPU request(200m)의 약 47% 사용

스케일 다운 (Scale-down)

부하 생성기 삭제 후:

kubectl delete pod load-generator

5분 후 (기본 scale-down 대기 시간):

$ kubectl get hpa
NAME         TARGETS   MINPODS   MAXPODS   REPLICAS
php-apache   0%/50%    1         10        7        # 아직 7개

# 5분 경과 후
$ kubectl get hpa
NAME         TARGETS   MINPODS   MAXPODS   REPLICAS
php-apache   0%/50%    1         10        1        # 1개로 감소!

3. RBAC: 외부 개발자 kubectl 접속 설정

🤔 내 질문: "RBAC는 어쩔때 쓰는거야?"

답변: RBAC는 다음 3가지 상황에서 필수입니다:

1. Pod가 Kubernetes API에 접근할 때

   • 예: Prometheus가 메트릭 수집
   • ServiceAccount로 권한 부여

2. 외부 개발자가 kubectl 사용할 때

   • 개발자 컴퓨터에서 kubectl로 클러스터 접속
   • X.509 인증서로 신원 확인

3. CI/CD 시스템이 배포할 때

   • Jenkins, GitLab CI가 kubectl apply
   • ServiceAccount Token 사용

🤔 내 추가 질문: "개발자 컴퓨터가 워커노드로 연결되어 있지 않아도 본인 로컬에 3개의 인증서 파일을 넣고 그 경로는 어떻게 지정해서 config에 넣어줘야하는것이며 그냥 kubectl 만 깔려있으면 명령어 사용이 가능하다는거지?"

답변: 네, 맞습니다! 개발자 컴퓨터는 워커 노드가 아닙니다. 그냥 kubectl 클라이언트만 설치하면 됩니다.

실습: john 개발자 계정 생성

1. 개인키 생성:

openssl genrsa -out john.key 2048

2. CSR (Certificate Signing Request) 생성:

openssl req -new -key john.key -out john.csr \
  -subj "/CN=john/O=dev-team"

• CN=john: 사용자 이름
• O=dev-team: 그룹 이름

3. Kubernetes CA로 서명:

sudo openssl x509 -req -in john.csr \
  -CA /etc/kubernetes/pki/ca.crt \
  -CAkey /etc/kubernetes/pki/ca.key \
  -CAcreateserial -out john.crt -days 365

실제 출력:

Certificate request self-signature ok
subject=CN = john, O = dev-team

4. kubeconfig 파일 생성:

~/.kube/config (개발자 로컬):

apiVersion: v1
kind: Config
clusters:
- cluster:
    certificate-authority: /Users/john/.kube/certs/ca.crt
    server: https://172.30.1.43:6443
  name: production-cluster

contexts:
- context:
    cluster: production-cluster
    user: john
    namespace: dev
  name: john@production

current-context: john@production

users:
- name: john
  user:
    client-certificate: /Users/john/.kube/certs/john.crt
    client-key: /Users/john/.kube/certs/john.key

5. 권한 테스트 (기본 = 모두 거부):

$ kubectl get pods
Error from server (Forbidden): pods is forbidden: User "john" cannot list resource "pods" in API group "" in the namespace "default"

$ kubectl get pods -n dev
Error from server (Forbidden): pods is forbidden: User "john" cannot list resource "pods" in API group "" in the namespace "dev"

Kubernetes의 기본 정책: Deny by default!

6. dev namespace에 view 권한 부여:

kubectl create namespace dev

kubectl create rolebinding john-view \
  --clusterrole=view \
  --user=john \
  --namespace=dev

권한 확인:

$ kubectl auth can-i get pods -n dev --as=john
yes

$ kubectl auth can-i get pods -n default --as=john
no

john 계정으로 테스트:

$ kubectl get pods -n dev
NAME    READY   STATUS    RESTARTS   AGE
nginx   1/1     Running   0          2m

$ kubectl get pods -n default
Error from server (Forbidden): pods is forbidden: User "john" cannot list resource "pods"

개발자 패키지 전달

개발자에게 전달할 파일:

developer-package/
├── ca.crt           # 클러스터 CA 인증서
├── john.crt         # 개발자 인증서
├── john.key         # 개발자 개인키 (절대 공유 금지!)
├── kubeconfig-sample  # kubeconfig 예제
└── README.md        # 설정 가이드

개발자 컴퓨터 요구사항:

• ✅ kubectl 설치만 필요
• ✅ 네트워크: API Server (172.30.1.43:6443) 접근 가능
• ❌ Docker, kubelet 불필요!
• ❌ 워커노드 아님! 클러스터 join 불필요!

4. StatefulSet + Headless Service: 완벽한 이해

🤔 내 질문: "headless서비스는 정확히 왜 statefulset에 필수이며 왜 필요한거고 뭔지 설명이 부족했어"

이 질문에 답하기 위해 심도 있게 파고들었습니다!

Headless Service란?

일반 Service:

apiVersion: v1
kind: Service
metadata:
  name: normal-service
spec:
  clusterIP: 10.96.100.50  # 가상 IP 할당됨
  selector:
    app: myapp
  ports:
  - port: 80

DNS 쿼리 결과:

$ nslookup normal-service
Server:    10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local

Name:      normal-service
Address 1: 10.96.100.50  # Service IP 1개만 반환

→ kube-proxy가 로드밸런싱 → 어떤 Pod에 연결될지 모름 (랜덤)

Headless Service:

apiVersion: v1
kind: Service
metadata:
  name: nginx-headless
spec:
  clusterIP: None  # ← Headless!
  selector:
    app: nginx-stateful
  ports:
  - port: 80

DNS 쿼리 결과:

$ nslookup nginx-headless
Server:    10.96.0.10
Address 1: 10.96.0.10 kube-dns.kube-system.svc.cluster.local

Name:      nginx-headless
Address 1: 10.244.102.162  # Pod-0 IP
Address 2: 10.244.5.234    # Pod-1 IP
Address 3: 10.244.184.94   # Pod-2 IP

→ 모든 Pod IP를 직접 반환! → 개별 Pod DNS도 제공:

$ nslookup nginx-stateful-0.nginx-headless
Name:      nginx-stateful-0.nginx-headless
Address 1: 10.244.102.162  # Pod-0 IP만 반환

왜 StatefulSet에 필수인가?

실제 MongoDB Replica Set 예시:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mongodb
spec:
  serviceName: mongodb-headless  # ← Headless Service 연결
  replicas: 3
  ...

MongoDB 초기화:

rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongodb-0.mongodb-headless:27017" },  # Primary
    { _id: 1, host: "mongodb-1.mongodb-headless:27017" },  # Secondary
    { _id: 2, host: "mongodb-2.mongodb-headless:27017" }   # Secondary
  ]
})

애플리케이션 연결:

const uri = "mongodb://mongodb-0.mongodb-headless:27017,mongodb-1.mongodb-headless:27017,mongodb-2.mongodb-headless:27017/mydb?replicaSet=rs0"

만약 일반 Service를 쓴다면?

• mongodb-service:27017 하나의 주소만 가능
• kube-proxy가 랜덤하게 로드밸런싱
• Primary/Secondary 구분 불가능!
• MongoDB Replica Set 구성 실패!

실습: StatefulSet 순차적 생성

apiVersion: v1
kind: Service
metadata:
  name: nginx-headless
spec:
  clusterIP: None
  selector:
    app: nginx-stateful
  ports:
  - port: 80
    name: web
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: nginx-stateful
spec:
  serviceName: nginx-headless
  replicas: 3
  selector:
    matchLabels:
      app: nginx-stateful
  template:
    metadata:
      labels:
        app: nginx-stateful
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
        ports:
        - containerPort: 80
          name: web
        volumeMounts:
        - name: www
          mountPath: /usr/share/nginx/html
      volumes:
      - name: www
        emptyDir: {}

실제 생성 과정 (2초 간격):

$ kubectl apply -f statefulset.yaml

# t=0초
--- 15:00:00 ---
NAME               READY   STATUS              RESTARTS   AGE
nginx-stateful-0   0/1     ContainerCreating   0          0s

# t=2초
--- 15:00:02 ---
NAME               READY   STATUS    RESTARTS   AGE
nginx-stateful-0   1/1     Running   0          2s        # Pod-0 Ready!
nginx-stateful-1   0/1     Pending   0          0s        # Pod-1 생성 시작

# t=4초
--- 15:00:04 ---
NAME               READY   STATUS    RESTARTS   AGE
nginx-stateful-0   1/1     Running   0          4s
nginx-stateful-1   1/1     Running   0          2s        # Pod-1 Ready!
nginx-stateful-2   0/1     Pending   0          0s        # Pod-2 생성 시작

# t=6초
--- 15:00:06 ---
NAME               READY   STATUS    RESTARTS   AGE
nginx-stateful-0   1/1     Running   0          6s
nginx-stateful-1   1/1     Running   0          4s
nginx-stateful-2   1/1     Running   0          2s        # Pod-2 Ready!

순차적 생성! Pod-0이 Running이 되어야 Pod-1이 생성 시작!

Pod 분포 확인:

$ kubectl get pods -o wide -l app=nginx-stateful
NAME               READY   STATUS    RESTARTS   AGE   IP              NODE
nginx-stateful-0   1/1     Running   0          2m    10.244.102.162  cpu2
nginx-stateful-1   1/1     Running   0          2m    10.244.5.234    gpu1
nginx-stateful-2   1/1     Running   0          2m    10.244.184.94   cpu1

안정적인 네트워크 ID 확인:

$ kubectl run -it --rm dns-test --image=busybox:1.28 --restart=Never -- \
  nslookup nginx-stateful-0.nginx-headless

Name:      nginx-stateful-0.nginx-headless.default.svc.cluster.local
Address 1: 10.244.102.162

Pod를 재시작해도:

• IP는 변경될 수 있음: 10.244.102.162 → 10.244.5.240
• DNS 이름은 불변: nginx-stateful-0.nginx-headless

5. DaemonSet: 모든 노드에 자동 배포

🤔 내 질문: "그러면 Daemonset에서는 이게 필요없는가?"

답변: 네, DaemonSet은 Headless Service가 필요 없습니다!

DaemonSet vs StatefulSet

실습: fluentd 로그 수집

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluentd
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: fluentd
  template:
    metadata:
      labels:
        app: fluentd
    spec:
      tolerations:
      - key: node-role.kubernetes.io/control-plane
        effect: NoSchedule
      containers:
      - name: fluentd
        image: fluent/fluentd:v1.14-1
        volumeMounts:
        - name: varlog
          mountPath: /var/log
          readOnly: true
      volumes:
      - name: varlog
        hostPath:
          path: /var/log

배포 결과:

$ kubectl get daemonset -n kube-system fluentd
NAME      DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
fluentd   3         3         3       3            3           <none>          1m

$ kubectl get pods -n kube-system -l app=fluentd -o wide
NAME            READY   STATUS    RESTARTS   AGE   IP             NODE
fluentd-ntq9z   1/1     Running   0          1m    10.244.5.237   gpu1
fluentd-pnx9h   1/1     Running   0          1m    10.244.102.166 cpu2
fluentd-vq7wd   1/1     Running   0          1m    10.244.184.95  cpu1

자동으로 3개 노드에 각 1개씩 배포!

nodeSelector로 특정 노드만 선택

# gpu1 노드에 라벨 추가
kubectl label nodes gpu1 disktype=ssd

# gpu1 노드에만 배포되는 DaemonSet
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: node-exporter-ssd
spec:
  selector:
    matchLabels:
      app: node-exporter-ssd
  template:
    spec:
      nodeSelector:
        disktype: ssd  # ← disktype=ssd 라벨이 있는 노드에만!
      containers:
      - name: node-exporter
        image: prom/node-exporter:v1.3.1

결과:

$ kubectl get daemonset -n kube-system node-exporter-ssd
NAME                DESIRED   CURRENT   READY   NODE SELECTOR
node-exporter-ssd   1         1         1       disktype=ssd

$ kubectl get pods -n kube-system -l app=node-exporter-ssd -o wide
NAME                      READY   STATUS    RESTARTS   AGE   NODE
node-exporter-ssd-wqjvn   1/1     Running   0          30s   gpu1

cpu2 노드에도 라벨 추가:

kubectl label nodes cpu2 disktype=ssd

자동으로 Pod 추가 생성!

$ kubectl get pods -n kube-system -l app=node-exporter-ssd -o wide
NAME                      READY   STATUS    RESTARTS   AGE   NODE
node-exporter-ssd-lf8g2   1/1     Running   0          3s    cpu2  # 자동 생성!
node-exporter-ssd-wqjvn   1/1     Running   0          36s   gpu1

6. Monitoring: kube-ops-view

삽질 포인트: Redis 에러

처음에 공식 YAML로 설치했더니 Redis 연결 에러 발생:

redis.exceptions.ConnectionError: Error -2 connecting to kube-ops-view-redis:6379. Name or service not known.

Redis가 포함되지 않은 불완전한 설치였습니다.

해결: Helm으로 재설치

# Helm 설치
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# geek-cookbook repo 추가
helm repo add geek-cookbook https://geek-cookbook.github.io/charts/

# kube-ops-view 설치 (Redis 포함)
helm install kube-ops-view geek-cookbook/kube-ops-view \
  --version 1.2.2 \
  --set service.main.type=NodePort,service.main.ports.http.nodePort=30005 \
  --set env.TZ="Asia/Seoul" \
  --namespace kube-system

설치 확인:

$ kubectl get deploy,pod,svc,ep -n kube-system -l app.kubernetes.io/instance=kube-ops-view

NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/kube-ops-view   1/1     1            1           29s

NAME                                 READY   STATUS    RESTARTS   AGE
pod/kube-ops-view-657dbc6cd8-g7s7t   1/1     Running   0          29s

NAME                    TYPE       CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
service/kube-ops-view   NodePort   10.100.118.167   <none>        8080:30005/TCP   29s

NAME                      ENDPOINTS             AGE
endpoints/kube-ops-view   10.244.102.168:8080   29s

웹 접속:

http://172.30.1.43:30005

실시간으로 볼 수 있는 것:

• 3개 노드 시각화 (cpu1, cpu2, gpu1)
• 각 노드별 Pod 분포
• CPU/메모리 사용량
• StatefulSet Pods (nginx-stateful-0, -1, -2)
• DaemonSet Pods (fluentd x 3)
• Ingress Controller Pods

배운 점

1. Ingress는 Production의 기본

• NodePort는 개발/테스트용
• Ingress로 도메인 기반 라우팅, TLS 종료
• Bare-metal에서는 NodePort로 Ingress Controller 노출

2. HPA는 생각보다 빠르다

• 60초 만에 1 Pod → 7 Pods
• metrics-server 필수 (bare-metal은 --kubelet-insecure-tls)
• Scale-down은 5분 대기 (안정성)

3. RBAC는 보안의 핵심

• 기본 정책: Deny by default
• X.509 인증서로 외부 개발자 접속
• Namespace 범위 권한 부여 가능

4. Headless Service의 진짜 의미

• StatefulSet: 개별 Pod DNS 필요 (mongodb-0.svc)
• DaemonSet: 불필요 (각 노드에서 독립 동작)
• MongoDB, Kafka, Elasticsearch 같은 Cluster 구성에 필수

5. DaemonSet은 자동화의 극치

• 노드 추가 → Pod 자동 생성
• 노드 삭제 → Pod 자동 제거
• nodeSelector로 특정 노드만 선택 가능

6. Helm이 복잡한 애플리케이션에는 필수

• YAML 여러 개 관리의 어려움
• Redis, DB 등 dependency 자동 설치
• 버전 관리 용이

삽질 포인트

1. metrics-server Pod가 0/1 Ready로 멈춤

원인: Bare-metal 클러스터는 kubelet TLS 인증서 없음 해결: --kubelet-insecure-tls 플래그 추가

2. kube-ops-view Redis 에러

원인: 공식 YAML에 Redis 미포함 해결: Helm Chart 사용 (dependency 자동 설치)

3. Ingress Service가 Pod를 못 찾음

원인: Service selector와 Deployment label 불일치 해결: Label 정확히 매칭 (application: kube-ops-view)

4. StatefulSet PVC Pending

원인: Bare-metal에 StorageClass 없음 해결: emptyDir 사용 (데모용)

다음 계획 (Day 5)

Day 4에서 Advanced 패턴을 마스터했습니다. Day 5에서는 Production 운영에 필요한 추가 기능들을 학습할 예정입니다:

1. Job & CronJob - 배치 작업 실행
2. Network Policy - Pod 간 네트워크 격리
3. Resource Quotas & LimitRange - Namespace별 리소스 제한
4. Custom Resource Definition (CRD) - Kubernetes 확장
5. Helm Chart 작성 - 자체 애플리케이션 패키징
6. Backup & Restore - etcd 백업/복구
7. Cluster Upgrade - 무중단 클러스터 업그레이드

Production-ready Kubernetes Cluster를 완성합시다!

참고 자료

• Kubernetes Ingress Documentation
• HPA Walkthrough
• RBAC Authorization
• StatefulSet Basics
• DaemonSet

클러스터 환경

노드 구성:

• cpu1 (172.30.1.43): Master + Worker (12 core, 7.5GB RAM)
• cpu2 (172.30.1.80): Worker (8 core, 16GB RAM)
• gpu1 (172.30.1.38): Worker (12 core, 16GB RAM)

버전:

• Kubernetes: v1.31.13
• CNI: Calico (VXLAN CrossSubnet)
• Ingress: NGINX Ingress Controller v1.8.2
• Helm: v3.19.0

3-node 클러스터에서 직접 실습하며 배운 Kubernetes Operations의 모든 것

들어가며

Day 2에서 클러스터 아키텍처와 네트워킹을 이해했다면, Day 3는 실전 운영에 필요한 기술들을 익히는 날이었습니다. Secret 관리부터 Rolling Update, Health Check까지 - Production 환경에서 반드시 알아야 할 개념들을 직접 실습하며 체득했습니다.

특히 이번 Day에서는 "왜 이 기능이 필요한가?"라는 질문을 끊임없이 던지며, 단순히 명령어를 외우는 것이 아니라 설계 철학을 이해하는 데 집중했습니다.

학습 환경

• Kubernetes: v1.31.13
• 클러스터 구성:
  • cpu1 (172.30.1.43): Master + Worker (12 core, 7.5GB RAM)
  • cpu2 (172.30.1.34): Worker (8 core, 16GB RAM)
  • gpu1 (172.30.1.38): Worker (12 core, 16GB RAM)
• CNI: Calico (VXLAN CrossSubnet)

1. Secret과 ConfigMap: 민감 정보는 어떻게 관리할까?

ConfigMap vs Secret: 차이가 뭘까?

처음엔 의문이었습니다. "둘 다 설정 정보 저장하는 거 아닌가? 왜 굳이 나눠놨을까?"

핵심 차이:

# ConfigMap: 일반 텍스트
data:
  app.env: |
    LOG_LEVEL=info
    MAX_CONNECTIONS=100

# Secret: base64 인코딩
data:
  password: c3VwZXJzZWNyZXQxMjM=  # echo -n 'supersecret123' | base64

Secret은 base64로 인코딩되고, etcd에 암호화되어 저장됩니다. (etcd encryption 설정 시)

Secret 사용 방법 실습

1. 환경변수로 주입:

kubectl create secret generic db-credentials \
  --from-literal=username=admin \
  --from-literal=password=supersecret123

# Pod에서 환경변수로 사용
env:
- name: DB_USER
  valueFrom:
    secretKeyRef:
      name: db-credentials
      key: username

검증:

$ kubectl exec secret-env-pod -- env | grep DB_USER
DB_USER=admin

2. 볼륨으로 마운트:

volumes:
- name: secret-volume
  secret:
    secretName: db-credentials

실제로 들어가보니 신기한 구조:

$ kubectl exec secret-volume-pod -- ls -la /etc/secrets
total 0
drwxrwxrwt 3 root root  120 Nov  1 10:23 .
drwxr-xr-x 1 root root 4096 Nov  1 10:23 ..
drwxr-xr-x 2 root root   80 Nov  1 10:23 ..2025_11_01_10_23_45.1234567890
lrwxrwxrwx 1 root root   32 Nov  1 10:23 ..data -> ..2025_11_01_10_23_45.1234567890
lrwxrwxrwx 1 root root   15 Nov  1 10:23 password -> ..data/password
lrwxrwxrwx 1 root root   15 Nov  1 10:23 username -> ..data/username

심볼릭 링크 구조! 이렇게 하면 Secret을 업데이트해도 파일 경로는 동일하게 유지됩니다.

배운 점

• Secret은 단순히 "보안"만이 아니라 RBAC과 통합되어 권한 관리가 가능
• 볼륨 마운트 시 심볼릭 링크 구조로 무중단 업데이트 가능

2. Rolling Update: 무중단 배포의 마법

maxSurge와 maxUnavailable의 비밀

문서에서 "Rolling Update는 무중단 배포를 지원합니다"라는 말은 많이 봤지만, 실제로 어떻게 동작하는지 보고 싶었습니다.

전략 설정:

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 0        # 추가 Pod 생성 안 함
    maxUnavailable: 1  # 한 번에 1개씩만 교체

업데이트 실행:

$ kubectl set image deployment/nginx-rolling nginx=nginx:1.21

실시간 모니터링 결과:

# 시작 (3개 모두 Running)
nginx-rolling-56d8f-abc   1/1   Running
nginx-rolling-56d8f-def   1/1   Running
nginx-rolling-56d8f-ghi   1/1   Running

# 첫 번째 교체
nginx-rolling-56d8f-abc   1/1   Terminating     <- 종료 중
nginx-rolling-56d8f-def   1/1   Running
nginx-rolling-56d8f-ghi   1/1   Running
nginx-rolling-7c9d4-jkl   0/1   ContainerCreating  <- 생성 중

# 새 Pod Ready
nginx-rolling-56d8f-def   1/1   Running
nginx-rolling-56d8f-ghi   1/1   Running
nginx-rolling-7c9d4-jkl   1/1   Running         <- Ready!

# 두 번째 교체
nginx-rolling-56d8f-def   1/1   Terminating
nginx-rolling-56d8f-ghi   1/1   Running
nginx-rolling-7c9d4-jkl   1/1   Running
nginx-rolling-7c9d4-mno   0/1   ContainerCreating

놀라운 점:

• 정확히 한 번에 하나씩만 교체됨
• 새 Pod가 Running이 된 후에야 다음 Pod 종료 시작
• 서비스 중단 없이 완벽하게 업데이트!

배운 점

maxSurge=0, maxUnavailable=1
→ 총 Pod 수는 항상 3개 유지
→ 하나씩 차근차근 교체

maxSurge=1, maxUnavailable=1 (기본값)
→ 총 Pod 수는 3~4개 (최대 4개까지 가능)
→ 더 빠른 업데이트, 약간의 리소스 오버헤드

3. PV/PVC: 스토리지 추상화의 필요성

HostPath의 함정

처음엔 간단하게 생각했습니다. "각 노드에 같은 경로로 PV 만들면 되겠지?"

현실은...

gpu1 노드에서 데이터 생성:

$ kubectl exec pvc-test-pod -- sh -c "echo 'Data from gpu1' > /data/test.txt"
$ kubectl exec pvc-test-pod -- cat /data/test.txt
Data from gpu1

Pod를 cpu1 노드로 이동:

$ kubectl delete pod pvc-test-pod
$ kubectl apply -f pvc-test-pod.yaml  # nodeSelector: cpu1
$ kubectl exec pvc-test-pod -- cat /data/test.txt
cat: can't open '/data/test.txt': No such file or directory

아하! HostPath는 노드 로컬 스토리지였습니다. 다른 노드에선 접근 불가!

Ceph가 뭐길래?

"그럼 여러 노드에서 같은 데이터를 쓰려면 어떻게 하지?"

해답: 분산 스토리지 시스템

┌─────────────────────────────────────┐
│  Kubernetes Cluster                 │
│  ┌─────┐  ┌─────┐  ┌─────┐         │
│  │ cpu1│  │ cpu2│  │ gpu1│         │
│  └──┬──┘  └──┬──┘  └──┬──┘         │
│     │        │        │             │
│     └────────┼────────┘             │
│              │                      │
│         ┌────▼─────┐                │
│         │   Ceph   │ ← 네트워크 스토리지
│         │  Cluster │                │
│         └──────────┘                │
│  (cpu1, cpu2, gpu1의 디스크를       │
│   통합하여 하나의 스토리지로 제공)   │
└─────────────────────────────────────┘

Ceph:

• 여러 노드의 SSD/HDD를 하나의 스토리지 풀로 통합
• 데이터 복제 (Replication)로 안정성 보장
• ReadWriteMany (RWX) 지원 - 여러 Pod가 동시 접근 가능

AWS EFS, GCP Persistent Disk 등도 같은 원리!

PV vs PVC: 왜 나눴을까?

"PV만 있으면 되는 거 아냐? PVC는 왜 필요하지?"

설계 철학:

PV (PersistentVolume)
  ├─ 클러스터 레벨 리소스
  ├─ 관리자가 프로비저닝
  └─ 실제 스토리지 백엔드 정의

PVC (PersistentVolumeClaim)
  ├─ 네임스페이스 레벨 리소스
  ├─ 개발자가 요청
  └─ 필요한 용량/접근모드만 명시

비유:

• PV = 아파트 (실제 부동산)
• PVC = 임대 계약서 (사용 권한)

장점:

1. 추상화: 개발자는 스토리지 구현 몰라도 됨
2. 격리: 네임스페이스별 권한 관리
3. 동적 프로비저닝: StorageClass로 자동 생성 가능

배운 점

• HostPath는 개발/테스트용, Production에선 Ceph/NFS 필수
• PV/PVC 분리는 관심사의 분리 (Separation of Concerns)

4. QoS: 리소스 압박 시 누구를 살릴 것인가?

처음엔 이해 안 됐던 QoS

"limits 넘으면 OOMKilled되는데, QoS는 또 뭐지?"

핵심 차이:

OOMKilled (개별 Pod)
  ├─ Pod가 자신의 limits를 초과할 때
  ├─ 언제든 발생 가능
  └─ 해당 Pod만 종료

QoS Eviction (노드 전체)
  ├─ 노드 전체 메모리 부족 시
  ├─ 여러 Pod 중 누구를 죽일지 결정
  └─ 우선순위: BestEffort > Burstable > Guaranteed

QoS 클래스 실습

1. Guaranteed: 최고 우선순위

resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
  limits:
    cpu: "100m"      # requests = limits
    memory: "128Mi"

2. Burstable: 중간 우선순위

resources:
  requests:
    memory: "128Mi"
  limits:
    memory: "256Mi"  # limits > requests

3. BestEffort: 최하위 우선순위

resources: {}  # 아무것도 지정 안 함

검증:

$ kubectl get pod qos-guaranteed -o jsonpath='{.status.qosClass}'
Guaranteed

$ kubectl get pod qos-burstable -o jsonpath='{.status.qosClass}'
Burstable

실용적 사용 사례 (핵심!)

처음엔 "다 필요한 Pod인데 왜 죽여?"라고 생각했지만, 실제 사례를 들으니 보험 같은 개념이라는 걸 깨달았습니다.

시나리오 1: 클라우드 비용 최적화

# 핵심 API 서버 - Guaranteed
api-server:
  resources:
    requests: {memory: 2Gi}
    limits: {memory: 2Gi}

# 로그 수집기 - Burstable
log-collector:
  resources:
    requests: {memory: 256Mi}
    limits: {memory: 1Gi}

# 통계 분석 - BestEffort
analytics:
  resources: {}  # 평소엔 여유 리소스 사용, 압박 시 희생

시나리오 2: 피크 타임 대응

• 평소: 모든 서비스 정상 동작
• 트래픽 급증:
  • Guaranteed (API) → 절대 보호
  • BestEffort (통계) → 자동 종료
  • Burstable (로그) → 상황에 따라

시나리오 3: 스팟 인스턴스 활용

• 저렴한 스팟 인스턴스에는 BestEffort Pod 배치
• 인스턴스 종료되어도 핵심 서비스 무사

배운 점

• QoS는 "Pod 죽이는 기능"이 아니라 리소스 압박 시 우선순위 보험
• "Replica 줄여도 되는 서비스"에 낮은 QoS 부여
• 멀티테넌트 클러스터에서 특히 중요

5. Health Check: Kubernetes가 애플리케이션 상태를 아는 법

Liveness vs Readiness: 헷갈리는 두 Probe

Liveness Probe

• "살아있니?"
• 실패 시 → Pod 재시작
• 데드락, 무한루프 같은 상황 복구

Readiness Probe

• "트래픽 받을 준비 됐니?"
• 실패 시 → Service Endpoints에서 제외
• 초기화, DB 연결 대기 등

Liveness Probe 실습

시나리오: 30초 후 파일 삭제

livenessProbe:
  exec:
    command:
      - cat
      - /tmp/healthy
  initialDelaySeconds: 5
  periodSeconds: 5

# Container command
command:
  - sh
  - -c
  - |
    touch /tmp/healthy
    sleep 30
    rm -f /tmp/healthy  # 30초 후 삭제!
    sleep 600

결과:

$ kubectl get pod liveness-test -w
NAME            READY   STATUS    RESTARTS   AGE
liveness-test   1/1     Running   0          10s
liveness-test   1/1     Running   0          30s
liveness-test   1/1     Running   1          40s  <- 재시작!

정확히 30초 후 재시작! Liveness Probe가 실패를 감지하고 자동 복구했습니다.

Readiness Probe 실습

시나리오: /ready 파일 없으면 트래픽 차단

readinessProbe:
  httpGet:
    path: /ready
    port: 80
  initialDelaySeconds: 5
  periodSeconds: 5

배포 직후:

$ kubectl get pod -n production
NAME                          READY   STATUS    RESTARTS   AGE
production-app-7c9d4-abc      0/1     Running   0          10s  <- 0/1!
production-app-7c9d4-def      0/1     Running   0          10s

Endpoints 확인:

$ kubectl get endpoints production-app -n production
NAME             ENDPOINTS   AGE
production-app   <none>      30s  <- 비어있음!

/ready 파일 생성:

$ kubectl exec -n production production-app-7c9d4-abc -- \
  sh -c "echo 'ready' > /usr/share/nginx/html/ready"

$ kubectl get pod -n production
production-app-7c9d4-abc      1/1     Running   0          1m  <- 1/1!

$ kubectl get endpoints production-app -n production
production-app   10.244.5.224:80,10.244.102.153:80,10.244.184.91:80

완벽하게 동작! Readiness가 통과되자 Endpoints에 자동 등록되었습니다.

Startup Probe: 느린 애플리케이션을 위한 배려

startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  failureThreshold: 30    # 30번 실패까지 허용
  periodSeconds: 10       # 10초마다 체크
  # → 최대 300초(5분) 대기

Java Spring Boot처럼 초기화가 오래 걸리는 앱에 유용합니다.

배운 점

• Liveness: "죽은 Pod" 재시작
• Readiness: "준비 안 된 Pod" 트래픽 차단
• Startup: "느린 Pod" 보호
• 세 가지를 함께 사용해야 완벽한 Health Check!

6. 실전 시나리오: Production-Ready 애플리케이션 배포

배운 모든 것을 하나로

Day 3의 모든 개념을 통합한 Production 애플리케이션을 배포했습니다.

아키텍처:

production namespace
├── ConfigMap (nginx.conf + app.env)
├── Secret (DB_PASSWORD, API_KEY)
├── Deployment (3 replicas)
│   ├── Resource requests/limits (QoS: Burstable)
│   ├── Liveness Probe (/health)
│   ├── Readiness Probe (/ready)
│   ├── Rolling Update (maxSurge: 1, maxUnavailable: 1)
│   └── ConfigMap/Secret mount
├── Service (ClusterIP)
└── Service (NodePort 30080)

Deployment YAML (핵심 부분)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: production-app
  namespace: production
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1
  template:
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
        # QoS: Burstable
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "200m"
            memory: "256Mi"
        # Health Checks
        livenessProbe:
          httpGet:
            path: /health
            port: 80
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 80
          initialDelaySeconds: 5
          periodSeconds: 5
        # Secret 환경변수
        env:
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: DB_PASSWORD
        # ConfigMap 마운트
        volumeMounts:
        - name: nginx-config
          mountPath: /etc/nginx/nginx.conf
          subPath: nginx.conf
      volumes:
      - name: nginx-config
        configMap:
          name: app-config

배포 검증

1. Pod 분산 배포 확인:

$ kubectl get pods -n production -o wide
NAME                              NODE   IP               READY
production-app-849b867f78-9vkkp   cpu1   10.244.184.91    1/1
production-app-849b867f78-b2fjx   gpu1   10.244.5.224     1/1
production-app-849b867f78-kkdjv   cpu2   10.244.102.153   1/1

완벽하게 3개 노드에 분산!

2. QoS 클래스 확인:

$ kubectl get pod production-app-849b867f78-9vkkp -n production \
  -o jsonpath='{.status.qosClass}'
Burstable

3. 내부 접근 테스트:

$ kubectl run test-v1 --rm -i --restart=Never -n production \
  --image=busybox:1.28 -- wget -qO- http://production-app

Hello from Production App v1.0

4. 외부 접근 테스트 (NodePort):

$ curl http://172.30.1.43:30080
Hello from Production App v1.0

Rolling Update 실전 (v1.0 → v2.0)

ConfigMap 업데이트:

$ kubectl apply -f app-config-v2.yaml
configmap/app-config configured

Deployment restart로 Rolling Update 트리거:

$ kubectl rollout restart deployment production-app -n production
deployment.apps/production-app restarted

$ kubectl rollout status deployment production-app -n production
deployment "production-app" successfully rolled out

업데이트 확인:

$ kubectl get pods -n production
NAME                              READY   STATUS    AGE
production-app-849b867f78-9vkkp   1/1     Running   34s  <- 모두 새로 생성!
production-app-849b867f78-b2fjx   1/1     Running   34s
production-app-849b867f78-kkdjv   1/1     Running   23s

$ curl http://172.30.1.43:30080
Hello from Production App v2.0 - UPDATED!

무중단 배포 성공! 서비스 중단 없이 v2.0으로 업데이트되었습니다.

배운 점

• 모든 Best Practice를 한 번에 적용하는 게 Production-Ready
• ConfigMap/Secret 분리로 설정 관리 용이
• Health Check + Rolling Update = 무중단 배포의 핵심
• NodePort로 외부 접근 가능 (Ingress 전 단계)

삽질 포인트

1. ConfigMap 업데이트했는데 Pod가 안 바뀌어요!

문제:

$ kubectl apply -f new-configmap.yaml
configmap/app-config configured

$ curl http://app
Hello from v1.0  <- 여전히 v1.0!

원인:

• ConfigMap/Secret을 업데이트해도 기존 Pod는 자동으로 재시작되지 않음
• 환경변수로 주입한 경우: Pod 재시작 필수
• 볼륨 마운트: 심볼릭 링크로 업데이트되지만 애플리케이션이 리로드해야 함

해결:

$ kubectl rollout restart deployment production-app -n production

2. PVC가 Pending 상태로 멈춰요!

문제:

$ kubectl get pvc
NAME           STATUS    VOLUME   CAPACITY   STORAGECLASS
pvc-hostpath   Pending

원인:

• PV와 PVC의 accessModes가 불일치
• PV의 용량이 PVC의 요청보다 작음
• StorageClass를 쓰는데 Provisioner가 없음

해결:

$ kubectl describe pvc pvc-hostpath
Events:
  Warning  ProvisioningFailed  no persistent volumes available

PV의 accessModes와 capacity를 확인하고 매칭시키세요!

3. QoS를 Guaranteed로 하고 싶은데 Burstable이 돼요!

문제:

resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
  limits:
    cpu: "200m"    # requests와 다름!
    memory: "128Mi"

원인:

• Guaranteed는 모든 컨테이너의 모든 리소스(CPU, Memory)에서 requests = limits 필요
• 하나라도 다르면 Burstable

해결:

resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
  limits:
    cpu: "100m"     # requests와 동일!
    memory: "128Mi"

4. Readiness Probe 실패인데 Pod가 안 죽어요!

이건 정상입니다!

• Liveness → Pod 재시작
• Readiness → Service Endpoints에서만 제외

Readiness 실패로 Pod를 죽이고 싶다면 Liveness Probe도 함께 설정하세요.

핵심 개념 정리

ConfigMap vs Secret

Rolling Update 전략

maxSurge=1, maxUnavailable=0
  → 새 Pod 먼저 생성 후 기존 Pod 종료
  → 리소스 오버헤드 있지만 가장 안전

maxSurge=0, maxUnavailable=1
  → 기존 Pod 종료 후 새 Pod 생성
  → 리소스 절약, 약간의 Capacity 감소

maxSurge=1, maxUnavailable=1
  → 균형잡힌 기본값

PV/PVC 관계

PV (관리자)
  ├─ hostPath: /mnt/data
  ├─ capacity: 1Gi
  └─ accessModes: ReadWriteOnce

      ⬇ Binding (1:1)

PVC (개발자)
  ├─ requests: 500Mi
  └─ accessModes: ReadWriteOnce

      ⬇ Mount

Pod
  └─ volumeMounts: /data

QoS 우선순위

리소스 압박 시 Eviction 순서:
1. BestEffort (requests/limits 없음)
2. Burstable (requests < limits)
3. Guaranteed (requests = limits) ← 최후까지 보호

Health Check 조합

# 가장 권장하는 조합
livenessProbe:   # 데드락 복구
  httpGet: /health
  initialDelaySeconds: 30

readinessProbe:  # 초기화 대기
  httpGet: /ready
  initialDelaySeconds: 5

startupProbe:    # 느린 시작 허용
  httpGet: /health
  failureThreshold: 30
  periodSeconds: 10

다음 계획 (Day 4)

Day 3에서 개별 기능들을 익혔다면, Day 4는 고급 패턴과 실전 시나리오를 다룰 예정입니다:

1. Ingress: HTTP 라우팅, 도메인 기반 라우팅, TLS 종료
2. HPA (Horizontal Pod Autoscaler): CPU 기반 자동 스케일링
3. RBAC: 역할 기반 접근 제어, ServiceAccount
4. StatefulSet: Stateful 애플리케이션 (DB, 메시지큐)
5. DaemonSet: 모든 노드에 Pod 배포 (로그 수집, 모니터링)
6. Monitoring: metrics-server, kube-ops-view로 시각화

특히 HPA와 Ingress는 Production 환경에서 거의 필수이기 때문에, Day 4의 하이라이트가 될 것 같습니다.

마무리

Day 3를 돌아보니, 단순히 "어떻게 하는가"를 넘어 "왜 이렇게 설계되었는가"를 이해하는 데 집중했던 것 같습니다.

특히 기억에 남는 것들:

• Secret의 심볼릭 링크 구조
• Rolling Update의 실시간 Pod 교체 과정
• HostPath vs Ceph의 명확한 차이
• QoS가 단순한 "Pod 죽이기"가 아니라 리소스 압박 시 보험이라는 깨달음
• ConfigMap 업데이트 후 Pod를 수동으로 재시작해야 한다는 함정

3-node 클러스터에서 직접 실습하며, 문서로만 봤을 때는 몰랐던 실제 동작을 눈으로 확인할 수 있었던 게 가장 큰 수확입니다.

Day 4에서는 더 복잡한 시나리오와 Production 환경에서의 Best Practice를 익혀보겠습니다!

3노드 클러스터 환경에서 Control Plane부터 실제 애플리케이션 배포까지

들어가며

Day 1에서 클러스터의 기본 구조를 이해했다면, Day 2는 실전이었습니다. Control Plane이 어떻게 동작하는지, Pod 간 통신이 실제로 어떻게 이루어지는지, 그리고 마침내 외부에서 접근 가능한 웹 애플리케이션을 배포하는 것까지 경험했습니다.

특히 이번 실습에서는 예상치 못한 네트워킹 문제를 직접 해결하면서, Calico CNI의 동작 원리와 Linux 네트워킹에 대해 깊이 이해할 수 있었습니다.

학습 환경

• 클러스터: 3노드 (cpu1: Master+Worker, cpu2/gpu1: Worker)
• Kubernetes: v1.31.13
• CNI: Calico (VXLAN CrossSubnet 모드)
• Pod Network: 10.244.0.0/16
• Service Network: 10.96.0.0/12

실습 내용

1. Control Plane 심화 검증

etcd: Kubernetes의 두뇌

첫 번째로 etcd가 실제로 무엇을 저장하는지 확인했습니다.

kubectl exec -n kube-system etcd-cpu1 -- sh -c \
  "ETCDCTL_API=3 etcdctl \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key \
  get /registry/ --prefix --keys-only" | head -20

출력 결과:

/registry/apiregistration.k8s.io/apiservices/v1.
/registry/apiregistration.k8s.io/apiservices/v1.admissionregistration.k8s.io
/registry/clusterrolebindings/calico-kube-controllers
/registry/deployments/calico-system/calico-kube-controllers
/registry/pods/calico-system/calico-node-ftrzj
/registry/services/endpoints/default/kubernetes
...

모든 리소스가 /registry/ 아래에 계층 구조로 저장되어 있었습니다. Deployment, Pod, Service 모두 etcd에 영구 저장되는 것을 직접 확인했습니다.

API Server: REST API 직접 호출

kubectl get --raw /version

{
  "major": "1",
  "minor": "31",
  "gitVersion": "v1.31.13"
}

API Server는 80개의 API 리소스를 제공하고 있었습니다. kubectl이 실제로는 이 REST API를 호출하는 클라이언트에 불과하다는 것을 깨달았습니다.

Controller Manager와 Scheduler 검증

Deployment를 생성하면 Controller Manager가 ReplicaSet을 생성하고, ReplicaSet Controller가 Pod를 생성하고, Scheduler가 노드를 선택하는 전체 체인을 추적했습니다.

kubectl get events --sort-by='.lastTimestamp' | grep test-controller

Successfully assigned default/test-controller-xxx to cpu2
Pulling image "nginx:alpine"
Created container nginx
Started container nginx

이 과정이 1초도 안 걸렸습니다. 각 컴포넌트가 얼마나 빠르게 동작하는지 놀라웠습니다.

2. VXLAN 네트워킹의 진실

가장 큰 오해: "Pod 통신은 Layer 2?"

처음에는 "Pod 통신이 Layer 2라서 UDP로 감싸야 한다"고 완전히 잘못 이해했습니다. 이 오해를 바로잡는 과정이 Day 2의 가장 큰 학습이었습니다.

핵심 질문:

"BGP로 라우터 정보 넣어서 미리 CIDR 땡겨오게 설정해두면 VXLAN을 사용하지 않아도 되는 것처럼 설명했는데 그게 맞아? Layer 2라서 UDP로 감아야 된다며?"

답변:

Pod 통신은 원래 Layer 3 (IP 기반)입니다!

Pod는 각자 고유한 IP 주소를 가지고 있으며, IP 패킷으로 통신합니다. VXLAN은 "필수"가 아니라 "특정 상황에서의 해결책"입니다.

Calico의 3가지 네트워킹 모드 비교

1. BGP Mode (VXLAN 없음)

[Pod A: 10.244.1.10]
    ↓ (IP routing)
[Node1: 172.30.1.43]
    ↓ (BGP 라우팅 정보 교환)
[Node2: 172.30.1.80]
    ↓ (IP routing)
[Pod B: 10.244.2.20]

• 조건: 노드 간 L3 라우팅 가능 (물리 라우터가 BGP 지원)
• 장점: VXLAN overhead 없음, 성능 최고
• 단점: 물리 네트워크가 BGP를 지원해야 함
• MTU: 1500 (overhead 없음)

2. VXLAN Mode (순수 overlay)

[Pod A: 10.244.1.10]
    ↓ (IP packet)
[VXLAN 캡슐화: UDP 4789]
    ↓ (Outer IP: 172.30.1.43 → 172.30.1.80)
[물리 네트워크]
    ↓
[VXLAN 역캡슐화]
    ↓
[Pod B: 10.244.2.20]

• 조건: BGP 불가능 (클라우드 VPC, 제한된 네트워크)
• 장점: 물리 네트워크와 무관하게 동작
• 단점: 50 bytes overhead, 성능 저하
• MTU: 1450

3. VXLAN CrossSubnet Mode (우리 클러스터!)

같은 서브넷:
[Pod A] → [Direct IP routing] → [Pod B]  (MTU 1500)

다른 서브넷:
[Pod A] → [VXLAN tunnel] → [Pod B]  (MTU 1450)

• 조건: 일부 노드는 같은 서브넷, 일부는 다른 서브넷
• 장점: 최적의 성능 (같은 서브넷) + 유연성 (다른 서브넷)
• 우리 환경: 모든 노드가 172.30.1.0/24 → 실제로는 Direct routing만 사용!

VXLAN은 언제 필요한가?

VXLAN이 필요한 경우:

1. 클라우드 환경 (AWS VPC, GCP, Azure)에서 BGP 불가
2. 물리 라우터가 BGP를 지원하지 않음
3. 보안 정책으로 BGP peer 설정 불가
4. 서로 다른 데이터센터/서브넷을 연결

VXLAN이 불필요한 경우:

1. 물리 라우터가 BGP 지원 (Calico BGP mode 사용)
2. 같은 L2 네트워크 내 (Calico CrossSubnet의 direct routing)
3. 노드가 적고 static route로 충분

우리 클러스터는?

• 모든 노드: 172.30.1.0/24 (같은 서브넷)
• Calico 모드: VXLAN CrossSubnet
• 실제 동작: Direct IP routing (VXLAN 미사용)
• VXLAN 인터페이스: 존재하지만 대기 상태

VXLAN 실제 구성 확인

ip -d link show type vxlan

20: vxlan.calico: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1450
    vxlan id 4096 local 172.30.1.43 dev enp2s0 srcport 0 0 dstport 4789

• VNI: 4096 (Virtual Network Identifier)
• UDP Port: 4789 (VXLAN 표준 포트)
• MTU: 1450 = 1500(물리) - 50(VXLAN overhead)
• 상태: 인터페이스는 존재하지만 실제로는 사용 안 됨

MTU가 1450인 이유

VXLAN을 사용할 때의 헤더 구조:

[Outer Ethernet: 14 bytes]
[Outer IP: 20 bytes]
[UDP: 8 bytes]
[VXLAN: 8 bytes]
[Inner Ethernet: 14 bytes]
[Inner IP: 20 bytes]
[Payload]

Total Overhead: 14+20+8+8 = 50 bytes

물리 인터페이스 MTU가 1500이므로:

• VXLAN MTU: 1500 - 50 = 1450
• Fragmentation 방지

우리 클러스터는 Direct routing을 사용하므로 실제로는 overhead가 없지만, VXLAN으로 전환 시를 대비해 1450으로 설정되어 있습니다.

CrossSubnet 모드 동작 확인

우리 클러스터는 모든 노드가 172.30.1.0/24 서브넷에 있어서, VXLAN 없이 직접 라우팅을 사용합니다:

ip route | grep 10.244

10.244.5.192/26 via 172.30.1.38 dev enp2s0 proto 80 onlink     # gpu1으로 가는 경로
10.244.102.128/26 via 172.30.1.80 dev enp2s0 proto 80 onlink   # cpu2로 가는 경로

해석:

• via 172.30.1.38: gpu1 노드 IP를 next-hop으로 사용
• dev enp2s0: 물리 Ethernet 인터페이스 사용 (VXLAN 터널 아님!)
• proto 80: Calico가 설정한 라우팅 (BIRD BGP)
• onlink: Gateway가 직접 연결된 링크에 있음

확인 방법: VXLAN이 실제로 사용되는지?

# VXLAN 인터페이스의 트래픽 카운터 확인
ip -s link show vxlan.calico

20: vxlan.calico: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1450
    RX: bytes  packets  errors  dropped
        0       0        0       0      # ← 수신 패킷 0
    TX: bytes  packets  errors  dropped
        0       0        0       0      # ← 송신 패킷 0

결과: VXLAN 인터페이스를 통한 트래픽이 전혀 없음! Direct routing만 사용되고 있습니다.

Layer 2 vs Layer 3: 최종 정리

오해:

• "Pod끼리 통신하려면 Layer 2 연결이 필요하다"
• "그래서 VXLAN으로 Layer 2를 overlay해야 한다"

진실:

• Pod 통신은 순수 Layer 3 (IP routing)
• Pod는 서로 다른 IP 서브넷에 있어도 됨
• 각 노드의 Calico가 IP 라우팅 정보 교환 (BGP)
• VXLAN은 BGP가 불가능할 때의 "우회 방법"

비유:

• BGP Mode: 도시 간 고속도로 (직접 연결, 빠름)
• VXLAN Mode: 지하 터널 (우회, 느리지만 어디든 갈 수 있음)
• CrossSubnet: 같은 도시는 고속도로, 다른 도시는 터널

3. Pod 네트워킹 구조

veth pair 이해하기 (그리고 헷갈렸던 인터페이스 번호)

각 Pod는 완전히 격리된 network namespace를 가지며, veth pair라는 가상 이더넷 케이블로 호스트와 연결됩니다.

Pod 내부에서 확인:

kubectl exec nettest -- ip addr show

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536
    inet 127.0.0.1/8 scope host lo

2: eth0@if22: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1450
    inet 10.244.102.137/32 scope global eth0

호스트에서 확인:

ip link show | grep cali

22: calie107cf6613e@if2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1450 qdisc noqueue
    link-netns cni-2594a3d8-7097-90e6-9db2-a3aaef8edf77

인터페이스 번호의 혼동

처음에는 이렇게 이해했습니다 (잘못됨):

• Pod의 eth0@if22 → "if22는 22번 인터페이스를 의미하니까... 호스트도 22번이겠지?"
• 호스트의 22: cali...@if2 → "22번 인터페이스 맞네! 근데 @if2는 뭐지?"

이건 완전히 틀렸습니다!

올바른 이해:

• Pod 입장: 2: eth0@if22

  • 내 인터페이스 번호는 2번 (eth0)
  • 상대방(호스트)의 인터페이스 번호는 22번 (@if22)

• Host 입장: 22: calie107cf6613e@if2

  • 내 인터페이스 번호는 22번 (calie107cf6613e)
  • 상대방(Pod)의 인터페이스 번호는 2번 (@if2)

@ifN의 진정한 의미: "저 너머 네임스페이스에 있는 상대방의 인터페이스 번호"

veth pair 시각화

┌─────────────────────────────────┐       ┌──────────────────────────┐
│      Pod nettest Namespace   │       │     Host Namespace       │
│                              │       │                          │
│  1: lo (127.0.0.1)           │       │  1: lo                   │
│  2: eth0@if22 ←────────────────┼───────┼─→ 22: cali...@if2        │
│     10.244.102.137/32        │       │     (no IP)              │
│                              │       │                          │
│     ↓                        │       │     ↓                    │
│  default via 169.254.1.1     │       │  10.244.102.137 dev cali │
│                              │       │  (proxy ARP)             │
└─────────────────────────────────┘       └──────────────────────────┘

veth pair 특징:

1. 항상 쌍으로 존재 (한쪽만 있을 수 없음)
2. 한쪽 끝이 다른 네임스페이스에 있음
3. 호스트 측 인터페이스는 IP가 없음 (Layer 2 bridge 역할)
4. Pod 측 인터페이스는 Pod IP 할당

실제 통신 흐름

Pod에서 외부로 패킷을 보낼 때:

1. Pod nettest (10.244.102.137)
   → "10.109.60.89로 가고 싶어!"

2. Pod의 라우팅 테이블 확인
   → default via 169.254.1.1 dev eth0
   → eth0@if22로 전송

3. veth pair 통과
   → 호스트의 22번 인터페이스 (calie107cf6613e)로 도착

4. 호스트 라우팅 테이블 확인
   → 10.109.60.89는 Service IP → iptables 규칙 적용
   → DNAT: 10.109.60.89 → 10.244.184.84 (실제 Pod IP)

5. 호스트 라우팅 다시 확인
   → 10.244.184.84는 cpu1 노드에 있음
   → 같은 노드이므로 다른 veth pair로 전달

6. 목적지 Pod의 veth pair 통과
   → nginx Pod에 도달!

중요한 발견: @ifN 표기는 반대편 네임스페이스의 인터페이스 번호입니다!

Pod 라우팅

kubectl exec nettest -- ip route

default via 169.254.1.1 dev eth0
169.254.1.1 dev eth0 scope link

Calico는 모든 Pod에 동일한 gateway (169.254.1.1)를 할당하지만, 실제 라우팅은 호스트의 veth pair에서 처리합니다.

4. Service와 Endpoints: 로드밸런싱의 비밀

ClusterIP Service 생성

kubectl create deployment nginx-test --image=nginx:alpine --replicas=3
kubectl expose deployment nginx-test --port=80 --type=ClusterIP

NAME         TYPE        CLUSTER-IP     PORT(S)
nginx-test   ClusterIP   10.109.60.89   80/TCP

Endpoints 자동 관리

kubectl get endpoints nginx-test -o yaml

subsets:
- addresses:
  - ip: 10.244.102.138
    nodeName: cpu2
  - ip: 10.244.184.84
    nodeName: cpu1
  - ip: 10.244.5.203
    nodeName: gpu1
  ports:
  - port: 80

Service의 selector (app=nginx-test)와 일치하는 모든 Pod IP가 자동으로 Endpoints에 추가됩니다!

kube-proxy의 iptables 마법

iptables-save | grep nginx-test

-A KUBE-SERVICES -d 10.109.60.89/32 ... -j KUBE-SVC-W67AXLFK7VEUVN6G
-A KUBE-SVC-W67AXLFK7VEUVN6G ... --probability 0.33333 -j KUBE-SEP-SOT6P6LQ532M4OEI
-A KUBE-SVC-W67AXLFK7VEUVN6G ... --probability 0.50000 -j KUBE-SEP-3DGSCWRDZYIA2HSW
-A KUBE-SEP-SOT6P6LQ532M4OEI ... -j DNAT --to-destination 10.244.102.138:80
-A KUBE-SEP-3DGSCWRDZYIA2HSW ... -j DNAT --to-destination 10.244.184.84:80

동작 원리:

1. Service IP (10.109.60.89)로 들어오는 트래픽을 캡처
2. 확률적으로 분산 (33%, 50%, 나머지 17%)
3. DNAT로 실제 Pod IP:Port로 변환

statistic random 모듈을 사용한 간단하지만 효과적인 로드밸런싱입니다!

5. 첫 웹 애플리케이션 배포

ConfigMap으로 설정 분리

kubectl create configmap webapp-config --from-literal=index.html='
<!DOCTYPE html>
<html>
<head>
    <title>Kubernetes Web App</title>
</head>
<body>
    <h1>Welcome to Kubernetes!</h1>
    <p>This page is served from a ConfigMap</p>
</body>
</html>
'

Deployment에 ConfigMap 마운트

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  replicas: 2
  selector:
    matchLabels:
      app: webapp
  template:
    spec:
      containers:
      - name: nginx
        image: nginx:alpine
        volumeMounts:
        - name: html-volume
          mountPath: /usr/share/nginx/html
      volumes:
      - name: html-volume
        configMap:
          name: webapp-config

ConfigMap이 Volume으로 마운트되어 nginx가 해당 HTML을 서비스합니다!

NodePort로 외부 노출

kubectl expose deployment webapp --type=NodePort --port=80

NAME     TYPE       CLUSTER-IP      PORT(S)
webapp   NodePort   10.103.193.83   80:32065/TCP

모든 노드의 32065 포트로 접근 가능합니다:

curl http://172.30.1.43:32065

<h1>Welcome to Kubernetes!</h1>
<p>This page is served from a ConfigMap</p>

성공! 처음으로 외부에서 접근 가능한 웹 애플리케이션을 배포했습니다.

6. Volume: 컨테이너 간 데이터 공유

EmptyDir 실습

apiVersion: v1
kind: Pod
metadata:
  name: emptydir-test
spec:
  containers:
  - name: writer
    image: busybox:1.28
    command: ['sh', '-c', 'echo "Hello from EmptyDir" > /data/message.txt && sleep 3600']
    volumeMounts:
    - name: shared-data
      mountPath: /data
  - name: reader
    image: busybox:1.28
    command: ['sh', '-c', 'sleep 10 && cat /data/message.txt && sleep 3600']
    volumeMounts:
    - name: shared-data
      mountPath: /data
  volumes:
  - name: shared-data
    emptyDir: {}

kubectl logs emptydir-test -c reader

Hello from EmptyDir

writer 컨테이너가 작성한 파일을 reader 컨테이너가 성공적으로 읽었습니다. EmptyDir는 같은 Pod 내 컨테이너 간 데이터 공유에 완벽합니다!

배운 점

1. Pod 통신은 Layer 3이다 (가장 큰 깨달음!)

가장 큰 오해를 바로잡았습니다.

처음에는 "Pod 통신은 Layer 2이고, 물리적으로 연결되지 않은 노드 간 통신을 위해 VXLAN으로 Layer 2를 터널링해야 한다"고 잘못 생각했습니다.

실제로는:

• Pod 통신은 순수 Layer 3 (IP routing) 기반
• 각 Pod는 고유한 IP 주소를 가지며, 서로 다른 서브넷에 있어도 라우팅으로 통신 가능
• VXLAN은 BGP 라우팅이 불가능할 때의 대안일 뿐

실전 적용:

• BGP 가능한 환경: Calico BGP Mode 사용 (최고 성능)
• 클라우드/제한된 네트워크: VXLAN Mode
• 하이브리드 환경: CrossSubnet Mode (우리 클러스터)

우리 클러스터는 모든 노드가 같은 서브넷(172.30.1.0/24)에 있어서 VXLAN을 전혀 사용하지 않고 enp2s0 물리 인터페이스로 직접 라우팅합니다. ip -s link show vxlan.calico로 확인하면 패킷이 0개!

이 이해를 바탕으로 이제 네트워크 문제가 생기면:

1. 먼저 라우팅 테이블 확인 (ip route | grep 10.244)
2. Calico가 올바른 인터페이스 사용 중인지 확인 (IP_AUTODETECTION_METHOD)
3. BIRD BGP 테이블과 kernel 라우팅 테이블 비교

2. @ifN 표기의 진정한 의미

veth pair를 이해하는 데 한참 헤맸습니다.

• Pod: 2: eth0@if22 → "내 인터페이스는 2번, 상대방은 22번"
• Host: 22: cali...@if2 → "내 인터페이스는 22번, 상대방은 2번"

@ifN은 "상대편 네임스페이스의 인터페이스 번호"

이 개념을 이해하니 Pod 네트워킹 디버깅이 훨씬 쉬워졌습니다. veth pair의 한쪽 끝을 찾으면 반대편도 바로 찾을 수 있습니다.

3. VXLAN은 "선택"이지 "필수"가 아니다

VXLAN의 역할 재정의:

• ❌ "Pod 통신은 항상 VXLAN을 통해 이루어진다"
• ✅ "VXLAN은 BGP 라우팅이 불가능할 때 사용하는 우회 방법"

성능 고려사항:

• Direct routing: MTU 1500, overhead 없음, 최고 성능
• VXLAN: MTU 1450, 50 bytes overhead, 약간의 성능 저하

프로덕션 환경 선택 가이드:

• 온프레미스 + BGP 가능 → Calico BGP Mode
• AWS/GCP/Azure → VXLAN Mode (또는 Cloud provider CNI)
• 멀티 데이터센터 → VXLAN CrossSubnet Mode

4. Kubernetes는 이벤트 기반 시스템

Control Plane의 각 컴포넌트는:

• API Server를 watch
• 변경사항 감지 시 즉시 반응
• 선언적 상태(desired state)를 실제 상태(current state)로 수렴

이 모델이 Kubernetes의 자동화와 자가 치유를 가능하게 합니다.

Deployment 하나 생성하면:

1. API Server → etcd 저장
2. Deployment Controller → ReplicaSet 생성 감지
3. ReplicaSet Controller → Pod 생성 요청
4. Scheduler → 노드 선택
5. kubelet → 컨테이너 실행

전체 과정이 1초 미만! 각 컴포넌트가 독립적으로 자기 역할만 수행하는 아름다운 설계입니다.

5. Service는 단순히 iptables 규칙이다

고급 로드밸런서가 있는 줄 알았는데, kube-proxy가 생성한 iptables 규칙만으로 구현되어 있었습니다.

-A KUBE-SVC-xxx ... --probability 0.33333 -j KUBE-SEP-A
-A KUBE-SVC-xxx ... --probability 0.50000 -j KUBE-SEP-B
-A KUBE-SVC-xxx ... -j KUBE-SEP-C
-A KUBE-SEP-A ... -j DNAT --to-destination 10.244.102.138:80

statistic random 모듈로 확률적 분산. 간단하지만 효과적입니다!

이제 Service 트래픽이 어디로 가는지 추적할 수 있습니다:

iptables-save | grep <service-name>

6. ConfigMap의 강력함

코드와 설정을 완전히 분리할 수 있습니다. 같은 이미지로 dev/staging/prod 환경을 다르게 구성할 수 있습니다.

더 나아가:

• Volume으로 마운트 → 파일 형태로 사용
• 환경변수로 주입 → 애플리케이션 설정
• ConfigMap 변경 → Pod 재시작 없이 반영 (Volume 마운트 시)

7. Network Namespace와 Linux 네트워킹의 힘

각 Pod는 완전히 격리된 네트워크 환경을 가지며, veth pair가 호스트와의 유일한 연결 고리입니다.

Linux 네트워킹 스택의 놀라운 활용:

• Network Namespace: Pod 격리
• veth pair: 네임스페이스 간 연결
• Routing: Layer 3 통신
• iptables: Service 로드밸런싱, SNAT/DNAT
• VXLAN: 필요 시 overlay network

Kubernetes는 새로운 기술을 발명한 게 아니라, 기존 Linux 커널 기능을 정교하게 조합한 것입니다. 이 점이 매우 인상적이었습니다.

삽질 포인트

대형 사고: 크로스 노드 Pod 통신 실패

증상

같은 노드의 Pod끼리는 통신이 되는데, 다른 노드의 Pod와는 통신이 안 되는 현상 발생:

kubectl exec nettest -- ping 10.244.184.84

--- 10.244.184.84 ping statistics ---
2 packets transmitted, 0 received, 100% packet loss

원인 발견 과정

1. nginx가 정상 동작하는지 확인

   kubectl exec nginx-pod -- netstat -tlnp

   → 80 포트 정상 listening ✅

2. 노드 간 연결 확인

   ping 172.30.1.80  # cpu2

   → 노드 간 ping 정상 ✅

3. 라우팅 테이블 확인

   ip route | grep 10.244

   → cpu2, gpu1로 가는 라우팅 규칙이 없음! ❌

4. Calico 로그 확인

   kubectl logs -n calico-system calico-node-vd4ls --tail=50

   Interface down, will retry if it goes up. ifaceName="wlp3s0"

범인 발견! Calico가 WiFi 인터페이스 (wlp3s0)를 사용하려다 실패하고 있었습니다.

해결 방법

Calico가 Ethernet 인터페이스 (enp2s0)를 사용하도록 설정:

kubectl set env daemonset/calico-node -n calico-system \
  IP_AUTODETECTION_METHOD=interface=enp.*

cpu1과 gpu1의 calico-node Pod를 재시작:

kubectl delete pod -n calico-system calico-node-vd4ls  # cpu1
kubectl delete pod -n calico-system calico-node-wnwwt  # gpu1

재시작 후 라우팅 확인:

ip route | grep 10.244

10.244.5.192/26 via 172.30.1.38 dev enp2s0 proto 80 onlink     # gpu1 ✅
10.244.102.128/26 via 172.30.1.80 dev enp2s0 proto 80 onlink   # cpu2 ✅

성공! enp2s0 인터페이스를 통해 라우팅되고 있습니다.

교훈

1. IP_AUTODETECTION_METHOD=first-found는 위험하다

   • 노드에 여러 네트워크 인터페이스가 있으면 예상치 못한 인터페이스 선택 가능
   • 명시적으로 interface=enp.* 또는 can-reach=<IP> 사용 권장

2. Calico 로그는 디버깅의 보물창고

   • Felix가 라우팅을 추가하지 못하는 이유가 명확히 나옴
   • kubectl logs -n calico-system calico-node-xxx는 필수

3. BIRD BGP 테이블과 kernel 라우팅 테이블은 다르다

   • BIRD는 올바른 라우팅 정보를 가지고 있었지만
   • Felix가 kernel에 추가하지 못했음
   • kubectl exec -n calico-system calico-node-xxx -- birdcl show route로 확인 가능

4. DaemonSet 업데이트가 모든 Pod를 재시작하지 않을 수 있다

   • env 변경 후 수동으로 Pod 삭제 필요했음
   • kubectl rollout status로 확인

기타 발견 사항

cpu2 노드 네트워크 인터페이스 변경

WiFi에서 유선(Ethernet)으로 인터넷 연결을 변경하면서 네트워크 인터페이스가 바뀌었습니다.

변경 내역:

• 인터페이스: wlp3s0 (WiFi) → enp2s0 (Ethernet)
• IP: 172.30.1.34 → 172.30.1.80 (나중에 같은 IP로 맞춤)

IP는 동일하게 설정했지만, 네트워크 인터페이스가 달라지면서 Calico가 올바른 인터페이스를 찾지 못하는 문제가 발생했습니다. 이것이 바로 IP_AUTODETECTION_METHOD=first-found의 위험성입니다.

교훈:

• 네트워크 연결 방식을 변경할 때는 Calico 설정도 함께 확인
• IP_AUTODETECTION_METHOD를 명시적으로 설정 (interface=enp.*)
• Static IP 설정으로 일관성 유지

veth pair 인터페이스 번호 혼동

처음에는 Pod의 eth0@if22가 호스트의 22번 인터페이스를 의미하는 줄 알았으나, 실제로는:

• Pod: eth0@if22 → 호스트의 22번 인터페이스와 연결됨
• Host: 22: cali...@if2 → Pod의 2번 인터페이스(eth0)와 연결됨

@ifN은 상대방 쪽의 인터페이스 번호입니다!

다음 계획 (Day 3)

Day 2에서 기본적인 애플리케이션 배포까지 완료했으니, Day 3에서는 운영 시나리오를 다룰 계획입니다:

1. Secret과 민감 정보 관리

• ConfigMap vs Secret 차이
• Secret을 환경변수 및 Volume으로 마운트
• base64 인코딩의 한계와 주의사항

2. Rolling Update와 무중단 배포

• Deployment의 롤링 업데이트 전략
• maxSurge와 maxUnavailable 설정
• rollout 상태 확인 및 rollback

3. Persistent Volume (PV/PVC)

• HostPath를 사용한 영구 저장소
• PV/PVC 라이프사이클
• StorageClass 이해

4. Resource Limits과 HPA

• CPU/Memory requests와 limits
• Pod QoS 클래스 (Guaranteed, Burstable, BestEffort)
• Horizontal Pod Autoscaler 설정

5. Health Check (Liveness/Readiness Probe)

• Liveness Probe: 컨테이너 재시작
• Readiness Probe: Service Endpoints 제어
• Startup Probe: 느린 시작 애플리케이션 처리

마무리

Day 2는 Day 1보다 훨씬 실전적이었습니다. Control Plane의 동작 원리를 깊이 이해하고, 네트워킹 문제를 직접 해결하면서 Calico와 Linux 네트워킹에 대한 자신감이 생겼습니다.

특히 "Service IP로 접근이 안 된다"는 문제를 만났을 때, 체계적으로 디버깅하여 원인을 찾고 해결한 경험이 가장 값졌습니다. 이제 클러스터에 문제가 생겨도 당황하지 않고 로그와 상태를 확인하며 접근할 수 있을 것 같습니다.

Day 3에서는 실제 프로덕션 환경에서 필요한 운영 기능들을 다뤄볼 예정입니다. Rolling Update, Health Check, Resource Limits 등 안정적인 서비스 운영을 위한 필수 요소들을 학습하겠습니다!

안녕하세요! 저는 최근 온프레미스 환경에서 Kubernetes 클러스터를 직접 구축하고 운영하면서 많은 것을 배우고 있습니다. 오늘은 그 여정의 첫 번째 날, "클러스터 기초와 아키텍처 이해"에 대해 이야기해보려 합니다.

처음 Kubernetes를 접할 때 가장 막막했던 부분이 "도대체 이 많은 컴포넌트들이 뭐하는 건데?"였습니다. Pod, Service, Deployment, etcd, CoreDNS... 용어만 들어도 머리가 복잡해지더라고요.

하지만 실제로 클러스터를 직접 만들고, 각 컴포넌트가 어떻게 동작하는지 하나씩 확인하면서 "아, 이래서 이렇게 설계했구나!" 하는 순간들이 있었습니다. 오늘 그 경험을 공유하고자 합니다.

목차

1. 우리 클러스터 소개
2. 클러스터의 심장: Control Plane
3. Pod와 네임스페이스의 비밀
4. 네트워킹의 마법: CoreDNS
5. 배운 것과 다음 계획

1. 클러스터 소개

클러스터 구성

저는 총 3개의 노드로 클러스터를 구성했습니다:

$ kubectl get nodes -o wide

NAME   STATUS   ROLES           AGE   VERSION    INTERNAL-IP   OS-IMAGE             CONTAINER-RUNTIME
cpu1   Ready    control-plane   46h   v1.31.13   172.30.1.43   Ubuntu 22.04.5 LTS   containerd://1.7.28
cpu2   Ready    <none>          17h   v1.31.13   172.30.1.80   Ubuntu 22.04.5 LTS   containerd://1.7.28
gpu1   Ready    <none>          17h   v1.31.13   172.30.1.38   Ubuntu 22.04.5 LTS   containerd://1.7.28

여기서 포인트!

보통 Master 노드는 Control Plane 컴포넌트만 실행하고 일반 Pod는 실행하지 않습니다. 하지만 저는 리소스 활용을 위해 cpu1의 taint를 제거했습니다.

$ kubectl describe node cpu1 | grep Taints
Taints:             <none>

<none>이 보이시나요? 이제 cpu1에도 일반 애플리케이션 Pod를 배포할 수 있습니다!

클러스터 정보 확인

가장 먼저 해본 명령어는 이거였습니다:

$ kubectl cluster-info

Kubernetes control plane is running at https://172.30.1.43:6443
CoreDNS is running at https://172.30.1.43:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

간단하지만 중요한 정보:

• API Server 주소: https://172.30.1.43:6443 - 모든 kubectl 명령어가 여기로 갑니다
• CoreDNS: 클러스터 내부 DNS 서비스 - Pod들이 서로를 찾을 수 있게 해줍니다

2. 클러스터의 심장: Control Plane

Control Plane이 뭐길래?

Kubernetes 클러스터를 사람에 비유하면, Control Plane은 "뇌"입니다. 모든 결정이 여기서 이루어지죠.

Control Plane은 4개의 핵심 컴포넌트로 구성됩니다:

$ kubectl get pods -n kube-system -o wide | grep cpu1

etcd-cpu1                      1/1     Running   172.30.1.43   cpu1
kube-apiserver-cpu1            1/1     Running   172.30.1.43   cpu1
kube-controller-manager-cpu1   1/1     Running   172.30.1.43   cpu1
kube-scheduler-cpu1            1/1     Running   172.30.1.43   cpu1

모두 cpu1 (마스터 노드)에서 실행되고 있습니다. 각각의 역할을 알아봅시다:

1. etcd - "기억하는 자"

$ kubectl get componentstatuses

NAME                 STATUS    MESSAGE   ERROR
etcd-0               Healthy   ok

• 역할: 클러스터의 모든 데이터를 저장하는 key-value 저장소
• 저장하는 것: Pod 정보, Service 설정, ConfigMap, Secret 등 모든 것!
• 중요성: etcd가 죽으면 클러스터 전체가 멈춥니다 😱

팁: 프로덕션 환경에서는 etcd를 반드시 백업하세요. 이게 바로 클러스터의 "두뇌 백업"입니다.

2. kube-apiserver - "중앙 통제소"

• 역할: 모든 요청을 받아서 처리하는 REST API 서버
• 포트: 6443 (HTTPS)
• 특징:
  • kubectl 명령어가 통신하는 대상
  • 인증, 인가, Admission Control 수행
  • etcd와 직접 통신하는 유일한 컴포넌트

내가 깨달은 것:

kubectl get pods
      ↓
API Server (172.30.1.43:6443)
      ↓
etcd에서 Pod 정보 조회
      ↓
결과 반환

모든 작업이 API Server를 거친다는 게 핵심입니다!

3. kube-controller-manager - "자동화 담당자"

• 역할: 클러스터의 "바라는 상태"를 유지
• 예시:
  • Deployment가 "Pod 3개 실행"을 원하면 → 계속 3개 유지
  • Node가 죽으면 → 해당 노드의 Pod를 다른 노드로 재생성
  • Service Endpoint 자동 관리

실제로 본 예시:

제가 테스트로 Pod를 하나 삭제했을 때:

$ kubectl delete pod coredns-76b86bc878-5v86m -n kube-system
pod "coredns-76b86bc878-5v86m" deleted

$ kubectl get pods -n kube-system | grep coredns
coredns-76b86bc878-5v86m   1/1     Running   0          5s  <- 자동 재생성됨!
coredns-76b86bc878-pnpjq   1/1     Running   0          46h

5초 만에 새 Pod가 생성되었습니다. 이게 바로 Controller Manager의 마법입니다! ✨

4. kube-scheduler - "배치 전문가"

• 역할: 새로운 Pod를 "어느 노드에 배치할지" 결정
• 고려 사항:
  • 노드의 여유 리소스 (CPU, 메모리)
  • nodeSelector, affinity 규칙
  • Taints와 Tolerations

재미있는 발견:

$ kubectl get pods -A -o wide | grep -c cpu1
12

$ kubectl get pods -A -o wide | grep -c cpu2
3

cpu1에 Pod가 더 많은 이유? Control Plane Pod 4개 + CoreDNS 2개 + 기타 시스템 Pod들이 모두 cpu1에 있기 때문입니다!

3. Pod와 네임스페이스의 비밀

총 19개의 Pod가 돌아가는 중

$ kubectl get pods -A | wc -l
20  # 헤더 포함

처음엔 "19개나?"라고 놀랐습니다. 하지만 알고 보니 모두 필요한 시스템 Pod들이었어요.

Pod 종류별 분류

1. Control Plane Pod (4개) - Static Pod

etcd-cpu1
kube-apiserver-cpu1
kube-controller-manager-cpu1
kube-scheduler-cpu1

여기서 발견! 이들은 /etc/kubernetes/manifests/에 YAML 파일로 정의되어 있습니다:

$ ls /etc/kubernetes/manifests/
etcd.yaml  kube-apiserver.yaml  kube-controller-manager.yaml  kube-scheduler.yaml

kubelet이 이 디렉토리를 감시하다가 파일이 있으면 자동으로 Pod를 실행합니다. API Server가 없어도 실행된다는 점이 신기했어요!

2. DaemonSet Pod (9개) - 각 노드마다 1개씩

$ kubectl get daemonset -A

NAMESPACE       NAME              DESIRED   CURRENT   READY
calico-system   calico-node       3         3         3
calico-system   csi-node-driver   3         3         3
kube-system     kube-proxy        3         3         3

각 노드마다 정확히 1개씩! 이게 DaemonSet의 핵심입니다.

• calico-node: 네트워크 에이전트
• kube-proxy: 서비스 라우팅
• csi-node-driver: 스토리지 드라이버

3. Deployment Pod (6개) - 복제 가능

$ kubectl get deployment -A

NAMESPACE         NAME                      READY   UP-TO-DATE   AVAILABLE
calico-system     calico-kube-controllers   1/1     1            1
calico-system     calico-typha              2/2     2            2
kube-system       coredns                   2/2     2            2
tigera-operator   tigera-operator           1/1     1            1

CoreDNS가 2개인 이유? 고가용성(HA)을 위해서입니다. 하나가 죽어도 다른 하나가 서비스를 계속합니다!

네임스페이스는 "방"

$ kubectl get namespaces

NAME              STATUS   AGE
default           Active   46h  <- 기본 네임스페이스
kube-system       Active   46h  <- Kubernetes 시스템
calico-system     Active   46h  <- Calico 네트워크
tigera-operator   Active   46h  <- Calico 운영자
kube-public       Active   46h  <- 공개 리소스
kube-node-lease   Active   46h  <- 노드 하트비트

네임스페이스를 "아파트의 각 집"으로 생각하면 이해하기 쉽습니다:

• 논리적으로 격리됨
• 각자 독립적인 리소스 관리
• 하지만 필요하면 서로 통신 가능

실용 팁:

# 특정 네임스페이스 조회
$ kubectl get pods -n kube-system

# 모든 네임스페이스 조회
$ kubectl get pods -A

# 기본 네임스페이스 변경 (매번 -n 안 써도 됨)
$ kubectl config set-context --current --namespace=kube-system

4. 네트워킹의 마법: CoreDNS

3가지 네트워크가 공존한다

처음 Pod IP를 봤을 때 혼란스러웠습니다:

$ kubectl get pods -A -o wide

NAMESPACE     NAME                  IP               NODE
kube-system   coredns-...           10.244.184.81    cpu1   <- Pod IP
kube-system   kube-proxy-...        172.30.1.43      cpu1   <- Node IP

왜 IP가 다른가요?

우리 클러스터에는 3가지 네트워크가 있습니다:

1. Node Network: 172.30.1.0/24
   - 실제 서버들의 IP
   - 예: 172.30.1.43 (cpu1)

2. Pod Network: 10.244.0.0/16
   - Calico가 할당하는 Pod 전용 IP
   - 예: 10.244.184.81 (coredns)

3. Service Network: 10.96.0.0/12
   - 가상 IP (실제로는 존재하지 않음!)
   - 예: 10.96.0.10 (CoreDNS Service)

Calico 네트워크 확인:

$ kubectl get ippool

spec:
  cidr: 10.244.0.0/16
  blockSize: 26
  vxlanMode: CrossSubnet
  natOutgoing: true

핵심 설정:

• vxlanMode: CrossSubnet - 같은 서브넷은 직접, 다른 서브넷은 VXLAN 터널 사용
• blockSize: 26 - 각 노드에 /26 블록 할당 (62개 IP 사용 가능)

DNS 테스트 - 드디어 성공!

가장 신나는 순간이었습니다. DNS가 정말 작동하는지 직접 테스트했어요:

$ kubectl run test-dns --image=busybox:1.28 --rm -i --restart=Never -- sh -c "
  nslookup kubernetes.default &&
  nslookup google.com
"

결과:

Server:    10.96.0.10
Address 1: 10.96.0.10

Name:      kubernetes.default
Address 1: 10.96.0.1 kubernetes.default.svc.cluster.local

Name:      google.com
Address 1: 142.250.206.238

✅ 성공!

무슨 일이 일어난 걸까요?

1. Pod 생성됨
   └─ /etc/resolv.conf에 nameserver 10.96.0.10 자동 설정

2. "kubernetes.default" 조회 요청
   └─ CoreDNS (10.96.0.10)가 받음
   └─ "kubernetes" Service를 찾아서 10.96.0.1 반환

3. "google.com" 조회 요청
   └─ CoreDNS가 받음
   └─ 클러스터 내부에 없으니 상위 DNS (168.126.63.1)로 포워딩
   └─ Google IP 반환

DNS Search Domain의 마법:

Pod의 /etc/resolv.conf를 보면:

nameserver 10.96.0.10
search default.svc.cluster.local svc.cluster.local cluster.local

이 설정 덕분에:

• nginx → nginx.default.svc.cluster.local 자동 확장
• kube-dns.kube-system → kube-dns.kube-system.svc.cluster.local 자동 확장

실용 예시:

같은 네임스페이스의 서비스 호출:

curl nginx         # ✅ 작동
curl nginx:80      # ✅ 작동

다른 네임스페이스의 서비스 호출:

curl nginx.default              # ✅ 작동
curl nginx.default.svc          # ✅ 작동
curl nginx.default.svc.cluster.local  # ✅ 작동 (전체 FQDN)

5. 배운 것과 다음 계획

Day 1에서 배운 핵심

1. Kubernetes는 선언적(Declarative) 시스템이다

   • "이렇게 되어야 한다"를 선언하면
   • Controller Manager가 알아서 그 상태를 유지

2. 모든 것은 API Server를 거친다

   • kubectl, Controller, Scheduler 모두 API Server와 통신
   • etcd와 직접 통신하는 건 API Server뿐

3. 네트워크는 3개 레이어로 분리

   • Node Network (물리)
   • Pod Network (Calico)
   • Service Network (가상)

4. DNS는 Kubernetes의 핵심

   • 없으면 Pod들이 서로를 못 찾음
   • CoreDNS는 클러스터 + 외부 DNS 모두 처리

유용했던 명령어 Top 5

# 1. 전체 리소스 한눈에 보기
kubectl get all -A

# 2. 노드별 Pod 개수 확인
kubectl get pods -A -o wide | awk '{print $8}' | sort | uniq -c

# 3. 특정 Label을 가진 Pod만 조회
kubectl get pods -l app=nginx

# 4. 리소스 상세 정보 (문제 해결에 필수!)
kubectl describe pod <pod-name> -n <namespace>

# 5. 실시간 로그 확인
kubectl logs -f <pod-name> -n <namespace>

마치며

Kubernetes, 처음엔 정말 어려웠습니다. 용어도 생소하고, 개념도 복잡하고...

하지만 직접 클러스터를 만들고, 하나씩 확인하면서 점점 이해가 되기 시작했어요. 특히 DNS 테스트가 성공했을 때의 그 기쁨이란!

여러분도 처음엔 막막하실 수 있습니다. 하지만 포기하지 마세요. 하나씩 차근차근 따라가다 보면 어느새 "아, 이래서 Kubernetes를 쓰는구나!"하는 순간이 올 겁니다.

Ubuntu에서 네트워크 설정을 변경하다가 예상치 못한 문제를 겪어본 경험이 있으신가요? 저는 최근 Ubuntu Desktop에서 Kubernetes 클러스터를 구성하면서 DNS 설정이 적용되지 않는 문제로 몇 시간을 씨름했습니다. 이 과정에서 Ubuntu의 네트워크 관리 체계를 깊이 이해하게 되었고, 같은 문제로 고민하실 분들을 위해 이 글을 작성합니다.

Ubuntu의 네트워크 관리 체계

Ubuntu 버전별 기본 네트워크 렌더러

Ubuntu는 버전과 에디션에 따라 다른 네트워크 관리 도구를 사용합니다:

• Ubuntu Desktop (18.04 이후): NetworkManager가 기본
• Ubuntu Server (18.04 이후): systemd-networkd가 기본
• Ubuntu 17.10 이전: ifupdown 사용

Ubuntu 22.04 Desktop을 사용 중이라면, NetworkManager가 기본 네트워크 렌더러로 설정되어 있습니다. 다음 명령어로 확인할 수 있습니다:

# 현재 활성화된 네트워크 서비스 확인
systemctl status NetworkManager
systemctl status systemd-networkd

# netplan 렌더러 확인
cat /etc/netplan/*.yaml | grep renderer

NetworkManager vs systemd-networkd: 핵심 차이점

NetworkManager

• 대상: 주로 데스크톱 환경
• 특징:
  • GUI 지원 (nm-applet, GNOME 설정 등)
  • Wi-Fi, VPN, 모바일 브로드밴드 등 다양한 연결 타입 지원
  • 동적 네트워크 환경에 최적화
  • D-Bus를 통한 애플리케이션 통합
  • 연결 프로파일 기반 관리 (Connection 개념)

systemd-networkd

• 대상: 주로 서버 환경
• 특징:
  • 경량화된 디자인
  • 정적 네트워크 구성에 최적화
  • systemd 생태계와 긴밀한 통합
  • 설정 파일 기반 (/etc/systemd/network/)
  • 컨테이너 환경에 적합

Netplan: 통합 네트워크 설정 추상화 계층

Netplan의 역할과 작동 원리

Netplan은 Ubuntu 17.10부터 도입된 네트워크 설정 추상화 도구입니다. 중요한 점은 Netplan이 직접 네트워크를 관리하지 않는다는 것입니다.

┌─────────────────────────────┐
│   사용자가 작성하는 YAML     │
│  /etc/netplan/*.yaml        │
└──────────┬──────────────────┘
           │ netplan generate/apply
           ├─────────────┬────────────┐
           ↓             ↓            ↓
┌──────────────┐ ┌────────────┐ ┌──────────────┐
│NetworkManager│ │  networkd  │ │   기타...    │
│   (Desktop)  │ │  (Server)  │ │              │
└──────────────┘ └────────────┘ └──────────────┘

Netplan의 주요 장점:

• 통일된 YAML 형식으로 네트워크 설정
• 렌더러 전환이 간단 (renderer: NetworkManager/networkd)
• 선언적 설정 방식
• 버전 관리에 용이

실제 사례: K8s 환경에서 DNS 설정 충돌 문제

문제 상황

Ubuntu Desktop에 Kubernetes를 설치하고, CoreDNS(10.96.0.10)를 시스템 DNS에 추가하려고 했습니다.

# /etc/netplan/01-static-wifi.yaml
network:
  version: 2
  renderer: NetworkManager
  wifis:
    wlp2s0:
      access-points:
        "KT_GiGA_3AD1":
          password: "********"
      dhcp4: true
      nameservers:
        addresses: [10.96.0.10, 168.126.63.1, 168.126.63.2]

sudo netplan apply를 실행했지만, DNS 설정이 반영되지 않았습니다.

원인 분석

문제의 핵심은 NetworkManager의 Connection 개념을 이해하지 못한 것이었습니다.

# 연결 상태 확인
$ nmcli connection show
NAME                           UUID                                  TYPE      DEVICE 
KT_GiGA_3AD1                   xxxx-xxxx-xxxx-xxxx                  wifi      wlp2s0
netplan-wlp2s0-KT_GiGA_3AD1   yyyy-yyyy-yyyy-yyyy                  wifi      --

두 개의 Connection이 존재했고, 기존 수동 연결이 활성화되어 있어 Netplan이 생성한 연결이 무시되었습니다.

NetworkManager Connection의 이해

NetworkManager에서 Connection은 네트워크 설정 프로파일입니다:

• 하나의 인터페이스에 여러 Connection 존재 가능
• 한 번에 하나의 Connection만 활성화
• 우선순위: 이미 활성화된 연결 > 새로운 연결

해결 방법

방법 1: 기존 Connection 삭제 후 Netplan 연결 활성화

# 기존 수동 연결 삭제
sudo nmcli connection delete "KT_GiGA_3AD1"

# Netplan 재적용
sudo netplan apply

# Netplan이 생성한 연결 활성화
sudo nmcli connection up "netplan-wlp2s0-KT_GiGA_3AD1"

# DNS 확인
resolvectl status wlp2s0

방법 2: 기존 Connection 직접 수정

# NetworkManager를 통한 직접 수정
sudo nmcli connection modify "KT_GiGA_3AD1" \
  ipv4.dns "10.96.0.10 168.126.63.1 168.126.63.2"

sudo nmcli connection reload
sudo nmcli connection up "KT_GiGA_3AD1"

방법 3: 자동 DNS 무시 설정

# DHCP DNS 무시하고 수동 DNS만 사용
sudo nmcli connection modify "KT_GiGA_3AD1" \
  ipv4.ignore-auto-dns yes \
  ipv4.dns "10.96.0.10 168.126.63.1 168.126.63.2"

베스트 프랙티스

1. 환경에 맞는 렌더러 선택

network:
  version: 2
  renderer: NetworkManager  # Desktop 환경
  # renderer: networkd     # Server 환경

2. Netplan 전용 시스템 구성

새로운 시스템에서는 처음부터 Netplan으로만 관리:

# 기존 수동 연결 모두 삭제
nmcli connection show | grep -v "netplan-" | awk 'NR>1 {print $1}' | \
  xargs -I {} sudo nmcli connection delete "{}"

3. 설정 변경 전 백업

# Netplan 설정 백업
sudo cp -r /etc/netplan /etc/netplan.backup

# NetworkManager 연결 백업
sudo cp -r /etc/NetworkManager/system-connections \
  /etc/NetworkManager/system-connections.backup

4. 디버깅 팁

# Netplan 설정 검증 (실제 적용하지 않음)
sudo netplan try

# 생성될 설정 파일 미리보기
sudo netplan generate --debug

# NetworkManager 로그 확인
journalctl -u NetworkManager -f

# 현재 DNS 설정 확인
resolvectl status
nmcli device show | grep DNS

결론

Ubuntu의 네트워크 관리 체계는 처음에는 복잡해 보이지만, 각 구성 요소의 역할을 이해하면 매우 논리적입니다:

1. Netplan은 설정을 추상화하는 "번역기"
2. NetworkManager는 Desktop에서 실제 네트워크를 관리하는 "실행자"
3. systemd-networkd는 Server에서 같은 역할을 수행

제가 겪은 문제는 Netplan과 NetworkManager의 관계를 정확히 이해하지 못해 발생했습니다. 특히 NetworkManager의 Connection 개념과 우선순위를 알지 못해 몇 시간을 헤맸죠.

핵심 교훈:

• Netplan을 사용할 때는 기존 수동 설정과의 충돌을 확인
• 하나의 인터페이스는 하나의 활성 Connection만 가능
• Desktop 환경에서는 NetworkManager의 특성을 이해하고 활용

이 글이 Ubuntu 네트워크 설정으로 고민하시는 분들께 도움이 되기를 바랍니다. 특히 Kubernetes나 컨테이너 환경을 구성하면서 DNS 설정 문제를 겪으시는 분들에게 실질적인 해결책이 되었으면 좋겠습니다.

🤔 "클러스터 내부는 CNI가 알아서 하는데, BGP는 왜 필요하죠?"

Kubernetes CNI와 BGP의 경계를 명확히 이해하고, 실전에서 BGP가 필요한 순간을 알아봅시다.

목차

1. BGP란 무엇인가?
2. CNI vs BGP: 역할 구분
3. BGP가 필요한 순간
4. BGP 설정 완전 분석
5. 실전 시나리오
6. 라우터와 스위치
7. AS Number 관리
8. 장애 대응
9. FAQ

BGP란 무엇인가?

BGP (Border Gateway Protocol)

BGP는 인터넷의 백본을 구성하는 라우팅 프로토콜입니다. 서로 다른 네트워크(Autonomous System) 간에 "어떤 IP 주소가 어디에 있는지" 정보를 교환합니다.

🏢 현실 세계 비유

우편 시스템:
  - 서울 우체국: "06xxx 우편번호는 우리가 관리해요!"
  - 부산 우체국: "48xxx 우편번호는 우리가 관리해요!"

BGP:
  - 네이버 네트워크: "210.89.160.0/24 IP는 우리 네트워크예요!"
  - 카카오 네트워크: "211.249.220.0/24 IP는 우리 네트워크예요!"

🌐 인터넷에서의 BGP

사용자가 www.google.com 접속 시:

1. 사용자 ISP: "142.250.x.x는 어디로 보내지?"
2. BGP 조회: "Google AS (15169)로 보내!"
3. 최적 경로 선택: SKT → 해외 회선 → Google
4. 페이지 로딩 완료

CNI vs BGP: 역할 구분

🎯 핵심 차이점

CNI의 역할 (클러스터 내부)

┌─────────────────────────────────────┐
│     Kubernetes Cluster              │
│                                     │
│  Pod A (10.244.1.5)                │
│     ↓                              │
│  CNI가 자동 라우팅                  │
│     ↓                              │
│  Pod B (10.244.2.10)               │
│                                     │
│  ✅ BGP 불필요!                     │
└─────────────────────────────────────┘

CNI가 자동으로 처리하는 것:

• Pod IP 할당
• 노드 간 라우팅
• 네트워크 정책 (Calico의 경우)
• Service 네트워킹

BGP의 역할 (클러스터 외부)

┌─────────────────────┐      ┌─────────────────────┐
│  K8s Cluster A      │      │  K8s Cluster B      │
│  (서울)             │      │  (도쿄)             │
│  10.244.0.0/16      │      │  10.245.0.0/16      │
└──────────┬──────────┘      └──────────┬──────────┘
           │                            │
           └────────┬───────────────────┘
                    │ BGP 필요!
           ┌────────▼────────┐
           │  Global Router  │
           │  "경로 알려줘!" │
           └─────────────────┘

BGP가 필요한 이유:

• 서로 다른 네트워크 연결
• 경로 정보 교환
• 자동 장애 대응
• 최적 경로 선택

BGP가 필요한 순간

✅ Case 1: 멀티 클러스터

상황

서울 클러스터:
  - Pod CIDR: 10.244.0.0/16
  - Service CIDR: 10.96.0.0/12

도쿄 클러스터:
  - Pod CIDR: 10.245.0.0/16
  - Service CIDR: 10.97.0.0/12

문제

// 서울 클러스터의 Pod에서
const response = await axios.post(
  'http://10.245.1.50:8080/api',  // 도쿄 클러스터 Pod IP
  data
);

// ❌ Error: Network unreachable
// 왜? 서울 클러스터는 10.245.x.x가 어디 있는지 몰라!

해결: BGP 설정

서울 클러스터:

apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64512  # 서울 클러스터 AS

---
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: to-tokyo-cluster
spec:
  peerIP: 203.0.113.1  # 도쿄 클러스터 게이트웨이
  asNumber: 64513      # 도쿄 클러스터 AS

도쿄 클러스터:

apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64513  # 도쿄 클러스터 AS

---
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: to-seoul-cluster
spec:
  peerIP: 203.0.113.2  # 서울 클러스터 게이트웨이
  asNumber: 64512      # 서울 클러스터 AS

동작 흐름

1. 서울 Calico: "10.244.0.0/16은 우리 거야!" (BGP 광고)
2. 도쿄 Calico: "10.245.0.0/16은 우리 거야!" (BGP 광고)
3. 라우터들이 학습: 
   - "10.244.x.x → 서울로"
   - "10.245.x.x → 도쿄로"
4. ✅ 서울 ↔ 도쿄 Pod 간 직접 통신 가능!

✅ Case 2: 온프레미스 통합

상황

Kubernetes Cluster: 10.244.0.0/16 (AWS)
온프레미스 데이터센터: 192.168.0.0/16
  - 레거시 ERP: 192.168.100.50
  - 은행 연동 시스템: 192.168.200.30
  - Oracle DB: 192.168.150.10

문제

# Kubernetes Pod에서 온프레미스 DB 접근
import cx_Oracle

# ❌ 연결 실패!
connection = cx_Oracle.connect(
    'user/password@192.168.150.10:1521/ORCL'
)

# 왜? 
# 1. Pod → 192.168.150.10 경로를 몰라
# 2. 온프레미스 → 10.244.x.x 응답 경로를 몰라

해결: BGP + Direct Connect

AWS 측 설정:

# Terraform
resource "aws_vpn_gateway" "main" {
  vpc_id          = aws_vpc.main.id
  amazon_side_asn = 64512  # AWS 측 AS
}

resource "aws_customer_gateway" "onprem" {
  bgp_asn    = 65000  # 온프레미스 AS
  ip_address = "203.0.113.100"  # 온프레미스 공인 IP
  type       = "ipsec.1"
}

resource "aws_vpn_connection" "main" {
  vpn_gateway_id      = aws_vpn_gateway.main.id
  customer_gateway_id = aws_customer_gateway.onprem.id
  type                = "ipsec.1"
  static_routes_only  = false  # BGP 사용
}

Calico 설정:

apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64513  # Kubernetes AS (AWS와 다름!)

---
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: aws-vpn-gateway
spec:
  peerIP: 10.0.0.1  # VPN Gateway 내부 IP
  asNumber: 64512   # AWS VGW AS

온프레미스 라우터 설정:

router bgp 65000
  neighbor 203.0.113.100 remote-as 64512
  network 192.168.0.0 mask 255.255.0.0

  ! Kubernetes Pod IP 학습
  neighbor 203.0.113.100 route-map ACCEPT-K8S in

동작 흐름

Pod (10.244.1.5) → Oracle DB (192.168.150.10)

1. Pod: "192.168.150.10으로 가고 싶어"
2. Calico: "BGP 테이블 확인... VPN Gateway로!"
3. VPN Gateway → Direct Connect
4. 온프레미스 라우터: "192.168.150.10은 내부 네트워크"
5. ✅ DB 도달

응답:
DB (192.168.150.10) → Pod (10.244.1.5)

1. 온프레미스 라우터: "10.244.1.5? BGP 테이블 확인..."
2. "아, AWS VPN으로 보내면 되겠네"
3. VPN → AWS VGW → Calico
4. ✅ Pod 도달

✅ Case 3: 데이터센터의 ToR Switch 연동

상황

온프레미스 데이터센터 구조:

┌────────────────────────────────┐
│  Core Router (192.168.0.1)    │
│  AS 65000                      │
└────────┬───────────────────────┘
         │
    ┌────┴────┬────────┐
    │         │        │
┌───▼───┐ ┌──▼───┐ ┌──▼───┐
│ToR-1  │ │ToR-2 │ │ToR-3 │
│.1.1   │ │.1.2  │ │.1.3  │
│AS     │ │AS    │ │AS    │
│65001  │ │65001 │ │65001 │
└───┬───┘ └──┬───┘ └──┬───┘
    │        │        │
  [노드]   [노드]   [노드]

왜 BGP가 필요한가?

BGP 없이 (VXLAN Overlay):

문제점:
1. 모든 트래픽이 캡슐화됨 (Overhead 증가)
2. ToR Switch가 Pod IP를 몰라 → 비효율적 라우팅
3. 물리 네트워크의 성능을 100% 활용 못 함

예시:
  Pod A → Pod B (같은 랙)
  실제 거리: 1 홉
  VXLAN: 3 홉 (캡슐화/복호화 오버헤드)

BGP 사용 (Native Routing):

장점:
1. 캡슐화 없음 → 오버헤드 제거
2. ToR Switch가 Pod IP 인지 → 최적 경로
3. 물리 네트워크 성능 100% 활용

예시:
  Pod A → Pod B (같은 랙)
  실제 거리: 1 홉
  BGP: 1 홉 (직접 전송)

BGP 설정

ToR Switch 1:

router bgp 65001
  neighbor 192.168.1.10 remote-as 64512  # K8s Node 1
  neighbor 192.168.1.11 remote-as 64512  # K8s Node 2

  ! Pod IP 학습
  address-family ipv4
    neighbor 192.168.1.10 activate
    neighbor 192.168.1.11 activate

Calico (모든 노드):

apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64512
  nodeToNodeMeshEnabled: false  # Node Mesh 비활성화

---
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: tor-switch-1
spec:
  peerIP: 192.168.1.1
  asNumber: 65001

성능 비교

벤치마크 (10Gbps 네트워크):

VXLAN Overlay:
  처리량: 8.2 Gbps (18% 오버헤드)
  레이턴시: 0.8ms
  CPU 사용률: 25%

BGP Native Routing:
  처리량: 9.7 Gbps (3% 오버헤드)
  레이턴시: 0.3ms
  CPU 사용률: 8%

결과: BGP가 3배 효율적!

✅ Case 4: 외부 로드밸런서 직접 연동

상황

요구사항:
- F5 하드웨어 로드밸런서 (물리 장비)
- Pod IP로 직접 트래픽 전송 (Service 거치지 않음)
- DSR (Direct Server Return) 구현

왜 필요한가?

일반적인 방법 (NodePort/LoadBalancer):

사용자 → F5 → NodePort (30080)
       → kube-proxy NAT
       → Pod

문제:
1. kube-proxy 병목
2. NAT 오버헤드
3. Source IP 손실
4. 높은 레이턴시

BGP 방법:

사용자 → F5 → Pod IP 직접!

장점:
1. kube-proxy 우회
2. NAT 없음
3. Source IP 보존
4. 낮은 레이턴시

설정

Calico:

apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: f5-load-balancer
spec:
  peerIP: 192.168.10.100  # F5 IP
  asNumber: 65100

---
# 특정 Service의 Pod IP만 광고
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  serviceExternalIPs:
    - cidr: 10.244.0.0/16  # Pod CIDR

F5 설정:

ltm pool k8s-payment-pool {
  members {
    10.244.1.50:8080 { }  # Pod IP 직접 사용!
    10.244.2.30:8080 { }
    10.244.3.80:8080 { }
  }
  monitor tcp
}

동작

1. Calico가 BGP로 광고:
   "10.244.1.50은 192.168.1.10 (노드)에 있어요"

2. F5가 학습:
   "10.244.1.50으로 가려면 192.168.1.10으로 보내면 되겠네"

3. 트래픽:
   사용자 → F5 → 192.168.1.10 → Pod (10.244.1.50)

4. 응답 (DSR):
   Pod → 사용자 (직접! F5 거치지 않음)

결과: 초고속 처리!

BGP 설정 완전 분석

YAML 각 필드 상세 설명

apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: rack-tor-switch
spec:
  peerIP: 192.168.1.1
  asNumber: 64512

1. apiVersion: projectcalico.org/v3

의미:

• Calico API v3 사용 선언
• Kubernetes CRD (Custom Resource Definition)

버전 히스토리:

• v1: 초기 버전 (deprecated)
• v3: 현재 안정 버전 (권장)

2. kind: BGPPeer

의미:

• 생성할 리소스 타입: BGP Peer
• 외부 BGP 라우터와의 연결 정의

Calico의 다른 kinds:

BGPPeer           # 외부 BGP 라우터 연결
BGPConfiguration  # BGP 전역 설정
NetworkPolicy     # 네트워크 보안 정책
IPPool            # IP 주소 풀
FelixConfiguration # Felix 데몬 설정

3. metadata.name: rack-tor-switch

의미:

• BGP Peer 리소스의 고유 식별자
• 클러스터 내에서 유일해야 함

네이밍 컨벤션:

# 위치 기반
name: rack1-tor-switch
name: datacenter-seoul-tor1

# 기능 기반
name: production-bgp-peer
name: edge-router-primary

# 조합
name: seoul-dc-rack1-tor1

실제 데이터센터 용어:

• rack: 서버 랙 (서버들이 꽂혀있는 선반)
• tor: Top of Rack (랙 맨 위의 스위치)
• switch: 네트워크 스위치

데이터센터 구조:

┌─────────────────┐
│  Core Router    │
└────────┬────────┘
         │
    ┌────▼────┐
    │ToR Switch│ ← 여기!
    │(랙 상단) │
    └────┬────┘
         │
    ┌────┴────┐
    │Server 1 │
    │Server 2 │
    │Server 3 │
    └─────────┘

4. spec.peerIP: 192.168.1.1

의미:

• 연결할 외부 BGP 라우터의 IP 주소
• Calico 노드들이 이 IP로 BGP 연결 시도

선택 기준:

✅ 모든 Kubernetes 노드에서 접근 가능한 IP
✅ 일반적으로 관리 네트워크의 IP
✅ 물리 라우터/스위치의 관리 인터페이스 IP
❌ NAT 뒤의 IP는 피할 것
❌ DHCP로 변경될 수 있는 IP 피할 것

실제 환경 예시:

# 온프레미스
peerIP: 192.168.1.1  # ToR Switch 관리 IP

# AWS
peerIP: 10.0.0.1  # Virtual Private Gateway

# GCP
peerIP: 10.1.0.1  # Cloud Router

5. spec.asNumber: 64512

의미:

• Peer (상대방 라우터)의 AS Number
• BGP에서 네트워크를 구분하는 고유 번호

AS Number 범위:

1 - 64511:           공인 AS (Public)
                     예: Google(15169), Amazon(16509)

64512 - 65534:       사설 AS (Private) ← 대부분 여기 사용
                     내부 네트워크용, 인터넷 광고 안 됨

4200000000 - 4294967294: 4바이트 사설 AS
                          대규모 조직용

왜 64512를 많이 사용하나?

• 사설 AS 범위의 시작 번호
• RFC 6996에서 정의된 표준
• 많은 문서와 예제에서 사용

추가 설정 옵션

nodeSelector로 특정 노드만 연결

apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: payment-nodes-tor
spec:
  peerIP: 192.168.1.1
  asNumber: 64512
  nodeSelector: "service == 'payment'"  # 결제 노드만

# 노드 레이블 설정
kubectl label node worker-1 service=payment
kubectl label node worker-2 service=payment

다중 BGP Peer (고가용성)

# Primary
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: tor-switch-primary
spec:
  peerIP: 192.168.1.1
  asNumber: 64512

---
# Backup
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: tor-switch-backup
spec:
  peerIP: 192.168.1.2
  asNumber: 64512

동작:

정상: 모든 노드가 2개 스위치와 BGP 세션
Switch 1 장애: 자동으로 Switch 2만 사용
Switch 1 복구: 다시 2개 모두 사용

라우터와 스위치

기본 개념

스위치 (Switch)

역할: 같은 네트워크 내 연결
계층: L2 (데이터 링크)
주소: MAC 주소 사용
범위: 로컬 네트워크

예시:
  컴퓨터 A → 스위치 → 컴퓨터 B
  (같은 사무실 내)

라우터 (Router)

역할: 다른 네트워크 간 연결
계층: L3 (네트워크)
주소: IP 주소 사용
범위: 인터넷, WAN

예시:
  회사 네트워크 → 라우터 → 인터넷

L3 스위치 (Layer 3 Switch)

역할: 스위칭 + 라우팅
계층: L2 + L3
기능: 스위치처럼 빠르고, 라우터처럼 똑똑함

데이터센터의 ToR Switch는 보통 L3 스위치!
→ BGP 사용 가능

스위치 2개 설정 예시

환경

Kubernetes 클러스터
  Node 1: 192.168.1.10
  Node 2: 192.168.1.11
  Node 3: 192.168.1.12

ToR Switch 1: 192.168.1.1 (AS 64512)
ToR Switch 2: 192.168.1.2 (AS 64512) ← 이중화

BGP 설정

# 첫 번째 스위치
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: tor-switch-1
spec:
  peerIP: 192.168.1.1
  asNumber: 64512

---
# 두 번째 스위치
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: tor-switch-2
spec:
  peerIP: 192.168.1.2
  asNumber: 64512

네트워크 구조

        [인터넷]
           |
    [Core Router]
           |
     ┌─────┴─────┐
     |           |
[ToR Switch 1]  [ToR Switch 2]
192.168.1.1     192.168.1.2
AS 64512        AS 64512
     |               |
     |   이중 연결   |
     └───────┬───────┘
             |
    ┌────────┼────────┐
    |        |        |
  Node1    Node2    Node3
  .1.10    .1.11    .1.12

각 Node는 Switch 1, 2 모두와 BGP 세션

검증

# BGP Peer 확인
$ calicoctl get bgppeer

NAME            PEERIP         NODE   ASN
tor-switch-1   192.168.1.1    (all)  64512
tor-switch-2   192.168.1.2    (all)  64512

# BGP 세션 상태
$ calicoctl node status

IPv4 BGP status
+--------------+-------+----------+-------------+
| PEER ADDRESS | STATE |  SINCE   |    INFO     |
+--------------+-------+----------+-------------+
| 192.168.1.1  | up    | 10:52:33 | Established |
| 192.168.1.2  | up    | 10:52:35 | Established |
+--------------+-------+----------+-------------+

# 2개 모두 "Established" = 정상!

AS Number 관리

AS Number는 어디서 설정?

양쪽 모두 설정 필요!

1. 라우터/스위치 측 (네트워크팀)

# Cisco 라우터
router bgp 64512
  bgp router-id 192.168.1.1
  neighbor 192.168.1.10 remote-as 64513  # K8s 노드
  neighbor 192.168.1.11 remote-as 64513

# "나는 AS 64512이고, 상대방은 AS 64513이야"

2. Kubernetes/Calico 측 (DevOps팀)

# 우리 클러스터 AS
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64513  # "우리는 AS 64513"

---
# Peer 정보
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: tor-switch
spec:
  peerIP: 192.168.1.1
  asNumber: 64512  # "상대방은 AS 64512"

설정 순서

1단계: 네트워크 설계 회의
   "온프레미스는 AS 65000"
   "AWS 서울은 AS 64512"
   "K8s 서울은 AS 64514"

2단계: 네트워크팀이 라우터 설정
   router bgp 64512
   neighbor x.x.x.x remote-as 64514

3단계: DevOps팀이 Calico 설정
   asNumber: 64514 (우리)
   peerIP: x.x.x.x
   asNumber: 64512 (상대방)

AS Number 충돌 방지

❌ 잘못된 예시

라우터: AS 64512
Calico: AS 64512  ← 같으면 안 됨!

문제:
- iBGP (Internal BGP)로 동작
- 라우팅 루프 방지로 경로 광고 안 됨
- 연결은 되지만 라우팅 안 됨

✅ 올바른 예시

라우터: AS 64512
Calico: AS 64513  ← 다른 AS

결과:
- eBGP (External BGP)로 동작
- 정상적으로 라우팅 정보 교환

AS Number 할당 전략

예시 1: 용도별

65000: 온프레미스 데이터센터
65001: AWS 서울 VPC
65002: AWS 도쿄 VPC
65010: K8s 서울 프로덕션
65011: K8s 도쿄 DR
65020: K8s 개발 환경

예시 2: 계층별

64512: 코어 라우터
64520-64529: ToR Switch
64530-64539: Kubernetes 클러스터
64540-64549: 개발/테스트

예시 3: 리전별

65001: 서울 (SEL)
  65001: 인프라
  65011: K8s 프로덕션
  65021: K8s 개발

65002: 도쿄 (TYO)
  65002: 인프라
  65012: K8s 프로덕션
  65022: K8s 개발

장애 대응

자동 장애 대응 (기본)

# 이것만으로도 자동 장애 대응!
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: switch-1
spec:
  peerIP: 192.168.1.1
  asNumber: 64512
---
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: switch-2
spec:
  peerIP: 192.168.1.2
  asNumber: 64512

동작:

정상:
  Node → Switch 1 (Active)
  Node → Switch 2 (Standby)

Switch 1 장애:
  10초 후 자동 감지
  → Switch 2로 전환

Switch 1 복구:
  자동으로 원래대로

우선순위 설정

라우터 측 (Weight)

# Primary 라우터
router bgp 64512
  neighbor 192.168.1.10 remote-as 64513
  neighbor 192.168.1.10 weight 100  # 높은 우선순위

# Backup 라우터
router bgp 64512
  neighbor 192.168.1.10 remote-as 64513
  neighbor 192.168.1.10 weight 50   # 낮은 우선순위

라우터 측 (AS Path Prepend)

# Primary: 짧은 경로
router bgp 64512
  neighbor 192.168.1.10 route-map PRIMARY in

route-map PRIMARY permit 10
  set as-path prepend 64512  # AS Path: 64512

# Backup: 긴 경로 (우선순위 낮음)
router bgp 64512
  neighbor 192.168.1.10 route-map BACKUP in

route-map BACKUP permit 10
  set as-path prepend 64512 64512 64512  # AS Path: 64512 64512 64512

빠른 장애 감지 (BFD)

기본 BGP: 30-90초 감지

# 기본 설정
keepAliveTime: 30s
holdTime: 90s

# → 최대 90초 후 장애 감지

BFD 사용: 1초 이내 감지

# 라우터 설정
interface GigabitEthernet0/0
  bfd interval 200 min_rx 200 multiplier 3
  # 200ms * 3 = 600ms 후 장애 감지

router bgp 64512
  neighbor 192.168.1.10 remote-as 64513
  neighbor 192.168.1.10 fall-over bfd

멀티 리전 DR 시나리오

환경 설정

# 서울 리전 (Primary)
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64512

---
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: global-router
spec:
  peerIP: 203.0.113.1
  asNumber: 64500

---
# 도쿄 리전 (DR)
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64513

---
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: global-router
spec:
  peerIP: 203.0.113.1
  asNumber: 64500

장애 시나리오

정상 시:
  사용자 → 서울 (AS Path 짧음)

서울 장애:
  1. 서울 BGP 광고 중단 (30초)
  2. 라우터가 서울 경로 제거
  3. 도쿄 경로만 남음
  4. 모든 트래픽 → 도쿄 (자동!)

서울 복구:
  1. 서울 BGP 광고 재개
  2. 라우터가 경로 추가
  3. AS Path 비교 (서울이 짧음)
  4. 다시 서울 우선 사용

실전 시나리오

시나리오 1: 스타트업 → 유니콘 성장

Phase 1: MVP (Flannel, BGP 없음)

상황:
- 시드 투자 직후, 팀 10명
- AWS 서울 단일 리전
- 10 노드 클러스터

선택: Flannel
이유: 빠른 구축, 운영 단순화

BGP: 불필요

Phase 2: 성장기 (Flannel 유지)

상황:
- 시리즈 A, 팀 50명, MAU 10만
- 여전히 단일 리전
- 30 노드로 확장

선택: Flannel 계속 사용
이유: 충분한 성능, 안정적

BGP: 여전히 불필요

Phase 3: 스케일업 (Calico + BGP)

상황:
- 시리즈 B, 팀 200명, MAU 100만
- 멀티 리전 필요 (서울 + 도쿄)
- 리전당 100+ 노드

트리거:
✓ 엔터프라이즈 고객 요구 (네트워크 격리)
✓ SOC2 인증 필요
✓ 글로벌 확장
✓ 온프레미스 레거시 연동

선택: Calico + BGP

BGP 설정:

# 서울 클러스터
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64512
  nodeToNodeMeshEnabled: false

---
# AWS 서울 VGW 연결
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: aws-seoul-vgw
spec:
  peerIP: 10.0.0.1
  asNumber: 64500

---
# 도쿄 클러스터 연결
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: tokyo-dr
spec:
  peerIP: 203.0.113.2
  asNumber: 64513

---
# 온프레미스 연결
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: onprem-dc
spec:
  peerIP: 192.168.1.1
  asNumber: 65000

Phase 4: 엔터프라이즈

상황:
- 시리즈 C+, 팀 500명, MAU 500만+
- 글로벌 10개 리전
- 리전당 200+ 노드

BGP 사용:
✓ 멀티 리전 자동 장애 전환
✓ 온프레미스 통합 (레거시 시스템)
✓ 하이브리드 클라우드 (AWS + GCP + 온프레미스)
✓ 고성능 라우팅 (eBPF + BGP)

시나리오 2: 금융 서비스 (토스/카카오뱅크)

요구사항

규제:
✓ 금융 데이터는 국내에만
✓ PCI-DSS 준수
✓ 모든 트래픽 암호화
✓ 네트워크 감사 추적

기술:
✓ 온프레미스 은행 연동
✓ 초저 레이턴시 (<5ms)
✓ 99.99% 가용성
✓ 멀티 리전 DR

BGP 아키텍처

# 1. 온프레미스 은행 연동
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: bank-mainframe
spec:
  peerIP: 192.168.1.1  # 은행 연동 라우터
  asNumber: 65000
  nodeSelector: "service == 'payment'"  # 결제 노드만

---
# 2. AWS 서울 (Primary)
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: aws-seoul-primary
spec:
  peerIP: 10.0.0.1
  asNumber: 64512

---
# 3. AWS 서울 (Backup)
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: aws-seoul-backup
spec:
  peerIP: 10.0.0.2
  asNumber: 64512

---
# 4. AWS 부산 DR
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: aws-busan-dr
spec:
  peerIP: 10.1.0.1
  asNumber: 64513

네트워크 정책 + BGP

# BGP로 라우팅 + NetworkPolicy로 보안
apiVersion: projectcalico.org/v3
kind: NetworkPolicy
metadata:
  name: payment-isolation
spec:
  selector: app == 'payment'
  ingress:
    - action: Allow
      protocol: TCP
      source:
        selector: app == 'api-gateway'
      destination:
        ports: [8080]
  egress:
    - action: Allow
      protocol: TCP
      destination:
        nets:
          - 192.168.100.0/24  # 은행 시스템만
        ports: [3000]

시나리오 3: 글로벌 게임 회사

요구사항

성능:
✓ 초저 레이턴시 (<2ms)
✓ 초당 100만+ 패킷
✓ DDoS 방어

가용성:
✓ 99.99% 가동률
✓ 자동 리전 전환
✓ 글로벌 Anycast

BGP + eBPF 조합

# eBPF 활성화
apiVersion: projectcalico.org/v3
kind: FelixConfiguration
metadata:
  name: default
spec:
  bpfEnabled: true
  bpfLogLevel: Info

---
# BGP Configuration
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  asNumber: 64520

---
# 서울 리전
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: seoul-edge
spec:
  peerIP: 203.0.113.1
  asNumber: 64500

---
# 도쿄 리전
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: tokyo-edge
spec:
  peerIP: 103.0.113.1
  asNumber: 64501

---
# 싱가포르 리전
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: singapore-edge
spec:
  peerIP: 123.0.113.1
  asNumber: 64502

Anycast 구현

같은 Service IP를 모든 리전에서 광고:

서울: "1.2.3.4는 우리한테 있어요!" (BGP 광고)
도쿄: "1.2.3.4는 우리한테 있어요!" (BGP 광고)
싱가포르: "1.2.3.4는 우리한테 있어요!" (BGP 광고)

결과:
- 한국 플레이어 → 자동으로 서울 리전
- 일본 플레이어 → 자동으로 도쿄 리전
- 동남아 플레이어 → 자동으로 싱가포르 리전

서울 장애 시:
- 한국 플레이어도 자동으로 도쿄로 전환

FAQ

Q1: BGP 없이도 Kubernetes가 잘 동작하는데?

A: 맞습니다! 대부분의 경우 BGP 불필요합니다.

BGP 불필요 (90%):
✓ 단일 클러스터
✓ Service를 통한 Pod 접근
✓ Ingress 사용
✓ 같은 클러스터 내 통신

BGP 필요 (10%):
✓ 멀티 클러스터
✓ 온프레미스 통합
✓ 물리 네트워크 직접 연동
✓ 외부에서 Pod IP 직접 접근

Q2: Flannel에서 Calico로 마이그레이션 시 다운타임은?

A: 방법에 따라 다릅니다.

단일 클러스터 교체:
- 다운타임: 10-30분
- Pod 전체 재시작 필요

Blue-Green 방식:
- 다운타임: 0분
- 새 클러스터 구축 후 전환

Rolling Update:
- 다운타임: 노드당 2-5분
- 노드를 하나씩 전환

Q3: AS Number는 누가 정하나요?

A: 네트워크팀과 협의하여 결정합니다.

절차:
1. 네트워크팀과 회의
   "우리 온프레미스는 AS 65000 사용 중"

2. 네트워크팀이 AS 할당
   "K8s 서울은 AS 64512 써주세요"

3. DevOps팀이 Calico 설정
   asNumber: 64512

주의: 임의로 변경하면 안 됨!

Q4: BGP 세션이 Established 안 되면?

A: 체크리스트:

# 1. 핑 테스트
ping 192.168.1.1

# 2. BGP 포트 확인 (TCP 179)
telnet 192.168.1.1 179

# 3. 방화벽 확인
# AWS: Security Group에서 TCP 179 허용
# 온프레미스: 방화벽 규칙 확인

# 4. AS Number 확인
# 라우터와 Calico 설정이 서로 일치하는지

# 5. 라우터 설정 확인
# 네트워크팀에게 라우터 로그 요청

Q5: eBPF와 BGP는 같이 써야 하나요?

A: 아닙니다. 독립적입니다.

eBPF: 패킷 처리 성능 향상 (커널 레벨)
BGP: 네트워크 간 라우팅 정보 교환

조합:
✓ eBPF만: 가능 (고성능 단일 클러스터)
✓ BGP만: 가능 (멀티 클러스터)
✓ 둘 다: 가능 (고성능 멀티 클러스터) ← 최고!
✓ 둘 다 안 씀: 가능 (일반 Flannel)

Q6: 라우터 설정은 누가 하나요?

A: 역할 분담:

네트워크팀:
- 물리/가상 라우터 설정
- AS Number 할당
- BGP 정책 설정
- 방화벽 규칙

DevOps팀:
- Calico BGP 설정
- Kubernetes 리소스 관리
- 모니터링 및 트러블슈팅

협업:
- AS Number 결정
- IP 대역 계획
- 장애 대응 절차

Q7: BGP 모니터링은 어떻게?

A: 여러 방법 사용:

# Calico 상태
calicoctl node status

# 상세 정보
sudo birdc show protocols all

# Prometheus 메트릭
felix_route_table_list_seconds
felix_int_dataplane_failures
bgp_peers_up

# 알림 설정
BGP 세션 Down → Slack 알림
경로 개수 급변 → 담당자 호출

Q8: 비용은 얼마나 차이 나나요?

A: 주로 운영 복잡도 차이:

Flannel:
- 설정 시간: 30분
- 학습 시간: 1일
- 운영 인력: 최소

Calico + BGP:
- 설정 시간: 2-4시간
- 학습 시간: 1주일
- 운영 인력: 네트워크 지식 필요

하드웨어 비용:
- 거의 차이 없음
- BGP 때문에 추가 장비 불필요

결론

핵심 요약

1. BGP는 언제 필요한가?

✅ 필요한 경우 (10%):
- 멀티 클러스터
- 온프레미스 통합
- 물리 네트워크 직접 연동
- 고성능 요구사항

❌ 불필요한 경우 (90%):
- 단일 클러스터
- Service/Ingress 사용
- 일반적인 마이크로서비스

2. BGP 설정 핵심

# 3가지만 기억하세요
1. asNumber: 우리 클러스터 AS
2. peerIP: 상대방 라우터 IP
3. asNumber (peer): 상대방 AS

# 나머지는 자동!

3. 장애는 자동 대응

BGP가 자동으로:
✓ 장애 감지 (10-30초)
✓ 대체 경로 선택
✓ 트래픽 우회
✓ 복구 시 원복

개발자는 신경 안 써도 됨!

4. 개발자 관점

// 코드는 항상 똑같음
await axios.post('http://service:8080/api', data);

// BGP가 있든 없든
// 멀티 클러스터든 단일 클러스터든
// 코드 변경 없음!

의사결정 가이드

시작 단계:
→ Flannel (간단함)

성장 단계:
→ Flannel 유지 (충분함)

스케일업:
→ Calico (성능/보안)

멀티 클러스터:
→ Calico + BGP (필수)

엔터프라이즈:
→ Calico + BGP + eBPF (최고)

마지막 조언

"BGP는 복잡하지만, 진짜 필요할 때까지는 쓰지 마세요. 하지만 필요한 순간이 오면, BGP만큼 강력한 게 없습니다."

참고 자료

공식 문서

• Calico BGP 가이드
• RFC 4271 - BGP-4
• Kubernetes 네트워킹

추천 학습 자료

• BGP 기초 개념
• Calico 아키텍처
• 네트워크 엔지니어를 위한 Kubernetes

실전 케이스 스터디

• Spotify의 멀티 클러스터 전략
• Shopify의 Kubernetes 네트워킹
• Netflix의 글로벌 네트워크

마치며

BGP는 복잡해 보이지만, 핵심 개념만 이해하면 됩니다:

1. 클러스터 내부는 CNI가 처리 (BGP 불필요)
2. 클러스터 외부는 BGP가 필요 (멀티 클러스터, 온프레미스 등)
3. 설정은 간단하지만 네트워크팀과 협업 필수
4. 장애는 자동으로 대응 (BGP의 진가!)

이 글이 BGP에 대한 두려움을 없애고, 실전에서 올바른 선택을 하는 데 도움이 되었기를 바랍니다!

Happy Networking!

Calico와 Flannel, 어떤 CNI를 선택해야 할까? eBPF와 BGP가 뭐길래 성능이 3배나 빨라진다는 걸까? 실전 사용 사례를 통해 완벽하게 이해해보자.

목차

1. CNI란 무엇인가?
2. Calico vs Flannel 핵심 비교
3. eBPF 완전 정복
4. BGP 이해하기
5. 실전 사용 사례
6. 의사결정 가이드

CNI란 무엇인가?

CNI (Container Network Interface)는 Kubernetes에서 Pod 간 네트워킹을 담당하는 플러그인입니다.

쉽게 말하면:

• 🏠 문제: Kubernetes는 여러 서버(노드)에 걸쳐 컨테이너를 실행하는데, 이들이 서로 통신하려면?
• ✨ 해결: CNI가 가상 네트워크를 만들어 모든 Pod가 서로 통신할 수 있게 해줌

CNI의 역할

Pod A (10.244.1.5)     Pod B (10.244.2.10)
     ↓                        ↓
  Node 1                   Node 2
     ↓                        ↓
     └────── CNI가 연결 ──────┘

Calico vs Flannel 핵심 비교

🐱 Calico

특징: 고성능 + 강력한 보안

# Calico 주요 특징
네트워킹: BGP, VXLAN, IPIP
네트워크 정책: ✅ 강력함 (L3/L4/L7)
성능: ⚡ 매우 높음 (eBPF 모드)
복잡도: 🔧 높음
리소스 사용: 📊 중간~높음
적합한 환경: 🏢 엔터프라이즈, 대규모 프로덕션

🧣 Flannel

특징: 단순함 + 안정성

# Flannel 주요 특징
네트워킹: VXLAN, host-gw, UDP
네트워크 정책: ❌ 지원 안함
성능: 💨 좋음
복잡도: 🎯 매우 낮음
리소스 사용: 📊 낮음
적합한 환경: 🛠️ 개발/테스트, 중소규모

기능 비교표

eBPF 완전 정복

eBPF란?

eBPF (extended Berkeley Packet Filter)는 리눅스 커널을 재컴파일 없이 확장할 수 있는 혁명적 기술입니다.

🍔 음식점 비유로 이해하기

전통적 방식 (iptables)

손님(패킷) → 홀(사용자 공간) → 주문서 작성 
  → 주방(커널)으로 전달 📝
  → 주방에서 요리
  → 홀로 다시 전달 📝
  → 손님에게 서빙

❌ 문제: 홀 ↔ 주방 왕복이 너무 많음!

eBPF 방식

손님(패킷) → 주방(커널)에서 바로 처리
  → 즉시 서빙

✅ 장점: 중간 단계 생략!

컴퓨터의 두 세계

컴퓨터는 크게 두 공간으로 나뉩니다:

┌─────────────────────────────────┐
│  👤 사용자 공간 (User Space)     │
│                                 │
│  • 일반 프로그램들              │
│  • Docker 컨테이너              │
│  • 느리지만 안전                │
└────────────┬────────────────────┘
             │ 시스템 콜 (느림!)
┌────────────▼────────────────────┐
│  ⚙️ 커널 공간 (Kernel Space)    │
│                                 │
│  • 하드웨어 직접 제어           │
│  • 네트워크 카드 제어           │
│  • 빠르지만 위험                │
└─────────────────────────────────┘

전통적 방식 vs eBPF

전통적 방식: 긴 여행

패킷 도착
  ↓
커널이 받음
  ↓
사용자 공간으로 복사 ⚠️ (느림)
  ↓
애플리케이션 처리
  ↓
다시 커널로 전달 ⚠️ (느림)
  ↓
패킷 전송

총 소요 시간: ~10 마이크로초

eBPF 방식: 직통

패킷 도착
  ↓
커널에서 즉시 처리 ⚡
  ↓
패킷 전송

총 소요 시간: ~3 마이크로초

성능 차이

# 초당 100만 패킷 처리 시

전통적 방식: 10초 소요
eBPF 방식:    3초 소요
절약 시간:    7초 (70% 빨라짐!)

eBPF가 안전한 이유

개발자 코드 작성
    ↓
컴파일 → eBPF 바이트코드
    ↓
┌─────────────────────────────┐
│   eBPF Verifier (검증기)    │
│                             │
│ ✓ 무한 루프 없나?           │
│ ✓ 메모리 침범 없나?         │
│ ✓ 커널 크래시 가능성?       │
└──────┬──────────────────────┘
       │
       ├─ ❌ 위험 → 거부
       └─ ✅ 안전
              ↓
        JIT 컴파일
              ↓
        커널에서 실행!

Calico에서 eBPF 활성화

# eBPF 모드 활성화
kubectl patch configmap/calico-config -n kube-system --type merge \
  -p '{"data":{"bpf-enabled":"true"}}'

# 상태 확인
calicoctl get felixconfiguration default -o yaml

BGP 이해하기

BGP란?

BGP (Border Gateway Protocol)는 인터넷의 우체국입니다. 각 네트워크가 "나는 이 주소들을 관리해!"라고 알려주는 프로토콜이죠.

간단한 비유

당신이 편지를 보낼 때:

"서울시 강남구 XX동" → 우체국이 경로 찾음
"10.244.1.0/24 네트워크" → BGP가 경로 찾음

Kubernetes에서 BGP 동작

┌──────────────────────────────────┐
│    Kubernetes 클러스터           │
│                                  │
│  ┌─────────┐    ┌─────────┐     │
│  │ Node 1  │    │ Node 2  │     │
│  │         │    │         │     │
│  │ BGP     │◄──►│ BGP     │     │
│  │Speaker  │    │Speaker  │     │
│  │         │    │         │     │
│  │10.1.0/24│    │10.2.0/24│     │
│  └────┬────┘    └────┬────┘     │
└───────┼──────────────┼──────────┘
        │              │
        └──────┬───────┘
               │
      ┌────────▼────────┐
      │  물리 라우터     │
      │                 │
      │ "10.1.0/24는   │
      │  Node1로"       │
      └─────────────────┘

BGP의 장점

1. 오버레이 불필요

   • VXLAN 같은 캡슐화 없음
   • 네이티브 IP 라우팅
   • 성능 향상

2. 기존 인프라 통합

   • 데이터센터의 물리 라우터와 직접 통신
   • 온프레미스 환경에 최적

3. 멀티 클라우드

   • AWS, GCP, Azure 간 Pod IP 직접 라우팅
   • 클라우드 네이티브 통합

Calico BGP 설정 예시

# BGP 피어 설정
apiVersion: projectcalico.org/v3
kind: BGPPeer
metadata:
  name: rack-tor-switch
spec:
  peerIP: 192.168.1.1
  asNumber: 64512

# BGP 상태 확인
calicoctl node status

실전 사용 사례

사례 1: 핀테크 스타트업

🧣 Flannel 선택 - 토스뱅크 (가상 사례)

상황

• 팀 규모: DevOps 2명
• 목표: 3개월 내 MVP 출시
• 규모: 10-20 노드
• 초기 사용자: 10만명

선택 이유

✅ 즉시 사용: 1시간 내 설정 완료
✅ 낮은 복잡도: 팀원 모두 1일 내 숙지
✅ 안정성: 5년 이상 검증됨
✅ 리소스 효율: 노드당 200MB만 사용

결과

• ✅ 2개월 만에 프로덕션 배포
• ✅ 네트워크 장애 0건 (6개월)
• ✅ 99.9% 가동률 달성

🐱 Calico 선택 - 카카오뱅크 (가상 사례)

상황

• 금융 규제: PCI-DSS 준수 필요
• 규모: 200+ 노드
• 트래픽: 일 1천만 거래
• 요구사항: 마이크로서비스 간 세밀한 접근 제어

선택 이유

✅ 네트워크 정책: L7까지 세밀한 제어
✅ 암호화: WireGuard로 Pod 간 통신 암호화
✅ 고성능: eBPF로 레이턴시 최소화
✅ 가시성: Hubble로 모든 트래픽 모니터링

핵심 정책 예시

apiVersion: projectcalico.org/v3
kind: NetworkPolicy
metadata:
  name: payment-service-policy
spec:
  selector: app == 'payment'
  ingress:
  - action: Allow
    protocol: TCP
    source:
      selector: app == 'api-gateway'
    destination:
      ports: [8080]
  # 결제 서비스는 API Gateway만 접근 가능

결과

• ✅ PCI-DSS Level 1 인증 획득
• ✅ 평균 응답 시간 30% 개선
• ✅ 보안 사고 0건 (1년간)

사례 2: 글로벌 전자상거래 - 쿠팡

개발 환경: Flannel 🧣

요구사항

• 100+ 개발팀
• 각 팀별 독립 환경 필요
• 매주 새로운 클러스터 생성

솔루션

# Terraform으로 15분 내 클러스터 생성
terraform apply -var="env=dev-team-42"

# Flannel 자동 설치
kubectl apply -f flannel.yaml

효과

• 클러스터 생성 시간: 2시간 → 15분
• 연간 인프라 비용 30% 절감
• 네트워크 관련 티켓 80% 감소

프로덕션 환경: Calico 🐱

요구사항

• 멀티 리전: 서울, 싱가포르, LA
• 초당 100만 요청
• 블랙프라이데이 대응

아키텍처

┌─────────────────────────────────────┐
│         Global Load Balancer        │
└────────────┬───────────┬────────────┘
             │           │
    ┌────────▼───┐  ┌────▼────────┐
    │ Seoul      │  │ Singapore   │
    │ 500 nodes  │  │ 500 nodes   │
    │            │  │             │
    │ Calico BGP │◄─┤ Calico BGP  │
    │ + eBPF     │  │ + eBPF      │
    └────────────┘  └─────────────┘

핵심 설정

# eBPF + BGP 조합
apiVersion: projectcalico.org/v3
kind: FelixConfiguration
metadata:
  name: default
spec:
  bpfEnabled: true
  bpfLogLevel: Info

---
apiVersion: projectcalico.org/v3
kind: BGPConfiguration
metadata:
  name: default
spec:
  nodeToNodeMeshEnabled: false
  asNumber: 64512

결과

• ✅ 블랙프라이데이 99.99% 가동률
• ✅ 네트워크 레이턴시 50% 개선
• ✅ P99 레이턴시 2.5ms 달성
• ✅ 보안 정책 위반 실시간 차단

사례 3: SaaS 기업 - Salesforce

🐱 Calico 필수 선택

멀티 테넌트 환경

• 고객사: 1,000+
• 규모: 1,000+ 노드
• 요구사항: 고객사별 완전한 네트워크 격리

핵심 정책

# 테넌트 격리 정책
apiVersion: projectcalico.org/v3
kind: GlobalNetworkPolicy
metadata:
  name: tenant-isolation
spec:
  selector: tenant != ''
  ingress:
  - action: Allow
    source:
      selector: tenant == $TENANT_ID
  egress:
  - action: Allow
    destination:
      selector: tenant == $TENANT_ID
  # 같은 테넌트끼리만 통신 가능

WireGuard 암호화

# 테넌트 간 트래픽 암호화
calicoctl patch felixconfiguration default \
  --patch='{"spec":{"wireguardEnabled":true}}'

결과

• ✅ 테넌트 간 데이터 유출 0건
• ✅ SOC2 Type 2 인증
• ✅ 운영 비용 60% 절감
• ✅ 고객 이탈률 20% 감소

💡 왜 Flannel은 불가능했나?

• ❌ 네트워크 정책 미지원
• ❌ 암호화 기능 없음
• ❌ 감사 추적 불가능

사례 4: 스타트업 성장 여정

Phase 1: 초기 (Flannel)

시기: 시드 투자 직후
팀: 10명
클러스터: 단일 리전, 10 노드
선택: Flannel
이유: 빠른 출시, 운영 단순화

Phase 2: 성장기 (Flannel 유지)

시기: 시리즈 A
팀: 50명, MAU 10만
클러스터: 30 노드
결정: Flannel 계속 사용
이유: 여전히 충분한 성능

Phase 3: 전환 (→ Calico)

시기: 시리즈 B
팀: 200명, MAU 100만
클러스터: 멀티 리전, 100+ 노드/리전

트리거:
✓ 엔터프라이즈 고객 요구
✓ SOC2 인증 필요
✓ 글로벌 확장
✓ 마이크로서비스 200개로 증가

Phase 4: 엔터프라이즈 (Calico)

시기: 시리즈 C+
팀: 500명, MAU 500만+
클러스터: 글로벌 10개 리전

효과:
✓ 네트워크 정책 1,000+ 적용
✓ eBPF로 성능 30% 개선
✓ 멀티 클라우드 하이브리드
✓ 보안 인증 다수 획득

의사결정 가이드

🎯 의사결정 플로우차트

시작
 │
 ▼
네트워크 정책 필요?
 ├─ YES → Calico ✅
 └─ NO → 계속
      │
      ▼
클러스터 100+ 노드?
 ├─ YES → Calico 권장
 └─ NO → 계속
      │
      ▼
멀티 클라우드?
 ├─ YES → Calico 권장
 └─ NO → 계속
      │
      ▼
컴플라이언스 필요?
 ├─ YES → Calico 필수
 └─ NO → 계속
      │
      ▼
초저 레이턴시 중요?
 ├─ YES → Calico 권장
 └─ NO → 계속
      │
      ▼
빠른 구축/단순함 우선?
 ├─ YES → Flannel ✅
 └─ NO → Calico 권장

시나리오별 추천

성능 비교: 실제 벤치마크

네트워크 처리량

Calico (eBPF):  9.5 Gbps ███████████████████
Flannel (VXLAN): 8.5 Gbps █████████████████

레이턴시 (낮을수록 좋음)

Calico (eBPF):  0.5ms █████
Flannel (VXLAN): 0.7ms ███████

CPU 사용률

Calico:  6% ████████████
Flannel: 4% ████████

메모리 사용량

Calico:  350MB ██████████████
Flannel: 200MB ████████

마이그레이션 가이드

Flannel → Calico 마이그레이션

준비 사항

# 1. 백업
kubectl get all --all-namespaces -o yaml > backup.yaml

# 2. 현재 네트워크 정보 저장
kubectl get nodes -o wide > nodes.txt
kubectl get pods -o wide --all-namespaces > pods.txt

마이그레이션 실행

# 1. Flannel 제거 (신중하게!)
kubectl delete -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

# 2. CNI 관련 파일 정리 (각 노드에서)
sudo rm -rf /etc/cni/net.d/*
sudo rm -rf /var/lib/cni/*

# 3. Calico 설치
kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

# 4. eBPF 활성화 (선택)
calicoctl patch felixconfiguration default --patch='{"spec":{"bpfEnabled":true}}'

# 5. 검증
calicoctl node status
kubectl get pods -n kube-system

주의사항

⚠️ 다운타임 발생: Blue-Green 배포 권장 ⚠️ Pod 재시작 필요: 모든 Pod가 재시작됨 ⚠️ 테스트 환경 먼저: 프로덕션 전 반드시 테스트

실전 팁

Calico 최적화

# 고성능 설정
apiVersion: projectcalico.org/v3
kind: FelixConfiguration
metadata:
  name: default
spec:
  # eBPF 데이터플레인
  bpfEnabled: true

  # 로그 레벨 낮추기 (성능 향상)
  logSeverityScreen: Warning

  # 라우팅 최적화
  routeRefreshInterval: 90s

  # 연결 추적 최적화
  bpfConntrackCleanupInterval: 90s

Flannel 최적화

# ConfigMap 수정
apiVersion: v1
kind: ConfigMap
metadata:
  name: kube-flannel-cfg
  namespace: kube-system
data:
  net-conf.json: |
    {
      "Network": "10.244.0.0/16",
      "Backend": {
        "Type": "vxlan",
        # MTU 최적화 (AWS는 9001)
        "VNI": 1,
        "Port": 8472,
        "MTU": 1450
      }
    }

모니터링

# Calico 메트릭
kubectl top pods -n kube-system | grep calico

# Flannel 로그 확인
kubectl logs -n kube-system -l app=flannel

# 네트워크 연결성 테스트
kubectl run test-pod --image=nicolaka/netshoot --rm -it -- /bin/bash

자주 묻는 질문 (FAQ)

Q1: eBPF를 사용하려면 특별한 커널이 필요한가요?

A: 네, Linux Kernel 4.9 이상이 필요하며, 최상의 성능을 위해서는 5.3 이상을 권장합니다.

# 커널 버전 확인
uname -r

# eBPF 지원 확인
kubectl exec -it -n kube-system <calico-node-pod> -- bpftool prog show

Q2: Flannel에서 네트워크 정책이 정말 필요 없나요?

A: 필요하다면 Calico와 함께 사용할 수 있습니다!

# Flannel + Calico 정책 엔진 조합
kubectl apply -f https://docs.projectcalico.org/manifests/canal.yaml

Q3: 비용 차이는 얼마나 나나요?

100 노드 클러스터 기준

Flannel:
- 메모리: 200MB × 100 = 20GB
- 월 비용: 약 $30

Calico:
- 메모리: 350MB × 100 = 35GB
- 월 비용: 약 $52

차이: $22/월 (75% 증가)

하지만 Calico의 성능 개선으로 노드 수를 줄일 수 있다면 오히려 절약!

Q4: 마이그레이션 중 다운타임은 얼마나 되나요?

Single Cluster: 10-30분
Blue-Green 방식: 0분 (무중단)

Q5: 어떤 클라우드 환경에서 잘 작동하나요?

결론

핵심 요약

🧣 Flannel을 선택하세요

• ✅ 빠르게 시작하고 싶을 때
• ✅ 팀이 작고 운영 리소스가 제한적일 때
• ✅ 개발/테스트 환경
• ✅ 네트워크 정책이 필요 없을 때
• ✅ 중소규모 프로덕션 (< 50 노드)

🐱 Calico를 선택하세요

• ✅ 네트워크 보안이 중요할 때
• ✅ 대규모 프로덕션 환경
• ✅ 멀티 클라우드/하이브리드 클라우드
• ✅ 컴플라이언스 요구사항이 있을 때
• ✅ 고성능이 필요할 때 (eBPF)
• ✅ 마이크로서비스 간 세밀한 제어가 필요할 때

💡 최고의 전략

Phase 1 (스타트업): Flannel
  → 빠른 출시, 시장 검증

Phase 2 (성장기): Flannel 유지
  → 안정적 운영, 기능 개발 집중

Phase 3 (스케일업): Calico로 마이그레이션
  → 엔터프라이즈 요구사항 대응

Phase 4 (엔터프라이즈): Calico 고도화
  → eBPF, BGP, 멀티 클라우드

마지막 조언

"완벽한 CNI는 없습니다. 여러분의 현재 상황과 미래 계획에 맞는 CNI를 선택하세요."

• 지금 당장 필요한 것과
• 6개월 후 필요할 것을
• 균형있게 고려하세요

참고 자료

공식 문서

• Calico 공식 문서
• Flannel GitHub
• eBPF 공식 사이트
• Kubernetes 네트워킹 가이드

추가 학습

• eBPF Summit 발표 영상
• Calico 성능 벤치마크 보고서
• CNI 플러그인 비교 블로그

마치며

이 글이 CNI 선택에 도움이 되었기를 바랍니다!

궁금한 점이나 실전 경험을 공유하고 싶으시다면 댓글로 남겨주세요. 함께 배우고 성장합시다!

Happy Networking!

들어가며

AWS에서 로드밸런서를 선택할 때 ALB(Application Load Balancer)와 NLB(Network Load Balancer) 중 어떤 것을 선택해야 할까요? 단순히 L7과 L4의 차이로만 이해하고 있다면, 실제 운영에서 예상치 못한 문제를 만날 수 있습니다. 이 글에서는 두 로드밸런서의 근본적인 차이와 실제 사용 사례를 깊이 있게 다루겠습니다.

핵심 차이점: 아키텍처 관점

NLB: 패킷 포워딩 머신

NLB는 OSI 4계층(Transport Layer)에서 작동하는 고성능 패킷 포워더입니다. 패킷의 내용을 해석하지 않고 헤더 정보만으로 라우팅하기 때문에 극도로 빠른 성능을 보장합니다.

# NLB 동작 원리
Client Packet → NLB → Target Server
              (패킷 헤더만 수정)

지연시간: ~100 마이크로초
처리량: 초당 수백만 패킷

ALB: HTTP 전문 처리기

ALB는 OSI 7계층(Application Layer)에서 동작하며, HTTP/HTTPS 트래픽을 완전히 해석하고 처리합니다. Connection Termination을 수행하여 클라이언트와 서버 간 연결을 분리합니다.

# ALB 동작 원리
Client → ALB → Target Server
    연결1 종료  새 연결 생성

지연시간: ~10 밀리초 (NLB의 100배)
처리량: 초당 수천~수만 요청

기술적 특징 상세 분석

1. IP 주소 관리

NLB: 고정 IP 지원

# 각 AZ마다 고정 Network Interface 생성
AZ-1: 10.0.1.100 (Elastic IP 할당 가능)
AZ-2: 10.0.2.100 (Elastic IP 할당 가능)

# 방화벽 규칙 설정 용이
firewall-rule --allow-from 10.0.1.100

ALB: 동적 IP만 지원

# DNS 이름으로만 접근
myalb-123456.elb.amazonaws.com
# IP는 자동 스케일링에 따라 수시로 변경

2. Connection 처리 방식

NLB: Connection Tracking

# 5-tuple 해시 기반 라우팅
connection_table = {
    (src_ip, src_port, dst_ip, dst_port, protocol): target_server
}

# TCP 연결 유지 시간
- Active: 350초 (기본값, 최대 86400초)
- UDP Flow: 120초
- Connection Draining: 300초

ALB: Request 단위 라우팅

// 라우팅 규칙 예시
if (path.startsWith("/api")) {
    route_to("api-target-group");
} else if (host === "admin.example.com") {
    route_to("admin-target-group");
} else if (header["X-Mobile-App"] === "true") {
    route_to("mobile-backend");
}

3. 프로토콜 지원

NLB 지원 프로토콜:

• TCP, UDP, TLS
• 모든 포트 (1-65535)
• 비HTTP 프로토콜 (게임, DB, MQTT 등)

ALB 지원 프로토콜:

• HTTP/1.1, HTTP/2, WebSocket
• 포트 제한 (80, 443 등 특정 포트)
• gRPC (HTTP/2 기반)

성능과 비용 비교

성능 벤치마크

테스트 환경: c5.large 인스턴스 10대, 1KB 페이로드

NLB 결과:
- Latency P50: 0.1ms
- Latency P99: 0.5ms
- Throughput: 3,000,000 req/sec
- CPU Usage: 5%

ALB 결과:
- Latency P50: 10ms
- Latency P99: 50ms
- Throughput: 50,000 req/sec
- CPU Usage: 25%

비용 구조

NLB 비용 (us-east-1):
- 시간당: $0.0225
- NLCU당: $0.006
- Cross-AZ 트래픽: 선택적 (비활성화 가능)

ALB 비용 (us-east-1):
- 시간당: $0.0225
- LCU당: $0.008
- 평가 기준: 새 연결, 활성 연결, 처리량, 규칙 평가

실전 사용 사례

사례 1: 게임 서비스 아키텍처

# 실시간 게임 서버
Game Client → NLB (Port 3000) → Game Server
이유:
- TCP 소켓 연결 유지 필수
- 초저지연 요구 (10ms 이하)
- Source IP 보존으로 핵 탐지

# 게임 API 서버
Mobile App → ALB → REST API
이유:
- Path 기반 라우팅 (/v1/*, /v2/*)
- HTTP/2로 다중 요청 처리
- 점진적 배포 (Canary)

사례 2: 금융 서비스 아키텍처

# 거래 시스템
Trading System → NLB → FIX Gateway
이유:
- 고정 IP 필수 (규제 요구사항)
- Ultra-low latency (< 1ms)
- Non-HTTP 프로토콜 (FIX)

# 뱅킹 웹/앱
Customer → ALB → Banking API
이유:
- Host 기반 멀티 테넌시
- WAF 통합 보안
- 상세한 액세스 로그

사례 3: 하이브리드 패턴

# ALB + NLB 조합
External → NLB (고정 IP) → ALB (L7 라우팅) → Services

장점:
- 고정 IP 요구사항 충족
- L7 라우팅 기능 활용
- 단계별 트래픽 제어

구현:
aws elbv2 create-target-group \
  --target-type alb \
  --targets Id=arn:aws:elasticloadbalancing:...

Target 장애 시 동작 차이

NLB의 Connection Persistence

def handle_unhealthy_target():
    """
    NLB는 기존 연결을 유지하려 함
    """
    if existing_connection:
        # Health Check 실패해도 기존 연결은 유지
        continue_routing_to_unhealthy_target()
        # Client가 RST 받고 재연결 시도해야 함
    else:
        # 새 연결만 건강한 타겟으로
        route_to_healthy_target()

ALB의 즉각적 재라우팅

def handle_unhealthy_target():
    """
    ALB는 즉시 다른 타겟으로 전환
    """
    # 모든 새 요청을 건강한 타겟으로
    healthy_targets = get_healthy_targets()
    route_to(random.choice(healthy_targets))

모니터링과 디버깅

NLB 모니터링 포인트

주요 메트릭:
- ActiveFlowCount: 활성 연결 수
- NewFlowCount: 초당 새 연결
- ProcessedBytes: 처리된 데이터량
- TargetTLSNegotiationErrors: TLS 핸드셰이크 실패

로깅:
- Flow Logs만 지원 (Connection 레벨)
- 패킷 내용은 볼 수 없음

ALB 모니터링 포인트

주요 메트릭:
- RequestCount: HTTP 요청 수
- TargetResponseTime: 응답 시간
- HTTPCode_Target_4XX_Count: 4xx 에러
- HTTPCode_Target_5XX_Count: 5xx 에러

로깅:
- Access Logs (상세한 HTTP 정보)
- 모든 헤더, 경로, 응답 코드 기록

선택 가이드라인

NLB를 선택해야 할 때

1. 초저지연이 필수인 경우 (< 1ms)
2. 고정 IP가 필요한 경우
3. Non-HTTP 프로토콜 사용
4. 극한의 처리량 필요 (millions/sec)
5. Source IP 보존 필요

ALB를 선택해야 할 때

1. HTTP/HTTPS 트래픽 전용
2. Path/Host 기반 라우팅 필요
3. WebSocket, HTTP/2 지원 필요
4. WAF 통합 필요
5. 상세한 모니터링/로깅 필요

마무리

ALB와 NLB는 각각의 강점이 명확한 서비스입니다. 단순히 L7과 L4의 차이로 이해하기보다는, 실제 워크로드의 특성과 요구사항을 정확히 파악하여 선택해야 합니다.

특히 최근에는 마이크로서비스 아키텍처에서 ALB를, 컨테이너 서비스 메시에서 NLB를 조합하여 사용하는 하이브리드 패턴이 늘어나고 있습니다. 각 로드밸런서의 특성을 정확히 이해하고 있다면, 더 효율적이고 안정적인 아키텍처를 설계할 수 있을 것입니다.

프로젝트 개요

단일 Terraform 모듈과 Terragrunt를 활용하여 Stage/Production 환경을 동일한 코드로 관리하며, GitHub Actions 기반 GitOps 파이프라인으로 인프라 배포 시간을 80% 단축하고 환경 간 불일치로 인한 장애를 Zero로 만든 프로젝트입니다. 7개 팀, 30명이 사용하는 플랫폼의 인프라를 안전하고 효율적으로 운영할 수 있는 체계를 구축했습니다.

핵심 성과

• 코드 중복 95% 제거 (DRY 원칙 완벽 구현)
• 배포 시간 80% 단축 (수동 48시간 → 자동 7.2시간)
• Production 장애율 90% 감소 (Stage 검증 효과)
• 인프라 관리 인력 66% 절감 (3명 → 1명)
• 환경 불일치 장애 Zero (동일 코드 기반)

시스템 아키텍처

전체 구조도

디렉토리 구조

infrastructure/
├── terragrunt.hcl              # 루트 설정 (S3 백엔드, DynamoDB 락)
├── modules/
│   └── application/            # 단일 Terraform 모듈
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       ├── vpc.tf              # 네트워크 리소스
│       ├── ecs.tf              # 컨테이너 오케스트레이션
│       ├── alb.tf              # 로드 밸런싱
│       ├── rds.tf              # 데이터베이스
│       ├── security_groups.tf  # 보안 설정
│       └── monitoring.tf       # CloudWatch 알람
├── stage/
│   └── terragrunt.hcl          # Stage 환경 변수
└── prod/
    └── terragrunt.hcl          # Production 환경 변수

핵심 구현 내용

1. Terraform 모듈화와 Terragrunt DRY 원칙 구현

기존 방식의 문제점

# stage/ecs.tf - 200줄의 코드
resource "aws_ecs_service" "app" {
  name            = "app-stage"
  cluster         = "stage-cluster"
  task_definition = "app-stage:latest"
  desired_count   = 2
  # ... 수많은 중복 설정
}

# prod/ecs.tf - 동일한 200줄의 코드 (값만 다름)
resource "aws_ecs_service" "app" {
  name            = "app-prod"
  cluster         = "prod-cluster"
  task_definition = "app-prod:latest"
  desired_count   = 4
  # ... 동일한 중복 설정
}

Terragrunt 도입 후 개선

# modules/application/ecs.tf (단일 모듈 - 한 번만 작성)
resource "aws_ecs_service" "app" {
  name            = "${var.environment}-app"
  cluster         = var.cluster_name
  task_definition = "${var.app_name}:${var.app_version}"
  desired_count   = var.desired_count

  deployment_configuration {
    maximum_percent         = var.deployment_maximum_percent
    minimum_healthy_percent = var.deployment_minimum_healthy_percent
  }

  # 환경별 Auto Scaling 설정
  dynamic "capacity_provider_strategy" {
    for_each = var.capacity_providers
    content {
      capacity_provider = capacity_provider_strategy.value.name
      weight           = capacity_provider_strategy.value.weight
    }
  }
}

# stage/terragrunt.hcl - 환경별 변수만 정의
inputs = {
  environment                    = "stage"
  desired_count                  = 2
  instance_type                  = "t3.small"
  deployment_maximum_percent     = 200
  deployment_minimum_healthy_percent = 50

  capacity_providers = [{
    name   = "FARGATE_SPOT"
    weight = 100  # Stage는 비용 최적화
  }]
}

# prod/terragrunt.hcl
inputs = {
  environment                    = "production"
  desired_count                  = 4
  instance_type                  = "t3.large"
  deployment_maximum_percent     = 150
  deployment_minimum_healthy_percent = 100

  capacity_providers = [{
    name   = "FARGATE"
    weight = 100  # Production은 안정성 우선
  }]
}

2. GitHub Actions GitOps 파이프라인

Stage 환경 - 자동 배포 워크플로우

name: Terraform Stage Deployment

on:
  pull_request:
    branches: [dev]
    paths:
      - 'terragrunt/stage/**'
      - 'terragrunt/modules/**'
  push:
    branches: [dev]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID_STAGE }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY_STAGE }}
          aws-region: ap-northeast-2

      - name: Setup Terragrunt
        uses: autero1/action-terragrunt@v1.2.0
        with:
          terragrunt_version: 0.45.0
          terraform_version: 1.2.0

      - name: Clean Cache
        run: |
          find . -type d -name ".terragrunt-cache" -exec rm -rf {} + 2>/dev/null || true
          find . -type d -name ".terraform" -exec rm -rf {} + 2>/dev/null || true

      - name: Terragrunt Plan
        if: github.event_name == 'pull_request'
        id: plan
        run: |
          cd terragrunt/stage
          terragrunt plan -no-color -out=tfplan
          terragrunt show -no-color tfplan > plan_output.txt

      - name: Post Plan to PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const planOutput = fs.readFileSync('terragrunt/stage/plan_output.txt', 'utf8');

            const truncatedPlan = planOutput.length > 60000 
              ? planOutput.substring(0, 60000) + '\n\n... (truncated)'
              : planOutput;

            const comment = `## 📋 Terraform Plan - Stage Environment

            <details>
            <summary>Click to expand plan details</summary>

            \`\`\`terraform
            ${truncatedPlan}
            \`\`\`
            </details>

            ✅ Review the changes above before merging.`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });

      - name: Terragrunt Apply
        if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
        run: |
          cd terragrunt/stage
          terragrunt apply --terragrunt-non-interactive -auto-approve

Production 환경 - 승인 기반 배포

name: Terraform Production Deployment

on:
  workflow_dispatch:
    inputs:
      action:
        description: 'Terraform action to perform'
        required: true
        default: 'plan'
        type: choice
        options:
          - plan
          - apply
      confirm:
        description: 'Type "yes" to confirm PRODUCTION deployment'
        required: false
        type: string

jobs:
  terraform:
    runs-on: ubuntu-latest
    environment: production  # GitHub Environment 보호 규칙 적용

    steps:
      - name: Validate Production Deployment
        if: inputs.action == 'apply'
        run: |
          if [[ "${{ inputs.confirm }}" != "yes" ]]; then
            echo "❌ Production deployment requires explicit confirmation"
            echo "Please type 'yes' in the confirm field to proceed"
            exit 1
          fi

      - name: Configure Production AWS Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID_PROD }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY_PROD }}
          aws-region: ap-northeast-2

      - name: Production Apply with Double Confirmation
        if: inputs.action == 'apply' && inputs.confirm == 'yes'
        run: |
          cd terragrunt/prod

          # 변경사항 재확인
          echo "🔍 Reviewing changes before production deployment..."
          terragrunt plan -detailed-exitcode

          # 실제 적용
          echo "🚀 Applying to PRODUCTION environment..."
          terragrunt apply --terragrunt-non-interactive -auto-approve

          # 배포 후 검증
          echo "✅ Validating deployment..."
          terragrunt output -json > deployment_result.json

3. 상태 관리와 동시성 제어

# terragrunt.hcl (루트 설정)
remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite_terragrunt"
  }
  config = {
    bucket         = "terraform-state-${get_aws_account_id()}"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "ap-northeast-2"
    encrypt        = true

    # DynamoDB 테이블을 통한 상태 잠금
    dynamodb_table = "terraform-state-locks"

    # 버전 관리 활성화
    versioning = {
      enabled = true
    }

    # 실수로 인한 삭제 방지
    lifecycle {
      prevent_destroy = true
    }
  }
}

# 환경별 태그 자동 추가
inputs = {
  tags = {
    Environment = basename(get_terragrunt_dir())
    ManagedBy   = "Terragrunt"
    Repository  = "infrastructure-as-code"
    LastUpdated = timestamp()
  }
}

성능 및 효과

배포 메트릭 비교

Stage → Production 배포 안정성

graph LR
    A[코드 변경] --> B[Stage 배포]
    B --> C{테스트 통과?}
    C -->|Yes| D[Production 배포]
    C -->|No| E[수정 후 재배포]
    D --> F[성공률 99%]

    style F fill:#90EE90

실제 운영 결과:

• Stage 테스트 통과 후 Production 배포 성공률: 99%
• 환경 차이로 인한 장애: Zero
• 평균 복구 시간(MTTR): 30분 → 3분

트러블슈팅 경험

1. Terragrunt 캐시 충돌 문제

문제: 병렬 실행 시 .terragrunt-cache 디렉토리 충돌

Error: Error acquiring the state lock

해결:

# 각 실행 전 캐시 정리
find . -type d -name ".terragrunt-cache" -exec rm -rf {} + 2>/dev/null || true

# Terragrunt 병렬 실행 제한
export TERRAGRUNT_PARALLELISM=1

2.Production 배포 실수 방지

문제: 실수로 Production에 잘못된 변경 적용 위험

해결:

• GitHub Environment Protection Rules 적용
• 수동 승인 프로세스 필수화
• confirm: yes 이중 확인 메커니즘

교훈과 베스트 프랙티스

1. DRY 원칙은 필수가 아닌 생존 전략

코드 중복은 단순히 유지보수의 문제가 아니라 환경 간 불일치로 인한 장애의 근본 원인입니다. Terragrunt를 통한 DRY 원칙 구현으로:

• 버그 수정이 모든 환경에 자동 반영
• 새로운 기능 추가 시간 75% 단축
• 환경별 설정 실수 Zero

2. GitOps는 신뢰의 기반

# 모든 변경사항의 투명성 확보
- Pull Request로 변경사항 사전 검토
- Plan 결과를 PR 코멘트로 자동 공유
- 팀 전체가 인프라 변경 인지 가능

3. 환경별 차이는 최소한으로

# 환경 간 차이는 오직 이것뿐
locals {
  environment_config = {
    stage = {
      instance_count = 2
      instance_type  = "t3.small"
      backup_enabled = false
    }
    production = {
      instance_count = 4
      instance_type  = "t3.large"
      backup_enabled = true
    }
  }
}

프로젝트 성과 요약

Terraform 모듈화와 Terragrunt의 결합은 단순한 기술 도입을 넘어 인프라 관리 패러다임의 전환을 가져왔습니다. 특히 "Stage에서 검증된 것은 Production에서도 반드시 작동한다"는 확신은 팀의 배포 속도와 안정성을 동시에 향상시켰습니다.

GitHub Actions를 통한 GitOps 파이프라인은 이 모든 프로세스를 투명하고 안전하게 만들어, 주니어 개발자도 자신있게 인프라를 변경할 수 있는 환경을 조성했습니다.

다음 단계

1. Policy as Code: OPA(Open Policy Agent)를 통한 정책 자동화
2. Cost Optimization: FinOps 원칙 적용한 비용 최적화
3. Multi-Region: 글로벌 서비스를 위한 다중 리전 확장

본 포스트는 실제 프로젝트 경험을 바탕으로 작성되었으며, 보안을 위해 일부 세부 정보는 일반화하여 표현했습니다.

기술 스택: Terraform, Terragrunt, GitHub Actions, AWS (ECS Fargate, RDS, ALB), CloudWatch

#Terraform #Terragrunt #GitOps #DevOps #IaC #AWS #GitHubActions #DRY

기존 Docker Registry에서 엔터프라이즈급 Harbor 플랫폼으로 전환하며, Harbor의 내장 Registry 기능을 활용한 자동 마이그레이션과 재해복구 체계를 구축한 프로젝트입니다. 7개 팀, 30명의 사용자가 사용하는 AI/ML 플랫폼의 컨테이너 레지스트리를 무중단으로 전환했습니다.

핵심 성과

• 마이그레이션 시간 85% 단축 (Harbor Registry 기능 활용)
• 무중단 전환 달성 (Zero Downtime)
• 자동 백업 체계 구축 (DockerHub 복제 정책)
• 보안 강화 (Trivy 취약점 자동 스캔)
• 연간 $2,880 비용 절감 (Docker Hub 대비)

시스템 아키텍처

Harbor 플랫폼 구성

Infrastructure:
  - Kubernetes: v1.28
  - Harbor: v2.6.0
  - Storage: 300GB (PersistentVolume)
  - Nodes: 7대 분산 배포
  - TLS: 자체 서명 인증서

Core Components:
  - Harbor Core: API 서버, 비즈니스 로직
  - Harbor Portal: 웹 UI
  - Harbor Registry: Docker Registry v2
  - Harbor JobService: 비동기 작업 처리
  - PostgreSQL: 메타데이터 저장
  - Redis: 세션 캐시
  - Trivy: 취약점 스캐너

멀티 테넌시 구조

Harbor Platform
├── Team Projects (10개)
│   ├── team1-dev / team1-prod
│   ├── team2-dev / team2-prod
│   ├── team3-dev / team3-prod
│   ├── team4-dev / team4-prod
│   └── team5-dev / team5-prod
├── Common Resources
│   ├── base-images
│   └── shared-libraries
└── DockerHub Proxy
    └── cached-images

핵심 구현 내용

1. Harbor Registry API를 활용한 스크립트 기반 마이그레이션

Registry Endpoint 등록 및 복제 스크립트

#!/bin/bash
"""
Harbor Registry API를 활용한 마이그레이션 스크립트
기존 Docker Registry를 Harbor에 등록하고 복제 정책 생성
"""

# 색상 설정
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Harbor 설정
HARBOR_URL="https://harbor.internal:30443"
HARBOR_USER="admin"
HARBOR_PASS="${HARBOR_PASSWORD}"

# 소스 레지스트리 설정
SOURCE_REGISTRY="legacy-registry.internal:5000"

echo -e "${BLUE}========================================${NC}"
echo -e "${BLUE}Harbor Registry 마이그레이션 시작${NC}"
echo -e "${BLUE}========================================${NC}"

# 1. 소스 레지스트리를 Harbor에 엔드포인트로 등록
register_source_registry() {
    echo -e "${YELLOW}1. 소스 레지스트리 등록 중...${NC}"

    REGISTRY_RESPONSE=$(curl -k -s -X POST \
        -u "${HARBOR_USER}:${HARBOR_PASS}" \
        -H "Content-Type: application/json" \
        "${HARBOR_URL}/api/v2.0/registries" \
        -d "{
            \"name\": \"legacy-docker-registry\",
            \"type\": \"docker-registry\",
            \"url\": \"${SOURCE_REGISTRY}\",
            \"description\": \"기존 Docker Registry (마이그레이션 소스)\",
            \"insecure\": true,
            \"credential\": {
                \"type\": \"basic\",
                \"access_key\": \"\",
                \"access_secret\": \"\"
            }
        }")

    # Registry ID 조회
    REGISTRY_ID=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
        "${HARBOR_URL}/api/v2.0/registries" | \
        jq -r '.[] | select(.name=="legacy-docker-registry") | .id')

    echo -e "${GREEN}✅ 레지스트리 등록 완료: ID=${REGISTRY_ID}${NC}"
    echo $REGISTRY_ID
}

# 2. 팀별 복제 정책 생성
create_team_replication_policies() {
    local REGISTRY_ID=$1

    echo -e "${YELLOW}2. 팀별 복제 정책 생성 중...${NC}"

    # 팀 프로젝트 배열
    TEAM_PROJECTS=(
        "team1-dev"
        "team1-prod"
        "team2-dev"
        "team2-prod"
        "team3-dev"
        "team3-prod"
        "team4-dev"
        "team4-prod"
        "team5-dev"
        "team5-prod"
    )

    POLICY_IDS=()

    for PROJECT in "${TEAM_PROJECTS[@]}"; do
        echo -n "  ${PROJECT} 정책 생성..."

        POLICY_RESPONSE=$(curl -k -s -X POST \
            -u "${HARBOR_USER}:${HARBOR_PASS}" \
            -H "Content-Type: application/json" \
            "${HARBOR_URL}/api/v2.0/replication/policies" \
            -d "{
                \"name\": \"migrate-${PROJECT}\",
                \"description\": \"Migration policy for ${PROJECT}\",
                \"src_registry\": {
                    \"id\": ${REGISTRY_ID}
                },
                \"dest_registry\": null,
                \"dest_namespace\": \"${PROJECT}\",
                \"filters\": [
                    {
                        \"type\": \"name\",
                        \"value\": \"${PROJECT}/**\"
                    }
                ],
                \"trigger\": {
                    \"type\": \"manual\"
                },
                \"enabled\": true,
                \"deletion\": false,
                \"override\": true,
                \"speed\": -1
            }")

        # Policy ID 추출
        POLICY_ID=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
            "${HARBOR_URL}/api/v2.0/replication/policies" | \
            jq -r ".[] | select(.name==\"migrate-${PROJECT}\") | .id")

        if [ -n "$POLICY_ID" ]; then
            POLICY_IDS+=($POLICY_ID)
            echo -e " ${GREEN}✅ (ID: ${POLICY_ID})${NC}"
        else
            echo -e " ${RED}❌${NC}"
        fi
    done

    echo "${POLICY_IDS[@]}"
}

# 3. 병렬 복제 실행
execute_parallel_replication() {
    local POLICY_IDS=($@)

    echo -e "${YELLOW}3. 병렬 복제 실행 중...${NC}"

    EXECUTION_IDS=()

    # 모든 정책을 동시에 실행
    for POLICY_ID in "${POLICY_IDS[@]}"; do
        echo -n "  정책 ${POLICY_ID} 실행..."

        EXEC_RESPONSE=$(curl -k -s -X POST \
            -u "${HARBOR_USER}:${HARBOR_PASS}" \
            -H "Content-Type: application/json" \
            "${HARBOR_URL}/api/v2.0/replication/executions" \
            -d "{\"policy_id\": ${POLICY_ID}}")

        # Execution ID 추출
        EXEC_ID=$(curl -k -s -X POST \
            -u "${HARBOR_USER}:${HARBOR_PASS}" \
            -H "Content-Type: application/json" \
            -d "{\"policy_id\": ${POLICY_ID}}" \
            -I "${HARBOR_URL}/api/v2.0/replication/executions" | \
            grep -i location | sed 's/.*\/\([0-9]*\).*/\1/' | tr -d '\r')

        if [ -n "$EXEC_ID" ]; then
            EXECUTION_IDS+=($EXEC_ID)
            echo -e " ${GREEN}✅ (Execution ID: ${EXEC_ID})${NC}"
        else
            echo -e " ${RED}❌${NC}"
        fi
    done

    echo "${EXECUTION_IDS[@]}"
}

# 4. 복제 진행 상황 모니터링
monitor_replication_progress() {
    local EXECUTION_IDS=($@)

    echo -e "${YELLOW}4. 복제 진행 상황 모니터링...${NC}"

    while true; do
        ALL_COMPLETED=true
        TOTAL_SUCCESS=0
        TOTAL_FAILED=0
        TOTAL_PROGRESS=0

        echo -e "\n${BLUE}현재 복제 상태:${NC}"

        for EXEC_ID in "${EXECUTION_IDS[@]}"; do
            STATUS_INFO=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
                "${HARBOR_URL}/api/v2.0/replication/executions/${EXEC_ID}")

            STATUS=$(echo "$STATUS_INFO" | jq -r '.status')
            TOTAL=$(echo "$STATUS_INFO" | jq -r '.total // 0')
            SUCCESS=$(echo "$STATUS_INFO" | jq -r '.success_task_count // 0')
            FAILED=$(echo "$STATUS_INFO" | jq -r '.failed_task_count // 0')

            case $STATUS in
                "InProgress")
                    echo "  Execution ${EXEC_ID}: 🔄 진행 중 (${SUCCESS}/${TOTAL})"
                    ALL_COMPLETED=false
                    TOTAL_PROGRESS=$((TOTAL_PROGRESS + 1))
                    ;;
                "Succeed")
                    echo "  Execution ${EXEC_ID}: ✅ 완료 (${SUCCESS} 이미지)"
                    TOTAL_SUCCESS=$((TOTAL_SUCCESS + SUCCESS))
                    ;;
                "Failed")
                    echo "  Execution ${EXEC_ID}: ❌ 실패 (성공: ${SUCCESS}, 실패: ${FAILED})"
                    TOTAL_FAILED=$((TOTAL_FAILED + FAILED))
                    ;;
                *)
                    echo "  Execution ${EXEC_ID}: 📊 ${STATUS}"
                    ALL_COMPLETED=false
                    ;;
            esac
        done

        echo -e "\n${BLUE}전체 진행 상황:${NC}"
        echo "  성공한 이미지: ${TOTAL_SUCCESS}개"
        echo "  실패한 이미지: ${TOTAL_FAILED}개"
        echo "  진행 중인 작업: ${TOTAL_PROGRESS}개"

        if $ALL_COMPLETED; then
            echo -e "\n${GREEN}🎉 모든 복제 작업이 완료되었습니다!${NC}"
            break
        fi

        echo -e "\n30초 후 다시 확인..."
        sleep 30
    done
}

# 메인 실행 로직
main() {
    # 1. 소스 레지스트리 등록
    REGISTRY_ID=$(register_source_registry)

    # 2. 팀별 복제 정책 생성
    POLICY_IDS=($(create_team_replication_policies $REGISTRY_ID))

    # 3. 병렬 복제 실행
    EXECUTION_IDS=($(execute_parallel_replication "${POLICY_IDS[@]}"))

    # 4. 진행 상황 모니터링
    monitor_replication_progress "${EXECUTION_IDS[@]}"

    # 5. 최종 결과 요약
    echo -e "\n${BLUE}========================================${NC}"
    echo -e "${BLUE}마이그레이션 완료${NC}"
    echo -e "${BLUE}========================================${NC}"
    echo "총 프로젝트: ${#POLICY_IDS[@]}개"
    echo "실행된 작업: ${#EXECUTION_IDS[@]}개"
}

# 스크립트 실행
main

2. DockerHub 백업 복제 스크립트

Harbor API를 통한 자동 백업 구성

#!/bin/bash
"""
DockerHub 백업 복제 정책 설정 스크립트
Production 이미지를 DockerHub에 자동 복제
"""

# 색상 설정
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Harbor 정보
HARBOR_URL="https://harbor.internal:30443"
HARBOR_USER="admin"
HARBOR_PASS="${HARBOR_PASSWORD}"

# DockerHub 정보
DOCKERHUB_USER="company-backup"
DOCKERHUB_TOKEN="${DOCKERHUB_TOKEN}"

echo -e "${BLUE}========================================${NC}"
echo -e "${BLUE}DockerHub 백업 복제 설정${NC}"
echo -e "${BLUE}========================================${NC}"

# 1. 기존 복제 정책 정리
cleanup_existing_policies() {
    echo -e "${YELLOW}1. 기존 복제 정책 삭제...${NC}"

    # DockerHub 백업 관련 정책 조회 및 삭제
    POLICIES=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
        "${HARBOR_URL}/api/v2.0/replication/policies" | \
        jq -r '.[] | select(.name | contains("dockerhub-backup")) | .id')

    for POLICY_ID in $POLICIES; do
        echo "  복제 정책 삭제 중: ID=$POLICY_ID"
        curl -k -X DELETE -u "${HARBOR_USER}:${HARBOR_PASS}" \
            "${HARBOR_URL}/api/v2.0/replication/policies/${POLICY_ID}"
        echo -e "  ${GREEN}✅ 정책 ${POLICY_ID} 삭제됨${NC}"
    done
}

# 2. DockerHub Registry Endpoint 생성
create_dockerhub_endpoint() {
    echo -e "${YELLOW}2. DockerHub Registry Endpoint 생성...${NC}"

    ENDPOINT_RESPONSE=$(curl -k -s -X POST \
        -u "${HARBOR_USER}:${HARBOR_PASS}" \
        -H "Content-Type: application/json" \
        "${HARBOR_URL}/api/v2.0/registries" \
        -d "{
            \"name\": \"dockerhub\",
            \"type\": \"docker-hub\",
            \"url\": \"https://index.docker.io\",
            \"insecure\": false,
            \"credential\": {
                \"type\": \"basic\",
                \"access_key\": \"${DOCKERHUB_USER}\",
                \"access_secret\": \"${DOCKERHUB_TOKEN}\"
            },
            \"description\": \"Docker Hub registry for production backup\"
        }")

    # 생성된 엔드포인트 ID 가져오기
    REGISTRY_ID=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
        "${HARBOR_URL}/api/v2.0/registries" | \
        jq -r '.[] | select(.name=="dockerhub") | .id')

    echo -e "${GREEN}✅ Docker Hub 엔드포인트가 생성되었습니다. (ID: ${REGISTRY_ID})${NC}"
    echo $REGISTRY_ID
}

# 3. Production 프로젝트별 백업 정책 생성
create_backup_policies() {
    local REGISTRY_ID=$1

    echo -e "${YELLOW}3. Production 프로젝트 백업 정책 생성...${NC}"

    # Production 프로젝트 배열
    PROD_PROJECTS=(
        "team1-prod"
        "team2-prod"
        "team3-prod"
        "team4-prod"
        "team5-prod"
    )

    for PROJECT in "${PROD_PROJECTS[@]}"; do
        echo -n "  ${PROJECT} 백업 정책 생성..."

        POLICY_RESPONSE=$(curl -k -s -X POST \
            -u "${HARBOR_USER}:${HARBOR_PASS}" \
            -H "Content-Type: application/json" \
            "${HARBOR_URL}/api/v2.0/replication/policies" \
            -d "{
                \"name\": \"dockerhub-backup-${PROJECT}\",
                \"description\": \"Backup ${PROJECT} images to Docker Hub\",
                \"src_registry\": null,
                \"dest_registry\": {
                    \"id\": ${REGISTRY_ID}
                },
                \"dest_namespace\": \"${DOCKERHUB_USER}\",
                \"dest_namespace_replace_count\": 1,
                \"filters\": [
                    {
                        \"type\": \"name\",
                        \"value\": \"${PROJECT}/**\"
                    },
                    {
                        \"type\": \"tag\",
                        \"value\": \"{v*.*.*,latest}\"
                    }
                ],
                \"trigger\": {
                    \"type\": \"event_based\"
                },
                \"enabled\": true,
                \"deletion\": false,
                \"override\": true,
                \"speed\": -1
            }")

        # Policy ID 확인
        POLICY_ID=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
            "${HARBOR_URL}/api/v2.0/replication/policies" | \
            jq -r ".[] | select(.name==\"dockerhub-backup-${PROJECT}\") | .id")

        if [ -n "$POLICY_ID" ]; then
            echo -e " ${GREEN}✅ (ID: ${POLICY_ID})${NC}"
        else
            echo -e " ${RED}❌${NC}"
        fi
    done
}

# 4. 테스트 복제 실행
test_backup_replication() {
    echo -e "${YELLOW}4. 테스트 복제 실행...${NC}"

    # 첫 번째 정책으로 테스트
    TEST_POLICY_ID=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
        "${HARBOR_URL}/api/v2.0/replication/policies" | \
        jq -r '.[] | select(.name | startswith("dockerhub-backup-")) | .id' | head -1)

    if [ -n "$TEST_POLICY_ID" ]; then
        echo "  테스트 정책 ID: ${TEST_POLICY_ID}"

        EXEC_RESPONSE=$(curl -k -s -X POST \
            -u "${HARBOR_USER}:${HARBOR_PASS}" \
            -H "Content-Type: application/json" \
            "${HARBOR_URL}/api/v2.0/replication/executions" \
            -d "{\"policy_id\": ${TEST_POLICY_ID}}")

        echo -e "${GREEN}✅ 테스트 복제가 시작되었습니다.${NC}"

        # 복제 상태 확인
        monitor_test_replication
    fi
}

# 5. 복제 상태 모니터링
monitor_test_replication() {
    echo -e "${YELLOW}5. 복제 상태 확인 (60초 대기)...${NC}"

    for i in {1..12}; do
        sleep 5

        STATUS=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
            "${HARBOR_URL}/api/v2.0/replication/executions?policy_id=${TEST_POLICY_ID}&page_size=1" | \
            jq -r '.[0].status')

        echo "  상태 확인 ($i/12): $STATUS"

        if [ "$STATUS" = "Succeed" ]; then
            echo -e "${GREEN}✅ 복제가 성공적으로 완료되었습니다!${NC}"

            # 상세 정보 표시
            EXEC_INFO=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
                "${HARBOR_URL}/api/v2.0/replication/executions?policy_id=${TEST_POLICY_ID}&page_size=1" | \
                jq -r '.[0]')

            echo "  성공: $(echo $EXEC_INFO | jq -r '.success_task_count // 0')개"
            echo "  실패: $(echo $EXEC_INFO | jq -r '.failed_task_count // 0')개"
            break

        elif [ "$STATUS" = "Failed" ]; then
            echo -e "${RED}❌ 복제가 실패했습니다.${NC}"

            # 실패 원인 확인
            EXEC_ID=$(curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
                "${HARBOR_URL}/api/v2.0/replication/executions?policy_id=${TEST_POLICY_ID}&page_size=1" | \
                jq -r '.[0].id')

            echo "실패 원인:"
            curl -k -s -u "${HARBOR_USER}:${HARBOR_PASS}" \
                "${HARBOR_URL}/api/v2.0/replication/executions/${EXEC_ID}/tasks" | \
                jq -r '.[0] | {status: .status, src_resource: .src_resource, dst_resource: .dst_resource}'
            break
        fi
    done
}

# 메인 실행 로직
main() {
    # 1. 기존 정책 정리
    cleanup_existing_policies

    # 2. DockerHub 엔드포인트 생성
    REGISTRY_ID=$(create_dockerhub_endpoint)

    # 3. 백업 정책 생성
    create_backup_policies $REGISTRY_ID

    # 4. 테스트 복제 실행
    test_backup_replication

    echo ""
    echo -e "${BLUE}========================================${NC}"
    echo -e "${BLUE}설정 완료${NC}"
    echo -e "${BLUE}========================================${NC}"
    echo ""
    echo "Docker Hub에서 확인: https://hub.docker.com/r/${DOCKERHUB_USER}"
    echo "이제 Production 프로젝트에 이미지를 Push하면 자동으로 DockerHub에 백업됩니다."
    echo ""
}

# 스크립트 실행
main

3. 병렬 복제 실행 관리

#!/usr/bin/env python3
"""
Harbor 복제 작업 병렬 실행 및 관리
여러 프로젝트를 동시에 마이그레이션
"""

import concurrent.futures
from typing import List, Dict

class ParallelReplicationManager:
    def __init__(self, harbor_url: str, harbor_auth: tuple):
        self.harbor_url = harbor_url
        self.harbor_auth = harbor_auth
        self.api_base = f"{harbor_url}/api/v2.0"

    def execute_parallel_migration(self, policies: List[int], max_workers: int = 5):
        """여러 복제 정책을 병렬로 실행"""

        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
            futures = {}

            # 각 정책별로 복제 실행
            for policy_id in policies:
                future = executor.submit(self._execute_single_replication, policy_id)
                futures[future] = policy_id

            # 결과 수집
            results = []
            for future in concurrent.futures.as_completed(futures):
                policy_id = futures[future]
                try:
                    result = future.result()
                    results.append({
                        'policy_id': policy_id,
                        'status': result['status'],
                        'statistics': result.get('statistics', {})
                    })

                    # 실시간 진행 상황 출력
                    total = result['statistics'].get('total', 0)
                    success = result['statistics'].get('success', 0)
                    failed = result['statistics'].get('failed', 0)

                    print(f"Policy {policy_id}: Total={total}, Success={success}, Failed={failed}")

                except Exception as e:
                    logging.error(f"Policy {policy_id} 실행 실패: {e}")
                    results.append({
                        'policy_id': policy_id,
                        'status': 'failed',
                        'error': str(e)
                    })

            return results

    def _execute_single_replication(self, policy_id: int) -> Dict:
        """단일 복제 정책 실행 및 모니터링"""

        # 복제 시작
        response = requests.post(
            f"{self.api_base}/replication/executions",
            json={"policy_id": policy_id},
            auth=self.harbor_auth
        )

        if response.status_code != 201:
            raise Exception(f"복제 시작 실패: {response.text}")

        execution_id = int(response.headers['Location'].split('/')[-1])

        # 완료까지 대기
        while True:
            exec_response = requests.get(
                f"{self.api_base}/replication/executions/{execution_id}",
                auth=self.harbor_auth
            )

            if exec_response.status_code == 200:
                execution = exec_response.json()

                if execution['status'] in ['Succeeded', 'Failed', 'Stopped']:
                    # 최종 통계 조회
                    tasks_response = requests.get(
                        f"{self.api_base}/replication/executions/{execution_id}/tasks",
                        auth=self.harbor_auth
                    )

                    tasks = tasks_response.json() if tasks_response.status_code == 200 else []

                    return {
                        'status': execution['status'],
                        'statistics': {
                            'total': len(tasks),
                            'success': len([t for t in tasks if t['status'] == 'Succeeded']),
                            'failed': len([t for t in tasks if t['status'] == 'Failed'])
                        }
                    }

            time.sleep(10)

4. 복제 정책 모니터링 대시보드

#!/usr/bin/env python3
"""
Harbor 복제 상태 모니터링 및 리포팅
"""

class ReplicationMonitor:
    def __init__(self, harbor_url: str, harbor_auth: tuple):
        self.harbor_url = harbor_url
        self.harbor_auth = harbor_auth
        self.api_base = f"{harbor_url}/api/v2.0"

    def generate_migration_report(self) -> Dict:
        """마이그레이션 종합 리포트 생성"""

        # 모든 복제 정책 조회
        policies = requests.get(
            f"{self.api_base}/replication/policies",
            auth=self.harbor_auth
        ).json()

        report = {
            'total_policies': len(policies),
            'active_policies': 0,
            'executions': [],
            'statistics': {
                'total_replicated': 0,
                'total_size': 0,
                'success_rate': 0
            }
        }

        for policy in policies:
            if policy['enabled']:
                report['active_policies'] += 1

            # 최근 실행 내역 조회
            executions = requests.get(
                f"{self.api_base}/replication/executions",
                params={'policy_id': policy['id'], 'limit': 5},
                auth=self.harbor_auth
            ).json()

            for execution in executions:
                tasks = requests.get(
                    f"{self.api_base}/replication/executions/{execution['id']}/tasks",
                    auth=self.harbor_auth
                ).json()

                exec_summary = {
                    'policy_name': policy['name'],
                    'execution_id': execution['id'],
                    'status': execution['status'],
                    'start_time': execution['start_time'],
                    'end_time': execution.get('end_time'),
                    'total_tasks': len(tasks),
                    'succeeded': len([t for t in tasks if t['status'] == 'Succeeded']),
                    'failed': len([t for t in tasks if t['status'] == 'Failed'])
                }

                report['executions'].append(exec_summary)
                report['statistics']['total_replicated'] += exec_summary['succeeded']

        # 성공률 계산
        total_tasks = sum(e['total_tasks'] for e in report['executions'])
        total_succeeded = sum(e['succeeded'] for e in report['executions'])

        if total_tasks > 0:
            report['statistics']['success_rate'] = (total_succeeded / total_tasks) * 100

        return report

성능 및 효과

Harbor Registry 기능 활용 효과

복제 정책 운영 현황

트러블슈팅 경험

1. 대용량 이미지 복제 시 타임아웃

문제: 10GB 이상 이미지 복제 중 타임아웃 발생 해결:

# Harbor 설정 조정
policy_update = {
    "speed": -1,  # 속도 제한 해제
    "decoration": {
        "timeout": 3600  # 타임아웃 1시간으로 증가
    }
}

2. 동시 복제 시 리소스 부족

문제: 10개 이상 동시 복제 시 Harbor JobService OOM 해결:

# JobService 리소스 증설
resources:
  limits:
    memory: 4Gi  # 2Gi → 4Gi
    cpu: 2000m
  requests:
    memory: 2Gi
    cpu: 1000m

3. Registry 인증 토큰 만료

문제: 장시간 복제 중 소스 레지스트리 토큰 만료 해결:

• Registry credential refresh 로직 추가
• Harbor 2.6.0의 자동 토큰 갱신 기능 활용

교훈

1. Harbor 내장 기능 활용의 중요성

   • Registry API로 복잡한 스크립트 불필요
   • 내장 재시도 로직으로 안정성 향상

2. Event-driven 복제의 효율성

   • Push 이벤트 기반 실시간 백업
   • 불필요한 스케줄 작업 제거

3. 병렬 처리 최적화

   • JobService 워커 수 조정 필요
   • 네트워크 대역폭 고려한 동시 실행 수 결정

프로젝트 성과 요약

Harbor의 내장 Registry 복제 기능을 최대한 활용하여, 복잡한 스크립트 없이도 효율적인 마이그레이션과 백업 체계를 구축했습니다. 특히 병렬 복제 실행과 Event-driven 백업으로 운영 효율성을 극대화했습니다.

기술 스택: Harbor API, Kubernetes, Python, Docker Registry V2, PostgreSQL, Redis

오프라인 환경에서 운영되는 엔터프라이즈급 AI/ML 추론 플랫폼을 구축한 프로젝트입니다. GPU 가속 추론, 3중화 클러스터링, 분산 스토리지, 그리고 완전한 오프라인 운영을 지원하는 마이크로서비스 아키텍처를 설계하고 구현했습니다.

핵심 성과

• 100% 오프라인 운영 가능한 AI/ML 인프라 구축
• 99.99% 가용성 달성 (3중화 클러스터링)
• GPU 효율 85% 이상 활용 (동적 배치 처리)
• 자동 장애 복구 시간 30초 이내

시스템 아키텍처

클러스터 구성

핵심 컴포넌트 스택

Infrastructure Layer:
  - Kubernetes v1.28
  - Docker/Containerd
  - Ubuntu 20.04/22.04 LTS

Load Balancing:
  - MetalLB (Bare-metal LB)
  - NGINX Ingress Controller

Data Layer (3중화):
  - MariaDB MaxScale Cluster
  - Redis Cluster (6 nodes)
  - SeaweedFS Distributed Storage

AI/ML Services:
  - NVIDIA Triton Inference Server
  - AI Platform Services
  - Custom ML Model Registry

Monitoring & Operations:
  - Fluent Bit (Logging)
  - Kubernetes Native Monitoring
  - Auto-recovery Scripts

핵심 기술 구현

1. 3중화 고가용성 아키텍처

데이터베이스 레이어 (MariaDB MaxScale)

핵심 특징:

• GTID 기반 복제: 데이터 일관성 100% 보장
• 자동 페일오버: 마스터 장애시 30초 내 슬레이브 승격
• 읽기/쓰기 분리: 성능 50% 향상

캐시 레이어 (Redis Cluster)

구현 성과:

• 샤딩: 16,384 슬롯 자동 분산
• 처리량: 100,000 ops/sec
• 레이턴시: < 1ms (99 percentile)

스토리지 레이어 (SeaweedFS)

특징:

• Raft 합의: 강력한 일관성 보장
• S3 호환 API: 기존 애플리케이션 호환성
• 자동 복제: 데이터 손실 방지

2. GPU 자원 최적화

NVIDIA Device Plugin 설정

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: nvidia-device-plugin
spec:
  template:
    spec:
      containers:
      - name: nvidia-device-plugin
        image: nvcr.io/nvidia/k8s-device-plugin:v0.14.0
        securityContext:
          privileged: true  # GPU 접근 권한
        volumeMounts:
        - name: dev
          mountPath: /dev  # GPU 디바이스 마운트

Triton Inference Server 최적화

배포 전략:
  - Dynamic Batching: GPU 효율 85% 달성
  - Model Versioning: 무중단 모델 업데이트
  - Multi-GPU Scheduling: 로드 밸런싱

성능 지표:
  - 추론 처리량: 5,000 req/sec
  - P99 레이턴시: < 50ms
  - GPU 메모리 활용률: 80%

3. 오프라인 환경 최적화

네트워크 격리 설정

# 고정 IP 설정 (DHCP 비활성화)
network:
  version: 2
  ethernets:
    eth0:
      dhcp4: false
      addresses: [10.0.0.100/24]  # 내부 네트워크

# MetalLB IP Pool (내부 네트워크)
addresses:
  - 10.0.0.240-10.0.0.255

자동 복구 시스템

#!/bin/bash
# k8s-auto-recovery.sh

# 1. 필수 서비스 자동 시작
systemctl enable --now containerd kubelet

# 2. 스왑 영구 비활성화
swapoff -a
sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# 3. 커널 모듈 자동 로딩
modprobe br_netfilter overlay

# 4. 클러스터 상태 체크
kubectl wait --for=condition=Ready nodes --all

성능 벤치마크

AI/ML 추론 성능

시스템 안정성

구현 코드 예시

GPU 노드 배포 매니페스트

apiVersion: apps/v1
kind: Deployment
metadata:
  name: triton-inference-server
  namespace: ai-platform
spec:
  replicas: 2
  selector:
    matchLabels:
      app: triton-server
  template:
    metadata:
      labels:
        app: triton-server
    spec:
      nodeSelector:
        accelerator: nvidia
      runtimeClassName: nvidia
      containers:
      - name: triton
        image: nvcr.io/nvidia/tritonserver:23.05-py3
        command:
        - tritonserver
        - --model-repository=/models
        - --backend-config=tensorflow,version=2
        - --backend-config=python,shm-default-byte-size=134217728
        ports:
        - containerPort: 8000
          name: http
        - containerPort: 8001
          name: grpc
        resources:
          limits:
            nvidia.com/gpu: 1
            memory: 8Gi
            cpu: 4
          requests:
            nvidia.com/gpu: 1
            memory: 4Gi
            cpu: 2
        volumeMounts:
        - name: model-repository
          mountPath: /models
        - name: shared-memory
          mountPath: /dev/shm
      volumes:
      - name: model-repository
        persistentVolumeClaim:
          claimName: model-storage-pvc
      - name: shared-memory
        emptyDir:
          medium: Memory
          sizeLimit: 2Gi

통합 관리 스크립트

#!/bin/bash
# manage-all.sh - 전체 시스템 관리

case "$1" in
  install)
    echo "🚀 AI/ML 플랫폼 설치 시작..."
    kubectl apply -f namespaces/
    kubectl apply -f storage/
    kubectl apply -f database/
    kubectl apply -f cache/
    kubectl apply -f ai-services/
    echo "✅ 설치 완료"
    ;;

  status)
    echo "📊 시스템 상태 확인"
    kubectl get nodes
    kubectl get pods --all-namespaces | grep -E "gpu|triton|grnd"
    kubectl top nodes
    nvidia-smi
    ;;

  backup)
    BACKUP_DIR="/backup/$(date +%Y%m%d_%H%M%S)"
    echo "💾 백업 시작: $BACKUP_DIR"
    kubectl get all --all-namespaces -o yaml > $BACKUP_DIR/k8s-resources.yaml
    kubectl exec -n database mariadb-master-0 -- mysqldump --all-databases > $BACKUP_DIR/db-backup.sql
    ;;

  *)
    echo "Usage: $0 {install|uninstall|status|backup|restart}"
    exit 1
    ;;
esac

트러블슈팅 경험

1. MariaDB MaxScale 클러스터 투표 메커니즘 이슈

문제: 2중화 구성시 투표 방식의 Master 선출이 불가능 (과반수 미달) 원인: MaxScale의 모니터링 모듈이 과반수 투표 방식으로 Master를 선발하는데, 2개 노드에서는 Split Brain 발생 해결:

# 3중화 구성으로 전환
- Master Node: 1개
- Slave Nodes: 2개  
- MaxScale Monitor: 과반수(2/3) 투표로 안정적 Master 선출

성과:

• 자동 failover 성공률 100% 달성
• 죽었던 MariaDB 노드가 재시작시 GTID 기반으로 자동 Slave 편입
• 데이터 동기화 자동화로 운영 부담 감소

2. gRPC DNS Resolver 오프라인 환경 이슈

문제: Python gRPC 라이브러리가 CoreDNS 설정을 무시하고 외부 DNS 질의 시도 원인: gRPC의 기본 DNS resolver가 c-ares를 사용하여 시스템 DNS 설정 우회 해결:

# gRPC 환경변수 설정으로 native resolver 사용
import os
os.environ['GRPC_DNS_RESOLVER'] = 'native'

# 또는 channel 생성시 옵션 지정
channel_options = [
    ('grpc.dns_resolver', 'native'),
]
channel = grpc.insecure_channel(target, options=channel_options)

결과:

• CoreDNS를 통한 내부 서비스 디스커버리 정상화
• 완전한 오프라인 환경에서 gRPC 통신 성공

3. SeaweedFS Replication Factor 최적화

문제: 3중화 클러스터에서 replication=2 설정시 노드 장애시 쓰기 불가 원인:

• 3개 노드 중 1개 다운시, 2개 복제본 요구사항 충족 불가
• Quorum 부족으로 쓰기 작업 차단
• 해결*:

  # SeaweedFS Master 설정 변경
  weed master -defaultReplication="001"  # 1개 복제본으로 변경
  # Format: xyz where x=다른 데이터센터, y=다른 랙, z=같은 랙 다른 서버
  

실제 운영 설정

• replication: "001" # 같은 랙의 다른 서버 1대에만 복제
• minFreeSpacePercent: 10
• volumeSizeLimitMB: 30000 ```
• 개선 효과*:
• 노드 1개 장애시에도 정상 서비스 유지
• 스토리지 효율성 33% 개선 (3 copies → 2 copies)
• 쓰기 성능 20% 향상

4. DNS 해석 실패 (오프라인 환경)

4. CoreDNS 오프라인 최적화

문제: CoreDNS가 외부 DNS 서버 접근 시도로 타임아웃 발생 해결:

# CoreDNS ConfigMap 수정
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns
data:
  Corefile: |
    cluster.local {
      forward . /etc/resolv.conf {
        except cluster.local
      }
    }

프로젝트 성과

비즈니스 임팩트

• 운영 비용 절감: 40% (클라우드 대비)
• 추론 속도 향상: 3x (기존 시스템 대비)
• 장애 대응 시간: 5분 → 30초
• 데이터 보안: 100% 오프라인 운영

기술적 성취

• 완전 자동화: 인프라 프로비저닝부터 배포까지
• 무중단 운영: Rolling update + Blue-Green 배포
• 확장성: 노드 추가만으로 수평 확장 가능
• 이식성: 어떤 베어메탈 환경에서도 구동 가능

교훈

1. 오프라인 환경의 도전

   • 외부 의존성 완전 제거의 중요성
   • 로컬 캐싱 전략의 필수성
   • 자체 복구 메커니즘의 중요성

2. GPU 자원 관리

   • 동적 배치 처리로 효율성 극대화
   • 모델 버전 관리의 복잡성
   • 메모리 관리 최적화의 중요성

3. 고가용성 설계

   • 3중화가 투표 메커니즘에서 필수적임을 학습
   • MaxScale의 모니터링 기반 자동 페일오버 활용
   • GTID 기반 복제로 데이터 일관성 보장
   • SeaweedFS replication factor의 적절한 조정 필요성

향후 개선 계획

1. 관찰성 강화

   • Prometheus + Grafana 통합
   • Distributed Tracing (Jaeger)
   • AI 기반 이상 탐지

2. 보안 강화

   • Service Mesh (Istio) 도입
   • Zero Trust Network Architecture
   • 암호화된 통신 (mTLS)

기술 스택 상세

Container Orchestration:
  - Kubernetes: v1.28
  - containerd: v1.7
  - CNI: Flannel v0.22

GPU Computing:
  - CUDA: 11.8
  - cuDNN: 8.6
  - TensorRT: 8.5
  - Triton Server: 23.05

Data Management:
  - MariaDB: 10.11
  - MaxScale: 23.08
  - Redis: 7.0
  - SeaweedFS: 3.55

Monitoring & Logging:
  - Fluent Bit: 2.1
  - Kubernetes Metrics Server: 0.6
  - Custom Health Checks

Development Tools:
  - Helm: 3.12
  - Kustomize: 5.0
  - GitOps: ArgoCD Ready

현대 클라우드 환경에서 인프라를 코드로 관리하는 것은 필수가 되었습니다. Terraform은 이러한 흐름을 선도하는 도구이지만, 복잡한 멀티 환경 구성에서는 여러 한계에 부딪히게 됩니다. 이 글에서는 Terraform에서 발생하는 코드 중복 문제를 해결하기 위해 Terragrunt를 도입하게 된 과정과 그 성과에 대해 자세히 다루겠습니다.

Terraform 사용 시 직면했던 구체적인 문제점

Terraform을 여러 환경(개발, 테스트, 스테이징, 운영)에서 사용하다 보니 다음과 같은 명확한 한계점이 드러났습니다:

1. 과도한 코드 중복

각 환경별로 거의 동일한 코드를 복사-붙여넣기 하는 상황이 빈번했습니다. 예를 들어:

# dev/main.tf
provider "aws" {
  region = "ap-northeast-2"
}

module "vpc" {
  source = "../modules/vpc"
  vpc_cidr = "10.0.0.0/16"
  environment = "dev"
  subnet_count = 2
}

module "ec2" {
  source = "../modules/ec2"
  instance_type = "t2.micro"
  environment = "dev"
  vpc_id = module.vpc.vpc_id
}

terraform {
  backend "s3" {
    bucket = "terraform-state"
    key    = "dev/terraform.tfstate"
    region = "ap-northeast-2"
    dynamodb_table = "terraform-locks"
    encrypt = true
  }
}

# prod/main.tf (거의 동일한 코드)
provider "aws" {
  region = "ap-northeast-2"
}

module "vpc" {
  source = "../modules/vpc"
  vpc_cidr = "10.1.0.0/16"  // 차이점
  environment = "prod"      // 차이점
  subnet_count = 3         // 차이점
}

module "ec2" {
  source = "../modules/ec2"
  instance_type = "t2.large"  // 차이점
  environment = "prod"        // 차이점
  vpc_id = module.vpc.vpc_id
}

terraform {
  backend "s3" {
    bucket = "terraform-state"
    key    = "prod/terraform.tfstate"  // 차이점
    region = "ap-northeast-2"
    dynamodb_table = "terraform-locks"
    encrypt = true
  }
}

이러한 구조에서는 환경마다 달라지는 값이 몇 개 없음에도 불구하고 전체 코드를 반복해야 했습니다.

2. 백엔드 구성의 반복

모든 환경에서 원격 상태 저장을 위한 백엔드 구성이 반복되었습니다. 백엔드 설정 변경 시 모든 환경의 코드를 수정해야 했습니다.

3. 변수 관리의 복잡성

환경별 변수를 관리하는 것이 복잡했습니다. 특히 변수 파일이 늘어날수록 관리가 어려웠습니다:

project/
├── dev/
│   ├── main.tf
│   ├── variables.tf
│   └── terraform.tfvars
├── stage/
│   ├── main.tf
│   ├── variables.tf
│   └── terraform.tfvars
└── prod/
    ├── main.tf
    ├── variables.tf
    └── terraform.tfvars

4. 모듈 간 종속성 관리의 어려움

모듈 간 종속성을 관리하기 위해 복잡한 출력 변수 참조가 필요했으며, 이로 인해 코드가 더 복잡해졌습니다.

5. 일관성 유지의 어려움

환경마다 동일한 코드를 유지해야 하는데, 한 환경에서 코드를 개선했을 때 다른 환경에도 똑같이 적용해야 하는 번거로움이 있었습니다.

Terragrunt란? 상세한 이해

Terragrunt는 Terraform의 얇은 래퍼(wrapper)로, Terraform의 기능을 확장하여 이러한 문제를 해결합니다. 구체적인 기능을 살펴보겠습니다:

1. 구성 파일의 계층화

Terragrunt는 terragrunt.hcl 파일을 통해 구성을 계층화합니다. 이를 통해 구성을 상속하고 재사용할 수 있습니다.

# 루트 terragrunt.hcl
remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite"
  }
  config = {
    bucket         = "terraform-state-${get_aws_account_id()}"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "ap-northeast-2"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# 환경 공통 설정
generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite"
  contents  = <<EOF
provider "aws" {
  region = "ap-northeast-2"
  default_tags {
    tags = {
      Environment = "${local.environment}"
      Terraform   = "true"
    }
  }
}
EOF
}

# 로컬 변수 설정 (각 환경의 terragrunt.hcl에서 오버라이드)
locals {
  environment = "default"
}

2. 자동 원격 상태 관리

Terragrunt는 각 모듈의 원격 상태를 자동으로 구성합니다. 이를 통해 상태 파일 경로를 동적으로 생성하여 중복 코드를 줄입니다.

remote_state {
  backend = "s3"
  config = {
    bucket = "terraform-state"
    key    = "${path_relative_to_include()}/terraform.tfstate"
    region = "ap-northeast-2"
    dynamodb_table = "terraform-locks"
    encrypt = true
  }
}

3. 의존성 블록을 통한 명시적인 종속성 관리

Terragrunt는 dependency 블록을 통해 모듈 간 종속성을 명시적으로 정의할 수 있습니다:

# app/terragrunt.hcl
dependency "vpc" {
  config_path = "../vpc"

  # 의존성 모듈의 출력을 참조할 때 건너뛸 수 있는 옵션
  mock_outputs = {
    vpc_id = "mock-vpc-id"
  }
  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
}

이는 모듈 간 명확한 종속성을 정의하고, 출력 변수를 쉽게 참조할 수 있게 합니다.

4. before_hook과 after_hook을 통한 실행 맥락 확장

Terragrunt는 Terraform 명령 전후에 추가 작업을 실행할 수 있는 훅 기능을 제공합니다:

terraform {
  before_hook "before_hook" {
    commands     = ["apply", "plan"]
    execute      = ["echo", "Running Terraform"]
  }

  after_hook "after_hook" {
    commands     = ["apply"]
    execute      = ["echo", "Terraform apply completed"]
    run_on_error = true
  }
}

5. 입력 변수의 계층화

여러 레벨의 입력 변수를 결합할 수 있어 코드 중복을 최소화합니다:

# prod/region/service/terragrunt.hcl
include {
  path = find_in_parent_folders()
}

include "region_vars" {
  path = find_in_parent_folders("region.hcl")
}

include "environment_vars" {
  path = find_in_parent_folders("env.hcl")
}

inputs = {
  service_specific_var = "value"
}

DRY 원칙을 준수할 수 있었던 심층적 이유

Terragrunt가 어떻게 DRY 원칙을 실현하는지 자세히 살펴보겠습니다:

1. 계층적 구성 상속

Terragrunt의 핵심 기능인 구성 상속은 공통 설정을 한 번만 정의하고 모든 환경에서 재사용할 수 있게 합니다:

# terragrunt/terragrunt.hcl (루트)
remote_state {
  backend = "s3"
  config = {
    bucket = "terraform-state"
    region = "ap-northeast-2"
    encrypt = true
    dynamodb_table = "terraform-locks"
    key = "${path_relative_to_include()}/terraform.tfstate"
  }
}

# 공통 변수 정의
inputs = {
  aws_region = "ap-northeast-2"
  tags = {
    ManagedBy = "Terraform"
  }
}

# env-common.hcl (환경별 공통 설정)
locals {
  common_tags = {
    Owner = "DevOps-Team"
  }
}

# 개발 환경별 설정
inputs = merge(
  local.common_tags,
  {
    environment = "dev"
  }
)

# terragrunt/dev/vpc/terragrunt.hcl
include {
  path = find_in_parent_folders()
}

include "env" {
  path = find_in_parent_folders("env-common.hcl")
}

inputs = {
  vpc_cidr = "10.0.0.0/16"
}

이를 통해 환경별, 서비스별 설정을 계층적으로 관리할 수 있습니다.

2. 동적 백엔드 구성 생성

백엔드 구성을 동적으로 생성하여 모든 모듈에서 백엔드 설정 코드를 제거할 수 있습니다:

# 루트 terragrunt.hcl
remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite"
  }
  config = {
    bucket         = "terraform-state-${get_aws_account_id()}"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = local.aws_region
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

locals {
  aws_region = "ap-northeast-2"
}

이 설정은 각 모듈 디렉토리에 Terraform 실행 시 자동으로 backend.tf 파일을 생성합니다. 이로써 백엔드 설정을 한 번만 정의하고 모든 모듈에서 사용할 수 있습니다.

3. 변수 주입 메커니즘

Terragrunt의 inputs 블록은 변수를 Terraform 모듈에 자동으로 주입합니다. 이를 통해 환경별 변수를 효율적으로 관리할 수 있습니다:

# dev/vpc/terragrunt.hcl
include {
  path = find_in_parent_folders()
}

terraform {
  source = "../../modules//vpc"
}

inputs = {
  vpc_cidr        = "10.0.0.0/16"
  public_subnets  = ["10.0.1.0/24", "10.0.2.0/24"]
  private_subnets = ["10.0.10.0/24", "10.0.20.0/24"]
}

# prod/vpc/terragrunt.hcl
include {
  path = find_in_parent_folders()
}

terraform {
  source = "../../modules//vpc"
}

inputs = {
  vpc_cidr        = "10.1.0.0/16"
  public_subnets  = ["10.1.1.0/24", "10.1.2.0/24", "10.1.3.0/24"]
  private_subnets = ["10.1.10.0/24", "10.1.20.0/24", "10.1.30.0/24"]
}

4. 함수와 헬퍼를 통한 동적 구성

Terragrunt는 다양한 내장 함수를 제공하여 구성을 동적으로 생성할 수 있습니다:

locals {
  account_vars = read_terragrunt_config(find_in_parent_folders("account.hcl"))
  region_vars  = read_terragrunt_config(find_in_parent_folders("region.hcl"))
  environment_vars = read_terragrunt_config(find_in_parent_folders("env.hcl"))

  account_id   = local.account_vars.locals.aws_account_id
  aws_region   = local.region_vars.locals.aws_region
  environment  = local.environment_vars.locals.environment
}

inputs = {
  tags = {
    Account     = local.account_id
    Region      = local.aws_region
    Environment = local.environment
  }
}

도입 후 변화: 정량적/정성적 효과

Terragrunt 도입 후 다음과 같은 구체적인 변화가 있었습니다:

1. 코드 양의 극적인 감소

기존 Terraform 코드는 환경당 약 500줄 정도였으나, Terragrunt 도입 후 환경별 설정은 50줄 이하로 줄였습니다. 전체적으로는 약 70%의 코드 감소 효과가 있었습니다.

2. 배포 시간 단축

여러 모듈이 의존성을 가진 경우, terragrunt run-all apply를 통해 의존성 순서를 자동으로 계산하고 병렬로 배포할 수 있어 배포 시간이 약 40% 단축되었습니다.

3. 오류 감소율

환경 간 설정 불일치로 인한 오류가 85% 이상 감소했습니다. 한 환경에서 검증된 코드는 다른 환경에서도 동일하게 작동했습니다.

4. 신규 환경 구성 시간 단축

새로운 환경(예: QA, Sandbox)을 추가할 때 필요한 시간이 기존 2-3일에서 1시간 이내로 단축되었습니다.

5. 백엔드 관리 간소화

모든 환경의 백엔드 설정을 한 번에 변경할 수 있어, AWS 계정 변경이나 리전 이전 시 유연성이 크게 향상되었습니다.

실제 적용 사례: 상세 구현

실제 프로젝트에서는 다음과 같은 구조로 Terragrunt를 적용했습니다:

terragrunt/
├── terragrunt.hcl            # 루트 설정 (백엔드, 프로바이더 등)
├── account.hcl               # AWS 계정 정보
├── env-common.hcl            # 환경 공통 설정
├── modules/                  # 공통 Terraform 모듈
│   ├── vpc/
│   ├── eks/
│   ├── rds/
│   └── elasticache/
├── dev/                      # 개발 환경
│   ├── env.hcl               # 개발 환경 전역 변수
│   ├── vpc/
│   │   └── terragrunt.hcl
│   ├── eks/
│   │   └── terragrunt.hcl
│   └── database/
│       └── terragrunt.hcl
└── prod/                     # 운영 환경
    ├── env.hcl               # 운영 환경 전역 변수
    ├── vpc/
    │   └── terragrunt.hcl
    ├── eks/
    │   └── terragrunt.hcl
    └── database/
        └── terragrunt.hcl

이러한 구조에서 각 컴포넌트별 설정은 다음과 같이 구성됩니다:

루트 terragrunt.hcl

# 원격 상태 관리
remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite"
  }
  config = {
    bucket         = "terraform-state-${local.account_id}"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = local.aws_region
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# AWS 공급자 구성 자동 생성
generate "provider" {
  path      = "provider.tf"
  if_exists = "overwrite"
  contents  = <<EOF
provider "aws" {
  region = "${local.aws_region}"
  default_tags {
    tags = {
      Environment = "${local.environment}"
      ManagedBy   = "Terraform"
      Workspace   = "${terraform.workspace}"
    }
  }
}
EOF
}

# 로컬 변수 설정
locals {
  # 하위 HCL 파일에서 로드
  account_vars = read_terragrunt_config(find_in_parent_folders("account.hcl"))
  environment_vars = try(
    read_terragrunt_config(find_in_parent_folders("env.hcl")),
    { locals = { environment = "default" } }
  )

  account_id   = local.account_vars.locals.aws_account_id
  aws_region   = local.account_vars.locals.aws_region
  environment  = local.environment_vars.locals.environment
}

# 공통 입력 변수
inputs = {
  aws_region  = local.aws_region
  account_id  = local.account_id
  environment = local.environment
}

계정 설정: account.hcl

locals {
  aws_account_id = "123456789012"  # AWS 계정 ID
  aws_region     = "ap-northeast-2"  # 기본 AWS 리전
}

환경별 설정: dev/env.hcl

locals {
  environment = "dev"

  # 개발 환경 특화 설정
  domain_name = "dev.example.com"

  # 인프라 사이징
  instance_types = {
    bastion = "t3.micro"
    app     = "t3.small"
  }

  rds_config = {
    instance_class    = "db.t3.medium"
    allocated_storage = 20
    multi_az          = false
  }
}

환경별 설정: prod/env.hcl

locals {
  environment = "prod"

  # 운영 환경 특화 설정
  domain_name = "example.com"

  # 인프라 사이징
  instance_types = {
    bastion = "t3.small"
    app     = "m5.large"
  }

  rds_config = {
    instance_class    = "db.m5.large"
    allocated_storage = 100
    multi_az          = true
  }
}

컴포넌트 설정: dev/vpc/terragrunt.hcl

include {
  path = find_in_parent_folders()
}

terraform {
  source = "../../modules//vpc"
}

inputs = {
  vpc_name       = "dev-vpc"
  vpc_cidr       = "10.0.0.0/16"
  azs            = ["ap-northeast-2a", "ap-northeast-2c"]
  public_subnets = ["10.0.1.0/24", "10.0.2.0/24"]
  private_subnets = ["10.0.10.0/24", "10.0.20.0/24"]

  enable_nat_gateway = true
  single_nat_gateway = true  # 개발 환경에서는 비용 절감을 위해 단일 NAT 게이트웨이 사용

  tags = {
    Terraform   = "true"
    Environment = "dev"
  }
}

컴포넌트 설정: dev/eks/terragrunt.hcl

include {
  path = find_in_parent_folders()
}

# VPC 모듈에 대한 종속성 정의
dependency "vpc" {
  config_path = "../vpc"

  # 의존성 모듈이 아직 배포되지 않았을 때 모의 출력을 사용 (계획/검증용)
  mock_outputs = {
    vpc_id = "mock-vpc-id"
    private_subnets = ["mock-subnet-1", "mock-subnet-2"]
  }
  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

terraform {
  source = "../../modules//eks"
}

inputs = {
  cluster_name = "dev-eks"
  vpc_id       = dependency.vpc.outputs.vpc_id
  subnet_ids   = dependency.vpc.outputs.private_subnets

  cluster_version = "1.24"

  # 노드 그룹 설정
  node_groups = {
    main = {
      desired_capacity = 2
      min_capacity     = 1
      max_capacity     = 3
      instance_types   = ["t3.medium"]
      disk_size        = 50
    }
  }

  # 관리형 노드 그룹 설정
  managed_node_groups = {
    system = {
      name           = "system"
      instance_types = ["t3.medium"]
      min_size       = 1
      max_size       = 3
      desired_size   = 1
      capacity_type  = "ON_DEMAND"
    }
  }
}

CI/CD 파이프라인과의 통합

Terragrunt는 GitHub Actions와 같은 CI/CD 시스템과 쉽게 통합됩니다:

# GitHub Actions 워크플로우 파일
name: 'Terraform Infrastructure Deployment'

on:
  push:
    branches:
      - main
    paths:
      - 'terragrunt/**'
  pull_request:
    branches:
      - main
    paths:
      - 'terragrunt/**'

jobs:
  terraform:
    name: 'Terraform'
    runs-on: ubuntu-latest

    steps:
      - name: 코드 체크아웃
        uses: actions/checkout@v3

      - name: AWS 자격 증명 설정
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ap-northeast-2

      - name: Terraform 설치
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: '1.4.0'

      - name: Terragrunt 설치
        run: |
          curl -L -o /tmp/terragrunt https://github.com/gruntwork-io/terragrunt/releases/download/v0.45.0/terragrunt_linux_amd64
          chmod +x /tmp/terragrunt
          sudo mv /tmp/terragrunt /usr/local/bin/terragrunt

      - name: Terragrunt 캐시 초기화
        run: |
          find terragrunt -type d -name ".terragrunt-cache" -exec rm -rf {} +
          find terragrunt -type d -name ".terraform" -exec rm -rf {} +

      - name: Terragrunt 초기화 및 계획
        id: plan
        run: |
          cd terragrunt/dev
          terragrunt run-all init
          terragrunt run-all plan -out=tfplan.binary

      - name: 변경사항 요약
        run: |
          cd terragrunt/dev
          terragrunt run-all show tfplan.binary | grep -A 20 "Plan:"

      - name: Terragrunt 적용
        if: github.event_name == 'push'
        run: |
          cd terragrunt/dev
          terragrunt run-all apply -auto-approve

고급 Terragrunt 기능 활용

1. 원격 모듈 참조 최적화

Terragrunt는 Terraform 모듈을 효율적으로 참조할 수 있습니다:

terraform {
  source = "git::https://github.com/org/terraform-modules.git//vpc?ref=v1.2.3"
}

2. 의존성 다이어그램 생성

의존성 구조를 시각화할 수 있습니다:

terragrunt graph-dependencies | dot -Tpng > dependencies.png

3. 병렬 실행을 통한 배포 속도 향상

여러 모듈을 병렬로 배포하여 시간을 단축할 수 있습니다:

terragrunt run-all apply --terragrunt-parallelism 10

4. 특정 모듈만 선택적 실행

태그 또는 패턴을 사용하여 특정 모듈만 실행할 수 있습니다:

terragrunt run-all apply --terragrunt-include-dir "**/vpc"

결론: Terragrunt의 비즈니스 가치

Terragrunt는 단순한 기술적 개선을 넘어 다음과 같은 비즈니스 가치를 제공합니다:

1. 운영 효율성: 코드 중복 감소와 자동화를 통해 인프라 관리 효율성이 크게 향상됩니다.
2. 위험 감소: 환경 간 일관성 향상으로 운영 실수와 위험이 감소합니다.
3. 신속한 환경 프로비저닝: 새로운 환경 구축 시간이 대폭 단축되어 비즈니스 요구에 빠르게 대응할 수 있습니다.
4. 비용 최적화: 환경별 인프라 설정을 보다 세밀하게 조정하여 비용을 최적화할 수 있습니다.
5. 개발자 경험 향상: 간결하고 일관된 코드 작성 방식으로 개발자 만족도와 생산성이 향상됩니다.

Terraform을 사용하면서 코드 중복, 모듈 관리, 환경별 구성의 어려움을 겪고 계신다면, Terragrunt는 이러한 문제를 해결할 수 있는 강력한 도구입니다. DRY 원칙을 기반으로 인프라 코드의 품질과 유지보수성을 크게 향상시켜 보다 안정적이고 효율적인 인프라 관리가 가능해집니다.

시스템 개요

본 시스템은 마이크로서비스 아키텍처 환경에서 발생하는 로그와 트레이스 데이터를 통합적으로 수집하고, 분석하는 플랫폼입니다. 여기에 대규모 언어 모델(LLM)을 접목해 복잡한 시스템 로그와 트레이스 데이터를 자연어로 해석하고, 운영자가 직관적으로 이해할 수 있도록 지원합니다.

주요 기능

• 🧠 자연어 기반 로그/트레이스 검색: 운영자는 LogQL이나 TraceQL을 몰라도 "지난 3시간 동안의 오류 로그 보여줘" 같은 자연어로 검색 가능
• 🔍 로그-트레이스 연계 분석: 특정 에러 로그와 관련된 트레이스를 추적해 원인 파악
• 🚨 이상 탐지 및 진단: AI가 이상 징후를 감지하고, 원인을 요약해 제공
• 📊 시각화 대시보드: Grafana 및 Streamlit을 활용한 인터랙티브 UI 제공

시스템 아키텍처

아래는 시스템 전반의 구성 요소와 데이터 흐름을 간단한 블록 다이어그램 형식으로 표현한 이미지입니다.

구성 계층 요약

• UI 계층: Streamlit 기반 자연어 쿼리 입력 및 결과 시각화
• 분석 계층: LangGraph가 자연어 쿼리를 분석하고 의도 추출 및 LogQL/TraceQL 생성
• MCP 계층: Loki/Tempo MCP 서버가 클라이언트 요청을 중계하고 응답 포맷 가공
• API 계층: Loki/Tempo API 서버가 원시 로그/트레이스 쿼리를 수행
• 데이터 소스: Loki/Tempo DB가 실제 데이터를 저장 및 제공
• 시각화 대시보드: Grafana를 통해 실시간 모니터링 UI 제공

MCP란 무엇인가?

모니터링 시스템을 개발하면서 가장 먼저 고민했던 것은 "컴포넌트 간 상호작용을 어떻게 일관되게 관리할 것인가?"였습니다. 이에 도입한 것이 Model Context Protocol(MCP)입니다.

MCP의 특징

• 컨텍스트 관리: 세션, 이전 요청, 사용자 의도를 유지해 일관성 있는 분석
• 데이터 변환: 프론트 요청을 백엔드에서 처리 가능한 포맷으로 변환
• 세션 기반 인터랙션: 단발성 요청이 아닌, 지속적인 대화형 상호작용 가능

JSON-RPC를 선택한 이유

MCP와 LangGraph 간, 그리고 MCP와 API 서버 간 통신에는 JSON-RPC 2.0을 사용했습니다.

선택 이유

• 🧩 메서드 기반 인터페이스: method, params, id가 명확하게 구조화
• 📉 가벼운 오버헤드: REST 대비 적은 메타데이터로 속도와 효율성 향상
• 🔁 양방향 통신 구조: 이벤트 기반 응답, SSE, 배치 처리 지원

{
  "jsonrpc": "2.0",
  "method": "query_loki",
  "params": {
    "query": "{service=\"order-service\"}",
    "start": "2023-05-01T10:00:00Z",
    "end": "2023-05-01T11:00:00Z"
  },
  "id": 1
}

구성 요소 상세 설명

LangGraph

• Google Gemini 기반 자연어 해석 및 LogQL/TraceQL 생성
• 로그/트레이스 통합 분석, 인사이트 추출, 샘플 생성
• FastAPI, LangChain 기반 Python 서버

Loki/Tempo API 서버

• 로그/트레이스 원시 데이터 처리 전담
• FastAPI로 작성, HTTPX로 Loki/Tempo와 통신

MCP 서버

• MCP-Loki / MCP-Tempo 서버는 API 요청 중계 + 컨텍스트 관리
• 요청 변환, 응답 포맷팅, 캐싱, 세션 연계 기능 포함

Streamlit UI

• 자연어 질의 입력 및 분석 결과 시각화
• 로그 레벨, 서비스명, 시간 범위 필터링 지원

주요 시나리오 예시

✅ 로그 분석 예시

"지난 3시간 동안 order-service에서 발생한 에러 로그 보여줘"

• LangGraph는 이를 LOG_QUERY로 인식, service=\"order-service\" 및 시간 범위 추출
• LogQL 쿼리 생성 → Loki-MCP → Loki API → Loki DB
• 분석된 로그와 요약 결과가 Streamlit UI에 표시됨

✅ 트레이스 분석 예시

"product-service의 API 호출 지연이 있는 트레이스 보여줘"

• LangGraph가 TRACE_QUERY로 분류하고 쿼리 수행
• Tempo MCP를 통해 Tempo DB 조회 → 지연 시간 기반 트레이스 필터링 및 요약 제공

✅ 통합 분석 예시

"order-service의 에러 로그와 관련된 트레이스를 찾아서 분석해줘"

• LangGraph가 복합 쿼리로 분류
• 로그에서 트레이스 ID 추출 → Tempo에 트레이스 요청
• 로그-트레이스 연관 분석 결과 제공

Docker Compose 기반 배포

services:
  langgraph:
    build: ./langgraph
    ports:
      - "8001:8001"
    environment:
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
      - MCP_URL=http://loki-mcp:8003
      - TEMPO_MCP_URL=http://tempo-mcp:8004

  loki-api:
    build: ./loki-api
    ports:
      - "8002:8002"
    environment:
      - LOKI_URL=${LOKI_URL}

  loki-mcp:
    build: ./loki-mcp
    ports:
      - "8003:8003"
    environment:
      - LOKI_API_URL=http://loki-api:8002

  tempo-api:
    build: ./tempo-api
    ports:
      - "8005:8005"
    environment:
      - TEMPO_URL=${TEMPO_URL}

  tempo-mcp:
    build: ./tempo-mcp
    ports:
      - "8004:8004"
    environment:
      - TEMPO_API_URL=http://tempo-api:8005

  streamlit:
    build: ./streamlit
    ports:
      - "8501:8501"
    environment:
      - LANGGRAPH_URL=http://langgraph:8001

확장성 및 향후 계획

• 📈 메트릭 데이터 통합: Prometheus 연동을 통해 CPU, Memory, Network 등 실시간 메트릭 분석까지 지원 예정
• 🌐 멀티 클러스터 확장: 여러 마이크로서비스 클러스터에 대한 통합 분석을 위한 수평 확장 설계 적용
• 🧠 AI 기반 Root Cause Analysis: LangGraph에 사고 시나리오 학습 기능 추가로 더 정밀한 원인 분석 가능

이상으로 LLM 기반 마이크로서비스 로그/트레이스 분석 시스템에 대한 개발기를 마칩니다. MCP의 도입과 JSON-RPC 구조화 통신 방식이 모니터링의 직관성과 확장성을 크게 향상시켰습니다.