# Helm Automation (K8s Agent)

{% hint style="info" %}
**What this guide covers:** Installing the Scoutflo K8s Agent on an existing cluster you manage. If you want Scoutflo to provision a new cluster, see Create a Cluster instead.
{% endhint %}

#### Prerequisites

Before you begin, ensure you have the following:

* **`kubectl`** installed and configured with cluster admin access
* **Helm v3.8+** installed ([Installation guide](https://helm.sh/docs/intro/install/))
* **Cluster admin permissions** to create namespaces, deployments, and RBAC resources
* **A domain name** with DNS management access (for the agent endpoint)
* **SSL certificate** for your domain (or ability to create one)
* **Load Balancer** configured in your cluster (or ability to create one)

***

#### Step-1: Open the Cluster Connection Wizard

The first step is navigating to the cluster connection wizard in Scoutflo. Here's how it works:

* **Navigate to Clusters:** Log in to [app.scoutflo.com](https://app.scoutflo.com/) and click on **Clusters** in the left sidebar.
* **Add Cluster:** Click the **+ Add Cluster** button in the top right corner.
* **Select Connect:** A modal will appear with two options. Select **Connect a cluster** to proceed.

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2FYH3Fh1NIleBRehLUjwDQ%2Fimage.png?alt=media&#x26;token=f6882ede-a43c-4b63-b225-6f0ac02557c6" alt="" width="563"><figcaption></figcaption></figure>

You will be redirected to the cluster connection wizard where you'll configure your cluster settings in two main steps.

***

#### Step-2: Configure Cluster Metadata

Once in the wizard, you'll need to provide details about your Kubernetes cluster. This information helps Scoutflo identify and categorize your cluster in the dashboard.

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2FAoE8v0ALAMWhkWtMGR73%2Fimage.png?alt=media&#x26;token=94ba4c35-0bf9-4b28-a919-bc2680496bed" alt="" width="563"><figcaption></figcaption></figure>

**Select Your Cloud Provider**

Choose the cloud platform where your Kubernetes cluster is running:

{% tabs %}
{% tab title="AWS" %}
**Amazon Web Services (EKS)**

Select this option if your cluster is running on Amazon Elastic Kubernetes Service.

* EKS cluster with kubectl access configured
* AWS CLI configured with appropriate IAM permissions
* Load balancer controller installed (for ALB ingress) or Nginx ingress controller

Scoutflo supports EKS clusters in all AWS regions.
{% endtab %}

{% tab title="GCP" %}
**Google Cloud (GKE)**

Select this option if your cluster is running on Google Kubernetes Engine.

* GKE cluster with kubectl access configured
* gcloud CLI authenticated with Kubernetes Engine Admin role
* Ingress controller deployed (GCE ingress or Nginx)

Scoutflo supports GKE clusters in all GCP regions and zones.
{% endtab %}

{% tab title="Azure" %}
**Microsoft Azure (AKS)**

Select this option if your cluster is running on Azure Kubernetes Service.

* AKS cluster with kubectl access configured
* Azure CLI authenticated with AKS Cluster Admin permissions
* Ingress controller deployed (Azure Application Gateway or Nginx)

Scoutflo supports AKS clusters in all Azure regions.
{% endtab %}
{% endtabs %}

#### Select Your Region

After selecting your cloud provider, choose the **region** where your cluster is deployed. The region dropdown will populate based on your selected cloud provider.

**Enter Cluster Information**

Provide the following details about your cluster:

* **Cluster Name:** A unique, descriptive name for your cluster. This will be displayed throughout the Scoutflo dashboard. Examples: `production-us-east`, `staging-cluster`
* **Kubernetes Version:** The version of Kubernetes running on your cluster. You can find this by running `kubectl version --short`. Examples: `1.28.0`, `1.27.5`
* **Environment:** The deployment environment type (Production, Staging, or Development). This helps categorize your clusters and can be used for filtering.

***

#### Step-3: Configure User Access Control

Control which team members can access this cluster through Scoutflo. Only users who are already members of your Scoutflo workspace can be granted access.

**Automatic Access**

The following users are automatically granted access and cannot be removed:

* **Super Admins** - Have access to all clusters by default
* **Credential Owners** - Users associated with the cloud credentials used for this cluster

**Assigning Users**

1. Review the list of workspace members displayed in the wizard
2. Check the box next to each user who should have access to this cluster
3. Users marked as **"Cannot be deselected"** have automatic access based on their role

The interface will display a summary showing how many users will be assigned to this cluster.

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2FTRU9g2FgZV2RPsoOTjaN%2Fimage.png?alt=media&#x26;token=6c0150da-956b-44e2-af2c-a09603ed3d51" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
You can modify user access later from the cluster settings page after installation is complete.
{% endhint %}

Click **Continue to Installation** to proceed to the next step.

***

#### Step-4: Configure Service Host URL

The Scoutflo K8s Agent runs as a web service inside your cluster and requires an externally accessible URL for the Scoutflo platform to communicate with it.

**What You Need**

Before proceeding, you must have:

1. **A Load Balancer** - Either create a new one or use an existing load balancer in your cluster
2. **A Domain/Subdomain** - A hostname that will point to your load balancer (e.g., `api-k8sagent.yourcompany.com`)
3. **DNS Access** - Ability to create a CNAME record for your domain

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2Fs9A7aSOc7qjGQNEsRL4V%2Fimage.png?alt=media&#x26;token=009b50be-7157-4c99-a51d-d9d16ef655eb" alt="" width="563"><figcaption></figcaption></figure>

**Configure Your DNS**

Create a CNAME record pointing your chosen hostname to your load balancer:

```
# DNS CNAME Record Format
hostname.yourcompany.com  CNAME  <your-load-balancer-address>

# AWS EKS Example
api-k8sagent.yourcompany.com  CNAME  a1b2c3d4e5f6.elb.us-east-1.amazonaws.com

# GKE Example
api-k8sagent.yourcompany.com  CNAME  34.120.50.100.bc.googleusercontent.com

# AKS Example
api-k8sagent.yourcompany.com  CNAME  myaks-dns-1234abcd.hcp.eastus.azmk8s.io
```

**Enter the Service Host URL**

In the wizard, enter your configured hostname as an **HTTP URL** (not HTTPS):

{% hint style="warning" %}
**Important:** Enter the URL with `http://` prefix, not `https://`. The wizard will configure TLS separately in the next step.

* Correct: `http://api-k8sagent.yourcompany.com`
* Incorrect: `https://api-k8sagent.yourcompany.com`
  {% endhint %}

#### DNS Validation

After entering your hostname, Scoutflo will perform a DNS resolution check. If validation fails, your DNS record may still be propagating. This typically takes 5-10 minutes but can take up to 24 hours.

You can verify DNS propagation manually:

```bash
nslookup api-k8sagent.yourcompany.com
# or
dig api-k8sagent.yourcompany.com
```

***

#### Step-5: Configure Ingress Controller

Scoutflo needs to know which ingress controller your cluster uses to properly configure the K8s Agent's network access.

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2F5JQP6oCr6S5xvLSpjavb%2Fimage.png?alt=media&#x26;token=3c7c9834-8fc2-4609-8341-06e43dc576f8" alt="" width="563"><figcaption></figcaption></figure>

**Select Ingress Management Mode**

* **Manage Ingress** (Recommended) - Scoutflo creates and manages the Ingress resource
* **Do not manage ingress** - You manage ingress configuration manually

**Select Your Ingress ControllerNginx Ingress Controller**

The most widely used ingress controller for Kubernetes. Works with any cloud provider.

**Status:** Fully Supported

**Requirements:**

* Nginx Ingress Controller installed in your cluster
* Installation guide: [kubernetes.github.io/ingress-nginx](https://kubernetes.github.io/ingress-nginx/deploy/)

  **AWS Application Load Balancer**

Native AWS integration using the AWS Load Balancer Controller. Recommended for EKS clusters.

**Status:** Fully Supported

**Requirements:**

* AWS Load Balancer Controller installed in your cluster
* Appropriate IAM permissions for ALB management
* Installation guide: [AWS Load Balancer Controller](https://docs.aws.amazon.com/eks/latest/userguide/aws-load-balancer-controller.html)

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2F5IfJbwxeOylyqPAGdyDS%2Fimage.png?alt=media&#x26;token=344b8638-333b-480b-9a14-7a46411fe939" alt=""><figcaption></figcaption></figure>

**Traefik Ingress Controller**

Modern, cloud-native ingress controller with automatic HTTPS and Let's Encrypt support.

**Status:** Coming Soon

Traefik support is currently in development. Please use Nginx or AWS ALB for now.

**Istio Service Mesh**

For clusters using Istio service mesh with Istio Ingress Gateway.

**Status:** Coming Soon

Istio support is currently in development. Please use Nginx or AWS ALB for now.

***

#### Step-6: Configure TLS/SSL Certificate

Secure communication between Scoutflo and the K8s Agent requires a valid TLS certificate.

**TLS Configuration Fields**

* **TLS Secret Name:** Name of the Kubernetes Secret that will store your certificate. Examples: `scoutflo-agent-tls`, `api-tls-cert`
* **Certificate (Base64):** Your SSL certificate, base64 encoded
* **Private Key (Base64):** Your certificate's private key, base64 encoded

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2FE6whfgQZERoloCog3H3X%2Fimage.png?alt=media&#x26;token=f433e92d-ce3f-40ef-a4ba-a3951c603b57" alt="" width="563"><figcaption></figcaption></figure>

Your certificate must:

* Be valid for the hostname you configured (e.g., `api-k8sagent.yourcompany.com`)
* Not be expired
* Include the full certificate chain (if applicable)
* Be in PEM format before base64 encoding

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>Security Note:</strong> Never share your private key. The base64-encoded values are only used during this setup and are securely stored as Kubernetes Secrets.</p></div>

***

#### Step-7: Deploy with Helm

After completing all configuration steps, Scoutflo generates a customized Helm install command for your cluster.

**The Generated Helm Command**

```bash
helm install scoutflo-k8sagent-rn-63d49a91 \
  oci://ghcr.io/scoutflo/k8s-dashboard/k8s-dashboard \
  --version 0.1.320 \
  --namespace scoutflo-k8sagent-ns-ac38461a \
  --create-namespace \
  --set namespace.name=scoutflo-k8sagent-ns-ac38461a \
  --set backend.host=https://api.app-server.scoutflo.com \
  --set auth.username=k8s-agent_a526cfe5 \
  --set auth.password=<auto-generated> \
  --set auth.sessionSecret=<auto-generated> \
  --set auth.deploymentId=<auto-generated> \
  --set auth.agentId=<auto-generated> \
  --set rbac.agentImpersonation.userResourceNames="{k8s-agent_a526cfe5}" \
  --set ingress.enabled=true \
  --set ingress.controller=nginx \
  --set ingress.hostname=api-k8sagent.yourcompany.com \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName="scoutflo-agent-tls" \
  --set ingress.tls.crt="<your-base64-certificate>" \
  --set ingress.tls.key="<your-base64-private-key>"
```

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2FqfUJCMCuRwxwlXnO7mCG%2Fimage.png?alt=media&#x26;token=9a0205a3-fef5-46f4-b9db-352d1b7f316f" alt=""><figcaption></figcaption></figure>

**Understanding the Parameters**

| Category           | Parameters                                             | Description                                            |
| ------------------ | ------------------------------------------------------ | ------------------------------------------------------ |
| **Deployment**     | `--namespace`, `--create-namespace`                    | Creates a dedicated namespace for the agent            |
| **Authentication** | `auth.username`, `auth.password`, `auth.sessionSecret` | Secure credentials for agent-to-platform communication |
| **Ingress**        | `ingress.controller`, `ingress.hostname`               | Configures external access to the agent                |
| **TLS**            | `ingress.tls.crt`, `ingress.tls.key`                   | Enables HTTPS with your certificate                    |

**Run the Command**

1. **Copy** the entire Helm command from the Scoutflo wizard
2. **Open** your terminal with kubectl configured for your cluster
3. **Verify** you're connected to the correct cluster:

   ```bash
   kubectl config current-context
   ```
4. **Paste and run** the Helm install command.

**Expected Output**

A successful installation will show:

```
NAME: scoutflo-k8sagent-rn-63d49a91
LAST DEPLOYED: Wed Feb 12 2026 10:30:00
NAMESPACE: scoutflo-k8sagent-ns-ac38461a
STATUS: deployed
REVISION: 1
```

***

#### Step-8: Complete SSL Verification

Return to the Scoutflo wizard to complete the final verification step.

1. In the Scoutflo wizard, you should see the installation status update to **"Installation Successful"**
2. Click the **Verify SSL** button
3. Scoutflo will test the secure connection to your agent.

{% hint style="success" %}
**Verification Complete!** Upon successful SSL verification, you will be redirected to your cluster's dashboard. Your cluster is now fully connected and ready for AI-powered incident analysis.
{% endhint %}

<figure><img src="https://4241237958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtffWbX4svYQUS7SraAdG%2Fuploads%2Fcguw6EZ5kc3NSGf6ohg5%2Fimage.png?alt=media&#x26;token=3eeda909-5cb7-4e41-821f-c7125330d0a0" alt="" width="563"><figcaption></figcaption></figure>

***

#### Troubleshooting

<details>

<summary>DNS validation failed</summary>

**Cause:** The DNS record hasn't propagated or is misconfigured.

**Solutions:**

1. Verify your DNS record exists:

   ```bash
   nslookup api-k8sagent.yourcompany.com
   ```
2. Wait 5-10 minutes for DNS propagation
3. Ensure the CNAME points to the correct load balancer address
4. Check for typos in the hostname

</details>

<details>

<summary>Helm install fails with "namespace already exists"</summary>

**Cause:** A previous installation attempt created the namespace.

**Solutions:**

```bash
# Option 1: Delete the namespace and retry
kubectl delete namespace scoutflo-k8sagent-ns-ac38461a

# Option 2: Remove --create-namespace flag if namespace should persist
```

</details>

<details>

<summary>Helm install fails with permission error</summary>

**Cause:** Insufficient RBAC permissions in your cluster.

**Solutions:**

```bash
# Check your permissions
kubectl auth can-i create namespace --all-namespaces
kubectl auth can-i create clusterrole --all-namespaces

# If needed, ensure you have cluster-admin access
```

</details>

<details>

<summary>Pods stuck in Pending state</summary>

**Cause:** Insufficient cluster resources or scheduling constraints.

**Solutions:**

```bash
# Check pod events for details
kubectl describe pod -n scoutflo-k8sagent-ns-ac38461a -l app=k8s-agent

# Check node resources
kubectl top nodes

# The agent requires minimal resources:
# - CPU: 100m request, 200m limit
# - Memory: 128Mi request, 256Mi limit
```

</details>

<details>

<summary>Pods in CrashLoopBackOff</summary>

**Cause:** Configuration error or connectivity issue.

**Solutions:**

```bash
# Check pod logs for error messages
kubectl logs -n scoutflo-k8sagent-ns-ac38461a -l app=k8s-agent --previous

# Common issues:
# - Incorrect auth credentials (regenerate from Scoutflo)
# - Network policy blocking outbound traffic
# - Backend host unreachable
```

</details>

<details>

<summary>SSL verification fails</summary>

**Cause:** Certificate issues or ingress misconfiguration.

**Solutions:**

1. Verify the certificate is valid:

   ```bash
   echo | openssl s_client -connect api-k8sagent.yourcompany.com:443 2>/dev/null | openssl x509 -noout -dates
   ```
2. Check that the certificate matches the hostname
3. Verify the TLS secret was created:

   ```bash
   kubectl get secret scoutflo-agent-tls -n scoutflo-k8sagent-ns-ac38461a
   ```

</details>

<details>

<summary>Agent connected but cluster not showing data</summary>

**Cause:** RBAC permissions or network connectivity issues.

**Solutions:**

```bash
# Verify agent can access Kubernetes API
kubectl logs -n scoutflo-k8sagent-ns-ac38461a -l app=k8s-agent | grep -i error

# Check RBAC permissions
kubectl auth can-i list pods --as=system:serviceaccount:scoutflo-k8sagent-ns-ac38461a:k8s-agent -A
```

</details>