Deployment overview and requirements
This page describes what a Foundation4 installation deploys on Kubernetes, the order in which the parts are installed, the two deployment profiles and the requirements for the cluster, the database and the operator's workstation. Operators read this page before planning an installation. Security reviewers use the requirements to assess the footprint of Foundation4 in a cluster. The procedure itself is described in Install on Kubernetes.
Components
A Foundation4 installation consists of two Helm releases in the namespace foundation4ai. The core release installs the services that Foundation4 depends on. The application release installs Foundation4 and reads the connection settings that the core release produces.
| Release | Chart | Installs |
|---|---|---|
foundation4ai-core | foundation4ai-core 1.1.0 | NATS JetStream (3 replicas and a NATS utility pod), Valkey as the Redis-compatible cache, the Prometheus server, optionally PostgreSQL with the vector, vchord, pg_tokenizer and vchord_bm25 extensions, and the Secret foundation4ai-core with the connection URLs |
foundation4ai | foundation4ai 1.1.0 | The API server (1 replica), the workers (3 replicas), the dashboard (1 replica), three installation Jobs, and optionally an Ingress or an HTTPRoute |
The releases have the following characteristics:
- Sidecar containers. The API server pod and each worker pod run two containers: the Foundation4 process and the gRPC service. The gRPC service is deployed as a sidecar container, a second container in the same Kubernetes pod, and hosts the Python text splitters and embedding providers.
- Installation Jobs. The application release runs the database migration, the license check and the creation of the master key as Helm hook Jobs before the Deployments start. All three Jobs run the API server image. Helm deletes the three Jobs once all of them complete. When a Job fails, the Jobs stay, with their logs, until the next install or upgrade.
- Credentials. The API server, worker and Job pods read the license, the application secret and the master key from the Secret
foundation4ai-secrets, and the connection URLs from the Secretfoundation4ai-core. - Fixed names. The application release reads the Secret
foundation4ai-coreby default, and the core values name the Valkey and NATS JetStream Secrets after the release namefoundation4ai-core. The core release is therefore namedfoundation4ai-coreand installed in the same namespace as the application release. - Rendering against the cluster. The core chart reads the Secret
foundation4ai-secretswhile Helm renders the templates, to build the connection URLs. The core release is therefore installed with the Helm command line and access to the cluster.helm template, client-side dry runs and GitOps tools that render charts offline stop with an error that the Secretfoundation4ai-secretswas not found. The application chart also renders offline, but the pods then do not restart after a change of the credentials and are restarted by hand.
Installation order
The installation follows a fixed order, because each step consumes the output of the step before:
- The operator creates the Secret
foundation4ai-secretsfrom the secrets filefoundation4ai.secrets.env. - The core release installs NATS JetStream, Valkey and Prometheus, and writes the connection URLs into the Secret
foundation4ai-core. - A first installation of the application release migrates the database. The license check Job then writes the system ID to the Job log and fails, so this installation stops with an error.
- The operator sends the system ID to the Foundation4 provider and receives the license. The operator adds the license to the secrets file and updates the Secret
foundation4ai-secrets. - The operator installs the application release again. The migration, license check and master key Jobs complete, and the API server, workers and dashboard start.
- The operator signs in with the master key and creates one API key for each client application. The master key stays with the operators and serves only for administration.
The license is bound to the system ID, which Foundation4 derives from the system identifier of the PostgreSQL server, the database name and the schema. Licensing describes the system ID and the license.
Solid arrows show actions and requests; dashed arrows show information returned to the operator.
Later changes, such as new image tags or a renewed license, use helm upgrade of the core release and then of the application release.
Deployment profiles
Foundation4 supports two deployment profiles. Install for evaluation installs the evaluation profile; Install on Kubernetes installs the production profile.
| Aspect | Evaluation | Production |
|---|---|---|
| Nodes | One node, such as a single-node k3s cluster | Several nodes, sized for the workload |
| PostgreSQL | Bundled chart (postgres.enabled: true) on one 8 GiB volume claim | External PostgreSQL with the extensions listed under PostgreSQL requirements, reached through POSTGRES_URL |
| Images | A registry, or images loaded onto the node | A registry that every node can pull from, mirrored when the cluster has no internet access |
| Resources | No requests or limits | Requests and limits for every component |
| Workers | 1 replica | 3 replicas (the default) or more |
| Monitoring | Bundled Prometheus | Bundled Prometheus or the cluster's monitoring stack |
| Access | Port forward, with an ingress for the dashboard | Ingress or HTTPRoute with Transport Layer Security (TLS) |
The evaluation profile is for evaluation only. The bundled PostgreSQL runs as a single pod and stores data on one volume claim, so deleting the volume claim deletes every pipeline and document. A new database also has a new system ID, which requires a new license.
Kubernetes requirements
The application chart requires Kubernetes 1.31 or later, and Helm refuses to install the chart on an earlier version. The bundled Prometheus chart requires Kubernetes 1.19 or later. The charts use the following resources and features:
| Resource or feature | Used by | Required when |
|---|---|---|
| Jobs run as Helm hooks | Migration, license check and master key Jobs | Always |
| Default StorageClass | NATS JetStream, Prometheus and bundled PostgreSQL volume claims | Always, unless the values name a storage class |
| ClusterRole and ClusterRoleBinding | Prometheus server service discovery | The bundled Prometheus is enabled (the default) |
| PodDisruptionBudget | NATS JetStream; the API server, workers and dashboard | Always for NATS JetStream; for the other components when api-server.podDisruptionBudget or dashboard.podDisruptionBudget is set |
| Image volumes | Model and package images | api-server.models or api-server.packages is set |
HorizontalPodAutoscaler autoscaling/v2 | API server and worker autoscaling | Autoscaling is enabled |
Ingress networking.k8s.io/v1 and an ingress controller | External access | ingress.enabled is true |
Gateway API gateway.networking.k8s.io/v1 and a Gateway | External access | httpRoute.enabled is true |
The following constraints also apply:
- Image volumes. Image volumes need the Kubernetes feature
ImageVolume, which is alpha in Kubernetes 1.31 and beta from 1.33, and support in the container runtime. The cluster operator or provider enables the feature on the cluster. Models, packages and air-gapped installs describes the model and package images. - Node architecture. The Foundation4 images are built for the
amd64architecture. The API server, worker and dashboard pods run onamd64nodes. - Pod security. The API server, worker and Job pods run as the unprivileged user 10001 with
runAsNonRoot, theRuntimeDefaultseccomp profile, no privilege escalation and no capabilities, the settings that therestrictedPod Security Standard requires. The dashboard chart sets no security context by default, so a namespace that enforces therestrictedstandard rejects the dashboard pod unlessdashboard.podSecurityContextanddashboard.securityContextset one. Security hardening describes the settings. - Cluster permissions. The installing account creates a namespace, namespaced resources and, for the bundled Prometheus, a ClusterRole and a ClusterRoleBinding.
Storage requirements
The core release requests 38 GiB in 4 volume claims, and 46 GiB in 5 volume claims with the bundled PostgreSQL. The claims name no storage class unless the values set one, so the cluster needs a default StorageClass.
| Component | Volume claims | Size | Values keys |
|---|---|---|---|
| NATS JetStream | 3, one per replica | 10 GiB each | nats.config.jetstream.fileStore.pvc.size, nats.config.jetstream.fileStore.pvc.storageClassName |
| Prometheus server | 1 | 8 GiB | prometheus.server.persistentVolume.size, prometheus.server.persistentVolume.storageClass |
| Valkey | None | Not applicable | The cache keeps data in memory only |
| Bundled PostgreSQL | 1 | 8 GiB | postgres.storage.requestedSize, postgres.storage.className |
The NATS JetStream volumes hold documents that wait for a worker. Deleting a NATS JetStream volume claim deletes the queued documents. The bundled PostgreSQL volume holds the database, so deleting the PostgreSQL volume claim deletes every pipeline and document.
PostgreSQL requirements
The production profile uses an external PostgreSQL database. The bundled PostgreSQL is disabled by default (postgres.enabled: false). PostgreSQL is the primary data store and holds every pipeline, document, fragment and vector. The external database needs what the bundled PostgreSQL image tensorchord/vchord-suite provides.
- Version. The bundled chart and the Foundation4 test environment use PostgreSQL 18.
- Extensions. The extensions
vector,vchord,pg_tokenizerandvchord_bm25are installed on the server. Many managed PostgreSQL services do not offervchord,pg_tokenizerorvchord_bm25. - pgvector. Version 0.8.0 or later. Similarity search sets the pgvector parameter
hnsw.iterative_scan, which pgvector 0.8.0 introduced. - Preloaded libraries. The server parameter
shared_preload_librariesincludesvchord,vchord_bm25,vector,pg_tokenizer. A change of the parameter takes effect after a restart of the PostgreSQL server. - Superuser step. Only a superuser can create the extensions. Before the first installation, a superuser runs the
postgres.customScriptsscript from the values file of the core chart once in the application database. The script creates the four extensions and the tokenizerbert, and grants every database user read access to the schemasbm25_catalogandtokenizer_catalog. The superuser also grants write access totokenizer_catalog, which BM25 indexes need and the script of the 1.1.0 chart omits, as described in Database preparation. Without the extensions, the migration Job fails. When the error names an extension, the Job log ends with a note that names the four extensions. - Schemas. Foundation4 runs
CREATE SCHEMA IF NOT EXISTSat every start for the schemaspublicandembeddings, the defaults ofdatabase.schemaanddatabase.embeddings_schema. The database user holds theCREATEprivilege on the database. A database owned by the Foundation4 database user meets this requirement. - System identifier. The database user can run the function
pg_control_system(), which the system ID of the license needs. Stock PostgreSQL allows every user to run the function; some managed services revoke the privilege, and an administrator then runsGRANT EXECUTE ON FUNCTION pg_control_system() TO <database user>;. - Connection. The secrets file carries the connection URL in
POSTGRES_URL. The user name and password in the URL are percent-encoded.
Database describes the connection settings, TLS and the connection budget. Licensing describes the system ID.
Operator tools
| Tool | Purpose | Required when |
|---|---|---|
kubectl | Namespace, Secrets, Job logs, port forward | Always |
| Helm 3 | Both releases | Always |
kubectl kustomize or kustomize | The Secret foundation4ai-secrets from the secrets file | Always |
openssl and uuidgen | Passwords, secrets and the master key identifier | Always |
curl | Access validation | Always |
just, kustomize and yq | The recipes in the .justfile of the deployment files | The recipes are used |
The .justfile checks for kubectl, kustomize, helm and yq when just loads the file, so every recipe fails when one of the four tools is missing from the PATH.
Sizing
No measured sizing figures are available. The charts establish the following starting points:
- Resource settings. The charts set no resource requests or limits for any component.
- Container resources. The values
api-server.server.resources,api-server.worker.resources,api-server.grpc.resourcesandapi-server.jobs.resourcesset the requests and limits of the API server container, the worker container, the gRPC service containers and the installation Jobs. A container without its own value usesapi-server.resources. - Dashboard resources. The value
dashboard.resourcessets the requests and limits of the dashboard container. - FastEmbed copies. Each API server and worker process loads up to
api-server.fastembedInstancescopies of each FastEmbed model, 2 by default, so that searches keep answering while documents are embedded with the same model. A second copy loads only when calls overlap. Each copy takes as much memory as the model: about 90 MB for the defaultall-MiniLM-L6-v2and over 1 GB for large models. - Replicas. 1 API server, 3 workers and 1 dashboard. Autoscaling is disabled by default; when enabled, the API server scales from 1 to 100 replicas and the workers from 3 to 100, at a CPU target of 80 percent.
- Worker batches. Each worker takes documents from the queue in batches of up to 100.
- Queue retention. NATS JetStream keeps a queued document for up to 24 hours. A document that waits longer than 24 hours is removed from the queue without processing, so the workers are sized to keep the queue shorter than 24 hours of submissions.
- Database connections. Each API server replica opens up to 3 database connections, and each worker opens 1.
Scaling and performance describes replica counts, autoscaling and the queue.