From 92d0aa05f0f94d1ed88ea24761b47e83b529e435 Mon Sep 17 00:00:00 2001
From: Kim Ngo <6362111+findkim@users.noreply.github.com>
Date: Fri, 15 Oct 2021 11:01:10 -0500
Subject: [PATCH] Add protocol example for TFC driver address (#11319)
* Add protocol example for TFC driver address
* Format cts code blocks
---
website/content/docs/nia/configuration.mdx | 91 ++++++++++---------
.../docs/nia/installation/configure.mdx | 28 +++---
.../content/docs/nia/installation/install.mdx | 4 +-
website/content/docs/nia/tasks.mdx | 54 +++++------
.../content/docs/nia/terraform-modules.mdx | 40 ++++----
5 files changed, 115 insertions(+), 102 deletions(-)
diff --git a/website/content/docs/nia/configuration.mdx b/website/content/docs/nia/configuration.mdx
index aef59cb387..24a0aaef1d 100644
--- a/website/content/docs/nia/configuration.mdx
+++ b/website/content/docs/nia/configuration.mdx
@@ -14,16 +14,18 @@ The Consul-Terraform-Sync daemon is configured using configuration files and sup
Top level options are reserved for configuring Consul-Terraform-Sync.
```hcl
-log_level = "INFO"
+log_level = "INFO"
working_dir = "sync-tasks"
-port = 8558
+port = 8558
+
syslog {
facility = "local2"
}
+
buffer_period {
enabled = true
- min = "5s"
- max = "20s"
+ min = "5s"
+ max = "20s"
}
```
@@ -89,8 +91,8 @@ A `service` block is an optional block to explicitly define configuration of ser
```hcl
service {
- name = "web"
- datacenter = "dc1"
+ name = "web"
+ datacenter = "dc1"
description = "all instances of the service web in datacenter dc1"
}
```
@@ -110,13 +112,13 @@ A `task` block configures which task to execute in automation. When the task sho
```hcl
task {
- name = "taskA"
- description = ""
- enabled = true,
- providers = []
- services = ["web", "api"]
- source = "org/example/module"
- version = "1.0.0"
+ name = "taskA"
+ description = ""
+ enabled = true,
+ providers = []
+ services = ["web", "api"]
+ source = "org/example/module"
+ version = "1.0.0"
variable_files = []
condition "catalog-services" {
regexp = ".*"
@@ -147,14 +149,19 @@ task {
- `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.
- `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 a dynamic 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. Buffer periods do not apply to scheduled tasks.
@@ -177,10 +184,10 @@ See [Task Execution: Services Condition](/docs/nia/tasks#services-condition) for
```hcl
task {
- name = "services_condition_task"
+ name = "services_condition_task"
description = "execute on changes to services with names starting with web"
- providers = ["my-provider"]
- source = "path/to/services-condition-module"
+ providers = ["my-provider"]
+ source = "path/to/services-condition-module"
condition "services" {
regexp = "^web.*"
@@ -198,10 +205,10 @@ See [Task Execution: Catalog Services Condition](/docs/nia/tasks#catalog-service
```hcl
task {
- name = "catalog_service_condition_task"
+ name = "catalog_service_condition_task"
description = "execute on service de/registrations with name matching 'web.*'"
- source = "path/to/catalog-services-module"
- providers = ["my-provider"]
+ source = "path/to/catalog-services-module"
+ providers = ["my-provider"]
// configure depending on module. provides detailed information for these
// services but does not execute task. refer to module docs on how to configure.
@@ -233,11 +240,11 @@ See [Task Execution: Consul KV Condition](/docs/nia/tasks#consul-kv-condition) f
```hcl
task {
- name = "consul_kv_condition_task"
+ name = "consul_kv_condition_task"
description = "execute on changes to Consul KV entry"
- source = "path/to/consul-kv-module"
- providers = ["my-provider"]
- services = ["web-api"]
+ source = "path/to/consul-kv-module"
+ providers = ["my-provider"]
+ services = ["web-api"]
condition "consul-kv" {
path = "my-key"
@@ -267,10 +274,10 @@ See [Terraform Module: Source Input](/docs/nia/terraform-modules#source-input) f
```hcl
task {
- name = "scheduled_task"
+ name = "scheduled_task"
description = "execute every Monday using service information from web and db"
- services = ["web", "db"]
- source = "path/to/module"
+ services = ["web", "db"]
+ source = "path/to/module"
condition "schedule" {
cron = "* * * * Mon"
}
@@ -355,9 +362,9 @@ The Terraform driver block is used to configure Consul-Terraform-Sync for instal
```hcl
driver "terraform" {
- log = false
+ log = false
persist_log = false
- path = ""
+ path = ""
backend "consul" {
gzip = true
@@ -365,7 +372,7 @@ driver "terraform" {
required_providers {
myprovider = {
- source = "namespace/myprovider"
+ source = "namespace/myprovider"
version = "1.3.0"
}
}
@@ -401,7 +408,7 @@ Only one network driver can be configured per deployment of Consul-Terraform-Syn
```hcl
driver "terraform-cloud" {
- hostname = "my.tfe.hostname.io"
+ hostname = "https://app.terraform.io"
organization = "my-org"
token = ""
// Optionally set the token to be securely queried from Vault instead of
@@ -410,7 +417,7 @@ driver "terraform-cloud" {
required_providers {
myprovider = {
- source = "namespace/myprovider"
+ source = "namespace/myprovider"
version = "1.3.0"
}
}
@@ -452,21 +459,21 @@ The below configuration captures the general design of defining a provider using
driver "terraform" {
required_providers {
aws = {
- source = "hashicorp/aws"
+ source = "hashicorp/aws"
version = "3.33.0"
}
}
}
terraform_provider "aws" {
- # Configuration options
+ // Configuration options
region = "us-east-1"
}
task {
- source = "some/source"
+ source = "some/source"
providers = ["aws"]
- services = ["web", "api"]
+ services = ["web", "api"]
}
```
@@ -572,7 +579,7 @@ The example Consul-Terraform-Sync configuration below defines two similar tasks
```hcl
terraform_provider "aws" {
- alias = "a"
+ alias = "a"
profile = "team-a"
task_env {
"AWS_ACCESS_KEY_ID" = "{{ env \"CTS_AWS_ACCESS_KEY_ID_A\" }}"
@@ -580,7 +587,7 @@ terraform_provider "aws" {
}
terraform_provider "aws" {
- alias = "b"
+ alias = "b"
profile = "team-b"
task_env {
"AWS_ACCESS_KEY_ID" = "{{ env \"CTS_AWS_ACCESS_KEY_ID_B\" }}"
@@ -592,15 +599,15 @@ terraform_provider "dns" {
}
task {
- name = "task-a"
- source = "org/module"
+ name = "task-a"
+ source = "org/module"
providers = ["aws.a", "dns"]
// ...
}
task {
- name = "task-b"
- source = "org/module"
+ name = "task-b"
+ source = "org/module"
providers = ["aws.b", "dns"]
// ...
}
diff --git a/website/content/docs/nia/installation/configure.mdx b/website/content/docs/nia/installation/configure.mdx
index 89f2df02a2..cade6131f8 100644
--- a/website/content/docs/nia/installation/configure.mdx
+++ b/website/content/docs/nia/installation/configure.mdx
@@ -19,12 +19,12 @@ Review the Terraform module to be used for network automation and identify the T
```hcl
task {
- name = "website-x"
+ name = "website-x"
description = "automate services for website-x"
- source = "namespace/example/module"
- version = "1.0.0"
- providers = ["myprovider"]
- services = ["web", "api"]
+ source = "namespace/example/module"
+ version = "1.0.0"
+ providers = ["myprovider"]
+ services = ["web", "api"]
}
```
@@ -36,7 +36,7 @@ Configuring Terraform providers within Consul-Terraform-Sync requires 2 config c
driver "terraform" {
required_providers {
myprovider = {
- source = "namespace/myprovider"
+ source = "namespace/myprovider"
version = "1.3.0"
}
}
@@ -59,6 +59,8 @@ Piecing it all together, the configuration file for Consul-Terraform-Sync will h
An example HCL configuration file is shown below to automate one task to execute a Terraform module on the condition when there are changes to two services.
+
+
```hcl
log_level = "info"
@@ -71,12 +73,12 @@ consul {
}
task {
- name = "website-x"
+ name = "website-x"
description = "automate services for website-x"
- source = "namespace/example/module"
- version = "1.0.0"
- providers = ["myprovider"]
- services = ["web", "api"]
+ source = "namespace/example/module"
+ version = "1.0.0"
+ providers = ["myprovider"]
+ services = ["web", "api"]
buffer_period {
min = "10s"
}
@@ -87,7 +89,7 @@ driver "terraform" {
required_providers {
myprovider = {
- source = "namespace/myprovider"
+ source = "namespace/myprovider"
version = "1.3.0"
}
}
@@ -97,3 +99,5 @@ terraform_provider "myprovider" {
address = "myprovider.example.com"
}
```
+
+
diff --git a/website/content/docs/nia/installation/install.mdx b/website/content/docs/nia/installation/install.mdx
index 4a7e0087a6..6d18959af3 100644
--- a/website/content/docs/nia/installation/install.mdx
+++ b/website/content/docs/nia/installation/install.mdx
@@ -46,7 +46,7 @@ Consul-Terraform-Sync connects with your Consul cluster in order to monitor the
```hcl
consul {
address = "localhost:8500"
- token = "my-consul-acl-token"
+ token = "my-consul-acl-token"
}
```
@@ -58,7 +58,7 @@ Once you have identified a Terraform provider for all of your network devices, y
```hcl
terraform_provider "fake-firewall" {
- address = "10.10.10.10"
+ address = "10.10.10.10"
username = "admin"
password = "password123"
}
diff --git a/website/content/docs/nia/tasks.mdx b/website/content/docs/nia/tasks.mdx
index f868062542..6866f42066 100644
--- a/website/content/docs/nia/tasks.mdx
+++ b/website/content/docs/nia/tasks.mdx
@@ -13,12 +13,12 @@ Below is an example task configuration:
```hcl
task {
- name = "frontend-firewall-policies"
+ 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"
+ providers = ["fake-firewall", "null"]
+ services = ["web", "image"]
+ source = "example/firewall-policy/module"
+ version = "1.0.0"
}
```
@@ -69,19 +69,19 @@ The services condition is the default behavior if no `condition` block is config
```hcl
task {
- name = "services_condition_task_1"
+ 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"]
+ providers = ["my-provider"]
+ source = "path/to/services-condition-module"
+ services = ["api", "db", "web"]
}
task {
- name = "services_condition_task_2"
+ 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"]
+ providers = ["my-provider"]
+ source = "path/to/services-condition-module"
+ services = ["api", "db", "web"]
condition "services" {}
}
@@ -91,10 +91,10 @@ Below is an example configuration for a task that will execute when a service wi
```hcl
task {
- name = "services_condition_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"
+ providers = ["my-provider"]
+ source = "path/to/services-condition-module"
condition "services" {
regexp = "^web.*"
@@ -112,10 +112,10 @@ Below is an example configuration for a task that will execute when a service wi
```hcl
task {
- name = "catalog_service_condition_task"
- source = "path/to/catalog-services-module"
+ name = "catalog_service_condition_task"
+ source = "path/to/catalog-services-module"
providers = ["my-provider"]
- services = ["web-api"]
+ services = ["web-api"]
condition "catalog-services" {
datacenter = "dc1"
@@ -125,7 +125,7 @@ task {
}
service {
- name = "web-api"
+ name = "web-api"
datacenter = "dc2"
}
```
@@ -144,11 +144,11 @@ Based on the `recurse` option, the condition either monitors a single Consul KV
```hcl
task {
- name = "consul_kv_condition_task"
+ name = "consul_kv_condition_task"
description = "execute on changes to Consul KV entry"
- source = "path/to/consul-kv-module"
- providers = ["my-provider"]
- services = ["web-api"]
+ source = "path/to/consul-kv-module"
+ providers = ["my-provider"]
+ services = ["web-api"]
condition "consul-kv" {
path = "my-key"
@@ -170,10 +170,10 @@ Below is an example configuration for a task that will execute every Monday, whi
```hcl
task {
- name = "scheduled_task"
+ name = "scheduled_task"
description = "execute every Monday using service information from web and db"
- services = ["web", "db"]
- source = "path/to/module"
+ services = ["web", "db"]
+ source = "path/to/module"
condition "schedule" {
cron = "* * * * Mon"
diff --git a/website/content/docs/nia/terraform-modules.mdx b/website/content/docs/nia/terraform-modules.mdx
index e56def12af..e62e5c37f0 100644
--- a/website/content/docs/nia/terraform-modules.mdx
+++ b/website/content/docs/nia/terraform-modules.mdx
@@ -118,10 +118,10 @@ Below is an example configuration for a task that will execute on a schedule and
```hcl
task {
- name = "services_condition_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"
+ providers = ["my-provider"]
+ source = "path/to/services-condition-module"
condition "schedule" {
cron = "* * * * Mon"
}
@@ -156,20 +156,22 @@ Below is a similar example to the one provided in the [Consul KV Condition](/doc
```hcl
task {
- name = "consul_kv_schedule_task"
+ name = "consul_kv_schedule_task"
description = "executes on Monday monitoring Consul KV"
- providers = ["my-provider"]
- services = ["web-api"]
- source = "path/to/consul-kv-module"
- source_input "consul-kv" {
- path = "my-key"
- recurse = true
- datacenter = "dc1"
- namespace = "default"
- }
+ providers = ["my-provider"]
+ services = ["web-api"]
+ source = "path/to/consul-kv-module"
+
condition "schedule" {
cron = "* * * * Mon"
}
+
+ source_input "consul-kv" {
+ path = "my-key"
+ recurse = true
+ datacenter = "dc1"
+ namespace = "default"
+ }
}
```
@@ -201,11 +203,11 @@ Example of a catalog-services condition which supports source input through `sou
```hcl
task {
- name = "catalog_services_condition_task"
+ name = "catalog_services_condition_task"
description = "execute on registration/deregistration of services"
- providers = ["my-provider"]
- services = ["web-api"]
- source = "path/to/catalog-services-module"
+ providers = ["my-provider"]
+ services = ["web-api"]
+ source = "path/to/catalog-services-module"
condition "catalog-services" {
datacenter = "dc1"
namespace = "default"
@@ -312,7 +314,7 @@ If you are creating a module for a [catalog-services condition](/docs/nia/tasks#
```hcl
variable "catalog_services" {
description = "Consul catalog service names and tags monitored by Consul-Terraform-Sync"
- type = map(list(string))
+ type = map(list(string))
}
```
@@ -333,7 +335,7 @@ If you are creating a module for a [consul-kv condition](/docs/nia/tasks#consul-
```hcl
variable "consul_kv" {
description = "Keys and values of the Consul KV pairs monitored by Consul-Terraform-Sync"
- type = map(string)
+ type = map(string)
}
```