Start and Configure MariaDB Agent Manager on a Dedicated Forwarding Host

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 configure a Dedicated Forwarding Host to be used with MariaDB Agent Manager, so that it can transmit monitoring metrics and topology status details to the Remote Observability Service.

Compatibility

  • 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 the Dedicated Forwarding Host and all Monitored Hosts.

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.

On the Dedicated 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)

Step 3: 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 the Dedicated 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"
          }
        ]
      }
    ]
  }
}

Distributed Transactions Topology

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-distributed",
        "type": "distributed",
        "servers": [
          {
            "name": "mxs1",
            "type": "maxscale",
            "hostname": "mxs1.example.com"
          },
          {
            "name": "xpand1",
            "type": "xpand-backend",
            "hostname": "xpand1.example.com"
          },
          {
            "name": "xpand2",
            "type": "xpand-backend",
            "hostname": "xpand2.example.com"
          },
          {
            "name": "xpand3",
            "type": "xpand-backend",
            "hostname": "xpand3.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 4: Start MariaDB Agent Manager

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

  • On the Dedicated 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.

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: Prometheus                               active
Service: MariaDB Agent Manager Daemon             active
Service: SkySQL Uni 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: