In order to connect to Couchbase deployments on cloud (AWS, Azure or GCP) or Kubernetes, we support multi-addresses in the form of alternate addresses. External applications use this facility to communicate with the cluster, but not directly to the nodes. These settings allow internal access to a router or other networked entity that provides interfaces on the cluster’s behalf.

When setting up alternate addresses, we can also set up alternate port numbers. The best example for the alternate address setup is AWS public and private IP addresses. Each node has a Private IP and DNS but they can also assign a public IP and DNS record. Those public IPs can be either statically or dynamically assigned.

Access to nodes within an internal network or cloud

Access to nodes within an internal network or cloud

The clients then connect to the public host and ports as seen under the external address section in the nodeServices information under the pools/default/nodesServices Rest endpoint.

Port Forwarding Couchbase Instance on AWS

One important step when setting up alternate addresses is port forwarding. When alternate addresses are provisioned, the mapping from external host and port to internal ports must be done by a network administrator. The client can then use the external address and port to connect to the service.

Once within the network (a user connects to an external facing address, internal to the deployment where the port mapping takes place), the external port will be mapped to the internal port to access the service based on authorization. This can be done on AWS using the steps outlined here.

Depending on what is accessible outside the firewall (port-level access), the client can send queries to that service. Once alternate external addresses and ports are provisioned the Couchbase ns_server service updates REST endpoints: 

Internally, Couchbase services don’t need to restart on new ports and only the client should allow connections to a particular host/port based on information available in the nodeServices property under the external attribute.

The nodeServices REST endpoint shows the mapping of hosts and ports:

Alternate address setup steps 

1 – Setup the Couchbase cluster and use REST calls or CLI to set up alternate addresses:


In the example below, the external address becomes for internal node It also sets the new N1QL external port to 9000

2 – Modify /etc/hosts to contain access to  

3 – For port forwarding on a virtual machine,  we can use the following command for the Query service running on port 8093

Then list the current forwarding settings to confirm:

List the alternate address settings: 

In order to use the cbq query tool to access alternate addresses, use the networkconfig or nfcg option and set it to external. This allows us to run queries:

Refer to the Couchbase documentation here for more cluster, networking and alternate address usage


Posted by Isha Kandaswamy

Isha Kandaswamy is a Senior Software Engineer at Couchbase. Isha is responsible for the development of designing the different features and tools for the N1QL Query Language -SQL for Json. Also, Designing and implementing features and tools for the N1QL query language.

Leave a reply