외부 Ceph 클러스터를 Kubernetes 기본 StorageClass로 재사용하기 (ceph-csi로 CephFS/RBD 연동)

결론 요약

• 이미 운영 중인 “외부 Ceph 클러스터”를 Kubernetes의 기본(StorageClass) 스토리지로 그대로 재사용할 수 있습니다.
• Kubernetes 쪽에는 **ceph-csi(=K8s 표준 CSI 드라이버)**만 설치하고,
  (1) Ceph 모니터(mon) 주소, (2) Ceph 인증(Secret), (3) StorageClass만 맞추면
  이후에는 PVC 만들면 PV가 자동 생성/연결됩니다.
• 선택지는 2가지:
  • CephFS(파일 스토리지): ReadWriteMany(RWX) 가능 → 여러 Pod가 공유 폴더처럼 같이 씀
  • RBD(블록 스토리지): 보통 성능 좋음, 대신 ReadWriteOnce(RWO) 중심 → 한 Pod(노드) 단독 디스크처럼 씀

---

쉬운 비유

• CephFS = “네트워크 공유폴더(NAS)”
  여러 사람이 동시에 같은 폴더를 열어 파일을 같이 쓰는 느낌(RWX).
• RBD = “컴퓨터에 꽂는 외장 SSD(디스크)”
  한 컴퓨터가 디스크를 붙여서 쓰는 느낌(대체로 RWO).

---

구성/동작 설명

Kubernetes에서 Ceph를 StorageClass로 쓰는 흐름은 항상 이 순서입니다.

1. ceph-csi 설치(드라이버 설치)
   K8s가 Ceph를 “동적 프로비저닝”으로 만들 수 있게 함
2. csiConfig(모니터 주소/클러스터 ID 설정)
   ceph-csi가 접속할 Ceph mon 목록 지정
3. Secret(cephx 계정 정보)
   admin 같은 user의 key를 K8s Secret에 저장
4. StorageClass(어떤 방식으로 볼륨 만들지 정의)
   • CephFS면 fsName, pool 등
   • RBD면 pool, imageFeatures, fstype 등
5. PVC 생성 → PV 자동 생성/바인딩 → Pod에서 마운트

---

실전 단계(복붙용) — CephFS 버전 (RWX)

0) 준비 체크

• K8s 모든 노드에서 Ceph mon으로 네트워크 통신 가능해야 합니다.
• Ceph에 CephFS가 이미 구성되어 있고, 사용할 fsName, pool을 알아야 합니다.
• 사용할 계정(admin 등)의 key를 확보합니다.

---

1) Helm repo 추가 + 네임스페이스 생성

helm repo add ceph-csi https://ceph.github.io/csi-charts
helm repo update

kubectl create namespace ceph-fs

---

2) values.yaml 핵심(초보자 관점에서 “필수 3종 세트”)

아래 3개만 정확하면 됩니다.

(1) csiConfig: mon 목록 + clusterID

csiConfig:
  - clusterID: "test-cephfs"
    monitors:
      - "192.168.0.138:6789"
      - "192.168.0.140:6789"
      - "192.168.0.141:6789"

(2) secret: ceph 계정

secret:
  create: true
  name: "ceph-fs-secret"
  adminID: "admin"
  adminKey: "여기에_키_값"

(3) storageClass: CephFS용 StorageClass

storageClass:
  create: true
  name: ceph-fs-sc
  annotations:
    storageclass.beta.kubernetes.io/is-default-class: "true"
  clusterID: "test-cephfs"
  fsName: "chunvol1"
  pool: "cephfs.chunvol1.data"
  provisionerSecret: ceph-fs-secret
  provisionerSecretNamespace: ceph-fs
  controllerExpandSecret: ceph-fs-secret
  controllerExpandSecretNamespace: ceph-fs
  nodeStageSecret: ceph-fs-secret
  nodeStageSecretNamespace: ceph-fs
  reclaimPolicy: Delete
  allowVolumeExpansion: true
  mountOptions:
    - discard

포인트

• clusterID는 csiConfig와 storageClass가 반드시 동일해야 합니다.
• fsName, pool은 Ceph에 실제 존재하는 값이어야 합니다.
• is-default-class: "true"는 “PVC에서 storageClassName을 안 적으면 이걸 기본으로 쓰겠다”는 뜻입니다. (기본은 1개만!)

---

3) CephFS ceph-csi 설치

helm install -n ceph-fs ceph-fs-driver ceph-csi/ceph-csi-cephfs -f values.yaml
kubectl get pods -n ceph-fs
kubectl get sc

---

4) PVC 생성 (RWX)

원문 예시에서 storageClassName: csi-fs-sc처럼 이름이 섞여 있는데, StorageClass 이름과 동일하게 맞추세요.

# cephfs-pvc01.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: cephfs-pvc01
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: ceph-fs-sc

kubectl apply -f cephfs-pvc01.yaml
kubectl get pvc

---

5) Pod에 마운트

# cephfs-pod01.yaml
apiVersion: v1
kind: Pod
metadata:
  name: csi-cephfs-test-pod
spec:
  containers:
    - name: web
      image: nginx
      volumeMounts:
        - name: vol
          mountPath: /data
  volumes:
    - name: vol
      persistentVolumeClaim:
        claimName: cephfs-pvc01
        readOnly: false

kubectl apply -f cephfs-pod01.yaml
kubectl exec -ti csi-cephfs-test-pod -- df -h

---

실전 단계 — RBD 버전 (RWO)

RBD는 보통 설정을 분리해서(csiConfig / secret / storageclass) 적용해도 됩니다.

1) 네임스페이스 + 드라이버 설치

kubectl create namespace ceph-rbd

helm install -n ceph-rbd ceph-rbd-driver ceph-csi/ceph-csi-rbd -f csiconfig.yaml
kubectl get pods -n ceph-rbd

csiconfig.yaml:

csiConfig:
  - clusterID: "test-ceph-rbd"
    monitors:
      - "192.168.0.138:6789"
      - "192.168.0.140:6789"
      - "192.168.0.141:6789"

---

2) Secret 생성

# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: ceph-rbd-secret
  namespace: ceph-rbd
stringData:
  userID: admin
  userKey: "여기에_키_값"

kubectl apply -f secret.yaml

---

3) StorageClass 생성 (RBD)

# storageclass.yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: rbd
  annotations:
    storageclass.beta.kubernetes.io/is-default-class: "true"
provisioner: rbd.csi.ceph.com
parameters:
  clusterID: "test-ceph-rbd"
  pool: "rbdvol1"
  imageFeatures: layering
  csi.storage.k8s.io/fstype: ext4

  csi.storage.k8s.io/provisioner-secret-name: ceph-rbd-secret
  csi.storage.k8s.io/provisioner-secret-namespace: ceph-rbd
  csi.storage.k8s.io/controller-expand-secret-name: ceph-rbd-secret
  csi.storage.k8s.io/controller-expand-secret-namespace: ceph-rbd
  csi.storage.k8s.io/node-stage-secret-name: ceph-rbd-secret
  csi.storage.k8s.io/node-stage-secret-namespace: ceph-rbd
reclaimPolicy: Delete
allowVolumeExpansion: true
mountOptions:
  - discard

kubectl apply -f storageclass.yaml
kubectl get sc

포인트

• clusterID(csiConfig) ↔ clusterID(StorageClass) 일치 필수
• pool은 Ceph에서 RBD pool로 초기화되어 있어야 합니다.
• Secret 이름/namespace 하나라도 틀리면 StorageClass는 만들어져도 PVC가 실패하는 경우가 많습니다.

---

4) PVC 생성 (RWO)

# rbd-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: rbd-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: rbd

kubectl apply -f rbd-pvc.yaml
kubectl get pvc

---

5) Pod 연결

# rbd-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: rbd-test-pod01
spec:
  containers:
    - name: web
      image: nginx
      volumeMounts:
        - name: rbd1
          mountPath: /data
  volumes:
    - name: rbd1
      persistentVolumeClaim:
        claimName: rbd-pvc

kubectl apply -f rbd-pod.yaml
kubectl exec -ti rbd-test-pod01 -- df -h

---

대안/옵션 (초보자가 자주 고민하는 것)

• StorageClass를 “기본”으로 만들지 말고, PVC마다 storageClassName을 명시하는 방식도 안전합니다.
  (운영 환경에서 “기본 클래스가 바뀌어 사고” 나는 걸 막기 쉬움)
• Ceph 권한을 admin으로 쓰는 대신, 전용 user를 만들어 최소 권한으로 운영하는 게 일반적으로 더 안전합니다(운영 보안 관점).

---

체크리스트 (여기서 많이 막힘)

• kubectl get pods -n ceph-fs/ceph-rbd에서 ceph-csi Pod들이 정상 Running?
• clusterID가 csiConfig와 StorageClass에서 완전히 동일?
• mon 주소/포트가 K8s 노드에서 접근 가능?
• Secret의 userID/userKey 값이 정확?
• (CephFS) fsName, pool이 Ceph에 실제 존재?
• (RBD) pool이 RBD 용도로 준비된 pool?
• PVC가 Pending이면 kubectl describe pvc <name> 이벤트에서 어떤 에러가 뜨는지 확인했나?

---

핵심 정리

• CephFS = 공유 스토리지(RWX), RBD = 단일 디스크(RWO)
• ceph-csi 구성의 핵심은 딱 3가지: mon 목록(csiConfig) + Secret + StorageClass
• StorageClass는 “생성” 자체는 잘 되지만, 값이 틀리면 PVC 단계에서 실패가 많이 납니다.