# Connection YAML Reference


This guide is the YAML reference for Event Stream connection resources in a Rudder CLI project.

## Overview

Set `kind` to `event-stream-connections`. The spec body is a **list**. Each entry is one Event Stream source to destination link. Store the files anywhere under the project root.

Reverse ETL connections are not supported yet.

{{< warning >}}
**Connection support is experimental**.

Enable `connectionSupport` (`RUDDERSTACK_X_CONNECTION_SUPPORT=true`). Destination resources in the same project still need `destinationSupport`.
{{< /warning >}}

Each `source` must be `#event-stream-source:…`. A `config` block on this kind is a parse error. Connection mode and other per-source-type settings live on the [destination spec]({{< ref "dev-tools/rudder-cli/yaml-destinations.md" >}}).

## Connection fields

Each entry in `spec.connections` has these fields:

| Property | Type | <div style="width:300px">Description</div> |
| :----| :-----| :------|
| `id` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Local identifier. Must be unique across connection entries in the project. |
| `source` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Reference to an Event Stream source in this project — `#event-stream-source:[source.id]`. |
| `destination` <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | String | Reference to a destination in this project — `#destination:[destination.id]`. |
| `enabled` | Boolean | Whether this connection delivers. Defaults to `true`. Both the source and the destination must also be enabled for data to flow; `validate` warns if they are not. |

Changing `source` or `destination` replaces the connection (delete + create). The backend allows only one live row per source–destination pair. `enabled` is the only field you can update in place.

## Example

```yaml
version: rudder/v1
kind: event-stream-connections
metadata:
  name: app-connections
spec:
  connections:
    - id: android-to-s3
      source: "#event-stream-source:my-android-source"
      destination: "#destination:s3"
      enabled: true
```

## Validation rules

`rudder-cli validate` runs these checks locally. **Error** blocks validate and apply. **Warning** does not.

| Check | Severity |
| :----| :-----|
| `source` and `destination` exist in the project | Error |
| Connection `id` is unique; refs use `#event-stream-source:` and `#destination:` | Error |
| The same source–destination pair appears only once in the project | Error |
| The destination definition supports the source's type | Error |
| The destination `config` includes every field that definition requires for the connecting source type | Error |
| An `enabled` connection has both endpoints enabled | Warning |
| The destination's other project connections are also Event Stream | Error |

The following are **not** checked locally. Apply surfaces the server error: workspace plan gates, permissions, and OAuth or account existence.

Topology rules see only connections in the project. Remote-only connections (created in the dashboard and never imported) are invisible at validate time.

## Import existing connections

```bash
rudder-cli import workspace -l <project-directory>
```

Import writes all Event Stream connections into one file, `imported/event-stream/connections.yaml`. Related Event Stream sources land under `imported/event-stream/sources/`. See [How to Import Workspace Resources]({{< ref "dev-tools/rudder-cli/import-resources/" >}}).

## See more

- [Manage Connections using Rudder CLI]({{< ref "dev-tools/rudder-cli/connections.md" >}}) for feature overview, and the [Connections walkthrough]({{< ref "dev-tools/rudder-cli/connections-walkthrough.md" >}}) for step-by-step setup
- [Destination YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-destinations.md" >}}) and [Event Stream Source YAML Reference]({{< ref "dev-tools/rudder-cli/yaml-event-stream-sources.md" >}})