Agent Installation Guide

The Infranexis Resolve agent connects your infrastructure to the RCA engine. It runs inside your environment, collects context when an alert fires, and sends it back over an encrypted WebSocket — giving the RCA engine the full picture of what went wrong.

Overview

The agent is a lightweight Python process. It does three things:

1. Opens a single outbound WebSocket to Infranexis Resolve — no inbound firewall rules needed.
2. Sits completely idle until an alert fires and the RCA engine requests context.
3. Collects only the data relevant to that incident (logs, metrics, events), returns it, then goes back to idle.

How it works

  Your Infrastructure                    Infranexis Resolve
  ─────────────────                      ──────────────────
                                         Alert arrives (PagerDuty /
  resolve-agent ──── WebSocket ────────▶ Prometheus / Grafana / etc.)
       │               (TLS)                      │
       │                                          │ RCA pipeline starts
       │◀──── collect_context request ────────────┘
       │        { service, fired_at }
       │
       ├─ Kubernetes API ──▶ pod logs, events, deployment status
       │
       ├─ Cloud API ────────▶ CloudWatch / Azure Monitor / GCP Logging
       │   (via IAM role)     logs + metrics in ±15 min window
       │
       └─ System ───────────▶ CPU, memory, journald logs (VM mode)
       │
       └──── context_response ─────────────────▶ AI engine generates RCA
                                                  RCA delivered to Slack /
                                                  Teams / PagerDuty / Email

Deployment model — how many agents do you need?

This is the most important thing to understand before installing. The short answer: one agent per cluster or cloud account is usually enough.

Typical deployment examples

  Example A — EKS + CloudWatch  (1 agent total)
  ─────────────────────────────
  EKS cluster
  └── resolve-agent pod
       ├── k8s API  → pod logs, events, deployments (all namespaces)
       └── AWS API  → CloudWatch logs from Lambda, RDS, EC2, ECS
                      CloudWatch Metrics, CloudTrail events
                      (uses IRSA role — no static credentials)


  Example B — Mixed: EKS prod + standalone VM  (2 agents)
  ──────────────────────────────────────────────────────
  EKS cluster
  └── resolve-agent pod  → k8s + CloudWatch (entire AWS account)

  Legacy VM (e.g. MySQL host)
  └── resolve-agent service  → systemd status + journald logs
                                (only needed for this specific host)


  Example C — Multi-cloud  (1 agent per cloud account)
  ─────────────────────────────────────────────────────
  AWS account  → 1 agent (EKS pod with IRSA)
  Azure sub    → 1 agent (AKS pod with Managed Identity)
  GCP project  → 1 agent (GKE pod with Workload Identity)

Installation — Kubernetes

Your personalised install command (with your customer ID embedded) is in Configuration → Intelligence in the dashboard.

1. Prerequisites
   • kubectl configured and pointing at the target cluster
   • Permission to create a Namespace, ServiceAccount, ClusterRole, and Deployment
2. Apply the manifest
   Copy

   kubectl apply -f https://app.infranexis.com/dashboard/install/<YOUR_CUSTOMER_ID>.yaml

   This creates a resolve-agent namespace and deploys the agent as a single-replica Deployment with a read-only ClusterRole.

3. Verify it's running
   Copy

   kubectl get pods -n resolve-agent
   # NAME                             READY   STATUS    RESTARTS
   # resolve-agent-7d9f8c-xxxx        1/1     Running   0

   Within 30 seconds the dashboard will show the agent as Connected.

Uninstall

kubectl delete namespace resolve-agent

Installation — Linux / VM

Use this for standalone hosts (bare metal, EC2, VMs) where you want OS-level context: journald logs, systemd service status, process metrics.

1. Prerequisites
   • Linux with systemd (Ubuntu 20+, Debian 11+, RHEL 8+, Amazon Linux 2)
   • Run as root or with sudo
   • Outbound HTTPS access to app.infranexis.com:443
2. Run the installer
   Copy

   curl -fsSL https://app.infranexis.com/dashboard/install/<YOUR_CUSTOMER_ID>.sh | sudo bash

   The installer creates a resolve-agent system user, installs into /opt/resolve-agent, and registers a systemd service that starts on boot.

3. Verify
   Copy

   sudo systemctl status resolve-agent

Manage the service

sudo systemctl restart resolve-agent     # restart
sudo journalctl -fu resolve-agent        # follow logs
sudo systemctl disable --now resolve-agent  # stop + disable

Uninstall

sudo systemctl disable --now resolve-agent
sudo rm -rf /opt/resolve-agent /etc/systemd/system/resolve-agent.service
sudo systemctl daemon-reload

Installation — Manual (Python)

pip install websockets psutil kubernetes

curl -fsSL https://app.infranexis.com/dashboard/agent.py -o agent.py

RCABOT_SERVER_URL=wss://app.infranexis.com/agent/ws \
RCABOT_API_KEY=rbk_live_xxx \
RCABOT_CUSTOMER_ID=your-uuid \
python3 agent.py

Cloud Integration — How it works

For cloud log services (CloudWatch, Azure Monitor, GCP Logging), the agent acts as an authenticated API client — it calls the cloud provider's centralised logging API, not individual machines. This means one agent can pull logs for your entire AWS account, Azure subscription, or GCP project without being installed on every host.

  WITHOUT cloud integration          WITH cloud integration
  ──────────────────────             ──────────────────────
  Alert: Lambda crashed              Alert: Lambda crashed
  Context: k8s events only           Context: k8s events +
  RCA: limited                         CloudWatch Logs ("/aws/lambda/my-fn")
                                         → last 50 error lines before alert
                                       CloudWatch Metrics
                                         → CPU spike at 14:32
                                         → Error count: 47 in 5 min
                                       CloudTrail
                                         → deploy at 14:28 by user: john
                                       RCA: "Deployment at 14:28 introduced
                                            a memory leak causing OOM at 14:32"

The agent uses your cloud's built-in credential mechanism — no static API keys or secrets stored anywhere:

AWS — CloudWatch Logs & Metrics

The agent collects from CloudWatch Logs, CloudWatch Metrics, CloudWatch Alarms, and CloudTrail — all scoped to the 15 minutes around the alert time.

Azure — Monitor Logs & Metrics

The agent collects from Log Analytics (AppTraces, AppExceptions, ContainerLog) and Azure Monitor Metrics (CPU, memory, HTTP 5xx). Authentication uses Managed Identity — no client secrets.

1. Install the Azure SDK on the agent
   Copy

   # Kubernetes
   kubectl exec -n resolve-agent deploy/resolve-agent -- \
     pip install azure-identity azure-monitor-query
   
   # Linux VM
   sudo /opt/resolve-agent/venv/bin/pip install azure-identity azure-monitor-query

2. Enable Managed Identity
   • Azure VM: Portal → VM → Identity → System assigned → On
   • AKS: Enable Workload Identity on the cluster, annotate the agent's ServiceAccount with the client ID
3. Grant the identity read access
   Copy

   # Log Analytics Reader — on the workspace
   az role assignment create \
     --assignee <managed-identity-object-id> \
     --role "Log Analytics Reader" \
     --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/\
   Microsoft.OperationalInsights/workspaces/<workspace>
   
   # Monitoring Reader — on the resource group
   az role assignment create \
     --assignee <managed-identity-object-id> \
     --role "Monitoring Reader" \
     --scope /subscriptions/<sub>/resourceGroups/<rg>

4. Set environment variables
   Copy

   # Log Analytics workspace GUID
   # Found in: Azure Portal → Log Analytics workspace → Settings → Agents
   RCABOT_AZURE_WORKSPACE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   
   # Full resource ID to pull metrics from (VM, AKS cluster, or App Service)
   RCABOT_AZURE_RESOURCE_ID=/subscriptions/<sub>/resourceGroups/<rg>/\
   providers/Microsoft.Compute/virtualMachines/<vm-name>

   Apply via kubectl:

   Copy

   kubectl set env deployment/resolve-agent -n resolve-agent \
     RCABOT_AZURE_WORKSPACE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
     RCABOT_AZURE_RESOURCE_ID=/subscriptions/...

GCP — Cloud Logging & Monitoring

The agent collects WARNING+ log entries and Cloud Monitoring metrics (Compute, Cloud Run, Cloud Functions). Uses Workload Identity or Application Default Credentials.

1. Install the GCP SDK on the agent
   Copy

   # Kubernetes
   kubectl exec -n resolve-agent deploy/resolve-agent -- \
     pip install google-cloud-logging google-cloud-monitoring
   
   # Linux VM
   sudo /opt/resolve-agent/venv/bin/pip install \
     google-cloud-logging google-cloud-monitoring

2. Create a GCP service account and grant read-only access
   Copy

   gcloud iam service-accounts create resolve-agent \
     --project=<project-id>
   
   gcloud projects add-iam-policy-binding <project-id> \
     --member="serviceAccount:resolve-agent@<project-id>.iam.gserviceaccount.com" \
     --role="roles/logging.viewer"
   
   gcloud projects add-iam-policy-binding <project-id> \
     --member="serviceAccount:resolve-agent@<project-id>.iam.gserviceaccount.com" \
     --role="roles/monitoring.viewer"

3. Bind to the k8s ServiceAccount (GKE Workload Identity)
   Copy

   gcloud iam service-accounts add-iam-policy-binding \
     resolve-agent@<project-id>.iam.gserviceaccount.com \
     --role=roles/iam.workloadIdentityUser \
     --member="serviceAccount:<project-id>.svc.id.goog[resolve-agent/resolve-agent]"
   
   kubectl annotate serviceaccount resolve-agent \
     -n resolve-agent \
     iam.gke.io/gcp-service-account=resolve-agent@<project-id>.iam.gserviceaccount.com

   On a Compute Engine VM the default service account already has logging/monitoring viewer. No extra steps needed.

4. Set environment variables
   Copy

   # Auto-detected from metadata server on GCE/GKE — only needed outside GCP
   RCABOT_GCP_PROJECT_ID=my-project-123
   
   # Specific Cloud Logging log names to search (optional)
   # Auto-matches by service name if blank
   RCABOT_GCP_LOG_NAMES=my-service,stderr,stdout

Environment Variables Reference

Security & Privacy

• Agent source code is open source — inspect every line before deploying. The script served by your install URL is the exact code that runs.
• Outbound-only WebSocket to port 443 — no inbound attack surface, no listening ports.
• Kubernetes RBAC is read-only — the agent cannot create, delete, or modify any resource.
• Cloud IAM permissions are read-only — logs:FilterLogEvents, cloudwatch:GetMetricStatistics, monitoring.viewer, etc.
• No static credentials — uses instance role (AWS), Managed Identity (Azure), or Workload Identity (GCP).
• WebSocket connection authenticated with your unique API key. No other customer can see your data.
• All data in transit encrypted with TLS 1.3.
• Context data is used only to generate the RCA — never sold, shared, or used to train models.
• Idle memory: ~10 MB. Collection burst: ~50–80 MB for a few seconds. No continuous background activity.

FAQ