diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index e4e8c02e6d6..34a2a7ef129 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -604,6 +604,16 @@ pg_upgrade.exe
pg_upgrade requires write permission in the current directory.
+
+
+ In order for pg_upgrade to safely be able
+ to start and stop the clusters they must reside in a shared process
+ namespace. If either cluster is isolated in a container it must share
+ process namespace with pg_upgrade to avoid
+ the risk of data corruption.
+
+
+
Obviously, no one should be accessing the clusters during the
upgrade. pg_upgrade defaults to running servers