nia/docs 0.4.2 (#11611)

* nia/docs: Add TLS options for the CTS API

* docs: Add workspace tags (#11564)

* nia/docs: Change CLI options to table format

Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: Michael Wilkerson <62034708+wilkermichael@users.noreply.github.com>

* nia/docs: Update TLS CLI defaults

Also clarifies some behavior for the CLI options.

Co-authored-by: Melissa Kam <mkam@hashicorp.com>
Co-authored-by: Kim Ngo <6362111+findkim@users.noreply.github.com>
Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com>
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
Co-authored-by: Michael Wilkerson <62034708+wilkermichael@users.noreply.github.com>

website/content/docs/nia/cli/index.mdx

@@ -82,4 +82,12 @@ consul-terraform-sync task disable -port=2000 task_a
 
 Below are options that can be used across all commands:
 
-- `-port=<port>` - (int: 8558) The port that the Consul-Terraform-Sync daemon serves its API.
+| Option         | Description                                                                                                                                                                                                                                                                                             | Required | Default            |
+|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------|
+| `-port`        | Integer value that specifies the port from which the Consul-Terraform-Sync daemon serves its API.<br/>The value is prepended with `http://localhost:`, but you can specify a different scheme or address with the `-http-addr` if necessary.                                                            | Optional | `8558`             |
+| `-http-addr`   | String value that specifies the address and port of the Consul-Terraform-Sync API. You can specify an IP or DNS address.<br/><br/> Alternatively, you can specify a value using the `CTS_HTTP_ADDR` environment variable.                                                                               | Optional | `http://localhost:8558` |
+| `-ssl-verify`  | Boolean value that configures Consul-Terraform-Connect to enable verification for TLS/SSL connections to the API. This does not affect insecure HTTP connections.<br/><br/>Alternatively, you can specify the value using the `CTS_SSL_VERIFY` environment variable.                                                                                        | Optional | `true`             |
+| `-ca-cert`     | String value that specifies the path to a PEM-encoded certificate authority file that is used to verify TLS/SSL connections. Takes precedence over `-ca-path` if both are provided.<br/><br/>Alternatively, you can specify the value using the `CTS_CACERT` environment variable.                                                                                 | Optional        | `""`                 |
+| `-ca-path`     | String value that specifies the path to a directory containing a PEM-encoded certificate authority file that is used to verify TLS/SSL connections.<br/><br/>Alternatively, you can specify the value using the `CTS_CAPATH` environment variable.                                                          | Optional        |  `""`                |
+| `-client-cert`  &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; | String value that specifies the path to a PEM-encoded client certificate that the Consul-Terraform-Sync API requires when [`verify_incoming`](/docs/nia/configuration#verify_incoming) is set to `true` on the API.<br/><br/>Alternatively, you can specify the value using the `CTS_CLIENT_CERT` environment variable.                                | Optional        | `""`                 |
+| `-client-key`  | String value that specifies the path to a PEM-encoded client key for the certificate configured with the `-client-cert` option. This is required if `-client-cert` is set and if [`verify_incoming`](/docs/nia/configuration#verify_incoming) is set to `true` on the Consul-Terraform-Sync API.<br/><br/>Alternatively, you can specify the value using the `CTS_CLIENT_KEY` environment variable. | Optional        | `""`                 |

website/content/docs/nia/configuration.mdx

@@ -27,6 +27,14 @@ buffer_period {
   min     = "5s"
   max     = "20s"
 }
+
+tls {
+  enabled         = true
+  cert            = "/path/to/cert.pem"
+  key             = "/path/to/key.pem"
+  verify_incoming = true
+  ca_cert         = "/path/to/ca.pem"
+}
 ```
 
 - `buffer_period` - Configures the default buffer period for all dynamic [tasks](#task) to dampen the effects of flapping services to downstream network devices. It defines the minimum and maximum amount of time to wait for the cluster to reach a consistent state and accumulate changes before triggering task executions. The default is enabled to reduce the number of times downstream infrastructure is updated within a short period of time. This is useful to enable in systems that have a lot of flapping. Buffer periods do not apply to scheduled tasks.
@@ -40,6 +48,13 @@ buffer_period {
   - `facility` - (string: "local0") Name of the syslog facility to log to.
   - `name` - (string: "consul-terraform-sync") Name to use for the daemon process when logging to syslog.
 - `working_dir` - (string: "sync-tasks") Specifies the base working directory for managing the artifacts generated by Consul-Terraform-Sync for each task, including Terraform configuration files. Consul-Terraform-Sync will also generate a subdirectory for each task, e.g., `./sync-tasks/task-name`. The subdirectory is the working directory for the task. Use the [`task.working_dir`](#working_dir-1) option to override task-level working directories.
+- `tls` - Configure TLS on the Consul-Terraform-Sync API.
+  - `enabled` - (bool: false) Enable TLS. Providing a value for any of the TLS options will enable this parameter implicitly.
+  - `cert` - (string) The path to a PEM-encoded certificate file used for TLS connections to the CTS API.
+  - `key` - (string) The path to the PEM-encoded private key file used with the certificate configured by `cert`.
+  - `verify_incoming` - (bool: false) Enable mutual TLS. Requires all incoming connections to the CTS API to use a TLS connection and provide a certificate signed by a Certificate Authority specified by the `ca_cert` or `ca_path`.
+  - `ca_cert` - (string) The path to a PEM-encoded certificate authority file used to verify the authenticity of the incoming client connections to the CTS API when `verify_incoming` is set to true. Takes precedence over `ca_path` if both are configured.
+  - `ca_path` - (string) The path to a directory of PEM-encoded certificate authority files used to verify the authenticity of the incoming client connections to the CTS API when `verify_incoming` is set to true.
 - `license_path` <EnterpriseAlert inline /> - (string: "") Configures the path to the file containing the license. A license must be set to use enterprise features. You can also set the license by defining the `CONSUL_LICENSE` and `CONSUL_LICENSE_PATH` environment variables. See [Setting the License](/docs/nia/enterprise/license#setting-the-license) for details.
 
 ## Consul
@@ -416,6 +431,12 @@ driver "terraform-cloud" {
   // written directly to the configuration file.
   // token = "{{ with secret \"secret/my/path\" }}{{ .Data.data.foo }}{{ end }}"
 
+  workspaces {
+    tags           = ["source:cts"]
+    tags_allowlist = []
+    tags_denylist  = []
+  }
+
   required_providers {
     myprovider = {
       source  = "namespace/myprovider"
@@ -430,6 +451,10 @@ driver "terraform-cloud" {
 - `token` - (string) Required [Team API token](https://www.terraform.io/docs/cloud/users-teams-organizations/api-tokens.html#team-api-tokens) used for authentication with Terraform Cloud and workspace management. Only workspace permissions are needed for Consul-Terraform-Sync. The token can also be provided using the `TFC_TOKEN` environment variable.
   - We recommend creating a dedicated team and team API token to isolate automation by Consul-Terraform-Sync from other Terraform Cloud operations.
 - `workspace_prefix` - (string) Specifies a prefix to prepend to the automatically-generated workspace names used for automation. This prefix will be used by all tasks that use this driver. By default, when no prefix is configured, the workspace name will be the task name. When a prefix is configured, the workspace name will be `<workspace_prefix value><task name>`. For example, if you configure the prefix as "cts_", then a task with the name "task_firewall" will have the workspace name "cts_task_firewall".
+- `workspaces` - Configure Consul-Terraform-Sync management of Terraform Cloud workspaces.
+  - `tags` - (list[string]) Tags for CTS to add to all automated workspaces when the workspace is first created or discovered. Tags are added to discovered workspaces only if the workspace meets [automation requirements](/docs/nia/network-drivers/terraform-cloud#remote-workspaces) and satisfies the allowlist and denylist tag options. This option will not affect existing tags. Tags that were manually removed during runtime will be re-tagged when CTS restarts. Compatible with Terraform Cloud and Terraform Enterprise v202108-1+
+  - `tags_allowlist` - (list[string]) Tag requirement to use as a provision check for CTS automation of workspaces. When configured, Terraform Cloud workspaces must have at least one tag from the allow list for CTS to automate the workspace and runs. Compatible with Terraform Cloud and Terraform Enterprise v202108-1+.
+  - `tags_denylist` - (list[string]) Tag restriction to use as a provision check for CTS automation of workspaces. When configured, Terraform Cloud workspaces must not have any tag from the deny list for CTS to automate the workspace and runs. Denied tags have higher priority than tags set in the `tags_allowlist` option. Compatible with Terraform Cloud and Terraform Enterprise v202108-1+.
 - `required_providers` - (obj: required) Declare each Terraform provider used across all tasks. This can be configured the same as how you would configure [Terraform `terraform.required_providers`](https://www.terraform.io/docs/configuration/provider-requirements.html#requiring-providers) field to specify the source and version for each provider. Consul-Terraform-Sync will process these requirements when preparing each task that uses the provider.
 - `tls` - Configure TLS to allow HTTPS connections to [Terraform Enterprise](https://www.terraform.io/docs/enterprise/install/installer.html#tls-key-amp-cert).
   - `enabled` - (bool) Enable TLS. Providing a value for any of the TLS options will enable this parameter implicitly.

website/content/docs/nia/network-drivers/terraform-cloud.mdx

@@ -40,6 +40,7 @@ Workspace automation requirements for Consul-Terraform-Sync are in place to avoi
 * Must be set to remote execution mode
 * Cannot be connected to a VCS
 * Cannot have an existing configuration version uploaded by another application
+* Must satisfy workspace [tag requirements](/docs/nia/configuration#tags_allowlist) and [tag restrictions](/docs/nia/configuration#tags_denylist) set by the CTS operator
 
 Workspaces created by Consul-Terraform-Sync will be configured with the following settings:
 
@@ -50,6 +51,7 @@ Workspaces created by Consul-Terraform-Sync will be configured with the followin
 | Execution mode | Remote |
 | Apply method | Auto apply |
 | Terraform Version | [`task.terraform_version`](/docs/nia/configuration#terraform_version) or the latest [Terraform version compatible with CTS](/docs/nia/compatibility#terraform) available for the organization. |
+| Tags | `source:cts` and [additional tags](/docs/nia/configuration#tags) set by the CTS operator |
 
 Other workspace settings can be pre-configured or updated, such as setting the workspace to [manual apply](#manual-apply) or adding a [run notification](https://www.terraform.io/docs/cloud/workspaces/notifications.html) to send messages to a Slack channel when Consul-Terraform-Sync updates your network infrastructure.