Values reference
This page lists the Helm values of the two Foundation4 charts and of the included charts, grouped by component, with type, default and effect. Keys that are unused or need care are marked. Operators who write the values file of a deployment need this page. Configuration reference describes the configuration that the values produce inside the containers.
Releases and values files
Foundation4 installs as two Helm releases in the namespace foundation4ai, and both releases read the same values file:
| Release | Chart | Top-level keys read |
|---|---|---|
foundation4ai-core | foundation4ai-core 1.1.0 | global, postgres, redis, nats, prometheus |
foundation4ai | foundation4ai 1.1.0 | global, api-server, dashboard, ingress, httpRoute |
Each release ignores the keys of the other release. The procedures of the Deploy and operate pages pass foundation4ai.values.yaml, the production values file that Install on Kubernetes creates; an evaluation installation passes evaluation.values.yaml in the same commands. Both releases keep the names above and share one namespace. The application chart mounts the Secret of the core release named in api-server.secret, foundation4ai-core by default. The cache and the NATS servers read the Secrets foundation4ai-core-redis and foundation4ai-core-nats-auth, named in redis.auth.usersExistingSecret and in the NATS authorization volume of nats.podTemplate.patch. A core release with another name needs these three values changed to the Secret names of that release.
The core chart includes four charts: PostgreSQL 1.6.1 (key postgres), Valkey 0.9.3 as the Redis-compatible cache (key redis), NATS 2.12.4 (key nats) and Prometheus 28.9.1 (key prometheus). The application chart includes the api-server and dashboard charts. The following commands print the defaults of a chart and the values of an installed release:
helm show values ./charts/foundation4ai-core
helm show values ./charts/foundation4ai-core/charts/nats-2.12.4.tgz
helm get values foundation4ai -n foundation4ai
Expected result: the first two commands print the default values of the chart, and the last prints the values that the operator supplied to the release.
Profiles
The following values differ between the two deployment profiles. Install for evaluation uses the evaluation profile, and Install on Kubernetes describes the production profile.
| Key | Evaluation | Production |
|---|---|---|
postgres.enabled | true, bundled PostgreSQL on a volume claim of 8Gi | false, external PostgreSQL through POSTGRES_URL |
api-server.replicaCount.worker | 1 | Default 3 or more |
api-server.resources, or the resources of api-server.server, worker, grpc and jobs | Not set | Requests and limits set |
| Image repositories | A registry, or images loaded onto the node | An internal registry or mirror, through global.foundation4aiImageRegistry or the repository values |
ingress or httpRoute | Optional | Enabled, with TLS |
| Storage classes | Default StorageClass | Set for NATS JetStream and Prometheus |
Global values
| Key | Type | Default | Effect |
|---|---|---|---|
global.serverImageTag | String | "" | Tag of the API server image, used by the API server, workers and hook Jobs. Required: without this tag or api-server.image.tag, the render fails with set global.serverImageTag (or api-server.image.tag) to the API server image tag. |
global.grpcImageTag | String | "" | Tag of the gRPC service image. Required: without this tag or api-server.image.tagGrpc, the render fails with set global.grpcImageTag (or api-server.image.tagGrpc) to the gRPC sidecar image tag. |
global.dashboardImageTag | String | "" | Tag of the dashboard image. Required when the dashboard is enabled: without this tag or dashboard.image.tag, the render fails with set global.dashboardImageTag (or dashboard.image.tag) to the dashboard image tag. |
global.foundation4aiImageRegistry | String | "" | Registry of the API server, gRPC service and dashboard images, such as registry.example.com/foundation4ai. The value replaces the registry host of api-server.image.repository, api-server.image.repositoryGrpc and dashboard.image.repository. Model, package and core release images keep their own values. |
global.imagePullSecrets | List | [] | Pull secrets. The Foundation4 charts read plain names or name entries; Valkey reads plain names only, so a values file that serves both releases lists plain names. |
global.image.registry, global.image.pullSecretNames | String, list of names | None, [] | Registry prefix and pull secrets of the NATS images |
global.imageRegistry | String | "" | Registry prefix of the Valkey image |
global.natsReplicas | Integer | 3 | Copies that NATS JetStream keeps of the document queue and the document text store, written to nats.replicas of the API server configuration. At most the number of NATS servers: 3 for the bundled cluster, 1 for a single external server. |
global.secrets.existingSecret | String | foundation4ai-secrets | Secret that the core release reads to build the addresses, and from which the application chart mounts the license, the application secret and the master key |
The core release reads the following key names in foundation4ai-secrets:
| Key | Default | Read when |
|---|---|---|
global.secrets.postgresUrlKey | POSTGRES_URL | postgres.enabled is false |
global.secrets.postgresUserKey | POSTGRES_USER | postgres.enabled is true |
global.secrets.postgresUserPasswordKey | POSTGRES_PASSWORD | postgres.enabled is true |
global.secrets.postgresDatabaseKey | POSTGRES_DATABASE | postgres.enabled is true |
global.secrets.redisUrlKey | REDIS_URL | redis.enabled is false |
global.secrets.redisPasswordKey | REDIS_PASSWORD | redis.enabled is true |
global.secrets.natsUser, global.secrets.natsPasswordKey | foundation4ai, NATS_PASSWORD | nats.enabled is true. The user name is a value, and the password is the Secret key. |
global.secrets.natsUrlKey | NATS_URL | nats.enabled is false |
global.secrets.prometheusUrlKey | PROMETHEUS_URL | prometheus.enabled is false; optional |
The PostgreSQL chart reads the superuser password itself, from postgres.settings.superuserPassword.secretKey. The application chart mounts the keys FOUNDATION4AI_APP_LICENSE, FOUNDATION4AI_APP_SECRET, FOUNDATION4AI_APP_MASTER_KEY and FOUNDATION4AI_APP_MASTER_SECRET from the Secret named in global.secrets.existingSecret. The charts generate no credential and take no credential as a value: every credential comes from foundation4ai-secrets, as described in Secrets and keys.
Core chart dependencies
| Key | Default | Effect when false |
|---|---|---|
postgres.enabled | false | The database URL comes from POSTGRES_URL |
redis.enabled | true | The cache URL comes from REDIS_URL |
nats.enabled | true | The NATS JetStream URL comes from NATS_URL |
prometheus.enabled | true | The address of the Prometheus server comes from PROMETHEUS_URL, an optional key. Without the key, the API server queries http://prometheus:9090. |
A required key that is missing or empty in foundation4ai-secrets stops the core release at render time with the message Set <key> in the foundation4ai-secrets Secret: <reason>, where the reason names the setting that needs the key. The core release reads foundation4ai-secrets from the cluster with the Helm lookup function, so helm template, a client-side dry run and GitOps tools that render offline stop with a message that starts with The Secret foundation4ai-secrets was not found in namespace. helm install, helm upgrade and --dry-run=server render the core release.
PostgreSQL
The bundled PostgreSQL serves the evaluation profile only. Database describes the external database of the production profile.
| Key | Default | Effect |
|---|---|---|
postgres.image.repository, postgres.image.tag | tensorchord/vchord-suite, pg18-20260501 | PostgreSQL 18 with the vector, vchord, pg_tokenizer and vchord_bm25 extensions |
postgres.image.registry | Docker Hub (PostgreSQL chart default) | Registry of the image |
postgres.settings.dataDir | /var/lib/postgresql/18/docker | Data directory of the image |
postgres.settings.existingSecret, postgres.settings.superuserPassword.secretKey | foundation4ai-secrets, POSTGRES_SUPERUSER_PASSWORD | Superuser password |
postgres.userDatabase.* | foundation4ai-secrets, keys POSTGRES_DATABASE, POSTGRES_USER, POSTGRES_PASSWORD | Application database and user |
postgres.customScripts.01-init-extension.sql | Creates the extensions and the bert tokenizer | Runs once as the superuser in the application database, when the data directory is first initialized. Creates the vector, vchord, pg_tokenizer and vchord_bm25 extensions and the bert tokenizer, and grants read access to the bm25_catalog and tokenizer_catalog schemas. The script grants no write access to tokenizer_catalog, which BM25 indexes need, so a superuser runs the grants of Bundled PostgreSQL once. |
postgres.storage.requestedSize, postgres.storage.className | 8Gi, not set | A volume claim of each PostgreSQL pod, which keeps the data when the pod is rescheduled. Without a class name, the default StorageClass applies. |
postgres.imagePullSecrets | [] | List of name entries |
postgres.resources | {} | No requests or limits |
Redis-compatible cache (Valkey)
| Key | Default | Effect |
|---|---|---|
redis.auth.enabled | true | Password authentication |
redis.auth.usersExistingSecret | foundation4ai-core-redis | Secret that the core chart creates from REDIS_PASSWORD, with the key default |
redis.auth.aclUsers.default.permissions | ~* &* +@all | Permissions of the default user |
redis.image.repository | valkey/valkey | Image; the tag defaults to the chart application version, 9.0.1 |
redis.dataStorage.enabled | false | Cache content lives in memory and is lost when the pod restarts |
redis.imagePullSecrets | [] | List of names |
redis.resources | {} | No requests or limits |
helm test of the core release runs the pod foundation4ai-core-redis-test-auth-existing of the Valkey chart. The test pod takes no pull secrets and pulls redis.image.repository without redis.image.registry or global.imageRegistry. With a mirrored registry, redis.image.repository holds the full path in the mirror, redis.image.registry is empty, and the namespace default ServiceAccount carries the pull secret.
NATS JetStream
| Key | Default | Effect |
|---|---|---|
nats.config.cluster.enabled, nats.config.cluster.replicas | true, 3 | 3 NATS servers in a StatefulSet |
nats.config.jetstream.enabled | true | JetStream persistence, required by Foundation4 |
nats.config.merge, nats.container.patch, nats.podTemplate.patch | Include and mount of the Secret foundation4ai-core-nats-auth | Client authentication. The core chart writes the user global.secrets.natsUser and the password NATS_PASSWORD into the Secret, and the configuration reloader applies a changed password without a restart of the NATS servers. |
nats.config.nats.tls.enabled, nats.config.nats.tls.secretName | false, not set | TLS for client connections, with a Secret that holds tls.crt, tls.key and ca.crt. With TLS, the core chart writes a tls:// URL, and the application chart names the same Secret in api-server.natsCaSecret. |
nats.config.cluster.tls | Not set | TLS between the NATS servers, configured as the commented example in the values file of the core chart shows |
nats.config.jetstream.fileStore.pvc.size | 10Gi | Volume claim of each server |
nats.config.jetstream.fileStore.pvc.storageClassName | Not set | The default StorageClass applies |
nats.container.resources | {} | No requests or limits |
nats.podDisruptionBudget.enabled | true | A PodDisruptionBudget for the NATS servers |
nats.natsBox.enabled | true | The utility Deployment foundation4ai-core-nats-box, which carries the nats command-line tool |
nats.promExporter.enabled | false | Prometheus exporter for NATS server and JetStream metrics |
nats.container.image, nats.reloader.image, nats.natsBox.container.image | nats 2.12.4-alpine, natsio/nats-server-config-reloader 0.21.1, natsio/nats-box 0.19.3 | Images |
Prometheus
| Key | Default | Effect |
|---|---|---|
prometheus.alertmanager.enabled, prometheus.kube-state-metrics.enabled, prometheus.prometheus-node-exporter.enabled, prometheus.prometheus-pushgateway.enabled | false | Only the Prometheus server is installed |
prometheus.server.ingress.enabled | false | No external access to Prometheus |
prometheus.scrapeConfigs | Every default job with enabled: false | Turns off the default jobs of the Prometheus chart |
prometheus.serverFiles.prometheus.yml.scrape_configs | Job foundation4ai-pods | Scrapes pods annotated prometheus.io/app: foundation4ai and prometheus.io/scrape: "true" every 10 seconds, with a timeout of 2 seconds, at the path and port of the pod annotations: /metrics on port 9090 for the API server and the workers |
prometheus.extraScrapeConfigs | "" | Further jobs, as YAML text |
prometheus.server.persistentVolume.size, prometheus.server.persistentVolume.storageClass | 8Gi, not set | Metrics volume |
prometheus.server.retention | 15d | Metrics retention |
prometheus.server.resources | {} | No requests or limits |
prometheus.imagePullSecrets | [] | List of name entries |
Monitoring and logging describes the scrape job and the metrics.
API server and workers
The api-server chart creates the API server Deployment foundation4ai-api-server, the worker Deployment foundation4ai-api-server-worker, the Service foundation4ai-api-server, the ServiceAccount foundation4ai-api-server, the hook ConfigMap and Secret foundation4ai-api-server and three hook Jobs. Each API server and worker pod runs the Foundation4 container, server or worker, and a grpc container with the gRPC service.
| Key | Type | Default | Effect |
|---|---|---|---|
api-server.enabled | Boolean | true | Installs the chart |
api-server.secret | String | foundation4ai-core | Secret of the core release, in the same namespace, whose addresses every pod mounts under /app/config/secrets |
api-server.replicaCount.server | Integer | 1 | API server replicas, when autoscaling is off |
api-server.replicaCount.worker | Integer | 3 | Worker replicas, when autoscaling is off |
api-server.image.repository | String | The provider's registry | API server image, also used by the workers and hook Jobs |
api-server.image.repositoryGrpc | String | The provider's registry | gRPC service image |
api-server.image.pullPolicy | String | IfNotPresent | Pull policy of both images |
api-server.image.tag, api-server.image.tagGrpc | String | "" | Tags that take precedence over global.serverImageTag and global.grpcImageTag |
api-server.imagePullSecrets | List | [] | Pull secrets of every pod of the chart, including the hook Jobs, together with global.imagePullSecrets and the pull secrets of each model and package image. Entries are plain names or name entries. |
api-server.serviceAccount.create, automount, annotations, name | Mixed | true, true, {}, "" | ServiceAccount of the API server and worker pods. The hook Jobs use the namespace default ServiceAccount, because at installation the hooks run before the chart creates its own. |
api-server.podAnnotations | Map | {} | Added to the API server and worker pods, next to the fixed Prometheus and checksum annotations |
api-server.podLabels | Map | {} | Added to the API server and worker pods |
api-server.podSecurityContext | Map | runAsNonRoot: true, user and group 10001, fsGroup: 10001, seccompProfile RuntimeDefault | Pod security context of the API server, worker and hook Job pods. The images run as the user 10001, and the defaults of this key and of api-server.securityContext meet the restricted Pod Security level. |
api-server.securityContext | Map | allowPrivilegeEscalation: false, all capabilities dropped | Security context of every container, unless server, worker, grpc or jobs sets its own |
api-server.server.securityContext, worker.securityContext, grpc.securityContext, jobs.securityContext | Map | {} | Security context of the server container, the worker container, both grpc containers and the hook Job containers |
api-server.service.type, api-server.service.port | String, integer | ClusterIP, 80 | Service of the API server, which targets container port 8000 |
api-server.resources | Map | {} | Requests and limits of every container, unless server, worker, grpc or jobs sets its own |
api-server.server.resources, worker.resources, grpc.resources, jobs.resources | Map | {} | Requests and limits of the server container, the worker container, both grpc containers and the hook Job containers |
api-server.server.startupProbe | Map | GET / on port 8000 every 10 seconds, failureThreshold: 30, timeoutSeconds: 5 | Startup probe of the server container, which holds back the liveness probe for up to 5 minutes while the API server waits for the database, the cache and the queue. null removes the probe. |
api-server.priorityClassName | String | "" | Priority class of the API server and worker pods. Empty uses the cluster default. |
api-server.podDisruptionBudget.server, api-server.podDisruptionBudget.worker | Map | {} | Specification of a PodDisruptionBudget without the selector, such as maxUnavailable: 1. Empty creates none. |
api-server.autoscaling.server.* | Map | enabled: false, minReplicas: 1, maxReplicas: 100, targetCPUUtilizationPercentage: 80 | HorizontalPodAutoscaler of the API server. targetMemoryUtilizationPercentage adds a memory target. |
api-server.autoscaling.worker.* | Map | enabled: false, minReplicas: 3, maxReplicas: 100, targetCPUUtilizationPercentage: 80 | HorizontalPodAutoscaler of the workers |
api-server.nodeSelector, tolerations, affinity | Map, list, map | Empty | Scheduling of the API server, worker and hook Job pods |
api-server.volumes, api-server.volumeMounts | List | [] | Extra volumes of the API server and worker pods, mounted in the server and worker containers |
api-server.configs | Map of strings | {} | Entries of the ConfigMap, mounted in /app/config and loaded as environment variables of the server and worker containers |
api-server.secrets | Map of strings | {} | Entries of the Secret, mounted in /app/config |
api-server.secretsAnnotations | Map | {} | Annotations of the Secret foundation4ai-api-server |
api-server.models, api-server.packages | List | [] | Model and package images, as described in Models, packages and air-gapped installs |
api-server.corsAllowedOrigins | List | [] | Browser origins allowed to call the API from another site, written to app.cors_allowed_origins. The dashboard calls the API from the same origin and needs no entry. |
api-server.allowPrivateEndpoints | Boolean | true | Accepts LLM and embedding provider addresses on private, loopback and link-local networks, written to app.allow_private_endpoints and passed to the gRPC service. false accepts public addresses only. |
api-server.fastembedInstances | Integer | 2 | Most copies of each FastEmbed model that one API server or worker process loads, written to app.fastembed_instances |
api-server.grpcExtraEnv | List | [] | Extra environment variables of both grpc containers, as Kubernetes env entries, such as HF_HUB_OFFLINE or TIKTOKEN_CACHE_DIR |
api-server.huggingfaceCache.enabled, api-server.huggingfaceCache.path | Boolean, string | true, /cache/huggingface | A writable emptyDir volume at the path in the server, worker and grpc containers, and paths.huggingface set to the path through FOUNDATION4AI__PATHS__HUGGINGFACE. The API server and the workers download the Hugging Face tokenizers of BM25 indexes into the directory. The chart skips the volume when a model image is mounted at /data/huggingface. |
api-server.natsCaSecret, api-server.natsCaKey | String | "", ca.crt | Secret and key of the certificate authority of the NATS server certificate, mounted as /app/config/nats-ca.crt. With a Secret, the API server, workers and hook Jobs require TLS to NATS JetStream. |
api-server.nameOverride, api-server.fullnameOverride | String | "" | Change object names. The ingress and the HTTPRoute assume the default names, so a deployment leaves both empty. |
Configuration reference describes how the chart delivers the configuration to the containers.
Dashboard
| Key | Type | Default | Effect |
|---|---|---|---|
dashboard.enabled | Boolean | true | Installs the dashboard Deployment and Service foundation4ai-dashboard, container port 3000 |
dashboard.replicaCount | Integer | 1 | Dashboard replicas |
dashboard.image.repository, pullPolicy, tag | String | The provider's registry, IfNotPresent, "" | Dashboard image; the tag falls back to global.dashboardImageTag |
dashboard.imagePullSecrets | List | [] | Pull secrets of the dashboard pods, together with global.imagePullSecrets. Entries are plain names or name entries. |
dashboard.serviceAccount.*, podAnnotations, podLabels | Mixed | Chart defaults | Standard pod settings |
dashboard.podSecurityContext, dashboard.securityContext | Map | {} | Pod and container security context. The chart sets none by default, so a namespace with the restricted Pod Security level needs both values. |
dashboard.service.type, dashboard.service.port | String, integer | ClusterIP, 80 | Service of the dashboard |
dashboard.resources | Map | {} | Requests and limits of the dashboard container |
dashboard.livenessProbe, dashboard.readinessProbe | Map | {} | Probes of the dashboard container, none by default. The dashboard answers under /dashboard/, so an HTTP probe uses that path on the port http. |
dashboard.priorityClassName | String | "" | Priority class of the dashboard pods |
dashboard.podDisruptionBudget | Map | {} | Specification of a PodDisruptionBudget without the selector. Empty creates none. |
dashboard.volumes, volumeMounts, nodeSelector, tolerations, affinity | Mixed | Empty | Standard pod settings |
Ingress and HTTPRoute
| Key | Default | Effect |
|---|---|---|
ingress.enabled | false | Creates the Ingress foundation4ai |
ingress.className | "" | Ingress class |
ingress.annotations | {} | Annotations of the Ingress |
ingress.hosts[].host | chart-example.local | Host names. Each host routes /dashboard to the dashboard, when the dashboard is enabled, and / to the API server. hosts[].paths is not read. |
ingress.tls | [] | TLS entries with secretName and hosts |
httpRoute.enabled | false | Creates the Gateway API HTTPRoute foundation4ai |
httpRoute.annotations | {} | Annotations of the HTTPRoute |
httpRoute.parentRefs | name: gateway, sectionName: http | Gateway and listener |
httpRoute.hostnames | chart-example.local | Host names |
The HTTPRoute sends /dashboard to the dashboard, when the dashboard is enabled, and every other path, including /, to the API server, as the Ingress does. API and dashboard access describes both options.
Keys that need care
- Image tags. The charts have no default image tags. The operator sets
global.serverImageTag,global.grpcImageTagandglobal.dashboardImageTag, or the tags of each chart, to the tags of the release, and the render fails without them. - Pull secrets. Valkey reads
global.imagePullSecretsas plain names, and the Foundation4 charts accept plain names in the same list, so a values file that serves both releases lists plain names there, as described in Charts, images and installation bundle. The pull secrets of model and package images reach every pod of theapi-serverchart. - Resources.
api-server.resourcesapplies to every container without its ownresources, including bothgrpccontainers and the hook Jobs. The gRPC service holds the Python models and usually needs more memory than the Foundation4 processes, so a production deployment setsapi-server.server.resources,api-server.worker.resourcesandapi-server.grpc.resources. Scaling and performance describes sizing. - Bundled PostgreSQL. The bundled database keeps the data on a volume claim of each pod. An installation of an earlier chart version kept the data on a temporary pod volume, and the volume claim template of a StatefulSet does not change in place, so the operator dumps the database with
pg_dump, deletes the StatefulSetfoundation4ai-core-postgres, upgrades the core release and restores the dump, as described in Backup, restore and upgrades. - Scrape configuration.
prometheus.scrapeConfigsturns off every default job of the Prometheus chart by name, and the core chart adds its own jobfoundation4ai-pods. Further jobs go intoprometheus.extraScrapeConfigs. - Rendering without a cluster. The core release reads
foundation4ai-secretsfrom the cluster at render time and renders only withhelm install,helm upgradeor--dry-run=server. The application release renders offline, but the checksums offoundation4ai-secretsandfoundation4ai-corethen stay constant, so a credential change needskubectl rollout restart. - Restarts. A
helm upgradeof the application release that changesconfigs,secrets, a credential infoundation4ai-secretsor an address infoundation4ai-corereplaces the API server and worker pods, as described in Configuration reference. - Hook Jobs. The hook Jobs take the pull secrets,
podSecurityContext, scheduling values andapi-server.jobssettings of the chart, and run with the namespace default ServiceAccount, because the chart creates its own ServiceAccount after the hooks. - Kubernetes version. The application chart requires Kubernetes 1.31 or later, as described in Deployment overview and requirements.
- Hugging Face directory.
FOUNDATION4AI__PATHS__HUGGINGFACEoverrides apaths.huggingfacevalue inconfigs. Hugging Face embedding models and the sentence-transformers token splitter read from a Hugging Face model image mounted at/data/huggingface. Such an image replaces the writable cache, so the image also holds every tokenizer that the BM25 indexes use, as described in Models, packages and air-gapped installs.
Production values example
The following values file sets the keys that a production installation usually sets. Every value in angle brackets is replaced. The API server runs 2 replicas and a PodDisruptionBudget so that the API stays available while one pod restarts.
global:
serverImageTag: "<api server image tag>"
grpcImageTag: "<grpc service image tag>"
dashboardImageTag: "<dashboard image tag>"
foundation4aiImageRegistry: <registry>
imagePullSecrets:
- <pull secret>
postgres:
enabled: false
nats:
config:
jetstream:
fileStore:
pvc:
storageClassName: <storage class>
prometheus:
server:
persistentVolume:
storageClass: <storage class>
api-server:
replicaCount:
server: 2
worker: 3
server:
resources:
requests:
cpu: <cpu request>
memory: <memory request>
limits:
memory: <memory limit>
worker:
resources:
requests:
cpu: <cpu request>
memory: <memory request>
limits:
memory: <memory limit>
grpc:
resources:
requests:
cpu: <cpu request>
memory: <memory request>
limits:
memory: <memory limit>
podDisruptionBudget:
server:
maxUnavailable: 1
ingress:
enabled: true
className: <ingress class>
hosts:
- host: <host name>
tls:
- secretName: <tls secret>
hosts:
- <host name>