imbajin commented on code in PR #3149:
URL: https://github.com/apache/hugegraph/pull/3149#discussion_r3760132573
##########
docker/README.md:
##########
@@ -168,14 +173,87 @@ To validate local images without Compose replacing them
with remote `latest`:
## 3-Node Cluster Quickstart
+The cluster and the Hubble add-on share one named Docker network so Hubble
+can attach to a running cluster without touching it. Treat that network as a
+trust boundary: PD and Store expose unauthenticated control APIs on it (only
+the Server layer authenticates), and any container on the host can join it
+by declaring the well-known name. One-time setup: write the required
+credentials to a mode-600 `docker/.env` and create the network.
+The cluster file requires both credentials — the admin password enables
+authentication, and every Server replica must share one token secret so a
+token issued by any server validates on all of them. The `:?` guards fire
+on every Compose subcommand, including `down`.
+
+```bash
+(
+ set -eu
+ cd docker
+ command -v openssl >/dev/null 2>&1 || { echo "openssl not found" >&2; exit
1; }
+ [ -e .env ] || install -m 600 /dev/null .env
+ chmod 600 .env
+ # Keep appends on their own lines even if the file was hand-edited.
+ [ ! -s .env ] || [ -z "$(tail -c1 .env)" ] || printf '\n' >> .env
+ pat='^[[:space:]]*(export[[:space:]]+)?'
+ if ! grep -Eq "${pat}HUGEGRAPH_ADMIN_PASSWORD=" .env; then
Review Comment:
⚠️ The setup block treats existing invalid credentials as complete.
Evidence: the checks only look for HUGEGRAPH_ADMIN_PASSWORD= and
HUGEGRAPH_AUTH_TOKEN_SECRET=, so an empty password or an existing short token
skips generation; the Compose :? guards reject empty values and
docker-entrypoint.sh rejects tokens shorter than 32 bytes. Validate non-empty
values and token length, or fail with a repair message before creating the
network.
##########
docker/hugegraph-hubble-3x3.properties:
##########
@@ -0,0 +1,33 @@
+# 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.
+
+server.host=0.0.0.0
+server.port=8088
+
+cluster=hg
+idc=docker
+
+pd.enabled=true
+# Bootstrap target; the live topology comes from PD discovery. If this
+# replica is down when Hubble starts, point it at another server.
+server.direct_url=http://server0:8080
+pd.peers=pd0:8686,pd1:8686,pd2:8686
+# PD REST endpoint for the operations view (single address).
+pd.server=pd0:8620
Review Comment:
⚠️ Hubble Operations is pinned to one PD REST node even though the cluster
has three PD peers. Evidence: Hubble LiveOperationsCollector uses pd.server as
the base for /v1/cluster, /v1/stores, and PD Prometheus requests; pd.peers only
serves discovery and does not fail over this HTTP endpoint. Use a stable PD
REST VIP or add endpoint failover, and cover a pd0 failure while pd1/pd2 retain
quorum.
##########
docker/docker-compose-hubble.yml:
##########
@@ -0,0 +1,47 @@
+#
+# 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.
+#
+
+# Hubble add-on for the distributed cluster defined in
+# docker-compose-3pd-3store-3server.yml. Requires the pre-created cluster
+# network (docker network create hugegraph-net). See "Hubble for the
+# 3-Node Cluster" in docker/README.md for the attach and combined flows.
+
+networks:
+ hg-net:
+ external: true
+ name: ${HUGEGRAPH_NETWORK:-hugegraph-net}
+
+services:
+ hubble:
+ # Pin a release via HUGEGRAPH_VERSION in docker/.env; unset, the image
+ # tag defaults to latest.
+ image: ${HUBBLE_IMAGE:-hugegraph/hubble:${HUGEGRAPH_VERSION:-latest}}
+ pull_policy: ${HUBBLE_PULL_POLICY:-missing}
+ container_name: hg-hubble
+ hostname: hubble
+ restart: unless-stopped
+ networks: [hg-net]
+ ports:
+ - "${HUBBLE_PUBLISH_HOST:-127.0.0.1}:8088:8088"
+ volumes:
+ -
./hugegraph-hubble-3x3.properties:/hubble/conf/hugegraph-hubble.properties:ro
Review Comment:
⚠️ Recreating Hubble loses its local state and uploaded files. Evidence: the
Hubble image uses the file H2 database jdbc:h2:file:./db and the default
upload_file.location upload-files, both under /hubble, but this service mounts
only the read-only properties file; the documented docker compose down removes
the container writable layer. Mount named volumes for the database and upload
directory, or explicitly make this add-on stateless.
##########
docker/hugegraph-hubble-3x3.properties:
##########
@@ -0,0 +1,33 @@
+# 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.
+
+server.host=0.0.0.0
+server.port=8088
+
+cluster=hg
+idc=docker
+
+pd.enabled=true
+# Bootstrap target; the live topology comes from PD discovery. If this
+# replica is down when Hubble starts, point it at another server.
+server.direct_url=http://server0:8080
Review Comment:
🧹 This fallback comment and value are ineffective in the mode selected
above. Evidence: HubbleOptions documents server.direct_url as used only when
pd.enabled=false, while this file sets pd.enabled=true and Hubble builds the
server client from PD discovery. Remove this bootstrap instruction or state
clearly that it applies only to standalone mode.
##########
.github/workflows/server-ci.yml:
##########
@@ -138,6 +138,107 @@ jobs:
check_compose docker/docker-compose.yml always always
check_compose docker/docker-compose.dev.yml build missing
+ check_cluster_compose() {
+ local cluster="docker/docker-compose-3pd-3store-3server.yml"
+ local addon="docker/docker-compose-hubble.yml"
+ local rendered
+ rendered="$(mktemp)"
+
+ # Both cluster credentials are required and may not be empty.
+ if HUGEGRAPH_AUTH_TOKEN_SECRET=ci-test-secret \
+ env -u HUGEGRAPH_ADMIN_PASSWORD \
+ docker compose -f "$cluster" config -q >/dev/null 2>&1; then
+ echo "$cluster accepted an unset admin password" >&2
+ return 1
+ fi
+ if HUGEGRAPH_ADMIN_PASSWORD= \
+ HUGEGRAPH_AUTH_TOKEN_SECRET=ci-test-secret \
+ docker compose -f "$cluster" config -q >/dev/null 2>&1; then
+ echo "$cluster accepted an empty admin password" >&2
+ return 1
+ fi
+ if HUGEGRAPH_ADMIN_PASSWORD=ci-test-password \
+ env -u HUGEGRAPH_AUTH_TOKEN_SECRET \
+ docker compose -f "$cluster" config -q >/dev/null 2>&1; then
+ echo "$cluster accepted an unset token secret" >&2
+ return 1
+ fi
+ if HUGEGRAPH_ADMIN_PASSWORD=ci-test-password \
+ HUGEGRAPH_AUTH_TOKEN_SECRET= \
+ docker compose -f "$cluster" config -q >/dev/null 2>&1; then
+ echo "$cluster accepted an empty token secret" >&2
+ return 1
+ fi
+
+ # The add-on alone must define Hubble and nothing else, join the
+ # shared external network with its default name, and need no
+ # credentials or overrides.
+ env -u HUGEGRAPH_ADMIN_PASSWORD -u HUGEGRAPH_AUTH_TOKEN_SECRET \
+ -u HUGEGRAPH_NETWORK -u HUGEGRAPH_VERSION \
+ docker compose -f "$addon" config --format json > "$rendered"
+ jq -e '
+ (.services | keys) == ["hubble"] and
+ .networks."hg-net".external == true and
+ .networks."hg-net".name == "hugegraph-net" and
+ (.services.hubble | has("depends_on") | not) and
+ any(.services.hubble.volumes[];
+ .target == "/hubble/conf/hugegraph-hubble.properties" and
+ (.source | endswith("hugegraph-hubble-3x3.properties")))
+ ' "$rendered" >/dev/null
+
+ # The combined render carries the PD-registration and auth
+ # settings on every server replica and keeps Hubble on loopback.
+ # Rendered with non-default HUGEGRAPH_NETWORK/HUGEGRAPH_VERSION so
+ # CI fails if any file stops honoring the overrides (the add-on
+ # render above covers the defaults).
+ HUGEGRAPH_ADMIN_PASSWORD=ci-test-password \
+ HUGEGRAPH_AUTH_TOKEN_SECRET=ci-test-secret \
Review Comment:
⚠️ This combined-render check uses a token that every Server container
rejects at startup. Evidence: exact-head docker-entrypoint.sh:93-98 exits when
HG_SERVER_AUTH_TOKEN_SECRET is shorter than 32 bytes, while this workflow sets
ci-test-secret and only runs docker compose config, so entrypoint validation is
never exercised. Use a >=32-byte fixture and add a minimal entrypoint or
container smoke check.
##########
docker/README.md:
##########
@@ -205,6 +283,110 @@ curl http://localhost:8620/v1/partitions
---
+## Hubble for the 3-Node Cluster
+
+`docker-compose-hubble.yml` defines only the Hubble service. It joins the
+cluster's external network (`hugegraph-net` by default, override with
+`HUGEGRAPH_NETWORK`) and has no `depends_on` on cluster services, so
+starting, stopping, or upgrading Hubble never recreates or restarts PD,
+Store, or Server containers. Hubble reads the cluster topology from
+`hugegraph-hubble-3x3.properties`; adjust that file when attaching to a
+cluster with different hostnames.
+
+Sign in at `http://localhost:8088` as `admin` with the
+`HUGEGRAPH_ADMIN_PASSWORD` from `docker/.env`. Hubble binds to host
+loopback by default (`HUBBLE_PUBLISH_HOST`, same caveats as the
+single-node setup).
+
+The two flows below create Hubble in different Compose projects, so manage
+Hubble with the same flags you started it with: the attach flow always uses
+`-p hugegraph-hubble -f docker-compose-hubble.yml`, the combined flow always
+uses both `-f` flags. The explicit `-p` keeps the attach project independent
+of the directory name and of other Compose projects.
+
+Run one Hubble per host: the single-node stack and both add-on flows all
+publish `127.0.0.1:8088` and name their container `hg-hubble`. The two
+add-on flows are therefore mutually exclusive — starting one while the
+other's Hubble exists fails with a container-name conflict, so `down` the
+flow you are leaving before switching.
+
+### Attach to a running cluster
+
+With the 3-node cluster already up:
+
+```bash
+cd docker
+docker compose -p hugegraph-hubble -f docker-compose-hubble.yml up -d
Review Comment:
⚠️ The documented attach command can produce a healthy Hubble container that
discovers no graph server on an older running cluster. Evidence: the pre-change
3-node Compose stack does not set HG_SERVER_USE_PD=true, HG_SERVER_CLUSTER=hg,
or per-node HG_SERVER_REST_URL, while this add-on enables PD discovery for
cluster hg and only starts Hubble. Require upgrading the cluster with the new
Compose file first, or provide a direct-server compatibility configuration.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
