feat(docker): add attachable Hubble Compose add-on for the 3-node cluster - #3149

‼️ The cluster quickstart exits immediately after generating its own credentials. Evidence: the regex has an optional export capture before the value, but both sed commands substitute capture group 1, so HUGEGRAPH_ADMIN_PASSWORD='...' yields an empty value (and an export form yields the word export); lines 216/220 then fail. Use the value capture group and parse or explicitly reject all supported Compose dotenv formats consistently.

Agreed and also in scope. The optional export group made \1 capture the wrong text. I’ll fix the setup parser to read the value group (and keep parsing as data, not by sourcing .env).

‼️ The H2 database is mounted at the wrong persistence boundary. Evidence: the Hubble image works from /hubble and its datasource is jdbc:h2:file:./db; mounting a volume at /hubble/db leaves the actual /hubble/db.mv.db outside that volume (or makes startup fail because /hubble/db is a directory). Point H2 at a file inside the mounted directory or mount the parent directory, then verify data survives container recreation.

I’ll fix the persistence boundary so Hubble state survives recreate.

‼️ This auth-required cluster can report healthy while remaining unauthenticated. Evidence: the documented compatible integration is newer than 1.7.x, but the image defaults to floating latest with pull_policy: missing; an already-cached older image can ignore PASSWORD and the token secret, while the healthcheck probes public /versions. Pin or fail closed on incompatible images, or add an authenticated readiness smoke check that proves graph requests are rejected without credentials and succeed with them.

Agree this is a real gap for the auth-required 3-node quickstart. I’d like to keep #3149 scoped to the Hubble add-on and the minimum cluster contract Hubble needs. Changing Server readiness to prove 401/200 and changing default pull policy feels like follow-up cluster hardening rather than the add-on itself. README already documents the manual 401/200 check for incompatible images.

‼️ The predictable external network and host-published control-plane ports expose unauthenticated PD/Store administration by default. Evidence: hugegraph-net is external and the file publishes PD/Store REST, gRPC, and Raft ports on all host interfaces; Store has no authentication and PD only checks the internal service username, not the password. Bind these ports to loopback/remove them by default, or require real authentication/TLS and explicit network ACLs before shipping this as the default quickstart.

Agree on the exposure concern. Default loopback binds / ACL+TLS requirements are a cluster-quickstart security redesign; I’d track that as a follow-up so this PR stays reviewable as a Hubble add-on.

⚠️ The two documented Hubble flows do not share these physical volumes. Evidence: attach runs under project hugegraph-hubble, while the combined flow runs under hugegraph-3x3; Compose therefore creates different project-prefixed H2 and upload volumes. Switching flows makes existing state and uploads appear to disappear. Give both volumes stable explicit names (with a multi-cluster override if needed) or document a supported volume migration.

I’ll give the Hubble DB/upload volumes explicit stable names so attach and combined share the same physical volumes.

⚠️ This verification block executes the entire Compose dotenv file as shell code. Evidence: set -a; . ./.env; set +a evaluates command substitutions and other shell syntax before the curl; a value such as HUGEGRAPH_ADMIN_PASSWORD=$(...) runs on the operator host. Parse only the required key with a dotenv-aware parser or avoid sourcing .env directly.

I’ll replace set -a; . ./.env; set +a with a parse‑only read of the required key, so the verify block does not execute dotenv as a shell.

⚠️ Each Server registers http://serverN:8080 with PD while the host publishes ports 8080/8081/8082. Evidence: Server registration uses restserver.url, so a PD-aware client outside the Docker network receives server0/server1/server2, names that only resolve inside hugegraph-net. Provide a separate configurable advertised address or make the external client path use addresses it can resolve.

Agree for PD-aware clients outside Docker DNS. Hubble on hugegraph-net can use serverN names as-is. Configurable advertised addresses feel like a follow-up to external-client addressing, not required for the add-on path. What do you think?

⚠️ The contract comment says PD-registration and auth settings are carried by every Server replica, but the assertions only check server0 for HG_SERVER_USE_PD, HG_SERVER_CLUSTER, HG_SERVER_INIT_STORE_ENABLED, and PASSWORD; server1/server2 only check REST URL and token. A per-replica override can therefore pass CI while breaking discovery or initialization. Apply the required-value assertions to all three Server services.

Agreed — in scope. This PR introduced the PD/auth Server env for Hubble discovery, so CI should assert the required values on server0/server1/server2, not only server0.

⚠️ The Hubble properties consistency check can pass while PD mode is disabled. Evidence: assert_props validates cluster, pd.peers, pd.server, and Store targets, but never asserts pd.enabled=true; the current server.direct_url is only meaningful when PD mode is false. Add the explicit mode assertion and a runtime smoke check so Hubble cannot silently fall back to one direct Server.

I’ll add an explicit assert_props "pd.enabled=true" so the Hubble properties check cannot pass with PD mode disabled.

⚠️ The new cluster contract remains render-only. Evidence: the combined check stops at docker compose config plus jq/grep and never creates the external network, starts the services, probes Hubble /about, verifies PD registration, or checks authenticated graph access. Add a Docker-capable smoke job for the combined and attach flows so entrypoint, DNS, registration, and auth failures cannot remain green.

Render‑only cannot catch runtime auth/DNS failures. For this PR I’ll keep and strengthen the compose contract assertions (including the in‑scope ones above). A full combined or attached Docker smoke job is useful but adds heavier CI overhead; I’d prefer a follow‑up rather than blocking the add‑on here.