Operator reference

EKS

Deploy Nexus on AWS EKS

Before you begin

This reference describes the underlying platform. Use a Nexus school release with its school membership, class policy, and cost controls. Installing a base engine alone does not add those controls.

EKS has recently updated their cluster and node group creation process. The contents of this guide are still relevant, but the flow has changed slightly.

Updates to this guide are Not available in this reference!

Guide#

Install requirements#

EKS requires the AWS CLI and kubectl CLI.

Download and install the AWS CLI
Download and install kubectl CLI

Create the cluster#

For this guide, we will use 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

If you do not see the newly created role in the dropdown, click the refresh button in the UI.

For Kubernetes version, select a version with standard support
Choose Standard upgrade policy
Add the Amazon EBS CSI Driver add-on for Nexus's Persistent Volume Claims
Keep the other default add-ons enabled
Review and click Create

The cluster may take several minutes to become ready

Add nodes#

Once the cluster is active, add worker nodes where Nexus services will run.

On the Cluster page, select the Compute tab and click Add node group
Provide a Name for the group (e.g., onyx-node-group)
For Node IAM role, either select an existing role used by your school or create a new one.

Ensure the role has the AmazonEBSCSIDriverPolicy attached so that PVCs can be fulfilled. If creating a role, add this policy in addition to the default policies.

Replace the Instance types with c5.2xlarge machines (or c5.4xlarge if you plan to scale beyond 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.
Maximum unavailable can remain at the default
Keep the default networking configuration and click Create

It may take up to 15 minutes for the compute nodes to come online.

Create and connect a user#

We will need an IAM user with CLI access to manage AWS and the cluster.

Navigate to the IAM Dashboard, select Users in the left sidebar, and click Create user
Give the user a descriptive name (e.g., onyx-eks-user)
Under permissions, click Attach policies directly and attach:
AmazonEKSClusterPolicy
AmazonEKSServicePolicy
Click Create user
On the user's page, click Create access key and follow the prompts.
Select the Command Line Interface (CLI) option during creation.

Save the Access key and Secret access key for later!

Navigate back to the EKS cluster and select Access and then Create access entry
In IAM principal, select the IAM ARN we just created, then click Next
For Access policies, set Policy name to AmazonEKSClusterAdminPolicy, then click Next and Create

Fetch kubeconfig#

  aws configure

Configure your kubeconfig to connect to the cluster by filling in the region-code and cluster-name:

  aws eks update-kubeconfig --region region-code --name cluster-name

Reference AWS EKS kubeconfig docs.

Install Onyx services#

The Onyx Helm chart packages all the required services (API, web, PostgreSQL, Vespa, etc.) into a single deployment. By default, persistent volumes will be created for stateful services.

First, ensure the gp2 storage class is set as the default storage class (required for PVCs):

  kubectl patch storageclass gp2 -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Add the Onyx Helm repository:

  helm repo add onyx https://onyx-dot-app.github.io/onyx/
  helm repo update
  helm search repo onyx

Create a dedicated namespace and install Onyx:

  kubectl create namespace onyx
  helm install onyx onyx/onyx -n onyx

This will pull the latest Onyx chart and deploy all dependencies.

Verify the installation#

  helm list -n onyx
  kubectl get pods -n onyx

Wait until all pods are in a Running state before accessing Onyx.

To check the API server logs (often the last to become ready):

  kubectl -n onyx get pods | grep api-server | awk '{print $1}' | xargs -I {} kubectl -n onyx logs {} -f

Access Onyx#

For local testing, port-forward:

  kubectl -n onyx port-forward service/onyx-nginx 8080:80

Then open http://localhost:8080.

Upgrading#

To upgrade Onyx services, first update the Helm repository:

helm repo update
helm upgrade onyx onyx/onyx -n onyx

To upgrade to a specific version, use:

helm upgrade onyx onyx/onyx -n onyx --version <VERSION>

Uninstalling#

To remove the Onyx services:

helm uninstall onyx -n onyx

Vespa, Postgres, and MinIO leave behind PVCs. To delete them:

kubectl -n onyx get pvc
kubectl -n onyx delete pvc vespa-storage-da-vespa-0
kubectl -n onyx delete pvc onyx-minio
kubectl -n onyx delete pvc data-onyx-postgresql-0