Configure a Private Network

Setting up a private network enables your application to interact with Couchbase Capella over a private connection by co-locating them through VPC or VNet peering.

Use the procedures on this page to configure a private network connection from a Couchbase Capella database hosted with Amazon Web Services (AWS), Google Cloud (GCP), or Microsoft Azure to your application’s Virtual Private Cloud.

Overview

You can configure a private network connection from Couchbase Capella databases hosted with AWS, GCP, or Microsoft Azure to your application’s VPC.

Capella does not support private networks between different cloud providers. For example, you cannot set up private networking between a Capella database hosted in GCP with an application hosted on AWS.

Using a private network (also known as network peering) provides an added layer of security for organizations by avoiding communication over the Internet. It also results in a significant reduction in latency and egress costs.

Private Endpoints

Private endpoints connect a Capella database to a chosen resource or service. You can set up private endpoints with AWS or Azure. Private endpoints are not available with GCP.

Setting up a Private Network

To set up a private network, use the instructions provided on the tab that corresponds with your Capella database’s cloud provider.

AWS
GCP
Azure

Prerequisites

To configure Couchbase Capella private networking with AWS, you need to complete the following prerequisites steps:

In AWS, enable DNS hostnames for the VPC:
In AWS, enable DNS resolution for the VPC:
You must also ensure that your Capella database’s CIDR block (specified when setting up the database) does not overlap with the application VPC CIDR block. You can retrieve the CIDR block for a database using the public API.

Creating a Private Network

In Capella, add a new private network for your database.
1. Open the database where you want to create the new private network.
2. Click the Settings tab.
3. In the navigation pane, click VPC Peering.
4. Click Set Up VPC.
5. Confirm the prerequisites and click Next.
In Capella, configure your private network details.
1. Fill out the Network Details fields.
  
  You can find most of the required info for these fields on the page for your chosen VPC in AWS.
  
  Name
  
  Enter a name.
  
  AWS Account ID
  
  The numeric AWS Account ID.
  
  Virtual Network ID
  
  The alphanumeric VPC ID which starts with vpc-.
  
  Available Regions
  
  The AWS region where your VPC is deployed (this can be seen in the top-right corner of the AWS console).
  
  CIDR Block
  
  The AWS VPC CIDR block of network in which your application runs. This cannot overlap with your Capella CIDR Block.
2. Click Set Up VNet.
  
  Capella sets up the private network. This typically takes up to a minute. If successful you should see the private network added to the list of private networks, then you may briefly see the database enter a "Deploying" state while the new network is set up.
  
  If there’s a problem with the private network then Capella will tell you via an error message, such as in the case of overlapping CIDR blocks.

Finishing Private Network Setup

When setup is complete, you can see the new network listed in the list of networks.
While the status of the network says "Complete" there are a final few steps you need to carry out before you can access your Capella database from your VPC over this private network.

If you click on the Private Network it will show you two commands that you must run to accept the peering request and also link your VPC to the appropriate DNS server for hostname resolution. You can also accept the VPC peering request in the AWS console:

However, you must associate the hosted zone via the AWS CLI command provided in Capella, as it is not currently possible to do this via the AWS console.

Upon executing these commands, you should see output similar to the following:

$ aws ec2 accept-vpc-peering-connection --region=us-west-2 --vpc-peering-connection-id=pcx-004adebd9bf32a24f

{
	"VpcPeeringConnection": {
    	"AccepterVpcInfo": {
        	"CidrBlock": "10.0.0.0/20",
        	"CidrBlockSet": [
            	{
                	"CidrBlock": "10.0.0.0/20"
            	}
        	],
        	"OwnerId": "264138468394",
        	"PeeringOptions": {
            	"AllowDnsResolutionFromRemoteVpc": false,
            	"AllowEgressFromLocalClassicLinkToRemoteVpc": false,
            	"AllowEgressFromLocalVpcToRemoteClassicLink": false
        	},
        	"VpcId": "vpc-09af4fa45689ca44c",
        	"Region": "us-west-2"
    	},
    	"RequesterVpcInfo": {
        	"CidrBlock": "10.0.16.0/20",
        	"CidrBlockSet": [
            	{
                	"CidrBlock": "10.0.16.0/20"
            	}
        	],
        	"OwnerId": "689827245340",
        	"VpcId": "vpc-091c6caeba936ac48",
        	"Region": "us-east-1"
    	},
    	"Status": {
        	"Code": "provisioning",
        	"Message": "Provisioning"
    	},
    	"Tags": [],
    	"VpcPeeringConnectionId": "pcx-004adebd9bf32a24f"
	}
}

$ aws route53 associate-vpc-with-hosted-zone --hosted-zone-id=Z04089311NGVVH0FO3QGG --vpc=VPCId=vpc-09af4fa45689ca44c,VPCRegion=us-west-2 --region=us-east-1

{
	"ChangeInfo": {
    	"Id": "/change/C0508746QOHOO1XX5BH5",
    	"Status": "PENDING",
    	"SubmittedAt": "2021-12-03T16:58:38.401Z",
    	"Comment": ""
	}
}

The final step is to then update the Route Table for your application VPC to ensure that all traffic destined for your Capella database is appropriately routed.

First, identify the Route Table for your application VPC:
Edit the routes of this Route Table to add the Capella database as a new route.

Take the CIDR block of the Capella database, either in the Capella UI or from the RequesterVpcInfo from the VPC peering request output. In this example, enter 10.0.16.0/20 as the destination. The target VpcPeeringConnectionId is pcx-004adebd9bf32a24f in this example.
If your VPC has any outbound security groups associated with it (i.e. limiting outbound traffic to specific IPs), then you must also add the CIDR block for your Capella database to the outbound security group.

Prerequisites

To configure Couchbase Capella private networking with GCP, you need a service account with these roles:

DNS Administrator (roles/dns.admin)
Compute Network Admin (roles/compute.networkAdmin)

Creating a Private Network

In Capella, add a new private network for your database.
1. Open the database where you want to create the new private network.
2. Click the Settings tab.
3. In the navigation pane, click VPC Peering.
4. Click Set Up VPC.
5. Confirm the prerequisites and click Next.
In Capella, configure your private network details.
1. Fill out the Network Details fields.
  
  You can find most of the required info for these fields on the page for your chosen VPC in GCP.
  
  Name
  
  Enter a descriptive name for the new private network.
  
  GCP Project ID
  
  The unique identifier for your GCP project. This is typically autogenerated in the form of rock-galaxy-123456 or similar.
  
  GCP Network Name
  
  The GCP VPC network name.
  
  Service Account Email
  
  The email address of the associated service account. This looks like <service-account-id>@rock-galaxy-123456.iam.gserviceaccount.com.
  
  CIDR Block
  
  The GCP VPC CIDR block of network in which your application runs. This cannot overlap with your Capella CIDR Block.
2. Click Set Up VPC.
  
  Capella sets up the private network. This typically takes up to a minute. If successful you should see the private network added to the list of private networks, then you may briefly see the database enter a "Deploying" state while the new network is set up.
  
  If there’s a problem with the private network then Capella will tell you via an error message.

Finishing Private Network Setup

Once setup is complete, you can see the new network listed in the list of networks.

While the status of the network says "Complete" there are some final steps you must carry out before you can access your Capella database from your VPC over this private network.

On the VPC Peering screen, click the listing for the new Private Network.

This shows you two commands that you must run to accept the peering request and also link your VPC to the appropriate DNS server for hostname resolution. For example:

$ gcloud compute networks peerings create <your-peer-name> --network=<your-vpc-network-name> --peer-project <your-gcp-project-id> --peer-network <capella-vpc-network-name>

$ gcloud dns managed-zones create <your-zone-name> --description="Peering Zone to Capella" --dns-name=<dns-name-suffix> --account=<service-account-email-address> --networks=<your-vpc-network-name> --target-network=<your-vpc-network-name> --target-project=<your-gcp-project-id> --visibility=private

Using the gcloud CLI, run the commands provided by Capella.
Verify connectively to ensure that the applications connecting from the application VPC are using the private network correctly.

Prerequisites

To configure Couchbase Capella VNet peering with Microsoft Azure, you need the following:

An Azure user with the Global Administrator Role.
The Azure CLI.

Creating VNet peering

In Capella, start the VNet peering configuration:
1. Open the database you want to peer with your application.
2. Click the Settings tab.
3. In the navigation pane, click VNet Peering.
4. Click Setup VNet Peering.
Confirm that you have a user with the Global Administrator Role.
Add your Azure configuration details to allow peering access:

Azure Tenant ID

Enter your tenant ID. To find your tenant ID, see How to find your Azure Active Directory tenant ID.

Azure Subscription ID

Enter your subscription ID. To find your subscription ID, see Find your Azure subscription.

Resource Group Name

Enter the resource group name holding the resource you’re connecting with Capella.

Virtual Network Name

Enter the name of the virtual network in Azure.
Click Allow Peering Access.

A new browser tab opens. Sign in to Azure if you have not already.
In Azure, accept Capella’s permissions request:

The Azure permissions request page is open in the new browser tab. Make a note of the application name and consent to the new permissions request. Consenting to this permission request creates a service principal that grants Capella access to the Azure tenant to perform VNet peering.

If you previously set up VNet peering with the same Azure tenant, you won’t see this permissions request page as that permission is already granted.

On accepting the new permission, you automatically return to the Capella VNet peering page. The Capella VNet peering pages shows a notice indicating that peering access is successful.
In Capella, add the Enterprise Application Object ID:

With consent now granted, you need to find and add the enterprise application object ID for the Capella service principal. You can find the enterprise application object ID in Azure by selecting Azure Active Directory Enterprise applications. Next, select the application name—the same name shown when accepting the Azure permissions request. The object ID is in the Object ID box.
Click Next.
Copy the role assignment command shown on this page and run it using Azure CLI.

This command assigns a new network contributor role. It scopes only to your specified subscription and the virtual network within that subscription. On success, the details of the role assignment are output in JSON.
Provide network details:

VNet Peering Name

Enter a descriptive VNet peering name of your choice.

CIDR Block

The virtual network CIDR block cannot overlap the CIDR that the database uses.

Enter the CIDR block from the virtual network that you created in Azure. You can find the CIDR block in Azure by viewing the page for the virtual network and selecting Subnets.
Click Set Up VNet.

Do not refresh the browser while Capella configures the peering connection.

Capella sets up the VNet peering connection, which can take several minutes. When successful, the new VNet peering connection is on the VNet peering list.

Verifying Connectivity to Private Networks

With a private network set up, it’s important to ensure that applications connecting from the application VPC are using the private network correctly.

Hostname Resolution

The first step whenever an application connects to a Capella database is to resolve the hostnames of all nodes in the database. Within the Capella UI, you can see the URL for the database, which is an SRV record containing multiple nodes of the database.

You can retrieve the DNS SRV record for your database within the Wide Area Network section of the Connect tab.

This hostname can be resolved using a command such as the following:

nslookup -type=SRV _couchbases._tcp.cb.a-lxzt-gdkzoqfuu.cloud.couchbase.com

Server:   	 127.0.0.53
Address:    127.0.0.53#53

Non-authoritative answer:
_couchbases._tcp.cb.a-lxzt-gdkzoqfuu.cloud.couchbase.com    service = 0 0 11207 9qvj8x-f2oxhahtz.a-lxzt-gdkzoqfuu.cloud.couchbase.com.
_couchbases._tcp.cb.a-lxzt-gdkzoqfuu.cloud.couchbase.com    service = 0 0 11207 jkzlapnfpklgjhtl.a-lxzt-gdkzoqfuu.cloud.couchbase.com.
_couchbases._tcp.cb.a-lxzt-gdkzoqfuu.cloud.couchbase.com    service = 0 0 11207 4ncgebm6lmtbxmkr.a-lxzt-gdkzoqfuu.cloud.couchbase.com.

You should then resolve one of these individual hostnames returned from the SRV record, for example:

nslookup 9qvj8x-f2oxhahtz.a-lxzt-gdkzoqfuu.cloud.couchbase.com

Server:   	 127.0.0.53
Address:    127.0.0.53#53

Non-authoritative answer:
Name:    9qvj8x-f2oxhahtz.a-lxzt-gdkzoqfuu.cloud.couchbase.com
Address: 10.0.18.110

If the DNS resolution is working correctly then you should see the private IP of the Capella Node (i.e. an IP from the database’s CIDR block). If you see that the public IP is returned for this node then you should validate that you have:
- Enabled DNS resolution
- Enabled DNS hostnames
- Associated the hosted zone with your VPC
  
  See the Prerequisites section, above.

Network Connectivity

Now that you have validated that DNS resolution is working correctly, you should validate the network connectivity between your application instances and your Capella database.

To validate that the routing is correctly set up for your VPC, you can run a traceroute to one of the nodes in your database (retrieved from the previous DNS resolution step). For example:

traceroute -T 9qvj8x-f2oxhahtz.a-lxzt-gdkzoqfuu.cloud.couchbase.com -p 18091

traceroute to 9qvj8x-f2oxhahtz.a-lxzt-gdkzoqfuu.cloud.couchbase.com (10.0.18.110), 30 hops max, 60 byte packets
 1  ip-10-0-18-110.us-west-2.compute.internal (10.0.18.110)  0.303 ms  0.288 ms  0.302 ms

This command should return quickly, if not then there are likely issues with your routing and you should validate the route table associated with the VPC to ensure that you have associated the correct CIDR block with the peering connection.

Finally, you can run a curl command to validate that Couchbase Server is responding correctly over the private network:

$ curl -k https://9qvj8x-f2oxhahtz.a-lxzt-gdkzoqfuu.cloud.couchbase.com:18091

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"><html><head><title>301 Moved Permanently</title></head><body><h1>Moved Permanently</h1><p>The document has moved <a href="https://9qvj8x-f2oxhahtz.a-lxzt-gdkzoqfuu.cloud.couchbase.com:18091/ui/index.html>here</a>.</p></body></html>

Troubleshoot Private Network Issues

Check the Status of Your Private Network Connection

The following table provides information about the status

Table 1. Private Network Connection Status
Status	Description
Not Setup (Default state)	No networks exist and no infrastructure has been provisioned.
Linking Network	One or more networks are being connected and/or the infrastructure is being provisioned.
Linking Failed	One or more networks have failed to connect but the infrastructure was provisioned successfully.
Infrastructure Failed	Infrastructure provisioning failed.
Ready	One or more networks are linked successfully.
No Networks	No networks are linked but the infrastructure has been provisioned for your database.
Infrastructure Provisioning	The infrastructure is being provisioned. Note that this is an intermediate state that is only possible for the first network linked for a database.

If you create multiple networks in rapid succession, both the Linking and Provisioning states may be displayed as Failed at the same time.

Possible Errors and Workarounds

You can set up private networks on a new deployment only after the private networking feature is enabled. Check if you are using an existing database and/or if the feature is enabled.
If the private networking feature does not exist in your region, the private zone creation can fail. Check that the feature is enabled in your region.
Policy added for the private zone could fail. Retry adding the policy to resolve the issue.
Security group update for the CIDR may fail. Retry the operation to resolve the issue.
If you provided an incorrect CIDR block, application VPC, VPC ID, or Regions when creating a private network, we recommend that you delete that private network and re-create a new one with the correct values.
Ensure that both DNS settings are enabled on the AWS VPC side — DNS hostname and DNS resolution. If changing this setting, allow time for DNS caching.
While we support multiple subscriptions within a single Azure tenant, VNet peering across two or more Azure tenants is not supported.
If using Couchbase Go SDK Version 1.6 with private networking, ensure that you set network=default in the connection string.

Tools such as the AWS VPC Reachability Analyzer can be useful to verify communications.