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 coming soon!
Guide
1
Install requirements
EKS requires the AWS CLI and kubectl CLI.
- Download and install the AWS CLI
- Download and install kubectl CLI
2
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 Onyx’s
Persistent Volume Claims - Keep the other default add-ons enabled
- Review and click Create
3
Add nodes
Once the cluster is active, add worker nodes where Onyx 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 organization 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.2xlargemachines (orc5.4xlargeif 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
4
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
5
Fetch kubeconfig
Log in to the AWS CLI and provide the access key and secret key from the IAM user we just created:Configure your kubeconfig to connect to the cluster by filling in the
region-code and cluster-name:Reference AWS EKS kubeconfig docs.
6
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 Add the Onyx Helm repository:Create a dedicated namespace and install Onyx:This will pull the latest Onyx chart and deploy all dependencies.
gp2 storage class is set as the default storage class (required for PVCs):7
Verify the installation
Running state before accessing Onyx.To check the API server logs (often the last to become ready):8
Access Onyx