doc: add Helm chart deployment page for Kubernetes - #494
bitflicker64 wants to merge 2 commits into
Conversation
Documents the distributed Helm chart from apache/hugegraph#3218: install with the three values presets, the auth Secrets model, PD health vs readiness probing, upgrade and scale-down caveats, uninstall behavior, and current limitations. EN and CN pages under quickstart/hugegraph, weight 4, matching the sibling page skeleton.
The versioned build validates that every canonical Docs page has a logical ID in data/version_routes.json; the two new pages were missing from it, failing the Build latest job. Adds en: and cn: entries with latest populated and the four older versions null, the same shape as the other pages introduced after 1.7.
bitflicker64
left a comment
bitflicker64
left a comment
There was a problem hiding this comment.
Blocking: yes, until apache/hugegraph#3218 merges. Summary: The EN and CN pages follow the chart at 05f3d9e0b closely and render in CI, but the chart is not on apache/hugegraph master yet (#3132 was closed unmerged, #3218 is an open draft), so merging this first publishes install commands that fail and seven 404 chart links per language. Four smaller mismatches with the chart are inline; each applies to the CN page too. Evidence: compared both pages with helm/hugegraph at 05f3d9e0b (values*.yaml, values.schema.json, _helpers.tpl, NOTES.txt, README anchors); helm template with defaults, values-cluster.yaml, hubble.enabled=true and invalid secret values; gh api repos/apache/hugegraph/contents/helm?ref=master (404); gh pr checks 494 (all passing, publish skipped).
|
|
||
| The Helm chart deploys a distributed HugeGraph cluster on Kubernetes: PD, Store, and Server, plus the optional | ||
| Hubble UI. It lives in the main repository under | ||
| [`helm/hugegraph`](https://github.com/apache/hugegraph/tree/master/helm/hugegraph). |
There was a problem hiding this comment.
gh api repos/apache/hugegraph/contents/helm?ref=master returns 404, #3132 was closed without merging, and #3218 is still an open draft. If this PR merges first, the site publishes a guide where the helm install in 3.2 fails because helm/hugegraph does not exist on master, and all seven tree/master/helm/hugegraph links on the page (EN and CN) are 404s. Please convert this PR to draft until #3218 merges.
| ### 2 Prerequisites | ||
|
|
||
| - Kubernetes 1.23 or later (the chart renders `autoscaling/v2` and `policy/v1`) | ||
| - Helm 3; the `--reset-then-reuse-values` flag mentioned under Upgrade needs Helm 3.14 or later |
There was a problem hiding this comment.
🧹 minor: section 7 of this page never mentions --reset-then-reuse-values, so this cross-reference points at nothing (CN line 45 too). The chart README brings it up under Upgrading for a reason: --reuse-values keeps the old release values as the whole base, so a release created by an earlier chart revision does not pick up new defaults such as the hardened securityContext. Please add that sentence to section 7 next to the --reuse-values explanation, or drop the reference here.
| |------|----------|--------------| | ||
| | `values.yaml` | 3 PD + 3 Store + 3 Server | Default; preferred anti-affinity, auth on, Hubble off | | ||
| | `values-single.yaml` | 1 + 1 + 1 | Single-node development and CI; smaller PVCs | | ||
| | `values-cluster.yaml` | 3 + 3 + 3 | Production starting point: JVM heap and resource settings, PD/Store PodDisruptionBudgets, `required` anti-affinity | |
There was a problem hiding this comment.
🧹 minor: the PD and Store PodDisruptionBudgets are not what values-cluster.yaml adds. values.yaml already sets pd.pdb.enabled: true and store.pdb.enabled: true, and helm template t ./helm/hugegraph renders both PDBs with default values. The preset's addition is the Server PDB (server.pdb.enabled: true, minAvailable: 2); rendering with -f values-cluster.yaml gives pd, server and store PDBs. Please say "Server PodDisruptionBudget" here and in CN line 96. The chart README's Values Presets table has the same wording.
|
|
||
| To manage a credential yourself, create the Secret before installing and point the matching `existingSecret` value | ||
| at it; the chart never modifies a Secret it did not create. Value constraints: the admin password must not contain | ||
| newlines, carriage returns, or backslashes; the JWT key must be at least 32 bytes; the PD secret must be printable |
There was a problem hiding this comment.
🧹 minor: the schema is stricter than this sentence. pd.auth.value must match ^([\x21-\x5b\x5d-\x7e][\x20-\x5b\x5d-\x7e]*)?$, so a printable ASCII secret with a backslash or a leading space is rejected (helm template with pd.auth.value: "abc\\def" fails schema validation). The admin password pattern also rejects leading whitespace. Please list both: the PD secret is printable ASCII with no leading whitespace and no backslashes, and the admin password has no newlines, carriage returns, backslashes or leading whitespace. CN line 135 needs the same change.
| still a healthy Raft member, and restarting it would make the outage worse. | ||
|
|
||
| Server startup gets a matching budget: the image would normally kill a Server still starting after 120 seconds, so | ||
| the chart derives `HG_SERVER_STARTUP_TIMEOUT_S` from the startup probe (450 seconds by default) and raises a lower |
There was a problem hiding this comment.
🧹 minor: "a matching budget" and "the image budget follows" read as if the image gets the full 450 s, but it does not. hugegraph.server.startupTimeoutSeconds in _helpers.tpl renders min 86400 (max 120 (budget - 300)), the probe budget minus the 300 s storage wait, and tests/server_startup_timeout_test.yaml asserts "150" for the defaults. Please say the probe budget is 450 s by default and the image gets that budget minus the 300 s storage wait (150 s by default, never below 120 s); CN lines 160-161 too. The chart README's Chart Details bullet also says the image gets 450, so #3218 may need the same fix.
This branch has not been deployed
1 participant
Purpose of the PR
apache/hugegraph#3218 adds a Helm chart for the distributed deployment (PD + Store + Server, optional Hubble), and the site has no page for it yet. This adds that page in EN and CN under
docs/quickstart/hugegraph/(weight 4, next to the Server/PD/Store install pages), following the same skeleton, heading numbering and mermaid usage as the sibling pages.What the page covers:
values.yaml,values-single.yaml,values-cluster.yaml),--waitguidance, and the two defaults to know before production use: no resources are set, and image tags tracklatestuntil the next release publishes versioned images.<release>-admin,<release>-auth-token,<release>-pd-auth), theexistingSecretbring-your-own paths, the value constraints, and the rotation caveats./v1/healthwhile readiness and the Store init-container wait use/v1/ready, and how the Server startup budget is derived from the startup probe.OnDeleteprocedure for production Store image rolls, the PVC resize constraint, and the guard that rejects PD/Store scale-down below the live StatefulSet.latesttags, the cross-replica graph visibility window of [Feature] Orchestrate graph creation through PD: new graphs are not consistently available across Server replicas ("Could not rebind [g]") hugegraph#3137, and operator-triggered Store recovery.The full values reference stays in the chart README; the page links to its anchors instead of duplicating the tables, so the two cannot drift apart.
Written against the chart at commit
05f3d9e0bof the PR branch (2026-09-18). Verified locally:scripts/hugo.sh buildpasses and both pages render (nav placement, mermaid diagram, tables, details blocks) in EN and CN.Rendered pages