/rudder-terraform-setup

name: rudder-terraform-setup
description: Installs Terraform and configures the RudderStack provider. Use when setting up terraform for rudderstack, installing terraform-provider-rudderstack, or terraform provider not found errors
allowed-tools: "Bash(which, curl, terraform *, uname), Read, Write, Edit"

RudderStack Terraform Setup

Install Terraform (if missing), configure the RudderStack provider, and verify setup.

Setup Workflow

1. Check Terraform ──► terraform version
         │
         ├── Found ──► Skip to Provider Setup
         │
         └── Not Found ──► Guide Installation
                                    │
2. Configure Provider ◄─────────────┘
         │
         └── Add required_providers block

3. Initialize ──► terraform init
         │
         └── Downloads provider from registry

4. Configure Auth ──► Check RUDDERSTACK_ACCESS_TOKEN
         │
         └── Verify with terraform plan

Step 1: Check Terraform Installation

terraform version

**If found:** Shows version. Skip to Step 2.

**If not found:** Install Terraform.

Install Terraform

macOS (Homebrew)

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

Linux (apt)

# Add HashiCorp GPG key
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

# Add repository
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

# Install
sudo apt update && sudo apt install terraform

Alternative: tfenv (Version Manager)

# macOS
brew install tfenv

# Then install Terraform
tfenv install latest
tfenv use latest

Verify Installation

terraform version

Expected: `Terraform v1.x.x`

Step 2: Configure RudderStack Provider

Create or Update versions.tf

In your Terraform project directory, create `versions.tf`:

terraform {
  required_version = ">= 1.0"

  required_providers {
    rudderstack = {
      source  = "rudderlabs/rudderstack"
      version = "~> 4.3.1"
    }
  }
}

provider "rudderstack" {
  # access_token read from RUDDERSTACK_ACCESS_TOKEN env var
}

Check Provider Latest Version

Visit https://registry.terraform.io/providers/rudderlabs/rudderstack/latest for the current version.

Step 3: Initialize Provider

terraform init

Expected output:

Initializing provider plugins...
- Finding rudderlabs/rudderstack versions matching "~> 4.3.1"...
- Installing rudderlabs/rudderstack v4.3.1...
- Installed rudderlabs/rudderstack v4.3.1

Terraform has been successfully initialized!

Verify Provider Installed

terraform providers

Should show `rudderlabs/rudderstack` in the list.

Step 4: Configure Authentication

Set Access Token

Get your access token from RudderStack dashboard: **Settings → Access Tokens**

export RUDDERSTACK_ACCESS_TOKEN="your-token-here"

For permanent setup, add to your shell profile (`~/.zshrc` or `~/.bashrc`):

echo 'export RUDDERSTACK_ACCESS_TOKEN="your-token-here"' >> ~/.zshrc
source ~/.zshrc

Verify Authentication

Create a minimal `main.tf` to test:

# main.tf - minimal test configuration
data "rudderstack_source" "test" {
  # This will fail if auth is wrong
}

Then run:

terraform plan

**If authenticated:** Shows "No changes" or data source info.

**If not authenticated:** Shows authentication error.

Credential Security

• **Never hardcode tokens** in `.tf` files
• Use environment variable `RUDDERSTACK_ACCESS_TOKEN`
• Add `.env` and `*.tfvars` containing secrets to `.gitignore`
• For CI/CD, use repository secrets or vault
• **Never commit `.tfstate`** without encryption (contains sensitive data)

Provider Configuration Options

provider "rudderstack" {
  # Token from env var (recommended)
  # access_token = var.rudderstack_token  # Alternative: use variable

  # Optional: Override API URL (default: https://api.rudderstack.com/v2)
  # api_url = "https://api.rudderstack.com/v2"
}

Troubleshooting

| Issue | Solution | |-------|----------| | `provider not found` | Run `terraform init` | | `unauthorized` | Check RUDDERSTACK_ACCESS_TOKEN is set correctly | | `version constraints` | Update version in required_providers block | | `init fails` | Check network; try with `-upgrade` flag |

Next Steps

After setup completes:

• Run `/rudder-environment-check` to verify full environment
• Use `/rudder-terraform-workflow` for plan/apply cycles