By default Sovereign will look for a YAML/JSON configuration file at /etc/sovereign.yaml
This can be overridden with the environment variable SOVEREIGN_CONFIG
1 2SOVEREIGN_CONFIG=file:///srv/sovereign/example.yaml
Take note of the file://
prefix used to indicate that it comes from a location on-disk.
Multiple configuration files can also be specified, and values will be replaced by the rightmost specified file.
Common example:
1 2SOVEREIGN_CONFIG=file:///srv/common.yaml,file:///srv/environments/production.yaml
Any values in production.yaml
will merge over the top of common.yaml
.
A list of Sources that Sovereign should use to obtain Instances.
1 2sources: # Clusters from a local file - type: file scope: clusters config: spec: protocol: file serialization: yaml path: /etc/envoy/static_clusters.yaml # Listeners from an etcd cluster - type: file scope: listeners config: spec: protocol: http serialization: json path: etcd.internal:8081/v2/keys/envoy_listeners # Other resources from an S3 bucket - type: file scope: default config: spec: protocol: s3 serialization: json path: my-bucket-name:envoy_data.json # Inline routes provided at deployment time - type: inline scope: routes config: instances: - name: virtualhost_custom_01 domains: ['*.custom.tld'] routes: - match: prefix: / redirect: host_redirect: somewhere-else.tld path_redirect: /docs
Various settings to change how source polling behaves:
How often (in seconds) Sovereign should refresh all sources. Defaults to 30.
When Sovereign polls sources, it stores them in-memory until they are refreshed/changed.
When serving out discovery requests, sovereign uses the in-memory sources to decide whether or not
an Envoy proxy is up-to-date, based on their "version_info"
.
This setting controls how sovereign makes this determination:
context
: Sovereign will compare a hash of various data (sources, template context, envoy node metadata) with the received envoy node version.content
: Sovereign will fully render a response, and compare a hash of the contents with the received envoy node version.Node matching configuration:
Whether Sovereign should compare the configured node & source keys. If set to False, all sources will be used when generating configuration.
Defaults to True
What key to look for within sources when considering which data should be supplied to particular Envoy proxies.
What key to look for within the discovery request of an Envoy node, to see which source data it should be supplied with.
A mapping of envoy version and template paths to use when responding to discovery requests.
See the templates section of the tutorial for more information
1 2templates: <envoy_version OR "default">: type: <discovery type> spec: protocol: <file/http/s3/etc> serialization: <yaml/json/string/python/etc> path: <file path>
1 2templates: # Specific version, including patch version 1.13.1: type: listeners spec: protocol: file serialization: yaml path: /etc/envoy/listeners.yaml # Target all patch versions of a particular minor release 1.14: type: listeners spec: protocol: file serialization: yaml path: /etc/envoy/listeners.yaml # If none of the above match, use this one default: type: listeners spec: protocol: file serialization: yaml path: /etc/envoy/listeners.yaml
Template context is extra data that is included in all templates.
The specified context can be dynamically loaded, and reloaded on a schedule.
A mapping of variable names and loadable specifications to make available in templates.
Specifying template context:
1 2template_context: context: # Make a python module available as "ipaddress" in template markdown ipaddress: protocol: module path: ipaddress # Make a file available to all templates via markdown default_routes: protocol: file serialization: json path: /etc/stuff.json
Using template context within a template with the above example:
1 2# /etc/envoy/listeners.yaml resources: - name: listener address: socket_address: address: {{ ipaddress.IPv4Address(0)|string }} # Makes "0.0.0.0" port_value: 80 protocol: TCP filter_chains: - filters: - name: envoy.http_connection_manager config: stat_prefix: http codec_type: AUTO http_filters: - name: envoy.router config: {{ default_routes }} # inlines the JSON blob
A 'loadable path' is a path that is interpreted by the config loaders built into sovereign
Whether or not to continually reload template context. Default is False.
How often (in seconds) Sovereign should reload template context. Defaults to 3600. (Only one of refresh_rate
or refresh_cron
can be set).
Cron expression for when Sovereign should reload template context. (Only one of refresh_rate
or refresh_cron
can be set).
Number of times to retry context refresh before emitting an error metric
Default is 3.
Time in seconds to wait before trying a context refresh again
Default is 10.
A list of modifiers that should be applied to Sources.
These modifiers can only access and modify one instance at a time.
See the modifiers page under advanced for info on how to set this up.
A list of global modifiers that should be applied to Sources. These modifiers can access the entire Instances object, therefore applying modifications that can span across instances.
See the modifiers page under advanced for info on how to set this up.
Enable tracebacks and extra detail in certain HTTP error responses.
An environment string mainly used for logging purposes.
This field is deprecated. Please specify environment in logging
via log_fmt
instead
When set to True, Sovereign will raise a HTTP exception for any DNS resolution failures that occur when using
the sovereign.utils.eds:locality_lb_endpoints
utility.
If False, it will return the supplied DNS name instead of IP addresses. This may cause Envoy to fail to load the configuration.
Default is False.
This field is deprecated. It is suggested to supply a module via template_context
that can perform
dns resolution in templates instead.
Settings for authentication. It is strongly recommended to set these via environment variables.
Controls whether or not Sovereign will reject XDS requests that do not contain auth. Default is false.
For information on how to enable and supply authentication in XDS requests, see :ref:Authentication
A list of strings that are considered valid for authentication. When Sovereign receives a
request from an Envoy proxy, it checks for an auth
field in the node metadata.
Sovereign attempts to decrypt the field, and checks if it is in this list of strings.
It is recommended to set this option via the environment variable SOVEREIGN_AUTH_PASSWORDS
.
1 2<div class="sc-gLdKKF bwagGt"><section class="sc-SFOxd iupVFy"><div class="sc-hkaZBZ gWhWHQ"><style data-emotion="css snhnyn">.css-snhnyn{display:inline-block;-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;line-height:1;}.css-snhnyn >svg{overflow:hidden;pointer-events:none;max-width:100%;max-height:100%;color:var(--icon-primary-color);fill:var(--icon-secondary-color);vertical-align:bottom;}.css-snhnyn >svg stop{stop-color:currentColor;}@media screen and (forced-colors: active){.css-snhnyn >svg{-webkit-filter:grayscale(1);filter:grayscale(1);--icon-primary-color:CanvasText;--icon-secondary-color:Canvas;}}</style><span aria-hidden="true" style="--icon-primary-color:#FF8B00;--icon-secondary-color:#FFFAE6" class="css-snhnyn"><svg width="24" height="24" viewBox="0 0 24 24" role="presentation"><g fill-rule="evenodd"><path d="M12.938 4.967c-.518-.978-1.36-.974-1.876 0L3.938 18.425c-.518.978-.045 1.771 1.057 1.771h14.01c1.102 0 1.573-.797 1.057-1.771L12.938 4.967z" fill="currentColor"/><path d="M12 15a1 1 0 01-1-1V9a1 1 0 012 0v5a1 1 0 01-1 1m0 3a1 1 0 010-2 1 1 0 010 2" fill="inherit"/></g></svg></span></div><div class="sc-jOBXIr jErMvQ"><div class="sc-kIWQTW nnCfa"> These passwords allow a person to authenticate to Sovereign and download configuration in plain-text. </div></div></section></div>
The Fernet key that Sovereign will use to encrypt/decrypt data.
It is recommended to set this option via the environment variable SOVEREIGN_ENCRYPTION_KEY
.
1 2<div class="sc-gLdKKF bwagGt"><section class="sc-SFOxd iupVFy"><div class="sc-hkaZBZ gWhWHQ"><style data-emotion="css snhnyn">.css-snhnyn{display:inline-block;-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;line-height:1;}.css-snhnyn >svg{overflow:hidden;pointer-events:none;max-width:100%;max-height:100%;color:var(--icon-primary-color);fill:var(--icon-secondary-color);vertical-align:bottom;}.css-snhnyn >svg stop{stop-color:currentColor;}@media screen and (forced-colors: active){.css-snhnyn >svg{-webkit-filter:grayscale(1);filter:grayscale(1);--icon-primary-color:CanvasText;--icon-secondary-color:Canvas;}}</style><span aria-hidden="true" style="--icon-primary-color:#FF8B00;--icon-secondary-color:#FFFAE6" class="css-snhnyn"><svg width="24" height="24" viewBox="0 0 24 24" role="presentation"><g fill-rule="evenodd"><path d="M12.938 4.967c-.518-.978-1.36-.974-1.876 0L3.938 18.425c-.518.978-.045 1.771 1.057 1.771h14.01c1.102 0 1.573-.797 1.057-1.771L12.938 4.967z" fill="currentColor"/><path d="M12 15a1 1 0 01-1-1V9a1 1 0 012 0v5a1 1 0 01-1 1m0 3a1 1 0 010-2 1 1 0 010 2" fill="inherit"/></g></svg></span></div><div class="sc-jOBXIr jErMvQ"><div class="sc-kIWQTW nnCfa"> This key can be used to decrypt any data that has been encrypted by it and then stored, for example in version control. </div></div></section></div>
If Sovereign has been installed with Sentry (via pip install sovereign[sentry]
), the DSN to send Sentry events to.
Whether or not to emit statsd metrics
Where to emit statsd metrics
Port to use when emitting metrics to above host
A key:value map of
1 2statsd: tags: environment: 'env://SERVICE_ENVIRONMENT'
Suffix for all emitted metrics. Default is sovereign
See :ref:Metrics
for a list of metrics emitted.
Currently cache keys are constructed from the following discovery request elements:
1 2api_version, resource_type, req.envoy_version, req.resource_names, req.desired_controlplane, req.hide_private_keys, req.type_url, req.node.cluster, req.node.locality, req.node.metadata.get("auth", None), req.node.metadata.get("num_cpus", None),
Whether or not discovery caching is enabled. Requires a Redis server. Default: False.
The domain name or IP of the Redis server. Default: localhost Also configurable via environmental variable DISCOVERY_CACHE_REDIS_HOST.
The client port of the Redis server. Default: 6379 Also configurable via environmental variable DISCOVERY_CACHE_REDIS_PORT.
Whether the Redis server requires TLS. Default: False
Password if required for Redis client connections. Default: None Also configurable via environmental variable DISCOVERY_CACHE_REDIS_PASSWORD.
Whether the redis client library should also perform in-memory client side caching. Default: True
How long we should wait for a connection slot before erroring out. Integer, seconds. Default: 5 (seconds)
How long a TCP handshake with the redis server should take. Integer, seconds. Default: 5 (seconds)
Maximum number of simultaneous connections per worker process to the redis server. Default: 100.
Whether to retry once on connection failures. Default: True
True: Supress connection error tracebacks from python, False: Do not suppress connection error tracebacks.
Whether to use TCP Keep-Alives to ensure redis connections are not interrupted by intermediate stateful network devices when idle. Default: True
How long to keep a discovery response cached for. Integer, seconds. Default: 60 (seconds)
Logging configuration
Settings specifically for application logs, which are emitted when particular application events occur, which may not be related to any discovery or other access.
Whether or not to emit application logs.
Logs are JSON formatted.
Default is False.
Settings specifically for access logs, which are emitted when any endpoint of sovereign is accessed.
Whether or not to emit HTTP request logs for discovery requests and other endpoints.
Logs are JSON formatted.
Default is True.
If a log field is empty/blank, it will be omitted from the logs.
Default is True.
The log format to use for HTTP request logs. This format should be a JSON encoded string.
The format supports the following keywords:
ENVIRONMENT The environment set in configuration
HOST The Host header provided by the HTTP client
METHOD The method used by the HTTP client
PATH The path portion of the URL provided by the HTTP client
QUERY The query string provided by the HTTP client
SOURCE_IP The source ip of the HTTP client
SOURCE_PORT The source port of the HTTP client
PID The process ID of the worker that processed the request
USER_AGENT The user agent supplied by the HTTP client
BYTES_RX Content size of the request
BYTES_TX Content size of the response
STATUS_CODE HTTP status code
DURATION Time taken between receiving the request, and writing out the response
REQUEST_ID A UUID to represent the request
XDS_CLIENT_VERSION The version_info of the resource on the client-side
XDS_SERVER_VERSION The version_info of the resource that sovereign responded with
XDS_RESOURCES Which resources, by name, were requested
XDS_ENVOY_VERSION The Envoy proxy version of the client
TRACEBACK A Python traceback message, when a traceback occurs
ERROR The name of the class of error, when an error occurs
ERROR_DETAIL Further details about the error, if a description is available
When troubleshooting a YAML issue, it may be useful to include all of the following:
1 2{ "env": "{ENVIRONMENT}", "site": "{HOST}", "method": "{METHOD}", "uri_path": "{PATH}", "uri_query": "{QUERY}", "src_ip": "{SOURCE_IP}", "src_port": "{SOURCE_PORT}", "pid": "{PID}", "user_agent": "{USER_AGENT}", "bytes_in": "{BYTES_RX}", "bytes_out": "{BYTES_TX}", "status": "{STATUS_CODE}", "duration": "{DURATION}", "request_id": "{REQUEST_ID}", "resource_version": "{XDS_CLIENT_VERSION} -> {XDS_SERVER_VERSION}", "resource_names": "{XDS_RESOURCES}", "envoy_ver": "{XDS_ENVOY_VERSION}", "traceback": "{TRACEBACK}", "error": "{ERROR}", "detail": "{ERROR_DETAIL}", }
1 2sources: - type: <type> scope: 'default' config: {} source_config: refresh_rate: 30 source_key: service_clusters node_key: cluster templates: default: type: clusters spec: protocol: file serialization: jinja2 path: templates/default/clusters.yaml type: routes spec: protocol: file serialization: jinja2 path: templates/default/routes.yaml 1.12.0: type: clusters spec: protocol: file serialization: jinja2 path: templates/1.12.x/clusters.yaml type: routes spec: protocol: file serialization: jinja2 path: templates/1.12.x/routes.yaml 1.13.0: type: clusters spec: protocol: file serialization: jinja2 path: templates/1.13.x/clusters.yaml type: routes spec: protocol: file serialization: jinja2 path: templates/1.13.x/routes.yaml template_context: context: region: protocol: env path: DEPLOY_REGION environment: protocol: env path: DEPLOY_ENV ip_acls: protocol: s3 path: bucket-name:ips.json refresh: no refresh_rate: 3600 debug: no sentry_dsn: sentry://blahfoobar authentication: enabled: yes encryption_key: you_should_use_environment_variables_for_this! auth_passwords: - VerySecretPassword1! - you_should_use_environment_variables_for_this! statsd: enabled: yes namespace: sovereign host: statsd-sink.internal port: 8125 tags: region: protocol: env path: DEPLOY_REGION environment: protocol: env path: DEPLOY_ENV hostname: protocol: env path: HOST logging: application_logs: enabled: no access_logs: enabled: yes ignore_empty_fields: yes log_fmt: | { "env": "{ENVIRONMENT}", "site": "{HOST}", "method": "{METHOD}", "uri_path": "{PATH}", "uri_query": "{QUERY}", "src_ip": "{SOURCE_IP}", "src_port": "{SOURCE_PORT}", "pid": "{PID}", "user_agent": "{USER_AGENT}", "bytes_in": "{BYTES_RX}", "bytes_out": "{BYTES_TX}", "status": "{STATUS_CODE}", "duration": "{DURATION}", "request_id": "{REQUEST_ID}", "resource_version": "{XDS_CLIENT_VERSION} -> {XDS_SERVER_VERSION}", "resource_names": "{XDS_RESOURCES}", "envoy_ver": "{XDS_ENVOY_VERSION}", "traceback": "{TRACEBACK}", "error": "{ERROR}", "detail": "{ERROR_DETAIL}", }
1 2<div class="sc-gLdKKF bwagGt"><section class="sc-SFOxd gpanBo"><div class="sc-hkaZBZ gWhWHQ"><style data-emotion="css snhnyn">.css-snhnyn{display:inline-block;-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;line-height:1;}.css-snhnyn >svg{overflow:hidden;pointer-events:none;max-width:100%;max-height:100%;color:var(--icon-primary-color);fill:var(--icon-secondary-color);vertical-align:bottom;}.css-snhnyn >svg stop{stop-color:currentColor;}@media screen and (forced-colors: active){.css-snhnyn >svg{-webkit-filter:grayscale(1);filter:grayscale(1);--icon-primary-color:CanvasText;--icon-secondary-color:Canvas;}}</style><span aria-hidden="true" style="--icon-primary-color:#0747A6;--icon-secondary-color:#DEEBFF" class="css-snhnyn"><svg width="24" height="24" viewBox="0 0 24 24" role="presentation"><g fill-rule="evenodd"><path d="M2 12c0 5.523 4.477 10 10 10s10-4.477 10-10S17.523 2 12 2 2 6.477 2 12z" fill="currentColor"/><rect fill="inherit" x="11" y="10" width="2" height="7" rx="1"/><circle fill="inherit" cx="12" cy="8" r="1"/></g></svg></span></div><div class="sc-jOBXIr jErMvQ"><div class="sc-kIWQTW nnCfa"> All of the following variables should be prefixed with `SOVEREIGN_`. For example, `HOST` is `SOVEREIGN_HOST` </div></div></section></div>
Most if not all of the following settings should have an equivalent in the above configuration settings.
If an environment variable is set, but a different value is set in a configuration file, the value supplied by the configuration file will take precedence.
Environment Variable | Default | Description |
---|---|---|
CONFIG | None | Where sovereign should look for it's configuration |
AUTH_ENABLED | False | Controls whether Sovereign will check node metadata for an encrypted authentication string |
AUTH_PASSWORDS | None | A list of passwords that Sovereign will consider valid for decrypted authentication strings |
ENCRYPTION_KEY | None | A Fernet key for asymmetric encryption/decryption |
NODE_MATCHING_ENABLED | True | Whether Sovereign should compare the configured node & source keys |
SOURCE_MATCH_KEY | service_clusters | What value in Source data should sovereign look for when matching nodes |
NODE_MATCH_KEY | cluster | What value in the Node Discovery Request should sovereign look for when matching nodes |
REFRESH_CONTEXT | False | Whether or not to continually reload template context |
CONTEXT_REFRESH_RATE | 3600 | How often (in seconds) Sovereign should reload template context |
CONTEXT_REFRESH_CRON | None | Cron expression for when Sovereign should reload template context |
CONTEXT_REFRESH_NUM_RETRIES | 3 | Number of times to retry context refresh before emitting an error metric |
CONTEXT_REFRESH_RETRY_INTERVAL_SECS | 10 | Time in seconds to wait before trying a context refresh again |
CONTEXT_CACHE_SIZE | 1000 | How many copies of cached context that Sovereign should keep |
SOURCES_REFRESH_RATE | 30 | How often (in seconds) Sovereign should reload sources (Cannot be disabled) |
CACHE_STRATEGY | context | What strategy Sovereign should use to determine if Envoy config is up to date |
ENABLE_APPLICATION_LOGS | False | Whether or not to emit application logs |
ENABLE_ACCESS_LOGS | True | Whether or not to emit HTTP request logs for discovery requests |
LOG_FORMAT | Default log format | What fields to include in HTTP request logs |
LOG_IGNORE_EMPTY | True | Omit empty fields from logs |
SENTRY_DSN | None | An optional Sentry DSN to send exceptions to |
DEBUG | False | Controls whether the server will log debug messages and tracebacks |
HOST | 0.0.0.0 | What address the server will listen on |
PORT | 8080 | What port the server will listen on |
KEEPALIVE | 5 | How long the server should hold connections open for clients before closing |
WORKERS | (cores * 2) + 1 | How many sovereign worker processes should be spawned |
WORKER_TIMEOUT | 30 | How long a worker can be idle before it will be restarted |
THREADS | 1 | How many threads each worker should use for handling requests |
PRELOAD | False | Whether the app should be preloaded before forking into worker processes |
DISCOVERY_CACHE_REDIS_HOST | localhost | The IP address or hostname of the redis server. |
DISCOVERY_CACHE_REDIS_PORT | 6379 | The port of the redis server. |
DISCOVERY_CACHE_REDIS_PASSWORD | None | Optional password to use when communicating with the redis server. (requires TLS) |
Rate this page: