feat(helm): add HStore deployment chart - #3132
Conversation
|
Ordering note: this chart depends on #3119 and should land after it.
No file overlap between the two, so there is nothing to rebase — it is purely a merge-order dependency. |
|
Blocking, and it comes from a change in #3119 rather than from this PR's own code. What changed. With What breaks here. This chart sets Before that change it did not fail — it came up as What to do. The wrapper should write
Two notes while you are in there: |
imbajin
left a comment
There was a problem hiding this comment.
Blocking: yes. In addition to the documented auth.admin_pa gap, the current chart does not actually gate Store startup or rolling progress on PD quorum and permits disruption budgets below the PD majority. Three independent current-head review lanes converged on these findings.
| until [ "$( | ||
| ok=0 | ||
| for peer in ${HEALTH_PEERS}; do | ||
| if curl -fsS "http://${peer}/v1/health" >/dev/null 2>&1; then |
There was a problem hiding this comment.
/v1/health handler returns success unconditionally and does not check for a Raft leader or member catch-up. Two REST endpoints can therefore release every Store while PD has no usable quorum; the PD/Store readiness probes use the same process-liveness signal, so a StatefulSet rolling update can also advance before the restarted member has rejoined safely. Please gate on an actual leader/quorum/catch-up-aware signal (for example, validated membership state) and add no-leader plus rolling-restart scenarios.
There was a problem hiding this comment.
Agreed on both counts: /v1/health is process liveness, not quorum, and the probes share the same weakness during rolling updates. The fix I intend is to gate the Store init container and the PD readiness signal on /v1/members (leader present, member state validated) rather than counting healthy responders, and to add the no-leader and PD rolling-restart scenarios you list to the full lifecycle matrix rerun already committed before this PR leaves draft. Landing it together with that rerun keeps the gating change and its runtime evidence in one reviewable step rather than shipping an untested probe contract now.
|
Addressed in 34234e3. The wrapper now writes |
Codecov Report✅ All modified and coverable lines are covered by tests.
Additional details and impacted files@@ Coverage Diff @@
## master #3132 +/- ##
============================================
- Coverage 41.06% 1.53% -39.53%
+ Complexity 519 21 -498
============================================
Files 771 749 -22
Lines 65962 63447 -2515
Branches 8766 8318 -448
============================================
- Hits 27088 975 -26113
- Misses 36008 62388 +26380
+ Partials 2866 84 -2782 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
0ebd2dc addresses the deployment-side feedback from testing:
|
…tore disabled The Server wrapper now writes auth.admin_pa from the auth Secret alongside usePD and pd.peers, so an auth-enabled release keeps its configured admin password with init_store.enabled=false instead of silently falling back to the public default. The Secret value is rejected when it contains properties-parser metacharacters that would inject config lines or store a different password than the Secret holds. The new hubble component deploys the Hubble UI as a single-replica Deployment with pd and direct wiring modes, optional Ingress and H2 persistence, schema validation, render-time guards, docs, and CI coverage. PD-meta installs (auth enabled, or Hubble in pd mode) also announce the Server client Service URL to PD via server.urls_to_pd and server.deploy_in_k8s so discovery clients receive a resolvable address instead of the 0.0.0.0 default, and the Hubble wrapper writes server.host so current images bind all interfaces. Because current Hubble images authenticate their login against the cluster, rendering Hubble without server.auth fails unless explicitly overridden. The CI invalid-value step now fails on every case rather than only its last line, and positive renders cover both Hubble modes. Validated against a composition of master 1716c77 plus the current heads of apache#3119 (edf07d0), apache#3126 (b40c42f), and apache#3130 (198de19): fresh auth-enabled installs reach Ready with zero restarts, the admin credential comes from the Secret while unauthenticated and default-password requests get 401, and Hubble logs in with the Secret credential and reads cluster metadata through PD discovery, with its H2 metadata persisted on the PVC.
…xtraEnv overrides A PD PodDisruptionBudget with minAvailable below floor(replicas/2)+1 permits voluntary evictions that leave PD without a Raft majority, so the render now requires the quorum floor in addition to the existing blocks-all-drains upper bound. With 2 replicas no valid budget exists; the README documents the even/odd contract. extraEnv entries render after the chart-owned variables and Kubernetes lets the last duplicate win, so a duplicate name could silently override a validated contract such as HG_SERVER_INIT_STORE_ENABLED=false. Each component's extraEnv now rejects its chart-managed variable names. Boundary and negative render cases for both rules are part of the CI invalid-value step.
The run failed at startup because azure/setup-helm@v4 is not on the ASF-approved actions allowlist; install the pinned helm release from the official tarball in a plain run step instead.
…cheduling defaults Fresh installs now seed PD with partition.default-shard-count derived from the Store count (3 when store.replicas is at least 3, otherwise 1, matching PD's odd-only constraint and its 2-to-1 clamp), so a default 3-Store deployment gets store-level HA instead of the image default of one shard replica per partition. The seed is delivered as -D system properties prepended into the PD JAVA_OPTS ahead of pd.javaOpts, preserving the start script's automatic heap sizing; it applies at first bootstrap only, after which PD metadata is authoritative, all documented together with the resulting initial partition count change. pd.antiAffinity and store.antiAffinity default to preferred so the chart schedules on clusters with fewer nodes than replicas; values-cluster.yaml keeps required for both, NOTES warns when PD quorum members may co-locate, and the README documents the upgrade implications. The Disaster Recovery documentation describes what current PD builds actually do: the scheduled patrol only marks silent stores Offline, shard reconciliation and tombstone processing run only via the manual /v1/task/patrolPartitions endpoint, and the pd.patrol-interval and store.max-down-time properties are bound but never read, which is why the chart does not expose them. Periodic leader balancing and recovery metrics are referenced as upstream feature requests. extraEnv now also rejects JAVA_OPTIONS for pd, store, and server, because the start scripts drop the chart-managed JAVA_OPTS entirely when it is set. Schema accepts numeric strings for the new keys, values-file integers at or above one million no longer fail as scientific notation, and CI asserts the rendered -D content, covers both shard-count validation messages, and kubeconforms the sharded render.
06805d9 to
fc830d0
Compare
…#3137) Document that the creating Server is consistent at HTTP 200 after apache#3138, while cross-replica convergence and PD-owned creation remain open upstream.
fc830d0 to
dd7c742
Compare
|
Todo (README): auth today is existingSecret-only (create Secret out-of-band; no password in values). Local/Kind docs on my test branch spell the steps. Worth a short Authentication subsection in the main chart README too? Happy to add in a follow-up if maintainers (@imbajin ) wants it. |
Multi-replica Server pods must use one JWT signing key or Hubble login fails behind the Service; chart-manage or BYO via server.auth.tokenSecret.
When auth is enabled without existingSecret, create a stable release-admin Secret so operators are not forced to pre-create credentials.
a85aedd to
1496459
Compare
Default installs get a chart-managed admin Secret; leave Hubble off so API-only clusters stay lean, and enable the UI with one flag when wanted.
1496459 to
9c267ca
Compare
Split server.auth into admin and token blocks so inline credentials (password/value) are distinct from Kubernetes Secret refs (existingSecret), matching the clearer values API for operators.
Let Server register a reachable URL with PD and optionally expose the PD client Service, so standalone Hubble can discover the cluster without in-cluster DNS. Fail closed when advertiseUrl is set without PD meta mode.
Checkpoint (2026-08-17)Re-validated this PR head (
Topology: 3 PD + 3 Store + 3 Server + 1 Hubble, authentication enabled (chart defaults), Hubble in Results
Notes (expected)
Still pending before leaving draft: the full multi-node upgrade / replacement / failover lifecycle matrix, and pinning image tags when the next release exists. |
Purpose of the PR
Add an official Helm installation path for the distributed HugeGraph HStore
topology on Kubernetes. The chart packages the PD, Store, and Server startup
contract that otherwise has to be reconstructed by each operator.
All six image-side prerequisites have now merged, including
#3130 (2026-08-15). This
branch already contains that merge (
84c56fc7) and is not behind currentmaster. The PR stays a draft until the remaining items under "Remainingbefore this leaves draft" are closed.
Main Changes
helm/hugegraphchart with chart version0.1.0:helm testconnection hook.values.schema.jsonwith render-time validation for replica counts,storage, PDBs, HPA, authentication, Services, and other value contracts.
disabled by default, configurable pod security contexts, hardened container
security defaults, graceful termination periods, probes, and
extraEnv.latestPD, Store, Server, and Hubble images while this PR is adraft, using pull policy
Alwaysso nodes do not retain an older cachedimage.
kubeconform, legacy-values, andpackaging CI.
limitations documentation, plus a root README installation link.
<release>-adminSecret supplies the password unlessserver.auth.admin.existingSecretorserver.auth.admin.passwordis set;a matching
<release>-auth-tokenSecret sharesauth.token_secretacrossServer replicas. Admin password and JWT token each have separate value vs
Secret keys. Set
server.auth.enabled=falseonly for trusted networks.Deployment with a
Recreatestrategy, ClusterIP Service, optional Ingressand persistence,
hubble.mode(pdfor PD discovery and the operationsview,
directfor the Server Service only), probes, schema validation,render-time guards, documentation, and CI coverage. Current Hubble images
authenticate their login against the cluster, so rendering Hubble without
server.authfails unless explicitly overridden.server.advertiseUrlregisters areachable Server URL with PD, and the PD client Service can be exposed as
NodePort or LoadBalancer. Empty
advertiseUrlkeeps the in-cluster ServiceURL. Render fails closed when
advertiseUrlis set without PD meta mode.auth.admin_pafrom the auth Secret alongsideusePDandpd.peers, andrejects Secret values containing properties-parser metacharacters.
wrapper always writes
usePD=true, chart-derivedpd.peers,server.urls_to_pd(the Server client Service URL, oradvertiseUrlwhenset), and
server.deploy_in_k8s=true. This keeps the graph catalog sharedacross Server replicas and gives discovery clients such as Hubble a
resolvable Server address.
server.host=0.0.0.0because current Hubbleimages bind
server.host(defaultlocalhost) and ignore the legacyhubble.hostkey in the shipped configuration.rather than only the last line, and add positive renders for both Hubble
modes.
partition.default-shard-countderived from the Store count (3 whenstore.replicasis at least 3, otherwise 1, matching PD's odd-onlyconstraint), replacing the image default of one shard replica per
partition. The seed applies at first bootstrap only; PD metadata is
authoritative afterwards, and the resulting initial partition count
change is documented.
pd.antiAffinityandstore.antiAffinitytopreferredso thechart schedules on clusters with fewer nodes than replicas;
values-cluster.yamlkeepsrequiredand NOTES warns when PD quorummembers may co-locate.
actually do (manual
/v1/task/patrolPartitionsreconciliation, noautomatic re-replication), and reject
JAVA_OPTIONSinextraEnvforpd, store, and server because the start scripts drop the chart-managed
JAVA_OPTSwhen it is set.Distributed startup and recovery contracts
HG_SERVER_SKIP_INIT. It setsHG_SERVER_INIT_STORE_ENABLED=false, relying on the dedicatedinit_store.enabledgate from fix(dist): gate init-store on a dedicated init_store.enabled option #3119 (issue InitStore should be able to skip local init in PD/HStore deployments #3118) so concurrent Serverreplicas do not initialize the same distributed backend.
/v1/healthresponses beforestarting. That is process liveness, not a Raft-leader check; the remaining
review thread on this signal is listed below.
always writes
usePD=true,pd.peers,server.urls_to_pd, andserver.deploy_in_k8s=truebefore handing control back to the imageentrypoint. This is required for distributed HStore so replicas share one
graph catalog. It does not make a local RocksDB backend shared or close the
cross-replica CreateGraph readiness window tracked in [Feature] Orchestrate graph creation through PD: new graphs are not consistently available across Server replicas ("Could not rebind [g]") #3137. When
authentication is enabled (the default), the same wrapper writes
auth.admin_pafrom the mounted Secret. That value applies only at firstcreation and lands in
rest-server.properties(mode 600) inside thecontainer.
truncation, keeping names valid and PVC identities stable across scaling.
startup command.
Prerequisites
All six image-side prerequisites have merged:
lsof1716c774init_store.enabledgate39f4f856de62d97fb026a90a8b2932c7431f6e6bThis branch includes #3130 via
merge(master): bring in #3130 Store channel refresh(84c56fc7) and currently contains all ofapache/hugegraphmaster. The Kubernetes validation below used the published Docker Hub:latestPD, Store, Server, and Hubble images.#3138 (CreateGraph Phase 1 of
#3137) merged on
master(2026-08-12). It is not a chart prerequisite but affects multi-Server behavior
documented in the chart README. #3139
remains open for cluster-wide graph readiness.
#3126's finite DNS TTL is required for #3130 to resolve a replacement Store
address. Neither change provides complete address recovery alone.
#3119 was narrowed before merge to the
init_store.enabledoption, its gate,the env mapping, and the init-flag guard. The Docker entrypoint and
auth-bootstrap work that previously shared its branch is tracked separately in
#3133. That split does not change what this chart uses from the merged PR, but
it does mean the entrypoint's
PASSWORDandauth.admin_pahandling is aknown-imperfect contract this chart depends on.
Validation baseline and head drift
The runtime matrix below was executed against a composition built from these
exact heads:
ee8f55591716c774; tested head superseded3e505a8139f4f856; tested head superseded and scope narrowed35e1a240de62d97f; tested head superseded0118e158b026a90afrom this PR head575a11228b2932c7from head61407213, one commit further26218cb3431f6e6b; tested head supersededOnly #3128 merged at exactly the head this chart was validated against. The
table below is the original evidence baseline (heads under test at the time).
All six prerequisites are now on
master. Results are not a claim about today'smasteruntil the committed matrix rerun completes.The
auth.admin_pafix and the Hubble component were validated separatelyagainst a newer composition:
masterat1716c774(which already carries#3105, #3128, and #3129) merged with #3119 at
edf07d0f(superseded beforemerge), #3126 at
b40c42fb(the merged PR head), and #3130 at198de19e(a later superseded head). Evidence from that composition:
Ready with zero restarts and
init_store.enabled=falsethroughout (nofail-closed refusal).
admin:paboth get401; the Secret credential gets 200.
and succeeds with the Secret credential in both
pdanddirectmodes;an authenticated session reads
/graphspacesfrom the cluster through PDdiscovery; with persistence enabled, the H2 metadata lands on the PVC.
pdmode confirmed the PD-metaproperties are written and discovery reaches the Server; it also showed
current Hubble images cannot complete their login against an auth-less
cluster (the server rejects
/auth/loginwith "Unconfiguredauthenticator"), which the chart now surfaces as a render-time guard.
issues (both fixed and re-verified): the CI invalid-value step enforced
only its last line, and the PD-meta properties were scoped to unrelated
settings.
Later chart commits (auth-on by default, auto-generated Secrets, nested
admin/token keys,
server.advertiseUrl, and the #3130 master merge) are onthis branch. Additional Kubernetes validation against this PR head is recorded
below. The full multi-node lifecycle matrix rerun remains pending before this
PR leaves draft.
Kubernetes validation (2026-08-17)
Against this PR head (
84c56fc7) on Kubernetes (Kind), with authenticationenabled by default, Hubble enabled in
pdmode, and the published Docker Hubimages
hugegraph/pd:latest,hugegraph/store:latest,hugegraph/server:latest, andhugegraph/hubble:latest(digests pulled thesame day).
Distributed topology (3 PD + 3 Store + 3 Server + 1 Hubble)
used the
:latesttag above;helm testpassed.the chart admin Secret and JWT login succeeded.
auth.token_secret).usePD=true, the three PD peers,server.urls_to_pd,server.deploy_in_k8s=true, andStandardAuthenticatorwithauth.admin_pafrom the chart Secret.spaces and graphs were visible through PD discovery; vertex create and
gremlin-querysucceeded.three healthy Stores. The overview lists a single Server endpoint because
all Server replicas register the shared client Service URL with PD; that is
the chart registration contract, not a missing replica. The overview may
report an aggregate PD status of UNKNOWN while individual PD members remain
UP.
An earlier single-node smoke on the same branch also passed; the authoritative
auth + Hubble check for this update is the 3+3+3+1 run on
:latestabove.This does not replace the pending multi-node fault and upgrade lifecycle
matrix.
Remaining before this leaves draft
84c56fc7); PR head is not behindcurrent
master.master, covering upgrade, Server/Store replacement, and PD failover forthe auth-default, Hubble, and
advertiseUrlwork. Single-node and3+3+3+1 Kubernetes smokes are already recorded above.
appVersionand component image tags (including Hubble) to thenext HugeGraph release and switch pull policies to
IfNotPresent. There isno 1.8.x release tag yet, so the 0.1.0 chart still tracks
latest./v1/health(process liveness, not a Raft-leader/quorum signal). PDBquorum-floor and
extraEnvreserved-name findings are fixed in the chart.Resolved on this branch
auth.admin_pabootstrap — the Server wrapper writesauth.admin_pafromthe auth Secret alongside
usePDandpd.peers, rejecting values withproperties-parser metacharacters. Verified with fix(dist): gate init-store on a dedicated init_store.enabled option #3119 on
master: auth-enabledinstalls reach Ready with
init_store.enabled=false; the Secret credentialworks end to end.
auth.admin_paapplies only at first creation and lands ina mode-600 file inside the container (documented in the chart README).
minAvailable >= floor(replicas/2)+1.extraEnvcannot override chart contracts — reserved names such asHG_SERVER_INIT_STORE_ENABLEDandPASSWORDare rejected at render time.server.advertiseUrland an exposablePD client Service.
Verifying these changes
PASS=239 FAIL=0 SKIP=0.usePD=trueand chart-derivedpd.peers; local wrapper execution alsoverified stale local values are replaced while
HG_SERVER_INIT_STORE_ENABLED=falseremains rendered.PASS=37 FAIL=0.--reuse-values:helm templateandhelm install --dry-run=clientpassed.61/0, dataset30/0.61/0, dataset30/0.PASS=91 FAIL=0.PASS=90 FAIL=0with data preserved.PASS=7 FAIL=0, with restoration verified.61/0and30/0.findings on the final template and schema implementation.
no templates or schema and repeated the full static gate at
239/0/0.hugegraph/{pd,store,server,hubble}:latestimages: 3+3+3+1 with authenabled; Ready Pods with zero restarts;
helm testpass; REST and HubbleCRUD; shared JWT across Server replicas (details above).
The runtime matrix used a four-node Kubernetes cluster and images built from a
composition containing the exact prerequisite heads listed under "Validation
baseline and head drift". Test-only validation harnesses and lab-specific
low-memory values are excluded from this PR. As noted above, those heads have
since moved (and #3130 has merged), so this matrix will be rerun before the PR
is marked ready.
Does this PR potentially affect the following parts?
Documentation Status
Doc - TODODoc - DoneDoc - No NeedDocumented operational limits
appVersionand component image tags (PD, Store,Server, Hubble) are
latest. This is intentionally temporary and is not thestable publication configuration; the next release tag will be pinned before
the PR is marked ready.
values-cluster.yamlis a production starting point, not a capacityguarantee.
preferred, so the chart scheduleson any node count; production should pin
required(asvalues-cluster.yamldoes) so one node failure cannot take out the PDquorum or co-locate shard replicas.
Secret only at first creation; the chart cannot rotate an existing cluster's
admin password. Disable auth only on a trusted network.
and its login requires
server.authon current images (the chart refusesto render it without auth unless explicitly overridden). Its UI connection
metadata, including graph credentials entered in the UI, lives in an
embedded H2 database that persists only when
hubble.persistenceisenabled; the PVC is kept on uninstall.
server.advertiseUrlis empty by default so PD hands back the in-clusterServer Service URL. Setting it for an outside Hubble also changes what
in-cluster discovery clients receive.
setting
runAsNonRootorreadOnlyRootFilesystem, which the current imagecontract cannot support.
tracked in [Bug] Docker entrypoint auth bootstrap is unsafe for mounted and upgraded configs #3133 and is outside this chart's control.
leader transfer, ConfigMap-based component configuration, and a complete
monitoring stack are outside this PR.
work, tracked in #3135;
the chart documents the manual balance endpoints as the current workaround.
work, tracked in #3136.
chart limitation, tracked in
#3137. Phase 1 (minimal
patch) merged: #3138
(2026-08-12) — the creating Server is consistent at HTTP 200. Other replicas
may still lag; mitigations remain in the chart README until Phases 2–3 land
(#3139 and PD-owned
creation).
TODO (later, needs more research)
deployment that joins an already-running cluster without recreating PD,
Store, or Server, with the Hubble image pinned to the matching HugeGraph
release. A Compose add-on with this shape is in #3149;
the same pattern fits Kubernetes well (compare TiDB Operator's standalone
TidbDashboardresource and the documented Kibana attach flow), soevaluate exposing Hubble here as an independently upgradable component
rather than only a bundled sub-chart option.