XTesting/kubespray/docs/cinder-csi.md

   1 # Cinder CSI Driver
   2
   3 Cinder CSI driver allows you to provision volumes over an OpenStack deployment. The Kubernetes historic in-tree cloud provider is deprecated and will be removed in future versions.
   4
   5 To enable Cinder CSI driver, uncomment the `cinder_csi_enabled` option in `group_vars/all/openstack.yml` and set it to `true`.
   6
   7 To set the number of replicas for the Cinder CSI controller, you can change `cinder_csi_controller_replicas` option in `group_vars/all/openstack.yml`.
   8
   9 You need to source the OpenStack credentials you use to deploy your machines that will host Kubernetes: `source path/to/your/openstack-rc` or `. path/to/your/openstack-rc`.
  10
  11 Make sure the hostnames in your `inventory` file are identical to your instance names in OpenStack. Otherwise [cinder](https://docs.openstack.org/cinder/latest/) won't work as expected.
  12
  13 If you want to deploy the cinder provisioner used with Cinder CSI Driver, you should set `persistent_volumes_enabled` in `group_vars/k8s_cluster/k8s_cluster.yml` to `true`.
  14
  15 You can now run the kubespray playbook (cluster.yml) to deploy Kubernetes over OpenStack with Cinder CSI Driver enabled.
  16
  17 ## Usage example
  18
  19 To check if Cinder CSI Driver works properly, see first that the cinder-csi pods are running:
  20
  21 ```ShellSession
  22 $ kubectl -n kube-system get pods | grep cinder
  23 csi-cinder-controllerplugin-7f8bf99785-cpb5v   5/5     Running   0          100m
  24 csi-cinder-nodeplugin-rm5x2                    2/2     Running   0          100m
  25 ```
  26
  27 Check the associated storage class (if you enabled persistent_volumes):
  28
  29 ```ShellSession
  30 $ kubectl get storageclass
  31 NAME         PROVISIONER                AGE
  32 cinder-csi   cinder.csi.openstack.org   100m
  33 ```
  34
  35 You can run a PVC and an Nginx Pod using this file `nginx.yaml`:
  36
  37 ```yml
  38 ---
  39 apiVersion: v1
  40 kind: PersistentVolumeClaim
  41 metadata:
  42   name: csi-pvc-cinderplugin
  43 spec:
  44   accessModes:
  45   - ReadWriteOnce
  46   resources:
  47     requests:
  48       storage: 1Gi
  49   storageClassName: cinder-csi
  50
  51 ---
  52 apiVersion: v1
  53 kind: Pod
  54 metadata:
  55   name: nginx
  56 spec:
  57   containers:
  58   - image: nginx
  59     imagePullPolicy: IfNotPresent
  60     name: nginx
  61     ports:
  62     - containerPort: 80
  63       protocol: TCP
  64     volumeMounts:
  65       - mountPath: /var/lib/www/html
  66         name: csi-data-cinderplugin
  67   volumes:
  68   - name: csi-data-cinderplugin
  69     persistentVolumeClaim:
  70       claimName: csi-pvc-cinderplugin
  71       readOnly: false
  72 ```
  73
  74 Apply this conf to your cluster: ```kubectl apply -f nginx.yml```
  75
  76 You should see the PVC provisioned and bound:
  77
  78 ```ShellSession
  79 $ kubectl get pvc
  80 NAME                   STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
  81 csi-pvc-cinderplugin   Bound    pvc-f21ad0a1-5b7b-405e-a462-48da5cb76beb   1Gi        RWO            cinder-csi     8s
  82 ```
  83
  84 And the volume mounted to the Nginx Pod (wait until the Pod is Running):
  85
  86 ```ShellSession
  87 kubectl exec -it nginx -- df -h | grep /var/lib/www/html
  88 /dev/vdb        976M  2.6M  958M   1% /var/lib/www/html
  89 ```
  90
  91 ## Compatibility with in-tree cloud provider
  92
  93 It is not necessary to enable OpenStack as a cloud provider for Cinder CSI Driver to work.
  94 Though, you can run both the in-tree openstack cloud provider and the Cinder CSI Driver at the same time. The storage class provisioners associated to each one of them are differently named.
  95
  96 ## Cinder v2 support
  97
  98 For the moment, only Cinder v3 is supported by the CSI Driver.
  99
 100 ## More info
 101
 102 For further information about the Cinder CSI Driver, you can refer to this page: [Cloud Provider OpenStack](https://github.com/kubernetes/cloud-provider-openstack/blob/master/docs/using-cinder-csi-plugin.md).