fix(docker): expose server discovery identity

[imbajin]

Purpose of the PR

Container and Helm deployments could not pass a Server service ID or graph space into rest-server.properties, even when callers supplied the legacy environment variables. Map the supported settings before startup and expose them in the chart. The Helm test also always queried DEFAULT-hugegraph; let operators select an existing graph binding while retaining the default.

Main Changes

• Accept HG_SERVER_SERVICE_ID / HG_SERVER_GRAPHSPACE and migrate their legacy aliases; an effective nonempty new value takes precedence.
• Add server.serviceId and server.graphSpace chart values, preserving existing DEFAULT behavior and avoiding duplicate identity variables.
• Add optional server.testGraphAlias for an existing Gremlin graph binding. Keep the default and saved-values fallback, authentication and complete per-Pod checks; do not infer or create a graph from the assigned space.
• Reject unsupported identity input before modifying configuration. Deployment service IDs accept printable ASCII, including spaces and backslashes; graph spaces follow the existing Server naming rules.
• Document graph-space creation, authentication and the deployment input boundary. Core service naming and mounted properties retain their current behavior.

Verifying these changes

Shell and process checks, real HugeConfig readback controls, Helm tests, packaging, lint/render and schema CI checks passed. Formatting, clean compilation and independent final reviews passed. A real standalone Server with StandardAuthenticator and RocksDB confirmed that selecting an existing alias passes while missing aliases fail, with unchanged graph data. This verifies graph selection; stock PD/HStore startup, non-default discovery, authorization, isolation and Kubernetes deployment still require their own acceptance checks.

Documentation Status

Doc - Done: Docker and Helm guides in this PR. Paired website documentation: ASF #517. Coordinate both merges.

Implementation illustration

Helm and container identity inputs are validated and mapped into Server properties before startup, with legacy-alias support and nonempty HG_SERVER_* values taking precedence. Helm DEFAULT values preserve the image configuration; non-default graph spaces must already exist. Configuration wiring only; live discovery, authentication and isolation still require topology validation.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.23%. Comparing base (0b7c0de) to head (2241dfd).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3322      +/-   ##
============================================
+ Coverage     54.29%   57.23%   +2.94%     
+ Complexity     2616      130    -2486     
============================================
  Files           770      514     -256     
  Lines         67952    49732   -18220     
  Branches       9213     7203    -2010     
============================================
- Hits          36892    28464    -8428     
+ Misses        27482    18357    -9125     
+ Partials       3578     2911     -667     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[bitflicker64]

Blocking: no. Summary: The entrypoint mapping, its validation order and the chart wiring hold up, and the default render is unchanged; two small gaps remain in how the chart guards the new service identity values. Evidence: read the full diff at 83bb23d (10 files) with docker-entrypoint.sh, GraphManager (NAME_REGEX, loadServices, the graph-space load filter), HugeConfig, K8sDriver and HugeGremlinServer at that head; rendered the chart at that head with helm template (helm v4.2.4) for both comments; ran the service ID encoder from the entrypoint over values with spaces, backslashes, commas and ${...} and read them back through commons-configuration2 2.8.0 PropertiesConfiguration (the repo pins 2.10.1), all unchanged; docker / deployment-contracts and build-server / server_memory (Java 17), which run docker-entrypoint-test.sh, and helm / lint-and-render pass on this head; Analyze (java) and the three pd_store jobs were still pending. The entrypoint test was not rerun locally (it needs GNU sed), and nothing was run against a PD cluster.

[imbajin]

Blocking: no. Summary: The deployment change has a test coverage gap around the service ID value loaded by the Server. Evidence: The new entrypoint checks inspect the serialized properties file while the test stubs the Server startup path.

[bitflicker64]

Blocking: yes. Summary: The entrypoint mapping, the validation and the chart wiring read correctly, and the earlier review points (legacy names in extraEnv, $(VAR) expansion, HugeConfig readback) are addressed at this head. One problem remains on the chart side: with a non-default server.graphSpace the chart's own helm test hook can no longer pass, because it queries DEFAULT-hugegraph on every Pod and a Server assigned to another graph space does not load graphs from DEFAULT. Evidence: static read of the full diff 6aa362a..91b00d2 plus GraphManager.java (filterLoadGraphByServiceGraphSpace, loadGraphsFromMeta, graph()), HugeConfig.java, K8sDriver.java and helm/hugegraph/templates/tests/test-connection.yaml at this head; all CI checks on this head pass, including docker / deployment-contracts and helm / lint-and-render. Nothing was run locally and the finding was not reproduced on a cluster.

[bitflicker64]

Blocking: yes. Summary: The entrypoint mapping, validation order, chart wiring and the new server.testGraphAlias hook read correctly, and the earlier review points are addressed at this head. One gap remains: the accepted service ID character set is wider than what the Server's service registry handles, so IDs containing / or - are accepted and then mis-keyed. Evidence: read the full diff 87239c5..dd10fda (13 files) with docker-entrypoint.sh, GraphManager (loadServices, clearGraphSpace, serviceName, NAME_REGEX), ServiceMetaManager, Service, HugeConfig and K8sDriver at that head; helm unittest on the chart at that head passed (27 suites, 209 tests); helm template accepted server.serviceId=a/b and analytics-prod. The entrypoint test was not run locally (it needs GNU sed), and the docker and helm CI jobs were still queued when this was written.

[imbajin]

Blocking: no. Summary: The alias schema permits graph names the Server rejects, so invalid values fail only after helm test starts. Evidence: GraphManager.NAME_REGEX is lowercase-only while the chart schema accepts uppercase.

[imbajin]

Blocking: yes. Summary: The new printable-ASCII inputs allow distinct service IDs that GraphManager.serviceId() normalizes to the same PD SERVICE_ID, so discovery queries can return endpoints from both deployments. Evidence: registration writes the normalized value to the SERVICE_ID label, and PD matches query labels by exact equality.

[imbajin]

⚠️ Important. Blocking: yes. Summary: This accepts printable IDs that GraphManager.serviceId() collapses before registering them with PD. In the same graph space, Foo and foo both produce default-oltp-foo; analytics_prod and analytics-prod also collide because the Server replaces _ with - and lowercases the value. Both registrations then carry the same SERVICE_ID label, so a PD query for that identity returns endpoints from both deployments. Evidence: GraphManager.registerService() sets SERVICE_ID from service.serviceId(), and DiscoveryMetaStore.labelMatch() uses exact label equality. Please make the identity mapping injective or reject non-canonical values here and in the Helm schema, and keep the legacy SERVICE_ID mapping under the same validation.