Light Dark Auto

Greymatter Control Plane

Configure the control plane

The greymatter.io control plane consists of two daemons, gm-control and gm-control-api.

gm-control-api provides a REST that lets remote clients configure a service mesh. The greymatter CLI is the only official client. gm-control-api also persists mesh configurations as a single JSON object in Redis, or a local flat file. Redis is recommended for production deployments.

gm-control is the component that distributes configuration to proxies. Proxies connect to gm-control via gRPC, and accept configuration via the xDS protocol. gm-control polls gm-control-api for configuration changes. When a change to mesh configuration is detected, it’s pushed out to the appropriate proxies.

Configure gm-control

The gm-control service is configured with env vars exclusively.

  • GM_CONTROL_CONSOLE_LEVEL(String, default: "debug") - Log level for gm-control.
  • GM_CONTROL_API_KEY(String) - Deprecated. API key for connecting to gm-control-api.
  • GM_CONTROL_API_ZONE_NAME(String, default: "default-zone")
  • GM_CONTROL_API_SSL - false
  • GM_CONTROL_API_HOST - gm-control-api:5555
  • GM_CONTROL_CMD - file
  • GM_CONTROL_FILE_FORMAT - yaml
  • GM_CONTROL_FILE_FILENAME - /app/routes.yaml
  • GM_CONTROL_XDS_RESOLVE_DNS - true
  • GM_CONTROL_XDS_ADS_ENABLED - true

Configure gm-control-api

  • GM_CONTROL_API_LOG_LEVEL - One of debug, info, error, warn.
  • GM_CONTROL_API_ADDRESS - The host:port combination to listen on for API clients.
  • GM_CONTROL_API_ORG_KEY - Organization metadata for the service mesh.
  • GM_CONTROL_API_PERSISTER_TYPE - One of: file, redis.
  • GM_CONTROL_API_PERSISTER_PATH - A fully-qualified filepath for the file persister’s state. A json file will be written to this path. Note valid for any other persister type.

Command line Flags

gm-control also accepts command line flags.

Global OptionsDescription
--api.header=header

Specifies a custom header to send with every gm-control request. Headers are given as name:value pairs. Leading and trailing whitespace will be stripped from the name and value. For multiple headers, this flag may be repeated or multiple headers can be delimited with commas.

--api.host=host:port

(default: localhost:80) The address (host:port) for gm-control requests. If no port is given, it defaults to port 443 if –api.ssl is true and port 80 otherwise.

--api.insecure

(default: false) If true, don’t validate server cert when using SSL for gm-control requests.

--api.key=string

(default: “none”) [SENSITIVE] The auth key for gm-control requests.

--api.prefix=value

The url prefix for gm-control requests. Forms the path part of :.

--api.ssl

(default: true) If true, use SSL for gm-control requests.

--api.sslCert=value

Specifies the SSL cert to use for every gm-control request.

--api.sslKey=value

Specifies the SSL key to use for every gm-control request.

--api.zone-name=string

The name of the API Zone for gm-control requests.

--console.level=level

(default: “info”) (valid values: “debug”, “info”, “error”, or “none”) Selects the log level for console logs messages.

--delay=duration

(default: 30s) Sets the minimum time between API updates. If the discovery data changes more frequently than this duration, updates are delayed to maintain the minimum time.

--diff.dry-run

(default: false) Log changes at the info level rather than submitting them to the API.

--diff.ignore-create

(default: false) If true, do not create new Clusters in the API.

--diff.include-delete

(default: false) If true, delete missing Clusters from the API.

--help (default: false)

Show a list of commands or help for one command.

--stats.api.header=header

Specifies a custom header to send with every stats API request. Headers are given as name:value pairs. Leading and trailing whitespace will be stripped from the name and value. For multiple headers, this flag may be repeated or multiple headers can be delimited with commas.

--stats.api.host=host:port

(default: localhost:80) The address (host:port) for stats API requests. If no port is given, it defaults to port 443 if –stats.api.ssl is true and port 80 otherwise.

--stats.api.insecure

(default: false) If true, don’t validate server cert when using SSL for stats API requests.

--stats.api.prefix=value

The url prefix for stats API requests. Forms the path part of :.

--stats.api.ssl

(default: true) If true, use SSL for stats API requests.

--stats.api.sslCert=value

Specifies the SSL cert to use for every stats API request.

--stats.api.sslKey=value

Specifies the SSL key to use for every stats API request.

--stats.backends=value

(valid values: “dogstatsd”, “prometheus”, “statsd”, or “wavefront”) Selects which stats backend(s) to use.

--stats.batch

(default: true) If true, stats requests are batched together for performance.

--stats.dogstatsd.debug

(default: false) If enabled, logs the stats data on stdout.

--stats.dogstatsd.flush-interval=duration

(default: 5s) Specifies the duration between stats flushes.

--stats.dogstatsd.host=string

(default: “127.0.0.1”) Specifies the destination host for stats.

--stats.dogstatsd.latch

(default: false) Specifies whether stats are accumulated over a window before being sent to the backend.

--stats.dogstatsd.latch.base-value=float

(default: 0.001) Specifies the upper bound of the first bucket used for accumulating histograms. Each subsequent bucket’s upper bound is double the previous bucket’s. For timings this value is taken to be in units of seconds. Must be greater than 0.

--stats.dogstatsd.latch.buckets=int

(default: 20) Specifies the number of buckets used for accumulating histograms. Must be greater than 1.

--stats.dogstatsd.latch.window=duration

(default: 1m0s) Specifies the period of time over which stats are latched. Must be greater than 0.

--stats.dogstatsd.max-packet-len=bytes

(default: 8192) Specifies the maximum number of payload bytes sent per flush. If necessary, flushes will occur before the flush interval to prevent payloads from exceeding this size. The size does not include IP and UDP header bytes. Stats may not be delivered if the total size of the headers and payload exceeds the network’s MTU.

--stats.dogstatsd.port=int

(default: 8125) Specifies the destination port for stats.

--stats.dogstatsd.scope=string

If specified, prepends the given scope to metric names.

--stats.dogstatsd.transform-tags=string

Defines one or more transformations for tags. A tag with a specific name whose value matches a regular expression can be transformed into one or more tags with values extracted from subexpressions of the regular expression (See hint below).

--stats.event-backends=value

(valid values: “console” or “honeycomb”) Selects which stats backend(s) to use for structured events.

--stats.exec.attempt-timeout=duration

(default: 1s) Specifies the default timeout for individual action attempts. A timeout of 0 means no timeout.

--stats.exec.delay=duration

(default: 100ms) Specifies the initial delay for the exponential delay type. Specifies the delay for constant delay type..

--stats.exec.delay-type=value

(default: “exponential”) (valid values: “constant” or “exponential”) Specifies the retry delay type.

--stats.exec.max-attempts=int

(default: 8) Specifies the maximum number of attempts made, inclusive of the original attempt.

--stats.exec.max-delay=duration

(default: 30s) Specifies the maximum delay for the exponential delay type. Ignored for the constant delay type.

--stats.exec.parallelism=int

(default: 8) Specifies the maximum number of concurrent attempts running.

--stats.exec.timeout=duration

(default: 10s) Specifies the default timeout for actions. A timeout of 0 means no timeout.

--stats.honeycomb.api-host=string

(default: “https://api.honeycomb.io”) The Honeycomb API host to send messages to .

--stats.honeycomb.batchSize=uint

(default: 50) The Honeycomb batch size to use.

--stats.honeycomb.dataset=string

They Honeycomb dataset to send messages to.

--stats.honeycomb.sample-rate=uint

(default: 1) The Honeycomb sample rate to use. Specified as 1 event sent per Sample Rate.

--stats.honeycomb.write-key=string

They Honeycomb write key used to send messages.

--stats.max-batch-delay=duration

(default: 1s) If batching is enabled, the maximum amount of time requests are held before transmission.

--stats.max-batch-size=int

(default: 100) If batching is enabled, the maximum number of requests that will be combined.

--stats.node=string

If set, specifies the node to use when submitting stats to backends. Equivalent to adding “–stats.tags=node=value” to the command line.

--stats.prometheus.addr=value

(default: 0.0.0.0:9102) Specifies the listener address for Prometheus scraping.

--stats.prometheus.scope=string

If specified, prepends the given scope to metric names.

--stats.source=string

If set, specifies the source to use when submitting stats to backends. Equivalent to adding “–stats.tags=source=value” to the command line. In either case, a UUID is appended to the value to insure that it is unique across proxies. Cannot be combined with –stats.unique-source.

--stats.statsd.debug

(default: false) If enabled, logs the stats data on stdout.

--stats.statsd.flush-interval=duration

(default: 5s) Specifies the duration between stats flushes.

--stats.statsd.host=string

(default: “127.0.0.1”) Specifies the destination host for stats.

--stats.statsd.latch

(default: false) Specifies whether stats are accumulated over a window before being sent to the backend.

--stats.statsd.latch.base-value=float

(default: 0.001) Specifies the upper bound of the first bucket used for accumulating histograms. Each subsequent bucket’s upper bound is double the previous bucket’s. For timings this value is taken to be in units of seconds. Must be greater than 0.

--stats.statsd.latch.buckets=int

(default: 20) Specifies the number of buckets used for accumulating histograms. Must be greater than 1.

--stats.statsd.latch.window=duration

(default: 1m0s) Specifies the period of time over which stats are latched. Must be greater than 0.

--stats.statsd.max-packet-len=bytes

(default: 8192) Specifies the maximum number of payload bytes sent per flush. If necessary, flushes will occur before the flush interval to prevent payloads from exceeding this size. The size does not include IP and UDP header bytes. Stats may not be delivered if the total size of the headers and payload exceeds the network’s MTU.

--stats.statsd.port=int

(default: 8125) Specifies the destination port for stats.

--stats.statsd.scope=string

If specified, prepends the given scope to metric names.

--stats.statsd.transform-tags=string

Defines one or more transformations for tags. A tag with a specific name whose value matches a regular expression can be transformed into one or more tags with values extracted from subexpressions of the regular expression. (See hint below).

--stats.tags=value

Tags to be included with every stat. May be comma-delimited or specified more than once. Should be of the form “=” or “tag”.

--stats.unique-source=string

If set, specifies the source to use when submitting stats to backends. Equivalent to adding “–stats.tags=source=value” to the command line. Unlike –stats.source, failing to specify a unique value may prevent stats from being recorded correctly. Cannot be combined with –stats.source.

--stats.wavefront.debug

(default: false) If enabled, logs the stats data on stdout.

--stats.wavefront.flush-interval=duration

(default: 5s) Specifies the duration between stats flushes.

--stats.wavefront.host=string

(default: “127.0.0.1”) Specifies the destination host for stats.

--stats.wavefront.latch.base-value=float

(default: 0.001) Specifies the upper bound of the first bucket used for accumulating histograms. Each subsequent bucket’s upper bound is double the previous bucket’s. For timings this value is taken to be in units of seconds. Must be greater than 0.

--stats.wavefront.latch.buckets=int

(default: 20) Specifies the number of buckets used for accumulating histograms. Must be greater than 1.

--stats.wavefront.latch.window=duration

(default: 1m0s) Specifies the period of time over which stats are latched. Must be greater than 0.

--stats.wavefront.max-packet-len=bytes

(default: 8192) Specifies the maximum number of payload bytes sent per flush. If necessary, flushes will occur before the flush interval to prevent payloads from exceeding this size. The size does not include IP and UDP header bytes. Stats may not be delivered if the total size of the headers and payload exceeds the network’s MTU.

--stats.wavefront.port=int

(default: 8125) Specifies the destination port for stats.

--stats.wavefront.scope=string

If specified, prepends the given scope to metric names.

--stats.wavefront.transform-tags=string

Defines one or more transformations for tags. A tag with a specific name whose value matches a regular expression can be transformed into one or more tags with values extracted from subexpressions of the regular expression (See hint below).

--version

(default: false) Print the version and exit.

--xds.addr=value

(default: :50000) The address on which to serve the envoy API server.

--xds.ads-enabled

(default: true) If false, turn off ads discovery mode.

--xds.ca-file=string

Path to a file (on the Envoy host’s file system) containing CA certificates for TLS.

--xds.default-timeout=duration

(default: 1m0s) The default request timeout, if none is specified in the RetryPolicy for a Route.

--xds.disabled

(default: false) Disables the xDS listener.

--xds.enable-tls

(default: false) Enable grpc xDS TLS.

--xds.grpc-log-top=int

(default: 0) When gRPC logging is enabled and this value is greater than 1, logs of non-success Envoy responses are tracked and periodically reported. This flag controls how many unique response code & request path combinations are tracked. When the number of tracked combinations in the reporting period is exceeded, uncommon paths are evicted.

--xds.grpc-log-top-interval=duration

(default: 5m0s) See the grpc-log-top flag. Controls the interval at which top logs are generated.

--xds.interval=duration

(default: 1s) The interval for polling the Greymatter API. Minimium value is 500ms.

--xds.resolve-dns

(default: true) If true, resolve EDS hostnames to IP addresses.

--xds.server-auth-type=string

TLS client authentication type.

--xds.server-cert=string

URL containing the server certificate for the grpc ADS server.

--xds.server-key=string

URL containing the server certificate key for the grpc ADS server.

--xds.server-trusts=string

Comma-delimited URLs containing truststores for the grpc ADS server.

--xds.standalone-cluster=string

(default: “default-cluster”) The name of the cluster for the Envoys consuming the standalone xDS server. Should match the –service-cluster flag for the envoy binary, or the ENVOY_NODE_CLUSTER value for the envoy-simple Docker image.

--xds.standalone-port=int

(default: 80) The port on which Envoys consuming the standalone xDS server should listen. Ignored if –api.key is specified.

--xds.standalone-zone=string

(default: “default-zone”) The name of the zone for the Envoys consuming the standalone xDS server. Should match the –service-zone flag for the envoy binary, or the ENVOY_NODE_ZONE value for the envoy-simple Docker image.

--xds.static-resources.conflict-behavior=value

(default: “merge”) (valid values: “overwrite” or “merge”) How to handle conflicts between configuration types. If “overwrite” configuration types overwrite defaults.

--xds.static-resources.filename=string

Path to a file containing static resources. The contents of the file should be either a JSON or YAML fragment.

--xds.static-resources.format=value

(default: “yaml”) (valid values: “json” or “yaml”) The format of the static resources file.

Transform Commands

Transformations (e.g.for statsd) are specified as follows:

tag=/regex/,n1,n2...

where:

  • tag is the name of the tag to be transformed
  • regex is a regular expression with 1 or more subexpressions
  • n1, n2… is a sequence of names for the tags formed from the regular expression’s subexpressions (matching groups).

Transformation Requirements

Transformations must meet the following requirements:

  • Any character may be used in place of the slashes (/) to delimit the regular expression
  • There must be at least one subexpression in the regular expression.
  • There must be exactly as many names as subexpressions.
  • If one of the names is the original tag name, the original tag is replaced with the transformed value. Otherwise, the original tag is passed through unchanged.
  • Multiple transformations may be separated by semicolons (;).
  • Any character may be escaped with a backslash ().

Examples

You can also configure global options via upper-case, underscore-delimited environment variables prefixed with GMCONTROL.

foo=/^(.+):.x=([0-9]+)/,foo,bar

foo=@.y=([A-Za-z_]+)@,yval