Helm Installation

What you'll learn: Deploy the Scoutflo Kubernetes Agent to enable AI-driven incident investigation and root-cause analysis across your Kubernetes infrastructure.

Overview

The Scoutflo Kubernetes Agent is a lightweight monitoring solution that provides deep visibility into your Kubernetes clusters. Once deployed, it automatically discovers and monitors your infrastructure to power intelligent incident response.

What the Agent Monitors

graph TD
    A[Scoutflo K8s Agent] --> B[Cluster Topology]
    A --> C[Metrics Collection]
    A --> D[Events & Failures]

    B --> B1[Namespaces]
    B --> B2[Services]
    B --> B3[Pods]
    B --> B4[Deployments]

    C --> C1[Pod Metrics]
    C --> C2[Node Metrics]
    C --> C3[Resource Usage]

    D --> D1[Kubernetes Events]
    D --> D2[Application Failures]
    D --> D3[Infrastructure Issues]

Architecture Overview

graph LR
    subgraph "Your Kubernetes Cluster"
        Agent[Scoutflo Agent]
        Ingress[Ingress Controller]
        Cert[TLS Certificate]

        Agent --> Ingress
        Cert --> Ingress
    end

    subgraph "Scoutflo Platform"
        API[Scoutflo API]
        AI[AI Analysis Engine]
    end

    Ingress -->|HTTPS| API
    API --> AI

    subgraph "Your Infrastructure"
        DNS[DNS Provider]
        LoadBalancer[Load Balancer]
    end

    DNS --> LoadBalancer
    LoadBalancer --> Ingress

Prerequisites Checklist

Before starting the installation, ensure you have the required access and components:

✅ System Requirements

Kubernetes 1.21+ (EKS, GKE, AKS, or self-managed)
Helm 3.8+ installed and configured
Active kubeconfig context for target cluster
Ingress controller deployed (NGINX, Traefik, etc.)

✅ Access Requirements

You have cluster-admin privileges or equivalent permissions to:

Create namespaces, deployments, services, ingresses
Manage RBAC resources (ServiceAccounts, ClusterRoles, ClusterRoleBindings)
Create and manage secrets

✅ DNS & TLS Requirements

DNS Control: Ability to create/update DNS records for agent hostname
TLS Management: Either cert-manager setup OR manual certificate management
Domain Ownership: Access to domain where agent will be hosted

Important: If you don't control DNS or TLS certificates, coordinate with your platform/infra team before proceeding.

Installation Guide

Prepare your environment

Install Required Components

If you don't have an ingress controller, install NGINX:

# Add the official NGINX ingress repository
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

# Install NGINX ingress controller
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --wait

For automatic TLS certificate management:

# Add Jetstack repository for cert-manager
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Install cert-manager with CRDs
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true \
  --wait

Configure TLS Certificate Issuer

Create a ClusterIssuer for Let's Encrypt certificates:

# File: clusterissuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@company.com  # Replace with your email
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - http01:
          ingress:
            class: nginx  # Match your ingress class

# Apply the ClusterIssuer
kubectl apply -f clusterissuer.yaml

Configure Helm registry access

Registry Credentials: Scoutflo will provide you with private registry credentials. Contact your Scoutflo representative if you haven't received them.

# Login to Scoutflo's private Helm registry
helm registry login ghcr.io \
  --username <YOUR_SCOUTFLO_USERNAME> \
  --password <YOUR_SCOUTFLO_TOKEN>

Deploy the Scoutflo Agent

Ready to install! The following command will deploy the agent with all necessary components.

helm install scoutflo-k8s-agent \
  oci://ghcr.io/scoutflo/k8s-dashboard/k8s-dashboard \
  --version 0.1.277 \
  --namespace scoutflo-k8s-agent \
  --create-namespace \
  --set namespace.name=scoutflo-k8s-agent \
  --set ingress.hostname=api-k8sagent.your-domain.com \
  --set ingress.tls.wildcardHostname=your-domain.com \
  --set ingress.tls.secretName=letsencrypt-prod \
  --set image.dockerConfigSecret=<REGISTRY_SECRET_NAME> \
  --set auth.username=<SCOUTFLO_AGENT_USERNAME> \
  --set auth.password=<SCOUTFLO_AGENT_PASSWORD> \
  --set auth.sessionSecret=<RANDOM_SESSION_SECRET> \
  --set auth.deploymentId=<SCOUTFLO_DEPLOYMENT_ID> \
  --set auth.agentId=<SCOUTFLO_AGENT_ID> \
  --set rbac.agentImpersonation.userResourceNames=<SCOUTFLO_AGENT_USERNAME> \
  --wait

Parameter Reference

Parameter

Description

Example Value

ingress.hostname

FQDN where agent will be accessible

api-k8sagent.company.com

ingress.tls.wildcardHostname

Root domain for TLS certificate

company.com

auth.username

Agent authentication username

Provided by Scoutflo

auth.password

Agent authentication password

Provided by Scoutflo

auth.sessionSecret

Random session encryption key

Generate with openssl rand -hex 32

auth.deploymentId

Your Scoutflo deployment ID

Provided by Scoutflo

auth.agentId

Unique agent identifier

Provided by Scoutflo

Security Note: Replace all placeholder values (<...>) with actual values provided by the Scoutflo team. Never commit these values to version control.

Verify installation

Check that all components are running correctly:

# Check agent pods
kubectl get pods -n scoutflo-k8s-agent

# Verify ingress configuration
kubectl get ingress -n scoutflo-k8s-agent

# Check TLS certificate status
kubectl describe certificate -n scoutflo-k8s-agent

# View agent logs
kubectl logs -n scoutflo-k8s-agent deployment/scoutflo-k8s-agent --tail=50

Expected Output

✅ Healthy Installation:

NAME                                 READY   STATUS    RESTARTS   AGE
scoutflo-k8s-agent-xxxxxxxxx-xxxxx  1/1     Running   0          2m

NAME                     CLASS   HOSTS                           ADDRESS          PORTS     AGE
scoutflo-k8s-agent      nginx   api-k8sagent.your-domain.com    203.0.113.10     80, 443   2m

NAME                     READY   SECRET                  AGE
scoutflo-k8s-agent-tls  True    letsencrypt-prod        2m

Configure DNS

Create a DNS record pointing to your ingress controller's external IP:

# Get ingress external IP
kubectl get ingress scoutflo-k8s-agent -n scoutflo-k8s-agent \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Create an A record:

Name: api-k8sagent (or your chosen subdomain)
Type: A
Value: <INGRESS_EXTERNAL_IP>
TTL: 300

DNS Propagation: DNS changes can take 5-15 minutes to propagate. Test with nslookup api-k8sagent.your-domain.com

Advanced Configuration

Advanced RBAC Setup

For security-conscious environments that restrict cluster-admin access:

🔒 Click to expand RBAC configuration

# File: scoutflo-rbac.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: scoutflo-agent-installer
  namespace: scoutflo-k8s-agent
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: scoutflo-agent-role
rules:
  # Core resources
  - apiGroups: [""]
    resources: ["pods", "services", "secrets", "configmaps", "namespaces", "nodes"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["secrets", "configmaps"]
    verbs: ["create", "update", "patch", "delete"]

  # App resources
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "daemonsets", "statefulsets"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

  # Networking
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses", "networkpolicies"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

  # Metrics and monitoring
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods", "nodes"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: scoutflo-agent-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: scoutflo-agent-role
subjects:
  - kind: ServiceAccount
    name: scoutflo-agent-installer
    namespace: scoutflo-k8s-agent

Apply the RBAC configuration:

kubectl apply -f scoutflo-rbac.yaml

Using Scoutflo-Managed Subdomain

Use your own domain (recommended for production):

--set ingress.hostname=api-k8sagent.your-company.com \
--set ingress.tls.wildcardHostname=your-company.com

Use a Scoutflo-provided subdomain for testing:

--set ingress.hostname=api-k8s-yourenv.scoutflo.agency \
--set ingress.tls.secretName=scoutflo-agency-tls \
--set ingress.tls.wildcardHostname=scoutflo.agency

Contact Scoutflo support to request a managed subdomain and TLS certificate.

Validation & Testing

Health Check Workflow

flowchart TD
    A[Agent Deployed] --> B{Pods Running?}
    B -->|No| B1[Check Logs]
    B -->|Yes| C{Ingress Ready?}
    C -->|No| C1[Check DNS & LB]
    C -->|Yes| D{TLS Valid?}
    D -->|No| D1[Check Certificate]
    D -->|Yes| E{Agent Reachable?}
    E -->|No| E1[Check Firewall]
    E -->|Yes| F[✅ Installation Complete]

    B1 --> B2[Fix Image/RBAC Issues]
    C1 --> C2[Update DNS Records]
    D1 --> D2[Check cert-manager]
    E1 --> E2[Verify Security Groups]

    B2 --> B
    C2 --> C
    D2 --> D
    E2 --> E

Test Connectivity

# Test HTTPS endpoint
curl -k https://api-k8sagent.your-domain.com/health

# Expected response
{"status":"healthy","version":"0.1.277","agent_id":"your-agent-id"}

Monitor Agent Status

# Real-time pod logs
kubectl logs -f -n scoutflo-k8s-agent deployment/scoutflo-k8s-agent

# Check resource usage
kubectl top pods -n scoutflo-k8s-agent

# View detailed pod information
kubectl describe pod -n scoutflo-k8s-agent -l app=scoutflo-k8s-agent

Troubleshooting Guide

Common Issues & Solutions

Symptom

Possible Cause

Solution

ImagePullBackOff

Registry credentials invalid

Verify helm registry login was successful

CrashLoopBackOff

Configuration error

Check pod logs for auth/config issues

Pending state

Resource constraints

Check node resources and pod requests

Debug Commands:

kubectl describe pod -n scoutflo-k8s-agent <POD_NAME>
kubectl logs -n scoutflo-k8s-agent <POD_NAME> --previous

Symptom

Possible Cause

Solution

Ingress not accessible

DNS misconfiguration

Verify A record points to correct IP

502/503 errors

Service/pod not ready

Check service endpoints and pod health

TLS certificate errors

cert-manager issues

Check certificate and challenge status

Debug Commands:

kubectl get endpoints -n scoutflo-k8s-agent
kubectl describe certificate -n scoutflo-k8s-agent
nslookup api-k8sagent.your-domain.com

Symptom

Possible Cause

Solution

403 Forbidden errors

Insufficient permissions

Review and update ClusterRole rules

Unable to create resources

ServiceAccount issues

Verify ClusterRoleBinding is correct

Agent can't read cluster data

Missing RBAC rules

Add required API group permissions

Debug Commands:

kubectl auth can-i --list --as=system:serviceaccount:scoutflo-k8s-agent:scoutflo-agent
kubectl get clusterrolebinding -o wide | grep scoutflo

Getting Help

If you're still experiencing issues:

Gather diagnostic information:

# Create a support bundle
kubectl get all,ingress,certificates -n scoutflo-k8s-agent -o yaml > scoutflo-debug.yaml
kubectl logs -n scoutflo-k8s-agent deployment/scoutflo-k8s-agent --tail=100 > scoutflo-logs.txt

Contact Scoutflo Support with:
- Your Helm installation command (with secrets redacted)
- The diagnostic files above
- Your cluster information (provider, version, ingress controller)

Pro Tip: Most issues are resolved by verifying DNS, TLS certificates, or RBAC permissions. Double-check these first!

Maintenance & Updates

Updating the Agent

# Check for available versions
helm search repo scoutflo --versions

# Upgrade to latest version
helm upgrade scoutflo-k8s-agent \
  oci://ghcr.io/scoutflo/k8s-dashboard/k8s-dashboard \
  --namespace scoutflo-k8s-agent \
  --reuse-values \
  --version <NEW_VERSION>

Backup Configuration

# Export current values
helm get values scoutflo-k8s-agent -n scoutflo-k8s-agent > scoutflo-values-backup.yaml

# Export complete configuration
kubectl get secret -n scoutflo-k8s-agent -o yaml > scoutflo-secrets-backup.yaml

Uninstalling

Warning: This will permanently remove the agent and all monitoring data. Ensure you want to proceed.

# Remove the Helm release
helm uninstall scoutflo-k8s-agent -n scoutflo-k8s-agent

# Optionally remove the namespace
kubectl delete namespace scoutflo-k8s-agent

# Clean up ClusterRole and ClusterRoleBinding (if using custom RBAC)
kubectl delete clusterrole scoutflo-agent-role
kubectl delete clusterrolebinding scoutflo-agent-binding

Next Steps

🎉 Congratulations! Your Scoutflo Kubernetes Agent is now monitoring your cluster and sending data to the Scoutflo platform.

What Happens Next

Automatic Discovery: The agent will begin discovering your cluster topology within 5-10 minutes
Baseline Establishment: Scoutflo will establish performance baselines over the next 24-48 hours
AI Training: The AI analysis engine will start learning your cluster's normal behavior patterns

Accessing Scoutflo

Log into your Scoutflo dashboard to view cluster insights
Configure alerting rules and notification channels
Explore the AI-powered incident investigation features

Additional Resources

Questions or feedback? Reach out to the Scoutflo team at support@scoutflo.com or join our community Slack.

PreviousCloud Connection (AWS)NextSentry Integration

hashtagOverview

hashtagWhat the Agent Monitors

hashtagArchitecture Overview

hashtagPrerequisites Checklist

hashtag✅ System Requirements

hashtag✅ Access Requirements

hashtag✅ DNS & TLS Requirements

hashtagInstallation Guide

hashtagPrepare your environment

hashtagConfigure Helm registry access

hashtagDeploy the Scoutflo Agent

hashtagVerify installation

hashtagConfigure DNS

hashtagAdvanced Configuration

hashtagAdvanced RBAC Setup

hashtagUsing Scoutflo-Managed Subdomain

hashtagValidation & Testing

hashtagHealth Check Workflow

hashtagTest Connectivity

hashtagMonitor Agent Status

hashtagTroubleshooting Guide

hashtagCommon Issues & Solutions

hashtagGetting Help

hashtagMaintenance & Updates

hashtagUpdating the Agent

hashtagBackup Configuration

hashtagUninstalling

hashtagNext Steps

hashtagWhat Happens Next

hashtagAccessing Scoutflo

hashtagAdditional Resources

Overview

What the Agent Monitors

Architecture Overview

Prerequisites Checklist

✅ System Requirements

✅ Access Requirements

✅ DNS & TLS Requirements

Installation Guide

Prepare your environment

Configure Helm registry access

Deploy the Scoutflo Agent

Verify installation

Configure DNS

Advanced Configuration

Advanced RBAC Setup

Using Scoutflo-Managed Subdomain

Validation & Testing

Health Check Workflow

Test Connectivity

Monitor Agent Status

Troubleshooting Guide

Common Issues & Solutions

Getting Help

Maintenance & Updates

Updating the Agent

Backup Configuration

Uninstalling

Next Steps

What Happens Next

Accessing Scoutflo

Additional Resources