Skip to main content
Run Onyx on Amazon EKS when you need Kubernetes scheduling, autoscaling, or an existing cluster. This guide creates the cluster in the AWS console and installs Onyx with Helm.
To create the VPC, EKS cluster, RDS, ElastiCache, and S3 with code, use the Terraform modules. They set sane production defaults (private API endpoint, gp3 storage class, cluster autoscaler) and install the Helm chart for you.

​
Guide

1

Install requirements

2

Create the cluster

This guide uses standard settings with the EBS CSI driver.
  • Navigate to Elastic Kubernetes Service (EKS) and create a new cluster
  • For Cluster service role, create a new IAM role with a descriptive name like onyx-eks-cluster-role
  • For Kubernetes version, select a version with standard support
  • Choose Standard upgrade policy
  • Add the Amazon EBS CSI Driver add-on. Onyx uses persistent volumes for PostgreSQL, OpenSearch, and the object store
  • Keep the other default add-ons enabled
The cluster can take several minutes to become ready.EKS Cluster Creation
3

Add nodes

Once the cluster is active, add worker nodes where Onyx services run.
  • On the Cluster page, select the Compute tab and click Add node group
  • For Node IAM role, select an existing role or create a new one
The role needs the AmazonEBSCSIDriverPolicy so the cluster can create persistent volumes. If you create a role, add this policy in addition to the default policies.
  • Replace the Instance types with m7i.2xlarge machines (or m7i.4xlarge for more than 200 users or more than 100k documents)
  • Set Volume size in the 200GB - 800GB range depending on your document count
See the Resourcing guide for more details on storage requirements.
  • For most setups, set the Desired size and Minimum size to 1. You can increase these later to scale up
It can take up to 15 minutes for the compute nodes to come online.
4

Grant cluster access

Your AWS identity needs admin access to the cluster.
  • On the cluster page, select Access and then Create access entry
  • In IAM principal, select the IAM role or user you use with the AWS CLI
  • For Policy name, select AmazonEKSClusterAdminPolicy
Prefer an IAM role (for example, through AWS SSO) over a long-lived IAM user with access keys.
5

Fetch kubeconfig

Log in to the AWS CLI:
Configure your kubeconfig to connect to the cluster. Fill in the region-code and cluster-name:
Reference AWS EKS kubeconfig docs.
6

Set a default storage class

The Onyx chart creates persistent volume claims without a storage class. The cluster must have a default. Check for one:
If no class is marked (default), mark gp2 or gp3 as the default:
7

Install Onyx

The Onyx Helm chart packages all the required services (API, web, PostgreSQL, Redis, OpenSearch, object store) into a single release. By default, the chart creates persistent volumes for the stateful services.Add the Onyx Helm repository:
Create a values.yaml with the object store credentials. The chart refuses to install with empty keys:
values.yaml
Create a dedicated namespace and install Onyx:
To use RDS, ElastiCache, or S3 instead of the bundled services, see RDS and External services. Full chart options are on the Kubernetes page.
8

Verify the installation

Wait until all pods are in a Running state before you open Onyx.The API server is often the last pod to become ready. Follow its logs:
9

Access Onyx

The chart creates a LoadBalancer service named onyx-nginx. Get its hostname:
Point your DNS record at the EXTERNAL-IP hostname and set WEB_DOMAIN in values.yaml under configMap.For local testing, port-forward instead:
Then open http://localhost:8080. The first user to sign up becomes the admin.

​
Upgrading

To upgrade Onyx, update the Helm repository and reuse your values:
To upgrade to a specific chart version, use:
Chart versions differ from Onyx release versions. Run helm search repo onyx --versions to see which Onyx version (APP VERSION) each chart ships.

​
Uninstalling

To remove the Onyx services:
OpenSearch, PostgreSQL, and the object store leave behind persistent volume claims. List and delete them:

​
Next Steps

Configure Authentication

Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.

More Onyx Configuration Options

Learn about all available configuration options for your Onyx deployment.