Add Overview and Troubleshooting docs

docs/book/overview.md

@@ -0,0 +1,63 @@
+<!-- markdownlint-disable MD033 -->
+# Overview
+
+## Driver components
+
+The driver consists on 3 main components
+
+- [vSphere CSI Controller](#vsphere_csi_controller)
+- [vSphere CSI Node](#vsphere_csi_node)
+- [Syncer](#syncer)
+  - [Metadata Syncer](#metadata_syncer)
+  - [Full Sync](#full_sync)
+  - [CnsOperator](#cns_operator)
+
+### vSphere CSI Controller<a id="vsphere_csi_controller"></a>
+
+The vSphere Container Storage Interface (CSI) Controller provides a CSI interface used by Container Orchestrators to manage the lifecycle of vSphere volumes.
+
+vSphere CSI Controller is responsible for volume provisioning, attaching and detaching the volume to VMs, mounting, formatting and unmounting volumes from the pod within the node VM etc.
+
+### vSphere CSI Node<a id="vsphere_csi_node"></a>
+
+vSphere CSI Node is responsible for formatting, mounting the volumes to node and bindmount the volumes inside the pod. The vSphere CSI Node runs as a deamonset inside the cluster.
+
+### Syncer<a id="syncer"></a>
+
+#### Metadata Syncer<a id="metadata_syncer"></a>
+
+The syncer is responsible for pushing PV, PVC and Pod metadata to CNS.
+These metadata will be shown in CNS dashboard (aka CNS UI) to help vSphere admin to get insights into which Kubernetes cluster(s), which app(s), Pod(s), PVC(s), PV(s) are using the volume.
+
+#### Full Sync<a id="full_sync"></a>
+
+Full sync is responsible for keeping CNS up to date with Kubernetes volume metadata information like PV, PVC and Pod etc. Some cases where full sync would be helpful are listed below:
+
+- CNS goes down
+- CSI Pod goes down
+- API server goes down / K8s core services goes down
+- VC is restored to a backup point
+- etcd is restored to a backup point
+
+#### CnsOperator<a id="cns_operator"></a>
+
+CnsOperator is used in the context of Project Pacific. CnsOperator is responsible for
+
+- attach/detach volumes to Tanzu K8S Grid VMs
+- pushing Tanzu K8S Grid PV, PVC and Pod metadata to CNS
+
+## Driver flavors
+
+vSphere CSI driver supports various flavors
+
+- [Vanilla Kubernetes](https://github.com/kubernetes/kubernetes)
+  - Support for block volumes.
+  - Support for file volumes.
+
+- [Project Pacific](https://blogs.vmware.com/vsphere/2019/08/introducing-project-pacific.html)
+  - In Project Pacific, vSphere CSI driver is called CNS CSI driver.
+  - Support for block volumes.
+
+- [Tanzu Kubernetes Grid](https://blogs.vmware.com/vsphere/2020/03/vsphere-7-tanzu-kubernetes-clusters.html)
+  - In Tanzu Kubernetes Grid, vSphere CSI driver is called pvCSI driver.
+  - Support for block volumes.

docs/book/troubleshooting.md

@@ -0,0 +1,76 @@
+# Troubleshooting
+
+vSphere CSI Driver supports 2 levels of logging
+
+- PRODUCTION where all INFO/ERROR logs are logged
+- DEVELOPMENT where all INFO/ERROR/DEBUG logs are logged
+
+The default log level for all the CSI flavors is PRODUCTION. To be able to examine problems related to your environment, modify the log level for the vSphere CSI driver from PRODUCTION to DEVELOPMENT.
+
+**NOTE**: PRODUCTION/DEVELOPMENT log level is available in 2.0 release. For prior releases, use the argument "--v" to change the log level.
+
+## Procedure to change log level
+
+### Vanilla CSI Driver
+
+- To examine the vSphere CSI controller related issues, update the log level for the vsphere-csi-controller and vsphere-syncer containers.
+  - Open the YAML file used for the deployment of vSphere CSI controller and find the LOGGER_LEVEL option in the container's arguments.
+  - Update the logger for this option from PRODUCTION to DEVELOPMENT which will give debug logs too.
+  - Run the kubectl apply command to reload the pods with new configuration.
+
+    ``` sh
+    kubectl apply -f vsphere-csi-controller-deployment.yaml
+    ```
+
+- Also update the log level for vsphere-csi-node daemon set
+  - Open the YAML file used for the vSphere CSI daemonset and find the LOGGER_LEVEL option in the container's arguments.
+  - Update the logger for this option from PRODUCTION to DEVELOPMENT which will give debug logs too.
+  - Run the kubectl apply command to reload the daemonset with new configuration.
+
+    ``` sh
+    kubectl apply -f vsphere-csi-node-ds.yaml
+    ```
+
+### CNS-CSI driver
+
+- To examine the CNS CSI driver related issues, update the log level for the vsphere-csi-controller and vsphere-syncer containers.
+  - CNS-CSI driver on Project Pacific Cluster is deployed on vmware-system-csi namespace as Kubernetes deployments.
+  - Edit the deployment of vSphere CSI controller and find the LOGGER_LEVEL option in the container's arguments.
+
+    ``` sh
+    kubectl edit deployment vsphere-csi-controller -n vmware-system-csi
+    ```
+
+  - Update the logger for this option from PRODUCTION to DEVELOPMENT which will give debug logs too.
+
+### pvCSI Driver
+
+- To examine the pvCSI controller related issues, update the log level for the vsphere-csi-controller and vsphere-syncer.
+  - pvCSI controller on Tanzu Kubernetes Grid is deployed on vmware-system-csi namespace as Kubernetes deployments.
+  - Edit the deployment of pvCSI controller and find the LOGGER_LEVEL option in the container's arguments.
+
+    ``` sh
+    kubectl edit deployment vsphere-csi-controller -n vmware-system-csi
+    ```
+
+  - Update the logger for this option from PRODUCTION to DEVELOPMENT which will give debug logs too.
+
+- To examine the pvCSI node daemon set related issues, update the log level for the vsphere-csi-node daemon set
+  - pvCSI node daemon on Tanzu Kubernetes Grid is deployed on vmware-system-csi namespace as Kubernetes DaemonSet.
+  - Edit the pvCSI node daemon and find the LOGGER_LEVEL option in the container's arguments.
+
+    ``` sh
+    kubectl edit daemonset vsphere-csi-node -n vmware-system-csi
+    ```
+
+  - Update the logger for this option from PRODUCTION to DEVELOPMENT which will give debug logs too.
+
+## Procedure to view the logs
+
+``` sh
+kubectl logs -f <pod-name> -c <container-name> -n <namespace>
+
+<pod-name> is the name of CSI controller pod
+<container-name> is the name of the container
+<namespace> is where the CSI driver is deployed
+```