# Templating

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [connect-full.txt](https://docs.redpanda.com/connect-full.txt)

---
title: Templating
latest-connect-version: 4.93.0
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-redpanda-tag: v26.1.9
docname: templating
page-component-name: connect
page-version: master
page-component-version: master
page-component-title: Connect
page-relative-src-path: templating.adoc
page-edit-url: https://github.com/redpanda-data/rp-connect-docs/edit/main/modules/configuration/pages/templating.adoc
description: Learn how templates work.
page-git-created-date: "2024-05-24"
page-git-modified-date: "2025-09-18"
---

<!-- Source: https://docs.redpanda.com/connect/configuration/templating.md -->

> ⚠️ **CAUTION**
>
> Templates are an experimental feature and are subject to change outside major version releases.

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

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

```bash
rpk connect run -t "./templates/*.yaml" ./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](https://docs.redpanda.com/connect/guides/bloblang/about/) that translates an object containing those fields into a Redpanda Connect configuration structure. This allows you to use logic to generate more complex configurations:

#### Template

```yaml
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,
    }
  })
```

#### Configuration

```yaml
input:
  aws_sqs_list:
    urls:
      - https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue1
      - https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue2

pipeline:
  processors:
    - mapping: |
        root.id = uuid_v4()
        root.foo = this.inner.foo
        root.body = this.outer
```

#### Result

```yaml
input:
  broker:
    inputs:
      - aws_sqs:
          url: https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue1
          region: us-east-1
      - aws_sqs:
          url: https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue2
          region: us-east-1

pipeline:
  processors:
    - mapping: |
        root.id = uuid_v4()
        root.foo = this.inner.foo
        root.body = this.outer
```

You can see more examples of templates on [GitHub](https://github.com/redpanda-data/connect/blob/main/config/template_examples).

## [](#fields)Fields

The schema of a template file is as follows:

### [](#name)`name`

The name of the component this template will create.

**Type**: `string`

### [](#type)`type`

The type of the component this template will create.

**Type**: `string`

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

### [](#status)`status`

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

**Type**: `string`

**Default**: `"stable"`

| Option | Summary |
| --- | --- |
| stable | This template is stable and will therefore not change in a breaking way outside of major version releases. |
| beta | This template is beta and will therefore not change in a breaking way unless a major problem is found. |
| experimental | This template is experimental and therefore subject to breaking changes outside of major version releases. |

### [](#categories)`categories`

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

**Type**: `array`

**Default**: `[]`

### [](#summary)`summary`

A short summary of the component.

**Type**: `string`

**Default**: `""`

### [](#description)`description`

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

**Type**: `string`

**Default**: `""`

### [](#fields-2)`fields`

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

**Type**: `array`

### [](#fields-name)`fields[].name`

The name of the field.

**Type**: `string`

### [](#fields-description)`fields[].description`

A description of the field.

**Type**: `string`

**Default**: `""`

### [](#fields-type)`fields[].type`

The scalar type of the field.

**Type**: `string`

| Option | Summary |
| --- | --- |
| string | standard string type |
| string_enum | string type which can have one of a discrete list of values |
| string_annotated_enum | string type which can have one of a discrete list of values, where each value must be accompanied by a description that annotates its behaviour in the documentation |
| int | standard integer type |
| float | standard float type |
| bool | A boolean true/false |
| bloblang | A bloblang mapping |
| unknown | Allows for nesting arbitrary configuration inside a field |

### [](#fields-kind)`fields[].kind`

The kind of the field.

**Type**: `string`

**Default**: `"scalar"`

Options: `scalar` , `map` , `list` .

### [](#fields-default)`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**: `object`

### [](#fields-advanced)`fields[].advanced`

Whether this field is considered advanced.

**Type**: `bool`

**Default**: `false`

### [](#fields-options)`fields[].options`

A list of options for `string_enum` fields, or a map of annotated options for `string_annotated_enum` fields.

Required when `fields[].type` is set to `string_enum` or `string_annotated_enum`.

-   For `string_enum`, provide a non-empty array of string values.

-   For `string_annotated_enum`, provide a map of `value: "description"` pairs, which are used to annotate behaviour in the docs UI.


**Type**: `unknown`

```yml
# Examples

fields:
  - name: mode
    type: string_enum
    options: ["fast", "balanced", "safe"]

  - name: delivery
    type: string_annotated_enum
    options:
      at_least_once: "May duplicate messages but never loses them."
      exactly_once: "Stronger guarantees but with a higher cost and constraints."
```

### [](#mapping)`mapping`

A [Bloblang](https://docs.redpanda.com/connect/guides/bloblang/about/) mapping that translates the fields of the template into a valid Redpanda Connect configuration for the target component type.

### [](#metrics_mapping)`metrics_mapping`

An optional [Bloblang mapping](https://docs.redpanda.com/connect/guides/bloblang/about/) that allows you to rename or prevent certain metrics paths from being exported. For more information check out the [metrics documentation](https://docs.redpanda.com/connect/components/metrics/about/#metric-mapping). When metric paths are created, renamed and dropped a trace log is written, enabling TRACE level logging is therefore a good way to diagnose path mappings.

Invocations of this mapping are able to reference a metadata field `@label` in order to obtain the value of the label provided to the template configuration. This allows you to match labels with the root of the configuration.

**Type**: `string`

**Default**: `""`

```yml
# Examples

metrics_mapping: this.replace("input", "source").replace("output", "sink")

metrics_mapping: |-
  root = if ![
    "input_received",
    "input_latency",
    "output_sent"
  ].contains(this) { deleted() }
```

### [](#tests)`tests`

Optional unit test definitions for the template to help you produce valid configurations.

The following examples show a test template, associated test configuration, and the commands to execute tests to verify them.

**Type**: `array`

**Default**: `[]`

`test.template.yaml`

```yaml
name: basictemplate
type: input

mapping: |
  root.generate = {
    "count": 1,
    "mapping": "root = \"" + @label.or("") + "\""
  }

tests:
  - name: basictemplate test
    label: quack
    config: {}
    expected:
      generate:
        count: 1
        mapping: root = "quack"
```

`testconfig.yaml`

```yaml
input:
  label: meow
  basictemplate: {}
```

Test execution:

```bash
rpk connect template lint test.template.yaml
rpk connect run -t "./test.template.yaml" ./testconfig.yaml
```

### [](#tests-name)`tests[].name`

A name to identify the test.

**Type**: `string`

### [](#tests-label)`tests[].label`

A label to assign to this template when running the test.

**Type**: `string`

**Default**: `""`

### [](#tests-config)`tests[].config`

A configuration to run this test against. Redpanda Connect checks the results of applying the template with this configuration using a linter.

**Type**: `object`

### [](#tests-expected)`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`