AI-Q Kubernetes Deployment

Deploy AI-Q from the cloned repository using the local Helm chart.

Looking to install from the NGC Helm repository? Refer to the Helm README instead.

Prerequisites

• Kubernetes cluster (EKS, GKE, AKS, etc.) or local cluster (Kind, Minikube)
• kubectl configured with cluster access
• helm v3.x installed
• An aiq-credentials Secret with database credentials and required API keys.

Deploy

Create the namespace and required user-supplied credentials first:

The source chart derives every namespaced resource from Helm's .Release.Namespace, supplied with -n. This guide uses ns-aiq; if you choose a different namespace, use it consistently for the Helm release, Secrets, kubectl commands, and external identity bindings. Setting aiq.namespace.create=true controls whether the chart renders a Namespace object; it does not override the release namespace.

kubectl create namespace ns-aiq --dry-run=client -o yaml | kubectl apply -f -

DB_USER_NAME="${DB_USER_NAME:-aiq}"
DB_USER_PASSWORD="${DB_USER_PASSWORD:-aiq_dev}" # pragma: allowlist secret

kubectl create secret generic aiq-credentials -n ns-aiq \
  --from-literal=DB_USER_NAME="$DB_USER_NAME" \
  --from-literal=DB_USER_PASSWORD="$DB_USER_PASSWORD" \
  --from-literal=NVIDIA_API_KEY="$NVIDIA_API_KEY" \
  --from-literal=TAVILY_API_KEY="$TAVILY_API_KEY"

Then install the chart:

helm dependency update deployment-k8s/
helm install aiq deployment-k8s/ -n ns-aiq

The default source install creates the PostgreSQL init ConfigMap. The credentials Secret is user-supplied so API keys are provided explicitly.

If pulling images from NGC, include the image pull secret and repository overrides:

helm dependency update deployment-k8s/
helm install aiq deployment-k8s/ -n ns-aiq --create-namespace \
  --set 'aiq.apps.backend.imagePullSecrets[0].name=ngc-secret' \
  --set 'aiq.apps.frontend.imagePullSecrets[0].name=ngc-secret' \
  --set aiq.apps.backend.image.repository=nvcr.io/nvidia/blueprint/aiq-agent \
  --set aiq.apps.frontend.image.repository=nvcr.io/nvidia/blueprint/aiq-frontend

Verify

kubectl get pods -n ns-aiq

Expected output:

NAME                            READY   STATUS    RESTARTS   AGE
aiq-backend-xxx                 1/1     Running   0          30s
aiq-frontend-xxx                1/1     Running   0          30s
aiq-postgres-xxx                1/1     Running   0          30s

Health Check

kubectl port-forward -n ns-aiq svc/aiq-backend 8000:8000 &
curl http://localhost:8000/live
curl http://localhost:8000/health

The backend liveness probe uses /live, which checks only that the API process responds. The readiness probe uses /health, so database or content-encryption outages remove the pod from service without triggering a restart loop.

Configuration, FRAG, Secrets, and Access

These topics apply to all deployment methods and are documented in the Helm README:

• Configuration — switching workflow configs (LlamaIndex vs FRAG)
• FRAG Integration — connecting to a RAG Blueprint deployment
• Secrets — required API keys and database credentials (DB_USER_NAME=aiq, DB_USER_PASSWORD=aiq_dev by default)
• Access the application — port-forwarding to the UI and API

Upgrade

helm upgrade aiq deployment-k8s/ -n ns-aiq

Uninstall

helm uninstall aiq -n ns-aiq

# Optionally remove namespace and secrets
kubectl delete namespace ns-aiq

Troubleshooting

Refer to the Helm README — Troubleshooting for common issues (pod status, logs, image pull errors, FRAG connection issues).

---

Getting Started with Minimal K8s (Kind)

For local development with a Kind cluster, you can build images locally and load them directly into the cluster — no registry push required.

1. Build the images

Run the following from the repository root:

# Backend
docker build --platform linux/amd64 \
  -f deploy/Dockerfile \
  -t aiq-agent:dev \
  .

# Frontend
docker build --platform linux/amd64 \
  -f frontends/ui/deploy/Dockerfile \
  -t aiq-frontend:dev \
  frontends/ui

This produces two local images:

• aiq-agent:dev — backend (Python / FastAPI)
• aiq-frontend:dev — frontend (Next.js)

2. Load the images into Kind

kind load docker-image aiq-agent:dev --name <your-cluster-name>
kind load docker-image aiq-frontend:dev --name <your-cluster-name>

Run kind get clusters if you are unsure of the cluster name.

3. Configure values to use the local images

Edit deployment-k8s/values.yaml (or pass --set flags at deploy time) so the image references match what you loaded:

aiq:
  apps:
    backend:
      image:
        repository: aiq-agent
        tag: dev
        pullPolicy: IfNotPresent
    frontend:
      image:
        repository: aiq-frontend
        tag: dev
        pullPolicy: IfNotPresent

Or pass them inline during deployment:

helm upgrade --install aiq deployment-k8s/ -n ns-aiq --create-namespace \
  --set aiq.apps.backend.image.repository=aiq-agent \
  --set aiq.apps.backend.image.tag=dev \
  --set aiq.apps.backend.image.pullPolicy=IfNotPresent \
  --set aiq.apps.frontend.image.repository=aiq-frontend \
  --set aiq.apps.frontend.image.tag=dev \
  --set aiq.apps.frontend.image.pullPolicy=IfNotPresent

4. Create credentials and deploy

Create the aiq-credentials Secret shown above, then deploy.

After a rebuild, reload the updated image with kind load docker-image ... and restart the affected deployment:

kubectl rollout restart deployment -n ns-aiq aiq-backend   # or aiq-frontend