Terracotta in Network Environments with Subnets
If Terracotta nodes reside in a given subnet (for example in a Kubernetes cluster) and clients in another (for example outside of the Kubernetes cluster), node addresses (host name or IP address) are not resolvable by clients. Administrators of the Terracotta cluster can use public addresses in this scenario to assign public names to Terracotta cluster nodes, using which clients can establish connections.
Configuring public addresses
A node's public address is defined by its public-hostname and public-port properties. Public addresses must be defined for all nodes in a cluster or none of them. When configured, each node's public address must be unique within the cluster.
Consider a 2x2 cluster (2-stripes, 2 nodes per stripe) with node names: node1, node2, node3 and node4. Public addresses can be configured using one of the following methods:
Using command-line parameters during node startup
This example illustrates starting each of the four nodes by passing the same public hostname (tc-cluster.public.com) to the startup script but specifying a unique public-port for each node:
> start-tc-server.sh -name node1 public-hostname=tc-cluster.public.com public-port=1111 ...
> start-tc-server.sh -name node2 public-hostname=tc-cluster.public.com public-port=2222 ...
> start-tc-server.sh -name node3 public-hostname=tc-cluster.public.com public-port=3333 ...
> start-tc-server.sh -name node4 public-hostname=tc-cluster.public.com public-port=4444 ...
Using config file during node startup
Public addresses for an entire cluster can be saved in a Terracotta
configuration file, which can later be used to start a cluster.
This example illustrates the configuration file entries required for specifying the same public hostname (tc-cluster.public.com) for all nodes but specifying a unique public-port for each node (as in the previous example):
public-hostname=tc-cluster.public.com
node1:port=1111
node2:port=2222
node3:port=3333
node4:port=4444
Using config tool "set" command
The config tool
set command can be used to dynamically configure public addresses on a cluster. NOTE: Public addresses can be updated without having to restart the cluster.
The following example illustrates how to set the same public hostname (tc-cluster.public.com) for all nodes but setting a unique public-port for each node:
> config-tool.sh set -connect-to tc-cluster.internal.com:9410
-setting public-hostname=tc-cluster.public.com
-setting node1:public-port=1111
-setting node2:public-port=2222
-setting node3:public-port=3333
-setting node4:public-port=4444
SSL/TLS considerations
The SSL/TLS certificates of the Terracotta nodes will need to include Subject Alternative Names (SANs) that match the public addresses.
Using public addresses
Once the public addresses have been set, all tools (e.g. config tool, cluster tool etc.) would use the public addresses by default.
The following example illustrates the execution of the cluster tool status command on the cluster with public addresses configured. Take note of how the internal to public address mapping is displayed in the Host-Port column:
> cluster-tool.sh status -cluster-name tc-cluster -connect-to tc-cluster.public.com:1111
| STRIPE: stripeA |
+-----------------+--------------------------------------------------------------+-------------+
| Node Name | Host-Port | Status |
+-----------------+--------------------------------------------------------------+-------------+
| node1 | tc-cluster.internal.com:9410=tc-cluster.public.com:1111 | ACTIVE |
------------------------------------------------------------------------------------------------
| node2 | tc-cluster.internal.com:9420=tc-cluster.public.com:2222 | PASSIVE |
+----------------------------------------------------------------------------------------------+
| STRIPE: stripeB |
+-----------------+--------------------------------------------------------------+-------------+
| Node Name | Host-Port | Status |
+-----------------+--------------------------------------------------------------+-------------+
| node3 | tc-cluster.internal.com:9430=tc-cluster.public.com:3333 | ACTIVE |
------------------------------------------------------------------------------------------------
| node4 | tc-cluster.internal.com:9440=tc-cluster.public.com:4444 | PASSIVE |
+-----------------+--------------------------------------------------------------+-------------+