{"id":7580,"date":"2026-05-03T08:55:45","date_gmt":"2026-05-03T08:55:45","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=7580"},"modified":"2026-05-03T08:55:47","modified_gmt":"2026-05-03T08:55:47","slug":"terraform-workspace-explained","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/terraform-workspace-explained\/","title":{"rendered":"Terraform workspace explained!!!"},"content":{"rendered":"\n

What is Terraform workspace?<\/strong><\/p>\n\n\n\n

Have you worked with terraform workflow? such as terraform init\/plan\/apply\/destroy with terraform configuration file? If Yes, you already have worked with Terraform workspace. YES. Thats a default workspace which you always been working with.<\/p>\n\n\n\n

It allows you to create different and independent states on the same configuration. And as it\u2019s compatible with remote backend this workspaces are shared with your team.<\/p>\n\n\n\n

Each Terraform configuration has an associated backend that defines how operations are executed and where persistent data such as the Terraform state are stored.<\/p>\n\n\n\n

The persistent data stored in the backend belongs to a workspace. Initially the backend has only one workspace, called “default”, and thus there is only one Terraform state associated with that configuration.<\/p>\n\n\n\n

Certain backends support multiple named workspaces, allowing multiple states to be associated with a single configuration. <\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n
\"\"\/<\/figure>\n\n\n\n

Terraform Workspace \u2014 10 Basic but Real Use Cases<\/strong><\/p>\n\n\n\n

    \n
  1. Separate environments (dev, stage, prod) using same code<\/strong>
    Use one Terraform codebase and create workspaces like dev<\/code>, stage<\/code>, prod<\/code> to deploy identical infrastructure with different sizes, tags, or configs.<\/li>\n\n\n\n
  2. Testing infrastructure changes safely before production<\/strong>
    Apply new Terraform changes in a test<\/code> workspace first to validate behavior without impacting production resources.<\/li>\n\n\n\n
  3. Deploying same application for multiple customers (multi-tenant setup)<\/strong>
    Create workspaces like customer-a<\/code>, customer-b<\/code>, each provisioning isolated infrastructure using shared modules.<\/li>\n\n\n\n
  4. Managing region-specific deployments<\/strong>
    Use workspaces like us-east<\/code>, eu-west<\/code>, asia-south<\/code> to deploy the same infrastructure in multiple regions.<\/li>\n\n\n\n
  5. Running feature branch infrastructure testing<\/strong>
    Developers create temporary workspaces like feature-login<\/code> to test infrastructure related to a feature before merging code.<\/li>\n\n\n\n
  6. Isolating developer sandbox environments<\/strong>
    Each developer uses a workspace such as dev-rajesh<\/code>, dev-amit<\/code> to safely test infrastructure changes without affecting others.<\/li>\n\n\n\n
  7. Maintaining separate state files for the same infrastructure pattern<\/strong>
    Each workspace automatically maintains its own Terraform state file, avoiding conflicts between deployments.<\/li>\n\n\n\n
  8. Blue-Green deployment environments<\/strong>
    Create workspaces like blue<\/code> and green<\/code> to deploy parallel environments and switch traffic during release.<\/li>\n\n\n\n
  9. Running infrastructure performance or load testing environments<\/strong>
    Use a loadtest<\/code> workspace to spin up temporary large-scale infrastructure for performance testing.<\/li>\n\n\n\n
  10. Temporary infrastructure for training, demos, or labs<\/strong>
    Create workspaces like training<\/code> or demo<\/code> to provision short-lived infrastructure without affecting production state.<\/li>\n<\/ol>\n\n\n\n

    Multiple workspaces are currently supported by the following backends:<\/strong><\/p>\n\n\n\n

      \n
    • AzureRM<\/li>\n\n\n\n
    • Consul<\/li>\n\n\n\n
    • GCS<\/li>\n\n\n\n
    • Local<\/li>\n\n\n\n
    • Manta<\/li>\n\n\n\n
    • Postgres<\/li>\n\n\n\n
    • Remote<\/li>\n\n\n\n
    • S3<\/li>\n<\/ul>\n\n\n\n

      In the 0.9 line of Terraform releases, this concept was known as “environment”. It was renamed in 0.10 based on feedback to workspace.<\/p>\n\n\n\n

      Terraform starts with a single workspace named “default”. This workspace is special both because it is the default and also because it cannot ever be deleted. If you’ve never explicitly used workspaces, then you’ve only ever worked on the “default” workspace<\/p>\n\n\n\n

      There are a couple of advantages to using Workspaces:<\/strong><\/p>\n\n\n\n

        \n
      • They are defined by Hashicorp, so it’s possible that improved features could be developed in the future<\/li>\n\n\n\n
      • They reduce the usage of code<\/li>\n<\/ul>\n\n\n\n

        However, Workspaces also present a couple of challenges:<\/strong><\/p>\n\n\n\n

          \n
        • They are still an early implementation<\/li>\n\n\n\n
        • They are not yet supported by all backends<\/li>\n\n\n\n
        • It is not clear at the time of deployment (terraform apply) which workspace will be used (terraform workspace show)<\/li>\n<\/ul>\n\n\n\n

          Working with Terraform workspace?<\/strong><\/p>\n\n\n

          \n$ terraform -help workspace\nUsage: terraform workspace\n\n  New<\/span>, list<\/span>, show, select and<\/span> delete Terraform workspaces.\n\nSubcommands:\n    delete    Delete a workspace\n    list<\/span>      List<\/span> Workspaces\n    new<\/span>       Create a new<\/span> workspace\n    select    Select a workspace\n    show      Show the name of the current workspace<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
          Demo Code – <\/strong>https:\/\/github.com\/devopsschool-sample-projects\/terraform\/tree\/master\/demo.3<\/p>\n\n\n\n
          So lets create a new dev workspace by running terraform workspace new dev and then run terraform apply. As we can see below instead of creating a terraform.tfstate file in the working folder Terraform created a new folder called terraform.tfstate.d\/dev<\/strong> and places the state file within that.<\/p>\n\n\n
          \n\u251c\u2500\u2500 deploy_website<\/span>.sh<\/span>\n\u251c\u2500\u2500 instance<\/span>.tf<\/span>\n\u251c\u2500\u2500 provider<\/span>.tf<\/span>\n\u251c\u2500\u2500 terraform<\/span>.tfstate<\/span>.d<\/span>\n\u2502   \u2514\u2500\u2500 dev<\/span>\n\u2502       \u2514\u2500\u2500 terraform<\/span>.tfstate<\/span>\n\u251c\u2500\u2500 terraform<\/span>.tfvars<\/span>\n\u2514\u2500\u2500 vars<\/span>.tf<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
          Ok so our webserver is now up and we are happy with the results, lets create and switch to a prod workspace. So we run terraform workspace new prod. This automatically places us in the prod workspace.<\/p>\n\n\n
          \n$ terraform workspace list<\/span>\ndefault<\/span>\ndev\n* prod<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
          Now lets run terraform apply again. Note if we were not using a different workspace Terraform would say no changes were needed as the remote and local state would match.<\/p>\n\n\n
          \n\u251c\u2500\u2500 deploy_website<\/span>.sh<\/span>\n\u251c\u2500\u2500 instance<\/span>.tf<\/span>\n\u251c\u2500\u2500 provider<\/span>.tf<\/span>\n\u251c\u2500\u2500 terraform<\/span>.tfstate<\/span>.d<\/span>\n\u2502   \u251c\u2500\u2500 dev<\/span>\n\u2502   \u2502   \u2514\u2500\u2500 terraform<\/span>.tfstate<\/span>\n\u2502   \u2514\u2500\u2500 prod<\/span>\n\u2502       \u2514\u2500\u2500 terraform<\/span>.tfstate<\/span>\n\u251c\u2500\u2500 terraform<\/span>.tfvars<\/span>\n\u2514\u2500\u2500 vars<\/span>.tf<\/span><\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
          And now we have a prod folder with a new state file. So as we can see above we can use Terraform workspaces to manage differences between development, staging, and production.<\/p>\n\n\n\n
          You can also backup the remote state of each workspace to S3<\/strong><\/p>\n\n\n\n
          \"\"<\/figure>\n\n\n
          \nbackend.tf:\n\n# Backend configuration is loaded early so we can't use variables<\/span>\nterraform {\n  backend \"s3\"<\/span> {\n    region = \"eu-central-1\"<\/span>\n    bucket = \"devopsschool.com\"<\/span>\n    key = \"state.tfstate\"<\/span>\n    encrypt = true<\/span>    #AES-256 encryption<\/span>\n  }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
          Create workspaces:<\/strong><\/p>\n\n\n
          \n$ terraform workspace new<\/span> dev\nCreated and switched to workspace 'dev'<\/span>\n$ terraform workspace new<\/span> preprod\nCreated and switched to workspace 'preprod'<\/span>\n$ terraform workspace new<\/span> prod\nCreated and switched to workspace 'prod'<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          Select the dev workspace:<\/strong><\/p>\n\n\n
          \n$ terraform workspace select dev\n<\/code><\/span><\/pre>\n\n\n
          List workspaces:<\/strong><\/p>\n\n\n
          \n$ terraform workspace list<\/span>\ndefault<\/span>\n* dev\npreprod\nprod\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
          With this workspace configuration, when a  terraform apply  is successfully executed, your tfstate will be now stored in the good environment folder in the s3 bucket:<\/p>\n\n\n
          \ndevopsschool.com\nenv:\/\n    dev\/\n       state.tfstate    \n    preprod\/\n        state.tfstate    \n    prod\/\n        state.tfstate<\/code><\/span><\/pre>\n\n\n
          Terraform Workspace Lab Workflow: Dev, QA, Prod<\/h2>\n\n\n\n
          1. Check workspace help<\/h3>\n\n\n
          terraform workspace\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          2. Initialize Terraform project<\/h3>\n\n\n
          terraform init\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          3. Show current workspace<\/h3>\n\n\n
          terraform workspace show\n<\/code><\/span><\/pre>\n\n\n
          Expected:<\/p>\n\n\n
          default<\/span>\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          4. List available workspaces<\/h3>\n\n\n
          terraform workspace list<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
          Expected:<\/p>\n\n\n
          * default<\/span>\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          5. Create dev<\/code> workspace<\/h3>\n\n\n
          terraform workspace new<\/span> dev\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          6. Create qa<\/code> workspace<\/h3>\n\n\n
          terraform workspace new<\/span> qa\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          7. Create prod<\/code> workspace<\/h3>\n\n\n
          terraform workspace new<\/span> prod\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          8. List all workspaces<\/h3>\n\n\n
          terraform workspace list<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
          Expected:<\/p>\n\n\n
            default<\/span>\n  dev\n  qa\n* prod\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          9. Select dev<\/code> workspace<\/h3>\n\n\n
          terraform workspace select dev\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          10. Confirm current workspace<\/h3>\n\n\n
          terraform workspace show\n<\/code><\/span><\/pre>\n\n\n
          Expected:<\/p>\n\n\n
          dev\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          11. Run Terraform for Dev<\/h3>\n\n\n
          terraform plan\nterraform apply\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          12. Select qa<\/code> workspace<\/h3>\n\n\n
          terraform workspace select qa\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          13. Run Terraform for QA<\/h3>\n\n\n
          terraform plan\nterraform apply\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          14. Select prod<\/code> workspace<\/h3>\n\n\n
          terraform workspace select prod\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          15. Run Terraform for Prod<\/h3>\n\n\n
          terraform plan\nterraform apply\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          16. Switch back to Dev<\/h3>\n\n\n
          terraform workspace select dev\n<\/code><\/span><\/pre>\n\n\n
          \n\n\n\n
          17. Delete QA workspace demo cleanup<\/h3>\n\n\n\n
          First select another workspace:<\/p>\n\n\n
          terraform workspace select default<\/span>\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          Then delete QA:<\/p>\n\n\n
          terraform workspace delete<\/span> qa\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
          \n\n\n\n
          18. Final list<\/h3>\n\n\n
          terraform workspace list<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
          Expected:<\/p>\n\n\n
          * default<\/span>\n  dev\n  prod\n<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n