Control Plane Relay

Note: This service is currently in active experimentation and development so there may be bugs which cause it to be unusable for production, as always all bug reports are welcome and appreciated.

For multi-cluster integration, Quilkin provides a relay service, that can be used with a multiple control plane services in different clusters to provide a unified "Aggregated Discovery Service" endpoint for proxy services.

To connect to a control plane to a relay, add the --relay flag to your control plane with the address of the relay. Then to connect a proxy service to the relay's ADS endpoint, you use the same --management-server argument for connecting to control planes.

To view all options for the relay subcommand, run:

$ quilkin relay --help
{{#include ../../../target/quilkin.relay.commands}}

Each sub-control planes (file, agones, etc) matches the quilkin manage providers capabilities. Have a look at each of the Control Plane > Providers documentation for integration details.

Quickstart

To get started with the relay service we need to start the relay service, and then setup our configuration source. For this we're going to the built-in relay client in the control plane service to forward information to the relay. For this demo we'll use the file provider for the control plane, but this example works with any configuration provider.

# quilkin.yaml
version: v1alpha1
clusters:
  - endpoints:
    - address: 127.0.0.1:8888

To start the relay, run the relay command:

quilkin --service.mds

To spawn the control plane and have the control plane send its configuration, we need to run quilkin with the provider.mds.endpoints flag with the address of the relay of the relay server we just spawned which is at port 7900 by default. We're also going to set admin.address to a different port to not conflict.

quilkin \
    --admin.address http://localhost:8001 \
    --provider.fs.path quilkin.yaml \
    --provider.mds.endpoints http://localhost:7900 \

Now if we run cURL on both the relay and the control plane we should see that they both contain the same set of endpoints.

# Check Control Plane
curl localhost:8001/config
# Check Relay
curl localhost:8000/config

Since the relay service also exposes a aDS control plane endpoint, that represents the merged set of all sources, to connect this to the proxy all we have to do is use provider.xds.endpoints to specify the location of control planes, then the proxies will be able to pull configuration from the relay.

quilkin --service.udp --admin.address http://localhost:8002 --provider.xds.endpoints http://127.0.0.1:7800

We can also additionally add a second control plane source to the relay, which will be merged with our control plane's configuration to create a singular set of data that the proxies can query using xDS discovery requests.

# quilkin2.yaml
version: v1alpha1
clusters:
  - endpoints:
    - address: 127.0.0.1:9999

quilkin \
    --admin.address http://localhost:8003 \
    --provider.fs.path quilkin2.yaml \
    --provider.mds.endpoints http://localhost:7900 \

And that's it! We've just setup control planes to look for configuration changes in our system, a relay to merge any changes into a unified dataset, and set up proxies that make use of that data to decide where and how to send packets.