Beta CTS Docs (#12916)
* updated beta docs * Update website/content/docs/release-notes/consul-terraform-sync/v0_6_0_beta.mdx Co-authored-by: AJ Jwair <aj.jwair@hashicorp.com> * Update website/content/docs/release-notes/consul-terraform-sync/v0_6_0_beta.mdx Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * Update website/content/docs/release-notes/consul-terraform-sync/v0_6_0_beta.mdx Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * Update website/content/docs/release-notes/consul-terraform-sync/v0_6_0_beta.mdx Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * Update website/content/docs/release-notes/consul-terraform-sync/v0_6_0_beta.mdx Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * Update website/content/docs/release-notes/consul-terraform-sync/v0_6_0_beta.mdx Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * Update website/content/docs/release-notes/consul-terraform-sync/v0_6_0_beta.mdx Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * updated beta docs * updated beta docs * updated beta docs * updated docs * updated docs * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * update docs * Update website/content/docs/release-notes/consul-terraform-sync/v0_6_0_beta.mdx Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> * docs/nia: Health endpoint and service registration - Add Health endpoint docs - Add CTS service registration docs * update docs * docs/nia: Miscellaneous fixes to beta docs Co-authored-by: lornasong <lornasong@users.noreply.github.com> * docs/nia: Update TFC agents description Co-authored-by: AJ Jwair <aj.jwair@hashicorp.com> Co-authored-by: Melissa Kam <3768460+mkam@users.noreply.github.com> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: lornasong <lornasong@users.noreply.github.com> Co-authored-by: Melissa Kam <mkam@hashicorp.com>
This commit is contained in:
Michael Wilkerson
GitHub
parent
a74710fd45
commit
3a196db8de
|
|
@ -0,0 +1,325 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: CTS v0.6.0 Beta
|
||||
description: >-
|
||||
Consul-Terraform-Sync beta release notes for v0.6.0
|
||||
---
|
||||
|
||||
-> The beta release notes for v0.6.0 focus on changes and deprecations in the upcoming Consul-Terraform-Sync (CTS) v0.6.0 release. Details of these features are subject to change as the beta period commences.
|
||||
|
||||
# New and Deprecated Features in v0.6.0
|
||||
|
||||
**Feature Summary:**
|
||||
|
||||
- New CLI Start Command
|
||||
- New CLI Autocompletion
|
||||
- Addition of Features to Support HCP Consul <EnterpriseAlert inline />
|
||||
- Addition of Features to Support Terraform Cloud Agents <EnterpriseAlert inline />
|
||||
- Get All Tasks API Endpoint
|
||||
- Health API Endpoint
|
||||
- CTS Service Registration with Consul
|
||||
|
||||
For additional information, see the [changelog in the CTS repository](https://github.com/hashicorp/consul-terraform-sync/blob/release/0.6.0-beta/CHANGELOG.md)
|
||||
|
||||
## Introduction of CLI Start Command
|
||||
~> Running CTS as a daemon without using a command is deprecated in CTS 0.6.0. The feature will be removed at a much later date in a major release. The preferred way to run CTS is to use the `start` command.
|
||||
|
||||
### start
|
||||
|
||||
In v0.6.0, the `start` command is the new and preferred way to start CTS as a daemon. This command shares the same behavior as running CTS without a command.
|
||||
|
||||
When CTS runs as a daemon, there is no default configuration to start CTS. You must set a configuration flag `-config-file` or `-config-dir`. For example:
|
||||
|
||||
```shell-session
|
||||
$ consul-terraform-sync start -config-file=config.hcl
|
||||
```
|
||||
|
||||
To review a list of available flags, use the `-help` or `-h` flag.
|
||||
|
||||
##### Options
|
||||
|
||||
The `start` command supports the following options:
|
||||
|
||||
| Name | Required | Type | Description |Default |
|
||||
| --------------- | -------- | ------- | ------------------------------- | ----------------------- |
|
||||
| `-config-dir ` | Required if `-config-file` not set | string | A directory to load files for configuring CTS. Configuration files require an .hcl or .json file extension in order to specify their format. This option can be specified multiple times to load different directories. | none |
|
||||
| `-config-file` | Required if `-config-dir` not set | string | A file to load for configuring CTS. Configuration file requires an .hcl or .json extension in order to specify their format. This option can be specified multiple times to load different configuration files. | none |
|
||||
| `-inspect` | Optional | boolean | Run CTS in Inspect mode to print the proposed state changes for all tasks, and then exit. No changes are applied in this mode. | false |
|
||||
| `-inspect-task` | Optional | string | Run CTS in Inspect mode to print the proposed state changes for the task, and then exit. The flag can be specified multiple times to inspect multiple tasks. No changes are applied in this mode. | none |
|
||||
| `-once` | Optional | boolean | Render templates and run tasks once. Does not start the process in long-running mode and disables buffer periods. | false |
|
||||
|
||||
## New CLI Autocompletion
|
||||
|
||||
In v0.6.0, the `consul-terraform-sync` command features opt-in autocompletion for flags, subcommands, and
|
||||
arguments (where supported).
|
||||
|
||||
To enable autocompletion, run:
|
||||
|
||||
```shell-session
|
||||
$ consul-terraform-sync -autocomplete-install
|
||||
```
|
||||
|
||||
~> After you install autocomplete, you must restart your shell for the change to take effect.
|
||||
|
||||
When you start typing a CTS command, press the `<tab>` key to show a
|
||||
list of available completions. To show available flag completes, type `-<tab>`.
|
||||
|
||||
If the `CTS_*` environment variables are set, the autocompletion
|
||||
automatically queries the running CTS server and returns helpful argument suggestions.
|
||||
|
||||
## Addition of Features to Support HCP Consul <EnterpriseAlert inline />
|
||||
|
||||
In v0.6.0, CTS officially supports HCP Consul. To help enable this support, v0.6.0 introduces license auto-retrieval (**Enterprise only**). The auto-retrieval feature works for both on-premise Consul Enterprise and HCP Consul, but it is especially useful for HCP Consul because the licenses for this service expire much sooner.
|
||||
|
||||
### License
|
||||
|
||||
#### Setting the License Manually
|
||||
~> In v0.6.0, CTS is configured by default to automatically retrieve a license from its configured Consul Enterprise backend when it starts. It also retrieves new licenses periodically.
|
||||
|
||||
If a license needs to be manually set, use one of the [existing methods](/docs/nia/enterprise/license#setting-the-license), or use the new license block:
|
||||
|
||||
```hcl
|
||||
license {
|
||||
path = "<PATH>/<TO>/<FILE>"
|
||||
}
|
||||
```
|
||||
|
||||
#### Updating the License Manually
|
||||
~> CTS automatically retrieves a license from its configured Consul Enterprise backend by default. If this default settings is disabled, follow the instructions under [Updating the License](/docs/nia/enterprise/license#updating-the-license).
|
||||
|
||||
#### License Expiration Handling
|
||||
As the license expiration date approaches, CTS Enterprise automatically retrieves a new license by default. If the automatic license retrieval fails, CTS increases the number of retrieval attempts. If auto-retrieval is disabled, CTS Enterprise provides notifications in the system logs:
|
||||
|
||||
| Time period | Behavior - auto-retrieval enabled (default) |Behavior - auto-retrieval disabled |
|
||||
| ------------------------------------------- |-------------------------------------------- |---------------------------------- |
|
||||
| 30 days before expiration | License retrieval attempt every 24-hours | Warning-level log every 24-hours |
|
||||
| 7 days before expiration | License retrieval attempt every 1 hour | Warning-level log every 1 hour |
|
||||
| 1 day before expiration | License retrieval attempt every 5 minutes | Warning-level log every 5 minutes |
|
||||
| 1 hour before expiration | License retrieval attempt every 1 minute | Warning-level log every 1 minute |
|
||||
| At or after expiration (before termination) | License retrieval attempt every 1 minute | Error-level log every 1 minute |
|
||||
| At or after termination | Error-level log and exit | Error-level log and exit |
|
||||
|
||||
#### License Configuration
|
||||
|
||||
~> [`license_path`](/docs/nia/configuration#license_path) <EnterpriseAlert inline /> is deprecated as of v0.6.0. The preferred way to set the license configuration is to use the 'license' block.
|
||||
|
||||
To configure how CTS attains a license, use the 'license' block. You can:
|
||||
- Provide a path to a license file.
|
||||
- Configure CTS to automatically retrieve a license from Consul.
|
||||
If a license block is not configured, 'license.auto_retrieval.enabled' defaults to true.
|
||||
|
||||
```hcl
|
||||
license {
|
||||
path = "path/to/license.lic"
|
||||
auto_retrieval {
|
||||
enabled = true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### License Config
|
||||
| Parameter | Required | Type | Description | Default |
|
||||
| --------- | -------- | ---- | ----------- | ------- |
|
||||
| `path` | Optional | string | Configures the path to the file containing a license. If a path to a license is configured, this license is used until you enable automatic license retrieval. You can also set the license by defining the `CONSUL_LICENSE` and `CONSUL_LICENSE_PATH` environment variables. To learn more, review [Setting the License](/docs/nia/enterprise/license#setting-the-license). | none |
|
||||
| `auto_retrieval` | Optional | object | Configures the license auto-retrieval used by CTS. To learn more, review [Auto-Retrieval Config](/docs/release-notes/consul-terraform-sync/v0_6_0_beta#auto-retrieval-config) for details | Review [Auto-Retrieval Config](/docs/release-notes/consul-terraform-sync/v0_6_0_beta#auto-retrieval-config) for defaults. |
|
||||
|
||||
|
||||
##### Auto-Retrieval Config
|
||||
|
||||
You can use the `auto_retrieval` block to configure the the automatic license retrieval in CTS. When enabled, CTS attempts to retrieve a new license from its configured Consul Enterprise backend once a day. If CTS cannot retrieve a license and the current license is reaching its expiration date, CTS attempts to retrieve a license with increased frequency, as defined by the [License Expiration Date Handling](/docs/release-notes/consul-terraform-sync/v0_6_0_beta#license-expiration-handling).
|
||||
|
||||
~> `auto_retrieval` is an important feature to enable when you connect to HCP Consul. To ensure that CTS can work without restarting the service, it is important for CTS to have the ability to dynamically obtain fresh licenses from HCP Consul.
|
||||
|
||||
| Parameter | Required | Type | Description | Default |
|
||||
| --------- | -------- | ---- | ----------- | ------- |
|
||||
| `enabled` | Optional | string | If set to true, enables license auto-retrieval | true |
|
||||
|
||||
## Additional Features to Support Terraform Cloud (TFC) Agents <EnterpriseAlert inline />
|
||||
|
||||
In v0.6.0, CTS officially supports [Terraform Cloud agents](https://www.terraform.io/cloud-docs/agents). Previously, CTS could use only existing workspaces that were manually configured with Terraform Cloud agents. CTS now supports creating new workspaces that use agents and updating existing workspaces to use agents.
|
||||
|
||||
### Terraform Cloud Remote Workspaces
|
||||
|
||||
Use the [`terraform_cloud_workspace`](/docs/release-notes/consul-terraform-sync/v0_6_0_beta#terraform-cloud-workspace-configuration) configuration in the [`task`](/docs/nia/configuration#task) configuration block to enable Terraform Cloud agents for a task's workspace. The `terraform_cloud_workspace` controls options for Terraform version, execution mode, and agent pools. Note that these options are different from the global workspace configurations set on the [`driver.workspaces`](/docs/nia/configuration#workspaces) configuration.
|
||||
|
||||
For a task to use Terraform Cloud agents, `terraform_cloud_workspace.execution_mode` must be set to "agent" and either `terraform_cloud_workspace.agent_pool_id` or `terraform_cloud_workspace.agent_pool_name` must be specified.
|
||||
|
||||
#### Terraform Cloud Workspace Configuration
|
||||
~> Configuring [`terraform_version`](/docs/nia/configuration#terraform_version) <EnterpriseAlert inline /> is deprecated as of v0.6.0. Use `terraform_cloud_workspace.terraform_version` instead.
|
||||
|
||||
You can use the new `terraform_cloud_workspace` `task` configuration object to configure attributes of the Terraform Cloud workspace associated with the task. This option is only available when used with the [Terraform Cloud driver](/docs/nia/configuration#terraform-cloud-driver). For global configurations of all workspaces, review [`driver.workspaces`](/docs/nia/configuration#workspaces).
|
||||
|
||||
```hcl
|
||||
task {
|
||||
name = "terraform_cloud_agent_task"
|
||||
description = "execute on changes to services with names starting with web using cloud agents"
|
||||
providers = ["my-provider"]
|
||||
module = "path/to/services-condition-module"
|
||||
|
||||
condition "services" {
|
||||
regexp = "^web.*"
|
||||
datacenter = "dc1"
|
||||
}
|
||||
|
||||
terraform_cloud_workspace {
|
||||
execution_mode = "agent"
|
||||
agent_pool_id = "apool-v9ZZW1qACRjTyzWh"
|
||||
terraform_version = "1.1.5"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The configuration options are:
|
||||
|
||||
| Name | Required | Type | Description |Default |
|
||||
| --------------- | -------- | ------- | ------------------------------- | ----------------------- |
|
||||
| `execution_mode ` | Optional | string | The execution mode that determines whether to use Terraform Cloud as the Terraform execution platform. Only supports "remote" or "agent".| "remote" |
|
||||
| `agent_pool_id` | Optional | string | The id of the agent pool that should run the Terraform workloads. Only supported if `execution_mode` is set to "agent". Either `agent_pool_id` or `agent_pool_name` are required. `agent_pool_id` takes precedence over `agent_pool_name` if both are provided. | none |
|
||||
| `agent_pool_name` | Optional | string | The name of the agent pool that should run the Terraform workloads. Only supported if `execution_mode` is set to "agent". Either `agent_pool_id` or `agent_pool_name` are required. `agent_pool_id` takes precedence over `agent_pool_name` if both are provided. | none |
|
||||
| `terraform_version` | Optional | string | The version of Terraform to use for the Terraform Cloud workspace associated with the task. Defaults to the latest compatible version supported by the organization. | none |
|
||||
|
||||
## Get All Tasks Endpoint
|
||||
|
||||
The Get `/tasks` endpoint returns information about all existing tasks in CTS.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/tasks` | `application/json` |
|
||||
|
||||
### Response Statuses
|
||||
|
||||
| Status | Reason |
|
||||
| ------ | ---------------------------------------------------- |
|
||||
| 200 | Successfully retrieved and returned a list of tasks |
|
||||
|
||||
### Response Fields
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------------- | ---------------------------------------------------------------------------------- |
|
||||
| `request_id` | string | The ID of the request. Used for auditing and debugging purposes. |
|
||||
| `tasks` | list[[Task](/docs/nia/api/tasks#task-object)] | A list of Tasks |
|
||||
|
||||
### Example: Retrieve all tasks
|
||||
|
||||
In this example, CTS contains a single task
|
||||
|
||||
Request:
|
||||
|
||||
```shell-session
|
||||
$ curl --request GET \
|
||||
localhost:8558/v1/tasks
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "0e0290f9-94df-3a4a-fd17-72467a16083c",
|
||||
"tasks": [
|
||||
{
|
||||
"buffer_period": {
|
||||
"enabled": true,
|
||||
"max": "25s",
|
||||
"min": "5s"
|
||||
},
|
||||
"condition": {
|
||||
"services": {
|
||||
"cts_user_defined_meta": {},
|
||||
"datacenter": "",
|
||||
"filter": "",
|
||||
"names": ["api", "web"],
|
||||
"namespace": "",
|
||||
"use_as_module_input": true
|
||||
}
|
||||
},
|
||||
"description": "Writes the service name, id, and IP address to a file",
|
||||
"enabled": true,
|
||||
"module": "path/to/module",
|
||||
"module_input": {},
|
||||
"name": "task_a",
|
||||
"providers": ["my-provider"],
|
||||
"variables": {},
|
||||
"version": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Health Endpoint
|
||||
The `/health` endpoint returns a successful response if CTS is available and running. Requests to this endpoint are not logged, which makes it suitable for health checks that constantly poll CTS.
|
||||
|
||||
| Method | Path | Produces |
|
||||
| ------ | ------------------- | ------------------ |
|
||||
| `GET` | `/health` | `application/json` |
|
||||
|
||||
### Response Statuses
|
||||
|
||||
| Status | Reason |
|
||||
| ------ | ---------------------------------------------------- |
|
||||
| 200 | CTS is healthy |
|
||||
|
||||
### Response Fields
|
||||
|
||||
| Name | Type | Description |
|
||||
| ------------ | ------ | ---------------------------------------------------------------------------------- |
|
||||
| `request_id` | string | The ID of the request. Used for auditing and debugging purposes. |
|
||||
|
||||
### Example
|
||||
|
||||
The following request makes a `GET` call to the `health` endpoint:
|
||||
|
||||
```shell-session
|
||||
$ curl --request GET \
|
||||
localhost:8558/v1/health
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "b7559ab0-5111-381b-367a-0dfb7e216d41"
|
||||
}
|
||||
```
|
||||
|
||||
## CTS Service Registration With Consul
|
||||
By default, CTS automatically registers itself as a service in Consul with a health check. The default health check is an HTTP check to the [health API endpoint](#health-endpoint). CTS deregisters itself with Consul when CTS stops gracefully.
|
||||
|
||||
If ACLs are enabled in Consul, then the [Consul token](/docs/nia/configuration#token) must have the policy `service:write` for service registration to succeed. Previously, CTS only required read access for services, so tokens used prior to 0.6.0 may not work with service registration.
|
||||
|
||||
If CTS is unable to register with Consul, then it will log the error and continue without exiting.
|
||||
|
||||
### Configuration
|
||||
Specify the global configuration `id` to assign instances of CTS an ID, which is used as the service ID for CTS if service registration is enabled. Configure the `service_registration` block in the `consul` configuration to configure the registration details. All configurations are optional.
|
||||
|
||||
```hcl
|
||||
id = "cts-01"
|
||||
|
||||
consul {
|
||||
service_registration {
|
||||
enabled = true
|
||||
service_name = "cts"
|
||||
namespace = "ns-1"
|
||||
default_check {
|
||||
enabled = true
|
||||
address = "http://172.22.0.2:8558"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The following table describes the options for the `id` global configuration:
|
||||
|
||||
| Name | Required | Type | Description |Default |
|
||||
| --------------- | -------- | ------- | ------------------------------- | ----------------------- |
|
||||
| `id ` | Optional | string | The ID of the CTS instance. Used as the service ID for CTS if service registration is enabled. | Generated ID with the format `cts-<uuid>` |
|
||||
|
||||
|
||||
The following table describes configuration options for `consul.service_registration`:
|
||||
|
||||
| Name | Required | Type | Description |Default |
|
||||
| --------------- | -------- | ------- | ------------------------------- | ----------------------- |
|
||||
| `enabled ` | Optional | boolean | Enables CTS to register itself as a service with Consul. | `true` |
|
||||
| `service_name` | Optional | string | The service name for CTS. | `Consul-Terraform-Sync` |
|
||||
| `namespace` | Optional | string | <EnterpriseAlert inline /> The namespace to register CTS in. | In order of precedence: <br/> 1. Inferred from the CTS ACL token <br/> 2. The `default` namespace. |
|
||||
| `default_check.enabled` | Optional | boolean | Enables CTS to create the default health check. | `true` |
|
||||
| `default_check.address` | Optional | string | The address to use for the default HTTP health check. Needs to include the scheme (`http`/`https`) and the port (if necessary). | `http://localhost:<port>` or `https://localhost:<port>`. Determined from the [port configuration](/docs/nia/configuration#port) and whether [TLS is enabled](/docs/nia/configuration#enabled-2) on the CTS API. |
|
||||
|
|
@ -1256,6 +1256,10 @@
|
|||
{
|
||||
"title": "v0.5.x",
|
||||
"path": "release-notes/consul-terraform-sync/v0_5_x"
|
||||
},
|
||||
{
|
||||
"title": "v0.6.0-beta",
|
||||
"path": "release-notes/consul-terraform-sync/v0_6_0_beta"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue