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
Runs Quilkin as a relay service that runs a Manager Discovery Service (mDS) for accepting cluster and configuration information from xDS management services, and exposing it as a single merged xDS service for proxy services

Usage: quilkin relay [OPTIONS] [COMMAND]

Commands:
  agones  Watches Agones' game server CRDs for `Allocated` game server endpoints, and for a `ConfigMap` that specifies the filter configuration
  file    Watches for changes to the file located at `path`
  help    Print this message or the help of the given subcommand(s)

Options:
  -m, --mds-port <MDS_PORT>
          Port for mDS service [env: QUILKIN_MDS_PORT=] [default: 7900]
  -x, --xds-port <XDS_PORT>
          Port for xDS management_server service [env: QUILKIN_PORT=] [default: 7800]
      --idle-request-interval-secs <IDLE_REQUEST_INTERVAL_SECS>
          The interval in seconds at which the relay will send a discovery request to an management server after receiving no updates [env: QUILKIN_IDLE_REQUEST_INTERVAL_SECS=]
  -h, --help
          Print help

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 relay 

To spawn the control plane and have the control plane send its configuration, we need to run the manage command with the --relay 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 and --port flags to avoid port collision with the relay's admin and xds endpoints.

quilkin --admin-address http://localhost:8001 \
    manage \
    --port 7801 \
    --relay http://localhost:7900 \
    file quilkin.yaml

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 the same --management-server flag that we use to specify the location of control planes, then the proxies will be able to pull configuration from the relay.

quilkin --admin-address http://localhost:8002 proxy --management-server 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 \
    manage \
    --port 7802 \
    --relay http://localhost:7900 \
    file quilkin.yaml

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.