Navigation

Set up a Private Endpoint

Note
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, and
  • Azure using the Azure Private Link 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 perceived 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 adding public IP addresses to the Atlas IP access list.

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

When you configure a private endpoint, Atlas generates DNS seedlist and standard private endpoint-aware connection strings:

  • DNS seedlist connection

    mongodb+srv://cluster0-pl-0-k45tj.mongodb.net
  • Standard connection string

    mongodb://pl-0-us-east-1-k45tj.mongodb.net:1024,pl-0-us-east-1-k45tj.mongodb.net:1025,pl-0-us-east-1-k45tj.mongodb.net:1026/?ssl=true&authSource=admin&replicaSet=Cluster0-shard-0-shard-0

When a client in your VPC connects to an Atlas cluster using one of these private endpoint-aware connection strings, the client attempts to establish a connection to the load balancer in the Atlas VPC through one of the interface endpoints. Your client's DNS resolution mechanism handles which of the interface endpoints the hostname resolves to. If one interface endpoint 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 or in the connection string.

SRV Record for DNS Seedlist Private Endpoint-Aware Connection Strings

The following example shows the SRV record for an AWS PrivateLink-enabled single-region cluster, showing three unique ports defined for pl-0-us-east-1-k45tj.mongodb.net:

$ 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 1026 pl-0-us-east-1-k45tj.mongodb.net.
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1024 pl-0-us-east-1-k45tj.mongodb.net.
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net service = 0 0 1025 pl-0-us-east-1-k45tj.mongodb.net.
Tip

In the preceding example:

  • _mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net is the SRV record that the mongodb+srv://cluster0-pl-0-k45tj.mongodb.net connection string references.
  • pl-0-us-east-1-k45tj.mongodb.net is the hostname for each node in one Atlas cluster in one region for which you have configured AWS PrivateLink.
  • 1024, 1025, and 1026 are unique ports that Atlas assigns on the load balancer for each Atlas replica set node in the region for which you enabled AWS PrivateLink. All nodes in an Atlas replica set are accessible via the same hostname, with the load balancer resolving individual nodes by their unique port.

Hostname DNS Resolution in Private Endpoint-Aware Connection Strings and SRV Records

The hostname in the SRV record and the standard connection string is a DNS Canonical Name (CNAME) record that resolves to the endpoint-specific regional DNS name that AWS generates for the interface endpoint. A DNS 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 for that subnet.

The following example shows the DNS lookup for the hostname in the SRV record and in the standard connection string, including the endpoint-specific regional DNS name for the interface endpoint and its DNS 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 Private Endpoints are enabled, you can still enable access to your Atlas clusters using other methods, such as adding public IPs to IP access lists and network 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.

For multi-region and global sharded clusters, you can deploy multiple private endpoints to a region if you need to connect to Atlas using a private endpoint from networks that can't be peered with one another.

You can deploy any number of private endpoints to regions that you deployed your cluster to. Each regional private endpoint connects to the mongos instances in that region.

Warning

Your connection strings to existing multi-region and global sharded clusters change when you enable this setting.

You must update your applications to use the new connection strings. This might cause downtime.

You can enable this setting only if your Atlas project contains no replica sets.

You can't disable this setting if you have:

  • More than one private endpoint in more than one region, or
  • More than one private endpoint in one region and one private endpoint in one or more regions.

You can create only sharded clusters when you enable the regionalized private endpoint setting. You can't create replica sets.

To use this feature, you must enable the regionalized private endpoint setting:

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
  3. Next to the Projects menu, expand the Options menu, then click Project Settings.
2

Toggle the Multiple Regionalized Private Endpoints setting to Yes.

  • You can use AWS PrivateLink to connect to Atlas clusters running MongoDB version 3.6 or later.
  • AWS PrivateLink must be active in all regions into which you deploy a multi-region cluster. You will receive an error if AWS PrivateLink is active in some, but not all, targeted regions.
  • You can do only one of the following:

    • Create more than one private endpoint in a single region, or
    • Create one private endpoint in multiple regions.

      Important

      This limitation applies across cloud providers. For example, if you create more than one private endpoint in a single region in AWS, you can't create private endpoints in more than one region in Azure.

    See Regionalized Private Endpoints for Multi-Region Sharded Clusters for an exception for multi-region and global sharded clusters.

  • If this is the first private endpoint that you deploy to a region, you must first resume any paused clusters in your project with nodes deployed to that region.

    This limitation doesn't apply for additional private endpoints that you deploy to the same region.

  • To connect to Atlas clusters using AWS PrivateLink from regions in which you haven't deployed a private endpoint connection, you must peer VPCs in those regions to VPCs in a region in which you have deployed a private endpoint connection.

    To learn about inter-region VPC peering, see the AWS documentation.

  • You can use AWS PrivateLink in Atlas projects with up to 50 addressable targets per region. If you need more than 50 addressable targets in a region:

    • Contact MongoDB Support, or
    • Use additional projects or regions to connect to addressable targets beyond this limit.

    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.

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

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

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
  3. Click Network Access in the sidebar.
2
  1. Click the Private Endpoint tab.
  2. Click Add Private Endpoint.
3

Click the AWS logo, then click Next.

4
  1. From the Atlas Region list, select the region in which you want to create the private endpoint.
  2. Click Next.
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.

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

    Important

    You must specify at least one subnet. If you don't, AWS won't provision an interface endpoint in your VPC. An interface endpoint is required for clients in your VPC to send traffic to the private endpoint.

  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.

  3. You might 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. Please contact Atlas support for assistance resolving this error. To contact support, click Support from the left-hand navigation bar of the Atlas UI.

  4. Click Next.
6
  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.
7

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 interface endpoint's private IP(s) on all ports.

See Adding Rules to a Security Group for more information.

8

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.

9

You can connect to an Atlas cluster using the AWS PrivateLink private endpoint when all of the resources are configured and the private endpoint becomes available.

To verify that the AWS PrivateLink private endpoint is available:

  1. In the Security section of the left navigation, click Network Access.
  2. On the Private Endpoint tab, verify the following statuses for the region that contains the cluster you want to connect to using AWS PrivateLink:

    Atlas Endpoint Service Status
    Ready for connection requests
    Endpoint Status
    Available

If you do not see these statuses, see Troubleshoot Private Endpoint Connection Issues for additional information.

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

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

2
3
4
Important

Skip this step if Atlas indicates in the Setup connection security step that you have at least one database user configured in your project. To manage existing database users, see Configure Database Users.

To access the cluster, you need a MongoDB user with access to the desired database or databases on the cluster in your project. If your project has no MongoDB users, Atlas prompts you to create a new user with the Atlas Admin role.

  1. Enter the new user's Username
  2. Enter a Password for this new user or click Autogenerate Secure Password.
  3. Click Create Database User to save the user.

Use this user to connect to your cluster in the following step.

Once you have added an IP address to your IP access list and added a database user, click Choose Your Connection Method.

5

Private endpoint-aware connection strings are available in one of the following formats:

  • DNS seedlist connection

    mongodb+srv://cluster0-pl-0-auylw.mongodb.net
  • Standard connection string

    mongodb://pl-0-us-east-1-auylw.mongodb.net:1024,pl-0-us-east-1-auylw.mongodb.net:1025,pl-0-us-east-1-auylw.mongodb.net:1026/?ssl=true&authSource=admin&replicaSet=Cluster0-shard-0-shard-0

MongoDB recommends that your clients use the DNS seedlist connection string format. If your driver doesn't support this format, select an older version of your driver or version 3.4 or earlier of the mongo shell from the Connect tab to use the standard connection string format.

1
  1. If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
  2. If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
  3. Click Network Access in the sidebar.
2
Note

When you delete a private endpoint from a region in Atlas, you must manually delete the private endpoint in AWS. AWS lists the endpoint as rejected. Atlas can't delete this resource because it lacks the required permissions.

1

The Private Endpoint tab on the Network Access page lists each private endpoint you've created. The Atlas Endpoint Service Status and Endpoint Status fields show the status of each private endpoint.

Refer to the following statuses to help you determine the state of your private endpoint connections:

Atlas Endpoint Service Status

Status
Description
Creating private link
Atlas is creating the network load balancer and VPC resources.
Failed
A system failure has occurred.
Ready for connection requests
The Atlas network load balancer and VPC endpoint service are created and ready to receive connection requests.
Deleting
Atlas is deleting the private endpoint service.

Endpoint Status

Status
Description
Not configured
Atlas created the network load balancer and VPC endpoint service, but AWS hasn't yet created the interface endpoint. Click Edit and complete the wizard to create the interface endpoint.
Pending acceptance
AWS has received the connection request from your interface endpoint to the Atlas VPC endpoint service.
Pending
AWS is establishing the connection between your interface endpoint and the Atlas VPC endpoint service.
Failed

AWS failed to establish a connection between Atlas VPC resources and the interface endpoint in your VPC. Click Edit, verify that the information you provided is correct, and then create the private endpoint again.

Important

If your Interface Endpoint fails, you might see the following message:

Example

No dns entries found for endpoint vpce-<guid>, your endpoint must be provisioned in at least one subnet Click "Edit" to fix the problem.

This message indicated that you didn't specify a subnet when you created the AWS PrivateLink connection. To resolve this error:

  1. Click Edit.
  2. Click Back.
  3. Specify at least one subnet.
  4. Follow the remaining instructions to create the AWS PrivateLink connection.
Available
Atlas VPC resources are connected to the interface endpoint in your VPC. You can connect to Atlas clusters in this region using AWS PrivateLink.
Deleting
Atlas is removing the interface endpoint from the private endpoint service.
2
  1. 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 interface endpoint's private IP(s) on all ports.

    See Adding Rules to a Security Group for more information.

  2. Your interface endpoint security group must allow inbound traffic on all ports from each resource that needs to connect to your Atlas clusters using AWS PrivateLink.

    Whitelist instance IP addresses or security groups to allow traffic from them to reach the interface endpoint security group.

Give Feedback