> This page location: /docs.md > /docs/management.md > /docs/kubernetes/current.md > /docs/kubernetes/current/om-resources.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Migrate an Application Database to an External Deployment

You can convert an Ops Manager resource that uses an internally managed Application Database to one that uses an **external** Application Database: a MongoDB custom resource with `spec.role` set to `AppDB`. This lets Ops Manager back up and restore the Application Database. To learn more, see [Back Up the Ops Manager Application Database.](https://www.mongodb.com/docs/kubernetes/current/tutorial/om-appdb-backup.md#std-label-om-appdb-backup)

The migration re-points ownership of the existing Application Database StatefulSet and its [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) from the Ops Manager resource to the MongoDB resource. The Kubernetes Operator doesn't move or recreate your data, and it doesn't restart the Ops Manager pods.

## 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`](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-om-specification.md#mongodb-opsmgrkube-opsmgrkube.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.](https://www.mongodb.com/docs/kubernetes/current/tutorial/install-k8s-operator.md#std-label-install-k8s-operator)

- Deploy a primary Ops Manager resource that uses an internally managed Application Database. This resource sets [`spec.applicationDatabase`](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-om-specification.md#mongodb-opsmgrkube-opsmgrkube.spec.applicationDatabase), and the Kubernetes Operator owns a StatefulSet named `<primary-om-name>-db`. To learn more, see [Deploy an Ops Manager Resource.](https://www.mongodb.com/docs/kubernetes/current/tutorial/deploy-om-container.md#std-label-deploy-om-container)

- 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.](https://www.mongodb.com/docs/kubernetes/current/tutorial/deploy-om-external-appdb.md#std-label-deploy-om-external-appdb)

- Create credentials for the Kubernetes Operator. The [secret](https://kubernetes.io/docs/concepts/configuration/secret/) holds the programmatic API (Application Programming Interface) key pair that the Kubernetes Operator uses to authenticate to the management Ops Manager API (Application Programming Interface) on your behalf. You can give the secret any name. To learn more, see [Create Credentials for the Kubernetes Operator.](https://www.mongodb.com/docs/kubernetes/current/tutorial/create-operator-credentials.md#std-label-create-k8s-secret)

## 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.

- To migrate a multi-cluster Application Database, the internally managed Application Database must set `spec.applicationDatabase.topology` to `MultiCluster`, and the external Application Database must be a MongoDBMultiCluster resource. The Kubernetes Operator rejects the migration if the topology of the current Application Database doesn't match the kind of the external Application Database. To learn more, see [Migrate a Multi-Cluster Application Database.](https://www.mongodb.com/docs/kubernetes/current/tutorial/migrate-appdb-to-external.md#std-label-migrate-appdb-to-external-multi-cluster)

## Procedure

1. Set the environment variables for the migration.

   ```sh
   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="<your-operator-credentials-secret>"

   export APPDB_PROJECT_CONFIGMAP="${APPDB_NAME}-config"
   export APPDB_PROJECT_NAME="external-appdb"
   ```

2. Confirm the starting state.

   Confirm that the primary Ops Manager resource and its internally managed Application Database are in the `Running` phase:

   ```sh
   kubectl get om "${PRIMARY_OM_NAME}" --context "${K8S_CTX}" -n "${MDB_NS}" \
     -o jsonpath='{.status.opsManager.phase} / appdb={.status.applicationDatabase.phase}{"\n"}'
   ```

   Confirm that the Ops Manager resource owns the Application Database StatefulSet:

   ```sh
   kubectl get statefulset "${APPDB_NAME}" --context "${K8S_CTX}" -n "${MDB_NS}" \
     -o jsonpath='{range .metadata.ownerReferences[*]}{.kind}/{.name}{"\n"}{end}'
   ```

   The command returns `MongoDBOpsManager/${PRIMARY_OM_NAME}`.

3. Create the project ConfigMap for the external Application Database.

   The `orgId` value is required. If you set it to an empty string, the Kubernetes Operator creates an organization with the same name as your project.

   ```sh
   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=""
   ```

4. Create the MongoDB resource for the external Application Database.

   Give the resource the same name as the existing Application Database StatefulSet.

   ```sh
   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
   ```

5. Confirm that the MongoDB resource waits for ownership.

   Until the Ops Manager resource releases the StatefulSet, the MongoDB resource stays in the `Pending` phase. This is expected and isn't an error.

   ```sh
   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"}'
   ```

   The status message reports that the resource can't take ownership of the Application Database StatefulSet.

6. Add the external Application Database reference to the Ops Manager resource.

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

   You can remove [`spec.applicationDatabase`](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-om-specification.md#mongodb-opsmgrkube-opsmgrkube.spec.applicationDatabase) in the same patch. Leaving it in place has no effect: once you set [`spec.externalApplicationDatabaseRef`](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-om-specification.md#mongodb-opsmgrkube-opsmgrkube.spec.externalApplicationDatabaseRef), the Kubernetes Operator stops managing an internal Application Database for this resource.

7. Wait for the migration to finish.

   ```sh
   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
   ```

8. Verify the migration.

   Confirm that the MongoDB resource owns the Application Database StatefulSet:

   ```sh
   kubectl get statefulset "${APPDB_NAME}" --context "${K8S_CTX}" -n "${MDB_NS}" \
     -o jsonpath='{range .metadata.ownerReferences[*]}{.kind}/{.name}{"\n"}{end}'
   ```

   The command returns `MongoDB/${APPDB_NAME}`.

   Confirm that the Ops Manager resource reports its Application Database as `Disabled`, which means that the Kubernetes Operator no longer manages an internal Application Database for it:

   ```sh
   kubectl get om "${PRIMARY_OM_NAME}" --context "${K8S_CTX}" -n "${MDB_NS}" \
     -o jsonpath='{.status.applicationDatabase.phase}{"\n"}'
   ```

   Confirm that the Ops Manager pods didn't restart by checking their age and restart counts:

   ```sh
   kubectl get pods --context "${K8S_CTX}" -n "${MDB_NS}"
   ```

## Migrate a Multi-Cluster Application Database

If the primary Ops Manager resource uses an internally managed multi-cluster Application Database, you can migrate it to an external MongoDBMultiCluster resource. The Kubernetes Operator detaches the Application Database StatefulSet in each [member cluster](https://www.mongodb.com/docs/kubernetes/current/multi-cluster-overview.md#std-label-central-and-member-clusters), and the MongoDBMultiCluster resource adopts each one. The Ops Manager pods don't restart, because the connection string doesn't change.

The procedure matches the single-cluster procedure on this page, with the following differences:

- The internally managed Application Database must set `spec.applicationDatabase.topology` to `MultiCluster`.

- The external Application Database must be a MongoDBMultiCluster resource with `spec.role` set to `AppDB`, with the same name, member layout, and TLS (Transport Layer Security) configuration as the internally managed Application Database. A multi-cluster external Application Database requires TLS (Transport Layer Security) encryption and cross-cluster networking between the member clusters, with or without a service mesh. To learn more, see [Deploy a Multi-Cluster External Application Database.](https://www.mongodb.com/docs/kubernetes/current/tutorial/deploy-om-external-appdb-multi-cluster.md#std-label-deploy-om-external-appdb-multi-cluster)

- Set `kind` to `MongoDBMultiCluster` when you add [`spec.externalApplicationDatabaseRef`:](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-om-specification.md#mongodb-opsmgrkube-opsmgrkube.spec.externalApplicationDatabaseRef)

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

- The Kubernetes Operator performs the ownership handover in each member cluster. To verify the migration, inspect the Application Database StatefulSet in each member cluster, named `<primary-om-name>-db-<cluster-index>`:

  ```sh
  kubectl get statefulset "${APPDB_NAME}-0" --context "${K8S_CTX_MEMBER}" -n "${MDB_NS}" \
    -o jsonpath='{.metadata.labels.mongodbmulticluster}{"\n"}'
  ```

  The command returns `<namespace>-<appdb-name>`, and the `mongodb.com/appdb-migration-ready` annotation is cleared. To learn more about ownership tracking in multi-cluster deployments, see [Migration Annotations.](https://www.mongodb.com/docs/kubernetes/current/tutorial/om-appdb-backup.md#std-label-om-appdb-backup-annotations)

## Common Migration Issues

### The MongoDB Resource Reports a Version Error

If the MongoDB resource reports `Failed` with a message that the MongoDB version isn't available, set [`spec.version`](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-specification.md#mongodb-setting-spec.version) to a version that the management Ops Manager instance offers, and keep the Ops Manager version and the Application Database version on the same major version.

### The MongoDB Resource Stays Pending After the Patch

The Kubernetes Operator must detach the StatefulSet before the MongoDB resource can take ownership of it. Confirm that you applied [`spec.externalApplicationDatabaseRef`](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-om-specification.md#mongodb-opsmgrkube-opsmgrkube.spec.externalApplicationDatabaseRef) to the primary Ops Manager resource, and that the value of [`spec.externalApplicationDatabaseRef.name`](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-om-specification.md#mongodb-opsmgrkube-opsmgrkube.spec.externalApplicationDatabaseRef.name) is exactly `<primary-om-name>-db`.

### The MongoDB Resource Reports a Project Error

If the MongoDB resource stays in the `Pending` phase with a project or registration error, the management Ops Manager public API (Application Programming Interface) might not have been ready when you created the resource. Confirm that the management Ops Manager resource is in the `Running` phase and that its API (Application Programming Interface) answers requests, then reconcile the resource again.

### The Ops Manager Pods Restart During the Migration

If the Ops Manager pods restart, the computed connection string changed. For a replica set that uses the default port, the connection string is identical before and after the migration. The Kubernetes Operator doesn't support non-default ports for this migration.

## 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.](https://www.mongodb.com/docs/kubernetes/current/tutorial/back-up-mdb-resources.md#std-label-back-up-mdb-resources)

- To reverse this migration, see [Return an External Application Database to Ops Manager.](https://www.mongodb.com/docs/kubernetes/current/tutorial/migrate-appdb-to-internal.md#std-label-migrate-appdb-to-internal)
