XTesting/kubespray/docs/aws-ebs-csi.md

   1 # AWS EBS CSI Driver
   2
   3 AWS EBS CSI driver allows you to provision EBS volumes for pods in EC2 instances. The old in-tree AWS cloud provider is deprecated and will be removed in future versions of Kubernetes. So transitioning to the CSI driver is advised.
   4
   5 To enable AWS EBS CSI driver, uncomment the `aws_ebs_csi_enabled` option in `group_vars/all/aws.yml` and set it to `true`.
   6
   7 To set the number of replicas for the AWS CSI controller, you can change `aws_ebs_csi_controller_replicas` option in `group_vars/all/aws.yml`.
   8
   9 Make sure to add a role, for your EC2 instances hosting Kubernetes, that allows it to do the actions necessary to request a volume and attach it: [AWS CSI Policy](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/blob/master/docs/example-iam-policy.json)
  10
  11 If you want to deploy the AWS EBS storage class used with the CSI Driver, you should set `persistent_volumes_enabled` in `group_vars/k8s_cluster/k8s_cluster.yml` to `true`.
  12
  13 You can now run the kubespray playbook (cluster.yml) to deploy Kubernetes over AWS EC2 with EBS CSI Driver enabled.
  14
  15 ## Usage example
  16
  17 To check if AWS EBS CSI Driver is deployed properly, check that the ebs-csi pods are running:
  18
  19 ```ShellSession
  20 $ kubectl -n kube-system get pods | grep ebs
  21 ebs-csi-controller-85d86bccc5-8gtq5                                  4/4     Running   4          40s
  22 ebs-csi-node-n4b99                                                   3/3     Running   3          40s
  23 ```
  24
  25 Check the associated storage class (if you enabled persistent_volumes):
  26
  27 ```ShellSession
  28 $ kubectl get storageclass
  29 NAME         PROVISIONER                AGE
  30 ebs-sc       ebs.csi.aws.com            45s
  31 ```
  32
  33 You can run a PVC and an example Pod using this file `ebs-pod.yml`:
  34
  35 ```yml
  36 --
  37 apiVersion: v1
  38 kind: PersistentVolumeClaim
  39 metadata:
  40   name: ebs-claim
  41 spec:
  42   accessModes:
  43     - ReadWriteOnce
  44   storageClassName: ebs-sc
  45   resources:
  46     requests:
  47       storage: 1Gi
  48 ---
  49 apiVersion: v1
  50 kind: Pod
  51 metadata:
  52   name: app
  53 spec:
  54   containers:
  55   - name: app
  56     image: centos
  57     command: ["/bin/sh"]
  58     args: ["-c", "while true; do echo $(date -u) >> /data/out.txt; sleep 5; done"]
  59     volumeMounts:
  60     - name: persistent-storage
  61       mountPath: /data
  62   volumes:
  63   - name: persistent-storage
  64     persistentVolumeClaim:
  65       claimName: ebs-claim
  66 ```
  67
  68 Apply this conf to your cluster: ```kubectl apply -f ebs-pod.yml```
  69
  70 You should see the PVC provisioned and bound:
  71
  72 ```ShellSession
  73 $ kubectl get pvc
  74 NAME          STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
  75 ebs-claim     Bound    pvc-0034cb9e-1ddd-4b3f-bb9e-0b5edbf5194c   1Gi        RWO            ebs-sc         50s
  76 ```
  77
  78 And the volume mounted to the example Pod (wait until the Pod is Running):
  79
  80 ```ShellSession
  81 $ kubectl exec -it app -- df -h | grep data
  82 /dev/nvme1n1   1014M   34M  981M   4% /data
  83 ```
  84
  85 ## More info
  86
  87 For further information about the AWS EBS CSI Driver, you can refer to this page: [AWS EBS Driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/).