Add noderef controller documentation to gitbook

Signed-off-by: Vince Prignano <[email protected]>

Author: vincepri

docs/book/SUMMARY.md

@@ -15,6 +15,7 @@
 * [Machine Controller](common_code/machine_controller.md)
 * [MachineSet Controller](common_code/machineset_controller.md)
 * [MachineDeployment Controller](common_code/machinedeployment_controller.md)
+* [NodeRef Controller](common_code/noderef_controller.md)
 * [Node Controller](common_code/node_controller.md)
 
 ## Creating a New Provider

docs/book/common_code/node_controller.md

@@ -1,5 +1,8 @@
 # Node Controller
 
+> NOTE: This controller is deprecated and going to be removed in v1alpha2,
+> infrastructure providers should switch to noderef controller.
+
 The node controller has one simple job.  It links or unlinks a `Machine` to the underlying
 core k8s `Node` object if an optional annotation `cluster.k8s.io/machine` is present on the `Node`.  The
 decision to add the annotation is left to each infrastructure-specific provider.  When the
@@ -8,7 +11,7 @@ objectRef.
 
 The simplest way for Infrastructure-specific providers to add this support is to annotate
 nodes in their node bootup script as part of the `kubeadm join` operation (via a commandline
-parameter). 
+parameter).
 
 ## Node Controller Semantics
 
@@ -19,4 +22,4 @@ deletion, it unlinks the `Node` from the `Machine`.
 
 #### node reconciliation logic
 
-![node object reconciliation logic](images/activity_node_reconciliation.svg)
+![node object reconciliation logic](images/activity_node_reconciliation.svg)

docs/book/common_code/noderef_controller.md

@@ -0,0 +1,8 @@
+# NodeRef Controller
+
+The NodeRef controller populates a `Machine`'s `Status.NodeRef` field using the Kubernetes Node
+object associated with the Machine. This controller supports only machines linked to a cluster.
+
+Infrastructure providers can opt-in to use this controller by providing a `kubeconfig` as a Kubernetes Secret.
+The secret must be stored in the namespace the Cluster lives in and named as `<cluster-name>-kubeconfig`,
+the data should only contain a single key called `value` and its data should be a valid Kubernetes `kubeconfig`.