Scaling with Proxy Nodes

This document assumes that the primary node is pre-existing and that only the layer of proxy nodes is new.

The primary node may itself be a more complex deployment with a load balancer, such as one of the resilient deployment models, or a legacy High-Availability Clustering (HA-C) cluster.

This reference architecture is compatible with a broad range of load balancers such as the following:

One simple balancing strategy is "round robin," and this is adequate for most deployments; for other options, see Advanced Considerations.

Setting up a load balancer requires header changes similar to those required by a reverse proxy. See Run Behind a Reverse Proxy for examples.

The number of proxy nodes you will need depends on your use case. To improve the scalability of a primary node under continuous read load, a single proxy node may be sufficient.

For situations with large request spikes, it may be necessary to use multiple proxy nodes with repository-replicated caches to protect the primary.

If the read load is anonymous (unauthenticated), then no special handling is required. However, if the read load is authenticated, then you should use an external identity provider (LDAP, SAML) so that credentials are synchronized for each user.

For authenticated read loads, you will need to set up the appropriate roles, privileges, and content selectors on each proxy node.

We do not recommend using this pattern with user tokens as they are not synchronized between the various instances.

Using this pattern may reduce search result completeness for Maven users as they must rely on Nexus Repository’s built-in search features (the UI or REST endpoints).

Nexus Repository’s built-in search only shows results for components that have been cached on that proxy node; it will not show components that are available on the primary and not yet cached on a proxy node.

This limitation does not apply to the search commands of non-Maven clients using Visual Studio’s NuGet functionality or the npm command-line client. Nexus Repository passes these ecosystem-specific search commands upstream from the proxy node to the primary node and from primary to remote repositories (if applicable).

From time to time, you may add or remove repositories from your primary node. This will require keeping the proxy nodes updated with appropriate configurations.

For proxy nodes that are long-lasting, the simplest approach is to use the Repositories REST API to add, update, and remove repositories from the proxy nodes as necessary.

When considering this pattern, the primary node should already be an enterprise-sized machine capable of coping with your regular loads. For this pattern, the number of Jetty Threads can be increased from 400 (default) to 600.

An example primary node configuration could appear as follows:

A proxy node machine could look like this:

The optimal storage size for each proxy node will depend on the characteristics of your load (e.g., if there is diversity or commonality in the components most requested by the readers) and the rate of new component production.

Whatever size you choose, use a cleanup policy that will keep the overall storage level within the allocated storage.

If the primary node has a large number of repositories, you may want to split them among separate sets of proxy nodes to improve the chance of a cache hit. Each pool only covers a subset of the repositories in the primary node.

In this model, the load balancer must decode the HTTP request and route the traffic to the appropriate proxy node pool.

In the recommended model, any new proxy nodes added to the pool will start with empty caches; cache misses will be common until the proxy node has time to catch up. Initially, this may detract from the overall performance of downstream clients. If the primary node has a lot of components (i.e., hundreds of thousands or millions), it may take some time before the cache is sufficiently warm to improve performance overall.

One technique for reducing the cache warming time is to clone an existing proxy node. You can do this using a normal backup and restore process on a proxy node, or by creating a snapshot at the VM or storage level and using it to instantiate a new proxy node.

Cloned nodes will start with a warm cache. Depending on the nature of the workload, even a clone from a days-old backup can be a significant improvement over an empty cache.

If you are using a cloud blob store (e.g., S3, Azure, etc.), the Nexus database includes a reference to a specific storage bucket. If you clone the Nexus Repository database/instance, this can cause two Nexus Repository instances to attempt to use the same bucket for blob storage, which will cause issues. Instead, you will need to create a different bucket and change the blob store configuration using the NEXUS_BLOB_STORE_OVERRIDE environment variable to use the new bucket as described in Using Replicated S3 Blob Stores for Recovery or Testing.

Cache hit and miss rates can be calculated from the data available at the Nexus Repository metrics endpoint ./service/metrics/data. Calculating the inbound vs. outbound requests through the proxy node.