Plugin

The plugin configuration defines how a plugin should behave at runtime.

Plugin configuration is defined in a YAML file. Most configuration options have sane default values. For simple plugins, these default values may suffice and no additional plugin configuration may be required.

Config Location

The plugin configuration YAML must be named config.{yml|yaml}. By default, the plugin will look for that file in the following directories (in the order in which they are specified):

  • $PWD/ (./)
  • ./config/
  • /etc/synse/plugin/config/

Once a matching YAML file is found, it will attempt to load it as a plugin configuration and will not continue searching in any remaining paths.

As plugins are intended to be run in a container, a custom configuration would need to be mounted in to one of the locations above, e.g.

docker run \
  -v $PWD/custom-cfg.yaml:/etc/synse/plugin/config/config.yaml \
  ...

Overriding Config Location

The plugin configuration may be specified off of the default search paths. In this case, the plugin will need to be told where the config file is. This can be done with the PLUGIN_CONFIG environment variable. For example, if the configuration file were in /tmp/cfg:

docker run \
  -v $PWD/custom-cfg.yaml:/tmp/cfg/config.yaml \
  -e PLUGIN_CONFIG=/tmp/cfg/config.yaml \
  ...

The PLUGIN_CONFIG environment variable can be used to specify either the full path to the file (e.g. /tmp/cfg/config.yaml), or the path to the directory containing the config file, with the assumption that the file is named config.y{a}ml (e.g. /tmp/cfg).

This may also be done in a compose file:

version: '3'
services:
  plugin:
    image: plugin-image
    volumes:
    - ./custom-cfg.yaml:/tmp/cfg/config.yaml
    environment:
      PLUGIN_CONFIG: /tmp/cfg/config.yml

Config Policies

A plugin may use a configuration policy in order to change the expected behavior for how it loads configuration data. There are currently two policy types which may be set:

Policy Description
Optional The plugin configuration is optional. If no plugin configuration is found, either on the search path or via env override, the plugin will just use configuration defaults.
Required The plugin configuration is required. If no plugin configuration is found, either on the search path or via env override, the plugin will terminate with an error. This should be used in the cases where the default values would not be enough to fully configure the plugin.

The default config policy for plugin configuration is Optional.

Configuration policies may be set as a PluginOption in the plugin constructor, e.g.

import (
  "github.com/vapor-ware/synse-sdk/sdk"
)

func main() {
  plugin, err := sdk.NewPlugin(
    sdk.PluginConfigRequired(),
  )
}

Configuration Options

This section describes the supported configuration options for a plugin, including any restrictions on the values and any defaults.


Version

description The major version of the plugin configuration. For all plugins using the SDK for Synse v3, this should be 3.
type int
key version
version: 3

Debug

description Run the plugin with debug logging. If false, the plugin will run with normal (info) logging.
type bool
key debug
default false
supported true, false
debug: true

ID

Settings for generating the plugin ID namespace.

Group key: id

Use Machine ID

description Use the machine ID as part of the input for plugin namespace generation. This is disabled by default, as it does not work well in containers, the primary run environment for plugins.
type bool
key useMachineID
default false
supported true, false
id:
  useMachineID: true

Use Plugin Tag

description Use the plugin tag (string comprised of maintainer and plugin name) as part of the input for plugin namespace generation.
type bool
key usePluginTag
default true
supported true, false
id:
  usePluginTag: true

Use Env

description Use the values from the specified environment variables as part of the input for plugin namespace generation.
type list[string]
key useEnv
default []
id:
  useEnv:
  - ENV_1
  - ENV_2

Use Custom

description Use custom string identifiers as part of the input for plugin namespace generation.
type list[string]
key useCustom
default []
id:
  useCustom:
  - foo
  - bar

Metrics

Settings for exposing application metrics.

Group key: metrics

Enabled

description Enable application metrics export via Prometheus.
type bool
key enabled
default false
supported true, false
metrics:
  enabled: true

Settings

The settings for the runtime behavior of the plugin.

Group key: settings

Mode

description The run mode of the plugin scheduler. This can either be "serial" or "parallel".
type string
key mode
default parallel
supported serial, parallel
settings:
  mode: parallel

Listen

The settings for how listener-type handlers should behave.

Group key: listen

Disable

description Globally disable listening for the plugin.
type bool
key disable
default false
supported true, false
settings:
  listen:
    disable: false

Read

The settings for how read-type handlers should behave.

Group key: read

Disable

description Globally disable reading for the plugin.
type bool
key disable
default false
supported true, false
settings:
  read:
    disable: false

Interval

description The duration that the read loop should wait between iterations. An interval may be useful for tuning the performance of a plugin, particularly for serial protocols. It is not recommended to set the interval to 0 as the loop would be unbounded and would consume excessive CPU resources.
type duration
key interval
default 1s
supported duration strings
settings:
  read:
    interval: 1s

Delay

description A plugin-global delay between successive reads within a single loop iteration. A delay may be useful for tuning the performance of a plugin, particularly for serial protocols.
type duration
key delay
default 0s
supported duration strings
settings:
  read:
    delay: 1s

QueueSize

description The size of the read queue. This is the size of the channel that passes along readings as they are collected. This can be set to tune performance for read-intensive plugins.
type int
key queueSize
default 128
settings:
  read:
    queueSize: 128

Write

The settings for how write-type handlers should behave.

Group key: write

Disable

description Globally disable writing for the plugin.
type bool
key disable
default false
supported true, false
settings:
  write:
    disable: false

Interval

description The duration that the write loop should wait between iterations. An interval may be useful for tuning the performance of a plugin, particularly for serial protocols. It is not recommended to set the interval to 0 as the loop would be unbounded and would consume excessive CPU resources.
type duration
key interval
default 1s
supported duration strings
settings:
  write:
    interval: 1s

Delay

description A plugin-global delay between successive writes within a single loop iteration. A delay may be useful for tuning the performance of a plugin, particularly for serial protocols.
type duration
key delay
default 0s
supported duration strings
settings:
  write:
    delay: 1s

QueueSize

description The size of the write queue. This is the size of the channel that passes along write requests as they are collected. This can be set to tune performance for write-intensive plugins.
type int
key queueSize
default 128
settings:
  write:
    queueSize: 128

BatchSize

description The maximum number of writes to process in a single loop iteration. This can be set to tune performance for plugins with slow-writing devices.
type int
key batchSize
default 128
settings:
  write:
    batchSize: 128

Transaction

The settings relating to write transactions.

Group key: transaction

TTL

description The time-to-live for the transaction in the transaction cache.
type duration
key ttl
default 5m
supported duration strings
settings:
  transaction:
    ttl: 5m

Limiter

Settings for rate limiting on reads and writes.

Group key: limiter

Rate

description The limit, or maximum frequency of events. A rate of 0 signifies "unlimited".
type int
key rate
default 0
settings:
  limiter:
    rate: 0

Burst

description The bucket size for the limiter, or maximum number of events that can be fulfilled at once. If this is 0, it will take the same value as the rate.
type int
key burst
default 0
settings:
  limiter:
    burst: 0

Cache

Settings for the in-memory windowed cache of plugin reading data.

Group key: cache

Enabled

description Enable the in-memory cache to hold a small window of reading data.
type bool
key enabled
default false
supported true, false
settings:
  cache:
    enabled: true

TTL

description The time-to-live for a reading in the cache. This is only used if the cache is enabled. Once a reading exceeds this TTL, it is removed from the cache.
type duration
key ttl
default 3m
supported duration strings
settings:
  cache:
    ttl: 3m

Network

Settings for a plugin's networking behavior.

Group key: network

Type

description The protocol type for the plugin to use for gRPC transport.
type string
key type
default tcp
supported tcp, unix
network:
  type: tcp

Address

description The address the gRPC server will run on. For "tcp", this should be the host/port (e.g. "0.0.0.0:5001"). For "unix", this should be the path to the socket (e.g. "/tmp/plugin.sock").
type string
key address
network:
  address: "0.0.0.0:5001"

TLS

Settings for TLS/SSL configuration for the plugin's gRPC server. If this is not set, insecure transport is used.

Group key: tls

Cert

description The path to the cert file to use for the gRPC server.
type string
key cert
network:
  tls:
    cert: /path/to/cert.crt

Key

description The path to the key file to use for the gRPC server.
type string
key key
network:
  tls:
    key: /path/to/key.key

CA Certs

description A list of certificate authority certs to use. If none are specified, the OS system-wide CA certs are used.
type list[string]
key caCerts
network:
  tls:
    caCerts: 
    - /path/to/cacerts.ca

Skip Verify

description Skip certificate checks.
type bool
key skipVerify
default false
supported true, false
network:
  tls:
    skipVerify: true

Dynamic Registration

Settings for dynamic device registration.

Group key: dynamicRegistration

Config

description The configuration(s) for dynamic device registration which is performed at runtime.
type list[map]
key config
default []
dynamicRegistration:
  config:
  - foo: 1
    bar: "baz"

Health

Settings for plugin health checks.

Group key: health

Health File

description The fully-qualified path to the file which will be used to signal that the plugin is healthy. If the file does not exist, the plugin can be considered in an "unhealthy" state.
type string
key healthFile
default /etc/synse/plugin/healthy
health:
  healthFile: /etc/synse/plugin/healthy

Update Interval

description The frequency with which the health file will be updated. This is essentially how frequently the plugin health status gets updated.
type duration
key updateInterval
default 30s
supported duration strings
health:
  updateInterval: 30s

Checks

Settings for the individual plugin health check behaviors.

Group key: checks

Disable Defaults

description Disable the default plugin health checks which are built-in to the plugin.
type bool
key disableDefaults
default false
supported true, false
health:
  checks:
    disableDefaults: false

Example

Below is an example of a relatively simple plugin configuration:

version: 3
debug: true
network:
  type: tcp
  address: ":5001"
settings:
  mode: parallel
  read:
    interval: 1s
  write:
    interval: 2s