Consul-Terraform-Sync run modes and status inspection
In the previous tutorial you learned how to install Consul-Terraform-Sync, the HashiCorp's Network Infrastructure Automation tool, to configure a task to monitor services in your Consul datacenter, to run it in daemon mode and to check the information it retrieves from Consul.
In this tutorial you will learn the different run modes available with Consul-Terraform-Sync, how to monitor the task status, and to locate the Terraform state files in the Consul backend.
Prerequisites
Prerequisite for this tutorial are the same as the ones you had for the previous one, specifically you will need:
A Consul datacenter with two registered services,
web
andapi
. You can follow the Network Infrastructure Automation with Consul-Terraform-Sync Intro for guidance on installing Consul.The Consul-Terraform-Sync binary
Terraform 0.13.0+ binary (will be automatically installed if not present).
For this tutorial, you will be using the Consul Print Module to configure Consul-Terraform-Sync. This Terraform module creates text files on your local machine containing Consul service information. It is a useful module to use to familiarize yourself with Consul Terraform Sync, without requiring deployed infrastructure and credentials.
Configure Consul-Terraform-Sync
The Consul-Terraform-Sync daemon is configured using configuration files and supports HashiCorp Configuration Language (HCL) and JSON file formats.
For this tutorial you will use the same configuration used in the previous tutorial.
Copy the content of the code block below and save it in a file named
cts-config.hcl
.
Start Consul-Terraform-Sync
Once the configuration file is created it is possible to start
Consul-Terraform-Sync using the consul-terraform-sync
binary. The binary
requires the configuration to be passed either using the -config-file
or
-config-dir
.
Consul-Terraform-Sync is intended to be run as a long-running daemon to be able to monitor Consul events and adapt your infrastructure accordingly. For better flexibility it also has different modes to run including some that can be useful to safely test your configuration and the changes that are going to be applied or to run them only once if you do not need to dynamically adapt your infrastructure deployment.
In this tutorial you will first inspect the validity of the configuration using the inspect mode, test the module correctness running in once mode, and finally run in daemon mode to verify the Consul-Terraform-Sync status.
Inspect mode
Inspect mode is designed to help you examine the changes that your configuration, once ran via Terraform, will apply to your infrastructure. Running Consul-Terraform-Sync in inspect mode will apply no changes to your infrastructure but will exit with a non-zero exit status if any error is encountered.
This is achieved by Consul-Terraform-Sync running terraform plan
for each
task in the configuration.
The inspect mode is intended to be ran before daemon mode to confirm configuration is accurate.
The inspect mode by default inspects all the available tasks in the
configuration, it is possible to inspect only single tasks in case you want to
confirm a configuration change is correct without the need to inspect the rest
of the tasks unaffected by the change. You can do this using the
-inspect-task [task-name]
flag instead.
Once mode
Once inspection is successful you might still want to test-run it to make sure it fully works before delegating to Consul-Terraform-Sync the infrastructural changes. You can do this by using the once running mode that will run all tasks once and gracefully exit or exit with a non-zero status in case an error is encountered before completion.
This is achieved by Consul-Terraform-Sync running terraform apply
for each
task in the configuration.
Daemon mode
Once you verified the correctness of the configuration and the proper execution of the different tasks configured you can now launch Consul-Terraform-Sync as a long running process.
Use the status
API to monitor task execution
Consul-Terraform-Sync provides the /status
REST endpoints to 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.
The 5 most recent events are stored in Consul-Terraform-Sync.
Example output:
Terraform state in Consul
When using Consul as a backend for Consul-Terraform-Sync the Terraform state will be persisted in the Consul KV store as a different state file for each task.
The default path for the state object is consul-terraform-sync/terraform-env:task-name
with task-name
being the task identifier appended to the end of the path.
Next steps
In this tutorial you learned the different run modes for Consul-Terraform-Sync and how to inspect task status using the REST API, and Terraform state when using Consul as backend for Terraform.
Specifically you:
- Tried the three different execution modes: daemon, inspect, and once
- Verified tasks execution using the REST API
- Checked the Terraform state files in Consul using Consul UI
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.
To learn even more about operating, observing, and monitoring your Consul service mesh, check out the following tutorials and collections.