mLab Private Environments (VPC)

Overview

Available for Dedicated plans on AWS only

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

You have now successfully peered your application’s VPC to the mLab-hosted VPC. In order to actually connect to your database, you’ll still need to open up your mLab-hosted deployment’s firewall to your VPC by adding inbound allow rules which whitelist an IP address range or Security Group within your VPC.

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.

Managing deployments within Private Environments

Creating a new deployment

You can place a new deployment in a Private Environment by selecting a specific Private Environment during the deployment creation process.

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 from EC2-Classic

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. Log in to the mLab management portal.
  2. Navigate to the MongoDB deployment that you want migrated to a Private Environment.
  3. Click the “Networking” tab.
  4. Ensure you have under 25 firewall rules.
  5. Remove existing inbound allow rules within 10.0.0.0/8 (EC2-Classic) and 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, stop here and contact support@mlab.com. It’s possible you will need to schedule downtime in order to migrate directly into Private mode.
  6. Click the “Tools” tab.
  7. Under the “Initiate maintenance operation” header, select the “Migrate to a Private Environment (EC2-VPC)” option.
  8. In the options that follow, first choose the desired Private Environment.
    • You can choose an existing Private Environment already created for your mLab account (they will be listed here by name).
    • You can create a new Private Environment which will prompt you for a name 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.
  9. Next, choose a failover option.
    • A failover will be required to complete this process. If you are not confident that your clients have been configured with a replica set connection that can handle failover and/or you’d like to be conservative with this maintenance, we recommend the first option which is to initiate the failover yourself. This way you can fail back over to your original Primary in case of an unexpected issue.
  10. Click the “Migrate to a Private Environment” button which will open a confirmation window. Once you confirm the migration process, the seamless rolling node replacement process will begin.
    • 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.
    • If you have chosen to initiate the failover yourself, you will need to perform the failover before the migration to a Private Environment can be completed. Check your email (or the Technical Contact’s email) for maintenance updates.
  11. (Optional) Transition your deployment from the Public network access mode to one of the Private modes

Managing inbound firewall rules

You can specify which IP address ranges or Security Groups within your VPC should have inbound access to your database deployment.

When you add in an additional inbound allow rule, we will make changes to both your firewall and routing 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 address range rule(s)”.
  5. Select a Network.
    • When allowing in private IP addresses, select the VPC of the private IP addresses.
    • When allowing public IP addresses, select “Public Internet”.
  6. Enter the IP address range, expressed as an IPv4 CIDR block and optionally, a description for the rule.
  7. Click the “Add” button.

Follow these instructions to allow in a Security Group within your VPC:

  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 Security Group rule”.
  5. In the “Network” field, select the VPC of the Security Group.
  6. Enter the Security Group’s ID and optionally, a description for the rule.
  7. Click the “Add” button.

Copy firewall rules from an existing deployment

For convenience, you can use the “Copy existing rules” button to copy firewall rules from an existing deployment within the same Private Environment as your deployment. This saves you the effort of having to add each firewall rule one by one.

Follow these instructions to copy existing inbound allow rules from an existing deployment:

  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 “Copy existing rules”.
  5. Select the deployment from which you want to replace the firewall rules with.
  6. Click the “Submit” button.
  7. Optionally, you can make additional changes to the firewall rules.
  8. Click the “Apply security changes” button to apply the firewall rules.
    • If you want to revert back to the firewall rule(s) before the copy, click the “Revert changes” link.

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, review the troubleshooting section below on peered connection issues. In particular, ensure that you have added the VPC peering connection to your route table(s) and that you’ve added your application’s VPC to your firewall whitelist (an inbound allow rule to 0.0.0.0/0 over the Public Internet is not sufficient).

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.

Steps to move out of “Public” network access mode

When a deployment is provisioned in a Private Environment, it can be configured to be in “Public” network access mode. When you are ready to move it to one of the private mode (i.e. “Private (Dual Access)” or “Private”) and allow communication between your application and the deployemnt to happen via VPC Peering, there are a few required setups to follow. The setup steps are:

  1. Verify that your application is running within a VPC (i.e. on a EC2-VPC instance type) and is in the same region as your deployment.
  2. Create a new peering connection between your application’s VPC and your deployment’s Private Environment/VPC.
  3. Log into your AWS account to accept the peering connection request that was created from Step #2
  4. Add the peered connection ID created in Step #2 to the route table that your application uses.
  5. Set up inbound allow rule(s) to allow private network traffic from your VPC to your deployment.
  6. Test that you are able to access the deployment from within your peered VPC using the deployment’s -internal address. See section “Test Private IP access from your VPC before leaving Public mode”.
  7. Once you have confirmed Step #6, change access mode from Public to Private (Dual Access).

Once you are in “Private (Dual Access)” mode, you may move into “Private” network access mode which will disable all access to the deployment via its public IP address.

If you run into any issues, the following section on troubleshooting peered connection issues may help, or contact us anytime at support@mlab.com.

Troubleshooting peered connection issues

If you are having trouble connecting to your database in a Private Environment via a peering connection, please review the following troubleshooting steps.

Temporarily return to Public mode if you started having trouble only after switching to a Private mode

If your application was able to connect while your deployment was in Public mode but unable to in one of the Private modes, we highly recommend switching back to Public mode temporarily.

Once you’re in Public mode again, be sure to review the “Test Private IP access from your VPC before leaving Public mode” section of the Public mode documentation above before trying to switch to Private (Dual Access) mode.

Ensure the peering connection is “active”

Verify that the peered connection between your VPC and the Private Environment’s VPC for your deployment is “active.” To do this:

  1. Navigate to the Peerings tab for your Private Environment.
  2. Make sure the status for your peering connection is “active”.
    • If the status is not “active”, please review Step 7 from the Peering a Private Environment section above to accept the request to peer connection with mLab.

Ensure the peering connection has been added to the route table used by your application

Verify that you have added the peering connection (pcx-xxxxx) to the route table used by your application. See Step 9 from section Peering a Private Environment above.

Ensure that you added your application’s VPC to your firewall whitelist

Make sure that you have set up inbound allow rule(s) to allow private network trafffic from your VPC to your deployment.

If you are still having trouble connecting, and you whitelisted an IP address range to your application’s VPC, verify the private IP address of the machine you’re connecting from by running the following command on the machine you are trying to connect from.

% curl http://169.254.169.254/latest/meta-data/local-ipv4

This private IP address should be within an IP address range defined in your deployment’s inbound allow rules.

Also, ensure that your database and application are in the same AWS region. Confirm the region of the machine that you’re trying to connect from by running:

% curl http://169.254.169.254/latest/meta-data/placement/availability-zone

If you are still having trouble connecting, and you whitelisted a Security Group in your application’s VPC, verify that the machine you’re connecting from really is part of the Security Group that you whitelisted.

Still having problems?

If you’re still having problems connecting, contact us at support@mlab.com and be sure to include your deployment’s identifier as well as relevant details (output, error messages, etc.) from the troubleshooting steps above.

Frequently Asked Questions (FAQ)

Q. Can my database run in a Private Environment but still be publicly accessible (i.e., without VPC Peering)?

Yes. To do so, place your deployment in Public network access mode. Be sure to also configure your database’s firewall rules on the “Networking” tab to allow in traffic from the public internet.

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)?

For more information, read AWS’s documentation on configuring Route Tables.

The “Destination” for the route in AWS’s route table should be the Private Environment’s IP address range. You can find this value in the “IP address range” field in the upper left area of your Private Environment page in mLab’s mangagement portal (e.g., “172.21.0.0/16”).

The “Target” for the route in AWS’s route table should be the AWS peering connection ID. You can find this value under the “PEERING CONNECTION” column, in the “Peerings” tab after navigating to your Private Environment page in mLab’s management portal (e.g., “pcx-a1b23456”).

Q. Why can’t I configure inbound allow rules from different VPCs with overlapping IP address ranges?

Routers route data based on IP address only; they do not have the context of a target VPC. Therefore, if you were to peer VPCs with overlapping IP addresses, the routing rules from the deployment’s perspective would be ambiguous.

As such, you need to configure your peered VPC(s) to avoid overlapping IP address spaces.

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.