Migrate an Application Database to an External Deployment

How the Migration Works

The Ops Manager resource starts with an internally managed Application Database, and the Kubernetes Operator owns a StatefulSet named <primary-om-name>-db. The migration proceeds as follows:

1. You create a MongoDB resource with spec.role set to AppDB and the same name as the StatefulSet, in a project that a management Ops Manager instance manages. The MongoDB resource can't take ownership of the StatefulSet yet, so it stays in the Pending phase with a message that it can't take ownership of the Application Database StatefulSet.

2. You add spec.externalApplicationDatabaseRef to the Ops Manager resource. The Kubernetes Operator detaches the StatefulSet by removing the Ops Manager resource's owner reference and marking the StatefulSet as ready for migration. The MongoDB resource then takes ownership of it.

Because the Kubernetes Operator computes the same connection string as before, which uses the same hostnames, the Ops Manager pods don't restart.

Prerequisites

Before you begin, complete the following tasks:

• Install the Kubernetes Operator and kubectl. To learn more, see Install with Kubernetes.

• Deploy a primary Ops Manager resource that uses an internally managed Application Database. This resource sets spec.applicationDatabase, and the Kubernetes Operator owns a StatefulSet named <primary-om-name>-db. To learn more, see Deploy an Ops Manager Resource.

• Deploy a management Ops Manager resource that is in the Running phase and that owns the project for the external Application Database. To learn more, see Deploy Ops Manager with an External Application Database.

• Confirm that the Kubernetes Operator created the programmatic API key secret for the management Ops Manager resource. The Kubernetes Operator names this secret <namespace>-<management-om-name>-admin-key.

Considerations

Review the following considerations before you migrate:

• The Application Database version that you set on the MongoDB resource must match the version that the internally managed Application Database runs, and it must be a MongoDB version that the management Ops Manager instance offers.

• The Kubernetes Operator doesn't support spec.applicationDatabase.passwordSecretKeyRef during migration. The Kubernetes Operator generates a new password, and it rotates any password that you provided.

• The Application Database can be unavailable for one to two minutes if the MongoDB resource configuration differs from the internally managed Application Database configuration, such as a different pod template or a different set of containers. If the two configurations are semantically identical, the Application Database remains available.

• The Kubernetes Operator supports migration on a single Kubernetes cluster only.

Procedure

export K8S_CTX="<your-kube-context>"
export MDB_NS="mongodb"
export MANAGEMENT_OM_NAME="management-om"
export PRIMARY_OM_NAME="primary-om"
export APPDB_NAME="${PRIMARY_OM_NAME}-db"
export APPDB_VERSION="8.0.5-ent"
export MANAGEMENT_OM_URL="http://${MANAGEMENT_OM_NAME}-svc.${MDB_NS}.svc.cluster.local:8080"
export MANAGEMENT_OM_ADMIN_KEY_SECRET="${MDB_NS}-${MANAGEMENT_OM_NAME}-admin-key"
export APPDB_PROJECT_CONFIGMAP="${APPDB_NAME}-config"
export APPDB_PROJECT_NAME="external-appdb"

kubectl create configmap "${APPDB_PROJECT_CONFIGMAP}" \
  --context "${K8S_CTX}" -n "${MDB_NS}" \
  --from-literal=baseUrl="${MANAGEMENT_OM_URL}" \
  --from-literal=projectName="${APPDB_PROJECT_NAME}" \
  --from-literal=orgId=""

kubectl apply --context "${K8S_CTX}" -n "${MDB_NS}" -f - <<EOF
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: ${APPDB_NAME}
spec:
  members: 3
  version: ${APPDB_VERSION}
  type: ReplicaSet
  role: AppDB
  opsManager:
    configMapRef:
      name: ${APPDB_PROJECT_CONFIGMAP}
  credentials: ${MANAGEMENT_OM_ADMIN_KEY_SECRET}
  persistent: true
  security:
    authentication:
      enabled: true
      modes: ["SCRAM"]
      ignoreUnknownUsers: true
EOF

kubectl wait --for=jsonpath='{.status.phase}'=Pending \
  mdb/"${APPDB_NAME}" --context "${K8S_CTX}" -n "${MDB_NS}" --timeout=300s
kubectl get mdb "${APPDB_NAME}" --context "${K8S_CTX}" -n "${MDB_NS}" \
  -o jsonpath='{.status.message}{"\n"}'

kubectl patch om "${PRIMARY_OM_NAME}" \
  --context "${K8S_CTX}" -n "${MDB_NS}" \
  --type merge \
  -p "{\"spec\":{\"externalApplicationDatabaseRef\":{\"name\":\"${APPDB_NAME}\",\"kind\":\"MongoDB\"}}}"

kubectl wait --for=jsonpath='{.status.phase}'=Running \
  mdb/"${APPDB_NAME}" --context "${K8S_CTX}" -n "${MDB_NS}" --timeout=1200s
kubectl wait --for=jsonpath='{.status.opsManager.phase}'=Running \
  om/"${PRIMARY_OM_NAME}" --context "${K8S_CTX}" -n "${MDB_NS}" --timeout=1800s

Common Migration Issues

Next Steps

• To back up the external Application Database, enable backup on the MongoDB resource in the project that the management Ops Manager instance manages. To learn more, see Configure MongoDB Database Backups.

• To reverse this migration, see Return an External Application Database to Ops Manager.