Skip to main content

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.

ReleaseChartInstalls
foundation4ai-corefoundation4ai-core 1.1.0NATS 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
foundation4aifoundation4ai 1.1.0The 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 Secret foundation4ai-core.
  • Fixed names. The application release reads the Secret foundation4ai-core by default, and the core values name the Valkey and NATS JetStream Secrets after the release name foundation4ai-core. The core release is therefore named foundation4ai-core and installed in the same namespace as the application release.
  • Rendering against the cluster. The core chart reads the Secret foundation4ai-secrets while 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 Secret foundation4ai-secrets was 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:

  1. The operator creates the Secret foundation4ai-secrets from the secrets file foundation4ai.secrets.env.
  2. The core release installs NATS JetStream, Valkey and Prometheus, and writes the connection URLs into the Secret foundation4ai-core.
  3. 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.
  4. 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.
  5. The operator installs the application release again. The migration, license check and master key Jobs complete, and the API server, workers and dashboard start.
  6. 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.

AspectEvaluationProduction
NodesOne node, such as a single-node k3s clusterSeveral nodes, sized for the workload
PostgreSQLBundled chart (postgres.enabled: true) on one 8 GiB volume claimExternal PostgreSQL with the extensions listed under PostgreSQL requirements, reached through POSTGRES_URL
ImagesA registry, or images loaded onto the nodeA registry that every node can pull from, mirrored when the cluster has no internet access
ResourcesNo requests or limitsRequests and limits for every component
Workers1 replica3 replicas (the default) or more
MonitoringBundled PrometheusBundled Prometheus or the cluster's monitoring stack
AccessPort forward, with an ingress for the dashboardIngress 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 featureUsed byRequired when
Jobs run as Helm hooksMigration, license check and master key JobsAlways
Default StorageClassNATS JetStream, Prometheus and bundled PostgreSQL volume claimsAlways, unless the values name a storage class
ClusterRole and ClusterRoleBindingPrometheus server service discoveryThe bundled Prometheus is enabled (the default)
PodDisruptionBudgetNATS JetStream; the API server, workers and dashboardAlways for NATS JetStream; for the other components when api-server.podDisruptionBudget or dashboard.podDisruptionBudget is set
Image volumesModel and package imagesapi-server.models or api-server.packages is set
HorizontalPodAutoscaler autoscaling/v2API server and worker autoscalingAutoscaling is enabled
Ingress networking.k8s.io/v1 and an ingress controllerExternal accessingress.enabled is true
Gateway API gateway.networking.k8s.io/v1 and a GatewayExternal accesshttpRoute.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 amd64 architecture. The API server, worker and dashboard pods run on amd64 nodes.
  • Pod security. The API server, worker and Job pods run as the unprivileged user 10001 with runAsNonRoot, the RuntimeDefault seccomp profile, no privilege escalation and no capabilities, the settings that the restricted Pod Security Standard requires. The dashboard chart sets no security context by default, so a namespace that enforces the restricted standard rejects the dashboard pod unless dashboard.podSecurityContext and dashboard.securityContext set 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.

ComponentVolume claimsSizeValues keys
NATS JetStream3, one per replica10 GiB eachnats.config.jetstream.fileStore.pvc.size, nats.config.jetstream.fileStore.pvc.storageClassName
Prometheus server18 GiBprometheus.server.persistentVolume.size, prometheus.server.persistentVolume.storageClass
ValkeyNoneNot applicableThe cache keeps data in memory only
Bundled PostgreSQL18 GiBpostgres.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_tokenizer and vchord_bm25 are installed on the server. Many managed PostgreSQL services do not offer vchord, pg_tokenizer or vchord_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_libraries includes vchord,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.customScripts script from the values file of the core chart once in the application database. The script creates the four extensions and the tokenizer bert, and grants every database user read access to the schemas bm25_catalog and tokenizer_catalog. The superuser also grants write access to tokenizer_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 EXISTS at every start for the schemas public and embeddings, the defaults of database.schema and database.embeddings_schema. The database user holds the CREATE privilege 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 runs GRANT 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​

ToolPurposeRequired when
kubectlNamespace, Secrets, Job logs, port forwardAlways
Helm 3Both releasesAlways
kubectl kustomize or kustomizeThe Secret foundation4ai-secrets from the secrets fileAlways
openssl and uuidgenPasswords, secrets and the master key identifierAlways
curlAccess validationAlways
just, kustomize and yqThe recipes in the .justfile of the deployment filesThe 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.resources and api-server.jobs.resources set 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 uses api-server.resources.
  • Dashboard resources. The value dashboard.resources sets the requests and limits of the dashboard container.
  • FastEmbed copies. Each API server and worker process loads up to api-server.fastembedInstances copies 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 default all-MiniLM-L6-v2 and 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.