KlusterAlert

Connecting Clusters

The KlusterAlert agent is a lightweight Helm chart that runs inside your cluster. It connects outbound to the KlusterAlert ingestion API. No inbound firewall rules required.

How the agent works

The agent runs as a single Deployment in the klusteralert-agent namespace. It uses the Kubernetes API to list pods and check their status every 60 seconds. Issues are pushed outbound over HTTPS to the KlusterAlert ingestion API on port 443. No data is stored on the node. The agent is stateless.

Getting your agent token

Each cluster gets its own unique agent token. To get one, go to Clusters → Add Cluster in the KlusterAlert dashboard and complete the onboarding wizard. The token is shown once. Copy it before closing the dialog.

Full Helm values reference

values.yaml

# Required
agentToken: ""                 # Per-cluster agent token from the KlusterAlert dashboard
clusterName: ""                # Display name for this cluster in the dashboard

# Optional
image:
  repository: klusteralert/agent
  tag: ""                      # Defaults to chart appVersion
  pullPolicy: IfNotPresent

resources:
  requests:
    cpu: "50m"
    memory: "64Mi"
  limits:
    cpu: "200m"
    memory: "256Mi"

# Store the agent token as a Kubernetes secret (recommended for production)
existingSecret: ""             # Name of existing Secret with AGENT_TOKEN key

# Namespaces to watch (empty = watch all non-system namespaces)
watchNamespaces: []
# watchNamespaces:
#   - production
#   - staging

# Node selector and tolerations for the agent pod
nodeSelector: {}
tolerations: []
affinity: {}

# Proxy configuration (if your cluster routes outbound through a proxy)
proxy:
  http: ""
  https: ""
  noProxy: ""

Using a Kubernetes secret for the agent token

Avoid passing the token directly via Helm values. Instead, create a Kubernetes secret:

kubectl create secret generic klusteralert-creds \
  --namespace klusteralert-agent \
  --from-literal=AGENT_TOKEN=your_token_here

Install referencing the secret

helm install klusteralert-agent klusteralert/agent \
  --namespace klusteralert-agent \
  --create-namespace \
  --set clusterName=production \
  --set existingSecret=klusteralert-creds

Multi-cluster setup

Install the Helm chart once per cluster. Each cluster needs its own token. Create a separate cluster entry in the KlusterAlert dashboard for each one. Use a descriptive clusterName:

# Production cluster (uses its own token)
helm install klusteralert-agent klusteralert/agent \
  --namespace klusteralert-agent --create-namespace \
  --set agentToken=$PROD_AGENT_TOKEN \
  --set clusterName=prod-eu-west-1 \
  --kube-context prod-context

# Staging cluster (uses its own separate token)
helm install klusteralert-agent klusteralert/agent \
  --namespace klusteralert-agent --create-namespace \
  --set agentToken=$STAGING_AGENT_TOKEN \
  --set clusterName=staging \
  --kube-context staging-context

RBAC requirements

The Helm chart automatically creates a ClusterRole with the following read-only permissions:

ClusterRole (created by Helm chart)

rules:
  - apiGroups: [""]
    resources: [pods, nodes, events, namespaces]
    verbs: [get, list, watch]
  - apiGroups: ["apps"]
    resources: [deployments, daemonsets, statefulsets, replicasets]
    verbs: [get, list, watch]

The agent never modifies any Kubernetes resources. All permissions are read-only.

Upgrading the agent

helm repo update
helm upgrade klusteralert-agent klusteralert/agent \
  --namespace klusteralert-agent

Uninstalling

helm uninstall klusteralert-agent --namespace klusteralert-agent
kubectl delete namespace klusteralert-agent