Configuration Options for Consul-Terraform-Sync

The Consul-Terraform-Sync daemon is configured using configuration files and supports HashiCorp Configuration Language (HCL) and JSON file formats.

Global Config Options

Top level options are reserved for configuring Consul-Terraform-Sync.

  1. log_level = "INFO"
  2. port = 8558
  3. syslog {
  4.   facility = "local2"
  5. }
  6. buffer_period {
  7.   enabled = true
  8.   min = "5s"
  9.   max = "20s"
  10. }
  • buffer_period - Configures the default buffer period for all tasks 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.
    • 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.
  • 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.

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 with, at least, the cert_file and 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.

To read more on suggestions for configuring the Consul agent, see run an agent.

  1. consul {
  2.   address = "consul.example.com"
  3.   auth {}
  4.   tls {}
  5.   token = null
  6.   transport {}
  7. }
  • address - (string: “localhost:8500”) Address is the address of the Consul agent. It may be an IP or FQDN.
  • auth - Auth is the HTTP basic authentication for communicating with Consul.
  • 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.
    • 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.
    • 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.
  • token - (string) The ACL token to use for client communication with the local Consul agent. The token can also be provided through the CONSUL_TOKEN or CONSUL_HTTP_TOKEN environment variables. More information on the required privileges required by Consul-Terraform-Sync are available in the Secure Consul-Terraform-Sync for Production tutorial
  • transport - Transport configures the low-level network connection details.
    • dial_keep_alive - (string: “30s”) The amount of time for keep-alives.
    • dial_timeout - (string: “30s”) The amount of time to wait to establish a connection.
    • disable_keep_alives - (bool) Determines if keep-alives should be used. Disabling this significantly decreases performance.
    • idle_conn_timeout - (string: “5s”) The timeout for idle connections.
    • max_idle_conns - (int: 0) The maximum number of total idle connections across all hosts. The limit is disabled by default.
    • max_idle_conns_per_host - (int: 100) The maximum number of idle connections per remote host. The majority of connections are established with one host, the Consul agent.
      • To achieve the shortest latency between a Consul service update to a task execution, configure max_idle_conns_per_host equal to or greater than the number of services in automation across all tasks.
      • This value should be lower than the configured http_max_conns_per_client for the Consul agent. If max_idle_conns_per_host and the number of services in automation is greater than the Consul agent limit, Consul-Terraform-Sync may error due to connection limits (status code 429). You may increase the agent limit with caution. Note: requests to the Consul agent made by Terraform subprocesses or any other process on the same host as Consul-Terraform-Sync will contribute to the Consul agent connection limit.
    • tls_handshake_timeout - (string: “10s”) amount of time to wait to complete the TLS handshake.

Service

A service block is an optional block to explicitly define configuration of services that Consul-Terraform-Sync monitors. A service block is only necessary for services that have non-default values e.g. custom datacenter. Services that do not have a service block configured will assume default values. To configure multiple services, specify multiple service blocks. For services to be included in task automation, the service must be included in the task.services field of a task block. If a service block is configured, the service can be referred in task.services by service name or ID. If a service block is not configured, it can only be referred to by service name.

  1. service {
  2.   name = "web"
  3.   datacenter = "dc1"
  4.   description = "all instances of the service web in datacenter dc1"
  5. }
  • datacenter - (string) The datacenter the service is deployed in.
  • description - (string) The human readable text to describe the service.
  • id - (string) ID identifies the service for Consul-Terraform-Sync. This is used to explicitly identify the service config for a task to use. If no ID is provided, the service is identified by the service name within a task definition.
  • name - (string: required) The Consul logical name of the service (required).

  • namespace

    Enterprise

    - (string: “default”) The namespace of the service. If not provided, the namespace will be inferred from the Consul-Terraform-Sync ACL token, or default to the default namespace.

  • tag - (string) Tag is used to filter nodes based on the tag for the service.
  • cts_user_defined_meta - (map[string]) User-defined metadata is a map of strings that will be appended to the service input variable for compatible Terraform modules. Not all modules may use this value. To determine if your task uses metadata or what the expected keys and format are, reference documentation for the module(s) configured for your tasks.
    • If multiple tasks depend on the same service but require different metadata, you can declare different sets of metadata for the same service. Define multiple service blocks for the service with unique IDs (and identical names) for those blocks. The metadata can then be separated per task based on the service IDs.

Task

A task block configures which task to run in automation for the selected services. The list of services can include services explicitly defined by a service block or implicitly declared by the service name. The task block may be specified multiple times to configure multiple tasks.

  1. task {
  2.   name = "taskA"
  3.   description = ""
  4.   enabled = true,
  5.   providers = []
  6.   services = ["web", "api"]
  7.   source = "org/example/module"
  8.   version = "1.0.0"
  9.   variable_files = []
  10. }
  • description - (string) The human readable text to describe the service.
  • name - (string: required) Name is the unique name of the task (required). A task name must start with a letter or underscore and may contain only letters, digits, underscores, and dashes.
  • 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 to the task.
  • services - (list[string]: required) 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.
  • 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, the source is the module path (local or remote). Read more on Terraform module source here.

  • variable_files - (list[string]) A list of paths to files containing variables for the task. For the Terraform driver, these are used as Terraform variable defintion (.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.

    1. address_group = "consul-services"
    2. tags = [
    3.   "consul-terraform-sync",
    4.   "terraform"
    5. ]

  • version - (string) The version of the provided source the task will use. For the 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. 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.

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.

  1. driver "terraform" {
  2.   log = false
  3.   persist_log = false
  4.   path = ""
  5.   working_dir = ""
  7.   backend "consul" {
  8.     gzip = true
  9.   }
  11.   required_providers {
  12.     myprovider = {
  13.       source = "namespace/myprovider"
  14.       version = "1.3.0"
  15.     }
  16.   }
  17. }
  • backend - (obj) The backend stores Terraform state files for each task. This option is similar to the Terraform backend configuration. 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 to configure Consul as the backend. 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.
  • 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 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 omittied, 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.

Terraform Provider

A terraform_provider block configures the options to interface with network infrastructure. Define a block for each provider required by the set of Terraform modules across all tasks. This block resembles provider blocks for Terraform configuration. To find details on how to configure a provider, refer to the corresponding documentation for the Terraform provider. The main directory of publicly available providers are hosted on the Terraform Registry.

The below configuration captures the general design of defining a provider using the AWS Terraform provider as an example.

  1. driver "terraform" {
  2.   required_providers {
  3.     aws = {
  4.       source = "hashicorp/aws"
  5.       version = "3.33.0"
  6.     }
  7.   }
  8. }
  10. terraform_provider "aws" {
  11.   # Configuration options
  12.   region = "us-east-1"
  13. }
  15. task {
  16.   source = "some/source"
  17.   providers = ["aws"]
  18.   services = ["web", "api"]
  19. }

Note: Provider arguments configured in Consul-Terraform-Sync configuration files are written in plain text to the generated terraform.tfvars file for each Terraform workspace that references the provider. To exclude arguments or dynamic values from rendering to local files in plain text, use task_env in addition to using dynamic configuration.

Securely Configure Terraform Providers

The terraform_provider block supports dynamically loading arguments and the local environment from other sources. This can be used to securely configure your Terraform provider from the shell environment, Consul KV, or Vault. Using the task_env meta-argument and template syntax below, you can avoid exposing sensitive values or credentials in plain text within configuration files for Consul-Terraform-Sync.

task_env and the template syntax for dynamic values are only supported within the terraform_provider block.

Provider Environment Variables

Terraform providers may support shell environment variables as values for some of their arguments. When available, we recommend using environment variables as a way to keep credentials out of plain-text configuration files. Refer to the official provider docs hosted on the Terraform Registry to find supported environment variables for a provider. By default, Consul-Terraform-Sync enables all Terraform workspaces to inherit from its environment.

The task_env block is a meta-argument available for the terraform_provider block that can be used to rename or scope the available environment to a selected set of variables. Passing sensitive values as environment variables will scope the values to only the tasks that require the provider.

  1. terraform_provider "foo" {
  2.   // Direct assignment of provider arguments are rendered in plain-text within
  3.   // the Consul-Terraform-Sync configuration and the generated terraform.tfvars
  4.   // file for the corresponding Terraform workspaces.
  5.   // token = "<token value>"
  7.   // Instead of configuring the token argument directly for the provider,
  8.   // use the provider's supported environment variable for the token argument.
  9.   // For example,
  10.   // $ export FOO_TOKEN = "<token value>"
  12.   // Dynamically assign the task's environment from the shell env, Consul KV,
  13.   // Vault.
  14.   task_env {
  15.     "FOO_TOKEN" = "{{ env \"CTS_FOO_TOKEN\" }}"
  16.   }
  17. }

Security note: Consul-Terraform-Sync does not prevent sensitive values from being written to Terraform state files. We recommend securing state files in addition to securely configuring Terraform providers. Options for securing state files can be set within driver.backend based on the backend used. For example, Consul KV is the default backend and can be secured with ACLs for KV path. For other backends, we recommend enabling encryption, if applicable.

Load Dynamic Values

Load dynamic values for Terraform providers with integrated template syntax.

Env

env reads the given environment variable accessible to Consul-Terraform-Sync.

  1. terraform_provider "example" {
  2.   address = "{{ env \"EXAMPLE_HOSTNAME\" }}"
  3. }

Consul

key queries the key’s value in the KV store of the Consul server configured in the required consul block.

  1. terraform_provider "example" {
  2.   value = "{{ key \"path/example/key\" }}"
  3. }

Vault

with secret queries the Vault KV secrets engine. Vault is an optional source that require operators to configure the Vault client with a vault block. Access the secret using template dot notation Data.data.<secret_key>.

  1. vault {
  2.   address = "vault.example.com"
  3. }
  5. terraform_provider "example" {
  6.   token = "{{ with secret \"secret/my/path\" }}{{ .Data.data.foo }}{{ end }}"
  7. }
Vault Configuration
  • address - (string) The URI of the Vault server. This can also be set via the VAULT_ADDR environment variable.
  • enabled - (bool) Enabled controls whether the Vault integration is active.
  • namespace - (string) Namespace is the Vault namespace to use for reading secrets. This can also be set via the VAULT_NAMESPACE environment variable.
  • renew_token - (bool) Renews the Vault token. This can also be set via the VAULT_RENEW_TOKEN environment variable.
  • tls - (tls block) TLS indicates the client should use a secure connection while talking to Vault. Supports the environment variables:
  • token - (string) Token is the Vault token to communicate with for requests. It may be a wrapped token or a real token. This can also be set via the VAULT_TOKEN environment variable, or via the VaultAgentTokenFile.
  • vault_agent_token_file - (string) The path of the file that contains a Vault Agent token. If this is specified, Consul-Terraform-Sync will not try to renew the Vault token.
  • transport - (transport block) Transport configures the low-level network connection details.
  • unwrap_token - (bool) Unwraps the provided Vault token as a wrapped token.

Note: Vault credentials are not accessible by tasks and the associated Terraform configurations, including automated Terraform modules. If the task requires Vault, you will need to seprately configure the Vault provider and explicitly include it in the task.providers list.

Multiple Provider Configurations

Consul-Terraform-Sync supports the Terraform feature to define multiple configurations for the same provider by utilizing the alias meta-argument. Define multiple provider blocks with the same provider name and set the alias to a unique value across a given provider. Select which provider configuration to use for a task by specifying the configuration with the provider name and alias (<name>.<alias>) within the list of providers in the task.provider parameter. A task can use multiple providers, but only one provider instance of a provider is allowed per task.

The example Consul-Terraform-Sync configuration below defines two similar tasks executing the same module with different instances of the AWS provider.

  1. terraform_provider "aws" {
  2.   alias = "a"
  3.   profile = "team-a"
  4.   task_env {
  5.     "AWS_ACCESS_KEY_ID" = "{{ env \"CTS_AWS_ACCESS_KEY_ID_A\" }}"
  6.   }
  7. }
  9. terraform_provider "aws" {
  10.   alias = "b"
  11.   profile = "team-b"
  12.   task_env {
  13.     "AWS_ACCESS_KEY_ID" = "{{ env \"CTS_AWS_ACCESS_KEY_ID_B\" }}"
  14.   }
  15. }
  17. terraform_provider "dns" {
  18.   // ...
  19. }
  21. task {
  22.   name = "task-a"
  23.   source = "org/module"
  24.   providers = ["aws.a", "dns"]
  25.   // ...
  26. }
  28. task {
  29.   name = "task-b"
  30.   source = "org/module"
  31.   providers = ["aws.b", "dns"]
  32.   // ...
  33. }