Enable FQDN access
This topic describes how to enable cluster access by using a fully qualified domain name (FQDN). An FQDN is a complete domain name for a specific entity that can be accessed over the Internet. The FQDN consists of two parts: the hostname and the domain name.
Before 2.4, StarRocks supports access to FEs and BEs via IP address only. Even if an FQDN is used to add a node to a cluster, it is transformed into an IP address eventually. This causes a huge inconvenience for DBAs because changing the IP addresses of certain nodes in a StarRocks cluster can lead to access failures to the nodes. In version 2.4, StarRocks decouples each node from its IP address. You can now manage nodes in StarRocks solely via their FQDNs.
Prerequisites
To enable FQDN access for a StarRocks cluster, make sure the following requirements are satisfied:
-
Each machine in the cluster must have a hostname.
-
In the file /etc/hosts on each machine, you must specify the corresponding IP addresses and FQDNs of other machines in the cluster.
-
IP addresses in the /etc/hosts file must be uniqule.
Set up a new cluster with FQDN access
By default, FE nodes in a new cluster are started via IP address access. To start a new cluster with FQDN access, you must start the FE nodes by running the following commands when you start the cluster for the first time:
./bin/start_fe.sh --host_type FQDN --daemon
The property --host_type
specifies the access method that is used to start the node. Valid values include FQDN
and IP
. You only need to specify this property ONCE when you start the node for the first time.
See Deploy StarRocks for detailed instructions on how to install StarRocks.
Each BE node identifies itself with BE Address
defined in the FE metadata. Therefore, you DO NOT need to specify --host_type
when you start BE nodes. If the BE Address
defines a BE node with an FQDN, the BE node identifies itself with this FQDN.
Enable FQDN access in an existing cluster
To enable FQDN access in an existing cluster that was previously started via IP addresses, you must first upgrade StarRocks to version 2.4.0 or later.
Enable FQDN access for FE nodes
You need to enable FQDN access for all the non-Leader Follower FE nodes before enabling that for the Leader FE node.
CAUTION
Make sure that the cluster has at least three Follower FE nodes before you enable FQDN access for FE nodes.
Enable FQDN access for non-Leader Follower FE nodes
-
Navigate to the deployment directory of the FE node, and run the following command to stop the FE node:
./bin/stop_fe.sh
-
Execute the following statement via your MySQL client to check the
Alive
status of the FE node that you have stopped. Wait until theAlive
status becomesfalse
.SHOW PROC '/frontends'\G
-
Execute the following statement to replace the IP address with FQDN.
ALTER SYSTEM MODIFY FRONTEND HOST "<fe_ip>" TO "<fe_hostname>";
-
Run the following command to start the FE node with FQDN access.
./bin/start_fe.sh --host_type FQDN --daemon
The property
--host_type
specifies the access method that is used to start the node. Valid values includeFQDN
andIP
. You only need to specify this property ONCE when you restart the node after you modify the node. -
Check the
Alive
status of the FE node. Wait until theAlive
status becomestrue
.SHOW PROC '/frontends'\G
-
Repeat the above steps to enable FQDN access for the other non-Leader Follower FE nodes one after another when the
Alive
status of the current FE node istrue
.
Enable FQDN access for the Leader FE node
After all the non-Leader FE nodes have been modified and restarted successfully, you can now enable FQDN access for the Leader FE node.
NOTE
Before the Leader FE node is enabled with FQDN access, the FQDNs used to add nodes to a cluster are still transformed into the corresponding IP addresses. After a Leader FE node with FQDN access enabled is elected for the cluster, the FQDNs will not be transformed into IP addresses.
-
Navigate to the deployment directory of the Leader FE node, and run the following command to stop the Leader FE node.
./bin/stop_fe.sh
-
Execute the following statement via your MySQL client to check whether a new Leader FE node has been elected for the cluster.
SHOW PROC '/frontends'\G
Any FE node with status
Alive
andisMaster
beingtrue
is a Leader FE that is running. -
Execute the following statement to replace the IP address with FQDN.
ALTER SYSTEM MODIFY FRONTEND HOST "<fe_ip>" TO "<fe_hostname>";
-
Run the following command to start the FE node with FQDN access.
./bin/start_fe.sh --host_type FQDN --daemon
The property
--host_type
specifies the access method that is used to start the node. Valid values includeFQDN
andIP
. You only need to specify this property ONCE when you restart the node after you modify the node. -
Check the
Alive
status of the FE node.SHOW PROC '/frontends'\G
If the Alive
status becomes true
, the FE node is successfully modified and added to the cluster as a Follower FE node.
Enable FQDN access for BE nodes
Execute the following statement via your MySQL client to replace the IP address with FQDN to enable FQDN access for the BE node.
ALTER SYSTEM MODIFY BACKEND HOST "<be_ip>" TO "<be_hostname>";
NOTE
You DO NOT need to restart the BE node after FQDN access is enabled.
Rollback
To rollback an FQDN access-enabled StarRocks cluster to an earlier version that does not support FQDN access, you must first enable IP address access for all nodes in the cluster. You can refer Enable FQDN access in an existing cluster for the general guidance except that you need to change the SQL commands to the following ones:
- Enable IP address access for an FE node:
ALTER SYSTEM MODIFY FRONTEND HOST "<fe_hostname>" TO "<fe_ip>";
- Enable IP address access for a BE node:
ALTER SYSTEM MODIFY BACKEND HOST "<be_hostname>" TO "<be_ip>";
The modification takes effect after your cluster is successfully restarted.
FAQ
Q: An error occurs when I enable FQDN access for an FE node: "required 1 replica. But none were active with this master". What should I do?
A: Make sure the cluster has at least three Follower FE nodes before you enable FQDN access for FE nodes.
Q: Can I add a new node by using IP address to a cluster with FQDN access enabled?
A: Yes.