Kubernetes

The Helm chart runs a headless kabactl node as a Deployment with a persistent volume. A chart is published to the Forgejo helm registry for every release.

Install

helm repo add kaba https://git.djcas9.com/api/packages/kaba-labs/helm
helm repo update

helm upgrade --install kabactl kaba/kabactl \
  --namespace kaba --create-namespace \
  --version 0.87.5

Adding the repo with credentials, pinning versions, upgrading and uninstalling are covered under install & quick start. To install from a checkout instead, use the chart at deploy/helm/kabactl.

The image reference is assembled as <registry>/<repository>/<name>:<tag>, by default git.djcas9.com/kaba-labs/kabactl/kabactl; image.tag defaults to the chart’s app version.

Reach it from your machine:

kubectl -n kaba port-forward svc/kabactl 28832:28832
curl -k https://localhost:28832/health
kubectl -n kaba logs -l app.kubernetes.io/instance=kabactl -f

What the chart creates

Resource	Notes
Deployment	One replica, Recreate strategy.
PersistentVolumeClaim	20 Gi, ReadWriteOnce, mounted at /home/kaba/.config.
Service	ClusterIP on port 28832.
ServiceAccount
ConfigMap	Only when config is set.
Secret	Only when jwtSecret is set.
Certificate	Only with cert-manager enabled.
Ingress, HorizontalPodAutoscaler	Off by default.

The pod runs as UID and GID 10001, non-root, with all capabilities dropped, no privilege escalation and the runtime’s default seccomp profile.

One replica

kabactl keeps a local SQLite database and vector store on a ReadWriteOnce volume. Two pods on the same volume would corrupt it, which is why the strategy is Recreate and why you should leave replicaCount at 1 and autoscaling.enabled at false. To scale out, install the chart more than once and join the nodes into a cluster.

Values

Value	Default	Description
image.registry, image.repository, image.name, image.tag		Image reference.
image.pullPolicy	IfNotPresent
imagePullSecrets	[]	For a private registry.
args	[]	Overrides the container’s default server command arguments.
env, envFrom	[]	Extra environment.
config	""	Inline config.toml. See below.
service.type, service.port	ClusterIP, 28832
service.proxyEnabled, service.proxyPort	false, 28833	Also expose the SOCKS5 proxy.
ingress.*	disabled	Standard ingress settings.
persistence.enabled	true	false uses an emptyDir and loses all data on restart.
persistence.size, storageClass, accessModes, existingClaim	20Gi
resources	200m / 512Mi requests, 2 CPU / 4Gi limits	Raise the memory limit for inference.
certs.*		See certificates.
livenessProbe, readinessProbe, startupProbe	TCP on the API port	The startup probe allows 5 minutes.
nodeSelector, tolerations, affinity, priorityClassName		Scheduling.
terminationGracePeriodSeconds	30

Configuration

Set config to supply a whole config.toml:

config: |
  jwt_exp_time = 28800
  jwt_secret = "change-me"
  cert_path = "/home/kaba/.config/kaba/certs/kaba.cert"
  key_path = "/home/kaba/.config/kaba/certs/kaba.key"
  tls = true
  cert_format_version = 1

  [memory_options]
  memory_version_limit = 100
  memory_optimization_interval = 60

  [adblock_options]
  enabled = true
  blocklist_urls = ["https://easylist.to/easylist/easylist.txt"]

  [cluster_options]
  relays = ["https://relay.example.com"]

The file is mounted read-only over /home/kaba/.config/kaba/config.toml, and the pod restarts when it changes. Leave config empty and kabactl writes its own defaults onto the volume. All keys are described in the config reference.

The JWT secret override is not wired up

The chart can inject jwtSecret (or an existing Secret through jwtSecretFrom) into the pod as the environment variable KABA_JWT_SECRET. kabactl 0.87 does not read that variable, so setting these values has no effect. Until it does, set jwt_secret inside config, and keep that values file out of version control or supply it from a secret manager.

Certificates

By default kabactl generates a self-signed certificate on the volume. The chart offers two alternatives.

cert-manager

certs:
  create: true
  useCertManager: true
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  commonName: kabactl.example.com
  dnsNames:
    - kabactl.example.com

This creates a Certificate, and mounts the resulting tls.crt and tls.key at the paths kabactl expects.

An existing Secret

certs:
  existingSecret: my-kabactl-tls
  fileNames:
    cert: kaba.cert
    key: kaba.key
    trustBundle: trust-bundle.pem

The Secret must contain all three named keys. The trust bundle is a file the desktop client builds for its own use; kabactl does not need it, so it can be a copy of the certificate.

See certs for the format and for cert_format_version.

Ingress

kabactl serves HTTPS, so an ingress in front of it must speak HTTPS to the back end. With ingress-nginx:

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
  hosts:
    - host: kabactl.example.com
      paths:
        - path: /
          pathType: Prefix

Exposing the API publicly is rarely necessary. Other devices reach this node through the mesh, not through the ingress.

Join the cluster

kubectl -n kaba exec deploy/kabactl -- kabactl cluster join kaba_invite_…
kubectl -n kaba rollout restart deploy/kabactl

Or create an invite on this node for other devices to use:

kubectl -n kaba exec deploy/kabactl -- kabactl cluster invite --name laptop

GPU nodes

Request the GPU resource and schedule onto GPU nodes with the usual Kubernetes mechanisms, and use an image built with the matching back end:

resources:
  limits:
    nvidia.com/gpu: 1
    memory: 16Gi
nodeSelector:
  nvidia.com/gpu.present: "true"

Packaging the chart

From the kabactl repository:

make helm-lint
make helm-template
make helm-package     # stamps the chart with the current version
make helm-push        # pushes the chart to the registry