doc: Apply trust establishment changes to the init, add and preseed docs

doc/explanation/initialisation.md

@@ -7,15 +7,25 @@ relatedlinks: https://en.wikipedia.org/wiki/Multicast_DNS
 
 See {ref}`howto-initialise` for instructions on how to set up MicroCloud.
 
+(trust-establishment-session)=
+## Trust establishment session
+
+To allow several instances of MicroCloud joining the final cluster, in both the interactive and non-interactive method each instance
+is running one half of the trust establishment session to trust the other side.
+
+Each trust establishment session has one initiator and one to many joiners.
+In case of the interactive mode the side which runs the `microcloud init` command becomes the initiator.
+The other side becomes the joiner by running `microcloud join`.
+In the non-interactive mode the initator is being defined using the `initiator` or `initiator_address` config key.
+
 (automatic-server-detection)=
 ## Automatic server detection
 
-MicroCloud uses {abbr}`mDNS (multicast DNS)` to automatically detect other servers on the network.
+If required MicroCloud uses {abbr}`mDNS (multicast DNS)` to automatically detect a so called initiator on the network.
 This method works in physical networks, but it is usually not supported in a cloud environment.
+Instead you can specify the address of the initiator instead to not require using mDNS.
 
-The scan can be limited to the default local subnet of the network interface you select.
-
-MicroCloud will display all servers that it detects and periodically update the list. You can select the servers you want to add to the MicroCloud cluster.
+The scan is limited to the local subnet of the network interface you select when choosing an address for MicroCloud's internal traffic (see {ref}`microcloud-networking-intracluster`).
 
 (bootstrapping-process)=
 ## Bootstrapping process

doc/how-to/add_machine.md

@@ -1,10 +1,33 @@
 (howto-add)=
 # How to add a machine
+## Interactive configuration
 
 If you want to add a machine to the MicroCloud cluster after the initialisation, use the {command}`microcloud add` command:
 
     sudo microcloud add
 
-Answer the prompts to add the machine.
+On the new machine use the {command}`microcloud join` command:
+
+    sudo microcloud join
+
+Answer the prompts on both sides to add the machine.
 Alternatively, you can add the `--auto` flag to accept the default configuration instead of an interactive setup.
 You can also add the `--wipe` flag to automatically wipe any disks you add to the cluster.
+
+## Non-interactive configuration
+
+If you want to automatically add a machine, you can provide a preseed configuration in YAML format to the {command}`microcloud preseed` command:
+
+    cat <preseed_file> | microcloud preseed
+
+In the list of systems include only the new machine and set either `initiator` or `initiator_address` which can point to any machine
+that is already part of the MicroCloud.
+
+Make sure to distribute and run the same preseed configuration on the new and existing system configured using either `initiator` or `initiator_address`.
+
+The preseed YAML file must use the following syntax:
+
+```{literalinclude} preseed.yaml
+:language: YAML
+:emphasize-lines: 1-3,6-8,11-12,19,29-33
+```

doc/how-to/initialise.md

@@ -2,7 +2,7 @@
 # How to initialise MicroCloud
 
 The {ref}`initialisation process <explanation-initialisation>` bootstraps the MicroCloud cluster.
-You run the initialisation on one of the machines, and it configures the required services on all machines.
+You run the initialisation on one of the machines, and it configures the required services on all of the machines that have been joined.
 
 (howto-initialise-interactive)=
 ## Interactive configuration
@@ -28,19 +28,26 @@ Complete the following steps to initialise MicroCloud:
 
        sudo microcloud init
 
+1. Select wether you want to set up more than one machine.
+
+   This allows you to create a MicroCloud using a single node.
+   It will skip the {ref}`trust-establishment-session` if no more machines should be part of the MicroCloud.
+
+   Additional machines can always be added at a later point in time.
+   See {ref}`howto-add` for more information.
 1. Select the IP address that you want to use for MicroCloud's internal traffic (see {ref}`microcloud-networking-intracluster`).
    MicroCloud automatically detects the available addresses (IPv4 and IPv6) on the existing network interfaces and displays them in a table.
 
    You must select exactly one address.
-1. Decide if you want to limit the search for other machines.
+1. On all the other machines, enter the following command and repeat the address selection:
 
-   If you accept the default (`yes`), MicroCloud will automatically detect machines in the local subnet.
-   Otherwise, it will detect all available machines, which might include duplicates (if machines are available both on IPv4 and on IPv6).
+       sudo microcloud join
 
-   See {ref}`automatic-server-detection` for more information.
+   It will automatically detect the machine acting as the initiator.
+   See {ref}`trust-establishment-session` for more information and  {ref}`automatic-server-detection` in case the network doesn't support mDNS.
 1. Select the machines that you want to add to the MicroCloud cluster.
 
-   MicroCloud displays all machines that it detects. This list will periodically update as new machines are detected.
+   MicroCloud displays all machines that have reached out during the trust establishment session.
    Make sure that all machines that you select have the required snaps installed.
 1. Select whether you want to set up local storage.
 
@@ -135,13 +142,15 @@ If more than one MicroCeph or MicroOVN cluster exists among the systems, the Mic
 (howto-initialise-preseed)=
 ## Non-interactive configuration
 
-If you want to automate the initialisation process, you can provide a preseed configuration in YAML format to the {command}`microcloud init` command:
+If you want to automate the initialisation process, you can provide a preseed configuration in YAML format to the {command}`microcloud preseed` command:
+
+    cat <preseed_file> | microcloud preseed
 
-    cat <preseed_file> | microcloud init --preseed
+Make sure to distribute and run the same preseed configuration on all systems that should be part of the MicroCloud.
 
 The preseed YAML file must use the following syntax:
 
 ```{literalinclude} preseed.yaml
 :language: YAML
-:emphasize-lines: 1,4-7,27,33-41
+:emphasize-lines: 1-3,6-8,11-12,19,29-33
 ```

doc/how-to/preseed.yaml

@@ -1,16 +1,42 @@
+# `initiator` defines which system takes over the role of the initiator during the trust establishment with mDNS.
+# Make sure to also set `lookup_subnet`.
+# The field cannot be set together with `initiator_address`.
+initiator: micro01
+
+# `initiator_address` defines which system takes over the role of the initiator during the trust establishment.
+# It also allows joining systems to learn about the address they have to connect to.
+# The field cannot be set together with `initiator`.
+initiator_address: 10.0.0.1
+
 # `lookup_subnet` limits the subnet when looking up systems with mDNS.
-lookup_subnet: 10.0.0.1/24
-# `lookup_interface` limits the interface when looking up systems with mDNS.
-lookup_interface: eth0
+# The first assigned address of this subnet is used for MicroCloud.
+lookup_subnet: 10.0.0.0/24
+
+# `lookup_timeout` is optional and configures how long the joining system will wait for a system to be discovered with mDNS.
+# It defaults to 60 seconds.
+lookup_timeout: 300
+
+# `session_passphrase` configures the passphrase used during the trust establishment session.
+session_passphrase: 83P27XWKbDczUyE7xaX3pgVfaEacfQ2qiQ0r6gPb
+
+# `session_timeout` is optional and configures how long the trust establishment session will last.
+# It defaults to 10 minutes.
+session_timeout: 300
+
+# `reuse_existing_clusters` is optional and configures wether or not to reuse existing clusters.
+reuse_existing_clusters: true
 
 # `systems` lists the systems we expect to find by their host name.
-#   `name` represents the host name
+#   `name` represents the host name.
+#   `address` sets the address used for MicroCloud and is required in case `initiator_address` is present.
 #   `ovn_uplink_interface` is optional and represents the name of the interface reserved for use with OVN.
 #   `storage` is optional and represents explicit paths to disks for each system.
 systems:
 - name: micro01
+  address: 10.0.0.1
   ovn_uplink_interface: eth1
 - name: micro02
+  address: 10.0.0.2
   ovn_uplink_interface: eth1
   storage:
     local:
@@ -23,8 +49,10 @@ systems:
         wipe: true
         encrypt: true
 - name: micro03
+  address: 10.0.0.3
   ovn_uplink_interface: eth1
 - name: micro04
+  address: 10.0.0.4
   ovn_uplink_interface: eth1
 
 # `ceph` is optional and represents the Ceph global configuration

doc/tutorial/get_started.md

@@ -238,18 +238,13 @@ Complete the following steps on each VM (`micro1`, `micro2`, `micro3`, and `micr
 ## 6. Initialise MicroCloud
 
 After installing all snaps on all VMs, you can initialise MicroCloud.
-This initialisation is done on one of the machines only.
 We use `micro1`, but you can choose another machine.
 
 Complete the following steps:
 
-1. Access the shell in `micro1`:
+1. Access the shell in `micro1` and start the initialisation process:
 
-       lxc exec micro1 -- bash
-
-1. Start the initialisation process:
-
-       microcloud init
+       lxc exec micro1 microcloud init
 
    ```{tip}
    In this tutorial, we initialise MicroCloud interactively.
@@ -258,8 +253,21 @@ Complete the following steps:
 
 1. Answer the questions:
 
+   1. Select `yes` to select more than one cluster member.
    1. As the address for MicroCloud's internal traffic, select the listed IPv4 address.
-   1. Select `yes` to limit the search for other MicroCloud servers to the local subnet.
+   1. Copy the session passphrase.
+   1. Head to the other servers (`micro02`, `micro03`, and `micro04`) and start the join process:
+
+          lxc exec micro02 microcloud join
+
+         ```{tip}
+
+         Open up three additional terminals to run the commands concurrently.
+         ```
+
+         In each terminal select an address for MicroCloud's internal traffic.
+         When prompted enter the passphrase in each terminal and return to `micro01`.
+
    1. Select all listed servers (these should be `micro2`, `micro3`, and `micro4`).
    1. Select `yes` to set up local storage.
    1. Select the listed local disks (`local1`, `local2`, `local3`, and `local4`).
@@ -293,7 +301,7 @@ Complete the following steps:
 MicroCloud will now initialise the cluster.
 See {ref}`explanation-initialisation` for more information.
 
-See the full initialisation process here:
+See the full process here for the initiating side:
 
 (initialisation-process)=
 
@@ -303,6 +311,7 @@ See the full initialisation process here:
 :host: micro1
 :scroll:
 
+Do you want to set up more than one cluster member? (yes/no) [default=yes]: yes
 Select an address for MicroCloud's internal traffic:
 Space to select; enter to confirm; type to filter results.
 Up/down to move; right to select all; left to select none.
@@ -315,18 +324,27 @@ Up/down to move; right to select all; left to select none.
 
  Using address "203.0.113.169" for MicroCloud
 
-Limit search for other MicroCloud servers to 203.0.113.169/24? (yes/no) [default=yes]: yes
-Scanning for eligible servers ...
+Use the following command on systems that you want to join the cluster:
+
+ microcloud join
+
+When requested enter the passphrase:
+
+ koala absorbing update dorsal
+
+Verify the fingerprint "5d0808de679d" is displayed on joining systems.
+Waiting to detect systems ...
 Space to select; enter to confirm; type to filter results.
 Up/down to move; right to select all; left to select none.
-       +---------+--------+---------------+
-       |  NAME   | IFACE  |     ADDR      |
-       +---------+--------+---------------+
-> [x]  | micro3  | enp5s0 | 203.0.113.171 |
-  [x]  | micro2  | enp5s0 | 203.0.113.170 |
-  [x]  | micro4  | enp5s0 | 203.0.113.172 |
-       +---------+--------+---------------+
-
+       +---------+---------------+--------------+
+       |  NAME   |    ADDRESS    | FINGERPRINT  |
+       +---------+---------------+--------------+
+> [x]  | micro3  | 203.0.113.171 | 4e80954d6a64 |
+  [x]  | micro2  | 203.0.113.170 | 84e0b50e13b3 |
+  [x]  | micro4  | 203.0.113.172 | 98667a808a99 |
+       +---------+---------------+--------------+
+
+ Selected "micro1" at "203.0.113.169"
  Selected "micro3" at "203.0.113.171"
  Selected "micro2" at "203.0.113.170"
  Selected "micro4" at "203.0.113.172"
@@ -432,6 +450,33 @@ Cluster initialization is complete
 MicroCloud is ready
 ```
 
+See the full process here for one of the joining sides (`micro02`):
+
+```{terminal}
+:input: microcloud init
+:user: root
+:host: micro1
+:scroll:
+
+Select an address for MicroCloud's internal traffic:
+
+ Using address "203.0.113.170" for MicroCloud
+
+Verify the fingerprint "84e0b50e13b3" is displayed on the other system.
+Specify the passphrase for joining the system: koala absorbing update dorsal
+Searching for an eligible system ...
+
+ Found system "micro01" at "203.0.113.169" using fingerprint "5d0808de679d"
+
+Select "micro02" on "micro01" to let it join the cluster
+
+ Received confirmation from system "micro01"
+
+Do not exit out to keep the session alive.
+Complete the remaining configuration on "micro01" ...
+Successfully joined the cluster
+```
+
 ## 7. Inspect your MicroCloud setup
 
 You can now inspect your cluster setup.