Search
Varnish Enterprise

Unified director object (udo)

Description

The udo 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 deny some backends easily on a per-request fashion.

Note: Calling std.healthy() on this director from a client context, for example vcl_recv, will always return false. This is subject to change in the future. Doing the same from a backend context returns true or false like any other director, depending on whether there are any healthy and unused backends in the director.

API

director

OBJECT director()

Create an empty hash director object. One characteristic of this director is that within a VCL task, it’ll remember which backends have been used, and it will skip them for the subsequent decisions.

Arguments: None

Type: Object

Returns: Object.

.set_type

VOID .set_type(ENUM {hash, fallback, random})

Changes the type of the director:

  • hash: use Highest Random Weight algorithm, using the backends and object hashes to pick a backend
  • fallback: use the first healthy backend available, by order of addition in the director
  • random: pick a random backend

If used in sub vcl_init, the change is global and all requests will inherit this property. If called from client (e.g. sub vcl_recv) or backend (e.g. sub vcl_backend_fetch) context, the type is changed just within this context.

Arguments: None

Type: Method

Returns: None

.set_subtype

VOID .set_subtype(ENUM {hash, fallback, random} subtype, INT top)

Apply a different type to the top highest scoring backends in the director. When set, the director will calculate a subtype score in addition to a main type score for each backend. For a given request, a list of all the backends in the director is created and sorted by main score. But each time the director is resolved to a backend, the top scoring backends are first re-sorted according to their subtype score. Used and unhealthy backends do not count towards the top limit, so when a backend is exhausted during a retry, it no longer counts towards the limit, and the director re-sorts the subset with one additional backend.

An example use-case is sharding objects over multiple backends. By setting .set_subtype(random, 2), the director will shard each object over two backends. This is useful for partial replication in a two-tier architecture.

Arguments:

  • top accepts type INT

  • subtype is an ENUM that accepts values of hash, fallback, and random

Type: Method

Returns: None

.set_hash

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 sub vcl_hash has been run

The blob must be 32 bytes long.

Arguments:

  • hash accepts type BLOB

Type: Method

Returns: None

.add_backend

VOID .add_backend(BACKEND be, 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 sub vcl_init and will fail the initialization of the VCL if a backend with the same hash already exists in the director.

The blob must be 32 bytes long.

Arguments:

  • be accepts type BACKEND

  • weight accepts type REAL with a default value of 1 optional

  • hash accepts type BLOB

Type: Method

Returns: None

.backend

BACKEND .backend()

Return a backend, according to the current type set.

Arguments: None

Type: Method

Returns: Backend

.dump

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:

  • fmt is an ENUM that accepts values of list, and json with a default value of list optional

Type: Method

Returns: String

.exhaust_backend

VOID .exhaust_backend(BACKEND be)

Mark be as “used” so that it won’t be returned again while in the same VCL task.

Arguments:

  • be accepts type BACKEND

Type: Method

Returns: None

.reset

VOID .reset(ENUM {exhausted, health} reset, [BACKEND be])

Reset attributes that are cached for the current task. Resetting exhausted will mark all backends as unused. Resetting health will prompt the director to re-check the health of all backends. If the optional be parameter is supplied, the reset only applies to that backend.

Arguments:

  • be accepts type BACKEND

  • reset is an ENUM that accepts values of exhausted, and health

Type: Method

Returns: None

.subscribe

VOID .subscribe(STRING tag)

Subscribe to an ActiveDNS DNS group. This director will start to generate dynamic backends based on DNS results and DNS group configuration. For more information on how to create and configure a DNS group, see the ActiveDNS VMOD documentation.

Depending on the DNS and DNS group, dual-address backends may be created. The backend hash used for the Highest Random Weight algorithm is generated from the combination of ipv4 address, ipv6 address, and port. ActiveDNS guarantees that each backend hash is unique.

If a dynamic backend is created with port number 443, and no backend hint has been set for the DNS group, ssl is implicitly enabled for that backend. However, if a backend hint has been set for the DNS group, .ssl = 1; must be set in the backend definition for ssl to be enabled.

When creating a backend from an SRV record, the SRV record weight is used as the weight of that backend. The weight influences the hash distribution in the same way as for static backends. Currently, the SRV record priority is ignored.

The name of each backend has the following format

udo.DIRNAME.(sa[4,6]:IP:PORT)[.(sa6:IP:PORT)]

Example backends for a director named udo_dir:

udo.udo_dir.(sa4:1.1.1.1:443) udo.udo_dir.(sa4:2.2.2.2:443).(sa6:::2:443) udo.udo_dir.(sa6:::3:443)

Example configuration

import udo;
import activedns;

sub vcl_init {
  new group1 = activedns.dns_group();
  group1.set_host("example.com");

  new udo_dir = udo.director();
  udo_dir.subscribe(group1.get_tag());
}

Arguments:

  • tag accepts type STRING

Type: Method

Returns: None

.set_identity

VOID .set_identity([STRING string], [BLOB hash])

For static backends, you can optionally use this method to manually set the identity of a node instead of relying on self-identification. The identity can be provided as either a string or a 32 byte hash, and must match one of the backends in the director. If the backend was added to the director using .add_backend() with the optional hash argument, the same hash should be passed to this function. Otherwise, the name of the backend should be passed as a string. Can only be used in vcl_init.

Arguments:

  • string accepts type STRING

  • hash accepts type BLOB

Type: Method

Returns: None

.is_identified

BOOL .is_identified()

Returns whether or not the director has successfully determined it’s own identity. The identity can either be determined through self-identification with .self_identify(), or it can be set manually with .set_identity().

Arguments: None

Type: Method

Returns: Bool

.get_identifier

STRING .get_identifier()

Returns a random alphanumeric identifier string.

The identifier should be placed in a header when self-routing a request, and becomes temporarily associated with the backend Varnish is fetching from. When an identifier header is received, it should be passed to the directors .self_identify() method, which will attempt to self-identify the director. When the director has successfully self-identified, this function returns an alphanumeric representation of this directors identity hash.

Arguments: None

Type: Method

Returns: String

.self_identify

BOOL .self_identify(STRING identifier)

Take an identifier string and attempt to self-identify the director, returns true if successful. The director keeps track of identifiers that have been retrieved with .get_identifier(), so if the identifier passed to this method is recognized, this director must have sent a request to itself. The backend that the identifier is associated with becomes the identity of the director.

If more than one identifier is passed in a comma-separated string, this method returns true if any of the identifiers/identities are recognized. The director identity is never set when more than one identifier is passed. This works both before and after self-identification, so it can be used to detect loops in a self-routing cluster.

Arguments:

  • identifier accepts type STRING

Type: Method

Returns: Bool

.self_is_next

BOOL .self_is_next([INT lookahead])

Returns true if this node is next in line for this request. The next in line for each request is determined by ordering the backends according to the director type (usually hash), and checking whether the directors identity matches the next healthy and unused backend in the list.

If lookahead is supplied, more than one backend is checked for an identity match. A lookahead value of two will match the director identity against the two next healthy and unused backends.

Minimal self-routing example

sub vcl_recv {
  if (udo_dir.self_identify(req.http.identifier)) {
    return (synth(242, "Self-Identified"));
  }
}

sub vcl_backend_fetch {
  if (!udo_dir.self_is_next()) {
    set bereq.http.identifier = udo_dir.get_identifier();
    set bereq.backend = udo_dir.backend();
  }
}

sub vcl_backend_response {
  if (beresp.status == 242 && beresp.reason == "Self-Identified") {
    return (retry);
  }
}

The above example is intended to show the bare minimum VCL required implement self-routing.

This VMOD ships also with a VCL called cluster.vcl, which uses this VMOD to implement self routing in a more complete way compared to the example above.

Please note that new versions of this file might alter the behavior slightly, if such changes can improve the overall design and performance of the solutions it provides.

If you use the VCL or the new self routing functions in this VMOD, please pay attention to change logs and release announcements until this notice has been removed.

The VCL file can be included at the top of your VCL to enable self-routing

include "cluster.vcl";

cluster.vcl provides a self-routing director called cluster, all the logic required to self-route within the cluster, and options to modify the caching behavior.

Available options:

  • token: Required. Used to indicate that a request is coming a cluster node.
  • primaries: Optional, default “1”. Determines the number of nodes that can go to origin for a given object.
  • replicas: Optional. If set, determines the number of long duration replicas that should be stored across the cluster.
  • long_ttl: Optional. TTL set for long duration replicas.
  • long_grace: Optional. Grace set for long duration replicas.
  • long_keep: Optional. Keep set for long duration replicas.
  • long_stores: Optional. Sets the MSE stores for long duration replicas.
  • short_ttl: Optional. TTL set for short duration objects.
  • short_grace: Optional. Grace set for short duration objects.
  • short_keep: Optional. Keep set for short duration objects.
  • short_stores: Optional. Sets the MSE stores for short duration objects.

Example configuration

import activedns;

include "cluster.vcl";

backend origin { .host = "origin.node"; }

sub vcl_init {
  new cluster_group = activedns.dns_group();
  cluster_group.set_host("varnish.nodes:6081");
  cluster.subscribe(cluster_group.get_tag());

  cluster_opts.set("token", "secret");
  cluster_opts.set("replicas", "2");
  cluster_opts.set("short_stores", "none");
  cluster_opts.set("long_stores", "ssd");
}

sub vcl_backend_fetch {
  set bereq.backend = origin;
}

This configuration will self route requests among nodes resolved from varnish.nodes, and the primary node for each request will fetch from origin. When caching an object in the cluster, two nodes will store the object on SSD, while the rest of the nodes store the object in memory. TTL, grace, and keep are not modified.

Arguments:

  • lookahead accepts type INT

Type: Method

Returns: Bool

Availability

The udo VMOD is available in Varnish Enterprise version 6.0.8r2 and later.