Prerequisites

Before running the deployment playbook, verify these requirements are met.

Cluster Requirements

• Red Hat OpenShift 4.12 or later
• Cluster admin privileges (or namespace admin with the ability to create Routes and OAuthClients)
• Sufficient compute capacity: minimum 4 CPU cores and 8 GB RAM allocatable for the LiteMaaS components alone
• A default StorageClass that supports ReadWriteOnce PVCs (or specify one explicitly)
• Outbound internet access to pull images from quay.io and registry.redhat.io

Local Workstation Requirements

• Ansible 2.14+ with kubernetes.core collection
• oc CLI authenticated to the target cluster
• python3 with kubernetes and openshift pip packages

# Install Python dependencies
pip install kubernetes openshift

# Install required Ansible collections
ansible-galaxy collection install kubernetes.core community.general

Image Registry Access

The deployment pulls images from two registries. Verify cluster access before starting:

Collection Installation

LiteMaaS is distributed as an Ansible collection. Install it from the repository or via Ansible Galaxy.

Option A: From GitHub (Recommended for RHDP)

# Clone the collection repository
git clone https://github.com/rhpds/rhpds.litemaas.git ~/work/code/rhpds.litemaas
cd ~/work/code/rhpds.litemaas

# Install the collection locally
ansible-galaxy collection install . --force

Option B: In AgnosticV (RHDP Catalog Items)

For catalog-deployed workloads, add the collection to your AgnosticV common.yaml:

# In agnosticv/config/catalog-item/common.yaml
requirements_collections:
  - name: rhpds.litemaas
    source: https://github.com/rhpds/rhpds.litemaas.git
    type: git
    version: main

workloads:
  - rhpds.litemaas.ocp4_workload_litemaas

Option C: Helm Chart (Kubernetes / OpenShift, no Ansible)

# Add the chart repository (if published) or install from local path
helm install litemaas ~/work/code/rh-litemaas/deployment/helm/litemaas/ \
  --namespace litemaas \
  --create-namespace \
  -f my-values.yaml

Deployment

Step 1: Configure Variables

Create an extra vars file. At minimum you need to set the namespace and decide whether to enable OAuth.

# litemaas-vars.yml
---
ocp4_workload_litemaas_namespace: "litemaas"

# OAuth login (recommended for production)
ocp4_workload_litemaas_oauth_enabled: true

# Scale LiteLLM replicas (default 3)
ocp4_workload_litemaas_ha_litellm_replicas: 3

# Enable RHDP branding
ocp4_workload_litemaas_branding_enabled: true

# Route prefix customization (optional)
ocp4_workload_litemaas_api_route_prefix: "litellm-prod"
ocp4_workload_litemaas_frontend_route_prefix: "litellm-prod-frontend"
ocp4_workload_litemaas_admin_route_prefix: "litellm-prod-admin"

# Pre-configure models (optional — can also be done via UI after deploy)
ocp4_workload_litemaas_litellm_models:
  - model_name: "granite-3-2-8b-instruct"
    litellm_model: "openai/granite-3-2-8b-instruct"
    api_base: "http://granite-3-2-8b-instruct-predictor.llm-hosting.svc.cluster.local/v1"
    api_key: "sk-placeholder"
    rpm: 120
    tpm: 200000

Step 2: Run the Playbook

# Deploy LiteMaaS in HA mode
ansible-playbook playbooks/deploy_litemaas_ha.yml \
  -e @litemaas-vars.yml

# Or pass variables inline
ansible-playbook playbooks/deploy_litemaas_ha.yml \
  -e ocp4_workload_litemaas_namespace=litemaas \
  -e ocp4_workload_litemaas_oauth_enabled=true \
  -e ocp4_workload_litemaas_branding_enabled=true

Step 3: Deployment Order

The HA task deploys components in this sequence. Each component waits for its predecessor to be ready before continuing:

Step 4: Post-Deploy Output

After successful deployment, the playbook prints connection details via agnosticd_user_info:

# Example output
LiteLLM Admin Portal: https://litellm-prod.apps.cluster.example.com
LiteLLM Admin Login: admin / <auto-generated-password>
LiteLLM Master API Key: sk-<auto-generated-key>
LiteMaaS User Interface: https://litellm-prod-frontend.apps.cluster.example.com

Complete Variable Reference

All variables with their defaults from roles/ocp4_workload_litemaas/defaults/main.yml.

Core Settings

Image Configuration

Route Configuration

Credentials (Auto-Generated)

PostgreSQL Configuration

HA-Specific Variables

OAuth Configuration

Resource Limits

Cloud-Specific Storage Classes

When ocp4_workload_litemaas_postgres_storage_class is empty, the role auto-detects the cloud provider and selects the appropriate StorageClass:

LiteLLM Database Migration

LiteLLM uses Prisma ORM and runs database migrations automatically on startup. However, when upgrading between LiteLLM versions, you may need to trigger a migration manually if automatic migration fails or is skipped.

Check Migration Status

# Check LiteLLM logs for migration output
oc logs -n litellm-rhpds deployment/litellm --tail=100 | grep -i migrat

# Check if database tables exist
oc exec -n litellm-rhpds litellm-postgres-0 -- \
  psql -U litellm -d litellm -c "\dt"

Run Migration Manually

# Get the DATABASE_URL from the running LiteLLM deployment
DB_URL=$(oc exec -n litellm-rhpds deployment/litellm -- \
  sh -c 'echo $DATABASE_URL')

# Exec into a LiteLLM pod and run migration
LITELLM_POD=$(oc get pods -n litellm-rhpds -l app=litellm \
  -o jsonpath='{.items[0].metadata.name}')

oc exec -n litellm-rhpds $LITELLM_POD -- \
  python -c "from litellm.proxy.proxy_server import prisma_client; prisma_client.db.migrate.deploy()"

# Alternative: restart the deployment (migration runs on startup)
oc rollout restart deployment/litellm -n litellm-rhpds
oc rollout status deployment/litellm -n litellm-rhpds

Post-Install Checklist

After deployment completes, verify the following before announcing the service to users.

• All pods are Running: oc get pods -n <namespace> — expect litellm (3), litellm-backend (3), litellm-frontend (3), litellm-postgres-0, litellm-redis-*
• All routes resolve: test the API, frontend, and admin routes in a browser
• LiteLLM health check passes: curl https://<api-route>/health/livenessz
• LiteLLM admin UI accessible: log in with the generated credentials at the API route URL
• LiteMaaS frontend loads: visit the frontend route, verify it shows the login page
• OAuth login works (if enabled): click Login, authenticate with OpenShift, verify redirect works
• At least one model is configured: use the LiteLLM admin UI to add and test a model
• Model is visible in LiteMaaS frontend: check that models appear in the catalog after sync
• Test subscription flow: as a non-admin user, subscribe to a model and retrieve an API key
• Test API key: make a curl request with the issued virtual key, verify response
• Retrieve and save admin credentials: oc get secret litellm-secret -n <ns> -o yaml
• Set up key cleanup cron (production): ./setup-key-cleanup-cronjob.sh <namespace>
• Configure backup cron (production): ./setup-litemaas-backup-cronjob.sh <namespace> <s3-bucket>

Resource Summary (Standard HA Deployment)

Removal / Uninstall

# Remove via playbook (cleanly removes OAuthClient too)
ansible-playbook playbooks/deploy_litemaas_ha.yml \
  -e ocp4_workload_litemaas_namespace=litemaas \
  -e ocp4_workload_litemaas_remove=true

# Or delete the namespace directly (OAuthClient persists — clean it up separately)
oc delete namespace litemaas
oc delete oauthclient litemaas