Skip to main content

Templating

EXPERIMENTAL: Templates are an experimental feature and therefore subject to change (or removal) outside of major version releases.

Templates are a way to define new Benthos components (similar to plugins) that are implemented by generating a Benthos config snippet from pre-defined parameter fields. This is useful when a common pattern of Benthos configuration is used but with varying parameters each time.

Templates will be available to try in version 3.47.0. The release date is yet to be determined, but in the meantime you can grab release candidates from the releases page or pull nightly builds from docker with the jeffail/benthos:edge tag.

A template is defined in a YAML file that can be imported when Benthos runs using the flag -t:

benthos -t "./templates/*.yaml" -c ./config.yaml

You can see examples of templates, including some that are included as part of the standard Benthos distribution, at https://github.com/Jeffail/benthos/tree/master/template.

Fields#

The schema of a template file is as follows:

name#

The name of the component this template will create.

Type: string

type#

The type of the component this template will create.

Type: string

Options: cache, input, output, processor, rate_limit.

status#

The stability of the template describing the likelihood that the configuration spec of the template, or it's behaviour, will change.

Type: string

OptionSummary
stableThis template is stable and will therefore not change in a breaking way outside of major version releases.
betaThis template is beta and will therefore not change in a breaking way unless a major problem is found.
experimentalThis template is experimental and therefore subject to breaking changes outside of major version releases.

categories#

An optional list of tags, which are used for arbitrarily grouping components in documentation.

Type: list of string

summary#

A short summary of the component.

Type: string

description#

A longer form description of the component and how to use it.

Type: string

fields#

The configuration fields of the template, fields specified here will be parsed from a Benthos config and will be accessible from the template mapping.

Type: list of object

fields[].name#

The name of the field.

Type: string

fields[].description#

A description of the field.

Type: string

fields[].type#

The scalar type of the field.

Type: string

Options: string, int, float, bool.

fields[].kind#

The kind of the field.

Type: string

Options: scalar, map, list.

fields[].default#

An optional default value for the field. If a default value is not specified then a configuration without the field is considered incorrect.

fields[].advanced#

Whether this field is considered advanced.

Type: bool

mapping#

A Bloblang mapping that translates the fields of the template into a valid Benthos configuration for the target component type.

Type: string

metrics_mapping#

An optional Bloblang mapping that allows you to rename or prevent certain metrics paths from being exported.

# Examples
metrics_mapping: this.replace(".foo.count", ".count")
metrics_mapping: if ![ "count", "error", "latency" ].contains(this) { deleted() }

tests#

Optional unit test definitions for the template that verify certain configurations produce valid configs. These tests are executed with the command benthos template lint.

Type: list of object

tests[].name#

A name to identify the test.

Type: string

tests[].config#

A configuration to run this test with, the config resulting from applying the template with this config will be linted.

Type: object

tests[].expected#

An optional configuration describing the expected result of applying the template, when specified the result will be diffed and any mismatching fields will be reported as a test error.

Type: object