Feature Description
Apache HugeGraph ships container images and Compose deployments, but it does
not currently provide an official Helm installation path for the distributed
PD + Store + Server topology on Kubernetes.
The main challenge is encoding the distributed startup and recovery contract,
not only rendering Kubernetes resources:
- PD must reach Raft quorum before Store registers.
- Server must not run concurrent
init-store operations against the same
distributed backend.
- Store addresses can change after rescheduling, so DNS and gRPC clients must
recover rather than retain stale addresses or channels.
- StatefulSet and PVC identities must remain stable when replica counts change.
Proposal
Add an application chart under helm/hugegraph that provides:
- PD and Store StatefulSets with persistent storage and headless Services.
- A Server Deployment with a client Service, optional HPA, PDB, and Ingress.
- PD, Store, and Server scheduling, resource, security, and ServiceAccount
controls.
- PodDisruptionBudgets for the stateful components.
- A
helm test connection check.
values.schema.json validation so invalid combinations fail during render.
- Default, single-node, and production-oriented values presets.
- An optional Hubble UI component: single replica,
pd (PD discovery with
the cluster operations view) or direct wiring mode, optional Ingress and
H2 persistence, wired to the deployed cluster. Current Hubble images
authenticate their login against the cluster, so the chart requires
server.auth when Hubble is enabled unless explicitly overridden.
- Helm lint, render, schema, compatibility, packaging, and
kubeconform CI.
- Installation, configuration, upgrade, troubleshooting, and limitations
documentation.
The chart configures the existing HugeGraph images. It does not vendor or
duplicate server-side implementation.
The implementation is #3132.
Prerequisites
The first chart release is version 0.1.0. While its PR is a draft, the chart
tracks the latest HugeGraph images. Before stable publication, the image tags
and appVersion will be pinned to the next HugeGraph release.
Three prerequisites have merged:
| PR |
Required behavior |
Merged as |
| #3128 |
One gRPC stub binding per channel |
b026a90a |
| #3129 |
Store readiness retries across all configured PD peers |
8b2932c7 |
| #3105 |
Bounded port preflight without requiring lsof |
09dbc744 |
Three remain open:
| PR |
Required behavior |
Current head |
| #3119 |
Dedicated init_store.enabled gate for distributed Server startup (issue #3118) |
edf07d0f |
| #3126 |
Finite JVM DNS cache TTL, plus startup DNS-policy validation and JDK 24+ security-check handling |
b40c42fb |
| #3130 |
Channel and stub refresh after a Store address change |
198de19e |
#3126 and #3130 form one recovery path: channel refresh cannot resolve a new
Store address while the JVM retains the old DNS result indefinitely.
#3119 has since been narrowed to the init_store.enabled option and its gate.
The Docker entrypoint and auth-bootstrap work that previously shared its branch
is now tracked separately in #3133. The chart does not depend on #3133 landing
first, but the entrypoint contract it describes is the one this chart relies on
for PASSWORD and auth.admin_pa handling.
Validation
The implemented chart was tested on a four-node Kubernetes cluster using a
3 PD + 3 Store + 3 Server topology, against a composition built from these
exact prerequisite heads:
| PR |
Head under test |
Status now |
| #3105 |
ee8f5559 |
superseded by 09dbc744 |
| #3119 |
3e505a81 |
superseded by ff1325ac |
| #3126 |
35e1a240 |
superseded by 4d0ff03e |
| #3128 |
0118e158 |
merged unchanged at this head |
| #3129 |
575a1122 |
merged at 61407213, one commit further |
| #3130 |
26218cb3 |
superseded by ddeef7a9 |
The completed validation covers:
- Static chart validation:
PASS=239 FAIL=0 SKIP=0.
- Edge and hardening validation:
PASS=37 FAIL=0.
- Fresh install with 9 Ready Pods and zero restarts.
- Same-package Helm upgrade with cluster and dataset checks passing.
- Server replacement:
PASS=91 FAIL=0.
- Store replacement:
PASS=90 FAIL=0, with data preserved.
- Deterministic PD REST failover:
PASS=7 FAIL=0, followed by successful
restoration.
- Legacy
--reuse-values rendering and client-side dry-run compatibility.
The auth bootstrap fix (the wrapper now writes auth.admin_pa from the auth
Secret) and the Hubble component were validated separately against a newer
composition of master at 1716c774 plus the current heads of #3119,
#3126, and #3130; details are in the PR. The full lifecycle matrix rerun is
still pending before the PR leaves draft.
Only #3128 merged at exactly the head under test, so this matrix is the current
evidence baseline rather than a statement about today's master. It will be
rerun against a composition of the then-current heads before the chart PR
leaves draft.
Known gap
With init_store.enabled=false, the built-in authenticator's admin is created
on the PD startup path from auth.admin_pa, and Docker PASSWORD is discarded
because init-store reads it from stdin and the disabled path returns first.
The chart's wrapper currently writes only usePD and pd.peers, so an
auth-enabled deployment silently ignores the configured Secret today, and will
fail closed at container start once #3119 merges. The wrapper needs to write
auth.admin_pa from the same Secret. This is tracked on #3132 and must be
fixed and retested before that PR leaves draft.
Scope and follow-ups
This contribution establishes the official Helm installation path. TLS,
backup and restore, an Operator, multi-cluster orchestration, automatic leader
transfer, ConfigMap-based component configuration, and a complete monitoring
stack remain separate follow-up work and are documented as limitations.
Entrypoint property handling for mounted and upgraded configs is tracked in
#3133 and is outside this chart's scope.
The chart PR should remain a draft while its prerequisite PRs are open. Before
it is marked ready, it will be rebased onto the then-current master, composed
with the merged prerequisites, and the affected validation matrix will be run
again.
Related upstream issues
Feature Description
Apache HugeGraph ships container images and Compose deployments, but it does
not currently provide an official Helm installation path for the distributed
PD + Store + Server topology on Kubernetes.
The main challenge is encoding the distributed startup and recovery contract,
not only rendering Kubernetes resources:
init-storeoperations against the samedistributed backend.
recover rather than retain stale addresses or channels.
Proposal
Add an application chart under
helm/hugegraphthat provides:controls.
helm testconnection check.values.schema.jsonvalidation so invalid combinations fail during render.pd(PD discovery withthe cluster operations view) or
directwiring mode, optional Ingress andH2 persistence, wired to the deployed cluster. Current Hubble images
authenticate their login against the cluster, so the chart requires
server.authwhen Hubble is enabled unless explicitly overridden.kubeconformCI.documentation.
The chart configures the existing HugeGraph images. It does not vendor or
duplicate server-side implementation.
The implementation is #3132.
Prerequisites
The first chart release is version
0.1.0. While its PR is a draft, the charttracks the
latestHugeGraph images. Before stable publication, the image tagsand
appVersionwill be pinned to the next HugeGraph release.Three prerequisites have merged:
b026a90a8b2932c7lsof09dbc744Three remain open:
init_store.enabledgate for distributed Server startup (issue #3118)edf07d0fb40c42fb198de19e#3126 and #3130 form one recovery path: channel refresh cannot resolve a new
Store address while the JVM retains the old DNS result indefinitely.
#3119 has since been narrowed to the
init_store.enabledoption and its gate.The Docker entrypoint and auth-bootstrap work that previously shared its branch
is now tracked separately in #3133. The chart does not depend on #3133 landing
first, but the entrypoint contract it describes is the one this chart relies on
for
PASSWORDandauth.admin_pahandling.Validation
The implemented chart was tested on a four-node Kubernetes cluster using a
3 PD + 3 Store + 3 Server topology, against a composition built from these
exact prerequisite heads:
ee8f555909dbc7443e505a81ff1325ac35e1a2404d0ff03e0118e158575a112261407213, one commit further26218cb3ddeef7a9The completed validation covers:
PASS=239 FAIL=0 SKIP=0.PASS=37 FAIL=0.PASS=91 FAIL=0.PASS=90 FAIL=0, with data preserved.PASS=7 FAIL=0, followed by successfulrestoration.
--reuse-valuesrendering and client-side dry-run compatibility.The auth bootstrap fix (the wrapper now writes
auth.admin_pafrom the authSecret) and the Hubble component were validated separately against a newer
composition of
masterat1716c774plus the current heads of #3119,#3126, and #3130; details are in the PR. The full lifecycle matrix rerun is
still pending before the PR leaves draft.
Only #3128 merged at exactly the head under test, so this matrix is the current
evidence baseline rather than a statement about today's
master. It will bererun against a composition of the then-current heads before the chart PR
leaves draft.
Known gap
With
init_store.enabled=false, the built-in authenticator's admin is createdon the PD startup path from
auth.admin_pa, and DockerPASSWORDis discardedbecause
init-storereads it from stdin and the disabled path returns first.The chart's wrapper currently writes only
usePDandpd.peers, so anauth-enabled deployment silently ignores the configured Secret today, and will
fail closed at container start once #3119 merges. The wrapper needs to write
auth.admin_pafrom the same Secret. This is tracked on #3132 and must befixed and retested before that PR leaves draft.
Scope and follow-ups
This contribution establishes the official Helm installation path. TLS,
backup and restore, an Operator, multi-cluster orchestration, automatic leader
transfer, ConfigMap-based component configuration, and a complete monitoring
stack remain separate follow-up work and are documented as limitations.
Entrypoint property handling for mounted and upgraded configs is tracked in
#3133 and is outside this chart's scope.
The chart PR should remain a draft while its prerequisite PRs are open. Before
it is marked ready, it will be rebased onto the then-current
master, composedwith the merged prerequisites, and the affected validation matrix will be run
again.
Related upstream issues
#3135 PD: periodic partition leader balancing, motivated by fault testing chart deployments.
#3136 Store: shard recovery metrics (sync progress, raft lag), motivated by fault testing chart deployments.
#3137 PD-orchestrated graph creation: new graphs are not consistently available across Server replicas; the chart documents the window as a limitation.
Update: the first server-side fix from the [Feature] Orchestrate graph creation through PD: new graphs are not consistently available across Server replicas ("Could not rebind [g]") #3137 roadmap (the creating server waits for its own graph binding before returning 200) is up in #3138.