# Account Resources YAML Reference


> Complete reference for defining your Reverse ETL warehouse account resources using YAML configuration files.



This guide serves as a detailed reference for the CLI project YAML files that contain definitions of your Reverse ETL warehouse account resources.

**Announcement**

**Account support requires Rudder CLI v0.25.0 or later**.

Upgrade if you are using an earlier version.

## Overview

An **account** holds the credentials and connection settings for a data warehouse. A [Reverse ETL SQL model](https://www.rudderstack.com/docs/rudder-cli/yaml-sql-models/) does not carry its own credentials — it points at an account through its `account_id`. Defining accounts in YAML keeps warehouse credentials under the same Git-based workflow as your other CLI resources.

You define accounts by setting `kind` to `account`. As with every other resource type, you can store the YAML files anywhere within the project's root directory or subdirectories.

**Info:** Account specs reference secrets as variables, so pass `--var-file` when you apply them. See [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

## Account resources

The `spec` parameter of the YAML file has the following structure:

| Property | Type | Description |
| :----| :-----| :------|
| `id` <br/> Required | String | Unique identifier for the account resource within the project. This parameter must be unique across all account resources, and identifies the account on subsequent applies. |
| `name` <br/> Required | String | Display name for the account as shown in the RudderStack dashboard. |
| `account_definition_name` <br/> Required | String | The warehouse type this account connects to. <br /><br />See [Supported account definitions](#supported-account-definitions) for the values you can use. |
| `config` <br/> Required | Object | Flat map of connection settings and credentials for the warehouse. The available keys depend on `account_definition_name`. |

**Warning:** `account_definition_name` is **immutable**. Changing it on an existing account fails the apply rather than silently recreating the resource — a warehouse account is a credential, and recreating one would break every Reverse ETL source pointing at it. To move to a different warehouse type, define a new account.

### Supported account definitions

| Warehouse | `account_definition_name` value |
| :------| :-------|
| Google BigQuery | `SOURCE_BIGQUERY` |
| PostgreSQL | `SOURCE_POSTGRES` |
| Snowflake | `SOURCE_SNOWFLAKE` |

### BigQuery configuration

The `config` object for `SOURCE_BIGQUERY` accepts the following keys:

| Key | Type | Description |
| :----| :-----| :------|
| `project` <br/> Required | String | The Google Cloud project ID that owns the BigQuery dataset. |
| `location` <br/> Required | String | The BigQuery dataset location, for example `US` or `EU`. |
| `credentials` <br/> Required | String | The service account key JSON. This is a **secret** — supply it as a variable reference, never as a literal. See [Secret handling](#secret-handling). |

Although `config` is a single flat map in YAML, it is split on the way to the API — the secret keys are sent as a write-only credential payload and everything else as plain options. You do not need to model that split yourself.

### Example definition

```yaml
version: rudder/v1
kind: "account"
metadata:
  name: "prod-bq"
spec:
  id: "prod-bq"
  name: "Production BigQuery"
  account_definition_name: "SOURCE_BIGQUERY"
  config:
    project: "acme-analytics-prod"
    location: "US"
    credentials: "{{ .BQ_CREDENTIALS }}"
```

With a var file (`credentials.vars.yaml`) alongside it:

```yaml
BQ_CREDENTIALS: '{"type":"service_account","project_id":"acme-analytics-prod","private_key":"..."}'
```

Apply the two together:

```bash
rudder-cli apply --location ./project --var-file ./credentials.vars.yaml
```

### PostgreSQL configuration

The `config` object for `SOURCE_POSTGRES` accepts the following keys:

| Key | Type | Description |
| :----| :-----| :------|
| `host` <br/> Required | String | Database host |
| `dbname` <br/> Required | String | Database name |
| `user` <br/> Required | String | Database username — this is a plain option, not a secret |
| `port` <br/> Required | String | Database port — this is a **string**, not a number, matching the PostgreSQL source form |
| `sslMode` | String | One of `disable` or `require`. Defaults to `disable`. |
| `password` <br/> Required | String | Database password — this is a **secret**; supply it as a variable reference |

```yaml
version: rudder/v1
kind: "account"
metadata:
  name: "prod-postgres"
spec:
  id: "prod-postgres"
  name: "Production Postgres"
  account_definition_name: "SOURCE_POSTGRES"
  config:
    host: "warehouse.acme.internal"
    dbname: "analytics"
    user: "rudderstack"
    port: "5432"
    sslMode: "require"
    password: "{{ .PG_PASSWORD }}"
```

### Snowflake configuration

The `config` object for `SOURCE_SNOWFLAKE` accepts the following keys:

| Key | Type | Description |
| :----| :-----| :------|
| `account` <br/> Required | String | Snowflake account identifier. |
| `dbname` <br/> Required | String | Database name. |
| `warehouse` <br/> Required | String | Virtual warehouse to run against. |
| `user` <br/> Required | String | Login name. This is a plain option, not a secret. |
| `role` | String | Snowflake role to assume. |
| `authenticationType` <br/> Required | String | One of `keyPair` or `password`. Determines which secret key you must supply — see below. |
| `privateKey` | String | PEM private key. **Secret**, required when `authenticationType` is `keyPair`. |
| `privateKeyPassphrase` | String | Passphrase for the private key. **Secret**, optional, only valid with `keyPair`. |
| `password` | String | Account password. **Secret**, required when `authenticationType` is `password`. |

**Warning**

`authenticationType` decides which secret keys are legal. The combination is validated rather than ignoring surplus keys:

- `keyPair` accepts **only** `privateKey` and `privateKeyPassphrase`.
- `password` accepts **only** `password`.

Supplying a secret that does not belong to the selected authentication type — for example, a `password` alongside `authenticationType: keyPair` — is rejected, not silently dropped.

#### Key pair authentication

```yaml
version: rudder/v1
kind: "account"
metadata:
  name: "prod-snowflake"
spec:
  id: "prod-snowflake"
  name: "Production Snowflake"
  account_definition_name: "SOURCE_SNOWFLAKE"
  config:
    account: "acme-prod.us-east-1"
    dbname: "ANALYTICS"
    warehouse: "TRANSFORMING"
    user: "RUDDERSTACK"
    role: "RUDDERSTACK_ROLE"
    authenticationType: "keyPair"
    privateKey: "{{ .SF_PRIVATE_KEY }}"
    privateKeyPassphrase: "{{ .SF_PRIVATE_KEY_PASSPHRASE }}"
```
#### Password authentication

```yaml
version: rudder/v1
kind: "account"
metadata:
  name: "prod-snowflake"
spec:
  id: "prod-snowflake"
  name: "Production Snowflake"
  account_definition_name: "SOURCE_SNOWFLAKE"
  config:
    account: "acme-prod.us-east-1"
    dbname: "ANALYTICS"
    warehouse: "TRANSFORMING"
    user: "RUDDERSTACK"
    role: "RUDDERSTACK_ROLE"
    authenticationType: "password"
    password: "{{ .SF_PASSWORD }}"
```

## Secret handling

Secret fields must be written as `{{ .VARIABLE_NAME }}` references, not literals.

See [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

## Import existing accounts

You can bring warehouse accounts created through the dashboard under Git control:

```bash
rudder-cli import workspace --location ./project
```

This scaffolds two things under `./project/imported`:

- `accounts/<id>.yaml` — one spec per importable account, with every secret field masked to a `{{ .VAR }}` reference.
- `secrets.vars.yaml` — a fill-in-the-blanks var file with one placeholder line per variable the generated specs reference.

Fill in each placeholder with the real credential, then run `apply` with `--var-file` to adopt the accounts. Import scaffolds the files; the accounts are claimed on apply, after which they are managed resources and are no longer offered for import.

See [Fill placeholders after import](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/#fill-placeholders-after-import) for how placeholders and empty values behave.

You can list the accounts in your workspace, managed or not, with:

```bash
rudder-cli workspace accounts list
```

## See more

- [SQL Model Resources YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-sql-models/) — SQL models reference accounts through `account_id`
- [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/) — var files and secret fields
- [How to Import Workspace Resources into Your Rudder CLI Project](https://www.rudderstack.com/docs/rudder-cli/import-resources/) — general import workflow