Cluster

Imagizer scales horizontally by running multiple instances as a cluster. Each node load balances requests across the cluster using Consistent Hashing with Bounded Loads, so each image maps to the same node (maximizing cache hits) without overloading any one node.

See the Config Reference to enable cluster mode, either across an AWS AutoScaling group or a static list of nodes.

Request flow

A request first reaches a front node, which load balances it to the backend node that owns that image's hash. The backend serves the image from its cache, or processes it on a cache miss.

The front and backend may be the same machine: every node plays both roles, and a node that owns the requested image's hash processes the request itself. See Logging in a cluster for which node writes the access log and which writes the application log.

Node communication

Cluster nodes must freely communicate with each other through ports 80, 17001, and optionally port 17006 for cache purging.

WARNING

Do not open ports 17001 and 17006 to the public internet.

Health checks

Every node serves a default health check endpoint at /health, which returns 200 healthy once the node is up, even if it is still running the default configuration. customHealthCheckEndpoint adds a second endpoint with its own path, response code, and response text. The default /health stays available alongside it.

External load balancers

When an external load balancer (such as an AWS ALB) fronts the cluster, point its health check at a customHealthCheckEndpoint rather than the default /health. The custom endpoint exists only after you apply your configuration, so an instance still running the default configuration (for example, a freshly launched instance) fails the health check and receives no traffic.

Configuration consistency New (v14.5-90.15)

All nodes in a cluster must run the same configuration. Imagizer verifies this automatically in cluster mode, with no extra setup. A node running a different configuration than its peers (a "drifted" node) stays out of rotation until its configuration converges, then rejoins automatically.

Imagizer enforces consistency at two levels:

Node health checks

Cluster nodes health check each other every few seconds, and each check carries the checking node's config hash. A node whose configuration does not match fails the check and drops out of the checking node's rotation. Each node therefore balances requests only across peers running the same configuration. Health checks from external load balancers or monitoring systems do not carry a config hash and are not affected.

The node that fails the check logs the mismatch as a warning in its application log.

Requests

Cluster nodes also validate each other's configuration on every request, in both directions:

• The front node sends its config hash with the request. A backend running a different configuration rejects it.
• The backend stamps its config hash on the response. The front node discards a response rendered under a different configuration.

In both cases the front node retries the request locally, so clients never receive an image rendered under a stale configuration, even in the window before a drifted node fails its next health check.