Destination YAML Reference Beta

This guide is the YAML reference for destination resources in a Rudder CLI project.

Destination support requires Rudder CLI v0.25.0 or later.

Upgrade if you are using an earlier version.

Overview

Set kind to destination. Each file defines one destination. You can store the file anywhere under the project root — Rudder CLI scans the directory recursively.

If config references secrets as {{ .VAR }}, pass --var-file on apply. See How to Use Variable Substitution in Rudder CLI.

Local YAML uses snake_case config keys. Rudder CLI converts them to the API’s camelCase at apply time. Do not put camelCase keys in the spec.

Destination resources

The spec object has the following structure:

type is immutable. To send data to a different destination product, define a new destination resource rather than editing type on an existing one.

Supported destination types

Rudder CLI supports 24 destination types. Every one takes definition_version: 1, and each has its own set of config keys.

See Destination Type Reference for Rudder CLI for the full list of type values, the config keys each type accepts, and the rules shared across all of them — source types, connection modes, consent_management, and secrets.

Important considerations

• Rudder CLI rejects any type outside this table. You can define more destinations in the RudderStack dashboard than what you can define in Rudder CLI.
• To start from a destination you already configured in the dashboard, run rudder-cli import workspace — the imported YAML uses the same keys these pages document. See How to Import Workspace Resources for more information.

Config keys

config keys are specific to the destination type. Unknown keys fail validation with unknown config field "<key>".

Two keys are accepted by every type:

• connection_mode — maps each source type you connect to the mode its events reach the destination in. This lives on the destination spec, not on the connection spec.
• consent_management — consent provider configuration per source type.

Both are objects keyed by local source type, and a key naming a source type the destination doesn’t support fails validation. See Connection modes and Consent management.

For everything else, see the type’s own page — for example Amazon S3 Destination Config Reference or BigQuery Destination Config Reference.

Examples

Amazon S3 with IAM role authentication

version: rudder/v1
kind: destination
metadata:
  name: amazon-s3-prod
spec:
  id: amazon-s3-prod
  display_name: "Amazon S3 Production"
  type: s3
  definition_version: 1
  enabled: true
  config:
    bucket_name: "rudder-events-prod"
    prefix: "rudder/events"
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ROLE_NAME>"

Amazon S3 with access keys

version: rudder/v1
kind: destination
metadata:
  name: amazon-s3-prod
spec:
  id: amazon-s3-prod
  display_name: "Amazon S3 Production"
  type: s3
  definition_version: 1
  enabled: true
  config:
    bucket_name: "rudder-events-prod"
    role_based_auth: false
    access_key_id: "{{ .AWS_ACCESS_KEY_ID }}"
    access_key: "{{ .AWS_SECRET_ACCESS_KEY }}"

Destination with a transformation

The transformation must exist in the same project. Rudder CLI creates or updates the destination, then links the transformation.

version: rudder/v1
kind: destination
metadata:
  name: amazon-s3-prod
spec:
  id: amazon-s3-prod
  display_name: "Amazon S3 Production"
  type: s3
  definition_version: 1
  enabled: true
  transformation: "#transformation:enrich-events"
  config:
    bucket_name: "rudder-events-prod"
    role_based_auth: true
    iam_role_arn: "arn:aws:iam::<AWS_ACCOUNT_ID>:role/<ROLE_NAME>"

Secret handling

Secret config keys (for example S3 access_key and access_key_id) must be {{ .VARIABLE_NAME }} references, not literals.

See How to Use Variable Substitution in Rudder CLI.

Import existing destinations

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

Rudder CLI writes one file per destination under imported/destinations/<id>.yaml, converts config to snake_case, and records import metadata. Use import to bring destinations you created in the dashboard under CLI management.

Secret keys it receives are written as {{ .VAR }} placeholders rather than values, and the imported YAML may or may not include every secret key. Before you apply, make sure each one your configuration needs is present and populated through variable substitution. See Fill placeholders after import.

See How to Import Workspace Resources for the full import workflow.

Validation rules

rudder-cli validate checks destination specs before apply. Failures block apply.

Plan limits, OAuth token state, and live warehouse connectivity are not checked locally. The server returns those errors on apply.

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

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  definition_version: 1
  transformation: "#transformation:my-transformation"
  config:
    webhook_url: "https://example.com/hook"

version: rudder/v1
kind: transformation
metadata:
  name: my-transformation
spec:
  id: my-transformation
  name: My Transformation
  language: javascript
  code: "export function transformEvent(event) { return event; }"

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  definition_version: 1
  transformation: "#transformation:ghost"
  config:
    webhook_url: "https://example.com/hook"

version: rudder/v1
kind: destination
metadata:
  name: webhook-a
spec:
  id: webhook-a
  display_name: Shared Name
  type: WEBHOOK
  definition_version: 1
  config:
    webhook_url: "https://example.com/hook-a"

version: rudder/v1
kind: destination
metadata:
  name: webhook-b
spec:
  id: webhook-b
  display_name: Shared Name
  type: WEBHOOK
  definition_version: 1
  config:
    webhook_url: "https://example.com/hook-b"

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  enabled: true
  definition_version: 1
  config:
    webhook_url: "https://example.com/hook"

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  definition_version: 1
  unexpected_field: true
  config:
    webhook_url: "https://example.com/hook"

version: rudder/v1
kind: destination
metadata:
  name: mystery-dest
spec:
  id: mystery-dest
  display_name: Mystery Destination
  type: NOT_A_REAL_TYPE
  definition_version: 1
  config: {}

version: rudder/v1
kind: destination
metadata:
  name: webhook-prod
spec:
  id: webhook-prod
  display_name: Production Webhook
  type: WEBHOOK
  definition_version: 1
  transformation: "transformation/my-transformation"
  config:
    webhook_url: "https://example.com/hook"

version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed

version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: cart_viewed
      name: Cart Viewed

version: rudder/v1
kind: events
metadata:
  name: events-a
spec:
  events:
    - id: order_completed
      name: Order Completed

version: rudder/v1
kind: events
metadata:
  name: events-b
spec:
  events:
    - id: order_completed
      name: Order Completed (duplicate)

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

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"

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

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"

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

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"

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

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

version: rudder/v1
kind: events
metadata:
  import:
    workspaces:
      - workspace_id: ws-123
spec:
  events: []

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

See more

• Destination Type Reference for Rudder CLI for the config keys each destination type accepts
• Manage Destinations using Rudder CLI for feature overview, and the Destinations walkthrough for step-by-step setup
• How to Use Variable Substitution in Rudder CLI for secret config keys
• Connection YAML Reference to link this destination to a source
• Transformation YAML Reference for the #transformation: target