Select spec version:

Destination YAML Reference Beta

Complete reference for defining destinations using YAML configuration files.

Available Plans

free
growth
enterprise

5 minute read

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

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.

Destination support is experimental.
Enable destinationSupport (RUDDERSTACK_X_DESTINATION_SUPPORT=true) before you validate or apply destination specs. Rudder CLI currently supports Amazon S3 (s3). See Supported destination types.
If config references secrets as {{ .VAR }}, also enable variable substitution and 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:

Property	Type	Description
`id` Required	String	Unique identifier for the destination within the project. Other specs reference it as `#destination:[id]`.
`display_name` Required	String	Name shown in the RudderStack dashboard. Must be 2–100 characters and contain only letters, digits, underscores, spaces, periods, and hyphens. Must be unique across destinations in the project.
`type` Required	String	Destination type. See Supported destination types. Immutable after apply — changing `type` fails the update.
`definition_version` Required	Integer	Definition version for `type`. Set this to `1` — that is the current version for every registered destination.
`enabled`	Boolean	Whether the destination is enabled. If you omit this field, Rudder CLI creates the destination as disabled. Set `enabled: true` to deliver events after you connect a source.
`config`	Object	Per-type connection settings. Keys and validation rules come from the destination definition. Unknown envelope fields (siblings of these properties) fail validation.
`transformation`	String	Optional URN of a transformation in the same project — `#transformation:[transformation.id]`. The referenced transformation must exist in the project.

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

Use the type value in YAML. Rudder CLI currently supports Amazon S3.

Unverified destinations will be supported in the next iteration.

Destination	`type`
Amazon S3	`s3`

Rudder CLI rejects any type that is not in this table. The dashboard supports more destinations than the CLI.

Amazon S3 configuration

config for type: s3 (definition_version: 1):

Key	Type	Description
`bucket_name` Required	String	S3 bucket name (1–100 characters).
`role_based_auth` Required	Boolean	`true` for IAM role authentication; `false` for access keys.
`iam_role_arn`	String	IAM role ARN. Required when `role_based_auth` is `true`; do not set it when `role_based_auth` is `false`.
`access_key_id`	String	AWS access key ID. Secret. Required when `role_based_auth` is `false`; do not set it when `role_based_auth` is `true`.
`access_key`	String	AWS secret access key. Secret. Required when `role_based_auth` is `false`; do not set it when `role_based_auth` is `true`.
`prefix`	String	Optional object prefix (max 100 characters).
`enable_sse`	Boolean	Optional server-side encryption setting.

access_key_id and access_key are secrets. Supply them as {{ .VAR }} references — see Secret handling.

Destination definitions also validate extra keys such as consent_management. validate reports unknown or invalid config keys for the selected type.

Source-type-scoped keys

The S3 config block also accepts source-type-scoped keys such as connection_mode and use_native_sdk. Each nested key must be a source type that destination supports. Connection mode belongs on the destination spec, not on an Event Stream connection.

Examples

Amazon S3 with IAM role authentication

yaml

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

Amazon S3 with access keys

yaml

version: rudder/v1
kind: destination
metadata:
  name: s3
spec:
  id: s3
  display_name: "S3 Destination"
  type: s3
  definition_version: 1
  enabled: true
  config:
    bucket_name: "my-rudder-bucket"
    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.

yaml

version: rudder/v1
kind: destination
metadata:
  name: s3
spec:
  id: s3
  display_name: "S3 Destination"
  type: s3
  definition_version: 1
  enabled: true
  transformation: "#transformation:enrich-events"
  config:
    bucket_name: "my-rudder-bucket"
    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

bash

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

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

Fill secret placeholders before apply. 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.

Check	When it fails
Required envelope fields	`id`, `display_name`, `type`, or `definition_version` is missing
`display_name` format	Value is outside 2–100 characters or uses characters other than letters, digits, underscores, spaces, periods, and hyphens
Duplicate `display_name`	Two destinations in the project share the same `display_name`
Unknown `type`	`type` is not a supported destination type (or `destinationSupport` is off)
Invalid `definition_version`	Version is not registered for that `type`
`config` shape	Required keys are missing, types are wrong, or mutually exclusive auth fields are combined (for example S3 role ARN together with access keys)
Unsupported source-type key	A nested `connection_mode` / `use_native_sdk` key uses a source type the destination does not support
Transformation reference	`transformation` is not `#transformation:[id]`, or that transformation is not in the project

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

See more

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

Destination YAML Reference Beta

Overview

Destination resources

Supported destination types

Amazon S3 configuration

Source-type-scoped keys

Examples

Amazon S3 with IAM role authentication

Amazon S3 with access keys

Destination with a transformation

Secret handling

Import existing destinations

Validation rules

See more

Questions? Let's figure it out together.