Module resty.dns.balancer.ring

Ring-balancer.

This balancer implements a consistent-hashing algorithm as well as a weighted-round-robin.

This loadbalancer is designed for consistent hashing approaches and to retain consistency on a maximum level while dealing with dynamic changes like adding/removing hosts/targets (ketama principle).

Due to its deterministic way of operating it is also capable of running identical balancers (identical consistent rings) on multiple servers/workers (though it does not implement inter-server/worker communication).

Only dns is non-deterministic as it might occur when a peer is requested, and hence should be avoided (by directly inserting ip addresses). Adding/deleting hosts, etc (as long as done in the same order) is always deterministic.

Whenever dns resolution fails for a hostname, the host will relinguish all the indices it owns, and they will be reassigned to other targets. Periodically the query for the hostname will be retried, and if it succeeds it will get (different) indices reassigned to it.

When using setAddressStatus to mark a peer as unavailable, the slots it owns will not be reassigned. So after a recovery, hashing will be restored.

NOTE: This documentation only described the altered user methods/properties, see the user properties from the balancer_base for a complete overview.

Info:

  • Copyright: 2016-2019 Kong Inc. All rights reserved.
  • License: Apache 2.0
  • Author: Thijs Schreijer

Functions

hashCrc32 (str) Creates a CRC32 hash value from a string.
hashMd5 (str) Creates a MD5 hash value from a string.
new (opts) Creates a new balancer.


Functions

hashCrc32 (str)
Creates a CRC32 hash value from a string. The string will be hashed using CRC32. The returned hash value can be used as input for the getpeer function. This is simply a shortcut to ngx.crc32_short.

Parameters:

  • str (string) value to create the hash from

Returns:

    32-bit numeric hash
hashMd5 (str)
Creates a MD5 hash value from a string. The string will be hashed using MD5, and then shortened to 4 bytes. The returned hash value can be used as input for the getpeer function.

Parameters:

  • str (string) value to create the hash from

Returns:

    32-bit numeric hash
new (opts)

Creates a new balancer. The balancer is based on a wheel with a number of positions (the index on the wheel). The indices will be randomly distributed over the targets. The number of indices assigned will be relative to the weight.

The options table has the following fields;

  • hosts (optional) containing hostnames, ports and weights. If omitted, ports and weights default respectively to 80 and 10. The list will be sorted before being added, so the order of entry is deterministic.
  • wheelSize (optional) for total number of positions in the balancer (the indices), if omitted the size of order is used, or 1000 if order is not provided. It is important to have enough indices to keep the ring properly randomly distributed. If there are to few indices for the number of targets then the load distribution might become to coarse. Consider the maximum number of targets expected, as new hosts can be dynamically added, and dns renewals might yield larger record sets. The wheelSize cannot be altered, only a new wheel can be created, but then all consistency would be lost. On a similar note; making it too big, will have a performance impact when the wheel is modified as too many indices will have to be moved between targets. A value of 50 to 200 indices per entry seems about right.
  • order (optional) if given, a list of random numbers, size wheelSize, used to randomize the wheel. Duplicates are not allowed in the list.
  • requery (optional) interval of requerying the dns server for previously failed queries. Defaults to 1 if omitted (in seconds)
  • ttl0 (optional) Maximum lifetime for records inserted with ttl=0, to verify the ttl is still 0. Defaults to 60 if omitted (in seconds)
  • callback (optional) a function called when an address is added. See setCallback for details.

Parameters:

  • opts table with options

Returns:

    new balancer object or nil+error

Usage:

    -- hosts example
    local hosts = {
      "konghq.com",                                      -- name only, as string
      { name = "github.com" },                           -- name only, as table
      { name = "getkong.org", port = 80, weight = 25 },  -- fully specified, as table
    }
generated by LDoc 1.4.6 Last updated 2019-06-26 11:39:54