Start and Configure MariaDB Agent Manager on MariaDB Enterprise Server Nodes

Overview

The MariaDB Agent Manager coordinates deployment of the agents needed to consolidate and push data to the Remote Observability Service.

This page shows how to start and configure MariaDB Agent Manager on MariaDB Enterprise Server nodes, so that they can be monitored by the Remote Observability Service.

With MariaDB Agent Manager, ES nodes can be configured as Monitored Hosts. In development environments, users might not want to dedicate a standalone host to be a Dedicated Forwarding Host. In those environments, one Monitored Host (such as any ES node) can also serve as a Forwarding Host. However, in production environments, MariaDB recommends using a Dedicated Forwarding Host.

Compatibility

MariaDB Enterprise ColumnStore

  • MariaDB Enterprise ColumnStore 5

  • MariaDB Enterprise ColumnStore 6

MariaDB Enterprise Server

  • MariaDB Enterprise Server 10.3

  • MariaDB Enterprise Server 10.4

  • MariaDB Enterprise Server 10.5

  • MariaDB Enterprise Server 10.6

Operating Systems

  • CentOS 7

  • Red Hat Enterprise Linux 7

  • Red Hat Enterprise Linux 8

  • Rocky Linux 8

  • Ubuntu 18.04 LTS

  • Ubuntu 20.04 LTS

  • Ubuntu 22.04 LTS

Prerequisites

Before performing this procedure, deploy MariaDB Agent Manager on each Forwarding Host and Monitored Host.

Step 1: Switch to Dedicated OS User

For security purposes, MariaDB does not recommend running MariaDB Agent Manager as root.

If you created a dedicated user account and group for MariaDB Agent Manager, switch to a shell using the dedicated user account:

$ su -l mariadbagent

Each of the subsequent steps in this procedure should be performed using this dedicated user account.

Step 2: Configure Firewalls

MariaDB Agent Manager communicates over TCP between the Forwarding Host and each Monitored Host. MariaDB Agent Manager also communicates over TCP between the Forwarding Host and the Remote Observability Service.

Firewall configuration must support this communication.

Forwarding Server ports

If the ES node is also acting as a Forwarding Host, allow incoming traffic on the following ports:

Port

Source

Purpose

TCP/9303

localhost

API port (overridden by specifying the --api-port option when executing the mariadb_agent_manager start sub-command)

Enterprise Server ports

On each Monitored Host running MariaDB Enterprise Server, allow incoming traffic on the following ports:

Port

Source

Purpose

TCP/3306

Each Forwarding Host

Enterprise Server port

TCP/9100

Each Forwarding Host

node_exporter listening port

TCP/9104

Each Forwarding Host

mariadb_exporter listening port

In environments where non-default ports are used, the firewall configuration must be adapted for the specific ports in use.

Step 3: Create ES Accounts

MariaDB Agent Manager connects to database user accounts on Monitored Hosts.

A dedicated ES user account should be created for MariaDB Agent Manager. In each topology, the user account needs to be created on different nodes:

  • With Single Node Enterprise Server, the user account should be created on the ES node.

  • With the Replicated Transactions and Multi-Node Analytics topologies, the user account should be created on the primary node, and the primary node replicates the user to all replica nodes.

  • With the Galera Cluster topology, the user account should be created on a single node in the Primary Component, and the node replicates the user account to all nodes in the Primary Component.

If you previously created an ES user when you ran the mariadb_agent_manager install sub-command, you can skip this step.

On each ES node that should get the account based on the rules above, create a dedicated ES user account using one of the following methods:

  • To have MariaDB Agent Manager automatically create the account with the correct privileges, execute the mariadb_agent_manager create-user sub-command:

    $ mariadb_agent_manager create-user
    
  • Or to manually create the user account, expand the section below that contains the privileges required for your specific version of MariaDB Enterprise Server:

Enterprise Server 10.5+ users

These instructions apply to Enterprise Server 10.5 and greater. Alternative instructions are provided for Enterprise Server 10.3 and 10.4.

On each topology running MariaDB Enterprise Server, create a user account with the following privileges:

CREATE USER ros@'localhost'
   IDENTIFIED BY 'passwd';

GRANT PROCESS, BINLOG MONITOR, REPLICA MONITOR
   ON *.*
   TO ros@'localhost';

GRANT SELECT
   ON mysql.global_priv
   TO ros@'localhost';

Enterprise Server 10.3/10.4 users

These instructions apply to Enterprise Server 10.3 and Enterprise Server 10.4. Alternative instructions are provided for Enterprise Server 10.5 and greater.

On each topology running MariaDB Enterprise Server, create a user account with the following privileges:

CREATE USER ros@'localhost'
   IDENTIFIED BY 'passwd';

GRANT PROCESS, REPLICATION CLIENT
   ON *.*
   TO ros@'localhost';

GRANT SELECT
   ON mysql.global_priv
   TO ros@'localhost';

Step 4: Prepare credentials.json

On each Monitored Host, exporters authenticate using credentials that are stored locally. These credentials must initially be provided in a credentials file.

The MariaDB Agent Manager credentials file is in JSON format. These instructions assume that the credentials file is named credentials.json

On each Monitored Host running MariaDB Enterprise Server, create a credentials file.

Create a mariadb section with the user account and password details from "Step 3: Create ES Accounts":

{
  "cred_store": {
    "mariadb": {
      "user": "ros",
      "pwd": "USER_PASSWORD"
    }
  }
}

Step 5: Encrypt Passwords

On each Monitored Host running MariaDB Enterprise Server, the passwords in the credentials file must be encrypted by executing the mariadb_agent_manager encrypt-creds sub-command:

$ mariadb_agent_manager encrypt-creds -p ~/credentials.json
The following files have been successfully created:
Encrypted credentials:    /home/USER/.config/mariadb-agent-manager/cred.json
Secret key:               /home/USER/.config/mariadb-agent-manager/.key.txt
  • The -p option specifies the path to the credentials file. Alternatively, the REMOTE_AGENT_CREDENTIALS environment variable can be used.

MariaDB Agent Manager encrypts the credentials and saves the encrypted credentials to its configuration directory.

After the credentials have been encrypted, MariaDB Agent Manager deletes the credentials file. If you need to preserve the credentials file, ensure that you have a backup.

Step 6: Prepare configuration.json

MariaDB Agent Manager reads a configuration file to understand the database infrastructure. These instructions assume that the configuration file is named configuration.json. The MariaDB Agent Manager configuration file is in JSON format.

Create a configuration file:

  • Select the example configuration file for your topology and edit to reflect your database infrastructure and parameters.

  • Alternatively, a configuration file can be created using the configuration wizard by executing the mariadb_agent_manager init sub-command.

The configuration file must be copied to each Forwarding Host and each Monitored Host.

Single Node Enterprise Server

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-standalone",
        "type": "standalone",
        "servers": [
          {
            "name": "mdb1",
            "type": "server",
            "hostname": "mdb1.example.com"
          }
        ]
      }
    ]
  }
}

Replicated Transactions Topology

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-replicated",
        "type": "replicated",
        "servers": [
          {
            "name": "mxs1",
            "type": "maxscale",
            "hostname": "mxs1.example.com"
          },
          {
            "name": "mdb1",
            "type": "server",
            "hostname": "mdb1.example.com"
          },
          {
            "name": "mdb2",
            "type": "server",
            "hostname": "mdb2.example.com"
          },
          {
            "name": "mdb3",
            "type": "server",
            "hostname": "mdb3.example.com"
          }
        ]
      }
    ]
  }
}

Multi-Node Analytics Topology

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-columnstore",
        "type": "columnstore",
        "servers": [
          {
            "name": "mxs1",
            "type": "maxscale",
            "hostname": "mxs1.example.com"
          },
          {
            "name": "cs_node1",
            "type": "server",
            "hostname": "mdb1.example.com"
          },
          {
            "name": "cs_node2",
            "type": "server",
            "hostname": "mdb2.example.com"
          },
          {
            "name": "cs_node3",
            "type": "server",
            "hostname": "mdb3.example.com"
          }
        ]
      }
    ]
  }
}

Galera Cluster Topology

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-galera",
        "type": "galera",
        "servers": [
          {
            "name": "mxs1",
            "type": "maxscale",
            "hostname": "mxs1.example.com"
          },
          {
            "name": "mdb1",
            "type": "server",
            "hostname": "mdb1.example.com"
          },
          {
            "name": "mdb2",
            "type": "server",
            "hostname": "mdb2.example.com"
          },
          {
            "name": "mdb3",
            "type": "server",
            "hostname": "mdb3.example.com"
          }
        ]
      }
    ]
  }
}

Step 7: Start MariaDB Agent Manager

On each Forwarding Host and Monitored Host running MariaDB Enterprise Server, MariaDB Agent Manager must be started by executing the mariadb_agent_manager start sub-command.

  • If the ES node is also acting as a Forwarding Host, MariaDB Agent Manager can be started for the first time with the following options:

    $ mariadb_agent_manager start -c ~/configuration.json -k ~/skysql-api-key.txt -f
    
    • The -c option specifies the path to the configuration file. Alternatively, the REMOTE_AGENT_CONFIG environment variable can be used.

    • The -k option specifies the path to a file that contains your SkySQL API Key. Alternatively, the REMOTE_AGENT_API_KEY environment variable can be used. Setting the API key is only required the first time that the services are started on the Forwarding Host, because MariaDB Agent Manager saves the API key to a file. If the option or environment variable are not set, MariaDB Agent Manager prompts the user to enter the API key.

    • The -f option indicates that the node is a Forwarding Host. Alternatively, the FORWARDING_SERVER environment variable can be used. If the host is not defined in the configuration file, MariaDB Agent Manager assumes that it is a dedicated Forwarding Host. If the host is defined in the configuration file, MariaDB Agent Manager handles it as a combination Forwarding and Monitored Host.

  • On each Monitored Host running MariaDB Enterprise Server, MariaDB Agent Manager can be started with the following options:

    $ mariadb_agent_manager start -c ~/configuration.json
    
    • The -c option specifies the path to the configuration file. Alternatively, the REMOTE_AGENT_CONFIG environment variable can be used.

After the service has been successfully started, MariaDB Agent Manager prints the status of the components running on the host:

STATUS of the SERVICES:
Service: MariaDB Exporter                         active
Service: Node Exporter                            active

Next Steps

If you still need to start and configure MariaDB Agent Manager on additional node types:

If you have already started and configured MariaDB Agent Manager on all nodes: