/ /

자체 관리 배포서버를 Kubernetes 로 마이그레이션하기

Docs Home

/ /

데이터베이스 리소스 배포

Migrate a Self-Managed Deployment to Kubernetes

Docs Home

관리

Kubernetes Operator용 컨트롤러

데이터베이스 리소스 배포

Migrate a Self-Managed Deployment to Kubernetes

복제본 세트를 Kubernetes 로 마이그레이션

This procedure migrates any replica set that Ops Manager or Cloud Manager manages into Kubernetes under Kubernetes Operator, using normal MongoDB replication. This includes deployments that run on virtual machines or bare metal, and deployments already managed by a different Kubernetes Operator instance. The migration is live and incremental: you extend the replica set into Kubernetes, promote the Kubernetes members, and then prune the external members. There is no snapshot restore and no mongosync involved.

시작하기 전에

복제본 세트 마이그레이션 전에 다음 사항을 확인하세요.

A Ops Manager or Cloud Manager connection ConfigMap with the keys baseUrl, orgId, and projectName.
An API key Secret with the keys publicKey and privateKey.
The Kubernetes Operator ServiceAccount has batch/jobs permissions (create, get, list, watch, and delete) for the dry-run connectivity Job.
프로젝트 배포서버 하나만 포함되어 있습니다.

또한 다음이 필요합니다.

An existing replica set that Ops Manager or Cloud Manager manages.
Exactly one deployment in the Ops Manager or Cloud Manager project.
Kubernetes Operator가 설치된 Kubernetes 클러스터 .
The kubectl mongodb plugin at a version that matches Kubernetes Operator. Kubernetes Operator enforces this match on every reconcile, including the dry run.
가상 머신 호스트와 Kubernetes Pod 간의 양방향 네트워크 연결 및 호스트 이름 확인.
배포서버 TLS를 사용하는 경우 모든 SAN을 포괄하는 사전 구성된 TLS 인증서입니다.
SCRAM 사용자 비밀번호. 자동화 구성에서는 복구할 수 없습니다.
시작하기 전에 만든 백업 입니다.
배포서버 가 정상이며 목표 상태.

항상 투표권이 있는 멤버를 최소 3명으로 유지합니다. Kubernetes Operator가 7 이상의 투표 멤버를 거부합니다. 7를 초과하는 경우, 투표권이 없는 Kubernetes 멤버를 추가하거나 투표권이 있는 외부 멤버를 제거 .
한 번에 한 가지 종류의 변경만 수행할 수 있습니다: Kubernetes 멤버를 추가하거나, 외부 멤버를 정리하거나, 한 번에 한 멤버의 투표 및 우선 순위 만 변경할 수 있습니다. 허용 유효성 검사 마이그레이션 시작되면 혼합된 변경 사항을 거부하며, 마이그레이션 중에 Kubernetes 멤버를 제거하거나 외부 멤버를 추가하는 것도 거부합니다.
배포서버 목표 상태 인 경우에만 작동합니다.
프라이머리 마지막으로 마이그레이션합니다. 투표와 우선 순위 를 멤버로 옮기면 투표 트리거하다 될 수 있으며, 복제본 세트 새 프라이머리 선택하는 동안 쓰기가 잠시 실패할 수 있습니다. 프라이머리 마지막으로 마이그레이션하면 최종 단계까지 해당 투표 및 이로 인해 발생하는 쓰기 (write) 다운타임이 트리거되는 것을 방지할 수 있습니다.

참고
Kubernetes 에서 멤버의 우선 순위 를 높여 재선을 트리거하다 할 수도 있습니다.
While spec.externalMembers is non-empty, Kubernetes Operator forces one-member-at-a-time scaling. This is why each change needs its own wait for goal state.

절차

Ops Manager 또는 Cloud Manager 액세스 준비합니다.

Create the project ConfigMap and the API key Secret described in the prerequisites.

MongoDB 사용자 지정 리소스 생성합니다.

kubectl mongodb migrate-to-mck mongodb 명령을 실행합니다.

kubectl mongodb migrate-to-mck mongodb \
  --config-map-name <configmap> \
  --secret-name <secret> \
  --namespace <namespace> \
  -o mongodb-cr.yaml

생성된 파일 검사합니다. 여기에는 다음이 포함됩니다.

spec.externalMembers, 소스 프로세스를 나열합니다.
spec.members 0(으)로 설정합니다.
The mongodb.com/migration-dry-run: true annotation, which the plugin always adds.

이 명령은 다음과 같은 선택적 플래그도 지원합니다.

--certs-secret-prefix: required when TLS is enabled. Sets spec.security.certsSecretPrefix.
--prometheus-secret-name: use when Prometheus is enabled. The Secret must already exist and have a password key.
--resource-name-override: sets metadata.name on the generated resource. The plugin normalizes the replica set name automatically when it is not a valid Kubernetes name, and sets spec.replicaSetNameOverride for you.

MongoDBUser 사용자 지정 리소스를 생성합니다.

데이터베이스 사용자를 마이그레이션 하려는 경우에만 이 단계를 완료하세요. 마이그레이션 에는 필요하지 않습니다.

Pre-create one Secret per SCRAM user, each with a password key. Run:

kubectl mongodb migrate-to-mck users \
  --config-map-name <configmap> \
  --secret-name <secret> \
  --namespace <namespace> \
  --users-secrets-file users.csv \
  -o users-cr.yaml

The CSV file maps users to Secrets, one per line, in the form username:database,secret-name. Omit --users-secrets-file to be prompted for each user instead.

플러그인은 $external 데이터베이스 대해 X.509 및 LDAP 사용자를 생성합니다. 자동화 에이전트 사용자를 건너뜁니다.

배포서버 TLS를 사용하는 경우 Kubernetes 구성원 인증서를 발급합니다.

가상 머신 인증서에 서명한 동일한 인증 기관에서 Kubernetes 구성원 인증서를 발급합니다.

Kubernetes Operator expects a kubernetes.io/tls Secret named <certsSecretPrefix>-<resourceName>-cert and a CA ConfigMap named <resourceName>-ca that contains both a ca-pem key and an mms-ca.crt key. The certificates need SANs that cover the per-Pod and Service DNS names, and both server auth and client auth usages.

If the source deployment does not use TLS, set net.tls.mode to disabled in Ops Manager or Cloud Manager, on the existing virtual machine deployment, before you migrate. You do not need to set anything in the MongoDB custom resource for this case.

참고

CA 불일치는 의도적으로 다음 단계의 실행 에서 포착됩니다.

외부 액세스 구성합니다.

Before you run the dry run, configure spec.externalAccess so that the virtual machine members can reach the Kubernetes Pods. To let those members resolve the Pods by hostname, you can also set spec.externalAccess.externalDomain. To learn about the fields involved and the DNS requirements, see Network Requirements for Migration.

이 설정 사용자가 소유하며, 환경에 맞게 LoadBalancer 또는 NodePort와 DNS 레코드를 구성합니다.

중요

Don't set externalDomain if you use MongoDB Search or Vector Search with this deployment. MongoDBSearch does not support a MongoDB resource that sets externalDomain, and you can't remove the field after you create the cluster. To learn more, see MongoDB Search Interaction with Migration.

테스트 실행 실행하고 연결을 확인합니다.

Apply the generated resource with the mongodb.com/migration-dry-run annotation still present. While the annotation is set, Kubernetes Operator makes no automation config changes and only validates connectivity.

Kubernetes Operator creates a Job named <resourceName>-connectivity-check, which dials every external member and authenticates. The Job deletes itself using ttlSecondsAfterFinished, and the next reconcile re-creates it, so re-validation is automatic. You can fix problems in Kubernetes or in the Ops Manager UI and re-run freely.

The dry run checks Kubernetes-to-virtual-machine reachability (DNS, TLS, firewalls, and member addresses) and credentials, including the __system role on the local database, and the CA when TLS is enabled. It does not check virtual-machine-to-Kubernetes inbound connectivity.

해당 방향은 전적으로 네트워킹 설정 에 따라 달라지므로 단일 명령으로 이를 보장할 수는 없습니다. 대신 다음 체크리스트를 살펴보세요.

Confirm that the hostnames the Kubernetes members will have, following the pattern <metadata.name>-0.<spec.externalAccess.externalDomain>, are resolvable from the virtual machine members.
가상 머신에서 Kubernetes 노드 또는 LoadBalancer IP에 연결할 수 있는지 확인합니다.

Read the result from status.conditions[type=NetworkConnectivityVerified]:

유효성 검사기 작업 종료 코드	조건 상태	이유	의미
작업이 아직 실행 .	`Unknown`	`Running`	The `status.phase` is `ConnectivityCheckRunning`.
`0`	`True`	`NetworkValidationPassed`	모든 외부 멤버에 연결할 수 있고 인증됩니다.
`2`	`False`	`AuthenticationFailed`	Credentials, the authentication mechanism, or a missing `__system@local` role.
`3`	`False`	`NetworkFailed`	DNS, TLS, 시간 초과 또는 연결할 수 없는 멤버. Job Pod 로그를 확인합니다.
`1` 또는 기타	`False`	`UnknownError`	분류되지 않은 오류입니다. Job Pod 로그를 확인합니다.

Failures that occur before the Job starts use the reasons OperatorImageUnknown, BuildStatefulSetOptions, AgentCertSecretFailed, and AgentCertSubject.

Kubernetes Operator removes the NetworkConnectivityVerified condition from status.conditions entirely once no external members remain.

복제본 세트 Kubernetes 로 확장합니다.

테스트 실행 주석을 제거합니다.

kubectl annotate mdb <resourceName> \
  mongodb.com/migration-dry-run-

This is the point at which Kubernetes Operator takes ownership of the Ops Manager project.

Raise spec.members and hand-write spec.memberConfig together.

경고

멤버 수를 늘리기 전에 spec.memberConfig를 설정하세요.

By default, new Kubernetes members join as voting members. The CRD defaults are votes: 1 and priority: "1", which let a still-syncing member participate in an election before it has finished its initial sync.

MongoDB recommends that you write one spec.memberConfig entry per new Kubernetes member with votes: 0 and priority: "0" before you raise the member count, so that a still-syncing member cannot win an election. votes is an integer. priority is a string.

예시 들어, 세 개의 Kubernetes 멤버를 투표권이 없는 멤버로 추가하려면 다음을 수행합니다.

spec:
  memberConfig:
    - votes: 0
      priority: "0"
    - votes: 0
      priority: "0"
    - votes: 0
      priority: "0"

Wait for full initial sync and goal state. If you generated MongoDBUser resources in the optional step above, apply them now and confirm each one reaches a status.phase of Updated.

Kubernetes 멤버를 승격합니다.

Shift votes and priority onto the Kubernetes members by editing spec.memberConfig. votes is an integer. priority is a string containing a float.

External members keep whatever votes and priority they carry in the source automation config. spec.externalMembers has no votes or priority field.

목표 상태 를 기다립니다.

외부 멤버를 정리합니다.

중요

Remove only one entry from spec.externalMembers at a time. Wait for goal state after each removal before you remove the next entry.

예를 들면 다음과 같습니다.

kubectl patch mdb <resourceName> --type=json \
  -p='[{"op":"remove","path":"/spec/externalMembers/0"}]'

항목을 제거 할 수는 있지만 마이그레이션 시작된 후에는 추가할 수 없습니다.

Watch status.conditions[type=Migrating].reason move through Extending, InProgress, and Pruning:

이유	상태	의미
`Validating`	`True`	테스트 실행 주석이 설정하다 되었습니다.
`Extending`	`True`	원하는 Kubernetes 멤버 수가 마지막으로 조정된 수를 초과했습니다.
`Pruning`	`True`	The `externalMembers` count dropped below `status.migrationObservedExternalMembersCount`.
`InProgress`	`True`	외부 멤버가 있지만 변경되는 것은 없습니다. 이것이 첫 번째 화해의 이유이기도 합니다.
`MigrationComplete`	`False`	모든 외부 멤버가 제거되었습니다.

Precedence is Validating > Extending > Pruning > InProgress. A prune that also grows the Kubernetes side reports Extending, which is another reason to make one change at a time.

가지 치기와 확장은 동시에 허용되지 않습니다.

To script against migration completion, use kubectl wait --for=condition=Migrating=False rather than polling status.phase.

확인하고 완료합니다.

Migration is complete when spec.externalMembers is empty, the Migrating condition is False with reason MigrationComplete, and all data lives in persistent volume claims:

kubectl wait --for=condition=Migrating=False mdb/<resourceName>

애플리케이션 연결 문자열을 업데이트하고 가상 머신을 폐기합니다. Kubernetes Operator는 사용자를 위해 가상 머신을 폐기하지 않습니다.

연결 문자열 비밀

Kubernetes Operator automatically generates a connection string Secret containing no credentials, named <metadata.name>-cluster-connection-string, and keeps it in sync with the active nodes. Point your applications at this Secret instead of hardcoding a connection string.

마이그레이션 중 가용성

읽기는 마이그레이션 내내 계속 사용할 수 있습니다. 투표 중에는 쓰기가 잠시 실패할 수 있으므로 드라이버는 재시도 가능 쓰기를 사용해야 합니다. 읽기 대상이 이동하면 읽기 지연 시간 증가할 수 있으므로 가상 머신과 동일한 리전 에서 Kubernetes 클러스터 실행 . 정지 모드 가 없기 때문에 마이그레이션된 세컨더리 중단에 대한 장기 실행 커서.

돌아가기

네트워크 요구 사항

샤딩된 클러스터