Docs tweaks for tfe_workspace_settings and friends

Updating several things I found unclear as a user, plus one thing I found
unclear as a fellow maintainer.

Also, an important adjustment to some messaging: `r/tfe_workspace_settings`
_cannot_ safely be used as a data source, because it interprets absence of each
optional argument to explicitly set the workspace's corresponding overwrite to
false. This makes me believe we need an overwrites object attribute added to
`d/workspace`, but this PR defers that for later.

Author: nfagerlund

internal/provider/resource_tfe_workspace.go

@@ -598,6 +598,12 @@ func resourceTFEWorkspaceUpdate(d *schema.ResourceData, meta interface{}) error
 			}
 		}
 
+		// NOTE: since agent_pool_id and execution_mode are both deprecated on
+		// tfe_workspace and we want tfe_workspace_settings to be authoritative,
+		// we must not set the overwrites values to false in the checks below.
+		// (Actually, I think we don't need to set them to true here either,
+		// since the API understands an explicit value in an update request to
+		// also result in an implicit overwrite = true.)
 		if d.HasChange("agent_pool_id") {
 			// Need the raw configuration value of the agent_pool_id because when the workspace's execution mode is set
 			// to default, we can't know for certain what the default value of the agent pool will be. This means we can

website/docs/d/workspace.html.markdown

@@ -60,7 +60,7 @@ In addition to all arguments above, the following attributes are exported:
 * `trigger_patterns` - List of [glob patterns](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/vcs#glob-patterns-for-automatic-run-triggering) that describe the files Terraform Cloud monitors for changes. Trigger patterns are always appended to the root directory of the repository.
 * `vcs_repo` - Settings for the workspace's VCS repository.
 * `working_directory` - A relative path that Terraform will execute within.
-* `execution_mode` - **Deprecated** Indicates the [execution mode](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#execution-mode) of the workspace. Use the `tfe_workspace_settings` resource instead.
+* `execution_mode` - Indicates the [execution mode](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#execution-mode) of the workspace. **Note:** This value might be derived from an organization-level default or set on the workspace itself; see the [`tfe_workspace_settings` resource](tfe_workspace_settings) for details.
 * `html_url` - The URL to the browsable HTML overview of the workspace
 
 

website/docs/r/organization_default_settings.html.markdown

@@ -7,7 +7,7 @@ description: |-
 
 # tfe_organization_default_settings
 
-Primarily, this is used to set the default execution mode of an organization. This setting will be used as the default for all workspaces in the organization.
+Primarily, this is used to set the default execution mode of an organization. Settings configured here will be used as the default for all workspaces in the organization, unless they specify their own values with a [`tfe_workspace_settings` resource](workspace_settings.html) (or deprecated attributes on the workspace resource).
 
 ## Example Usage
 
@@ -32,7 +32,9 @@ resource "tfe_organization_default_settings" "org_default" {
 
 resource "tfe_workspace" "my_workspace" {
   name       = "my-workspace"
-  # Ensures this workspace will inherit the org defaults
+  # This workspace will use the org defaults, and will report those defaults as
+  # the values of its corresponding attributes. Use depends_on to get accurate
+  # values immediately, and to ensure reliable behavior of tfe_workspace_run.
   depends_on = [tfe_organization_default_settings.org_default]
 }
 ```

website/docs/r/workspace.html.markdown

@@ -9,7 +9,7 @@ description: |-
 
 Provides a workspace resource.
 
-~> **NOTE:** Setting the execution mode and agent pool affinity directly on the workspace has been deprecated in favor of using both [tfe_workspace_settings](workspace_settings) and [tfe_organization_default_settings](organization_default_settings). Use caution when unsetting `execution_mode` because the default value `"remote"` is no longer applied when the `execution_mode` is unset.
+~> **NOTE:** Setting the execution mode and agent pool affinity directly on the workspace is deprecated in favor of using both [tfe_workspace_settings](workspace_settings) and [tfe_organization_default_settings](organization_default_settings), since they allow more precise control and fully support [agent_pool_allowed_workspaces](agent_pool_allowed_workspaces). Use caution when unsetting `execution_mode`, as it now leaves any prior value unmanaged instead of reverting to the old default value of `"remote"`.
 
 ~> **NOTE:** Using `global_remote_state` or `remote_state_consumer_ids` requires using the provider with Terraform Cloud or an instance of Terraform Enterprise at least as recent as v202104-1.
 

website/docs/r/workspace_settings.markdown

@@ -7,7 +7,7 @@ description: |-
 
 # tfe_workspace_settings
 
-Manages or reads execution mode and agent pool settings for a workspace. If [tfe_organization_default_settings](organization_default_settings.html) are used, those settings may be read using a combination of the read-only `overwrites` argument and the setting itself.
+Manages or reads execution mode and agent pool settings for a workspace. This also interacts with the organization's default values for several settings, which can be managed with [tfe_organization_default_settings](organization_default_settings.html). If other resources need to identify whether a setting is a default or an explicit value set for the workspace, you can refer to the read-only `overwrites` argument.
 
 ## Example Usage
 
@@ -88,7 +88,7 @@ The following arguments are supported:
 * `agent_pool_id` - (Optional) The ID of an agent pool to assign to the workspace. Requires `execution_mode`
   to be set to `agent`. This value _must not_ be provided if `execution_mode` is set to any other value.
 * `execution_mode` - (Optional) Which [execution mode](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings#execution-mode)
-  to use. Using Terraform Cloud, valid values are `remote`, `local` or `agent`. Defaults  your organization's default execution mode, or `remote` if no organization default is set. Using Terraform Enterprise, only `remote` and `local` execution modes are valid.  When set to `local`, the workspace will be used for state storage only.
+  to use. Using Terraform Cloud, valid values are `remote`, `local` or `agent`. Using Terraform Enterprise, only `remote` and `local` execution modes are valid. When set to `local`, the workspace will be used for state storage only. **Important:** If you omit this attribute, the resource configures the workspace to use your organization's default execution mode (which in turn defaults to `remote`), removing any explicit value that might have previously been set for the workspace.
 
 ## Attributes Reference