Helm chart Installation steps

This guide walks you through deploying Patronus AI on Kubernetes using the official Helm charts.

Prerequisites

Before starting the deployment, ensure you have completed all prerequisites.

Required tools

• Kubernetes cluster version 1.23 or above
• Helm version 3.8.0 or above
• kubectl configured to access your cluster
• Docker credentials for accessing Patronus AI images

Step 1: Container registry setup

Using internal registry (recommended)

If you've set up an internal container registry as described in the Prerequisites, create a Kubernetes secret for your internal registry:

kubectl create secret docker-registry regcred \
  --docker-server=<YOUR_INTERNAL_REGISTRY> \
  --docker-username=<REGISTRY_USERNAME> \
  --docker-password=<REGISTRY_PASSWORD> \
  --namespace=<YOUR_NAMESPACE>

Migrating images to your internal registry:

1. Pull images from Docker Hub:

docker login --username <PATRONUS_USERNAME> --password <PATRONUS_PASSWORD>
docker pull patronusdevops/patronus-backend:<TAG>

2. Tag and push to your internal registry:

docker tag patronusdevops/patronus-backend:<TAG> <YOUR_INTERNAL_REGISTRY>/patronus-backend:<TAG>
docker push <YOUR_INTERNAL_REGISTRY>/patronus-backend:<TAG>

3. Repeat for all required images (see Docker images reference below)

Using Patronus registry directly

If using the Patronus registry directly (not recommended for production), create a secret with Patronus credentials:

kubectl create secret docker-registry regcred \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=<PATRONUS_USERNAME> \
  --docker-password=<PATRONUS_PASSWORD> \
  --namespace=<YOUR_NAMESPACE>

Verify registry access

You can verify your registry credentials by pulling an image locally:

docker pull <YOUR_INTERNAL_REGISTRY>/patronus-backend:<TAG>

If successful, you should see the image listed:

docker image ls | grep patronus-backend

Step 2: Add Patronus Helm repository

Add the official Patronus AI Helm repository to your Helm client:

helm repo add patronus-ai https://patronus-ai.github.io/helm-charts
helm repo update

Verify the repository was added successfully:

helm search repo patronus-ai

Expected output:

NAME                            CHART VERSION   APP VERSION             DESCRIPTION
patronus-ai/patronus-stack      0.13.4          2025-02-13-12-40        A Helm chart for Kubernetes

Step 3: Configure values.yaml

Obtain example configuration

Request example values.yaml configuration files from the Patronus AI team. These files contain pre-configured settings for different deployment scenarios.

Required configuration values

Update the following values in your values.yaml file:

Global configuration

global:
  # Image configuration
  image:
    registry: <YOUR_INTERNAL_REGISTRY>  # e.g., registry.mycompany.com
    tag: <GLOBAL_IMAGE_TAG>  # e.g., "2025-02-13-12-40"
 
  # Security keys (generate securely!)
  admin_secret: <GLOBAL_ADMIN_SECRET>
 
  # PostgreSQL configuration
  postgresql:
    auth:
      username: patronusai
      password: <GLOBAL_POSTGRESQL_PASSWORD>
      database: backend_db
 
  # Redis configuration
  redis:
    password: <GLOBAL_REDIS_PASSWORD>

Post-installation configuration

# Post-installation configuration
postinstall:
  enabled: true
  customerName: <POST_INSTALL_CUSTOMER_NAME>
  executeMigrations: "true"
  executeSeed: "true"

Networking and ingress

For detailed ingress configuration with different Identity Providers, see:

• Deployment in AWS with Amazon Cognito
• Deployment in Azure with Microsoft Entra ID
• Deployment in GCP with Google Identity
• Common deployment options for cert-manager and ExternalDNS

Configuration reference

Step 4: Verify Kubernetes connectivity

Before deploying, verify you can connect to your Kubernetes cluster:

kubectl get nodes
kubectl get namespaces

Create the namespace for Patronus AI if it doesn't exist:

kubectl create namespace patronus

Step 5: Deploy Patronus stack

Install the Patronus AI stack using Helm:

helm upgrade patronus-stack patronus-ai/patronus-stack \
  --install \
  --create-namespace \
  --namespace patronus \
  --values ./values.yaml

Command options explained

• upgrade: Upgrades the release if it exists, or installs it if it doesn't
• --install: Install the release if it doesn't already exist
• --create-namespace: Create the namespace if it doesn't exist
• --namespace: Kubernetes namespace to deploy into
• --values: Path to your customized values.yaml file

Expected output

If successful, you should see:

Release "patronus-stack" has been upgraded. Happy Helming!
NAME: patronus-stack
LAST DEPLOYED: <timestamp>
NAMESPACE: patronus
STATUS: deployed
REVISION: 1

Step 6: Validate deployment

Check pod status

Monitor the deployment progress:

kubectl get pods -n patronus

Wait for all pods to reach Running status. This may take several minutes.

kubectl get pods -n patronus -w

Check ingress

If you configured ingress controllers:

kubectl get ingress -n patronus

Verify logs

First, check the post-installation job to ensure database migrations and seeding completed successfully:

# Check post-install job status
kubectl get jobs -n patronus | grep post-install
 
# View complete post-install logs
kubectl logs -n patronus job/patronus-post-install

Check the logs of core services for any errors:

# Backend API logs
kubectl logs -n patronus deployment/patronus-backend --tail=50
 
# Frontend app logs
kubectl logs -n patronus deployment/patronus-app --tail=50
 
# Admin portal logs
kubectl logs -n patronus deployment/patronus-admin-portal --tail=50

Step 7: Post-deployment configuration

Access the application

Depending on your ingress configuration, access the Patronus AI application at:

• Frontend: https://<PATRONUS_APP_HOST>
• Admin Portal: https://<PATRONUS_ADMIN_PORTAL_HOST>
• API: https://<PATRONUS_BACKEND_API_HOST>

Configure accounts and authentication

Follow the Accounts and Authentication guide to:

1. Create your first account
2. Configure role mappings (for IdP)
3. Set up user authentication

Troubleshooting

Pods not starting

Check pod events and logs:

kubectl describe pod <pod-name> -n patronus
kubectl logs <pod-name> -n patronus

Common issues:

• Image pull errors: Verify the regcred secret is created correctly
• Pending pods: Check node resources and scheduling constraints
• CrashLoopBackOff: Review pod logs for application errors

Database connection errors

Verify PostgreSQL is running and accessible:

kubectl get pods -n patronus | grep postgresql
kubectl logs -n patronus <postgresql-pod-name>

Check database credentials in your values.yaml match the configuration.

Ingress not working

Verify ingress controller is installed and running:

kubectl get pods -n <ingress-namespace>
kubectl get ingress -n patronus

Check ingress annotations and TLS configuration.

Upgrading

To upgrade to a newer version of Patronus AI:

1. Update the Helm repository:

helm repo update

2. Check available versions:

helm search repo patronus-ai/patronus-stack --versions

3. Update your values.yaml with the new image tag

4. Run the upgrade:

helm upgrade patronus-stack patronus-ai/patronus-stack \
  --namespace patronus \
  --values ./values.yaml

Uninstalling

To completely remove Patronus AI:

helm uninstall patronus-stack --namespace patronus

Additional resources

• Patronus Helm Charts Repository
• Helm Documentation
• Common deployment options
• Architecture overview

Docker images reference

Private images (require authentication)

• patronus-backend
• patronus-migrate
• patronus-evaluation-api
• patronus-accounts-api
• patronus-app
• patronus-admin-portal
• patronus-trace-insights-api
• Evaluator images:
  • evaluator-sdk-judge
  • evaluator-sdk-judge-mm
  • evaluator-sdk-hallucination
  • evaluator-sdk-pii
  • evaluator-sdk-toxicity
  • evaluator-sdk-glider
  • evaluator-sdk-lynx
  • evaluator-sdk-answer-relevance
  • evaluator-sdk-context-relevance
  • evaluator-sdk-context-sufficiency
  • And more...

Public images

• Hasura GraphQL Engine: hasura/graphql-engine:v2.26.x
• Vouch Proxy: quay.io/vouch/vouch-proxy:0.39
• PostgreSQL: bitnamilegacy/postgresql:17.x
• Redis: bitnamilegacy/redis:7.2.x
• NGINX: bitnamilegacy/nginx:1.27.x

Next steps

Once deployment is complete, proceed to:

1. Accounts and Authentication - Set up user accounts and access control
2. Model Installation - Deploy containerized models (optional)
3. Explore deployment options:
   • Deployment in AWS with Amazon Cognito
   • Deployment in Azure with Microsoft Entra ID
   • Deployment in GCP with Google Identity

← Back to Self Hosting Guide