Helm Chart

The proxima-agent Helm chart deploys both the node agent (DaemonSet) and the cluster agent (StatefulSet) in a single installation. This is the recommended method for Kubernetes deployments.

Prerequisites

Kubernetes 1.26+
Helm 3.x or 4.x
Proxima Console backend running and accessible
Install token from Proxima Console (Settings → Install Tokens)

Add the Helm Repository

The chart is published to the GitLab Package Registry.

# Add the Proxima Helm repository (requires authentication)
helm repo add proxima \
  https://gitlab.prxm.uz/api/v4/projects/271/packages/helm/stable \
  --username <token-name> \
  --password <access-token>

helm repo update

tip

Use a GitLab deploy token or personal access token with read_package_registry scope.

Quick Start

helm install proxima-agent proxima/proxima-agent \
  --namespace proxima-system \
  --create-namespace \
  --set backendUrl=https://api-console.prxm.uz \
  --set installToken.value=YOUR_INSTALL_TOKEN \
  --set clusterAgent.clusterName=my-cluster

This deploys:

A DaemonSet on every Linux node (node agent with host metrics + kubelet metrics)
A StatefulSet (cluster agent for K8s API inventory) — one replica by default, each replica backed by its own PVC for a stable, restart-durable enrollment identity. Run more than one replica for high availability.

Configuration

Required Values

Value	Description
`backendUrl`	Proxima Console backend URL (e.g., `https://api-console.prxm.uz`)
`installToken.value`	Install token for agent enrollment
`clusterAgent.clusterName`	Display name for this cluster in the Console UI

Using an Existing Secret

Instead of passing the install token as a value, reference a pre-existing Kubernetes Secret:

# Create the secret first
kubectl -n proxima-system create secret generic proxima-install-token \
  --from-literal=token=YOUR_INSTALL_TOKEN

# Install with existingSecret reference
helm install proxima-agent proxima/proxima-agent \
  --namespace proxima-system \
  --set backendUrl=https://api-console.prxm.uz \
  --set installToken.existingSecret.name=proxima-install-token \
  --set installToken.existingSecret.key=token \
  --set clusterAgent.clusterName=my-cluster

Common Customizations

# custom-values.yaml

backendUrl: "https://api-console.prxm.uz"

installToken:
  existingSecret:
    name: proxima-install-token
    key: token

# Node Agent
nodeAgent:
  logLevel: "info"
  metricsInterval: "60s"
  hostMetrics: true
  # Schedule on all nodes including control-plane
  tolerations:
    - operator: Exists
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "400m"
      memory: "512Mi"

# Cluster Agent
clusterAgent:
  clusterName: "production-rke2"
  syncInterval: "5m"
  heartbeatInterval: "30s"
  podLimit: 5000
  excludeNamespaces:
    - kube-system

helm install proxima-agent proxima/proxima-agent \
  --namespace proxima-system \
  -f custom-values.yaml

Running Alongside a Host Agent

If you install the standalone Proxima host agent on K8s nodes (for full inventory, terminal access, and runbooks), the DaemonSet agent coexists safely — they use different agent types (k8s-node-monitor vs host).

The Helm chart defaults to nodeAgent.agentType: k8s-node-monitor. No configuration change is needed.

# Install host agent on a K8s node (separate from DaemonSet)
# Use a DIFFERENT data directory to avoid state conflicts
PROXIMA_AGENT_DATA_DIR=/var/lib/proxima-agent-host \
  PROXIMA_INSTALL_TOKEN=... PROXIMA_BACKEND_URL=... proxima-agent

See Dual-Agent Setup for details.

Disabling Components

# Node agent only (no cluster inventory)
helm install proxima-agent proxima/proxima-agent \
  --set nodeAgent.enabled=true \
  --set clusterAgent.enabled=false \
  ...

# Cluster agent only (no per-node metrics)
helm install proxima-agent proxima/proxima-agent \
  --set nodeAgent.enabled=false \
  --set clusterAgent.enabled=true \
  ...

High Availability (leader election)

The cluster agent can run as multiple replicas for high availability. Replicas elect a single leader through a Kubernetes coordination.k8s.io Lease; only the leader collects and publishes inventory and heartbeats, while the others stay enrolled, connected, and ready to take over. This avoids duplicate inventory while giving fast failover (seconds, versus waiting for a single pod to reschedule).

clusterAgent:
  replicas: 2          # >1 enables leader-elected HA
  persistence:
    enabled: true      # required for HA — each replica gets its own PVC

Each replica is a StatefulSet pod with its own PVC (volumeClaimTemplate) and a stable, restart-durable enrollment identity (its pod name). No ReadWriteOnce volume is ever shared between pods.
Standby replicas appear as separate agents in the Console; only the leader publishes, so exactly one is actively reporting at any time. Standbys log standing by; another collector holds leadership.
Leader election needs a namespaced Role for its Lease — the chart creates it automatically.

replicas: 1 (the default) runs without contention (the single pod is always the leader) and behaves exactly like a single collector.

All Values

See the full values.yaml with documentation comments:

helm show values proxima/proxima-agent

Key sections:

Section	Description
`backendUrl`	Backend API URL
`installToken`	Token config (plaintext or existing Secret)
`namespace`	Namespace creation and naming
`commonLabels` / `commonAnnotations`	Applied to all resources
`nodeAgent.*`	DaemonSet image, resources, tolerations, security context
`clusterAgent.*`	StatefulSet image, replicas, sync interval, pod limit, persistence, security

GitOps (Argo CD)

Deploy the chart declaratively with an Argo CD Application that points at the published Helm chart. Keep the install token in a Secret managed by your secrets operator (e.g. External Secrets / Vault) and reference it with installToken.existingSecret — never commit the token to Git.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: proxima-agent
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitlab.prxm.uz/api/v4/projects/271/packages/helm/stable
    chart: proxima-agent
    targetRevision: 0.6.15          # pin to a published chart version
    helm:
      releaseName: proxima-agent
      values: |
        backendUrl: https://api-console.prxm.uz
        clusterAgent:
          clusterName: production-rke2
          replicas: 2               # leader-elected HA
        installToken:
          existingSecret:
            name: proxima-install-token
            key: token
  destination:
    server: https://kubernetes.default.svc
    namespace: proxima-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Validation runs under helm template

The chart's required-value checks (backendUrl, install token, clusterName) run during template rendering — so a misconfigured Application fails the Argo CD sync with a clear error instead of deploying a broken collector.

Repository credentials

The GitLab Helm registry requires authentication. Register it as an Argo CD repository (Settings → Repositories) with a deploy/access token that has read_package_registry scope. Published chart versions track the release tag (the release pipeline pins the chart version/appVersion to the tag), so targetRevision can be any released agent version.

Upgrading

helm repo update
helm upgrade proxima-agent proxima/proxima-agent \
  --namespace proxima-system \
  -f custom-values.yaml

Uninstalling

helm uninstall proxima-agent --namespace proxima-system

caution

Uninstalling removes the DaemonSet and Deployment but does not remove agent records from the Proxima Console database. Agents will appear as "offline" after their stale timeout.

Security

Both components follow security best practices:

Node agent: readOnlyRootFilesystem, capabilities dropped, no privilege escalation. Runs as root (required for /proc and /sys access).
Cluster agent: runAsNonRoot (UID 65532), read-only filesystem, all capabilities dropped, seccompProfile: RuntimeDefault (meets the restricted Pod Security Standard). Its ClusterRole is read-only — no access to Secrets or ConfigMaps — plus a small namespaced Role for its leader-election Lease only.

Troubleshooting

# Check pod status
kubectl -n proxima-system get pods

# Node agent logs
kubectl -n proxima-system logs daemonset/proxima-agent-node-agent

# Cluster agent logs (leader runs collection; standbys log "standing by")
kubectl -n proxima-system logs statefulset/proxima-agent-cluster-agent

# Verify enrollment
kubectl -n proxima-system logs daemonset/proxima-agent-node-agent | grep "enrolled"

# Check NATS connectivity
kubectl -n proxima-system logs daemonset/proxima-agent-node-agent | grep "nats"

Common Issues

Issue	Cause	Fix
Pod stuck in `ImagePullBackOff`	Private registry, no pull secret	Add `imagePullSecrets`
`connection refused` to backend	Wrong `backendUrl` or network policy	Verify URL and cluster egress rules
Kubelet metrics not flowing	`hostMetrics: false` or kubelet RBAC	Set `hostMetrics: true`, check ClusterRole
Cluster not appearing in Console	Collector not enrolling	Check logs for enrollment errors, verify install token

Prerequisites​

Add the Helm Repository​

Quick Start​

Configuration​

Required Values​

Using an Existing Secret​

Common Customizations​

Running Alongside a Host Agent​

Disabling Components​

High Availability (leader election)​

All Values​

GitOps (Argo CD)​

Upgrading​

Uninstalling​

Security​

Troubleshooting​

Common Issues​