Rook-Ceph 해설 2: Rook operator 가 해 주는 일과 하지 않는 일

상태: 초안 (2026-10-29), 소스와 공식 문서 기준, 실측 없음. 기준 판은 Rook v1.21.1(태그가 가리키는 커밋 09d2f0d8d883b70b30de796c4390371be725ff3b, 2026-10-26 릴리스)과, Rook 차트가 하위 차트로 넣는 ceph-csi-operator v1.1.0 (커밋 98eee8980fc69e5c9c02c80958abe06c3faba5eb)입니다. 글의 소스 링크는 모두 이 커밋에 고정했습니다. TT Lab 실습 클러스터에서 operator 가 만든 자원을 직접 세어 보는 일은 4편(원자료가 모이면 씁니다)에서 합니다. 작성 규칙: 실측 데이터가 기본이고, 못 잰 것은 「미실측」, 원문에서 찾지 못한 것은 「미확인」으로 표시합니다.

목차

• 1. operator 와 Rook 의 자리
• 2. CRD 목록과 reconcile 이 만드는 것
• 3. mon 의 배치와 failover
• 4. OSD prepare Job 이 디스크를 고르는 방식
• 5. CSI 배포: v1.21 에서는 셋이 나눠 맡는다
• 6. 업그레이드 순서
• 7. 클러스터 정리: cleanupPolicy
• 8. toolbox
• 9. operator 가 하지 않는 일
• 참고

1. operator 와 Rook 의 자리

쿠버네티스의 operator 는 사람이 하던 운영 지식을 컨트롤러로 옮긴 프로그램입니다. 사용자가 「이런 상태였으면 좋겠다」 를 사용자 정의 자원(CR, Custom Resource)으로 적어 두면, operator 가 지금 상태와 비교해 모자란 것을 만들고 넘치는 것을 지웁니다. 이 비교와 맞추기를 한 번 도는 것을 reconcile 이라 합니다.

Rook 의 공식 문서(Storage Architecture)는 Rook 의 일을 세 층으로 나눕니다. Ceph 설정을 자동화하는 Rook operator, 볼륨을 만들고 붙이는 Ceph-CSI 드라이버, 그리고 실제 저장을 하는 Ceph 데몬입니다. 같은 문서에 가장 중요한 한 줄이 있습니다. 「Rook is not in the Ceph data path.」 앱의 읽기·쓰기는 1편에서 본 대로 앱과 OSD 사이를 직접 오가고, operator 는 그 길에 서지 않습니다. 그러니 operator 파드가 잠시 멈춰도 이미 붙은 볼륨의 I/O 가 operator 를 거치지는 않습니다. operator 가 멈추면 늦어지는 것은 새 OSD, mon 교체처럼 operator 가 맡은 「바꾸는 일」 입니다.

2. CRD 목록과 reconcile 이 만드는 것

v1.21.1 의 deploy/examples/crds.yaml에는 CRD(CR 의 종류를 정의하는 스키마)가 21종 있습니다.

CephBlockPool, CephBlockPoolRadosNamespace, CephBucketNotification, CephBucketTopic, CephCOSIDriver, CephClient, CephCluster, CephFilesystem, CephFilesystemMirror, CephFilesystemSubVolumeGroup, CephNFS, CephNVMeOFGateway, CephObjectRealm, CephObjectStore, CephObjectStoreAccount, CephObjectStoreUser, CephObjectZone, CephObjectZoneGroup, CephRBDMirror, ObjectBucket, ObjectBucketClaim

자주 쓰는 것들이 reconcile 에서 만드는 것을 Ceph 안쪽과 쿠버네티스 쪽으로 나누면 이렇습니다.

나머지는 쓰임새만 짧게 적습니다. CephNFS(NFS 게이트웨이), CephRBDMirror·CephFilesystemMirror(다른 클러스터로 미러링), CephObjectRealm·ZoneGroup·Zone(RGW 멀티사이트), CephBucketTopic·Notification(버킷 이벤트 알림), CephCOSIDriver(COSI 드라이버), CephNVMeOFGateway(NVMe over Fabrics 게이트웨이), CephObjectStoreAccount(RGW 계정)입니다.

CephCluster 의 reconcile 은 순서가 정해져 있습니다. cluster.go 의 reconcileCephDaemons를 따라가면 설정 덮어쓰기 ConfigMap 을 만들고, mon 을 띄우고(L121), 클러스터 정체성이 생겼는지 확인하고, mgr 을 띄우고(L149), OSD 를 띄웁니다(L164). MDS 와 RGW 는 이 함수에 없습니다. 각각 CephFilesystem 과 CephObjectStore 를 맡는 별도 컨트롤러가 reconcile 합니다.

3. mon 의 배치와 failover

1편에서 본 대로 MON 은 과반이 살아 있어야 클러스터가 움직입니다. 그래서 Rook 이 가장 공들여 지키는 것이 mon 입니다. Rook 문서 Monitor Health와 소스를 함께 읽으면 이렇습니다.

정체성은 Service 의 IP 입니다. Ceph 에서 mon 의 정체성은 IP 주소이고 바뀌면 안 됩니다. 파드 IP 는 다시 뜰 때마다 바뀌므로, Rook 은 mon 마다 쿠버네티스 Service 를 하나씩 만들고 그 ClusterIP 를 고정된 정체성으로 씁니다.

데이터는 노드에 묶입니다. mon 의 메타데이터는 CephCluster 의 dataDirHostPath(기본 /var/lib/rook) 아래 호스트 디스크나 volumeClaimTemplate 으로 만든 볼륨에 저장됩니다. 그래서 mon 파드는 다시 뜰 때 같은 노드로 돌아가야 하고, 그 덕분에 기존 데이터로 이어서 시작할 수 있습니다.

배치는 canary 로 정합니다. 새 mon 을 어느 노드에 둘지 정할 때 Rook 은 먼저 이름 끝에 -canary 를 붙인 시험용 Deployment 를 띄워 쿠버네티스 스케줄러가 노드를 고르게 하고, 그 결과를 mon 의 자리로 씁니다 (scheduleMonitor, mon.go#L731-L740). allowMultiplePerNode: false 이면 mon 끼리 같은 노드에 서지 않게 하는 anti-affinity 가 필수 규칙으로 들어가고, true 이면 가중치 50 의 선호 규칙이 됩니다(3편에서 볼 클러스터 차트 values 의 주석).

검사는 45초마다, 교체는 10분 뒤입니다.

health.go에 두 상수가 있습니다. HealthCheckInterval = 45 * time.Second 와 MonOutTimeout = 10 * time.Minute 입니다. 흐름은 이렇습니다.

1. 45초마다 Ceph 에 쿼럼 상태를 묻습니다.
2. 쿼럼에 없는 mon 을 처음 보면 그 시각을 적어 둡니다. 그사이 쿠버네티스는 Deployment 로 그 파드를 다시 띄우려 애씁니다. 문서는 「새 mon 으로 바꾸는 것보다 기존 mon 을 살리는 쪽이 언제나 낫다」 고 적습니다.
3. 10분이 지나도 돌아오지 않으면 새 이름(지금까지의 가장 큰 번호 다음, 예를 들어 mon-a·b·c 였다면 mon-d)으로 새 mon 을 세웁니다. 옛 mon 의 Deployment 는 0으로 줄여 두고(호스트 네트워크를 쓰는 mon 은 새 mon 이 같은 호스트 IP 로 뜨지 않게 하려고 줄이지 않습니다), 새 mon 이 실패하면 되돌립니다 (failoverMon, health.go#L742).
4. 한 번의 검사에서 바꾸는 mon 은 하나뿐입니다(health.go#L331).

예외가 셋 있습니다(health.go#L286-L323).

• 타임아웃 0: failover 를 하지 않습니다. 문서는 계획된 정비 때 쓸모가 있다고 적습니다.
• mon 이 있던 노드가 지워졌으면 10분을 기다리지 않고 바로 옮깁니다(shouldFailoverMonImmediately).
• 타임아웃이 지났는데 mon 파드가 노드에 배치조차 안 된 상태면(예: 노드 드레인) 한 번 더 타임아웃만큼 기다립니다. 문서 표현으로 「기다리는 시간이 두 배가 된다」 입니다.

두 값은 CephCluster 의 healthCheck.daemonHealth.mon.interval·timeout 으로 바꿀 수 있습니다. operator 의 환경 변수 ROOK_MON_OUT_TIMEOUT·ROOK_MON_HEALTHCHECK_INTERVAL 이 있으면 그쪽이 먼저입니다(예전 동작과의 호환, health.go#L58-L103). 문서는 간격이 너무 짧으면 mon 을 지나치게 자주 갈아 치우고, 너무 길면 새 mon 이 서기 전에 다른 mon 이 죽어 쿼럼을 잃을 위험이 있다고 경고합니다.

mon 이 바뀌면 주소도 바뀝니다. Rook 은 mon 을 띄운 뒤마다 CSI 쪽에 mon 주소를 다시 알립니다(5절의 CephConnection, mon.go#L1261-L1269).

4. OSD prepare Job 이 디스크를 고르는 방식

OSD 는 「디스크를 찾고, 준비하고, 데몬을 띄우는」 두 단계로 만들어집니다. 앞 단계는 노드마다 하나씩 도는 Job 이 하고, 뒤 단계는 operator 가 합니다. 이름은 osd.go#L64-L69에 정해져 있습니다. Job 은 rook-ceph-osd-prepare-<노드>, OSD 데몬은 rook-ceph-osd-<번호> 입니다.

prepare Job 안에서 일어나는 일을 소스 순서대로 따라가면 이렇습니다.

1. 장치 목록. lsblk 로 노드의 블록 장치를 찾습니다. 이때 rbd·nbd·drbd·zram 장치는 아예 목록에서 뺍니다. 앞의 셋은 네트워크 저장소라 읽기가 멈출 수 있고, zram 은 휘발성 메모리이기 때문입니다 (disk.go#L37-L39, v1.21.1 의 변경 사항).
2. 이미 쓰이는 장치 거르기(getAvailableDevices, daemon.go#L347-L410). 마운트된 장치, 파일시스템 서명이 있는 장치, 이미 BlueStore OSD 가 들어 있는 장치를 건너뜁니다.
3. ceph-volume 에 묻기. 남은 장치마다 ceph-volume inventory --format json <장치> 를 돌려 「쓸 수 있다」 고 답하는 것만 남깁니다. 거절 이유는 그대로 로그에 찍힙니다(device.go#L399-L428).
4. 사용자 설정과 맞추기. useAllDevices: true 면 남은 장치를 모두 쓰되 LVM 논리 볼륨과 loop 장치는 고르지 않습니다. deviceFilter (장치 이름 정규식), devicePathFilter, 노드별 devices 목록이 있으면 거기에 맞는 것만 씁니다.
5. 준비. 기본은 ceph-volume raw prepare 입니다. 암호화를 켜거나, 장치 하나에 OSD 를 여럿 두거나(osdsPerDevice 2 이상), 메타데이터 장치를 따로 두면 raw 모드를 쓸 수 없어서 ceph-volume lvm batch 로 갑니다 (allowRawMode, volume.go#L497-L525).
6. 결과 보고. 만든 OSD 목록을 ConfigMap rook-ceph-osd-<노드>-status 에 적습니다 (status.go#L47). operator 가 이것을 읽고 OSD 마다 Deployment 를 만듭니다.

공식 문서의 요건(Prerequisites)도 같은 말을 합니다. OSD 로 쓸 수 있는 것은 파티션도 파일시스템도 없는 raw 장치, 파일시스템이 없는 raw 파티션, 파일시스템이 없는 LVM 논리 볼륨, 그리고 block 모드 PV 입니다. 그러니 「디스크를 새로 붙였는데 OSD 가 안 생긴다」 면 먼저 lsblk -f 로 파일시스템 서명이 남아 있지 않은지 봅니다. 거꾸로, 아무 서명도 없는 빈 디스크는 useAllDevices: true 에서 묻지도 않고 OSD 가 됩니다. 3편에서 이 기본값을 경고하는 이유입니다.

prepare Job 은 장치 크기에 따라 메모리를 한 번 크게 씁니다. 문서는 큰 디스크에서 1에서 2Gi 쯤이라며 이 Job 에는 메모리 상한을 두지 말라고 권합니다. 한 번 준비된 OSD 는 다음 prepare 에서 「이미 있다」 로 건너뛰므로 큰 사용은 한 번뿐입니다.

5. CSI 배포: v1.21 에서는 셋이 나눠 맡는다

CSI(Container Storage Interface)는 쿠버네티스가 저장소 업체의 드라이버를 부르는 표준 규약입니다. PVC 가 생기면 CSI 드라이버의 provisioner(컨트롤러 쪽)가 저장소에 볼륨을 만들고, 파드가 노드에 뜨면 그 노드의 nodeplugin 이 볼륨을 붙여(map·mount) 줍니다.

예전 Rook 은 CSI 드라이버를 직접 배포했습니다. v1.21 에서는 이 일을 세 주체가 나눠 맡습니다. 처음 설치하는 사람이 가장 많이 걸릴 수 있는 대목이라 순서대로 적습니다.

1. ceph-csi-operator. rook-ceph 차트가 하위 차트(ceph-csi-operator 1.1.0)로 함께 설치합니다 (Chart.yaml, 조건 csi.installCsiOperator). 이 operator 가 실제 드라이버 파드를 만듭니다.
2. ceph-csi-drivers 차트. 어떤 드라이버를 켤지 적은 Driver CR, OperatorConfig, 드라이버 파드가 쓸 RBAC 를 만듭니다. 이 차트는 Rook 저장소가 아니라 ceph-csi-operator 의 Helm 저장소에서 받고, Rook 이 맞춰 둔 values 파일 (deploy/charts/ceph-csi-drivers/values.yaml)을 넣어 설치합니다. 기본은 RBD·CephFS 를 켜고 NFS·NVMe-oF 는 끕니다. 드라이버 이름은 rook-ceph.rbd.csi.ceph.com 처럼 operator 네임스페이스를 앞에 붙입니다. 업그레이드 문서는 이 차트를 설치하지 않으면 서비스 계정이 없어 CSI 드라이버가 실패 상태가 된다고 적습니다(v1.20 부터의 요구 사항, Rook Upgrades).
3. Rook operator. mon 이 뜬 뒤 operator 네임스페이스에 CephConnection CR(mon 주소 목록, read affinity, RBD 미러 수)과 기본 ClientProfile(RBD·CephFS 가 쓸 Secret 이름)을 만들고 고칩니다 (ceph_connection.go#L37-L103, config.go#L149-L190). 둘 다 이름은 CephCluster 의 네임스페이스입니다. 서브볼륨 그룹과 RADOS 네임스페이스마다 ClientProfile 을 따로 만드는 것은 2절에서 본 대로입니다.

ceph-csi-operator 는 Driver CR 하나를 받으면 CSIDriver 객체, 이름이 -ctrlplugin 으로 끝나는 Deployment(provisioner 와 사이드카들), -nodeplugin 으로 끝나는 DaemonSet(모든 노드), liveness Service, NetworkPolicy, 설정 ConfigMap 을 만듭니다 (driver_controller.go#L254-L264). 그래서 Rook quickstart 의 파드 목록에 rook-ceph.rbd.csi.ceph.com-ctrlplugin-… 와 rook-ceph.rbd.csi.ceph.com-nodeplugin-… 가 보입니다.

StorageClass 의 provisioner 는 이 드라이버 이름과 정확히 같아야 합니다. 이름 앞부분을 바꾸고 싶으면(CSI_DRIVER_NAME_PREFIX) 처음 설치할 때만 하라고 문서가 경고합니다. 이미 쓰는 클러스터에서 바꾸면 예상하지 못한 동작이 난다고 적혀 있습니다 (Ceph CSI Drivers).

6. 업그레이드 순서

Rook 은 업그레이드를 둘로 나눕니다. Rook 자체(관리 층) 와 Ceph(데이터 층) 입니다.

Rook 업그레이드. 차트는 rook-ceph → ceph-csi-drivers → rook-ceph-cluster 순서로 올립니다. 문서가 밝힌 v1.21 의 깨지는 변경은 셋입니다.

• Helm OCI 차트 태그에 v 를 붙이지 않습니다(1.21.0).
• Ceph msgr2 프로토콜이 기본으로 필수가 되었습니다. msgr2 는 커널 5.11 이상이 필요하고, 오래된 커널이면 requireMsgr2: false 로 끕니다. 이미 붙은 볼륨은 다시 붙을 때까지 msgr1 을 계속 쓰고, mon 은 failover 로 새로 설 때부터 msgr2 만 받습니다.
• 지원하는 쿠버네티스 최소 판이 v1.32 입니다.

또 v1.21 에서 블록 StorageClass 에 CSI Secret 매개변수가 새로 생겼는데, StorageClass 의 parameters 는 바꿀 수 없으므로 차트를 올리기 전에 ceph-block StorageClass 를 지우라고 안내합니다. 이름이 같은 StorageClass 가 다시 생기므로 기존 PV 는 영향을 받지 않는다고 적혀 있습니다.

Ceph 업그레이드. CephCluster 의 이미지를 바꾸면 시작됩니다 (Ceph Upgrades). Rook 은 데몬을 하나씩 멈춰도 되는지 확인하고, 바꾸고, 자리가 잡히기를(mon 은 쿼럼, OSD 는 PG 가 clean, MDS 는 up) 기다린 뒤 다음 데몬으로 갑니다. 2절에서 본 reconcile 순서대로 CephCluster 안에서는 mon, mgr, OSD 순이고, MDS 와 RGW 는 각자의 컨트롤러가 맡습니다. OSD 하나가 멈춰도 되는 상태가 되기를 기다리는 시간은 waitTimeoutForHealthyOSDInMinutes(기본 10분)입니다. 지원하는 Ceph 는 Squid v19.2.0 이상과 Tentacle v20.2.1 이상이고, v20.2.0 은 read affinity 를 켰을 때 데이터 손상 문제가 알려져 권하지 않습니다. Rook 은 v20.2.0 에서 read affinity 를 스스로 끕니다 (ceph_connection.go#L105-L116).

7. 클러스터 정리: cleanupPolicy

CephCluster 를 지운다고 데이터가 지워지지는 않습니다. 이것이 기본이고, 실수로 지운 CR 이 데이터를 날리지 않게 하려는 장치입니다. 차트 문서도 rook-ceph-cluster 를 지워도 /var/lib/rook 과 OSD 디스크의 데이터는 남으니 디스크를 다시 쓰려면 직접 지우라고 적습니다.

정말로 지우려면 먼저 CephCluster 에 확인 문구를 적습니다 (Cleanup, CephCluster CRD: Cleanup policy).

확인 문구가 있는 상태에서 CephCluster 를 지우면, operator 는 Ceph 데몬 파드가 있던 노드를 기억해 두고 그 파드들이 모두 사라질 때까지 5초 간격으로 기다린 뒤, 그 노드마다 Job(cluster-cleanup-job-<노드>, 레이블 rook-ceph-cleanup)을 띄워 dataDirHostPath 를 지우고 OSD 디스크를 닦습니다(cleanup.go#L62-L100). 문서는 앱의 볼륨과 PVC 를 먼저 정리하라고 강조합니다. 그러지 않으면 볼륨이 매달리고 노드를 재시작해야 할 수 있습니다. CSI operator 의 CR(operatorconfigs·drivers·clientprofiles·clientprofilemappings·cephconnections)도 따로 지워야 합니다.

확인 문구 없이 지웠다면 노드마다 dataDirHostPath 를 손으로 지우고 디스크를 닦아야 합니다(문서의 sgdisk --zap-all, dd, blkdiscard, LVM·device mapper 정리 절차). 특히 dataDirHostPath 를 남겨 둔 채 다시 설치하면 mon 이 새 클러스터에서 뜨지 못한다고 차트 values 의 주석이 경고합니다.

8. toolbox

Ceph 를 들여다보는 기본 도구는 ceph 명령입니다. Rook 은 이 명령이 든 컨테이너를 toolbox 라는 Deployment(rook-ceph-tools)로 줍니다 (Toolbox). 클러스터 차트에서는 toolbox.enabled 가 기본 false 이고, 켜면 Ceph 이미지와 같은 이미지로 뜹니다. 한 번만 명령을 돌리고 결과를 로그로 남기는 Job 방식도 있고, toolbox 없이 쓰는 kubectl 플러그인도 있습니다.

kubectl -n rook-ceph exec -it deploy/rook-ceph-tools -- ceph status
kubectl -n rook-ceph exec -it deploy/rook-ceph-tools -- ceph osd tree
kubectl -n rook-ceph exec -it deploy/rook-ceph-tools -- ceph df

4편에서 TT Lab 실습 클러스터의 이 세 출력을 1편의 개념과 맞춰 읽을 예정입니다.

9. operator 가 하지 않는 일

operator 를 들이면 「이제 다 알아서 해 주겠지」 하고 기대하기 쉽습니다. 원문에서 확인한, Rook 이 하지 않거나 기본으로는 하지 않는 일입니다.

하나 더 짚어 둘 것이 있습니다. useAllNodes: true 일 때 노드의 taint 나 affinity 를 바꿔 노드가 Rook 의 대상에서 빠지면, 그 노드의 OSD 는 operator 파드를 지워 다시 띄우는 것으로 「확인」 해야 제거됩니다. 실수로 데이터를 잃지 않으려는 장치이고, 문서는 운영 환경에서는 useAllNodes: false 로 노드를 명시하라고 권합니다.

티티 한마디. Rook 은 꼼꼼한 관리인이에요. mon 이 아프면 10분은 기다려 주고, 빈 디스크를 보면 OSD 로 만들고, 지우라고 하면 「정말요?」 를 꼭 물어봐요. 그런데 데이터를 직접 나르지는 않아요. 그건 Ceph 데몬들 몫이죠. 그러니 operator 가 잠깐 쉬어도 이미 붙은 볼륨은 멀쩡해요!

참고

소스와 문서는 모두 2026-10-29 에 위 커밋에서 열람했습니다.

• Rook v1.21.1 릴리스: https://github.com/rook/rook/releases/tag/v1.21.1
• Storage Architecture: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Getting-Started/storage-architecture.md
• Monitor Health: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Storage-Configuration/Advanced/ceph-mon-health.md
• CephCluster CRD: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/CRDs/Cluster/ceph-cluster-crd.md
• Prerequisites: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Getting-Started/Prerequisites/prerequisites.md
• Ceph CSI Drivers: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-drivers.md
• Ceph-CSI Driver Helm Chart: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Helm-Charts/csi-drivers-chart.md
• Rook Upgrades: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Upgrade/rook-upgrade.md
• Ceph Upgrades: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Upgrade/ceph-upgrade.md
• Cleanup: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Storage-Configuration/ceph-teardown.md
• Toolbox: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Troubleshooting/ceph-toolbox.md
• ceph-csi-operator v1.1.0 Driver 컨트롤러: https://github.com/ceph/ceph-csi-operator/blob/98eee8980fc69e5c9c02c80958abe06c3faba5eb/internal/controller/driver_controller.go