File Configuration
The following is the schema and reference for a Quilkin configuration file. See the examples folder for example configuration files.
By default Quilkin will look for a configuration file named quilkin.yaml
in
its current running directory first, then if not present, in
/etc/quilkin/quilkin.yaml
on UNIX systems. This can be overridden with the
-c/--config
command-line argument, or the QUILKIN_FILENAME
environment variable.
Static Configuration
Example of a full configuration for quilkin proxy
that utlisies a static Endpoint configuration:
#
# Example configuration for a Quilkin Proxy with static Endpoints
#
version: v1alpha1
admin: # configuration options for administration
address: "[::]:9091" # the address and port to bind the admin API to.
maxmind_db: null # Remote URL or local file path to retrieve a Maxmind database (requires licence).
id: my-proxy # An identifier for the proxy instance.
port: 7001 # the port to receive traffic to locally
clusters: # grouping of clusters
default:
localities: # grouping of endpoints within a cluster
- endpoints: # array of potential endpoints to send on traffic to
- address: 127.0.0.1:26000
metadata: # Metadata associated with the endpoint
quilkin.dev:
tokens:
- MXg3aWp5Ng== # the connection byte array to route to, encoded as base64 (string value: 1x7ijy6)
- OGdqM3YyaQ== # (string value: 8gj3v2i)
- address: 127.0.0.1:26001
metadata: # Metadata associated with the endpoint
quilkin.dev:
tokens:
- bmt1eTcweA== # (string value: nkuy70x)
Dynamic Configuration
Example of a full configuration for quilkin proxy
that utlisies a dynamic Endpoint configuration through an
xDS management endpoint:
#
# Example configuration for a Quilkin Proxy that is configured via an xDS control plane.
#
version: v1alpha1
admin: # configuration options for administration
address: "[::]:9091" # the address and port to bind the admin API to.
maxmind_db: null # Remote URL or local file path to retrieve a Maxmind database (requires licence).
id: my-proxy # An identifier for the proxy instance.
port: 7001 # the port to receive traffic to locally
management_servers: # array of management servers to configure the proxy with.
# Multiple servers can be provided for redundancy.
- address: http://127.0.0.1:26000
Json Schema
The full JSON Schema for the YAML configuration file.
type: object
properties:
version:
type: string
description: |
The configuration file version to use.
enum:
- v1alpha1
id:
type: string
description: |
An identifier for the proxy instance.
default: On linux, the machine hostname is used as default. On all other platforms a UUID is generated for the proxy.
port:
type: integer
description: |
The listening port. In "proxy" mode, the port for traffic to be sent to. In "manage" mode, the port to connect to the xDS API.
default: 7000
maxmind_db:
type: string
description: |
The remote URL or local file path to retrieve the Maxmind database (requires licence).
admin:
type: object
description: |
Configuration of proxy admin HTTP interface.
properties:
address:
type: string
description: |
Socket Address and port to bind the administration interface to.
default: "[::]:9091"
filters:
type: array
description: |
A filter chain.
items:
'$ref': {} # Refer to the Filter documentation for a filter configuration schema.
clusters:
type: object
description: |
grouping of clusters, each with a key for a name
additionalProperties:
type: object
description: |
An individual cluster
properties:
localities:
type: array
description: |
grouping of endpoints, per cluster.
items:
type: object
properties:
endpoints:
type: array
description: |
A list of upstream endpoints to forward packets to.
items:
type: object
description: |
An upstream endpoint
properties:
address:
type: string
description: |
Socket address of the endpoint. This must be of the ´IP:Port` form e.g `192.168.1.1:7001`
metadata:
type: object
description: |
Arbitrary key value pairs that is associated with the endpoint.
These are visible to Filters when processing packets and can be used to provide more context about endpoints (e.g whether or not to route a packet to an endpoint).
Keys must be of type string otherwise the configuration is rejected.
required:
- address
management_servers:
type: array
description: |
A list of XDS management servers to fetch configuration from.
Multiple servers can be provided for redundancy for the proxy to
fall back to upon error.
items:
type: object
description: |
Configuration for a management server.
properties:
address:
type: string
description: |
Address of the management server. This must have the `http(s)` scheme prefix.
Example: `http://example.com`