Research Help improve navigation and content organization by answering a short survey. Start Survey
Consul
Consul on VMs

Register your services to Consul

  • 19min
  • |
  • Consul
  • Interactive

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.

Architectural diagram 01

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.

Architectural diagram 02

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.

$ consul version
Consul v1.12.4
Revision 94542765
Protocol 2 spoken by default, understands 2 to 3 (agent will automatically use protocol >2 when speaking to compatible agents)

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.

$ tree
.
|-- assets
|   |-- acl-policy-dns.hcl
|   |-- acl-policy-server-node.hcl
|   |-- acl-token-bootstrap.json
|   |-- acl-token-dns.json
|   |-- agent-gossip-encryption.hcl
|   |-- agent-server-acl.hcl
|   |-- agent-server-secure.hcl
|   |-- agent-server-specific.hcl
|   |-- agent-server-tls.hcl
|   |-- consul-agent-ca-key.pem
|   |-- consul-agent-ca.pem
|   |-- dc1-server-consul-0-key.pem
|   |-- dc1-server-consul-0.pem
|   `-- server-acl-token.json
|-- consul_conf.env
|-- filebrowser.db
|-- generate_consul_client_config.sh
|-- logs
|   |-- filebrowser.log
|   `-- provision.log
`-- start_scenario.sh

2 directories, 20 files

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.

$ export DATACENTER="dc1" \
export DOMAIN="consul" \
export CONSUL_DATA_DIR="/etc/consul/data" \
export CONSUL_CONFIG_DIR="/etc/consul/config"

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

$ export CA_CERT="/home/app/assets/consul-agent-ca.pem"; \
export GOSSIP_CONFIG="/home/app/assets/agent-gossip-encryption.hcl"

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.

$ export CONSUL_HTTP_ADDR="https://consul:8443" \
export CONSUL_HTTP_SSL=true \
export CONSUL_CACERT="$CA_CERT" \
export CONSUL_TLS_SERVER_NAME="server.${DATACENTER}.${DOMAIN}" \
export CONSUL_FQDN_ADDR="consul"

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.

acl-token-bootstrap.json
{
  "CreateIndex": 24,
  "ModifyIndex": 24,
  "AccessorID": "a09ee518-f4bf-f1a0-7bdd-2124ef1157af",
  "SecretID": "4becaa33-8fa3-a4c4-6ac5-fed2e20ee3a3",
  "Description": "Bootstrap Token (Global Management)",
  "Policies": [
    {
      "ID": "00000000-0000-0000-0000-000000000001",
      "Name": "global-management"
    }
  ],
  "Local": false,
  "CreateTime": "2022-08-23T14:17:57.686753287Z",
  "Hash": "X2AgaFhnQGRhSSF/h0m6qpX1wj/HJWbyXcxkEM/5GrY="
}

Retrieve this value and set it to an environment variable named CONSUL_HTTP_TOKEN.

$ export CONSUL_HTTP_TOKEN=`cat /home/app/assets/acl-token-bootstrap.json | jq -r ".SecretID"`

Verify your Consul CLI can interact with your Consul server.

$ consul members
Node    Address           Status  Type    Build   Protocol  DC   Partition  Segment
consul  10.2.19.238:8301  alive   server  1.12.4  2         dc1  default    <all>

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.

$ ./generate_consul_client_config.sh
Generate Consul agent configuration
Create node db specific configuration
Create service db configuration
Create node api specific configuration
Create service api configuration
Create node frontend specific configuration
Create service frontend configuration
Create node nginx specific configuration
Create service nginx configuration

The script generates the configuration files into multiple directory, one for each client HashiCups node.

$ tree ./client_configs   
./client_configs
|-- agent-client-secure.hcl
|-- api
|   |-- agent-client-acl-tokens.hcl
|   |-- agent-client-secure.hcl
|   |-- agent-gossip-encryption.hcl
|   |-- consul-agent-ca.pem
|   `-- svc-api.hcl
|-- db
|   |-- agent-client-acl-tokens.hcl
|   |-- agent-client-secure.hcl
|   |-- agent-gossip-encryption.hcl
|   |-- consul-agent-ca.pem
|   `-- svc-db.hcl
|-- frontend
|   |-- agent-client-acl-tokens.hcl
|   |-- agent-client-secure.hcl
|   |-- agent-gossip-encryption.hcl
|   |-- consul-agent-ca.pem
|   `-- svc-frontend.hcl
`-- nginx
    |-- agent-client-acl-tokens.hcl
    |-- agent-client-secure.hcl
    |-- agent-gossip-encryption.hcl
    |-- consul-agent-ca.pem
    `-- svc-nginx.hcl

4 directories, 21 files

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.

$ ssh app@hashicups-db "mkdir -p /etc/consul/config && mkdir -p /etc/consul/data"; \
ssh app@hashicups-api "mkdir -p /etc/consul/config && mkdir -p /etc/consul/data"; \
ssh app@hashicups-frontend "mkdir -p /etc/consul/config && mkdir -p /etc/consul/data"; \
ssh app@hashicups-nginx "mkdir -p /etc/consul/config && mkdir -p /etc/consul/data"

Then, copy the configuration files in each node's configuration folder.

$ scp client_configs/db/* hashicups-db:/etc/consul/config/; \
scp client_configs/api/* hashicups-api:/etc/consul/config/; \
scp client_configs/frontend/* hashicups-frontend:/etc/consul/config/; \
scp client_configs/nginx/* hashicups-nginx:/etc/consul/config/

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.

$ export CONSUL_CONFIG_DIR="/etc/consul/config"

Verify the configuration files are present in this directory.

$ ls -1 ${CONSUL_CONFIG_DIR}
agent-client-acl-tokens.hcl
agent-client-secure.hcl
agent-gossip-encryption.hcl
consul-agent-ca.pem
svc-db.hcl

Validate the configuration.

Tip

Despite the INFO messages, the Consul configuration files are valid.

$ consul validate ${CONSUL_CONFIG_DIR}
## ...
Configuration is 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.

$ consul agent -node=${HOSTNAME} -config-dir=${CONSUL_CONFIG_DIR}
==> Starting Consul agent...
           Version: '1.12.4'
           Node ID: 'a19a823f-ea3d-89dd-0d16-d1607aa1fc66'
         Node name: 'hashicups-db'
        Datacenter: 'dc1' (Segment: '')
            Server: false (Bootstrap: false)
       Client Addr: [127.0.0.1] (HTTP: 8500, HTTPS: 8443, gRPC: 8502, DNS: 8600)
      Cluster Addr: 10.2.17.106 (LAN: 8301, WAN: 8302)
           Encrypt: Gossip: true, TLS-Outgoing: true, TLS-Incoming: true, Auto-Encrypt-TLS: true

==> Log data will now stream in as it occurs:
...
[INFO]  agent: Consul agent running!

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.

$ export CONSUL_CONFIG_DIR="/etc/consul/config"

Finally, start the Consul client. 

$ consul agent -node=${HOSTNAME} -config-dir=${CONSUL_CONFIG_DIR}
==> Starting Consul agent...
           Version: '1.12.4'
           Node ID: '13b39cb5-7158-1345-1770-8e998fd88e8a'
         Node name: 'hashicups-api'
        Datacenter: 'dc1' (Segment: '')
            Server: false (Bootstrap: false)
       Client Addr: [127.0.0.1] (HTTP: 8500, HTTPS: 8443, gRPC: 8502, DNS: 8600)
      Cluster Addr: 10.2.2.165 (LAN: 8301, WAN: 8302)
           Encrypt: Gossip: true, TLS-Outgoing: true, TLS-Incoming: true, Auto-Encrypt-TLS: true

==> Log data will now stream in as it occurs:
...
[INFO]  agent: Consul agent running!

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.

$ export CONSUL_CONFIG_DIR="/etc/consul/config"

Finally, start the Consul client. 

$ consul agent -node=${HOSTNAME} -config-dir=${CONSUL_CONFIG_DIR}
==> Starting Consul agent...
           Version: '1.12.4'
           Node ID: 'ccde1389-214a-1ebe-ce19-fff6f21013b7'
         Node name: 'hashicups-frontend'
        Datacenter: 'dc1' (Segment: '')
            Server: false (Bootstrap: false)
       Client Addr: [127.0.0.1] (HTTP: 8500, HTTPS: 8443, gRPC: 8502, DNS: 8600)
      Cluster Addr: 10.2.4.60 (LAN: 8301, WAN: 8302)
           Encrypt: Gossip: true, TLS-Outgoing: true, TLS-Incoming: true, Auto-Encrypt-TLS: true

==> Log data will now stream in as it occurs:
...
[INFO]  agent: Consul agent running!

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.

$ export CONSUL_CONFIG_DIR="/etc/consul/config"

Finally, start the Consul client. 

$ consul agent -node=${HOSTNAME} -config-dir=${CONSUL_CONFIG_DIR}
==> Starting Consul agent...
           Version: '1.12.4'
           Node ID: '20f61f23-6411-9298-2990-a6c1ce582eb2'
         Node name: 'hashicups-nginx'
        Datacenter: 'dc1' (Segment: '')
            Server: false (Bootstrap: false)
       Client Addr: [127.0.0.1] (HTTP: 8500, HTTPS: 8443, gRPC: 8502, DNS: 8600)
      Cluster Addr: 10.2.14.142 (LAN: 8301, WAN: 8302)
           Encrypt: Gossip: true, TLS-Outgoing: true, TLS-Incoming: true, Auto-Encrypt-TLS: true

==> Log data will now stream in as it occurs:
...
[INFO]  agent: Consul agent running!

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.

$ consul members
Node                Address           Status  Type    Build   Protocol  DC   Partition  Segment
consul              10.2.19.238:8301  alive   server  1.12.4  2         dc1  default    <all>
hashicups-api       10.2.2.165:8301   alive   client  1.12.4  2         dc1  default    <default>
hashicups-db        10.2.17.106:8301  alive   client  1.12.4  2         dc1  default    <default>
hashicups-frontend  10.2.4.60:8301    alive   client  1.12.4  2         dc1  default    <default>
hashicups-nginx     10.2.14.142:8301  alive   client  1.12.4  2         dc1  default    <default>

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.

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

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.

$ ssh app@hashicups-db

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.

svc-db.hcl
## svc-db.hcl
service {
  name = "db"
  id = "db-1"
  tags = ["v1", "v2"]
  port = 5432
 
  check {
    id =  "check-db",
    name = "Product db status check",
    service_id = "db-1",
    tcp  = "localhost:5432",
    interval = "1s",
    timeout = "1s"
  }
}
svc-db.json
{
  "service": {
    "id": "db-1",
    "name": "db",
    "tags": ["v1", "v2"],
    "port": 5432,
    "checks": [
      {
        "ID" : "check-db",
        "Name" : "Product db status check",
        "ServiceID" : "db-1",
        "TCP": "localhost:5432",
        "interval": "1s",
        "Timeout": "1s"
      }
    ]
  }
}
svc-db-api.json
{
  "ID": "db-1",
  "Name": "db",
  "Tags": ["v1", "v2", "pippo"],
  "Port": 5432,
  "Checks": [
    {
      "CheckID" : "check-db",
      "Name" : "Product db status check",
      "ServiceID" : "db-1",
      "TCP": "localhost:5432",
      "Interval": "1s",
      "Timeout": "1s"
    }
  ]
}

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

$ mv svc-db.hcl /etc/consul/config/

Then, use the reload command to update the service definition.

$ consul reload
Configuration reload triggered

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.

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

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:

Previous
Next