Add docs and examples for the BackendConfig Custom Resource.

deploy/README.md

@@ -45,11 +45,23 @@ The project defines a
 [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
 ``VarnishConfig`` to specify special configurations and features of
 Varnish running as an Ingress (beyond the standard Ingress
-specification):
+specification, see the [docs](/docs/ref-varnish-cfg.md) for details):
+
 ```
 $ kubectl apply -f varnishcfg-crd.yaml
 ```
 
+### BackendConfig Custom Resource definition
+
+The project also defines the Custom Resource ``BackendConfig`` to
+configure properties of Services that are implemented as Varnish
+backends, such as timeouts, health probes and load-balancing (see
+the [docs](/docs/ref-backend-cfg.md)):
+
+```
+$ kubectl apply -f backendcfg-crd.yaml
+```
+
 ### Deploy the controller
 
 This example uses a Deployment to run the controller container in the

docs/README.md

@@ -5,6 +5,7 @@ The docs in this folder cover these topics:
 * Technical references: authoritative documentation for these subjects:
 
   * [``VarnishConfig`` Custom Resource](ref-varnish-cfg.md)
+  * [``BackendConfig`` Custom Resource](ref-backend-cfg.md)
   * [controller command-line options](ref-cli-options.md)
   * [customizing the Pod template](varnish-pod-template.md) for Varnish
 

examples/README.md

@@ -22,3 +22,8 @@ requirements.
 
 * [Access control lists](/examples/acl) -- whitelisting or
   blacklisting requests by IP address
+
+* The [BackendConfig](/examples/backend-config) Custom Resource, to
+  configure properties such as timeouts, health probes and
+  load-balancing for Services to which requests are routed according
+  to an Ingress.

examples/backend-config/README.md

+# Sample BackendConfig resources
+
+The sample manifest in this folder configures BackendConfig resources,
+to specify properties of Services and their Endpoints when they are
+implemented as Varnish backends. These are Services named in the
+``backend`` field of an Ingress, to which requests are routed
+according to the Host header and/or URL path. See the
+[docs](/docs/ref-backend-cfg.md) for the tecnhinal reference.
+
+The example applies to the Services defined in the
+["cafe" example](/examples/hello) -- the ``coffee-svc`` and ``tea-svc``.
+
+First consider the BackendConfig for ``tea-svc``:
+
+```
+apiVersion: "ingress.varnish-cache.org/v1alpha1"
+kind: BackendConfig
+metadata:
+  name: tea-svc-cfg
+spec:
+  services:
+    - tea-svc
+[...]
+```
+
+The ``services`` array is required, must have at least one element,
+and must name Services in the same namespace in which the
+BackendConfig is defined. When a Service in the array is named as the
+``backend`` for an Ingress to be implemented by Varnish, the
+BackendConfig is applied to that Service. Listing more than one
+Service in the array is way to define one BackendConfig that applies
+to several Services.
+
+```
+spec:
+  [...]
+  host-header: cafe.example.com
+  connect-timeout: 1s
+  first-byte-timeout: 2s
+  between-bytes-timeout: 1s
+  max-connections: 200
+  [...]
+```
+
+These top-level properties of ``spec`` correspond to attributes of a
+[Varnish backend definition](https://varnish-cache.org/docs/6.1/reference/vcl.html#backend-definition).
+The configuration in the example means that:
+
+* The Host header of a backend request is set to ``cafe.example.com``
+  if it is missing from the request.
+
+* The connect timeout (for opening new connections to an Endpoint) is
+  one second.
+
+* The first byte timeout (until the first byte of a backend response
+  header is received) is two seconds.
+
+* The between bytes timeout (while a response is being received) is
+  one second.
+
+* No more than 200 connections to an Endpoint may be opened.
+
+The properties of ``spec.probe`` correspond to attributes of a
+[Varnish health probe](https://varnish-cache.org/docs/6.1/reference/vcl.html#probes):
+
+```
+spec:
+  probe:
+    url: /tea/healthz
+    expected-response: 200
+    timeout: 5s
+    interval: 5s
+    initial: 1
+    window: 3
+    threshold: 2
+```
+
+This defines the health probe requests for Endpoints of tea-svc such
+that:
+
+* The URL path of the request is ``/tea/healthz``.
+
+* Health probes are good when the response code is 200.
+
+* Responses time out after five seconds.
+
+* Probes are sent every five seconds.
+
+* Two of three probes must be good for the Endpoint to count as
+  healthy.
+
+* At startup, one probe is implicitly assumed to be good.
+
+The last part of the BackendConfig for ``tea-svc`` selects the
+[random](https://varnish-cache.org/docs/6.1/reference/vmod_directors.generated.html#new-xrandom-directors-random)
+director -- load-balancing requests to Endpoints is random (the
+default is round-robin):
+
+```
+spec:
+  [...]
+  director:
+    type: random
+```
+
+Now consider the BackendConfig for ``coffee-svc``:
+
+```
+apiVersion: "ingress.varnish-cache.org/v1alpha1"
+kind: BackendConfig
+metadata:
+  name: coffee-svc-cfg
+spec:
+  services:
+    - coffee-svc
+[...]
+```
+
+The top-level properties of ``spec`` just set the first-byte and
+between-bytes timeouts (other properties are left to the Varnish
+defaults):
+
+```
+spec:
+  [...]
+  first-byte-timeout: 3s
+  between-bytes-timeout: 2s
+```
+
+The ``spec.probe`` configuration sets an explicit request to be used
+for health probes (and some of the other attributes):
+
+```
+spec:
+  [...]
+  probe:
+    request:
+    - GET /coffee/healthz HTTP/1.1
+    - "Host: cafe.example.com"
+    - "Connection: close"
+    timeout: 3s
+    interval: 3s
+    window: 4
+    threshold: 3
+```
+
+The strings in the ``request`` array form lines in the probe request,
+separated by ``\r\n``, so this probe is sent as:
+
+```
+GET /coffee/healthz HTTP/1.1\r\n
+Host: cafe.example.com\r\n
+Connection: close\r\n
+\r\n
+```
+
+Note that a line with a request header must be explicitly quoted.
+Otherwise it is interpreted as a YAML object and rejected, since the
+array may only consist of strings.
+
+The ``spec.director`` configuration specifies the shard director
+for load-balancing, and sets the ``warmup`` and ``rampup`` parameters:
+
+```
+spec:
+  [...]
+  director:
+    type: shard
+    warmup: 50
+    rampup: 5m
+```
+
+The shard director shards requests to Endpoints by URL. This may be
+advantageous, for example, for applications with resources such as
+their own data caches, so that cache hits are more likely if requests
+with the same URL path are always sent to the same Endpoint.
+
+The ``warmup`` and ``rampup`` parameters serve to mitigate the impact
+of adding or removing Endpoints from the Service. ``warmup`` is the
+probability in percent that, instead of choosing the "first" Endpoint
+to which a request is ordinarily sharded, the director chooses the
+next Endpoint that would be chosen if the first Endpoint is
+removed. Then if the first Endpoint is removed, the "next" Endpoint
+has already received some of the requests that the director now sends
+to it. This allows an application resource such as a cache to be
+"pre-warmed" for some of the new requests it receives.
+
+``rampup`` is a time interval that begins when a new Endpoint is
+added. During that time, the director chooses the "next" Endpoint
+rather than the new Endpoint for a request, with a probability that is
+100% when the Endpoint is added, and decreases linearly to 0% at the
+end of the rampup interval. This mitigates the "thundering herd" of
+requests for a newly added Endpoint.
+
+The configuration above means that:
+
+* The "next" Endpoint is chosen by the director with probability 50%.
+
+* Newly added Endpoints have a rampup period of five minutes.

examples/backend-config/backend-cfg.yaml

+# Sample backend configurations
+
+apiVersion: "ingress.varnish-cache.org/v1alpha1"
+kind: BackendConfig
+metadata:
+  name: tea-svc-cfg
+spec:
+  # The services array is required and must have at least one element.
+  # Lists the names of Services that act as Backends for an Ingress in
+  # the same namespace, and are configured as backends for a Varnish
+  # Service that implements the Ingress. This config is to be applied
+  # to the Varnish backends corresponding to the Services named in the
+  # array.
+  services:
+    - tea-svc
+
+  # For requests routed to tea-svc:
+  # - The Host header is set to cafe.example.com if it is missing from
+  #   the request.
+  # - The connect timeout (for opening new connections to an Endpoint)
+  #   is one second.
+  # - The first byte timeout (until the first byte of a backend response
+  #   header is received) is two seconds.
+  # - The between bytes timeout (while a response is being received)
+  #   is one second.
+  # - No more than 200 connections to an Endpoint may be opened.
+  host-header: cafe.example.com
+  connect-timeout: 1s
+  first-byte-timeout: 2s
+  between-bytes-timeout: 1s
+  max-connections: 200
+  probe:
+    # Health probe requests for Endpoints of tea-svc:
+    # - Request URL path is /tea/healthz
+    # - Health probes are good when the response code is 200.
+    # - Five second timeout to receive responses.
+    # - Probes are sent every five seconds.
+    # - Two of three probes must be good for the Endpoint to count as
+    #   healthy.
+    # - At startup, one probe is implicitly assumed to be good.
+    url: /tea/healthz
+    expected-response: 200
+    timeout: 5s
+    interval: 5s
+    initial: 1
+    window: 3
+    threshold: 2
+  director:
+    # Use random load balancing of Endpoints.
+    type: random
+---
+apiVersion: "ingress.varnish-cache.org/v1alpha1"
+kind: BackendConfig
+metadata:
+  name: coffee-svc-cfg
+spec:
+  services:
+    - coffee-svc
+
+  # For requests routed to coffee-svc:
+  # - The first byte timeout is three seconds.
+  # - The between bytes timeout is two seconds.
+  first-byte-timeout: 3s
+  between-bytes-timeout: 2s
+  probe:
+    # Health probe for coffee-svc:
+    # - Requests are send as shown in the request array.
+    # - Timeout three seconds.
+    # - Three of four good probes are required for the Endpoint to
+    #   count as healthy.
+    request:
+    - GET /coffee/healthz HTTP/1.1
+    - "Host: cafe.example.com"
+    - "Connection: close"
+    timeout: 3s
+    interval: 3s
+    window: 4
+    threshold: 3
+  director:
+    # Shard requests to Endpoints by URL path.
+    # - 50% of requests are sent to the "next" Endpoint to which they
+    #   would be sharded if the "first" Endpoint were to be removed.
+    # - Requests for newly added Endpoints ramp up over five minutes.
+    type: shard
+    warmup: 50
+    rampup: 5m