From 2edd7f10b0b0b9f6d14d880ff18c64719e17ea52 Mon Sep 17 00:00:00 2001 From: Michelle Au Date: Wed, 26 Dec 2018 18:38:00 -0800 Subject: [PATCH] Update documentation and argument descriptions --- README.md | 87 ++++++++++++++++++++++++++++++- cmd/node-driver-registrar/main.go | 13 ++--- 2 files changed, 89 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f7916fb2b..cd8001f16 100644 --- a/README.md +++ b/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/-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//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//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//`). + * 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. `` 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//csi.sock" + lifecycle: + preStop: + exec: + command: ["/bin/sh", "-c", "rm -rf /registration/ /registration/-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// + type: DirectoryOrCreate +``` -1. Registers the containerized CSI driver with kubelet (in the future). ## Community, discussion, contribution, and support diff --git a/cmd/node-driver-registrar/main.go b/cmd/node-driver-registrar/main.go index 3679808d7..c3bce88ff 100644 --- a/cmd/node-driver-registrar/main.go +++ b/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"}