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.
  • 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.

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.

The chart depends on the following changes:

PR Required behavior
#3105 Bounded port preflight without requiring lsof
#3119 Dedicated init_store.enabled gate for distributed Server startup
#3126 Finite JVM DNS cache TTL
#3128 One gRPC stub binding per channel
#3129 Store readiness retries across all configured PD peers
#3130 Channel and stub refresh after a Store address change

PR #3126 and PR #3130 form one recovery path: channel refresh cannot resolve a
new Store address while the JVM retains the old DNS result indefinitely.

Validation

The implemented chart has been tested against a composition containing the
current heads of all six prerequisite PRs on a four-node Kubernetes cluster
using a 3 PD + 3 Store + 3 Server topology.

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.

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.

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.

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