diff --git a/doc/administration/gitaly/praefect/_index.md b/doc/administration/gitaly/praefect/_index.md
index 806fb39dc69874e93d7d1a04879eab564e780b92..1b745098eedfcce143c2d2e1598d55ee9bce5ac9 100644
--- a/doc/administration/gitaly/praefect/_index.md
+++ b/doc/administration/gitaly/praefect/_index.md
@@ -412,6 +412,30 @@ To migrate to Gitaly Cluster (Praefect):
 Even if you don't use the `default` repository storage, you must ensure it is configured.
 [Read more about this limitation](../configure_gitaly.md#gitlab-requires-a-default-repository-storage).
 
+### Storage move considerations for Kubernetes deployments
+
+{{< alert type="warning" >}}
+
+Known issue with HPA and storage moves: When using Horizontal Pod Autoscaler (HPA) with Sidekiq pods, mass storage moves can fail silently due to pod scaling during job execution.
+
+{{< /alert >}}
+
+Before performing mass storage moves, configure HPA with fixed replicas:
+
+```yaml
+# Set minReplicas = maxReplicas to prevent scaling during migration
+spec:
+  minReplicas: 4
+  maxReplicas: 4
+```
+
+If a (bulk) migration has already failed due to this issue, failed projects can remain stuck in a read-only state. 
+Affected repositories can be recovered via the following steps:
+
+1. [Reset affected projects to read-write state](../../read_only_gitlab.md#make-the-repositories-read-only) using `gitlab-rails console`
+1. [Re-run storage moves via REST API](../../operations/moving_repositories.md) for individual projects
+1. Restore HPA configuration after migration completes
+
 ## Migrate off Gitaly Cluster (Praefect)
 
 If the limitations and tradeoffs of Gitaly Cluster (Praefect) are found to be not suitable for your environment, you can