Sources are used to retrieve arbitrary data that can then be represented in templates as envoy configuration.

A new custom source can be added by subclassing the Source class and adding an entry point using setuptools.

todo add guide for adding entry points

When the control plane receives a request for configuration from an envoy proxy, it first runs through all the configured sources and combines the data received from them into a single list, to be used within templates.

The results are cached for a configurable number of seconds to allow several proxies to poll at the same time, receiving data that is consistent with each other.


Checks for all match keys present in existing sources and adds them to a list

A dict is used instead of a set because dicts cannot have duplicate keys, and have ordering since python 3.6

sovereign.sources.contains(container, item)
sovereign.sources.match_node(request: sovereign.schemas.DiscoveryRequest, modify=True) → List[dict]

Checks a node against all sources, using the node_match_key and source_match_key to determine if the node should receive the source in its configuration.

  • request – envoy discovery request

  • modify – switch to enable or disable modifications via Modifiers


Runs .get() on every configured Source; returns the results in a generator.


Returns a copy of source data in order to ensure it is not modified outside of the refresh function

sovereign.sources.setup_sources(source: sovereign.schemas.Source)

Takes Sources from config and turns them into Python objects, ready to use.


All source data is stored in sovereign.sources._source_data. Since the variable is outside this functions scope, we can only make in-place modifications to it via its methods.

This function retrieves all sources, puts them into a temporary list, and then clears and re-fills _source_data with the new data.

The process is done in two steps to avoid _source_data being empty for any significant amount of time.

Adding your own source

You can use the following base class to create your own sources.

They can then be added as an entry point which will be automatically loaded by Sovereign.

Currently implemented Sources