• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Consul
  • Install
  • Tutorials
  • Documentation
  • API
  • CLI
  • Try Cloud(opens in new tab)
  • Sign up
Service Mesh & Gateways

Skip to main content
17 tutorials
  • Control Access into the Service Mesh with Consul API Gateway
  • Getting Started with Consul Service Mesh for Virtual Machines
  • Secure Service Communication with Consul Service Mesh and Envoy
  • Visualize Service Mesh Communication in the Consul UI
  • Consul Service Mesh in Production
  • Traffic Splitting for Service Deployments
  • Implement Circuit Breaking in Consul Service Mesh with Envoy
  • Load Balancing Services in Consul Service Mesh with Envoy
  • Application Aware Intentions with Consul Service Mesh
  • Connect Services Across Datacenters with Mesh Gateways
  • Understand Terminating Gateways
  • Connect External Services to Consul With Terminating Gateways
  • Allow External Traffic Inside Your Service Mesh With Ingress Gateways
  • Integrate Consul with Ambassador Edge Stack on Kubernetes
  • Extend your Service Mesh to Support AWS Lambda
  • Connect Services in Different Consul Clusters with Cluster Peering
  • Connect Services on Windows Workloads to Consul Service Mesh

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Consul
  3. Tutorials
  4. Service Mesh & Gateways
  5. Getting Started with Consul Service Mesh for Virtual Machines

Getting Started with Consul Service Mesh for Virtual Machines

  • 20min

  • VagrantVagrant
  • ConsulConsul
  • VideoVideo

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.

NOTE: The virtual machines in this demonstration do not use the production reference architecture.

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.

consul-server.hcl
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.

consul ui showing services tab with consul

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.

NOTE: In this tutorial, you will not deploy the payments service or Redis to reduce resource requirements.

demo application architecture with three services and a database

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.

consul-client.sh
#!/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.

coffee cup with packer logo to buy a packer spiced latte

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

consul ui showing services tab with consul

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.

consul ui showing topology and graph for requests to product api

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
 Previous
 Next

On this page

  1. Getting Started with Consul Service Mesh for Virtual Machines
  2. Prerequisites
  3. Deploy Consul
  4. Deploy a demo application
  5. Explore the application
  6. Clean up
  7. Next steps
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)