feat(hugegraph): add standalone and distributed addon by weicao · Pull Request #3412 · apecloud/kubeblocks-addons

weicao · 2026-08-18T17:07:55Z

Summary

Add a HugeGraph 1.7.0 addon on release-1.0.

This is the HugeGraph development-branch main PR (dev/hugegraph-release-1.0 -> release-1.0). Later fixes go through child PRs into this branch, not directly onto release-1.0.

Scope

Supported:

Standalone: one HugeGraph Server 1.7.0 replica with embedded RocksDB
HTTP 8080 and Gremlin 8182
admin init system account
Persistent data on /hugegraph-data
Full-instance checkpoint backup of every persistent graph (standalone)
Restore to a new same-version standalone Cluster
Restart, Stop/Start, VerticalScaling, VolumeExpansion, Expose
Metrics sidecar hugegraph-exporter:0.1.1 (amd64+arm64) and MonitorDefinition
Distributed: PD + Store + Server topology, provision [pd,store] then server, Raft identity from pod FQDNs
PD HG_PD_INITIAL_STORE_COUNT derived from Store FQDNs (official 3-store bootstrap)
Server start waits for every Store /v1/health
Store start waits for every PD /v1/health

Not in this PR:

Distributed backup/restore, Store scale-in/rebalance, roleProbe
TLS, reconfigure, PITR, incremental/selective restore, RebuildInstance, cross-version or cross-topology restore

Candidate package

Item	Pin
Target branch	`release-1.0` @ `678ef794`
Development branch	`dev/hugegraph-release-1.0`
Development head	`c986b81be7dcbcbf7801ba390c4fbc72bd9c3d1c`
Addon path	`addons/hugegraph`, `addons-cluster/hugegraph`, `examples/hugegraph`
Chart / app	`hugegraph-1.0.0` / `1.7.0`
Exporter image	`docker.io/apecloud/hugegraph-exporter:0.1.1`
Engine images	`hugegraph:1.7.0`, `hugegraph-pd:1.7.0`, `hugegraph-store:1.7.0`, `hugegraph-server:1.7.0` (CI rewrites official `hugegraph/` to `docker.io/apecloud/`)
KB line	KubeBlocks `release-1.0`
Tests PR	apecloud/kubeblocks-tests#949 @ `8ef64760`

Child / companion PRs

Exporter sidecar: feat(hugegraph): add native metrics exporter sidecar #3413 (merged into this branch as 3634d7b8)
Distributed topology: feat(hugegraph): add distributed PD/Store/Server topology #3414 (merged into this branch as 4069790f)
Distributed 12a limits: docs(hugegraph): declare distributed limits in README #3415 (merged into this branch as 754d5d61)
Distributed systemAccounts restriction: docs(hugegraph): mark distributed systemAccounts unsupported #3416 (merged into this branch as 8354081)
Store PD health fail-closed: fix(hugegraph): fail store start if PD health never succeeds #3417 (merged as f79df45)
Server Store health fail-closed: fix(hugegraph): fail server start if Store health never succeeds #3418 (merged as bb20a02)
PD initial store count from Store FQDNs: fix(hugegraph): derive PD initial store count from store FQDNs #3419 (merged as 9b1cc33)
Server waits for every Store health: fix(hugegraph): wait for every Store before server start #3420 (merged as 2b088d8)
Store waits for every PD health: fix(hugegraph): wait for every PD before store start #3421 (merged as ef535ae)
Distributed health-wait budget: fix(hugegraph): give distributed health waits official start budget #3422 (merged as c986b81)
Tests: apecloud/kubeblocks-tests#949

Evidence

Offline on this head:

addons/hugegraph/tests/contract_test.sh PASS on c986b81
Helm lint PASS
Child fix(hugegraph): wait for every PD before store start #3421 CI: helm dockerhub/aliyun/default, shell-check, shellspec all SUCCESS
Tests static on chore: modify redis xtrace empty password logic #949 @ 8ef64760: 34/0/0 vs addon c986b81

Prior runtime on equivalent standalone content (8220a018): final fresh all 33/0/0. Historical, not a new release-final count on ef535ae.

Acceptance gate

Reviewer cannot approve until both run on this exact head:

standalone checkpoint backup/restore
distributed Cluster create

Release-final still requires repeated full kubeblocks-tests HugeGraph suite rounds on this pinned head, on a dedicated HugeGraph vcluster. This PR is the upstreaming vehicle, not the release-standard closeout. Launcher: tests#949 hugegraph/launch-reviewer-gate.sh. No approved dedicated target yet.

Contract

Reviewed against addon API docs for ClusterDefinition topology (docs/addon-api/03-cluster-definition.md: orders, default topology, component name alignment), ComponentDefinition lifecycle/accounts, BackupPolicyTemplate/ActionSet checkpoint restore, and minimum acceptance (12a) for the declared standalone topology. Distributed topology is declared and statically contracted; distributed BR / scale-in / roleProbe / TLS remain unclaimed (12b). Exporter/MonitorDefinition is an observability enhancement, not an addon-api contract requirement.

codecov-commenter · 2026-08-18T17:11:11Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 0.00%. Comparing base (678ef79) to head (d5e2d25).

Additional details and impacted files

@@             Coverage Diff             @@
##           release-1.0   #3412   +/-   ##
===========================================
  Coverage         0.00%   0.00%           
===========================================
  Files               69      69           
  Lines             7275    7275           
===========================================
  Misses            7275    7275

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

leon-ape

The title omits the required addon scope for this single-addon change. The PR cannot pass the approval title gate.

Co-authored-by: Ava <ava@apecloud.com> Co-authored-by: Amber <amber@slock.local>

Co-authored-by: Amber <amber@slock.local>

weicao · 2026-08-18T20:09:19Z

Reviewer runtime gate on 83540814 is accepted. Title gate is already closed. No new source change.

Missing live evidence on this exact head:

standalone checkpoint backup/restore
distributed topology Cluster create

Those runs need a dedicated HugeGraph vcluster. None is handed off yet (local Kubernetes is out of scope). Routed Ops for that entrance. Offline contracts remain 25/0/0 on kubeblocks-tests#949 @ ac321e2d. Historical standalone 33/0/0 was on 8220a018, not this SHA.

Co-authored-by: Amber <amber@slock.local>

weicao · 2026-08-19T01:26:57Z

Candidate SHA moved to f79df452 (child #3417). Store start now fails if PD /v1/health never succeeds. Exact-head live rows must restart on this SHA when the dedicated vcluster is handed off.

Co-authored-by: Amber <amber@slock.local>

weicao · 2026-08-19T02:29:14Z

Candidate SHA moved to bb20a02c (child #3418). Server start now fails if Store /v1/health never succeeds. Exact-head live rows must restart on this SHA.

Co-authored-by: Amber <amber@slock.local>

weicao · 2026-08-19T04:20:16Z

Head is now 9b1cc331 after merging #3419.

HG_PD_INITIAL_STORE_COUNT is derived from STORE_POD_FQDNS instead of hardcoded 1, matching official pd.initial-store-count for a 3-store bootstrap.

Exact-head live rows are still required and still blocked on a dedicated HugeGraph vcluster:

standalone checkpoint backup/restore
distributed Cluster create

Offline contract on this head: PASS.

Co-authored-by: Amber <amber@slock.local>

weicao · 2026-08-19T04:32:54Z

Head is now 2b088d88 after merging #3420.

Server start waits for every Store /v1/health in STORE_POD_FQDNS, not only the first FQDN. That matches official 3-store compose and the #3419 initial-store-count pin.

Exact-head live rows still required and still blocked on a dedicated HugeGraph vcluster:

standalone checkpoint backup/restore
distributed Cluster create

Co-authored-by: Amber <amber@slock.local>

weicao · 2026-08-19T05:04:52Z

Head is now ef535ae4 after merging #3421.

Store start waits for every PD /v1/health in PD_POD_FQDNS, not only the first FQDN. That matches official 3-PD compose.

Exact-head live rows still required and still blocked on a dedicated HugeGraph vcluster:

standalone checkpoint backup/restore
distributed Cluster create

…3422) Co-authored-by: Amber <amber@slock.local>

weicao · 2026-08-19T11:11:01Z

Head is now c986b81b after merging #3422.

Store/Server health waits default to 90x2s. Store and Server startupProbe failureThreshold is 72 (360s), so official 3-node start_period cannot trip fail-closed.

Exact-head live rows still required and still blocked on a dedicated HugeGraph vcluster:

standalone checkpoint backup/restore
distributed Cluster create

weicao · 2026-08-19T12:07:03Z

Reviewer restated: no new source finding on c986b81b. Exact-head live rows still required and still blocked on a dedicated HugeGraph vcluster:

standalone checkpoint backup/restore
distributed Cluster create

Launcher: tests#949 @ 5cf1bc88 hugegraph/launch-reviewer-gate.sh.

Co-authored-by: Amber <amber@slock.local>

…3424) Co-authored-by: Amber <amber@slock.local>

Co-authored-by: Amber <amber@slock.local>

leon-ape

Exact-head review checkpoint for d5e2d25f1f9a39053f235d2a9307bd9dd2df2cdd:

Source and contract review is clean; the test-only schema-pin successor introduces no new source finding.
Approval is pending because this exact head has no runtime result for standalone checkpoint backup/restore or distributed-topology Cluster creation.

Owner: HugeGraph vcluster/Test lane. Required artifact: terminal runtime results bound to this addon SHA and the exact KubeBlocks, test, vcluster, and image identities. Predecessor-head results do not transfer.

Amber added 3 commits August 19, 2026 01:06

feat: add HugeGraph standalone addon

ac7acaf

fix: preserve HugeGraph auth across pod replacement

8a62a1d

test: make HugeGraph shutdown auditable

f0411fc

weicao requested review from a team, JashBook, ahjing99, leon-ape and shanshanying as code owners August 18, 2026 17:07

weicao mentioned this pull request Aug 18, 2026

feat(hugegraph): add native metrics exporter sidecar #3413

Merged

leon-ape reviewed Aug 18, 2026

View reviewed changes

weicao changed the title ~~feat: add HugeGraph standalone addon~~ feat(hugegraph): add standalone addon Aug 18, 2026

feat(hugegraph): add native metrics exporter sidecar (#3413)

3634d7b

Co-authored-by: Ava <ava@apecloud.com> Co-authored-by: Amber <amber@slock.local>

weicao added the nopick Not auto cherry-pick when PR merged label Aug 18, 2026

weicao mentioned this pull request Aug 18, 2026

feat(hugegraph): add distributed PD/Store/Server topology #3414

Merged

feat(hugegraph): add distributed PD/Store/Server topology (#3414)

4069790

Co-authored-by: Amber <amber@slock.local>

weicao changed the title ~~feat(hugegraph): add standalone addon~~ feat(hugegraph): add standalone and distributed addon Aug 18, 2026

weicao mentioned this pull request Aug 18, 2026

docs(hugegraph): declare distributed limits in README #3415

Merged

docs(hugegraph): declare distributed limits in README (#3415)

754d5d6

Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 18, 2026

docs(hugegraph): mark distributed systemAccounts unsupported #3416

Merged

docs(hugegraph): mark distributed systemAccounts unsupported (#3416)

8354081

Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

fix(hugegraph): fail store start if PD health never succeeds #3417

Merged

fix(hugegraph): fail store start if PD health never succeeds (#3417)

f79df45

Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

fix(hugegraph): fail server start if Store health never succeeds #3418

Merged

fix(hugegraph): fail server start if Store health never succeeds (#3418)

bb20a02

Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

fix(hugegraph): derive PD initial store count from store FQDNs #3419

Merged

fix(hugegraph): derive PD initial store count from store FQDNs (#3419)

9b1cc33

Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

fix(hugegraph): wait for every Store before server start #3420

Merged

fix(hugegraph): wait for every Store before server start (#3420)

2b088d8

Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

fix(hugegraph): wait for every PD before store start #3421

Merged

fix(hugegraph): wait for every PD before store start (#3421)

ef535ae

Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

fix(hugegraph): give distributed health waits official start budget #3422

Merged

fix(hugegraph): give distributed health waits official start budget (#…

c986b81

…3422) Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

test(hugegraph): fail closed on empty distributed FQDNs #3423

Merged

test(hugegraph): fail closed on empty distributed FQDNs (#3423)

f4b75a1

Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

fix(hugegraph): expose claimed distributed shape in cluster schema #3424

Merged

fix(hugegraph): expose claimed distributed shape in cluster schema (#…

f9e598f

…3424) Co-authored-by: Amber <amber@slock.local>

weicao mentioned this pull request Aug 19, 2026

test(hugegraph): pin cluster schema claimed distributed shape #3425

Merged

test(hugegraph): pin cluster schema claimed distributed shape (#3425)

d5e2d25

Co-authored-by: Amber <amber@slock.local>

leon-ape reviewed Aug 26, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(hugegraph): add standalone and distributed addon - #3412

feat(hugegraph): add standalone and distributed addon#3412
weicao wants to merge 16 commits into
release-1.0from
dev/hugegraph-release-1.0

weicao commented Aug 18, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Aug 18, 2026 •

edited

Loading

Uh oh!

leon-ape left a comment

Uh oh!

weicao commented Aug 18, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

leon-ape left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

weicao commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Scope

Candidate package

Child / companion PRs

Evidence

Acceptance gate

Contract

Uh oh!

codecov-commenter commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

leon-ape left a comment

Choose a reason for hiding this comment

Uh oh!

weicao commented Aug 18, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

weicao commented Aug 19, 2026

Uh oh!

leon-ape left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

weicao commented Aug 18, 2026 •

edited

Loading

codecov-commenter commented Aug 18, 2026 •

edited

Loading