»New and Deprecated Features in v0.6.0

Feature Summary:

• New CLI Start Command
• New CLI Autocompletion
• Addition of Features to Support HCP Consul
  Enterprise
• Addition of Features to Support Terraform Cloud Agents
  Enterprise
• Get All Tasks API Endpoint
• Health API Endpoint
• CTS Service Registration with Consul

For additional information, see the changelog in the CTS repository

»Introduction of CLI 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:

$ consul-terraform-sync start -config-file=config.hcl

$ 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:

»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:

$ consul-terraform-sync -autocomplete-install

$ consul-terraform-sync -autocomplete-install

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

Enterprise

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

If a license needs to be manually set, use one of the existing methods, or use the new license block:

license {
  path = "<PATH>/<TO>/<FILE>"
}

license {
  path = "<PATH>/<TO>/<FILE>"
}

»Updating the License Manually

»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:

»License Configuration

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.

license {
  path = "path/to/license.lic"
  auto_retrieval {
    enabled = true
  }
}

license {
  path = "path/to/license.lic"
  auto_retrieval {
    enabled = true
  }
}

»License Config

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

»Additional Features to Support Terraform Cloud (TFC) Agents

Enterprise

In v0.6.0, CTS officially supports Terraform Cloud 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 configuration in the 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 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

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. For global configurations of all workspaces, review driver.workspaces.

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"
  }
}

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:

»Get All Tasks Endpoint

The Get /tasks endpoint returns information about all existing tasks in CTS.

»Response Statuses

»Response Fields

»Example: Retrieve all tasks

In this example, CTS contains a single task

Request:

$ curl --request GET \
  localhost:8558/v1/tasks

$ curl --request GET \
  localhost:8558/v1/tasks

Response:

{
  "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": ""
    }
  ]
}

{
  "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.

»Response Statuses

»Response Fields

»Example

The following request makes a GET call to the health endpoint:

$ curl --request GET \
  localhost:8558/v1/health

$ curl --request GET \
  localhost:8558/v1/health

Response:

{
  "request_id": "b7559ab0-5111-381b-367a-0dfb7e216d41"
}

{
  "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. CTS deregisters itself with Consul when CTS stops gracefully.

If ACLs are enabled in Consul, then the Consul 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.

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"
    }
  }
}

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:

The following table describes configuration options for consul.service_registration: