[RFC] server.vcls for per-domain VCLs

[gquintard]

The current helm charts don't allow for split configuration per domain (https://info.varnish-software.com/blog/one-vcl-per-domain), but it's quite easy to make happen, we just need to agree on an API.

In short, I want to introduce a new field, server.vcls , looking like this:

vcls:
  # routes lists all the "main" VCLs, one for each domains or subpath to cover
  routes:
    # by default, the name is use for the VCL name, label, and the hostname the VCL will be used for.
    # files will be placed in /etc/varnish/routes
    foo.com:
      content: |
        vcl 4.1;
        backend default none;
        sub vcl_recv { return (synth(200)); };

    # some VCL may be used on multiple domain/subpaths
    some_alias:
      # matcher's type isn't defined yet, I'm sure @Alve will have opinions :-)
      # for now we can use a list of wildcard
      matcher:
        - example.com/admin/*
        - *.api.bar.com
      # instead of content, you migth just want to point at a file on disk
      path: /etc/some/file.vcl

    # we can make "default" special, in that it will be run in case no other route matches
    default:
      content: |
        vcl 4.1
        backend default none;
        sub vcl_recv { return (synth(404)); };

  # finally we list all the non-main VCLs, i.e. the files included directly or recursively by the VCLs in vcls.routes
  # files will be placed in /etc/varnish/includes
  includes:
    an_include.vcl: |
      ...
    another_include.vcl: |
      ...

This would allow to supersede server.vclConfigs, replacing

server:
  vclConfigs:
    default.vcl: |
      vcl 4.1;
      include "included.vcl";
    included.vcl: |
      backend default none;

with

server:
  routes:
    default:
      content: |
        vcl 4.1;
        include "included.vcl";
  includes:
    included.vcl: |
      backend default none;

it's slightly longer, but this would be a unified syntax that would cover the regular case and per-domain configuration

[sirn]

This sounds like a generalized version of https://docs.varnish-software.com/varnish-helm/guides/using-cmdfile-for-multi-tenant/ (I just noticed that someone accidentally ate vclConfigs sub-level config), am I understanding this correctly?

p.s. hi :D

[gquintard]

Hi friend!

Correct, this would automatically generate the start CLI file (I'll share a branch soon), the idea here is to simplify the general use case as much as possible

[sirn]

Makes sense. I'm wondering if matchers should have been a list of objects instead:

server:
  vcls:
    routes:
      <label>:
        matchers:   # here, so we can have a non-domain matching too
          - domain: <domain>
          - domain: <domain>
          - custom: <vcl match verbatim>
        content: |
          <vcl>
    includes:
      <filename>:   # still unsure if list of objects would be better
        content: |  # I'd say let's have `content` sub-level key for consistency
          <vcl>
      # versus this:
      #- filename: <filename>
      #  content: |
      #    <vcl>

[AlveElde]

Hi Sirn!

If you squint hard enough, this kinda resembles HTTPRoutes. I'm not saying we go reimplementing varnish-gateway here, but perhaps we can borrow some of the API design patterns?

Here's a "simple" example:

server:
  routes:
    foo: # VCL and label names are derived from this
      hostnames: # As defined in https://gateway-api.sigs.k8s.io/reference/spec/#hostname
      - "www.foo.com"
      rules:
      - vcl: # No "matches:", this catches everything
          path: "/etc/varnish/foo.vcl"
    bar:
      hostnames:
      - "www.bar.com"
      rules:
      - vcl:
          path: "/etc/varnish/bar.vcl" # This is the "main VCL", needs no explicit name
          includes:
          - name: "admin.vcl" # Name referenced by the main VCL
            path: "/etc/varnish/admin.vcl"

More advanced example:

server:
  routes:
    foo:
      hostnames:
      - "www.example.com"
      - "example.com"
      rules: # Rules are processed from top to bottom
      - matches:
        - path:
            type: PathPrefix
            value: /healthz
        vcl: # Only exectuted for /healthz requests
          content: |
            vcl 4.1;
            backend default none;
            sub vcl_recv { return (synth(200)); }
      - vcl: # Gets everything else going to (www.)example.com
          path: "/etc/varnish/default.vcl"
    catchall: # Has no hostnames, so it acts as a catch-all
      rules:
      - vcl:
          content: |
            vcl 4.1;
            backend default none;
            sub vcl_recv { return (synth(404)); }

[gquintard]

hum...

First thing first: routes can't actually be a map, we need it to be an array, or we need to handle match overlaps, and I'm not doing that.

Second, @AlveElde , I think you have a decent point, in practice, we just need to implement hostnames first, and match later on.

This makes the one-vcl case look like this:

server:
  routes:
    - vclContent:
        vcl 4.1;
        backend default none;
        sub vcl_recv { return (synth(200)); }

It's not stellar, but I can live with that. vclContent for the actual content, VCLPath for paths (I know, what a stroke of genius!)

Now, the question is: do we go with server.routes or with server.vcls.routes? I think I'd prefer the latter, so we can put the included VCLs in server.vcls.includes?

[AlveElde]

First thing first: routes can't actually be a map, we need it to be an array, or we need to handle match overlaps, and I'm not doing that.

Fair enough, I'm happy as long as the routing is predictable and well defined.

It's not stellar, but I can live with that. vclContent for the actual content, VCLPath for paths (I know, what a stroke of genius!)

vclConfigPath would align better with the current config :) Also, that hopefully disambiguates it from vcl_path (the cache param).

Now, the question is: do we go with server.routes or with server.vcls.routes? I think I'd prefer the latter, so we can put the included VCLs in server.vcls.includes?

I'm not against allowing some simple VCLs to be provided directly in values.yaml, but do we really want people to maintain complex VCL inline in their values file? I'm really no expert here, but I would probably want to maintain my VCL in external VCL ConfigMaps.

[gquintard]

Fair enough, I'm happy as long as the routing is predictable and well defined.

That was more a realization that my initial draft was dumb than a critique on your snippets :-)

vclConfigPath would align better with the current config :) Also, that hopefully disambiguates it from vcl_path (the cache param).

is aligning a good point here? Having server.vcls.routes[*].vclConfigPath and server.vclConfigPath would be confusing?
Not sure, and again, my call is to kill server.vclConfig* eventually, so maybe I'm arguing against myself here.

I'm not against allowing some simple VCLs to be provided directly in values.yaml, but do we really want people to maintain complex VCL inline in their values file? I'm really no expert here, but I would probably want to maintain my VCL in external VCL ConfigMaps.

agreed, but remember that values.yaml and just be transport, instead of input source, so we need a way for people to have everything in the yaml. Also, the problem with a configMap is that if you add a route, you need to modify both the values.yaml and the configMap, which is impractical and error-prone.

Eventually (and not limited to helm charts), I'd love to have self-documented directory trees that we can point Varnish at. But that needs to come later