How to manage regions (deb/2.9/CLI)

A region controller manages communication with the user, via the Web UI/API, as well as managing the rack controller(s) in your system. The MAAS postgres database is also managed by the region controller. Typical region-level responsibilities include requesting that a rack controller boot a machine, and providing the ephemeral Ubuntu image needed to commission or enlist a machine.

Three questions you might have:

  1. How do I set up PostgreSQL for the region?
  2. How do I add a new region host?
  3. How can I improve region controller performance?

Set up PostgreSQL for the region

Any number of API servers (region controllers) can be present as long as each connects to the same PostgreSQL database and allows the required number of connections.

On the primary database host, edit file /etc/postgresql/9.5/main/pg_hba.conf to allow the eventual secondary API server to contact the primary PostgreSQL database. Include the below line, replacing
$SECONDARY_API_SERVER_IP with the IP address of the host that will contain the secondary API server:

host maasdb maas $SECONDARY_API_SERVER_IP/32 md5

The primary database and API servers often reside on the same host.

Apply this change by restarting the database:

sudo systemctl restart postgresql

Add a new region host

On a secondary host, add the new region controller by installing maas-region-api:

sudo apt install maas-region-api

You will need the /etc/maas/regiond.conf file from the primary API server. Below, we assume it can be copied (scp) from the ‘ubuntu’ account home directory using password authentication (adjust otherwise). The local_config_set command will edit that file by pointing to the host that contains the primary PostgreSQL database. Do not worry: MAAS will rationalise the DNS (bind9) configuration options so that they match those used within MAAS:

sudo systemctl stop maas-regiond
sudo scp ubuntu@$PRIMARY_API_SERVER:regiond.conf /etc/maas/regiond.conf
sudo chown root:maas /etc/maas/regiond.conf
sudo chmod 640 /etc/maas/regiond.conf
sudo maas-region local_config_set --database-host $PRIMARY_PG_SERVER
sudo systemctl restart bind9
sudo systemctl start maas-regiond

Check three log files for any errors:

  1. /var/log/maas/regiond.log
  2. /var/log/maas/maas.log
  3. /var/log/syslog

Improving region controller performance

This functionality is available starting from MAAS 2.4.

The MAAS Region Controller is a daemon collection of 4 workers that are in charge of handling all the internals of MAAS. The regiond workers handle the UI, API and the internal communication between Region and Rack controllers.

In larger environments, which multiple rack controllers, you can easily improve performance within a region. You can increase the number of workers, which allows faster (parallel) handling of internal communication between region and rack controllers.

Increasing the number of workers will also increase the number of required database connections by 11 per extra worker. This may required PostgreSQL to have an increased number of allowed connections; please see the high availability article for more information on increasing the connections.

To increase the number of workers, simply edit regiond.conf (/etc/maas/regiond.conf) and set num_workers. For example:

[...]
num_workers: 8

Keep in mind that adding too many workers may reduce performance. We recommended one worker per CPU, up to eight workers in total. Increasing beyond that is possible but use at your own risk.