fix(chart): add first-class Nebula graph backend values

Add first-class Helm values and API/indexing-worker env injection for Nebula graph backend credentials.

Author: earayu

deploy/aperag/README.md

@@ -24,3 +24,30 @@ helm install aperag ./deploy/aperag \
 ## Environment Variables
 
 All environment variables are managed through the `aperag-env` Secret. See `aperag-secret.yaml` template for configuration options.
+
+## Graph Backend Values
+
+The default graph backend is PostgreSQL (`api.env.GRAPH_DB_TYPE=postgresql`).
+For external graph stores, set the deployment default and enable the matching
+first-class dependency block:
+
+```bash
+# Neo4j
+helm upgrade -i aperag ./deploy/aperag \
+  --set api.env.GRAPH_DB_TYPE=neo4j \
+  --set neo4j.enabled=true \
+  --set neo4j.NEO4J_URI=bolt://neo4j-cluster-neo4j:7687 \
+  --set neo4j.NEO4J_CREDENTIALS_SECRET_NAME=neo4j-cluster-neo4j-account-neo4j
+
+# NebulaGraph
+helm upgrade -i aperag ./deploy/aperag \
+  --set api.env.GRAPH_DB_TYPE=nebula \
+  --set nebula.enabled=true \
+  --set nebula.NEBULA_HOSTS=nebula-cluster-graphd:9669 \
+  --set nebula.NEBULA_CREDENTIALS_SECRET_NAME=nebula-cluster-account-root
+```
+
+When `*.CREDENTIALS_SECRET_NAME` is set, the API and indexing-worker
+Deployments read usernames and passwords from Kubernetes Secret keys
+`username` and `password`. The same graph backend values are injected into both
+Deployments so read paths and indexing write paths use the same backend.

deploy/aperag/templates/api-deployment.yaml

@@ -159,6 +159,30 @@ spec:
               value: {{ .Values.neo4j.NEO4J_PASSWORD | default "neo4j" | quote }}
               {{- end }}
             {{- end }}
+            {{- if .Values.nebula.enabled }}
+            - name: NEBULA_HOSTS
+              value: {{ .Values.nebula.NEBULA_HOSTS | quote }}
+            - name: NEBULA_USERNAME
+              {{- if .Values.nebula.NEBULA_CREDENTIALS_SECRET_NAME }}
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.nebula.NEBULA_CREDENTIALS_SECRET_NAME }}
+                  key: username
+              {{- else }}
+              value: {{ .Values.nebula.NEBULA_USERNAME | default "root" | quote }}
+              {{- end }}
+            - name: NEBULA_PASSWORD
+              {{- if .Values.nebula.NEBULA_CREDENTIALS_SECRET_NAME }}
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.nebula.NEBULA_CREDENTIALS_SECRET_NAME }}
+                  key: password
+              {{- else }}
+              value: {{ .Values.nebula.NEBULA_PASSWORD | default "nebula" | quote }}
+              {{- end }}
+            - name: NEBULA_SPACE_PREFIX
+              value: {{ .Values.nebula.NEBULA_SPACE_PREFIX | default "aperag" | quote }}
+            {{- end }}
 
           image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
           name: aperag-api

deploy/aperag/templates/indexing-worker-deployment.yaml

@@ -105,6 +105,30 @@ spec:
               value: {{ .Values.neo4j.NEO4J_PASSWORD | default "neo4j" | quote }}
               {{- end }}
             {{- end }}
+            {{- if .Values.nebula.enabled }}
+            - name: NEBULA_HOSTS
+              value: {{ .Values.nebula.NEBULA_HOSTS | quote }}
+            - name: NEBULA_USERNAME
+              {{- if .Values.nebula.NEBULA_CREDENTIALS_SECRET_NAME }}
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.nebula.NEBULA_CREDENTIALS_SECRET_NAME }}
+                  key: username
+              {{- else }}
+              value: {{ .Values.nebula.NEBULA_USERNAME | default "root" | quote }}
+              {{- end }}
+            - name: NEBULA_PASSWORD
+              {{- if .Values.nebula.NEBULA_CREDENTIALS_SECRET_NAME }}
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.nebula.NEBULA_CREDENTIALS_SECRET_NAME }}
+                  key: password
+              {{- else }}
+              value: {{ .Values.nebula.NEBULA_PASSWORD | default "nebula" | quote }}
+              {{- end }}
+            - name: NEBULA_SPACE_PREFIX
+              value: {{ .Values.nebula.NEBULA_SPACE_PREFIX | default "aperag" | quote }}
+            {{- end }}
           image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
           name: aperag-indexing-worker
           imagePullPolicy: {{ .Values.image.pullPolicy }}

deploy/aperag/values.yaml

@@ -91,6 +91,27 @@ neo4j:
   # ⚠️ Recommend to use NEO4J_CREDENTIALS_SECRET_NAME
   NEO4J_PASSWORD: ""
 
+nebula:
+  enabled: false  # Enable/disable NebulaGraph integration (optional for graph features)
+  # Also set api.env.GRAPH_DB_TYPE=nebula to make Nebula the default graph backend.
+  # Comma-separated graphd endpoints, e.g. "nebula-cluster-graphd:9669".
+  NEBULA_HOSTS: "nebula-cluster-graphd:9669"
+  # The name of the Secret containing Nebula username and password (e.g. "username" and "password" keys).
+  # Example: "nebula-cluster-account-root" (references your Nebula credential Secret)
+  NEBULA_CREDENTIALS_SECRET_NAME: ""
+  # Username and Password Priority:
+  # 1. If NEBULA_CREDENTIALS_SECRET_NAME is set, attempts to fetch 'username' and 'password' from that Secret.
+  # 2. If NEBULA_CREDENTIALS_SECRET_NAME is empty, uses the direct values of NEBULA_USERNAME and NEBULA_PASSWORD.
+  # 3. If direct values are also empty, defaults to "root" / "nebula".
+  # ⚠️ Recommend to use NEBULA_CREDENTIALS_SECRET_NAME
+  NEBULA_USERNAME: "root"
+  # Password (Sensitive information, strongly recommended NOT to set directly in values.yaml):
+  # Only use this if you are NOT using NEBULA_CREDENTIALS_SECRET_NAME and accept the security implications.
+  # ⚠️ Strongly discourage directly setting sensitive passwords here. Use Secrets for production.
+  # ⚠️ Recommend to use NEBULA_CREDENTIALS_SECRET_NAME
+  NEBULA_PASSWORD: "nebula"
+  NEBULA_SPACE_PREFIX: "aperag"
+
 api:
   dataPath: /data/aperag
   replicaCount: 1