Start and Configure MariaDB Agent Manager on MariaDB Xpand Nodes
This page is part of MariaDB's Documentation.
The parent of this page is: Start and Configure MariaDB Agent Manager
Topics on this page:
Overview
The MariaDB Agent Manager coordinates deployment of the agents needed to consolidate and push data to the SkySQL Observability service.
This page shows how to start and configure MariaDB Agent Manager on MariaDB Xpand nodes, so that they can be monitored by the SkySQL Observability service.
With MariaDB Agent Manager, Xpand 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 Xpand node) can also serve as a Forwarding Host. However, in production environments, MariaDB recommends using a Dedicated Forwarding Host.
Compatibility
MariaDB Xpand
MariaDB Xpand 5.3
MariaDB Xpand 6.0
MariaDB Xpand 6.1
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, install MariaDB Agent Manager on each Forwarding Host and Monitored Host.
Step 1: Login as Appropriate OS User
Login as the appropriate user, which depends on which systemd mode MariaDB Agent Manager uses for your operating system:
On operating systems that use MariaDB Agent Manager in user systemd mode, perform the procedure as the non-root OS user that runs the services. When logging in, do not use
su
to switch to the user, because a full login session is required to start the systemd user manager instance used by MariaDB Agent Manager's systemd services.On operating systems that use MariaDB Agent Manager in system systemd mode, perform the procedure as the
root
OS user.
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 SkySQL Observability service.
Firewall configuration must support this communication.
Forwarding Server ports
If the Xpand node is also acting as a Forwarding Host, allow incoming traffic on the following ports:
Port | Source | Purpose |
---|---|---|
TCP/9303 |
| API port (overridden by specifying the |
Xpand ports
On each Monitored Host running MariaDB Xpand, allow incoming traffic on the following ports:
Port | Source | Purpose |
---|---|---|
TCP/3306 | Each Forwarding Host | |
TCP/9100 | Each Forwarding Host | |
TCP/9104 | Each Forwarding Host |
In environments where non-default ports are used, the firewall configuration must be adapted for the specific ports in use.
Step 3: Create Xpand Accounts
If you previously created an Xpand user when you ran the mariadb_agent_manager install
sub-command, you can skip this step.
MariaDB Agent Manager connects to database user accounts on Monitored Hosts.
A dedicated Xpand user account should be created for MariaDB Agent Manager. The user account only needs to be created on a single node in the Xpand cluster. The user account is replicated to all nodes.
On each Xpand cluster, create a dedicated Xpand 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, create the account with the following privileges:
CREATE USER mariadbagent@'localhost' IDENTIFIED BY 'passwd'; GRANT PROCESS, REPLICATION CLIENT ON *.* TO mariadbagent@'localhost'; GRANT SELECT ON system.* TO mariadbagent@'localhost';
Step 4: Prepare mariadb-credentials.json
On each Monitored Host, exporters authenticate using credentials that are stored locally. These credentials must initially be provided in a credentials file.
If you created a database user account on this server using the mariadb_agent_manager create-user
or mariadb_agent_manager create-user
install sub-commands, the file should have been created automatically by MariaDB Agent Manager. If not, you need to create the file manually or copy it from another server that has the same credentials.
The MariaDB Agent Manager credentials file is in JSON format. These instructions assume that the credentials file is named mariadb-credentials.json
On each Monitored Host running MariaDB Xpand, create a credentials file.
Create a mariadb
section with the user account and password details from "Step 3: Create Xpand Accounts":
{
"cred_store": {
"mariadb": {
"user": "mariadbagent",
"pwd": "USER_PASSWORD"
}
}
}
Step 5: Encrypt Passwords
On each Monitored Host running MariaDB Xpand, 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 ~/mariadb-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, theREMOTE_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.
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"
}
]
}
]
}
}
Step 7: Start MariaDB Agent Manager
On each Forwarding Host and Monitored Host running MariaDB Xpand, MariaDB Agent Manager must be started by executing the mariadb_agent_manager start
sub-command.
If the Xpand 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 ~/api_token.txt -f
The
-c
option specifies the path to the configuration file. Alternatively, theREMOTE_AGENT_CONFIG
environment variable can be used.The
-k
option specifies the path to a file that contains your SkySQL API Key. Alternatively, theREMOTE_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, theFORWARDING_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 Xpand, MariaDB Agent Manager can be started with the following options:
$ mariadb_agent_manager start -c ~/configuration.json -k ~/api_token.txt
The
-c
option specifies the path to the configuration file. Alternatively, theREMOTE_AGENT_CONFIG
environment variable can be used.If you plan to use Fluent Bit to collect and process logs, the
-k
option is required to specify the path to a file that contains your SkySQL API Key. Alternatively, theREMOTE_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 Monitored 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.
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: