mirror of https://github.com/status-im/consul.git
Docs: Nia/docs tech preview (#8908)
* Add outline and basic content for Tech Preview docs * Add Tech Preview tag * Add auto-labler for Consul Terrform Sync * Add Consul Terraform Sync config docs (#8837) * CLI Docs for Consul Terraform Sync * Task Docs for Consul Terraform Sync * Add docs for NIA Terraform driver (#8871) * Update Installation Docs for Consul Terraform Sync * Initial high level architecture overview (#8872) * Docs: compatible Terraform modules for Consul-Terraform-Sync (#8887) * Update Requirements Docs for Consul Terraform Sync * Remove empty partner module sections
This commit is contained in:
Sabeen Syed
GitHub
parent
ea77eccb14
commit
bd7433c808
|
|
@ -29,6 +29,8 @@ theme/connect:
|
|||
- '(Connect|connect|service\smesh|mesh|proxy|gateway)'
|
||||
theme/consul-nomad:
|
||||
- '(nomad|Nomad)'
|
||||
theme/consul-terraform-sync:
|
||||
- '(nia|NIA|Network\sInfrastructure\sAutomation)'
|
||||
theme/consul-vault:
|
||||
- '(vault|Vault)'
|
||||
# theme/contributing:
|
||||
|
|
|
|||
|
|
@ -32,6 +32,8 @@ theme/connect:
|
|||
- connect/**/*
|
||||
- agent/connect/**/*
|
||||
# theme/consul-nomad:
|
||||
theme/consul-terraform-sync:
|
||||
- website/pages/docs/nia/**/*
|
||||
# theme/consul-vault:
|
||||
theme/contributing:
|
||||
- .github/**/*
|
||||
|
|
|
|||
|
|
@ -163,6 +163,22 @@ export default [
|
|||
'helm',
|
||||
],
|
||||
},
|
||||
|
||||
{
|
||||
category: 'nia',
|
||||
content: [
|
||||
{
|
||||
category: 'installation',
|
||||
name: 'Get Started',
|
||||
content: ['install', 'requirements', 'configuration', 'run'],
|
||||
},
|
||||
'architecture',
|
||||
'cli',
|
||||
'tasks',
|
||||
'network-drivers',
|
||||
],
|
||||
},
|
||||
|
||||
{
|
||||
category: 'dynamic-app-config',
|
||||
name: 'Dynamic App Configuration',
|
||||
|
|
|
|||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Architecture
|
||||
sidebar_title: Architecture
|
||||
description: >-
|
||||
Consul-Terraform-Sync Architecture
|
||||
---
|
||||
|
||||
# Consul-Terraform-Sync Architecture
|
||||
|
||||
Consul-Terraform-Sync is a service-oriented tool for managing
|
||||
network infrastructure near real-time. Consul-Terraform-Sync runs as a daemon
|
||||
and integrates the network topology maintained by your Consul cluster with your
|
||||
network infrastructure to dynamically secure and connect services.
|
||||
|
||||
## 10,000 Foot View
|
||||
|
||||
[](/img/nia-highlevel-diagram.png)
|
||||
|
||||
The diagram shows Consul-Terraform-Sync monitoring the Consul service catalog
|
||||
for updates and utilizing Terraform to update the state of the infrastructure.
|
||||
|
||||
There are two principal aspects of Sync to know about corresponding to the
|
||||
lines to Consul and Terraform in the diagram above. The line to Consul
|
||||
represents the Watchers monitoring the state of Consul's service catalog (and
|
||||
possibly KV store) while the line to Terraform represents tasks being run to
|
||||
update the infrastructure.
|
||||
|
||||
## Watcher and Views
|
||||
|
||||
Consul-Terraform-Sync monitors Consul for updates utilizing Consul's [Blocking
|
||||
Queries](/api-docs/features/blocking) whenever supported, falling back on
|
||||
polling when not. The watcher maintains a separate thread (known internally as
|
||||
a view) for each value monitored, running any tasks that depend on that watched
|
||||
value whenever it's updated. Say, for example, running a task to update a
|
||||
proxy when an instance goes unhealthy.
|
||||
|
||||
## Tasks
|
||||
|
||||
A task is the action triggered by the updated data monitored in Consul. It
|
||||
takes the that dynamic service data and translates it into a call to the
|
||||
infrastructure application to configure it with the updates. It uses a driver
|
||||
to push out these updates, the initial driver being a local Terraform run. An
|
||||
example of a task is to automate a firewall security policy rule with
|
||||
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/installation/requirements#how-to-create-a-compatible-terraform-module) a wide variety of
|
||||
infrastructure applications.
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Consul-Terraform-Sync CLI
|
||||
sidebar_title: CLI
|
||||
description: >-
|
||||
How to use the Consul-Terraform-Sync CLI
|
||||
---
|
||||
|
||||
# Consul-Terraform-Sync Command (CLI)
|
||||
|
||||
Consul-Terraform-Sync is controlled via an easy to use command-line interface (CLI). Consul-Terraform-Sync is only a single command-line application: `consul-terraform-sync`.
|
||||
|
||||
Since there is no default configuration to run Consul-Terraform-Sync in a meaningful way, setting a configuration flag `-config-file` or `-config-dir` is required. For example:
|
||||
|
||||
```shell-session
|
||||
$ consul-terraform-sync -config-file=config.hcl
|
||||
```
|
||||
|
||||
To view a list of available flags, use the `-help` or `-h` flag.
|
||||
|
||||
## Modes
|
||||
|
||||
Consul-Terraform-Sync can be run in different modes.
|
||||
|
||||
### Daemon Mode
|
||||
|
||||
Flag: none
|
||||
|
||||
Behavior: This is the default mode in which Consul-Terraform-Sync passes through a once-mode phase and then turns into a long running process. During the once-mode phase, the daemon will exit with a non-zero status if it encounters an error. After successfully passing through once-mode phase, it will begin a long running process in which errors are logged and exiting is not expected behavior.
|
||||
|
||||
Usage: Intended to be run as a long running process after running once-mode successfully for given configuration and tasks.
|
||||
|
||||
### Once Mode
|
||||
|
||||
Flag: `-once`
|
||||
|
||||
Behavior: Consul-Terraform-Sync will run all tasks once with buffer periods disabled and exit. On encountering an error before completing, Consul-Terraform-Sync will exit with a non-zero status.
|
||||
|
||||
Usage: Intended to be run before daemon-mode in order to confirm configuration is accurate and tasks update network infrastructure as expected.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Network Infrastructure Automation <sup>Tech Preview</sup>
|
||||
sidebar_title: Network Infrastructure Automation <sup>Tech Preview</sup>
|
||||
description: >-
|
||||
Network Infrastructure Automation (NIA) is the concept of dynamically updating infrastructure devices triggered by service changes. Consul-Terraform-Sync is a tool that performs NIA and utilizes Consul as a data source that contains networking information about services and monitors those services. Terraform is used as the underlying automation tool and leverages the Terraform provider ecosystem to drive relevant changes to the network infrastructure.
|
||||
---
|
||||
|
||||
# Network Infrastructure Automation <sup>Tech Preview</sup>
|
||||
|
||||
Network Infrastructure Automation (NIA) enables dynamic updates to network infrastructure devices triggered by service changes. Consul-Terraform-Sync utilizes Consul as a data source that contains networking information about services and monitors those services. Terraform is used as the underlying automation tool and leverages the Terraform provider ecosystem to drive relevant changes to the network infrastructure.
|
||||
|
||||
Consul-Terraform-Sync executes one or more automation tasks with the most recent service variable values from the Consul service catalog. Each task consists of a runbook automation written as a Consul-Terraform-Sync compatible Terraform module using resources and data sources for the underlying network infrastructure. The `consul-terraform-sync` daemon runs on the same node as a Consul agent.
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Application teams must wait for manual changes in the network to release, scale up/down and re-deploy their applications.** This creates a bottleneck, especially in frequent workflows related to scaling up/down the application, breaking the DevOps goal of self-service enablement. Consul-Terraform-Sync automates this process, thus decreasing the possibility of human error in manually editing configuration files, as well as decreasing the overall time taken to push out configuration changes.
|
||||
|
||||
**Networking and security teams cannot scale processes to the speed and changes needed.** Manual approaches don't scale well, causing backlogs in network and security teams. Even in organizations that have some amount of automation (such as scripting), there is a need for an accurate, real-time source of data to trigger and drive their network automation workflows. Consul-Terraform-Sync runs in near real-time to keep up with the rate of change.
|
||||
|
||||
## Glossary
|
||||
|
||||
**Consul-Terraform-Sync** - GitHub repo 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 Infrastructure Automation (NIA)** - Enables dynamic updates to network infrastructure devices triggered by service changes.
|
||||
|
||||
**Tasks** - A task is the translation of dynamic service information from the Consul Catalog into network infrastructure changes downstream.
|
||||
|
||||
**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.
|
||||
|
|
@ -0,0 +1,264 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Configure Consul-Terraform-Sync
|
||||
sidebar_title: Configuration
|
||||
description: >-
|
||||
Consul-Terraform-Sync requires a Terraform Provider, a Terraform Module and a running Consul Cluster outside of the consul-terraform-sync daemon.
|
||||
---
|
||||
|
||||
# Configuration Options for Consul-Terraform-Sync
|
||||
|
||||
The Consul-Terraform-Sync daemon is configured using configuration files and supports [HashiCorp Configuration Language](https://github.com/hashicorp/hcl) (HCL) and JSON file formats.
|
||||
|
||||
## Example
|
||||
|
||||
An example HCL configuration is shown below to automate a task to execute a Terraform module for 2 services.
|
||||
|
||||
```hcl
|
||||
log_level = "info"
|
||||
|
||||
consul {
|
||||
address = "consul.example.com"
|
||||
}
|
||||
|
||||
buffer_period {
|
||||
min = "5s"
|
||||
max = "20s"
|
||||
}
|
||||
|
||||
task {
|
||||
name = "website-x"
|
||||
description = "automate services for website-x"
|
||||
source = "namespace/example/module"
|
||||
version = "1.0.0"
|
||||
providers = ["myprovider"]
|
||||
services = ["web", "api"]
|
||||
wait {
|
||||
min = "10s"
|
||||
}
|
||||
}
|
||||
|
||||
driver "terraform" {
|
||||
required_providers {
|
||||
myprovider = {
|
||||
source = "namespace/myprovider"
|
||||
version = "1.3.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "myprovider" {
|
||||
address = "myprovider.example.com"
|
||||
}
|
||||
```
|
||||
|
||||
## Global Config Options
|
||||
|
||||
Top level options are reserved for configuring Consul-Terraform-Sync.
|
||||
|
||||
```hcl
|
||||
log_level = "INFO"
|
||||
syslog {}
|
||||
buffer_period {
|
||||
enabled = true
|
||||
min = "5s"
|
||||
max = "20s"
|
||||
}
|
||||
```
|
||||
|
||||
* `log_level` - `(string: "WARN")` The log level to use for Consul-Terraform-Sync logging.
|
||||
* `syslog` - Specifies the syslog server for logging.
|
||||
* `enabled` - `(bool: false)` Enable syslog logging. Specifying other option also enables syslog logging.
|
||||
* `facility` - `(string: <none>)` Name of the syslog facility to log to.
|
||||
* `name` - `(string: "consul-terraform-sync")` Name to use for the daemon process when logging to syslog.
|
||||
* `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.
|
||||
* `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`.
|
||||
|
||||
## 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.
|
||||
|
||||
```hcl
|
||||
consul {
|
||||
address = "consul.example.com"
|
||||
auth {}
|
||||
tls {}
|
||||
token = null
|
||||
transport {}
|
||||
}
|
||||
```
|
||||
|
||||
* `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.
|
||||
* `enabled` - `(bool: false)`
|
||||
* `username` - `(string: <none>)`
|
||||
* `password` - `(string: <none>)`
|
||||
* `tls` - Configure TLS to use a secure client connection with Consul. This requires Consul to be configured to serve HTTPS.
|
||||
* `enabled` - `(bool: false)` 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: <none>)` 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: <none>)` The CA file to use for talking to Consul over TLS. Can also be provided though the `CONSUL_CACERT` environment variable.
|
||||
* `ca_path` - `(string: <none>)` 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: <none>)` 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: <none>)` 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: <none>)` 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.
|
||||
* `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: false)` Determines if keep-alives should be used. Disabling this significantly decreases performance.
|
||||
* `idle_conn_timeout` - `(string: "90s")` The timeout for idle connections.
|
||||
* `max_idle_conns` - `(int: 100)` The maximum number of total idle connections.
|
||||
* `max_idle_conns_per_host` - `(int: 1)` The maximum number of idle connections per remote host.
|
||||
* `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](#task). 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.
|
||||
|
||||
```hcl
|
||||
service {
|
||||
name = "web"
|
||||
datacenter = "dc1"
|
||||
description = "all instances of the service web in datacenter dc1"
|
||||
}
|
||||
```
|
||||
|
||||
* `datacenter` - `(string: <none>)` The datacenter the service is deployed in.
|
||||
* `description` - `(string: <none>)` The human readable text to describe the service.
|
||||
* `id` - `(string: <none>)` 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](#task).
|
||||
* `name` - `(string: <required>)` The Consul logical name of the service (required).
|
||||
* `namespace` <EnterpriseAlert inline /> - `(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: <none>)` Tag is used to filter nodes based on the tag for the service.
|
||||
|
||||
## 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.
|
||||
|
||||
```hcl
|
||||
task {
|
||||
name = "taskA"
|
||||
description = ""
|
||||
providers = []
|
||||
services = ["web", "api"]
|
||||
source = "org/example/module"
|
||||
version = "1.0.0"
|
||||
variable_files = []
|
||||
}
|
||||
```
|
||||
|
||||
* `description` - `(string: <none>)` 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.
|
||||
* `providers` - `(list(string): [])` Providers is the list of provider names the task is dependent on. This is used to map [provider configuration](#provider) to the task.
|
||||
* `services` - `(list(string): [])` 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](#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 defintion (`.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 providers using [provider blocks](#provider).*
|
||||
```hcl
|
||||
address_group = "consul-services"
|
||||
tags = [
|
||||
"consul-terraform-sync",
|
||||
"terraform"
|
||||
]
|
||||
```
|
||||
* `version` - `(string: <none>)` 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.
|
||||
* `enabled` - `(bool: false)` 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 does not need to be explicitly configured and has reasonable default values.
|
||||
|
||||
```hcl
|
||||
driver "terraform" {
|
||||
log = false
|
||||
persist_log = false
|
||||
path = ""
|
||||
working_dir = ""
|
||||
|
||||
backend "consul" {
|
||||
scheme = "https"
|
||||
}
|
||||
|
||||
required_providers {
|
||||
myprovider = {
|
||||
source = "namespace/myprovider"
|
||||
version = "1.3.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* `backend` - `(obj: optional)` 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/backends/types/consul.html). Consul backend is the only supported backend at this time. If omitted, Consul-Terraform-Sync will generate default values and use configuration from the [`consul` block](#consul). 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: false)` 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: optional)` 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.
|
||||
* `persist_log` - `(bool: false)` 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)` 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.
|
||||
* `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`.
|
||||
|
||||
## Provider
|
||||
|
||||
A `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](https://www.terraform.io/docs/configuration/providers.html). 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](https://registry.terraform.io/browse/providers).
|
||||
|
||||
The below configuration captures the general design of defining a provider using the [Vault Terraform provider](https://registry.terraform.io/providers/hashicorp/vault/latest/docs) as an example.
|
||||
|
||||
```hcl
|
||||
driver "terraform" {
|
||||
required_providers {
|
||||
vault = {
|
||||
source = "hashicorp/vault"
|
||||
version = "2.13.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
provider "vault" {
|
||||
address = "vault.example.com"
|
||||
}
|
||||
|
||||
task {
|
||||
source = "some/source"
|
||||
providers = ["vault"]
|
||||
services = ["web", "api"]
|
||||
}
|
||||
```
|
||||
|
||||
### Multiple Provider Configurations
|
||||
|
||||
Consul-Terraform-Sync supports the [Terraform feature to define multiple configurations](https://www.terraform.io/docs/configuration/providers.html#alias-multiple-provider-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`](#task) 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 Vault provider.
|
||||
|
||||
```hcl
|
||||
provider "vault" {
|
||||
alias = "a"
|
||||
address = "vault.example.com"
|
||||
namespace = "team-a"
|
||||
}
|
||||
|
||||
provider "vault" {
|
||||
alias = "b"
|
||||
address = "vault.internal.com"
|
||||
namespace = "team-b"
|
||||
}
|
||||
|
||||
provider "dns" {
|
||||
// ...
|
||||
}
|
||||
|
||||
task {
|
||||
name = "task-a"
|
||||
source = "org/module"
|
||||
providers = ["vault.a", "dns"]
|
||||
// ...
|
||||
}
|
||||
|
||||
task {
|
||||
name = "task-b"
|
||||
source = "org/module"
|
||||
providers = ["vault.b", "dns"]
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Install Consul and Consul-Terraform-Sync
|
||||
sidebar_title: Installation
|
||||
description: >-
|
||||
Consul-Terraform-Sync is a daemon that runs alongside Consul. Consul-Terraform-Sync is not included with the Consul binary and will need to be installed separately.
|
||||
---
|
||||
|
||||
# Install Consul-Terraform-Sync
|
||||
|
||||
## Installing Consul-Terraform-Sync
|
||||
|
||||
To install Consul-Terraform-Sync, find the [appropriate package](https://releases.hashicorp.com/consul-terraform-sync/) for your system and download it as a zip archive. Unzip the package to extract the binary named consul-terraform-sync. Move the consul-terraform-sync binary to a location available on your PATH.
|
||||
|
||||
```shell-session
|
||||
$ mv ~/Downloads/consul-terraform-sync /usr/local/bin/consul-terraform-sync
|
||||
```
|
||||
|
||||
You can also install Consul-Terraform-Sync as a [Docker container](https://hub.docker.com/u/hashicorp/consul-terraform-sync) or build the binary from [source](https://github.com/hashicorp/consul-terraform-sync).
|
||||
|
||||
Once installed, verify the installation works by prompting the help option.
|
||||
|
||||
```shell-session
|
||||
$ consul-terraform-sync -h
|
||||
Usage of consul-terraform-sync:
|
||||
-config-dir value
|
||||
A directory to load files for configuring Sync. Configuration files
|
||||
require an .hcl or .json file extention in order to specify their format.
|
||||
This option can be specified multiple times to load different directories.
|
||||
-config-file value
|
||||
A file to load for configuring Sync. Configuration file requires an
|
||||
.hcl or .json extension in order to specify their format. This option can
|
||||
be specified multiple times to load different configuration files.
|
||||
-once
|
||||
Render templates and run tasks once. Does not run the process as a daemon
|
||||
and disables wait timers.
|
||||
-version
|
||||
Print the version of this daemon.
|
||||
```
|
||||
|
||||
## Connect your Consul Cluster
|
||||
|
||||
Consul-Terraform-Sync connects with your Consul cluster in order to monitor the Consul catalog for service changes. These service changes lead to downstream updates to your network devices. You can configure your Consul cluster in Consul-Terraform-Sync with the [Consul block](/docs/nia/installation/configuration#consul). Below is an example:
|
||||
|
||||
```hcl
|
||||
consul {
|
||||
address = "localhost:8500"
|
||||
token = "my-consul-acl-token"
|
||||
}
|
||||
```
|
||||
|
||||
## Connect your Network Device
|
||||
|
||||
Consul-Terraform-Sync interacts with your network device through a network driver. For the Terraform network driver, Consul-Terraform-Sync uses Terraform providers to make changes to your network infrastructure resources. You can reference existing provider docs on the Terraform Registry to configure each provider or create a new Terraform provider.
|
||||
|
||||
Once you have identified a Terraform provider for all of your network devices, you can configure them in Consul-Terraform-Sync with a [provider block](/docs/nia/installation/configuration#provider) for each network device. Below is an example:
|
||||
|
||||
```hcl
|
||||
provider "fake-firewall" {
|
||||
address = "10.10.10.10"
|
||||
username = "admin"
|
||||
password = "password123"
|
||||
}
|
||||
```
|
||||
|
||||
This provider is then used by task(s) to execute a Terraform module that will update the related network device.
|
||||
|
||||
### Multiple Instances per Provider
|
||||
|
||||
You might have multiple instances of the same type of network device; for example, multiple instances of a firewall or load balancer. You can configure each instance with its own provider block and distinguish it by the `alias` meta-argument. See [multiple provider configurations](/docs/nia/installation/configuration#multiple-provider-configurations) for more details and an example of the configuration.
|
||||
|
|
@ -0,0 +1,183 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Requirements
|
||||
sidebar_title: Requirements
|
||||
description: >-
|
||||
Consul-Terraform-Sync requires a Terraform Provider, a Terraform Module, and a running Consul cluster outside of the consul-terraform-sync daemon.
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
|
||||
## Run a Consul Cluster
|
||||
|
||||
Below are several steps towards a minimum Consul setup required for running Consul-Terraform-Sync.
|
||||
|
||||
### Install Consul
|
||||
|
||||
Consul-Terraform-Sync is a daemon that runs alongside Consul, similar to other Consul ecosystem tools like Consul Template. Consul-Terraform-Sync is not included with the Consul binary and needs to be installed separately.
|
||||
|
||||
To install a local Consul agent, refer to the [Getting Started: Install Consul Tutorial](https://learn.hashicorp.com/tutorials/consul/get-started-install).
|
||||
|
||||
### Run an Agent
|
||||
|
||||
The Consul agent must be running in order to dynamically update network devices. To run the local Consul agent, you can run Consul in development mode which can be started with `consul agent -dev` for simplicity. For more details on running Consul agent, refer to the [Getting Started: Run the Consul Agent Tutorial](https://learn.hashicorp.com/tutorials/consul/get-started-agent?in=consul/getting-started).
|
||||
|
||||
### Register Services
|
||||
|
||||
Consul-Terraform-Sync monitors Consul catalog for service changes which lead to downstream changes to your network devices. Without services, your Consul-Terraform-Sync daemon will be operational but idle. You can register services with your Consul agent either by loading a service definition or by HTTP API request.
|
||||
|
||||
If you are running Consul in development mode, below is an example of registering a service by HTTP API request:
|
||||
|
||||
```shell-session
|
||||
$ echo '{
|
||||
"ID": "web",
|
||||
"Name": "web",
|
||||
"Address": "10.10.10.10",
|
||||
"Port": 8000
|
||||
}' > payload.json
|
||||
|
||||
$ curl --request PUT --data @payload.json http://localhost:8500/v1/agent/service/register
|
||||
```
|
||||
|
||||
The above example registers a service named "web" with your Consul agent. This represents a non-existent web service running at 10.10.10.10:8000. Your web service is now available for Consul-Terraform-Sync to consume. In Consul-Terraform-Sync, you can optionally configure the web service with a [service block](/docs/nia/installation/configuration#service) if it has any non-default values. You can also have Consul-Terraform-Sync monitor the web service to execute a task and update network device(s) by configuring "web" in [`task.services`](/docs/nia/installation/configuration#services) of a task block.
|
||||
|
||||
For more details on registering a service by HTTP API request, refer to the [register service API docs](https://www.consul.io/api-docs/agent/service#register-service).
|
||||
|
||||
For more details on registering a service by loading a service definition, refer to the [Getting Started: Register a Service with Consul Service Discovery Tutorial](https://learn.hashicorp.com/tutorials/consul/get-started-service-discovery?in=consul/getting-started).
|
||||
|
||||
### Run a Cluster
|
||||
|
||||
The previous steps of installing and running a single Consul agent then registering a single service is sufficient to meaningfully start running Consul-Terraform-Sync.
|
||||
|
||||
If you would like to run a Consul cluster rather than a single agent, refer to [Getting Started: Create a Local Consul Datacenter](https://learn.hashicorp.com/tutorials/consul/get-started-create-datacenter?in=consul/getting-started). This will walk you through the steps of running multiple Consul agents and then joining them together into a cluster.
|
||||
|
||||
## Network Infrastructure (using a Terraform Provider)
|
||||
|
||||
Consul-Terraform-Sync integrations for the Terraform driver utilizes Terraform providers as plugins to interface with specific network infrastructure platforms. The Terraform driver of Consul-Terraform-Sync inherits the expansive collection of Terraform providers to integrate with, and with release of [Terraform 0.13](https://www.hashicorp.com/blog/announcing-hashicorp-terraform-0-13/), this extends to include providers written by the community too by using [provider source](https://www.hashicorp.com/blog/adding-provider-source-to-hashicorp-terraform/).
|
||||
|
||||
### Finding and Using Terraform Providers
|
||||
|
||||
To find providers for the infrastructure platforms you use, browse the providers section of the [Terraform Registry](https://registry.terraform.io/browse/providers).
|
||||
|
||||
### How to Create a Provider
|
||||
|
||||
If there is no existing Terraform provider, a new Terraform provider can be [created](https://learn.hashicorp.com/tutorials/terraform/provider-setup) and [published](https://www.terraform.io/docs/registry/providers/publishing.html). The provider can then be used within a network integration task by authoring a compatible Terraform module.
|
||||
|
||||
## Network Integration (using a Terraform Module)
|
||||
|
||||
Working with a Terraform provider, you can write an integration task for Consul-Terraform-Sync by creating a Terraform module that is compatible with the Terraform driver.
|
||||
|
||||
### Using Terraform Modules
|
||||
|
||||
The modules listed below are availabe to use and are compatible with Consul-Terraform-Sync.
|
||||
|
||||
#### Palo Alto Networks
|
||||
- Dynamic Address Group (DAG) Tags: [Terraform Registry](https://registry.terraform.io/modules/devarshishah3/dag-nia/panos) / [GitHub](https://github.com/devarshishah3/terraform-panos-ag-dag-nia)
|
||||
|
||||
### How to Create a Compatible Terraform Module
|
||||
|
||||
-> **Note:** Consul-Terraform-Sync is currently in Technology Preview. Specifications in this section may change going into Beta release.
|
||||
|
||||
You can read more on how to [create a module](https://www.terraform.io/docs/modules/index.html) or work through a [tutorial to build a module](https://learn.hashicorp.com/tutorials/terraform/module-create). Consul-Terraform-Sync is designed to integrate with any module that satisfies the specifications in the following section.
|
||||
|
||||
#### Module Specifications
|
||||
|
||||
Compatible modules for Consul-Terraform-Sync follow the [standard module](https://www.terraform.io/docs/modules/index.html#standard-module-structure) structure. Modules can use syntax supported by Terraform version 0.13 and newer. There are **2 required elements for compatibility:**
|
||||
|
||||
1. **Root module** - Terraform has one requirement for files in the root directory of the repository to function as the primary entrypoint for the module. It should encapsulate the core logic to be used by Consul-Terraform-Sync for task automation. `main.tf` is the recommended filename for the main file where resources are created.
|
||||
2. **`services` input variable** - Consul-Terraform-Sync requires all modules to have the following input variable declared within the root module. The declaration of the `services` variable can be included at the top of the suggested `variables.tf` file where other input variables are commonly declared. This variable functions as the response object from the Consul catalog API and surfaces network information to be consumed by the module. It is structured as a map of objects.
|
||||
|
||||
```hcl
|
||||
variable "services" {
|
||||
description = "Consul services monitored by Consul-Terraform-Sync"
|
||||
type = map(
|
||||
object({
|
||||
id = string
|
||||
name = string
|
||||
address = string
|
||||
port = number
|
||||
meta = map(string)
|
||||
tags = list(string)
|
||||
namespace = string
|
||||
status = string
|
||||
|
||||
node = string
|
||||
node_id = string
|
||||
node_address = string
|
||||
node_datacenter = string
|
||||
node_tagged_addresses = map(string)
|
||||
node_meta = map(string)
|
||||
})
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Keys of the `services` map are unique identifiers of the service across Consul agents and data centers. Keys follow the format `service-id.node.datacenter` (or `service-id.node.namespace.datacenter` for Consul Enterprise).
|
||||
|
||||
| Attribute | Description |
|
||||
| -- | -- |
|
||||
| `id` | A unique Consul ID for this service. This is unique per Consul agent. |
|
||||
| `name` | The logical name of the service. Many service instances may share the same logical service name. |
|
||||
| `address` | IP address of the service host -- if empty, node address should be used. |
|
||||
| `port` | Port number of the service |
|
||||
| `meta` | List of user-defined metadata key/value pairs for the service |
|
||||
| `tags` | List of tags for the service |
|
||||
| `namespace` | Consul Enterprise namespace of the service instance |
|
||||
| `status` | Representative status for the service instance based on an aggregate of the list of health checks |
|
||||
| `node` | Name of the Consul node on which the service is registered |
|
||||
| `node_id` | ID of the node on which the service is registered. |
|
||||
| `node_address` | The IP address of the Consul node on which the service is registered. |
|
||||
| `node_datacenter` | Data center of the Consul node on which the service is registered. |
|
||||
| `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 |
|
||||
|
||||
Terraform variables when passed as module arguments can be [lossy for object types](https://www.terraform.io/docs/configuration/types.html#conversion-of-complex-types). This allows Consul-Terraform-Sync to declare the full variable with every object attribute in the generated root module, and pass the variable to a child module that contains a subset of these attributes for its variable declaration. Modules compatible with Consul-Terraform-Sync may simplify the services variable within the module by omitting unused attributes. For example, the following services variable has 4 attributes with the rest omitted.
|
||||
|
||||
```hcl
|
||||
variable "services" {
|
||||
description = "Consul services monitored by Consul-Terraform-Sync"
|
||||
type = map(
|
||||
object({
|
||||
id = string
|
||||
name = string
|
||||
node_address = string
|
||||
port = number
|
||||
status = string
|
||||
})
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### Module Input Variables
|
||||
|
||||
Network infrastructure differs vastly across teams and organizations, and the automation needs of practitioners are unique based on their existing setup. [Input variables](https://www.terraform.io/docs/configuration/variables.html) can be used to serve as customization parameters to the module for practitioners.
|
||||
|
||||
1. Identify areas in the module where practitioners could tailor the automation to fit their infrastructure.
|
||||
2. Declare input variables and insert the use of variables throughout module resources to expose these options to practitioners.
|
||||
3. Include descriptions to capture what the variables are and how they are used, and specify [custom validation rules for variables](https://www.terraform.io/docs/configuration/variables.html#custom-validation-rules) to provide context to users the expected format and conditions for the variables.
|
||||
4. Set reasonable default values for variables that are optional, and omit default values for variables that are required module arguments.
|
||||
|
||||
Terraform is an explicit configuration language and requires variables to be declared, typed, and passed explicitly through as module arguments. Consul-Terraform-Sync abstracts this by creating intermediate variables at the root level from values intended for the module. These values are configured by practitioners within the [`task` block](/docs/nia/installation/configuration#variable_files). Value assignments are parsed to interpolate the corresponding variable declaration and are written to the appropriate Terraform files. A few assumptions are made for the intermediate variables: the variables users provide Consul-Terraform-Sync are declared and supported by the module, matching name and type.
|
||||
|
||||
#### Module Guidelines
|
||||
|
||||
This section covers guidelines for authoring compatible Consul-Terraform-Sync modules.
|
||||
|
||||
##### Scope
|
||||
|
||||
We recommend scoping the module to a few related resources for a provider. Small modules are easier and more flexible for end users to adopt for Consul-Terraform-Sync. It allows them to iteratively combine different modules and use them as building blocks to meet their unique network infrastructure needs.
|
||||
|
||||
##### Complexity
|
||||
|
||||
Consider authoring modules with low complexity to reduce the run time for Terraform execution. Complex modules that have a large number of dependencies may result in longer runs, which adds delay to the near real time network updates.
|
||||
|
||||
##### Providers
|
||||
|
||||
Provider configurations belong in the root module of a Terraform configuration and should not be included within the authored module for network integrations. End users will configure the providers through Consul-Terraform-Sync, and Consul-Terraform-Sync will then translate provider configuration to the generated root module appropriately.
|
||||
|
||||
##### Documentation
|
||||
|
||||
Modules for Consul-Terraform-Sync are Terraform modules and can effectively run independently from the `consul-terraform-sync` daemon and Consul environment. They should be written and designed with Terraform best practices and should be clear to a Terraform user what the module does and how to use it. Module documentation should be named `README` or `README.md`. The description should capture what the module should be used for and the implications of running it in automation with Consul-Terraform-Sync.
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Run Consul-Terraform-Sync
|
||||
sidebar_title: Run Consul-Terraform-Sync
|
||||
description: >-
|
||||
Consul-Terraform-Sync requires a Terraform Provider, a Terraform Module and a running Consul Cluster outside of the consul-terraform-sync daemon.
|
||||
---
|
||||
|
||||
# Run Consul-Terraform-Sync
|
||||
|
||||
1. Move the `consul-terraform-sync` binary to a location available on your `PATH`.
|
||||
|
||||
```
|
||||
$ mv ~/Downloads/consul-terraform-sync /usr/local/bin/consul-terraform-sync
|
||||
```
|
||||
|
||||
2. Create the config.hcl file, all the options are available [here](https://github.com/hashicorp/consul-terraform-sync/blob/master/docs/config.md#consul-terraform-sync).
|
||||
|
||||
3. Run consul-terraform-sync.
|
||||
|
||||
```
|
||||
./consul-terraform-sync -config-file <config.hcl>
|
||||
```
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Network Drivers
|
||||
sidebar_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 the set of services for the module to execute on. 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 service 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 the Consul catalog for discovering service information.
|
||||
|
||||
Autogenerated 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/installation/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 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 2 types of variable declarations. The required `services` input variable which determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](#compatible-terraform-modules) for more details) and 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/installation/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 is assigned values from the Consul catalog. It is periodically updated to reflect the current state of the configured set of services for the task.
|
||||
* `terraform.tfvars.tmpl` - The template file is used by Consul-Terraform-Sync to template service information from the Consul catalog 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.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Tasks
|
||||
sidebar_title: Tasks
|
||||
description: >-
|
||||
Consul-Terraform-Sync Tasks
|
||||
---
|
||||
|
||||
# Tasks
|
||||
|
||||
A task is the translation of dynamic service information from the Consul Catalog into network infrastructure changes downstream. Consul-Terraform-Sync carries out automation for executing tasks using network drivers. For a Terraform driver, the scope of a task is a Terraform module.
|
||||
|
||||
Below is an example task configuration:
|
||||
|
||||
```hcl
|
||||
task {
|
||||
name = "frontend-firewall-policies"
|
||||
description = "Add firewall policy rules for frontend services"
|
||||
providers = ["fake-firewall", "null"]
|
||||
services = ["web", "image"]
|
||||
source = "example/firewall-policy/module"
|
||||
version = "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
In the example task above, the "fake-firewall" and "null" providers, listed in the `providers` field, are used. These providers themselves should be configured in their own separate [provider blocks](/docs/nia/installation/configuration#provider). These providers are used in the Terraform module "example/firewll-policy/module", configured in the `source` field, to create, update, and destroy resources. This module may do something like use the providers to create and destroy firewall policy objects based on IP addresses. The IP addresses come from the "web" and "image" service instances configured in the `services` field. This service-level information is retrieved by Consul-Terraform-Sync which watches Consul catalog for changes.
|
||||
|
||||
See [task configuration](/docs/nia/installation/configuration#task) for more details on how to configure a task.
|
||||
|
||||
Consul-Terraform-Sync automatically generates any files needed to execute the network driver for each task. See [network drivers](/docs/nia/network-drivers) for more details on the files generated for the Terraform driver.
|
||||
Loading…
Reference in New Issue