HashiConf Last chance to register for our cloud conference October 10-12. Register today
Consul
Network Automation with CTS

Consul-Terraform-Sync and Terraform Enterprise/Cloud integration

  • 14min
  • |
  • Enterprise
  • Terraform
  • Consul

Version Note

The integration with the self-hosted version of Terraform Enterprise is available only in Consul-Terraform-Sync version 0.3.0 and later. The integration with Terraform Cloud is available only in Consul-Terraform-Sync version 0.4.0 and later.

Enterprise Only

The terraform-cloud driver requires Consul-Terraform-Sync Enterprise which is available with Consul Enterprise.

With the 0.3.0 release, Consul-Terraform-Sync added the possibility to run remote operations directly on your Terraform Enterprise instance, using the terraform-cloud driver. With the 0.4.0 release the integration got extended to the Terraform Cloud platform.

In this tutorial you will learn how to configure Consul-Terraform-Sync to interact with Terraform Enterprise and Terraform Cloud.

Prerequisites

  • A running instance of Terraform Enterprise or a Terraform Cloud account.
  • A Consul datacenter; you can use a local dev instance if you do not have a running Consul datacenter.

Start Consul server in dev mode.

$ consul agent -dev

Register a service named web.

$ consul services register -name web -id web01

Registered service: web

Check service is present in the Consul catalog.

$ consul catalog services 

consul
web
  • Consul-Terraform-Sync 0.3.0+ if interacting with a self-hosted instance of Terraform Enterprise or Consul-Terraform-Sync 0.4.0+ if interacting with Terraform Cloud.

Prepare Terraform instance for the integration

Prior to running Consul-Terraform-Sync with a Terraform Cloud driver, you need to have an account on your Terraform instance and an organization set up.

Consul-Terraform-Sync uses API integration to communicate with Terraform, so you will also need a dedicated token.

Once you have an account and organization, the next step is to create a team. We recommend using a dedicated team and team token to run and authenticate Consul-Terraform-Sync. Using a team token has the benefits of restricting organization permissions as well as associating Consul-Terraform-Sync automated actions with the team rather than an individual.

NIA CTS TFE Create Team

After creating a dedicated team, update the team's permissions with "Manage Workspaces" organization access level. Consul-Terraform-Sync's main workflow revolves around creating and managing workspaces. Restricting the dedicated team's permission to "Manage Workspaces" level is sufficient and reduces security risk.

NIA CTS TFE Team Permissions

Finally, create a team token.

NIA CTS TFE Team Token Create

Once created, copy the token and save it in a safe place. You need it to configure Consul-Terraform-Sync.

NIA CTS TFE Team Token Created

Install Consul-Terraform-Sync

To install Consul-Terraform-Sync, find the appropriate package for your system and download it as a zip archive. Unzip the package to extract the binary named consul-terraform-sync.

Visit the Network Infrastructure Automation with Consul-Terraform-Sync Intro tutorial to learn more about the installation process.

Once installed, verify Consul-Terraform-Sync is available in your path:

$ consul-terraform-sync --version

consul-terraform-sync v0.3.0+ent (ed93043)
Compatible with Terraform >= 0.13.0, < 1.1.0

$ consul-terraform-sync --version

consul-terraform-sync v0.4.0+ent
Compatible with Terraform >= 0.13.0, < 1.1.0

Configure Consul-Terraform-Sync license

Consul-Terraform-Sync Enterprise binaries require a Consul Enterprise license to run. There is no Consul-Terraform-Sync Enterprise specific license. As a result, Consul-Terraform-Sync Enterprise's licensing is similar to Consul Enterprise licensing.

If you do not have a valid Consul Enterprise license, you can sign-up for the trial license for Consul Enterprise.

Once you have a license, you can setup the license for Consul-Terraform-Sync in three different ways, in order of precedence:

  • CONSUL_LICENSE: environment variable to set the license value
  • CONSUL_LICENSE_PATH: environment variable to set the path to the file containing the license
  • license_path: configuration file variable to set the path to the file containing the license

The Install a HashiCorp Enterprise License tutorial provides detailed steps on how to configure an enterprise license.

Configure Consul-Terraform-Sync

Next, configure the daemon to interact with your Consul datacenter and your Terraform instance.

cts-config.hcl
## Global Config
log_level   = "DEBUG"
working_dir = "sync-tasks"
port        = 8558

syslog {}

buffer_period {
  enabled = true
  min     = "5s"
  max     = "20s"
}

# Consul Block
consul {
  address = "localhost:8500"
}

# Driver block
driver "terraform-cloud" {
  hostname     = "<TERRAFORM_ADDRESS>"
  organization = "<ORGANIZATION_NAME>"
  token        = "<TEAM_TOKEN>"
  // Optionally set the token to be securely queried from Vault instead of
  // written directly to the configuration file.
  // token = "{{ with secret \"secret/my/path\" }}{{ .Data.data.foo }}{{ end }}"
}

# Task Block
task {
  name        = "learn-cts-example"
  description = "Example task with two services"
  module      = "mkam/hello/cts"
  version     = "0.1.0"
  condition "services" {
    names = ["web", "api"]
  }
}

The terraform-cloud driver block

The driver block configures the subprocess that Consul-Terraform-Sync runs in automation.

The Terraform Cloud driver enables Consul-Terraform-Sync Enterprise to integrate with Terraform Cloud and with Terraform Enterprise, the self-hosted distribution of Terraform Cloud. With this driver, Consul-Terraform-Sync automates Terraform runs and remote operations for workspaces.

To configure the driver block you need the following information:

  • hostname - The Terraform Enterprise hostname to connect to. Can be overridden with the TFC_HOSTNAME environment variable. For Terraform Cloud use https://app.terraform.io as hostname.

  • organization - The organization that hosts the workspaces managed by Consul-Terraform-Sync. Can be overridden with the TFC_ORGANIZATION environment variable.

  • token - Team API token used for authentication with Terraform Enterprise and workspace management. Only workspace permissions are needed for Consul-Terraform-Sync. If you don't want to write it directly in the configuration file, the token can also be:

    • provided by the TFC_TOKEN environment variable
    • securely queried from Vault

Note : Only one network driver can be configured per deployment of Consul-Terraform-Sync. If you need to automate workflows on multiple instances of Terraform Enterprise or have a mixed environment with Terraform Enterprise, Terraform Cloud, and Terraform OSS you need to configure and launch multiple instances of Consul-Terraform-Sync.

The task block

A task is executed when Consul-Terraform-Sync detects any changes associated with services in the catalog that have been configured in the task block. The changes may include one or more of the following events:

  • changes to service values (for example the service's IP address)
  • added or removed service instance
  • added or removed tags

In the example configuration provided, you defined a task block that will monitor and react to changes on web and api services and launch the module defined in the module parameter when any change is detected.

task {
  name        = "learn-cts-example"
  description = "Example task with two services"
  module      = "mkam/hello/cts"
  version     = "0.1.0"
  condition "services" {
    names = ["web", "api"]
  }
}

The module used in this tutorial is the Consul-Terraform-Sync Test Module - Hello. The module creates two text files, a static file and a file that has a greeting for each Consul service. The module will help you test the automation without the need to deploy infrastructure.

The task name, learn-cts-example in this configuration, will be the name of the workspace created in Terraform UI.

Start Consul-Terraform-Sync

Once the configuration is complete, start Consul-Terraform-Sync.

Warning

If you are using Consul-Terraform-Sync version older than v0.6.0, the start parameter is not supported and must be removed.

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

[INFO]  cli: 0.6.0+ent
[INFO]  cli: running controller in daemon mode
[INFO]  cli: setting up controller: type=readwrite
[INFO]  ctrl: initializing Consul client and testing connection
[INFO]  cli: watch and notify any license expiration events
[INFO]  cli: initializing controller
[INFO]  ctrl: initializing driver
[INFO]  ctrl: initializing all tasks
[INFO]  ctrl: initializing task: task=learn-cts-example
[INFO]  driver.terraform: retrieved 0 Terraform handlers for task: task_name=learn-cts-example
[INFO]  driver.tfc: creating workspace: org_name=hashicorp-training workspace_name=learn-cts-example
2021-09-30T20:29:08.002+0200 [DEBUG] driver.tfc: no Terraform version provided, using latest compatible version
[INFO]  templates.tftmpl: overwriting file in root module for task: file_name=variables.tf task_name=learn-cts-example
[DEBUG] templates.tftmpl: creating file in root module for task: file_name=variables.tf task_name=learn-cts-example file_path=sync-tasks/learn-cts-example/variables.tf
[INFO]  templates.tftmpl: overwriting file in root module for task: file_name=main.tf task_name=learn-cts-example
[DEBUG] templates.tftmpl: creating file in root module for task: file_name=main.tf task_name=learn-cts-example file_path=sync-tasks/learn-cts-example/main.tf
[INFO]  driver.tfc: uploading new configuration version for workspace: workspace_name=learn-cts-example
[INFO]  driver.tfc: uploaded new configuration version for workspace: config_version_id=cv-V8SgMPi77SBMRKcD workspace_name=learn-cts-example
[INFO]  driver.tfc: initialized task: task_name=learn-cts-example
[INFO]  ctrl: driver initialized
[INFO]  ctrl: executing all tasks once through
[DEBUG] ctrl: watching dependencies: dependency_size=0
[DEBUG] driver.tfc: change detected for task: task_name=learn-cts-example.services
[INFO]  ctrl: executing task: task_name=learn-cts-example
[INFO]  driver.tfc: creating new run: workspace_name=learn-cts-example
[INFO]  driver.tfc: created new run: run_id=run-e5S1C5PVFeQQ9RAg workspace_name=learn-cts-example
[INFO]  driver.tfc: run results can be viewed at run URL: run_url=https://app.terraform.io/app/hashicorp-training/workspaces/learn-cts-example/runs/run-e5S1C5PVFeQQ9RAg
[INFO]  driver.tfc: waiting on completion of run: run_id=run-e5S1C5PVFeQQ9RAg workspace_name=learn-cts-example
[INFO]  driver.tfc: run completed: run_id=run-e5S1C5PVFeQQ9RAg workspace_name=learn-cts-example
[INFO]  ctrl: task completed: task_name=learn-cts-example
[INFO]  ctrl: all tasks completed once
[INFO]  api: starting server: port=8558
...

From the output, you can verify that Consul-Terraform-Sync successfully connected to Terraform. Additionally, Consul-Terraform-Sync successfully created the learn-cts-example workspace before launching the task.

Verify task execution on Terraform UI

By clicking on the link in the logs, you can verify the run in Terraform Enterprise UI.

NIA CTS TFE Workspace Applying

By clicking on the workspace, you can see the details of the run queued by Consul-Terraform-Sync. Notice that the workspace takes the value of the task name and that the workspace mentions it was created via Consul-Terraform-Sync.

NIA CTS TFE Workspace Applying Details

On the variables tab you can find the terraform.tfvars that, when integrating with Terraform, gets created as a workspace variable.

NIA CTS TFE Workspace Run Variables

Test Consul-Terraform-Sync driven changes

To test the automation, you can register a new service in Consul matching one of the names captured by the task.

$ consul services register -name api -id api01

Once the services is registered you can verify Consul-Terraform-Sync picks up the change from the logs.

...
[DEBUG] driver.tfc: change detected for task: task_name=learn-cts-example.services
[INFO]  ctrl: executing task: task_name=learn-cts-example
[INFO]  driver.tfc: creating new run: workspace_name=learn-cts-example
[INFO]  driver.tfc: created new run: run_id=run-34mBfajomYjsKfsZ workspace_name=learn-cts-example
[INFO]  driver.tfc: run results can be viewed at run URL: run_url=https://app.terraform.io/app/hashicorp-training/workspaces/learn-cts-example/runs/run-34mBfajomYjsKfsZ
[INFO]  driver.tfc: waiting on completion of run: run_id=run-34mBfajomYjsKfsZ workspace_name=learn-cts-example
[INFO]  driver.tfc: run completed: run_id=run-34mBfajomYjsKfsZ workspace_name=learn-cts-example
[INFO]  ctrl: task completed: task_name=learn-cts-example
...

Also, by clicking on the link in the logs, you can verify the run in Terraform UI.

Setup notification for automatic workflows

To monitor the automated runs in your workspace, you can use the "Create a Notification" feature in Terraform Enterprise and Terraform Cloud to receive notifications on your workflow events.

From your workspace tab, navigate over Settings/Notification to setup the feature.

NIA CTS TFE Workspace Settings Notifications

Read more on how to configure notification in Terraform documentation

Clean up resources

To clean up your environment, stop Consul-Terraform-Sync daemon and delete the workspace from Terraform UI.

Navigate to Settings/Destruction and Deletion and click Delete from Terraform Cloud.

NIA CTS TFC Workspace Delete

Next steps

In this tutorial, you learned how to integrate Consul-Terraform-Sync with your Terraform Enterprise and Terraform Cloud instance and automatically run workflows based on your Consul service catalog.

In the next tutorial you will learn the requirements to build a Consul-Terraform-Sync compatible module and the steps to test it and publish it to the Terraform registry.

To learn more about Network Infrastructure Automation with Consul-Terraform-Sync check the full documentation for it on the Consul website.

If you need guidance on how to deploy your services to Consul service mesh, refer to our tutorials for getting started with service mesh on Kubernetes or VMs.

Check out the following tutorials and collections to learn even more about operating, observing, and monitoring your Consul service mesh.

Previous

CTS run modes and status inspection

 Next

Build a custom CTS module