added docs
diff --git a/docs/storage.md b/docs/storage.md
index d255aa4..07d5f9e 100644
--- a/docs/storage.md
+++ b/docs/storage.md
@@ -1,5 +1,78 @@
# Storage
+## Enable RBD persistent write-back cache
+
+There are frequently cases of environments that sustain write-heavy loads which can overwhelm the underlying storage OSDs. It's also possible that non-enterprise 3D NAND flash is in use with small memory buffers which can do fast upfront writes but unable to sustain those writes.
+
+In those environments, it's possible that a lot of slow operations will start to cumulate inside of the cluster, which will bubble up as performance issues inside the virtual machines. This can be highly impactful on workloads, increase the latency of the VMs and drop IOPs down to near zero.
+
+There are environments that have local storage on all of the RBD clients (in this case, VMs) which can potentially be backed by battery backed hardware RAID with a local cache. This can significantly drive down the latency and increase write speeds since they are persisted onto the local system. The only fallback is that if the client crashes (or hypervisor in this case), the data won't easily be recoverable, however, this is a small risk to take in workloads replacing the storage infrastructure is not realistic and the stability of systems is relatively high.
+
+### Configuring compute hosts
+
+There are a few steps that needs to be done on the underlying operating system
+which runs the compute nodes. The steps bellow assumes that a device `/deb/<dev>`
+is already setup accordingly to the host's storage capabilities.
+
+1. Create filesystem for cache:
+
+ ```yaml
+ mkfs.ext4 /dev/<dev>
+ ```
+
+2. Get fs uuid
+ ```yaml
+ blkid
+ ```
+
+3. Add record to mount filesystem in `/etc/fstab`:
+ ```yaml
+ UUID="XXXXX" /var/lib/libvirt/rbd-cache ext4 defaults 0 1
+ ```
+
+4. Create folder for cache
+ ```yaml
+ mkdir /var/lib/libvirt/rbd-cache
+ ```
+
+5. Mount the cache
+ ```yaml
+ mount /var/lib/libvirt/rbd-cache
+ ```
+
+### Enabling rbd write-back cache
+
+In order to be able to confirgure write-back cache, you need to override the following
+values for ceph provisioners to your Ansible inventory:
+
+```yaml
+openstack_helm_infra_ceph_provisioners_values:
+ conf:
+ ceph:
+ global:
+ rbd_plugins: pwl_cache
+ rbd_persistent_cache_mode: ssd
+ rbd_persistent_cache_path: /var/lib/libvirt/rbd-cache
+ rbd_persistent_cache_size: 30G
+```
+
+### Verifying
+
+Once the configurations are applied to the ceph provisioners, once you create a virtual machine backed by ceph, you should be able to see a file for cache inside `/var/lib/libvirt/rbd-cache`:
+
+```yaml
+/var/lib/libvirt# ls -l rbd-cache/
+total 344
+drwxrwxr-x 2 42424 syslog 16384 Nov 30 20:38 lost+found
+-rw-r--r-- 1 42424 syslog 29999759360 Dec 1 17:37 rbd-pwl.cinder.volumes.a8eba89efc83.pool
+```
+
+ > **Note**
+>
+> For existing vms to take advantage of write-back cache, you will need
+to hard reboot them.
+
+
## External storage
When using an external storage platform, it's important to create to disable Ceph