feat(docker): run PD, Store and Server images as a non-root user

.github/actions/helm-checks/action.yml

@@ -527,7 +527,13 @@ runs:
       cp -R helm/hugegraph "$LEGACY_ROOT/chart"
       cp helm/hugegraph/testdata/values-pre-hardening.yaml "$LEGACY_ROOT/chart/values.yaml"
       helm template legacy "$LEGACY_ROOT/chart" > /dev/null
-      helm template legacy "$LEGACY_ROOT/chart" --is-upgrade > /dev/null
+      LEGACY_UPGRADE=$(helm template legacy "$LEGACY_ROOT/chart" --is-upgrade)
+      # The non-root PD and Store images need fsGroup on their data volumes
+      # even when the reused values predate that default.
+      [ "$(grep -c 'fsGroup: 10001' <<<"$LEGACY_UPGRADE")" -eq 2 ] || {
+        echo "PD and Store must keep fsGroup 10001 under --reuse-values"
+        exit 1
+      }
 
   - name: helm package
     shell: 'bash -e {0}'

.github/scripts/check-docker-images.sh

@@ -30,6 +30,23 @@ for pair in \
         HC=$(docker image inspect --format '{{json .Config.Healthcheck}}' "$IMAGE_ID")
         [[ "$HC" != null ]] || { echo "Missing HEALTHCHECK: $dockerfile"; exit 1; }
 
+        # The images must run as the fixed non-root user and own the directories
+        # the start scripts and default volumes write to.
+        case "$dockerfile" in
+            hugegraph-pd/*) OWNED_DIRS=". logs pd_data" ;;
+            hugegraph-store/*) OWNED_DIRS=". logs storage" ;;
+            hugegraph-server/Dockerfile) OWNED_DIRS=". logs rocksdb-data" ;;
+            *) OWNED_DIRS=". logs" ;;
+        esac
+        IMAGE_USER=$(docker image inspect --format '{{.Config.User}}' "$IMAGE_ID")
+        RUNTIME_IDS=$(docker run --rm --pull never --entrypoint sh "$IMAGE_ID" -c \
+            'echo "$(id -u):$(id -g)" $(stat -c %u:%g "$@")' owners $OWNED_DIRS)
+        EXPECTED_IDS="10001:10001$(printf ' 10001:10001%.0s' $OWNED_DIRS)"
+        [[ "$IMAGE_USER" == 10001:10001 && "$RUNTIME_IDS" == "$EXPECTED_IDS" ]] || {
+            echo "ERROR: $dockerfile runs as '$IMAGE_USER' ($RUNTIME_IDS); expected 10001:10001 owning $OWNED_DIRS"
+            exit 1
+        }
+
         # Helm reuses these images for tool containers instead of pulling curlimages/curl.
         # Check the same non-root/read-only tool environment as the Server test hook.
         if [[ "$dockerfile" == hugegraph-store/* || "$dockerfile" == hugegraph-server/* ]]; then
@@ -73,7 +90,9 @@ for pair in \
         if [[ "$dockerfile" == hugegraph-server/* ]]; then
             CHECK_DIR=$(mktemp -d)
             trap 'rm -rf "$CHECK_DIR"' EXIT
-            docker run --rm --pull never --entrypoint bash \
+            # The image user cannot write the runner-owned temp dir, so copy
+            # the jars out as the runner's own uid.
+            docker run --rm --pull never --user "$(id -u):$(id -g)" --entrypoint bash \
                 -v "$CHECK_DIR:/check" "$IMAGE_ID" -c \
                 'cp /hugegraph-server/lib/hugegraph-api-*.jar \
                     /hugegraph-server/lib/hugegraph-common-*.jar /check/'

docker/README.md

@@ -285,6 +285,25 @@ Standalone stores RocksDB data at `/hugegraph-server/rocksdb-data`. The HStore t
 
 `docker compose down` keeps named-volume data. `docker compose down -v` intentionally deletes it.
 
+### Container user
+
+The PD, Store and Server images run as the non-root user `hugegraph`, UID/GID `10001:10001`. A new named volume mounted at a directory the image already has (the application directory, `pd_data`, `storage`, `rocksdb-data` or `logs`) starts out owned by that user; one mounted anywhere else, such as a custom `HG_PD_DATA_PATH` or `HG_STORE_DATA_PATH`, starts out owned by root and needs the `chown` below. A host directory used as a bind mount must be writable by UID `10001` (`sudo chown 10001:10001 <dir>`). A mounted file only needs to be readable, except Server configuration files that the entrypoint edits from environment variables, which must be writable by UID `10001`. Use `docker exec -u 0` for root access while debugging.
+
+<details>
+<summary>Upgrading data written by an image that ran as root</summary>
+
+Images built before this change, including 1.7.0 and earlier and older `latest` builds, run as root, so their volumes are owned by root and the new image fails with `Permission denied` on its first write. Stop the topology with `docker compose ... down` (not `down -v`), then change the owner of each data volume once with the new image:
+
+```bash
+docker run --rm -u 0 --entrypoint chown -v <volume>:/data <new-image> -R 10001:10001 /data
+```
+
+List the volumes with `docker volume ls`; Compose prefixes each name with the project name. Then start again with `docker compose ... up -d`. Do not upgrade running containers with a plain `up -d`: Compose reattaches the anonymous volume that holds the previous image's root-owned application directory. Run `down` first, or use `up -d --renew-anon-volumes`.
+
+On Kubernetes, set `fsGroup: 10001` (optionally with `fsGroupChangePolicy: OnRootMismatch`) in the pod security context so the user can write volumes created by older images. The [Helm chart](../helm/hugegraph) sets this for PD and Store unless their `podSecurityContext` sets `fsGroup`, also on releases upgraded with `--reuse-values`; see [Upgrade and verify](../helm/hugegraph/README.md#upgrade-and-verify).
+
+</details>
+
 ### Server service identity
 
 Server image builds containing this configuration mapping accept
@@ -352,7 +371,7 @@ Both Server images (`hugegraph/hugegraph` and `hugegraph/server`) write the Huge
 
 `/hugegraph-server/logs` holds `hugegraph-server.log`, JVM crash logs (`hs_err_pid<pid>_<host>_<launch time>.log`) and out-of-memory heap dumps (`heapdump_<host>_<launch time>/java_pid<pid>.hprof`), where `<launch time>` is the container's local time as `YYYYMMDD-HHMMSS`. Each start gets its own `heapdump_*` directory, so the Server and the JVMs it starts, such as computer jobs, write separate dumps. HotSpot names each dump and crash log after the JVM's PID, so a JVM that reuses the PID of an earlier one from the same start cannot write its dump, and its crash log replaces the earlier one's. The host name (on Kubernetes, the pod name, or `spec.hostname` when that is set) and a `-1`, `-2`, ... counter keep names from clashing; the counter also separates pods that share a host name. If the directory cannot be created, for example on a full volume, the Server still starts and dumps go to `logs/` itself as `java_pid<pid>.hprof`. That is best effort: a full volume may have no room for the dump either, and a restarted container that reuses a PID cannot write over an earlier dump with the same name. If the logs path contains a double quote or `%`, the launcher warns and heap dumps go to `logs/` itself, with no per-launch directory and no crash log default; the `JAVA_TOOL_OPTIONS` opt-out below still applies. A path that contains both quote characters gets no heap dump default at all.
 
-Both images declare `VOLUME /hugegraph-server`, so `docker restart` and a Compose recreate keep the files in that anonymous volume. `docker compose down` leaves the volume behind but the next `up` does not attach it, so the files become hard to reach and keep using disk. A later `docker compose down -v` does not remove that orphaned volume either, since it only removes anonymous volumes of the containers it removes; note the volume name with `docker inspect` before `down` and delete it with `docker volume rm <name>`, or stop with `docker compose down -v` in the first place. Avoid `docker volume prune` for this: it deletes every unused anonymous volume on the Docker host, including other projects' data. Mount a named volume or a bind mount at `/hugegraph-server/logs` to keep the files reachable. Kubernetes starts a new container on every restart and does not turn the image's `VOLUME` into a pod volume, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume, or a per-pod directory on a shared PVC: crash files get distinct names, but `hugegraph-server.log`, the audit log and the slow-query log have fixed names, and pods sharing them would roll them over for each other. For a per-pod directory, pass the pod name in through the Downward API and use it in `subPathExpr` (the Helm chart sets neither):
+Both images declare `VOLUME /hugegraph-server`, so `docker restart` and a Compose recreate keep the files in that anonymous volume. `docker compose down` leaves the volume behind but the next `up` does not attach it, so the files become hard to reach and keep using disk. A later `docker compose down -v` does not remove that orphaned volume either, since it only removes anonymous volumes of the containers it removes; note the volume name with `docker inspect` before `down` and delete it with `docker volume rm <name>`, or stop with `docker compose down -v` in the first place. Avoid `docker volume prune` for this: it deletes every unused anonymous volume on the Docker host, including other projects' data. Mount a named volume or a bind mount at `/hugegraph-server/logs` to keep the files reachable. Kubernetes starts a new container on every restart and does not turn the image's `VOLUME` into a pod volume, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`; for a PersistentVolumeClaim, set `fsGroup: 10001` in the Server pod security context so the non-root user can write it. Give each pod its own volume, or a per-pod directory on a shared PVC: crash files get distinct names, but `hugegraph-server.log`, the audit log and the slow-query log have fixed names, and pods sharing them would roll them over for each other. For a per-pod directory, pass the pod name in through the Downward API and use it in `subPathExpr` (the Helm chart sets neither):
 
 ```yaml
 env:
@@ -454,6 +473,7 @@ docker build -f hugegraph-server/Dockerfile -t hugegraph-standalone:local .
 | `MAVEN_PROJECTS` | Override the module selection; retain all three distributions required by the shared build and archive cleanup. |
 | `MAVEN_ARGS` | Pass other Maven options. |
 | `RUNTIME_DEPS_EPOCH` | Change the value to refresh cached OS packages without invalidating the Maven build stage. Default: `1`. |
+| `HG_UID`, `HG_GID` | UID and GID of the non-root `hugegraph` user that runs the image. Default: `10001`. The Helm chart's `fsGroup` default assumes `10001`. Bake does not read these from the environment; pass `--set '*.args.HG_UID=<uid>'`. |
 
 <details>
 <summary>Custom modules, package refresh, and cache behavior</summary>

helm/hugegraph/README.md

@@ -246,7 +246,62 @@ helm test hugegraph -n hugegraph --logs --timeout 5m
 An easy-mode upgrade that inherits Server/Hubble entry types prints a short
 NodePort-default notice in NOTES; explicitly configured entry types are preserved.
 To adopt new defaults, use `--reset-values` with a reviewed values file retaining
-all settings your release needs. Older explicit helper images also remain under
+all settings your release needs.
+
+PD, Store and Server images built from this version run as UID/GID `10001`. The
+PD and Store pods get `fsGroup: 10001` (with `fsGroupChangePolicy: OnRootMismatch`)
+unless their `podSecurityContext` sets `fsGroup`, also when `--reuse-values` keeps
+an older release's empty value, so that user can write PVCs created by older
+images, which ran as root.
+
+Switch PD and Store to images 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 the published `latest` before it moves 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`. A non-empty `image.digest` wins
+over `image.tag`, and `--reuse-values` keeps an existing digest, so a release
+pinned by digest must change the digest, not only the tag.
+
+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 images
+in the same command, so the recursive change runs for the `10001` image rather
+than for a pinned root image. The example clears any reused digest so the tag
+applies; a release pinned by digest sets `pd.image.digest` and
+`store.image.digest` to the digests of this version's images instead:
+
+```bash
+helm upgrade hugegraph ./helm/hugegraph -n hugegraph --reuse-values \
+  --set pd.image.tag=<this-version> \
+  --set store.image.tag=<this-version> \
+  --set-string pd.image.digest= \
+  --set-string store.image.digest= \
+  --set pd.podSecurityContext.fsGroupChangePolicy=Always \
+  --set store.podSecurityContext.fsGroupChangePolicy=Always \
+  --wait --timeout 15m
+```
+
+Before switching the policy back, check that every PD and Store Pod runs the
+`10001` image you set, not an older root image:
+
+```bash
+kubectl get pods -n hugegraph \
+  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
+```
+
+`--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 ./helm/hugegraph -n hugegraph --reuse-values \
+  --set pd.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --set store.podSecurityContext.fsGroupChangePolicy=OnRootMismatch \
+  --wait --timeout 15m
+```
+
+See [Storage and upgrades](docs/operations.md#storage-and-upgrades) for volumes
+the kubelet cannot change. Older explicit helper images also remain under
 value reuse; clear `store.waitImage` and `server.waitImage` to reuse component images.
 
 The admin Secret is an **initial credential**. Changing it alone does not rotate

helm/hugegraph/docs/operations.md

@@ -95,6 +95,24 @@ Inspect saved values before upgrading. `--reuse-values` preserves old effective
 settings, including disabled Hubble, ClusterIP and explicit helper images.
 Adopt new defaults only with reviewed values and `--reset-values`.
 
+PD, Store and Server images built from this version run as UID/GID `10001`. PD
+and Store need `podSecurityContext.fsGroup: 10001` to write PVCs created by older
+root images; the chart applies it unless `fsGroup` is set, including under
+`--reuse-values` (see [Upgrade and verify](../README.md#upgrade-and-verify)). With
+`fsGroupChangePolicy: OnRootMismatch` the kubelet fixes ownership only when the
+volume root does not match, so switch to the `10001` images in the same rollout
+that first applies `fsGroup`. If the release ran a root image after `fsGroup`
+was already set, files that image created can stay unwritable: roll out the
+first `10001` image with `fsGroupChangePolicy: Always` (update or clear a reused
+`image.digest`, which wins over `image.tag`), then set it back to
+`OnRootMismatch` explicitly, because `--reuse-values` keeps it (see
+[Upgrade and verify](../README.md#upgrade-and-verify)), 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.
+Restricted Pod Security also needs `securityContext.runAsNonRoot: true`, which
+is safe only with images from this version.
+
 PD/Store PVC size and StorageClass live in StatefulSet claim templates and are
 not routine mutable settings. For capacity growth, the StorageClass must support
 expansion: resize each PVC, wait for completion, then coordinate an orphaned

helm/hugegraph/examples/README.md

@@ -31,8 +31,10 @@ are `<volume-name>-<fullname>-<component>-<ordinal>`; Hubble uses
 `<fullname>-hubble-data`.
 
 On each indicated host, create these directories on disks with sufficient free
-space and make them writable by the UID/GID of the chosen images (published
-images currently run as root). Existing unrelated data must not be reused.
+space and make them writable by the UID/GID of the chosen images. PD, Store
+and Server images built from this version run as `10001:10001`, and the chart's
+PD and Store `fsGroup` default makes their directories writable; Hubble runs as
+the user of its own image. Existing unrelated data must not be reused.
 
 | Node | Directories | Required capacities |
 |---|---|---|

helm/hugegraph/templates/_helpers.tpl

@@ -158,6 +158,22 @@ app.kubernetes.io/instance: {{ .Release.Name | quote }}
 {{- printf "%s-hubble-data" (include "hugegraph.fullname" . | trunc 51 | trimSuffix "-") }}
 {{- end }}
 
+{{/*
+PD and Store pod securityContext. The images run as UID/GID 10001, so their data
+volumes need fsGroup 10001. Apply it here as well as in values.yaml: --reuse-values
+keeps a pre-existing release's empty value. An explicit fsGroup is kept as set.
+*/}}
+{{- define "hugegraph.dataPodSecurityContext" -}}
+{{- $context := deepCopy (. | default dict) -}}
+{{- if not (hasKey $context "fsGroup") -}}
+{{- $_ := set $context "fsGroup" 10001 -}}
+{{- if not (hasKey $context "fsGroupChangePolicy") -}}
+{{- $_ := set $context "fsGroupChangePolicy" "OnRootMismatch" -}}
+{{- end -}}
+{{- end -}}
+{{- toYaml $context -}}
+{{- end }}
+
 {{- define "hugegraph.test.name" -}}
 {{- printf "%s-test-connection" (include "hugegraph.fullname" . | trunc 47 | trimSuffix "-") }}
 {{- end }}

helm/hugegraph/templates/pd-statefulset.yaml

@@ -77,10 +77,8 @@ spec:
       topologySpreadConstraints:
         {{- toYaml . | nindent 8 }}
       {{- end }}
-      {{- with .Values.pd.podSecurityContext }}
       securityContext:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
+        {{- include "hugegraph.dataPodSecurityContext" .Values.pd.podSecurityContext | nindent 8 }}
       {{- if .Values.pd.affinity }}
       affinity:
         {{- toYaml .Values.pd.affinity | nindent 8 }}

helm/hugegraph/templates/store-statefulset.yaml

@@ -76,10 +76,8 @@ spec:
       topologySpreadConstraints:
         {{- toYaml . | nindent 8 }}
       {{- end }}
-      {{- with .Values.store.podSecurityContext }}
       securityContext:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
+        {{- include "hugegraph.dataPodSecurityContext" .Values.store.podSecurityContext | nindent 8 }}
       {{- if .Values.store.affinity }}
       affinity:
         {{- toYaml .Values.store.affinity | nindent 8 }}

helm/hugegraph/tests/data_pod_security_context_test.yaml

@@ -0,0 +1,66 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+suite: PD and Store pod securityContext keeps fsGroup for the non-root images
+templates:
+  - pd-statefulset.yaml
+  - store-statefulset.yaml
+tests:
+  - it: defaults fsGroup to the image user
+    asserts:
+      - equal:
+          path: spec.template.spec.securityContext
+          value:
+            fsGroup: 10001
+            fsGroupChangePolicy: OnRootMismatch
+  - it: still sets fsGroup when a reused release has no podSecurityContext
+    set:
+      pd.podSecurityContext: null
+      store.podSecurityContext: null
+    asserts:
+      - equal:
+          path: spec.template.spec.securityContext
+          value:
+            fsGroup: 10001
+            fsGroupChangePolicy: OnRootMismatch
+  - it: keeps an explicit fsGroup and other settings
+    set:
+      pd.podSecurityContext:
+        fsGroup: 2000
+        runAsNonRoot: true
+      store.podSecurityContext:
+        fsGroup: 2000
+        runAsNonRoot: true
+    asserts:
+      - equal:
+          path: spec.template.spec.securityContext.fsGroup
+          value: 2000
+      - equal:
+          path: spec.template.spec.securityContext.runAsNonRoot
+          value: true
+  - it: keeps an explicit fsGroupChangePolicy
+    set:
+      pd.podSecurityContext:
+        fsGroupChangePolicy: Always
+      store.podSecurityContext:
+        fsGroupChangePolicy: Always
+    asserts:
+      - equal:
+          path: spec.template.spec.securityContext
+          value:
+            fsGroup: 10001
+            fsGroupChangePolicy: Always