Add design for simplified node-add process

Instead of initiating many SSH connections to copy files using “scp”, a
JSON structure is passed to a program running on the node to be added.
The design is similar to the one used for SSH setup.

Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>

doc/design-node-add.rst

@@ -20,10 +20,20 @@ requires a tight coupling and equality between nodes (e.g. paths to
 files being the same). Most of the logic and error handling is also done
 on the connecting machine.
 
+Once a node's SSH daemon has been configured, more than 25 files need to
+be copied using ``scp`` before the node daemon can be started. No
+verification is being done before files are copied. Once the node daemon
+is started, an opcode is submitted to the master daemon, which will then
+copy more files, such as the configuration and job queue for master
+candidates, using RPC. This process is somewhat fragile and requires
+initiating many SSH connections.
 
 Proposed changes
 ----------------
 
+SSH
+~~~
+
 The main goal is to move more logic to the newly added node. Instead of
 having a relatively large script executed on the master node, most of it
 is moved over to the added node.
@@ -42,10 +52,37 @@ SSH client and to drop the dependency on Paramiko for Ganeti itself
 
 Eventually ``setup-ssh`` can be removed.
 
+
+Node daemon
+~~~~~~~~~~~
+
+Similar to SSH setup changes, the process of copying files and starting
+the node daemon will be moved into a dedicated program. On its standard
+input it will receive a standardized JSON structure (defined :ref:`below
+<node-daemon-setup-json>`). Once the input data has been successfully
+decoded and the received values were verified for sanity, the program
+proceeds to write the values to files and then starts the node daemon
+(``ganeti-noded``).
+
+To add a new node to the cluster, the master node will have to gather
+all values, build the data structure, and then invoke the newly added
+``node-daemon-setup`` program via SSH. In this way only a single SSH
+connection is needed and the values can be verified before being written
+to files.
+
+If the program exits successfully, the node is ready to be added to the
+master daemon's configuration. The node daemon will be running, but
+``OpNodeAdd`` needs to be run before it becomes a full node. The opcode
+will copy more files, such as the :doc:`RAPI certificate <rapi>`.
+
+
+Data structures
+---------------
+
 .. _prepare-node-join-json:
 
-JSON structure
-~~~~~~~~~~~~~~
+JSON structure for SSH setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The data is given in an object containing the keys described below.
 Unless specified otherwise, all entries are optional.
@@ -78,6 +115,43 @@ and public part of the key. Example:
     ("dsa", "-----BEGIN DSA PRIVATE KEY-----...", "ssh-dss AAAA..."),
   ]
 
+
+.. _node-daemon-setup-json:
+
+JSON structure for node daemon setup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The data is given in an object containing the keys described below.
+Unless specified otherwise, all entries are optional.
+
+``cluster_name``
+  Required string with the cluster name. If a local cluster name is
+  found, the join process is aborted unless the passed cluster name
+  matches the local name. The cluster name is also included in the
+  dictionary given via the ``ssconf`` entry.
+``node_daemon_certificate``
+  Public and private part of cluster's node daemon certificate in PEM
+  format. If a local node certificate is found, the process is aborted
+  unless it matches.
+``ssconf``
+  Dictionary with ssconf names and their values. Both are strings.
+  Example:
+
+  .. highlight:: javascript
+
+  ::
+
+    {
+      "cluster_name": "cluster.example.com",
+      "master_ip": "192.168.2.1",
+      "master_netdev": "br0",
+      # …
+    }
+
+``start_node_daemon``
+  Boolean denoting whether the node daemon should be started (or
+  restarted if it was running for some reason).
+
 .. vim: set textwidth=72 :
 .. Local Variables:
 .. mode: rst