Helm Automation (K8s Agent)

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.

Prerequisites

Before you begin, ensure you have the following:

• kubectl installed and configured with cluster admin access

• Helm v3.8+ installed (Installation guide)

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

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.

Select Your Cloud Provider

Choose the cloud platform where your Kubernetes cluster is running:

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.

GCP

Azure

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.

You can modify user access later from the cluster settings page after installation is complete.

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

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

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

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:

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.

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

  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

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

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

  Security Note: Never share your private key. The base64-encoded values are only used during this setup and are securely stored as Kubernetes Secrets.

---

Step-7: Deploy with Helm

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

The Generated Helm Command

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

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:

   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.

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.

---

Troubleshooting

DNS validation failed

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

Solutions:

1. Verify your DNS record exists:

   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

Helm install fails with "namespace already exists"

Cause: A previous installation attempt created the namespace.

Solutions:

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

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

Helm install fails with permission error

Cause: Insufficient RBAC permissions in your cluster.

Solutions:

# 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

Pods stuck in Pending state

Cause: Insufficient cluster resources or scheduling constraints.

Solutions:

# 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

Pods in CrashLoopBackOff

Cause: Configuration error or connectivity issue.

Solutions:

# 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

SSL verification fails

Cause: Certificate issues or ingress misconfiguration.

Solutions:

1. Verify the certificate is valid:

   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:

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

Agent connected but cluster not showing data

Cause: RBAC permissions or network connectivity issues.

Solutions:

# 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