Working with Workspaces

1. Understanding Workspaces

Property	Description	Default
workspace.name	Name of the workspace	default
workspace.type	Type of workspace (local, remote)	local
workspace.backend	Backend configuration for the workspace	local

Example: Creating a new workspace

terraform workspace new production

Note: Workspaces allow you to manage multiple, isolated instances of your infrastructure within the same Terraform configuration.

Warning: Be cautious when switching between workspaces as they can have different states and configurations.

2. Listing Workspaces

Command	Description	Notes
terraform workspace list	List all workspaces in the current Terraform configuration	Shows the currently selected workspace with an asterisk (*)

Example: Listing Workspaces

terraform workspace list

Note: Workspaces are stored in the Terraform backend. The output will vary depending on the backend configuration (e.g., local, remote, etc.).

3. Creating Workspaces

Example: Creating a New Workspace

terraform workspace new production

Command	Description	Notes
terraform workspace new <name>	Creates a new workspace	Switches to the new workspace after creation
terraform workspace new -clone=<source> <name>	Creates a new workspace cloned from an existing one	Useful for copying configuration and state from another workspace

Note: Workspaces are stored in the Terraform backend. Ensure your backend supports workspace operations (e.g., local, S3, GCS).

4. Switching Workspaces

Command	Description	Example
terraform workspace list	List all workspaces	`terraform workspace list`
terraform workspace select <name>	Switch to a specific workspace	`terraform workspace select prod`
terraform workspace new <name>	Create and switch to a new workspace	`terraform workspace new staging`

Example: Switching to a workspace

terraform workspace select prod

Note: The default workspace is created automatically when initializing a Terraform configuration.

5. Deleting Workspaces

Command	Description	Notes
terraform workspace delete	Deletes a specified workspace	Cannot delete the current workspace. Must switch to another workspace first.

Example: Deleting a Workspace

# Switch to default workspace
terraform workspace select default

# Delete the test workspace
terraform workspace delete test

Note: Workspaces are stored in the Terraform backend. Ensure you have proper permissions to delete workspaces in your backend configuration.

6. Showing Current Workspace

Command	Description	Example
terraform workspace show	Displays the name of the currently active workspace	`terraform workspace show`

Note: The output of terraform workspace show is the name of the current workspace, which is used in state files and other operations.

7. Using Workspace in Configuration

Property	Description	Example
workspace.name	Name of the workspace to use	`"prod"`
workspace.path	Path to the workspace directory	`"./prod"`

Example: Using workspace in configuration

terraform {
  required_version = "~> 1.0"
}

provider &#34;aws&#34; {
  region = &#34;us-west-2&#34;
}

resource &#34;aws_instance&#34; &#34;web&#34; {
  ami           = &#34;ami-12345678&#34;
  instance_type = &#34;t2.micro&#34;
  tags = {
    Name = &#34;web-${terraform.workspace}&#34;
  }
}

Note: The terraform.workspace variable is automatically set by Terraform to the name of the current workspace.

8. Managing Workspace State

Command	Description	Notes
terraform workspace list	Lists all workspaces in the current Terraform configuration.	Shows the currently selected workspace with an asterisk (*).
terraform workspace select <name>	Selects an existing workspace by name.	Switches the active workspace to the specified one.
terraform workspace new <name>	Creates a new workspace with the given name.	Switches to the newly created workspace after creation.
terraform workspace delete <name>	Deletes the specified workspace.	Cannot delete the currently selected workspace.

Example: Creating and Switching Workspaces

terraform workspace new production
terraform workspace select development

Note: Workspace state files are stored in the backend configured for your Terraform configuration.

Warning: Never manually edit or delete state files in the backend, as this can lead to inconsistent or corrupted state.

9. Comparing Workspaces vs Modules

Feature	Workspaces	Modules
Purpose	Manage multiple instances of the same configuration	Reusability and organization of configuration code
Scope	Environment-level separation (dev, staging, prod)	Component-level reuse (e.g., VPC, EC2 instances)
State Management	Each workspace has its own state file	Modules do not manage state directly
Configuration	Same configuration, different variables per workspace	Different configurations, shared or isolated
Variable Handling	Variables can be overridden per workspace	Variables defined within module scope
Resource Isolation	Resources are isolated by workspace	Resources defined within module scope
Use Case	Environment-specific deployments	Reusable infrastructure components

Example: Workspace Variables

// workspace.tf
variable "environment" {
  description = "Environment name"
  type        = string
}

resource "aws_instance" "web" {
  ami           = "ami-12345678"
  instance_type = "t2.micro"
  tags = {
    Name        = "web-${var.environment}"
    Environment = var.environment
  }
}

Example: Module Usage

// main.tf
module "vpc" {
  source = "./modules/vpc"
  cidr_block = "10.0.0.0/16"
}

module "web_server" {
  source = "./modules/web-server"
  vpc_id = module.vpc.vpc_id
}

10. Implementing Workspace Naming Strategies

Example: Workspace Naming Convention

terraform workspace new prod-us-east-1
terraform workspace new staging-eu-west-2
terraform workspace new dev-ap-southeast-1

Strategy	Description	Example
Environment + Region	Separates workspaces by environment and cloud region	`prod-us-east-1`
Environment + Team	Groups workspaces by environment and team ownership	`prod-backend`
Environment + Application	Organizes workspaces by environment and application scope	`staging-api-server`

Note: Workspace names must be unique within a Terraform backend and cannot contain special characters like / or \.

Best Practices for Workspace Naming

Use consistent naming conventions across teams
Include environment (e.g., dev, staging, prod) to avoid confusion
Include region or team name for multi-account deployments
Avoid spaces and special characters in workspace names