Skip to content

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

feat(examples): simplify k8s Helm chart to MVP (#234)

Zayn Jarvis5bb7709bef95
diff --git a/examples/k8s-helm/.helmignore b/examples/k8s-helm/.helmignore
new file mode 100644
index 000000000..0e8a0eb36
--- /dev/null
+++ b/examples/k8s-helm/.helmignore
@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/
diff --git a/examples/k8s-helm/Chart.yaml b/examples/k8s-helm/Chart.yaml
new file mode 100644
index 000000000..be7f6635b
--- /dev/null
+++ b/examples/k8s-helm/Chart.yaml
@@ -0,0 +1,17 @@
+apiVersion: v2
+name: openviking
+description: A Helm chart for OpenViking - RAG and semantic search via OpenViking Context Database MCP server
+type: application
+version: 0.1.0
+appVersion: "0.1.0"
+keywords:
+ - openviking
+ - rag
+ - semantic-search
+ - mcp
+ - knowledge-base
+home: https://github.com/volcengine/OpenViking
+sources:
+ - https://github.com/volcengine/OpenViking
+maintainers:
+ - name: OpenViking Contributors
diff --git a/examples/k8s-helm/README.md b/examples/k8s-helm/README.md
new file mode 100644
index 000000000..86479be91
--- /dev/null
+++ b/examples/k8s-helm/README.md
@@ -0,0 +1,272 @@
+# OpenViking Helm Chart
+
+This Helm chart deploys OpenViking on Kubernetes, providing a scalable and production-ready RAG (Retrieval-Augmented Generation) and semantic search service.
+
+## Overview
+
+[OpenViking](https://github.com/volcengine/OpenViking) is an open-source RAG and semantic search engine that serves as a Context Database MCP (Model Context Protocol) server. This Helm chart enables easy deployment on Kubernetes clusters with support for major cloud providers.
+
+## Prerequisites
+
+- Kubernetes 1.24+
+- Helm 3.8+
+- A valid Volcengine API key for embedding and VLM services
+
+## Installation
+
+### Add the Helm repository (when published)
+
+```bash
+helm repo add openviking https://volcengine.github.io/openviking
+helm repo update
+```
+
+### Install from local chart
+
+```bash
+# Clone the repository
+git clone https://github.com/volcengine/OpenViking.git
+cd OpenViking/deploy/helm
+
+# Install with default values
+helm install openviking ./openviking
+
+# Install with custom values
+helm install openviking ./openviking -f my-values.yaml
+```
+
+### Quick Start
+
+```bash
+# GCP deployment
+helm install openviking ./openviking \
+ --set cloudProvider=gcp \
+ --set openviking.config.embedding.dense.api_key=YOUR_API_KEY
+
+# AWS deployment
+helm install openviking ./openviking \
+ --set cloudProvider=aws \
+ --set openviking.config.embedding.dense.api_key=YOUR_API_KEY
+```
+
+## Configuration
+
+### Cloud Provider Support
+
+The chart supports automatic LoadBalancer annotation configuration for major cloud providers:
+
+| Provider | Configuration Value |
+|----------|-------------------|
+| Google Cloud Platform | `cloudProvider: gcp` |
+| Amazon Web Services | `cloudProvider: aws` |
+| Other/Generic | `cloudProvider: ""` (default) |
+
+### Key Configuration Options
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `cloudProvider` | Cloud provider for LoadBalancer annotations | `""` |
+| `replicaCount` | Number of replicas | `1` |
+| `image.repository` | Container image repository | `ghcr.io/astral-sh/uv` |
+| `image.tag` | Container image tag | `python3.12-bookworm` |
+| `service.type` | Kubernetes service type | `LoadBalancer` |
+| `service.port` | Service port | `1933` |
+| `openviking.config.server.api_key` | API key for authentication | `null` |
+| `openviking.config.embedding.dense.api_key` | Volcengine API key | `null` |
+
+### OpenViking Configuration
+
+All OpenViking configuration options from `ov.conf` are available under `openviking.config`. See `values.yaml` for the complete default configuration.
+
+### Embedding Configuration
+
+The embedding service requires a Volcengine API key:
+
+```yaml
+openviking:
+ config:
+ embedding:
+ dense:
+ api_key: "your-api-key-here"
+ api_base: "https://ark.cn-beijing.volces.com/api/v3"
+ model: "doubao-embedding-vision-250615"
+```
+
+### VLM Configuration
+
+For vision-language model support:
+
+```yaml
+openviking:
+ config:
+ vlm:
+ api_key: "your-api-key-here"
+ api_base: "https://ark.cn-beijing.volces.com/api/v3"
+ model: "doubao-seed-1-8-251228"
+```
+
+## Storage
+
+### Default (emptyDir)
+
+By default, the chart uses `emptyDir` volumes for data storage. This is suitable for development and testing but **data will be lost** when pods are restarted.
+
+### Persistent Storage (Optional)
+
+To enable persistent storage with PVC:
+
+```yaml
+openviking:
+ dataVolume:
+ enabled: true
+ usePVC: true
+ size: 50Gi
+ storageClassName: standard
+ accessModes:
+ - ReadWriteOnce
+```
+
+## Security
+
+### API Key Authentication
+
+Enable API key authentication to secure your OpenViking server:
+
+```yaml
+openviking:
+ config:
+ server:
+ api_key: "your-secure-api-key"
+ cors_origins:
+ - "https://your-domain.com"
+```
+
+### Secrets Management
+
+For production deployments, use Kubernetes secrets or external secret management:
+
+```bash
+# Create secret from literal
+kubectl create secret generic openviking-config \
+ --from-literal=ov.conf='{"server":{"api_key":"secret"}}'
+
+# Or mount existing secret
+helm install openviking ./openviking \
+ --set existingSecret=openviking-config
+```
+
+## Autoscaling
+
+Enable Horizontal Pod Autoscaler for production workloads:
+
+```yaml
+autoscaling:
+ enabled: true
+ minReplicas: 2
+ maxReplicas: 10
+ targetCPUUtilizationPercentage: 80
+ targetMemoryUtilizationPercentage: 80
+```
+
+## Resource Limits
+
+Default resource configuration:
+
+```yaml
+resources:
+ limits:
+ cpu: 2000m
+ memory: 4Gi
+ requests:
+ cpu: 500m
+ memory: 1Gi
+```
+
+Adjust based on your workload requirements.
+
+## Usage Examples
+
+### Connect with CLI
+
+```bash
+# Get the LoadBalancer IP
+export OPENVIKING_IP=$(kubectl get svc openviking -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
+
+# Create CLI configuration
+cat > ~/.openviking/ovcli.conf <<EOF
+{
+ "url": "http://$OPENVIKING_IP:1933",
+ "api_key": null,
+ "output": "table"
+}
+EOF
+
+# Test connection
+openviking health
+```
+
+### Python Client
+
+```python
+import openviking as ov
+
+# Get service endpoint
+# kubectl get svc openviking
+
+client = ov.OpenViking(url="http://<load-balancer-ip>:1933", api_key="your-key")
+client.initialize()
+
+# Add a resource
+client.add_resource(path="./document.pdf")
+client.wait_processed()
+
+# Search
+results = client.find("your search query")
+print(results)
+
+client.close()
+```
+
+## Troubleshooting
+
+### Pod fails to start
+
+Check the pod logs:
+```bash
+kubectl logs -l app.kubernetes.io/name=openviking
+```
+
+### Health check fails
+
+Verify the configuration:
+```bash
+kubectl get secret openviking-config -o jsonpath='{.data.ov\.conf}' | base64 -d
+```
+
+### LoadBalancer not getting IP
+
+Wait for the cloud provider to provision the load balancer:
+```bash
+kubectl get svc openviking -w
+```
+
+Check cloud provider-specific annotations in `values.yaml`.
+
+## Uninstallation
+
+```bash
+helm uninstall openviking
+```
+
+To remove persistent data (if PVC was enabled):
+```bash
+kubectl delete pvc openviking-data
+```
+
+## Contributing
+
+Contributions are welcome! Please see the [OpenViking repository](https://github.com/volcengine/OpenViking) for contribution guidelines.
+
+## License
+
+This Helm chart is licensed under the Apache License 2.0, matching the OpenViking project license.
diff --git a/examples/k8s-helm/templates/NOTES.txt b/examples/k8s-helm/templates/NOTES.txt
new file mode 100644
index 000000000..33d342d2f
--- /dev/null
+++ b/examples/k8s-helm/templates/NOTES.txt
@@ -0,0 +1,11 @@
+OpenViking has been deployed!
+
+Access the server via port-forward:
+
+ kubectl port-forward svc/{{ include "openviking.fullname" . }} 1933:{{ .Values.service.port }} -n {{ .Release.Namespace }}
+
+Then update your ovcli.conf to point to http://localhost:1933.
+
+Check health:
+
+ curl http://localhost:1933/health
diff --git a/examples/k8s-helm/templates/_helpers.tpl b/examples/k8s-helm/templates/_helpers.tpl
new file mode 100644
index 000000000..0408c6d33
--- /dev/null
+++ b/examples/k8s-helm/templates/_helpers.tpl
@@ -0,0 +1,45 @@
+{{/*
+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.
+*/}}
+{{- define "openviking.fullname" -}}
+{{- $name := .Chart.Name }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- 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 }}
diff --git a/examples/k8s-helm/templates/deployment.yaml b/examples/k8s-helm/templates/deployment.yaml
new file mode 100644
index 000000000..6adedee05
--- /dev/null
+++ b/examples/k8s-helm/templates/deployment.yaml
@@ -0,0 +1,58 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: {{ include "openviking.fullname" . }}
+ labels:
+ {{- include "openviking.labels" . | nindent 4 }}
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ {{- include "openviking.selectorLabels" . | nindent 6 }}
+ template:
+ metadata:
+ labels:
+ {{- include "openviking.labels" . | nindent 8 }}
+ annotations:
+ checksum/config: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}
+ spec:
+ containers:
+ - name: {{ .Chart.Name }}
+ image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+ imagePullPolicy: {{ .Values.image.pullPolicy }}
+ command:
+ - /bin/sh
+ - -c
+ - |
+ exec uv run --with openviking openviking serve \
+ --host {{ .Values.server.host }} \
+ --port {{ .Values.server.port }} \
+ --config /etc/openviking/ov.conf
+ ports:
+ - name: http
+ containerPort: {{ .Values.server.port }}
+ protocol: TCP
+ livenessProbe:
+ httpGet:
+ path: /health
+ port: http
+ initialDelaySeconds: 120
+ periodSeconds: 15
+ failureThreshold: 5
+ readinessProbe:
+ httpGet:
+ path: /health
+ port: http
+ initialDelaySeconds: 60
+ periodSeconds: 10
+ failureThreshold: 5
+ resources:
+ {{- toYaml .Values.resources | nindent 12 }}
+ volumeMounts:
+ - name: config
+ mountPath: /etc/openviking
+ readOnly: true
+ volumes:
+ - name: config
+ secret:
+ secretName: {{ include "openviking.fullname" . }}-config
diff --git a/examples/k8s-helm/templates/secret.yaml b/examples/k8s-helm/templates/secret.yaml
new file mode 100644
index 000000000..e188f010e
--- /dev/null
+++ b/examples/k8s-helm/templates/secret.yaml
@@ -0,0 +1,10 @@
+apiVersion: v1
+kind: Secret
+metadata:
+ name: {{ include "openviking.fullname" . }}-config
+ labels:
+ {{- include "openviking.labels" . | nindent 4 }}
+type: Opaque
+stringData:
+ ov.conf: |
+{{ toJson .Values.openviking.config | indent 4 }}
diff --git a/examples/k8s-helm/templates/service.yaml b/examples/k8s-helm/templates/service.yaml
new file mode 100644
index 000000000..d0fcb4791
--- /dev/null
+++ b/examples/k8s-helm/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/examples/k8s-helm/values.yaml b/examples/k8s-helm/values.yaml
new file mode 100644
index 000000000..722fa9907
--- /dev/null
+++ b/examples/k8s-helm/values.yaml
@@ -0,0 +1,37 @@
+image:
+ repository: ghcr.io/astral-sh/uv
+ pullPolicy: IfNotPresent
+ tag: "python3.12-bookworm"
+
+service:
+ type: ClusterIP
+ port: 1933
+
+resources:
+ limits:
+ cpu: 1000m
+ memory: 2Gi
+ requests:
+ cpu: 200m
+ memory: 512Mi
+
+server:
+ host: "0.0.0.0"
+ port: 1933
+
+# OpenViking confmap - only embedding and vlm are valid fields
+# Stored as a Secret and mounted into the container
+openviking:
+ config:
+ embedding:
+ dense:
+ model: "doubao-embedding-vision-250615"
+ api_key: null
+ api_base: "https://ark.cn-beijing.volces.com/api/v3"
+ dimension: "1024"
+ backend: "volcengine"
+ vlm:
+ model: "doubao-seed-1-8-251228"
+ api_key: null
+ api_base: "https://ark.cn-beijing.volces.com/api/v3"
+ backend: "volcengine"