# 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.
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: {% 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.
{% 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
**Configure Your DNS** Create a CNAME record pointing your chosen hostname to your load balancer: ``` # DNS CNAME Record Format hostname.yourcompany.com CNAME # 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.
**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)
**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** ```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= \ --set auth.sessionSecret= \ --set auth.deploymentId= \ --set auth.agentId= \ --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="" \ --set ingress.tls.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: ```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 %}
*** #### Troubleshooting
DNS validation failed **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
Helm install fails with "namespace already exists" **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 ```
Helm install fails with permission error **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 ```
Pods stuck in Pending state **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 ```
Pods in CrashLoopBackOff **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 ```
SSL verification fails **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 ```
Agent connected but cluster not showing data **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 ```
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://scoutflo-documentation.gitbook.io/scoutflo-documentation/features/helm-automation-k8s-agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.