.. _regions:

Regions
-------

As your network and your NetSpyGlass installation grows, certain steps need to be
taken to make sure NetSpyGlass can keep up with this growth. First step is to
switch from a single server NetSpyGlass set up to a cluster. This allows you to
share the workload across multiple servers to improve scalability. This way,
you can take your NetSpyGlass installation to a few thousand devices.

The next step is to introduce regions.

Regions help improve scalability of NetSpyGlass instances monitoring large
geographically distributed networks. All devices are divided into groups
called regions to which agents are assigned, with several agents per region.
In this configuration, servers use configuration file `cluster.conf` to determine
which region each device belongs to and send polling tasks to the agents
in each region.

Regions provide a mechanism to control which agent is going
to poll each device. Agents should be deployed on servers somewhere close to the devices
they poll (in terms of lower network latency). This helps improve the performance
and reliability of polling.

Devices are assigned to regions using parameter `allocation` from configuration
file `cluster.conf` (see below). The value of this parameter is a list of subnet
definitions in CIDR notation. Each device is assigned to a region if its address
belongs to one of the subnets in the `allocation` parameter of that region.
More on this below.

.. note:
Although it is possible to assign NSG servers to regions too, this is optional.
By default, all servers receive data from all agents. Note that agents must be assigned
to regions, even if this is just one default region named 'world'. Agents are
assigned to regions using parameter `region` in the configuration file `agent.conf`



.. _cluster_config:

Cluster Configuration
^^^^^^^^^^^^^^^^^^^^^

Configuration file `cluster.conf` is used to allocate devices to regions.
This file is located in the directory `/opt/netspyglass/home/conf`.
This configuration file describes regions and defines rules for device allocation to regions.

Here is how file `cluster.conf` looks like:

.. code-block:: none

    REGION_SJC = [ "10.1.1.0/24", "10.23.1.0/24", ]
    REGION_IAD = [ "10.101.11.0/24", "10.101.5.0/24", ]

    cluster {
        regions = [
            {
                name = sjc
                allocation = ${REGION_SJC}
            }

            {
                name = iad
                allocation = ${REGION_IAD}
            }

            {
                # this region is used for NetSpyGlass own self-monitoring
                name = netspyglass
                # allocation must not be an empty list
                allocation = [ "255.255.255.255/32" ]
            }

        ]
    }

Parameters:

 - list `regions` defines cluster regions. Each element in this list is a dictionary
   with keys `name` and `allocation`. The name of the region must match region
   configured with NetSpyGlass agents (see :ref:`agent-config`)

 - `allocation` - this is a list of subnet addresses in CIDR location. Network
   devices are allocated to regions according to this list.