XTesting/kubespray/docs/vsphere-csi.md

   1 # vSphere CSI Driver
   2
   3 vSphere CSI driver allows you to provision volumes over a vSphere deployment. The Kubernetes historic in-tree cloud provider is deprecated and will be removed in future versions.
   4
   5 ## Prerequisites
   6
   7 The vSphere user for CSI driver requires a set of privileges to perform Cloud Native Storage operations. Follow the [official guide](https://vsphere-csi-driver.sigs.k8s.io/driver-deployment/prerequisites.html#roles_and_privileges) to configure those.
   8
   9 ## Kubespray configuration
  10
  11 To enable vSphere CSI driver, uncomment the `vsphere_csi_enabled` option in `group_vars/all/vsphere.yml` and set it to `true`.
  12
  13 To set the number of replicas for the vSphere CSI controller, you can change `vsphere_csi_controller_replicas` option in `group_vars/all/vsphere.yml`.
  14
  15 You need to source the vSphere credentials you use to deploy your machines that will host Kubernetes.
  16
  17 | Variable                                    | Required | Type    | Choices                    | Default                   | Comment                                                                                                             |
  18 |---------------------------------------------|----------|---------|----------------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------|
  19 | external_vsphere_vcenter_ip                 | TRUE     | string  |                            |                           | IP/URL of the vCenter                                                                                               |
  20 | external_vsphere_vcenter_port               | TRUE     | string  |                            | "443"                     | Port of the vCenter API                                                                                             |
  21 | external_vsphere_insecure                   | TRUE     | string  | "true", "false"            | "true"                    | set to "true" if the host above uses a self-signed cert                                                             |
  22 | external_vsphere_user                       | TRUE     | string  |                            |                           | User name for vCenter with required privileges (Can also be specified with the `VSPHERE_USER` environment variable) |
  23 | external_vsphere_password                   | TRUE     | string  |                            |                           | Password for vCenter (Can also be specified with the `VSPHERE_PASSWORD` environment variable)                       |
  24 | external_vsphere_datacenter                 | TRUE     | string  |                            |                           | Datacenter name to use                                                                                              |
  25 | external_vsphere_kubernetes_cluster_id      | TRUE     | string  |                            | "kubernetes-cluster-id"   | Kubernetes cluster ID to use                                                                                        |
  26 | external_vsphere_version                    | TRUE     | string  |                            | "6.7u3"                   | Vmware Vsphere version where located all VMs                                                                        |
  27 | external_vsphere_cloud_controller_image_tag          | TRUE     | string  |                            | "latest"                  | Kubernetes cluster ID to use                                                                                        |
  28 | vsphere_syncer_image_tag                    | TRUE     | string  |                            | "v2.2.1"                  | Syncer image tag to use                                                                                             |
  29 | vsphere_csi_attacher_image_tag              | TRUE     | string  |                            | "v3.1.0"                  | CSI attacher image tag to use                                                                                       |
  30 | vsphere_csi_controller                      | TRUE     | string  |                            | "v2.2.1"                  | CSI controller image tag to use                                                                                     |
  31 | vsphere_csi_controller_replicas             | TRUE     | integer |                            | 1                         | Number of pods Kubernetes should deploy for the CSI controller                                                      |
  32 | vsphere_csi_liveness_probe_image_tag        | TRUE     | string  |                            | "v2.2.0"                  | CSI liveness probe image tag to use                                                                                 |
  33 | vsphere_csi_provisioner_image_tag           | TRUE     | string  |                            | "v2.1.0"                  | CSI provisioner image tag to use                                                                                    |
  34 | vsphere_csi_node_driver_registrar_image_tag | TRUE     | string  |                            | "v1.1.0"                  | CSI node driver registrar image tag to use                                                                          |
  35 | vsphere_csi_driver_image_tag                | TRUE     | string  |                            | "v1.0.2"                  | CSI driver image tag to use                                                                                         |
  36 | vsphere_csi_resizer_tag                     | TRUE     | string  |                            | "v1.1.0"                  | CSI resizer image tag to use
  37 | vsphere_csi_aggressive_node_drain           | FALSE    | boolean |                            | false                     | Enable aggressive node drain strategy                                                                               |
  38 | vsphere_csi_aggressive_node_unreachable_timeout            | FALSE     | int  | 300   |                           | Timeout till node will be drained when it in an unreachable state                                                           |
  39 | vsphere_csi_aggressive_node_not_ready_timeout              | FALSE     | int  | 300   |                           | Timeout till node will be drained when it in not-ready state                                                                |
  40
  41 ## Usage example
  42
  43 To test the dynamic provisioning using vSphere CSI driver, make sure to create a [storage policy](https://github.com/kubernetes/cloud-provider-vsphere/blob/master/docs/book/tutorials/kubernetes-on-vsphere-with-kubeadm.md#create-a-storage-policy) and [storage class](https://github.com/kubernetes/cloud-provider-vsphere/blob/master/docs/book/tutorials/kubernetes-on-vsphere-with-kubeadm.md#create-a-storageclass), then apply the following manifest:
  44
  45 ```yml
  46 ---
  47 apiVersion: v1
  48 kind: PersistentVolumeClaim
  49 metadata:
  50   name: csi-pvc-vsphere
  51 spec:
  52   accessModes:
  53   - ReadWriteOnce
  54   resources:
  55     requests:
  56       storage: 1Gi
  57   storageClassName: Space-Efficient
  58
  59 ---
  60 apiVersion: v1
  61 kind: Pod
  62 metadata:
  63   name: nginx
  64 spec:
  65   containers:
  66   - image: nginx
  67     imagePullPolicy: IfNotPresent
  68     name: nginx
  69     ports:
  70     - containerPort: 80
  71       protocol: TCP
  72     volumeMounts:
  73       - mountPath: /usr/share/nginx/html
  74         name: csi-data-vsphere
  75   volumes:
  76   - name: csi-data-vsphere
  77     persistentVolumeClaim:
  78       claimName: csi-pvc-vsphere
  79       readOnly: false
  80 ```
  81
  82 Apply this conf to your cluster: ```kubectl apply -f nginx.yml```
  83
  84 You should see the PVC provisioned and bound:
  85
  86 ```ShellSession
  87 $ kubectl get pvc
  88 NAME              STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS      AGE
  89 csi-pvc-vsphere   Bound    pvc-dc7b1d21-ee41-45e1-98d9-e877cc1533ac   1Gi        RWO            Space-Efficient   10s
  90 ```
  91
  92 And the volume mounted to the Nginx Pod (wait until the Pod is Running):
  93
  94 ```ShellSession
  95 kubectl exec -it nginx -- df -h | grep /usr/share/nginx/html
  96 /dev/sdb         976M  2.6M  907M   1% /usr/share/nginx/html
  97 ```
  98
  99 ## More info
 100
 101 For further information about the vSphere CSI Driver, you can refer to the official [vSphere Cloud Provider documentation](https://cloud-provider-vsphere.sigs.k8s.io/container_storage_interface.html).