This vmod offers flexible load-balancing features, with notably local reconfiguration and smart retry behavior.
vcl 4.1;
import udo;
backend be1 { .host = "1.1.1.1"; }
backend be2 { .host = "2.2.2.2"; }
backend be3 { .host = "3.3.3.3"; }
backend be4 { .host = "4.4.4.4"; }
# create a weighted random director
sub vcl_init {
new udo_dir = udo.director();
udo_dir.set_type(random);
udo_dir.add_backend(be1, weight = 1);
udo_dir.add_backend(be2, weight = 1);
udo_dir.add_backend(be3, weight = 1);
udo_dir.add_backend(be4, weight = 4);
}
sub vcl_backend_fetch {
set bereq.backend = udo_dir.backend();
# for videos, use consistent hashing
if (bereq.url ~ "^/video/") {
udo_dir.set_type(hash);
}
}
sub vcl_backend_response {
# if the response isn't a 200, retry, udo_dir will pick a different
# backend, even with consistent hashing enabled
if (beresp.status != 200) {
return (retry);
}
}
An important facet of udo is that each task get its own cache of the state,
allowing the VCL writer to change load-balancing policy or to blocklist some
backends easily on a per-request fashion.
OBJECT udo.director()
Creates a new director. must be called in vcl_init.
Returns
An empty director object, configure for consistent hashing.
Method VOID .add_backend(BACKEND backend, REAL weight = 1, [BLOB hash])
Introduce be into the director, with an optional weight and hash. If no
hash is given, the VCL name of the backend is used.
Note that this call must be made from vcl_init and will fail the
initialization of the VCL if a backend with the same hash already exists in
the director.
Arguments
BACKEND backend - the backend to add to the directorREAL weight - a number dictating how much of the traffic should be pushed
to the new backendBLOB hash - override the hash of the backend (based on its VCL name). Must
be 32 bytes long.Returns
Nothing
VOID .set_type(ENUM {hash, fallback, random})
Changes the type of the director:
If used in vcl_init, the change is global and all requests will inherit this
property. If called from client (e.g. vcl_recv) or backend (e.g.
vcl_backend_fetch) context, the type is changed just within this context.
Arguments
ENUM {hash, fallback, random} - a policy keywordReturns
Nothing
VOID .set_hash(BLOB hash)
Override the object hash, within a client or backend context. It’s useful in two
notable cases:
- to select a backend on a subset of the URL, for example in the video case
where you need to send all requests pertaining to one stream to the same
backend
- to use .dump() before vcl_hash has been run
Arguments
BLOB hash - The object hash to use for the current taskReturns
Nothing
STRING .dump(ENUM {list, json} fmt = list)
Output some of the director’s internal information.
json will produce a fairly complete (and large) string:
{
"hash": "0x77d833ebbeae1ef5fcc14eb2fe94cf23a7d12bf5d582926e199b68808c6788b0",
"type": "hash",
"backends": [
{
"name": "s2",
"used": false,
"score": 5.733361,
"weight": 1.000000,
"hash": "0xad328846aa18b32a335816374511cac163c704b8c57999e51da9f908290a7a4"
},
...
]
}
While list is a simple comma-separated list:
s2, s1, s3, s4
Arguments
ENUM {list, json} fmt - the output format to use, defaults to listReturns
The current request-local state of the director in the selected format.
BACKEND .backend()
Return a backend, according to the current type set.
Arguments
None
Returns
A healthy, non-used backend.
VOID .exhaust_backend(BACKEND be)
Backends are automatically used and avoided later while in the same task, but
this function forcefully marks be as “used” so that it won’t be returned
again while in the same VCL task, without needing to actually use it first.
Arguments
BACKEND be - The backend to avoid.Returns
Nothing