luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

nia/docs 0.1.0 beta (#9803) 

nia/docs 0.1.0-beta

Co-authored-by: Kent 'picat' Gruber <kent@hashicorp.com>
Co-authored-by: Lorna Song <lorna@hashicorp.com>
Co-authored-by: John Eikenberry <jae@zhar.net>
This commit is contained in:
Kim Ngo 2021-02-25 16:48:24 -06:00 committed by GitHub
parent 4ebdbf57d7
commit 6f042a2edb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 444 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
website/content/docs/integrate/nia-integration.mdx
View File

@ -44,14 +44,14 @@ Consul-Terraform-Sync compatible Terraform module development process is fairly
- Consul [documentation](/docs)
- Consul-Terraform-Sync [documentation](/docs/nia)
- Writing Consul-Terraform-Sync compatible Terraform modules [guide](/docs/nia/installation/requirements#how-to-create-a-compatible-terraform-module)
- Writing Consul-Terraform-Sync compatible Terraform modules [guide](/docs/nia/terraform-modules)
- Example [module](https://registry.terraform.io/modules/PaloAltoNetworks/dag-nia/panos/latest) for reference
- Publishing to the Terraform Registry [guidelines](https://www.terraform.io/docs/registry/modules/publish.html)
### 3. Develop & Test
Terraform modules are written in HashiCorp Configuration Language (HCL). Writing [Terraform modules](https://www.terraform.io/docs/modules/index.html) or a [tutorial to build a module](https://learn.hashicorp.com/tutorials/terraform/module-create) are good resources to begin writing a new module.
Consul-Terraform-Sync compatible modules follow the [standard module structure](https://www.terraform.io/docs/modules/index.html#standard-module-structure). Modules can use syntax supported by Terraform version 0.13, or higher. Consul-Terraform-Sync is designed to integrate with any module that satisfies these [specifications](/docs/nia/installation/requirements#how-to-create-a-compatible-terraform-module). The guide will give you an introduction of the code structure and the basics of authoring a plugin that Terraform can interact with.
Consul-Terraform-Sync compatible modules follow the [standard module structure](https://www.terraform.io/docs/modules/index.html#standard-module-structure). Modules can use syntax supported by Terraform version 0.13, or higher. Consul-Terraform-Sync is designed to integrate with any module that satisfies these [specifications](/docs/nia/terraform-modules#module-specifications). The guide will give you an introduction of the code structure and the basics of authoring a plugin that Terraform can interact with.
It is recommended that partners develop modules that cater to specific workflows on an individual platform in their product portfolio rather than having overarching modules that try to cover multiple workflows across different platforms. This is to keep the automation modular and adoptable by a broad set of users with varying network infrastructure topologies. Partners are encouraged to test the functionality of the modules against their supported platforms.
@ -87,7 +87,7 @@ Once the module development has been completed another email should be sent to n
At this stage, it is expected that the module is fully developed, all tests and documentation are in place, and that HashiCorp has reviewed the module to be compatible with Consul-Terraform-Sync.
Once this is done, HashiCorp will get the new module listed as Consul-Terraform-Sync compatible on [consul.io](/docs/nia/installation/requirements#using-terraform-modules), and then the partner will be asked to publish the Terraform module to the [Terraform Registry](https://registry.terraform.io/browse/modules).
Once this is done, HashiCorp will get the new module listed as Consul-Terraform-Sync compatible on [consul.io](/docs/nia/installation/requirements#partner-terraform-modules), and then the partner will be asked to publish the Terraform module to the [Terraform Registry](https://registry.terraform.io/browse/modules).
### 6. Support
@ -95,7 +95,7 @@ Many partners view the release step to be the end of the journey, while at Hashi
The expectation is to resolve all critical issues within 48 hours and all other issues within 5 business days. HashiCorp Consul and Terraform have an extremely wide community of users and contributors and we encourage everyone to report issues however small, as well as help resolve them when possible.
Partners who choose to not follow the process of NIA Integration Program for their Consul-Terraform-Sync compatible Terraform modules will not have their modules listed on [consul.io](/docs/nia/installation/requirements#using-terraform-modules).
Partners who choose to not follow the process of NIA Integration Program for their Consul-Terraform-Sync compatible Terraform modules will not have their modules listed on [consul.io](/docs/nia/installation/requirements#partner-terraform-modules).
### Contact Us

34
website/content/docs/nia/api/api-overview.mdx Normal file
View File

@ -0,0 +1,34 @@
---
layout: docs
page_title: Consul-Terraform-Sync API
sidebar_title: Overview
description: >-
How to use the Consul-Terraform-Sync API
---
# Consul-Terraform-Sync API
When running in [daemon mode](/docs/nia/cli#daemon-mode), Consul-Terraform-Sync serves an HTTP API interface. Details of the available API endpoints is available in the navigation to the left.
### Port
The API is served at the default port `8558` or a different port if set with [`port` configuration](/docs/nia/configuration#port)
### Version Prefix
All API routes are prefixed with `/v1/`. This documentation is for v1 of the API, which is the only version currently.
Example: `localhost:8558/v1/status`
### Error
Successful API requests will receive a 2XX success status code. For other unsuccessful status codes, when possible, more details will be provided in a response body containing an error object.
Example: Status 400 Bad Request
```json
{
"error": {
"message": "example error message: unsupported status parameter value"
}
}
```

68
website/content/docs/nia/api.mdx → website/content/docs/nia/api/status.mdx
View File

@ -1,43 +1,17 @@
---
layout: docs
page_title: Consul-Terraform-Sync API
sidebar_title: API
page_title: Consul-Terraform-Sync Status API
sidebar_title: Status
description: >-
How to use the Consul-Terraform-Sync API
Consul-Terraform-Sync Status API
---
# Consul-Terraform-Sync API
When running in [daemon mode](/docs/nia/cli#daemon-mode), Consul-Terraform-Sync serves an HTTP API interface.
### Port
The API is served at the default port `8558` or a different port if set with [`port` configuration](/docs/nia/configuration#port)
### Version Prefix
All API routes are prefixed with `/v1/`. This documentation is for v1 of the API, which is the only version currently.
Example: `localhost:8558/v1/status`
### Error
Successful API requests will receive a 2XX success status code. For other unsuccessful status codes, when possible, more details will be provided in a response body. The response will be a JSON map with an "error" key.
Example: Status 400 Bad Request
```json
{
"error": "example error message: unsupported status parameter value"
}
```
## Status
# Status
The `/status` endpoints share status-related information for tasks. This information is available for understanding the status of individual tasks and across tasks.
The health status value is determined by aggregating the success or failure of the event of a task detecting changes in Consul services and then updating network infrastructure. Currently, only the 5 most recent events are stored in Consul-Terraform-Sync. For more information on the hierarchy of status information and how it is collected, see [Status Information](/docs/nia/tasks#status-information).
### Overall Status
## Overall Status
This endpoint currently returns the overall status information for all tasks.
@ -50,10 +24,15 @@ Currently no request parameters are offered for the overall status API.
#### Response Fields
* `task_summary` - Summary of the count of tasks for each health status. See [Task Status API](/docs/nia/api#task-status) to learn more about how health status is determined.
* `successful` - (int) The number of tasks that have a 'successful' health status
* `errored` - (int) The number of tasks that have a 'errored' health status
* `critical` - (int) The number of tasks that have a 'critical' health status
* `task_summary` - Summary of task information. See [Task Status API](/docs/nia/api#task-status) to learn more about how health status is determined.
* `status` - Summary count of how many tasks have each health status value
* `successful` - (int) The number of tasks that have a 'successful' health status
* `errored` - (int) The number of tasks that have a 'errored' health status
* `critical` - (int) The number of tasks that have a 'critical' health status
* `unknown` - (int) The number of tasks that have an 'unknown' health status
* `enabled` - Summary count of how many tasks are enabled or disabled
* `true` - (int) The number of tasks that are enabled
* `false` - (int) The number of tasks that are disabled
#### Example
@ -67,14 +46,21 @@ Response:
```json
{
"task_summary": {
"successful": 28,
"errored": 5,
"critical": 1
"status": {
"successful": 28,
"errored": 5,
"critical": 1,
"unknown": 0
},
"enabled": {
"true": 32,
"false": 2
}
}
}
```
### Task Status
## Task Status
This endpoint returns the individual task status information for a single specified task or for all tasks.
@ -100,6 +86,7 @@ The response is a JSON map of task name to a status information structure with t
* `task_name` - (string) Name that task is configured with in Consul-Terraform-Sync.
* `status` - (string) Values are "successful", "errored", "critical", or "unknown". This is determined by the success or failure of all stored events on the network infrastructure update process for the task, as described earlier.
* `enabled` - (bool) Whether the task is enabled or not.
* `services` - (list[string]) List of the services configured for the task.
* `providers` - (list[string]) List of the providers configured for the task.
* `events_url` - (string) Relative URL to retrieve the event data stored for the task.
@ -134,6 +121,7 @@ Response:
"task_a": {
"task_name": "task_a",
"status": "successful",
"enabled": true,
"providers": [
"local"
],
@ -145,6 +133,7 @@ Response:
"task_b": {
"task_name": "task_b",
"status": "errored",
"enabled": false,
"providers": [
"null"
],
@ -169,6 +158,7 @@ Response:
"task_b": {
"task_name": "task_b",
"status": "errored",
"enabled": false,
"providers": [
"null"
],

72
website/content/docs/nia/api/tasks.mdx Normal file
View File

@ -0,0 +1,72 @@
---
layout: docs
page_title: Consul-Terraform-Sync Tasks API
sidebar_title: Tasks
description: >-
Consul-Terraform-Sync Tasks API
---
# Tasks
The `/tasks` endpoints modify the tasks that Consul-Terraform-Sync is responsible for running.
## Update Task
This endpoint allows patch updates to specifically supported fields for existing tasks. Currently only supports updating a task's [`enabled` value](/docs/nia/configuration#enabled-4).
| Method | Path | Produces |
| ------ | ------------------- | ------------------ |
| `PATCH` | `/tasks/:task_name` | `application/json` |
#### Request Parameters
* `run` - (string) Values can be only be "inspect" and "now".
* "inspect": Does not update the task but returns information on if/how resources would be changed for the proposed task update.
* "now": Updates the task accordingly and immediately runs the task, rather than allowing the task to run at the natural daemon cadence
#### Response Fields
* `inspect` - Information on how resources would be changed given a proposed task update, similar to [inspect-mode](/docs/nia/cli/cli-overview#inspect-mode). This is only returned when passed the `run=inspect` request parameter
* `changes_present` - (bool) Whether or not changes were detected for running the proposed task update
* `plan` - (string) The Terraform plan generated for the proposed task update . Note: a non-empty string does not necessarily indicate changes were detected.
#### Example: Disable a task
Request:
```shell-session
$ curl --header "Content-Type: application/json" \
--request PATCH \
--data '{"enabled":false}' \
localhost:8558/v1/tasks/task_a
```
Response:
```json
{}
```
#### Example: Inspect enabling a task
Request:
```shell-session
$ curl --header "Content-Type: application/json" \
--request PATCH \
--data '{"enabled":true}' \
localhost:8558/v1/tasks/task_a?run=inspect
```
Response if no changes present:
```json
{
"changes_present": false,
"plan": "No changes. Infrastructure is up-to-date. <truncated>"
}
```
Response if changes present:
```json
{
"changes_present": true,
"plan": "<terraform plan truncated> Plan: 3 to add, 0 to change, 0 to destroy."
}
```

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

@ -48,5 +48,5 @@ discovered IP addresses for a set of Consul services.
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
with a set of providers that [enables supporting](/docs/nia/terraform-modules) a wide variety of
infrastructure applications.

49
website/content/docs/nia/cli.mdx → website/content/docs/nia/cli/cli-overview.mdx
View File

@ -1,16 +1,18 @@
---
layout: docs
page_title: Consul-Terraform-Sync CLI
sidebar_title: CLI
sidebar_title: Overview
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`.
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`. Consul-Terraform-Sync can be run as a daemon and execute CLI commands. When Consul-Terraform-Sync is run as a daemon, it acts as a server to the CLI commands. Users can use the commands to interact and modify the daemon as it is running. The complete list of commands is in the navigation to the left. Both the daemon and commands return a non-zero exit status on error.
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:
## Daemon
When running as a daemon, 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
@ -18,19 +20,19 @@ $ consul-terraform-sync -config-file=config.hcl
To view a list of available flags, use the `-help` or `-h` flag.
## Modes
### Modes
Consul-Terraform-Sync can be run in different modes.
Consul-Terraform-Sync can be run as a daemon in different modes.
### Daemon Mode
#### Long-running 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.
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. Once beginning the long-running process, the daemon serves any API and command requests.
Usage: Intended to be run as a long running process after running once-mode successfully for given configuration and tasks.
### Inspect Mode
#### Inspect Mode
Flag: `-inspect`
@ -46,10 +48,39 @@ Behavior: This has similar behavior as `-inspect` mode for the selected task. Th
Usage: Useful to debug one or more tasks to confirm configuration is accurate and the selected tasks would update network infrastructure as expected.
### Once Mode
#### 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.
## Commands
In addition to running the daemon, Consul-Terraform-Sync has a set of commands that act as a client to the daemon server. The commands provide a user-friendly experience interacting with the daemon. The commands use the Consul-Terraform-Sync's APIs but does not correspond one-to-one with it. Please see the individual commands in the left navigation for more details.
To get help for a command, run: `consul-terraform-sync <command> -h`
### CLI Structure
Consul-Terraform-Sync commands follow the below structure
```shell-session
consul-terraform-sync <command> [options] [args]
```
- `options`: Flags to specify additional settings. There are general options that can be used across all commands and command-specific options.
- `args`: Required arguments specific to a commands
Example:
```shell-session
consul-terraform-sync task disable -port=2000 task_a
```
### General Options
Below are options that can be used across all commands:
- `-port=<port>` - (int: 8558) The port that the Consul-Terraform-Sync daemon serves its API.

76
website/content/docs/nia/cli/task.mdx Normal file
View File

@ -0,0 +1,76 @@
---
layout: docs
page_title: Task Command
sidebar_title: task
description: >-
Consul-Terraform-Sync supports task commands for users to modify tasks while the daemon is running
---
# task
## task enable
`task enable` command enables an existing task so that it will run and update task resources. If the task is already enabled, it will return a success. The command generates and outputs a Terraform plan, similar to [inspect-mode](/docs/nia/cli/cli-overview#inspect-mode), of how resources will be modified if task becomes enabled. If resources changes are detected, the command will ask for user approval before enabling the task. If no resources are detected, the command will go ahead and enable the task.
### Usage
`consul-terraform-sync task enable [options] <task_name>`
**Arguments:**
- `task_name` - (string: required) The name of the task to enable
**Options:** Currently only supporting [general options](/docs/nia/cli/cli-overview#general-options)
### Example
```shell-session
$ consul-terraform-sync task enable task_a
==> Inspecting changes to resource if enabling 'task_a'...
Generating plan that Consul Terraform Sync will use Terraform to execute
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
+ create
Terraform will perform the following actions:
// <diff truncated>
Plan: 3 to add, 0 to change, 0 to destroy.
==> Enabling the task will perform the actions described above.
Do you want to perform these actions for 'task_a'?
- This action cannot be undone.
- Consul Terraform Sync cannot guarantee Terraform will perform
these exact actions if monitored services have changed.
Only 'yes' will be accepted to approve.
Enter a value: yes
==> Enabling and running 'task_a'...
==> 'task_a' enable complete!
```
## task disable
`task disable` command disables an existing task so that it will no longer run and update task resources. If the task is already disabled, it will return a success.
### Usage
`consul-terraform-sync task disable [options] <task_name>`
**Arguments:**
- `task_name` - (string: required) The name of the task to disable
**Options:** Currently only supporting [general options](/docs/nia/cli/cli-overview#general-options)
### Example
```shell-session
$ consul-terraform-sync task disable task_b
==> Waiting to disable 'task_b'...
==> 'task_b' disable complete!
```

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

@ -17,7 +17,9 @@ Top level options are reserved for configuring Consul-Terraform-Sync.
```hcl
log_level = "INFO"
port = 8558
syslog {}
syslog {
facility = "local2"
}
buffer_period {
enabled = true
min = "5s"
@ -33,13 +35,15 @@ buffer_period {
- `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) Name of the syslog facility to log to.
- `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](/docs/agent/options) with, at least, the [cert_file](/docs/agent/options#cert_file) and [key_file](/docs/agent/options#key_file) set. Consul-Terraform-Sync's configuration for HTTP/2 requires `tls.enabled = true` and it must have the address set to the HTTPS URL, `address = example.consul.com:8501`. Optionally you'll need to set `tls.verify = false` if using self-signed certificates for Consul. Using HTTP/2 can solve issues hitting Consul's maximum connections limits as well as just generally perform more efficiently when processing lots of blocking queries.
To read more on suggestions for configuring the Consul agent, see [run an agent](/docs/nia/installation/requirements#run-an-agent).
```hcl
@ -70,9 +74,11 @@ consul {
- `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: "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.
- `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`](https://www.consul.io/docs/agent/options#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
@ -93,6 +99,8 @@ service {
- `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) 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](/docs/nia/installation/requirements#module-specifications) 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
@ -102,6 +110,7 @@ A `task` block configures which task to run in automation for the selected servi
task {
name = "taskA"
description = ""
enabled = true,
providers = []
services = ["web", "api"]
source = "org/example/module"
@ -112,6 +121,7 @@ task {
- `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](#terraform-provider) 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](#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).

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

@ -1,12 +1,12 @@
---
layout: docs
page_title: Network Infrastructure Automation
sidebar_title: Network Infrastructure Automation <sup>Tech Preview</sup>
sidebar_title: Network Infrastructure Automation <sup>Beta</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 <sup>Beta</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.
@ -37,4 +37,4 @@ Consul-Terraform-Sync executes one or more automation tasks with the most recent
- [Contribute](https://github.com/hashicorp/consul-terraform-sync) to the open source project
- [Report](https://github.com/hashicorp/consul-terraform-sync/issues) bugs or request enhancements
- [Discuss](https://discuss.hashicorp.com/tags/c/consul/29/consul-terraform-sync) with the community or ask questions
- [Build integrations](/docs/nia/installation/requirements#how-to-create-a-compatible-terraform-module) for Consul-Terraform-Sync
- [Build integrations](/docs/nia/terraform-modules) for Consul-Terraform-Sync

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

@ -24,7 +24,9 @@ To install a local Consul agent, refer to the [Getting Started: Install Consul T
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).
When running a Consul agent with Consul-Terraform-Sync in production, we suggest to keep a few considerations in mind. Consul-Terraform-Sync uses [blocking queries](/api/features/blocking) to monitor task dependencies, like changes to registered services. This results in multiple long running TCP connections between Consul-Terraform-Sync and the agent to poll changes for each dependency. Monitoring a high number of services may quickly hit the default Consul agent connection limits. Configure [`limits.http_max_conns_per_client`](/docs/agent/options#http_max_conns_per_client) for the agent to a reasonable value proportional to the number of services monitored by Consul-Terraform-Sync.
When running a Consul agent with Consul-Terraform-Sync in production, we suggest to keep a few considerations in mind. Consul-Terraform-Sync uses [blocking queries](/api/features/blocking) to monitor task dependencies, like changes to registered services. This results in multiple long running TCP connections between Consul-Terraform-Sync and the agent to poll changes for each dependency. Monitoring a high number of services may quickly hit the default Consul agent connection limits.
There are 2 ways to fix this issue. The first and recommended fix is to use HTTP/2 (requires HTTPS) to communicate between Consul-Terraform-Sync and the Consul agent. When using HTTP/2 only a single connection is made and reused for all communications. See the [Consul Configuration section](/docs/nia/configuration#consul) for more. The other option is to configure [`limits.http_max_conns_per_client`](/docs/agent/options#http_max_conns_per_client) for the agent to a reasonable value proportional to the number of services monitored by Consul-Terraform-Sync.
### Register Services
@ -59,7 +61,7 @@ If you would like to run a Consul cluster rather than a single agent, refer to [
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
### Finding 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).
@ -69,11 +71,13 @@ If there is no existing Terraform provider, a new Terraform provider can be [cre
## 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.
The Terraform module for a task in Consul-Terraform-Sync is the core component of the integration. It declares which resources and how your infrastructure is dynamically updated.
-> **Note:** [Release 0.1.0-techpreview2](https://github.com/hashicorp/consul-terraform-sync/releases/tag/v0.1.0-techpreview2) is compatible with Terraform modules with syntax supported by Terraform version [0.13](https://github.com/hashicorp/terraform/blob/v0.13/CHANGELOG.md) - [0.14](https://github.com/hashicorp/terraform/blob/v0.14/CHANGELOG.md).
Working with a Terraform provider, you can write an integration task for Consul-Terraform-Sync by [creating a Terraform module](/docs/nia/terraform-modules) that is compatible with the Terraform driver or use a module built by partners below.
### Using Terraform Modules
Continue to the next page to [get started with configuring Consul-Terraform-Sync and how to use Terraform providers and modules for tasks.](/docs/nia/installation/configure)
### Partner Terraform Modules
The modules listed below are availabe to use and are compatible with Consul-Terraform-Sync.
@ -97,92 +101,3 @@ The modules listed below are availabe to use and are compatible with Consul-Terr
- Dynamic Address Group (DAG) Tags: [Terraform Registry](https://registry.terraform.io/modules/PaloAltoNetworks/dag-nia/panos/latest) / [GitHub](https://github.com/PaloAltoNetworks/terraform-panos-dag-nia)
- Address Group and Dynamic Address Group (DAG) Tags: [Terraform Registry](https://registry.terraform.io/modules/PaloAltoNetworks/ag-dag-nia/panos/latest) / [GitHub](https://github.com/PaloAltoNetworks/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). A complete list of attributes available for the `services` variable is included in the [documentation for Consul-Terraform-Sync tasks](/docs/nia/tasks#task-execution).
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, or omit default values for variables that are required module arguments.
5. Set the [sensitive argument](https://www.terraform.io/docs/language/values/variables.html#suppressing-values-in-cli-output) for variables that contain secret or sensitive values. When set, Terraform will redact the value from output when Terraform commands are run.
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/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.

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

@ -45,7 +45,7 @@ The following files of the root module are generated for each task. An [example
- `terraform` block - The corresponding provider source and versions for the task from the configuration files are placed into this block for the root module. The Terraform backend from the configuration is also templated here.
- `provider` blocks - The provider blocks generated in the root module resemble the `terraform_provider` blocks in the configuration. They have identical arguments present and are set from the intermediate variable created per provider.
- `module` block - The module block is where the task's module is called as a [child module](https://www.terraform.io/docs/configuration/modules.html#calling-a-child-module). The child module contains the core logic for automation. Required and optional input variables are passed as arguments to the module.
- `variables.tf` - This file contains 2 types of variable declarations. The required `services` input variable which determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](/docs/nia/installation/requirements#how-to-create-a-compatible-terraform-module) 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.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](/docs/nia/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/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)).

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

@ -27,9 +27,11 @@ In the example task above, the "fake-firewall" and "null" providers, listed in t
See [task configuration](/docs/nia/configuration#task) for more details on how to configure a task.
A task can be either enabled or disabled using the [task cli](/docs/nia/cli/task). When enabled, tasks are executed and automated as described in sections below. However, disabled tasks do not execute when changes are detected from Consul catalog. Since disabled tasks do not execute, they also do not store [events](/docs/nia/tasks#event) until re-enabled.
## Task Execution
A task is executed when any change of information for services the task is configured for is detected from the Consul catalog. Execution could include one or more changes to service values, like IP address, added or removed service instance, or tags. A complete list of values that would cause a task to run are expanded below:
An enabled task is executed when any change of information for services the task is configured for is detected from the Consul catalog. Execution could include one or more changes to service values, like IP address, added or removed service instance, or tags. A complete list of values that would cause a task to run are expanded below:
| Attribute | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
@ -52,7 +54,7 @@ Consul-Terraform-Sync automatically generates any files needed to execute the ne
## Task Automation
Consul-Terraform-Sync will attempt to execute each task once upon startup to synchronize infrastructure with the current state of Consul. The daemon will stop and exit if any error occurs while preparing the automation environment or executing a task for the first time. This helps ensure all tasks have proper configuration and are executable before the daemon transitions into running tasks in full automation as service changes are discovered over time. After all tasks have successfully executed once, task failures during automation will be logged and retried or attempted again after a subsequent change.
Consul-Terraform-Sync will attempt to execute each enabled task once upon startup to synchronize infrastructure with the current state of Consul. The daemon will stop and exit if any error occurs while preparing the automation environment or executing a task for the first time. This helps ensure tasks have proper configuration and are executable before the daemon transitions into running tasks in full automation as service changes are discovered over time. As a result, it is not recommended to configure a task as disabled from the start. After all tasks have successfully executed once, task failures during automation will be logged and retried or attempted again after a subsequent change.
Tasks are executed near-real time when service changes are detected. For services or environments that are prone to flapping, it may be useful to configure a [buffer period](/docs/nia/configuration#buffer_period-1) for a task to accumulate changes before it is executed. The buffer period would reduce the number of consecutive network calls to infrastructure by batching changes for a task over a short duration of time.
@ -67,7 +69,7 @@ These three levels form a hierarchy where each level of data informs the one hig
### Event
Each time a task's services has an update, Consul-Terraform-Sync takes a series of steps in order to update network infrastructure. This process starts with updating the task's templates to fetch new service data from Consul and ends with any post-actions after modifying network infrastructure. An event is a data structure that captures information on this process of updating network infrastructure. It stores information to help understand if the update to network infrastructure was successful or not, and it stores any errors that occurred.
Each time a task's services has an update, Consul-Terraform-Sync takes a series of steps in order to update network infrastructure. This process starts with updating the task's templates to fetch new service data from Consul and ends with any post-actions after modifying network infrastructure. An event is a data structure that captures information on this process of updating network infrastructure. It stores information to help understand if the update to network infrastructure was successful or not, and it stores any errors that occurred. Because disabled tasks do not update network infrastructures, they therefore do not have store events until re-enabled.
Sample event:
```json

125
website/content/docs/nia/terraform-modules.mdx Normal file
View File

@ -0,0 +1,125 @@
---
layout: docs
page_title: Compatible Terraform Modules for NIA
sidebar_title: Terraform Modules
description: >-
Consul-Terraform-Sync automates execution Terraform modules for network infrastructure automation.
---
# Compatible Terraform Modules for Network Infrastructure Automation
-> **Note:** Consul-Terraform-Sync is currently in Beta. Specifications in this section may change going into the General Availability release.
Consul-Terraform-Sync automates execution of Terraform modules through tasks. A task is a construct in Consul-Terraform-Sync that defines the automation of Terraform and the module.
## 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**](#services-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.
## How to Create a Compatible Terraform Module
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.
The repository [hashicorp/consul-terraform-sync-template-module](https://github.com/hashicorp/consul-terraform-sync-template-module) can be cloned and used as a starting point for structuring a compatible Terraform module. The template repository has the files described in the next steps prepared.
First, create a directory to organize Terraform configuration files that make up the module. You can start off with creating two files `main.tf` and `variables.tf` and expand from there based on your module and network infrastructure automation needs.
The `main.tf` is the entry point of the module and this is where you can begin authoring your module. It can contain multiple Terraform resources related to an automation task that uses Consul service discovery information, particularly the required [`services` input variable](#services-variable). The code example below shows a resource using the `services` variable. When this example is used in automation with Consul-Terraform-Sync, the content of the local file would dynamically update as Consul service discovery information changes.
```hcl
# Create a file with service names and their node addresses
resource "local_file" "consul_services" {
content = join("\n", [
for _, service in var.services : "${service.name} ${service.id} ${service.node_address}"
])
filename = "consul_services.txt"
}
```
### Services variable
To satisfy the specification requirements for a compatible module, copy the `services` variable declaration to the `variables.tf` file. Your module can optionally have other [variable declarations](#module-input-variables) in addition to `var.services`.
```hcl
variable "services" {
description = "Consul services monitored by Consul-Terraform-Sync"
type = map(
object({
id = string
name = string
kind = 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)
cts_user_defined_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). A complete list of attributes available for the `services` variable is included in the [documentation for Consul-Terraform-Sync tasks](/docs/nia/tasks#task-execution).
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 `var.services` declaration 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, or omit default values for variables that are required module arguments.
5. Set the [sensitive argument](https://www.terraform.io/docs/language/values/variables.html#suppressing-values-in-cli-output) for variables that contain secret or sensitive values. When set, Terraform will redact the value from output when Terraform commands are run.
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/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
The Terraform module must declare which providers it requires within the [`terraform.required_providers` block](https://www.terraform.io/docs/language/providers/requirements.html#requiring-providers). We suggest to also include a version constraint for the provider to specify which versions the module is compatible with.
Aside from the `required_providers` block, provider configurations should not be included within the sharable 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.

47
website/content/docs/security/security-models/nia.mdx
View File

@ -1,34 +1,27 @@
---
layout: docs
page_title: Consul NIA Security Model
sidebar_title: Network Infrastructure Automation <sup>Tech Preview</sup>
sidebar_title: Network Infrastructure Automation <sup>Beta</sup>
description: >-
Security model including requirements, recommendations, and threats for Consul Network Infrastructure Automation (NIA).
---
## Overview
Consul Network Infrastructure Automation (NIA) enables declarative workflows to handle Day-2 network security
infrastructure tasks for network, security, and operations teams. NIA uses [Terraform](https://www.terraform.io/)
to propagate Consul catalog changes, and relevant configuration to network appliances, or network APIs.
Network Infrastructure Automation (NIA) enables dynamic updates to network infrastructure devices triggered by service changes using the [Consul Terraform Sync](https://github.com/hashicorp/consul-terraform-sync) (`consul-terraform-sync`) daemon. This daemon uses Consul's catalog to monitor networking information about services along with [Terraform](https://www.terraform.io/)'s provider ecosystem to apply relevant changes to network infrastructure.
### Personas
When thinking about Consul NIA, it helps to consider the following types of base personas when managing the security
requirements for the cluster deployment.
- **System Administrator** - This is someone who has access to the underlying infrastructure to the
Consul NIA daemon, and possibly the core Consul service. Often she has access to SSH directly
into a server within a cluster through a bastion host. Ultimately they have read, write and
execute permissions for the actual NIA daemon binary. These users potentially have sudo,
administrative, or some other super-user access to the underlying compute resource. Users like
these are essentially totally trusted by Consul NIA as they have administrative rights to the
system and can start or stop the daemon.
- **Consul NIA Operator** - This is someone (probably the same System Administrator) who has access
to define the Consul NIA daemon configuration, and possibly a Consul ACL token, and other secrets to
run the daemon against various network infrastructure APIs. They also have total rights to all of
the parts in the Consul NIA system including the ability to configure, start, and stop the daemon.
When considering Consul NIA's security model, it helps to think of the following personas.
- **System Administrator** - This is someone who has access to the underlying infrastructure of the
NIA daemon ([`consul-terraform-sync`](https://github.com/hashicorp/consul-terraform-sync)), and possibly the core Consul service. Often she has access to SSH directly
into a server within a cluster through a bastion host. Ultimately they have read, write, and
execute permissions for the `consul-terraform-sync` binary. These users potentially have sudo,
administrative, or some other privileged access to the underlying compute resource. Users like
these are essentially totally trusted by NIA as they have administrative rights to the system.
- **Consul NIA Operator** - This is someone who has access
to define the `consul-terraform-sync` configuration, and possibly a Consul ACL token, and other secrets used to interact with various network infrastructure APIs. They have full access to all parts of `consul-terraform-sync` including the ability to configure, start, and stop the daemon.
- **Developer** - This is someone who is responsible for creating, and possibly deploying applications
connected, or configured with Consul. In some cases they may have no access, or limited capabilities
to view Consul information, such as through metrics, or logs.
@ -39,15 +32,15 @@ requirements for the cluster deployment.
### Secure Configuration
Consul NIA’s security model is applicable only if all parts of the system are running with a secure
configuration; the daemon is not secure-by-default. Without the following mechanisms enabled in the
configuration; `consul-terraform-sync` is not secure-by-default. Without the following mechanisms enabled in the
daemon’s configuration, it may be possible to abuse access to the daemon. Like all security
considerations, one must determine what concerns are appropriate for their environment, and adapt these
security concerns accordingly.
#### Requirements
- **Protect Configuration Files & Directories** - A dedicated NIA daemon user and group with limited
permissions should be created for production, along with directory and file permissions appropriately
- **Protect Configuration Files and Directories** - A dedicated NIA user and group with limited
permissions should be created for production, along with directory, and file permissions appropriately
scoped for your operating environment.
Example commands to illustrate creating a dedicated `consul-nia` system user, along with the supporting
@ -63,8 +56,8 @@ security concerns accordingly.
$ chmod -R 0750 consul-nia/
```
- **Protect Consul KV Path or Namespaces** - Note the NIA daemon can monitor Consul services in other Namespaces.
This can be limited based on the ACL token used for the NIA daemon.
- **Protect Consul KV Path or Namespaces** - Note the daemon can monitor Consul services in other Namespaces.
This can be limited based on the ACL token used for the daemon.
- **Use Consul ACLs** - The Access Control List (ACL) system within Consul can be used to restrict access to
only the required parts of Consul for the NIA daemon to operate.
@ -76,8 +69,6 @@ security concerns accordingly.
- **Use Dedicated Host** - The NIA daemon will potentially have access to critical secrets for your environment’s
network infrastructure. Using a hardened, dedicated host, for supporting these sensitive operations is highly.
Workload orchestrators, such as [HashiCorp Nomad](https://www.nomadproject.io/), also provide benefits of ensuring
uptime and isolation.
- **Run without Root** - The NIA daemon does not require root or other administrative privileges to operate.
@ -85,7 +76,7 @@ security concerns accordingly.
protected using Consul Connect and appropriate firewall rules.
- **Use a centralized logging solution** - Export log entries within [syslog](https://en.wikipedia.org/wiki/Syslog)
generated from the NIA daemon to a centralized logging solution.
generated from `consul-terraform-sync` to a centralized logging solution.
- **Audit used Terraform providers** - [Terraform providers](https://www.terraform.io/docs/providers/index.html) that
are configured with the NIA daemon should be audited to ensure you’re only using providers from sources that
@ -125,7 +116,7 @@ a production deployment:
- **Access (read or write) to the Consul NIA Consul KV Path** - Access to the daemon’s Consul KV path may leak sensitive
information such as usernames, passwords, certificates, and tokens used by Terraform to provision infrastructure.
- **Memory Access to a Running Consul NIA Daemon Process** - Direct access to the memory of running the daemon process
- **Memory Access to a Running Consul-Terraform-Sync Process** - Direct access to the memory of running the daemon process
allows an attacker to extract sensitive information.
- **Memory Access to a Running Terraform Process** - Direct access to the memory of running the Terraform process
@ -134,7 +125,7 @@ a production deployment:
- **Access to the Terraform Binary** - Direct access to the Terraform binary used by the NIA daemon can allow an
attacker to extract sensitive information.
- **Access to the Consul NIA Daemon Binary** - Direct access to the system binary used to start the NIA daemon can allow
- **Access to the Consul-Terraform-Sync Binary** - Direct access to the system binary used to start the NIA daemon can allow
an attacker to extract sensitive information.
#### Internal Threats

13
website/data/docs-navigation.js
View File

@ -222,10 +222,19 @@ export default [
content: ['install', 'requirements', 'configure', 'run'],
},
'architecture',
'api',
'cli',
{
category: 'api',
name: 'API',
content: ['api-overview', 'status', 'tasks'],
},
{
category: 'cli',
name: 'CLI',
content: ['cli-overview', 'task'],
},
'configuration',
'tasks',
'terraform-modules',
'network-drivers',
],
},