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 tongx.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, additional to the ones from the
balancer_base
;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 oforder
is used, or 1000 iforder
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. ThewheelSize
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, sizewheelSize
, used to randomize the wheel. Duplicates are not allowed in the list.
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 }