Backend
A backend
declaration creates an origin server in VCL code.
This can also be achieved via an API call, using the CLI, or using the web interface.
WARNING: It's usually better to create backends using the API, CLI, or web interface, rather than using custom VCL code. This will offer better validation, and enable a number of features not available to VCL-defined backends, including shielding.
Syntax
The following examples show the syntax of a backend definition with all possible properties:
backend backend_name {
# Required to be set for all VCL defined backends .dynamic = true; .share_key = "YOUR_SERVICE_ID";
# Server location .host = "storage.googleapis.com"; .port = "443"; .ssl = true; .ssl_cert_hostname = "storage.googleapis.com"; .ssl_check_cert = always; .ssl_sni_hostname = "storage.googleapis.com";
# Timeouts and limits .between_bytes_timeout = 10s; .connect_timeout = 1s; .first_byte_timeout = 15s; .max_connections = 200;
# Host header override .host_header = "storage.googleapis.com"; .always_use_host_header = true;
# Healthcheck .probe = { .dummy = true; .request = "HEAD / HTTP/1.1" "Host: storage.googleapis.com" "Connection: close"; .expected_response = 200; .interval = 60s; # Send a check every 60s .timeout = 2s; # Allow up to 2s for the backend to respond to the check .window = 5; # Keep a history of 5 checks .initial = 3; # Start with 3 successful checks in the history .threshold = 4; # 4 of the recent checks must be successful for backend to be healthy }}
A backend name is alphanumeric and may not start with a number (most backends created via the API, CLI or web interface will be prefixed with F_
in VCL to prevent a leading digit).
Property descriptions are the same as those described in the API reference, with the following exceptions:
- All backend definitions in VCL must additionally have a
dynamic
property set totrue
and ashare_key
(see below). - The API properties
address
,hostname
,ipv4
andipv6
map to thehost
property of the backend declaration. - The API property
use_ssl
becomesssl
here. - Time values are expressed using
RTIME
literals here, while the API takes a number in milliseconds. - The
probe
field in the backend declaration is configured via the API separately as a healthcheck.
Using share_key
to reduce healthcheck load
Backends with identical definitions, including the healthcheck (.probe
property in VCL), will share the same healthcheck process. However, since this behavior can be unexpected, backends created via the API, CLI, or web interface will automatically set the share_key
property to the service ID. This ensures that two otherwise-identical backends added to two different services will perform healthchecks independently.
Defining backends in VCL, however, provides an opportunity to set the share_key
to something that is consistent across multiple services in your account. If the backends are also identical in all other ways, they will share the same healthcheck, reducing the amount of healthcheck traffic to your origin. Healthchecks are already performed independently from each POP, so if you have 10 services and there are 100 POPs and you configure your healthcheck to try your origin once per second, this will create healthcheck traffic of 1000 rps.
If all ten of those services use exactly the same backend with the same settings, and you define the backend in VCL, use an identical share_key
, this will consolidate their healthchecks. In the above example this would reduce healthcheck load to only 100 rps.
Usage
A backend is assigned to a request by setting the value of req.backend
in VCL:
set req.backend = backend_name;