Kubernetes MongoDB Community 버전 업그레이드 가이드 (6.0.5 → 8.2.6)

개요

MongoDB Community Operator를 사용하여 Kubernetes에서 운영 중인 MongoDB를 6.0.5에서 8.2.6으로 업그레이드하는 과정을 정리합니다.

• Operator: mongodb-kubernetes (Community) v1.7.0
• 업그레이드 경로: 6.0.5 → 7.0.31 → 8.0.20 → 8.2.6

MongoDB 설치 방법에 대한 글은 아래 링크를 타고 가시면 볼 수 있습니다.
Kubernetes에 MongoDB 설치하기

---

사전 지식

MongoDB는 Major 버전을 건너뛸 수 없다

MongoDB는 Major 버전을 순차적으로 업그레이드해야 합니다. 예를 들어 6.0에서 8.0으로 바로 올릴 수 없습니다.

6.0 → 7.0 → 8.0 → 8.2

featureCompatibilityVersion (FCV)

FCV는 MongoDB 내부 기능 호환성을 제어하는 설정입니다. 새로운 Major 버전으로 업그레이드하기 전에 현재 버전의 FCV가 올바르게 설정되어 있어야 합니다.

• 7.0.x 실행 중 → FCV 7.0 필요
• 8.0.x 실행 중 → FCV 8.0 필요
• 8.2.x는 8.x 계열이므로 FCV 8.0 유지

MongoDB Community Operator와 FCV

Operator는 MongoDBCommunity 리소스의 featureCompatibilityVersion 필드를 통해 FCV를 관리합니다.

version과 featureCompatibilityVersion을 yaml에서 함께 변경 후 apply하면 Operator가 순서에 맞게 처리합니다.

---

업그레이드 절차

Step 1. 6.0.5 → 7.0.31

mongodb.yaml의 version과 featureCompatibilityVersion을 함께 변경 후 apply합니다.

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: mongodb
spec:
  members: 1
  type: ReplicaSet
  version: "7.0.31" # MongoDB 버전 업그레이드 6.0.5 -> 7.0.31
  featureCompatibilityVersion: "7.0" # FCV 버전 정의하는 내용 추가
  ...

이제 mongodb.yaml 파일을 적용해줍니다.

kubectl apply -f mongodb.yaml -n mongodb

이렇게 적용을 해주면 mongodb-operator 가 알아서version,featureCompatibilityVersion의 변경된 값을 감지하여 업그레이드 시켜줍니다.

업그레이드 확인

우선 MongoDB 버전이 업그레이드 되었나 확인해보겠습니다.

kubectl get mongodbcommunity.mongodbcommunity.mongodb.com -n mongodb
---
NAME                   PHASE     VERSION
mongodb-0   Running   7.0.31

이제 FCV 버전도 업그레이드 되었는지 확인해보겠습니다.

# 먼저 설치된 mongodb 파드 접속
kubectl exec -it mongodb-0  -c mongod -- bash -n mongodb

# mongosh 를 사용하여 FCV 버전 확인
mongosh -u admin -p powertask --authenticationDatabase admin --eval "db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })"
---
{
  featureCompatibilityVersion: { version: '7.0' }, # 여기 보면 7.0 으로 업그레이드 된 것을 확인 할 수 있습니다.
  ok: 1,
  ...
}

Step 2. 7.0.31 → 8.0.20

여기서 부터는 앞서 6.0.5 -> 7.0.31 버전으로 업그레이드 했던 방식과 동일하게 진행을 하시면 됩니다.

Step 3. 8.0.20 → 8.2.6

8.2.x는 8.x 계열이므로 FCV는 8.0을 유지합니다.

따라서 이번엔 version 만 변경을 해주면 됩니다.

spec:
  version: "8.2.6" # 8.0.20 -> 8.2.6 변경
  featureCompatibilityVersion: "8.0" # Step 2에서 8.0으로 변경한 그대로 두기

버전 업그레이드 확인

앞선 방식과 동일하게 업그레이드 된 버전을 확인해보겠습니다.

kubectl get mongodbcommunity.mongodbcommunity.mongodb.com -n mongodb
---
NAME                   PHASE     VERSION
mongodb-0   Running   8.2.6

# 먼저 설치된 mongodb 파드 접속
kubectl exec -it mongodb-0  -c mongod -- bash -n mongodb

# mongosh 를 사용하여 FCV 버전 확인
mongosh -u admin -p powertask --authenticationDatabase admin --eval "db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })"
---
{
  featureCompatibilityVersion: { version: '8.0' }, # 여기 보면 7.0 으로 업그레이드 된 것을 확인 할 수 있습니다.
  ok: 1,
  ...
}

---

마치며

이번 업그레이드를 진행하면서 처음에는 version 필드만 변경했더니 Pod가 계속 오류로 재시작되는 문제를 겪었습니다. 원인을 찾아보니 featureCompatibilityVersion도 함께 올려줘야 한다는 것을 알게 되었고, 두 필드를 같이 변경하니 정상적으로 동작했습니다.

업그레이드를 진행하게 된 계기는 Vector Search 기능 도입 때문이었습니다. MongoDB의 Vector Search는 버전 8.2 이상에서 지원되기 때문에, 6.0.5에서 8.2.6까지 순차 업그레이드를 진행했습니다.

같은 상황을 겪는 분들에게 도움이 되길 바라며 과정을 정리해 공유합니다.

감사합니다.