Getting Started with Consul Service Mesh for Virtual Machines

This tutorial installs and configures Consul service mesh on virtual machines running Linux.

By the end of this tutorial, you will be able to identify the installation prerequisites, provision a Consul server, and deploy an example workload with Consul clients and proxies.

Prerequisites

Install VirtualBox for your machine. You will create 5 Linux machines, each using Ubuntu 18.04, 1 CPU, and 512 MB of memory.

Validate you have vagrant installed.

$ vagrant version

Installed Version: 2.2.15
Latest Version: 2.2.15

You're running an up-to-date version of Vagrant!

Validate you have consul installed.

$ consul version

Consul v1.9.5
Revision 3c1c22679
Protocol 2 spoken by default, understands 2 to 3 (agent will automatically use protocol >2 when speaking to compatible agents)

Clone the demo configuration and application.

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

Change directory to use the demo configuration and application.

$ cd learn-consul-vms/service-mesh/deploy

Deploy Consul

To deploy Consul service mesh, you need a control plane for the service mesh. Review the Consul server configuration at config/consul-server.hcl. It sets up one Consul server, enables the Consul UI, and enables Consul's service mesh features. The configuration also sets the protocol for services to HTTP and exposes proxy metrics by default.

data_dir = "/tmp/consul/server"

server           = true
bootstrap_expect = 1
advertise_addr   = "{{ GetInterfaceIP `eth1` }}"
client_addr      = "0.0.0.0"
bind_addr        = "0.0.0.0"

ports {
  grpc = 8502
}

enable_central_service_config = true

ui_config {
  enabled          = true
  metrics_provider = "prometheus"
  metrics_proxy {
    base_url = "http://$PROMETHEUS_IP_ADDR:9090"
  }
}

connect {
  enabled = true
}

datacenter = "dc1"

telemetry {
  prometheus_retention_time = "24h"
  disable_hostname          = true
}

config_entries {
  bootstrap = [
    {
      kind = "proxy-defaults"
      name = "global"
      config {
        protocol                   = "http"
        envoy_prometheus_bind_addr = "0.0.0.0:9102"
      }
    }
  ]
}

Use Vagrant to deploy a Consul server pre-configured with a demo instance of Prometheus for metrics.

$ vagrant up consul-server

Bringing machine 'consul-server' up with 'virtualbox' provider...
==> consul-server: Importing base box 'bento/ubuntu-18.04'...

# omitted for clarity

==> consul-server: Running provisioner: shell...
    consul-server: Running: /var/folders/j_/7xx00jkx6hs4grvl0k4zm8sm0000gp/T/vagrant-shell20210427-81143-15fl1r1.sh
    consul-server: /mnt/my-machine /home/vagrant
    consul-server: /home/vagrant
    consul-server: Created symlink /etc/systemd/system/multi-user.target.wants/consul.service → /etc/systemd/system/consul.service.

Vagrant port forwards requests to the Consul server on port 8500. As a result, you can use the Consul CLI to check Consul on http://localhost:8500 without need to set an environment variable for CONSUL_HTTP_ADDR. Validate the installation by checking for the running Consul server using consul members.

$ consul members

Node           Address           Status  Type    Build  Protocol  DC   Segment
consul-server  10.199.0.10:8301  alive   server  1.9.5  2         dc1  <all>

To access the Consul UI, go to http://localhost:8500 in your browser. Explore the Consul UI by examining the Nodes and Services tabs.

Deploy a demo application

You can explore Consul service mesh by installing a demo application. The demo application, named HashiCups, includes a set of three services and a PostgreSQL database. It allows you to order a cup of coffee.

Each virtual machine installs its own Consul client and proxy. The Consul client configures a proxy on the virtual machine. The proxies create a data plane to handle requests between services based on configuration from Consul.

Review scripts/consul-client.sh, which Vagrant runs for each machine. It copies configuration files for the Consul client and the service. When the Consul client starts, it uses the configuration files to start a client and register the service.

#!/usr/bin/env bash

CONSUL_HTTP_ADDR=${1}
APP_NAME=${2}
APP_IP_ADDR=${3}

pushd /mnt/my-machine
cp consul.service /etc/systemd/system/consul.service
mkdir -p /etc/consul.d
popd

sed 's/$CONSUL_HTTP_ADDR/'"${CONSUL_HTTP_ADDR}"'/g' /mnt/my-machine/consul-client.hcl > /etc/consul.d/consul.hcl
sed 's/$IP_ADDR/'"${APP_IP_ADDR}"'/g' /mnt/my-machine/services/${APP_NAME}.hcl > /etc/consul.d/${APP_NAME}.hcl

cat << EOF > /etc/systemd/system/consul-envoy.service
[Unit]
Description=Consul Envoy
After=syslog.target network.target

[Service]
ExecStart=/usr/bin/consul connect envoy -sidecar-for ${APP_NAME}
ExecStop=/bin/sleep 5
Restart=always

[Install]
WantedBy=multi-user.target
EOF

chmod 644 /etc/systemd/system/consul-envoy.service

systemctl daemon-reload

# Enable and start the daemons
systemctl enable consul
systemctl enable consul-envoy

systemctl start consul
systemctl start consul-envoy

Use Vagrant to provision the database and three services. On a modern machine with 16GB of RAM, this takes about 10 minutes to complete.

$ vagrant up

# omitted for clarity

    frontend: /home/vagrant
    frontend: Synchronizing state of nginx.service with SysV service script with /lib/systemd/systemd-sysv-install.
    frontend: Executing: /lib/systemd/systemd-sysv-install enable nginx

While Vagrant deploys the services, review our video for a brief introduction to Consul.

Validate the installation by checking for the running Consul clients using the Consul CLI.

$ consul members

Node           Address           Status  Type    Build  Protocol  DC   Segment
consul-server  10.199.0.10:8301  alive   server  1.9.5  2         dc1  <all>
frontend       10.199.0.50:8301  alive   client  1.9.5  2         dc1  <default>
postgres       10.199.0.20:8301  alive   client  1.9.5  2         dc1  <default>
product-api    10.199.0.30:8301  alive   client  1.9.5  2         dc1  <default>
public-api     10.199.0.40:8301  alive   client  1.9.5  2         dc1  <default>

Explore the application

You can now explore the demo application and how it uses Consul service mesh. Vagrant port forwards requests to the frontend virtual machine on port 8000. Access the frontend service at http://localhost:8000 in your browser. Refresh the page a few times.

Go to the Consul UI on http://localhost:8500. You'll find the HashiCups services registered to Consul service mesh with proxies.

Select the product-api service. The Topology tab indicates that requests to the public-api goes to the product-api before accessing the database. Consul embeds a graph aggregating successful requests and error metrics.

Clean up

When you finish exploring the deployment, remove Consul and HashiCups from your machine.

$ vagrant destroy -f

Next steps

In this tutorial, you configured Consul service mesh on virtual machines using Vagrant. You also deployed an example application to explore the service topology and track requests.

For a detailed explanation of Consul service mesh, review our tutorial explaining its design and features.

Learn more about using Consul on virtual machines in the following tutorials:

• Mutual authentication
• Network policy
• Metrics
• Traffic management