The chart in charts/kumoss deploys the same stack as
docker-compose.yml on Kubernetes: the proxy, the core, the IaC and
notifications sidecars, and the bundled backing services (two
PostgreSQL databases, Redis, RustFS object storage, Phoenix and
SearXNG). Every backing service can be switched off and replaced by an
external one.
Each release publishes the chart as an OCI artifact,
oci://ghcr.io/inditextech/charts/kumoss, with the same version as the
release; its Kumoss image tags default to that version. Install it
without a checkout:
helm upgrade --install kumoss oci://ghcr.io/inditextech/charts/kumoss \
--version <version> -n kumoss --create-namespace \
--set core.existingSecret=<secret with LLM / Git credentials>
The examples below use charts/kumoss from a checkout; the OCI
reference works in its place everywhere.
The chart does not make a deployment production-ready on its own. The decisions in Deploy to production still apply; this page covers only how the chart maps them to Kubernetes.
What the chart deploys
| Component | Kind | Notes |
|---|---|---|
|
Deployment + Service |
The single entry point, as in Compose: port 80 serves the SPA, |
|
Deployment (1 replica, |
Mounts |
|
Deployment (1 replica, |
Mounts the same |
|
Deployment |
Off by default: the service refuses to start without
|
|
StatefulSet ( |
Single instance each. Use a managed database or an operator in production. |
|
Deployment / StatefulSet |
Same images and settings as Compose. SearXNG runs the upstream image
with the repository’s |
The repository’s config.yaml, nginx/nginx.conf and
services/searxng/settings.yml are symlinked into charts/kumoss/files,
so the chart always ships what Compose ships. At render time the chart
replaces the Compose hostnames (core, iac, phoenix, …) with the
release’s Service names, then applies your config overrides on top.
Values that matter
| Value | Purpose |
|---|---|
|
URL the browser uses to reach the proxy. It becomes the core’s only
CORS origin ( |
|
URL the browser uses to reach the proxy’s port 9000. The core signs
artifact download links for this host ( |
|
Any |
|
Secret loaded whole into the core: LLM credentials (see
LLM providers and models),
|
|
Cloud provider credentials for plan and apply. |
|
Extra CA roots (PEM) trusted for outbound HTTPS by every pod that calls out: the core, the IaC and notifications sidecars, and SearXNG. Needed behind a TLS-inspecting proxy; see Behind a TLS-inspecting proxy. |
|
Service tokens and bundled-service passwords. Leave them blank: the
chart generates them on first install and reuses them on upgrade. If
the chart is rendered offline, see Rendering offline (Argo CD, Flux, |
|
The core and the IaC sidecar share this volume. With |
|
Replace a bundled backing service. |
|
The Kubernetes identity each of |
|
Off by default. Turning it on requires |
|
CPU and memory requests and limits. Empty by default; set them for production, and on clusters that require them (GKE Autopilot fills in its own defaults otherwise). |
|
On by default, as in Compose: the proxy serves the Phoenix UI under
|
|
With |
|
Optional Ingress in front of the proxy. |
<component>.extraEnv, extraVolumes and extraVolumeMounts cover
everything else.
Cloud credentials with workload identity
On a managed cluster, prefer workload identity over long-lived keys in Secrets: each pod runs as a Kubernetes ServiceAccount that the cloud maps to one of its identities, and the pod receives short-lived tokens automatically.
The chart creates one ServiceAccount per Kumoss component, so permissions stay separate. Two of them need cloud access:
-
core: the LLM provider (Vertex AI, Azure AI, Bedrock) and, withS3storage, the artifacts store: leave the static keys blank and the default AWS credential chain picks up the identity.STORAGE_ACCOUNTstorage does not use the pod identity; it still needsSTORAGE_ACCOUNT_KEY(for example incore.existingSecret), because the core signs download links with the account key. -
iac: the permissionsplanandapplyneed on the target infrastructure. This is the most privileged identity in the deployment; scope it accordingly.
Bind a ServiceAccount by annotating it (and, on AKS, labelling the pods):
# AKS — Azure Workload Identity. The webhook injects AZURE_* variables;
# the azurerm provider and import discovery read the ARM_* ones.
iac:
serviceAccount:
annotations:
azure.workload.identity/client-id: <managed-identity-client-id>
podLabels:
azure.workload.identity/use: "true"
env:
ARM_USE_AKS_WORKLOAD_IDENTITY: "true"
ARM_CLIENT_ID: <managed-identity-client-id>
ARM_TENANT_ID: <tenant-id>
# EKS — IRSA (EKS Pod Identity needs no annotation: associate the
# ServiceAccount with the role in EKS instead). The webhook injects the
# role and token; only the region is yours to set.
iac:
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::<account>:role/<role>
env:
AWS_REGION: <region>
# GKE — Workload Identity Federation, impersonating a service account.
# The provider finds the identity through the metadata server.
iac:
serviceAccount:
annotations:
iam.gke.io/gcp-service-account: <name>@<project>.iam.gserviceaccount.com
The per-cloud variables come from services/iac/PROVIDERS.md, which
lists every supported credential form.
The cloud side (the managed identity or role, its permissions, and the
trust that lets this ServiceAccount assume it) is set up outside the
chart. The trust is keyed on the namespace and ServiceAccount name:
<release>-kumoss-<component> by default (kumoss-iac for a release
named kumoss), or set serviceAccount.name. To use a ServiceAccount
you manage yourself, set serviceAccount.create: false and
serviceAccount.name.
Kumoss does not call the Kubernetes API, so the pods do not mount a
Kubernetes API token (serviceAccount.automount: false). The
workload-identity token is injected separately and is unaffected.
Rendering offline (Argo CD, Flux, helm template)
The chart reads its generated credentials back from the cluster with
Helm’s lookup, which only works when Helm talks to the cluster
(helm install / helm upgrade). Tools that render the chart offline
get nothing back, so every render would generate new passwords, and
the databases, initialised with the first ones, would reject them.
Manage that Secret yourself instead (with Sealed Secrets, External
Secrets, SOPS…) and set secrets.existingSecret to its name. The chart
then renders no credentials of its own. The Secret needs every key the
generated one has:
| Key | Value |
|---|---|
|
Bearer tokens between the core and the sidecars (any random string) |
|
Passwords the bundled databases are initialised with |
|
Connection URLs, e.g.
|
|
e.g. |
|
Credentials of the bundled object store |
|
SearXNG’s secret key (any random string) |
Keys for components you disabled can be omitted. Pods do not restart when this Secret changes; restart them after rotating it.
Try it on kind
kind runs a Kubernetes cluster as Docker
containers on your workstation. The steps below give a single-node
cluster whose host ports 80 and 9000 reach the proxy, so the browser
uses the same URLs as with Compose and the default publicUrl /
storagePublicUrl work unchanged. Run them from the repository root.
charts/kind-up.sh runs all of them in one idempotent command; re-run
it to upgrade. It reads the credentials from a Compose-style .env
(stripping the quotes kubectl --from-env-file would keep), and with
CA_DIR set it also does the TLS-inspecting
proxy steps:
ENV_FILE=core/.env charts/kind-up.sh
# Behind a TLS-inspecting proxy:
ENV_FILE=core/.env CA_DIR=/usr/local/share/ca-certificates charts/kind-up.sh
# Other host ports, or the published chart instead of the checkout:
HTTP_PORT=8080 STORAGE_PORT=9900 charts/kind-up.sh
CHART=oci://ghcr.io/inditextech/charts/kumoss CHART_VERSION=<version> charts/kind-up.sh
Its header lists every setting; arguments after them go to helm
upgrade --install. The manual steps:
-
Create the cluster. The port mappings forward host ports 80 and 9000 to the node ports the proxy is exposed on in step 4:
cat <<'EOF' | kind create cluster --name kumoss --config - kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane extraPortMappings: - { containerPort: 30080, hostPort: 80 } - { containerPort: 30900, hostPort: 9000 } EOF -
Make the images available. The chart’s image tags follow the chart version, so a chart from a release pulls that release’s images and nothing needs doing. To run your checkout instead, build the images you changed and load them into the node, which has its own image store:
docker build -f core/Dockerfile --build-context host-certs=docker/certs \ -t kumoss-core:dev . kind load docker-image kumoss-core:dev --name kumossThen point the component at it with
--set core.image.repository=kumoss-core,core.image.tag=dev,core.image.pullPolicy=Never. -
Store the LLM credentials the configured models need (here, the default Vertex AI models) and, optionally, the Git credentials:
kubectl create namespace kumoss kubectl -n kumoss create secret generic kumoss-credentials \ --from-literal=VERTEXAI_PROJECT=my-project \ --from-literal=VERTEXAI_LOCATION=europe-west1 \ --from-file=VERTEXAI_CREDENTIALS=./service-account.json \ --from-literal=GIT_USER=<user> \ --from-literal=GIT_TOKEN=<token> -
Install, exposing the proxy on the node ports mapped in step 1:
helm upgrade --install kumoss charts/kumoss -n kumoss \ --set proxy.service.type=NodePort \ --set proxy.service.nodePorts.http=30080 \ --set proxy.service.nodePorts.storage=30900 \ --set core.existingSecret=kumoss-credentials \ --wait --timeout 10m helm test kumoss -n kumoss -
Open
http://localhost. Phoenix is athttp://localhost/monitoring/.
Behind a TLS-inspecting proxy
The proxy re-signs HTTPS with a corporate root that neither the kind
node nor the images trust. Two things change, matching the
Compose
setup; charts/kind-up.sh does both when CA_DIR is set.
-
Image pulls. The node fails to pull with
x509: certificate signed by unknown authority(ImagePullBackOff). Pull the images on the host and copy them in, all in one archive. Save a single platform, becausekind load docker-imagefails on multi-platform images:images=$(helm template kumoss charts/kumoss | sed -n 's/^ *image: *"\{0,1\}\([^"]*\)"\{0,1\}$/\1/p' | sort -u) for i in $images; do docker pull -q "$i"; done docker save --platform linux/amd64 -o /tmp/kumoss-images.tar $images kind load image-archive /tmp/kumoss-images.tar --name kumossRender with the same
--setflags you install with: enablingnotificationsadds its image. The list includes thecurlimages/curlimagehelm testruns. -
Outbound HTTPS from the pods. Put your corporate roots (PEM) in a ConfigMap and point
caBundle.existingConfigMapat it:kubectl -n kumoss create configmap corporate-ca-roots \ --from-file=/usr/local/share/ca-certificates helm upgrade --install kumoss charts/kumoss -n kumoss ... \ --set caBundle.existingConfigMap=corporate-ca-rootsOr pass the certificates inline with
--set-file caBundle.certificates=corp-root.pemand the chart creates the ConfigMap. Every pod that calls out gets an init container that combines its image’s public roots with yours into one bundle, pointed at bySSL_CERT_FILE,REQUESTS_CA_BUNDLE,NODE_EXTRA_CA_CERTSandAWS_CA_BUNDLE. A file may hold several PEM certificates:Pod Outbound HTTPS coreLLM providers, Git hosts, web pages read by
web_search. The roots are also mounted atKUMOSS_CA_DIR, so the entrypoint imports them into Chromium’s store.iacThe OpenTofu registry and provider downloads (
tofu init). Without the roots, the pod starts and passes its probes, but every plan fails.notificationsSlack.
searxngThe search engines.
Pods do not restart when an
existingConfigMapchanges; restart them after editing it. Earlier versions of this guide mounted the roots throughcore.extraVolumesandsearxng.extraVolumes; remove those when switching tocaBundle.When building the core image, pass the same directory as the
host-certsbuild context instead ofdocker/certs.
Troubleshooting kind
kube-proxy crash-looping with too many open files, followed by
CoreDNS and the local-path-provisioner failing, means the host ran
out of inotify instances. Every kind node on the host shares the
per-user limit, so it shows up with several clusters. Raise it, and
persist it if your distribution reads /etc/sysctl.d:
sudo sysctl fs.inotify.max_user_instances=512
echo 'fs.inotify.max_user_instances=512' | sudo tee /etc/sysctl.d/99-kind.conf
Then delete the crashed pods so they restart immediately, for example
kubectl -n kube-system delete pod -l k8s-app=kube-proxy.
Upgrades and removal
-
config.yamlchanges roll the core automatically (the pod carries a checksum of the rendered file). Changes tosecrets.*, the external service URLs, or a component’ssecretEnvroll every pod that reads them the same way. A Secret you reference throughexistingSecretis managed outside the chart: after rotating it, restart its readers (kubectl rollout restart deploy/<release>-kumoss-core). The same goes forcaBundle.existingConfigMap; inlinecaBundle.certificatesroll the pods on change. -
Generated passwords and tokens are read back from the existing Secret on every upgrade. Changing a database password in values after the first install does not change it inside an initialised database.
-
helm uninstallkeeps the data: theworkspacesclaim, the StatefulSets' data claims, and the<release>-kumoss-internalSecret holding the passwords that data was initialised with (both carryhelm.sh/resource-policy: keep). Reinstalling the same release in the same namespace picks all three up again. To start from scratch, delete them explicitly:kubectl -n kumoss delete pvc -l app.kubernetes.io/instance=kumoss kubectl -n kumoss delete secret kumoss-internal