Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(examples): simplify k8s Helm chart to MVP (#234)
Zayn Jarvis5bb7709bef95
diff --git a/examples/k8s-helm/.helmignore b/examples/k8s-helm/.helmignorenew file mode 100644index 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.yamlnew file mode 100644index 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 Contributorsdiff --git a/examples/k8s-helm/README.md b/examples/k8s-helm/README.mdnew file mode 100644index 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.txtnew file mode 100644index 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/healthdiff --git a/examples/k8s-helm/templates/_helpers.tpl b/examples/k8s-helm/templates/_helpers.tplnew file mode 100644index 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.yamlnew file mode 100644index 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" . }}-configdiff --git a/examples/k8s-helm/templates/secret.yaml b/examples/k8s-helm/templates/secret.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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.yamlnew file mode 100644index 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"