홈 k3s 클러스터 구축기 (6) — Longhorn 분산 스토리지

환경: k3s v1.31+, Longhorn v1.8.1, ArgoCD v3.3+, Ubuntu Server 24.04 LTS

들어가며

4편에서 Bitnami Helm 차트로 Redis를 배포할 때, storageClassName을 별도로 지정하지 않았습니다. k3s의 기본 StorageClass인 local-path가 자동으로 사용되었고, PVC는 특정 노드의 로컬 디스크에 바인딩되었습니다. Redis처럼 자체 복제를 지원하고 데이터 유실이 허용되는 캐시 워크로드라면 이것으로 충분하지만, 모든 워크로드가 그렇지는 않습니다.

local-path로 생성된 PVC는 해당 노드의 디스크에 직접 연결되므로, Pod도 그 노드에서만 스케줄링됩니다. 노드가 장애를 겪으면 디스크에 접근할 수 없고, Pod은 다른 노드에서 재시작되더라도 데이터에는 도달하지 못합니다. 데이터베이스처럼 유실이 허용되지 않는 워크로드에서는 이 구조가 치명적입니다.

이 문제를 해결하려면 스토리지 레이어를 특정 노드에서 분리해야 합니다. 여러 노드의 디스크를 하나의 풀로 묶고, 데이터를 복제본으로 분산 저장하면 노드 한 대가 죽어도 나머지 노드에서 데이터를 제공할 수 있습니다. 이것이 분산 스토리지이며, 이 편에서는 그중 가장 가벼운 솔루션인 Longhorn을 ArgoCD로 배포하고, 데이터베이스 워크로드에 적용하는 방법을 다룹니다.

분산 스토리지의 구조

분산 스토리지는 CSI(Container Storage Interface) 기반으로 동작합니다. 각 노드에 에이전트(DaemonSet)가 실행되면서 로컬 디스크의 일부를 스토리지 풀에 기여하고, PVC가 생성되면 풀에서 볼륨을 할당하는 방식입니다.

Pod 입장에서는 달라지는 것이 없습니다. 동일하게 PVC를 만들고 마운트해서 사용할 뿐, 볼륨이 로컬 디스크에 있는지 네트워크 분산 스토리지에 있는지 알지 못합니다. 바뀌는 건 PVC 아래쪽, 즉 StorageClass가 가리키는 provisioner입니다. local-path는 노드의 디스크에 직접 볼륨을 만들고, 분산 스토리지(Longhorn 등)는 네트워크 스토리지 엔진을 경유하여 여러 노드에 복제본을 분산 저장합니다.

StorageClass

StorageClass는 볼륨을 어떻게 프로비저닝할지 정의하는 템플릿입니다. PVC가 용량을 요청하면, StorageClass가 어떤 provisioner를 써서 어떤 설정으로 볼륨을 만들지 결정합니다.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: longhorn-replicated
provisioner: driver.longhorn.io
reclaimPolicy: Retain
volumeBindingMode: Immediate
parameters:
  numberOfReplicas: "3"
  staleReplicaTimeout: "2880"

StorageClass는 여러 개를 만들어두고 용도별로 나눠 쓸 수 있습니다. 하나를 default로 지정하면, PVC에서 storageClassName을 생략했을 때 자동으로 사용됩니다. 현재 클러스터의 구성은 다음과 같습니다.

스토리지 유형

분산 스토리지를 이해하려면, 스토리지가 어떤 레벨에서 동작하는지를 먼저 파악해야 합니다.

Kubernetes에서 사용하는 스토리지는 크게 세 유형으로 나뉩니다.

세 유형 모두 분산 스토리지 위에서 동작하면 여러 노드의 디스크를 풀링하여 사용할 수 있습니다. Longhorn은 이 중 블록 스토리지를 중심으로 제공하며, RWX가 필요한 경우에는 NFS를 경유하는 방식으로 지원합니다.

AccessMode와 복제본

AccessMode

PVC를 생성할 때 지정하는 AccessMode는 볼륨에 동시에 접근할 수 있는 노드 수를 제한하는 설정입니다. 데이터가 어디에 저장되는지와는 별개의 개념이므로, 분산 스토리지와 혼동하지 않아야 합니다.

RWO 볼륨이라 해도 분산 스토리지를 사용하면 데이터 복제본은 여러 노드에 분산 저장되어 있습니다. "하나의 노드에서만"은 마운트에 대한 제약이지 저장 위치에 대한 제약이 아닙니다. 따라서 노드 장애가 발생하면 다른 노드에서 Pod이 재시작되고, 동일한 볼륨에 재연결되어 서비스를 계속할 수 있습니다.

복제본

복제본(Replica)은 노드 장애 시 데이터를 보호하기 위해 존재합니다. 복제본이 1개이면 해당 노드가 죽었을 때 데이터가 유실되고, 3개이면 서로 다른 노드 3곳에 동일한 데이터가 저장되어 노드 하나가 죽어도 서비스가 지속됩니다. 쓰기가 발생하면 모든 복제본에 동시에 기록하고, 읽기는 하나의 복제본에서 수행합니다. 노드가 복구되면 자동으로 복제본을 재동기화합니다.

Longhorn vs Ceph

Kubernetes에서 분산 스토리지로 가장 많이 언급되는 두 선택지는 Longhorn과 Ceph(Rook-Ceph)입니다.

블록 스토리지만 필요하고 운영 부담을 최소화하고 싶다면 Longhorn이 적합합니다. 특히 홈 클러스터처럼 노드가 2~3대이고 자원이 제한된 환경에서는, Ceph의 무거운 컴포넌트 구성이 부담이 됩니다. 오브젝트 스토리지(S3 호환)나 네이티브 RWX 파일시스템이 필요해지는 시점에 Ceph 도입을 고려하면 됩니다.

Longhorn 배포

3편에서 구축한 ArgoCD App-of-Apps 패턴으로 Longhorn을 배포합니다. Longhorn은 Helm 차트로 제공되므로, 4편의 Redis와 동일하게 multi-source로 공식 차트와 커스텀 values.yaml을 조합합니다.

# 각 노드에서 실행
kubectl debug node/<노드명> -it --image=ubuntu -- chroot /host bash
 
apt update
apt install open-iscsi nfs-common -y
systemctl enable iscsid --now
exit

# longhorn/values.yaml
defaultSettings:
  defaultDataPath: /var/lib/longhorn       # 각 노드에서 스토리지로 사용할 경로
  defaultReplicaCount: 2                   # 볼륨당 복제본 수 (노드 수에 맞게 설정)
  storageMinimalAvailablePercentage: 15    # 노드 디스크 최소 여유 비율
  storageOverProvisioningPercentage: 200   # 오버프로비저닝 허용 비율
 
persistence:
  defaultClassReplicaCount: 2              # StorageClass 기본 복제본 수
  defaultClass: false                      # local-path를 기본으로 유지
 
longhornUI:
  enabled: true                            # 웹 UI 활성화
 
preUpgradeChecker:
  jobEnabled: false                        # ArgoCD 호환: pre-upgrade hook 비활성화

# argocd/longhorn-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: longhorn
  namespace: argocd
spec:
  project: default
  sources:
    - repoURL: https://charts.longhorn.io
      chart: longhorn
      targetRevision: 1.8.1
      helm:
        valueFiles:
          - $values/longhorn/values.yaml
    - repoURL: https://github.com/mirunamu00/helm-chart.git
      targetRevision: master
      ref: values
  destination:
    server: https://kubernetes.default.svc
    namespace: longhorn-system
  ignoreDifferences:
    - group: apiextensions.k8s.io
      kind: CustomResourceDefinition
      jsonPointers:
        - /metadata/annotations
        - /spec/conversion
        - /spec/preserveUnknownFields
        - /status
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true
      - RespectIgnoreDifferences=true

git add longhorn/ argocd/longhorn-app.yaml
git commit -m "feat: add Longhorn distributed storage"
git push

# ArgoCD 앱 상태
kubectl get app longhorn -n argocd
 
# Pod 상태 (모두 Running이면 정상)
kubectl get pods -n longhorn-system
 
# StorageClass 생성 확인
kubectl get storageclass

Longhorn 볼륨 활용

Longhorn이 배포되었으니, 실제 워크로드에 활용할 차례입니다. 4편에서 배포한 Redis는 캐시 용도이므로 local-path로 충분합니다. Redis는 master-replica 간 애플리케이션 레벨 복제를 자체적으로 수행하고, 캐시 데이터는 유실되더라도 원본에서 다시 채워지기 때문입니다.

하지만 데이터베이스는 사정이 다릅니다. 저장된 데이터가 파생물이 아니라 원본 그 자체이므로, 노드 장애로 인한 유실은 곧 서비스 장애를 의미합니다. 이런 워크로드에 Longhorn이 필요합니다. PostgreSQL을 Bitnami Helm 차트로 배포한다면, values.yaml에서 storageClass를 longhorn으로 지정하는 것만으로 분산 스토리지 위에서 동작하게 됩니다.

# postgresql/values.yaml
primary:
  persistence:
    storageClass: longhorn
    size: 5Gi
 
readReplicas:
  replicaCount: 1
  persistence:
    storageClass: longhorn
    size: 5Gi

이렇게 설정하면 PVC가 Longhorn provisioner를 통해 생성되며, 볼륨 데이터가 설정된 복제본 수만큼 여러 노드에 분산 저장됩니다. primary가 위치한 노드에 장애가 발생하더라도, Pod이 다른 노드에서 재시작되면 동일한 볼륨에 재연결되어 데이터를 그대로 사용할 수 있습니다. local-path였다면 PVC가 특정 노드에 묶여 있어 Pod 재스케줄링 자체가 불가능했을 상황입니다.

ArgoCD Application은 4편의 Redis와 동일한 multi-source 패턴을 사용하면 됩니다. 차트 소스를 Bitnami의 postgresql로, values 파일 경로만 변경하면 동일한 구조로 배포할 수 있습니다.

트러블슈팅

정리

다음 편에서는 Prometheus와 Grafana를 배포하여, 클러스터와 워크로드의 상태를 실시간으로 모니터링할 수 있는 환경을 구축합니다.

참고 자료

• Longhorn 공식 문서
• Longhorn ArgoCD 설치 가이드
• Kubernetes StorageClass 공식 문서
• Kubernetes Persistent Volumes
• Rook-Ceph 공식 문서