Skip to content

Quick Start Guide

Get your dbt Cloud project set up with Terraform in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

Step 1: Copy the Example

Start with the basic example as a template:

git clone https://github.com/trouze/terraform-dbtcloud-yaml.git
cd terraform-dbtcloud-yaml/examples/basic

# Or copy to your own directory
cp -r examples/basic ~/my-dbt-setup
cd ~/my-dbt-setup

The basic example includes:

basic/
├── main.tf                         # Terraform module call
├── variables.tf                    # Input variable definitions
├── dbt-config.yml                  # Your dbt Cloud configuration
├── .env.example                    # Credential template
└── .github/
    └── workflows/
        ├── ci.yml                  # Plan on PR
        └── cd.yml                  # Apply on merge

Step 2: Set Your Credentials

Credentials are passed via environment variables — never hardcoded. In CI/CD, set these as secrets in your platform (see CI/CD Guide). For local use:

cp .env.example .env
# Edit .env with your actual values, then:
source .env

Your .env should look like:

# Required
export TF_VAR_dbt_account_id=12345
export TF_VAR_dbt_token=dbtc_your_api_token
export TF_VAR_dbt_host_url=https://cloud.getdbt.com

# Environment credentials — keyed by "{project_key}_{env_key}"
export TF_VAR_environment_credentials='{
  "analytics_prod": {
    "credential_type": "databricks",
    "token": "dapi...",
    "catalog": "main",
    "schema": "analytics"
  }
}'

Where to find these values

Security

Never commit .env or terraform.tfvars to version control. Both are in .gitignore by default.

Step 3: Configure Your dbt Project

Edit dbt-config.yml with your project details:

projects:
  - name: Analytics
    key: analytics
    repository:
      remote_url: "your-org/your-repo"      # GitHub: "org/repo", or full URL
      github_installation_id: 1234567        # From GitHub App integration

    environments:
      - name: Production
        key: prod
        type: deployment
        deployment_type: production
        connection_key: databricks_prod      # References global_connections[].key
        credential:
          credential_type: databricks
          catalog: main
          schema: analytics

    jobs:
      - name: Daily Build
        key: daily_build
        environment_key: prod               # References environments[].key
        execute_steps:
          - dbt build
        triggers:
          schedule: true
        schedule_type: every_day
        schedule_hours: [6]                 # 6 AM UTC

connection_key

Instead of a raw numeric connection_id, environments reference connections by connection_key — matching global_connections[].key in the YAML. This keeps your config portable and readable.

Jobs at project level

Jobs are defined at the project level with an environment_key field, not nested inside environments. This makes them easier to read and reference by key for deferral.

See the YAML Schema for all available fields including global connections, service tokens, Snowflake credentials, scheduled jobs, and more.

Step 4: Initialize Terraform

source .env

terraform init

You should see:

Initializing modules...
Downloading git::https://github.com/trouze/terraform-dbtcloud-yaml.git...

Terraform has been successfully initialized!

Step 5: Preview Changes

Always review what Terraform will create:

terraform plan

You'll see output like:

Plan: 5 to add, 0 to change, 0 to destroy.

  + dbtcloud_project.projects["analytics"]
  + dbtcloud_repository.repositories["analytics"]
  + dbtcloud_environment.environments["analytics_prod"]
  + dbtcloud_databricks_credential.credentials["analytics_prod"]
  + dbtcloud_job.jobs["analytics_daily_build"]

Step 6: Apply Configuration

terraform apply

Type yes when prompted. Terraform will create your dbt Cloud project, environments, credentials, and jobs.

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Step 7: Verify in dbt Cloud

  1. Log into dbt Cloud
  2. Navigate to your account
  3. Confirm your project, environments, and jobs are configured correctly

Making Changes

After initial setup, all changes go through the same loop:

  1. Edit dbt-config.yml
  2. Run terraform plan to preview
  3. Run terraform apply to apply
source .env
terraform plan
terraform apply

What's Next?

  • YAML Schema

    All configuration options with types, defaults, and examples

    YAML Schema

  • :material-github-box:{ .lg .middle } CI/CD Integration

    Automate plan on PR and apply on merge

    CI/CD Guide

  • Environment Variables

    Full credential variable reference

    Environment Variables

  • Troubleshooting

    Common issues and solutions

    Troubleshooting

You're all set!

Your dbt Cloud project is now managed as code. All changes are tracked in Git and deployed via Terraform.