split_clients
The `split_clients` directive allows NGINX to split clients into different groups based on a specified percentage and execute different actions for each group.
Description
The split_clients directive can be used within the http context to facilitate A/B testing and traffic distribution among multiple backends or configurations. Essentially, it directs requests from clients into one of several defined blocks based on a hashed client value, typically the client's IP address.
When the directive is defined, it accepts one or more percentages and corresponding blocks of configuration. The first argument to split_clients specifies the client request's percentage that should match for the first block to take effect, followed by rules for handling those clients. Each subsequent block can define additional percentages, effectively creating multiple 'buckets' of clients where each bucket can route traffic differently. This is useful, for example, when testing new features with a subset of users while directing the rest to the stable version.
To illustrate, if 70% of clients are being routed to one version of an application while the remaining 30% receives another version, the split_clients directive can manage this splitting based on the hash of the client's IP address. As a result, individual users will consistently land on the version they have been assigned to throughout their session, making it highly effective for consistent user experience in A/B tests and gradual rollouts.
Config Example
split_clients ${remote_addr} 70% { server server_v1; }
30% { server server_v2; };Make sure the percentages total 100% across all defined blocks.
The variable used for hashing (e.g., $remote_addr) should be stable across requests to ensure users remain in the same bucket.
Avoid using complex conditions or high cardinality data to ensure balanced distribution.