Skip to main content

​
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 to TrueFoundry Central Auth Server:
    • https://auth.truefoundry.com
    • https://login.truefoundry.com
  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 7.8.26 \
--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.

​
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 this document.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 TrueFoundry managed Central Auth server to authenticate users. However, you can also deploy the control plane without using the TrueFoundry managed Central Auth server. We currently support any OIDC compliant Identity Provider to be used as external identity provider.You need to add your OIDC application details under servicefoundryServer.env in the values.yaml file of truefoundry helm installation.
servicefoundryServer:
  env:
    OAUTH_PROVIDER_TYPE: "EXTERNAL"
    EXTERNAL_OAUTH_ISSUER: "<OIDC_ISSUER_URL>"
    EXTERNAL_OAUTH_CLIENT_ID: "<OIDC_CLIENT_ID>"
    EXTERNAL_OAUTH_CLIENT_SECRET: "<OIDC_CLIENT_SECRET>"
    ## Other optional configuration if required
    # USE_ID_TOKEN_AS_ACCESS_TOKEN: boolean (default: false)
    # EXTERNAL_OAUTH_USER_INFO_EMAIL_KEY_NAME: string (default: "email")
    # EXTERNAL_OAUTH_USER_INFO_ID_KEY_NAME: string (default: "id")
    # EXTERNAL_OAUTH_USER_INFO_NAME_KEY_NAME: string (default: "name")
    # EXTERNAL_OAUTH_USER_INFO_FIRST_NAME_KEY_NAME: string (default: "firstName")
    # EXTERNAL_OAUTH_USER_INFO_LAST_NAME_KEY_NAME: string (default: "lastName")
    # EXTERNAL_OAUTH_USER_INFO_IMAGE_URI_KEY_NAME: string (default: "picture")
    # EXTERNAL_OAUTH_TOKEN_EMAIL_CLAIM_KEY_NAME: string (default: "email")
    # EXTERNAL_OAUTH_TOKEN_USERNAME_CLAIM_KEY_NAME: string (default: "username")
    # EXTERNAL_OAUTH_TOKEN_ID_CLAIM_KEY_NAME: string (default: "sub")
    # EXTERNAL_OAUTH_USER_INFO_USERNAME_KEY_NAME: string (default: "username")

    INCLUDE_TRUEFOUNDRY_MANAGED_JWKS: "false"
    INTERNAL_JWT_SERVICE_ENABLED: "true"
    INTERNAL_JWT_JWKS: "<INTERNAL_JWT_JWKS>" # To be provided by TrueFoundry team
tfy-llm-gateway:
  env:
    ENABLE_EXTERNAL_OAUTH: "true"
    ## If you are using a custom email claim key, you can set it here
    # EXTERNAL_OAUTH_EMAIL_CLAIM_KEY: sub
Here we are assuming the identity provider is OIDC compliant and satisfies following:
  1. Openid configuration is available at <ISSUER_URL>/.well-known/openid-configuration.
  2. Scopes configured should include openid, email, profile and offline_access.
  3. Allowed Redirect URI should be set to <CONTROL_PLANE_URL>/auth/callback.
  4. OIDC issuer servers should be accessible from user’s browser, TrueFoundry control plane servers and all multi zone AI Gateway servers.