Kubernetes & Helm Deployments

Relevant source files

The following files were used as context for generating this wiki page:

• deployment/helm/README.md
• deployment/helm/charts/onyx/Chart.yaml
• deployment/helm/charts/onyx/templates/api-deployment.yaml
• deployment/helm/charts/onyx/templates/webserver-deployment.yaml
• deployment/helm/charts/onyx/templates/indexing-model-deployment.yaml
• deployment/helm/charts/onyx/templates/celery-worker-docfetching.yaml
• deployment/helm/charts/onyx/templates/celery-beat.yaml
• deployment/helm/charts/onyx/templates/slackbot.yaml
• deployment/terraform/modules/aws/README.md

Onyx is deployed to Kubernetes environments using Helm charts, which orchestrate the complex interaction between its modular services. The deployment architecture leverages horizontal scaling for core components like the API server and web server, while utilizing specialized workers for background tasks such as document fetching and indexing.

The system is designed to be cloud-agnostic but provides specific optimizations for AWS through Terraform modules, supporting managed services like Amazon EKS, RDS for PostgreSQL, and ElastiCache for Redis. For search capabilities, it integrates with Vespa or OpenSearch as vector databases.

Sources: deployment/helm/README.md, deployment/terraform/modules/aws/README.md:3-12, deployment/helm/charts/onyx/Chart.yaml:20-50

Core Component Architecture

The Onyx Helm chart manages several discrete deployments that work together to provide the search and AI platform.

API and Web Servers

The API server acts as the central hub for the backend, handling requests via FastAPI and managing database migrations through Alembic during the container startup phase. The web server handles the frontend Next.js application.

The diagram above illustrates the high-level flow of user traffic through the ingress to the core Onyx services and their respective data stores.
Sources: deployment/helm/charts/onyx/templates/api-deployment.yaml:68-72, deployment/helm/charts/onyx/templates/webserver-deployment.yaml, deployment/helm/charts/onyx/Chart.yaml:37-41

Background Processing (Celery)

Onyx utilizes Celery for asynchronous task management. This includes a celery-beat scheduler for periodic tasks and specialized workers for intensive operations like document fetching.

• Celery Beat: Orchestrates periodic task scheduling.
• Docfetching Worker: Specifically handles fetching documents from external connectors.
• Indexing Model: A specialized model server used during the indexing pipeline to process and embed documents.

Sources: deployment/helm/charts/onyx/templates/celery-beat.yaml, deployment/helm/charts/onyx/templates/celery-worker-docfetching.yaml:62-71, deployment/helm/charts/onyx/templates/indexing-model-deployment.yaml:58-61

Scaling and Autoscaling

Onyx supports two primary methods for scaling pods automatically:

1. HorizontalPodAutoscaler (HPA): The default engine, which scales pods based on resource metrics.
2. KEDA (Kubernetes Event-driven Autoscaling): An optional engine that allows for more complex scaling triggers. When autoscaling.engine is set to keda, the chart renders ScaledObject templates instead of standard HPAs.

Sources: deployment/helm/README.md:59-71

Component	Default Replica Count	Scaling Capability
API Server	Configurable	HPA / KEDA
Web Server	Configurable	HPA / KEDA
Celery Workers	Configurable	HPA / KEDA
Indexing Model	Configurable	Static Replicas

Sources: deployment/helm/charts/onyx/templates/api-deployment.yaml:12-14, deployment/helm/charts/onyx/templates/indexing-model-deployment.yaml:15, deployment/helm/README.md:59-65

Security and Identity

Container Security

Onyx supports running as a non-root user for improved security posture. This is configured through securityContext and podSecurityContext settings in the Helm values.

# Example Security Context for Non-Root Execution
securityContext:
  runAsNonRoot: true
  runAsUser: 1001

Sources: deployment/helm/README.md:43-53

AWS Integration (IRSA)

When deployed on AWS EKS, Onyx can use IAM Roles for Service Accounts (IRSA). This allows the application to access S3 buckets without needing static credentials stored in secrets. The Terraform eks module creates an IRSA role and a Kubernetes ServiceAccount (defaulting to onyx-s3-access).

Sources: deployment/terraform/modules/aws/README.md:126-133

Deployment Infrastructure (Terraform)

For AWS deployments, Onyx provides a set of Terraform modules to provision the required infrastructure.

The diagram shows how the Terraform modules establish the network and managed services required before the Helm chart is applied.
Sources: deployment/terraform/modules/aws/README.md:14-25

Managed Service Modules

• VPC: Sized specifically for EKS with public and private subnets.
• EKS: Provisions the cluster, node groups, and essential addons like EBS CSI and Metrics Server.
• Postgres (RDS): Manages the relational database.
• Redis (ElastiCache): Handles caching and Celery message brokering.
• OpenSearch: Optional managed search domain.

Sources: deployment/terraform/modules/aws/README.md:82-120

Health and Monitoring

Deployments include liveness and readiness probes to ensure traffic is only routed to healthy pods. Celery workers use a specialized Python-based probe script (onyx/background/celery/celery_k8s_probe.py) to verify worker status rather than simple HTTP checks.

Sources: deployment/helm/charts/onyx/templates/celery-worker-docfetching.yaml:94-118, deployment/helm/charts/onyx/templates/api-deployment.yaml:83-93

Deployment Commands Reference

Operation	Command
Update Dependencies	helm dependency update .
Template Inspection	helm template test-output . --set auth.opensearch.values.opensearch_admin_password='...'
Installation	helm install onyx . -n onyx --set postgresql.primary.persistence.enabled=false
Local Access	kubectl -n onyx port-forward service/onyx-nginx 8080:80

Sources: deployment/helm/README.md:1-35

Onyx's Kubernetes deployment provides a robust, enterprise-ready platform that balances ease of installation via Helm with the deep infrastructure control required for large-scale production environments.