Workspaces

Manage multiple Terraform configurations within a single repository.

Overview

A workspace in Controlinfra represents a directory containing Terraform configuration files. A single GitHub repository can have multiple workspaces, allowing you to:

• Monitor different environments (production, staging, dev)
• Track separate infrastructure components (networking, compute, database)
• Use different AWS credentials per workspace
• Set independent scan schedules

Workspace Concepts

Repository vs Workspace

GitHub Repository: my-org/infrastructure
│
├── Workspace: /production
│   ├── main.tf
│   └── variables.tf
│
├── Workspace: /staging
│   ├── main.tf
│   └── variables.tf
│
└── Workspace: /networking
    ├── vpc.tf
    └── subnets.tf

• Repository: The GitHub repo connected to Controlinfra
• Workspace: A directory with Terraform files to scan

Common Workspace Patterns

By Environment

infrastructure/
├── production/       # Production workspace
├── staging/          # Staging workspace
└── development/      # Development workspace

By Component

infrastructure/
├── networking/       # VPC, subnets, routing
├── compute/          # EC2, ECS, Lambda
├── database/         # RDS, DynamoDB
└── security/         # IAM, security groups

By Region

infrastructure/
├── us-east-1/        # US East region
├── eu-west-1/        # EU West region
└── ap-southeast-1/   # Asia Pacific region

Monorepo with Services

services/
├── api/
│   └── terraform/    # API service infrastructure
├── web/
│   └── terraform/    # Web app infrastructure
└── worker/
    └── terraform/    # Background worker infrastructure

Adding Workspaces

Initial Setup

When adding a repository, specify the first workspace:

1. Click "Add Repository"
2. Select your GitHub repo
3. Set Working Directory (e.g., /production)
4. Configure AWS credentials
5. Click Save

Adding More Workspaces

1. Navigate to your repository
2. Click "Add Workspace"
3. Enter workspace path (e.g., /staging)
4. Configure workspace-specific settings
5. Click Save

Workspace Settings

Each workspace can have:

Setting	Description	Can Differ
Working Directory	Path to Terraform files	✅ Required
AWS Credentials	Access key and secret	✅ Yes
AWS Region	Default region	✅ Yes
Terraform Version	Version to use	✅ Yes
Backend Config	State backend settings	✅ Yes
Variables	Terraform variables	✅ Yes
Var Files	.tfvars file paths	✅ Yes
Scan Schedule	Automatic scan timing	✅ Yes

Workspace Configuration

Environment-Specific Settings

# Production Workspace
Path: /production
AWS Access Key: AKIAIOSFODNN7EXAMPLE
AWS Region: us-east-1
Backend:
  Bucket: terraform-state-prod
  Key: production/terraform.tfstate
Variables:
  environment: production
  instance_count: 5
Schedule: Daily at 6:00 AM

# Staging Workspace
Path: /staging
AWS Access Key: AKIASTAGING12345678
AWS Region: us-east-1
Backend:
  Bucket: terraform-state-staging
  Key: staging/terraform.tfstate
Variables:
  environment: staging
  instance_count: 2
Schedule: Weekly on Monday

Cross-Account Setup

For multi-account AWS setups:

# Production Account
Path: /production
AWS Access Key: [Production Account Key]
Backend:
  Bucket: prod-account-terraform-state

# Staging Account
Path: /staging
AWS Access Key: [Staging Account Key]
Backend:
  Bucket: staging-account-terraform-state

Terraform Workspaces Integration

If using Terraform's native workspaces:

# Same path, different Terraform workspaces
Path: /infrastructure
Terraform Workspace: production

Path: /infrastructure
Terraform Workspace: staging

Viewing Workspaces

Repository Dashboard

The repository page shows all workspaces:

my-org/infrastructure

├── production/
│   Status: ✅ Clean (Last scan: 2 hours ago)
│   Resources: 47
│
├── staging/
│   Status: ⚠️ 3 drifts (Last scan: 1 day ago)
│   Resources: 23
│
└── networking/
    Status: 🔄 Scanning...
    Resources: 12

Workspace Details

Click a workspace to see:

• Recent scans
• Current drift status
• Configuration
• Scan history

Scanning Workspaces

Scan Single Workspace

1. Navigate to the workspace
2. Click "Scan"
3. Wait for results

Scan All Workspaces

1. From the repository page
2. Click "Scan All"
3. All workspaces scan in parallel

Scan Results

Results are grouped by workspace:

Scan Results - my-org/infrastructure

production/ ✅ Clean
└── No drift detected

staging/ ⚠️ 3 drifts
├── aws_instance.api      - Medium
├── aws_security_group.db - High
└── aws_s3_bucket.logs    - Low

networking/ ✅ Clean
└── No drift detected

Managing Workspaces

Editing Workspace

1. Click workspace name
2. Click Settings (gear icon)
3. Update configuration
4. Click Save

Removing Workspace

1. Navigate to workspace settings
2. Click "Remove Workspace"
3. Confirm deletion

WARNING

Removing a workspace deletes its scan history. The Terraform files remain in GitHub.

Reorganizing Workspaces

If your repository structure changes:

1. Remove old workspace
2. Add new workspace with updated path
3. Run initial scan

Best Practices

1. Consistent Naming

Use clear, consistent workspace names:

✅ Good: /production, /staging, /development
✅ Good: /infrastructure/prod, /infrastructure/staging
❌ Bad: /prod, /stg, /infra

2. Match Your Repository Structure

Align workspaces with your actual Terraform layout:

# If your repo looks like this:
terraform/
├── environments/
│   ├── prod/
│   └── staging/
└── modules/

# Create workspaces:
/terraform/environments/prod
/terraform/environments/staging

3. Use Appropriate Scan Schedules

Environment	Recommended Schedule
Production	Daily or more frequent
Staging	Daily
Development	Weekly or on-demand
Networking	Daily (critical infra)

4. Separate Credentials

Use different AWS credentials per environment:

• Limits blast radius of credential compromise
• Enables environment-specific IAM policies
• Easier credential rotation

5. Document Workspace Purpose

Add descriptions to workspaces:

Name: production
Description: Production infrastructure including web servers,
             databases, and networking for customer-facing services.

Troubleshooting

Workspace Shows Wrong Path

• Verify the path matches your repository structure
• Check for typos in directory names
• Ensure Terraform files exist at that path

"No Terraform files found"

• Check the working directory path
• Verify .tf files exist in the directory
• Ensure files aren't in a subdirectory

Different Results Than Expected

• Check Terraform version matches your local setup
• Verify backend configuration is correct
• Ensure variables and var files are configured

Scan Fails for One Workspace

• Each workspace is independent
• Check workspace-specific configuration
• Verify AWS credentials for that workspace

Next Steps

• Connecting Repositories - Add more repos
• Scan Scheduling - Automate scans
• AWS Credentials - Per-workspace credentials