Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Key Components

To install the control plane on your generic Kubernetes infrastructure, you need to install the following components:
  • TrueFoundry Control Plane (Shipped as a helm chart called truefoundry)
  • PostgreSQL Database (Managed or Self-Hosted with PostgreSQL >= 13)
  • Blob Storage (S3, Minio, or any other S3 compatible storage)

​
Compute Requirements

TrueFoundry ships as a helm chart (https://github.com/truefoundry/infra-charts/tree/main/charts/truefoundry) that has configurable options to deploy the control plane according to your needs. The compute requirements change based on the scale of the number of users and requests. Here are a few scenarios that you can choose from based on your needs.
The small tier is recommended for development purposes. Here all the components are deployed on Kubernetes and in non HA mode (single replica). This is suitable if you are just testing out the different features of TrueFoundry.
This setup brings up 1 replica of the services and is not highly-available. It can enable you to test the features but we do not recommend this for production mode.
ComponentCPUMemoryStorageMin NodesRemarks
Helm-Chart
(Control Plane components)		4 vCPU8GB60GB
Persistent Volumes (Block Storage) On Kubernetes		2
Pods should be spread over min 2 nodes
Postgres
(Deployed on Kubernetes)		0.5 vCPU0.5GB5GB
Persistent Volumes (Block Storage) On Kubernetes		PostgreSQL version >= 13
IOPS: Default (suitable for dev/testing)
Blob Storage
(S3 Compatible)		20GB

​
Prerequisites for Installation

  1. Kubernetes Cluster: K8s cluster 1.27+
  2. Support for dynamic provisioning of storage for PVC (such as local storage provisioners, NFS, Longhorn, OpenEBS, or other on-premises storage solutions) and support for exposing the control plane dashboard via an ingress controller:
    • Ingress controller (e.g., Nginx Ingress Controller)
    • Istio service mesh
  3. Domain to map the ingress of the Control Plane dashboard along with certificate for the domain.
    This Domain will be referred as Control Plane URL in our documentation.
  4. Egress Access from TrueFoundry:
  5. Tenant Name, Licence key, and image pull secret - This will be given by TrueFoundry team. Make sure your organization is registered((https://truefoundry.com/register)) on TrueFoundry.
    One Tenant Name and Licence key must only be used to setup one Control Plane. Later, switching to new tenant name and licence key would lead to complete data lose of existing control plane.
  6. PostgreSQL database (version >= 13). We recommend managed PostgreSQL database for production environments. For instance requirements, refer to the Compute Requirements section.
    In case you do not have a managed database for testing purposes, set devMode to true in the values file to spin up a local PostgreSQL database.
  7. Blob Storage to store artifacts (S3, Minio, or any other S3 compatible storage).

​
Installation Instructions

1

Setup Blob Storage

You need to configure S3-compatible blob storage (such as Minio, AWS S3, or any other S3-compatible storage) to store artifacts, logs, and AI Gateway request logs.
If you’re using Minio or another S3-compatible storage solution, you’ll need to provide the following configuration:
  1. Bucket Name: Name of the S3-compatible bucket
  2. Region: Region identifier (can be any string for Minio)
  3. Access Key ID: Access key for authentication
  4. Secret Access Key: Secret key for authentication
  5. Endpoint URL: Full URL to your S3-compatible storage endpoint
These values will be used in the configuration steps below.
Make sure your blob storage is accessible from your Kubernetes cluster and note down all credentials and endpoints for the next steps.
2

Setup PostgreSQL Database

Ensure you have a PostgreSQL database (version >= 13) set up and accessible from your Kubernetes cluster.
For production environments, we strongly recommend using a managed PostgreSQL service:
  1. Create a PostgreSQL instance with the specifications from the Compute Requirements section
  2. Create a database named truefoundry (or your preferred name)
  3. Create a user with full permissions on this database
  4. Note down the following details:
    • DB_HOST: Database hostname or IP address
    • DB_PORT: Database port (usually 5432)
    • DB_NAME: Database name
    • DB_USERNAME: Database username
    • DB_PASSWORD: Database password
For development or testing purposes only, you can deploy PostgreSQL on Kubernetes:
  1. Set devMode.enabled: true in the values file (shown in a later step)
  2. The PostgreSQL will be automatically deployed with the control plane
This setup is NOT highly-available and should NOT be used for production environments.
PostgreSQL SSL Configuration: For PostgreSQL 17+, SSL must be disabled in the database configuration. This can typically be done by setting SSL-related parameters to false or 0 in your database configuration.
3

Add Helm Repository

Add the ArgoCD helm repository:
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update argo
4

Install ArgoCD

Install ArgoCD if not already installed:
helm install argocd argo/argo-cd \
--namespace argocd \
--create-namespace \
--version 9.4.14 \
--set server.extraArgs[0]="--insecure" \
--set server.extraArgs[1]="--application-namespaces=*" \
--set controller.extraArgs[0]="--application-namespaces=*" \
--set applicationSet.enabled=false \
--set notifications.enabled=false \
--set dex.enabled=false
5

Create Kubernetes Secrets

We will create two secrets in this step:
  1. Store the License Key and DB Credentials
  2. Store the Image Pull Secret
We need to create a Kubernetes secret containing the licence key and database credentials that you configured in the previous step.
If you are using PostgreSQL on Kubernetes in the dev mode, the values will be as follows:DB_HOST: <HELM_RELEASE_NAME>-postgresql.<NAMESPACE>.svc.cluster.local // eg. truefoundry-postgresql.truefoundry.svc.cluster.localDB_NAME: truefoundryDB_USERNAME: postgres # In order to use custom username, please update the same at postgresql.auth.usernameDB_PASSWORD: randompassword # You can change this to any value here.
truefoundry-creds.yaml
apiVersion: v1
kind: Secret
metadata:
  name: truefoundry-creds
type: Opaque
stringData:
  TFY_API_KEY: <TFY_API_KEY> # Provided by TrueFoundry team
  DB_HOST: <DB_HOST>
  DB_NAME: <DB_NAME>
  DB_USERNAME: <DB_USERNAME>
  DB_PASSWORD: <DB_PASSWORD>
Apply the secret to the Kubernetes cluster (Assuming you are installing the control plane in the truefoundry namespace)
kubectl apply -f truefoundry-creds.yaml -n truefoundry
We need to create a Image Pull Secret to enable pulling the truefoundry images from the private registry.
truefoundry-image-pull-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: truefoundry-image-pull-secret
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <IMAGE_PULL_SECRET> # Provided by TrueFoundry team
Apply the secret to the Kubernetes cluster (Assuming you are installing the control plane in the truefoundry namespace)
kubectl apply -f truefoundry-image-pull-secret.yaml -n truefoundry
6

Create HelmChart Values File

Create a values file as given below and replace the following values:
  • Control Plane URL: URL that you will map to the control plane dashboard (e.g., https://truefoundry.example.com)
  • Tenant Name: Tenant name provided by TrueFoundry team
  • Blob Storage Configuration: Use the bucket name, region, access keys, and endpoint URL from the “Setup Blob Storage” step above. Depending on the storage you can chose your defaultCloudProvider as aws, gcp, azure etc
  • You can disable any addons that you don’t need by setting the enabled flag to false
truefoundry-values.yaml
tenantName: ""
controlPlaneURL: ""
clusterName: ""

tolerations: []
affinity: {}

argocd:
  enabled: true
argoWorkflows:
  enabled: true
argoRollouts:
  enabled: true
certManager:
  enabled: true
metricsServer:
  enabled: false # enable if you don't have metrics server already enabled
gpu:
  enabled: true

truefoundry:
  enabled: true
  devMode:
    enabled: false # enable for dev mode
  virtualservice:
    enabled: false
    hosts: []
    gateways: []
    annotations: {}
  existingTruefoundryCredsSecret: ""
  imagePullSecrets: []

  defaultCloudProvider: ""
  storageConfiguration: {}

  tolerations: []
  affinity: {}

tfyLogs:
  enabled: true
istio:
  enabled: true
  tfyGateway:
    httpsRedirect: false
    tls:
      enabled: false # make this true for encrypted traffic. Ensure you have TLS certs as k8s secrets in istio-system namespace
      mode: SIMPLE
      credentialName: "" # secret name containing TLS certificates
    domains: ["*"]

keda:
  enabled: true
kubecost:
  enabled: true

prometheus:
  enabled: true
  alertmanager:
    config:
      receivers:
        - name: tfy-agent
          webhook_configs:
            - url: http://tfy-agent.tfy-agent.svc.cluster.local:3000/alerts
              send_resolved: true
  config:
    enabled: true

tfyAgent:
  enabled: false
elasti:
  enabled: true
helm:
  resourcePolicy: keep
7

Install TrueFoundry Control Plane

Install the TrueFoundry control plane using the OCI helm chart:
helm upgrade --install tfy-k8s-generic-inframold oci://tfy.jfrog.io/tfy-helm/tfy-k8s-generic-inframold \
-n argocd --create-namespace -f truefoundry-values.yaml
8

Configure Load Balancer and DNS

  1. Get the IP address of the load balancer:
kubectl get svc -n istio-system
  1. Point your control plane domain to this IP address in your DNS provider.
  2. Configure TLS certificates for the load balancer to terminate TLS traffic.
9

Verify Installation

  1. Wait for all pods to be running:
kubectl get pods -n argocd
kubectl get pods -n truefoundry
  1. Access the control plane at your configured URL and login with the same credentials used to register the tenant.
10

Start deploying workloads to your cluster

You can start by going here

​
Setting Up Compute Plane

After installing the control plane, you need to set up a compute plane where your applications will run.
Compute Plane InstallationFor complete instructions on setting up the compute plane on your generic cluster, please refer to the Generic Compute Plane Setup guide.
Important: Setting Up Control Plane as a Compute PlaneWhen installing the control plane, you need to set up the control plane cluster as a compute plane managed by TrueFoundry itself. This allows you to manage control plane upgrades and configuration through the TrueFoundry UI.To enable this, you MUST disable all add-ons to avoid conflicts with existing cluster components. The add-ons that should be disabled include:
  • ArgoCD - Already installed separately in Step 2
  • Argo Workflows - Conflicts with control plane installation
  • Argo Rollouts - Conflicts with control plane installation
  • Istio - Conflicts if already present
  • Cert Manager - Conflicts if already present
  • Prometheus - Conflicts if already present
  • KEDA - Conflicts if already present
These add-ons will be automatically disabled when you use the TrueFoundry chart for control plane installation (they are not included in the values file above).

​
FAQ

Yes. You can configure your Artifactory to mirror our registry.
Credentials for accessing the TrueFoundry private registry are required and will be provided during onboarding.
As applications created in the control plane are deployed in multiple namespace, you need to create the image pull secret in all the namespaces.Update Helm values as follows:
registry: <YOUR_REGISTRY> # Replace with your registry

imagePullSecrets:
  - name: <IMAGE_PULL_SECRET_NAME> # Replace with your image pull secret name
Following script you can use to create the image pull secret in all the namespaces
NAMESPACES=(argocd prometheus truefoundry keda istio-system tfy-agent cert-manager argo-workflows argo-rollouts tfy-logs kubecost elasti tfy-gpu-operator)

for ns in "${NAMESPACES[@]}"; do kubectl create namespace "$ns"; kubectl create secret docker-registry <IMAGE_PULL_SECRET_NAME> --namespace="$ns" --docker-server=<YOUR_REGISTRY> --docker-username=<USERNAME> --docker-password=<PASSWORD> --docker-email=<EMAIL>; done
  • Replace <IMAGE_PULL_SECRET_NAME> with your image pull secret name.
  • Replace <YOUR_REGISTRY> with your registry URL. Ensure you are also adding your namespace as TrueFoundry will preserve the namespace structure of the images.
  • Replace <USERNAME> with your registry username.
  • Replace <PASSWORD> with your registry password.
  • Replace <EMAIL> with your registry email.
Yes, you can copy the images to your own private registry. To get the entire list of images and instructions to push the images to your registry, you can refer to the air-gapped installation FAQ in the control plane installation guide.The script maintains the namespacing structure of the images in the destination registry. For example, if image is quay.io/argoproj/argo-rollouts:v1.8.2, it will be pushed to <YOUR_REGISTRY>/<NAMESPACE>/argoproj/argo-rollouts:v1.8.2 where <NAMESPACE> is the namespace of the image in which you want to push the images.Once the images are pushed to your registry, you can update the Helm values as follows:
registry: <YOUR_REGISTRY>

imagePullSecrets:
  - name: <IMAGE_PULL_SECRET_NAME>
Following script you can use to create the image pull secret in all the namespaces
NAMESPACES=(argocd prometheus truefoundry keda istio-system tfy-agent cert-manager argo-workflows argo-rollouts tfy-logs kubecost elasti tfy-gpu-operator)

for ns in "${NAMESPACES[@]}"; do kubectl create namespace "$ns"; kubectl create secret docker-registry <IMAGE_PULL_SECRET_NAME> --namespace="$ns" --docker-server=<YOUR_REGISTRY> --docker-username=<USERNAME> --docker-password=<PASSWORD> --docker-email=<EMAIL>; done
  • Replace <IMAGE_PULL_SECRET_NAME> with your image pull secret name.
  • Replace <YOUR_REGISTRY> with your registry URL. Ensure you are also adding your namespace as TrueFoundry will preserve the namespace structure of the images.
  • Replace <USERNAME> with your registry username.
  • Replace <PASSWORD> with your registry password.
  • Replace <EMAIL> with your registry email.
By default, the control plane uses the TrueFoundry Auth Server for user authentication. However, you can configure it to use your own external identity provider instead. We support both OIDC and SAML-compliant identity providers. Read more
The TrueFoundry control plane supports SSL connections to PostgreSQL. You can configure SSL by setting the DB_SSL_MODE environment variable in your truefoundry-values.yaml.Supported DB_SSL_MODE values:
ModeEncryptionCertificate ValidationUse Case
disableNoNoLocal development or trusted networks
no-verifyYesNoManaged databases with self-signed or unverified certs
requireYesYes (system CA store)When you have a valid CA certificate and want full verification
verify-caYesYes (custom CA)Same as require but explicitly checks CA
verify-fullYesYes (CA + hostname)Strictest mode, validates CA and hostname
SSL certificate environment variables:
VariablePurposeRequired
DB_SSL_CA_PATHPath to the server CA certificate fileFor require, verify-ca, or verify-full modes
DB_SSL_CERT_PATHPath to the client certificate file (for mTLS)Only for mTLS (GCP Cloud SQL, Azure Database for PostgreSQL)
DB_SSL_KEY_PATHPath to the client private key file (for mTLS)Only for mTLS (GCP Cloud SQL, Azure Database for PostgreSQL)
The certificate requirements vary by cloud provider. AWS RDS only needs the server CA bundle (DB_SSL_CA_PATH), while GCP Cloud SQL and Azure Database for PostgreSQL may require all three certificate paths when client certificate authentication (mTLS) is enabled. Refer to the cloud-specific control plane documentation for detailed examples.
Scenario 1: Encrypted connection without certificate validation (no-verify)This is the simplest option for managed databases. It encrypts the connection but skips server certificate validation.
truefoundry-values.yaml
servicefoundryServer:
  env:
    DB_SSL_MODE: "no-verify"
mlfoundryServer:
  env:
    DB_SSL_MODE: "no-verify"
Scenario 2: Encrypted connection with certificate validation (require)This mode encrypts the connection and validates the server certificate. You must provide the appropriate certificate files for your database provider. The example below shows the full configuration with all three certificate paths (for GCP/Azure mTLS). For AWS RDS, only DB_SSL_CA_PATH is needed.Create a Kubernetes Secret containing your certificate files:
# Server CA only (e.g. AWS RDS)
kubectl create secret generic db-ssl-certs \
  --from-file=ca-certificate.crt=/path/to/your/ca-certificate.crt \
  -n truefoundry

# Full mTLS (e.g. GCP Cloud SQL, Azure Database for PostgreSQL)
kubectl create secret generic db-ssl-certs \
  --from-file=ca-certificate.crt=/path/to/server-ca.pem \
  --from-file=client-cert.pem=/path/to/client-cert.pem \
  --from-file=client-key.pem=/path/to/client-key.pem \
  -n truefoundry
Then configure truefoundry-values.yaml to mount the certificates and set the SSL paths:
truefoundry-values.yaml
servicefoundryServer:
  env:
    DB_SSL_MODE: "require"
    DB_SSL_CA_PATH: "/etc/ssl/custom/ca-certificate.crt"
    # Only needed for mTLS (GCP Cloud SQL, Azure Database for PostgreSQL)
    DB_SSL_CERT_PATH: "/etc/ssl/custom/client-cert.pem"
    DB_SSL_KEY_PATH: "/etc/ssl/custom/client-key.pem"
  extraVolumes:
    - name: db-ssl-certs
      secret:
        secretName: db-ssl-certs
  extraVolumeMounts:
    - name: db-ssl-certs
      mountPath: /etc/ssl/custom
      readOnly: true
mlfoundryServer:
  env:
    DB_SSL_MODE: "require"
    DB_SSL_CA_PATH: "/etc/ssl/custom/ca-certificate.crt"
    # Only needed for mTLS (GCP Cloud SQL, Azure Database for PostgreSQL)
    DB_SSL_CERT_PATH: "/etc/ssl/custom/client-cert.pem"
    DB_SSL_KEY_PATH: "/etc/ssl/custom/client-key.pem"
  extraVolumes:
    - name: db-ssl-certs
      secret:
        secretName: db-ssl-certs
  extraVolumeMounts:
    - name: db-ssl-certs
      mountPath: /etc/ssl/custom
      readOnly: true
Upgrade the Helm release to apply the changes:
helm upgrade --install truefoundry oci://tfy.jfrog.io/tfy-helm/truefoundry -n truefoundry --create-namespace -f truefoundry-values.yaml
TrueFoundry ships with a built-in monitoring stack that includes Grafana dashboards for the control plane. To enable it, add the following to your truefoundry-values.yaml:
truefoundry-values.yaml
truefoundryMonitoring:
  enabled: true
  grafana:
    grafana.ini:
      auth.jwt:
        jwk_set_url: >-
          https://<your-truefoundry-control-plane-url>/api/svc/v1/keys/<tenant-name>/jwks
Then upgrade the Helm release to apply the changes:
helm upgrade --install truefoundry oci://tfy.jfrog.io/tfy-helm/truefoundry \
  -n truefoundry --create-namespace \
  -f truefoundry-values.yaml
Once enabled, platform admins can access the Grafana dashboard at:
https://<your-truefoundry-control-plane-url>/admin/grafana/
  • Replace <your-truefoundry-control-plane-url> with your actual control plane domain (e.g., app.example.com) and <tenant-name> with your TrueFoundry tenant name provided during onboarding.
  • Only users with the admin role can access this endpoint.
  • Make sure to include the trailing / at the end of the URL.
  • If you already have Prometheus or VictoriaLogs in your cluster, you can point the monitoring stack to them using externalServices instead of installing new instances.
For the full configuration reference, see the Control Plane Monitoring guide.