Remotes

Configuration of remotes for virtual_registry.

Remotes are selected according to the defined load_balancer policy (fallback by default). When a remote does not respond, or responds with response status 5xx, a different remote is selected and the fetch is retried. Fetches are retried until one of the following conditions are met:

• We get a non-5xx response from the remote.
• We have retried varnish.params.max_retries times.
• We have tried all the remotes.

Example:

virtual_registry:
  registries:
   - name: example
     remotes:
     - url: https://example.com

url

# (...)
     remotes:
     - url: https://example.com

Type: String

URL of the remote, on the form scheme://host:port.

Scheme can be http or https. If omitted, defaults to https if port has been set to 443, defaults to http otherwise.

Host can be an IP address or a domain name. If the domain name resolves to multiple IP addresses, traffic is load balanced evenly over them.

priority

# (...)
     remotes:
     - url: https://example.com
       priority: 2

Type: Integer

Default: 1

Priority can be used to divide a list of remotes into distinct load balancer groups. A remote from the highest priority group is always chosen first, and groups with lower priority are only selected if none of the higher priority give a successful response.

Priority increases with a lower numerical value. 1 is the highest possible priority.

weight

# (...)
     remotes:
     - url: https://example.com
       weight: 10

Type: Number

Default: 1

Weight can be used to shift the traffic distribution over the list of remotes. Has no effect when the failover load balancer policy is used.

Weight increases with a higher numerical value. 1 is the lowest possible weight.

dns_ttl

# (...)
     remotes:
     - url: https://example.com
       dns_ttl: 300

Type: Number

Override the interval at which DNS is resolved for this remote, in seconds. By default, DNS resolution follows the TTL from the DNS response.

preserve_subdomain

# (...)
     remotes:
     - url: https://example.com
       preserve_subdomain: true

Type: Boolean

Default: false

Preserve the subdomain from the original request when fetching from this remote. When enabled, the subdomain portion of the incoming request’s Host header is prepended to the remote’s hostname. The final hostname is also used for DNS and TLS SNI when accessing the remote.

preserve_host

# (...)
     remotes:
     - url: https://example.com
       preserve_host: true

Type: Boolean

Default: false

Forward the original request’s Host header to the remote, while the connection still targets the remote’s url. Useful when a single backend routes internally based on the Host header. Takes precedence over preserve_subdomain.

probe

Configuration for a health check probe to monitor the availability of a remote.

url

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz

Type: String

URL of the remote, on the form /path. It is mandatory to set either url or tcponly, and they are mutually exclusive.

interval

Type: Number

Default: 5

The number of seconds between health checks.

timeout

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz
         interval: 5

Type: Number

Default: 2

The timeout in seconds for each health check.

expected_response

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz
         expected_response: 404

Type: Integer

Default: 200

Expected HTTP status code from the health check endpoint.

window

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz
         window: 5

Type: Integer

Default: 8

The number of most recent health check results to consider when determining health.

threshold

# (...)
     remotes:
     - url: https://example.com
       probe:
         url: /healthz
         threshold: 4

Type: Integer

Default: 3

The minimum number of successful checks in the window required to be considered healthy

tcponly

# (...)
     remotes:
     - url: https://example.com
       probe:
         tcponly: true

Type: Boolean

Default: false

Perform a TCP health check instead of HTTP.