Deploy Consul server
Consul is a service networking solution that enables you to manage secure network connectivity between services and across on-prem 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 and configure it to use Consul's service discovery and service mesh capabilities. During the process, you will learn how to leverage Consul to securely connect your services running on any environment.
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
This tutorial uses an interactive lab to guide you through how to deploy Consul server on a dedicated VM. 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.
Generate Consul server configuration
In order to securely configure Consul by ensuring all communications between the Consul server and clients 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.
The interactive lab environment includes these scripts. In Consul T1, list the files in your current directory.
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.
Generate all necessary files to configure and run the Consul server agent.
When the script completes, list the generated files. If you did not change the defaults, you will find it in /etc/consul/config
.
The scripts generated multiple configuration files to separate the configuration 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-secure.hcl
file configures a secure server agent. This is an example configuration, and should not be used in production environments. - The
agent-server-specific.hcl
file contains specific server 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.
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.
Tip
Despite the INFO
messages, the Consul configuration files are valid.
Start Consul server
Now that you have you created the Consul configuration files, you can start the Consul server.
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.
Tip
Ensure ${DATACENTER}
${DOMAIN}
and ${CONSUL_CONFIG_DIR}
are
still defined as environment variables. Refer to the Generate Consul server configuration to redefine these environment variables.
In Consul T2, run the following commands to 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.
After you set the management token, the Consul server logs (Consul T1) will show a message to indicate that you have successfully initialized the ACL system.
Now that you have bootstrap the ACL system, you can interact with the Consul server.
Create server tokens
In the Consul server logs, notice that it still contains 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
.
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 this and consul-template to configure your services automatically.
- use Consul server as a DNS server> You can use this to register and resolve external services in your network.
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 services. 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: