Skip to main content

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:

ReleaseChartTop-level keys read
foundation4ai-corefoundation4ai-core 1.1.0global, postgres, redis, nats, prometheus
foundation4aifoundation4ai 1.1.0global, 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.

KeyEvaluationProduction
postgres.enabledtrue, bundled PostgreSQL on a volume claim of 8Gifalse, external PostgreSQL through POSTGRES_URL
api-server.replicaCount.worker1Default 3 or more
api-server.resources, or the resources of api-server.server, worker, grpc and jobsNot setRequests and limits set
Image repositoriesA registry, or images loaded onto the nodeAn internal registry or mirror, through global.foundation4aiImageRegistry or the repository values
ingress or httpRouteOptionalEnabled, with TLS
Storage classesDefault StorageClassSet for NATS JetStream and Prometheus

Global values​

KeyTypeDefaultEffect
global.serverImageTagString""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.grpcImageTagString""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.dashboardImageTagString""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.foundation4aiImageRegistryString""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.imagePullSecretsList[]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.pullSecretNamesString, list of namesNone, []Registry prefix and pull secrets of the NATS images
global.imageRegistryString""Registry prefix of the Valkey image
global.natsReplicasInteger3Copies 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.existingSecretStringfoundation4ai-secretsSecret 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:

KeyDefaultRead when
global.secrets.postgresUrlKeyPOSTGRES_URLpostgres.enabled is false
global.secrets.postgresUserKeyPOSTGRES_USERpostgres.enabled is true
global.secrets.postgresUserPasswordKeyPOSTGRES_PASSWORDpostgres.enabled is true
global.secrets.postgresDatabaseKeyPOSTGRES_DATABASEpostgres.enabled is true
global.secrets.redisUrlKeyREDIS_URLredis.enabled is false
global.secrets.redisPasswordKeyREDIS_PASSWORDredis.enabled is true
global.secrets.natsUser, global.secrets.natsPasswordKeyfoundation4ai, NATS_PASSWORDnats.enabled is true. The user name is a value, and the password is the Secret key.
global.secrets.natsUrlKeyNATS_URLnats.enabled is false
global.secrets.prometheusUrlKeyPROMETHEUS_URLprometheus.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​

KeyDefaultEffect when false
postgres.enabledfalseThe database URL comes from POSTGRES_URL
redis.enabledtrueThe cache URL comes from REDIS_URL
nats.enabledtrueThe NATS JetStream URL comes from NATS_URL
prometheus.enabledtrueThe 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.

KeyDefaultEffect
postgres.image.repository, postgres.image.tagtensorchord/vchord-suite, pg18-20260501PostgreSQL 18 with the vector, vchord, pg_tokenizer and vchord_bm25 extensions
postgres.image.registryDocker Hub (PostgreSQL chart default)Registry of the image
postgres.settings.dataDir/var/lib/postgresql/18/dockerData directory of the image
postgres.settings.existingSecret, postgres.settings.superuserPassword.secretKeyfoundation4ai-secrets, POSTGRES_SUPERUSER_PASSWORDSuperuser password
postgres.userDatabase.*foundation4ai-secrets, keys POSTGRES_DATABASE, POSTGRES_USER, POSTGRES_PASSWORDApplication database and user
postgres.customScripts.01-init-extension.sqlCreates the extensions and the bert tokenizerRuns 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.className8Gi, not setA 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)​

KeyDefaultEffect
redis.auth.enabledtruePassword authentication
redis.auth.usersExistingSecretfoundation4ai-core-redisSecret that the core chart creates from REDIS_PASSWORD, with the key default
redis.auth.aclUsers.default.permissions~* &* +@allPermissions of the default user
redis.image.repositoryvalkey/valkeyImage; the tag defaults to the chart application version, 9.0.1
redis.dataStorage.enabledfalseCache 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​

KeyDefaultEffect
nats.config.cluster.enabled, nats.config.cluster.replicastrue, 33 NATS servers in a StatefulSet
nats.config.jetstream.enabledtrueJetStream persistence, required by Foundation4
nats.config.merge, nats.container.patch, nats.podTemplate.patchInclude and mount of the Secret foundation4ai-core-nats-authClient 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.secretNamefalse, not setTLS 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.tlsNot setTLS between the NATS servers, configured as the commented example in the values file of the core chart shows
nats.config.jetstream.fileStore.pvc.size10GiVolume claim of each server
nats.config.jetstream.fileStore.pvc.storageClassNameNot setThe default StorageClass applies
nats.container.resources{}No requests or limits
nats.podDisruptionBudget.enabledtrueA PodDisruptionBudget for the NATS servers
nats.natsBox.enabledtrueThe utility Deployment foundation4ai-core-nats-box, which carries the nats command-line tool
nats.promExporter.enabledfalsePrometheus exporter for NATS server and JetStream metrics
nats.container.image, nats.reloader.image, nats.natsBox.container.imagenats 2.12.4-alpine, natsio/nats-server-config-reloader 0.21.1, natsio/nats-box 0.19.3Images

Prometheus​

KeyDefaultEffect
prometheus.alertmanager.enabled, prometheus.kube-state-metrics.enabled, prometheus.prometheus-node-exporter.enabled, prometheus.prometheus-pushgateway.enabledfalseOnly the Prometheus server is installed
prometheus.server.ingress.enabledfalseNo external access to Prometheus
prometheus.scrapeConfigsEvery default job with enabled: falseTurns off the default jobs of the Prometheus chart
prometheus.serverFiles.prometheus.yml.scrape_configsJob foundation4ai-podsScrapes 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.storageClass8Gi, not setMetrics volume
prometheus.server.retention15dMetrics 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.

KeyTypeDefaultEffect
api-server.enabledBooleantrueInstalls the chart
api-server.secretStringfoundation4ai-coreSecret of the core release, in the same namespace, whose addresses every pod mounts under /app/config/secrets
api-server.replicaCount.serverInteger1API server replicas, when autoscaling is off
api-server.replicaCount.workerInteger3Worker replicas, when autoscaling is off
api-server.image.repositoryStringThe provider's registryAPI server image, also used by the workers and hook Jobs
api-server.image.repositoryGrpcStringThe provider's registrygRPC service image
api-server.image.pullPolicyStringIfNotPresentPull policy of both images
api-server.image.tag, api-server.image.tagGrpcString""Tags that take precedence over global.serverImageTag and global.grpcImageTag
api-server.imagePullSecretsList[]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, nameMixedtrue, 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.podAnnotationsMap{}Added to the API server and worker pods, next to the fixed Prometheus and checksum annotations
api-server.podLabelsMap{}Added to the API server and worker pods
api-server.podSecurityContextMaprunAsNonRoot: true, user and group 10001, fsGroup: 10001, seccompProfile RuntimeDefaultPod 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.securityContextMapallowPrivilegeEscalation: false, all capabilities droppedSecurity context of every container, unless server, worker, grpc or jobs sets its own
api-server.server.securityContext, worker.securityContext, grpc.securityContext, jobs.securityContextMap{}Security context of the server container, the worker container, both grpc containers and the hook Job containers
api-server.service.type, api-server.service.portString, integerClusterIP, 80Service of the API server, which targets container port 8000
api-server.resourcesMap{}Requests and limits of every container, unless server, worker, grpc or jobs sets its own
api-server.server.resources, worker.resources, grpc.resources, jobs.resourcesMap{}Requests and limits of the server container, the worker container, both grpc containers and the hook Job containers
api-server.server.startupProbeMapGET / on port 8000 every 10 seconds, failureThreshold: 30, timeoutSeconds: 5Startup 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.priorityClassNameString""Priority class of the API server and worker pods. Empty uses the cluster default.
api-server.podDisruptionBudget.server, api-server.podDisruptionBudget.workerMap{}Specification of a PodDisruptionBudget without the selector, such as maxUnavailable: 1. Empty creates none.
api-server.autoscaling.server.*Mapenabled: false, minReplicas: 1, maxReplicas: 100, targetCPUUtilizationPercentage: 80HorizontalPodAutoscaler of the API server. targetMemoryUtilizationPercentage adds a memory target.
api-server.autoscaling.worker.*Mapenabled: false, minReplicas: 3, maxReplicas: 100, targetCPUUtilizationPercentage: 80HorizontalPodAutoscaler of the workers
api-server.nodeSelector, tolerations, affinityMap, list, mapEmptyScheduling of the API server, worker and hook Job pods
api-server.volumes, api-server.volumeMountsList[]Extra volumes of the API server and worker pods, mounted in the server and worker containers
api-server.configsMap of strings{}Entries of the ConfigMap, mounted in /app/config and loaded as environment variables of the server and worker containers
api-server.secretsMap of strings{}Entries of the Secret, mounted in /app/config
api-server.secretsAnnotationsMap{}Annotations of the Secret foundation4ai-api-server
api-server.models, api-server.packagesList[]Model and package images, as described in Models, packages and air-gapped installs
api-server.corsAllowedOriginsList[]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.allowPrivateEndpointsBooleantrueAccepts 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.fastembedInstancesInteger2Most copies of each FastEmbed model that one API server or worker process loads, written to app.fastembed_instances
api-server.grpcExtraEnvList[]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.pathBoolean, stringtrue, /cache/huggingfaceA 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.natsCaKeyString"", ca.crtSecret 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.fullnameOverrideString""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​

KeyTypeDefaultEffect
dashboard.enabledBooleantrueInstalls the dashboard Deployment and Service foundation4ai-dashboard, container port 3000
dashboard.replicaCountInteger1Dashboard replicas
dashboard.image.repository, pullPolicy, tagStringThe provider's registry, IfNotPresent, ""Dashboard image; the tag falls back to global.dashboardImageTag
dashboard.imagePullSecretsList[]Pull secrets of the dashboard pods, together with global.imagePullSecrets. Entries are plain names or name entries.
dashboard.serviceAccount.*, podAnnotations, podLabelsMixedChart defaultsStandard pod settings
dashboard.podSecurityContext, dashboard.securityContextMap{}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.portString, integerClusterIP, 80Service of the dashboard
dashboard.resourcesMap{}Requests and limits of the dashboard container
dashboard.livenessProbe, dashboard.readinessProbeMap{}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.priorityClassNameString""Priority class of the dashboard pods
dashboard.podDisruptionBudgetMap{}Specification of a PodDisruptionBudget without the selector. Empty creates none.
dashboard.volumes, volumeMounts, nodeSelector, tolerations, affinityMixedEmptyStandard pod settings

Ingress and HTTPRoute​

KeyDefaultEffect
ingress.enabledfalseCreates the Ingress foundation4ai
ingress.className""Ingress class
ingress.annotations{}Annotations of the Ingress
ingress.hosts[].hostchart-example.localHost 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.enabledfalseCreates the Gateway API HTTPRoute foundation4ai
httpRoute.annotations{}Annotations of the HTTPRoute
httpRoute.parentRefsname: gateway, sectionName: httpGateway and listener
httpRoute.hostnameschart-example.localHost 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.grpcImageTag and global.dashboardImageTag, or the tags of each chart, to the tags of the release, and the render fails without them.
  • Pull secrets. Valkey reads global.imagePullSecrets as 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 the api-server chart.
  • Resources. api-server.resources applies to every container without its own resources, including both grpc containers and the hook Jobs. The gRPC service holds the Python models and usually needs more memory than the Foundation4 processes, so a production deployment sets api-server.server.resources, api-server.worker.resources and api-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 StatefulSet foundation4ai-core-postgres, upgrades the core release and restores the dump, as described in Backup, restore and upgrades.
  • Scrape configuration. prometheus.scrapeConfigs turns off every default job of the Prometheus chart by name, and the core chart adds its own job foundation4ai-pods. Further jobs go into prometheus.extraScrapeConfigs.
  • Rendering without a cluster. The core release reads foundation4ai-secrets from the cluster at render time and renders only with helm install, helm upgrade or --dry-run=server. The application release renders offline, but the checksums of foundation4ai-secrets and foundation4ai-core then stay constant, so a credential change needs kubectl rollout restart.
  • Restarts. A helm upgrade of the application release that changes configs, secrets, a credential in foundation4ai-secrets or an address in foundation4ai-core replaces the API server and worker pods, as described in Configuration reference.
  • Hook Jobs. The hook Jobs take the pull secrets, podSecurityContext, scheduling values and api-server.jobs settings 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__HUGGINGFACE overrides a paths.huggingface value in configs. 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>