vmod_directors¶
Varnish Directors Module¶
Manual section: | 3 |
---|
SYNOPSIS¶
import directors [from "path"] ;
DESCRIPTION¶
vmod_directors enables backend load balancing in Varnish.
The module implements a set of basic 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 {
new vdir = directors.round_robin();
vdir.add_backend(backend1);
vdir.add_backend(backend2);
}
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.
CONTENTS¶
- fallback
- fallback.add_backend
- fallback.backend
- fallback.remove_backend
- hash
- hash.add_backend
- hash.backend
- hash.remove_backend
- random
- random.add_backend
- random.backend
- random.remove_backend
- round_robin
- round_robin.add_backend
- round_robin.backend
- round_robin.remove_backend
round_robin¶
new OBJ = round_robin()
- Description
Create a round robin director.
This director will pick backends in a round robin fashion.
- Example
- new vdir = directors.round_robin();
round_robin.add_backend¶
VOID round_robin.add_backend(BACKEND)
- Description
- Add a backend to the round-robin director.
- Example
- vdir.add_backend(backend1); vdir.add_backend(backend2);
round_robin.remove_backend¶
VOID round_robin.remove_backend(BACKEND)
- Description
- Remove a backend from the round-robin director.
- Example
- vdir.remove_backend(backend1); vdir.remove_backend(backend2);
round_robin.backend¶
BACKEND round_robin.backend()
- Description
- Pick a backend from the director.
- Example
- set req.backend_hint = vdir.backend();
fallback¶
new OBJ = fallback()
- Description
Create a fallback director.
A fallback director will try each of the added backends in turn, and return the first one that is healthy.
- Example
- new vdir = directors.fallback();
fallback.add_backend¶
VOID fallback.add_backend(BACKEND)
- Description
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); vdir.add_backend(backend2);
fallback.remove_backend¶
VOID fallback.remove_backend(BACKEND)
- Description
- Remove a backend from the director.
- Example
- vdir.remove_backend(backend1); vdir.remove_backend(backend2);
fallback.backend¶
BACKEND fallback.backend()
- Description
- Pick a backend from the director.
- Example
- set req.backend_hint = vdir.backend();
random¶
new OBJ = random()
- Description
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();
random.add_backend¶
VOID random.add_backend(BACKEND, REAL)
- Description
Add a backend to the director with a given weight.
Each backend 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);
random.remove_backend¶
VOID random.remove_backend(BACKEND)
- Description
- Remove a backend from the director.
- Example
- vdir.remove_backend(backend1); vdir.remove_backend(backend2);
random.backend¶
BACKEND random.backend()
- Description
- Pick a backend from the director.
- Example
- set req.backend_hint = vdir.backend();
hash¶
new OBJ = hash()
- Description
Create a hashing backend director.
The director chooses the backend server by computing a hash/digest of the string given to .backend().
Commonly used with
client.ip
or a session cookie to get sticky sessions.- Example
- new vdir = directors.hash();
hash.add_backend¶
VOID hash.add_backend(BACKEND, REAL)
- Description
Add a backend to the director with a certain weight.
Weight is used as in the random director. Recommended value is 1.0 unless you have special needs.
- Example
- vdir.add_backend(backend1, 1.0); vdir.add_backend(backend2, 1.0);
hash.remove_backend¶
VOID hash.remove_backend(BACKEND)
- Description
- Remove a backend from the director.
- Example
- vdir.remove_backend(backend1); vdir.remove_backend(backend2);
hash.backend¶
BACKEND hash.backend(STRING)
- Description
Pick a backend from the backend director.
Use the string or list of strings provided to pick the backend.
- Example
- # pick a backend based on the cookie header from the client set req.backend_hint = vdir.backend(req.http.cookie);
COPYRIGHT¶
This document is licensed under the same licence as Varnish itself. See LICENCE for details.
- Copyright (c) 2013-2015 Varnish Software AS
COPYRIGHT¶
Copyright (c) 2013-2015 Varnish Software AS
All rights reserved.
Author: Poul-Henning Kamp <phk@FreeBSD.org>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.