status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

nia/docs 0.3.0 (#10930) 

Co-authored-by: Kim Ngo <6362111+findkim@users.noreply.github.com>
Co-authored-by: Melissa Kam <mkam@hashicorp.com>
Co-authored-by: Michael Wilkerson <mwilkerson@hashicorp.com>
Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com>
This commit is contained in:
lornasong 2021-09-01 14:45:36 -04:00 committed by GitHub
parent 2b10d61bce
commit 6ee3c63c71
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 474 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
website/content/docs/nia/architecture.mdx
View File

@ -46,9 +46,12 @@ discovered IP addresses for a set of Consul services.
## Drivers
A driver encapsulates the resources required to communicate the updates to the
network infrastructure. Terraform is the initial supported driver. It comes
with a set of providers that [enables supporting](/docs/nia/terraform-modules) a wide variety of
infrastructure applications.
network infrastructure. The following [drivers](/docs/nia/network-drivers#terraform) are supported:
* Terraform driver
* Terraform Cloud driver<EnterpriseAlert inline />
Each driver includes a set of providers that [enables support](/docs/nia/terraform-modules) for a wide variety of infrastructure applications.
## Security Guidelines

124
website/content/docs/nia/configuration.mdx
View File

@ -15,6 +15,7 @@ Top level options are reserved for configuring Consul-Terraform-Sync.
```hcl
log_level = "INFO"
working_dir = "sync-tasks"
port = 8558
syslog {
facility = "local2"
@ -26,22 +27,24 @@ buffer_period {
}
```
- `buffer_period` - Configures the default buffer period for all [tasks](#task) to dampen the affects 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_period` - Configures the default buffer period for all [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.
- `enabled` - (bool: true) Enable or disable buffer periods globally. Specifying `min` will also enable it.
- `min` - (string: "5s") The minimum period of time to wait after changes are detected before triggering related tasks.
- `max` - (string: "20s") The maximum period of time to wait after changes are detected before triggering related tasks. If `min` is set, the default period for `max` is 4 times the value of `min`.
- `log_level` - (string: "WARN") The log level to use for Consul-Terraform-Sync logging.
- `log_level` - (string: "INFO") The log level to use for Consul-Terraform-Sync logging. This defaults to "INFO". The available log levels are "TRACE", "DEBUG", "INFO", "WARN", and "ERR".
- `port` - (int: 8558) The port for Consul-Terraform-Sync to use to serve API requests.
- `syslog` - Specifies the syslog server for logging.
- `enabled` - (bool) Enable syslog logging. Specifying other option also enables syslog logging.
- `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.
- `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
The `consul` block is used to configure Consul-Terraform-Sync connection with a Consul agent to perform queries to the Consul Catalog and Consul KV pertaining to task execution.
-> **Note:** For improved performance of Consul-Terraform-Sync communicating with the local Consul process you can use HTTP/2. To use HTTP/2 the local Consul needs to have [TLS/HTTPS configured](/docs/agent/options) with, at least, the [cert_file](/docs/agent/options#cert_file) and [key_file](/docs/agent/options#key_file) set. Consul-Terraform-Sync's configuration for HTTP/2 requires `tls.enabled = true` and it must have the address set to the HTTPS URL, `address = example.consul.com:8501`. Optionally you'll need to set `tls.verify = false` if using self-signed certificates for Consul. Using HTTP/2 can solve issues hitting Consul's maximum connections limits as well as just generally perform more efficiently when processing lots of blocking queries.
-> **Note:** Use HTTP/2 to improve Consul-Terraform-Sync performance when communicating with the local Consul process. [TLS/HTTPS](/docs/agent/options) must be configured for the local Consul with the [cert_file](/docs/agent/options#cert_file) and [key_file](/docs/agent/options#key_file) parameters set. For the Consul-Terraform-Sync configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false`.
To read more on suggestions for configuring the Consul agent, see [run an agent](/docs/nia/installation/requirements#run-an-agent).
@ -60,11 +63,11 @@ consul {
- `enabled` - (bool)
- `username` - (string)
- `password` - (string)
- `tls` - Configure TLS to use a secure client connection with Consul. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/options#verify_incoming).
- `tls` - Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/options#verify_incoming).
- `enabled` - (bool) Enable TLS. Specifying any option for TLS will also enable it.
- `verify` - (bool: true) Enables TLS peer verification. The default is enabled, which will check the global CA chain to make sure the given certificates are valid. If you are using a self-signed certificate that you have not added to the CA chain, you may want to disable SSL verification. However, please understand this is a potential security vulnerability.
- `key` - (string) The client key file to use for talking to Consul over TLS. The key also be provided through the `CONSUL_CLIENT_KEY` environment variable.
- `ca_cert` - (string) The CA file to use for talking to Consul over TLS. Can also be provided though the `CONSUL_CACERT` environment variable.
- `key` - (string) The client key file to use for talking to Consul over TLS. The key can also be provided through the `CONSUL_CLIENT_KEY` environment variable.
- `ca_cert` - (string) The CA file to use for talking to Consul over TLS. Can also be provided through the `CONSUL_CACERT` environment variable.
- `ca_path` - (string) The path to a directory of CA certs to use for talking to Consul over TLS. Can also be provided through the `CONSUL_CAPATH` environment variable.
- `cert` - (string) The client cert file to use for talking to Consul over TLS. Can also be provided through the `CONSUL_CLIENT_CERT` environment variable.
- `server_name` - (string) The server name to use as the SNI host when connecting via TLS. Can also be provided through the `CONSUL_TLS_SERVER_NAME` environment variable.
@ -127,21 +130,37 @@ task {
- `enabled` - (bool: true) Enable or disable a task from running and managing resources.
- `providers` - (list[string]) Providers is the list of provider names the task is dependent on. This is used to map [Terraform provider configuration](#terraform-provider) to the task.
- `services` - (list[string]) Required depending on [`condition`](#condition) configuration. Services is the list of logical service names or service IDs the task executes on. Consul-Terraform-Sync monitors the Consul Catalog for changes to these services and triggers the task to run. Any service value not explicitly defined by a `service` block with a matching ID is assumed to be a logical service name in the default namespace. Alternative to configuring `services`, a `condition` can be configured so that the task does not trigger on changes to services (default behavior) but instead trigger on a different condition. See [Task Condition](#task-condition) configuration for more details.
- `source` - (string: required) Source is the location the driver uses to fetch task dependencies. The source format is dependent on the driver. For the [Terraform driver](#terraform-driver), the source is the module path (local or remote). Read more on [Terraform module source here](https://www.terraform.io/docs/modules/sources.html).
- `variable_files` - (list[string]) A list of paths to files containing variables for the task. For the [Terraform driver](#terraform-driver), these are used as Terraform [variable definition (`.tfvars`) files](https://www.terraform.io/docs/configuration/variables.html#variable-definitions-tfvars-files) and consists of only variable name assignments. The variable assignments must match the corresponding variable declarations available by the Terraform module for the task. Consul-Terraform-Sync will generate the intermediate variable declarations to pass as arguments from the auto-generated root module to the task's module. Variables are loaded in the same order as they appear in the order of the files. Duplicate variables are overwritten with the later value. _Note: unless specified by the module, configure arguments for Terraform providers using [`terraform_provider` blocks](#terraform-provider)._
```hcl
address_group = "consul-services"
tags = [
"consul-terraform-sync",
"terraform"
]
```
- `source` - (string: required) Source is the location the driver uses to discover the Terraform module used for automation. The source is the module path which can be local or remote on the [Terraform Registry](https://registry.terraform.io/) or private module registry. Read more on [Terraform module source and other supported types here](https://www.terraform.io/docs/modules/sources.html).
- To use a private module with the [`terraform` driver](#terraform-driver), run the command [`terraform login [hostname]`](https://learn.hashicorp.com/tutorials/terraform/cloud-login) to authenticate the local Terraform CLI prior to starting Consul-Terraform-Sync.
- To use a private module with the [`terraform_cloud` driver](#terraform-cloud-driver), no extra steps are needed.
```hcl
// local module example: "./terraform-cts-hello"
source = "<PATH>"
// public module example: "mkam/hello/cts"
source = "<NAMESPACE>/<MODULE NAME>/<PROVIDER>"
// private module example: "my.tfe.hostname.io/my-org/hello/cts"
source = "<HOSTNAME>/<ORGANIZATION>/<MODULE NAME>/<PROVIDER>"
```
- `variable_files` - (list[string]) Specifies list of paths to [Terraform variable definition files (`.tfvars`)](https://www.terraform.io/docs/configuration/variables.html#variable-definitions-tfvars-files). The content of these files should consist of only variable name assignments. The variable assignments must match the corresponding variable declarations made available by the Terraform module for the task.
- Variables are loaded in the order they appear in the files. Duplicate variables are overwritten with the later value. _Unless specified by the module, configure arguments for Terraform providers using [`terraform_provider` blocks](#terraform-provider)._
```hcl
# example.tfvars
address_group = "consul-services"
tags = [
"consul-terraform-sync",
"terraform"
]
```
- `version` - (string) The version of the provided source the task will use. For the [Terraform driver](#terraform-driver), this is the module version. The latest version will be used as the default if omitted.
- `buffer_period` - Configures the buffer period for the task to dampen the affects 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 execution. The default is inherited from the top level [`buffer_period` block](#global-config-options). If configured, these values will take precedence over the global buffer period. This is useful to enable for a task that is dependent on services that have a lot of flapping.
- `working_dir` - (string) The working directory to manage generated artifacts by Consul-Terraform-Sync for this task, including Terraform configuration files. By default, a working directory is created for each task as a subdirectory in the base [`working_dir`](#working_dir), e.g. `sync-tasks/task-name`.
- `buffer_period` - Configures the buffer period for the 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 execution. The default is inherited from the top level [`buffer_period` block](#global-config-options). If configured, these values will take precedence over the global buffer period. This is useful to enable for a task that is dependent on services that have a lot of flapping.
- `enabled` - (bool) Enable or disable buffer periods for this task. Specifying `min` will also enable it.
- `min` - (string: "5s") The minimum period of time to wait after changes are detected before triggering related tasks.
- `max` - (string: "20s") The maximum period of time to wait after changes are detected before triggering related tasks. If `min` is set, the default period for `max` is 4 times the value of `min`.
- `condition` - (obj) The requirement that, when met, triggers Consul-Terraform-Sync to execute the task. When unconfigured, the default condition is to trigger the task on changes in the services configured in [`services`](#services). Only one `condition` may be configured per task. Consul-Terraform-Sync supports different types of conditions, which each have their own configuration options. See [Task Condition](#task-condition) configuration for full details on configuration options for each condition type.
- `terraform_version` - (string) <EnterpriseAlert inline /> The version of Terraform to use for the Terraform Enterprise workspace associated with the task. Defaults to the latest compatible version supported by the organization. This option is only available when used with the [Terraform Cloud driver](#terraform-cloud-driver); otherwise, set the version within the [Terraform driver](#terraform-driver).
### Task Condition
@ -149,24 +168,23 @@ A `task` block can be optionally configured with a `condition` block to set the
#### Services Condition
This is the default type of condition when no `condition` block is configured for a task. This condition will trigger the task on changes in services configured in [`task.services`](#services). The task can optionally be configured with a services condition block. However, this is not necessary since this is the default type of condition and there is currently no additional configuration options available for services condition.
This is the default type of condition when no `condition` block is configured for a task. This condition will trigger the task on either changes in services configured in [`task.services`](#services) or changes in services that match the regular expression configured in `regexp`. The default behavior is to trigger on changes to [`task.services`](#services). The [`task.services`](#services) option is required if `regexp` is not configured.
See [Task Execution: Services Condition](/docs/nia/tasks#services-condition) for more details on how tasks are triggered with a services condition.
```hcl
task {
name = "services_condition_task"
description = "execute on changes to api, db, and web services"
services = ["api", "db", "web"]
description = "execute on changes to services with names starting with web"
providers = ["my-provider"]
source = "path/to/services-condition-module"
// optional: declare empty services condition block
condition "services" {
// no additional configuration options currently
regexp = "^web.*"
}
}
```
- `regexp` - **(beta)** (string) Only services that have a name which matches the regular expression are used by the task. If `regexp` is configured, then [`task.services`](#services) must be omitted or empty. If both a list and a regex are needed, consider including the list as part of the regex or creating separate tasks.
#### Catalog-Services Condition
@ -203,16 +221,21 @@ task {
- `regexp` - (string) Optional if [`task.services`](/docs/nia/configuration#services) is configured. Either `regexp` or `task.services` or both must be configured. Only services that have a name which matches the regular expression are used by the task. If not provided, `regexp` will default to an exact match on `task.services` list. For example, if `task.services = ["api", "web"]`, then `regexp` will default to `^api$|^web$`. See [Task Execution: Catalog Services Condition](/docs/nia/tasks#catalog-services-condition) for more details on the relationship between `task.services` and `regexp`. Some resources for more information on regular expressions: [regular expression syntax](https://github.com/google/re2/wiki/Syntax), [try out regular expression string matching](https://golang.org/pkg/regexp/#Regexp.MatchString).
- `source_includes_var` - (bool: false) Whether or not the module configured at [`task.source`](#source) includes the [`catalog_services` variable](/docs/nia/terraform-modules#catalog-services-variable). Please refer to the documentation of the selected module for guidance on how to configure this field. If configured inconsistently with the module, Consul-Terraform-Sync will error and exit.
## Network Drivers
A driver is required for Consul-Terraform-Sync to propagate network infrastructure change. The `driver` block configures the subprocess that Consul-Terraform-Sync runs in automation. The default driver is the [Terraform driver](#terraform-driver) which automates Terraform as a local installation of the Terraform CLI.
Only one network driver can be configured per deployment of Consul-Terraform-Sync.
## Terraform Driver
The `driver` block configures the subprocess for Consul-Terraform-Sync to propagate infrastructure change. The Terraform driver is a required configuration for Consul-Terraform-Sync to relay provider discovery and installation information to Terraform, specifically the `required_providers` stanza. Other driver options do not need to be explicitly configured and has reasonable default values.
The Terraform driver block is used to configure Consul-Terraform-Sync for installing and automating Terraform locally. The driver block supports Terraform configuration to specify the `backend` used for state management and `required_providers` configuration used for provider discovery.
```hcl
driver "terraform" {
log = false
persist_log = false
path = ""
working_dir = ""
backend "consul" {
gzip = true
@ -227,15 +250,62 @@ driver "terraform" {
}
```
- `backend` - (obj) The backend stores [Terraform state files](https://www.terraform.io/docs/state/index.html) for each task. This option is similar to the [Terraform backend configuration](https://www.terraform.io/docs/configuration/backend.html). Consul-Terraform-Sync supports Terraform backends used as a state store and currently does not support enhanced backends. If omitted, Consul-Terraform-Sync will generate default values and use configuration from the [`consul` block](#consul) to configure [Consul as the backend](https://www.terraform.io/docs/backends/types/consul.html). The Consul KV path is the base path to store state files for tasks. The full path of each state file will have the task identifer appended to the end of the path, e.g. `consul-terraform-sync/terraform-env:task-name`.
- `backend` - (obj) The backend stores [Terraform state files](https://www.terraform.io/docs/state/index.html) for each task. This option is similar to the [Terraform backend configuration](https://www.terraform.io/docs/configuration/backend.html). Consul-Terraform-Sync supports Terraform backends used as a state store. It does not support enhanced backends. If omitted, Consul-Terraform-Sync will generate default values and use configurations from the [`consul` block](#consul) to configure [Consul as the backend](https://www.terraform.io/docs/backends/types/consul.html). The Consul KV path is the base path to store state files for tasks. The full path of each state file will have the task identifier appended to the end of the path, e.g., `consul-terraform-sync/terraform-env:task-name`.
- Supported backend options: [azurerm](https://www.terraform.io/docs/backends/types/azurerm.html), [consul](https://www.terraform.io/docs/backends/types/consul.html), [cos](https://www.terraform.io/docs/backends/types/cos.html), [gcs](https://www.terraform.io/docs/backends/types/gcs.html), [kubernetes](https://www.terraform.io/docs/backends/types/kubernetes.html), [local](https://www.terraform.io/docs/backends/types/local.html), [manta](https://www.terraform.io/docs/backends/types/manta.html), [pg](https://www.terraform.io/docs/backends/types/pg.html) (Terraform v0.14+), [s3](https://www.terraform.io/docs/backends/types/s3.html)
- Visit the Terraform documentation links above for the specific backend configuration options.
- `log` - (bool) Enable all Terraform output (stderr and stdout) to be included in the Consul-Terraform-Sync log. This is useful for debugging and development purposes. It may be difficult to work with log aggregators that expect uniform log format.
- `path` - (string) The file path to install Terraform or discover an existing Terraform binary. If omitted, Terraform will be installed in the same directory as the Consul-Terraform-Sync daemon. To resolve an incompatible Terraform version or to change versions will require removing the existing binary or change to a different path.
- `persist_log` - (bool) Enable trace logging for each Terraform client to disk per task. This is equivalent to setting `TF_LOG_PATH=<work_dir>/terraform.log`. Trace log level results in verbose logging and may be useful for debugging and development purposes. We do not recommend enabling this for production. There is no log rotation and may quickly result in large files.
- `required_providers` - (obj: required) Declare each Terraform provider used across all tasks. This is similar to the [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.
- `version` - (string) The Terraform version to install and run in automation for task execution. If omitted, the driver will install the latest official release of Terraform. To change versions, remove the existing binary or change the path to install the desired version. Verify that the desired Terraform version is compatible across all Terraform modules used for Consul-Terraform-Sync automation.
- `working_dir` - (string: "sync-tasks") The base working directory to manage Terraform configurations all tasks. The full path of each working directory will have the task identifier appended to the end of the path, e.g. `./sync-tasks/task-name`.
- `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.
- `version` - (string) The Terraform version to install and run in automation for task execution. If omitted, the driver will install the latest [compatible release of Terraform](/docs/nia/compatibility#terraform). To change versions, remove the existing binary or change the path to install the desired version. Verify that the desired Terraform version is compatible across all Terraform modules used for Consul-Terraform-Sync automation.
- `working_dir` - (string: "sync-tasks") **Deprecated in Consul-Terraform-Sync 0.3.0**, use the global [`working_dir`](#working_dir) option instead. The base working directory to manage Terraform configurations for all tasks. The full path of each working directory will have the task identifier appended to the end of the path, e.g. `./sync-tasks/task-name`.
## Terraform Cloud Driver
<EnterpriseAlert>
This feature requires{' '}
<a href="https://www.hashicorp.com/products/consul/features">
Consul-Terraform-Sync Enterprise
</a>{' '}
which is available with <strong>Consul Enterprise</strong>.
</EnterpriseAlert>
The Terraform Cloud driver enables Consul-Terraform-Sync Enterprise to integrate with [**Terraform Enterprise**](https://www.hashicorp.com/products/terraform/editions/enterprise)<sup>1</sup>, the self-hosted distribution of Terraform Cloud. With this driver, Consul-Terraform-Sync automates Terraform runs and remote operations for workspaces.
An overview of features enabled with Terraform Enterprise can be viewed within the [Network Drivers](/docs/nia/network-drivers) documentation.
Only one network driver can be configured per deployment of Consul-Terraform-Sync.
-> <sup>1</sup> **Upcoming**: The Terraform Cloud driver is introduced in Consul-Terraform-Sync v0.3.0 and only supports [Terraform Enterprise](https://www.hashicorp.com/products/terraform/editions/enterprise), the self-hosted distribution. The upcoming v0.4.0 release will support integration with [Terraform Cloud](https://www.terraform.io/cloud), the HashiCorp managed service.
```hcl
driver "terraform-cloud" {
hostname = "my.tfe.hostname.io"
organization = "my-org"
token = "<TEAM_TOKEN>"
// Optionally set the token to be securely queried from Vault instead of
// written directly to the configuration file.
// token = "{{ with secret \"secret/my/path\" }}{{ .Data.data.foo }}{{ end }}"
required_providers {
myprovider = {
source = "namespace/myprovider"
version = "1.3.0"
}
}
}
```
- `hostname` - (string) The Terraform Enterprise hostname to connect to. Can be overridden with the `TFC_HOSTNAME` environment variable.
- `organization` - (string) The Terraform Enterprise organization that hosts the managed workspaces by Consul-Terraform-Sync. Can be overridden with the `TFC_ORGANIZATION` environment variable.
- `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 Enterprise 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 Enterprise 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".
- `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.
Consul-Terraform-Sync generates local artifacts to prepare configuration versions used for workspace runs. The location of the files created can be set with the [`working_dir`](/docs/nia/configuration#working_dir) option or configured per task. When a task is configured with a local module and is run with the Terraform Cloud driver, the local module is copied and uploaded as a part of the configuration version.
The version of Terraform to use for each workspace can also be set within the [task](#task) configuration.
## Terraform Provider

14
website/content/docs/nia/enterprise/index.mdx Normal file
View File

@ -0,0 +1,14 @@
---
layout: docs
page_title: Consul-Terraform-Sync Enterprise
description: >-
Consul-Terraform-Sync Enterprise
---
# Consul-Terraform-Sync Enterprise
Consul-Terraform-Sync Enterprise features address organization complexities of collaboration, operations, scale, and governance. Please see the sidebar navigation on the left to view all enterprise features.
Enterprise features require a Consul [license](/docs/nia/enterprise/license) to be applied.
These features are part of Consul-Terraform-Sync Enterprise which is part of [Consul Enterprise](https://www.hashicorp.com/products/consul).

64
website/content/docs/nia/enterprise/license.mdx Normal file
View File

@ -0,0 +1,64 @@
---
layout: docs
page_title: Consul-Terraform-Sync Enterprise License
description: >-
Consul-Terraform-Sync Enterprise License
---
# Consul-Terraform-Sync Enterprise License
<EnterpriseAlert>
Licenses are only required for Consul-Terraform-Sync Enterprise
</EnterpriseAlert>
Consul-Terraform-Sync Enterprise binaries require a [Consul Enterprise license](/docs/enterprise/license/overview) to run. There is no Consul-Terraform-Sync Enterprise specific license. As a result, Consul-Terraform-Sync Enterprise's licensing is very similar to Consul Enterprise.
All Consul-Terraform-Sync Enterprise features are available with a valid Consul Enterprise license, regardless of your Consul Enterprise packaging or pricing model.
To get a trial license for Consul-Terraform-Sync Enterprise, you can sign-up for the [trial license for Consul Enterprise](/docs/enterprise/license/faq#q-where-can-users-get-a-trial-license-for-consul-enterprise).
## Setting the License
Choose one of the following methods (in order of precedence) to set the license:
1. Set the `CONSUL_LICENSE` environment variable to the license string.
```shell-session
export CONSUL_LICENSE=<LICENSE_VALUE>
```
2. Set the `CONSUL_LICENSE_PATH` environment variable to the path of the file containing the license.
```shell-session
export CONSUL_LICENSE_PATH=<PATH>/<TO>/<FILE>
```
3. Configure the [`license_path`](/docs/nia/configuration#license_path) option in the configuration file to point to the file containing the license.
```hcl
license_path = "<PATH>/<TO>/<FILE>"
```
~> **Note**: the [options to set the license and the order of precedence](/docs/enterprise/license/overview#binaries-without-built-in-licenses) are the same as Consul Enterprise server agents.
### Updating the License
The previous section describes options for [setting the license](#setting-the-license) needed to start running Consul-Terraform-Sync Enterprise. Use the following procedure to update the license when it expires or is near the expiration date:
1. Update the license environment variable or configuration with the new license value or path to the new license file
1. Stop and restart Consul-Terraform-Sync Enterprise
Once Consul-Terraform-Sync Enterprise starts again, it will pick up the new license and run the tasks with any changes that may have occurred between the stop and restart period.
## Notification and Termination Behavior
Licenses have an expiration date and a termination date. The termination date is a time at or after the license expires. Consul-Terraform-Sync Enterprise will cease to function once the termination date has passed.
The time between the expiration and termination dates is a grace period. Grace periods are generally 24-hours, but you should refer to your license agreement for complete terms of your grace period.
When approaching expiration and termination, Consul-Terraform-Sync Enterprise will provide notifications in the system logs:
| Time period | Behavior |
|---------------------------------------------|-----------------------------------|
| 30 days before expiration | Warning-level log every 24-hours |
| 7 days before expiration | Warning-level log every 1 hour |
| 1 hour before expiration | Warning-level log every 1 minute |
| 1 day before expiration | Warning-level log every 5 minutes |
| At or after expiration (before termination) | Error-level log every 1 minute |
| At or after termination | Error-level log and exit |
~> **Note**: Notification frequency and [grace period](/docs/enterprise/license/faq#q-is-there-a-grace-period-when-licenses-expire) behavior is the same as Consul Enterprise.

4
website/content/docs/nia/index.mdx
View File

@ -23,12 +23,14 @@ Consul-Terraform-Sync executes one or more automation tasks with the most recent
**Consul-Terraform-Sync** - [GitHub repo](https://github.com/hashicorp/consul-terraform-sync) and binary/CLI name for the project that is used to perform Network Infrastructure Automation.
**Network Drivers** - Network drivers are used by Consul-Terraform-Sync to execute and update network infrastructure. Drivers transform Consul service level information into downstream changes by understanding and abstracting API and resource details tied to specific network infrastructure.
**Network Drivers** - Consul-Terraform-Sync uses [network drivers](/docs/nia/network-drivers) to execute and update network infrastructure. Drivers transform Consul service-level information into downstream changes by processing and abstracting API and resource details tied to specific network infrastructure.
**Network Infrastructure Automation (NIA)** - Enables dynamic updates to network infrastructure devices triggered when specific conditions, such as service changes and registration, are met.
**Tasks** - A task is the translation of dynamic service information from the Consul Catalog into network infrastructure changes downstream.
**Terraform Cloud** - Per the [Terraform documentation](https://www.terraform.io/docs/cloud/index.html), "Terraform Cloud" describes both Terraform Cloud and Terraform Enterprise, which are different distributions of the same application. Documentation will apply to both distributions unless specifically stated otherwise.
**Terraform Module** - A [Terraform module](https://www.terraform.io/docs/configuration/modules.html) is a container for multiple Terraform resources that are used together.
**Terraform Provider** - A [Terraform provider](https://www.terraform.io/docs/providers/index.html) is responsible for understanding API interactions and exposing resources for an infrastructure type.

3
website/content/docs/nia/installation/install.mdx
View File

@ -7,8 +7,7 @@ description: >-
# Install Consul-Terraform-Sync
The [introduction](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-intro?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial provides a quick walkthrough of installing, configuring, and running
Consul-Terraform-Sync on your local machine.
Refer to the [introduction](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-intro?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial for details about installing, configuring, and running Consul-Terraform-Sync on your local machine with the Terraform driver.
## Installing Consul-Terraform-Sync

10
website/content/docs/nia/installation/requirements.mdx
View File

@ -7,7 +7,15 @@ description: >-
# Prerequisites Needed to Run Consul-Terraform-Sync
Consul-Terraform-Sync requires a Terraform Provider, a Terraform Module, and a running Consul cluster outside of the consul-terraform-sync daemon. Practitioners can add support for their network infrastructure through Terraform providers. Once network infrastructure support exists, practitioners can add network integrations in the form of Terraform modules.
The following components are required to run Consul-Terraform-Sync:
* A Terraform Provider
* A Terraform Module
* A Consul cluster running outside of the consul-terraform-sync daemon
Practitioners can add support for their network infrastructure through Terraform providers. Once network infrastructure support exists, practitioners can add network integrations in the form of Terraform modules.
The following guidance is for running Consul-Terraform-Sync using the Terraform driver. The Terraform Cloud driver<EnterpriseAlert inline />has [additional prerequisites](/docs/nia/network-drivers/terraform-cloud#setting-up-terraform-cloud-driver).
## Run a Consul Cluster

60
website/content/docs/nia/network-drivers.mdx
View File

@ -1,60 +0,0 @@
---
layout: docs
page_title: Network Drivers
description: >-
Consul-Terraform-Sync Network Drivers
---
# Network Drivers
Network drivers are used by Consul-Terraform-Sync to execute and update network infrastructure. Drivers transform Consul service level information into downstream changes by understanding and abstracting API and resource details tied to specific network infrastructure.
## Terraform
Consul-Terraform-Sync is a HashiCorp solution to Network Infrastructure Automation by bridging the networking features of Consul and infrastructure management with Terraform. The solution seamlessly embeds Terraform as a network driver to manage automation of Terraform modules. This expands the Consul ecosystem and taps into the rich features and community of Terraform and Terraform providers. Consul-Terraform-Sync automates Terraform execution of templated configuration files to carry out infrastructure changes. The auto-generated configuration leverages input variables sourced from Consul and builds on top of reusable Terraform modules published and maintained by HashiCorp partners and the community.
### Understanding Terraform Automation
On startup, Consul-Terraform-Sync downloads and installs [Terraform](https://www.terraform.io/downloads.html), prepares the local environment, and generates Terraform configuration files that make up the root module for each task. Terraform configuration and execution for each task is organized as separate [Terraform workspaces](https://www.terraform.io/docs/state/workspaces.html). The state files for tasks are independent of each other.
~> **Note:** Although Terraform state files for task workspaces are independent, this does not guarantee the infrastructure changes from concurrent task executions are independent. Ensure that modules across all tasks are not modifying the same resource objects or have overlapping changes that may result in race conditions during automation.
Within the Consul-Terraform-Sync configuration for a task, practitioners can select the desired module to run for the task as well as set the condition to execute the task. Each task executed by the Terraform driver corresponds to an automated root module that calls the selected module in an isolated Terraform environment. Consul-Terraform-Sync will manage concurrent execution of these tasks.
### Root Module
The root module is simple in structure and proxies Consul information, configuration, and other variables to the Terraform module for the task. The content of the files that make up the root module are sourced from Consul-Terraform-Sync configuration, information for task's module to use as the automation playbook, and information from Consul such as service information.
Auto-generated root modules for tasks are stored in local subdirectories of the Terraform working directory. By default, the working directory `sync-tasks` is created in the current directory. To configure where Terraform configuration files are stored, set [`working_dir`](/docs/nia/configuration#working_dir) for the Terraform driver to the desired path.
A working directory with one task named "my-task" would have the folder structure below.
```
sync-tasks/
my-task/
main.tf
variables.tf
terraform.tfvars
terraform.tfvars.tmpl
```
The following files of the root module are generated for each task. An [example of a root module created by Consul-Terraform-Sync](https://github.com/hashicorp/consul-terraform-sync/tree/master/examples) can be found in the project repository.
- `main.tf` - The main file contains the terraform block, provider blocks, and a module block calling the module configured for the task.
- `terraform` block - The corresponding provider source and versions for the task from the configuration files are placed into this block for the root module. The Terraform backend from the configuration is also templated here.
- `provider` blocks - The provider blocks generated in the root module resemble the `terraform_provider` blocks in the configuration. They have identical arguments present and are set from the intermediate variable created per provider.
- `module` block - The module block is where the task's module is called as a [child module](https://www.terraform.io/docs/configuration/modules.html#calling-a-child-module). The child module contains the core logic for automation. Required and optional input variables are passed as arguments to the module.
- `variables.tf` - This file contains 3 types of variable declarations. The first type is the required `services` input variable which determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](/docs/nia/terraform-modules) for more details). The second type is any additional Consul-Terraform-Sync provided [optional input variables](/docs/nia/terraform-modules#optional-input-variables) that the module may include. The final type is various intermediate variables used to dynamically configure providers. These intermediate provider variables are interpolated from the provider blocks and arguments configured in the Consul-Terraform-Sync configuration.
- `variables.module.tf` - This file is conditionally created if there are [variables configured for the task](/docs/nia/configuration#variable_files) and contains the interpolated variable declarations that match the variables from configuration. These are then used to proxy the configured variables to the module through explicit assignment in the module block.
- `terraform.tfvars` - The variable definitions file is where the services input variable and any optional Consul-Terraform-Sync input variables are assigned values from Consul. It is periodically updated, typically when the task condition is met, to reflect the current state of Consul.
- `terraform.tfvars.tmpl` - The template file is used by Consul-Terraform-Sync to template information from Consul by using the HashiCorp configuration and templating library ([hashicorp/hcat](https://github.com/hashicorp/hcat)).
-> **Note:** Generated template and Terraform configuration files are crucial to the automation of tasks. Any manual changes to the files may not be preserved and could be overwritten by a subsequent update.
### Upgrading Terraform
Upgrading the Terraform version used by Consul-Terraform-Sync may introduce breaking changes that can impact the Terraform modules. Refer to the Terraform [upgrade guides](https://www.terraform.io/upgrade-guides/index.html) for details before upgrading.
The following versions were identified as containing changes that may impact Terraform modules.
- [Terraform v0.15](https://www.terraform.io/upgrade-guides/0-15.html)

36
website/content/docs/nia/network-drivers/index.mdx Normal file
View File

@ -0,0 +1,36 @@
---
layout: docs
page_title: Network Drivers
description: >-
Consul-Terraform-Sync Network Drivers with Terraform and Terraform Cloud
---
# Network Drivers
Consul-Terraform-Sync uses network drivers to execute and update network infrastructure. Drivers transform Consul service-level information into downstream changes by processing and abstracting API and resource details tied to specific network infrastructure.
Consul-Terraform-Sync is a HashiCorp solution to Network Infrastructure Automation. It bridges Consul's networking features and Terraform infrastructure management capabilities. The solution seamlessly embeds Terraform as network drivers to manage automation of Terraform modules. This expands the Consul ecosystem and taps into the rich features and community of Terraform and Terraform providers.
The following table highlights some of the additional features Terraform and Terraform Enterprise offer when used as a network driver for Consul-Terraform-Sync. Visit the [Terraform product page](https://www.hashicorp.com/products/terraform) or [contact our sales team](https://www.hashicorp.com/contact-sales) for a comprehensive list of features.
| Network Driver | Description | Features |
| -------------- | ----------- | -------- |
| [Terraform driver](/docs/nia/network-drivers/terraform) | Consul-Terraform-Sync automates a local installation of the [Terraform CLI](https://www.terraform.io/) | - Local Terraform execution <br/> - Local workspace directories <br/> - [Backend options](/docs/nia/configuration#backend) available for state storage <br/> |
| [Terraform Cloud driver](/docs/nia/network-drivers/terraform-cloud) | Consul-Terraform-Sync Enterprise automates remote workspaces on [Terraform Enterprise](https://www.terraform.io/docs/cloud/index.html)<sup>1</sup> | - [Remote Terraform execution](https://www.terraform.io/docs/cloud/run/index.html) <br/> - Concurrent runs <br/> - [Secured variables](https://www.terraform.io/docs/cloud/workspaces/variables.html) <br/> - [State versions](https://www.terraform.io/docs/cloud/workspaces/state.html) <br/> - [Sentinel](https://www.terraform.io/docs/cloud/sentinel/index.html) to enforce governance policies as code <br/> - [Audit logs](https://www.terraform.io/docs/enterprise/admin/logging.html) <br/> - Run [history](https://www.terraform.io/docs/cloud/run/manage.html), [triggers](https://www.terraform.io/docs/cloud/workspaces/run-triggers.html) and [notifications](https://www.terraform.io/docs/cloud/workspaces/notifications.html) |
-> <sup>1</sup> **Upcoming**: The Terraform Cloud driver is introduced in Consul-Terraform-Sync v0.3.0 and only supports [Terraform Enterprise](https://www.hashicorp.com/products/terraform/editions/enterprise), the self-hosted distribution. The upcoming v0.4.0 release will support integration with [Terraform Cloud](https://www.terraform.io/cloud), the HashiCorp managed service.
## Understanding Terraform Automation
Consul-Terraform-Sync automates Terraform execution using a templated configuration to carry out infrastructure changes. The auto-generated configuration leverages input variables sourced from Consul and builds on top of reusable Terraform modules published and maintained by HashiCorp partners and the community. Consul-Terraform-Sync can also run your custom built modules that suit your team's specific network automation needs.
The network driver for Consul-Terraform-Sync determines how the Terraform automation operates. Visit the driver pages to read more about the [Terraform driver](/docs/nia/network-drivers/terraform) and the [Terraform Cloud driver](/docs/nia/network-drivers/terraform-cloud).
### Upgrading Terraform
Upgrading the Terraform version used by Consul-Terraform-Sync may introduce breaking changes that can impact the Terraform modules. Refer to the Terraform [upgrade guides](https://www.terraform.io/upgrade-guides/index.html) for details before upgrading.
The following versions were identified as containing changes that may impact Terraform modules.
- [Terraform v0.15](https://www.terraform.io/upgrade-guides/0-15.html)

112
website/content/docs/nia/network-drivers/terraform-cloud.mdx Normal file
View File

@ -0,0 +1,112 @@
---
layout: docs
page_title: Terraform Cloud Driver
description: >-
Consul-Terraform-Sync Network Drivers with Terraform Enterprise
---
# Terraform Cloud Driver
<EnterpriseAlert>
This feature requires{' '}
<a href="https://www.hashicorp.com/products/consul/features">Consul-Terraform-Sync Enterprise</a>{' '}
which is available with <strong>Consul Enterprise</strong>.
</EnterpriseAlert>
Consul-Terraform-Sync is more powerful when you integrate it with [Terraform Enterprise](https://www.hashicorp.com/products/terraform/editions/enterprise)<sup>1</sup>. Integrating with Terraform Enterprise provides features, such as enhanced workspaces and insight into Terraform operations as Consul-Terraform-Sync dynamically updates your network infrastructure.
This page describes how the Terraform Cloud driver operates within Consul-Terraform-Sync.
-> <sup>1</sup> **Upcoming**: The Terraform Cloud driver is introduced in Consul-Terraform-Sync v0.3.0 and only supports [Terraform Enterprise](https://www.hashicorp.com/products/terraform/editions/enterprise), the self-hosted distribution. The upcoming v0.4.0 release will support integration with [Terraform Cloud](https://www.terraform.io/cloud), the HashiCorp managed service.
## Terraform Workspace Automation
Consul-Terraform-Sync manages Terraform runs following the [API-driven run workflow](https://www.terraform.io/docs/cloud/run/api.html) for workspaces in Terraform Enterprise.
On startup, Consul-Terraform-Sync:
1. Creates or discovers Terraform Enterprise workspaces corresponding to the configured tasks.
2. Prepares the local environment and generates Terraform configuration files that make up the root module for each task.
3. Packages the generated files and uploads them as a configuration version for the task's workspace on Terraform Enterprise.
Once all workspaces are set up, Consul-Terraform-Sync monitors the Consul catalog for service changes. When relevant changes are detected, the Terraform Cloud driver dynamically updates input variables for that task directly as [workspace variables](https://www.terraform.io/docs/cloud/workspaces/variables.html) using the Terraform Cloud API. The driver then queues a run on the workspace, with auto-apply enabled, to update your network infrastructure.
~> **Note:** Although workspaces for tasks are executed in isolated environments, this does not guarantee the infrastructure changes from concurrent task executions are independent. Ensure that modules across all tasks are not modifying the same resource objects or have overlapping changes that may result in race conditions during automation.
## Remote Workspaces
Consul-Terraform-Sync will discover or create a new workspaces based on your configured tasks. The task configuration options for `name`, `description`, and `terraform_version` are used to set the workspace name, description, and Terraform version.
[![CTS Workspace Overview](/img/nia/cts-tfc-workspace.png)](/img/nia/cts-tfc-workspace.png)
Workspace automation requirements for Consul-Terraform-Sync:
* Must be set to remote execution mode
* Cannot be connected to a VCS
* Cannot have an existing configuration version uploaded by another application
Other workspace settings can be pre-configured or updated, such as 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.
## Configuration Version
An example configuration version for a task named "cts-example" would have the folder structure below when running with the Terraform Cloud driver and using the default working directory.
```shell-session
$ tree sync-tasks/
sync-tasks/
└── cts-example/
├── main.tf
└── variables.tf
```
- `main.tf` - The main file contains the terraform block, provider blocks, and a module block calling the module configured for the task.
- `terraform` block - The corresponding provider source and versions for the task from the configuration files are placed into this block for the root module.
- `provider` blocks - The provider blocks generated in the root module resemble the `terraform_provider` blocks from the configuration for Consul-Terraform-Sync. They have identical arguments present and are set from the intermediate variable created per provider.
- `module` block - The module block is where the task's module is called as a [child module](https://www.terraform.io/docs/configuration/modules.html#calling-a-child-module). The child module contains the core logic for automation. Required and optional input variables are passed as arguments to the module.
- `variables.tf` - This file contains three types of variable declarations:
- `services` input variable (required) determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](/docs/nia/terraform-modules) for more details).
- Any additional [optional input variables](/docs/nia/terraform-modules#optional-input-variables) provided by Consul-Terraform-Sync that the module may include.
- Various intermediate variables used to configure providers. Intermediate provider variables are interpolated from the provider blocks and arguments configured in the Consul-Terraform-Sync configuration.
- `variables.module.tf` - This file is created if there are [variables configured for the task](/docs/nia/configuration#variable_files) and contains the interpolated variable declarations that match the variables from configuration. These are then used to proxy the configured variables to the module through explicit assignment in the module block.
## Variables
Consul-Terraform-Sync uses Terraform input variables to reflect the latest Consul service information. They are used as parameters for your Terraform module. Input variables are dynamic and are updated by the driver throughout the runtime of Consul-Terraform-Sync.
You can view the latest service information in the Terraform UI by navigating to that workspace and clicking the "Variables" tab in the workspace navigation.
[![CTS Workspace Variables](/img/nia/cts-tfc-workspace-variables.png)](/img/nia/cts-tfc-workspace-variables.png)
~> **Caution:** Dynamic variables maintained by Consul-Terraform-Sync are formatted for automation. Unexpected manual changes to these variables may result in automation errors.
## Setting Up Terraform Cloud Driver
### Deployment
Because a Consul-Terraform-Sync instance can only be configured with one driver, an instance can only be associated with either a Terraform driver or a Terraform Cloud driver. If there is a need to run both types of drivers, users will need to deploy a separate Consul-Terraform-Sync instance for each type of driver. Relatedly, if there is a need to run Consul-Terraform-Sync across multiple Terraform Enterprise organizations, users will need to deploy a separate instance for each organization.
### Required Setup
This section captures requirements for setting up Consul-Terraform-Sync to integrate with your [Terraform Enterprise](https://www.hashicorp.com/products/terraform/editions/enterprise) solution.
1. Hostname of your Terraform Enterprise, self-hosted distribution
1. Name of your organization
1. [Team API token](https://www.terraform.io/docs/cloud/users-teams-organizations/api-tokens.html#team-api-tokens) used for authentication with Terraform Enterprise
Prior to running Consul-Terraform-Sync with a Terraform Cloud driver, you will need an account and organization set up, as well as a dedicated token. We recommend using a team token that is restricted to [Manage Workspaces](https://www.terraform.io/docs/cloud/users-teams-organizations/teams.html#managing-workspace-access)-level permissions. Below are the steps for the recommended setup.
The first step is to create an account with your Terraform Cloud service. After creating an account, create a new [organization](https://www.terraform.io/docs/cloud/users-teams-organizations/organizations.html#creating-organizations) or select an existing organization. The address of your Terraform Cloud service will be used to configure the [`hostname`](/docs/nia/configuration#hostname), and the organization name will be used to configure the [`organization`](/docs/nia/configuration#organization) on the Terraform Cloud driver.
Once you have an account and organization, the next step is to [create a team](https://www.terraform.io/docs/cloud/users-teams-organizations/teams.html). We recommend using a dedicated team and team token to run and authenticate Consul-Terraform-Sync. Using a team token has the benefits of restricting organization permissions as well as associating Consul-Terraform-Sync automated actions with the team rather than an individual.
After creating a dedicated team, update the team's permissions with "Manage Workspaces" organization access-level. Consul-Terraform-Sync's main work revolves around creating and managing workspaces. Therefore restricting the dedicated team's permission to Manage Workspaces level is sufficient and reduces security risk.
[![CTS Terraform Team Setup](/img/nia/cts-tfc-team-setup.png)](/img/nia/cts-tfc-team-setup.png)
After setting the team's permissions, the final setup step is to [generate the associated team token](https://www.terraform.io/docs/cloud/users-teams-organizations/api-tokens.html#team-api-tokens), which can be done on the same team management page. This token will be used by Consul-Terraform-Sync for API authentication and will be used to configure the [`token`](/docs/nia/configuration#token-1) on the Terraform Cloud driver.
### Recommendations
We recommend configuring workspaces managed by Consul-Terraform-Sync with [run notifications](https://www.terraform.io/docs/cloud/workspaces/notifications.html) through the Terraform web application. Run notifications notify external systems about the progress of runs and could help notify users of Consul-Terraform-Sync events, particularly errored runs.
[![CTS Terraform Cloud Run Notifications](/img/nia/cts-tfc-run-notifications.png)](/img/nia/cts-tfc-run-notifications.png)
In order to configure a run notification, users can [manually create a notification configuration](https://www.terraform.io/docs/cloud/workspaces/notifications.html#creating-a-notification-configuration) for workspaces automated by Consul-Terraform-Sync. A workspace may already exist for a task if the workspace name is identical to the configured task's [`name`](/docs/nia/configuration#name-2). This may occur if Consul-Terraform-Sync has already already run and created the workspace for the task. This may also occur if the workspace is manually created for the task prior to Consul-Terraform-Sync running.

61
website/content/docs/nia/network-drivers/terraform.mdx Normal file
View File

@ -0,0 +1,61 @@
---
layout: docs
page_title: Terraform Driver
description: >-
Consul-Terraform-Sync Network Drivers with Terraform
---
# Terraform Driver
Consul-Terraform-Sync extends the Consul ecosystem to include Terraform as an officially supported tooling project. With the Terraform driver, Consul-Terraform-Sync installs the [Terraform CLI](https://www.terraform.io/downloads.html) locally and runs Terraform commands based on monitored Consul changes. This page details how the Terraform driver operates using local workspaces and templated files.
## Terraform CLI Automation
On startup, Consul-Terraform-Sync:
1. Downloads and installs Terraform
2. Prepares local workspace directories. Terraform configuration and execution for each task is organized as separate [Terraform workspaces](https://www.terraform.io/docs/state/workspaces.html). The state files for tasks are independent of each other.
3. Generates Terraform configuration files that make up the root module for each task.
Once all workspaces are set up, Consul-Terraform-Sync monitors the Consul catalog for service changes. When relevant changes are detected, the Terraform driver dynamically updates input variables for that task using a template to render them to a file named [`terraform.tfvars`](/docs/nia/network-drivers#terraform-tfvars). This file is passed as a parameter to the Terraform CLI when executing `terraform plan` and `terraform apply` to update your network infrastructure with the latest Consul service details.
### Local Workspaces
Within the Consul-Terraform-Sync configuration for a task, practitioners can select the desired module to run for the task as well as set the condition to execute the task. Each task executed by the Terraform driver corresponds to an automated root module that calls the selected module in an isolated Terraform environment. Consul-Terraform-Sync will manage concurrent execution of these tasks.
Autogenerated root modules for tasks are mantained in local subdirectories of the Consul-Terraform-Sync working directory. Each subdirectory represents the local workspace for a task. By default, the working directory `sync-tasks` is created in the current directory. To configure where Terraform configuration files are stored, set [`working_dir`](/docs/nia/configuration#working_dir) to the desired path or configure the [`task.working_dir`](/docs/nia/configuration#working_dir-1) individually.
~> **Note:** Although Terraform state files for task workspaces are independent, this does not guarantee the infrastructure changes from concurrent task executions are independent. Ensure that modules across all tasks are not modifying the same resource objects or have overlapping changes that may result in race conditions during automation.
### Root Module
The root module proxies Consul information, configuration, and other variables to the Terraform module for the task. The content of the files that make up the root module are sourced from Consul-Terraform-Sync configuration, information for task's module to use as the automation playbook, and information from Consul such as service information.
A working directory with one task named "cts-example" would have the folder structure below when running with the Terraform driver.
```shell-session
$ tree sync-tasks/
sync-tasks/
└── cts-example/
├── main.tf
├── variables.tf
├── terraform.tfvars
└── terraform.tfvars.tmpl
```
The following files of the root module are generated for each task. An [example of a root module created by Consul-Terraform-Sync](https://github.com/hashicorp/consul-terraform-sync/tree/master/examples) can be found in the project repository.
- `main.tf` - The main file contains the terraform block, provider blocks, and a module block calling the module configured for the task.
- `terraform` block - The corresponding provider source and versions for the task from the configuration files are placed into this block for the root module. The Terraform backend from the configuration is also templated here.
- `provider` blocks - The provider blocks generated in the root module resemble the `terraform_provider` blocks from the configuration for Consul-Terraform-Sync. They have identical arguments present and are set from the intermediate variable created per provider.
- `module` block - The module block is where the task's module is called as a [child module](https://www.terraform.io/docs/configuration/modules.html#calling-a-child-module). The child module contains the core logic for automation. Required and optional input variables are passed as arguments to the module.
- `variables.tf` - This file contains three types of variable declarations.
- `services` input variable (required) determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](/docs/nia/terraform-modules) for more details).
- Any additional [optional input variables](/docs/nia/terraform-modules#optional-input-variables) provided by Consul-Terraform-Sync that the module may include.
- Various intermediate variables used to configure providers. Intermediate provider variables are interpolated from the provider blocks and arguments configured in the Consul-Terraform-Sync configuration.
- `variables.module.tf` - This file is created if there are [variables configured for the task](/docs/nia/configuration#variable_files) and contains the interpolated variable declarations that match the variables from configuration. These are then used to proxy the configured variables to the module through explicit assignment in the module block.
- `providers.tfvars` - This file is created if there are [providers configured for the task](/docs/nia/configuration#providers) and defined [`terraform_provider` blocks](/docs/nia/configuration#terraform-provider). This file may contain sensitive information. To omit sensitive information from this file, you can [securely configure Terraform providers for Consul-Terraform-Sync](/docs/nia/configuration#securely-configure-terraform-providers) using environment variables or templating.
- `terraform.tfvars` - The variable definitions file is where the services input variable and any optional Consul-Terraform-Sync input variables are assigned values from Consul. It is periodically updated, typically when the task condition is met, to reflect the current state of Consul.
- `terraform.tfvars.tmpl` - The template file is used by Consul-Terraform-Sync to template information from Consul by using the HashiCorp configuration and templating library ([hashicorp/hcat](https://github.com/hashicorp/hcat)).
~> **Note:** Generated template and Terraform configuration files are crucial for the automation of tasks. Any manual changes to the files may not be preserved and could be overwritten by a subsequent update. Unexpected manual changes to the format of the files may cause automation to error.

41
website/content/docs/nia/tasks.mdx
View File

@ -38,9 +38,9 @@ Below are details on the types of execution conditions that Consul-Terraform-Syn
### Services Condition
The services condition is the default condition to execute a task. Tasks with the services condition monitor and execute on changes to a list of configured services.
The services condition is the default condition to execute a task. Tasks with the services condition monitor and execute on either changes to a list of configured services or changes to any services that match a given regex.
In order to configure a task with the services condition, the list of services to trigger the task must be configured in the task's [`services`](/docs/nia/configuration#services). The task's `condition` block can be left unconfigured since it is the default. See the [Services Condition](/docs/nia/configuration#services-condition) configuration section for more details.
In order to configure a task with the services condition, the list of services to trigger the task must be configured in the task's [`services`](/docs/nia/configuration#services) or a regex must be configured in the task's `condition` block. Only one of these two options can be configured for a single task. See the [Services Condition](/docs/nia/configuration#services-condition) configuration section for more details.
The services condition operates by monitoring the [Health List Nodes For Service API](/api-docs/health#list-nodes-for-service) and executing the task on any change of information for services configured. These changes include one or more changes to service values, like IP address, added or removed service instance, or tags. A complete list of values that would cause a task to run are expanded below:
@ -61,6 +61,43 @@ The services condition operates by monitoring the [Health List Nodes For Service
| `node_tagged_addresses` | List of explicit LAN and WAN IP addresses for the agent |
| `node_meta` | List of user-defined metadata key/value pairs for the node |
The services condition is the default behavior if no `condition` block is configured for a task. The two tasks below have equivalent behavior, which is to execute when any of the listed services have changes to the previously stated attributes.
```hcl
task {
name = "services_condition_task_1"
description = "execute on changes to api, db, and web services"
providers = ["my-provider"]
source = "path/to/services-condition-module"
services = ["api", "db", "web"]
}
task {
name = "services_condition_task_2"
description = "execute on changes to api, db, and web services"
providers = ["my-provider"]
source = "path/to/services-condition-module"
services = ["api", "db", "web"]
condition "services" {
}
}
```
Below is an example configuration for a task that will execute when a service with a name that matches the regular expression has a change. Note that because `regexp` is set, `task.services` is omitted.
```hcl
task {
name = "services_condition_task"
description = "execute on changes to services whose name starts with web"
providers = ["my-provider"]
source = "path/to/services-condition-module"
condition "services" {
regexp = "^web.*"
}
}
```
### Catalog-Services Condition

33
website/data/docs-nav-data.json
View File

@ -659,9 +659,40 @@
"title": "Terraform Modules",
"path": "nia/terraform-modules"
},
{
"title": "Enterprise",
"routes": [
{
"title": "Overview",
"path": "nia/enterprise"
},
{
"title": "License",
"path": "nia/enterprise/license"
},
{
"title": "Terraform Cloud Driver",
"href": "/docs/nia/network-drivers/terraform-cloud"
}
]
},
{
"title": "Network Drivers",
"path": "nia/network-drivers"
"routes": [
{
"title": "Overview",
"path": "nia/network-drivers"
},
{
"title": "Terraform",
"path": "nia/network-drivers/terraform"
},
{
"title": "Terraform Cloud",
"path": "nia/network-drivers/terraform-cloud"
}
]
},
{
"title": "Compatibility",

BIN
website/public/img/nia/cts-tfc-run-notifications.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 229 KiB

BIN
website/public/img/nia/cts-tfc-team-setup.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 288 KiB

BIN
website/public/img/nia/cts-tfc-workspace-variables.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 301 KiB

BIN
website/public/img/nia/cts-tfc-workspace.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 468 KiB