[pve-devel] [PATCH docs] Update pvecm doc regarding IP vs hostname as ring address

[Thomas Lamprecht]

On 6/17/19 4:13 PM, Stefan Reiter wrote:
> Signed-off-by: Stefan Reiter <s.reiter at proxmox.com>
> ---
> 
> Based on recent conversation in pve-user list.
> 
>  pvecm.adoc | 33 +++++++++++++++++++++++++++++++--
>  1 file changed, 31 insertions(+), 2 deletions(-)
> 
> diff --git a/pvecm.adoc b/pvecm.adoc
> index 61453f7..773c2dd 100644
> --- a/pvecm.adoc
> +++ b/pvecm.adoc
> @@ -149,7 +149,8 @@ Login via `ssh` to the node you want to add.
>   hp2# pvecm add IP-ADDRESS-CLUSTER
>  ----
>  
> -For `IP-ADDRESS-CLUSTER` use the IP from an existing cluster node.
> +For `IP-ADDRESS-CLUSTER` use the IP or hostname of an existing cluster node.
> +An IP address is recommended (see <<ring-node-address-types,Ring Address Types>>).
>  
>  CAUTION: A new node cannot hold any VMs, because you would get
>  conflicts about identical VM IDs. Also, all existing configuration in
> @@ -572,7 +573,8 @@ you do not see them already. Those *must* match the node name.
>  
>  Then replace the address from the 'ring0_addr' properties with the new
>  addresses.  You may use plain IP addresses or also hostnames here. If you use
> -hostnames ensure that they are resolvable from all nodes.
> +hostnames ensure that they are resolvable from all nodes. (see also
> +<<ring-node-address-types,Ring Address Types>>)
>  
>  In my example I want to switch my cluster communication to the 10.10.10.1/25
>  network. So I replace all 'ring0_addr' respectively. I also set the bindnetaddr
> @@ -654,6 +656,33 @@ systemctl status corosync
>  If corosync runs again correct restart corosync also on all other nodes.
>  They will then join the cluster membership one by one on the new network.
>  
> +[[ring-node-address-types]]

we normally prefix/namespace such explicit references with the chapter name,
at least for new references (pvecm has a few wrong uses already)..

Further, in the rest of the docs we normally use xref:REFERENCE_NAME[reference text]
not <<>>, but here you just copied already existing (wrong) behavior too -
this was even done by me some years ago, IIRC, so no offense just a note.

I'll clean this up later, so that we do not interfere to much with Aaron's
rewrite work.. Maybe he could change the style of this once he touches pvecm.

> +Ring/Node Address Types
> +~~~~~~~~~~~~~~~~~~~~~~~

I'd call it something more ambiguous/general, e.g.: Corosync Addresses
and that for two reasons:
1. they ain't called rings anymore with corosync 3, but links, while the
   config is backwards compatible so some ringX mentions are still present
   I'd like to not add to the confusion then.
2. Easier to understand what this chapter is about
3. Corosync is a term all PVE users know or get to know quite early when they
   get into PVE contact, Rings ain't

> +
> +A ring address (sometimes called node address) can be specified in two ways:

Especially in multi ring/link setups our term of node address and corosync's
differ, so I'd omit the part in parenthesis.

> +
> +* **IPv4/v6 addresses** will be used directly. They are the preferred way of
> +setting a node's address, since they are static.

Maybe a bit more nuanced like:

Most of the time they should be preferred over hostnames, as changing corosync
addresses must done with a bit of care, and a hostname may lead to a situation
where one changes the address it resolves to without thinking about corosync at
all. If one prefers host name a extra, only used for corosync, should be added.

(grammar wording may surely be improved for above)

> +
> +* **Hostnames** will be resolved using `getaddrinfo`, which means that IPv6
> +addresses will always be used first, if available (see also `man gai.conf`).

IMO, I'd add something like "per default", e.g.:
.. which means that per default IPv6 ...

> +
> +NOTE: Since {pve} 5.1, while supported, hostnames will never be configured by
> +integrated tooling. Instead, they will be resolved at the time of entry. The
> +internal order of preferring IPv6 over v4 still applies, however.

IMO "hostnames will never be configured by integrated tooling" is to complicated
and if I'd read that somewhere I would not understand anything at all.

> +
> +In the `corosync.conf` file, if nodes in the `nodelist` section have their
> +`ringX_addr` specified as a hostname (either by manually <<edit-corosync-conf,editing the corosync.conf file>>
> +or by upgrading from older {pve} versions), you need to make sure that every
> +node in the cluster can resolve each hostname correctly. Once again, keep in
> +mind that IPv6 will always be resolved first.
> +
> +If your setup uses hostnames in `corosync.conf`, it might be a good idea to
> +either replace them with IPs, or at least check the file and cluster for
> +correctness after major upgrades. Given the dynamic nature of hostname
> +resolving, this configuration can easily lead to unwanted behaviour.

For above two paragraphs + the note one could maybe simply write something
like:

Since version 5.1 {pve} uses the resolve node name, if no specific address was
passed.
Nodes which got joined before {pve} 5.1 used the unresolved nodename as
address per default.
Given the dynamic nature of hostname resolving, it might be a good idea to
either replace them with static IPs or keep a separate hostname just for
corosync, to avoid accidentally switching it to resolve to another address.

> +
>  [[pvecm_rrp]]
>  Redundant Ring Protocol
>  ~~~~~~~~~~~~~~~~~~~~~~~
>