Learn How to manage Terraform Workspace and configure Multi-Environment Deployment.

💡 Introduction

Welcome to the world of Cloud and Automation, Devs!

Today, we’re going to explore one of the most powerful and widely used Infrastructure-as-Code (IaC) tools — Terraform. In this guide, we’ll learn how to use Terraform workspaces to manage multiple environments seamlessly — from Development to Staging and finally Production.

By the end of this blog, you’ll not only understand how Terraform organizes infrastructure across environments but also see it in action through a hands-on demonstration — deploying a static website on Amazon S3 with three isolated environments.

So, without further ado, let’s dive in and uncover how Terraform simplifies multi-environment deployments in the cloud.

---

💡 Prerequisites

Before we jump into the implementation, let’s make sure your setup is ready. You’ll need the following tools installed and configured on your system:

AWS CLI – Installed and configured with an IAM user that has full access to Amazon S3. If you don’t know how to do that, Follow these steps 1-3 from my Terraform Starter blog. (Just change the Permissions from EC2 to S3FullAccess)

Terraform CLI – Installed and ready to execute Terraform commands.

Once these are in place, you’ll have everything you need to follow along with the tutorial and deploy your multi-environment infrastructure.

---

💡 What is Terraform Workspace?

When managing infrastructure with Terraform, it’s common to work with multiple environments such as Development, Staging, and Production. Each of these environments often requires its own set of resources and configurations. To keep things organized and maintain a clean infrastructure codebase, Terraform provides a powerful feature called Workspaces.

A Terraform Workspace allows you to create and manage separate environments within a single Terraform configuration. Each workspace is associated with its own state file, which means the resources for one environment are isolated from another, even though they share the same configuration files. This makes it much easier to manage multiple deployments — all from a single codebase.

When you initialize Terraform for the first time, a default workspace named “default” is automatically created. Any infrastructure you create without explicitly switching workspaces will live in this default environment. You can then create new workspaces for different environments as needed.

Here are the available Terraform workspace commands:

terraform workspace --help

Usage: terraform [global options] workspace
new, list, show, select and delete Terraform workspaces.

Subcommands:
delete    Delete a workspace
list      List workspaces
new       Create a new workspace
select    Select a workspace
show      Show the name of the current workspace

Each workspace must have a unique name. When you switch between them, Terraform automatically updates the state file to match the selected workspace — ensuring your deployments remain consistent and isolated per environment.

---

💡 Pros and Cons of Using Terraform Workspaces

Before deciding to use Terraform Workspaces for managing your environments, it’s important to understand both their advantages and limitations. While they provide a convenient way to organize infrastructure, they may not always be the best fit for every use case — especially in large-scale or complex deployments.

✅ Pros

Single Configuration for Multiple Environments

You can manage multiple environments — like Dev, Stage, and Prod — using a single Terraform configuration. This reduces code duplication and keeps your setup clean and maintainable.

Easy Environment Switching

Workspaces come with a simple built-in command to switch between environments:

terraform workspace select <name>

This makes moving between environments effortless and consistent.

Simplifies Non-Production Environment Creation

You can easily spin up non-production environments such as Development, QA, Beta, or UAT that mirror your production setup — often as smaller, scaled-down versions.

Resource and Variable Isolation

Each workspace maintains its own state file and can have environment-specific variables, reducing the chance of misconfigurations or accidental resource overlap.

Ideal for Small to Medium Projects

For small teams or projects where environments share similar configurations, workspaces provide just the right balance of simplicity and control.

⚠️ Cons

Added Complexity for Large-Scale Infrastructure

As projects grow, managing multiple environments and configurations through workspaces can become cumbersome and harder to maintain.

Not Fully Isolated

While each workspace has its own state file, they still share the same backend configuration. Without proper management, this can lead to state conflicts or accidental cross-environment changes.

Limited for Advanced Use Cases

Workspaces aren’t ideal for multi-provider setups or situations where resources need to be shared across environments. In those cases, using separate directories or repositories for each environment is often a better approach.

---

💡 Practical Demonstration

Now that we’ve covered the theory, it’s time to get our hands dirty with a real-world example.

The project we’ll be working on demonstrates how to use Terraform Workspaces to deploy a static website on AWS S3for multiple environments — Dev, Stage, and Prod.

Navigate to the terraform-workspace-s3 directory, and you’ll see the following files and folders:

provider.tf – Defines AWS as the cloud provider and specifies the region (us-east-1).

output.tf – Prints the website URL once deployment is complete. The output changes based on the environment.

main.tf – The core of the project. It:

• Creates an S3 bucket named pravesh-{env}-terraform-workspace-site.
• Configures it as a static website.
• Uploads two HTML objects: index.html and error.html.
• Includes configurations for ownership controls, public access, and bucket policies.

index/ – Contains three subdirectories: dev, stage, and prod.

Each folder has its own index.html file with environment-specific content.

create.sh – A shell script that automates workspace creation and resource deployment.

delete.sh – A cleanup script that destroys all created resources to prevent unnecessary AWS charges.

Inside the main.tf, we’ve set locals.env equal to the current workspace name. This dynamic link ensures Terraform automatically detects the environment (Dev, Stage, or Prod) and applies the corresponding configuration.

Once you’ve cloned the repository locally, open your terminal and run the following commands:

cd terra-projects/terraform-workspace-s3
chmod u+x create.sh
./create.sh

This script will:

Create all the required Terraform workspaces. 1.

Apply the configuration and deploy the static website for each environment.

If you prefer, you can also run the Terraform commands manually instead of using the script.

(I ran it manually while testing, Here are some Screenshots)

After the deployment completes successfully, Terraform will output a website URL for each environment.

Open the URL in your browser — and you’ll see your static website live, hosted directly from your S3 bucket!

When you’re done testing, make sure to delete the resources to avoid unwanted charges.

You can do this easily by running the cleanup script:

cd terra-projects/terraform-workspace-s3
chmod u+x delete.sh
./delete.sh

This will remove all S3 buckets, associated objects, and delete the Terraform workspaces you created.

---

🧩 Conclusion

As we wrap up this project, we’ve seen how Terraform Workspaces simplify managing multiple environments like Dev, Stage, and Prod — all from a single configuration.

Instead of maintaining separate folders or repos, workspaces help isolate state files while keeping the infrastructure code consistent and scalable.

We also explored how to host a static website on AWS S3 using Terraform, learned about configuring ownership, access policies, and automating deployment across environments.

While Workspaces are great for small to medium-sized projects, they do have some limitations for larger infrastructure setups. Still, they’re a great way to get started with multi-environment IaC and understand how Terraform handles isolation through state management.

If you’ve followed along till the end, congratulations — you’ve just taken a big step toward mastering Infrastructure as Code with Terraform!

🌐 Connect with Me

If you enjoyed this guide, share it with your DevOps buddies and stay tuned for more such projects!

You can also find me sharing tech content, tutorials, and behind-the-scenes DevOps experiments here 👇

💼 LinkedIn: linkedin.com/in/pravesh-sudha

🐦 Twitter/X: x.com/praveshstwt

📹 YouTube: youtube.com/@pravesh-sudha

🌐 Website: blog.praveshsudha.com