![]() |
![]()
| ![]() |
![]()
NAMEvmod_directors - Varnish Directors Module SYNOPSISimport directors [as name] [from "path"] new xround_robin = directors.round_robin() DESCRIPTIONvmod_directors enables backend load balancing in Varnish. The module implements load balancing techniques, and also serves as an example on how one could extend the load balancing capabilities of Varnish. To enable load balancing you must import this vmod (directors). Then you define your backends. Once you have the backends declared you can add them to a director. This happens in executed VCL code. If you want to emulate the previous behavior of Varnish 3.0 you can just initialize the directors in vcl_init{}, like this: sub vcl_init { As you can see there is nothing keeping you from manipulating the directors elsewhere in VCL. So, you could have VCL code that would add more backends to a director when a certain URL is called. Note that directors can use other directors as backends. new xround_robin = directors.round_robin()Create a round robin director. This director will pick backends in a round robin fashion. Example: new vdir = directors.round_robin(); VOID xround_robin.add_backend(BACKEND)Add a backend to the round-robin director. Example: vdir.add_backend(backend1); VOID xround_robin.remove_backend(BACKEND)Remove a backend from the round-robin director. Example: vdir.remove_backend(backend1); BACKEND xround_robin.backend()Pick a backend from the director. Example: set req.backend_hint = vdir.backend(); new xfallback = directors.fallback(BOOL sticky=0)Create a fallback director. A fallback director will try each of the added backends in turn, and return the first one that is healthy. If sticky is set to true, the director will keep using the healthy backend, even if a higher-priority backend becomes available. Once the whole backend list is exhausted, it'll start over at the beginning. Example: new vdir = directors.fallback(); VOID xfallback.add_backend(BACKEND)Add a backend to the director. Note that the order in which this is done matters for the fallback director. Example: vdir.add_backend(backend1); VOID xfallback.remove_backend(BACKEND)Remove a backend from the director. Example: vdir.remove_backend(backend1); BACKEND xfallback.backend()Pick a backend from the director. Example: set req.backend_hint = vdir.backend(); new xrandom = directors.random()Create a random backend director. The random director distributes load over the backends using a weighted random probability distribution. The "testable" random generator in varnishd is used, which enables deterministic tests to be run (See: d00004.vtc). Example: new vdir = directors.random(); VOID xrandom.add_backend(BACKEND, REAL)Add a backend to the director with a given weight. Each backend will receive approximately 100 * (weight / (sum(all_added_weights))) per cent of the traffic sent to this director. Example: # 2/3 to backend1, 1/3 to backend2. vdir.add_backend(backend1, 10.0); vdir.add_backend(backend2, 5.0); VOID xrandom.remove_backend(BACKEND)Remove a backend from the director. Example: vdir.remove_backend(backend1); BACKEND xrandom.backend()Pick a backend from the director. Example: set req.backend_hint = vdir.backend(); new xhash = directors.hash()Create a hashing backend director. The director chooses the backend server by computing a hash/digest of the string given to xhash.backend(). Commonly used with client.ip or a session cookie to get sticky sessions. Example: new vdir = directors.hash(); VOID xhash.add_backend(BACKEND, REAL weight=1.0)Add a backend to the director with a certain weight. Weight is used as in the random director. Recommended and default value is 1.0 unless you have special needs. Example: vdir.add_backend(normal_backend); vdir.add_backend(larger_backend, 1.5); VOID xhash.remove_backend(BACKEND)Remove a backend from the director.
BACKEND xhash.backend(STRING)Pick a backend from the hash director. Use the string or list of strings provided to pick the backend.
new xshard = directors.shard()Create a shard director. IntroductionThe shard director selects backends by a key, which can be provided directly or derived from strings. For the same key, the shard director will always return the same backend, unless the backend configuration or health state changes. Conversely, for differing keys, the shard director will likely choose different backends. In the default configuration, unhealthy backends are not selected. The shard director resembles the hash director, but its main advantage is that, when the backend configuration or health states change, the association of keys to backends remains as stable as possible. In addition, the rampup and warmup features can help to further improve user-perceived response times. ShardingThis basic technique allows for numerous applications like optimizing backend server cache efficiency, Varnish clustering or persisting sessions to servers without keeping any state, and, in particular, without the need to synchronize state between nodes of a cluster of Varnish servers:
When used with clusters of varnish servers, the shard director will, if otherwise configured equally, make the same decision on all servers. In other words, requests sharing a common criterion used as the shard key will be balanced onto the same backend server(s) no matter which Varnish server handles the request. The drawbacks are:
MethodWhen xshard.reconfigure() is called explicitly (or implicitly at the end of any task containing reconfigurations like xshard.add_backend()), a consistent hashing circular data structure gets built from the last 32 bits of SHA256 hash values of <ident><n> (default ident being the backend name) for each backend and for a running number n from 1 to the replicas argument to xshard.reconfigure(). Hashing creates the seemingly random order for placement of backends on the consistent hashing ring. When xshard.add_backend() was called with a weight argument, replicas is scaled by that weight to add proportionally more copies of the that backend on the ring. When xshard.backend() is called, a load balancing key gets generated unless provided. The smallest hash value in the circle is looked up that is larger than the key (searching clockwise and wrapping around as necessary). The backend for this hash value is the preferred backend for the given key. If a healthy backend is requested, the search is continued linearly on the ring as long as backends found are unhealthy or all backends have been checked. The order of these "alternative backends" on the ring is likely to differ for different keys. Alternative backends can also be selected explicitly. On consistent hashing see:
Error ReportingFailing methods should report errors to VSL with the Error tag, so when configuring the shard director, you are advised to check: varnishlog -I Error:^vmod_directors.shard Additional information may be provided as Notices, which can be checked using varnishlog -I Notice:^vmod_directors.shard
VOID xshard.set_warmup(REAL probability=0.0)Set the default warmup probability. See the warmup parameter of xshard.backend(). If probability is 0.0 (default), warmup is disabled. VOID xshard.set_rampup(DURATION duration=0)Set the default rampup duration. See rampup parameter of xshard.backend(). If duration is 0 (default), rampup is disabled. VOID xshard.associate(BLOB param=0)Associate a default directors.shard_param() object or clear an association. The value of the param argument must be a call to the xshard_param.use() method. No argument clears the association. The association can be changed per backend request using the param argument of xshard.backend(). BOOL xshard.add_backend(BACKEND backend, [STRING ident], [DURATION rampup], [REAL weight])BOOL xshard.add_backend( Add a backend backend to the director. ident: Optionally specify an identification string for this backend, which will be hashed by xshard.reconfigure() to construct the consistent hashing ring. The identification string defaults to the backend name. ident allows to add multiple instances of the same backend. rampup: Optionally specify a specific rampup time for this backend. Otherwise, the per-director rampup time is used (see xshard.set_rampup()). weight: Optionally specify a weight to scale the xshard.reconfigure() replicas parameter. weight is limited to at least 1. Values above 10 probably do not make much sense. The effect of weight is also capped such that the total number of replicas does not exceed UINT32_MAX. BOOL xshard.remove_backend([BACKEND backend], [STRING ident])BOOL xshard.remove_backend( Remove backend(s) from the director. Either backend or ident must be specified. ident removes a specific instance. If backend is given without ident, all instances of this backend are removed. BOOL xshard.clear()Remove all backends from the director. BOOL xshard.reconfigure(INT replicas=67)Explicitly reconfigure the consistent hashing ring to reflect backend changes to become effective immediately. If this method is not called explicitly, reconfiguration happens at the end of the current task (after vcl_init {} or when the current client or backend task is finished). INT xshard.key(STRING)Convenience method to generate a sharding key for use with the key argument to the xshard.backend() method by hashing the given string with SHA256. To generate sharding keys using other hashes, use a custom vmod
like vmod blobdigest
<https://code.uplex.de/uplex-varnish/libvmod-blobdigest/blob/master/README.rst>
BACKEND xshard.backend([ENUM by], [INT key], [BLOB key_blob], [INT alt], [REAL warmup], [BOOL rampup], [ENUM healthy], [BLOB param], [ENUM resolve])BACKEND xshard.backend( Lookup a backend on the consistent hashing ring. This documentation uses the notion of an order of backends for a particular shard key. This order is deterministic but seemingly random as determined by the consistent hashing algorithm and is likely to differ for different keys, depending on the number of backends and the number of replicas. In particular, the backend order referred to here is _not_ the order given when backends are added.
VOID xshard.debug(INT)intentionally undocumented new xshard_param = directors.shard_param()Create a shard parameter set. A parameter set allows for re-use of xshard.backend() arguments across many shard director instances and simplifies advanced use cases (e.g. shard director with custom parameters layered below other directors). Parameter sets have two scopes:
The per-VCL scope defines defaults for the per backend scope. Any changes to a parameter set in backend context and in vcl_pipe {} only affect the respective backend request. Parameter sets cannot be used in client context except for vcl_pipe {}. The following example is a typical use case: A parameter set is associated with several directors. Director choice happens on the client side and parameters are changed on the backend side to implement retries on alternative backends: sub vcl_init { VOID xshard_param.clear()Reset the parameter set to default values as documented for xshard.backend().
Restricted to: vcl_pipe, backend, housekeeping. VOID xshard_param.set([ENUM by], [INT key], [BLOB key_blob], [INT alt], [REAL warmup], [BOOL rampup], [ENUM healthy])VOID xshard_param.set( Change the given parameters of a parameter set as documented for xshard.backend().
Restricted to: vcl_pipe, backend, housekeeping. STRING xshard_param.get_by()Get a string representation of the by enum argument which denotes how a shard director using this parameter object would derive the shard key. See xshard.backend(). INT xshard_param.get_key()Get the key which a shard director using this parameter object would use. See xshard.backend(). INT xshard_param.get_alt()Get the alt parameter which a shard director using this parameter object would use. See xshard.backend(). REAL xshard_param.get_warmup()Get the warmup parameter which a shard director using this parameter object would use. See xshard.backend(). BOOL xshard_param.get_rampup()Get the rampup parameter which a shard director using this parameter object would use. See xshard.backend(). STRING xshard_param.get_healthy()Get a string representation of the healthy enum argument which a shard director using this parameter object would use. See xshard.backend(). BLOB xshard_param.use()For use with the param argument of xshard.backend() to associate this shard parameter set with a shard director. Restricted to: vcl_pipe, backend, housekeeping. BACKEND lookup(STRING)Lookup a backend by its name. Restricted to: housekeeping. ACKNOWLEDGEMENTSDevelopment of a previous version of the shard director was partly sponsored by Deutsche Telekom AG - Products & Innovation. Development of a previous version of the shard director was partly sponsored by BILD GmbH & Co KG. COPYRIGHTThis document is licensed under the same licence as Varnish itself. See LICENCE for details. SPDX-License-Identifier: BSD-2-Clause Copyright (c) 2013-2015 Varnish Software AS Copyright 2009-2020 UPLEX - Nils Goroll Systemoptimierung All rights reserved. Authors: Poul-Henning Kamp <phk@FreeBSD.org>
|