> For the complete documentation index, see [llms.txt](https://docs.onelens.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onelens.cloud/integrations/kubernetes/onelens-agent/onboarding-a-k8s-cluster.md).

# Onboarding a K8s Cluster

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

{% hint style="success" %}

### **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.

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

{% endhint %}

## Onboarding Checklist

Before you onboard your cluster, you need to verify that all the necessary prerequisites are in place.

Use the below command to quickly verify the prerequisites:

```bash
curl -sSL https://raw.githubusercontent.com/astuto-ai/onelens-installation-scripts/refs/heads/master/scripts/prereq-check/onelens-prereq-check.sh | bash
```

This script will automatically check your cluster's configuration and let you know if anything needs to be adjusted.

## Onboarding Process: Video Guide

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

{% embed url="<https://youtu.be/RIvO0ziukBw>" %}

## 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.

{% hint style="info" %}
**For GKE clusters only**

Before onboarding a GKE cluster, complete these two additional steps:

1. [Enable Cost Allocation for GKE](/integrations/kubernetes/enable-cost-allocation-for-gke.md) : turns on the per-cluster flag so pod-level costs reach OneLens.
2. [Create a GCP API Key for Pricing Data](/integrations/kubernetes/onelens-agent/create-gcp-api-key-for-pricing-data.md) : lets OpenCost fetch GCP public pricing.

EKS and AKS clusters can skip this and continue below.
{% endhint %}

### 2. **Select the EKS/AKS/GKE Cluster**

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

```bash
kubectl config use-context <cluster-name>
```

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

{% hint style="danger" %}

#### **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.
{% endhint %}

### **3**. **Run the Onboarding Script**

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

Click on the **plus** icon.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FFUbajNGPZ0F4b2vcDtIv%2FScreenshot%202025-04-09%20at%2018.24.28.png?alt=media&amp;token=b5c7d23a-5ff7-4cba-9f22-15bb42fb114b" alt=""><figcaption></figcaption></figure>

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:

```sh
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>"
```

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2F3SAaYJQQ1fmjEEDOsu8h%2Fimage.png?alt=media&amp;token=56cbdd55-5f05-45b5-887a-f6c8c8500458" alt=""><figcaption></figcaption></figure>

Run it in your terminal.<br>

### 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`**.

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FRLKvfoDEcpfBN4J2WTZY%2Fimage.png?alt=media&amp;token=b28ac66b-1c2c-44ec-97de-1d83e99baaa3" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://3963693991-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiyNGpqVYfmDF6qt7Lzar%2Fuploads%2FuQqxuOIUv9cwOBKaBx1N%2Fimage.png?alt=media&amp;token=a74b6fe8-9bc7-4077-b60a-414084468de4" alt=""><figcaption></figcaption></figure>

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

## Upgrade the OneLens Agent

{% hint style="info" %}
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.
{% endhint %}

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 your 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:

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.onelens.cloud/integrations/kubernetes/onelens-agent/onboarding-a-k8s-cluster.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.