Deploy Consul on VMs
Consul is a service networking solution that enables you to manage secure network connectivity between services and across on-premise and multi-cloud environments and runtimes. Consul offers service discovery, service mesh, traffic management, and automated updates to network infrastructure device. Check out the What is Consul? page to learn more.
In this tutorial, you will configure, deploy, and bootstrap a Consul server on
a virtual machine (VM). After deploying Consul, you will interact with Consul
using the UI, CLI, and API.
In the following tutorials, you will deploy a demo application, configure it to use Consul service discovery, secure it with service mesh, allow external traffic into the service mesh, and enhance observability into your service mesh. During the process, you will learn how to leverage Consul to securely connect your services running on any environment.
In this tutorial, you will:
- Deploy your VM environment on AWS EC2 using Terraform
- Configure a Consul server
- Start a Consul server instance
- Configure your terminal to communicate with the Consul datacenter
- Bootstrap Consul ACL system and create tokens for Consul management
- Interact with Consul API, KV store and UI
Tutorial scenario
This tutorial uses HashiCups, a demo coffee shop application made up of several microservices running on VMs.
At the beginning of this tutorial, you have an instance of HashiCups running on four VMs and one empty VM that you will use to deploy Consul server.
By the end of this tutorial, you will have deployed a Consul server agent running on the extra virtual machine.
Prerequisites
For this tutorial, you will need:
- An AWS account configured for use with Terraform
- aws-cli >= 2.0
- terraform >= 1.0
- consul >= 1.15.0
Clone GitHub repository
Clone the GitHub repository containing the configuration files and resources.
Change into the directory that contains the complete configuration files for this tutorial.
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.
Then, deploy the resources. Confirm the run by entering yes
. 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.
Once the deployment is complete, Terraform will return a list of outputs you can use to interact with the newly created environment.
The Terraform outputs provide useful information, including the bastion host IP address. The following is a brief description of the Terraform outputs:
- The
ip_bastion
provides IP address of the bastion host you will use to run the rest of the commands in this tutorial. - The
remote_ops
lists the bastion host IP, which you can use access the bastion host. - The
retry_join
output lists Consul'sretry_join
configuration parameter. The next tutorial will use this to generate Consul server and client configuration. - The
ui_consul
output lists the Consul UI address. The Consul UI is not currently running. You will use this in a later tutorial to verify Consul started correctly. - The
ui_grafana
output lists the Grafana UI address. You will use this in a future tutorial. - The
ui_hashicups
output lists the HashiCups UI address. You can use it to verify the HashiCups demo application is running properly.
Login into the bastion host VM
Login to the bastion host using ssh
.
Verify Consul binary
Verify that the VM you want to deploy the Consul server on has the Consul binary.
Generate Consul server configuration
To securely configure Consul by ensuring all communications between the Consul nodes are inaccessible to unintended agents, you need to provide Consul with:
- A gossip encryption key.
- A root certificate authority (CA) certificate from a private CA. Consul will use this CA certificate to sign all certificates in the Consul datacenter.
- A certificate key-pair for each server you intend to deploy signed by the above CA.
In addition, you want to enable ACLs to ensure every request to your Consul datacenter is authorized.
This tutorial and interactive lab environment uses scripts in the tutorial's GitHub repository to generate these secrets and the Consul configuration files. You will use these scripts to generate your Consul server configuration.
On the bastion host, verify that the scripts are correctly present in the home
directory of the admin
user.
The scripts rely 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.
A Consul datacenter is composed by multiple nodes that, at startup, connect with
each other using the Gossip protocol. To be able to automatically locate other
nodes at startup, Consul configuration needs a retry_join
parameter.
In this scenario we use the Cloud auto join functionality for AWS and the value to include in the Consul configuration is generated by Terraform during the infrastructure provisioning.
Terraform output includes a retry_join
value. Use it to populate the following
environment variable.
With all environment variables set, generate all necessary files to configure and run the Consul server agent.
When the script completes, list the generated files.
The scripts generated multiple configuration files so it is easier to read and tune them for your environment. The following are the generated files and a description of what they do:
- The
agent-gossip-encryption.hcl
file configures gossip encryption. - The
agent-server-acl.hcl
file configures the ACL system. - The
agent-server-networking.hcl
file configures networking for the server agent. - The
agent-server-specific-ui.hcl
file contains specific server UI configuration. - The
agent-server-specific.hcl
file contains specific server parameters. - The
agent-server-telemetry.hcl
file configures agent telemetry parameters. - The
agent-server-tls.hcl
file configures specific TLS encryption. - The
*.pem
files are certificate key-pair Consul uses to enforce mTLS for datacenter communications. - The
consul.hcl
file contains node specific configuration and it is needed, with this specific name, if you want to configure Consul as a systemd daemon.
Visit the agent configuration documentation to interpret the files or to tune them when applying them to your scenario.
Test configuration
Verify the configuration generated is valid. Despite the INFO
messages, the Consul configuration files are valid.
Copy configuration on Consul server node
Once the configuration is created, copy it to the Consul server VM.
Tip
In the AWS lab environment, all the VM 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 do not have an SSH server, you may
need to use a different approach to create the configuration directories and
copy the files.
First, configure the Consul configuration directory.
Then, remove existing configuration from the server.
Finally, use scp
to copy the configuration into the server node.
Start Consul server
Now that you have created the Consul configuration files, you can start the Consul server.
Login to the server VM.
Configure the Consul configuration and data directories.
Make sure your user has write permissions in the Consul data directory.
Finally, start the Consul server process.
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-server.log
file.
Once the Consul server is started, exit the SSH session to return to the bastion host.
The output shows the Consul server successfully starting, but some checks are blocked by ACLs. This is because the datacenter is configured to have ACL enabled by default, denying any request that does not present a valid token.
You must bootstrap the ACL system to finish setting up your Consul server.
Configure Consul CLI to interact with Consul server
In order to interact with the Consul server, you need to setup your terminal.
Make sure scenario environment variables are still defined.
Configure the Consul CLI to interact with the Consul server.
Bootstrap ACLs
Verify that the Consul CLI can reach your Consul server.
The output informs you that while the Consul CLI can reach your Consul server, Consul's ACLs are blocking the request.
Bootstrap the Consul ACL system and save the output in a file named acl-token-bootstrap.json
.
The command generates a management token with full permissions over your
datacenter. The output will look similar to the following. The management token
is the value associated with the SecretID
key.
Extract the management token from the file and set it to the CONSUL_HTTP_TOKEN
environment variable.
Warning
A management token is a very sensitive information for the security of your Consul datacenter. In these tutorials, we use a management token in the scenarios to simplify the get started experience. We do not recommended for production environments.
After you set the management token, the Consul server logs will signal that you have successfully initialized the ACL system.
Now that you have bootstrapped the ACL system, you can interact with the Consul server.
Create server tokens
The Consul datacenter is now fully bootstrapped and is ready to receive requests.
The Consul server logs still contain warnings related to ACL permissions. This is because the server tries to update the node information but the ACL system blocks the requests.
In order to complete configuring the Consul server, you need to create the tokens for the server agents and assign them to the server.
The generate_consul_sever_tokens.sh
script automates the process of creating
policies and tokens for your Consul server. This script generates ACL policies
for Consul DNS service and for the server agent and applies them to the Consul
server.
After you create the server tokens, your Consul logs will show the updated ACL tokens.
Interact with Consul server
Now that you have completed configuring and deploying your Consul server, you will interact with it. Consul provides different ways to retrieve information about the datacenter — select the tab(s) for your preferred method.
Use the Consul CLI to retrieve members in your Consul datacenter.
Check the Consul CLI commands reference for the full list of available commands.
Interact with Consul KV
Consul includes a key/value (KV) store that you can use to manage your service's configuration. Even though you can use the KV store using the CLI, API, and UI, this tutorial only covers the CLI and API methods. Select the tab(s) for your preferred method.
Create a key named db_port
with a value of 5432
.
Then, retrieve the value.
Interact with Consul DNS
Consul also provides you with a fully featured DNS server that you can use to
resolve the IPs for your services. By default, Consul DNS service is
configured to listen on port 8600
.
Tip
If you want to test Consul DNS interface from the Consul server node, use the following command.
Next steps
In this tutorial, you deployed a Consul server on a VM. After deploying Consul, you interacted with Consul using the CLI, UI, and API.
Even when deployed without Consul clients, you can:
- use Consul's KV store as a centralized configuration management tool. You can use it with consul-template to configure your services automatically.
- use Consul server as a DNS server. You can use it to register and resolve external services in your network.
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.
In the next tutorial, you will deploy Consul clients on the VMs hosting your application. Then, you will register the services running on each server and set up health checks for each service. This enables service discovery using Consul's distributed health check system and DNS.
For more information about the topics covered in this tutorial, refer to the following resources: