Terminology

XDS

Envoy uses the XDS protocol to discover the resources that it should configure.

More information can be found in the Envoy documentation

Discovery Request

This is the XDS mechanism by which an Envoy proxy requests configuration from a control-plane, such as Sovereign.

1
2
HTTP POST /v2/discovery:<resource_type>
Host: sovereign

{
    "node": {
      "cluster": "ABC",
      "metadata": {},
      "build_version": "abcdefabcdefabcdefabcdefabcdefabcdefabcd/N.N.N/Clean/RELEASE",
      "locality": {
        "zone": "ABCDEF"
      } 
    },
    "resource_names": [],
    "version_info": "0"
}

Sovereign uses parts of this request to identify Envoys and handle exactly what configuration they should receive.

Discovery Response

Simply the response to a Discovery Request.

The structure is as follows:

1
2
{
  "version_info": "123123123123",
  "resources": [
    {
      "@type": "<type_url>",
      ...
    },
    ...
  ] 
}

Templates

Sovereign uses a templating system to generate configuration for Envoy proxies.

A typical configuration may look like the following:

1
2
templates:
  1.31.0:
    routes: 
      protocol: file
      serialization: jinja
      path: templates/1.13.0/routes.yaml
    clusters: 
      protocol: python
      path: templates/1.13.0/clusters.py
    listeners: 
      protocol: file
      serialization: jinja
      path: templates/1.13.0/listeners.yaml

The contents that should be in a template is covered in the Tutorial

Context

Context is the name given to the dynamic data that should be included when generating the configuration.

Context is a key:value mapping, and when context is supplied to a template, the keys become available as variables.

How these concepts fit together

When Sovereign starts up, it begins a cycle where it continually refreshes Context for new data on a configurable schedule

After Sovereign has Source data stored in memory, with modifiers applied to it, it is ready to receive requests.

Sovereign passes the Context to the Template which generates a string ready to be serialized into a Discovery Response and passed to the Node.