If the failover load-balancing algorithm is configured with one or more load-spreading base DNs, then requests that target entries below a load-spreading base DN may be balanced across any of the servers with the same health check state and location. Requests targeting a specific portion of the data will consistently be routed to the same server, but requests targeting a different portion of the data may be sent to a different server.

Load spreading is useful for deployments in which the DIT contains a large number of branches below a common parent, and in which most operations (including search operations, as indicated by the search base DN) only target entries at least one level below that common parent. For example, this may be useful for a multi-tenant deployment in which all of the entries for a given tenant are within their own branch, and all of the tenant branches reside below a common parent.

Load spreading is configured with the load-spreading-base-dn property. The value(s) of this property are the base DN(s) below which the tenant entries reside. For example, in a deployment with a DIT like the following, the load-spreading-base-dn value would be set to ou=customers,dc=example,dc=com:

  • dc=example,dc=com
    • ou=customers,dc=example,dc=com
      • ou=Customer 1,ou=customers,dc=example,dc=com
      • ou=Customer 2,ou=customers,dc=example,dc=com
      • ou=Customer 3,ou=customers,dc=example,dc=com
      • ...

If the load-spreading-base-dn property is not configured, the failover load-balancing algorithm will uses the default behavior. If the property is configured with one or more values, but a client requests an operation that targets an entry that is not below any of the configured base DNs, then that operation will be handled using the default behavior. When the load-spreading-base-dn property is configured with one or more values, the load-balancing algorithm will continue to generate the same list of lists, but the order of the servers within each list will be determined using the following algorithm:

  1. If the list is empty or contains only a single item, then leave it unchanged and skip the remaining steps.
  2. Identify the RDN component from the target entry DN that is exactly one level below one of the load-spreading-base-dn values. If the targeted entry is not below any of the configured load-spreading-base-dn values, then the order of servers in each of those lists will be based only on the order in which they appear in the load-balancing algorithm’s backend-server property. The remaining steps are skipped.
  3. Compute a SHA-1 digest from the normalized string representation of the identified RDN component. SHA-1 is notably faster than more secure digest algorithms, and it does a very good job at distributing bits across the entire range of the 160 bits that it generates.
  4. Create a non-negative integer from the last 31 bits of the computed SHA-1 digest.
  5. Compute a modulus using the integer value as the dividend, and the number of servers in the current list as the divisor. This will yield an integer value that is between 0 and (list.size() - 1), inclusive.
  6. If the modulus computed is equal to zero, no further action is necessary. If not, move a number of servers equal to the computed modulus from the beginning of the list to the end of the list. The order of the elements that are moved should be preserved.

For example, consider a load-spreading-base-dn value of “ou=customers,dc=example,dc=com”, a list that contains three servers (ds1, ds2, and ds3, in that order), and a modify request that targets the entry with DN “uid=jdoe,ou=People,ou=Acme,ou=customers,dc=example,dc=com”. The RDN component immediately below the load-spreading-base-dn is “ou=Acme”. The normalized string representation of that RDN component is “ou=acme”, and the hexadecimal representation of the SHA-1 digest of that is “f0c69713535daf8816038f1bceab70380c92b83e”. The last 31 bits of that SHA-1 digest are 0c92b83e hex, which is 210942014. With 210942014 modulo 3 is 2, which means that the first two servers are moved from the beginning of the list to the end of the list, resulting in and order of ds3, ds1, ds2.

While this algorithm will spread the load across multiple backend servers, it does not mean that there will be an even distribution of the load across all of those servers. The load-balancing algorithm will still prioritize based on location and health check state, so the load will generally be spread only across the available servers in the same location as the Directory Proxy Server. Second, assuming that the entries that are immediate children of a load-spreading-base-dn are the tops of the branches that define tenants, some tenants will still be targeted more heavily than others (because they have more entries, or because their entries are accessed more frequently). The modulo operation may therefore not result in an even distribution across those servers.