Migration scenarios for Azure DocumentDB

The public and private connectivity scenarios in this article apply to Azure Database Migration Service-based migrations created by using either the Azure DocumentDB Migration Extension or the Azure Database Migration Service experience in the Azure portal.

Azure Database Migration Service (DMS) runs the migration and manages the network connection between your source environment and Azure DocumentDB. DMS supports MongoDB instances running in Azure, on-premises datacenters, and other cloud providers. This article also describes a self-hosted Kubernetes option for environments that can't use DMS.

Supported source environments

The following table summarizes the supported migration sources:

Source environment Description
Within Azure MongoDB instances running on Azure Virtual Machines or other Azure-hosted services
On-premises MongoDB servers running in your local data center or private infrastructure
Other cloud providers MongoDB instances hosted on other cloud platforms
Amazon DocumentDB Amazon DocumentDB (with MongoDB compatibility) instances hosted on AWS

Public connectivity

In public connectivity mode, the Azure Database Migration Service (DMS) connects to your source and target servers over the public internet. DMS provides static IP addresses that you add to the firewall allow lists on both the source and target servers. DMS uses a shared public virtual network for all migrations within a given region. While this virtual network is shared across customers, each migration job runs on its own isolated private worker node to ensure job-level isolation.

Use public connectivity when:

  • Your source and target servers are accessible through public IP addresses.
  • Your organization's security policies allow connections over the public internet.
  • You need a simpler setup without virtual network configuration.

Diagram showing network architecture for public connectivity.

Private connectivity

In private connectivity mode, DMS provisions a dedicated private virtual network for each migration job and peers it with your source and target virtual networks. This setup means every job gets both isolated worker nodes and an isolated network, ensuring that no traffic crosses between jobs and no shared network paths exist between customers.

The DMS migration experience supports up to two virtual networks:

  • Source virtual network: The virtual network where your source MongoDB server is accessible.
  • Target virtual network: The virtual network where your Azure DocumentDB cluster is accessible.

Use private connectivity when:

  • Your source or target servers aren't accessible over the public internet.
  • Your organization requires all traffic to flow through private networks.
  • You need to avoid public internet exposure.

Private connectivity relies on DMS to provision a Microsoft-hosted virtual network that peers with your networks. If your organization's policies don't allow connectivity from a Microsoft-hosted virtual network, use the self-hosted migration with Kubernetes option instead.

Important

A single virtual network can support only one active migration job at a time when connectivity mode is private. To run multiple concurrent jobs, use different virtual networks for each job.

Complete the following requirements before starting the migration job:

  • Disable network policies on the private endpoint subnet. Subnet-level private endpoint network policies can block traffic originating from the DMS virtual network. Disable them on the subnet that hosts the target Azure DocumentDB private endpoint: 
    az network vnet subnet update \
   --subscription "<SUBSCRIPTION>" -g "<TARGET_RG>" \
   --vnet-name "<TARGET_VNET>" -n "<PRIVATE_ENDPOINT_SUBNET>" \
   --disable-private-endpoint-network-policies true
  • Grant the DMS principal read access on the hub's virtual network gateway. When DMS peers with the hub, it validates the gateway configuration to use useRemoteGateways. Assign the Reader role on the VPN or ExpressRoute gateway resource to the DMS service principal. Without this access, the peering setup step in the wizard fails.
  • Allow list the DMS CIDR end-to-end. Add the DMS CIDR shown in the migration wizard to your on-premises firewalls, NSGs in the path, and any ExpressRoute route filters. If any device in the path doesn't recognize the range, return traffic from the source is dropped.
  • Remove resource locks that affect the source or target virtual network. A resource lock on the source or target virtual network, or the source or target resource group, can prevent DMS from deleting the source-to-DMS or target-to-DMS peering after a job finishes. The leftover peering causes a new migration that uses the same CIDR range to fail. Remove the lock before the migration, and reapply it after DMS cleans up the peering.
  • Don't rely on custom on-premises DNS for the peered network. On-premises DNS servers can't resolve Azure private DNS zone records for the DMS-peered hub. Use an IP-based connection string for the source in the migration job to skip DNS.

Why you select virtual networks and a CIDR range

Private connectivity works by placing DMS inside your private network space so it can reach your source and target over private IP addresses instead of the public internet. To do that, DMS needs two things from you: the virtual networks to connect to, and a CIDR range for its own network. Understanding what each one does helps you avoid the most common setup mistakes.

What the virtual network selections do

DMS can't see your private endpoints on its own. When you select a source virtual network and a target virtual network, DMS creates its own dedicated virtual network and peers it with the networks you selected. Peering is what builds the private path: after peering, DMS can resolve and reach the source MongoDB server and the target Azure DocumentDB cluster over their private IPs.

The virtual network you pick for each side must be the one that actually provides a network path to that endpoint:

  • Source: Select the virtual network from which the source MongoDB server is reachable over a private IP. If your source is on-premises or in another cloud, this network holds (or routes to) the VPN/ExpressRoute gateway. If the source is in Azure behind a private endpoint, select the virtual network that contains that private endpoint.
  • Target: Select the virtual network from which the Azure DocumentDB private endpoint is reachable.

Selecting a virtual network that looks related but doesn't have a route to the endpoint is the most frequent mistake. Peering succeeds, but traffic never reaches the source or target because there's no underlying route.

What the CIDR range does

The dedicated virtual network that DMS creates needs its own private IP address space, and you supply that address space as a CIDR range (for example, 10.240.0.0/24). DMS assigns its worker nodes addresses from this range, and those addresses become the source of all migration traffic. This is why the CIDR range appears throughout the validation and firewall steps.

The CIDR range must not overlap with any network it needs to reach. If the DMS CIDR overlaps with your source virtual network, target virtual network, or any on-premises range reachable through your gateway, the network can't tell whether an address is local or remote, so peering fails or traffic is silently misrouted.

Because the CIDR range is the source of all migration traffic, you must also allow it through every firewall or network security group (NSG) that protects the source or target. Add the CIDR range to the source MongoDB firewall, the Azure DocumentDB firewall, and any on-premises or other-cloud firewall in the network path. If the CIDR isn't allowlisted, the traffic is blocked even when peering and routing are correct.

Common mistakes to avoid

  • Selecting the wrong virtual network. Choose the virtual network that has a real route to the endpoint, not just one with a similar name or in the same resource group.
  • Choosing an overlapping CIDR. Pick a range that doesn't overlap with your source virtual network, target virtual network, or on-premises address space. Check the existing address spaces first.
  • Not allowlisting the CIDR through your firewalls. Add the DMS CIDR range to every firewall and NSG that protects the source or target. Traffic is blocked if the CIDR isn't on the allow list, even when peering succeeds.
  • Choosing a CIDR that's too small. Provide a range large enough for the DMS worker nodes (a /24 is a safe default). A range that's too small can cause provisioning to fail.
  • Reusing a CIDR that's still in use. If you built a simulation environment to validate connectivity, remove it before starting the real job. A leftover network using the same CIDR conflicts with the one DMS tries to create.

For step-by-step validation of these selections, see Troubleshoot connectivity.

From other cloud providers or on-premises

Use your preferred VPN tools to set up network connectivity between Azure and your source environment in another cloud or on-premises. The following topologies are supported depending on your network architecture.

Single virtual network

In this topology, the VPN/ExpressRoute gateway and source workloads are in the same virtual network. DMS peers directly with this virtual network and uses useRemoteGateways to reach the on-premises or other-cloud source.

Diagram showing single virtual network topology for private connectivity from on-premises or other cloud.

Hub-direct

In this topology, the VPN/ExpressRoute gateway is in a dedicated hub virtual network. DMS peers directly with the hub, so it can use the gateway natively via useRemoteGateways.

Diagram showing hub-direct topology for private connectivity from on-premises or other cloud.

Hub-spoke with TCP proxy

If DMS can only peer to a spoke virtual network and direct hub peering isn't possible, deploy a MongoDB migration proxy VM in the DMS-peered spoke. The proxy forwards traffic from DMS to the source MongoDB server through the hub's VPN/ExpressRoute gateway.

Add an inbound security rule to the network security group (NSG) that protects the proxy. Set Source to the DMS CIDR range that you provide in the migration wizard, and allow TCP traffic to the proxy's listening port. Without this rule, the proxy can't receive requests from the DMS virtual network.

Diagram showing hub-spoke topology with TCP proxy for private connectivity from on-premises or other cloud.

Note

DMS creates an ephemeral virtual network that peers to your networks. In enterprise hub-and-spoke topologies, virtual network peering is non-transitive, DMS can't reach a hub VPN gateway through a spoke virtual network automatically. You need a routing mechanism such as direct hub peering or a TCP proxy deployed in the DMS-peered virtual network. For validation steps, see Troubleshoot connectivity.

From a private endpoint in Azure

Set up private endpoints for the source and target virtual networks.

Diagram showing network architecture for private connectivity within Azure.

Self-hosted migration with Kubernetes

Both public and private connectivity rely on Azure Database Migration Service (DMS), which runs in a Microsoft-hosted virtual network. Some environments don't allow inbound connectivity from a Microsoft-hosted virtual network. In these cases, use the self-hosted, Kubernetes-based web application to run the migration entirely within your own infrastructure. The self-hosted tool runs the same migration code as the hosted DMS solution; only the hosting environment differs.

Use self-hosted migration when:

  • Your organization's security policies don't allow connectivity from a Microsoft-hosted virtual network.
  • You need full control over the compute and network path used for the migration.

The self-hosted web application migrates any MongoDB source to Azure DocumentDB by using your own Kubernetes cluster. Download and install it from the AzureDocumentDBMigration-K8s repository, then follow the setup instructions in that repository.

Related content

  • Last updated on