Skip to main content

Templating

EXPERIMENTAL: Templates are an experimental feature and therefore subject to change 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.

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

The template describes the type of the component and configuration fields that can be used to customize it, followed by a Bloblang mapping that translates an object containing those fields into a benthos config structure. This allows you to use logic to generate more complex configurations:

name: aws_sqs_list
type: input


fields:
  - name: urls
    type: string
    kind: list
  - name: region
    type: string
    default: us-east-1


mapping: |
  root.broker.inputs = this.urls.map_each(url -> {
    "aws_sqs": {
      "url": url,
      "region": this.region,
    }
  })

You can see more 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
Default: "stable"

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
Default: []

summary​

A short summary of the component.

Type: string
Default: ""

description​

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

Type: string
Default: ""

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
Default: ""

fields[].type​

The scalar type of the field.

Type: string
Options: string, int, float, bool.

fields[].kind​

The kind of the field.

Type: string
Default: "scalar"
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.

Type: unknown

fields[].advanced​

Whether this field is considered advanced.

Type: bool
Default: false

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.

Type: string
Default: "" 

# 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
Default: []

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