provider/terraform: "workspace" argument instead of "environment"

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.

builtin/providers/terraform/data_source_state.go

@@ -40,6 +40,14 @@ func dataSourceRemoteState() *schema.Resource {
 			"environment": {
 				Type:     schema.TypeString,
 				Optional: true,
+
+				ConflictsWith: []string{"workspace"},
+				Deprecated:    "use the \"workspace\" argument instead, with the same value",
+			},
+
+			"workspace": {
+				Type:     schema.TypeString,
+				Optional: true,
 				Default:  backend.DefaultStateName,
 			},
 
@@ -80,8 +88,12 @@ func dataSourceRemoteStateRead(d *schema.ResourceData, meta interface{}) error {
 	}
 
 	// Get the state
-	env := d.Get("environment").(string)
-	state, err := b.State(env)
+	workspace := d.Get("environment").(string)
+	if workspace == "" {
+		// This is actually the main path, since "environment" is deprecated.
+		workspace = d.Get("workspace").(string)
+	}
+	state, err := b.State(workspace)
 	if err != nil {
 		return fmt.Errorf("error loading the remote state: %s", err)
 	}

builtin/providers/terraform/data_source_state_test.go

@@ -63,6 +63,38 @@ func TestState_complexOutputs(t *testing.T) {
 	})
 }
 
+func TestState_workspace(t *testing.T) {
+	resource.UnitTest(t, resource.TestCase{
+		PreCheck:  func() { testAccPreCheck(t) },
+		Providers: testAccProviders,
+		Steps: []resource.TestStep{
+			{
+				Config: testAccState_workspace,
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckStateValue(
+						"data.terraform_remote_state.foo", "foo", "bar"),
+				),
+			},
+		},
+	})
+}
+
+func TestState_legacyEnvironment(t *testing.T) {
+	resource.UnitTest(t, resource.TestCase{
+		PreCheck:  func() { testAccPreCheck(t) },
+		Providers: testAccProviders,
+		Steps: []resource.TestStep{
+			{
+				Config: testAccState_legacyEnvironment,
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckStateValue(
+						"data.terraform_remote_state.foo", "foo", "bar"),
+				),
+			},
+		},
+	})
+}
+
 func testAccCheckStateValue(id, name, value string) resource.TestCheckFunc {
 	return func(s *terraform.State) error {
 		rs, ok := s.RootModule().Resources[id]
@@ -109,3 +141,23 @@ resource "terraform_remote_state" "foo" {
 		path = "./test-fixtures/complex_outputs.tfstate"
 	}
 }`
+
+const testAccState_workspace = `
+data "terraform_remote_state" "foo" {
+	backend   = "local"
+	workspace = "test"
+
+	config {
+		workspace_dir = "./test-fixtures/workspaces"
+	}
+}`
+
+const testAccState_legacyEnvironment = `
+data "terraform_remote_state" "foo" {
+	backend     = "local"
+	environment = "test" # old, deprecated name for "workspace"
+
+	config {
+		workspace_dir = "./test-fixtures/workspaces"
+	}
+}`

builtin/providers/terraform/test-fixtures/workspaces/test/terraform.tfstate

@@ -0,0 +1,7 @@
+{
+    "version": 1,
+    "modules": [{
+        "path": ["root"],
+        "outputs": { "foo": "bar" }
+    }]
+}

website/source/docs/providers/terraform/d/remote_state.html.md

@@ -31,9 +31,9 @@ resource "aws_instance" "foo" {
 The following arguments are supported:
 
 * `backend` - (Required) The remote backend to use.
-* `environment` - (Optional) The Terraform environment to use.
-* `config` - (Optional) The configuration of the remote backend.
- * Remote state config docs can be found [here](/docs/backends/types/terraform-enterprise.html)
+* `workspace` - (Optional) The Terraform workspace whose state will be requested. Defaults to "default".
+* `config` - (Optional) The configuration of the remote backend. For more information,
+  see [the Backend Types documentation](/docs/backends/types/).
 
 ## Attributes Reference