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 on your workstation using one of the options below.

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

# 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

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

User Budget & Rate Limits

These control the defaults applied to every new user on first OAuth login. Existing users are not affected by changes — update them via the admin UI or API.

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
• Promote at least one user to admin: oc adm groups add-users litemaas-admins user@redhat.com, then have them log in via the frontend
• Set up key cleanup cron (production): ./setup-key-cleanup-cronjob.sh <namespace>
• Configure backup cron (production): ./setup-litemaas-backup-cronjob.sh <namespace> <s3-bucket>

Adding Admin Users

LiteMaaS determines admin access by checking OpenShift group membership at OAuth login time. Users in the litemaas-admins OCP Group are granted the admin role automatically when they log in.

Step 1 — Add the user to the litemaas-admins group

# Add a user to the litemaas-admins OCP group
oc adm groups add-users litemaas-admins user@redhat.com

# Verify group membership
oc get group litemaas-admins -o yaml

Step 2 — User logs in via the frontend

Have the user visit the LiteMaaS frontend and log in with their OpenShift credentials. The backend reads their group membership from OCP during the OAuth callback and assigns the admin role automatically. No further action is needed.

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