Onboarding a K8s Cluster

Onboarding your Kubernetes (EKS) cluster to OneLens is quick and easy. By following the steps below, you will integrate your kubernetes cluster with OneLens.

RBAC Permission Required

To set up the OneLens K8 Agent, user who will be executing the Helm charts needs to have the following RBAC permissions. This is a one-time requirement.

rules:
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["*"]

Onboarding Checklist

Before you begin onboarding your cluster, make sure you have the following configuration:

1. Terminal Setup & Access

• AWS CLI installed and configured.

• AWS user credentials with appropriate access.

• Admin access to your Kubernetes cluster via kubeconfig.

• kubectl installed (make sure it matches your cluster’s version).

• A kubeconfig file containing the cluster contexts.

• Helm (version 3 or later) installed.

2. EKS Cluster Configuration

Ensure your EKS cluster meets the following requirements:

• EKS Version: Must be version 1.25 or later.

• Kubernetes nodes need a NAT gateway configured.

• Minimum Node Resources:

Cluster Size (Pods)	CPU (Cores)	Memory (GB)
< 100	0.237	1.33
100-499	0.386	1.92
500-999	0.587	3.70
1000-1499	0.696	5.47
1500-2000	0.805	7.25

3. Kubernetes Resources

• No existing namespace named onelens-agent should exist.

• Ensure that security groups and network policies allow pods to communicate properly.

4. Persistent Storage

Persistent storage must be available to support Prometheus data durability. It is recommended to preconfigure the EBS driver in your cluster to enable dynamic provisioning of Persistent Volumes. This ensures reliable storage and helps prevent data loss during pod restarts or rescheduling.

The recommended size for the associated PersistentVolumeClaim (PVC) is 10 GB.

5. Internet Accessibility

The following endpoints and container images are pulled from the internet as part of the OneLens agent setup. Make sure your Kubernetes cluster has outbound internet access to reach all of them:

Endpoints

The cluster must be able to communicate with these OneLens service URLs:

• Agent Storage Access

  https://onelens-kubernetes-agent.s3.amazonaws.com

• OneLens API Endpoint

  https://api-in.onelens.cloud

• Installation Script Access

  https://astuto-ai.github.io

Container Images

During setup, the OneLens agent pulls the following public images from internet:

• public.ecr.aws/w7k6q5m9/onelens-deployer

• public.ecr.aws/w7k6q5m9/onelens-agent

• quay.io/prometheus/prometheus

• quay.io/kubecost1/kubecost-cost-model

• quay.io/prometheus-operator/prometheus-config-reloader

• registry.k8s.io/kube-state-metrics/kube-state-metrics

• quay.io/prometheus/pushgateway

Helm Chart Artifacts

OneLens Helm chart for Onelensdeployer and Onelens-agent are hosted on GitHub Pages. These must be accessible to your cluster during installation to successfully deploy the agent.

To check the packages and source code, visit the Artifacts page.

7. EBS Driver (Recommended)

It is recommended to have the EBS driver preconfigured in your cluster. This driver is used to create Persistent Volumes for Prometheus during agent deployment. While not a hard dependency, having it ensures durable storage for Prometheus data and helps prevent data loss in case of pod restarts or rescheduling.

Video Guide

Here is the detailed video showcasing how you can setup the OneLens Agent in your kubernetes cluster.

Step-by-Step Guide

Follow these steps to onboard your Kubernetes cluster. You can execute them locally or from a bastion server that has access to your clusters.

1. Verify Prerequisites

Ensure you meet all the prerequisites outlined above before proceeding.

2. Select the EKS Cluster

Use kubectl to set the context to the cluster you want to onboard:

kubectl config use-context <cluster-name>

This command targets the correct cluster for the OneLens Agent deployment.

Precaution

Make sure you are running the onboarding script on the correct cluster. Copying and pasting a script generated for one cluster into a different cluster's context can cause errors or misconfiguration.

3. Run the Onboarding Script

Log into the OneLens UI and select the EKS cluster you want to onboard.

Click on the plus icon.

The UI will automatically generate a deployment command for the selected cluster.

Copy the onboarding script.

Here’s the format of setup command that you’ll will get:

helm upgrade --install onelensdeployer onelens/onelensdeployer \
--set job.env.CLUSTER_NAME="<cluster_name>" \
--set job.env.REGION="<region>" \
--set-string job.env.ACCOUNT="<account_id>" \
--set job.env.REGISTRATION_TOKEN="<registration_token>"

Run it in your terminal.

4. Verification

It will take around 2-3 minutes for the deployment of the agent in your cluster.

After the agent deployment, the status in the OneLens UI will show as Connecting.

The status will update to Connected within 1–2 hours, once data is received on our end.

Finally, simply click on the cluster name to view detailed insights and analysis.

Upgrade the OneLens Agent

Currently the process is manual. OneLens team will reach out to you in order to perform new patches on each integrated cluster. The following process outlines the approach we are working on, in order to make this seamless.

You can initiate OneLens agent upgrades directly from your OneLens account. The console displays the available patch version along with detailed release notes. You can select the clusters to patch, and the request will be routed to the authorized owner in your organization for approval.

How Patching is executed in you Cluster

• OneLens Updater is responsible for the patch process.

• It runs daily at 2:00 AM UTC and checks via OneLens APIs whether the current cluster is approved for patching.

• If a request is found, it applies the patch without manual intervention.

Patch Command

Following patch command will be executed by OneLens Updater, ensuring the existing configurations are used:

helm upgrade onelens-agent onelens/onelens-agent --version=<latest-release> -n onelens-agent