Navigation

Set up a Private Endpoint

Feature unavailable in Free and Shared-Tier Clusters

This feature is not available for M0 (Free Tier), M2, and M5 clusters. To learn more about which features are unavailable, see Atlas M0 (Free Tier), M2, and M5 Limitations.

MongoDB Atlas supports private endpoints on AWS using the AWS PrivateLink feature. When you enable this feature, Atlas creates its own VPC and places clusters within a region behind a network load balancer in the Atlas VPC. Then you create resources that establish a one-way connection from your VPC to the network load balancer in the Atlas VPC using a private endpoint.

Image showing how AWS PrivateLink establishes connections from your application VPC to resources in the |service| VPC.

Connections to Atlas clusters using private endpoints offer the following advantages over other network access management options:

  • Connections using private endpoints are one-way. Atlas VPCs can’t initiate connections back to your VPCs. This ensures your network trust boundary is not extended.
  • Connections to private endpoints within your VPC can be made transitively from:
    • Another VPC peered to the private endpoint-connected VPC.
    • An on-premises data center connected with DirectConnect to the private endpoint-connected VPC. This enables you to connect to Atlas directly from your on-premises data center without whitelisting public IP addresses.

Considerations

High Availability

To ensure AWS PrivateLink connections to Atlas can withstand an availability zone outage, you should deploy VPC subnets to multiple availability zones in a region.

Private Endpoint-Aware Connection Strings

When you enable AWS PrivateLink, Atlas generates an SRV record for your VPC. This SRV record resolves to the interface endpoint ENIs deployed in the VPC subnets you specified when you created the AWS PrivateLink connection. The interface endpoint ENIs connect to the network load balancer provisioned in the Atlas VPC. The network load balancer assigns a unique port to each Atlas cluster node in the region for which you enabled AWS PrivateLink.

Clients connecting to Atlas clusters using AWS PrivateLink use private endpoint-aware connection strings containing SRV records:

mongodb+srv://cluster0-pl-0-k45tj.mongodb.net/test

The SRV record used in a private endpoint-aware connection string contains a configuration that maps a unique port for each member in a cluster’s replica set to that hostname. The ports listed correspond to ports on the load balancer provisioned in the Atlas VPC. When you connect using AWS PrivateLink, all nodes in an Atlas cluster are accessible via the same hostname, with the load balancer resolving individual nodes by their port.

The following example shows a DNS lookup of the SRV record for a AWS PrivateLink-enabled single-region cluster, showing three unique ports defined for the cluster0-pl-0-k45tj.mongodb.net hostname:

$ nslookup -type=SRV _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net

Server: 127.0.0.53
Address: 127.0.0.53#53

Non-authoritative answer:
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 3 pl-0-us-east-1-k45tj.mongodb.net.
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1 pl-0-us-east-1-k45tj.mongodb.net.
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 2 pl-0-us-east-1-k45tj.mongodb.net.

The hostname that the SRV record contains is a CNAME record that resolves to the endpoint-specific regional DNS name AWS generates for the interface endpoint in your VPC. An alias record exists for each subnet in your VPC that you deployed the interface endpoint to. Each alias record contains the private IP address of the interface endpoint ENI for that subnet in your VPC.

The following example shows the DNS lookup for the hostname in the SRV record, including the endpoint-specific regional DNS name for the interface endpoint and its alias records:

$ nslookup pl-0-us-east-1-k45tj.mongodb.net
Server: 127.0.0.53
Address: 127.0.0.53#53

Non-authoritative answer:
pl-0-us-east-1-k45tj.mongodb.net
canonical name = vpce-024f5b57108c8d3ed-ypwbxwll.vpce-svc-02863655456245e5c.us-east-1.vpce.amazonaws.com.

Name: vpce-024f5b57108c8d3ed-ypwbxwll.vpce-svc-02863655456245e5c.us-east-1.vpce.amazonaws.com
Address: 10.0.30.194
Name: vpce-024f5b57108c8d3ed-ypwbxwll.vpce-svc-02863655456245e5c.us-east-1.vpce.amazonaws.com
Address: 10.0.20.54

When a client in your VPC connects to an Atlas cluster using a private endpoint-aware connection string, the client attempts to establish a connection to the load balancer in the Atlas VPC through one of the interface endpoint ENIs. Your client’s DNS resolution mechanism handles which of the interface endpoint ENIs the hostname resolves to. If one ENI is unavailable the next is used. This is opaque to the driver or other connection mechanism. The driver is only aware of the hostname in the SRV record, listening on one port for each node in the cluster’s replica set.

See Connect to Atlas using a Private Endpoint to learn how to connect to Atlas clusters using private endpoint-aware connection strings.

IP Whitelists and VPC Peering with Private Endpoints

When Private Endpoints are enabled, you can still enable access to your Atlas clusters using other methods, such as public IP whitelisting and VPC peering.

Clients connecting to Atlas clusters using other methods use standard connection strings. Your clients might have to identify when to use private endpoint-aware connection strings and standard connection strings.

Limitations

  • You can’t use AWS PrivateLink to connect to Atlas clusters running MongoDB version 3.6 or earlier.

  • AWS PrivateLink must be active in all regions into which you deploy a multi-region cluster. You receive an error if AWS PrivateLink is active in some, but not all, targeted regions.

  • If you create private endpoints in more than one region, you can’t create more than one private endpoint in each region. If you create more than one private endpoint in a single region, you can’t create private endpoints in other regions.

  • You can use AWS PrivateLink in Atlas projects with up to 50 addressable targets per region. Use additional projects or regions to connect to addressable targets beyond this limit in the same region.

    Addressable targets include:

    • Each node in a replica set, excluding nodes that comprise a shard in a sharded cluster.
    • Each mongos instance for sharded clusters.
    • Each BI Connector for Atlas instance across all dedicated clusters in the project.

    Note

    To request a one-time increase to use AWS PrivateLink with up to 100 addressable targets per Atlas project, contact MongoDB Support.

  • When you delete all AWS PrivateLink endpoints for a region in Atlas, you must manually delete the private endpoint. AWS lists the endpoint as rejected. Atlas can’t delete this resource because it lacks the required permissions.

Prerequisites

To enable connections to Atlas using private endpoints, you must:

  1. Have either the Project Owner or Organization Owner role in Atlas.
  2. Have an AWS user account with an IAM user policy that grants permissions to create, modify, describe, and delete endpoints. For more information on controlling the use of VPC endpoints, see the AWS Documentation.
  3. (Recommended): Install the AWS CLI.
  4. If you have not already done so, create your VPC and EC2 instances in AWS. See the AWS documentation for guidance.

Procedures

Configure an Atlas Private Endpoint

Enable clients to connect to Atlas clusters using private endpoints with the following procedure:

1

In the Security section of the left navigation, click Network Access.

2
3

Select the AWS region in which you want to create the Atlas VPC, then click Next.

You must select the same region in which your AWS VPC resides.

Note

If your organization has no payment information stored, Atlas prompts you to add it before continuing.

Atlas creates VPC resources in the region you selected. This might take several minutes to complete.

4

Create the Atlas VPC Endpoint and your VPC Endpoint Interface.

  1. Enter the following details about your AWS VPC:

    Your VPC ID Unique identifier of the peer AWS VPC. Find this value on the VPC dashboard in your AWS account.
    Your Subnet IDs Unique identifiers of the subnets your AWS VPC uses. Find these values on the Subnet dashboard in your AWS account.
  2. Copy the command the dialog displays and run it using the AWS CLI.

    Note

    You can’t copy the command until Atlas finishes creating VPC resources in the background.

    See Creating an Interface Endpoint to perform this task using the AWS CLI.

    AWS creates the private endpoint and connects it from your VPC to the Atlas VPC using the details you provided.

  3. You may receive an error like the following when you create the private endpoint:

    An error occurred (InvalidParameter) when calling the CreateVpcEndpoint
    operation: The VPC endpoint service com.amazonaws.vpce.us-east-1.vpce-svc-<...>
    does not support the availability zone of the subnet: subnet-<...>.
    

    If you receive this error, Atlas has deployed VPC resources into different availability zones than the ones to which you deployed your VPC subnets. To resolve this error:

    1. Describe the service endpoint on the service-name from the command displayed in the CLI command in the Atlas UI.
    2. Deploy a VPC subnet into at least one of the availability zones the service endpoint supports.
    3. Create the private endpoint again using the VPC subnet IDs you deployed into the supported availability zones. If you’re using the AWS CLI, Replace the Subnet IDs in the Atlas UI with the VPC subnets you deployed. Copy the displayed command again, then run it using the AWS CLI.
  4. Click Next.

5

Create the Application VPC Endpoint.

  1. Enter your VPC Endpoint ID. This is a 22-character alphanumeric string that identifies your private endpoint. Find this value on the AWS VPC Dashboard under Endpoints > VPC ID.
  2. Click Create.
6

Configure your resources’ security groups to send traffic to and receive traffic from the VPC endpoint.

For each resource that needs to connect to your Atlas clusters using AWS PrivateLink, the resource’s security group must allow outbound traffic to the VPC endpoint’s private IP(s) on all ports.

See Adding Rules to a Security Group for more information.

7

Create a security group for your VPC endpoint to allow resources to access it.

This security group must allow inbound traffic on all ports from each resource that needs to connect to your Atlas clusters using AWS PrivateLink:

  1. In the AWS console, navigate to the VPC Dashboard.
  2. Click Security Groups, then click Create security group.
  3. Use the wizard to create a security group. Make sure you select your VPC from the VPC list.
  4. Select the security group you just created, then click the Inbound Rules tab.
  5. Click Edit Rules.
  6. Add rules to allow all inbound traffic from each resource in your VPC that you want to connect to your Atlas cluster.
  7. Click Save Rules.
  8. Click Endpoints, then click the endpoint for your VPC.
  9. Click the Security Groups tab, then click Edit Security Groups.
  10. Add the security group you just created, then click Save.

To learn more about VPC security groups, see the AWS documentation.

8

Connect to Atlas using a Private Endpoint

You use a private endpoint-aware connection string when you connect to Atlas clusters using a private endpoint:

mongodb+srv://cluster0-pl-0-k45tj.mongodb.net/test

Note

For important considerations about private endpoint-aware connection strings, see Private Endpoint-Aware Connection Strings.

Use a private endpoint-aware connection string to connect to an Atlas cluster with the following procedure:

1

Open the Connect dialog.

In the Clusters view, click the Connect button for the cluster to which you want to connect.

2

Select the Private Endpoint connection type.

3

Select the private endpoint to which you want to connect.

4

Create a MongoDB User.

To access the cluster, you must create a MongoDB user with access to the desired database(s) on the cluster.

Note

You can skip this step if Atlas indicates in the Setup Connection Security step that you have at least one MongoDB user configured in your project. To manage existing MongoDB users, see Add MongoDB Users.

If the project has no MongoDB users, Atlas prompts you to create a new user with the Atlas Admin privilege. Enter the new user’s Username and Password and click Create MongoDB User to save the user. Use this user to connect to your cluster in the following step.

Once you have whitelisted an IP address and added a MongoDB user, click Choose Your Connection Method.

5

Select your preferred connection method.

In the Choose a connection method step, Atlas provides instructions for each listed connection method. Click your preferred connection method and follow the instructions given.

For connecting via a command line tool such as mongodump or mongorestore, use the Command Line Tools tab for an auto-generated template for connecting to your Atlas cluster with your preferred tool.