Cherry pick #13 to release-1.0: Update documentation and argument descriptions

README.md

@@ -1,9 +1,92 @@
 [![Build Status](https://travis-ci.org/kubernetes-csi/node-driver-registrar.svg?branch=master)](https://travis-ci.org/kubernetes-csi/node-driver-registrar)
 # Node Driver Registrar
+The node-driver-registrar is a sidecar container that registers the CSI driver
+with Kubelet using the
+[kubelet plugin registration mechanism](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/#device-plugin-registration).
 
-A sidecar container that
+This is necessary because Kubelet is responsible for issuing CSI `NodeGetInfo`,
+`NodeStageVolume`, `NodePublishVolume` calls. The `node-driver-registrar` registers
+your CSI driver with Kubelet so that it knows which Unix domain socket to issue
+the CSI calls on.
+
+## Compatibility
+Latest stable release | Branch| Compatible with CSI Version | Container Image | Min K8s Version | Max K8s Version
+-----------------------|-----------------------|-----------------------------|----------------|---------|--------|
+[node-driver-registrar v1.0.2](https://github.com/kubernetes-csi/cluster-driver-registrar/releases/tag/v1.0.2) | [release-1.0](https://github.com/kubernetes-csi/node-driver-registrar/tree/release-1.0) | [CSI Spec v1.0.0](https://github.com/container-storage-interface/spec/releases/tag/v1.0.0) | quay.io/k8scsi/csi-node-driver-registrar:v1.0.2 | 1.13 | -
+[driver-registrar v0.4.2](https://github.com/kubernetes-csi/driver-registrar/releases/tag/v0.4.2) | [release-0.4](https://github.com/kubernetes-csi/driver-registrar/tree/release-0.4) | [CSI Spec v0.3.0](https://github.com/container-storage-interface/spec/releases/tag/v0.3.0) | quay.io/k8scsi/driver-registrar:v0.4.2 | 1.10 | -
+
+
+For release-0.4 and below, please refer to the [node-registrar
+repository](https://github.com/kubernetes-csi/driver-registrar).
+
+## Usage
+There are two UNIX domain sockets used by the node-driver-registrar:
+
+* Registration socket:
+  * Registers the driver with kubelet.
+  * Created by the `node-driver-registrar`.
+  * Exposed on a Kubernetes node via hostpath in the Kubelet plugin registry.
+    (typically `/var/lib/kubelet/plugins_registry/<drivername.example.com>-reg.sock`).
+
+* CSI driver socket:
+  * Used by kubelet to interact with the CSI driver.
+  * Created by the CSI driver.
+  * Exposed on a Kubernetes node via hostpath somewhere other than the Kubelet.
+    plugin registry (typically `/var/lib/kubelet/plugins/<drivername.example.com>/csi.sock`).
+  * This is the socket referenced by the `--csi-address` and `--kubelet-registration-path` arguments.
+
+### Required arguments
+
+* `--csi-address`: This is the path to the CSI driver socket (defined above) inside the
+  pod that the `node-driver-registrar` container will use to issue CSI
+  operations (e.g. `/csi/csi.sock`).
+* `--kubelet-registration-path`: This is the path to the CSI driver socket on
+  the host node that kubelet will use to issue CSI operations (e.g.
+  `/var/lib/kubelet/plugins/<drivername.example.com>/csi.sock). Note this is NOT
+  the path to the registration socket.
+
+### Required permissions
+The node-driver-registrar does not interact with the Kubernetes API, so no RBAC
+rules are needed.
+
+It does, however, need to be able to mount hostPath volumes and have the file
+permissions to:
+* Access the CSI driver socket (typically in `/var/lib/kubelet/plugins/<drivername.example.com>/`).
+  * Used by the `node-driver-registrar` to fetch the driver name from the driver
+    contain (via the CSI `GetPluginInfo()` call).
+* Access the registration socket (typically in `/var/lib/kubelet/plugins_registry/`).
+  * Used by the `node-driver-registrar` to register the driver with kubelet.
+
+### Example
+Here is an example sidecar spec in the driver DaemonSet. `<drivername.example.com>` should be replaced by
+the actual driver's name.
+```
+      containers:
+        - name: csi-driver-registrar
+          image: quay.io/k8scsi/csi-node-driver-registrar:v1.0.2
+          args:
+            - "--csi-address=/csi/csi.sock"
+            - "--kubelet-registration-path=/var/lib/kubelet/plugins/<drivername.example.com>/csi.sock"
+          lifecycle:
+            preStop:
+              exec:
+                command: ["/bin/sh", "-c", "rm -rf /registration/<plugin> /registration/<drivername.example.com>-reg.sock"]
+          volumeMounts:
+            - name: plugin-dir
+              mountPath: /csi
+            - name: registration-dir
+              mountPath: /registration
+      volumes:
+        - name: registration-dir
+          hostPath:
+            path: /var/lib/kubelet/plugins_registry/
+            type: Directory
+        - name: plugin-dir
+          hostPath:
+            path: /var/lib/kubelet/plugins/<drivername.example.com>/
+            type: DirectoryOrCreate
+```
 
-1. Registers the containerized CSI driver with kubelet (in the future).
 
 ## Community, discussion, contribution, and support
 

cmd/node-driver-registrar/main.go

@@ -44,15 +44,10 @@ const (
 // Command line flags
 var (
 	connectionTimeout       = flag.Duration("connection-timeout", 1*time.Minute, "Timeout for waiting for CSI driver socket.")
-	csiAddress              = flag.String("csi-address", "/run/csi/socket", "Address of the CSI driver socket.")
-	kubeletRegistrationPath = flag.String("kubelet-registration-path", "",
-		`Enables Kubelet Plugin Registration service, and returns the specified path as "endpoint" in "PluginInfo" response.
-If this option is set, the driver-registrar expose a unix domain socket to handle Kubelet Plugin Registration,
-this socket MUST be surfaced on the host in the kubelet plugin registration directory (in addition to the CSI driver socket).
-If plugin registration is enabled on kubelet (kubelet flag KubeletPluginsWatcher is set), then this option should be set
-and the value should be the path of the CSI driver socket on the host machine.`)
-	showVersion = flag.Bool("version", false, "Show version.")
-	version     = "unknown"
+	csiAddress              = flag.String("csi-address", "/run/csi/socket", "Path of the CSI driver socket that the node-driver-registrar will connect to.")
+	kubeletRegistrationPath = flag.String("kubelet-registration-path", "", "Path of the CSI driver socket on the Kubernetes host machine.")
+	showVersion             = flag.Bool("version", false, "Show version.")
+	version                 = "unknown"
 
 	// List of supported versions
 	supportedVersions = []string{"1.0.0"}