Last updated Jan 2, 2025

Context

In the previous section we created templates that serve static envoy configuration for clusters.

These templates will give back the same result every time.

What is context?

Although it's fine to deploy sovereign with static templates, the advantage of using sovereign in the first place is the ability to bring in data that changes over time and using it to influence how configuration is rendered.

Context is what gives you the ability to serve dynamic config.

Adding context to templates

Sovereign has a few builtin ways to provide context. There's a guide in the "Extending" section if your needs aren't covered by the builtin plugins.

See the following tabs for some of the ways you can add context.

In this example we have a file that is changing on-disk. Maybe your server running sovereign has a cronjob or some other mechanism that updates a file on a schedule with new information.

Let's imagine a file is located at /etc/backends.json and has a list of backends.

You can tell sovereign to load this file using the following configuration

1
2
template_context:
  context:
    my_backends:
      protocol: file
      serialization: json
      path: /etc/backends.json

Using any of the above examples, let's consider two possible sets of data:

1
2
[
    {
        "cluster_name": "galactus",
        "hostname": "edgediag.services.atlassian.com",
        "port": 443,
        "tls": true
    },
    {
        "cluster_name": "omegastar",
        "hostname": "galactus.mycompany.local",
        "port": 42069
    },
    {
        "cluster_name": "wingman",
        "hostname": "wingman.mycompany.local",
        "port": 8080
    }
]

This data is simple mainly because it is homogenous, consistent, predictable from item to item.

For the purposes of the tutorial we recommend using a file, so that you can see the results straight away.

Perhaps these examples remind you of your own data, or give you ideas about how you could supply different data to sovereign.

We can now transform our original, static template, into one that is filled in with dynamic data

Template examples using context

Using the same YAML as in the previous tutorial, let's augment it to bring in the data and create more clusters:

1
2
resources:
{%- for backend in my_backends %}
- '@type': type.googleapis.com/envoy.config.cluster.v3.Cluster
  name: {{ backend["cluster_name"] }}
  connect_timeout: 0.25s
  type: STRICT_DNS
  {%- if backend.get("tls") %}
  transport_socket:
    name: envoy.transport_sockets.tls
    typed_config:
      '@type': type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
  {%- endif %}
  load_assignment:
    cluster_name: {{ backend["cluster_name"] }}
    endpoints:
      - lb_endpoints:
          - endpoint:
              address:
                socket_address:
                  address: {{ backend["hostname"] }}
                  port_value: {{ backend["port"] }}
{%- endfor %}

Reloading context on a schedule

By default, sovereign does not reload context. You can enable this behavior, and configure how frequently it occurs, like so:

1
2
template_context:
  refresh: true    # defaults to false
  refresh_rate: 60 # default 3600 (1 hour)
  context:
    # Your context items here
    example:
      protocol: file
      serialization: json
      path: /etc/foobar.json

Now that we've added dynamic configuration via context, let's run the server and see it configuring Envoy.

Rate this page: