nia/docs 0.1.0 beta (#9803) (#9834)

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>

website/content/docs/integrate/nia-integration.mdx

@@ -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,15 +87,15 @@ 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
 
 Many partners view the release step to be the end of the journey, while at HashiCorp we view it to be the start. Getting the Consul-Terraform-Sync compatible module built is just the first step in enabling users to use it against the infrastructure. Once this is done, on-going effort is required to maintain the module and address any issues in a timely manner.
 
 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
 

website/content/docs/nia/api/api-overview.mdx

@@ -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"
+  }
+}
+```

website/content/docs/nia/api.mdx → website/content/docs/nia/api/status.mdx

@@ -1,44 +1,18 @@
 ---
 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.
 
@@ -52,10 +26,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
 
@@ -70,14 +49,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.
 
@@ -104,6 +90,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.
@@ -140,13 +127,15 @@ Response:
   "task_a": {
     "task_name": "task_a",
     "status": "successful",
+    "enabled": true,
     "providers": ["local"],
     "services": ["api"],
     "events_url": "/v1/status/tasks/task_a?include=events"
   },
   "task_b": {
     "task_name": "task_b",
     "status": "errored",
+    "enabled": false,
     "providers": ["null"],
     "services": ["web"],
     "events_url": "/v1/status/tasks/task_b?include=events"
@@ -169,6 +158,7 @@ Response:
   "task_b": {
     "task_name": "task_b",
     "status": "errored",
+    "enabled": false,
     "providers": ["null"],
     "services": ["web"],
     "events_url": "/v1/status/tasks/task_b?include=events",

website/content/docs/nia/api/tasks.mdx

@@ -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."
+}
+```

website/content/docs/nia/architecture.mdx

@@ -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.

website/content/docs/nia/cli.mdx → website/content/docs/nia/cli/cli-overview.mdx

@@ -1,36 +1,38 @@
 ---
 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
 ```
 
 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.