[pve-devel] [PATCH docs 1/2] Mention GUI for creating a cluster and adding nodes

[Thomas Lamprecht]

On 8/22/19 4:53 PM, Stefan Reiter wrote:
> Signed-off-by: Stefan Reiter <s.reiter at proxmox.com>
> ---
>  pvecm.adoc | 81 ++++++++++++++++++++++++++++++++++++++++--------------
>  1 file changed, 60 insertions(+), 21 deletions(-)
> 
> diff --git a/pvecm.adoc b/pvecm.adoc
> index e986a75..5379c3f 100644
> --- a/pvecm.adoc
> +++ b/pvecm.adoc
> @@ -103,25 +103,33 @@ to the other with SSH via the easier to remember node name (see also
>  xref:pvecm_corosync_addresses[Link Address Types]). Note that we always
>  recommend to reference nodes by their IP addresses in the cluster configuration.
>  
> -
> -[[pvecm_create_cluster]]

NAK! You remove this but never re-add it in this patch. After installing pve-docs
with that patch applied building pve-manager would be broken, as this reference
is used there by the cluster GUI parts...

>  Create the Cluster
>  ------------------
>  
> -Login via `ssh` to the first {pve} node. Use a unique name for your cluster.
> -This name cannot be changed later. The cluster name follows the same rules as
> -node names.
> +Use a unique name for your cluster. This name cannot be changed later. The
> +cluster name follows the same rules as node names.
> +
> +Create via Web GUI
> +~~~~~~~~~~~~~~~~~~
> +
> +Under __Datacenter -> Cluster__, click on *Create Cluster*. Type your cluster
> +name and select a network connection from the dropdown to serve as your main
> +cluster network (Link 0, default is what the node's hostname resolves to).
> +
> +Optionally, you can select the 'Advanced' check box and choose an additional
> +network interface for fallback purposes (Link 1, see also
> +xref:pvecm_redundancy[Corosync Redundancy]).
> +
> +Create via Command Line
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Login via `ssh` to the first {pve} node and run the following command:
>  
>  ----
>   hp1# pvecm create CLUSTERNAME
>  ----
>  
> -NOTE: It is possible to create multiple clusters in the same physical or logical
> -network. Use unique cluster names if you do so. To avoid human confusion, it is
> -also recommended to choose different names even if clusters do not share the
> -cluster network.
> -
> -To check the state of your cluster use:
> +To check the state of your new cluster use:
>  
>  ----
>   hp1# pvecm status
> @@ -131,9 +139,9 @@ Multiple Clusters In Same Network
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
>  It is possible to create multiple clusters in the same physical or logical
> -network. Each such cluster must have a unique name, this does not only helps
> -admins to distinguish on which cluster they currently operate, it is also
> -required to avoid possible clashes in the cluster communication stack.
> +network. Each such cluster must have a unique name, to not only help admins
> +distinguish which cluster they are currently operating on, but also to avoid
> +possible clashes in the cluster communication stack.
>  
>  While the bandwidth requirement of a corosync cluster is relatively low, the
>  latency of packages and the package per second (PPS) rate is the limiting
> @@ -145,6 +153,39 @@ infrastructure for bigger clusters.
>  Adding Nodes to the Cluster
>  ---------------------------
>  
> +CAUTION: A new node cannot hold any VMs, because you would get
> +conflicts about identical VM IDs. Also, all existing configuration in
> +`/etc/pve` is overwritten when you join a new node to the cluster. To
> +workaround, use `vzdump` to backup and restore to a different VMID after
> +adding the node to the cluster.
> +
> +Add Node via GUI
> +~~~~~~~~~~~~~~~~
> +
> +If you want to use "assisted join", where most parameters will be filled in for
> +you, first login to the web interface on a node already in the cluster. Under
> +__Datacenter -> Cluster__, click on *Join Information* at the top. Click on
> +*Copy Information* or manually copy the string from the 'Information' field.
> +
> +To add the new node, login to the web interface on the node you want to add.
> +Under __Datacenter -> Cluster__, click on *Join Cluster*. Fill in the
> +'Information' field with the text you copied earlier.
> +
> +For security reasons, the password is not included, so you have to fill that in
> +manually.
> +
> +NOTE: The Join Information is not necessarily required, you can also uncheck the
> +'Assisted Join' checkbox and fill in the required fields manually.
> +
> +After clicking on *Join* your node will immediately be added to the cluster.
> +You might need to reload the web page, and re-login with the cluster
> +credentials.
> +
> +Confirm that your node is visible under __Datacenter -> Cluster__.
> +
> +Add Node via Command Line
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
>  Login via `ssh` to the node you want to add.
>  
>  ----
> @@ -154,11 +195,6 @@ Login via `ssh` to the node you want to add.
>  For `IP-ADDRESS-CLUSTER` use the IP or hostname of an existing cluster node.
>  An IP address is recommended (see xref:pvecm_corosync_addresses[Link Address Types]).
>  
> -CAUTION: A new node cannot hold any VMs, because you would get
> -conflicts about identical VM IDs. Also, all existing configuration in
> -`/etc/pve` is overwritten when you join a new node to the cluster. To
> -workaround, use `vzdump` to backup and restore to a different VMID after
> -adding the node to the cluster.
>  
>  To check the state of the cluster use:
>  
> @@ -229,6 +265,8 @@ pvecm add IP-ADDRESS-CLUSTER -link0 LOCAL-IP-ADDRESS-LINK0
>  If you want to use the built-in xref:pvecm_redundancy[redundancy] of the
>  kronosnet transport layer, also use the 'link1' parameter.
>  
> +In the GUI you can select the correct interface from the corresponding 'Link 0'
> +and 'Link 1' fields.
>  
>  Remove a Cluster Node
>  ---------------------
> @@ -692,8 +730,9 @@ Corosync Redundancy
>  Corosync supports redundant networking via its integrated kronosnet layer by
>  default (it is not supported on the legacy udp/udpu transports). It can be
>  enabled by specifying more than one link address, either via the '--linkX'
> -parameters of `pvecm` (while creating a cluster or adding a new node) or by
> -specifying more than one 'ringX_addr' in `corosync.conf`.
> +parameters of `pvecm`, in the GUI as **Link 1** (while creating a cluster or
> +adding a new node) or by specifying more than one 'ringX_addr' in
> +`corosync.conf`.
>  
>  NOTE: To provide useful failover, every link should be on its own
>  physical network connection.
>