github.com/Jeffail/benthos/v3@v3.65.0/internal/template/docs.md (about)

     1  ---
     2  title: Templating
     3  description: Learn how Benthos templates work.
     4  ---
     5  
     6  <!--
     7       THIS FILE IS AUTOGENERATED!
     8  
     9       To make changes please edit the contents of:
    10       internal/template/docs.md.tmpl
    11  -->
    12  
    13  EXPERIMENTAL: Templates are an experimental feature and therefore subject to change outside of major version releases.
    14  
    15  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.
    16  
    17  A template is defined in a YAML file that can be imported when Benthos runs using the flag `-t`:
    18  
    19  ```sh
    20  benthos -t "./templates/*.yaml" -c ./config.yaml
    21  ```
    22  
    23  The template describes the type of the component and configuration fields that can be used to customize it, followed by a [Bloblang mapping][bloblang.about] that translates an object containing those fields into a benthos config structure. This allows you to use logic to generate more complex configurations:
    24  
    25  import Tabs from '@theme/Tabs';
    26  
    27  <Tabs defaultValue="template" values={[
    28    { label: 'Template', value: 'template', },
    29    { label: 'Config', value: 'config', },
    30    { label: 'Result', value: 'result', },
    31  ]}>
    32  
    33  import TabItem from '@theme/TabItem';
    34  
    35  <TabItem value="template">
    36  
    37  ```yml
    38  name: aws_sqs_list
    39  type: input
    40  
    41  fields:
    42    - name: urls
    43      type: string
    44      kind: list
    45    - name: region
    46      type: string
    47      default: us-east-1
    48  
    49  mapping: |
    50    root.broker.inputs = this.urls.map_each(url -> {
    51      "aws_sqs": {
    52        "url": url,
    53        "region": this.region,
    54      }
    55    })
    56  ```
    57  
    58  </TabItem>
    59  <TabItem value="config">
    60  
    61  ```yml
    62  input:
    63    aws_sqs_list:
    64      urls:
    65        - https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue1
    66        - https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue2
    67  
    68  pipeline:
    69    processors:
    70      - bloblang: |
    71          root.id = uuid_v4()
    72          root.foo = this.inner.foo
    73          root.body = this.outter
    74  ```
    75  
    76  </TabItem>
    77  <TabItem value="result">
    78  
    79  ```yaml
    80  input:
    81    broker:
    82      inputs:
    83        - aws_sqs:
    84            url: https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue1
    85            region: us-east-1
    86        - aws_sqs:
    87            url: https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue2
    88            region: us-east-1
    89  
    90  pipeline:
    91    processors:
    92      - bloblang: |
    93          root.id = uuid_v4()
    94          root.foo = this.inner.foo
    95          root.body = this.outter
    96  ```
    97  
    98  </TabItem>
    99  
   100  </Tabs>
   101  
   102  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](https://github.com/Jeffail/benthos/tree/master/template).
   103  
   104  ## Fields
   105  
   106  The schema of a template file is as follows:
   107  
   108  {{template "field_docs" . -}}
   109  
   110  [bloblang.about]: /docs/guides/bloblang/about