Managing Alternate Addresses
- reference
Alternate addresses and port-numbers can be established for and removed from nodes, by means of thePUT
andDELETE
HTTP methods, using the/node/controller/setupAlternateAddresses/external
URI.
HTTP methods and URI
PUT /node/controller/setupAlternateAddresses/external DELETE /node/controller/setupAlternateAddresses/external
Description
A single, alternate address can be established for and removed from a node. Likewise, a single alternate port-number can be established for and removed from each node-service. This facilitates communication with external applications that are not permitted to contact nodes directly; but have access to a router or other networked entity that provides interfaces on the cluster’s behalf.
Curl Syntax
curl -v -X PUT -u [admin]:[password] http://[ip-address]:8091/node/controller/setupAlternateAddresses/external [-d hostname=<alternate-address> ] [-d <service-name>=<alternate-port-number> ] curl -v -X DELETE -u [admin]:[password] http://[ip-address]:8091/node/controller/setupAlternateAddresses/external
The parameters are:
-
localhost
. The address of the cluster-node to which an alternate address is to be assigned. -
hostname
. The alternate address to be assigned to the cluster-node. This can be either a hostname or an IP address (either V4 or V6). -
service
. Optionally, one or more service-names corresponding to services running on the node, each service-name being specified with an alternate port number. Possible service-names arekv
(Data Service),index
(Index Service),n1ql
(Query Service),fts
(Search Service),cbas
(Analytics Service),eventing
(Eventing Service) andbackup
(Backup Service). Each successive use of thePUT
method entirely deletes all previous alternate settings (hostname and service) on the node. TheDELETE
method deletes all alternate settings (hostname and service).
Responses
For both methods, success gives the status 200 OK
, with no object returned.
If no hostname is specified, the message hostname should be specified
is displayed.
If either method is used to specify an unknown node, the message No route to host
is given, and the call fails.
Specifying an invalid service-name gives the status 400 Bad Request
, with the message Invalid Port "<submitted-service-name>" : No such port.
Examples
The following examples demonstrate how to assign alternate addresses and port-numbers, and how to remove them.
Assign an Alternate Address and Port-Numbers
To assign an alternate address and alternate port-numbers, use the PUT /node/controller/setupAlternateAddresses/external
method and URI.
curl -v -X PUT -u Administrator:password \ http://10.143.192.101:8091/node/controller/setupAlternateAddresses/external \ -d hostname=10.10.10.11 \ -d kv=9000 \ -d n1ql=9050
This assigns the alternate address 10.10.10.11
to node 10.143.192.101
, and the alternate port-numbers 9000
and 9050
to the Data and Query Services, respectively.
No object is returned.
List Alternate Addresses and Port Numbers
To list alternate addresses and port numbers, use the GET /pools/default/nodeServices
method and URI.
In the following example, the output is piped to the jq
tool, to optimize readability.
curl -v -X GET -u Administrator:password \ http://localhost:8091/pools/default/nodeServices | jq
The output is as follows:
{ "rev": 603, "nodesExt": [ { "services": { "backupAPI": 8097, "backupAPIHTTPS": 18097, "backupGRPC": 9124, "capi": 8092, "capiSSL": 18092, "indexAdmin": 9100, "indexHttp": 9102, "indexHttps": 19102, "indexScan": 9101, "indexStreamCatchup": 9104, "indexStreamInit": 9103, "indexStreamMaint": 9105, "kv": 11210, "kvSSL": 11207, "mgmt": 8091, "mgmtSSL": 18091, "n1ql": 8093, "n1qlSSL": 18093, "projector": 9999 }, "thisNode": true, "hostname": "10.144.210.101", "alternateAddresses": { "external": { "hostname": "10.10.10.11", "ports": { "kv": 9000, "n1ql": 9050 } } } }, { "services": { "capi": 8092, "capiSSL": 18092, "kv": 11210, "kvSSL": 11207, "mgmt": 8091, "mgmtSSL": 18091, "projector": 9999 }, "hostname": "10.144.210.102" } ], "clusterCapabilitiesVer": [ 1, 0 ], "clusterCapabilities": { "n1ql": [ "enhancedPreparedStatements" ] } }
The output shows, in the internal alternateAddresses
object, the specified alternate hostname, and the alternate port-numbers for the Data and Query Services.
Remove Alternate Addresses and Port Numbers
The following example removes the alternate address and all alternate port numbers from the specified node.
curl -v -X DELETE -u Administrator:password \ http://localhost:8091/node/controller/setupAlternateAddresses/external
If the call is successful, the status 200 OK
is provided.
The results can be checked as before:
curl -v -X GET -u Administrator:password \ http://localhost:8091/pools/default/nodeServices | jq
This now produces the following output:
{ "rev": 604, "nodesExt": [ { "services": { "backupAPI": 8097, "backupAPIHTTPS": 18097, "backupGRPC": 9124, "capi": 8092, "capiSSL": 18092, "indexAdmin": 9100, "indexHttp": 9102, "indexHttps": 19102, "indexScan": 9101, "indexStreamCatchup": 9104, "indexStreamInit": 9103, "indexStreamMaint": 9105, "kv": 11210, "kvSSL": 11207, "mgmt": 8091, "mgmtSSL": 18091, "n1ql": 8093, "n1qlSSL": 18093, "projector": 9999 }, "thisNode": true, "hostname": "10.144.210.101" }, { "services": { "capi": 8092, "capiSSL": 18092, "kv": 11210, "kvSSL": 11207, "mgmt": 8091, "mgmtSSL": 18091, "projector": 9999 }, "hostname": "10.144.210.102" } ], "clusterCapabilitiesVer": [ 1, 0 ], "clusterCapabilities": { "n1ql": [ "enhancedPreparedStatements" ] } }
The internal alternateAddresses
object has been removed; indicating that the alternate address and port numbers no longer exist.
See Also
For an overview of alternate addresses, and examples of how they can be used, see Alternate Addresses.
A complete list of Couchbase Services and the ports they occupy, along with information on custom port mapping, is provided in Couchbase Server Ports.
Also see Listing Node Services.