Skip to content

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

Open
imbajin wants to merge 26 commits into
apache:masterfrom
hugegraph:feat/helm-rag-integration
Open

imbajin wants to merge 26 commits into
apache:masterfrom
hugegraph:feat/helm-rag-integration

Conversation

@imbajin

@imbajin imbajin commented Nov 3, 2026

Copy link
Copy Markdown
Member

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

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@imbajin
imbajin force-pushed the feat/helm-rag-integration branch from 9816d5f to c00c00f Compare November 3, 2026 17:24
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 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread helm/hugegraph/docs/rag.md Outdated

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@bitflicker64

Copy link
Copy Markdown
Contributor

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))

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants