Skip to content

All about hosts entries

A hosts entry gives one node in your cluster an extra name, and makes that name resolve on every node in the same cluster. Point redis.internal at your Redis node or mariadb.internal at your MariaDB node, and your applications can connect to that name instead of an IP address.

Wondering when you'd want one, and what happens on the servers? This article explains what a hosts entry does, how to create one, and what already works without any hosts entries at all.

What it solves

Your application needs to find its database, cache, or search engine. The obvious way is to put the target node's IP address in a configuration file. That works until the address changes — then you have to find and update every file holding it.

A hosts entry replaces the address with a name you choose. The name resolves to that node's current internal addresses, so your configuration file keeps saying redis.internal and nothing breaks when the address changes.

The name is also easier to read. mariadb.internal tells the next person which service it is. 10.0.0.14 does not.

Creating one

  1. Open a cluster.
  2. Click 'Hosts Entries' under 'Configurations' in the sidebar.
  3. Click '+'.
  4. 'Hostname': the name you want, such as redis.internal. Must be unique within the cluster.
  5. 'Target Node': the node the name resolves to. Nodes show as their hostname, with their comment behind it when they have one.

The entry is applied to all nodes in the cluster, after which the name works everywhere in it.

What happens on the servers

Cyberfusion writes the cluster's hosts entries to /etc/hosts on every node in that cluster. The name is mapped to both the internal IPv6 and the internal IPv4 address of the node you selected.

Two consequences:

  • The name only works inside the cluster. It is not DNS. Nothing outside the cluster, including your visitors, can resolve it.
  • Traffic to the name stays on the internal network, because the entry uses internal addresses, not public ones.

Nodes already reach each other by hostname

You do not need a hosts entry for one node to reach another. Every node in a cluster is written to /etc/hosts on every other node automatically, under its own hostname (the full hostname and the short first part). Those entries use internal addresses too.

Hosts entries are for the extra, service-shaped names on top of that: redis.internal, mariadb.internal, search.internal.

Deleting one

Delete an entry from the same page.

Anything still configured to use that name stops being able to resolve it. Update your applications before you delete the entry.