mLab Private Environments

Overview

Available for Dedicated plans on AWS only 1

An mLab Private Environment is a dedicated, software-defined network into which you can provision multiple mLab-hosted MongoDB deployments. Using a Private Environment allows you to limit communication between your application and your database to private networks.

When you provision a Private Environment with mLab on AWS, we provision a VPC dedicated to your deployment(s) in mLab’s AWS account(s). You can then have any number of mLab-hosted MongoDB deployments inside of that Private Environment.

Once the Private Environment has been provisioned, you can peer the VPC backing it to the AWS VPC that houses your application infrastructure. This peering operation will create a single, extended, private network consisting of both your application infrastructure and your database deployments.

img-private-environments

Once peered, you can conveniently and scalably design network routing and firewall rules to allow access to your database deployment from only the parts of your application infrastructure that need it.

Managing Private Environments

Users can create and manage one or more Private Environments through the mLab management portal.

Creating a Private Environment

To create a new Private Environment, follow these instructions:

  1. Log in to the mLab management portal
  2. From your account’s Home page, click “Create new” under the “Private Environments” section
  3. You will be prompted for a name, cloud region, and IP address space
    • We recommend naming your Private Environment based on what applications or phase of development it will serve (e.g., Production, Staging, or Test). This name can be changed at any time.
    • The region must be the same as the VPC you are planning to peer with.
  4. Review your choices and when you’re ready, click the “Create new” button. Your new Private Environment will then be listed on your account’s Home page.
  5. Once the Private Environment has been provisioned, you will be able to navigate to its home (administrative) page

Choosing an IP address space

When creating a Private Environment, you will be prompted to supply an IP address space. This is the set of IPs from which all private IPs used in the Private Environment will be drawn.

Changing your Private Environment’s IP address space is an expensive operation. Carefully review the IP address spaces used by your application servers and other products and services to look for potential routing conflicts.

IP address space rules

The IP address space that you supply when creating your mLab Private Environment must conform to the following rules:

(1) It MUST use IPv4 addresses exclusively

IPv4 addresses are 32 bits in size and commonly expressed as four octets written in decimal notation with values between 0 and 255 and dots (‘.’) in between octets, e.g. “192.168.0.1”.

IPv6 addresses are not supported for use in the address space for Private Environments.

(2) It MUST be expressed as a /16 IPv4 CIDR block

You must supply a /16 CIDR block, which is an IP address range that consists of 65,536 IP addresses (2^16 IPs). If, for example, you choose 172.21.0.0/16 for your IP address space, the private IPs of your mLab-hosted deployments in this Private Environment would then range from 172.21.0.0 to 172.21.255.255.

(3) It MUST be a private address space

The address space must be a subspace of the RFC 1918 IPv4 private address space. Specifically:

(4) It MUST NOT overlap with the IP address space of any VPC with which you plan to peer your mLab-hosted VPC

The IP address space that you supply must not overlap with the IP address space of any of your app’s VPCs that you want to or could potentially want to peer with.

For example, let’s say there are two VPCs that you plan to peer with:

You would want to:

(5) It MUST NOT create routing conflicts with transitive networks

The IP address space that you supply should not overlap with the IP address space of any VPC or other private network to which your peered VPC(s) can route. This includes, for example, Docker containers and networks routable via a VPN.

If you do choose to overlap the IP address space with any transitive network, this must not create routing conflicts.

For example, let’s say you were using the following network toplogy:

You would want to:

Other examples of possible transitive networks:

IP address space tips

Avoid these IP address spaces unless you know what you’re doing:

These IP address spaces are not as popular and are the least likely to cause collision:

Peering a Private Environment

To create a new peering connection between your application’s VPC and your mLab Private Environment, follow these instructions:

  1. Log in to the mLab management portal
  2. From your account’s Home page, navigate to the Private Environment that you would like to create a peering connection with
  3. Click the “Peerings” tab
  4. Click the “Add peering connection” button
  5. In the form that appears, provide your AWS account ID and VPC ID
    • This VPC’s region must be the same as your mLab Private Environment’s.
  6. Click “Start peering process” to initiate the peering request
  7. Accept the peering connection from mLab via the AWS console
    • You’ll need to first log in to your AWS account.
    • Navigate to the correct region and the “VPC Dashboard”.
    • Under the “Peering Connections” section, select the peering connection and “Accept Request”.
  8. When the peering connection is complete, you will see “active” for peering connection STATUS.
    • Note that this change can take a few minutes to propagate to mLab’s management console img-peering-success
  9. Add this peering connection to each route table that your app uses

Deleting a Private Environment

To delete your Private Environment, follow these instructions:

  1. Log in to the mLab management portal
  2. From your account’s Home page, navigate to the Private Environment that you would like to delete
  3. Click the “Delete environment” button
  4. Click the “Delete” button

Creating a new deployment in a Private Environment

You can place a new deployment in a Private Environment by selecting a specific Private Environment during the deployment creation process. Otherwise your deployment will be provisioned in EC2-Classic.

When provisioning into a Private Environment, you can provision into either the Public or Private network access mode directly. Documentation about network access modes and how to manage them follows in a section below.

Migrating an existing deployment to a Private Environment

We can seamlessly migrate the data-bearing nodes of any existing Dedicated Cluster deployment into a Private Environment using our rolling node replacement process. This is the same process that we use for plan upgrades/downgrades and compactions which allows you to maintain high availability and requires no changes to connection string(s).

To migrate an existing deployment to a Private Environment, follow these steps:

  1. Create a Private Environment
  2. Ensure you have under 25 firewall rules.
  3. Remove existing inbound allow rules referencing EC2-Classic Security Groups, if any.
    • As part of this, you will need to ensure that your application can still communicate with the deployment. Some options include putting a NAT between your app and database deployment or allowing in a more permissive IP address range.
    • If these options do not work for you or if you have questions, contact support@mlab.com. It’s possible you will need to schedule downtime in order to migrate directly into Private mode.
  4. Contact support@mlab.com to migrate your deployment into the Private Environment using our seamless rolling node replacement process.
    • Note that if your deployment has an arbiter node, it will be migrated to a dedicated virtual machine in the VPC we have provisioned for your Private Environment
  5. (Optional) Transition your deployment from the Public network access mode to one of the Private modes

Managing your deployment’s network

Managing inbound firewall rules

You can specify which IP address ranges should have inbound access to your database deployment. When allowing in a private address, you will need to first select your VPC.

When you add in an additional inbound allow rule, we will make changes to both your firewall and routing rules. Note that in Public mode, we will not apply rules associated with a peered VPC and in Private mode, we will not apply public internet rules.

Follow these instructions to allow in an IP address range:

  1. Log in to the mLab management portal
  2. Navigate to the MongoDB deployment that you want to configure
  3. Click the “Networking” tab
  4. Click the “Add IP rule(s)” button
  5. Select a Network
  6. Enter the IP address range, expressed as an IPv4 CIDR block and optionally, a description for the rule
  7. Click the “Add” button

We allow a max of 25 CIDR block rules. This is a hard limit which cannot be changed.

Managing network access modes

You can choose between three different network access modes for your deployments in a Private Environment: Public, Private (Dual Access), and Private. To switch between network access modes:

  1. Log in to the mLab management portal
  2. Navigate to the MongoDB deployment that you want to configure
  3. Click the “Networking” tab

Network access modes determine:

Public mode

In the Public network access mode, traffic to a deployment via the standard MongoDB connection string URI that we publish is routed via the deployment’s public IP addresses.

Note that this mode also allows you to access the deployment via its private IP addresses. Before switching from Public to Private (Dual Access) mode, you should test connecting to your deployment via private IPs.

Test Private IP access from your VPC before leaving Public mode

From a machine in your VPC, confirm that you can connect to your deployment by appending “-internal” to the leading part of the DNS address. This address is mapped to the private IP address that the deployment’s addresses will be remapped to use when switching to Private mode.

For example, you could test access by connecting via the mongo shell to one of the nodes in your deployment. In this example, the address in your connection string is “ds012345-a0.mlab.com:12345” but you would test the “-internal” version of this address:

% mongo ds012345-a0-internal.mlab.com:12345

If this test fails, ensure that you have opened the firewalls to allow in your client(s) and added the VPC peering connection to your route table(s). For SSL-enabled deployments, if you run into trouble with this test please contact support@mlab.com for help.

You should not change the connection string that your application is using. The “-internal” address that we have made available is to be used only for testing purposes.

Private (Dual Access) mode

In the Private (Dual Access) network access mode, traffic to a deployment via your deployment’s published connection URI using a DNS address (e.g. ds012345-a0.mlab.com) is routed via the deployment’s private IP address. However, this mode still allows you to access the deployment via its public IP address using a single-node (non replica set) connection (see FAQ below on how to connect from your home and/or office).

Before changing to this mode from Public mode, ensure that you have tested private IP address from your VPC (see instructions above).

Private mode

In the Private network access mode, traffic to a deployment via the connection URI using a DNS address, e.g. ds012345-a0.mlab.com, is routed via the deployment’s private IP address. This mode does not allow access to the deployment via its public IP address.

It is common for software components to cache the IP result of DNS name resolutions. If the public IP is cached when you either disallow inbound access from the public internet and/or move to Private mode, your application may encounter errors.

To flush such caches you should restart all processes connecting to your deployment. Doing so will ensure that by the time you transition from Private (Dual Access) mode to Private mode, all of the clients connecting to your deployment are routed using private IPs.

Frequently Asked Questions (FAQ)

Q. Do you charge for VPC peering via your Private Environments feature?

We do not charge extra for our Private Environments feature. In other words, if you choose to peer your VPC with your mLab deployment’s VPC, there is no additional charge.

Q. How do I add my peering connection to my route table(s)?

To obtain the IP address space (CIDR block) of your Private Environment and the AWS peering connection ID:

  1. Log in to the mLab management portal
  2. From your account’s Home page, navigate to your Private Environment
  3. Click the “Peerings” tab

Once you have these two pieces of information, you’ll want to add a route to each route table your application uses.

For more information, read AWS’s documentation on configuring Route Tables. The Destination for the route should be the Private Environment’s CIDR block. The Target for the route should be the AWS peering connection ID for the network peering.

Q. How do I connect to my deployment from home and/or office?

If you need to access your deployment from outside of your peered VPC(s), your deployment must be in either Public or Private (Dual Access) mode; it cannot be in Private mode.

If you’re in the Private (Dual Access) mode you will need to connect using one of the “-external” addresses that we have made available.

For example, let’s say you absolutely need to connect from your office with IP address 199.116.71.90 but you still want your app to exlusively use private routing. You would then:

  1. Ensure that your deployment is in Private (Dual Access) mode

  2. Add 199.116.71.90/32 as an inbound allow rule

  3. Connect from your office using the mongo shell to one of the nodes in your deployment using an “-external” address. If the address in your connection string is “ds012345-a0.mlab.com:12345”, then you would connect using the “-external” version of this address:

      % mongo ds012345-a0-external.mlab.com:12345
    

You will not be able to make a replica set connection to your deployment, only a single-node connection. If you are having trouble connecting using a single-node connection, make sure that your connection string does not include the replicaSet parameter.


  1. Supported AWS regions: us-east-1, us-east-2, eu-west-1, us-west-2, ap-southeast-2