Register your services to Consul
In the previous tutorial, you deployed a Consul server with all security features enabled.
In this tutorial, you will deploy Consul client agents to your virtual machine (VM) workloads. Then, you will register the services to the Consul catalog and setup a distributed monitoring system using Consul health checks.
Tutorial scenario
This tutorial uses HashiCups, a demo coffee shop application made up of several microservices running on VMs.
At the beginning of the tutorial, you have an instance of HashiCups running on four VMs and one Consul server (you deployed this in the previous tutorial.
By the end of this tutorial, you will have deployed and started a Consul client agent on each VMs that hosts HashiCups. In addition, you will have registered the HashiCups services in the Consul service catalog and setup health checks for each service.
Prerequisites
This tutorial uses an interactive lab to guide you through how to deploy Consul client agents on VMs hosting your services. This lab environment includes all required binaries and sample configurations. We highly recommend using the interactive lab environment to complete this tutorial.
Launch Terminal
This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.
Verify Consul binary
Verify that the VM you want to deploy the Consul server on has the Consul binary.
Configure environment
This tutorial and interactive lab environment uses scripts in the tutorial's GitHub repository to generate the Consul configuration files for your client agents.
The interactive lab environment includes these scripts and the pre-configured Consul server. In Operator, list the files in your current directory.
The script relies on default parameters to generate the configuration files. Set the following default values. Ensure you have permission to write in the specified paths.
Tip
We suggest using an unprivileged user to run Consul for security reasons.
In addition, the Consul client agents must have following Consul resources that are compatible with your Consul server:
- The root CA certificate that you generated during the Consul server deployment.
- The gossip encryption key that you used to encrypt gossip communication.
Define these files' path. The script will include resources in the auto-generated client configuration files
Finally, the script uses Consul CLI to interact with Consul server and generate tokens for the Consul client agents. In order to interact with the Consul server, you need to setup your terminal.
Run the following commands to configure the Consul CLI to interact with the Consul server.
You also need to provide an ACL token to authenticate to your Consul server. In the previous tutorial, you generated an ACL token and stored it in a file.
Retrieve this value and set it to an environment variable named CONSUL_HTTP_TOKEN
.
Verify your Consul CLI can interact with your Consul server.
Generate Consul clients configuration
Once you have set up your environment by defining the defaults for your script and configuring the Consul CLI, generate the Consul clients configuration files.
The script generates the configuration files into multiple directory, one for each client HashiCups node.
Note
The script is configured for the interactive lab environment. You may need to adapt the ACL policies and service definitions if you are running this on your own environment.
Copy configuration on client VMs
After the script generates the client configuration, you will copy these files into the respective Consul configuration directories in each client node.
Tip
In the interactive lab environment, the HashiCups application nodes have a running SSH server. As a result, you can use ssh
and scp
commands to perform the following operations. If the nodes in your personal environment does not have an SSH server, you may need to use a different approach to create the configuration directories and copy the files.
First, create the directories for Consul in all client nodes. The command will create both the configuration directory (/etc/consul/config
) and the data directory (/etc/consul/data
) on the client nodes.
Then, copy the configuration files in each node's configuration folder.
Start Consul on client VMs
Now that you have copied the configuration files to each client VMs, you will start the Consul client agent on each VM.
Setup Database Consul client agent
Log into the virtual machine that hosts the database.
Tip
For the interactive lab environment, select the tab that corresponds with the service — in this case, Database.
Create an environment variable named CONSUL_CONFIG_DIR
and set it to your Consul configuration directory path.
Verify the configuration files are present in this directory.
Validate the configuration.
Tip
Despite the INFO
messages, the Consul configuration files are valid.
Finally, start the Consul client.
Tip
This tutorial uses the ${HOSTNAME}
variable to define the node name for each Consul client. You can replace that with a different value as long as you do not use duplicate node names.
For production environments, we recommend using systemd
to start Consul. Complete the Deloyment Guide tutorial for Consul deployment best practices.
Setup API Consul client agent
Log into the virtual machine that hosts the API.
Create an environment variable named CONSUL_CONFIG_DIR
and set it to your Consul configuration directory path.
Finally, start the Consul client.
Setup Frontend Consul client agent
Log into the virtual machine that hosts the frontend.
Create an environment variable named CONSUL_CONFIG_DIR
and set it to your Consul configuration directory path.
Finally, start the Consul client.
Setup NGINX Consul client agent
Log into the virtual machine that hosts NGINX.
Create an environment variable named CONSUL_CONFIG_DIR
and set it to your Consul configuration directory path.
Finally, start the Consul client.
Verify Consul datacenter members
After you started all Consul agents, verify they successfully joined the Consul datacenter. If you are using the interactive lab environment, go to the Operator tab.
Retrieve the agents in the Consul datacenter.
Query services in Consul catalog
When you started the Consul client agents, they registered the service running on their node into the Consul catalog. Each service definition also contained the service's health check. You can find the service defintion files in each node's respective Consul configuration file you defined earlier.
Query the healthy services using the Consul CLI, API, or DNS.
Use the Consul CLI to query the service catalog.
Modify service definition tags
When using Consul CLI or the API endpoints, Consul will also show you the metadata associated with the services. In this tutorial, you registered each service with the v1
tag.
In this section, you will update the database service definition to learn how to update Consul service definitions. You must run these commands on the virtual machine that hosts the services.
First, login to database VM.
Note
If you are using the interactive lab environment, the Database
tab is locked by the Consul agent. Run this command from the Operator tab.
Next, create the new configuration file. Notice that this configuration adds a v2
tag to the database service.
Once you have created the new service definition file, it is time to update the service in the Consul catalog.
Consul can automatically update some of its configuration by reloading the content of the configuration folder.
To use this feature, move the svc-db.hcl
file into the Consul configuration directory (/etc/consul/config
).
Then, use the reload
command to update the service definition.
Query services by tags
After you have updated the database service definition, query it to verify the new tag.
Retrieve the tags associated with each service and verify the new v2
tag for the database service.
Next steps
In this tutorial, you deployed Consul clients on each HashiCups' nodes VMs. In addition, you configured Consul to perform health checks on the registered services and updated a service definition.
You now have a distributed system to monitor and resolve your services all without changing your services' configuration or implementation. At this stage, your you can use Consul to automatically configure and monitor your services. However, they have the same security they had before introducing Consul.
In the next tutorial, you will learn how to introduce zero trust security in your network by implementing Consul service mesh.
For more information about the topics covered in this tutorial, refer to the following resources: