Select spec version:

Connection YAML Reference Beta

Complete YAML reference for event-stream-connections resources in Rudder CLI.
Available Plans
  • free
  • growth
  • enterprise

  •   12 minute read  

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

Connection support requires Rudder CLI v0.25.0 or later. Reverse ETL connections are not supported yet.

Upgrade if you are using an earlier version.

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.

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.

Connection fields

Each entry in spec.connections has these fields:

PropertyType
Description
id
Required		StringLocal identifier. Must be unique across connection entries in the project.
source
Required		StringReference to an Event Stream source in this project — #event-stream-source:[source.id].
destination
Required		StringReference to a destination in this project — #destination:[destination.id].
enabledBooleanWhether 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.

CheckSeverity
source and destination exist in the projectError
Connection id is unique; refs use #event-stream-source: and #destination:Error
The same source–destination pair appears only once in the projectError
The destination definition supports the source’s typeError
The destination config includes every field that definition requires for the connecting source typeError
An enabled connection has both endpoints enabledWarning
The destination’s other project connections are also Event StreamError

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.

The rule catalog below lists every rule with valid and invalid examples.

Spec version
Filter by phase

Showing 6 of 6 rules

An enabled Event Stream connection needs both its endpoints enabled to deliver events

semantic warning

Rule ID: event-stream/connection/enabled-endpoints-valid

Examples

Enabled connection whose source and destination are both enabled

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
      enabled: true
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
  enabled: true

Disabled connection may point at disabled endpoints

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
      enabled: false
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: false
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
  enabled: false

Enabled connection whose source is disabled

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
  enabled: false
Diagnostics
  • connections.yaml /spec/connections/0/source connection 'js-to-s3' is enabled but its source 'my-js-source' is disabled

Enabled connection whose destination is disabled

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: false
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
  enabled: true
Diagnostics
  • connections.yaml /spec/connections/0/destination connection 'js-to-s3' is enabled but its destination 'my-s3-destination' is disabled

Event Stream connection endpoints must exist in the project and form a valid, compatible topology

semantic error

Rule ID: event-stream/connection/semantic-valid

Examples

Connection whose source and destination exist and are compatible

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript

Connection whose source does not exist in the project

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: ghost-to-s3
      source: "#event-stream-source:ghost-source"
      destination: "#destination:my-s3-destination"
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud
Diagnostics
  • connections.yaml /spec/connections/0/source event stream source 'ghost-source' not found in the project

Connection whose destination does not exist in the project

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-ghost
      source: "#event-stream-source:my-js-source"
      destination: "#destination:ghost-destination"
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
Diagnostics
  • connections.yaml /spec/connections/0/destination destination 'ghost-destination' not found in the project

The same source-destination pair connected twice

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
    - id: js-to-s3-again
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      web: cloud
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
Diagnostics
  • connections.yaml /spec/connections/0 connected more than once in the project
  • connections.yaml /spec/connections/1 connected more than once in the project

Destination that does not support the source's type

The WEBHOOK definition here supports web and android sources only; a python source connects as a cloud source, so the pairing is rejected.

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: python-to-webhook
      source: "#event-stream-source:my-python-source"
      destination: "#destination:my-webhook-destination"
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-webhook-destination
spec:
  id: my-webhook-destination
  display_name: Production Webhook
  type: WEBHOOK
  enabled: true
  definition_version: 1
  config:
    webhook_url: "https://example.com/hook"
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-python-source
spec:
  id: my-python-source
  name: My Python Source
  type: python
Diagnostics
  • connections.yaml /spec/connections/0/destination does not support source 'my-python-source'

Destination declaring no settings for the source's type

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-s3
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-s3-destination"
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-s3-destination
spec:
  id: my-s3-destination
  display_name: Production S3
  type: s3
  enabled: true
  definition_version: 1
  config:
    bucket_name: my-bucket
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::123456789012:role/rudder"
    connection_mode:
      android: cloud
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
Diagnostics
  • connections.yaml /spec/connections/0/destination has no 'connection_mode' entry for source type 'web'

Destination config missing a field the source type requires to connect

The WEBHOOK definition here requires webhook_url before a web source may connect in cloud mode; the config declares that mode but omits the field.

connections.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: js-to-webhook
      source: "#event-stream-source:my-js-source"
      destination: "#destination:my-webhook-destination"
destination.yaml yaml 
version: rudder/v1
kind: destination
metadata:
  name: my-webhook-destination
spec:
  id: my-webhook-destination
  display_name: Production Webhook
  type: WEBHOOK
  enabled: true
  definition_version: 1
  config:
    connection_mode:
      web: cloud
source.yaml yaml 
version: rudder/v1
kind: event-stream-source
metadata:
  name: my-js-source
spec:
  id: my-js-source
  name: My JavaScript Source
  type: javascript
Diagnostics
  • connections.yaml /spec/connections/0/destination config is missing fields required to connect a 'web' source

Event Stream connection spec syntax must be valid

syntactic error

Rule ID: event-stream/connection/spec-syntax-valid

Examples

Valid connection linking an Event Stream source to a destination

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

Valid connection list with an explicitly disabled entry

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

Connection entry missing required source and destination

spec.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: android-to-s3
Diagnostics
  • spec.yaml /spec/connections/0/source 'source' is required
  • spec.yaml /spec/connections/0/destination 'destination' is required

Connection whose source is not a reference

spec.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: android-to-s3
      source: "my-android-source"
      destination: "#destination:my-s3-destination"
Diagnostics
  • spec.yaml /spec/connections/0/source 'source' is invalid: must be of pattern #event-stream-source:<id>

Connection whose source ref points at a rETL source kind

spec.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: model-to-s3
      source: "#retl-source-sql-model:my-model"
      destination: "#destination:my-s3-destination"
Diagnostics
  • spec.yaml /spec/connections/0/source 'source' must reference an event stream source (#event-stream-source:<id>), got a 'retl-source-sql-model' reference

Connection whose destination ref points at a source

spec.yaml yaml 
version: rudder/v1
kind: event-stream-connections
metadata:
  name: my-connections
spec:
  connections:
    - id: android-to-s3
      source: "#event-stream-source:my-android-source"
      destination: "#event-stream-source:my-js-source"
Diagnostics
  • spec.yaml /spec/connections/0/destination 'destination' must reference a destination (#destination:<id>), got a 'event-stream-source' reference

URNs must be unique across the project

syntactic error

Rule ID: project/duplicate-urn

Examples

Distinct URNs across files

Each spec declares a different resource, so URNs do not collide.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

Same URN declared in two files

Both files declare the same event ID, which resolves to one URN. The rule flags each occurrence.

a.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed
b.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)
Diagnostics
  • a.yaml /spec/events/0/id duplicate URN 'event:order_completed'
  • b.yaml /spec/events/0/id duplicate URN 'event:order_completed'

A (workspace_id, urn) must not be defined in both an import-manifest and inline metadata.import with differing remote_ids

syntactic error

Rule ID: project/manifest-inline-conflict

Examples

Manifest and inline metadata import distinct resources

One resource is imported via the manifest, a different one via inline metadata. No URN appears in both, so the project is valid.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:cart_viewed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
    - id: cart_viewed
      name: Cart Viewed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"

Same URN imported by both a manifest and inline metadata

The URN event:order_completed is declared in both the manifest and an inline metadata.import block — an ambiguous double import. The rule flags both locations; remove one.

events.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - urn: "event:order_completed"
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Manifest URN overlaps a legacy rudder/0.1 inline local_id import

The events spec uses the legacy rudder/0.1 format, whose inline imports reference resources by local_id + remote_id. The local_id order_completed resolves to the URN event:order_completed — the same URN the manifest imports. Legacy specs are still subject to the conflict rule, so both locations are flagged; remove the inline metadata entry.

events.yaml yaml 
version: rudder/0.1
kind: events
metadata:
  name: events
  import:
    workspaces:
      - workspace_id: "ws-1"
        resources:
          - local_id: order_completed
            remote_id: "remote_b"
spec:
  events:
    - id: order_completed
      name: Order Completed
import-manifest.yaml yaml 
version: rudder/v1
kind: import-manifest
metadata:
  name: import-manifest
spec:
  workspaces:
    - workspace_id: "ws-1"
      resources:
        - urn: "event:order_completed"
          remote_id: "remote_a"
Diagnostics
  • import-manifest.yaml /spec/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata
  • events.yaml /metadata/import/workspaces/0/resources/0/urn URN 'event:order_completed' is defined in both an import-manifest and inline metadata

Metadata syntax must be valid

syntactic error

Rule ID: project/metadata-syntax-valid

Examples

Metadata with only the required name

Minimal valid metadata: a name only.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
spec:
  events: []

Metadata with a well-formed import block

An import block where each workspace declares workspace_id and each resource references a URN in the spec body.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - workspace_id: ws-123
        resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed

Metadata missing required name

Every spec metadata block must declare a name.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []
Diagnostics
  • spec.yaml /metadata/name 'name' is required

Import workspace missing required workspace_id

Each import workspace entry must declare a workspace_id.

spec.yaml yaml 
version: rudder/v1
kind: events
metadata:
  name: my-events
  import:
    workspaces:
      - resources:
          - urn: "event:order_completed"
            remote_id: ev-remote-456
spec:
  events:
    - id: order_completed
      name: Order Completed
Diagnostics
  • spec.yaml /metadata/import/workspaces/0/workspace_id 'workspace_id' is required

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.

See more

Questions? Let's figure it out together.

Join the RudderStack Slack community to connect with other users, customers, and the RudderStack team — or reach out for direct support.

Slack community Join now Email support Reach out