From 090d6e741f358fbe06b46e79a4f457823dc82e39 Mon Sep 17 00:00:00 2001
From: ayanx <98254953+byteayan@users.noreply.github.com>
Date: Tue, 20 Oct 2026 17:29:41 +0000
Subject: [PATCH 1/4] docs(docker): document the non-root PD, Store and Server
 images

Images built from current master run as UID/GID 10001. Add a chown step to
the PD and Store bind-mount examples, a troubleshooting entry for volumes
written by older root images, and the Helm fsGroup upgrade step, in English
and Chinese.

Pairs with apache/hugegraph#3381.
---
 .../cn/docs/guides/hugegraph-docker-cluster.md   | 11 +++++++++++
 .../docs/quickstart/hugegraph/hugegraph-helm.md  | 16 ++++++++++++++++
 .../quickstart/hugegraph/hugegraph-hstore.md     |  2 ++
 .../cn/docs/quickstart/hugegraph/hugegraph-pd.md |  2 ++
 .../quickstart/hugegraph/hugegraph-server.md     |  2 ++
 .../en/docs/guides/hugegraph-docker-cluster.md   | 12 ++++++++++++
 .../docs/quickstart/hugegraph/hugegraph-helm.md  | 16 ++++++++++++++++
 .../quickstart/hugegraph/hugegraph-hstore.md     |  2 ++
 .../en/docs/quickstart/hugegraph/hugegraph-pd.md |  2 ++
 .../quickstart/hugegraph/hugegraph-server.md     |  2 ++
 10 files changed, 67 insertions(+)

diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md
index 190868908..c9f03a49d 100644
--- a/content/cn/docs/guides/hugegraph-docker-cluster.md
+++ b/content/cn/docs/guides/hugegraph-docker-cluster.md
@@ -312,6 +312,17 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \
 
 5. **数据在意料之外地保留了下来**：`docker compose down` 会保留命名卷。要同时删除该拓扑的数据，请使用 `docker compose down -v`
 
+6. **升级到 master 构建的镜像后出现 `Permission denied`**：基于当前 master 构建的 PD、Store 和 Server 镜像以非 root 用户 `hugegraph`（UID/GID `10001`）运行。
+   旧镜像以 root 运行，写入的卷仍归 root 所有。先执行 `docker compose down`（不要用 `down -v`），对每个数据卷执行一次属主变更，再重新启动：
+
+   ```bash
+   docker run --rm -u 0 --entrypoint chown -v <volume>:/data <new-image> -R 10001:10001 /data
+   ```
+
+   不要对运行中的容器直接执行 `up -d` 升级：Compose 会重新挂载保存旧镜像应用目录（归 root 所有）的匿名卷。请先执行 `down`，或使用 `up -d --renew-anon-volumes`。
+   作为 bind mount 的宿主机目录必须对 UID `10001` 可写。在 Kubernetes 上，请在 Pod 安全上下文中设置 `fsGroup: 10001`，参见
+   [Helm 升级和验证](/cn/docs/quickstart/hugegraph/hugegraph-helm/#5-升级和验证)。
+
 **查看运行时日志**：使用 `docker logs <container-name>`（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的
 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；Hadoop、Netty 和 Commons 的
 INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。`/hugegraph-server/logs` 中包含 `hugegraph-server.log`、JVM
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
index 69eb34691..570b4ae57 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -222,6 +222,22 @@ helm test hugegraph -n hugegraph --logs --timeout 5m
 
 已有配置中的显式 helper 镜像也会保留。添加 `--set-string store.waitImage= --set-string server.waitImage=` 可清空覆盖并复用组件镜像。
 要采用新的默认值，先审阅已有配置，再使用 `--reset-values` 和保留镜像、凭据、存储、拓扑设置的配置文件。
+
+基于当前 master 构建的 PD、Store 和 Server 镜像以 UID/GID `10001` 运行；Chart 将 `pd.podSecurityContext` 和 `store.podSecurityContext` 默认设为
+`fsGroup: 10001`，使其能写入旧镜像（以 root 运行）创建的 PVC。`--reuse-values` 会保留已有 Release 的空值，而默认的 `latest` 标签配合 `pullPolicy: Always`
+可能在任意 Pod 重启时拉取新镜像，因此请先显式设置：
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroup=10001 \
+  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --set store.podSecurityContext.fsGroup=10001 \
+  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --wait --timeout 15m
+```
+
+如果 Pod 仍报 `Permission denied`，可在一次滚动更新中设置 `fsGroupChangePolicy: Always`，或执行一次 `chown -R 10001:10001`；CSI 驱动忽略 `fsGroup` 的卷
+（例如许多 NFS 驱动）和 `hostPath` 卷同样需要执行该 `chown`。
 PD 成员、持久存储和共享凭据变更需要按生命周期说明协调处理。
 
 `server.storageWaitTimeoutSeconds` 默认 300，通过 `WAIT_STORAGE_TIMEOUT_S` 传给启动脚本。
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md
index b3649bbf5..f00f2bb53 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md
@@ -111,6 +111,8 @@ set -a; . ./.env; set +a
 单独运行当前主线构建的 Store 时，将示例地址换成 Store 与 PD 均可路由的实际地址：
 
 ```bash
+# master 构建的镜像以 UID 10001 运行，宿主机数据目录必须对该用户可写
+mkdir -p /path/to/storage && sudo chown 10001:10001 /path/to/storage
 docker run -d \
   -p 8520:8520 -p 8500:8500 -p 8510:8510 \
   -e HG_STORE_PD_ADDRESS=192.168.1.10:8686 \
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md
index 337a63588..14351e204 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-pd.md
@@ -83,6 +83,8 @@ docker build -f hugegraph-pd/Dockerfile -t hugegraph/pd:local .
 
 ```bash
 export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)"
+# master 构建的镜像以 UID 10001 运行，宿主机数据目录必须对该用户可写
+mkdir -p /path/to/data && sudo chown 10001:10001 /path/to/data
 docker run -d \
   -p 8620:8620 -p 8686:8686 -p 8610:8610 \
   -e HG_PD_GRPC_HOST=192.168.1.10 \
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md
index 9ef4904a0..f590ec9af 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md
@@ -670,6 +670,8 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK
           - 8080:8080
     ```
 
+    基于当前 master 构建的 Server 镜像以非 root 的 UID `10001` 运行，挂载的脚本必须对该用户可读。
+
     使用命令 `docker compose up -d` 启动容器
 
 使用 RESTful API 请求 `HugeGraphServer` 得到如下结果：
diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md
index 0deb2ffe1..1da5670f2 100644
--- a/content/en/docs/guides/hugegraph-docker-cluster.md
+++ b/content/en/docs/guides/hugegraph-docker-cluster.md
@@ -317,6 +317,18 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD
 
 5. **Unexpected retained data**: `docker compose down` keeps named volumes. To delete topology data too, use `docker compose down -v`.
 
+6. **`Permission denied` after upgrading to master-built images**: PD, Store and Server images built from current master run as the non-root user
+   `hugegraph`, UID/GID `10001`. Volumes written by older images, which ran as root, stay owned by root. Stop with `docker compose down` (not `down -v`),
+   change the owner of each data volume once, then start again:
+
+   ```bash
+   docker run --rm -u 0 --entrypoint chown -v <volume>:/data <new-image> -R 10001:10001 /data
+   ```
+
+   Do not upgrade running containers with a plain `up -d`: Compose reattaches the anonymous volume holding the previous image's root-owned application
+   directory. Run `down` first, or use `up -d --renew-anon-volumes`. A host directory used as a bind mount must be writable by UID `10001`. On Kubernetes, set
+   `fsGroup: 10001` in the pod security context; see [Helm upgrade and verification](/docs/quickstart/hugegraph/hugegraph-helm/#5-upgrade-and-verification).
+
 **Runtime logs**: `docker logs <container-name>` (for example, `docker logs hg-pd0`) shows logs without entering containers. In images built from current
 master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout.
 For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; INFO from Hadoop, Netty and Commons and the audit and
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
index a87432cd3..ea817b7dc 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -230,6 +230,22 @@ helm test hugegraph -n hugegraph --logs --timeout 5m
 Existing explicit helper images also remain under `--reuse-values`;
 add `--set-string store.waitImage= --set-string server.waitImage=` to reuse component images.
 Adopt new defaults deliberately with `--reset-values` and a reviewed file retaining your image, credential, storage and topology settings.
+
+PD, Store and Server images built from current master run as UID/GID `10001`, and the chart defaults `pd.podSecurityContext` and
+`store.podSecurityContext` to `fsGroup: 10001` so they can write PVCs created by older images, which ran as root. `--reuse-values` keeps an existing
+release's empty value, and the default `latest` tag with `pullPolicy: Always` can pull the new image on any Pod restart, so set it explicitly first:
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroup=10001 \
+  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --set store.podSecurityContext.fsGroup=10001 \
+  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --wait --timeout 15m
+```
+
+If a Pod still reports `Permission denied`, set `fsGroupChangePolicy: Always` for one rollout or change the owner once with `chown -R 10001:10001`;
+volumes whose CSI driver ignores `fsGroup` (for example many NFS drivers) and `hostPath` volumes need that `chown` too.
 Do not treat PD membership, storage or credential changes as ordinary independent overrides; consult the lifecycle reference.
 
 `server.storageWaitTimeoutSeconds` defaults to 300 and is passed as `WAIT_STORAGE_TIMEOUT_S`. An unspecified startup probe threshold is derived
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md
index ad62bf4e3..708931b9e 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md
@@ -112,6 +112,8 @@ Multi-node service names are `pd0`–`pd2`, `store0`–`store2`, and `server0`
 To run master-built Store alone, replace example addresses with actual routable Store and PD addresses:
 
 ```bash
+# Master-built images run as UID 10001; the host data directory must be writable by it
+mkdir -p /path/to/storage && sudo chown 10001:10001 /path/to/storage
 docker run -d \
   -p 8520:8520 -p 8500:8500 -p 8510:8510 \
   -e HG_STORE_PD_ADDRESS=192.168.1.10:8686 \
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md
index 402142084..fa1e8b913 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-pd.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-pd.md
@@ -84,6 +84,8 @@ To run master-built PD alone, first set a deployment-specific secret and replace
 
 ```bash
 export HG_PD_AUTH_SECRET_KEY="$(openssl rand -hex 24)"
+# Master-built images run as UID 10001; the host data directory must be writable by it
+mkdir -p /path/to/data && sudo chown 10001:10001 /path/to/data
 docker run -d \
   -p 8620:8620 -p 8686:8686 -p 8610:8610 \
   -e HG_PD_GRPC_HOST=192.168.1.10 \
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md
index f1c899be9..1869bad10 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md
@@ -694,6 +694,8 @@ Set the environment variable `PRELOAD=true` when starting Docker so that sample
           - 8080:8080
     ```
 
+    Server images built from current master run as the non-root UID `10001`, so a mounted script must be readable by that user.
+
     Use `docker compose up -d` to start the container.
 
 And use the RESTful API to request `HugeGraphServer` and get the following result:

From a41e1881f0c4fb0b01dbf3bfd9b7bd20482be2cd Mon Sep 17 00:00:00 2001
From: ayanx <98254953+byteayan@users.noreply.github.com>
Date: Tue, 20 Oct 2026 22:08:40 +0000
Subject: [PATCH 2/4] docs(helm): the chart now keeps fsGroup under
 --reuse-values

apache/hugegraph#3381 applies the PD and Store fsGroup in the chart
templates, so an upgrade with --reuse-values no longer needs explicit
--set flags. Drop them from the English and Chinese upgrade notes.
---
 .../cn/docs/guides/hugegraph-docker-cluster.md   |  2 +-
 .../docs/quickstart/hugegraph/hugegraph-helm.md  | 15 +++------------
 .../en/docs/guides/hugegraph-docker-cluster.md   |  5 +++--
 .../docs/quickstart/hugegraph/hugegraph-helm.md  | 16 ++++------------
 4 files changed, 11 insertions(+), 27 deletions(-)

diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md
index c9f03a49d..7c3a17eb0 100644
--- a/content/cn/docs/guides/hugegraph-docker-cluster.md
+++ b/content/cn/docs/guides/hugegraph-docker-cluster.md
@@ -320,7 +320,7 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \
    ```
 
    不要对运行中的容器直接执行 `up -d` 升级：Compose 会重新挂载保存旧镜像应用目录（归 root 所有）的匿名卷。请先执行 `down`，或使用 `up -d --renew-anon-volumes`。
-   作为 bind mount 的宿主机目录必须对 UID `10001` 可写。在 Kubernetes 上，请在 Pod 安全上下文中设置 `fsGroup: 10001`，参见
+   作为 bind mount 的宿主机目录必须对 UID `10001` 可写。在 Kubernetes 上，Pod 安全上下文需要 `fsGroup: 10001`，Helm Chart 已为 PD 和 Store 设置，参见
    [Helm 升级和验证](/cn/docs/quickstart/hugegraph/hugegraph-helm/#5-升级和验证)。
 
 **查看运行时日志**：使用 `docker logs <container-name>`（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的
diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
index 570b4ae57..c9329cb46 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -223,18 +223,9 @@ helm test hugegraph -n hugegraph --logs --timeout 5m
 已有配置中的显式 helper 镜像也会保留。添加 `--set-string store.waitImage= --set-string server.waitImage=` 可清空覆盖并复用组件镜像。
 要采用新的默认值，先审阅已有配置，再使用 `--reset-values` 和保留镜像、凭据、存储、拓扑设置的配置文件。
 
-基于当前 master 构建的 PD、Store 和 Server 镜像以 UID/GID `10001` 运行；Chart 将 `pd.podSecurityContext` 和 `store.podSecurityContext` 默认设为
-`fsGroup: 10001`，使其能写入旧镜像（以 root 运行）创建的 PVC。`--reuse-values` 会保留已有 Release 的空值，而默认的 `latest` 标签配合 `pullPolicy: Always`
-可能在任意 Pod 重启时拉取新镜像，因此请先显式设置：
-
-```bash
-helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
-  --set pd.podSecurityContext.fsGroup=10001 \
-  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
-  --set store.podSecurityContext.fsGroup=10001 \
-  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
-  --wait --timeout 15m
-```
+基于当前 master 构建的 PD、Store 和 Server 镜像以 UID/GID `10001` 运行。除非 `podSecurityContext` 已设置 `fsGroup`，Chart 会为 PD 和 Store Pod 设置
+`fsGroup: 10001`（以及 `fsGroupChangePolicy: OnRootMismatch`），即使 `--reuse-values` 保留了旧 Release 的空值也是如此，使其能写入旧镜像（以 root 运行）创建的 PVC。
+默认的 `latest` 标签配合 `pullPolicy: Always` 可能在任意 Pod 重启时拉取新镜像，因此请在此之前升级 Chart，或在升级前固定旧镜像标签。
 
 如果 Pod 仍报 `Permission denied`，可在一次滚动更新中设置 `fsGroupChangePolicy: Always`，或执行一次 `chown -R 10001:10001`；CSI 驱动忽略 `fsGroup` 的卷
 （例如许多 NFS 驱动）和 `hostPath` 卷同样需要执行该 `chown`。
diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md
index 1da5670f2..ab2bedc41 100644
--- a/content/en/docs/guides/hugegraph-docker-cluster.md
+++ b/content/en/docs/guides/hugegraph-docker-cluster.md
@@ -326,8 +326,9 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD
    ```
 
    Do not upgrade running containers with a plain `up -d`: Compose reattaches the anonymous volume holding the previous image's root-owned application
-   directory. Run `down` first, or use `up -d --renew-anon-volumes`. A host directory used as a bind mount must be writable by UID `10001`. On Kubernetes, set
-   `fsGroup: 10001` in the pod security context; see [Helm upgrade and verification](/docs/quickstart/hugegraph/hugegraph-helm/#5-upgrade-and-verification).
+   directory. Run `down` first, or use `up -d --renew-anon-volumes`. A host directory used as a bind mount must be writable by UID `10001`. On Kubernetes,
+   the pod security context needs `fsGroup: 10001`, which the Helm chart sets for PD and Store; see [Helm upgrade and
+   verification](/docs/quickstart/hugegraph/hugegraph-helm/#5-upgrade-and-verification).
 
 **Runtime logs**: `docker logs <container-name>` (for example, `docker logs hg-pd0`) shows logs without entering containers. In images built from current
 master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout.
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
index ea817b7dc..ed03d8e37 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -231,18 +231,10 @@ Existing explicit helper images also remain under `--reuse-values`;
 add `--set-string store.waitImage= --set-string server.waitImage=` to reuse component images.
 Adopt new defaults deliberately with `--reset-values` and a reviewed file retaining your image, credential, storage and topology settings.
 
-PD, Store and Server images built from current master run as UID/GID `10001`, and the chart defaults `pd.podSecurityContext` and
-`store.podSecurityContext` to `fsGroup: 10001` so they can write PVCs created by older images, which ran as root. `--reuse-values` keeps an existing
-release's empty value, and the default `latest` tag with `pullPolicy: Always` can pull the new image on any Pod restart, so set it explicitly first:
-
-```bash
-helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
-  --set pd.podSecurityContext.fsGroup=10001 \
-  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
-  --set store.podSecurityContext.fsGroup=10001 \
-  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
-  --wait --timeout 15m
-```
+PD, Store and Server images built from current master run as UID/GID `10001`. The chart gives the PD and Store pods `fsGroup: 10001` (with
+`fsGroupChangePolicy: OnRootMismatch`) unless their `podSecurityContext` sets `fsGroup`, also when `--reuse-values` keeps an older release's empty value,
+so they can write PVCs created by older images, which ran as root. The default `latest` tag with `pullPolicy: Always` can pull the new image on any Pod
+restart, so upgrade the chart before that happens, or pin the old image tags until you do.
 
 If a Pod still reports `Permission denied`, set `fsGroupChangePolicy: Always` for one rollout or change the owner once with `chown -R 10001:10001`;
 volumes whose CSI driver ignores `fsGroup` (for example many NFS drivers) and `hostPath` volumes need that `chown` too.

From 2d0308612e63ee6469c1fd55781ae6ebe0b1c9f5 Mon Sep 17 00:00:00 2001
From: ayanx <98254953+byteayan@users.noreply.github.com>
Date: Wed, 21 Oct 2026 02:10:26 +0000
Subject: [PATCH 3/4] docs(helm): switch to the non-root images in the fsGroup
 rollout

Mirror apache/hugegraph#3381: switch PD and Store to the 10001 images in
the same rollout that first applies fsGroup, and use a one-time
fsGroupChangePolicy=Always rollout when root images already ran with it.
---
 .../quickstart/hugegraph/hugegraph-helm.md    | 18 +++++++++++++---
 .../quickstart/hugegraph/hugegraph-helm.md    | 21 +++++++++++++++----
 2 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
index c9329cb46..a347ab448 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -225,10 +225,22 @@ helm test hugegraph -n hugegraph --logs --timeout 5m
 
 基于当前 master 构建的 PD、Store 和 Server 镜像以 UID/GID `10001` 运行。除非 `podSecurityContext` 已设置 `fsGroup`，Chart 会为 PD 和 Store Pod 设置
 `fsGroup: 10001`（以及 `fsGroupChangePolicy: OnRootMismatch`），即使 `--reuse-values` 保留了旧 Release 的空值也是如此，使其能写入旧镜像（以 root 运行）创建的 PVC。
-默认的 `latest` 标签配合 `pullPolicy: Always` 可能在任意 Pod 重启时拉取新镜像，因此请在此之前升级 Chart，或在升级前固定旧镜像标签。
 
-如果 Pod 仍报 `Permission denied`，可在一次滚动更新中设置 `fsGroupChangePolicy: Always`，或执行一次 `chown -R 10001:10001`；CSI 驱动忽略 `fsGroup` 的卷
-（例如许多 NFS 驱动）和 `hostPath` 卷同样需要执行该 `chown`。
+请在首次应用 `fsGroup` 的同一次滚动更新中，将 PD 和 Store 切换到基于此版本构建的镜像，使 kubelet 在 `10001` 镜像启动前修改卷的属主。不要先用仍以 root
+运行的镜像（例如尚未更新到此版本的 `latest`）运行此 Chart：这些镜像创建的文件归 root 所有，而 `OnRootMismatch` 只检查卷的根目录，之后不会再修正它们。
+请将 `pd.image` 和 `store.image` 固定为基于此版本构建的镜像，而不要依赖 `latest`。
+
+如果 Release 已在设置了 `fsGroup` 的情况下运行过 root 镜像，请在首次滚动更新到 `10001` 镜像时执行一次递归属主变更，并在下次升级时改回
+`OnRootMismatch`，因为 `Always` 会在每次 Pod 启动时遍历整个卷：
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroupChangePolicy=Always \
+  --set store.podSecurityContext.fsGroupChangePolicy=Always \
+  --wait --timeout 15m
+```
+
+CSI 驱动忽略 `fsGroup` 的卷（例如许多 NFS 驱动）和 `hostPath` 卷需要改为执行一次 `chown -R 10001:10001`。
 PD 成员、持久存储和共享凭据变更需要按生命周期说明协调处理。
 
 `server.storageWaitTimeoutSeconds` 默认 300，通过 `WAIT_STORAGE_TIMEOUT_S` 传给启动脚本。
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
index ed03d8e37..2ec96d312 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -233,11 +233,24 @@ Adopt new defaults deliberately with `--reset-values` and a reviewed file retain
 
 PD, Store and Server images built from current master run as UID/GID `10001`. The chart gives the PD and Store pods `fsGroup: 10001` (with
 `fsGroupChangePolicy: OnRootMismatch`) unless their `podSecurityContext` sets `fsGroup`, also when `--reuse-values` keeps an older release's empty value,
-so they can write PVCs created by older images, which ran as root. The default `latest` tag with `pullPolicy: Always` can pull the new image on any Pod
-restart, so upgrade the chart before that happens, or pin the old image tags until you do.
+so they can write PVCs created by older images, which ran as root.
 
-If a Pod still reports `Permission denied`, set `fsGroupChangePolicy: Always` for one rollout or change the owner once with `chown -R 10001:10001`;
-volumes whose CSI driver ignores `fsGroup` (for example many NFS drivers) and `hostPath` volumes need that `chown` too.
+Switch PD and Store to images built from this version in the same rollout that first applies `fsGroup`, so the kubelet changes the volume ownership right
+before the `10001` image starts. Do not run images that still run as root with this chart first, for example a `latest` that has not moved to this version:
+files they create stay owned by root, and `OnRootMismatch` checks only the volume root, so it does not fix them later. Pin `pd.image` and `store.image` to a
+build from this version rather than relying on `latest`.
+
+If a release already ran root images with `fsGroup` set, roll out the first `10001` image with a one-time recursive ownership change, then return to
+`OnRootMismatch` on the next upgrade, because `Always` walks the whole volume on every Pod start:
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroupChangePolicy=Always \
+  --set store.podSecurityContext.fsGroupChangePolicy=Always \
+  --wait --timeout 15m
+```
+
+Volumes whose CSI driver ignores `fsGroup` (for example many NFS drivers) and `hostPath` volumes need a one-time `chown -R 10001:10001` instead.
 Do not treat PD membership, storage or credential changes as ordinary independent overrides; consult the lifecycle reference.
 
 `server.storageWaitTimeoutSeconds` defaults to 300 and is passed as `WAIT_STORAGE_TIMEOUT_S`. An unspecified startup probe threshold is derived

From f777f3a455b22dc7da57fd0c8b2c160d560828e0 Mon Sep 17 00:00:00 2001
From: ayanx <98254953+byteayan@users.noreply.github.com>
Date: Wed, 21 Oct 2026 06:21:57 +0000
Subject: [PATCH 4/4] docs(helm): pin the image in the one-time Always rollout
 and switch back

Mirror apache/hugegraph#3381: set the 10001 image tags in the one-time
fsGroupChangePolicy=Always upgrade, and show the follow-up upgrade that
sets the policy back to OnRootMismatch.
---
 .../docs/quickstart/hugegraph/hugegraph-helm.md   | 15 +++++++++++++--
 .../docs/quickstart/hugegraph/hugegraph-helm.md   | 15 +++++++++++++--
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
index a347ab448..8b7ff2791 100644
--- a/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/cn/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -230,16 +230,27 @@ helm test hugegraph -n hugegraph --logs --timeout 5m
 运行的镜像（例如尚未更新到此版本的 `latest`）运行此 Chart：这些镜像创建的文件归 root 所有，而 `OnRootMismatch` 只检查卷的根目录，之后不会再修正它们。
 请将 `pd.image` 和 `store.image` 固定为基于此版本构建的镜像，而不要依赖 `latest`。
 
-如果 Release 已在设置了 `fsGroup` 的情况下运行过 root 镜像，请在首次滚动更新到 `10001` 镜像时执行一次递归属主变更，并在下次升级时改回
-`OnRootMismatch`，因为 `Always` 会在每次 Pod 启动时遍历整个卷：
+如果 Release 已在设置了 `fsGroup` 的情况下运行过 root 镜像，请在首次滚动更新到 `10001` 镜像的同时执行一次递归属主变更。请在同一条命令中设置镜像标签，
+使递归变更作用于 `10001` 镜像，而不是已固定的 root 镜像：
 
 ```bash
 helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.image.tag=<this-version> \
+  --set store.image.tag=<this-version> \
   --set pd.podSecurityContext.fsGroupChangePolicy=Always \
   --set store.podSecurityContext.fsGroupChangePolicy=Always \
   --wait --timeout 15m
 ```
 
+`--reuse-values` 会保留 `Always`，而它会在每次 Pod 启动时遍历整个卷，因此请在这些 Pod 运行后改回原策略：
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --wait --timeout 15m
+```
+
 CSI 驱动忽略 `fsGroup` 的卷（例如许多 NFS 驱动）和 `hostPath` 卷需要改为执行一次 `chown -R 10001:10001`。
 PD 成员、持久存储和共享凭据变更需要按生命周期说明协调处理。
 
diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
index 2ec96d312..1debbc058 100644
--- a/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
+++ b/content/en/docs/quickstart/hugegraph/hugegraph-helm.md
@@ -240,16 +240,27 @@ before the `10001` image starts. Do not run images that still run as root with t
 files they create stay owned by root, and `OnRootMismatch` checks only the volume root, so it does not fix them later. Pin `pd.image` and `store.image` to a
 build from this version rather than relying on `latest`.
 
-If a release already ran root images with `fsGroup` set, roll out the first `10001` image with a one-time recursive ownership change, then return to
-`OnRootMismatch` on the next upgrade, because `Always` walks the whole volume on every Pod start:
+If a release already ran root images with `fsGroup` set, roll out the first `10001` image together with a one-time recursive ownership change. Set the
+image tags in the same command, so the recursive change runs for the `10001` image rather than for a pinned root image:
 
 ```bash
 helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.image.tag=<this-version> \
+  --set store.image.tag=<this-version> \
   --set pd.podSecurityContext.fsGroupChangePolicy=Always \
   --set store.podSecurityContext.fsGroupChangePolicy=Always \
   --wait --timeout 15m
 ```
 
+`--reuse-values` keeps `Always`, which walks the whole volume on every Pod start, so set the policy back once those Pods are running:
+
+```bash
+helm upgrade hugegraph "$CHART" --devel -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --wait --timeout 15m
+```
+
 Volumes whose CSI driver ignores `fsGroup` (for example many NFS drivers) and `hostPath` volumes need a one-time `chown -R 10001:10001` instead.
 Do not treat PD membership, storage or credential changes as ordinary independent overrides; consult the lifecycle reference.