Clustering Mode

1. Clustering mode #

Ensuring high availability and load balancing.

Resilience and Horizontal Scaling #

In vast environments, a single instance of Alloy is not enough to collect from tens of thousands of targets. Alloy's Clustering mode allows launching multiple instances that communicate with each other (via a Gossip protocol). Together, they form a cluster that intelligently distributes the workload (sharding Prometheus scraping targets or log files). If a cluster node fails, the other nodes immediately take over its load, ensuring highly available telemetry collection without data duplication.

Best Practice: In Kubernetes, always deploy Alloy in Cluster mode as a StatefulSet rather than a Deployment. The StatefulSet guarantees stable network identities, which are essential for proper load balancing (Gossip) between nodes.

Common Mistake: Forgetting to configure persistent storage (PVC) on each cluster node for the WAL. If a pod restarts or is rescheduled, unsent metrics will be permanently lost.

# Helm configuration snippet (values.yaml)
alloy:
  clustering:
    enabled: true
    name: "my-alloy-cluster"
  controller:
    type: statefulset
    replicas: 3
    volumeClaimTemplates:
      - metadata:
          name: alloy-wal
        spec:
          accessModes: [ "ReadWriteOnce" ]
          resources:
            requests:
              storage: 10Gi