. . .

Consul Installation

Introduction

When using ApiOmat in a multi-server environment or when using microservice components like the Monitoring Service, a discovery service is needed to make all nodes aware of each other. Each service is announcing itself to the discovery service, which makes it possible to query for all available services in the network afterwards.

ApiOmat uses the Consul discovery serviced by HashiCorp.

Prerequisites

Open the following ports in the firewall to other ApiOmat nodes:

  • 8500 (HTTP)

  • 8600 (DNS)

System requirements

(Taken from https://www.consul.io/docs/guides/deployment.html)

The following instance configurations are recommended.

Size

CPU

Memory

Disk

Typical Cloud Instance Types

Small

2 core

8-16 GB RAM

50 GB

AWS: m5.large, m5.xlarge

Azure: Standard_A4_v2, Standard_A8_v2

Large

4-8 core

32-64+ GB RAM

100 GB

AWS: m5.2xlarge, m5.4xlarge

Azure: Standard_D4_v3, Standard_D5_v3

The small size instance configuration is appropriate for most initial production deployments, or for development/testing environments. The large size is for production environments where there is a consistently high workload.

Installation

USERNAME, PASSWORD, and TOKEN values are provided per customer from ApiOmat.

Debian/Ubuntu
# Install the repo key
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 4DE92D69
# Add the repository
echo "deb https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/deb ./" | sudo tee /etc/apt/sources.list.d/apiomat.list
 
# Update APT and install
apt-get update
apt-get install -y aom-consul
service consul start
Centos/Oracle/RedHat
# Add the repository
echo "[apiomat]
name=ApiOmat
baseurl=https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/rpm
gpgcheck=0
enabled=1" > /etc/yum.repos.d/apiomat.repo
 
# Install
yum -y --nogpgcheck install aom-consul
service consul start
Suse
# Add the repository
zypper addrepo --no-gpgcheck https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/suse?token=<TOKEN> "ApiOmat"
 
 
# Refresh zypper and install
zypper refresh
zypper --no-gpg-checks --non-interactive install aom-consul
service consul start
Docker
# Login
docker login -u <USERNAME> -p <PASSWORD>
 
# More information: https://hub.docker.com/_/consul/
# Store the following file and execute:
docker-compose -f consul.yml up
Docker

consul.yml:

Docker
version: '3'
services:
consul:
image: library/consul
# bind port 8500 of container to localhost port 8500
ports:
- "8500:8500"
Windows

  1. Download file: https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/aom-consul-<VERSION>.zip?token=<TOKEN> and unzip it to your installation folder.

  2. To install as a service and start, open an administrative console and execute :

    aom-consul-<VERSION>.exe install
    aom-consul-<VERSION>.exe start

    To uninstall the service, execute :

    aom-consul-<VERSION>.exe uninstall

After service start, Consul will be accessible on

http://localhost:8500

Configuration

Linux and Windows

The following configuration files are provided:

%CONFIG_PATH/consul.json

The main configuration file, which contains all necessary information to start Consul in a single node environment. The most common configuration keys are:

Key

Default

Explanation

data_dir

Linux: /tmp/consul
Windows: data\\consul

Place where Consul stores information about registered nodes/services

bind_addr

127.0.0.1

The address that should be bound to for internal cluster communications

bootstrap_expect

1

Number of expected Consul nodes

client_addr

127.0.0.1

The address to which Consul will bind client interfaces; to make e.g. the UI available on multi node setups, change to 0.0.0.0!

More information about all possible settings can be found at the consul website.

Docker

These specific configuration are only relevant if you want to set up a cluster of consul instances. In this case please refer to hashicorp docker compose cluster example.

Environmental variables

Key

Default

Explanation

CONSUL_BIND_INTERFACE

The address that should be bound to for internal cluster communications

CONSUL_CLIENT_INTERFACE

The address to which Consul will bind client interfaces

Arguments

Key

Default

Explanation

-bootstrap-expect

Number of expected Consul nodes; set to 1 on single node and to 3 on multi node setups

-bind

(Same as CONSUL_BIND_INTERFACE, see above)

-client

(Same as CONSUL_CLIENT_INTERFACE, see above)

The container exposes its data directory, /consul/data, as a volume. This is where Consul will store its persisted state.

Mor e information about all possible settings can be found at the consul container documentation.

Cluster setup

  1. An uneven node number is required ( usually 3) where Consul should be running on.

  2. Install Consul on each node as described above; other services like YAMBAS or Dashboard may run on the same node as well.

  3. Change bind_addr and client_addr values, in the config file 'consul.json', depending on your network setup (bind_addr should be set to the address available to other nodes).

  4. Still in the 'consul.json' configuration file, set the bootstrap_expect value to the number of nodes where Consul is running.

  5. Make sure that each nodes can communicate to each other through the ports used by Consul : 

    TCP : 8300 | 8301 | 8302 | 8400 | 8500 | 8600
UDP : 8301 | 8302 | 8600

  6. Start Consul on all nodes.

  7. To make all nodes find each others and elect a primary, execute on all but the first :

    %INSTALL_PATH/consul join <IP_OF_THE_FIRST_NODE>

More information are provided by the consul website.

Logging

Logging is done to syslog. You can get the latest logs by executing

Linux
tail -f /var/log/syslog | grep consul
#or
tail -f /var/log/messages | grep consul

Please replace <CONSUL_CONTAINER_ID> with your running container ID. You can list your running container using 'docker container list' command.

Docker
docker logs -f <CONSUL_CONTAINER_ID>
Windows

All logs are written to Event manager.

Next steps

Install futher microservices.