Set Up a Private Endpoint for a Dedicated Cluster
On this page
- Overview
- Considerations
- High Availability
- Port Ranges Used for Private Endpoints
- Private Endpoint-Aware Connection Strings
- IP Access Lists and Network Peering Connections with Private Endpoints
- (Optional) Regionalized Private Endpoints for Multi-Region Sharded Clusters
- Limitations
- Prerequisites
- Procedures
- Configure an Atlas Private Endpoint
- Connect to Atlas using a Private Endpoint
- Remove a Private Endpoint from Atlas
- Troubleshoot Private Endpoint Connection Issues
- Check the status of your AWS PrivateLink connections.
- Make sure that your security groups are configured properly.
This feature is not available for M0
free clusters, M2
, and
M5
clusters. To learn more about which features are unavailable,
see Atlas M0 (Free Cluster), M2, and M5 Limitations.
Serverless instances are in preview and do not support this feature at this time. To learn more, see Serverless Instance Limitations.
MongoDB Atlas supports private endpoints on:
- AWS using the AWS PrivateLink feature,
- Azure using the Azure Private Link feature, and
- Google Cloud using the Google Cloud Private Service Connect feature.
You can set up private endpoints for your Online Archive. To learn more, see Set Up a Private Endpoint for Online Archives.
Overview
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.
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.
Considerations
High Availability
To ensure private endpoint connections to Atlas can withstand an availability zone outage, you should deploy subnets to multiple availability zones in a region.
Port Ranges Used for Private Endpoints
By default, AWS PrivateLink supports 50 addressable targets, from port 1024 to port 1073.
Private Endpoint-Aware Connection Strings
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.
In the preceding example:
_mongodb._tcp.cluster0-pl-0-k45tj.mongodb.net
is the SRV record that themongodb+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
, and1026
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
IP Access Lists and Network Peering Connections with Private Endpoints
When you enable private endpoints, 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.
(Optional) Regionalized Private Endpoints for Multi-Region Sharded Clusters
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.
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:
Navigate to the Settings page for your project.
- If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
- If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
- Next to the Projects menu, expand the Options menu, then click Project Settings.
Limitations
- 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. If you have a multi-cloud cluster in AWS or Azure, you must provision an endpoint in each provider or region.
You can do only one of the following:
- Create more than one private endpoint in a single region, or
Create no more than one private endpoint per region, if nodes are deployed in more than one region.
ImportantThis 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 (Optional) 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
mongod
instance in a replica set deployment (sharded clusters excluded). - Each
mongos
instance in a sharded cluster deployment. - Each BI Connector for Atlas instance across all dedicated clusters in the project.
NoteTo request a one-time increase to use AWS PrivateLink with up to 100 addressable targets per Atlas project, contact MongoDB Support.
Prerequisites
To enable connections to Atlas using private endpoints, you must:
- Have either the
Project Owner
orOrganization Owner
role in Atlas. - 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.
- (Recommended): Install the AWS CLI.
- 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:
Navigate to the Network Access page for your project.
- If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
- If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
- Click Network Access in the sidebar.
Choose a region.
- From the Atlas Region list, select the region in which you want to create the private endpoint.
- Click Next.
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.
Configure your private endpoint.
Enter the following details about your AWS VPC:
Your VPC IDUnique identifier of the peer AWS VPC. Find this value on the VPC dashboard in your AWS account.Your Subnet IDsUnique identifiers of the subnets your AWS VPC uses. Find these values on the Subnet dashboard in your AWS account.
ImportantYou 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.
Copy the command the dialog displays and run it using the AWS CLI.
NoteYou 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.
- Click Next.
Configure your resources' security groups to send traffic to and receive traffic from the interface 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 interface endpoint's private IP(s) on all ports.
See Adding Rules to a Security Group for more information.
Create a security group for your interface 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:
- In the AWS console, navigate to the VPC Dashboard.
- Click Security Groups, then click Create security group.
- Use the wizard to create a security group. Make sure you select your VPC from the VPC list.
- Select the security group you just created, then click the Inbound Rules tab.
- Click Edit Rules.
- Add rules to allow all inbound traffic from each resource in your VPC that you want to connect to your Atlas cluster.
- Click Save Rules.
- Click Endpoints, then click the endpoint for your VPC.
- Click the Security Groups tab, then click Edit Security Groups.
- Add the security group you just created, then click Save.
To learn more about VPC security groups, see the AWS documentation.
Verify that the private endpoint is available.
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:
- In the Security section of the left navigation, click Network Access.
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 StatusReady for connection requestsEndpoint StatusAvailable
If you do not see these statuses, see Troubleshoot Private Endpoint Connection Issues for additional information.
Connect to Atlas using a Private Endpoint
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:
Create a Database User.
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 database deployment, you need a MongoDB user with access to the desired database or databases on the database deployment in your project. If your project has no MongoDB users, Atlas prompts you to create a new user with the Atlas Admin role.
- Enter the new user's Username.
- Enter a Password for this new user or click Autogenerate Secure Password.
- Click Create Database User to save the user.
Use this user to connect to your database deployment 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.
Click Choose a connection method.
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.
Remove a Private Endpoint from Atlas
Navigate to the Network Access page for your project.
- If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
- If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
- Click Network Access in the sidebar.
Remove the private endpoint from Atlas.
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.
Troubleshoot Private Endpoint Connection Issues
Check the status of your AWS PrivateLink connections.
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:
|
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. |
Make sure that your security groups are configured properly.
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.
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.