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.

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

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.

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

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

Limitations

  • 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 30 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 50 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 the following details about your AWS private endpoints:

    Your VPC Endpoint ID A 22-character alphanumeric string that identifies your private endpoint. Find this value on the AWS VPC Dashboard under Endpoints > Endpoint ID.
    Your VPC Endpoint Hostname

    The hostname of your private endpoint. Find this value on the AWS VPC Dashboard under Endpoints > DNS Name.

    Note

    The AWS UI might list multiple DNS names: one for the region and one for each availability zone to which the endpoint is deployed.

    Use the DNS Name for the region. This is the first DNS Name in the list.

  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 all inbound and outbound traffic on all ports to and from the VPC endpoint.

See Adding Rules to a Security Group for more information.

7

Configure the VPC endpoint security group to allow resources to access it.

Your VPC 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 VPC endpoint security group.

8

Connect to Atlas using a Private Endpoint

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.