Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Get started

Clustering

Open source

Clustering

Clustering allows a fleet of Alloy deployments to work together for workload distribution and high availability. It enables horizontally scalable deployments with minimal resource and operational overhead.

Alloy uses an eventually consistent model to achieve clustering. This model assumes all participating Alloy deployments are interchangeable and converge on the same configuration file.

A standalone, non-clustered Alloy behaves the same as a single-node cluster.

You configure clustering by passing cluster command-line flags to the run command.

Use cases

Target auto-distribution

Target auto-distribution is the simplest use case of clustering. It lets scraping components running on all peers distribute the scrape load among themselves. Target auto-distribution requires all Alloy deployments in the same cluster to access the same service discovery APIs and scrape the same targets.

You must explicitly enable target auto-distribution on components by defining a clustering block.

alloy
prometheus.scrape "default" {
    clustering {
        enabled = true
    }

    ...
}

A cluster detects state changes when a node joins or leaves. All participating components locally recalculate target ownership and re-balance the number of targets they’re scraping without explicitly communicating ownership over the network.

Target auto-distribution lets you dynamically scale the number of Alloy deployments to handle workload peaks. It also provides resiliency because one of the node peers automatically picks up targets if a node leaves.

Alloy uses a local consistent hashing algorithm to distribute targets. On average, only ~1/N of the targets are redistributed.

Refer to the component reference documentation to check if a component supports clustering, such as: