NOTE: It is not possible to mix {pve} 3.x and earlier with {pve} 4.X cluster
nodes.
-NOTE: While it's possible for {pve} 4.4 and {pve} 5.0 this is not supported as
-production configuration and should only used temporarily during upgrading the
-whole cluster from one to another major version.
+NOTE: While it's possible to mix {pve} 4.4 and {pve} 5.0 nodes, doing so is
+not supported as production configuration and should only used temporarily
+during upgrading the whole cluster from one to another major version.
NOTE: Running a cluster of {pve} 6.x with earlier versions is not possible. The
cluster protocol (corosync) between {pve} 6.x and earlier versions changed
installed with the final hostname and IP configuration. Changing the
hostname and IP is not possible after cluster creation.
-Currently the cluster creation can either be done on the console (login via
-`ssh`) or the API, which we have a GUI implementation for (__Datacenter ->
-Cluster__).
-
While it's common to reference all nodenames and their IPs in `/etc/hosts` (or
make their names resolvable through other means), this is not necessary for a
cluster to work. It may be useful however, as you can then connect from one node
[[pvecm_create_cluster]]
-Create the Cluster
-------------------
+Create a Cluster
+----------------
+
+You can either create a cluster on the console (login via `ssh`), or through
+the API using the {pve} Webinterface (__Datacenter -> Cluster__).
+
+NOTE: Use a unique name for your cluster. This name cannot be changed later.
+The cluster name follows the same rules as node names.
+
+[[pvecm_cluster_create_via_gui]]
+Create via Web GUI
+~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-cluster-create.png"]
+
+Under __Datacenter -> Cluster__, click on *Create Cluster*. Enter the cluster
+name and select a network connection from the dropdown to serve as the main
+cluster network (Link 0). It defaults to the IP resolved via the node's
+hostname.
+
+To add a second link as fallback, you can select the 'Advanced' checkbox and
+choose an additional network interface (Link 1, see also
+xref:pvecm_redundancy[Corosync Redundancy]).
+
+NOTE: Ensure the network selected for the cluster communication is not used for
+any high traffic loads like those of (network) storages or live-migration.
+While the cluster network itself produces small amounts of data, it is very
+sensitive to latency. Check out full
+xref:pvecm_cluster_network_requirements[cluster network requirements].
+
+[[pvecm_cluster_create_via_cli]]
+Create via Command Line
+~~~~~~~~~~~~~~~~~~~~~~~
-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.
+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 the new cluster use:
----
hp1# pvecm status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 avoid possible clashes in
+the cluster communication stack. This also helps avoid human confusion by making
+clusters clearly distinguishable.
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
Adding Nodes to the Cluster
---------------------------
-Login via `ssh` to the node you want to add.
+CAUTION: A node that is about to be added to the cluster cannot hold any guests.
+All existing configuration in `/etc/pve` is overwritten when joining a cluster,
+since guest IDs could be conflicting. As a workaround create a backup of the
+guest (`vzdump`) and restore it as a different ID after the node has been added
+to the cluster.
+
+Join Node to Cluster via GUI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-cluster-join-information.png"]
+
+Login to the web interface on an existing cluster node. Under __Datacenter ->
+Cluster__, click the button *Join Information* at the top. Then, click on the
+button *Copy Information*. Alternatively, copy the string from the 'Information'
+field manually.
+
+[thumbnail="screenshot/gui-cluster-join.png"]
+
+Next, 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 'Join Information' text you copied earlier.
+Most settings required for joining the cluster will be filled out
+automatically. For security reasons, the cluster password has to be entered
+manually.
+
+NOTE: To enter all required data manually, you can disable the 'Assisted Join'
+checkbox.
+
+After clicking the *Join* button, the cluster join process will start
+immediately. After the node joined the cluster its current node certificate
+will be replaced by one signed from the cluster certificate authority (CA),
+that means the current session will stop to work after a few seconds. You might
+then need to force-reload the webinterface and re-login with the cluster
+credentials.
+
+Now your node should be visible under __Datacenter -> Cluster__.
+
+Join Node to Cluster via Command Line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Login via `ssh` to the node you want to join into an existing cluster.
----
hp2# pvecm add IP-ADDRESS-CLUSTER
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:
If you want to use the built-in xref:pvecm_redundancy[redundancy] of the
kronosnet transport layer, also use the 'link1' parameter.
+Using the GUI, you can select the correct interface from the corresponding 'Link 0'
+and 'Link 1' fields in the *Cluster Join* dialog.
Remove a Cluster Node
---------------------
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.
projects / pve-docs.git / blobdiff