/vmod-prehash

A director VMOD for Varnish 4.1

Primary LanguageC

VMOD prehash

Varnish Prehash Director w/ Overrides & Random Fallthrough

Manual section:3

SYNOPSIS

import prehash [from "path"]

new xdirector = prehash.director()

    VOID xdirector.set_hash_header(STRING)

    VOID xdirector.add_backend(BACKEND, REAL)

    VOID xdirector.add_exclusive_backend(BACKEND, STRING)

    VOID xdirector.add_lastresort_backend(BACKEND, REAL)

    VOID xdirector.finalize()

    BACKEND xdirector.backend()

    BACKEND xdirector.self()

    BACKEND xdirector.hash(STRING)

new xpassthru = prehash.passthru(BACKEND)

    BACKEND xpassthru.backend()

DESCRIPTION

A Varnish 6.2 meta-director that layers three sub-directors internally in order to provide deterministic load-balancing (affinity) behavior as well as default-case and ultimate fail-over support so that requests can be handled by the "most preferred" application server backend currently available.

new xdirector = prehash.director()

Description
Create a new prehash meta-director.
Example
vd_main = prehash.director();

VOID xdirector.set_hash_header(STRING)

Description
Set the header name whose value, if present, will be hashed in order to pick a backend. By default req.http.Host is used.
Example
vd_main.set_hash_header("Publication");

VOID xdirector.add_backend(BACKEND, REAL)

Description
Add a new backend or director to the the prehash meta-director. New inbound requests that can be hashed (via Host header or header set w/ set_hash_header()) are "pinned" to the backend closest to their hash value. This is deterministic based on the order in which backends were added (and its also a consistent hash, an unhealthy backend will NOT move hash values of other backends around). It is NOT, however, trivial to predetermine which hash values will be distributed to which backends; for that feature use add_exclusive_backend(). Note that weight should probably always be 1.0 otherwise the hash can become non-consistent.
Example
vd_main.add_backend(vd_rr1.backend(), 1.0);

VOID xdirector.add_exclusive_backend(BACKEND, STRING)

Description
Add a backend that will be exclusively used for a given hash value. The hash value is computed from the second argument. Note that normal backends can be reused as exclusive backends, although exclusives, if present, are always attempted first. Exclusive backends require an exact hash value match, not simply "nearest" as with add_backend().
Example
vd_main.add_exclusive_backend(vd_rr1.backend(), "www.myhost.com");

VOID xdirector.add_lastresort_backend(BACKEND, REAL)

Description
Add a last resort backends that will only be used if all normal backends (added via add_backend() are unhealthy). Multiple last resort backends can be added and will be used in round-robin order. Note that std.healthy() does not take into account lastresort backends when determining if the overall prehash meta-director is healthy, only if at least one of the backends added via add_backend() is healthy.
Example
vd_main.add_lastresort_backend(lastresort, 1.0);

VOID xdirector.finalize()

Description
Finalizes the entire meta-director. This should only be called after all backends have been added and no new backends can be added after this has been called. It is not necessary to call this method unless exclusive backends are actually in use.
Example
vd_main.finalize();

BACKEND xdirector.backend()

Description
Returns a Varnish 6.2 backend director object that can be assigned to req.backend_hint. Final resolution of the actual real backend is deferred until just before the bereq is sent. Calling std.healthy() on the director returned by this method will be true if any non-exclusive backend is healthy _excluding_ last resorts.
Example
set req.backend_hint = vd_main.backend();

BACKEND xdirector.self()

Description

Use the current req or bereq (depending on whether this is called from the client or backend state machines) to determine the actual backend to be used. This is subtly different than calling backend() as it returns the final backend rather than the director which is later used to resolve the backend.

Note that this method is typically only used for debugging.

Example
sub vcl_init {
  new vdir = prehash.director();
  vdir.add_backend(some_backend, 1.0);
}

sub vcl_recv {
  req.backend_hint = vdir.self();
}

BACKEND xdirector.hash(STRING)

Description
Hash the arguments and return a backend. This is typically only used for debugging.
Example
sub vcl_init {
  new vdir = prehash.director();
  vdir.add_backend(some_backend, 1.0);
}

sub vcl_recv {
  req.backend_hint = vdir.hash("foo", "bar");
}

new xpassthru = prehash.passthru(BACKEND)

Description
Creates a pass-through director to make vcl standardization a bit easier. Pass-through directors always return the director or backend they encapsulate when their backend method is called.
Example
backend ahost {
  .host = "127.0.0.1";
}

sub vcl_init {
  new s_ahost = prehash.passthru(ahost);
  new vdir = directors.round_robin();
  vdir.add_backend(s_ahost.backend());
}

BACKEND xpassthru.backend()

Description
Returns the actual backend or director that the passthru wraps.