This deployment guide covers the steps required to install and configure a single HashiCorp Consul cluster as defined in the Consul Reference Architecture.
Below are instructions for installing and configuring Consul on Linux hosts running the systemd system and service manager.
This deployment guide is designed to work in combination with the Consul Reference Architecture. Although not a strict requirement to follow the Consul Reference Architecture, please ensure you are familiar with the overall architecture design; for example installing Consul on multiple physical or virtual (with correct anti-affinity) hosts for high-availability.
To provide a highly-available single cluster architecture, we recommend Consul be deployed to more than one host, as shown in the Consul Reference Architecture.
The below setup steps should be completed on all Consul hosts.
Precompiled Consul binaries are available for download at https://releases.hashicorp.com/consul/ and Consul Enterprise binaries are available for download by following the instructions made available to HashiCorp Consul customers.
You should perform checksum verification of the zip packages using the SHA256SUMS and SHA256SUMS.sig files available for the specific release version. HashiCorp provides a guide on checksum verification for precompiled binaries.
CONSUL_VERSION="1.2.0"
curl --silent --remote-name https://releases.hashicorp.com/consul/${CONSUL_VERSION}/consul_${CONSUL_VERSION}_linux_amd64.zip
curl --silent --remote-name https://releases.hashicorp.com/consul/${CONSUL_VERSION}/consul_${CONSUL_VERSION}_SHA256SUMS
curl --silent --remote-name https://releases.hashicorp.com/consul/${CONSUL_VERSION}/consul_${CONSUL_VERSION}_SHA256SUMS.sig
Unzip the downloaded package and move the consul binary to /usr/local/bin/. Check consul is available on the system path.
unzip consul_${CONSUL_VERSION}_linux_amd64.zip
sudo chown root:root consul
sudo mv consul /usr/local/bin/
consul --version
The consul command features opt-in autocompletion for flags, subcommands, and arguments (where supported). Enable autocompletion by running:
consul -autocomplete-install
Create a unique, non-privileged system user to run consul as a server and create it’s data directory.
sudo useradd --system --home /etc/consul.d --shell /bin/false consul
mkdir -p -m 644 /opt/consul
chown -R consul:consul /opt/consul
Systemd uses documented sane defaults so only non-default values must be set in the configuration file.
Create a vault service file at /etc/systemd/system/consul.service
sudo touch /etc/systemd/system/consul.service
Add the below configuration to the consul service file:
[Unit]
Description="HashiCorp Consul - A service mesh solution"
Documentation=https://www.consul.io/
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/consul.d/consul.hcl
[Service]
User=consul
Group=consul
ExecStart=/usr/local/bin/consul agent -config-dir=/etc/consul.d/
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
The following parameters are set for the [Unit] stanza:
Description- Free-form string describing the consul serviceDocumentation- Link to the consul documentationRequires- Configure a requirement dependency on the network serviceAfter- Configure an ordering dependency on the network service being started before the consul serviceConditionFileNotEmpty- Check for a non-zero sized configuration file before consul is started
The following parameters are set for the [Service] stanza:
User,Group- Run consul as the consul userExecStart- Start consul with theserverargument and path to the configuration fileExecReload- Send consul a HUP signal to trigger a configuration reload in consulKillMode- Treat consul as a single processRestart- Restart consul unless it returned a clean exit codeRestartSec- Restart consul after 5 seconds of it being considered 'failed'
The following parameters are set for the [Install] stanza:
WantedBy- Creates a weak dependency on consul being started by the multi-user run level
Consul uses documented sane defaults so only non-default values must be set in the configuration file.
Create a configuration file at /etc/consul.d/consul.hcl
sudo mkdir --parents /etc/consul.d
sudo touch /etc/consul.d/consul.hcl
sudo chown consul:consul /etc/consul.d/consul.hcl
sudo chmod 640 /etc/consul.d/consul.hcl
{
"datacenter": "east-aws",
"data_dir": "/opt/consul",
"log_level": "INFO",
"server": true,
"bootstrap-expect": 5,
"auto-pilot": {
"dead_server_cleanup": true,
"redundancy-zone-tag": "consul-zone"
},
"addresses": {
"https": "0.0.0.0"
},
"performance": {
"raft_multiplier": 1
}
}
addresses- This is a nested object that allows setting bind addresses. In Consul 1.0 and later these can be set to a space-separated list of addresses to bind to, or a go-sockaddr template that can potentially resolve to multiple addresses.datacenter- This flag controls the datacenter in which the agent is running. If not provided, it defaults to "dc1". Consul has first-class support for multiple datacenters, but it relies on proper configuration. Nodes in the same datacenter should be on a single LAN.data_dir- This flag provides a data directory for the agent to store state. This is required for all agents. The directory should be durable across reboots. This is especially critical for agents that are running in server mode as they must be able to persist cluster state. Additionally, the directory must support the use of filesystem locking, meaning some types of mounted folders (e.g. VirtualBox shared folders) may not be suitable. Note: both server and non-server agents may store ACL tokens in the state in this directory so read access may grant access to any tokens on servers and to any tokens used during service registration on non-servers. On Unix-based platforms the files are written with 0600 permissions so you should ensure only trusted processes can execute as the same user as Consul. On Windows, you should ensure the directory has suitable permissions configured as these will be inherited.log_level- The level of logging to show after the Consul agent has started. This defaults to "info". The available log levels are "trace", "debug", "info", "warn", and "err". You can always connect to an agent via consul monitor and use any log level. Also, the log level can be changed during a config reload.server- This flag is used to control if an agent is in server or client mode. When provided, an agent will act as a Consul server. Each Consul cluster must have at least one server and ideally no more than 5 per datacenter. All servers participate in the Raft consensus algorithm to ensure that transactions occur in a consistent, linearizable manner. Transactions modify cluster state, which is maintained on all server nodes to ensure availability in the case of node failure. Server nodes also participate in a WAN gossip pool with server nodes in other datacenters. Servers act as gateways to other datacenters and forward traffic as appropriate.bootstrap-expect- This flag provides the number of expected servers in the datacenter. Either this value should not be provided or the value must agree with other servers in the cluster. When provided, Consul waits until the specified number of servers are available and then bootstraps the cluster. This allows an initial leader to be elected automatically. This cannot be used in conjunction with the legacy -bootstrap flag. This flag requires -server mode.
The Cloud Auto-joiningstanza leverages go-discover library for doing automatic cluster joining using cloud metadata. For more information, see the Cloud Auto-join page.
The autopilot stanza specifies various configurations for Consul to configure operator friendly settings in Consul.
cleanup_dead_servers- This controls the automatic removal of dead server nodes periodically and whenever a new server is added to the cluster. Defaults to true.redundancy-zone-tag- (Enterprise-only) This controls the -node-meta key to use when Autopilot is separating servers into zones for redundancy. Only one server in each zone can be a voting member at one time. If left blank (the default), this feature will be disabled.
The Performance stanza allows tuning the performance of different subsystems in Consul.
raft_multiplier- An integer multiplier used by Consul servers to scale key Raft timing parameters. Omitting this value or setting it to 0 uses default timing described below. Lower values are used to tighten timing and increase sensitivity while higher values relax timings and reduce sensitivity. Tuning this affects the time it takes Consul to detect leader failures and to perform leader elections, at the expense of requiring more network and CPU resources for better performance.
By default, Consul will use a lower-performance timing that's suitable for minimal Consul servers, currently equivalent to setting this to a value of 5 (this default may be changed in future versions of Consul, depending if the target minimum server profile changes). Setting this to a value of 1 will configure Raft to its highest-performance mode, equivalent to the default timing of Consul prior to 0.7, and is recommended for production Consul servers. See the note on last contact timing for more details on tuning this parameter. The maximum allowed value is 10.
The telemetry stanza specifies various configurations for Consul to publish metrics to upstream systems.
If you decide to configure Consul to publish telemtery data, you should review the telemetry configuration section of our documentation.
Consul features a user interface (web interface) for interacting with Consul, allowing you to easily
Optionally, add the below configuration to the Consul configuration file to enable the Consul UI:
ui = true
A Demo version of the Consul UI.
Enable and start Consul using the systemctl command responsible for controlling systemd managed services. Check the status of the consul service using systemctl.
sudo systemctl enable consul
sudo systemctl start consul
sudo systemctl status consul
Once running it is important to have a backup and restore strategy for Consul.