WIP: feat: add Kubernetes Helm chart for OpenViking deployment

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/

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

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.

examples/k8s-helm/templates/NOTES.txt

@@ -0,0 +1,53 @@
+{{- if not .Values.openviking.config.embedding.dense.api_key -}}
+#####################################################################################
+### WARNING: No embedding API key configured!                                      ###
+#####################################################################################
+
+The OpenViking server is deployed but no embedding API key is configured.
+You need to update the secret with your Volcengine API key:
+
+  kubectl create secret generic {{ include "openviking.fullname" . }}-config \
+    --from-literal=ov.conf='{{ toJson .Values.openviking.config }}' \
+    --dry-run=client -o yaml | kubectl apply -f -
+
+Or use:
+
+  helm upgrade {{ .Release.Name }} openviking/openviking \
+    --set openviking.config.embedding.dense.api_key=YOUR_API_KEY
+
+{{- end }}
+
+OpenViking has been deployed!
+
+1. Get the application URL by running these commands:
+{{- if contains "LoadBalancer" .Values.service.type }}
+     NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+           You can watch the status by running:
+           kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "openviking.fullname" . }}
+
+  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "openviking.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
+  echo http://$SERVICE_IP:{{ .Values.service.port }}
+{{- else if contains "ClusterIP" .Values.service.type }}
+  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "openviking.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
+  export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
+  echo "Visit http://127.0.0.1:8080 to use your application"
+  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
+{{- end }}
+
+2. Check the health of your deployment:
+
+  kubectl get pods -n {{ .Release.Namespace }} -l app.kubernetes.io/name={{ include "openviking.name" . }}
+  curl http://$SERVICE_IP:{{ .Values.service.port }}/health
+
+3. To use the OpenViking CLI with your server:
+
+   Create an ovcli.conf file:
+   {
+     "url": "http://$SERVICE_IP:{{ .Values.service.port }}",
+     "api_key": null,
+     "output": "table"
+   }
+
+4. For more information:
+   - Documentation: https://github.com/volcengine/OpenViking
+   - Configuration: Check values.yaml for all available options