Running the server locally

Recap before running the server

The previous sections introduced the basic parts that are required for running Sovereign:

• We configured a YAML or Python template that generates static envoy configuration
• We added template context from either a file, http endpoint, or s3 bucket
• We used the context in the templates, making them produce dynamic envoy configuration

Running the Sovereign server

Installing sovereign

For this part of the tutorial I'm going to use uv to install and run sovereign for simplicity

1
2
mkdir controlplane
cd controlplane
uv init
uv add --prerelease=allow sovereign
uv add --prerelease=allow envoy_data_plane

uv run --prerelease=allow sovereign

Checking the interface

You should then be able to visit the server locally by browsing to http://localhost:8080

Upon browsing to Sovereign locally, you'll be redirected to its web interface. This web interface is read-only, and was created to enable quickly inspecting and troubleshooting issues with configuration.

We can use this interface now to see the configuration that the combination of our context and templates have generated.

Connecting an Envoy proxy to Sovereign

Writing the bootstrap

Creating a bootstrap file like the following will cause envoy to call Sovereign for clusters and listeners:

1
2
# ./envoy.yaml
node:
  id: envoy
  cluster: testing

admin:
  access_log_path: /dev/null
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 9901

static_resources:
  listeners:
  - name: static
    address:
      socket_address:
        address: 0.0.0.0
        port_value: 8085
    filter_chains:
      - filters:
        - name: hcm
          typed_config:
            '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
            stat_prefix: test
            codec_type: AUTO
            route_config: {}
            http_filters:
              - name: route to cluster
                typed_config:
                   '@type': type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

dynamic_resources:
  cds_config:
    api_config_source:
      api_type: REST
      transport_api_version: V3
      cluster_names:
        - sovereign
      refresh_delay: 5s

static_resources:
  clusters:
  - name: sovereign
    connect_timeout: 5s
    type: STATIC
    load_assignment:
      cluster_name: sovereign
      endpoints:
        - lb_endpoints:
            - endpoint:
                address:
                  socket_address:
                    address: 127.0.0.1
                    port_value: 8080

You don't have to use both CDS and LDS, you could just use one or the other if that suits your needs.

Running Envoy inside a container

Given that you have a file in the current directory named envoy.yaml, you can then run a proxy with the following command:

1
2
docker run --rm -it \
    --network=host \
    --volume ./envoy.yaml:/etc/envoy.yaml \
    envoyproxy/envoy:v1.31.0 \
    envoy -c /etc/envoy.yaml

Now that we have set up an envoy proxy with a basic dynamic config, we can expand on this by adding more discovery types.