feat(helm): integrate optional HugeGraph RAG deployment by imbajin · Pull Request #3450 · apache/hugegraph

imbajin · 2026-11-03T15:34:15Z

Before → After

Before: HugeGraph RAG uses a separate Kubernetes chart, creating configuration and credential drift from the main HugeGraph deployment.
After: add RAG as an opt-in component of the canonical Helm chart, with release-scoped Server and Secret wiring, single-node and cluster presets, and optional networking and persistence controls.

Validation boundary

The source PR reports local source-contract and configuration checks; rendered tests were skipped locally because Helm was unavailable. Live deployment acceptance has not been established.

Source: hugegraph#365

imbajin · 2026-11-03T15:38:55Z

+  - it: connects an enabled RAG pod to the same-release Server service
+    template: rag-deployment.yaml
+    set:
+      rag.enabled: true


Please load the RAG overlay for enabled test fixtures.

The enabled cases set only rag.enabled, but the root chart values do not supply the overlay's RAG defaults. Validation requires an image repository, so these cases cannot reach their success assertions. The provider Secret example likewise omits the overlay and fails validation. Load values-rag.yaml or supply complete fixtures, and update the example to include it.

This is a static finding; Helm was not run and this is not a proven cause of the current CI failures.

imbajin · 2026-11-03T15:38:55Z

+          {{- end }}
+          ports:
+            - name: http
+              containerPort: {{ include "hugegraph.rag.port" . }}


Please align the configured port with the application listener.

rag.port changes this declared container port, the Service target and the named probe port, but this Deployment does not change the application arguments. The official hugegraph-ai source Dockerfile at 1cfad720 starts the application with --port 8001. A non-default rag.port therefore mismatches an image built from that source. Pass the listener argument through to the application, or separate the Service port from a fixed listener port.

This is a static finding for that inspected source version; the mutable latest image and Kubernetes behavior were not inspected or run, and this is not a proven cause of current CI failures.

Keep generated runtime configuration ephemeral so rotated Kubernetes Secrets remain authoritative after restarts. Retain prompts and indexes on the PVC, enforce the application's single-active replica contract, reject unsafe security overrides and unknown RAG fields, and strengthen Helm regressions and documentation.

Keep the editable HugeGraph AI .env, prompts, indexes and resources on the retained PVC while reconciling current Kubernetes env and envFrom keys before startup so rotated Secrets remain authoritative. Inherit the global persistence switch, support platform-assigned non-root IDs, avoid archive-mode writes to CSI roots, exclude documentation images from the packaged chart, and document the minimal same-release configuration and external editing workflow.

Fix the retained PVC claim helper name, remove an extra readiness get invocation, and keep the non-persistent prompt path aligned with the HugeGraph AI image layout.

Reject extra RAG volumes and mounts that collide with the chart-managed persistent data volume, add regression coverage, and document the special GRAPH_PWD envFrom rule plus explicit GitOps rollout triggers for rotated external credentials.

Reject rag.env names containing '=' or non-printable bytes during Helm rendering, matching the Kubernetes relaxed EnvVar name contract, and add regression coverage for invalid names.

bitflicker64

Blocking: yes. Summary: the RAG Pod keeps Kubernetes service links, so it crash-loops at import when a qdrant or milvus Service shares its namespace; the docs also name the RAG Deployment and PVC wrongly for the documented release name.

bitflicker64 · 2026-11-03T22:44:58Z

+      {{- $serviceAccount := get $rag "serviceAccount" | default dict }}
+      {{- $serviceAccountCreate := true }}
+      {{- if hasKey $serviceAccount "create" }}{{- $serviceAccountCreate = get $serviceAccount "create" }}{{- end }}
+      automountServiceAccountToken: {{ get $serviceAccount "automountServiceAccountToken" | default false }}


Important: the RAG Pod keeps Kubernetes service links, so a qdrant or milvus Service in the same namespace injects QDRANT_PORT=tcp://<ip>:6333 or MILVUS_PORT=tcp://<ip>:19530, and IndexConfig raises ValueError at import on int(os.environ.get("QDRANT_PORT", "6333")). Set enableServiceLinks: false in the RAG Pod spec.

bitflicker64 · 2026-11-03T22:44:58Z

+
+```bash
+RELEASE=hugegraph
+kubectl -n hugegraph rollout restart deployment/${RELEASE}-hugegraph-rag


Minor: with the documented release name hugegraph, hugegraph.fullname resolves to hugegraph, so the objects are hugegraph-rag and hugegraph-rag-data, and this command and those at lines 162, 269 and 291 target hugegraph-hugegraph-rag, which does not exist. Use the real names, or select the Deployment by app.kubernetes.io/instance=${RELEASE},app.kubernetes.io/component=rag.

Move configuration precedence and resource ownership to the RAG application, preserve full Server URLs, support external mounts, and fix RAG regression discovery across Helm versions. Requires the updated HugeGraph AI latest/1.8 image from AI #96. Helm 1+1+1 runtime acceptance, credential rotation and persistence checks were completed with a local source-overlay image.

bitflicker64 · 2026-11-04T08:33:14Z

The earlier review comments below still apply at 7b69834; this head does not fix them.

Important: the RAG Pod keeps Kubernetes service links, so a qdrant or milvus Service in the same namespace injects QDRANT_PORT=tcp://<ip>:6333 or MILVUS_PORT=tcp://<ip>:19530, and IndexConfig raises ValueError at import on int(os.environ.get("QDRANT_PORT", "6333")). Set enableServiceLinks: false in the RAG Pod spec. (feat(helm): integrate optional HugeGraph RAG deployment #3450 (comment))
Minor: with the documented release name hugegraph, hugegraph.fullname resolves to hugegraph, so the objects are hugegraph-rag and hugegraph-rag-data, and this command and those at lines 162, 269 and 291 target hugegraph-hugegraph-rag, which does not exist. Use the real names, or select the Deployment by app.kubernetes.io/instance=${RELEASE},app.kubernetes.io/component=rag. (feat(helm): integrate optional HugeGraph RAG deployment #3450 (comment))

bitflicker64 · 2026-11-04T22:44:43Z

The earlier review comments below still apply at 0d458bc; this head does not fix them.

Important: the RAG Pod keeps Kubernetes service links, so a qdrant or milvus Service in the same namespace injects QDRANT_PORT=tcp://<ip>:6333 or MILVUS_PORT=tcp://<ip>:19530, and IndexConfig raises ValueError at import on int(os.environ.get("QDRANT_PORT", "6333")). Set enableServiceLinks: false in the RAG Pod spec. (feat(helm): integrate optional HugeGraph RAG deployment #3450 (comment))
Minor: with the documented release name hugegraph, hugegraph.fullname resolves to hugegraph, so the objects are hugegraph-rag and hugegraph-rag-data, and this command and those at lines 162, 269 and 291 target hugegraph-hugegraph-rag, which does not exist. Use the real names, or select the Deployment by app.kubernetes.io/instance=${RELEASE},app.kubernetes.io/component=rag. (feat(helm): integrate optional HugeGraph RAG deployment #3450 (comment))

bitflicker64

Blocking: yes. Summary: the RAG Pod still keeps Kubernetes service links, so a qdrant or milvus Service in the namespace crash-loops it at import, and the docs still name hugegraph-hugegraph-rag for release hugegraph. The merge-gate note also links fork PR hugegraph/hugegraph-ai#96 instead of apache/hugegraph-ai#396.

The earlier review comments below still apply at 8211e6c; this head does not fix them.

Important: the RAG Pod keeps Kubernetes service links, so a qdrant or milvus Service in the same namespace injects QDRANT_PORT=tcp://<ip>:6333 or MILVUS_PORT=tcp://<ip>:19530, and IndexConfig raises ValueError at import on int(os.environ.get("QDRANT_PORT", "6333")). Set enableServiceLinks: false in the RAG Pod spec. (#3450 (comment))
Minor: with the documented release name hugegraph, hugegraph.fullname resolves to hugegraph, so the objects are hugegraph-rag and hugegraph-rag-data, and this command and those at lines 162, 269 and 291 target hugegraph-hugegraph-rag, which does not exist. Use the real names, or select the Deployment by app.kubernetes.io/instance=${RELEASE},app.kubernetes.io/component=rag. (#3450 (comment))

bitflicker64 · 2026-11-05T06:42:32Z

+independent of whether HugeGraph uses one PD/Store/Server or a distributed cluster.
+RAG remains a single process with a persistent resource directory.
+
+> This refactor requires [HugeGraph AI PR #96](https://github.com/hugegraph/hugegraph-ai/pull/96) in the


Minor: this merge gate and the guide link at line 205 point at fork PR hugegraph/hugegraph-ai#96 and its branch, while the upstream change is apache/hugegraph-ai#396. Link apache/hugegraph-ai#396 and its merged docs path instead.

bitflicker64 · 2026-11-05T11:05:44Z

The earlier review comments below still apply at 55857d1; this head does not fix them.

Important: the RAG Pod keeps Kubernetes service links, so a qdrant or milvus Service in the same namespace injects QDRANT_PORT=tcp://<ip>:6333 or MILVUS_PORT=tcp://<ip>:19530, and IndexConfig raises ValueError at import on int(os.environ.get("QDRANT_PORT", "6333")). Set enableServiceLinks: false in the RAG Pod spec. (feat(helm): integrate optional HugeGraph RAG deployment #3450 (comment))
Minor: with the documented release name hugegraph, hugegraph.fullname resolves to hugegraph, so the objects are hugegraph-rag and hugegraph-rag-data, and this command and those at lines 162, 269 and 291 target hugegraph-hugegraph-rag, which does not exist. Use the real names, or select the Deployment by app.kubernetes.io/instance=${RELEASE},app.kubernetes.io/component=rag. (feat(helm): integrate optional HugeGraph RAG deployment #3450 (comment))
Minor: this merge gate and the guide link at line 205 point at fork PR hugegraph/hugegraph-ai#96 and its branch, while the upstream change is apache/hugegraph-ai#396. Link apache/hugegraph-ai#396 and its merged docs path instead. (feat(helm): integrate optional HugeGraph RAG deployment #3450 (comment))

imbajin added 2 commits November 3, 2026 23:05

feat(helm): add optional HugeGraph RAG component

74c1676

test(helm): cover optional RAG rendering

4b10f1f

imbajin mentioned this pull request Nov 3, 2026

feat(helm): integrate single-instance RAG with external configuration hugegraph/hugegraph#365

Closed

imbajin commented Nov 3, 2026

View reviewed changes

imbajin mentioned this pull request Nov 3, 2026

refactor(helm): retire duplicate RAG chart apache/hugegraph-ai#393

Merged

fix(helm): align RAG runtime and security defaults

c00c00f

imbajin force-pushed the feat/helm-rag-integration branch from 9816d5f to c00c00f Compare November 3, 2026 17:24

imbajin added 10 commits November 4, 2026 02:26

fix(helm): persist and harden RAG configuration

b3c15a1

test(helm): avoid duplicate and eager RAG test loading

fed1821

probe

9e4f5e4

fix(helm): correct RAG template rendering

dcaa28e

Fix the retained PVC claim helper name, remove an extra readiness get invocation, and keep the non-persistent prompt path aligned with the HugeGraph AI image layout.

fix(helm): validate RAG environment names

00410c0

Reject rag.env names containing '=' or non-printable bytes during Helm rendering, matching the Kubernetes relaxed EnvVar name contract, and add regression coverage for invalid names.

fix(helm): complete RAG test package license header

5dddbf7

Merge branch 'master' into feat/helm-rag-integration

eae8d49

imbajin mentioned this pull request Nov 3, 2026

refactor(helm): retire duplicate RAG chart hugegraph/hugegraph-ai#92

Closed

imbajin added 2 commits November 4, 2026 05:27

fix(helm): harden RAG validation and startup

7181b07

fix(helm): purge stale RAG credentials on restart

855d2a3

bitflicker64 reviewed Nov 3, 2026

View reviewed changes

imbajin added 9 commits November 4, 2026 07:23

fix(helm): validate RAG probes and clarify storage changes

81560b8

test(helm): strengthen RAG storage and network assertions

b0da111

test(helm): validate enabled RAG presets with kubeconform

bd5f88c

fix(helm): validate RAG resource switches and clarify release gate

b83ba4e

test(helm): strengthen RAG resource and network boundaries

872cce6

fix(helm): validate optional RAG probe timing

f9ada05

fix(helm): validate RAG grace period and probe paths

49d1b5a

fix(helm): validate RAG persistent volume settings

ada4222

fix(helm): reject invalid kilo suffix and preserve claim name types

7b69834

merge: include apache master and document app-owned RAG connections

0d458bc

imbajin added 2 commits November 5, 2026 14:03

fix(helm): reject mixed ReadWriteOncePod access modes

3485e72

test(helm): cover exclusive ReadWriteOncePod mode

8211e6c

bitflicker64 reviewed Nov 5, 2026

View reviewed changes

HugeGraph Contributor and others added 5 commits November 5, 2026 10:47

docs(helm): align RAG configuration contract

6237345

test(helm): consolidate RAG chart coverage

9655878

test(helm): preserve default service port checks

85a9382

refactor(helm): simplify single RAG replica handling

b28f41f

refactor(helm): derive RAG config paths in application

55857d1

HugeGraph Contributor and others added 5 commits November 5, 2026 12:49

docs(helm): clarify cluster RAG setup

e84c1dc

Remove unused RAG architecture illustration

279a053

docs(helm): remove temporary RAG release gate history

abc75bd

test(helm): skip schema bypass check on older Helm

1dd99e4

fix(helm): pin validated RAG image

14134fd

imbajin force-pushed the feat/helm-rag-integration branch from 64c566c to 14134fd Compare November 5, 2026 13:47

fix(helm): isolate RAG service environment

30ee6d0

imbajin force-pushed the feat/helm-rag-integration branch from 8c9bedb to 30ee6d0 Compare November 5, 2026 13:51

docs(helm): use rendered RAG resource names

767d789

MrJs133 approved these changes Nov 5, 2026

View reviewed changes

imbajin merged commit cd7f149 into apache:master Nov 5, 2026
1 check passed

Navigation Menu

Repository navigation

feat(helm): integrate optional HugeGraph RAG deployment - #3450

feat(helm): integrate optional HugeGraph RAG deployment#3450
imbajin merged 40 commits into
apache:masterfrom
hugegraph:feat/helm-rag-integration

imbajin commented Nov 3, 2026

Uh oh!

imbajin Nov 3, 2026

Uh oh!

imbajin Nov 3, 2026

Uh oh!

bitflicker64 left a comment

Uh oh!

bitflicker64 Nov 3, 2026

Uh oh!

bitflicker64 Nov 3, 2026

Uh oh!

bitflicker64 commented Nov 4, 2026

Uh oh!

bitflicker64 commented Nov 4, 2026

Uh oh!

bitflicker64 left a comment

Uh oh!

bitflicker64 Nov 5, 2026

Uh oh!

bitflicker64 commented Nov 5, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

imbajin commented Nov 3, 2026

Before → After

Validation boundary

Uh oh!

imbajin Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

imbajin Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

bitflicker64 left a comment

Choose a reason for hiding this comment

Uh oh!

bitflicker64 Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

bitflicker64 Nov 3, 2026

Choose a reason for hiding this comment

Uh oh!

bitflicker64 commented Nov 4, 2026

Uh oh!

bitflicker64 commented Nov 4, 2026

Uh oh!

bitflicker64 left a comment

Choose a reason for hiding this comment

Uh oh!

bitflicker64 Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

bitflicker64 commented Nov 5, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants