diff --git a/docs/book/SUMMARY.md b/docs/book/SUMMARY.md
index 7df25196681e..b63d40616693 100644
--- a/docs/book/SUMMARY.md
+++ b/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
diff --git a/docs/book/common_code/node_controller.md b/docs/book/common_code/node_controller.md
index d18d4994ba57..8724e4045509 100644
--- a/docs/book/common_code/node_controller.md
+++ b/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)
\ No newline at end of file
+![node object reconciliation logic](images/activity_node_reconciliation.svg)
diff --git a/docs/book/common_code/noderef_controller.md b/docs/book/common_code/noderef_controller.md
new file mode 100644
index 000000000000..64608f6645e7
--- /dev/null
+++ b/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`.