> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budecosystem.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Helm Configuration
> Reference for configuring Bud-Stack via the bud Helm chart values
This page is a reference for configuring the **`bud`** Helm chart — the
platform application. It is the chart published at
`oci://registry.bud.studio/charts/bud` and sourced in this repo at
`infra/charts/bud/`.
**The chart does NOT bundle the databases.** Postgres, ClickHouse, Kafka,
MongoDB, Valkey and S3 (SeaweedFS/MinIO) are deployed **separately** — as
in-cluster addon charts (see the [Installation Guide](/developer-docs/installation))
or as managed services you already run (see the
[Deployment Guide](/developer-docs/deployment)). The `bud` chart only holds
**connection settings** for them, under `externalServices` (below). There are no
`postgresql.*` / `minio.*` / `kafka.*` / `clickhouse.*` subchart values.
**Source of truth.** Defaults drift between releases. For the authoritative,
version-exact list, dump the values from the chart you are installing:
```bash theme={null}
helm show values oci://registry.bud.studio/charts/bud --version 0.14.2
```
The tables below describe the most commonly-set keys; they are not exhaustive.
## How values are supplied
The chart is installed from the OCI registry, with your configuration layered on
top. Two files, merged in order (later overrides earlier):
| File | Purpose |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `values.yaml` | Your non-secret cluster config — ingress root, storage class/size, `externalServices.*` hosts. |
| `secrets.yaml` | Sensitive values — DB passwords, registry token, RSA keypair, Dapr crypto keys, OIDC client secrets, admin login. Keep out of version control (or SOPS-encrypt). |
```bash theme={null}
# direct helm install (Deployment Guide / managed-DB path)
helm install bud oci://registry.bud.studio/charts/bud --version 0.14.2 \
-n bud --create-namespace \
-f values.yaml -f secrets.yaml
```
Under ArgoCD (Installation Guide) the same two files are delivered to the chart
via a `$values` config-repo source instead of `-f` flags.
The chart ships two reference secret files, `secrets.bud.yaml` and
`secrets.demo.yaml` (`helm pull oci://registry.bud.studio/charts/bud --version
0.14.2 --untar` to get them). Both are **SOPS-encrypted** — values show as
`ENC[...]` — so they are not drop-in templates. Use `secrets.bud.yaml` to
see the full set of required key *paths*, then author your own `secrets.yaml`
with plaintext values (see the [Deployment Guide](/developer-docs/deployment)).
***
## Global Configuration
| Parameter | Description | Default |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `global.ingress.hosts.root` | Base public hostname. All service sub-hosts (`admin.`, `app.`, `gateway.`, `s3.`, …) derive from it via `_helpers.tpl`. | `bud.lan` |
| `global.ingress.hosts.` | Override an individual sub-host (e.g. `budadmin`, `budapp`, `budgateway`, `s3`, `mcpgateway`, `onyx`, `novuapi`, `novuws`). Empty = auto-derive from root. | `""` |
| `global.nodeSelector` | Node selector applied to all microservices (override per-service under `microservices..nodeSelector`). | `{}` |
| `global.affinity` | Affinity applied to all microservices. | `{}` |
| `registries.registry.bud.studio.username` / `.password` | Registry robot credentials; the chart creates the imagePullSecret every Deployment references. | `getmefrombud` |
| `imagePullSecrets` | Image pull secrets. | `[{name: registry.bud.studio}]` |
| `imagePullPolicy` | Pull policy for all containers. | `IfNotPresent` |
| `deploymentAnnotations` | Annotations applied to all deployments (e.g. Keel auto-update triggers). | `{}` |
| `appApiToken` | Dapr `APP_API_TOKEN` securing internal service-to-service endpoints. Empty = auto-generated. | `""` |
***
## Ingress Configuration
| Parameter | Description | Default |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `ingress.enabled` | Create Ingress resources. | `true` |
| `ingress.https` | TLS mode: `disabled` (plain HTTP), `internal` (cert-manager issues + Traefik terminates in-cluster), `external` (terminated upstream by an LB/WAF; no certs issued in-cluster). | `disabled` |
| `usecases.domain` | Set to enable wildcard ingress for use-cases (e.g. `usecases.bud.example.com`). Empty = disabled. | `""` |
Ingresses are pinned to `ingressClassName: traefik`. With `https: internal` the
chart annotates them `kubernetes.io/tls-acme: "true"`, resolved by cert-manager's
default ClusterIssuer (`letsencrypt-http01`, the HTTP-01 challenge — hosts
must be publicly reachable on :80).
***
## Storage Configuration
| Parameter | Description | Default |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `storage.budmodelRegistry.className` | StorageClass for the model-registry PVC. Empty = cluster default. | `""` |
| `storage.budmodelRegistry.size` | Model-registry PVC size. The small default is intentional — bumping it on upgrade triggers a PVC resize that fails on storage classes without `allowVolumeExpansion`. Set per-env (e.g. 300Gi for \~20B models). | `60Gi` |
| `storage.budmodelAddDir.className` / `.size` | Additional model directory. | `""` / `20Gi` |
| `storage.budevalDataset.className` / `.size` | Evaluation datasets (only used when `microservices.budeval.enabled`). | `""` / `32Gi` |
| `storage.budappStaticDir.className` / `.size` | budapp static files. | `""` / `20Gi` |
***
## External Services
Connection settings for the databases and object storage the platform consumes.
The in-cluster defaults point at the addon charts deployed by the Installation
Guide; override the hosts (and put passwords in `secrets.yaml`) for managed
services.
### PostgreSQL (`externalServices.postgresql`)
| Parameter | Description | Default |
| --------------------------------------------------- | ------------------------------- | ----------------------- |
| `.host` | Postgres host (pooler/primary). | `pooler-rw.postgres` |
| `.port` | Port. | `5432` |
| `.databases..name` / `.username` / `.password` | One block per service. | `` / `bud` / `bud` |
Databases (one per service): `budapp`, `budcluster`, `budmetrics`, `budmodel`,
`budsim`, `budeval`, `buddoc`, `budprompt`, `budask`, `budcodeinterpreter`,
`mcpgateway`, `budpipeline`, `onyx`.
### ClickHouse (`externalServices.clickhouse`)
| Parameter | Description | Default |
| ---------------------------------------------- | -------------------------------------------------- | ---------------------------------- |
| `.host` | ClickHouse host. | `clickhouse-clickhouse.clickhouse` |
| `.port` | Native protocol port. | `9000` |
| `.auth.username` / `.auth.password` | Credentials. | `bud` / `bud` |
| `.databases.budmetrics` | **Must stay `metrics`** — hardcoded in budmetrics. | `metrics` |
| `.databases.budeval` / `.databases.budgateway` | Per-service DBs. | `bud_eval` / `bud_gateway` |
### Valkey / Redis (`externalServices.valkey`)
| Parameter | Description | Default |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `.host` | Valkey host. | `valkey-master.valkey` |
| `.port` | Port. | `6379` |
| `.password` | Auth password. | `valkey` |
| `.databases.` | Logical DB index per consumer (`config_store`, `state_store`, `novu`, `budgateway`, `mcpgateway`, `budprompt`, `global`, `onyx`, `budcodeinterpreter`). | `3`–`11` |
### S3 / object storage (`externalServices.s3`)
Works with SeaweedFS (default), MinIO, AWS S3, or Azure Blob via an S3 gateway.
| Parameter | Description | Default |
| ------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
| `.endpoint` | S3 endpoint `host:port`. | `seaweed-s3.seaweedfs:8333` |
| `.secure` | Use HTTPS to the endpoint (independent of `ingress.https`). | `false` |
| `.auth.accessKey` / `.auth.secretKey` | Credentials. | `bud` / `bud` |
| `.buckets.modelRegistry` / `.modelInfo` / `.novu` | Bucket names (pre-create them). | `bud-models-registry` / `bud-model-info` / `bud-novu` |
### MongoDB (`externalServices.mongodb`)
| Parameter | Description | Default |
| ----------------------------------- | ----------------------- | --------------------------- |
| `.endpoint` | Mongo host `host:port`. | `mongodb-rs0.mongodb:27017` |
| `.auth.username` / `.auth.password` | Credentials. | `bud_novu` / `bud_novu` |
| `.databases.novu` | Novu database name. | `bud_novu` |
### Kafka (`externalServices.kafka`)
| Parameter | Description | Default |
| --------------------------------------- | ------------------------------ | -------------------------------- |
| `.endpoint` | Bootstrap brokers `host:port`. | `kafka-kafka-brokers.kafka:9092` |
| `.auth.username` / `.auth.password` | SASL credentials. | `bud` / `bud` |
| `.topics.pubsub` / `.topics.budgateway` | Topic names. | `bud_pubsub` / `bud_gateway` |
### OIDC (`externalServices.oidc`)
budapp validates ID tokens via OIDC discovery and stores authorization in its own
Postgres PDP; the IdP only issues tokens.
| Parameter | Description | Default |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `.url` | Canonical OIDC issuer. For Keycloak this is `https:///realms/bud-keycloak` — must match the keycloak chart's `ingress.host`. | `http://auth.bud.lan/realms/bud-keycloak` |
| `.clients.mcpgateway.id` / `.secret` | The mcpgateway OAuth client. | `mcp-gateway` / `mcp-gateway` |
The bundled Keycloak admin credentials live under the top-level `keycloak.auth`
block (`adminUser` / `adminPassword`), consulted only when you run the sibling
keycloak chart. They are **not** budapp's issuer config — that is
`externalServices.oidc.url`.
***
## Microservices
Every backend/frontend service lives under `microservices.` with at least
`enabled`, `image`, and (for backends) `daprid`. Images default to
`registry.bud.studio/runtime/:`, where `` is the
chart's appVersion (`0.14.2` at the time of writing) — except where noted
(`mcpgateway` and `budsentinel` track different tags). Backend pods run a Dapr
sidecar (expect `2/2 READY`).
| Service | Image tag | Enabled | Notes |
| -------------------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `budapp` | `` | `true` | Main API: users, projects, models, endpoints, auth/redirect-flow. |
| `budadmin` | `` | `true` | Next.js dashboard. `env.NEXT_PUBLIC_*` for logo/favicon/dev-mode (build-time). |
| `budcustomer` | `` | `true` | Customer portal. |
| `budplayground` | `` | `true` | Model playground. |
| `budgateway` | `` | `true` | Rust inference gateway. |
| `budcluster` | `` | `true` | Cluster lifecycle. Holds `registerDefaultCluster` (auto-registers the in-cluster as default). |
| `budmodel` | `` | `true` | Model registry / leaderboard. |
| `budmetrics` | `` | `true` | Observability (ClickHouse). DB hardcoded to `metrics`. |
| `budsim` | `` | `true` | Performance simulation. |
| `budnotify` | `` | `true` | Notifications / pub-sub (Novu wrapper). |
| `askbud` | `` | `true` | Cluster/perf AI assistant. |
| `buddoc` | `` | `true` | Document processing. |
| `budeval` | `` | `false` | Model evaluation; **disabled by default**. Enabling it provisions a `WaitForFirstConsumer` dataset PVC (stays `Pending` until a workload binds it), so leave it off unless you run evals. |
| `budprompt` | `` | `true` | Prompt management. |
| `budpipeline` | `` | `true` | Pipeline orchestration. |
| `budcodeinterpreter` | `` | `true` | Code interpreter. |
| `mcpgateway` | `latest` | `true` | MCP gateway. |
| `budsentinel` | `nightly` | `true` | Sentinel. |
| `semanticRouter` | `` | `true` | Semantic router (embedding + intent classification for request routing). Image repo is `semantic-router`. |
Image tags above are the chart's published defaults; per-environment overlays
(e.g. dev) pin services to `:nightly` and may toggle `enabled`. Always confirm
against `helm show values` for the exact release.
***
## OpenTelemetry Collector
| Parameter | Description | Default |
| ------------------------------------------- | -------------------------- | -------------------------------------------------- |
| `otelCollector.enabled` | Deploy the collector. | `true` |
| `otelCollector.image.repository` / `.tag` | Collector image. | `otel/opentelemetry-collector-contrib` / `0.151.0` |
| `otelCollector.replicas` | Replicas. | `1` |
| `otelCollector.batchSize` / `.batchTimeout` | Export batching. | `10000` / `10s` |
| `otelCollector.resources.limits.memory` | Memory limit. | `1Gi` |
| `otelCollector.clickhouse.database` | Target ClickHouse DB. | `metrics` |
| `otelCollector.clickhouse.ttl` | Raw OTel metric retention. | `720h` (30 days) |
***
## Onyx (optional)
AI knowledge assistant; disabled by default.
| Parameter | Description | Default |
| ------------------------------------------------------- | ---------------------- | -------------- |
| `onyx.enabled` | Deploy Onyx. | `false` |
| `onyx.configMap.AUTH_TYPE` | Auth type. | `oidc` |
| `onyx.configMap.KEYCLOAK_REALM` | Keycloak realm. | `bud-keycloak` |
| `onyx.vespa.enabled` / `.replicaCount` | Vespa search backend. | `true` / `1` |
| `onyx.webserver.replicaCount` / `onyx.api.replicaCount` | Onyx web/API replicas. | `1` / `1` |
Onyx reuses the platform's Postgres/Valkey/S3 via `externalServices` — its
own bundled `postgresql`/`valkey`/`minio`/`nginx` stay disabled.
***
## Dapr
Dapr is **not** bundled; install it cluster-wide before deploying Bud-Stack.
```bash theme={null}
dapr init -k
# or:
helm repo add dapr https://dapr.github.io/helm-charts/
helm install dapr dapr/dapr -n dapr-system --create-namespace
```
`daprExtra.crypto.symmetricKey` / `.asymmetricKey` hold the Dapr crypto-component
keys used for cluster-credential encryption — **generate your own** (see
the [Deployment Guide](/developer-docs/deployment#per-service-secrets-you-must-change)).
***
## Secrets Management (SOPS)
For GitOps, keep `secrets.yaml` encrypted with SOPS + age.
```bash theme={null}
# generate a key
age-keygen -o ~/.config/sops/age/keys.txt
grep -Eom1 "age1.*$" ~/.config/sops/age/keys.txt # public key
# encrypt / edit
sops --encrypt --age secrets.yaml > secrets.enc.yaml
sops secrets.enc.yaml
# decrypt at deploy time
sops -d secrets.enc.yaml | \
helm upgrade --install bud oci://registry.bud.studio/charts/bud --version 0.14.2 \
-f values.yaml -f - -n bud
```
***
## Related Documentation
Full in-cluster install with bundled dependency charts (ArgoCD).
Install against managed/external databases; per-service secret reference.