Kubernetes

Run KiwiFS in a cluster with persistent storage, config, secrets, and health probes.

KiwiFS runs on Kubernetes as a single-replica Deployment backed by a PersistentVolumeClaim. The project doesn’t ship a Helm chart, so this page gives plain manifests you can adapt.

Run exactly one KiwiFS pod per knowledge root. KiwiFS serializes writes inside one process and takes an exclusive lock on the data directory, so a second pod on the same volume fails to start.

Deployment, Service, and storage

kiwifs-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kiwifs
  labels:
    app: kiwifs
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: kiwifs
  template:
    metadata:
      labels:
        app: kiwifs
    spec:
      containers:
        - name: kiwifs
          image: ameliaanhlam/kiwifs:0.19.78
          args: ["serve", "--root", "/data", "--port", "3333", "--host", "0.0.0.0"]
          ports:
            - containerPort: 3333
              name: http
          volumeMounts:
            - name: knowledge
              mountPath: /data
          livenessProbe:
            httpGet:
              path: /healthz
              port: http
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /readyz
              port: http
            initialDelaySeconds: 3
            periodSeconds: 5
          resources:
            requests:
              memory: "128Mi"
              cpu: "100m"
            limits:
              memory: "512Mi"
              cpu: "1000m"
      volumes:
        - name: knowledge
          persistentVolumeClaim:
            claimName: kiwifs-data

Terminal

kubectl apply -f kiwifs-pvc.yaml -f kiwifs-deployment.yaml -f kiwifs-service.yaml

strategy: Recreate stops the old pod before starting the new one, so an upgrade never has two pods competing for the volume. On first start, KiwiFS initializes an empty volume as a new knowledge base.

The image runs as the non-root user kiwi. If the volume isn’t writable by that user, set securityContext.fsGroup on the pod to the user’s group ID, which docker run --rm --entrypoint id ameliaanhlam/kiwifs prints.

Configuration and secrets

Keep config.toml in a ConfigMap and secrets in a Secret. config.toml can read secrets from environment variables with ${VAR}, which you then fill from the Secret.

kiwifs-configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: kiwifs-config
data:
  config.toml: |
    [search]
    engine = "sqlite"

    [versioning]
    strategy = "git"
    async_commit = true
    batch_window_ms = 200
    batch_max_size = 50

    [auth]
    type = "apikey"
    api_key = "${KIWI_API_KEY}"

    [search.vector]
    enabled = true

    [search.vector.embedder]
    provider = "openai"
    model = "text-embedding-3-small"
    api_key = "${OPENAI_API_KEY}"

    [search.vector.store]
    provider = "pgvector"
    dsn = "${KIWI_PGVECTOR_DSN}"

Mount only the file, with subPath, so the rest of /data/.kiwi stays on the writable volume. Because the config file already exists, KiwiFS skips its first-start initialization, so run kiwifs init in an init container. It only creates files that are missing.

kiwifs-deployment.yaml (excerpt)

spec:
  template:
    spec:
      initContainers:
        - name: init
          image: ameliaanhlam/kiwifs:0.19.78
          args: ["init", "--root", "/data"]
          volumeMounts:
            - name: knowledge
              mountPath: /data
      containers:
        - name: kiwifs
          envFrom:
            - secretRef:
                name: kiwifs-secrets
          volumeMounts:
            - name: knowledge
              mountPath: /data
            - name: config
              mountPath: /data/.kiwi/config.toml
              subPath: config.toml
      volumes:
        - name: knowledge
          persistentVolumeClaim:
            claimName: kiwifs-data
        - name: config
          configMap:
            name: kiwifs-config

KiwiFS reads config.toml at startup. A subPath mount doesn’t pick up ConfigMap edits, so restart the Deployment after changing it with kubectl rollout restart deployment/kiwifs.

KiwiFS only reads a few environment variables directly: KIWI_BACKUP_REMOTE, KIWI_BACKUP_INTERVAL, KIWI_BACKUP_REBASE_BEFORE_PUSH, and KIWI_PUBLIC_URL. Everything else, including API keys, must be referenced from config.toml.

Health probes

Endpoint	Behavior	Use as
/health	Always 200 with {"status": "ok"}	Informational
/healthz	200 with status, uptime, and version while the process serves HTTP	livenessProbe
/readyz	200 when storage is reachable and every enabled protocol listener (NFS, S3, WebDAV) is up, otherwise 503	readinessProbe

Health endpoints don’t require authentication, even when auth is on.

NFS for other pods

KiwiFS includes a userspace NFSv3 server, so other pods can mount the knowledge base as a native volume. It doesn’t need privileged mode or kernel NFS support.

1. Enable NFS on the KiwiFS pod

   containers:
     - name: kiwifs
       args: ["serve", "--root", "/data", "--nfs", "--nfs-allow", "10.0.0.0/8"]
       ports:
         - containerPort: 3333
           name: http
         - containerPort: 2049
           name: nfs
   

   By default NFS accepts localhost only. Set --nfs-allow to the CIDRs your nodes mount from, since the kubelet performs the mount from the node.

2. Expose the NFS port

   kiwifs-nfs-service.yaml

   apiVersion: v1
   kind: Service
   metadata:
     name: kiwifs-nfs
   spec:
     selector:
       app: kiwifs
     ports:
       - port: 2049
         targetPort: nfs
         protocol: TCP
     type: ClusterIP
   
3. Mount it from another pod

   spec:
     volumes:
       - name: knowledge
         nfs:
           server: 10.96.12.34   # ClusterIP of kiwifs-nfs
           path: /
     containers:
       - name: app
         volumeMounts:
           - name: knowledge
             mountPath: /knowledge
             readOnly: true
   

   Nodes often can’t resolve cluster DNS names, so use the Service’s ClusterIP as server.

Mount NFS read-only in consumer pods and send writes through the REST API or MCP, so every change gets a commit and an index update.

See Alternate protocols for S3 and WebDAV, which you expose the same way on ports 3334 and 3335.

Multiple spaces

Serve several knowledge bases from one pod by mounting a volume per space and registering each with --space name=path.

containers:
  - name: kiwifs
    args:
      - "serve"
      - "--root=/data/default"
      - "--space=team=/data/team"
      - "--space=docs=/data/docs"
    volumeMounts:
      - name: default-data
        mountPath: /data/default
      - name: team-data
        mountPath: /data/team
      - name: docs-data
        mountPath: /data/docs

Each space has its own files, history, and search index, served under /api/kiwi/<name>/.... See Multi-space.

Ingress

kiwifs-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kiwifs
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "256m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
spec:
  rules:
    - host: kiwi.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: kiwifs
                port:
                  number: 3333
  tls:
    - hosts:
        - kiwi.example.com
      secretName: kiwifs-tls

Raise proxy-body-size for file uploads, which the import endpoint accepts up to 256 MB, and proxy-read-timeout for document exports, which can take up to five minutes. The web UI and API expect to be served from the root path.

Related

Docker

Image contents, environment variables, and Compose.

Backup sync

Push history to a git remote on a schedule.