Add warning about AWS EFS and performance

1 files changed, 17 insertions, 0 deletions

diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md
index c5125dc6d5a..82bb5689d0a 100644
--- a/doc/administration/high_availability/nfs.md
+++ b/doc/administration/high_availability/nfs.md
@@ -7,6 +7,23 @@ supported natively in NFS version 4. NFSv3 also supports locking as long as
 Linux Kernel 2.6.5+ is used. We recommend using version 4 and do not
 specifically test NFSv3.
 
+## AWS Elastic File System (EFS) not recommended
+
+Customers and users have reported that AWS EFS does not perform well for GitLab's
+use-case. There are several issues that can cause problems. For these reasons
+GitLab recommends against using EFS with GitLab.
+
+- EFS bases allowed IOPS on volume size. The larger the volume, the more IOPS
+  are allocated. For smaller volumes, users may experience decent performance
+  for a period of time due to 'Burst Credits'. Over a period of weeks to months
+  credits may run out and performance will bottom out.
+- For larger volumes, allocated IOPS may not be the problem. Workloads where
+  many small files are written in a serialized manner are not well-suited for EFS.
+  EBS with an NFS server on top will perform much better.
+
+For more details on another person's experience with EFS, see
+[Amazon's Elastic File System: Burst Credits]()https://www.rawkode.io/2017/04/amazons-elastic-file-system-burst-credits/
+
 ### Recommended options
 
 When you define your NFS exports, we recommend you also add the following