13년차의 서버실

서버, 인프라, 홈랩 기술 블로그

[카테고리:] k8s

  • [k8s] 쿠버네티스 보안 강화: 베스트 프랙티스 가이드

    쿠버네티스 보안, 왜 지금 더 중요해졌나요?

    솔직히 말씀드리면, 저도 처음 쿠버네티스를 도입했을 때는 “일단 돌아가면 됐지”라는 마음이 컸어요. Pod가 뜨고, 서비스가 노출되고, 배포 파이프라인이 연결되면 그걸로 충분하다고 생각했거든요. 근데 운영 2년차쯤 됐을 때 실제로 클러스터 하나가 크립토마이닝 공격에 당하는 걸 목격하고 나서… 그때부터 쿠버네티스 보안을 진지하게 공부하기 시작했습니다.

    최근 들어 클라우드 네이티브 환경이 보편화되면서 쿠버네티스(Kubernetes) 클러스터를 겨냥한 공격도 눈에 띄게 늘었어요. 잘못 설정된 RBAC(Role-Based Access Control, 역할 기반 접근 제어), 노출된 API 서버, 권한 과잉 서비스 계정… 이런 것들이 실제로 침해 사고로 이어지는 경우가 많더라고요.

    이 글에서는 제가 13년간 인프라를 운영하면서 직접 적용해보고, 실제로 효과를 확인한 쿠버네티스 보안 베스트 프랙티스를 정리해드릴게요. 개념만 나열하는 게 아니라 실제 적용 가능한 YAML 설정과 명령어도 함께 다룰 겁니다.

    ▲ 쿠버네티스 클러스터의 주요 보안 레이어 — API 서버, RBAC, 네트워크 정책, Pod 보안이 어떻게 계층적으로 동작하는지 보여주는 아키텍처 다이어그램


    쿠버네티스 보안의 핵심 개념 먼저 짚고 가기

    쿠버네티스 보안은 크게 4가지 영역으로 나뉘어요. 흔히 “4C 보안 모델”이라고 부르는데, 쉽게 말해 Cloud → Cluster → Container → Code 순서로 각 레이어를 지켜야 한다는 개념이에요.

    레이어 설명 주요 관리 포인트
    Cloud 클라우드 인프라 수준 보안 IAM, VPC, 방화벽, 노드 OS 보안
    Cluster 쿠버네티스 클러스터 수준 보안 API 서버 접근 제어, RBAC, Audit 로깅
    Container 컨테이너 런타임 수준 보안 이미지 취약점 스캔, securityContext 설정
    Code 애플리케이션 코드 수준 보안 시크릿 관리, TLS 통신, 의존성 취약점

    이 중에서 Cluster와 Container 레이어가 실제로 가장 많이 놓치는 부분이에요. Cloud는 CSP(클라우드 서비스 제공자)가 어느 정도 기본 보호를 해주고, Code는 개발팀이 챙기는 경우가 많은데, 정작 클러스터 내부 설정은 인프라팀도 개발팀도 서로 남의 일이라고 생각하는 경우가 많거든요. 제가 딱 그랬었어요 ㅎㅎ.


    RBAC 설정: 최소 권한 원칙을 철저히 지켜라

    RBAC(Role-Based Access Control)는 쿠버네티스 보안의 핵심 중 핵심입니다. “필요한 권한만, 필요한 리소스에만”이라는 최소 권한 원칙(Principle of Least Privilege)을 RBAC로 구현하는 거예요.

    흔히 보이는 실수가 뭔지 아세요? 빠르게 개발하려고 ServiceAccount에 cluster-admin 권한을 줘버리는 거예요. 저도 초반에 “일단 개발 환경이니까”라며 그냥 넘어간 적이 있는데, 그 습관이 프로덕션까지 이어지면 진짜 큰일 납니다.

    나쁜 예시 — 절대 이렇게 하지 마세요

    # ⚠️ 절대 금지: 모든 권한을 서비스 계정에 부여
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: dangerous-binding
    subjects:
    - kind: ServiceAccount
      name: my-app
      namespace: default
    roleRef:
      kind: ClusterRole
      name: cluster-admin  # 이거 쓰면 안 됩니다!
      apiGroup: rbac.authorization.k8s.io
    

    좋은 예시 — 최소 권한으로 Role 정의하기

    # ✅ 권장: 특정 네임스페이스의 특정 리소스에만 접근 허용
    apiVersion: rbac.authorization.k8s.io/v1
    kind: Role
    metadata:
      namespace: production
      name: pod-reader
    rules:
    - apiGroups: [""]  # core API 그룹
      resources: ["pods", "pods/log"]
      verbs: ["get", "list", "watch"]  # 읽기 전용만 허용
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: read-pods
      namespace: production
    subjects:
    - kind: ServiceAccount
      name: monitoring-agent
      namespace: production
    roleRef:
      kind: Role
      name: pod-reader
      apiGroup: rbac.authorization.k8s.io
    

    💡 팁: 현재 클러스터에서 과도한 권한이 있는 바인딩을 빠르게 확인하려면 아래 명령어를 써보세요.

    # cluster-admin 권한을 가진 바인딩 전체 조회
    kubectl get clusterrolebindings -o json | \
      jq '.items[] | select(.roleRef.name == "cluster-admin") | .metadata.name'
    
    # 특정 서비스 계정의 권한 확인
    kubectl auth can-i --list --as=system:serviceaccount:production:my-app
    

    네트워크 정책으로 Pod 간 통신 제어하기

    기본적으로 쿠버네티스 클러스터 내 모든 Pod는 서로 통신할 수 있어요. 이게 편리하긴 한데, 보안 관점에서는 꽤 위험한 기본값이에요. 만약 하나의 Pod가 침해당하면 클러스터 내 모든 서비스로 횡적 이동(Lateral Movement)이 가능하거든요.

    NetworkPolicy(네트워크 정책)는 Pod 간 또는 Pod와 외부 간의 트래픽을 화이트리스트 방식으로 제어하는 k8s 리소스예요. 처음엔 이게 뭔가 복잡해 보였는데, 개념만 잡으면 생각보다 직관적이더라고요.

    기본 원칙: 먼저 모든 트래픽 차단 후 필요한 것만 열기

    # 1단계: 특정 네임스페이스의 모든 인바운드/아웃바운드 트래픽 차단
    apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: default-deny-all
      namespace: production
    spec:
      podSelector: {}  # 네임스페이스 내 모든 Pod에 적용
      policyTypes:
      - Ingress
      - Egress
    
    # 2단계: 필요한 트래픽만 허용 (예: frontend -> backend 통신)
    apiVersion: networking.k8s.io/v1
    kind: NetworkPolicy
    metadata:
      name: allow-frontend-to-backend
      namespace: production
    spec:
      podSelector:
        matchLabels:
          app: backend  # 이 정책이 적용될 Pod
      policyTypes:
      - Ingress
      ingress:
      - from:
        - podSelector:
            matchLabels:
              app: frontend  # frontend Pod에서 오는 트래픽만 허용
        ports:
        - protocol: TCP
          port: 8080
    

    ⚠️ 주의사항: NetworkPolicy는 CNI(Container Network Interface) 플러그인이 지원해야 동작해요. Calico, Cilium, Weave Net 등은 지원하지만, 기본 flannel은 NetworkPolicy를 지원하지 않아요. 클러스터 구성 전에 꼭 확인하세요!

    ▲ NetworkPolicy 적용 전후 Pod 간 트래픽 흐름 비교 — 기본 개방 상태와 화이트리스트 방식 적용 후 허용된 경로만 표시된 다이어그램


    컨테이너 보안 컨텍스트 설정하기

    컨테이너 보안에서 제일 많이 놓치는 부분이 바로 SecurityContext(시큐리티 컨텍스트)예요. 이 설정 하나만 제대로 해도 컨테이너 탈출(Container Escape) 공격을 상당 부분 방어할 수 있거든요.

    제가 보안 감사를 해드린 한 팀의 클러스터를 보니까, 거의 모든 Pod가 root 권한으로 실행되고 있었어요. 개발 편의를 위해 그렇게 설정했다고 하는데, 그건 컨테이너 안에서 root 권한을 얻은 공격자가 호스트 노드까지 공격할 수 있는 발판을 주는 거나 마찬가지예요.

    apiVersion: v1
    kind: Pod
    metadata:
      name: secure-pod
      namespace: production
    spec:
      securityContext:
        runAsNonRoot: true          # root로 실행 금지
        runAsUser: 1000             # 특정 UID로 실행
        runAsGroup: 3000            # 특정 GID로 실행
        fsGroup: 2000               # 볼륨 파일시스템 그룹
        seccompProfile:
          type: RuntimeDefault      # 기본 seccomp 프로파일 적용
      containers:
      - name: app
        image: my-app:1.0.0
        securityContext:
          allowPrivilegeEscalation: false  # 권한 상승 금지 (핵심!)
          readOnlyRootFilesystem: true     # 루트 파일시스템 읽기 전용
          capabilities:
            drop:
            - ALL                          # 모든 Linux 기능(capability) 제거
            add:
            - NET_BIND_SERVICE             # 필요한 것만 다시 추가
        resources:
          limits:
            cpu: "500m"
            memory: "128Mi"
          requests:
            cpu: "250m"
            memory: "64Mi"
    

    💡 핵심 포인트! allowPrivilegeEscalation: false는 반드시 설정하세요. 이 설정이 없으면 컨테이너 내부에서 sudo나 setuid 바이너리를 통해 권한 상승이 가능해요.

    Pod Security Admission으로 클러스터 전체에 정책 적용하기

    쿠버네티스 1.25부터 기존의 PodSecurityPolicy(PSP)가 제거되고 Pod Security Admission(PSA)이 정식 출시됐어요. 네임스페이스 레벨에서 보안 프로파일을 강제할 수 있는데, 세 가지 레벨이 있어요.

    레벨 설명 적용 권장 환경
    privileged 제한 없음 (기본값) 시스템 네임스페이스 (kube-system 등)
    baseline 최소한의 보안 제한 적용 일반 애플리케이션 네임스페이스
    restricted 가장 강력한 보안 제한 보안이 중요한 프로덕션 환경
    # 네임스페이스에 PSA 레벨 적용 (enforce: 위반 시 Pod 생성 거부)
    kubectl label namespace production \
      pod-security.kubernetes.io/enforce=restricted \
      pod-security.kubernetes.io/enforce-version=latest
    
    # warn: 경고만 (생성은 허용), audit: 감사 로그만 기록
    kubectl label namespace staging \
      pod-security.kubernetes.io/warn=baseline \
      pod-security.kubernetes.io/audit=restricted
    

    시크릿 관리와 etcd 암호화

    이건 진짜 많은 분들이 모르고 지나치는 부분인데요. 쿠버네티스 Secret은 기본적으로 암호화되지 않은 채로 etcd에 저장돼요. Base64 인코딩이 되어 있긴 하지만, 이건 암호화가 아니라 그냥 인코딩이에요. etcd에 직접 접근하면 바로 읽을 수 있거든요.

    # etcd에서 시크릿 평문 확인 (이게 되면 안 되는 거예요!)
    ETCDCTL_API=3 etcdctl get /registry/secrets/default/my-secret \
      --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 | hexdump -C
    

    etcd 암호화 설정하기

    # /etc/kubernetes/encryption-config.yaml
    apiVersion: apiserver.config.k8s.io/v1
    kind: EncryptionConfiguration
    resources:
    - resources:
      - secrets
      - configmaps  # configmap도 같이 암호화 권장
      providers:
      - aescbc:     # AES-CBC 암호화 방식
          keys:
          - name: key1
            secret: 
      - identity: {}  # 암호화 안 된 기존 데이터 읽기 위해 fallback
    
    # kube-apiserver에 암호화 설정 파일 적용 (kubeadm 기준)
    # /etc/kubernetes/manifests/kube-apiserver.yaml에 아래 플래그 추가
    # --encryption-provider-config=/etc/kubernetes/encryption-config.yaml
    
    # 기존 시크릿 모두 재암호화 (설정 후 반드시 실행!)
    kubectl get secrets --all-namespaces -o json | kubectl replace -f -
    

    ⚠️ 중요: 암호화 키는 반드시 안전하게 보관하세요. 키를 잃어버리면 모든 시크릿을 복구할 수 없어요. 실제 프로덕션에서는 AWS KMS, HashiCorp Vault, Azure Key Vault 같은 외부 키 관리 서비스(KMS)와 연동하는 걸 강력히 권장합니다.


    감사 로깅과 런타임 보안 모니터링

    보안은 예방도 중요하지만, 이상 행동을 빠르게 탐지하는 것도 똑같이 중요해요. Audit Logging(감사 로깅)을 설정하면 API 서버에 대한 모든 요청을 기록할 수 있어요.

    # /etc/kubernetes/audit-policy.yaml
    apiVersion: audit.k8s.io/v1
    kind: Policy
    rules:
    # 시크릿 접근은 반드시 RequestResponse 레벨로 상세 기록
    - level: RequestResponse
      resources:
      - group: ""
        resources: ["secrets"]
    
    # 인증 실패 이벤트 기록
    - level: Request
      users: ["system:anonymous"]
    
    # exec 명령어 실행 기록 (공격자가 주로 사용)
    - level: RequestResponse
      resources:
      - group: ""
        resources: ["pods/exec", "pods/attach", "pods/portforward"]
    
    # 그 외 일반 요청은 메타데이터만 기록
    - level: Metadata
      omitStages:
      - RequestReceived
    

    런타임 보안 모니터링 도구로는 Falco를 많이 사용해요. Falco는 CNCF(Cloud Native Computing Foundation) 프로젝트로, 커널 시스템 콜을 분석해서 컨테이너 내부의 이상 행동을 실시간으로 탐지해줘요.

    # Helm으로 Falco 설치
    helm repo add falcosecurity https://falcosecurity.github.io/charts
    helm repo update
    helm install falco falcosecurity/falco \
      --namespace falco \
      --create-namespace \
      --set falco.grpc.enabled=true \
      --set falco.grpc_output.enabled=true
    
    # Falco 로그 확인 (이상 탐지 이벤트)
    kubectl logs -l app.kubernetes.io/name=falco -n falco -f
    

    ▲ Falco 런타임 보안 모니터링 — 컨테이너 내부의 의심스러운 시스템 콜과 이상 행동이 실시간으로 탐지되는 대시보드 예시


    이미지 보안: 공급망 공격 방어

    최근 몇 년간 컨테이너 이미지를 통한 공급망 공격이 크게 늘었어요. 신뢰할 수 없는 이미지를 클러스터에 배포하면 그 자체가 침해의 시작이 될 수 있거든요.

    • ✅ 이미지 취약점 스캔: Trivy, Grype 같은 도구로 CI/CD 파이프라인에서 이미지 스캔 필수화
    • ✅ 이미지 서명 검증: Cosign + Sigstore로 이미지 서명 및 검증 (공급망 무결성 보장)
    • ✅ 신뢰할 수 있는 레지스트리만 허용: Admission Webhook으로 허용된 레지스트리 이미지만 배포 가능하도록 제한
    • ✅ latest 태그 금지: 이미지 버전을 명확하게 고정 (mutable tag는 보안 위험)
    • ✅ distroless 또는 minimal 이미지 사용: 불필요한 바이너리가 없는 이미지를 쓰면 공격 표면 자체가 줄어요
    # Trivy로 이미지 취약점 스캔
    trivy image --severity HIGH,CRITICAL nginx:1.25.3
    
    # Cosign으로 이미지 서명
    cosign sign --key cosign.key my-registry.io/my-app:1.0.0
    
    # Cosign으로 이미지 서명 검증
    cosign verify --key cosign.pub my-registry.io/my-app:1.0.0
    

    전체 보안 체크리스트 정리 및 다음 단계

    ▲ 쿠버네티스 보안 베스트 프랙티스 전체 체크리스트 — RBAC, 네트워크 정책, 컨테이너 보안, 시크릿 관리, 모니터링 항목이 단계별로 정리된 요약 인포그래픽

    여기까지 꽤 많은 내용을 다뤘는데요, 핵심을 정리해드릴게요.

    1. RBAC 최소 권한 원칙 — cluster-admin은 진짜 필요한 경우에만, 서비스 계정은 네임스페이스 범위 Role로 제한
    2. 네트워크 정책(k8s 보안의 방화벽) — 기본 차단 후 필요한 트래픽만 허용, CNI 지원 여부 먼저 확인
    3. SecurityContext 설정 — root 실행 금지, 권한 상승 차단, 읽기 전용 파일시스템 적용
    4. etcd 암호화 — Secret은 반드시 암호화, 가능하면 외부 KMS 연동
    5. 감사 로깅 + 런타임 모니터링 — 예방만큼 탐지도 중요, Falco 도입 검토
    6. 이미지 보안 — 스캔, 서명, 신뢰 레지스트리 제한까지 CI/CD에 통합

    처음부터 모든 걸 한 번에 적용하려고 하면 오히려 지쳐서 포기하게 돼요. 제 경험상 RBAC 정리 → NetworkPolicy → SecurityContext 순서로 하나씩 적용해나가는 게 가장 현실적이더라고요.

    다음 글에서는 OPA Gatekeeper를 활용한 쿠버네티스 정책 자동화를 다룰 예정이에요. Admission Webhook으로 보안 정책을 코드로 관리하는 방법인데, 이걸 도입하면 위에서 설명한 SecurityContext 설정 같은 것들을 개발자가 실수로 빠뜨려도 자동으로 차단하거나 수정할 수 있거든요. 꽤 강력합니다.

    혹시 이 글 읽으면서 “우리 클러스터 이거 안 돼 있는데…” 싶은 항목 있으셨나요? 댓글로 공유해주시면 같이 고민해볼게요. 저도 아직 배우는 중이거든요 😄


    자주 묻는 질문 (FAQ)

    Q. RBAC 설정이 복잡한데, 자동으로 감사하는 도구가 있나요?

    네! rbac-tool이나 kubectl-who-can 같은 플러그인을 사용하면 현재 클러스터의 RBAC 설정을 시각화하고 과도한 권한을 쉽게 찾을 수 있어요. kubectl krew install rbac-tool로 설치할 수 있습니다.

    Q. 관리형 쿠버네티스(EKS, GKE, AKS)를 쓰면 보안 설정이 덜 필요한가요?

    아니요. 관리형 서비스는 컨트롤 플레인(마스터 노드) 보안을 CSP가 담당하지만, RBAC, NetworkPolicy, SecurityContext, 시크릿 관리 같은 워크로드 수준의 보안은 여전히 사용자 책임이에요. 오히려 관리형이라고 방심하는 경우가 더 위험할 수 있어요.

    Q. 컨테이너 보안 스캔은 언제 하는 게 좋나요?

    이상적으로는 Shift Left 보안 원칙에 따라 개발자 로컬 환경 → CI 파이프라인 → 레지스트리 푸시 전 → 배포 전 총 4단계에서 스캔하는 게 좋아요. 최소한 CI 파이프라인에는 반드시 포함시키세요.

  • [k8s] 쿠버네티스 모니터링: Prometheus & Grafana 구축 및 대시보드 활용 가이드

    [k8s] 쿠버네티스 모니터링: Prometheus & Grafana 구축 및 대시보드 활용 가이드

    🚀 쿠버네티스 모니터링, 왜 중요할까요?

    안녕하세요, 13년차의 서버실 주인장입니다. 오늘은 쿠버네티스 모니터링의 핵심이라고 할 수 있는 Prometheus(프로메테우스)와 Grafana(그라파나) 구축 경험을 공유해볼까 합니다. 쿠버네티스 환경을 운영하다 보면 ‘도대체 내 파드는 잘 돌고 있나?’, ‘CPU 사용량이 왜 이렇게 높지?’, ‘메모리 누수가 생긴 건 아닐까?’ 같은 고민을 하게 되죠.

    저도 처음 쿠버네티스를 도입했을 때, 여러 파드들이 여기저기서 돌아다니는데 이걸 어떻게 한눈에 볼 수 있을까 막막했어요. 로그를 일일이 뒤져보는 것도 한계가 있고요. 그때 제 눈을 번쩍 뜨이게 한 것이 바로 Prometheus와 Grafana 조합이었습니다. 이 두 가지 도구 덕분에 제 홈랩의 쿠버네티스 클러스터는 24시간 감시 체제를 갖추게 되었고, 문제가 생기면 빠르게 파악하고 조치할 수 있게 됐죠. 마치 제 서버실에 똑똑한 비서 한 명을 들인 기분이랄까요?

    이번 글에서는 이 강력한 모니터링 스택을 어떻게 구축하고, 어떤 대시보드를 활용하면 좋을지 제 경험을 녹여서 자세히 알려드리겠습니다. 삽질했던 부분들도 솔직하게 공유할 테니, 여러분은 저처럼 헤매지 않으시길 바랍니다! 자, 그럼 시작해볼까요?

    쿠버네티스 환경에서 Prometheus와 Grafana를 이용한 모니터링 시스템의 전체 아키텍처 다이어그램입니다.

    💡 Prometheus와 Grafana, 핵심 개념 파헤치기

    자, 이제 본론으로 들어가서 쿠버네티스 모니터링의 양대 산맥인 Prometheus(프로메테우스)와 Grafana(그라파나)에 대해 좀 더 깊이 있게 알아볼까요? 처음엔 이름도 어렵고, 뭐가 뭔지 헷갈렸는데, 사실 원리만 이해하면 생각보다 간단하더라고요.

    Prometheus (프로메테우스): 지표 수집의 달인

    Prometheus는 오픈 소스 모니터링 시스템으로, 시계열 데이터베이스(Time-series Database, TSDB)를 기반으로 합니다. 쉽게 말해, 시간의 흐름에 따라 변화하는 다양한 지표(Metrics)들을 수집하고 저장하는 데 특화된 도구거든요. 기존의 많은 모니터링 시스템이 에이전트가 데이터를 서버로 밀어 넣는 Push 방식이었다면, Prometheus는 대상으로부터 데이터를 Pull(가져오는) 방식을 사용합니다. 이 방식은 서비스 디스커버리(Service Discovery)와 결합될 때 쿠버네티스 같은 동적인 환경에서 정말 큰 시너지를 내거든요.

    • Metrics (메트릭, 지표 데이터): CPU 사용량, 메모리 사용량, 네트워크 트래픽 등 서버나 애플리케이션의 상태를 나타내는 수치 데이터입니다.
    • Exporters (익스포터): Prometheus가 지표를 가져올 수 있도록 데이터를 노출하는 작은 에이전트예요. 예를 들어, 서버의 OS 지표를 수집하는 Node Exporter나 쿠버네티스 노드/파드의 지표를 수집하는 cAdvisor 같은 것들이죠.
    • Service Discovery (서비스 디스커버리): 쿠버네티스 환경에서는 파드(Pod)가 수시로 생성되고 사라집니다. Prometheus는 이런 변화를 감지해서 자동으로 새로운 모니터링 대상을 찾아냅니다. 정말 편리하더라고요.

    Grafana (그라파나): 시각화의 마법사

    Prometheus가 지표를 열심히 수집하고 저장해놨다면, Grafana는 그 데이터를 멋진 그래프와 대시보드로 시각화해주는 도구입니다. 복잡한 숫자들을 한눈에 알아보기 쉽게 보여주니까, 이상 징후를 빠르게 파악하고 문제 해결에 집중할 수 있게 도와주죠. 처음에는 Grafana UI가 좀 어려웠는데, 몇 번 써보니 이거 진짜 물건이더라고요! 다양한 데이터 소스(Prometheus 외에도 많은 DB를 지원합니다)를 연결해서 대시보드를 만들 수 있고, 커스텀도 자유롭습니다.

    🛠️ 실전! Helm으로 Prometheus & Grafana 배포하기

    이제 이론은 충분히 봤으니, 실제로 쿠버네티스 클러스터에 Prometheus와 Grafana를 배포해보겠습니다. 저는 Helm(헬름)을 이용하는 것을 선호하는데, 복잡한 쿠버네티스 리소스들을 한 번에 쉽게 배포하고 관리할 수 있거든요. 마치 패키지 매니저처럼요!

    사전 준비물

    1. 동작하는 쿠버네티스 클러스터 (저는 홈랩에서 Kubeadm으로 구성한 클러스터를 사용했습니다.)
    2. Helm v3 이상 설치
    3. (선택 사항) PersistentVolume(영구 볼륨)을 위한 StorageClass(스토리지 클래스) 설정 (데이터 유실 방지를 위해 권장합니다)

    Step 1: Helm Repository 추가

    Prometheus와 Grafana를 포함하는 <code>kube-prometheus-stack은 Helm 차트로 제공됩니다. 먼저 Helm 레포지토리를 추가해주세요.

    helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
    helm repo update

    Step 2: Prometheus 스택 배포

    이제 kube-prometheus-stack을 배포할 차례입니다. 이 차트 안에는 Prometheus, Grafana, Alertmanager(알림 관리자), Kube-State-Metrics(쿠버네티스 상태 지표 수집기), Node Exporter(노드 지표 수집기) 등 쿠버네티스 모니터링에 필요한 모든 것이 한 번에 들어있어서 정말 편합니다. 저는 보통 monitoring 네임스페이스에 배포합니다.

    ⚠️ 중요: 프로덕션 환경에서는 values.yaml 파일을 통해 스토리지 클래스, 리소스 제한, 서비스 타입 등을 반드시 커스터마이징해야 합니다. 저는 홈랩이라 기본 설정으로 진행했지만, 여러분은 꼭 신경 써주세요!

    # values.yaml 파일 예시 (간단하게 스토리지 클래스만 지정)
    # my-prometheus-values.yaml
    
    prometheus:
      prometheusSpec:
        storageSpec:
          volumeClaimTemplate:
            spec:
              storageClassName: my-storage-class # 본인의 StorageClass 이름으로 변경
              resources:
                requests:
                  storage: 10Gi
    
    grafana:
      persistence:
        enabled: true
        storageClassName: my-storage-class # 본인의 StorageClass 이름으로 변경
        size: 5Gi
    

    이제 위 values.yaml 파일을 적용하여 배포합니다.

    helm install prometheus prometheus-community/kube-prometheus-stack \
      --namespace monitoring --create-namespace \
      -f my-prometheus-values.yaml # 커스터마이징한 values.yaml 파일 적용

    배포가 완료되면 kubectl get pods -n monitoring 명령어로 파드들이 잘 떠 있는지 확인해보세요. 모든 파드가 Running 상태라면 성공입니다! 🎉

    Step 3: Grafana 접속 및 초기 설정

    Grafana는 기본적으로 ClusterIP 타입의 서비스로 배포됩니다. 외부에서 접속하려면 Ingress(인그레스, 외부 트래픽 진입점)를 설정하거나, 간단하게 포트 포워딩(Port-forwarding)을 이용할 수 있어요. 저는 테스트를 위해 포트 포워딩을 자주 사용합니다.

    kubectl port-forward svc/prometheus-grafana 3000:80 -n monitoring

    이제 웹 브라우저에서 http://localhost:3000으로 접속해보세요. 초기 로그인 정보는 다음과 같습니다.

    • User (사용자): admin
    • Password (비밀번호): prom-operator (또는 kubectl get secret prometheus-grafana -n monitoring -o jsonpath='{.data.admin-password}' | base64 --decode 명령어로 확인)

    로그인 후에는 비밀번호 변경을 요청할 겁니다. 안전하게 변경해주세요!

    Grafana에서 Prometheus 데이터 소스를 추가하는 설정 화면입니다.

    📊 나만의 쿠버네티스 대시보드 만들기 & 활용하기

    Grafana에 접속했다면 이제 Prometheus 데이터를 시각화할 차례예요. kube-prometheus-stack 덕분에 Prometheus 데이터 소스는 이미 설정되어 있을 겁니다. 혹시 없다면, Configuration > Data Sources에서 Prometheus를 추가하고 URL을 http://prometheus-kube-prometheus-prometheus.monitoring.svc.cluster.local:9090 (네임스페이스와 서비스 이름에 따라 다를 수 있음)으로 설정하면 됩니다.

    기본 대시보드 활용하기

    kube-prometheus-stack은 기본적으로 여러 유용한 대시보드들을 Grafana에 자동으로 임포트해줍니다. 왼쪽 메뉴에서 Dashboards > Manage로 이동해보세요. 아마 Kubernetes / Compute Resources, Node Exporter Full 같은 대시보드들을 볼 수 있을 겁니다. 저도 처음엔 이 대시보드들만으로도 충분히 모니터링이 가능해서 정말 편하더라고요.

    Grafana Labs 공유 대시보드 임포트하기

    만약 더 다양한 대시보드를 원한다면, Grafana Labs 웹사이트(https://grafana.com/grafana/dashboards/)에서 다른 사람들이 공유한 대시보드를 임포트할 수 있습니다. 예를 들어, Node Exporter Full 대시보드(ID: 1860)나 Kubernetes Cluster Overview(ID: 12150) 같은 것들이 인기가 많죠.

    1. Grafana 좌측 메뉴에서 + > Import를 클릭합니다.
    2. Import via grafana.com dashboard 칸에 대시보드 ID (예: 1860)를 입력하고 Load를 클릭합니다.
    3. 대시보드 이름, 폴더를 설정하고, Prometheus 데이터 소스를 선택한 후 Import를 클릭합니다.

    짜잔! 멋진 대시보드가 눈앞에 펼쳐질 겁니다. 🤩

    나만의 대시보드 커스터마이징

    기존 대시보드를 활용하는 것도 좋지만, 특정 애플리케이션이나 서비스에 특화된 대시보드 구축은 필수입니다. 저는 주로 복제(Duplicate) 기능을 이용해서 기존 대시보드를 복사한 다음, 필요한 패널(Panel)을 추가하거나 수정하는 방식으로 커스터마이징합니다. PromQL(프로메테우스 쿼리 언어)을 조금만 익히면 원하는 지표를 자유자재로 뽑아낼 수 있거든요.

    Prometheus와 Grafana를 통해 구현된 쿠버네티스 클러스터 모니터링 대시보드 예시입니다.

    ⚠️ 삽질 대잔치! 트러블슈팅 경험담

    인프라 엔지니어의 삶은 삽질의 연속이죠. 저도 Prometheus & Grafana 구축 과정에서 몇 번의 삽질을 경험했어요. 여러분은 이런 문제들을 미리 알고 피하시길 바랍니다.

    1. PersistentVolumeClaim (PVC) Pending 문제

    증상: Prometheus나 Grafana 파드가 Pending 상태에서 벗어나지 못하고, PVC가 Pending으로 남아있을 때입니다.

    원인: 대부분 StorageClass가 없거나, 잘못 지정되었을 때 발생합니다. Prometheus는 데이터를 저장하기 위해 영구 스토리지를 써야 하는데, 이를 위한 StorageClass가 없으면 볼륨을 프로비저닝할 수 없거든요.

    해결: 클러스터에 NFS CSI Driver나 Longhorn 같은 동적 프로비저너를 설치하고, 해당 StorageClass를 values.yaml에 올바르게 지정해주세요. 저는 처음에 이 부분을 놓쳐서 한참 헤맸습니다. 🤦‍♂️

    2. 리소스 부족으로 인한 OOMKilled

    증상: Prometheus 파드가 자꾸 재시작되면서 OOMKilled(Out Of Memory Killed) 오류가 발생합니다.

    원인: Prometheus는 수집하는 지표의 양이 많아질수록 메모리 사용량이 늘어나요. 기본 설정된 리소스 제한(Resource Limits)이 클러스터 규모에 비해 너무 낮을 때 발생하는 거죠.

    해결: values.yaml에서 Prometheus 파드의 resources.requests와 resources.limits를 적절히 늘려주세요. 특히 memory 부분을 여유 있게 설정하는 게 중요합니다. 너무 많이 늘리면 다른 파드에 영향을 줄 수 있으니, 모니터링하면서 점진적으로 조정하는 것을 추천합니다.

    3. Prometheus가 타겟을 찾지 못하는 문제

    증상: Grafana 대시보드에서 데이터가 보이지 않거나, Prometheus UI의 Targets 페이지에서 특정 파드가 DOWN 상태로 표시될 때입니다.

    원인: Prometheus의 서비스 디스커버리 설정이 잘못되었거나, 파드에 올바른 레이블(Label)이 지정되지 않았을 때, 혹은 네트워크 정책(Network Policy) 등으로 인해 Prometheus가 파드의 익스포터에 접근하지 못할 때 발생합니다.

    해결:

    • 해당 파드에 Prometheus가 찾을 수 있는 annotations나 labels가 잘 붙어있는지 확인합니다. (예: prometheus.io/scrape: "true")
    • ServiceMonitor 또는 PodMonitor 리소스가 올바르게 정의되어 있는지 확인합니다.
    • 네트워크 정책이 Prometheus 파드에서 대상 파드로의 트래픽을 허용하는지 검토합니다.

    제가 직접 커스텀 애플리케이션을 모니터링할 때 이 문제로 고생 좀 했어요. 애플리케이션 파드에 어노테이션을 빼먹어서 그랬더라고요. ㅎㅎ

    ✅ 구축 결과 확인 및 다음 단계 제안

    이제 여러분의 쿠버네티스 클러스터는 Prometheus와 Grafana라는 강력한 모니터링 시스템을 갖추게 되었습니다. Grafana 대시보드를 통해 노드의 CPU/메모리 사용량, 파드의 상태, 네트워크 트래픽 등 다양한 지표들을 한눈에 볼 수 있을 겁니다. 문제가 발생하면 즉시 알 수 있고, 미리 예방할 수도 있게 되는 거죠. 정말 뿌듯하지 않나요? 🎉

    저도 처음 이 대시보드를 보면서 ‘드디어 됐다!’ 싶었던 기억이 생생하네요. 덕분에 제 홈랩 클러스터가 훨씬 더 안정적으로 운영되고 있습니다.

    다음 단계로 나아가기

    여기서 멈추지 마세요! 쿠버네티스 모니터링은 계속 발전해야 합니다. 몇 가지 다음 단계를 제안해봅니다.

    • Alertmanager(알림 관리자) 설정: Prometheus가 수집한 지표를 기반으로 알림(Alert)을 생성하고, 이를 Slack, 이메일, PagerDuty 등으로 전송하도록 설정해보세요. 저는 슬랙으로 알림을 받는데, 긴급 상황 발생 시 정말 유용합니다.
    • Custom Exporter 개발: 여러분의 특정 애플리케이션에서만 나오는 커스텀 지표를 수집하고 싶다면, 직접 익스포터를 개발해보는 것도 좋은 경험입니다. Python이나 Go 언어로 쉽게 만들 수 있어요.
    • 장기 지표 저장 (Long-term Storage): Prometheus는 기본적으로 로컬 스토리지를 써요. 장기간 지표를 보관하고 싶다면 Thanos(타노스)나 Cortex(코텍스) 같은 솔루션을 연동하여 스케일 아웃 및 장기 보관 기능을 추가할 수 있습니다.

    Prometheus 및 Grafana 기반 쿠버네티스 모니터링 시스템의 주요 이점과 활용 방안을 요약한 인포그래픽입니다.

    맺음말: 13년차 엔지니어의 조언

    쿠버네티스 모니터링은 클러스터 운영의 핵심이자, 인프라 엔지니어의 역량을 보여주는 중요한 부분입니다. 처음에는 어렵게 느껴질 수 있지만, 이렇게 직접 구축하고 활용해보면서 얻는 경험은 그 어떤 이론보다 값지다고 생각합니다. 저도 13년차 엔지니어이지만, 여전히 새로운 기술을 배우고 직접 손으로 만져보면서 배우는 것이 가장 즐겁고 효과적하더라고요.

    오늘 제가 공유한 내용이 여러분의 쿠버네티스 여정에 작은 도움이 되었기를 바랍니다. 혹시 진행 중에 궁금한 점이나 막히는 부분이 있다면 언제든지 댓글로 남겨주세요. 제가 아는 선에서 최대한 도와드리겠습니다. 다음에는 Alertmanager 설정이나 Custom Exporter 개발 경험에 대해서도 다뤄볼 예정이니 기대해주세요!

    다음 글에서 또 만나요! ✋

  • [k8s] Kubernetes Longhorn 스토리지: 설치부터 운영까지 완벽 가이드

    [k8s] Kubernetes Longhorn 스토리지: 설치부터 운영까지 완벽 가이드

    안녕하세요, 13년차 서버실 지킴이입니다. 🤓

    오늘은 제가 홈랩에서 Kubernetes(쿠버네티스) 클러스터를 운영하면서 겪었던 스토리지 고민과 그 해결책, 바로 Longhorn(롱혼)에 대해 이야기해보려고 합니다. 쿠버네티스에서 컨테이너 애플리케이션을 운영하다 보면, 데이터 영속성(Persistence) 확보가 정말 중요한데요. 특히 분산 스토리지(Distributed Storage)는 고가용성(High Availability)과 데이터 안정성을 위해 필수적이죠. 처음엔 로컬 스토리지를 PersistentVolume(PV)으로 직접 연결해보기도 하고, NFS(Network File System)를 써보기도 했는데, 이게 또 생각보다 관리하기가 만만치 않더라고요.

    그러다 우연히 Longhorn을 알게 되었고, 직접 설치하고 운영해보니 “아, 이거다!” 싶었습니다. 설치도 비교적 간단하고, 웹 UI로 볼륨 관리도 직관적이라 삽질 좀 덜 수 있었거든요. 오늘은 저의 경험을 바탕으로 Longhorn을 처음 접하시는 분들도 쉽게 따라할 수 있도록 설치부터 운영까지 완벽 가이드를 준비해봤습니다. 함께 시작해볼까요?

    쿠버네티스 클러스터 내 롱혼 분산 스토리지 아키텍처 개요

    이미지 캡션: 쿠버네티스 클러스터 내 롱혼 분산 스토리지 아키텍처 개요. 여러 노드에 걸쳐 데이터가 복제되고 관리되는 모습을 보여줍니다.

    💡 Longhorn, 넌 누구냐? (핵심 개념 설명)

    자, 그럼 먼저 Longhorn이 뭔지부터 알아봐야겠죠? Longhorn은 CNCF(Cloud Native Computing Foundation) 프로젝트 중 하나로, 쿠버네티스를 위한 분산 블록 스토리지 시스템입니다. 쉽게 말해, 쿠버네티스 클러스터 내의 여러 노드에 있는 디스크들을 모아서 하나의 거대한 가상 스토리지 풀을 만들고, 이 풀에서 PersistentVolume(영구 볼륨)을 생성하여 파드(Pod)에 제공해주는 역할을 해요.

    • 분산 스토리지 (Distributed Storage): 여러 노드의 저장 공간을 하나로 묶어 사용하며, 데이터가 여러 노드에 복제되어 저장되기 때문에 특정 노드에 문제가 생겨도 데이터 유실 걱정을 덜 수 있습니다.
    • CSI (Container Storage Interface, 컨테이너 스토리지 인터페이스) 호환: 쿠버네티스의 표준 스토리지 인터페이스인 CSI를 완벽하게 지원하기 때문에, 쿠버네티스에서 제공하는 StorageClass(스토리지 클래스), PersistentVolumeClaim(PVC, 영구 볼륨 클레임) 등의 기능을 문제없이 쓸 수 있습니다.
    • 스냅샷 및 백업/복구: 볼륨의 스냅샷을 찍고, S3와 같은 오브젝트 스토리지(Object Storage)나 NFS로 백업 및 복구를 쉽게 할 수 있어요. 제가 써보니 이 기능이 정말 편하더라고요!

    사실 처음엔 이런 분산 스토리지가 복잡하고 어렵게 느껴졌는데, Longhorn은 웹 UI가 워낙 직관적이라 금방 익숙해질 수 있었습니다. 덕분에 홈랩에서 여러 스테이트풀(Stateful) 애플리케이션들을 안정적으로 운영할 수 있게 되었죠. 예를 들어, 제 홈랩의 Prometheus(프로메테우스)나 Grafana(그라파나) 같은 모니터링 툴의 데이터도 Longhorn 볼륨에 저장해서 쓰고 있거든요.

    🛠️ 실전 구현: Longhorn 설치부터 PersistentVolume 사용까지

    이제 본격적으로 Longhorn을 설치하고 사용하는 방법을 알아볼 차례입니다. 저는 Helm(헬름)을 이용해서 설치하는 방법을 선호합니다. 배포가 간편하고 버전 관리가 용이하거든요. 시작하기 전에 몇 가지 준비물이 필요합니다.

    ✅ 준비물 확인

    1. Kubernetes 클러스터: 최소 3개 이상의 노드(Node)를 권장합니다. 각 노드에 충분한 여유 디스크 공간이 필요합니다.
    2. iSCSI initiator 설치: Longhorn은 iSCSI 프로토콜을 사용합니다. 각 노드에 <code>iscsi-initiator-utils (CentOS/RHEL) 또는 open-iscsi (Ubuntu/Debian) 패키지가 설치되어 있어야 합니다. 제가 처음 이걸 몰라서 삽질 좀 했습니다. 꼭 확인하세요!
      
      # CentOS/RHEL 계열
      sudo yum install -y iscsi-initiator-utils
      sudo systemctl enable --now iscsid
      
      # Ubuntu/Debian 계열
      sudo apt update
      sudo apt install -y open-iscsi
      sudo systemctl enable --now iscsid
      
    3. Helm 설치: 클러스터에 Helm이 설치되어 있어야 합니다.

    🚀 Longhorn 설치하기

    Helm을 이용하면 Longhorn 설치는 정말 간단합니다. 다음 명령어를 순서대로 실행해주세요.

    
    # 1. Longhorn Helm 레포지토리 추가
    helm repo add longhorn https://charts.longhorn.io
    helm repo update
    
    # 2. Longhorn 네임스페이스 생성 (선택 사항이지만 권장)
    kubectl create namespace longhorn-system
    
    # 3. Longhorn 설치 (기본 설정으로 충분합니다)
    helm install longhorn longhorn/longhorn --namespace longhorn-system --version 1.5.3 # 버전은 최신 안정 버전을 확인하세요!
    

    설치가 완료되면, 잠시 기다리면 모든 Longhorn 컴포넌트 파드들이 longhorn-system 네임스페이스에 배포되고 실행될 겁니다. kubectl get pods -n longhorn-system 명령으로 확인해보세요. 모든 파드가 Running 상태인지 확인하는 것이 중요합니다.

    🌐 Longhorn UI 접속하기

    Longhorn은 웹 UI를 제공해서 볼륨 상태, 노드 상태 등을 직관적으로 확인할 수 있습니다. UI에 접속하려면 보통 Ingress(인그레스, 외부 트래픽 진입점)를 설정하거나 NodePort(노드포트) 서비스를 생성하는 방법이 있습니다. 저는 간단하게 포트 포워딩(Port Forwarding)으로 접속해보겠습니다.

    
    # Longhorn UI 서비스 찾기
    kubectl get svc -n longhorn-system
    
    # UI 서비스 포트 포워딩 (예: longhorn-frontend 서비스)
    kubectl -n longhorn-system port-forward svc/longhorn-frontend 8080:80
    

    이제 웹 브라우저에서 http://localhost:8080으로 접속하면 Longhorn 대시보드를 볼 수 있습니다. 🎉 드디어 Longhorn의 세상으로 들어온 것을 환영합니다!

    롱혼 웹 UI 대시보드 화면. 클러스터 노드 스토리지 상태 및 볼륨 목록 확인

    이미지 캡션: Longhorn 웹 UI 대시보드 화면. 클러스터 내 노드들의 스토리지 상태와 생성된 볼륨 목록을 한눈에 확인할 수 있습니다.

    ⚙️ StorageClass 생성 및 PersistentVolumeClaim 사용

    Longhorn이 설치되었으니, 이제 쿠버네티스에서 스토리지를 사용할 차례입니다. Longhorn은 기본 StorageClass(스토리지 클래스)를 자동으로 생성하지만, 필요에 따라 커스터마이징할 수 있습니다. 저는 기본 StorageClass를 사용하되, 예시로 PVC를 만들어보겠습니다.

    
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: my-longhorn-pvc
    spec:
      accessModes:
        - ReadWriteOnce # 하나의 파드에서만 읽기/쓰기 가능
      storageClassName: longhorn # Longhorn이 생성한 기본 StorageClass 이름
      resources:
        requests:
          storage: 5Gi # 5GB 볼륨 요청
    

    위 YAML 파일을 pvc.yaml로 저장하고 적용합니다.

    
    kubectl apply -f pvc.yaml
    kubectl get pvc my-longhorn-pvc
    

    PVC가 Pending에서 Bound 상태로 바뀌면 성공입니다. 이제 이 PVC를 사용하는 파드를 배포해봅시다. 간단한 Nginx(엔진엑스) 파드를 예시로 들어보겠습니다.

    
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx-with-longhorn
    spec:
      selector:
        matchLabels:
          app: nginx
      replicas: 1
      template:
        metadata:
          labels:
            app: nginx
        spec:
          containers:
            - name: nginx
              image: nginx:latest
              ports:
                - containerPort: 80
              volumeMounts:
                - name: longhorn-volume
                  mountPath: /usr/share/nginx/html # Nginx 웹 페이지 경로
          volumes:
            - name: longhorn-volume
              persistentVolumeClaim:
                claimName: my-longhorn-pvc # 위에서 생성한 PVC 이름
    

    위 YAML 파일을 nginx-deployment.yaml로 저장하고 적용하면, Nginx 파드가 Longhorn 볼륨을 마운트하여 시작됩니다. 이제 /usr/share/nginx/html 경로에 데이터를 써보면, 파드가 재시작되거나 다른 노드로 옮겨가도 데이터가 그대로 유지되는 것을 확인할 수 있습니다. 💡

    ⚠️ 삽질 경험: 주의사항 및 트러블슈팅

    제가 Longhorn을 운영하면서 겪었던 몇 가지 삽질 경험과 주의사항을 공유해드릴게요. 독자분들은 저처럼 고생하지 마시라고요! ㅎㅎ

    • iSCSI initiator 문제: 가장 흔한 문제 중 하나입니다. 노드에 iscsi-initiator-utils나 open-iscsi가 설치되어 있지 않거나, iscsid 서비스가 실행 중이 아니라서 볼륨 마운트가 실패하는 경우가 많습니다. 꼭 설치 여부와 서비스 상태를 확인해주세요!
    • 네트워크 대역폭: Longhorn은 데이터를 여러 노드에 복제하기 때문에, 노드 간 네트워크 대역폭이 충분해야 합니다. 네트워크가 느리면 볼륨 성능 저하로 이어질 수 있습니다. 특히 홈랩 환경에서는 유선 네트워크를 사용하는 것이 좋습니다.
    • 디스크 공간 관리: Longhorn은 노드의 가용 디스크 공간을 사용합니다. 볼륨을 너무 많이 생성하거나 스냅샷을 자주 찍으면 노드의 디스크 공간이 부족해질 수 있습니다. Longhorn UI에서 각 노드의 디스크 사용량을 주기적으로 확인하고, 불필요한 스냅샷이나 백업은 정리하는 습관을 들이는 것이 좋습니다.
    • 노드 드레인(Drain) 시 주의: 쿠버네티스 노드를 유지보수할 때 kubectl drain 명령을 사용하죠. Longhorn 볼륨이 마운트된 파드가 있는 노드를 드레인할 때는 Longhorn이 해당 볼륨을 다른 노드로 안전하게 옮길 수 있도록 충분한 시간을 주어야 합니다. 급하게 드레인하면 볼륨이 Faulted 상태가 될 수도 있더라고요.

    ✅ 검증 및 결과: Longhorn 볼륨 확인하기

    모든 설치와 설정이 끝났으니, 이제 제대로 작동하는지 확인해볼 차례입니다. 저는 Nginx 파드에 접속해서 간단한 HTML 파일을 만들어보고, 파드를 삭제 후 다시 생성하여 데이터 영속성을 확인하는 방법을 즐겨 씁니다.

    
    # Nginx 파드 이름 확인
    kubectl get pods -l app=nginx
    
    # Nginx 파드 내부로 접속하여 파일 생성
    kubectl exec -it <nginx-pod-name> -- bash
    echo "Hello from Longhorn!" > /usr/share/nginx/html/index.html
    exit
    
    # Nginx 서비스 포트 포워딩 (테스트용)
    kubectl port-forward svc/<nginx-service-name> 8080:80 # Nginx 서비스가 없다면 배포해야 합니다.
    
    # 웹 브라우저에서 http://localhost:8080 접속하여 내용 확인
    

    이제 Nginx 파드를 삭제했다가 다시 생성해보세요. 그리고 다시 접속해보면, 이전에 작성했던 “Hello from Longhorn!” 메시지가 그대로 남아있는 것을 확인할 수 있을 겁니다. 🎉 드디어 영구적인 스토리지를 성공적으로 구축한 거죠!

    Nginx 파드에 마운트된 Longhorn 볼륨과 데이터 영속성 확인 화면

    이미지 캡션: Nginx 파드에 성공적으로 마운트된 Longhorn 볼륨과 데이터 영속성을 확인하는 모습. 웹 브라우저를 통해 저장된 내용을 확인하고 있습니다.

    마무리: 13년차 서버실 지킴이의 한마디

    오늘은 Kubernetes Longhorn(쿠버네티스 롱혼) 스토리지의 설치부터 운영까지 제가 직접 경험한 내용을 바탕으로 자세히 설명해드렸습니다. Longhorn은 쿠버네티스 환경에서 영구 볼륨(Persistent Volume)을 안정적이고 유연하게 제공하는 훌륭한 분산 스토리지 솔루션이라고 생각합니다. 특히 홈랩이나 소규모 클러스터 환경에서는 초기 구축 비용이나 복잡성 측면에서 다른 엔터프라이즈 솔루션보다 훨씬 매력적이죠. 저는 Longhorn 덕분에 홈랩에서 다양한 스테이트풀 애플리케이션들을 걱정 없이 운영하고 있습니다. 백업과 스냅샷 기능도 정말 유용하구요!

    물론 Longhorn도 만능은 아닙니다. 대규모 엔터프라이즈 환경에서는 Ceph(세프)나 NetApp(넷앱) 같은 더욱 강력하고 복잡한 솔루션들이 필요할 수도 있습니다. 하지만 “간단하게 시작해서 점진적으로 확장하고 싶다”는 분들에게는 Longhorn이 정말 좋은 선택지가 될 거라고 확신합니다. 제 경험상, 중요한 건 어떤 툴을 쓰느냐보다, 그 툴을 얼마나 잘 이해하고 자신의 환경에 맞게 활용하느냐인 것 같아요. 저도 아직 배워야 할 게 많지만, 계속해서 새로운 기술들을 실험하고 삽질하면서 여러분께 유용한 정보를 공유해드리겠습니다.

    다음 글에서는 Longhorn의 백업 및 복구 기능에 대해 더 자세히 다뤄보거나, Longhorn 볼륨의 성능 튜닝 방법에 대해 이야기해볼까 합니다. 궁금한 점이 있다면 언제든지 댓글로 남겨주세요! 다음에 또 유익한 정보로 찾아뵙겠습니다. 감사합니다! 😊

    Longhorn 주요 특징, 장단점 및 다른 쿠버네티스 스토리지 솔루션 비교 인포그래픽

    이미지 캡션: Longhorn의 주요 특징과 장단점을 요약한 인포그래픽. 쿠버네티스 스토리지 선택에 있어 Longhorn의 위치를 보여줍니다.

  • [쿠버네티스] Nginx vs Traefik Ingress Controller 선택 가이드: 13년차 엔지니어의 경험담

    [쿠버네티스] Nginx vs Traefik Ingress Controller 선택 가이드: 13년차 엔지니어의 경험담

    [쿠버네티스] Nginx vs Traefik Ingress Controller 선택 가이드: 13년차 엔지니어의 경험담

    안녕하세요, 13년차 서버실을 지키는 인프라 엔지니어입니다. 쿠버네티스(Kubernetes) 환경에서 애플리케이션을 운영하다 보면, 외부 트래픽을 어떻게 효율적으로 서비스에 연결할지가 항상 큰 고민이 됩니다. 특히 여러 서비스를 운영할수록 이 문제는 더욱 복잡해지죠. 처음엔 저도 단순히 <code>NodePort나 LoadBalancer 서비스를 사용했었는데, 점점 더 많은 도메인과 복잡한 라우팅 규칙을 관리해야 하는 상황에 부딪히더라고요. 이럴 때 필요한 것이 바로 Ingress Controller(인그레스 컨트롤러)입니다.

    오늘은 제가 홈랩(Homelab)에서 Nginx Ingress Controller와 Traefik Ingress Controller를 모두 사용해보면서 겪었던 경험과 두 솔루션의 장단점을 솔직하게 비교해드릴게요. 어떤 상황에서 어떤 Ingress Controller를 선택하는 것이 좋을지 제 경험을 토대로 멘토처럼 알려드리겠습니다. 이 글이 여러분의 쿠버네티스 트래픽 관리 고민을 덜어주면 정말 좋겠어요.

    쿠버네티스 Ingress Controller의 역할과 외부 트래픽 흐름을 보여주는 아키텍처 다이어그램

    쿠버네티스 클러스터 내에서 Ingress Controller가 외부 트래픽을 서비스로 라우팅하는 전체 아키텍처를 보여주는 다이어그램입니다. 외부 로드밸런서에서 Ingress Controller로, 다시 Ingress Rule에 따라 내부 서비스로 트래픽이 흐르는 과정을 시각화합니다.

    Ingress Controller, 대체 뭘까요?

    쿠버네티스에서 Ingress(인그레스, 외부 트래픽 진입점)는 클러스터 내부의 서비스(Service)로 외부 트래픽을 라우팅하는 규칙들을 정의하는 API 오브젝트죠. 쉽게 말해, example.com으로 들어온 요청은 web-service로 보내고, api.example.com/v1으로 들어온 요청은 api-service로 보내는 것과 같은 규칙을 정의하는 거예요. 하지만 Ingress 오브젝트 자체는 단순히 규칙을 정의할 뿐, 실제로 그 규칙에 따라 트래픽을 처리하는 역할을 하지는 않습니다. 바로 이걸 실제로 처리하는 게 Ingress Controller(인그레스 컨트롤러)입니다.

    Ingress Controller는 클러스터 내부에서 실행되는 일종의 역방향 프록시(Reverse Proxy) 또는 로드 밸런서(Load Balancer)로, Ingress 리소스에 정의된 규칙을 읽어 실제 트래픽 라우팅을 수행합니다. 대표적으로 Nginx, Traefik, HAProxy, Envoy 등의 솔루션들이 Ingress Controller로 활용될 수 있습니다. 이 중에서 가장 널리 사용되고 제가 직접 많이 써본 Nginx와 Traefik을 중심으로 이야기해볼게요.

    Nginx Ingress Controller 파헤치기

    Nginx Ingress Controller는 이름에서 알 수 있듯이, 인기 있는 웹 서버이자 역방향 프록시인 Nginx를 기반으로 만들어졌습니다. 오랫동안 인프라 엔지니어들에게 사랑받아온 Nginx의 안정성과 성능을 쿠버네티스 환경에서도 활용할 수 있다는 게 가장 큰 장점이죠. 저도 예전부터 Nginx를 많이 써왔던 터라, 처음 쿠버네티스 Ingress를 접했을 때 가장 먼저 선택하게 된 솔루션입니다.

    ✅ Nginx Ingress Controller의 주요 장점

    • 높은 안정성과 성능: Nginx 자체가 워낙 안정적이고 고성능이어서, 대규모 트래픽 처리에도 강합니다.
    • 광범위한 사용처와 커뮤니티: 가장 널리 사용되는 Ingress Controller 중 하나인 만큼, 자료가 풍부하고 문제가 생겼을 때 도움을 받기 쉽습니다.
    • 풍부한 기능: Nginx의 강력한 기능을 annotation(어노테이션)을 통해 활용할 수 있습니다. (예: 리다이렉트, 인증, 로드밸런싱 알고리즘 등)

    ⚠️ Nginx Ingress Controller의 아쉬운 점

    • 설정의 복잡성: Nginx 설정 파일(nginx.conf)을 직접 다루지 않고 ConfigMap(컨피그맵)이나 annotation으로 간접적으로 설정하다 보니, 특정 고급 기능을 사용하려면 Nginx 설정 문법을 이해하고 annotation을 정확히 알아야 합니다.
    • 동적 업데이트의 한계: 새로운 Ingress 규칙을 적용하거나 기존 규칙을 변경할 때, Nginx 프로세스를 리로드(reload)하는 과정이 필요합니다. 컨트롤러가 자동으로 처리하지만, Traefik에 비해서는 동적이라는 느낌이 덜합니다.

    간단한 Nginx Ingress 리소스 예시를 볼까요? example.com으로 들어오는 요청을 my-service로 라우팅하는 설정입니다.

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: my-nginx-ingress
      annotations:
        nginx.ingress.kubernetes.io/rewrite-target: /
    spec:
      ingressClassName: nginx
      rules:
      - host: example.com
        http:
          paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-service
                port:
                  number: 80
    

    Traefik Ingress Controller 만나보기

    Traefik Proxy(트래픽 프록시)는 클라우드 네이티브 환경에 최적화된 최신 역방향 프록시 및 로드 밸런서입니다. 특히 쿠버네티스 Ingress Controller로서의 강점이 두드러지죠. 처음엔 이게 뭔가 싶었는데, 써보니 동적인 설정 관리가 정말 신세계더라고요.

    ✅ Traefik Ingress Controller의 주요 장점

    • 뛰어난 동적 설정: 쿠버네티스의 CRD(Custom Resource Definition, 사용자 정의 리소스 정의)를 적극 활용하여 Ingress 규칙을 실시간으로 업데이트합니다. Nginx처럼 리로딩 과정 없이 즉시 반영돼요.
    • 쉬운 설정 및 대시보드: IngressRoute와 같은 CRD를 통해 직관적인 설정이 가능하고, 웹 대시보드를 기본으로 제공하여 현재 라우팅 상태를 한눈에 파악하기 좋습니다. 저는 홈랩에서 여러 서비스를 띄울 때 이 대시보드가 정말 편하더라고요.
    • 자동 HTTPS (Let’s Encrypt): Let’s Encrypt(렛츠 인크립트)를 내장하여 도메인에 대한 HTTPS 인증서를 자동으로 발급하고 갱신해줍니다. 이거 진짜 편합니다!
    • 간결한 설정: Nginx의 복잡한 annotation 대신, 자체 CRD를 사용해 더 명확하고 간결하게 설정을 정의할 수 있습니다.

    ⚠️ Traefik Ingress Controller의 아쉬운 점

    • Nginx 대비 상대적으로 작은 커뮤니티: Nginx만큼 오랜 역사를 가진 건 아니어서, 자료나 커뮤니티 규모가 상대적으로 작을 수 있습니다. 하지만 성장세가 빠르고 공식 문서가 잘 되어 있습니다.
    • 특정 고급 기능의 복잡성: Nginx가 가진 다양한 모듈만큼의 유연성은 아닐 수 있습니다. 특정 시나리오에서는 Nginx의 annotation이 더 직관적일 때도 있습니다.

    Traefik의 IngressRoute CRD 예시입니다. Nginx Ingress와 동일하게 example.com을 my-service로 라우팅합니다.

    apiVersion: traefik.containo.us/v1alpha1
    kind: IngressRoute
    metadata:
      name: my-traefik-ingressroute
    spec:
      entryPoints:
        - web
        - websecure
      routes:
        - match: Host(`example.com`)
          kind: Rule
          services:
            - name: my-service
              port: 80
      tls:
        certResolver: myresolver # Let's Encrypt를 사용하는 경우
    

    실전 비교: Nginx vs Traefik, 어떤 걸 선택해야 할까?

    이제 두 Ingress Controller의 특징을 알았으니, 어떤 상황에서 어떤 것을 선택하는 것이 좋을지 제 경험을 토대로 비교해드릴게요. 사실 정답은 없습니다. 여러분의 환경과 요구사항에 따라 달라지는 거죠.

    Nginx Ingress Controller와 Traefik Ingress Controller의 주요 기능 및 장단점을 비교하는 표

    Nginx Ingress Controller와 Traefik Ingress Controller의 핵심적인 기능, 설정 방식, 성능, 커뮤니티 지원, 자동화 기능 등을 비교하는 표입니다. 사용자가 두 Ingress Controller 중 하나를 선택하는 데 필요한 정보를 요약하여 제공합니다.

    특징 Nginx Ingress Controller Traefik Ingress Controller
    기반 기술 Nginx 웹 서버 Golang으로 개발된 클라우드 네이티브 프록시
    설정 방식 Ingress 리소스 + Annotation, ConfigMap IngressRoute (CRD), Middlewares (CRD)
    동적 설정 변경 시 Nginx 리로드 필요 (자동화) 실시간 반영, 리로드 불필요
    HTTPS (Let’s Encrypt) 외부 Cert-Manager 등 연동 필요 내장 기능으로 자동화 용이
    관리 대시보드 별도 모니터링 툴 연동 (Prometheus, Grafana 등) 기본 제공 웹 대시보드
    커뮤니티/자료 매우 크고 풍부함 상대적으로 작지만 활발하며 성장 중
    성능 오랜 검증을 통한 고성능 클라우드 네이티브 환경에 최적화된 고성능
    사용 편의성 Nginx 지식 필요, Annotation 학습 필요 CRD 기반의 직관적인 설정, 빠른 학습 곡선

    Nginx Ingress Controller 추천하는 경우

    • 레거시 시스템과의 연동: 이미 Nginx 설정을 잘 다루는 팀이 있거나, 기존 Nginx 설정에 익숙하다면 Nginx Ingress Controller가 더 자연스럽게 느껴질 겁니다.
    • 최고의 안정성과 성능이 요구될 때: 미션 크리티컬한 서비스로, 수년간 검증된 Nginx의 안정성과 성능이 절대적으로 필요하다면 좋은 선택입니다.
    • 복잡하고 세밀한 트래픽 제어: Nginx의 다양한 모듈과 세밀한 설정을 통해 고도로 커스터마이징된 트래픽 제어가 필요할 때 유용합니다.

    Traefik Ingress Controller 추천하는 경우

    • 클라우드 네이티브 환경에 대한 높은 이해도와 선호: 쿠버네티스의 CRD를 활용한 동적인 설정에 강점이 있습니다.
    • 빠른 개발 및 배포 주기: 새로운 서비스를 자주 배포하거나 Ingress 규칙이 자주 변경되어야 하는 환경에서 실시간 업데이트는 큰 장점입니다.
    • 간편한 Let’s Encrypt 자동화: 수많은 서비스에 HTTPS를 쉽게 적용하고 싶다면 Traefik이 제공하는 자동화 기능은 정말 강력합니다. 저도 홈랩에서 이 기능 덕분에 HTTPS 적용이 너무 쉬웠어요.
    • 초보자나 소규모 환경: 대시보드와 쉬운 설정 덕분에 초보자도 빠르게 시작하고 관리할 수 있습니다.

    제가 겪었던 삽질과 해결 과정 ⚠️

    저도 처음부터 모든 걸 다 알았던 건 아니죠. 두 Ingress Controller를 사용하면서 꽤나 삽질을 많이 했습니다. 특히 몇 가지 기억에 남는 경험을 공유해볼게요.

    Nginx Ingress Controller 삽질: Annotation 지옥과 ConfigMap 캐싱

    Nginx Ingress Controller를 사용하면서 가장 많이 헷갈렸던 부분은 annotation이었습니다. Nginx의 모든 기능을 annotation으로 매핑하는 게 아니다 보니, 특정 기능(예: 커스텀 에러 페이지, 특정 헤더 추가)을 넣으려 할 때 어떤 annotation을 써야 할지, 아니면 ConfigMap을 수정해야 할지 찾는 데 시간을 많이 썼습니다. 특히 ConfigMap을 수정했을 때 바로 반영이 안 되고 캐싱 때문에 고생했던 기억도 있네요. ConfigMap을 업데이트하면 Nginx Ingress Controller Pod가 재시작되거나 설정이 리로드되는데, 이 과정에서 찰나의 순간 서비스에 영향을 줄까 봐 조마조마했던 적도 많았습니다.

    💡 해결 팁: Nginx Ingress Controller의 공식 문서에 있는 annotation 목록을 즐겨찾기에 등록해두고, ConfigMap 수정 후에는 항상 컨트롤러 로그를 확인하며 제대로 리로드되었는지 확인하는 습관을 들였습니다.

    Traefik Ingress Controller 삽질: CRD 이해와 EntryPoint 설정

    Traefik은 Nginx와는 다르게 IngressRoute라는 자체 CRD를 사용합니다. 처음엔 이 개념이 좀 낯설었어요. 특히 entryPoints와 middlewares 같은 개념들을 이해하는 데 시간이 걸렸죠. 예를 들어, 특정 포트(entryPoint)로 들어오는 요청에만 적용되는 규칙을 만들거나, 인증(middleware)을 추가하는 설정을 하려다가 몇 번이나 실패했는지 모릅니다. 특히 tls 설정에서 certResolver를 제대로 지정하지 않아서 Let’s Encrypt 자동 발급이 안 되는 문제도 겪었고요.

    # 잘못된 IngressRoute 설정 예시 (entryPoints 누락)
    apiVersion: traefik.containo.us/v1alpha1
    kind: IngressRoute
    metadata:
      name: my-broken-route
    spec:
      routes:
        - match: Host(`broken.example.com`)
          kind: Rule
          services:
            - name: my-service
              port: 80
    # 이 경우, Traefik이 어떤 entryPoint로 트래픽을 받을지 몰라 동작하지 않습니다.
    

    💡 해결 팁: Traefik 공식 문서를 정독하고, 특히 entryPoints와 middlewares 개념을 확실히 이해하는 것이 중요했습니다. 그리고 IngressRoute를 배포하기 전에 항상 Traefik 대시보드를 통해 현재 설정이 어떻게 반영될지 미리 확인하는 습관을 들였어요. 대시보드만큼 직관적인 디버깅 도구가 없더라고요!

    Traefik Ingress Controller 웹 대시보드에서 서비스 목록과 라우팅 규칙을 보여주는 화면

    Traefik Ingress Controller의 웹 대시보드 스크린샷으로, 현재 활성화된 서비스와 라우팅 규칙(IngressRoutes)이 명확하게 표시되어 트래픽 흐름을 시각적으로 파악할 수 있는 화면입니다.

    결론: 당신의 환경에 맞는 Ingress Controller는?

    제가 Nginx와 Traefik을 모두 써보면서 느낀 점은, 두 Ingress Controller 모두 훌륭한 솔루션이라는 것입니다. 다만 각자의 강점과 약점이 뚜렷하다는 것이죠. Nginx는 전통적인 인프라 환경에서 익숙한 안정성과 고성능을 제공하며, 복잡한 설정에 대한 유연성을 가집니다. 반면 Traefik은 클라우드 네이티브 환경의 동적인 특성에 완벽하게 부합하며, 자동화와 사용 편의성에서 큰 강점을 보입니다.

    저의 홈랩 환경에서는 새로운 서비스를 빠르게 올리고 내리며, Let’s Encrypt로 HTTPS를 쉽게 적용해야 하는 경우가 많아서 최종적으로는 Traefik Ingress Controller를 선택하여 운영하고 있습니다. 대시보드를 통해 현재 라우팅 상황을 한눈에 볼 수 있고, 새로운 IngressRoute를 배포하면 바로 적용되는 그 편리함이 정말 매력적이었거든요. 물론 Nginx도 여전히 중요한 역할을 하는 곳이 많습니다. 여러분의 팀 문화, 기존 인프라 스택, 그리고 프로젝트의 요구사항을 신중하게 고려하여 쿠버네티스 트래픽 관리에 최적의 선택을 하시길 바랍니다.

    Nginx Ingress Controller와 Traefik Ingress Controller의 핵심 차이점을 요약한 인포그래픽

    Nginx Ingress Controller와 Traefik Ingress Controller의 주요 특징, 장단점, 추천 사용 사례를 한눈에 비교할 수 있도록 시각적으로 요약한 인포그래픽입니다.

    마무리하며

    쿠버네티스 환경에서 Ingress Controller는 외부와 내부를 연결하는 중요한 다리 역할을 합니다. Nginx와 Traefik 모두 각자의 방식으로 이 역할을 훌륭하게 수행하죠. 어떤 것을 선택하든, 중요한 것은 해당 솔루션의 작동 방식을 이해하고 여러분의 환경에 맞게 최적화하는 것입니다. 제가 겪었던 삽질 경험들이 여러분의 시간과 노력을 아끼는 데 조금이나마 도움이 되었기를 바랍니다.

    다음 글에서는 Traefik을 이용한 Let’s Encrypt 자동화 설정에 대해 좀 더 자세히 다뤄볼까 합니다. 긴 글 읽어주셔서 감사합니다! 궁금한 점이 있다면 언제든지 댓글로 남겨주세요. 제가 아는 선에서는 성심성의껏 답변해드리겠습니다. 🎉

  • [k8s] Istio 서비스 메시 완벽 가이드: 설치부터 트래픽 관리, 보안까지

    마이크로서비스가 늘어날수록 머리가 아파지더라고요

    처음 마이크로서비스(Microservices) 아키텍처를 도입했을 때만 해도 “이제 서비스별로 독립 배포되니까 편하겠다!” 싶었거든요. 근데 서비스가 10개, 20개를 넘어가면서 슬슬 문제가 생기기 시작했습니다. 서비스 A가 서비스 B를 호출하다 타임아웃이 나는데, 어디서 문제가 생겼는지 추적이 안 되고… 보안 정책은 각 서비스마다 따로 관리해야 하고… 트래픽을 특정 버전으로 라우팅하고 싶은데 코드를 건드려야 하고…

    그때 Istio 서비스 메시(Service Mesh)를 처음 접했습니다. 솔직히 처음엔 “또 새로운 복잡한 거 배워야 하나…” 싶었는데, 써보고 나서 생각이 완전히 바뀌었어요. 오늘은 Istio 설치부터 트래픽 관리, 보안까지 제가 직접 삽질하며 쌓은 경험을 공유해 드리려 합니다.

    Istio 서비스 메시의 전체 아키텍처 — 컨트롤 플레인(istiod)과 데이터 플레인(Envoy 사이드카)의 관계를 보여줍니다.

    Istio 서비스 메시가 뭔지 먼저 짚고 가죠

    서비스 메시(Service Mesh)란?

    쉽게 말해, 마이크로서비스들 사이의 통신을 인프라 레벨에서 투명하게 관리해주는 레이어입니다. 각 서비스 옆에 Envoy(엔보이)라는 프록시를 붙여놓고, 모든 네트워크 트래픽이 이 프록시를 거치게 하는 방식이에요. 개발자는 코드를 건드릴 필요 없이 운영팀에서 트래픽 정책을 관리할 수 있게 됩니다.

    Istio는 현재 가장 널리 쓰이는 서비스 메시 솔루션으로, CNCF(Cloud Native Computing Foundation)의 그래듀에이티드 프로젝트입니다.

    Istio 핵심 구성 요소

    • istiod: 컨트롤 플레인(Control Plane). Pilot, Citadel, Galley가 합쳐진 단일 바이너리. 정책 관리의 두뇌 역할을 합니다
    • Envoy Sidecar(엔보이 사이드카): 각 Pod에 자동 주입되는 프록시. 실제 트래픽을 처리하는 데이터 플레인(Data Plane)입니다
    • Ingress Gateway(인그레스 게이트웨이): 클러스터 외부에서 들어오는 트래픽의 진입점입니다
    • Egress Gateway(이그레스 게이트웨이): 클러스터 외부로 나가는 트래픽을 제어합니다
    구성 요소 역할 위치
    istiod 설정 배포, 인증서 관리, 서비스 디스커버리 컨트롤 플레인 (istio-system 네임스페이스)
    Envoy Proxy 실제 트래픽 처리, 메트릭 수집 각 Pod 내 사이드카 컨테이너
    Ingress Gateway 외부 트래픽 수신 및 라우팅 데이터 플레인 (별도 Pod)

    Istio 설치 — 제가 권장하는 방법

    사전 준비

    Istio 설치 전에 Kubernetes 클러스터가 준비되어 있어야 합니다. 저는 홈랩에서 k3s 위에 올려서 테스트했고, 실무에서는 EKS, GKE 환경에서도 써봤어요. 공통적으로 잘 동작하더라고요.

    • Kubernetes 1.21 이상 (권장)
    • kubectl 설치 및 클러스터 접근 설정
    • 충분한 리소스 (컨트롤 플레인용 최소 4GB RAM 권장)

    istioctl 설치

    Istio 공식 CLI 도구인 istioctl을 먼저 설치합니다. 가장 간단한 방법은 공식 설치 스크립트를 사용하는 거예요.

    # Istio 최신 버전 다운로드 및 설치
    curl -L https://istio.io/downloadIstio | sh -
    
    # 다운로드된 디렉토리로 이동 (버전 번호는 다를 수 있습니다)
    cd istio-*
    
    # PATH에 istioctl 추가
    export PATH=$PWD/bin:$PATH
    
    # 영구 적용을 원하면 ~/.bashrc 또는 ~/.zshrc에 추가
    echo 'export PATH=$HOME/istio-*/bin:$PATH' >> ~/.bashrc
    
    # 설치 확인
    istioctl version

    Istio 프로파일 선택 및 설치

    Istio는 여러 설치 프로파일(Profile)을 제공합니다. 처음엔 이게 뭔 차이인지 몰라서 그냥 default로 했다가 나중에 조정했었는데요. 미리 파악해두시면 정말 도움이 됩니다.

    프로파일 특징 권장 사용처
    default istiod + Ingress Gateway 포함 프로덕션 환경
    demo 모든 기능 활성화, 모니터링 포함 학습/테스트
    minimal istiod만 설치 커스텀 구성
    external 외부 컨트롤 플레인 연결용 멀티 클러스터
    # 사전 체크 (클러스터 호환성 확인)
    istioctl x precheck
    
    # demo 프로파일로 설치 (학습 목적)
    istioctl install --set profile=demo -y
    
    # 설치 확인
    kubectl get pods -n istio-system
    
    # 출력 예시:
    # NAME                                   READY   STATUS    RESTARTS   AGE
    # istiod-xxxxxxxxx-xxxxx                 1/1     Running   0          2m
    # istio-ingressgateway-xxxxxxxxx-xxxxx   1/1     Running   0          2m
    # istio-egressgateway-xxxxxxxxx-xxxxx    1/1     Running   0          2m

    네임스페이스에 사이드카 자동 주입 활성화

    이 단계를 빠뜨리면 나중에 “왜 메시가 안 되지?” 하고 한참 헤맵니다. 저도 처음에 이거 놓쳐서 30분을 날렸어요 ㅎㅎ

    # default 네임스페이스에 사이드카 자동 주입 레이블 추가
    kubectl label namespace default istio-injection=enabled
    
    # 확인
    kubectl get namespace default --show-labels

    Envoy 사이드카가 Pod에 자동 주입되는 과정 — 모든 인바운드/아웃바운드 트래픽이 사이드카 프록시를 거쳐 처리됩니다.

    Istio 트래픽 관리 — 이게 진짜 핵심입니다

    트래픽 관리가 Istio를 쓰는 가장 큰 이유 중 하나라고 생각해요. 카나리 배포(Canary Deployment), 블루/그린 배포(Blue/Green Deployment), A/B 테스트를 코드 변경 없이 할 수 있거든요.

    VirtualService와 DestinationRule 이해하기

    Istio 트래픽 관리의 두 핵심 리소스입니다.

    • VirtualService(버추얼 서비스): “이 트래픽을 어디로 보낼지” 라우팅 규칙을 정의합니다
    • DestinationRule(데스티네이션 룰): “목적지 서비스를 어떻게 나눌지” 서브셋(Subset) 및 로드밸런싱 정책을 정의합니다

    카나리 배포 설정 예시

    실제로 제가 가장 많이 쓰는 패턴입니다. 새 버전(v2)에 10%만 트래픽을 보내고, 안정적이면 점진적으로 늘리는 방식이에요.

    # destination-rule.yaml
    apiVersion: networking.istio.io/v1alpha3
    kind: DestinationRule
    metadata:
      name: my-service-destination
    spec:
      host: my-service
      subsets:
      - name: v1
        labels:
          version: v1
      - name: v2
        labels:
          version: v2
      trafficPolicy:
        loadBalancer:
          simple: ROUND_ROBIN
    # virtual-service.yaml — 90% v1, 10% v2로 트래픽 분배
    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: my-service-vs
    spec:
      hosts:
      - my-service
      http:
      - route:
        - destination:
            host: my-service
            subset: v1
          weight: 90
        - destination:
            host: my-service
            subset: v2
          weight: 10
    # 적용
    kubectl apply -f destination-rule.yaml
    kubectl apply -f virtual-service.yaml
    
    # 확인
    kubectl get virtualservice
    kubectl get destinationrule

    헤더 기반 라우팅 — A/B 테스트에 유용해요

    특정 헤더가 있는 요청만 새 버전으로 보내는 방식입니다. QA팀이나 내부 테스터에게만 새 버전을 보여줄 때 정말 유용하더라고요.

    # 헤더 기반 라우팅 VirtualService
    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: my-service-header-routing
    spec:
      hosts:
      - my-service
      http:
      - match:
        - headers:
            x-test-user:
              exact: "true"
        route:
        - destination:
            host: my-service
            subset: v2
      - route:
        - destination:
            host: my-service
            subset: v1

    서킷 브레이커(Circuit Breaker) 설정

    장애가 전파되는 걸 막는 패턴입니다. 특정 서비스가 느려지거나 에러가 많이 나면 자동으로 차단해서 전체 시스템을 보호해주는 거예요.

    # circuit-breaker.yaml
    apiVersion: networking.istio.io/v1alpha3
    kind: DestinationRule
    metadata:
      name: my-service-cb
    spec:
      host: my-service
      trafficPolicy:
        outlierDetection:
          consecutive5xxErrors: 5        # 연속 5xx 에러 5회
          interval: 30s                   # 30초 간격으로 체크
          baseEjectionTime: 30s           # 30초 동안 제외
          maxEjectionPercent: 100         # 최대 100% 제외 가능
        connectionPool:
          tcp:
            maxConnections: 100
          http:
            http1MaxPendingRequests: 100
            http2MaxRequests: 1000

    Istio 보안 — mTLS로 서비스 간 통신 암호화

    mTLS(Mutual TLS) 이해하기

    Istio 보안의 핵심은 mTLS(상호 TLS 인증)입니다. 클라이언트와 서버 양쪽 모두 인증서로 신원을 증명하는 방식이에요. 일반 TLS는 서버만 인증서를 제시하지만, mTLS는 양방향 인증이라 훨씬 강력합니다.

    Istio 1.5 버전부터는 기본적으로 mTLS가 PERMISSIVE(허용) 모드로 설정됩니다. 암호화된 연결과 평문 연결 모두 허용하는 모드예요. 마이그레이션할 때 유용하지만, 프로덕션에서는 STRICT 모드로 바꾸는 걸 강력히 권장합니다.

    # peer-auth-strict.yaml — STRICT mTLS 적용
    apiVersion: security.istio.io/v1beta1
    kind: PeerAuthentication
    metadata:
      name: default
      namespace: default
    spec:
      mtls:
        mode: STRICT
    # 적용
    kubectl apply -f peer-auth-strict.yaml
    
    # 검증 — 사이드카 없는 Pod에서 호출하면 실패해야 함
    kubectl exec -it [pod-name] -c istio-proxy -- curl http://my-service:8080

    AuthorizationPolicy — 세밀한 접근 제어

    mTLS로 암호화는 됐는데, 어떤 서비스가 어떤 서비스를 호출할 수 있는지 제어하고 싶을 때 AuthorizationPolicy(인가 정책)를 사용합니다.

    # authz-policy.yaml — frontend 서비스만 backend 서비스 호출 허용
    apiVersion: security.istio.io/v1beta1
    kind: AuthorizationPolicy
    metadata:
      name: backend-authz
      namespace: default
    spec:
      selector:
        matchLabels:
          app: backend
      action: ALLOW
      rules:
      - from:
        - source:
            principals:
            - "cluster.local/ns/default/sa/frontend-service-account"
        to:
        - operation:
            methods: ["GET", "POST"]
            paths: ["/api/*"]

    JWT 인증 설정

    # request-auth.yaml — JWT 토큰 검증
    apiVersion: security.istio.io/v1beta1
    kind: RequestAuthentication
    metadata:
      name: jwt-auth
      namespace: default
    spec:
      selector:
        matchLabels:
          app: my-service
      jwtRules:
      - issuer: "https://your-auth-server.com"
        jwksUri: "https://your-auth-server.com/.well-known/jwks.json"

    ⚠️ 삽질 경험 — 이것만 조심하세요

    제가 Istio 도입하면서 겪었던 주요 문제들 공유합니다. 미리 알고 계시면 정말 시간 많이 절약하실 거예요.

    문제 1: 사이드카가 주입이 안 된다

    # Pod 확인 — READY가 2/2가 아니라 1/1이면 사이드카 미주입
    kubectl get pods
    
    # 네임스페이스 레이블 확인
    kubectl get namespace default --show-labels
    
    # istio-injection=enabled 레이블이 없으면 추가
    kubectl label namespace default istio-injection=enabled
    
    # 기존 Pod는 재시작해야 사이드카가 주입됨!
    kubectl rollout restart deployment/my-deployment

    문제 2: mTLS STRICT 모드 전환 후 통신 두절

    STRICT 모드로 바꿨더니 레거시 서비스들이 다 죽어버린 경험이 있습니다. 사이드카가 없는 서비스는 mTLS를 못 하거든요.

    # 어떤 서비스가 mTLS를 안 하고 있는지 확인
    istioctl x describe service my-service
    
    # 특정 네임스페이스만 STRICT, 나머지는 PERMISSIVE 유지하는 방법
    # 네임스페이스별로 PeerAuthentication 적용 가능

    문제 3: VirtualService 적용했는데 트래픽 분배가 안 된다

    VirtualService의 hosts 필드와 실제 Kubernetes Service 이름이 정확히 일치해야 합니다. FQDN(완전 정규화 도메인 이름)으로 쓰거나 짧은 이름으로 통일해야 해요.

    # Istio 설정 검증
    istioctl analyze
    
    # 특정 Pod의 Envoy 설정 확인
    istioctl proxy-config cluster [pod-name]
    istioctl proxy-config route [pod-name]
    
    # 트래픽 흐름 확인
    istioctl proxy-config listeners [pod-name]

    문제 4: 리소스 사용량이 예상보다 높다

    사이드카가 모든 Pod에 붙으니까 메모리, CPU 사용량이 꽤 올라갑니다. 소규모 환경에서는 부담이 될 수 있어요. 저는 홈랩에서 처음 올렸을 때 메모리가 모자라서 한참 고생했습니다.

    • Envoy 프록시 하나당 약 50~100MB 메모리 사용 (환경마다 다름)
    • 사이드카 리소스 제한 설정을 통해 조절 가능
    • 꼭 필요한 네임스페이스에만 주입하는 것도 방법

    Kiali로 서비스 메시 시각화 확인하기

    Kiali(키알리)는 Istio의 공식 관찰성(Observability) 대시보드입니다. 서비스 간 트래픽 흐름을 그래프로 보여줘서 정말 유용해요. 처음 켰을 때 “오, 이게 되네!” 하고 감탄했습니다.

    # Kiali 설치 (demo 프로파일이면 이미 설치되어 있을 수 있음)
    kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/addons/kiali.yaml
    
    # Prometheus, Grafana, Jaeger도 함께 설치 권장
    kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/addons/prometheus.yaml
    kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/addons/grafana.yaml
    kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/addons/jaeger.yaml
    
    # Kiali 대시보드 열기
    istioctl dashboard kiali

    Kiali 대시보드에서 서비스 간 트래픽 흐름을 시각적으로 확인 — 실시간 RPS, 에러율, 레이턴시를 한눈에 볼 수 있습니다.

    Istio 도입 전후 비교 정리

    항목 Istio 도입 전 Istio 도입 후
    트래픽 라우팅 코드 변경 필요, 재배포 필요 YAML 수정만으로 즉시 적용
    서비스 간 암호화 개별 서비스에서 TLS 직접 구현 mTLS 자동 적용
    장애 추적 로그 뒤지며 수동 추적 분산 트레이싱(Distributed Tracing)으로 자동 추적
    접근 제어 각 서비스에서 개별 구현 AuthorizationPolicy로 중앙 관리
    카나리 배포 Ingress 설정 복잡, 별도 도구 필요 VirtualService weight 조정만으로 가능
    서킷 브레이커 라이브러리 직접 구현 (Hystrix 등) DestinationRule로 선언적 설정

    Istio 서비스 메시 도입 전후 비교 — 트래픽 관리, 보안, 관찰성 측면에서의 변화를 한눈에 정리한 인포그래픽입니다.

    자주 묻는 질문 (FAQ)

    Q. Istio는 소규모 환경에도 도입할 만한가요?

    솔직히 말씀드리면, 서비스가 5개 미만이면 오버엔지니어링일 수 있습니다. Istio 자체의 운영 복잡도가 있거든요. 서비스가 10개 이상이고, 트래픽 관리나 보안 요구사항이 복잡해질 때 도입을 고려하는 걸 권장합니다.

    Q. Istio 업그레이드는 어떻게 하나요?

    istioctl upgrade 명령어로 인플레이스(In-place) 업그레이드가 가능합니다. 다만 프로덕션에서는 카나리 업그레이드 방식을 권장해요. 이 부분은 다음 글에서 자세히 다룰 예정입니다.

    Q. Linkerd와 비교하면 어떤가요?

    Linkerd는 더 가볍고 단순하지만 기능이 제한적입니다. Istio는 기능이 풍부하지만 복잡도가 높아요. 팀의 기술 역량과 요구사항에 따라 선택하시면 됩니다. 서비스 메시 솔루션 비교는 별도 글로 정리해 드리겠습니다.

    Q. 사이드카 없이 Istio를 쓸 수 있나요?

    Istio 1.15부터 Ambient Mesh(앰비언트 메시)라는 사이드카 없는 방식이 알파로 도입됐습니다. 사이드카의 리소스 오버헤드를 줄이는 방향으로 발전하고 있어요. 아직 프로덕션에 쓰기엔 이르지만 지켜볼 만한 기술입니다.

    마무리 — 처음엔 어렵지만 익숙해지면 없어서 못 삽니다

    처음 Istio를 배울 때는 개념도 많고, CRD(Custom Resource Definition)도 낯설고, 트러블슈팅도 어렵게 느껴집니다. 저도 처음 3개월은 꽤 힘들었어요. 근데 한 번 익숙해지고 나면, 이게 없는 환경으로 돌아가기가 싫어지더라고요.

    오늘 다룬 내용을 정리하면:

    1. ✅ istioctl로 Istio 설치 및 네임스페이스 레이블 설정
    2. ✅ VirtualService + DestinationRule로 카나리 배포, A/B 테스트 구현
    3. ✅ PeerAuthentication STRICT으로 mTLS 강제 적용
    4. ✅ AuthorizationPolicy로 서비스 간 접근 제어
    5. ✅ Kiali + Prometheus로 서비스 메시 가시성 확보

    다음 글에서는 Istio를 활용한 멀티 클러스터 서비스 메시 구성과 Istio 업그레이드 전략을 다뤄볼 예정입니다. 그리고 이전 글에서 다뤘던 Kubernetes 네트워크 정책(NetworkPolicy)과 Istio를 함께 쓰는 방법도 참고하시면 좋아요.

    궁금한 점이나 막히는 부분 있으시면 댓글로 남겨주세요. 같이 삽질해봐요! 🎉

  • [k8s] 쿠버네티스 Pod 트러블슈팅: CrashLoopBackOff, OOMKilled 완벽 해결

    쿠버네티스 Pod가 계속 죽는다면? 당신만 그런 게 아닙니다

    쿠버네티스를 처음 운영하다 보면 꼭 한 번씩 마주치는 상황이 있어요. 열심히 작성한 배포 파일을 kubectl apply로 올렸는데, Pod 상태가 CrashLoopBackOff거나 OOMKilled로 떠 있는 겁니다. 처음엔 진짜 당황스럽죠. 로그를 봐도 뭔가 무한루프처럼 에러가 쌓이고, 뭘 고쳐야 할지 막막하고요.

    저도 입사 초반에 이거 때문에 밤새 삽질한 기억이 있습니다. 당시엔 kubectl describe pod 명령어조차 제대로 활용 못 했거든요. 지금은 쿠버네티스 Pod 트러블슈팅이 거의 반사적으로 손가락이 움직일 정도가 됐지만, 처음엔 정말 막막했어요. 이번 글에서는 제가 직접 겪고 해결한 경험을 바탕으로, CrashLoopBackOff와 OOMKilled 두 가지 대표적인 Pod 오류를 어떻게 진단하고 해결하는지 단계별로 풀어드릴게요.

    ▲ 쿠버네티스 Pod의 주요 상태 전환 흐름. Pending → Running → CrashLoopBackOff / OOMKilled 경로를 시각화한 다이어그램

    CrashLoopBackOff와 OOMKilled, 이게 대체 뭔가요?

    CrashLoopBackOff — “계속 죽었다 살아났다 반복”

    쉽게 말해서, 컨테이너가 시작됐다가 바로 죽고, 쿠버네티스가 다시 살리고, 또 죽고를 반복하는 상태예요. 쿠버네티스는 기본적으로 컨테이너가 죽으면 재시작(restart)을 시도하는데, 계속 실패하면 재시작 간격을 점점 늘리면서 BackOff 상태로 전환됩니다. 10초, 20초, 40초… 이런 식으로요.

    원인은 정말 다양합니다:

    • 애플리케이션 자체 버그 (예외 처리 안 된 panic, exit code 1)
    • 잘못된 환경 변수(Environment Variable) 설정
    • ConfigMap이나 Secret 마운트 실패
    • Liveness Probe(생존 확인 프로브) 설정 오류
    • 의존 서비스(DB, 외부 API 등)에 연결 못 하는 경우

    OOMKilled — “메모리를 너무 많이 먹어서 강제 종료”

    OOM은 Out Of Memory의 약자입니다. 컨테이너가 설정된 메모리 Limit(제한)을 초과하면, 리눅스 커널의 OOM Killer가 해당 프로세스를 강제로 죽여버려요. kubectl describe pod로 확인하면 OOMKilled라고 딱 찍혀 있고, exit code는 137이에요.

    이건 크게 두 가지 경우인데요:

    • 메모리 Limit이 너무 낮게 설정된 경우: 실제 앱이 필요한 메모리보다 Limit이 작아서 죽는 거예요
    • 메모리 누수(Memory Leak)가 있는 경우: Limit은 적절한데 앱이 메모리를 계속 잡아먹고 반환 안 하는 경우
    오류 유형 주요 원인 Exit Code 확인 명령어
    CrashLoopBackOff 앱 오류, 설정 문제, Probe 실패 1, 2 등 다양 kubectl logs, kubectl describe
    OOMKilled 메모리 Limit 초과, 메모리 누수 137 kubectl describe, metrics-server

    1단계: 상황 파악 — 일단 뭐가 문제인지 보자

    쿠버네티스 Pod 트러블슈팅의 첫 번째 단계는 항상 현재 상태 파악이에요. 저는 이 순서대로 확인합니다.

    Pod 상태 전체 확인

    # 네임스페이스 전체 Pod 상태 확인
    kubectl get pods -n <네임스페이스> -o wide
    
    # 모든 네임스페이스에서 문제 있는 Pod만 필터링
    kubectl get pods -A | grep -v Running | grep -v Completed

    여기서 RESTARTS 컬럼 숫자가 높으면 CrashLoopBackOff 의심이에요. 한 자리면 괜찮은데, 두세 자리 넘어가면 심각한 거거든요.

    Pod 상세 이벤트 확인 — 이게 핵심입니다

    kubectl describe pod  -n <네임스페이스>

    출력 맨 아래 Events: 섹션을 꼭 보세요. 여기에 실제로 무슨 일이 있었는지 타임라인이 찍혀 있어요. OOMKilled라면 이런 식으로 보입니다:

    Events:
      Type     Reason     Age                From               Message
      ----     ------     ----               ----               -------
      Warning  BackOff    2m (x5 over 5m)   kubelet            Back-off restarting failed container
      Normal   Pulled     6m                kubelet            Successfully pulled image
      Normal   Started    6m                kubelet            Started container app
      Warning  OOMKilling 5m                kubelet            Memory limit reached, killing container

    로그 확인 — 현재 로그와 이전 컨테이너 로그

    # 현재 컨테이너 로그
    kubectl logs  -n <네임스페이스>
    
    # 이전에 죽은 컨테이너 로그 (이게 더 중요할 때가 많아요!)
    kubectl logs  -n <네임스페이스> --previous
    
    # 실시간 로그 스트리밍
    kubectl logs -f  -n <네임스페이스>
    
    # 멀티 컨테이너 Pod인 경우 컨테이너 지정
    kubectl logs  -c  -n <네임스페이스> --previous

    💡 팁: --previous 플래그를 꼭 써보세요. 현재 로그에는 아무것도 없어도, 이전에 죽을 때의 로그가 여기 남아 있거든요. 저도 처음엔 이걸 몰라서 한참 헤맸습니다 ㅎㅎ

    ▲ kubectl describe pod 명령어 실행 결과. Events 섹션에서 OOMKilled 및 CrashLoopBackOff 원인을 확인하는 화면

    2단계: CrashLoopBackOff 원인별 해결법

    케이스 1: 애플리케이션 자체 오류

    로그에서 스택 트레이스(stack trace)나 panic, exception 같은 키워드가 보인다면 앱 코드 문제예요. 이건 개발팀에 공유해야 하는 케이스고, 인프라 엔지니어 입장에서 할 수 있는 건 명확한 로그를 전달하는 거예요.

    # 마지막 100줄 로그 확인
    kubectl logs  --previous --tail=100 -n <네임스페이스>

    케이스 2: Liveness Probe 설정 오류

    이게 은근히 많은 케이스더라고요. Liveness Probe(생존 확인 프로브)가 너무 엄격하게 설정되어 있으면, 앱이 정상인데도 쿠버네티스가 죽었다고 판단해서 재시작시켜 버립니다.

    # 잘못된 설정 예시 — 너무 빠른 초기 딜레이
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 3   # 앱 시작에 10초 걸리는데 3초만 기다림
      periodSeconds: 5
      failureThreshold: 1      # 1번만 실패해도 재시작
    
    ---
    
    # 올바른 설정 예시
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 30  # 앱 시작 시간보다 여유 있게
      periodSeconds: 10
      failureThreshold: 3      # 3번 연속 실패해야 재시작
      timeoutSeconds: 5        # 응답 타임아웃도 여유 있게

    ⚠️ 주의: initialDelaySeconds는 컨테이너 시작 후 처음 Probe를 시도하기 전 대기 시간이에요. 앱이 완전히 뜨는 데 걸리는 시간보다 넉넉하게 잡아야 합니다. 저는 보통 실제 시작 시간의 1.5~2배로 잡아요.

    케이스 3: ConfigMap / Secret 마운트 실패

    # ConfigMap 존재 여부 확인
    kubectl get configmap -n <네임스페이스>
    
    # Secret 존재 여부 확인
    kubectl get secret -n <네임스페이스>
    
    # describe에서 Volume 마운트 실패 메시지 확인
    kubectl describe pod  -n <네임스페이스> | grep -A5 "Volumes"

    describe 출력에서 이런 메시지가 보이면 ConfigMap이나 Secret이 없는 겁니다:

    Warning  FailedMount  10s   kubelet  MountVolume.SetUp failed for volume "config" :
    configmap "my-app-config" not found

    케이스 4: 환경 변수 누락

    # 실행 중인 Pod의 환경 변수 확인
    kubectl exec  -n <네임스페이스> -- env | sort
    
    # Pod가 죽어서 exec가 안 되는 경우 — 임시 디버그 Pod 실행
    kubectl run debug-pod --image=busybox -it --rm -- /bin/sh

    3단계: OOMKilled 해결법

    현재 메모리 사용량 확인

    먼저 실제로 얼마나 쓰고 있는지 봐야죠. metrics-server가 설치되어 있다면:

    # Pod 리소스 사용량 확인
    kubectl top pod  -n <네임스페이스>
    
    # 컨테이너별 상세 확인
    kubectl top pod  -n <네임스페이스> --containers

    현재 설정된 Limit 확인:

    kubectl get pod  -n <네임스페이스> -o jsonpath='{.spec.containers[*].resources}'

    메모리 Limit 조정

    실제 사용량이 Limit에 근접하거나 초과한다면 Limit을 올려야 해요. 이건 Deployment를 수정해야 합니다:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-app
    spec:
      template:
        spec:
          containers:
          - name: app
            image: my-app:latest
            resources:
              requests:
                memory: "256Mi"   # 스케줄링 기준 (최소 보장량)
                cpu: "250m"
              limits:
                memory: "512Mi"   # 최대 허용량 (이 이상 쓰면 OOMKilled)
                cpu: "500m"

    💡 Request와 Limit의 차이:

    • requests: 쿠버네티스가 Pod를 노드에 배치할 때 기준이 되는 최소 보장량이에요. 이 공간이 있는 노드에만 배치됩니다.
    • limits: 컨테이너가 절대 넘을 수 없는 상한선이에요. 메모리 Limit을 넘으면 OOMKilled, CPU Limit을 넘으면 쓰로틀링(throttling)이 발생해요.

    메모리 누수 의심 케이스

    Limit을 올렸는데도 계속 OOMKilled가 난다면 메모리 누수를 의심해야 해요. 이 경우엔 시간에 따른 메모리 증가 패턴을 봐야 합니다. Prometheus + Grafana 조합이 있다면 메모리 사용량 그래프를 확인하세요. 선형으로 계속 올라간다면 누수 가능성이 높습니다.

    # 메모리 사용량 변화를 5초 간격으로 모니터링
    watch -n 5 kubectl top pod  -n <네임스페이스>

    누수가 확인되면 개발팀에 공유하고, 임시 방편으로는 Deployment에 주기적 재시작을 설정하는 방법도 있어요 (권장하진 않지만요):

    # CronJob으로 주기적 재시작 — 근본 해결책은 아닙니다!
    apiVersion: batch/v1
    kind: CronJob
    metadata:
      name: restart-my-app
    spec:
      schedule: "0 4 * * *"  # 매일 새벽 4시
      jobTemplate:
        spec:
          template:
            spec:
              containers:
              - name: kubectl
                image: bitnami/kubectl
                command:
                - kubectl
                - rollout
                - restart
                - deployment/my-app
              restartPolicy: OnFailure

    ▲ Grafana 대시보드에서 Pod 메모리 사용량 추이를 모니터링하는 화면. 메모리 누수 시 선형 증가 패턴이 확인됨

    4단계: 고급 디버깅 — 그래도 모르겠을 때

    임시 디버그 컨테이너 (kubectl debug)

    쿠버네티스 1.23 이상이라면 kubectl debug를 활용할 수 있어요. 이미지에 쉘이 없거나, distroless 이미지를 쓰는 경우에도 쿠버네티스 Pod를 디버깅할 수 있습니다.

    # 실행 중인 Pod에 디버그 컨테이너 추가
    kubectl debug -it  -n <네임스페이스> \
      --image=busybox \
      --target=
    
    # Pod를 복사해서 디버그 버전으로 실행
    kubectl debug  -n <네임스페이스> \
      -it \
      --copy-to=debug-pod \
      --image=ubuntu \
      -- bash

    Pod가 계속 죽어서 exec가 안 될 때

    이건 진짜 난감한 상황인데요. 이럴 때 쓰는 트릭이 있어요. 컨테이너 커맨드를 sleep infinity로 덮어써서 앱이 실행되지 않은 상태에서 내부를 들여다보는 겁니다:

    # 임시로 커맨드를 sleep으로 덮어쓰기
    kubectl debug  -n <네임스페이스> \
      --copy-to=debug-pod \
      --image= \
      -- sleep infinity
    
    # 그 다음 exec로 들어가서 환경 확인
    kubectl exec -it debug-pod -n <네임스페이스> -- bash

    네트워크 연결 문제 확인

    DB나 외부 서비스 연결 실패로 CrashLoopBackOff가 나는 경우도 많아요:

    # 네임스페이스 내 Service 확인
    kubectl get svc -n <네임스페이스>
    
    # DNS 해석 확인 (임시 Pod 사용)
    kubectl run dns-test --image=busybox -it --rm -n <네임스페이스> \
      -- nslookup my-db-service
    
    # TCP 연결 확인
    kubectl run tcp-test --image=busybox -it --rm -n <네임스페이스> \
      -- nc -zv my-db-service 5432

    검증 — 제대로 고쳐졌는지 확인하기

    수정 후에는 꼭 아래 순서로 확인해요:

    1. Pod 상태가 Running으로 안정적으로 유지되는지 확인
    2. RESTARTS 카운트가 더 이상 올라가지 않는지 확인
    3. 로그에 정상 동작 메시지가 찍히는지 확인
    4. Readiness Probe(준비 확인 프로브)가 통과하는지 확인
    # 실시간으로 Pod 상태 변화 모니터링
    kubectl get pods -n <네임스페이스> -w
    
    # Rollout 상태 확인
    kubectl rollout status deployment/ -n <네임스페이스>
    
    # 최근 이벤트 확인
    kubectl get events -n <네임스페이스> --sort-by='.lastTimestamp' | tail -20

    🎉 kubectl get pods에서 STATUS가 Running이고 READY가 1/1이면서 RESTARTS가 안 올라가면 성공입니다!

    쿠버네티스 Pod 트러블슈팅 체크리스트 정리

    확인 항목 CrashLoopBackOff OOMKilled 명령어
    Pod 상태 확인 ✅ ✅ kubectl get pods
    이벤트 로그 확인 ✅ ✅ kubectl describe pod
    이전 컨테이너 로그 ✅ ✅ kubectl logs –previous
    Probe 설정 확인 ✅ – kubectl get pod -o yaml
    메모리 사용량 확인 – ✅ kubectl top pod
    리소스 Limit 조정 – ✅ kubectl edit deployment
    ConfigMap/Secret 확인 ✅ – kubectl get cm,secret
    네트워크 연결 확인 ✅ – kubectl run (임시 Pod)

    ▲ CrashLoopBackOff와 OOMKilled 트러블슈팅 플로우차트. 증상별 진단 경로와 해결 방법을 한눈에 정리한 인포그래픽

    마무리 — 결국 로그가 답이더라고요

    여러 해 동안 수많은 인프라 사고를 겪어오면서 느낀 건, 쿠버네티스 Pod 트러블슈팅의 핵심은 결국 로그와 이벤트를 제대로 읽는 것이에요. 화려한 도구가 없어도, kubectl describe와 kubectl logs --previous 두 개만 잘 써도 대부분의 문제는 해결됩니다.

    CrashLoopBackOff는 원인이 다양하니까 로그를 꼼꼼히 보고 하나씩 제거해 나가는 방식이 좋아요. OOMKilled는 일단 메모리 사용량 측정부터 시작해서 Limit 조정이냐, 누수 수정이냐를 판단하면 되고요.

    정리하면:

    • ✅ CrashLoopBackOff: kubectl logs --previous로 죽기 직전 로그 확인 → Probe 설정, 환경 변수, 마운트 순서로 체크
    • ✅ OOMKilled: kubectl top pod로 실제 사용량 확인 → Limit 상향 조정 또는 누수 수정
    • ✅ 막막할 땐 kubectl debug로 임시 컨테이너 붙여서 내부 확인

    다음 글에서는 Pending 상태에서 Pod가 뜨지 않는 경우 (노드 리소스 부족, Taints/Tolerations 문제 등)를 다뤄볼 예정입니다. Pod가 아예 시작조차 안 된다면 그쪽 글을 참고해 주세요!

    혹시 이 글에서 다루지 않은 케이스로 고생하고 계신 분 있으시면 댓글로 남겨주세요. 같이 고민해 볼게요 😊

  • [k8s] ArgoCD 프로덕션 환경 GitOps 베스트 프랙티스: 안정적인 배포와 보안 강화

    [k8s] ArgoCD 프로덕션 환경 GitOps 베스트 프랙티스: 안정적인 배포와 보안 강화

    ArgoCD 프로덕션 환경 GitOps 베스트 프랙티스: 안정적인 배포와 보안 강화

    안녕하세요, 13년차 인프라 엔지니어입니다. 오늘은 쿠버네티스(Kubernetes) 배포의 핵심 툴 중 하나인 ArgoCD와 GitOps에 대해 이야기해보려고 해요. 사실 제가 처음 인프라 엔지니어를 시작했을 때는 배포라고 하면 SSH로 서버에 접속해서 스크립트 돌리고, 수동으로 설정을 변경하고, 문제가 터지면 눈으로 찾아 헤매는 게 일상이었거든요. 그러다 쿠버네티스 세상이 열리고 CI/CD 파이프라인이 중요해지면서, 더 안정적이고 효율적인 배포 방식에 대한 갈증이 커졌습니다.

    수많은 삽질 끝에 제가 정착한 방법이 바로 GitOps였습니다. 그리고 그 중심에는 ArgoCD가 있었죠. 처음엔 이게 뭔가 싶었는데, 막상 써보니까 ‘아, 이거 진짜 편하고 안전하네!’ 싶더라고요. 프로덕션 환경에서 ArgoCD를 안정적으로 운영하고 GitOps 보안을 강화하기 위한 저만의 경험과 베스트 프랙티스를 공유해볼까 합니다. 혹시 쿠버네티스 배포 때문에 밤잠 설치고 계신 분들이 있다면, 이 글이 조금이나마 도움이 되었으면 좋겠네요. 💡

    ArgoCD와 GitOps의 전체 아키텍처는 위 그림처럼 구성됩니다. Git을 중심으로 모든 것이 돌아가는 모습을 보실 수 있어요.

    왜 ArgoCD와 GitOps인가요? – 삽질 끝에 찾은 안정성

    저도 처음에는 Jenkins 같은 전통적인 CI/CD 툴로 쿠버네티스 배포를 시도했어요. 하지만 배포 스크립트 관리도 어렵고, 배포 이력 추적도 쉽지 않더라고요. 특히 긴급 롤백(Rollback) 상황에서는 정말 아찔한 경험도 많았습니다. 😱

    GitOps는 쉽게 말해, Git을 인프라의 ‘단 하나의 진실된 소스(Single Source of Truth)’로 삼는 운영 방식입니다. 모든 인프라와 애플리케이션의 상태를 Git 리포지토리(Repository)에 코드(Code)로 저장하고, Git에 변경사항이 푸시(Push)되면 자동으로 인프라에 반영하는 방식이죠. ArgoCD는 이 GitOps 철학을 쿠버네티스 환경에서 구현해주는 강력한 선언적(Declarative) GitOps 지속적 배포(Continuous Delivery) 툴입니다.

    ArgoCD는 쿠버네티스 클러스터(Cluster) 내부에서 동작하면서, Git 리포지토리의 상태와 실제 클러스터의 상태를 계속 비교합니다. 만약 두 상태가 다르면, Git 리포지토리의 상태(원하는 상태)로 클러스터의 상태를 동기화(Sync)하려고 시도하죠. 이걸 풀 기반(Pull-based) 배포라고 하는데, 기존의 푸시 기반(Push-based) CI/CD 방식보다 훨씬 안정적이고 보안에도 유리합니다. 직접 써보니, 이 방식이 정말 믿음직하더라고요. ✅

    ArgoCD와 GitOps, 쉽게 이해하기

    복잡하게 생각할 것 없이, GitOps는 우리가 늘 쓰던 Git으로 인프라도 관리하자는 이야기입니다. 애플리케이션 코드를 Git으로 관리하듯이, 쿠버네티스 매니페스트(Manifest) 파일들도 Git에 넣고 관리하는 거죠. 이렇게 하면 다음과 같은 장점들이 생깁니다.

    • 버전 관리(Version Control): 모든 변경 이력이 Git에 남으니, 누가 언제 무엇을 바꿨는지 명확하게 알 수 있습니다.
    • 롤백(Rollback) 용이: 문제가 생기면 Git 커밋(Commit)을 되돌리는 것만으로 이전 상태로 쉽게 돌아갈 수 있습니다.
    • 감사(Auditing) 및 보안 강화: 모든 변경이 Git을 통해 이루어지므로, 승인된 변경만 반영될 수 있도록 워크플로우(Workflow)를 구축하기 좋습니다.
    • 단일 진실 공급원(Single Source of Truth): 개발, 운영팀 모두 Git만 보면 현재 인프라 상태를 파악할 수 있습니다.

    ArgoCD는 이 GitOps를 쿠버네티스에서 실현시켜주는 컨트롤러(Controller)입니다. 주요 특징은 다음과 같아요.

    • 선언적(Declarative) 관리: 원하는 상태를 YAML 파일로 선언해두면, ArgoCD가 알아서 그 상태를 유지합니다.
    • 자동 동기화(Automatic Synchronization): Git 리포지토리의 변경을 감지하고 자동으로 클러스터에 반영할 수 있습니다.
    • 시각적인 UI: 웹 UI를 통해 애플리케이션의 배포 상태, 리소스(Resource) 현황, 동기화 이력 등을 한눈에 확인할 수 있습니다. 저처럼 눈으로 확인해야 직성이 풀리는 사람에겐 정말 최고더라고요.
    • 다양한 배포 전략 지원: 롤링 업데이트(Rolling Update), 카나리 배포(Canary Deployment), 블루/그린 배포(Blue/Green Deployment) 등 다양한 배포 전략을 연동하여 구현할 수 있습니다.

    프로덕션 환경을 위한 ArgoCD 설정 팁

    이제 본격적으로 프로덕션 환경에서 ArgoCD를 효과적으로 사용하는 베스트 프랙티스를 공유해볼게요. 제가 직접 겪으면서 터득한 노하우들이니, 꼭 참고하시면 좋겠습니다.

    1. Git Repository 구조화: Monorepo vs. Multirepo

    Git 리포지토리를 어떻게 구성할지는 GitOps 전략의 첫 단추입니다. 크게 모노레포(Monorepo)와 멀티레포(Multirepo) 두 가지 방식이 있어요.

    • 모노레포(Monorepo): 모든 애플리케이션과 인프라 설정 파일을 하나의 Git 리포지토리에 저장하는 방식입니다. 초기 설정이 간단하고, 모든 것을 한곳에서 관리할 수 있다는 장점이 있습니다.
    • 멀티레포(Multirepo): 각 애플리케이션이나 환경별로 별도의 Git 리포지토리를 사용하는 방식입니다. 팀별 권한 분리나 대규모 서비스 운영에 유리할 수 있습니다.

    저 같은 경우, 초기에는 모노레포로 시작했다가 규모가 커지면서 멀티레포 형태로 전환했어요. 하지만 ArgoCD를 통해 여러 애플리케이션을 관리할 때는 애플리케이션별 Git 리포지토리 + 인프라 설정용 Git 리포지토리를 분리하는 방식이 가장 효율적이라고 느꼈습니다. 프로덕션 환경에서는 GitOps 보안과 관리의 용이성을 위해 인프라 설정과 애플리케이션 코드를 분리하는 것을 추천합니다.

    예시: 인프라 설정 Git 리포지토리 구조

    ├── applications # ArgoCD Application 정의
    │   ├── app1.yaml
    │   ├── app2.yaml
    │   └── ...
    ├── environments
    │   ├── dev
    │   │   ├── kustomization.yaml
    │   │   ├── namespace.yaml
    │   │   └── ...
    │   ├── stage
    │   │   ├── kustomization.yaml
    │   │   └── ...
    │   └── prod
    │       ├── kustomization.yaml
    │       └── ...
    └── base # 공통 설정
        ├── deployment.yaml
        ├── service.yaml
        └── ...
    

    위 다이어그램은 제가 주로 사용하는 Git Repository 구조를 시각적으로 보여줍니다. 환경별로 설정을 분리하고, 공통 설정은 base에 두는 방식이에요.

    2. 환경별 분리 및 Kustomize/Helm 활용

    개발(dev), 스테이징(stage), 프로덕션(prod) 환경은 각각 다른 설정(리소스 요구 사항, 환경 변수 등)을 가집니다. 이를 효과적으로 관리하려면 Kustomize나 Helm을 적극적으로 활용해야 합니다.

    • Kustomize: 기존 YAML 파일을 수정하지 않고 덮어쓰기(Overlay) 방식으로 환경별 설정을 관리하는 데 매우 유용합니다. base 디렉터리에 공통 설정 파일을 두고, 각 환경별 overlays 디렉터리에서 필요한 부분만 변경하는 방식은 정말 깔끔하죠.
    • Helm: 재사용 가능한 쿠버네티스 애플리케이션 패키징(Packaging) 도구입니다. 데이터베이스(Database)나 메시지 큐(Message Queue)처럼 공통적으로 사용되는 미들웨어(Middleware)를 배포할 때 매우 편리합니다. 저도 처음엔 Helm이 좀 어렵게 느껴졌는데, 익숙해지니 없으면 안 되는 존재가 되더라고요.

    ArgoCD 애플리케이션 정의에서 Kustomize나 Helm을 소스(Source)로 지정하면, ArgoCD가 알아서 해당 툴을 사용해서 매니페스트를 렌더링(Rendering)하고 배포해줍니다. 🚀

    apiVersion: argoproj.io/v1alpha1
    kind: Application
    metadata:
      name: my-app-prod
      namespace: argocd
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-infra-gitops.git
        targetRevision: HEAD
        path: environments/prod/my-app # Kustomize overlay 경로
      destination:
        server: https://kubernetes.default.svc
        namespace: my-app-prod
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true
    

    3. Sync Options와 Health Checks

    ArgoCD의 syncPolicy는 배포의 안정성을 결정하는 중요한 부분입니다. 프로덕션 환경에서는 다음 옵션들을 신중하게 설정해야 합니다.

    • automated.prune: true: Git 리포지토리에서 삭제된 리소스를 클러스터에서도 자동으로 삭제합니다. 클러스터의 불필요한 리소스 잔여물을 방지해줍니다.
    • automated.selfHeal: true: 클러스터의 상태가 Git 리포지토리의 상태와 다를 경우, ArgoCD가 자동으로 Git의 상태로 되돌립니다. 누군가 수동으로 클러스터 설정을 변경했을 때 원래대로 복구해주는 강력한 기능이죠. GitOps의 핵심 정신과 일치하는 부분입니다.
    • syncOptions: - CreateNamespace=true: 해당 네임스페이스(Namespace)가 없으면 ArgoCD가 자동으로 생성하도록 합니다.
    • 커스텀 헬스 체크(Custom Health Checks): 애플리케이션이 단순히 배포되었다고 끝이 아닙니다. 실제로 정상 작동하는지 확인하는 헬스 체크가 중요하죠. ArgoCD는 기본적으로 Pod의 Readiness/Liveness Probe를 활용하지만, 경우에 따라 ConfigMap에 커스텀 헬스 체크를 정의하여 더 정교한 상태 감지를 할 수 있습니다.

    4. Rollback 전략

    아무리 잘 준비해도 문제는 발생하기 마련이죠. 이때 빠르고 안전하게 롤백하는 것이 중요합니다. ArgoCD 환경에서의 롤백은 크게 두 가지 방식이 있어요.

    1. Git Revert: 가장 권장되는 방식입니다. 문제가 발생한 커밋을 Git에서 되돌리면(Revert) ArgoCD가 이를 감지하고 자동으로 이전 상태로 클러스터를 동기화합니다. 이 방식은 Git의 변경 이력이 그대로 남으므로 감사 추적에도 유리합니다.
    2. ArgoCD UI 롤백: ArgoCD 웹 UI에서 특정 애플리케이션의 History and Rollback 탭을 통해 이전 동기화 지점(Sync Point)으로 롤백할 수 있습니다. 긴급 상황에서 빠르게 대처할 수 있는 방법이지만, Git의 변경 이력에는 남지 않으므로 나중에 Git Revert로 맞춰주는 게 좋습니다.

    저도 예전에 새벽에 긴급 롤백을 해야 했던 적이 있었는데, Git Revert 하나로 모든 상황이 깔끔하게 정리되었을 때의 안도감이란… 정말 겪어봐야 알 수 있습니다. 👍

    GitOps 보안 강화: ArgoCD 프로덕션 환경 보안 설정

    프로덕션 환경에서는 GitOps 보안이 최우선 고려사항입니다. ArgoCD를 통해 모든 것이 배포되므로, ArgoCD 자체의 보안 설정은 물론 주변 환경과의 연동도 중요합니다.

    1. RBAC (Role-Based Access Control)

    ArgoCD는 자체적인 RBAC(Role-Based Access Control)를 지원합니다. 이를 통해 누가 어떤 애플리케이션을 조회, 동기화, 삭제할 수 있는지 세밀하게 권한을 제어할 수 있어요. argocd-cm ConfigMap이나 argocd-rbac-cm ConfigMap을 수정하여 정책을 정의합니다.

    또한, ArgoCD 프로젝트(Project)를 활용하여 애플리케이션들을 논리적으로 묶고, 프로젝트별로 RBAC 정책을 적용하면 관리 효율성과 보안을 동시에 잡을 수 있습니다. 예를 들어, 개발팀은 dev-project에만 접근 가능하고, 운영팀은 prod-project에만 접근 가능하도록 설정하는 식이죠.

    # argocd-rbac-cm ConfigMap 예시
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: argocd-rbac-cm
      namespace: argocd
    data:
      policy.csv: |
        p, role:admin, applications, *, */*, allow
        p, role:dev, applications, get, dev-project/*, allow
        g, myuser, role:dev
      policy.default: role:readonly
    

    2. Secret Management (외부 Secret 연동)

    민감한 정보인 시크릿(Secret)을 Git 리포지토리에 평문으로 저장하는 것은 절대 금물입니다. 🙅‍♂️ GitOps 보안을 위해 외부 시크릿 관리 솔루션과 연동하는 것이 필수입니다.

    • Sealed Secrets: 클러스터에 배포된 컨트롤러가 시크릿을 암호화하고, Git에 암호화된 시크릿을 저장합니다. 암호화된 시크릿은 해당 클러스터에서만 복호화(Decrypt)될 수 있어 안전합니다. 제가 홈랩에서도 가장 즐겨 쓰는 방식이에요.
    • External Secrets Operator: AWS Secrets Manager, Azure Key Vault, Google Secret Manager, HashiCorp Vault 등 클라우드(Cloud) 기반 시크릿 관리 서비스와 연동하여 시크릿을 쿠버네티스 시크릿으로 동기화합니다. 프로덕션 환경에서는 이 방식이 가장 일반적입니다.

    어떤 방법을 선택하든, 절대 시크릿을 Git에 직접 올리는 일은 없어야 합니다! 이건 제가 정말 피땀 흘려 배운 교훈입니다. ⚠️

    3. Private Repository 접근

    대부분의 프로덕션 환경에서는 프라이빗 Git 리포지토리(Private Git Repository)를 사용합니다. ArgoCD가 이 리포지토리에 접근하려면 인증 정보가 필요하겠죠. 다음 방법들을 사용할 수 있습니다.

    • SSH 키(SSH Key): 가장 일반적이고 강력한 방법입니다. ArgoCD에 SSH 키를 등록하고, 해당 키를 사용하여 리포지토리에 접근합니다.
    • HTTPS with Username/Password 또는 Personal Access Token (PAT): Git 서비스에서 발급받은 PAT를 ArgoCD에 등록하여 사용할 수 있습니다. 보안상 일반적인 비밀번호보다는 PAT를 사용하는 게 좋습니다.

    인증 정보를 ArgoCD에 등록할 때는 쿠버네티스 시크릿으로 안전하게 관리해야 합니다. 당연한 이야기지만, 이걸 놓쳐서 문제가 되는 경우를 꽤 많이 봤거든요. 😅

    ArgoCD 트러블슈팅: 제가 겪었던 문제들 (그리고 해결책)

    13년차 엔지니어라고 해도 삽질은 피할 수 없는 운명이죠. ArgoCD를 쓰면서도 여러 번 머리를 쥐어뜯었습니다. 몇 가지 흔한 문제와 해결책을 공유해볼게요.

    • 문제: ImagePullBackOff 에러 (프라이빗 레지스트리)
      상황: 배포된 Pod에서 프라이빗 컨테이너 이미지 레지스트리(Private Container Image Registry)의 이미지를 당겨오지 못하고 ImagePullBackOff 에러가 발생하는 경우.
      해결: 해당 네임스페이스에 ImagePullSecrets를 제대로 설정했는지 확인해야 합니다. ArgoCD 애플리케이션이 배포될 때 이 시크릿이 같이 생성되도록 매니페스트에 포함하거나, 수동으로 시크릿을 생성하고 Pod Spec에 추가해야 합니다. 저는 주로 ArgoCD가 CreateNamespace=true와 함께 시크릿도 함께 배포하도록 설정합니다.

    • 문제: Resource is not available 또는 Failed to install CRD
      상황: 애플리케이션 배포 시 커스텀 리소스 정의(CRD: Custom Resource Definition)가 먼저 설치되어야 하는데, 순서가 맞지 않아 발생하는 에러.
      해결: ArgoCD의 Sync Waves 기능을 활용하면 배포 순서를 제어할 수 있습니다. CRD를 먼저 배포하고, 그 이후에 CRD를 사용하는 애플리케이션 리소스를 배포하도록 설정하는 거죠. 예를 들어, CRD는 sync-wave: "-1", 일반 리소스는 sync-wave: "0"으로 설정하면 됩니다. 이 기능을 알게 된 후로 정말 속이 시원했습니다. 🎉

    • 문제: 롤백 후에도 문제가 지속됨
      상황: Git Revert나 ArgoCD UI 롤백을 했는데도 애플리케이션이 정상 상태로 돌아오지 않는 경우.
      해결: 롤백 대상이 되는 커밋이 정말 이전의 ‘정상’ 상태를 가리키는지 확인해야 합니다. 때로는 환경 변수나 외부 의존성(예: 데이터베이스 스키마 변경) 때문에 롤백만으로는 해결되지 않을 수 있거든요. 이럴 때는 문제 발생 시점을 정확히 파악하고, 관련된 모든 변경사항(Git, DB 스키마, 외부 서비스 설정 등)을 함께 되돌려야 합니다. 그리고 롤백 후 ArgoCD UI에서 애플리케이션의 Health 상태와 Events 탭을 꼼꼼히 확인하는 습관을 들이는 게 좋습니다.

    결과 및 검증: 안정적인 배포, 이제 Git만 바라봅니다.

    ArgoCD와 GitOps 베스트 프랙티스를 적용하고 나니, 정말 배포 과정이 안정적이고 예측 가능해졌습니다. 더 이상 불안에 떨며 배포 버튼을 누를 필요가 없어졌죠. ✅

    배포가 완료되면 ArgoCD 웹 UI에서 각 애플리케이션의 상태를 한눈에 확인할 수 있습니다. 모든 리소스가 Healthy 상태이고, Synced 상태인지 확인하는 것이 중요해요. 혹시 OutOfSync 상태라면, 어떤 리소스가 Git과 다른지 명확하게 보여주므로 문제 파악이 매우 쉽습니다. 이 시각적인 피드백(Feedback) 덕분에 트러블슈팅 시간도 대폭 줄었습니다.

    ArgoCD UI에서 모든 애플리케이션이 건강하고(Healthy) 동기화(Synced)된 상태를 보여주는 화면입니다. 이 화면을 볼 때마다 뿌듯하더라고요!

    실제로 저는 홈랩에서 여러 서비스를 ArgoCD로 관리하고 있는데, Git에 커밋만 하면 알아서 배포가 되고, 문제가 생겨도 Git Revert 한 번으로 해결되는 경험은 정말 혁신적이었습니다. CI/CD 파이프라인의 완성도를 높이는 데 ArgoCD가 결정적인 역할을 했다고 생각합니다.

    ArgoCD GitOps를 프로덕션 환경에 적용하기 위한 핵심 베스트 프랙티스를 요약한 인포그래픽입니다.

    마무리: GitOps 여정, 계속됩니다

    오늘은 ArgoCD 프로덕션 환경 GitOps 베스트 프랙티스에 대해 저의 경험을 바탕으로 이야기해봤습니다. 안정적인 배포와 GitOps 보안 강화를 위해 Git 리포지토리 구조화, 환경별 설정 관리, Sync Policy, 롤백 전략, RBAC, 시크릿 관리 등 다양한 측면을 다루었네요.

    처음에는 복잡하게 느껴질 수도 있지만, 한 번 제대로 구축해두면 개발팀과 운영팀 모두에게 엄청난 효율성과 안정성을 가져다줄 겁니다. 저도 아직 배워야 할 것이 많고, 계속해서 새로운 기술을 실험하고 있습니다. 이 글이 여러분의 쿠버네티스 배포 여정에 작은 등불이 되기를 바랍니다. 궁금한 점이나 공유하고 싶은 삽질 경험이 있다면 언제든지 댓글로 남겨주세요! 다음에는 ArgoCD와 함께 CI/CD 파이프라인을 더욱 자동화하는 방법에 대해 다뤄보겠습니다. 그때까지 모두 즐거운 서버실 라이프 즐기시길 바랍니다! 😊

  • [k8s] 쿠버네티스 영구 스토리지: Longhorn vs Rook Ceph 비교 및 선택 가이드

    쿠버네티스 영구 스토리지, 왜 이렇게 어렵냐고요

    쿠버네티스(Kubernetes)로 처음 스테이트풀(Stateful) 애플리케이션을 올려본 분들이라면 공감하실 텐데요. 컨테이너는 죽었다 살아나는 게 당연한 세계인데, 데이터는 절대 사라지면 안 되잖아요. 데이터베이스, 메시지 큐, 로그 수집기… 이런 것들을 올리려면 결국 쿠버네티스 영구 스토리지(Persistent Storage) 문제를 해결해야 합니다.

    저도 처음 홈랩에서 쿠버네티스 클러스터를 구성할 때 이 부분에서 꽤 오래 고민했거든요. NFS 마운트로 버티다가 결국 제대로 된 분산 스토리지를 써야겠다 싶어서 Longhorn이랑 Rook Ceph를 둘 다 실제로 구성해봤습니다. 오늘은 그 경험을 바탕으로 두 솔루션을 비교하고, 어떤 상황에서 뭘 선택해야 하는지 정리해 드릴게요.

    ▲ 쿠버네티스 영구 스토리지의 전체 구조 — PVC(Persistent Volume Claim)가 어떻게 실제 스토리지 백엔드와 연결되는지 보여주는 아키텍처 다이어그램

    먼저 개념부터: PV, PVC, CSI가 뭔가요?

    비교 얘기 전에 기본 개념을 짚고 넘어가겠습니다. 저도 처음엔 이 용어들이 다 비슷비슷해 보여서 헷갈렸거든요 ㅎㅎ

    • PV (Persistent Volume, 영구 볼륨): 클러스터 관리자가 프로비저닝한 실제 스토리지 리소스입니다. 쉽게 말해 “실제 저장 공간”이에요.
    • PVC (Persistent Volume Claim, 영구 볼륨 클레임): 개발자(또는 파드)가 스토리지를 요청하는 오브젝트입니다. “나 10GB짜리 저장 공간 필요해요”라고 요청하는 거죠.
    • StorageClass (스토리지 클래스): 스토리지의 종류와 프로비저닝 방식을 정의합니다. PVC가 요청하면 자동으로 PV를 만들어주는 동적 프로비저닝(Dynamic Provisioning)을 가능하게 해줘요.
    • CSI (Container Storage Interface, 컨테이너 스토리지 인터페이스): 쿠버네티스가 다양한 스토리지 벤더와 통신하기 위한 표준 인터페이스입니다. Longhorn도, Rook Ceph도 이 CSI 드라이버를 통해 쿠버네티스와 연동돼요.

    💡 핵심 포인트: 개발자는 PVC만 선언하면 되고, 실제 스토리지가 어디에 있는지는 신경 안 써도 됩니다. 그 복잡한 연결을 StorageClass와 CSI 드라이버가 처리해주거든요.

    Longhorn 소개: CNCF가 인정한 경량 분산 스토리지

    Longhorn은 Rancher(현재 SUSE 산하)에서 개발한 쿠버네티스 전용 분산 블록 스토리지입니다. CNCF(Cloud Native Computing Foundation) 졸업 프로젝트로 등록되어 있고, 오픈소스이면서 완전히 쿠버네티스 네이티브하게 설계됐어요.

    Longhorn의 주요 특징

    • 쿠버네티스 위에서 동작하는 컨트롤러 기반 아키텍처
    • 볼륨 복제본(Replica)을 여러 노드에 자동 분산
    • 내장 UI 대시보드 — 볼륨 상태를 시각적으로 확인 가능
    • 스냅샷(Snapshot) 및 백업 기능 내장 (S3, NFS 등으로 백업 가능)
    • 볼륨 확장(Volume Expansion) 지원
    • RWO(ReadWriteOnce) 지원, RWX(ReadWriteMany)는 NFS 게이트웨이를 통해 제한적으로 지원

    Longhorn 설치 — Helm으로 빠르게

    실제로 설치해보겠습니다. 저는 k3s 기반 3노드 클러스터에서 테스트했어요.

    # 사전 요구사항 확인 (iscsi 패키지 필요)
    sudo apt-get install -y open-iscsi
    sudo systemctl enable --now iscsid
    
    # Helm 저장소 추가
    helm repo add longhorn https://charts.longhorn.io
    helm repo update
    
    # longhorn 네임스페이스 생성 및 설치
    helm install longhorn longhorn/longhorn \
      --namespace longhorn-system \
      --create-namespace \
      --set defaultSettings.defaultReplicaCount=3

    설치가 완료되면 longhorn-system 네임스페이스에 여러 파드가 뜨는 걸 확인할 수 있어요.

    kubectl get pods -n longhorn-system
    # NAME                                        READY   STATUS    RESTARTS
    # longhorn-manager-xxxxx                      1/1     Running   0
    # longhorn-driver-deployer-xxxxx              1/1     Running   0
    # longhorn-ui-xxxxx                           1/1     Running   0
    # engine-image-ei-xxxxx-xxxxx                 1/1     Running   0

    Longhorn UI에 접근하려면 포트 포워딩이나 인그레스(Ingress, 외부 트래픽 진입점)를 설정해야 합니다.

    kubectl port-forward -n longhorn-system svc/longhorn-frontend 8080:80

    브라우저에서 http://localhost:8080으로 접속하면 볼륨 상태, 노드 디스크 현황을 한눈에 볼 수 있는 대시보드가 나옵니다. 이거 처음 봤을 때 진짜 편하다 싶었어요.

    Longhorn StorageClass 및 PVC 생성 예시

    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: longhorn
    provisioner: driver.longhorn.io
    allowVolumeExpansion: true
    parameters:
      numberOfReplicas: "3"
      staleReplicaTimeout: "2880"
      fromBackup: ""
      fsType: "ext4"
    ---
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: my-longhorn-pvc
    spec:
      accessModes:
        - ReadWriteOnce
      storageClassName: longhorn
      resources:
        requests:
          storage: 10Gi

    Rook Ceph 소개: 엔터프라이즈급 분산 스토리지

    Rook은 Ceph를 쿠버네티스에서 오퍼레이터(Operator) 패턴으로 운영할 수 있게 해주는 프레임워크입니다. Ceph 자체는 수십 년의 역사를 가진 검증된 분산 스토리지 시스템이고, Rook은 그 복잡한 Ceph를 쿠버네티스 위에서 쉽게(?) 운영하게 해주죠.

    솔직히 말하면 “쉽게”라는 말에 따옴표를 붙인 이유가 있어요. 처음 Rook Ceph 설치할 때 삽질을 꽤 했거든요 ㅎㅎ

    Rook Ceph의 주요 특징

    • 블록 스토리지(RBD), 파일시스템(CephFS), 오브젝트 스토리지(S3 호환 RGW) 모두 지원
    • CephFS를 통한 RWX(ReadWriteMany) 네이티브 지원 — 여러 파드가 동시에 같은 볼륨 마운트 가능
    • PG(Placement Group), CRUSH Map 등 고급 튜닝 옵션
    • 대규모 클러스터에서 검증된 안정성
    • Ceph Dashboard 내장
    • 최소 3개 OSD(Object Storage Daemon) 노드 권장

    Rook Ceph 설치 — 조금 더 복잡합니다

    # Rook 오퍼레이터 설치
    git clone --single-branch --branch v1.13.0 https://github.com/rook/rook.git
    cd rook/deploy/examples
    
    # CRD 및 공통 리소스 먼저 설치
    kubectl create -f crds.yaml
    kubectl create -f common.yaml
    
    # 오퍼레이터 배포
    kubectl create -f operator.yaml
    
    # 오퍼레이터 파드 확인
    kubectl get pods -n rook-ceph
    # NAME                                  READY   STATUS    RESTARTS
    # rook-ceph-operator-xxxxx              1/1     Running   0

    오퍼레이터가 Running 상태가 되면 Ceph 클러스터를 생성합니다. 아래는 기본 클러스터 설정이에요.

    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: 3
        allowMultiplePerNode: false
      mgr:
        count: 2
      dashboard:
        enabled: true
        ssl: true
      storage:
        useAllNodes: true
        useAllDevices: false
        deviceFilter: "^sd[b-z]"
      resources:
        mgr:
          requests:
            cpu: "500m"
            memory: "512Mi"

    ⚠️ 주의사항: deviceFilter 설정이 중요합니다. 잘못 설정하면 OS 디스크까지 Ceph OSD로 사용하려고 할 수 있어요. 저도 이 부분에서 한 번 아찔한 경험을 했습니다. 반드시 데이터 디스크만 지정하세요.

    # Ceph 블록 스토리지 풀 및 StorageClass 생성
    kubectl create -f csi/rbd/storageclass.yaml
    
    # CephFS (RWX 지원) StorageClass 생성
    kubectl create -f filesystem.yaml
    kubectl create -f csi/cephfs/storageclass.yaml

    ▲ Rook Ceph 아키텍처 — MON(모니터), MGR(매니저), OSD(오브젝트 스토리지 데몬)의 구성과 CSI 드라이버를 통한 쿠버네티스 연동 구조

    Longhorn vs Rook Ceph: 직접 써본 비교

    두 솔루션을 실제로 운영해보면서 느낀 점들을 솔직하게 비교해 드릴게요.

    항목 Longhorn Rook Ceph
    설치 난이도 ⭐⭐ (쉬움) ⭐⭐⭐⭐ (복잡함)
    최소 노드 수 1개 (복제본 설정에 따라) 3개 (OSD 최소 3개 권장)
    리소스 사용량 가벼움 무거움 (MON, MGR, OSD 등 다수)
    RWX 지원 제한적 (NFS 게이트웨이 필요) 네이티브 지원 (CephFS)
    오브젝트 스토리지 미지원 지원 (S3 호환 RGW)
    UI/관리 편의성 직관적인 내장 UI Ceph Dashboard (기능 풍부)
    백업 기능 내장 (S3, NFS 백업) 별도 구성 필요
    성숙도/안정성 CNCF 졸업 프로젝트 CNCF 졸업 프로젝트 (Ceph는 업계 표준)
    운영 복잡도 낮음 높음 (PG 튜닝, CRUSH Map 등)
    적합한 규모 소~중형 클러스터 중~대형 클러스터

    실제로 겪은 트러블슈팅 사례들

    Longhorn에서 겪은 문제: 노드 한 대를 재부팅했더니 해당 노드의 복제본이 degraded 상태가 됐어요. 근데 이건 Longhorn이 자동으로 다른 노드에 복제본을 재빌드해주더라고요. 시간이 좀 걸리긴 했지만 데이터 손실은 없었습니다. ✅

    Rook Ceph에서 겪은 문제: OSD 디스크 하나에 파티션이 남아있었는데, Rook이 해당 디스크를 인식 못 하는 문제가 있었어요. 이게 처음엔 왜 안 되는지 몰라서 꽤 삽질했습니다.

    # OSD 디스크 초기화 — 기존 파티션 제거
    sgdisk --zap-all /dev/sdb
    dd if=/dev/zero of=/dev/sdb bs=1M count=100 oflag=direct
    blkdiscard /dev/sdb
    
    # 파티션 확인
    lsblk /dev/sdb

    ⚠️ 경고: 위 명령어는 해당 디스크의 모든 데이터를 완전히 삭제합니다. 반드시 올바른 디스크를 지정했는지 확인하고 실행하세요.

    또 Ceph 클러스터 상태가 HEALTH_WARN으로 뜰 때 원인 파악하는 방법도 알아두면 좋아요.

    # Ceph 상태 확인
    kubectl exec -n rook-ceph -it deploy/rook-ceph-tools -- ceph status
    kubectl exec -n rook-ceph -it deploy/rook-ceph-tools -- ceph health detail
    
    # OSD 상태 확인
    kubectl exec -n rook-ceph -it deploy/rook-ceph-tools -- ceph osd status

    ▲ Longhorn 대시보드 — 볼륨 상태, 노드별 복제본 분산 현황, 백업 상태를 한눈에 모니터링하는 화면

    어떤 상황에서 뭘 선택해야 할까요?

    이게 결국 핵심 질문이잖아요. 저는 이렇게 기준을 잡아드리고 싶어요.

    Longhorn을 선택하세요, 만약…

    • ✅ 홈랩이나 소규모 클러스터(노드 3~5개 이하)를 운영한다면
    • ✅ 쿠버네티스 스토리지를 처음 도입하는 팀이라면
    • ✅ 운영 인력이 부족하고 관리 부담을 최소화하고 싶다면
    • ✅ 블록 스토리지(RWO) 위주로만 사용한다면
    • ✅ 백업/복구 기능을 간편하게 쓰고 싶다면
    • ✅ 빠르게 구성해서 바로 써야 하는 상황이라면

    Rook Ceph를 선택하세요, 만약…

    • ✅ 중대형 클러스터(노드 5개 이상)를 운영한다면
    • ✅ RWX(ReadWriteMany) 볼륨이 반드시 필요하다면
    • ✅ S3 호환 오브젝트 스토리지도 함께 필요하다면
    • ✅ 전담 인프라 운영 인력이 있다면
    • ✅ 엔터프라이즈 환경에서 검증된 기술 스택이 필요하다면
    • ✅ 고가용성과 세밀한 스토리지 정책 제어가 필요하다면

    둘 다 쓰는 경우도 있어요

    실제로 일부 팀에서는 일반적인 파드 스토리지는 Longhorn으로, RWX가 필요한 공유 파일시스템이나 오브젝트 스토리지는 Rook Ceph로 나눠서 운영하기도 합니다. 복잡해지긴 하지만 각각의 장점을 활용할 수 있는 방법이기도 해요.

    결과 검증: 실제로 제대로 동작하는지 확인하기

    설치만 하면 끝이 아니죠. 실제로 데이터가 잘 보존되는지 확인해봐야 합니다. 아래는 간단한 테스트 시나리오예요.

    # 테스트용 파드 생성
    apiVersion: v1
    kind: Pod
    metadata:
      name: storage-test
    spec:
      containers:
      - name: test
        image: busybox
        command: ["/bin/sh", "-c", "while true; do date >> /data/test.log; sleep 5; done"]
        volumeMounts:
        - mountPath: /data
          name: test-volume
      volumes:
      - name: test-volume
        persistentVolumeClaim:
          claimName: my-longhorn-pvc
    # 파드 실행 후 데이터 확인
    kubectl exec storage-test -- cat /data/test.log
    
    # 파드를 강제 삭제
    kubectl delete pod storage-test
    
    # 새 파드로 다시 마운트해서 데이터가 남아있는지 확인
    kubectl apply -f storage-test.yaml
    kubectl exec storage-test -- cat /data/test.log
    # 이전 로그가 그대로 남아있으면 성공! 🎉

    🎉 데이터가 살아있는 걸 확인했을 때의 그 안도감… 처음엔 진짜 설레더라고요. 쿠버네티스에서 영구 스토리지가 제대로 동작한다는 걸 눈으로 확인한 순간이었습니다.

    추가로 볼륨 상태도 확인해두면 좋아요.

    # PVC 상태 확인
    kubectl get pvc
    # NAME               STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
    # my-longhorn-pvc    Bound    pvc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   10Gi       RWO            longhorn       5m
    
    # PV 상세 정보
    kubectl describe pv pvc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    ▲ Longhorn vs Rook Ceph 선택 가이드 요약 — 클러스터 규모, 기능 요구사항, 운영 복잡도를 기준으로 한 비교 인포그래픽

    자주 묻는 질문 (FAQ)

    Q. Longhorn은 프로덕션 환경에서 써도 되나요?

    네, CNCF 졸업 프로젝트이고 실제로 많은 기업에서 프로덕션에 사용하고 있습니다. 다만 대규모 클러스터나 높은 I/O가 필요한 환경에서는 Ceph 대비 한계가 있을 수 있어요.

    Q. Rook Ceph 최소 사양이 어떻게 되나요?

    OSD 노드 최소 3개를 권장합니다. 각 OSD 노드에는 전용 디스크가 필요하고, MON(모니터) 데몬 운영을 위한 CPU와 메모리도 여유 있게 확보해야 해요. 리소스가 빠듯한 환경에서는 Longhorn이 훨씬 현실적입니다.

    Q. 기존 NFS 스토리지에서 마이그레이션이 가능한가요?

    직접적인 마이그레이션 도구는 없고, 보통 데이터를 백업 후 새 PVC에 복원하는 방식을 사용합니다. Velero(벨레로) 같은 쿠버네티스 백업 도구를 활용하면 좀 더 체계적으로 진행할 수 있어요. 이 내용은 다음 글에서 다룰 예정입니다.

    Q. 홈랩에서는 뭘 추천하세요?

    저는 홈랩에서 Longhorn을 쓰고 있어요. 설치가 간단하고 UI가 직관적이어서 관리하기 편합니다. 노드 3대 이하 환경이라면 Longhorn이 압도적으로 편해요.

    마무리: 결국 “상황에 맞는” 선택이 정답입니다

    13년 동안 인프라 일을 하면서 느낀 건데요. 기술 선택에 “절대적인 정답”은 없더라고요. Longhorn이 좋냐, Rook Ceph가 좋냐가 아니라 내 환경에 뭐가 맞냐가 핵심이에요.

    소규모 클러스터에서 빠르게 쿠버네티스 영구 스토리지를 도입하고 싶다면 Longhorn으로 시작하세요. 운영하다가 규모가 커지고 RWX나 오브젝트 스토리지가 필요해지면 그때 Rook Ceph로 전환하거나 병행하는 것도 방법이에요.

    중요한 건 일단 시작하는 거라고 생각해요. NFS로 버티다가 나중에 대규모 마이그레이션 하는 것보다, 처음부터 제대로 된 CSI 드라이버 기반 스토리지를 도입하는 게 훨씬 낫거든요.

    다음 글에서는 Velero를 활용한 쿠버네티스 백업 전략에 대해 다룰 예정입니다. Longhorn 내장 백업과 Velero를 조합하면 꽤 탄탄한 백업 체계를 만들 수 있거든요. 기대해 주세요! 🎉

    혹시 설치하다가 막히는 부분이 있으시면 댓글로 남겨주세요. 제가 겪었던 삽질 경험이 도움이 될 수도 있으니까요 ㅎㅎ

  • [k8s] Helm Chart 베스트 프랙티스: 프로덕션 배포 및 관리 전략

    Helm Chart를 제대로 쓰고 있는 게 맞나요?

    솔직히 말씀드리면, 저도 처음 Helm을 쓰기 시작했을 때는 그냥 helm install 하나로 모든 게 해결된다고 생각했거든요. 차트 가져다 쓰고, values 파일 조금 수정하고, 배포하면 끝. 근데 이게 개발 환경에서는 통했는데, 프로덕션에 올리는 순간 문제가 터지기 시작하더라고요.

    롤백이 안 된다, 시크릿이 차트에 하드코딩돼 있다, 팀원이 values 파일을 잘못 수정해서 서비스가 내려갔다… 이런 일들을 겪으면서 “아, Helm Chart 베스트 프랙티스라는 게 괜히 있는 게 아니구나” 싶었습니다. 그래서 오늘은 13년 동안 쿠버네티스 인프라를 운영하면서 직접 삽질하며 정리한 Helm 배포 전략과 관리 노하우를 공유해드리려고 해요.

    쿠버네티스 Helm을 처음 시작하신 분들도, 이미 쓰고 계신데 뭔가 찜찜한 분들도 도움이 될 거예요.

    ▲ Helm Chart가 쿠버네티스 클러스터에 배포되는 전체 흐름 — Chart Repository부터 Release 관리까지 한눈에 볼 수 있습니다.

    Helm이 뭔지 다시 한번 짚고 가기

    아마 대부분 아시겠지만, 한 번 정리하고 넘어갈게요. Helm(헬름)은 쿠버네티스의 패키지 매니저입니다. 쉽게 말해, apt나 yum처럼 쿠버네티스 애플리케이션을 패키징하고 배포하는 도구예요.

    핵심 개념 세 가지만 기억하시면 됩니다.

    • Chart(차트): 쿠버네티스 리소스를 정의하는 파일 묶음. npm의 package.json 같은 개념이에요.
    • Release(릴리스): 클러스터에 설치된 Chart의 인스턴스. 같은 Chart를 여러 번 설치하면 각각 다른 Release가 됩니다.
    • Repository(레포지토리): Chart를 저장하고 공유하는 저장소. Docker Hub의 Chart 버전이라고 보시면 돼요.

    Helm 3 기준으로 설명드릴 거예요. Helm 2는 Tiller(틸러)라는 서버 컴포넌트가 있었는데, 보안 문제로 Helm 3에서 완전히 제거됐거든요. 혹시 아직 Helm 2를 쓰시는 분 계시면, 진짜 빨리 마이그레이션하세요.

    Chart 구조를 제대로 잡는 것부터 시작

    프로덕션 Helm 관리의 첫 번째 원칙은 Chart 디렉토리 구조를 일관성 있게 가져가는 것입니다. 처음부터 잘 잡아두지 않으면 나중에 수습하기가 정말 힘들어요.

    my-app/
    ├── Chart.yaml          # 차트 메타데이터 (이름, 버전, 의존성)
    ├── values.yaml         # 기본 설정값
    ├── values-dev.yaml     # 개발 환경 오버라이드
    ├── values-staging.yaml # 스테이징 환경 오버라이드
    ├── values-prod.yaml    # 프로덕션 환경 오버라이드
    ├── templates/
    │   ├── _helpers.tpl    # 재사용 가능한 템플릿 함수
    │   ├── deployment.yaml
    │   ├── service.yaml
    │   ├── ingress.yaml
    │   ├── configmap.yaml
    │   ├── hpa.yaml        # HorizontalPodAutoscaler
    │   ├── pdb.yaml        # PodDisruptionBudget
    │   └── NOTES.txt       # 설치 후 출력되는 안내 메시지
    └── charts/             # 의존 차트들 (서브차트)

    여기서 핵심은 환경별 values 파일을 분리하는 거예요. 하나의 values.yaml에 모든 환경 설정을 때려넣는 분들이 많은데, 그러면 관리가 안 됩니다. 제가 실제로 운영하는 방식은 기본값은 values.yaml에 두고, 환경별 차이점만 오버라이드 파일에 담아두는 거죠.

    # values.yaml (기본값)
    replicaCount: 1
    
    image:
      repository: my-registry/my-app
      tag: "latest"  # CI/CD에서 덮어씁니다
      pullPolicy: IfNotPresent
    
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 512Mi
    
    autoscaling:
      enabled: false
      minReplicas: 1
      maxReplicas: 10
      targetCPUUtilizationPercentage: 70
    
    podDisruptionBudget:
      enabled: false
      minAvailable: 1
    # values-prod.yaml (프로덕션 오버라이드)
    replicaCount: 3
    
    image:
      pullPolicy: Always
    
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
      limits:
        cpu: 2000m
        memory: 2Gi
    
    autoscaling:
      enabled: true
      minReplicas: 3
      maxReplicas: 20
    
    podDisruptionBudget:
      enabled: true
      minAvailable: 2

    배포할 때는 이렇게 쓰면 됩니다.

    # 프로덕션 배포
    helm upgrade --install my-app ./my-app \
      -f values.yaml \
      -f values-prod.yaml \
      --namespace production \
      --create-namespace \
      --set image.tag=${IMAGE_TAG}

    💡 팁: --install 플래그를 함께 쓰면 없으면 설치하고, 있으면 업그레이드합니다. CI/CD 파이프라인에서 정말 유용하게 쓰이는 옵션이더라고요.

    실전 배포 전략: 이것만 지켜도 반은 성공

    ▲ GitOps 기반 Helm 배포 파이프라인 — Git push부터 프로덕션 릴리스까지의 자동화 흐름을 보여줍니다.

    1. Chart.yaml 버전 관리를 철저하게

    Chart.yaml에서 version과 appVersion을 구분하는 게 중요합니다. 처음엔 저도 이걸 같은 거라고 생각했는데, 아니더라고요.

    apiVersion: v2
    name: my-app
    description: My Application Helm Chart
    type: application
    version: 1.3.0      # Chart 자체의 버전 (Chart 구조가 바뀌면 올림)
    appVersion: "2.1.4" # 실제 애플리케이션 버전
    
    dependencies:
      - name: postgresql
        version: "12.x.x"
        repository: "https://charts.bitnami.com/bitnami"
        condition: postgresql.enabled

    SemVer(시맨틱 버저닝)를 반드시 지켜주세요. Chart 구조가 바뀌면 version을, 앱 소스만 바뀌면 appVersion만 올리는 습관을 들이면 나중에 롤백할 때 정말 편합니다.

    2. _helpers.tpl로 중복 제거하기

    템플릿 파일에서 같은 라벨, 같은 셀렉터를 매번 복붙하고 계신 분 계신가요? 저 예전에 그랬거든요. 나중에 앱 이름 하나 바꾸려고 파일을 10개 수정한 적이 있었는데, 그때 _helpers.tpl의 소중함을 알았습니다.

    # templates/_helpers.tpl
    {{/*
    공통 라벨 정의
    */}}
    {{- define "my-app.labels" -}}
    helm.sh/chart: {{ include "my-app.chart" . }}
    {{ include "my-app.selectorLabels" . }}
    {{- if .Chart.AppVersion }}
    app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
    {{- end }}
    app.kubernetes.io/managed-by: {{ .Release.Service }}
    {{- end }}
    
    {{/*
    셀렉터 라벨
    */}}
    {{- define "my-app.selectorLabels" -}}
    app.kubernetes.io/name: {{ include "my-app.name" . }}
    app.kubernetes.io/instance: {{ .Release.Name }}
    {{- end }}
    
    {{/*
    ServiceAccount 이름
    */}}
    {{- define "my-app.serviceAccountName" -}}
    {{- if .Values.serviceAccount.create }}
    {{- default (include "my-app.fullname" .) .Values.serviceAccount.name }}
    {{- else }}
    {{- default "default" .Values.serviceAccount.name }}
    {{- end }}
    {{- end }}

    3. 시크릿 관리 — 절대 Chart에 넣지 마세요

    ⚠️ 경고: 이게 진짜 중요합니다. DB 패스워드, API 키, 인증서 같은 민감한 정보를 values.yaml이나 Chart에 직접 넣으면 안 돼요. Git에 올라가는 순간 끝입니다.

    제가 추천하는 방법은 두 가지예요.

    방법 1: 외부 시크릿 참조

    # templates/deployment.yaml
    env:
      - name: DB_PASSWORD
        valueFrom:
          secretKeyRef:
            name: my-app-secrets  # 별도로 생성된 Secret
            key: db-password

    방법 2: Helm Secrets 플러그인 활용

    # helm-secrets 플러그인 설치
    helm plugin install https://github.com/jkroepke/helm-secrets
    
    # secrets.yaml을 암호화 (SOPS + AWS KMS 또는 GPG 활용)
    helm secrets encrypt secrets.yaml
    
    # 배포 시 복호화하여 사용
    helm secrets upgrade --install my-app ./my-app \
      -f values.yaml \
      -f secrets.yaml

    저는 현재 AWS Secrets Manager와 External Secrets Operator를 조합해서 쓰고 있는데, 이 조합이 가장 깔끔하더라고요. 나중에 이 주제로 별도 글 하나 써볼게요.

    4. PodDisruptionBudget과 HPA는 프로덕션 필수

    롤링 업데이트 중에 서비스가 잠깐 내려간 경험 있으신가요? 저 처음에 그거 때문에 새벽에 전화 받았거든요. PDB(PodDisruptionBudget)를 설정하면 노드 드레인이나 업그레이드 중에도 최소 파드 수를 보장해줍니다.

    # templates/pdb.yaml
    {{- if .Values.podDisruptionBudget.enabled }}
    apiVersion: policy/v1
    kind: PodDisruptionBudget
    metadata:
      name: {{ include "my-app.fullname" . }}
      labels:
        {{- include "my-app.labels" . | nindent 4 }}
    spec:
      minAvailable: {{ .Values.podDisruptionBudget.minAvailable }}
      selector:
        matchLabels:
          {{- include "my-app.selectorLabels" . | nindent 6 }}
    {{- end }}
    # templates/hpa.yaml
    {{- if .Values.autoscaling.enabled }}
    apiVersion: autoscaling/v2
    kind: HorizontalPodAutoscaler
    metadata:
      name: {{ include "my-app.fullname" . }}
      labels:
        {{- include "my-app.labels" . | nindent 4 }}
    spec:
      scaleTargetRef:
        apiVersion: apps/v1
        kind: Deployment
        name: {{ include "my-app.fullname" . }}
      minReplicas: {{ .Values.autoscaling.minReplicas }}
      maxReplicas: {{ .Values.autoscaling.maxReplicas }}
      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
    {{- end }}

    ⚠️ 실제로 겪었던 트러블슈팅 사례

    문제 1: helm upgrade 후 롤백이 안 되는 상황

    배포했는데 문제가 생겨서 롤백하려고 했더니 이전 릴리스 히스토리가 없는 거예요. 알고 보니 --history-max 옵션을 설정 안 해서 히스토리가 날아가 있었고, 심지어 ConfigMap이 Helm 외부에서 직접 수정돼 있어서 상태가 꼬여 있었습니다.

    # 릴리스 히스토리 최대 10개 유지 (기본값 10)
    helm upgrade --install my-app ./my-app \
      --history-max 10 \
      --atomic \
      --timeout 5m0s
    
    # 롤백 방법
    helm history my-app -n production  # 히스토리 확인
    helm rollback my-app 3 -n production  # 3번 리비전으로 롤백

    💡 팁: --atomic 플래그를 쓰면 배포 실패 시 자동으로 이전 상태로 롤백해줍니다. CI/CD에서 정말 유용하더라고요.

    문제 2: helm diff 없이 배포했다가 낭패

    values 파일을 수정하고 바로 배포했다가 예상치 못한 리소스가 변경된 적이 있었어요. 이후로는 반드시 helm-diff 플러그인을 써서 변경 사항을 먼저 확인합니다.

    # helm-diff 플러그인 설치
    helm plugin install https://github.com/databus23/helm-diff
    
    # 배포 전 변경 사항 미리 확인
    helm diff upgrade my-app ./my-app \
      -f values.yaml \
      -f values-prod.yaml \
      -n production

    문제 3: 네임스페이스 간 의존성 충돌

    서브차트를 쓰다 보면 의존성 버전이 충돌하는 경우가 있어요. helm dependency update를 주기적으로 실행하고, Chart.lock 파일을 Git에 함께 커밋하는 걸 습관화하세요.

    # 의존성 업데이트
    helm dependency update ./my-app
    
    # 의존성 목록 확인
    helm dependency list ./my-app

    배포 결과 검증하기

    ▲ Helm 릴리스 상태와 쿠버네티스 리소스 헬스를 한눈에 확인할 수 있는 모니터링 대시보드 예시입니다.

    배포가 끝났다고 끝이 아닙니다. 제대로 됐는지 확인하는 과정이 중요해요.

    # 릴리스 상태 확인
    helm status my-app -n production
    
    # 실제 렌더링된 매니페스트 확인
    helm get manifest my-app -n production
    
    # 적용된 values 확인
    helm get values my-app -n production
    
    # 전체 릴리스 목록
    helm list -A
    
    # 배포된 리소스 상태 확인
    kubectl get all -l app.kubernetes.io/instance=my-app -n production
    
    # 파드 로그 확인
    kubectl logs -l app.kubernetes.io/name=my-app -n production --tail=100

    저는 배포 후 항상 이 체크리스트를 확인합니다.

    1. 모든 파드가 Running 상태인지 확인
    2. Readiness Probe가 통과했는지 확인
    3. HPA가 올바르게 연결됐는지 확인
    4. Ingress가 정상 응답하는지 확인
    5. 에러 로그가 없는지 확인

    Helm Chart 관리 전략 정리

    ▲ 프로덕션 Helm Chart 관리를 위한 핵심 베스트 프랙티스를 한눈에 정리한 요약 가이드입니다.

    항목 나쁜 예 좋은 예
    시크릿 관리 values.yaml에 패스워드 직접 기입 External Secrets 또는 helm-secrets 활용
    환경 분리 단일 values.yaml에 모든 환경 설정 환경별 values 파일 분리 + 오버라이드
    배포 전 검증 바로 helm upgrade 실행 helm diff로 변경 사항 먼저 확인
    롤백 준비 히스토리 관리 없이 배포 –history-max 설정 + –atomic 플래그
    가용성 보장 PDB 없이 운영 PodDisruptionBudget + HPA 설정
    차트 버전 version과 appVersion 혼용 SemVer 기반으로 명확히 분리
    중복 코드 각 템플릿에 라벨 직접 기입 _helpers.tpl로 공통 템플릿 관리

    마무리: Helm은 도구, 전략은 여러분 몫

    Helm Chart 베스트 프랙티스를 정리하다 보니 꽤 길어졌네요. 핵심만 다시 짚어드리면 이렇습니다.

    • ✅ 환경별 values 파일 분리는 선택이 아닌 필수
    • ✅ 시크릿은 절대 Chart에 직접 넣지 말 것
    • ✅ --atomic + --history-max로 안전망 확보
    • ✅ helm-diff로 배포 전 반드시 변경 사항 확인
    • ✅ PDB와 HPA는 프로덕션 환경에서 필수 설정
    • ✅ _helpers.tpl로 중복 템플릿 코드 제거

    사실 이 모든 게 처음부터 완벽하게 되지는 않아요. 저도 수많은 삽질을 거쳐서 지금의 방식에 안착했거든요. 중요한 건 조금씩 개선해나가는 거예요.

    다음 글에서는 Helm과 ArgoCD를 연동한 GitOps 배포 전략을 다뤄볼 예정입니다. Helm만으로는 아쉬운 부분들을 GitOps가 어떻게 채워주는지 실제 경험 기반으로 써볼게요. 기대해 주세요!

    궁금한 점이나 다른 경험 있으시면 댓글로 편하게 남겨주세요. 같이 고민해봐요. 🎉

  • [k8s] 쿠버네티스 Ingress Controller 비교: Nginx, Traefik, HAProxy 선택 가이드

    [k8s] 쿠버네티스 Ingress Controller 비교: Nginx, Traefik, HAProxy 선택 가이드

    쿠버네티스 Ingress Controller, 뭘 써야 할까요?

    쿠버네티스를 처음 공부할 때 저도 Ingress Controller 선택 앞에서 한참 멈췄던 기억이 나요. Nginx는 익숙하고, Traefik은 이름이 예쁘고, HAProxy는 오래됐으니 안정적일 것 같고… 근데 막상 뭘 골라야 할지 기준이 없으니까 그냥 남들 쓰는 거 따라갔었거든요.

    13년 동안 인프라 엔지니어로 일하면서 홈랩부터 실제 프로덕션 환경까지 세 가지 컨트롤러를 다 써봤습니다. 오늘은 그 경험을 바탕으로 Nginx Ingress, Traefik Ingress, HAProxy Ingress를 솔직하게 비교해 드릴게요. 어떤 상황에서 어떤 걸 골라야 하는지, 실제 겪었던 삽질 포인트까지 전부 공유해 드리겠습니다.

    팀에서 쿠버네티스 Ingress Controller를 선택해야 하는데 레퍼런스가 너무 많고 각자 장점만 얘기해서 오히려 더 헷갈리는 상황, 있으시죠? 이 글이 그 혼란을 정리해 드릴 거예요.

    쿠버네티스 Ingress Controller 전체 아키텍처 - Nginx, Traefik, HAProxy 트래픽 흐름 비교

    쿠버네티스 클러스터에서 외부 트래픽이 Ingress Controller를 통해 각 서비스로 라우팅되는 전체 흐름. Nginx, Traefik, HAProxy 세 가지 컨트롤러의 위치를 비교하여 보여줍니다.

    Ingress Controller가 뭔지 먼저 짚고 가요

    쉽게 말해서, Ingress(인그레스)는 클러스터 외부에서 내부 서비스로 들어오는 트래픽을 관리하는 쿠버네티스 오브젝트예요. 근데 Ingress 오브젝트 자체는 그냥 규칙 명세서일 뿐이고, 이걸 실제로 실행하는 게 바로 Ingress Controller(인그레스 컨트롤러)입니다.

    비유하자면 Ingress는 “3번 테이블 손님은 A 주방으로, 4번 테이블은 B 주방으로” 같은 안내판이고, Ingress Controller는 그 안내판을 읽고 실제로 손님을 안내하는 직원인 거죠. 이 직원 역할을 Nginx가 할 수도 있고, Traefik이나 HAProxy가 할 수도 있는 겁니다.

    • Ingress Resource: 라우팅 규칙을 정의하는 쿠버네티스 오브젝트
    • Ingress Controller: Ingress 규칙을 실제로 처리하는 프록시/로드밸런서 파드
    • 쿠버네티스는 기본으로 Ingress Controller를 제공하지 않아서 직접 설치해야 해요

    세 가지 Ingress Controller 핵심 특징 비교

    본격 비교 전에 각 컨트롤러의 DNA를 먼저 이해하면 선택이 훨씬 쉬워져요.

    Nginx Ingress Controller

    가장 널리 쓰이는 컨트롤러입니다. 사실 Nginx Ingress Controller에는 두 가지 버전이 있어요. 쿠버네티스 커뮤니티가 관리하는 ingress-nginx와 Nginx 사가 직접 관리하는 nginx-ingress. 보통 오픈소스 쪽에서 말하는 건 ingress-nginx 쪽이에요. 처음에 저도 이게 헷갈려서 잘못된 걸 설치했던 기억이 있습니다.

    • 레퍼런스가 가장 많고 커뮤니티가 활발해요
    • Nginx.conf 기반이라 기존 Nginx 경험자에게 친숙함
    • Annotation(어노테이션) 기반 세밀한 설정 가능
    • 설정 변경 시 nginx reload가 필요한 구조 (무중단 배포 시 주의)

    Traefik Ingress Controller

    클라우드 네이티브 시대에 맞게 설계된 현대적인 리버스 프록시예요. 처음 Traefik을 접했을 때 “이게 진짜 쿠버네티스랑 찰떡이구나” 싶었거든요. 서비스 디스커버리(Service Discovery)를 자동으로 처리해서 설정 파일을 거의 안 만져도 되는 게 매력이에요.

    • 자동 서비스 디스커버리로 설정 최소화
    • 내장 대시보드(Dashboard)로 트래픽 시각화 가능
    • Let’s Encrypt TLS 인증서 자동 발급/갱신 지원
    • 미들웨어(Middleware) 체인으로 요청 처리 파이프라인 구성
    • CRD(Custom Resource Definition) 기반 설정으로 쿠버네티스 네이티브한 느낌

    HAProxy Ingress Controller

    HAProxy는 원래 고성능 로드밸런서로 유명하죠. 금융권이나 대용량 트래픽 환경에서 오랫동안 검증된 친구입니다. 쿠버네티스 Ingress Controller로서의 HAProxy는 이 안정성과 성능을 그대로 가져왔어요.

    • 로드밸런싱 알고리즘 선택지가 풍부함
    • TCP/UDP 레이어 처리에 강점
    • 설정 변경 시 무중단 리로드(hitless reload) 지원
    • Nginx, Traefik 대비 국내 레퍼런스가 적은 편

    Ingress Controller 핵심 비교표

    항목 Nginx Ingress Traefik Ingress HAProxy Ingress
    설정 방식 Annotation + ConfigMap CRD + Annotation ConfigMap + Annotation
    자동 서비스 디스커버리 제한적 ✅ 강력 지원 제한적
    TLS 자동화 cert-manager 연동 필요 ✅ 내장 지원 cert-manager 연동 필요
    내장 모니터링 UI ❌ 없음 ✅ 대시보드 내장 HAProxy Stats 페이지
    무중단 설정 리로드 부분 지원 ✅ 지원 ✅ 지원
    학습 난이도 낮음 (친숙함) 중간 중간~높음
    커뮤니티/레퍼런스 매우 풍부 풍부 보통
    적합한 환경 범용, 소~대규모 클라우드 네이티브, 동적 환경 고성능, 금융/엔터프라이즈

    실전 설치 및 기본 설정 방법

    자, 이제 실제로 설치해 봅시다. 각 컨트롤러별로 가장 빠른 설치 방법을 보여드릴게요. 제가 홈랩에서 테스트할 때 쓰는 방식이에요.

    Helm을 이용한 Nginx, Traefik, HAProxy Ingress Controller 설치 및 배포 구성

    Helm을 이용한 Nginx, Traefik, HAProxy Ingress Controller 설치 과정과 각 컨트롤러의 파드 구성을 보여주는 다이어그램.

    1. Nginx Ingress Controller 설치

    Helm을 이용하는 게 제일 편합니다. ingress-nginx 공식 차트를 사용해요.

    # Helm 레포지토리 추가
    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
    helm repo update
    
    # 설치
    helm install ingress-nginx ingress-nginx/ingress-nginx \
      --namespace ingress-nginx \
      --create-namespace

    설치 후 기본 Ingress 리소스 예시입니다.

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: my-app-ingress
      annotations:
        kubernetes.io/ingress.class: "nginx"
        nginx.ingress.kubernetes.io/rewrite-target: /
    spec:
      rules:
      - host: myapp.example.com
        http:
          paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app-service
                port:
                  number: 80

    2. Traefik Ingress Controller 설치

    Traefik도 Helm으로 설치하는 게 가장 깔끔해요. 대시보드 활성화 옵션도 같이 넣어줄게요.

    # Helm 레포지토리 추가
    helm repo add traefik https://helm.traefik.io/traefik
    helm repo update
    
    # values 파일 생성 (대시보드 활성화)
    cat < traefik-values.yaml
    dashboard:
      enabled: true
    api:
      dashboard: true
    EOF
    
    # 설치
    helm install traefik traefik/traefik \
      --namespace traefik \
      --create-namespace \
      -f traefik-values.yaml

    Traefik에서는 IngressRoute라는 CRD를 사용하는 방식이 더 권장돼요.

    apiVersion: traefik.containo.us/v1alpha1
    kind: IngressRoute
    metadata:
      name: my-app-route
      namespace: default
    spec:
      entryPoints:
        - web
      routes:
        - match: Host(`myapp.example.com`)
          kind: Rule
          services:
            - name: my-app-service
              port: 80

    3. HAProxy Ingress Controller 설치

    # Helm 레포지토리 추가
    helm repo add haproxytech https://haproxytech.github.io/helm-charts
    helm repo update
    
    # 설치
    helm install haproxy-ingress haproxytech/kubernetes-ingress \
      --namespace haproxy-controller \
      --create-namespace
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: my-app-ingress
      annotations:
        kubernetes.io/ingress.class: "haproxy"
    spec:
      rules:
      - host: myapp.example.com
        http:
          paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: my-app-service
                port:
                  number: 80

    ⚠️ 실제로 겪었던 주의사항과 트러블슈팅

    이론은 여기까지 하고, 제가 실제로 삽질했던 포인트들 정리해 드릴게요. 이게 진짜 중요한 부분이에요.

    Nginx Ingress에서 자주 만나는 문제들

    ⚠️ 문제 1: Annotation 오타로 설정이 안 먹히는 경우

    Nginx Ingress는 Annotation에 오타가 있어도 에러를 안 뿜고 그냥 무시해버려요. 처음에 이걸 몰라서 한참 헤맸습니다. 설정이 안 먹힌다 싶으면 아래 명령어로 컨트롤러 로그를 꼭 확인하세요.

    kubectl logs -n ingress-nginx \
      $(kubectl get pods -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx -o jsonpath='{.items[0].metadata.name}')

    ⚠️ 문제 2: 413 Request Entity Too Large 에러

    파일 업로드 기능이 있는 서비스를 Nginx Ingress 뒤에 놓으면 자주 만나는 에러예요. Annotation으로 해결 가능합니다.

    annotations:
      nginx.ingress.kubernetes.io/proxy-body-size: "50m"

    Traefik에서 자주 만나는 문제들

    ⚠️ 문제 1: IngressRoute와 기본 Ingress 혼용 시 충돌

    Traefik은 기본 쿠버네티스 Ingress 오브젝트도 처리하고 자체 IngressRoute CRD도 처리해요. 근데 팀 내에서 두 가지 방식을 섞어 쓰면 나중에 관리가 진짜 복잡해집니다. 처음부터 방식을 통일하는 걸 강력 추천해요.

    ⚠️ 문제 2: 대시보드 외부 노출 시 인증 필수

    Traefik 대시보드를 아무 인증 없이 외부에 노출하면 큰일 납니다. BasicAuth 미들웨어라도 꼭 붙여주세요.

    apiVersion: traefik.containo.us/v1alpha1
    kind: Middleware
    metadata:
      name: dashboard-auth
      namespace: traefik
    spec:
      basicAuth:
        secret: traefik-dashboard-auth-secret

    HAProxy Ingress에서 자주 만나는 문제들

    ⚠️ 문제 1: ConfigMap 설정 반영 지연

    HAProxy Ingress는 ConfigMap을 통한 글로벌 설정 변경이 즉시 반영되지 않는 경우가 있어요. 설정 변경 후 컨트롤러 파드를 재시작해줘야 하는 상황이 생길 수 있습니다.

    kubectl rollout restart deployment haproxy-ingress -n haproxy-controller

    어떤 상황에서 뭘 골라야 할까요?

    제가 내린 결론을 솔직하게 말씀드릴게요. 완벽한 정답은 없지만, 상황별 추천은 꽤 명확해요.

    Nginx Traefik HAProxy Ingress Controller 성능 및 기능 비교 대시보드

    Nginx, Traefik, HAProxy Ingress Controller의 주요 지표(성능, 설정 편의성, 생태계, 모니터링)를 레이더 차트로 비교한 시각화.

    ✅ Nginx Ingress를 선택하세요, 만약…

    • 팀원들이 Nginx에 익숙한 경우
    • 레퍼런스와 커뮤니티 지원이 중요한 경우
    • 처음 쿠버네티스를 도입하는 팀
    • 범용적인 웹 트래픽 처리가 주 목적인 경우

    ✅ Traefik Ingress를 선택하세요, 만약…

    • 마이크로서비스가 자주 추가/삭제되는 동적인 환경
    • TLS 인증서 관리를 자동화하고 싶은 경우
    • 별도 모니터링 설정 없이 트래픽을 시각화하고 싶은 경우
    • 클라우드 네이티브 환경에서 GitOps 방식으로 운영하는 경우

    ✅ HAProxy Ingress를 선택하세요, 만약…

    • 기존에 HAProxy를 잘 알고 있는 팀
    • L4(TCP/UDP) 레벨의 세밀한 로드밸런싱이 필요한 경우
    • 금융, 통신 등 고성능/고가용성이 핵심인 환경
    • 엄격한 엔터프라이즈 지원이 필요한 경우

    자주 묻는 질문 (FAQ)

    Q. 클러스터에 Ingress Controller를 여러 개 동시에 설치할 수 있나요?

    네, 가능합니다. IngressClass 리소스를 이용해서 각 Ingress 오브젝트가 어떤 컨트롤러를 사용할지 지정할 수 있어요. 다만 운영 복잡도가 올라가니까 특별한 이유가 없다면 하나만 쓰는 걸 추천합니다.

    Q. 쿠버네티스 Ingress Controller와 서비스 메시는 다른 건가요?

    다릅니다. Ingress Controller는 클러스터 외부에서 내부로 들어오는 북-남(North-South) 트래픽을 처리하고, Istio 같은 서비스 메시는 클러스터 내부 서비스 간의 동-서(East-West) 트래픽을 관리해요. 보통 두 가지를 같이 쓰기도 합니다.

    Q. Traefik v2와 v3는 많이 다른가요?

    Traefik v3에서 일부 API와 설정 방식이 변경됐어요. 특히 일부 CRD API 버전이 바뀌었으니 마이그레이션 시 공식 문서를 꼭 확인하세요. 신규 설치라면 최신 버전을 쓰는 게 좋습니다.

    마무리 — 결국 팀의 상황이 답이에요

    쿠버네티스 Ingress Controller 선택 가이드 - Nginx Traefik HAProxy 상황별 추천 요약

    Nginx, Traefik, HAProxy Ingress Controller의 특징과 적합한 사용 환경을 한눈에 정리한 요약 인포그래픽.

    오늘 세 가지 쿠버네티스 Ingress Controller를 비교해 봤는데요. 제 개인적인 결론을 한 줄로 정리하면 이래요.

    “처음이라면 Nginx, 클라우드 네이티브 환경이라면 Traefik, 고성능/엔터프라이즈라면 HAProxy.”

    저는 홈랩에서는 Traefik을 주로 써요. 대시보드가 있어서 트래픽 흐름 보기 편하고, TLS 자동화가 정말 편리하거든요. 근데 실무에서 처음 쿠버네티스를 도입하는 팀이라면 역시 Nginx가 제일 무난합니다. 레퍼런스가 많아서 문제 생겼을 때 해결하기 수월하니까요.

    💡 팁 하나 더! 어떤 Ingress Controller를 선택하든 cert-manager와 함께 쓰면 TLS 인증서 관리가 훨씬 수월해집니다. cert-manager 설정 방법은 다음 글에서 자세히 다룰 예정이에요.

    궁금한 점이나 다른 삽질 경험이 있으시면 댓글로 공유해 주세요. 같이 고민해 봅시다! 🎉