Kubernetes 기반 데이터베이스 Operator - MongoDB Replica Set 관리

KubeBlocks

Kubernetes 기반 데이터베이스 Operator - MongoDB Replica Set 관리

개요

KubeBlocks는 데이터베이스를 Kubernetes 네이티브하게 관리하는 오픈소스 Operator입니다.

imprun.dev에서의 용도:

• ✅ MongoDB Replica Set 관리: 고가용성 MongoDB 클러스터
• ✅ 자동 백업/복구: 데이터 보호
• ✅ 동적 스케일링: CPU/Memory 자동 조절
• ✅ 모니터링 통합: Prometheus 메트릭 자동 수집

왜 KubeBlocks인가?

StatefulSet vs KubeBlocks

항목	StatefulSet (직접 관리)	KubeBlocks
Replica Set 구성	❌ 수동 설정	✅ 자동 구성
장애 복구	❌ 수동 개입	✅ 자동 복구
백업/복구	❌ 별도 구현 필요	✅ 내장
스케일링	❌ 수동	✅ 자동
모니터링	❌ 별도 설정	✅ 자동 통합

설치 방법

1. 스크립트를 통한 자동 설치 (권장)

cd k8s/kubeblocks
bash install.sh

설치 과정:

1. Helm Repository 추가 (kubeblocks)
2. Namespace 생성 (kb-system)
3. KubeBlocks Operator 설치 (v0.9.5)
4. ComponentDefinition 생성 대기

2. 수동 설치

# Repository 추가
helm repo add kubeblocks https://apecloud.github.io/helm-charts
helm repo update

# 설치
helm install kubeblocks kubeblocks/kubeblocks \
  --namespace kb-system \
  --create-namespace \
  --version 0.9.5 \
  --timeout 10m

버전 선택: 왜 0.9.5인가?

버전	상태	문제점
1.0.1 (최신)	❌ 설치 실패	CRD annotation 크기 제한 초과 (Kubernetes 1.28 이슈)
0.9.5 (안정)	✅ 설치 성공	안정적, 모든 기능 정상 작동

CRD 오류 예시 (1.0.1):

CustomResourceDefinition.apiextensions.k8s.io "clusters.apps.kubeblocks.io" is invalid: 
metadata.annotations: Too long: must have at most 262144 bytes

설치 후 확인

1. Pod 상태 확인

kubectl get pods -n kb-system

# 정상 출력:
# NAME                                  READY   STATUS    RESTARTS   AGE
# kubeblocks-xxxxxxx                    1/1     Running   0          2m
# kubeblocks-dataprotection-xxxxx       1/1     Running   0          2m

2. ComponentDefinition 확인 (1-2분 소요)

kubectl get componentdefinition

# MongoDB 관련 정의가 표시되어야 함:
# NAME                  ...
# mongodb-5.0           ...
# mongodb-6.0           ...

3. ComponentVersion 확인

kubectl get componentversion | grep mongo

# 출력:
# mongodb-5.0.28
# mongodb-6.0.21

imprun Chart에서 사용

KubeBlocks 설치 후 imprun Chart의 templates/mongodb-cluster.yaml에서 MongoDB Cluster를 생성합니다.

예시: MongoDB Cluster 리소스

apiVersion: apps.kubeblocks.io/v1alpha1
kind: Cluster
metadata:
  name: mongodb
  namespace: imprun-system
spec:
  # ComponentDefinition 참조
  clusterDefinitionRef: mongodb

  # MongoDB 버전
  clusterVersionRef: mongodb-6.0

  # 종료 정책
  terminationPolicy: DoNotTerminate  # helm uninstall 시에도 데이터 보존

  componentSpecs:
    - name: mongodb
      componentDefRef: mongodb

      # Replica 수
      replicas: 1  # ARM64 환경 (4 cores, 24GB)에서는 1 권장

      # 리소스
      resources:
        requests:
          cpu: 200m
          memory: 512Mi
        limits:
          cpu: 500m
          memory: 1Gi

      # 스토리지
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi

imprun Chart 배포

cd ../imprun
helm dependency update
helm install imprun . -n imprun-system --create-namespace \
  --values values.yaml --values values-production.yaml

자동 생성되는 리소스:

• MongoDB Cluster (KubeBlocks 관리)
• Secret: mongodb-conn-credential (연결 정보)
• Service: mongodb-mongodb (ClusterIP)
• StatefulSet: mongodb-mongodb (KubeBlocks 생성)

MongoDB 연결 정보 확인

1. Secret에서 비밀번호 가져오기

# Root 비밀번호
kubectl get secret mongodb-conn-credential -n imprun-system \
  -o jsonpath='{.data.password}' | base64 -d

2. MongoDB Shell 접속

# Pod 내부에서 접속
kubectl exec -it mongodb-mongodb-0 -n imprun-system -- mongosh \
  --username root \
  --password $(kubectl get secret mongodb-conn-credential -n imprun-system -o jsonpath='{.data.password}' | base64 -d) \
  --authenticationDatabase admin

3. 연결 문자열

# imprun-server에서 사용하는 연결 문자열
mongodb://root:${PASSWORD}@mongodb-mongodb:27017/sys_db?authSource=admin&replicaSet=mongodb

트러블슈팅

1. ComponentDefinition이 생성되지 않음

증상:

kubectl get componentdefinition
# No resources found

원인: KubeBlocks Pod가 아직 시작 중

해결:

# Pod 상태 확인
kubectl get pods -n kb-system

# 로그 확인
kubectl logs -n kb-system -l app.kubernetes.io/name=kubeblocks

2. MongoDB Cluster가 Pending 상태

증상:

kubectl get cluster -n imprun-system
# NAME      STATUS    AGE
# mongodb   Pending   5m

원인: StorageClass 없음

해결:

# StorageClass 확인
kubectl get storageclass

# Local Path Provisioner 설치 (없는 경우)
kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.28/deploy/local-path-storage.yaml

# 기본 StorageClass 설정
kubectl patch storageclass local-path \
  -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

3. CRD 버전 충돌

증상:

Error: ... CRD version mismatch

해결:

# 기존 KubeBlocks 완전 삭제
helm uninstall kubeblocks -n kb-system
kubectl delete namespace kb-system

# CRD 삭제
kubectl get crd | grep kubeblocks | awk '{print $1}' | xargs kubectl delete crd

# 재설치
cd k8s/kubeblocks && bash install.sh

MongoDB Cluster 관리

스케일 업/다운

# Replica 수 변경 (1 → 3)
kubectl patch cluster mongodb -n imprun-system \
  --type='json' \
  -p='[{"op": "replace", "path": "/spec/componentSpecs/0/replicas", "value":3}]'

백업 생성

kubectl apply -f - <<EOF
apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: mongodb-backup-$(date +%Y%m%d)
  namespace: imprun-system
spec:
  backupPolicyName: mongodb-backup-policy