Skip to content

[Feature] Add an official Helm chart for distributed HStore deployment #3131

Description

@bitflicker64

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    ci-cdBuild or deployfeatureNew feature

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions