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

Minor followup to nia 0.4.0 docs (#11306) 

* Minor updates to source-input docs
Co-authored-by: lornasong <lornasong@users.noreply.github.com>
This commit is contained in:
Kim Ngo 2021-10-14 12:48:34 -05:00 committed by GitHub
parent 5f762515a1
commit 07425b149c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 57 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -253,7 +253,7 @@ task {
- `recurse` - (bool: false) Setting to `true` instructs Consul-Terraform-Sync to treat the path as a prefix instead of a literal match.
- `datacenter` - (string) The datacenter of the services to query for the task. If not provided, the datacenter will default to the datacenter of the agent that Consul-Terraform-Sync queries.
- `namespace` <EnterpriseAlert inline /> - (string) The namespace of the services to query for the task. If not provided, the namespace will be inferred from the Consul-Terraform-Sync ACL token or default to the `default` namespace.
- `source_includes_var` - (bool: false) If set to `true`, then Consul-Terraform-Sync will include the [`consul_kv` variable](/docs/nia/terraform-modules#consul-kv-variable) as a source input. Refer to the documentation of the selected module for guidance on how to configure this field. If configured inconsistently with the module, Consul-Terraform-Sync will error and exit.
- `source_includes_var` - (bool: false) If set to `true`, then Consul-Terraform-Sync will include the [`consul_kv` variable](/docs/nia/terraform-modules#consul-kv-variable) as an input to the module specified in `task.source`. Refer to the documentation of the selected module for guidance on how to configure this field. If configured inconsistently with the module, Consul-Terraform-Sync will error and exit.
#### Schedule Condition
@ -289,9 +289,9 @@ You can add an optional `source_input` block to the `task` block. The `source_in
This `services` source input object defines services registered to Consul whose metadata will be used as [services source input to the Terraform Module](/docs/nia/terraform-modules/#services-source-input). The following parameters are supported:
| Parameter | Description | Default | Required |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------------------------------------------------------------- |
| `regexp` | String value matching the names of Consul services to monitor. Only services that have a name matching the regular expression are used by the task. <br/><br/> If `regexp` is configured, then [`task.services`](#services) must be omitted or empty. <br/><br/> If both a list and a regex are needed, consider including the list as part of the regex or creating separate tasks. | empty string `""` | Optional unless the `task.services` option is not configured. |
| Parameter | Required |Description | Default |
| --------- | --------- | ---------- | ------- |
| `regexp` | Optional | String value matching the names of Consul services to monitor. Only services that have a name matching the regular expression are used by the task. <br/><br/> If `regexp` is configured, then [`task.services`](#services) must be omitted or empty. <br/><br/> If both a list and a regex are needed, consider including the list as part of the regex or creating separate tasks. | none |
In the following example, the scheduled task queries all Consul services with `web` as the suffix. The metadata of matching services are provided to the Terraform module.
@ -300,12 +300,14 @@ task {
name = "schedule_condition_task"
description = "execute every Monday using information from service names starting with web"
source = "path/to/module"
source_input “services” {
regexp = "^web.*"
}
condition "schedule" {
cron = "* * * * Mon"
}
source_input “services” {
regexp = "^web.*"
}
}
```
@ -313,29 +315,31 @@ task {
A Consul KV source input block defines changes to Consul KV that will be monitored. These changes will then be provided as [Consul KV source input to the Terraform Module](/docs/nia/terraform-modules/#consul-kv-source-input). The source input can be configured for a single Consul KV entry or for any Consul KV entries that are prefixed with a given path. The following parameters are supported:
| Parameter | Description | Default | Required |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------- |
| `path` | String value that specifies the path of the key used by the task. The path can point to a single Consul KV entry or several entries within the path. | none | Required |
| `recurse` | Boolean value that enables Consul-Terraform-Sync to treat the path as a prefix. If set to `false`, the path will be treated as a literal match. | `false` | Optional |
| `datacenter` | String value specifying the name of a datacenter to query for the task. | Datacenter of the agent that Consul-Terraform-Sync queries. | Optional |
| `namespace` | <EnterpriseAlert inline /> <br/> String value indicating the namespace of the services to query for the task. | In order of precedence: <br/> 1. Inferred from the Consul-Terraform-Sync ACL token <br/> 2. The `default` namespace. | Optional |
| Parameter | Required | Description | Default |
| --------- | -------- | ----------- | ------- |
| `path` | Required | String value that specifies the path of the key used by the task. The path can point to a single Consul KV entry or several entries within the path. | none |
| `recurse` | Optional | Boolean value that enables Consul-Terraform-Sync to treat the path as a prefix. If set to `false`, the path will be treated as a literal match. | `false` |
| `datacenter` | Optional | String value specifying the name of a datacenter to query for the task. | Datacenter of the agent that Consul-Terraform-Sync queries. |
| `namespace` | Optional | <EnterpriseAlert inline /> <br/> String value indicating the namespace of the services to query for the task. | In order of precedence: <br/> 1. Inferred from the Consul-Terraform-Sync ACL token <br/> 2. The `default` namespace. |
In the following example, the scheduled task queries datacenter `dc1` in the `default` namespace for changes to the value held by the key `my-key`.
```hcl
task {
name = "schedule_condition_task"
name = "schedule_condition_task_kv"
description = "execute every Monday using information from Consul KV entry my-key"
source = "path/to/module"
condition "schedule" {
cron = "* * * * Mon"
}
source_input "consul-kv" {
path = "my-key"
recurse = false
datacenter = "dc1"
namespace = "default"
}
condition "schedule" {
cron = "* * * * Mon"
}
}
```

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

@ -83,8 +83,7 @@ task {
source = "path/to/services-condition-module"
services = ["api", "db", "web"]
condition "services" {
}
condition "services" {}
}
```
@ -167,7 +166,7 @@ If the task condition's [`source_includes_var`](/docs/nia/configuration#source_i
All scheduled tasks must be configured with a schedule condition. The schedule condition sets the cadence to trigger a task with a [`cron`](/docs/nia/configuration#cron) configuration. The schedule condition block does not support parameters to configure source input. As a result, inputs must be configured separately. You can configure [`task.services`](/docs/nia/configuration#services) or a [`source_input` block](/docs/nia/configuration#source_input) to set the source input.
Below is an example configuration for a task that will execute every Monday, which is set by the schedule condition’s [`cron`](/docs/nia/configuration#cron) configuration. The source input is defined by the `task.services` configuration. When the task is triggered on Monday, it will retrieve the latest information on 'web' and 'db' from Consul and provide this to the module’s input variables.
Below is an example configuration for a task that will execute every Monday, which is set by the schedule condition’s [`cron`](/docs/nia/configuration#cron) configuration. The source input is defined by the `task.services` configuration. When the task is triggered on Monday, it will retrieve the latest information on "web" and "db" from Consul and provide this to the module’s input variables.
```hcl
task {
@ -175,6 +174,7 @@ task {
description = "execute every Monday using service information from web and db"
services = ["web", "db"]
source = "path/to/module"
condition "schedule" {
cron = "* * * * Mon"
}
@ -192,7 +192,7 @@ Scheduled tasks generally run on schedule, but they can be triggered on demand w
- [Long-running mode](/docs/nia/cli#long-running-mode): At the beginning of the long-running mode, Consul-Terraform-Sync first passes through a once-mode phase in which all tasks are executed once. Scheduled tasks will trigger once during this once-mode phase. This behavior also applies to tasks that are not scheduled. After once-mode has completed, scheduled tasks subsequently trigger on schedule.
- [Inspect mode](/docs/nia/cli#inspect-mode): When running in inspect mode, the terminal will output a plan of proposed updates that would be made if the tasks were to trigger at that moment and then exit. The outputted plan for a scheduled task is also the proposed updates that would be made if the task was triggered at that moment, even if off-schedule.
- [Inspect mode](/docs/nia/cli#inspect-mode): When running in inspect mode, the terminal will output a plan of proposed updates that would be made if the tasks were to trigger at that moment and then exit. No changes are applied in this mode. The outputted plan for a scheduled task is also the proposed updates that would be made if the task was triggered at that moment, even if off-schedule.
- [Once mode](/docs/nia/cli#once-mode): During the once mode, all tasks are only triggered one time. Scheduled tasks will execute during once mode even if not on the schedule.

36
website/content/docs/nia/terraform-modules.mdx
View File

@ -31,7 +31,11 @@ See below sections for more information on [defining source input](#source-input
### Source Input
A source input allows for a task to satisfy the input requirements defined by the Terraform Module’s [input variables](https://www.terraform.io/docs/language/values/variables.html), and is configured alongside a task’s condition. Both the source input and condition define objects to be monitored, but for differing reasons. The condition defines monitored objects with criteria. When this criteria is satisfied, Consul-Terraform-Sync will then trigger a task. The source input however, defines monitored objects with the intent of providing values or metadata about these objects to the Terraform Module. The source input and condition objects can be the same, such as when `task.services` is provided without a source input block and condition block, but they can also be defined using separate blocks. In this way the source input does not need to be tied to the provided condition in order to satisfy the Terraform Module.
A source input allows for a task to satisfy the input requirements defined by the Terraform Module’s [input variables](https://www.terraform.io/docs/language/values/variables.html), and is configured alongside a task’s condition. Both the source input and condition define objects to be monitored, but for differing reasons.
The condition defines monitored objects with criteria. When this criteria is satisfied, Consul-Terraform-Sync will then trigger a task.
The source input however, defines monitored objects with the intent of providing values or metadata about these objects to the Terraform Module. The source input and condition objects can be the same, such as when `task.services` is provided without a source input block and condition block, but they can also be defined using separate blocks. In this way the source input does not need to be tied to the provided condition in order to satisfy the Terraform Module.
There are a few ways that a source input can be defined:
@ -52,6 +56,8 @@ Tasks configured with a services source input monitor for changes to services. M
Sample rendered services input:
<CodeBlockConfig filename="terraform.tfvars">
```hcl
services = {
"web.test-server.dc1" = {
@ -81,6 +87,8 @@ services = {
}
```
</CodeBlockConfig>
In order to configure a task with the services source input, the list of services that will be used for the input must be configured in one of the following ways:
- the task's [`services`](/docs/nia/configuration#services)
@ -129,12 +137,16 @@ Tasks configured with a Consul KV source input monitor Consul KV for changes to
Sample rendered consul KV input:
<CodeBlockConfig filename="terraform.tfvars">
```hcl
consul_kv = {
"my-key" = "some value"
}
```
</CodeBlockConfig>
To configure a task with the Consul KV source input, the KVs which will be used for the input must be configured in one of the following ways:
- a [`condition "consul-kv"` block](/docs/nia/configuration#consul-kv-condition) configured with the `source_includes_var` set to true.
@ -167,21 +179,25 @@ Tasks configured with a Catalog Services source input monitors for service and t
Sample rendered catalog-services input:
<CodeBlockConfig filename="terraform.tfvars">
```hcl
catalog_services = {
"api" = ["prod", "staging"]
"api" = ["prod", "staging"]
"consul" = []
"web" = ["blue", "green"]
"web" = ["blue", "green"]
}
```
</CodeBlockConfig>
To configure a task with the Catalog Services source input, the catalog services which will be used for the input must be configured in one of the following ways:
- a [`condition "catalog-services"` block](/docs/nia/configuration#consul-kv-condition) configured with `source_includes_var` set to true.
-> **Note:** Currently there is no support for a `source_input “catalog-services”` block.
Example of a catalog-services condition which supports source input through source_includes_var:
Example of a catalog-services condition which supports source input through `source_includes_var`:
```hcl
task {
@ -268,6 +284,8 @@ Keys of the `services` map are unique identifiers of the service across Consul a
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.
<CodeBlockConfig filename="variables.tf">
```hcl
variable "services" {
description = "Consul services monitored by Consul-Terraform-Sync"
@ -283,10 +301,14 @@ variable "services" {
}
```
</CodeBlockConfig>
### Catalog Services Variable
If you are creating a module for a [catalog-services condition](/docs/nia/tasks#catalog-services-condition), then you have the option to add the `catalog_services` variable, which contains service registration and tag information. If your module would benefit from consuming this information, you can copy the `catalog_services` variable declaration to your `variables.tf` file in addition to the other variables.
<CodeBlockConfig filename="variables.tf">
```hcl
variable "catalog_services" {
description = "Consul catalog service names and tags monitored by Consul-Terraform-Sync"
@ -294,6 +316,8 @@ variable "catalog_services" {
}
```
</CodeBlockConfig>
The keys of the `catalog_services` map are the names of the services that are registered with Consul at the given datacenter. The value for each service name is a list of all known tags for that service.
We recommend that if you make a module with with a catalog-services condition, that you document this in the README. This way, users that want to configure a task with your module will know to configure a catalog-services [condition](/docs/nia/configuration#condition) block.
@ -304,6 +328,8 @@ Similarly, if you include the `catalog_services` variable in your module, we rec
If you are creating a module for a [consul-kv condition](/docs/nia/tasks#consul-kv-condition), then you have the option to add the `consul_kv` variable, which contains a map of the keys and values for the Consul KV pairs. If your module would benefit from consuming this information, you can copy the `consul_kv` variable declaration to your `variables.tf` file in addition to the other variables.
<CodeBlockConfig filename="variables.tf">
```hcl
variable "consul_kv" {
description = "Keys and values of the Consul KV pairs monitored by Consul-Terraform-Sync"
@ -311,6 +337,8 @@ variable "consul_kv" {
}
```
</CodeBlockConfig>
If your module contains the `consul_kv` variable, we recommend documenting the usage in the README file so that users know to set the [`source_includes_var`](/docs/nia/configuration#source_includes_var-1) configuration to `true` in the `consul-kv` condition. Setting the field to `true` instructs Consul-Terraform-Sync to declare the `consul_kv` variable in the generated root module and pass the variable to a child module. Therefore, if this field is configured inconsistently, Consul-Terraform-Sync will error and exit.
### Module Input Variables