Rename "state environments" to "workspaces" #14952

apparentlymart · 2017-05-30T23:57:19Z

NOT TO BE MERGED UNTIL master IS TRACKING TOWARDS 0.10

After the "environments" feature was added in 0.9, we got lots of feedback that this terminology creates confusion due to it overlapping with several other non-equivalent concepts related to Terraform:

OS environment variables, like TF_LOG.
The word "environment" as used in the usage information for terraform init.
The idea of "environment" in Terraform Enterprise.

Furthermore, the word "environment" is often used in slightly- or wholly-inconsistent ways within organizations that use Terraform, creating further confusion as they try to map the feature onto their existing workflows.

In response, we've decided to rename this concept "workspace". This is honestly not that great a word either, but it has no existing conflicts within Terraform's concepts and we expect it will not be used in overlapping, conflicting ways within the vernacular of most organizations.

This PR deprecates many existing places that "env" or "environment" appear in the UX, replacing it with "workspace". The goal here is to support the old commands, variables and attributes from 0.10.0 until at least until 0.11.0, giving people time to switch over. (we will re-evaluate as we get closer to 0.11.0 whether it's feeling reasonable to remove support in that version.)

It leaves some aspects of the code with the old names, under the assumption that we can change these at our leisure without affecting backward compatibility. However, some obvious top-level names are changed, with the goal of reducing confusion for those who need to keep maintaining the code in the mean time.

This change includes @glasser's work from #14602, since this was the easiest way to also update that to use the environment variable TF_WORKSPACE without creating merge conflicts.

jbardin

backend.Operation still has a field named Environment too, as well as some environment related comments.

Otherwise, nice PR for such an extensive renaming!

jbardin · 2017-05-31T16:17:09Z

backend/local/backend.go

-	DefaultEnvDir          = "terraform.tfstate.d"
-	DefaultEnvFile         = "environment"
+	DefaultWorkspaceDir    = "terraform.tfstate.d"
+	DefaultWorkspaceFile   = "environment"


I know this is an internal detail, but should we migrate this file name too?

I was nervous about touching this right now because it would probably require some careful touches to make sure we don't inadvertently revert people back to default when they upgrade. I agree that we'd ideally change it, but my threshold for this initial change was either "easy and low-risk" or "in the UI", and this didn't pass either of those.

Of course, if you disagree with that as the goal then we can talk about that. 😀

I can agree with that ;) Just making sure it wasn't overlooked.

jbardin · 2017-05-31T16:21:17Z

backend/local/backend.go

-	StateBackupPath string
-	StateEnvDir     string
+	// StateWorkspaceDir is the path to the folder containing environments.
+	// This defaults to DefaultEnvDir if not set.


still a couple of env references in the comments here

jbardin · 2017-05-31T16:22:40Z

backend/local/backend.go

@@ -385,28 +401,9 @@ func (b *Local) createState(name string) error {

 // stateEnvDir returns the directory where state environments are stored.
 func (b *Local) stateEnvDir() string {


another env name and comment

apparentlymart · 2017-05-31T16:58:37Z

I updated the extra things you pointed out, @jbardin. I think we'll need to accept some things being missed in this first pass, since it's primarily intended as a UI change, but I'm happy you caught a few more easy cases!

cemo · 2017-06-01T20:34:01Z

@apparentlymart any idea about when master will be tracking 0.10? :)

apparentlymart · 2017-06-01T21:52:20Z

@cemo we don't have the release plan finalized yet, but my guess would be that we'd do at least one more 0.9 release beforehand, since we've got a reasonable backlog of things to release.

This allows you to run multiple concurrent terraform operations against different environments from the same source directory. Fixes #14447. Also removes some dead code which appears to do the same thing as the function I modified.

Feedback after 0.9 was that the term "environment" was confusing due to it colliding with several other concepts, such as OS environment variables, a non-aligned Terraform Enterprise concept, and differing ideas of "environment" within various organizations. This new term "workspace" is intended to ease some of that confusion. This term is not used anywhere else in Terraform today, and we expect it to not be used in a manner that would be confusing within user organizations. This begins a deprecation cycle for the "terraform env" family of commands, instead moving to an equivalent set of "terraform workspace" commands. There are some remaining references to the old "environment" concept in the code, which will be cleaned up in a separate change. This change is instead focused on text visible in the UI and wording within code comments for the benefit of human maintainers of the code.

As part of switching our terminology, we begin a deprecation cycle for "environment_dir" and advise users to switch to "workspace_dir" instead.

Previously we just silently ignored warnings from validating the backend config, but now that we have a deprecated argument it's important to print these out so users can respond to the deprecation warning.

As part of our terminology shift, the interpolation variable for the name of the current workspace changes to terraform.workspace. The old name continues to be supported for compatibility. We can't generate a deprecation warning from here so for now we'll just silently accept terraform.env as an alias, but not mention it at all in the error message in the hope that its use phases out over time before we actually remove it.

This replaces the previous documentation on "State Environments", as part of our intentional terminology shift.

We are moving away from using the term "environment" to describe separate named states for a single config, using "workspace" instead. The old attribute name remains supported for backward compatibility, but is marked as deprecated.

We're shifting terminology from "environment" to "workspace". This takes care of some of the main internal API surface that was using the old terminology, though is not intended to be entirely comprehensive and is mainly just to minimize the amount of confusion for maintainers as we continue moving towards eliminating the old terminology.

We are replacing this terminology. The old command continues to work for compatibility, but is deprecated. The docs should reflect the currently-recommended form.

This is part of an effort to switch this terminology across all of Terraform.

ghost · 2020-04-11T02:09:59Z

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.

apparentlymart requested a review from jbardin May 30, 2017 23:57

apparentlymart self-assigned this May 30, 2017

apparentlymart added core enhancement cli config labels May 30, 2017

apparentlymart force-pushed the 0.10-workspaces branch 2 times, most recently from f0ecccf to b00d6f4 Compare May 31, 2017 00:52

jbardin requested changes May 31, 2017

View reviewed changes

apparentlymart force-pushed the 0.10-workspaces branch from b00d6f4 to fb91140 Compare May 31, 2017 16:41

apparentlymart removed config core labels May 31, 2017

jbardin approved these changes May 31, 2017

View reviewed changes

apparentlymart mentioned this pull request Jun 7, 2017

Add workspace show command #15157

Merged

apparentlymart force-pushed the 0.10-workspaces branch from fb91140 to e87f784 Compare June 9, 2017 01:03

glasser and others added 7 commits June 9, 2017 15:01

core: allow overriding environment name via env var

c25d848

This allows you to run multiple concurrent terraform operations against different environments from the same source directory. Fixes #14447. Also removes some dead code which appears to do the same thing as the function I modified.

backend/local: "environment_dir" renamed to "workspace_dir"

5026e1d

As part of switching our terminology, we begin a deprecation cycle for "environment_dir" and advise users to switch to "workspace_dir" instead.

command: show warnings from backend config validation

5f9f13a

Previously we just silently ignored warnings from validating the backend config, but now that we have a deprecated argument it's important to print these out so users can respond to the deprecation warning.

website: documentation for state workspaces

3be1d31

This replaces the previous documentation on "State Environments", as part of our intentional terminology shift.

apparentlymart force-pushed the 0.10-workspaces branch from e87f784 to 7821668 Compare June 9, 2017 22:02

apparentlymart added 3 commits June 9, 2017 16:26

website: replace "env" command docs with "workspace" command docs

5a57962

We are replacing this terminology. The old command continues to work for compatibility, but is deprecated. The docs should reflect the currently-recommended form.

backend: Operation.Environment renamed to "Workspace"

f7ce6a1

This is part of an effort to switch this terminology across all of Terraform.

apparentlymart force-pushed the 0.10-workspaces branch from 7821668 to f7ce6a1 Compare June 9, 2017 23:26

apparentlymart merged commit 698c22c into master Jun 9, 2017

stack72 deleted the 0.10-workspaces branch June 13, 2017 13:38

glasser mentioned this pull request Jun 15, 2017

core: allow overriding environment name via env var #14602

Closed

erikvanbrakel mentioned this pull request Jun 23, 2017

add support for env command cake-contrib/Cake.Terraform#26

Closed

2rs2ts mentioned this pull request Nov 11, 2017

Support separate backend configurations for each workspace #16627

Open

ghost locked and limited conversation to collaborators Apr 11, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rename "state environments" to "workspaces" #14952

Rename "state environments" to "workspaces" #14952

apparentlymart commented May 30, 2017

jbardin left a comment

jbardin May 31, 2017

apparentlymart May 31, 2017

jbardin May 31, 2017

jbardin May 31, 2017

jbardin May 31, 2017

apparentlymart commented May 31, 2017

cemo commented Jun 1, 2017 •

edited

Loading

apparentlymart commented Jun 1, 2017

ghost commented Apr 11, 2020

		@@ -385,28 +401,9 @@ func (b *Local) createState(name string) error {

		// stateEnvDir returns the directory where state environments are stored.
		func (b *Local) stateEnvDir() string {

Rename "state environments" to "workspaces" #14952

Rename "state environments" to "workspaces" #14952

Conversation

apparentlymart commented May 30, 2017

jbardin left a comment

Choose a reason for hiding this comment

jbardin May 31, 2017

Choose a reason for hiding this comment

apparentlymart May 31, 2017

Choose a reason for hiding this comment

jbardin May 31, 2017

Choose a reason for hiding this comment

jbardin May 31, 2017

Choose a reason for hiding this comment

jbardin May 31, 2017

Choose a reason for hiding this comment

apparentlymart commented May 31, 2017

cemo commented Jun 1, 2017 • edited Loading

apparentlymart commented Jun 1, 2017

ghost commented Apr 11, 2020

cemo commented Jun 1, 2017 •

edited

Loading