Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat: add Helm chart for Kubernetes deployment (#800)

Jackjin723069cf5124
diff --git a/deploy/helm/README.md b/deploy/helm/README.md
new file mode 100644
index 000000000..9645d0676
--- /dev/null
+++ b/deploy/helm/README.md
@@ -0,0 +1,142 @@
+# OpenViking Helm Chart
+
+Deploy OpenViking on Kubernetes using Helm.
+
+## Prerequisites
+
+- Kubernetes 1.24+
+- Helm 3.x
+- A storage class that supports `ReadWriteOnce` persistent volumes (for RocksDB data)
+
+## Installation
+
+### Quick Start
+
+```bash
+helm install openviking ./deploy/helm/openviking \
+ --set config.embedding.dense.api_key="YOUR_EMBEDDING_API_KEY" \
+ --set config.vlm.api_key="YOUR_VLM_API_KEY"
+```
+
+### Install with Custom Values
+
+Create a `my-values.yaml` file:
+
+```yaml
+replicaCount: 1
+
+resources:
+ limits:
+ cpu: "4"
+ memory: 8Gi
+ requests:
+ cpu: "1"
+ memory: 2Gi
+
+persistence:
+ size: 50Gi
+ storageClass: "gp3"
+
+config:
+ storage:
+ workspace: /app/data/openviking_workspace
+ log:
+ level: INFO
+ output: stdout
+ server:
+ host: "0.0.0.0"
+ port: 1933
+ workers: 1
+ embedding:
+ dense:
+ api_base: "https://api.openai.com/v1"
+ api_key: "your-key"
+ provider: "openai"
+ dimension: 3072
+ model: "text-embedding-3-large"
+ max_concurrent: 10
+ vlm:
+ api_base: "https://api.openai.com/v1"
+ api_key: "your-key"
+ provider: "openai"
+ model: "gpt-4o"
+ max_concurrent: 100
+```
+
+Then install:
+
+```bash
+helm install openviking ./deploy/helm/openviking -f my-values.yaml
+```
+
+### Using Secrets for API Keys
+
+For production, avoid putting API keys directly in values. Use `extraEnv` with
+Kubernetes secrets instead:
+
+```bash
+# Create a secret
+kubectl create secret generic openviking-api-keys \
+ --from-literal=embedding-api-key="YOUR_KEY" \
+ --from-literal=vlm-api-key="YOUR_KEY"
+```
+
+Then reference it in your values:
+
+```yaml
+extraEnv:
+ - name: EMBEDDING_API_KEY
+ valueFrom:
+ secretKeyRef:
+ name: openviking-api-keys
+ key: embedding-api-key
+ - name: VLM_API_KEY
+ valueFrom:
+ secretKeyRef:
+ name: openviking-api-keys
+ key: vlm-api-key
+```
+
+## Configuration
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `replicaCount` | Number of replicas | `1` |
+| `image.repository` | Container image repository | `ghcr.io/volcengine/openviking` |
+| `image.tag` | Container image tag | Chart appVersion |
+| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
+| `service.type` | Kubernetes service type | `ClusterIP` |
+| `service.port` | Service port | `1933` |
+| `persistence.enabled` | Enable persistent storage | `true` |
+| `persistence.size` | PVC size | `20Gi` |
+| `persistence.storageClass` | Storage class name | `""` (default) |
+| `persistence.existingClaim` | Use an existing PVC | `""` |
+| `resources.limits.cpu` | CPU limit | `2` |
+| `resources.limits.memory` | Memory limit | `4Gi` |
+| `resources.requests.cpu` | CPU request | `500m` |
+| `resources.requests.memory` | Memory request | `1Gi` |
+| `ingress.enabled` | Enable ingress | `false` |
+| `config` | Full ov.conf configuration object | See `values.yaml` |
+| `extraEnv` | Additional environment variables | `[]` |
+
+## Upgrading
+
+```bash
+helm upgrade openviking ./deploy/helm/openviking -f my-values.yaml
+```
+
+The deployment uses a `Recreate` strategy to avoid data corruption from
+multiple pods accessing the same RocksDB volume simultaneously.
+
+## Uninstalling
+
+```bash
+helm uninstall openviking
+```
+
+Note: The PersistentVolumeClaim is not deleted automatically. To remove stored
+data:
+
+```bash
+kubectl delete pvc openviking-data
+```
diff --git a/deploy/helm/openviking/.helmignore b/deploy/helm/openviking/.helmignore
new file mode 100644
index 000000000..414bb6e8a
--- /dev/null
+++ b/deploy/helm/openviking/.helmignore
@@ -0,0 +1,18 @@
+# Patterns to ignore when building packages.
+.DS_Store
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+.project
+.idea/
+*.tmproj
+.vscode/
diff --git a/deploy/helm/openviking/Chart.yaml b/deploy/helm/openviking/Chart.yaml
new file mode 100644
index 000000000..cbfc1bf0b
--- /dev/null
+++ b/deploy/helm/openviking/Chart.yaml
@@ -0,0 +1,18 @@
+apiVersion: v2
+name: openviking
+description: OpenViking - The Context Database for AI Agents
+type: application
+version: 0.1.0
+appVersion: "0.1.18"
+keywords:
+ - openviking
+ - ai
+ - agents
+ - context-database
+ - rag
+home: https://github.com/volcengine/OpenViking
+sources:
+ - https://github.com/volcengine/OpenViking
+maintainers:
+ - name: OpenViking Contributors
+ url: https://github.com/volcengine/OpenViking
diff --git a/deploy/helm/openviking/templates/NOTES.txt b/deploy/helm/openviking/templates/NOTES.txt
new file mode 100644
index 000000000..8afef2617
--- /dev/null
+++ b/deploy/helm/openviking/templates/NOTES.txt
@@ -0,0 +1,29 @@
+Thank you for installing OpenViking!
+
+Your release is named: {{ .Release.Name }}
+
+To check the status of your deployment:
+
+ kubectl get pods -l "app.kubernetes.io/name={{ include "openviking.name" . }},app.kubernetes.io/instance={{ .Release.Name }}"
+
+To access the OpenViking API:
+
+{{- if .Values.ingress.enabled }}
+{{- range $host := .Values.ingress.hosts }}
+ http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}
+{{- end }}
+{{- else if contains "NodePort" .Values.service.type }}
+ export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "openviking.fullname" . }})
+ export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
+ echo "http://$NODE_IP:$NODE_PORT"
+{{- else if contains "LoadBalancer" .Values.service.type }}
+ NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+ kubectl get --namespace {{ .Release.Namespace }} svc {{ include "openviking.fullname" . }} -w
+{{- else }}
+ kubectl port-forward --namespace {{ .Release.Namespace }} svc/{{ include "openviking.fullname" . }} {{ .Values.service.port }}:{{ .Values.service.port }}
+ echo "Visit http://127.0.0.1:{{ .Values.service.port }}/health to verify the server is running."
+{{- end }}
+
+IMPORTANT: Make sure to configure your embedding and VLM API keys in values.yaml
+or via extraEnv before using OpenViking. The server will not function correctly
+without valid model provider credentials.
diff --git a/deploy/helm/openviking/templates/_helpers.tpl b/deploy/helm/openviking/templates/_helpers.tpl
new file mode 100644
index 000000000..bbca5b8d4
--- /dev/null
+++ b/deploy/helm/openviking/templates/_helpers.tpl
@@ -0,0 +1,71 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "openviking.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this
+(by the DNS naming spec). If release name contains chart name it will be used
+as a full name.
+*/}}
+{{- define "openviking.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "openviking.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels.
+*/}}
+{{- define "openviking.labels" -}}
+helm.sh/chart: {{ include "openviking.chart" . }}
+{{ include "openviking.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels.
+*/}}
+{{- define "openviking.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "openviking.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use.
+*/}}
+{{- define "openviking.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "openviking.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
+
+{{/*
+Return the image name including tag.
+*/}}
+{{- define "openviking.image" -}}
+{{- $tag := default .Chart.AppVersion .Values.image.tag -}}
+{{- printf "%s:%s" .Values.image.repository $tag -}}
+{{- end }}
diff --git a/deploy/helm/openviking/templates/configmap.yaml b/deploy/helm/openviking/templates/configmap.yaml
new file mode 100644
index 000000000..e86b1b6e3
--- /dev/null
+++ b/deploy/helm/openviking/templates/configmap.yaml
@@ -0,0 +1,9 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: {{ include "openviking.fullname" . }}-config
+ labels:
+ {{- include "openviking.labels" . | nindent 4 }}
+data:
+ ov.conf: |
+ {{- .Values.config | toPrettyJson | nindent 4 }}
diff --git a/deploy/helm/openviking/templates/deployment.yaml b/deploy/helm/openviking/templates/deployment.yaml
new file mode 100644
index 000000000..4b8838cfd
--- /dev/null
+++ b/deploy/helm/openviking/templates/deployment.yaml
@@ -0,0 +1,98 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: {{ include "openviking.fullname" . }}
+ labels:
+ {{- include "openviking.labels" . | nindent 4 }}
+spec:
+ replicas: {{ .Values.replicaCount }}
+ selector:
+ matchLabels:
+ {{- include "openviking.selectorLabels" . | nindent 6 }}
+ strategy:
+ type: Recreate
+ template:
+ metadata:
+ annotations:
+ checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+ {{- with .Values.podAnnotations }}
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ labels:
+ {{- include "openviking.labels" . | nindent 8 }}
+ {{- with .Values.podLabels }}
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ spec:
+ {{- with .Values.imagePullSecrets }}
+ imagePullSecrets:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- if .Values.serviceAccount.create }}
+ serviceAccountName: {{ include "openviking.serviceAccountName" . }}
+ {{- end }}
+ {{- with .Values.podSecurityContext }}
+ securityContext:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ containers:
+ - name: {{ .Chart.Name }}
+ {{- with .Values.securityContext }}
+ securityContext:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ image: {{ include "openviking.image" . }}
+ imagePullPolicy: {{ .Values.image.pullPolicy }}
+ command: ["openviking-server"]
+ env:
+ - name: OPENVIKING_CONFIG_FILE
+ value: /app/ov.conf
+ {{- with .Values.extraEnv }}
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ ports:
+ - name: http
+ containerPort: {{ .Values.config.server.port | default 1933 }}
+ protocol: TCP
+ {{- with .Values.livenessProbe }}
+ livenessProbe:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.readinessProbe }}
+ readinessProbe:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- with .Values.resources }}
+ resources:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ volumeMounts:
+ - name: config
+ mountPath: /app/ov.conf
+ subPath: ov.conf
+ readOnly: true
+ - name: data
+ mountPath: {{ .Values.persistence.mountPath }}
+ volumes:
+ - name: config
+ configMap:
+ name: {{ include "openviking.fullname" . }}-config
+ - name: data
+ {{- if .Values.persistence.enabled }}
+ persistentVolumeClaim:
+ claimName: {{ .Values.persistence.existingClaim | default (printf "%s-data" (include "openviking.fullname" .)) }}
+ {{- else }}
+ emptyDir: {}
+ {{- end }}
+ {{- with .Values.nodeSelector }}
+ nodeSelector:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.affinity }}
+ affinity:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.tolerations }}
+ tolerations:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
diff --git a/deploy/helm/openviking/templates/ingress.yaml b/deploy/helm/openviking/templates/ingress.yaml
new file mode 100644
index 000000000..2bfd27a9c
--- /dev/null
+++ b/deploy/helm/openviking/templates/ingress.yaml
@@ -0,0 +1,41 @@
+{{- if .Values.ingress.enabled -}}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+ name: {{ include "openviking.fullname" . }}
+ labels:
+ {{- include "openviking.labels" . | nindent 4 }}
+ {{- with .Values.ingress.annotations }}
+ annotations:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+spec:
+ {{- if .Values.ingress.className }}
+ ingressClassName: {{ .Values.ingress.className }}
+ {{- end }}
+ {{- if .Values.ingress.tls }}
+ tls:
+ {{- range .Values.ingress.tls }}
+ - hosts:
+ {{- range .hosts }}
+ - {{ . | quote }}
+ {{- end }}
+ secretName: {{ .secretName }}
+ {{- end }}
+ {{- end }}
+ rules:
+ {{- range .Values.ingress.hosts }}
+ - host: {{ .host | quote }}
+ http:
+ paths:
+ {{- range .paths }}
+ - path: {{ .path }}
+ pathType: {{ .pathType }}
+ backend:
+ service:
+ name: {{ include "openviking.fullname" $ }}
+ port:
+ name: http
+ {{- end }}
+ {{- end }}
+{{- end }}
diff --git a/deploy/helm/openviking/templates/pvc.yaml b/deploy/helm/openviking/templates/pvc.yaml
new file mode 100644
index 000000000..a6118d662
--- /dev/null
+++ b/deploy/helm/openviking/templates/pvc.yaml
@@ -0,0 +1,17 @@
+{{- if and .Values.persistence.enabled (not .Values.persistence.existingClaim) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+ name: {{ include "openviking.fullname" . }}-data
+ labels:
+ {{- include "openviking.labels" . | nindent 4 }}
+spec:
+ accessModes:
+ - {{ .Values.persistence.accessMode }}
+ {{- if .Values.persistence.storageClass }}
+ storageClassName: {{ .Values.persistence.storageClass | quote }}
+ {{- end }}
+ resources:
+ requests:
+ storage: {{ .Values.persistence.size }}
+{{- end }}
diff --git a/deploy/helm/openviking/templates/service.yaml b/deploy/helm/openviking/templates/service.yaml
new file mode 100644
index 000000000..d0fcb4791
--- /dev/null
+++ b/deploy/helm/openviking/templates/service.yaml
@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+ name: {{ include "openviking.fullname" . }}
+ labels:
+ {{- include "openviking.labels" . | nindent 4 }}
+spec:
+ type: {{ .Values.service.type }}
+ ports:
+ - port: {{ .Values.service.port }}
+ targetPort: http
+ protocol: TCP
+ name: http
+ selector:
+ {{- include "openviking.selectorLabels" . | nindent 4 }}
diff --git a/deploy/helm/openviking/values.yaml b/deploy/helm/openviking/values.yaml
new file mode 100644
index 000000000..c1996b90d
--- /dev/null
+++ b/deploy/helm/openviking/values.yaml
@@ -0,0 +1,134 @@
+# Default values for openviking.
+
+replicaCount: 1
+
+image:
+ repository: ghcr.io/volcengine/openviking
+ pullPolicy: IfNotPresent
+ # Overrides the image tag whose default is the chart appVersion.
+ tag: ""
+
+imagePullSecrets: []
+nameOverride: ""
+fullnameOverride: ""
+
+serviceAccount:
+ # Specifies whether a service account should be created.
+ create: false
+ # Annotations to add to the service account.
+ annotations: {}
+ # The name of the service account to use.
+ # If not set and create is true, a name is generated using the fullname template.
+ name: ""
+
+podAnnotations: {}
+podLabels: {}
+
+podSecurityContext: {}
+ # fsGroup: 1000
+
+securityContext: {}
+ # runAsNonRoot: true
+ # runAsUser: 1000
+
+service:
+ type: ClusterIP
+ port: 1933
+
+ingress:
+ enabled: false
+ className: ""
+ annotations: {}
+ # kubernetes.io/ingress.class: nginx
+ # cert-manager.io/cluster-issuer: letsencrypt-prod
+ hosts:
+ - host: openviking.local
+ paths:
+ - path: /
+ pathType: Prefix
+ tls: []
+ # - secretName: openviking-tls
+ # hosts:
+ # - openviking.local
+
+resources:
+ limits:
+ cpu: "2"
+ memory: 4Gi
+ requests:
+ cpu: 500m
+ memory: 1Gi
+
+persistence:
+ enabled: true
+ # Storage class for the PVC. Leave empty for the default storage class.
+ storageClass: ""
+ accessMode: ReadWriteOnce
+ size: 20Gi
+ # Existing PVC name. If set, no new PVC is created.
+ existingClaim: ""
+ # Mount path inside the container for data directory.
+ mountPath: /app/data
+
+# OpenViking server configuration (ov.conf).
+# This is rendered into a ConfigMap and mounted at /app/ov.conf.
+config:
+ storage:
+ workspace: /app/data/openviking_workspace
+ log:
+ level: INFO
+ output: stdout
+ server:
+ host: "0.0.0.0"
+ port: 1933
+ workers: 1
+ cors_origins:
+ - "*"
+ embedding:
+ dense:
+ api_base: ""
+ api_key: ""
+ provider: "openai"
+ dimension: 3072
+ model: "text-embedding-3-large"
+ max_concurrent: 10
+ vlm:
+ api_base: ""
+ api_key: ""
+ provider: "openai"
+ model: "gpt-4o"
+ max_concurrent: 100
+
+# Extra environment variables to set on the container.
+# Use this for secrets or overrides that should not be in the ConfigMap.
+extraEnv: []
+ # - name: OPENVIKING_CONFIG_FILE
+ # value: /app/ov.conf
+ # - name: SOME_SECRET
+ # valueFrom:
+ # secretKeyRef:
+ # name: my-secret
+ # key: api-key
+
+# Liveness and readiness probes.
+livenessProbe:
+ httpGet:
+ path: /health
+ port: http
+ initialDelaySeconds: 30
+ periodSeconds: 30
+ timeoutSeconds: 5
+ failureThreshold: 3
+
+readinessProbe:
+ httpGet:
+ path: /health
+ port: http
+ initialDelaySeconds: 15
+ periodSeconds: 10
+ timeoutSeconds: 5
+ failureThreshold: 3
+
+nodeSelector: {}
+tolerations: []
+affinity: {}