Replacing a Static Node FQDN

Warning

This article is dedicated to YDB clusters that use configuration V2. This configuration method is currently experimental and is only available for YDB versions starting from v25.1. For production use, we recommend choosing configuration V1 — it is the main method and is officially supported for all YDB clusters.

The fully qualified domain name (FQDN) of a static node is specified by the host parameter in the hosts section. To change the FQDN without replacing the server or its disks, follow these steps.

Create a DNS record for the new FQDN that points to the same server. The new FQDN must be resolvable from every cluster node. Keep the old DNS record until the procedure is complete. If the cluster uses TLS, prepare a node certificate that contains the new FQDN.

Fetch the current cluster configuration using the ydb admin cluster config fetch command:
```
ydb [global options...] admin cluster config fetch > config.yaml
```
In config.yaml, locate the existing hosts list entry for the target node and change only its host value. Do not delete the node entry and create a new one elsewhere — this would change the node's position in the configuration and break the update.

For example, for node 1, replace node-1.example.com with node-1-new.example.com:
```
config:
  hosts:
  - host: node-1-new.example.com
    node_id: 1
```
Apply the updated configuration using the ydb admin cluster config replace command:
```
ydb [global options...] admin cluster config replace -f config.yaml
```
Wait until the new FQDN appears in the local copy of config.yaml on the target node.
Prepare the target node for restart:
- If the cluster uses TLS, install the prepared certificate.
- If the node starts with --node static, make sure that the new host value matches the output of either hostname or hostname -f. If the values do not match, configure the operating system so that hostname -f returns the new host value before restarting.
Obtain permission to stop the process, then restart the static node process. For example, when using systemd:
```
sudo systemctl restart ydbd-storage
```
The service name may differ depending on the deployment method.
On the Nodes tab of the cluster monitoring page, make sure the node has reconnected with its original ID and the new FQDN. You can then remove the old DNS record.

Was the article helpful?

Static group move

Database node authentication and authorization