XTesting/kubespray/docs/kubernetes-apps/local_volume_provisioner.md

   1 # Local Storage Provisioner
   2
   3 The [local storage provisioner](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume)
   4 is NOT a dynamic storage provisioner as you would
   5 expect from a cloud provider. Instead, it simply creates PersistentVolumes for
   6 all mounts under the host_dir of the specified storage class.
   7 These storage classes are specified in the `local_volume_provisioner_storage_classes` nested dictionary.
   8 Example:
   9
  10 ```yaml
  11 local_volume_provisioner_storage_classes:
  12   local-storage:
  13     host_dir: /mnt/disks
  14     mount_dir: /mnt/disks
  15   fast-disks:
  16     host_dir: /mnt/fast-disks
  17     mount_dir: /mnt/fast-disks
  18     block_cleaner_command:
  19        - "/scripts/shred.sh"
  20        - "2"
  21     volume_mode: Filesystem
  22     fs_type: ext4
  23 ```
  24
  25 For each key in `local_volume_provisioner_storage_classes` a storageClass with the
  26 same name is created. The subkeys of each storage class are converted to camelCase and added
  27 as attributes to the storageClass.
  28 The result of the above example is:
  29
  30 ```yaml
  31 data:
  32   storageClassMap: |
  33     local-storage:
  34       hostDir: /mnt/disks
  35       mountDir: /mnt/disks
  36     fast-disks:
  37       hostDir: /mnt/fast-disks
  38       mountDir:  /mnt/fast-disks
  39       blockCleanerCommand:
  40         - "/scripts/shred.sh"
  41         - "2"
  42       volumeMode: Filesystem
  43       fsType: ext4
  44 ```
  45
  46 The default StorageClass is local-storage on /mnt/disks,
  47 the rest of this doc will use that path as an example.
  48
  49 ## Examples to create local storage volumes
  50
  51 1. tmpfs method:
  52
  53 ``` bash
  54 for vol in vol1 vol2 vol3; do
  55 mkdir /mnt/disks/$vol
  56 mount -t tmpfs -o size=5G $vol /mnt/disks/$vol
  57 done
  58 ```
  59
  60 The tmpfs method is not recommended for production because the mount is not
  61 persistent and data will be deleted on reboot.
  62
  63 1. Mount physical disks
  64
  65 ``` bash
  66 mkdir /mnt/disks/ssd1
  67 mount /dev/vdb1 /mnt/disks/ssd1
  68 ```
  69
  70 Physical disks are recommended for production environments because it offers
  71 complete isolation in terms of I/O and capacity.
  72
  73 1. Mount unpartitioned physical devices
  74
  75 ``` bash
  76 for disk in /dev/sdc /dev/sdd /dev/sde; do
  77   ln -s $disk /mnt/disks
  78 done
  79 ```
  80
  81 This saves time of precreating filesystems. Note that your storageclass must have
  82 volume_mode set to "Filesystem" and fs_type defined. If either is not set, the
  83 disk will be added as a raw block device.
  84
  85 1. File-backed sparsefile method
  86
  87 ``` bash
  88 truncate /mnt/disks/disk5 --size 2G
  89 mkfs.ext4 /mnt/disks/disk5
  90 mkdir /mnt/disks/vol5
  91 mount /mnt/disks/disk5 /mnt/disks/vol5
  92 ```
  93
  94 If you have a development environment and only one disk, this is the best way
  95 to limit the quota of persistent volumes.
  96
  97 1. Simple directories
  98
  99 In a development environment using `mount --bind` works also, but there is no capacity
 100 management.
 101
 102 1. Block volumeMode PVs
 103
 104 Create a symbolic link under discovery directory to the block device on the node. To use
 105 raw block devices in pods, volume_type should be set to "Block".
 106
 107 ## Usage notes
 108
 109 Beta PV.NodeAffinity field is used by default. If running against an older K8s
 110 version, the useAlphaAPI flag must be set in the configMap.
 111
 112 The volume provisioner cannot calculate volume sizes correctly, so you should
 113 delete the daemonset pod on the relevant host after creating volumes. The pod
 114 will be recreated and read the size correctly.
 115
 116 Make sure to make any mounts persist via /etc/fstab or with systemd mounts (for
 117 Flatcar Container Linux). Pods with persistent volume claims will not be
 118 able to start if the mounts become unavailable.
 119
 120 ## Further reading
 121
 122 Refer to the upstream docs here: <https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume>