Register your services to Consul

34min
|
Consul
Interactive

Workflow

In the previous tutorial, you deployed a Consul server, enabled ACL security features, and explored how to use Consul as a KV store and DNS server.

Consul gains additional use as a centralized service catalog. This use case requires Consul client agents to serve as a distributed health monitoring platform for your services.

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.

In this tutorial, you will:

(Optional) Deploy your VM environment on AWS EC2 using Terraform
Configure Consul client agents for the different VMs
Start Consul client instances on your workload VMs
Configure your terminal to communicate with the Consul datacenter
Verify Consul datacenter members
Query the Consul catalog using CLI, API, and DNS interfaces
Modify a service definition and update the service in Consul catalog

Note

Because this tutorial is part of the Get Started on VMs tutorial collection, the following workflow was designed for education and demonstration. It uses scripts to generate agent configurations and requires you to execute commands manually on different nodes. If you are setting up a production environment you should codify and automate the installation and deployment process according to your infrastructure and networking needs. Refer to the VM production patterns tutorial collection for Consul production deployment considerations and best practices.

Tutorial scenario

This tutorial uses HashiCups, a demo coffee shop application made up of several microservices running on VMs.

t the beginning of this tutorial, there are six VMs: an instance of the HashiCups application running on four VMs, the VM running the Consul server that you deployed in the previous tutorial, and one Bastion host to interact with the other VMs.

Architectural diagram 01

At the end of this tutorial, a Consul client agent runs on each VM that hosts a HashiCups service. The HashiCups services are registered in the Consul catalog, and there are health checks set up for each service.

Architectural diagram 02

Prerequisites

If you completed the previous tutorial, the infrastructure is already in place with all prerequisites.

For this tutorial, you will need:

An AWS account configured for use with Terraform
aws-cli >= 2.0
terraform >= 1.0
git >= 2.0

Clone GitHub repository

Clone the GitHub repository containing the configuration files and resources.

$ git clone https://github.com/hashicorp-education/learn-consul-get-started-vms

Change into the directory that contains the complete configuration files for this tutorial.

$ cd learn-consul-get-started-vms/self-managed/infrastructure/aws

Create infrastructure

With these Terraform configuration files, you are ready to deploy your infrastructure.

Issue the terraform init command from your working directory to download the necessary providers and initialize the backend.

$ terraform init
Initializing the backend...
Initializing provider plugins...
...
Terraform has been successfully initialized!
...

Then, deploy the resources. Enter yes to confirm the run.

$ terraform apply --var-file=../../ops/conf/GS_01_deploy_consul.tfvars
## ...
Do you want to perform these actions?
 Terraform will perform the actions described above.
 Only 'yes' will be accepted to approve.
 Enter a value: yes
## ...
Apply complete! Resources: 49 added, 0 changed, 0 destroyed.

The Terraform deployment could take up to 15 minutes to complete. Feel free to explore the next sections of this tutorial while waiting for the environment to complete initialization.

After it completes deployment, Terraform returns a list of outputs you can use to interact with the newly created environment.

Outputs:

connection_string = "ssh -i certs/id_rsa.pem admin@`terraform output -raw ip_bastion`"
ip_bastion = "34.222.160.35"
retry_join = <sensitive>
ui_consul = "https://44.244.31.105:8443"
ui_grafana = "http://34.222.160.35:3000/d/hashicups/hashicups"
ui_hashicups = "http://34.220.146.55"
ui_hashicups_API_GW = "https://54.201.39.96:8443"

The Terraform outputs provide useful information, including the bastion host IP address. The following is a brief description of the Terraform outputs:

The connection_string provides the command to SSH connect to the bastion host.
The ip_bastion provides the IP address of the bastion host. You will use the bastion host to run the rest of the commands in this tutorial.
The retry_join output lists Consul's retry_join configuration parameter. The tutorials will use this to generate Consul server and client configuration.
The ui_consul output lists the Consul UI address.
The ui_grafana output lists the Grafana UI address. You will use this in the service mesh monitoring tutorial.
The ui_hashicups output lists the HashiCups UI address. You can use it to verify the HashiCups demo application is running properly.
The ui_hashicups_API_GW output lists the API gateway address that permits access to HashiCups UI address. The API gateway is not currently running. You will use this address in the service mesh access tutorial to verify the HashiCups demo application is running properly in the service mesh.

Terraform output provides a series of useful information, including bastion host IP address.

$ ssh -i certs/id_rsa.pem admin@`terraform output -raw ip_bastion`

Verify Consul binary in service servers

Verify that the VMs you want to deploy the Consul agents on have the Consul binary.

For example, to check Consul installation on the Database VM, login to the Database VM from the bastion host.

$ ssh -i certs/id_rsa hashicups-db-0

Verify Consul binary is installed.

$ consul version
Consul v1.20.2
Revision 33e5727a
Build Date 2025-01-03T14:38:40Z
Protocol 2 spoken by default, understands 2 to 3 (agent will automatically use protocol >2 when speaking to compatible agents)

Return to the bastion host by exiting the SSH session.

$ exit
logout
Connection to hashicups-db-0 closed.
admin@bastion:~$

Repeat the steps for all VMs (hashicups-nginx, hashicups-frontend, hashicups-api) you want to add to the Consul datacenter.

Configure environment

The tutorial uses scripts to creates all files in a destination folder. Export the path where you want to create the configuration files for the scenario.

$ export OUTPUT_FOLDER=/home/admin/assets/scenario/conf/

Make sure the folder exists.

$ mkdir -p ${OUTPUT_FOLDER}

Source the env-scenario.env file to set the variables in the terminal session.

$ source assets/scenario/env-scenario.env

Configure the Consul CLI to interact with the Consul server.

$ export CONSUL_HTTP_ADDR="https://consul-server-0:8443" \
  export CONSUL_HTTP_SSL=true \
  export CONSUL_CACERT="${OUTPUT_FOLDER}secrets/consul-agent-ca.pem" \
  export CONSUL_TLS_SERVER_NAME="server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}" \
  export CONSUL_HTTP_TOKEN=`cat ${OUTPUT_FOLDER}secrets/acl-token-bootstrap.json | jq -r ".SecretID"`

The lab contains two environment files that will help you configure the terminal and generate the required configuration files.

$ ls -1 ~/assets/scenario/env*.env 
~/assets/scenario/env-consul.env
~/assets/scenario/env-scenario.env

Source the files to set the variables in the terminal session.

$ source ~/assets/scenario/env-scenario.env; \
source ~/assets/scenario/env-consul.env

Verify your Consul CLI can interact with your Consul server.

$ consul members 
Node             Address          Status  Type    Build   Protocol  DC   Partition  Segment
consul-server-0  172.18.0.4:8301  alive   server  1.20.2  2         dc1  default    <all>

Generate Consul clients configuration

The Consul datacenter is configured with ACLs enabled by default, so you must define the ACL tokens you want to pass to the Consul clients when you create the configuration.

First, export the token you generated for DNS so you can use it as default token for clients.

$ export CONSUL_DNS_TOKEN=`cat ${OUTPUT_FOLDER}secrets/acl-token-dns.json | jq -r ".SecretID"`

Then define a second Consul token for the service definition file to secure communication with the Consul datacenter.

In this example, you will use the bootstrap token.

$ export CONSUL_AGENT_TOKEN="${CONSUL_HTTP_TOKEN}"

Generate configuration for Database node

First, define the Consul node name.

$ export NODE_NAME="hashicups-db-0"

Then, generate the Consul configuration.

$ ~/ops/scenarios/00_base_scenario_files/supporting_scripts/generate_consul_client_config.sh 
[generate_consul_client_config.sh] - - Generate configuration for [hashicups-db-0]
+ --------------------
| Parameter Check
+ --------------------
[WARN] Script is running with the following values:
[WARN] ----------
[WARN] CONSUL_DATACENTER = dc1
[WARN] CONSUL_DOMAIN = consul
[WARN] CONSUL_RETRY_JOIN = consul-server-0
[WARN] CONSUL_CONFIG_DIR = /etc/consul.d/
[WARN] CONSUL_DATA_DIR = /opt/consul/
[WARN] ----------
[WARN] Generated configuration will be placed under:
[WARN] OUTPUT_FOLDER = ~/assets/scenario/conf/
[WARN] ----------

+ --------------------
| Generate configuration for Consul agent hashicups-db-0
+ --------------------
 - Cleaning folder from pre-existing files
[WARN] Removing pre-existing configuration in ~/assets/scenario/conf/
 - Generate folder structure
 - Copy available configuration
 - Generate configuration files
 - Validate configuration for hashicups-db-0

To complete Consul agent configuration, you need to set up tokens for the client. For this tutorial, you are using the bootstrap token. We recommend you create more restrictive tokens for the client agents in production.

$ tee ${OUTPUT_FOLDER}${NODE_NAME}/agent-acl-tokens.hcl > /dev/null << EOF
acl {
  tokens {
    agent  = "${CONSUL_HTTP_TOKEN}"
    default  = "${CONSUL_DNS_TOKEN}"
    config_file_service_registration = "${CONSUL_HTTP_TOKEN}"
  }
}
EOF

After you generate the Consul agent configuration, copy the configuration to the remote node.

First, define the Consul configuration directory.

$ export CONSUL_REMOTE_CONFIG_DIR=/etc/consul.d/

Then, remove the existing configuration from the VM.

$ ssh -i ~/certs/id_rsa ${NODE_NAME} "sudo rm -rf ${CONSUL_REMOTE_CONFIG_DIR}*"

Finally, use rsync to copy the configuration files into the remote node.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}${NODE_NAME}/ \
    ${NODE_NAME}:${CONSUL_REMOTE_CONFIG_DIR}

The output is similar to the following:

sending incremental file list
./
agent-acl-tokens.hcl
agent-gossip-encryption.hcl
consul-agent-ca.pem
consul.hcl

sent 3,153 bytes  received 95 bytes  6,496.00 bytes/sec
total size is 2,800  speedup is 0.86

Generate configuration for API node

First, define the Consul node name.

$ export NODE_NAME="hashicups-api-0"

Then, generate the Consul configuration.

$ ~/ops/scenarios/00_base_scenario_files/supporting_scripts/generate_consul_client_config.sh 
[generate_consul_client_config.sh] - - Generate configuration for [hashicups-api-0]
+ --------------------
| Parameter Check
+ --------------------
[WARN] Script is running with the following values:
[WARN] ----------
[WARN] CONSUL_DATACENTER = dc1
[WARN] CONSUL_DOMAIN = consul
[WARN] CONSUL_RETRY_JOIN = consul-server-0
[WARN] CONSUL_CONFIG_DIR = /etc/consul.d/
[WARN] CONSUL_DATA_DIR = /opt/consul/
[WARN] ----------
[WARN] Generated configuration will be placed under:
[WARN] OUTPUT_FOLDER = ~/assets/scenario/conf/
[WARN] ----------

+ --------------------
| Generate configuration for Consul agent hashicups-api-0
+ --------------------
 - Cleaning folder from pre-existing files
[WARN] Removing pre-existing configuration in ~/assets/scenario/conf/
 - Generate folder structure
 - Copy available configuration
 - Generate configuration files
 - Validate configuration for hashicups-api-0

To complete Consul agent configuration, you need to setup tokens for the client. For this tutorial, you are using the bootstrap token. In production environments, we recommend that you create more restrictive tokens for the client agents.

$ tee ${OUTPUT_FOLDER}${NODE_NAME}/agent-acl-tokens.hcl > /dev/null << EOF
acl {
  tokens {
    agent  = "${CONSUL_HTTP_TOKEN}"
    default  = "${CONSUL_DNS_TOKEN}"
    config_file_service_registration = "${CONSUL_HTTP_TOKEN}"
  }
}
EOF

After you generate the Consul agent configuration, copy the configuration to the remote node.

First, define the Consul configuration directory.

$ export CONSUL_REMOTE_CONFIG_DIR=/etc/consul.d/

Then, remove the existing configuration from the VM.

$ ssh -i ~/certs/id_rsa ${NODE_NAME} "sudo rm -rf ${CONSUL_REMOTE_CONFIG_DIR}*"

Finally, use rsync to copy the configuration files into the remote node.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}${NODE_NAME}/ \
    ${NODE_NAME}:${CONSUL_REMOTE_CONFIG_DIR}

The output is similar to the following:

sending incremental file list
./
agent-acl-tokens.hcl
agent-gossip-encryption.hcl
consul-agent-ca.pem
consul.hcl

sent 3,154 bytes  received 95 bytes  6,498.00 bytes/sec
total size is 2,801  speedup is 0.86

Generate configuration for Frontend node

First, define the Consul node name.

$ export NODE_NAME="hashicups-frontend-0"

Then, generate the Consul configuration.

$ ~/ops/scenarios/00_base_scenario_files/supporting_scripts/generate_consul_client_config.sh 
[generate_consul_client_config.sh] - - Generate configuration for [hashicups-frontend-0]
+ --------------------
| Parameter Check
+ --------------------
[WARN] Script is running with the following values:
[WARN] ----------
[WARN] CONSUL_DATACENTER = dc1
[WARN] CONSUL_DOMAIN = consul
[WARN] CONSUL_RETRY_JOIN = consul-server-0
[WARN] CONSUL_CONFIG_DIR = /etc/consul.d/
[WARN] CONSUL_DATA_DIR = /opt/consul/
[WARN] ----------
[WARN] Generated configuration will be placed under:
[WARN] OUTPUT_FOLDER = ~/assets/scenario/conf/
[WARN] ----------

+ --------------------
| Generate configuration for Consul agent hashicups-frontend-0
+ --------------------
 - Cleaning folder from pre-existing files
[WARN] Removing pre-existing configuration in ~/assets/scenario/conf/
 - Generate folder structure
 - Copy available configuration
 - Generate configuration files
 - Validate configuration for hashicups-frontend-0

To complete Consul agent configuration, you need to set up tokens for the client. For this tutorial, you are using the bootstrap token. In production environments, we recommend that you create more restrictive tokens for the client agents.

$ tee ${OUTPUT_FOLDER}${NODE_NAME}/agent-acl-tokens.hcl > /dev/null << EOF
acl {
  tokens {
    agent  = "${CONSUL_HTTP_TOKEN}"
    default  = "${CONSUL_DNS_TOKEN}"
    config_file_service_registration = "${CONSUL_HTTP_TOKEN}"
  }
}
EOF

Once Consul agent configuration is generated, you can copy the configuration to the remote node.

First, define the Consul configuration directory.

$ export CONSUL_REMOTE_CONFIG_DIR=/etc/consul.d/

Then remove any existing configurations from the VM. This step is useful when you run the Getting Started tutorials out of order or more than once in a row on the same devices.

$ ssh -i ~/certs/id_rsa ${NODE_NAME} "sudo rm -rf ${CONSUL_REMOTE_CONFIG_DIR}*"

Finally, use rsync to copy the configuration files into the remote node.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}${NODE_NAME}/ \
    ${NODE_NAME}:${CONSUL_REMOTE_CONFIG_DIR}

The output is similar to the following:

sending incremental file list
./
agent-acl-tokens.hcl
agent-gossip-encryption.hcl
consul-agent-ca.pem
consul.hcl

sent 3,154 bytes  received 95 bytes  6,498.00 bytes/sec
total size is 2,806  speedup is 0.86

Generate configuration for NGINX node

First, define the Consul node name.

$ export NODE_NAME="hashicups-nginx-0"

Then, generate the Consul configuration.

$ ~/ops/scenarios/00_base_scenario_files/supporting_scripts/generate_consul_client_config.sh 
[generate_consul_client_config.sh] - - Generate configuration for [hashicups-nginx-0]
+ --------------------
| Parameter Check
+ --------------------
[WARN] Script is running with the following values:
[WARN] ----------
[WARN] CONSUL_DATACENTER = dc1
[WARN] CONSUL_DOMAIN = consul
[WARN] CONSUL_RETRY_JOIN = consul-server-0
[WARN] CONSUL_CONFIG_DIR = /etc/consul.d/
[WARN] CONSUL_DATA_DIR = /opt/consul/
[WARN] ----------
[WARN] Generated configuration will be placed under:
[WARN] OUTPUT_FOLDER = ~/assets/scenario/conf/
[WARN] ----------

+ --------------------
| Generate configuration for Consul agent hashicups-nginx-0
+ --------------------
 - Cleaning folder from pre-existing files
[WARN] Removing pre-existing configuration in ~/assets/scenario/conf/
 - Generate folder structure
 - Copy available configuration
 - Generate configuration files
 - Validate configuration for hashicups-nginx-0

To complete Consul agent configuration, you need to set up tokens for the client. For this tutorial, you are using the bootstrap token. In production environments, we recommend that you create more restrictive tokens for the client agents.

$ tee ${OUTPUT_FOLDER}${NODE_NAME}/agent-acl-tokens.hcl > /dev/null << EOF
acl {
  tokens {
    agent  = "${CONSUL_HTTP_TOKEN}"
    default  = "${CONSUL_DNS_TOKEN}"
    config_file_service_registration = "${CONSUL_HTTP_TOKEN}"
  }
}
EOF

Once Consul agent configuration is generated, you can copy the configuration to the remote node.

First, define the Consul configuration directory.

$ export CONSUL_REMOTE_CONFIG_DIR=/etc/consul.d/

Then remove any existing configurations from the VM. This step is useful when you run the Getting Started tutorials out of order or more than once in a row on the same devices.

$ ssh -i ~/certs/id_rsa ${NODE_NAME} "sudo rm -rf ${CONSUL_REMOTE_CONFIG_DIR}*"

Finally, use rsync to copy the configuration files into the remote node.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}${NODE_NAME}/ \
    ${NODE_NAME}:${CONSUL_REMOTE_CONFIG_DIR}

The output is similar to the following:

sending incremental file list
./
agent-acl-tokens.hcl
agent-gossip-encryption.hcl
consul-agent-ca.pem
consul.hcl

sent 3,151 bytes  received 95 bytes  6,492.00 bytes/sec
total size is 2,803  speedup is 0.86

Start Consul on client nodes

Now that each client VM has access to an agent configuration file, start the Consul client agent on each VM.

Start Consul on Database node

Log into the Database VM from the bastion host.

$ ssh -i certs/id_rsa hashicups-db-0
##..
admin@hashicups-db-0:~

Ensure your user has write permission to the Consul data directory.

$ sudo chmod g+w /opt/consul/

Finally, start the Consul client process.

$ consul agent -config-dir=/etc/consul.d/ > /tmp/consul-client.log 2>&1 &

The command starts the Consul server in the background to not lock the terminal. You can access the Consul server log through the /tmp/consul-client.log file.

Exit the SSH session to return to the bastion host.

$ exit
logout
Connection to hashicups-db-0 closed.
admin@bastion:~$

Start Consul on API node

Log into the API VM from the bastion host.

$ ssh -i certs/id_rsa hashicups-api-0
##..
admin@hashicups-api-0:~

Ensure your user has write permission to the Consul data directory.

$ sudo chmod g+w /opt/consul/

Finally, start the Consul client process.

$ consul agent -config-dir=/etc/consul.d/ > /tmp/consul-client.log 2>&1 &

The command starts the Consul server in the background to avoid a lock on the active terminal. You can access the Consul server log through the /tmp/consul-client.log file.

Exit the SSH session to return to the bastion host.

$ exit
logout
Connection to hashicups-api-0 closed.
admin@bastion:~$

Start Consul on Frontend node

Log into the Frontend VM from the bastion host.

$ ssh -i certs/id_rsa hashicups-frontend-0
##..
admin@hashicups-frontend-0:~

Ensure your user has write permission to the Consul data directory.

$ sudo chmod g+w /opt/consul/

Finally, start the Consul client process.

$ consul agent -config-dir=/etc/consul.d/ > /tmp/consul-client.log 2>&1 &

The command starts the Consul server in the background to not lock the terminal. You can access the Consul server log through the /tmp/consul-client.log file.

Exit the SSH session to return to the bastion host.

$ exit
logout
Connection to hashicups-frontend-0 closed.
admin@bastion:~$

Start Consul on NGINX node

Log into the NGINX VM from the bastion host.

$ ssh -i certs/id_rsa hashicups-nginx-0
##..
admin@hashicups-nginx-0:~

Ensure your user has write permission to the Consul data directory.

$ sudo chmod g+w /opt/consul/

Finally, start the Consul client process.

$ consul agent -config-dir=/etc/consul.d/ > /tmp/consul-client.log 2>&1 &

The command starts the Consul server in the background to avoid a lock on the terminal. You can access the Consul server log through the /tmp/consul-client.log file.

Exit the SSH session to return to the bastion host.

$ exit
logout
Connection to hashicups-nginx-0 closed.
admin@bastion:~$

Verify Consul datacenter members

After you start all of the Consul agents, verify that they successfully joined the Consul datacenter.

Retrieve the agents in the Consul datacenter.

$ consul members 
Node                  Address          Status  Type    Build   Protocol  DC   Partition  Segment
consul-server-0       172.18.0.4:8301  alive   server  1.20.2  2         dc1  default    <all>
hashicups-api-0       172.18.0.5:8301  alive   client  1.20.2  2         dc1  default    <default>
hashicups-db-0        172.18.0.7:8301  alive   client  1.20.2  2         dc1  default    <default>
hashicups-frontend-0  172.18.0.2:8301  alive   client  1.20.2  2         dc1  default    <default>
hashicups-nginx-0     172.18.0.8:8301  alive   client  1.20.2  2         dc1  default    <default>

Use the /v1/agent/members API endpoint to retrieve the agents in the Consul datacenter.

$ curl --silent \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --connect-to server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}:8443:consul-server-0:8443 \
  --cacert ${CONSUL_CACERT} \
  https://server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}:8443/v1/agent/members | jq

The output is similar to the following:

[
  {
    "Name": "consul-server-0",
    "Addr": "172.18.0.4",
    "Port": 8301,
    ##...
  },
  {
    "Name": "hashicups-db-0",
    "Addr": "172.18.0.7",
    "Port": 8301,
    ##...
  },
  {
    "Name": "hashicups-api-0",
    "Addr": "172.18.0.5",
    "Port": 8301,
    ##...
  },
  {
    "Name": "hashicups-frontend-0",
    "Addr": "172.18.0.2",
    "Port": 8301,
    ##...
  },
  {
    "Name": "hashicups-nginx-0",
    "Addr": "172.18.0.8",
    "Port": 8301,
    ##...
  }
]

Retrieve the Consul UI address from Terraform.

terraform output -raw ui_consul

Open the address in a browser.

In the Consul UI, select the Nodes page. This page displays a list of agents in the Consul datacenter.

Nodes page with HashiCups

Register services in the Consul catalog

After the Consul client agent is running on a node, you can use that node to register services in the Consul catalog and make them discoverable to your network.

Register the Database service

First, define the Consul node name.

$ export NODE_NAME="hashicups-db-0"

Then, generate the service configuration for the node.

$ ~/ops/scenarios/00_base_scenario_files/supporting_scripts/generate_hashicups_service_config.sh 
 [generate_hashicups_service_config.sh] - [hashicups-db-0]

+ --------------------
| Parameter Check
+ --------------------
 - Check if a service token is defined

+ --------------------
| Generate service configuration files for hashicups-db-0
+ --------------------
 - Get service details
 - Prepare folders
 - Generate checks definition
 - Generate service definition for service discovery
 - Generate service definition for service mesh

Then copy the service definition file into the remote node.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}${NODE_NAME}/svc/service_discovery/svc-hashicups-db.hcl \
    ${NODE_NAME}:${CONSUL_REMOTE_CONFIG_DIR}/svc.hcl

The output is similar to the following:

sending incremental file list
svc-hashicups-db.hcl

sent 549 bytes  received 35 bytes  1,168.00 bytes/sec
total size is 429  speedup is 0.73

Register the API service

First, define the Consul node name.

$ export NODE_NAME="hashicups-api-0"

Then, generate the service configuration for the node.

$ ~/ops/scenarios/00_base_scenario_files/supporting_scripts/generate_hashicups_service_config.sh 
 [generate_hashicups_service_config.sh] - [hashicups-api-0]

+ --------------------
| Parameter Check
+ --------------------
 - Check if a service token is defined

+ --------------------
| Generate service configuration files for hashicups-api-0
+ --------------------
 - Get service details
 - Prepare folders
 - Generate checks definition
 - Generate service definition for service discovery
 - Generate service definition for service mesh

Then, copy the service definition file into the remote node.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}${NODE_NAME}/svc/service_discovery/svc-hashicups-api.hcl \
    ${NODE_NAME}:${CONSUL_REMOTE_CONFIG_DIR}/svc.hcl

The output is similar to the following:

sending incremental file list
svc-hashicups-api.hcl

sent 992 bytes  received 35 bytes  2,054.00 bytes/sec
total size is 871  speedup is 0.85

Register the Frontend service

First, define the Consul node name.

$ export NODE_NAME="hashicups-frontend-0"

Then, generate the service configuration for the node.

$ ~/ops/scenarios/00_base_scenario_files/supporting_scripts/generate_hashicups_service_config.sh 
 [generate_hashicups_service_config.sh] - [hashicups-frontend-0]

+ --------------------
| Parameter Check
+ --------------------
 - Check if a service token is defined

+ --------------------
| Generate service configuration files for hashicups-frontend-0
+ --------------------
 - Get service details
 - Prepare folders
 - Generate checks definition
 - Generate service definition for service discovery
 - Generate service definition for service mesh

Then, copy the service definition file into the remote node.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}${NODE_NAME}/svc/service_discovery/svc-hashicups-frontend.hcl \
    ${NODE_NAME}:${CONSUL_REMOTE_CONFIG_DIR}/svc.hcl

The output is similar to the following:

sending incremental file list
svc-hashicups-frontend.hcl

sent 592 bytes  received 35 bytes  1,254.00 bytes/sec
total size is 465  speedup is 0.74

Register the NGINX service

First, define the Consul node name.

$ export NODE_NAME="hashicups-nginx-0"

Then, generate the service configuration for the node.

$ ~/ops/scenarios/00_base_scenario_files/supporting_scripts/generate_hashicups_service_config.sh 
 [generate_hashicups_service_config.sh] - [hashicups-nginx-0]

+ --------------------
| Parameter Check
+ --------------------
 - Check if a service token is defined

+ --------------------
| Generate service configuration files for hashicups-nginx-0
+ --------------------
 - Get service details
 - Prepare folders
 - Generate checks definition
 - Generate service definition for service discovery
 - Generate service definition for service mesh

Then, copy the service definition file into the remote node.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}${NODE_NAME}/svc/service_discovery/svc-hashicups-nginx.hcl \
    ${NODE_NAME}:${CONSUL_REMOTE_CONFIG_DIR}/svc.hcl

The output is similar to the following:

sending incremental file list
svc-hashicups-nginx.hcl

sent 567 bytes  received 35 bytes  1,204.00 bytes/sec
total size is 443  speedup is 0.74

Query services in Consul catalog

You can query services using the Consul CLI, API, or DNS to return a healthy instance.

Use the Consul CLI to query the service catalog.

$ consul catalog services -tags 
consul                  
hashicups-api           v1
hashicups-db            v1
hashicups-frontend      v1
hashicups-nginx         v1

Use the /v1/catalog/services API endpoint to get a list of the services in the Consul catalog.

$ curl --silent \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --connect-to server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}:8443:consul-server-0:8443 \
  --cacert ${CONSUL_CACERT} \
  https://server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}:8443/v1/catalog/services | jq

The output is similar to the following:

{
  "consul": [],
  "hashicups-api": [
    "v1"
  ],
  "hashicups-db": [
    "v1"
  ],
  "hashicups-frontend": [
    "v1"
  ],
  "hashicups-nginx": [
    "v1"
  ]
}

The output shows the tags (v1) associated with each service instance.

If you want more information on a specific service, use the /v1/catalog/service/:service API endpoint.

Retrieve more information about the database service.

$ curl --silent \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --connect-to server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}:8443:consul-server-0:8443 \
  --cacert ${CONSUL_CACERT} \
  https://server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}:8443/v1/catalog/service/hashicups-db | jq

The output is similar to the following:

[
  {
    "ID": "6953bc0e-0fb5-7fb6-6ace-ba35b2429617",
    "Node": "hashicups-db-0",
    "Address": "172.18.0.7",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "172.18.0.7",
      "lan_ipv4": "172.18.0.7",
      "wan": "172.18.0.7",
      "wan_ipv4": "172.18.0.7"
    },
    "NodeMeta": {
      "consul-network-segment": "",
      "consul-version": "1.20.2"
    },
    "ServiceKind": "",
    "ServiceID": "hashicups-db-0",
    "ServiceName": "hashicups-db",
    "ServiceTags": [
      "v1"
    ],
    "ServiceAddress": "",
    "ServiceWeights": {
      "Passing": 1,
      "Warning": 1
    },
    "ServiceMeta": {},
    "ServicePort": 5432,
    "ServiceSocketPath": "",
    "ServiceEnableTagOverride": false,
    "ServiceProxy": {
      "Mode": "",
      "MeshGateway": {},
      "Expose": {}
    },
    "ServiceConnect": {},
    "ServiceLocality": null,
    "CreateIndex": 42,
    "ModifyIndex": 42
  }
]

Use the Consul DNS service to resolve the service name into an IP address. Consul uses the syntax <SERVICE_NAME>.service.<DATACENTER>.<DOMAIN> to query services.

Retrieve the database service's IP address.

$ dig @consul-server-0 -p 8600 hashicups-db.service.dc1.consul ANY

; <<>> DiG 9.16.50-Debian <<>> @consul-server-0 -p 8600 hashicups-db.service.dc1.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 18200
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;hashicups-db.service.dc1.consul. IN    ANY

;; ANSWER SECTION:
hashicups-db.service.dc1.consul. 0 IN   A   10.0.4.179

;; Query time: 0 msec
;; SERVER: 10.0.4.228#8600(10.0.4.228)
;; WHEN: Thu Jan 23 13:17:58 UTC 2025
;; MSG SIZE  rcvd: 76

Modify service definition tags

When you use the Consul CLI or the API endpoints to return information about services, Consul can return custom metadata associated with the services. In this tutorial, you registered each service with the v1 tag.

In this section, you will learn how to update Consul service definitions. You must run these commands on the virtual machine that hosts the services.

Edit the service definition file for the Database service to add a v2 tag to the service.

$ sed 's/"v1"/"v1","v2"/' \
  ${OUTPUT_FOLDER}hashicups-db-0/svc/service_discovery/svc-hashicups-db.hcl \
  > ${OUTPUT_FOLDER}hashicups-db-0/svc/service_discovery/svc-hashicups-db-multi-tag.hcl

Review the file to verify the change was applied.

$ cat ${OUTPUT_FOLDER}hashicups-db-0/svc/service_discovery/svc-hashicups-db-multi-tag.hcl

Tags array now contains both v1 and v2.

## -----------------------------
## svc-hashicups-db.hcl
## -----------------------------
service {
  name = "hashicups-db"
  id = "hashicups-db-0"
  tags = [ "v1","v2" ]
  port = 5432
  token = "69b2a14e-7030-0232-e56c-db1aae43f102"

  check     
  {
    id =  "check-hashicups-db",
    name = "hashicups-db status check",
    service_id = "hashicups-db-0",
    tcp  = "localhost:5432",
    interval = "5s",
    timeout = "5s"
  }
}

Finally, copy the service definition file to the remote node to apply the change.

$ rsync -av --no-g --no-t --no-p \
    -e "ssh -i ~/certs/id_rsa" \
    ${OUTPUT_FOLDER}hashicups-db-0/svc/service_discovery/svc-hashicups-db-multi-tag.hcl \
    hashicups-db-0:${CONSUL_REMOTE_CONFIG_DIR}svc.hcl

The output is similar to the following:

sending incremental file list
svc-hashicups-db-multi-tag.hcl

sent 565 bytes  received 41 bytes  1,212.00 bytes/sec
total size is 434  speedup is 0.72

Query services by tags

After you 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.

$ consul catalog services -tags 
consul                  
hashicups-api           v1
hashicups-db            v1,v2
hashicups-frontend      v1
hashicups-nginx         v1

Use the /v1/catalog/services API endpoint to get a list of the services in the Consul catalog and verify the new v2 tag for the database service.

$ curl --silent \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --connect-to server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}:8443:consul-server-0:8443 \
  --cacert ${CONSUL_CACERT} \
  https://server.${CONSUL_DATACENTER}.${CONSUL_DOMAIN}:8443/v1/catalog/services | jq

The output is similar to the following:

{
  "consul": [],
  "hashicups-api": [
    "v1"
  ],
  "hashicups-db": [
    "v1",
    "v2"
  ],
  "hashicups-frontend": [
    "v1"
  ],
  "hashicups-nginx": [
    "v1"
  ]
}

The DNS service does not return tag information because tags are part of Consul's internal metadata. Instead, Consul exposes the tags as a subdomain associated with the service in the form: <TAG>.<SERVICE_NAME>.service.<DATACENTER>.<DOMAIN>.

Retrieve the database service's IP address using the v2 tag.

$ dig @consul-server-0 -p 8600 v2.hashicups-db.service.dc1.consul ANY 

; <<>> DiG 9.16.50-Debian <<>> @consul-server-0 -p 8600 v2.hashicups-db.service.dc1.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 13690
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;v2.hashicups-db.service.dc1.consul. IN ANY

;; ANSWER SECTION:
v2.hashicups-db.service.dc1.consul. 0 IN A  10.0.4.179

;; Query time: 0 msec
;; SERVER: 10.0.4.228#8600(10.0.4.228)
;; WHEN: Thu Jan 23 14:57:56 UTC 2025
;; MSG SIZE  rcvd: 79

Next steps

In this tutorial, you deployed Consul clients on each HashiCups node VM. In addition, you created service definitions that includes health checks, registered the 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, you can use Consul to automatically configure and monitor your services. However, they have the same security they had before introducing Consul.

(Optional) Destroy infrastructure

If you want to stop at this tutorial, you can destroy the infrastructure now.

From the ./self-managed/infrastruture/aws folder of the repository, use terraform to destroy the infrastructure.

$ terraform destroy --auto-approve

In the next tutorial, you will learn how to implement Consul's service mesh to introduce zero trust security in your network.

You can automate Consul service deployment in your datacenter using Nomad. To learn more, complete the Integrate service discovery tutorial in the Nomad tutorials.

For more information about the topics covered in this tutorial, refer to the following resources:

Deploy Consul on VMs

Securely connect your services

Tutorial scenario

Prerequisites

Login into the bastion host VM

Verify Consul binary in service servers

Configure environment

Generate Consul clients configuration

Generate configuration for Database node

Generate configuration for API node

Generate configuration for Frontend node

Generate configuration for NGINX node

Start Consul on client nodes

Start Consul on Database node

Start Consul on API node

Start Consul on Frontend node

Start Consul on NGINX node

Verify Consul datacenter members

Register services in the Consul catalog

Register the Database service

Register the API service

Register the Frontend service

Register the NGINX service

Query services in Consul catalog

Modify service definition tags

Query services by tags

Next steps