============
Consul Usage
============

Consul overview
===============

Consul is a service mesh solution providing a full featured control plane
with service discovery, configuration, and segmentation functionality.
Each of these features can be used individually as needed, or they can be
used together to build a full service mesh.

The Consul agent is the core process of Consul. The Consul agent maintains
membership information, registers services, runs checks, responds to queries,
and more.

Consul clients can provide any number of health checks, either associated
with a given service or with the local node. This information can be used
by an operator to monitor cluster health.

Please refer to `Consul Agent Overview <https://www.consul.io/docs/agent>`_.

Test Environment
================

There are three controller nodes and two compute nodes in the test environment.
Every node has three network interfaces. The first interface is used for
management, with an ip such as '192.168.101.*'. The second interface is used
to connect to storage, with an ip such as '192.168.102.*'. The third interface
is used for tenant, with an ip such as '192.168.103.*'.

Configure Firewalld
===================

Before installing packages, you must open ports on your Consul servers.

  .. code-block:: console

    firewall-cmd --permanent --zone=public --add-port={8300,8301,8302,8400,8500,8600}/tcp
    firewall-cmd --reload
    firewall-cmd --zone=public --list-all

Install Consul
==============

Install Consul for RHEL-based distributions. Other OS please refer to `Download Consul
<https://www.consul.io/downloads>`_.

  .. code-block:: console

    sudo dnf install -y dnf-plugins-core
    sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
    sudo dnf repolist
    sudo dnf install consul

Verify
------

  .. code-block:: console

    which consul
    consul version

Configure Consul agent
======================

Consul agent must runs on every node. Consul server agent runs on controller
nodes, while Consul client agent runs on compute nodes, which makes up one
Consul cluster.

The following is an example of a config file for Consul server agent which
binds to management interface of the host.

management.json

  .. code-block:: ini

    {
        "bind_addr": "192.168.101.1",
        "datacenter": "management",
        "data_dir": "/tmp/consul_m",
        "log_level": "INFO",
        "server": true,
        "bootstrap_expect": 3,
        "node_name": "node01",
        "addresses": {
            "http": "192.168.101.1"
        },
        "ports": {
            "http": 8500,
            "serf_lan": 8501
        },
        "retry_join": ["192.168.101.1:8501", "192.168.101.2:8501", "192.168.101.3:8501"]
    }


The following is an example of a config file for Consul client agent which
binds to management interface of the host.

management.json

  .. code-block:: ini

    {
        "bind_addr": "192.168.101.4",
        "datacenter": "management",
        "data_dir": "/tmp/consul_m",
        "log_level": "INFO",
        "node_name": "node04",
        "addresses": {
            "http": "192.168.101.4"
        },
        "ports": {
            "http": 8500,
            "serf_lan": 8501
        },
        "retry_join": ["192.168.101.1:8501", "192.168.101.2:8501", "192.168.101.3:8501"]
    }

Use the tenant or storage interface ip and ports when config agent in tenant
or storage datacenter.

Please refer to `Consul Agent Configuration <https://www.consul.io/docs/agent/options#command-line-options>`_.

Start Consul agent
==================

The Consul agent is started by the following command.

  .. code-block:: console

    # Consul agent –config-file management.json

  .. code-block:: console

    # sudo systemctl start consul
    # sudo systemctl enable consul

Test Consul installation
========================

After all Consul agents installed and started,
you can see all nodes in the cluster by the following command.

  .. code-block:: console

    # Consul members -http-addr=192.168.101.1:8500
    Node    Address              Status  Type    Build   Protocol  DC
    node01  192.168.101.1:8501   alive   server  1.10.2  2         management
    node02  192.168.101.2:8501   alive   server  1.10.2  2         management
    node03  192.168.101.3:8501   alive   server  1.10.2  2         management
    node04  192.168.101.4:8501   alive   client  1.10.2  2         management
    node05  192.168.101.5:8501   alive   client  1.10.2  2         management
