Search
Varnish Controller

Brainz

Brainz will start by waiting for database connection. Once a connection is established, it will wait for connection towards NATS.

Brainz can be scaled out with multiple instances. All instances need access to the same database in order to operate in the same cluster. Multiple brainz instances will all act as active and the message handling will be spread among them.

Installation

# Ubuntu/Debian
sudo apt install varnish-controller-brainz

# CentOS/RedHat
sudo yum install varnish-controller-brainz

System Administrator

A system administrator user is required in order to use the system. This user is a special user with full system permissions and can only be created using the brainz binary.

See authentication chapter for details about creating an system administrator account.

License

When the installation is done you need to add your license file. Brainz will by default look for the license file named varnish-controller.lic in the /var/lib/varnish-controller/varnish-controller-brainz/ directory. If you want to change where Brainz looks for the license file, edit the systemd service file and add a command line parameter -license or add the VARNISH_CONTROLLER_LICENSE environment variable.

For details about the license, see the license chapter.

PostgreSQL Interaction

Brainz is started with user, password and database for PostreSQL.

varnish-controller-brainz -db-server localhost:5432 -db-user varnish-controller -db-pass mypassword -db-name varnish-controller

These can be configured in the systemd service file as environment variables (or as environment variables in containers).

Advanced Configuration

There are some configuration parameters that can be tuned to change how the brainz process operates. These might not be self-explanatory and are described below.

Note: Do not change these parameters if you are not sure about the implications.

Deployment Throttle (-deployment-throttle <duration>)

This is mainly for handling large numbers of API requests that trigger changes to the deployed VCLGroups. When there is a flood of requests the deployment algorithm will wait this number of seconds before it will decide where things will be deployed. This is to avoid too many re-configurations due to a high number of fast changes.

Deployment Update (-deployment-update <duration>)

This is the time between each periodic deployment configuration verification. A deployment configuration is basically the algorithm that checks where things should be deployed and verifies that they are. This just makes sure that things are correct in the system. In normal operation this wouldn’t trigger any changes to the system.

Heartbeat Timeout (-hb-timeout <duration>)

This is the maximum time since last heartbeat from an agent. If this is reached and no heartbeats have been received during this time, the agent is considered down. Any VCLGroup deployed to this agent will be moved to any other matching agent if one exists. It is important that this value is in correlation with the agent heartbeat rate. An agent heartbeat rate set to higher than this value will mark the agent as down.

Keep Deleted (-keep-deleted <days>)

All resources in the system are kept in the database but marked as deleted (deleted_at in DB) when removed. This is to be able to revert back to removals that weren’t meant to happen (this is however a manual process using the database CLI). This argument tells how many days these deleted entries should be kept in the database. Entries reaching this timeout in days will be purged from the database.

Tick Rate (-tick-rate <duration>)

The brainz process has a main loop that handles a lot of different tasks, such as removal of old database entries, checking deployments, down agents, updating states of deployments, etc. This is the interval for which these checks will run.

Mod Admin User (-mod-admin-user)

This will tell brainz to update or create a system administrator. When specifying the two environment variables VARNISH_CONTROLLER_SYSTEM_ADMIN_USER and VARNISH_CONTROLLER_SYSTEM_ADMIN_PASS the user given by the environment variables will automatically be created/updated. If these two environment variables aren’t set, brainz will ask for interactive input of username and password.

Max Key Age (-max-key-age <duration>)

The max key age is the maximum age the current JWT signing key can have before a new key is generated. The previous keys will be kept until there are no signed JWTs with these keys remaining. All new JWTs will be signed with the latest generated key. Both the access token and refresh token consist of a JWT that is signed with these keys.

Compile Timeout (-compile-timeout <duration>)

When a VCLGroup is deployed OR validated its given VCL files will be compiled. This is a process that can take some time depending on the size of the VCL files. This setting should be set larger than the maximum time it takes to compile used VCL files. If this is set to low, timeout will occur between both agent and brainz and also for the REST API calls for functions that compile the VCL files. This should also be configured with the same value for api-gw.

Quit (-quit)

When this argument is provided, brainz will automatically exit after performing tasks such as -mod-admin-user for adminstrator user creation. This is suitable as a one shot invocation to create the first system administrator account without the further need of exposing system administrator credentials when starting brainz.