Workspaces

Workspaces in FreeState help you organize and isolate your Terraform states across different projects, environments, and teams. Learn how to create, manage, and configure workspaces effectively.

What are Workspaces?

A workspace in FreeState is an isolated environment for your Terraform state files. Each workspace maintains its own state, configuration, and access controls, allowing you to:

Separate different environments (dev, staging, production)
Isolate different projects or applications
Manage team access and permissions
Track changes and audit history independently

Creating Workspaces

Via Dashboard

Log in to your FreeState dashboard
Click New Workspace
Enter workspace details:
- Name: Descriptive name (e.g., "my-app-production")
- Description: Optional description
- Environment: dev, staging, production, or custom
- Project: Group related workspaces
Configure access permissions
Click Create Workspace

Via API (Coming Soon)

curl -X POST https://api.freestate.cloud/v1/workspaces \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app-production",
    "description": "Production environment for my application",
    "environment": "production",
    "project": "my-app"
  }'

Workspace Configuration

Basic Settings

Setting	Description	Example
Name	Unique identifier for the workspace	my-app-prod, frontend-staging
Environment	Environment type	production, staging, development
Project	Project grouping	ecommerce, api, frontend
Tags	Custom labels for organization	team:platform, cost-center:engineering

Terraform Backend Configuration

Each workspace has a unique backend configuration:

terraform {
  backend "http" {
    address        = "https://api.freestate.cloud/terraform/state"
    username       = "your-workspace-id"  # Unique to each workspace
    password       = "your-api-key"
    lock_address   = "https://api.freestate.cloud/terraform/state/lock"
    lock_method    = "POST"
    unlock_address = "https://api.freestate.cloud/terraform/state/lock"
    unlock_method  = "DELETE"
  }
}

Workspace Organization Strategies

Environment-Based Organization

# Example workspace structure
my-company-app-dev
my-company-app-staging  
my-company-app-prod

# Or with prefixes
dev-my-app
staging-my-app
prod-my-app

Project-Based Organization

# Frontend project
frontend-dev
frontend-staging
frontend-prod

# API project
api-dev
api-staging
api-prod

# Infrastructure project
infra-shared
infra-monitoring

Team-Based Organization

# Platform team
platform-infrastructure
platform-monitoring
platform-security

# Product teams
payments-service-prod
user-service-prod
notification-service-prod

Access Control and Permissions

Workspace Roles

Role	Permissions	Use Case
Viewer	Read state, view configuration	Auditors, monitoring systems
Contributor	Read/write state, manage locks	Developers, CI/CD pipelines
Admin	Full workspace management	DevOps engineers, team leads

Team Management

Assign team members to workspaces with appropriate roles:

Go to workspace settings
Click Team tab
Add team members by email
Assign appropriate roles
Send invitations

Environment Variables

Workspace-Level Variables

Set environment variables at the workspace level for consistent configuration:

AWS_REGION: Default AWS region
ENVIRONMENT: Environment identifier
PROJECT_NAME: Project identifier
TERRAFORM_VERSION: Required Terraform version

Sensitive Variables

Store sensitive values securely:

API keys and tokens
Database passwords
SSL certificates
Third-party service credentials

🔐 Security Note

Sensitive variables are encrypted at rest and only accessible to authorized users and systems.

Workspace Monitoring

Activity Tracking

Monitor workspace activity through the dashboard:

State changes and modifications
Lock acquisition and release
User access and operations
API usage and patterns

Audit Logs

Comprehensive audit logs include:

Timestamp of operations
User or system performing actions
IP addresses and user agents
Before/after state checksums

Workspace Settings

Lock Configuration

# Default lock timeout
lock_timeout = "15m"

# Auto-unlock after timeout
auto_unlock = true

# Lock notifications
notify_on_lock = true

Backup Settings

Auto-backup: Automatic state backups before changes
Retention: How long to keep backup copies
Notifications: Alerts for backup failures

Integration Settings

Webhooks: HTTP callbacks for state changes
Notifications: Slack, email, or custom integrations
CI/CD: GitHub Actions, GitLab CI integrations

Multi-Environment Workflows

Promotion Pipeline

# Development environment
terraform workspace select dev
terraform apply

# Test and validate changes
terraform plan  # Should show no changes

# Promote to staging
terraform workspace select staging
terraform apply

# Production deployment (with approval)
terraform workspace select prod
terraform apply

Configuration Management

Use workspace-specific configurations:

# terraform/environments/dev/terraform.tfvars
environment = "dev"
instance_type = "t3.micro"
min_capacity = 1
max_capacity = 2

# terraform/environments/prod/terraform.tfvars
environment = "prod"
instance_type = "t3.large"
min_capacity = 3
max_capacity = 10