Installing Agent and adding instance via CLI
Important
Before installing Agent via CLI, complete the following steps:
check if “postgresql-contrib” package is installed. If not, install it;
check if the “pg_stat_statements” extension is created. If not, install it.
Registration of Agent in Platform
This installation algorithm allows adding Agent, that can exist without the list of instances to monitor.
Important
It is recommended to use automation tools (Ansible/Chef/Puppet etc.) used in your organization to prepare the DBMS for Agent installation.
Download and install Agent.
For deb distributions (Debian/Ubuntu):
if there is internet access:
mkdir -p /etc/apt/sources.list.d && sh -c 'echo "deb [arch=amd64] https://nexus.tantorlabs.ru/repository/apt-packages tantorlabs main" > /etc/apt/sources.list.d/tantorlabs.list' wget --quiet -O - https://public.tantorlabs.ru/tantorlabs.ru.asc | apt-key add - apt-get update apt-get install -y pmaagent=6.2.0
if there is no internet access:
curl "https://your-domain-name:8443/packages/pmaagent.deb" -o /tmp/pmaagent.deb -k apt-get install -y /tmp/pmaagent.deb
Instead of <your-domain-name>, put down the domain name specified during Platform installation.
For rpm distributions (CentOS/Rocky/RedHat/Amazon Linux):
if there is internet access:
mkdir -p /etc/yum.repos.d && cat >/etc/yum.repos.d/tantorlabs.repo <<EOL [tantorlabs] name=tantorlabs baseurl=https://nexus.tantorlabs.ru/repository/yum-packages/ enabled=1 gpgcheck=1 gpgkey=https://public.tantorlabs.ru/tantorlabs.ru.asc repo_gpgcheck=0 priority=1 deltarpm=0 EOL yum install -y pmaagent-6.2.0
if there is no internet access:
curl "https://your-domain-name:8443/packages/pmaagent.rpm" -o /tmp/pmaagent.rpm -k yum install -y /tmp/pmaagent.rpm
For CentOS 8+:
if there is internet access:
mkdir -p /etc/yum.repos.d && cat >/etc/yum.repos.d/tantorlabs.repo <<EOL [tantorlabs] name=tantorlabs baseurl=https://nexus.tantorlabs.ru/repository/yum-packages/ enabled=1 gpgcheck=1 gpgkey=https://public.tantorlabs.ru/tantorlabs.ru.asc repo_gpgcheck=0 priority=1 deltarpm=0 EOL dnf install -y pmaagent-6.2.0-0.x86_64
if there is no internet access:
curl "https://your-domain-name:8443/packages/pmaagent.rpm" -o /tmp/pmaagent.rpm -k dnf install -y /tmp/pmaagent.rpm
Instead of <your-domain-name>, put down the domain name specified during Platform installation.
Get a token in Platform interface on the “Tokens” page. To open this page, click on the profile icon in the upper right corner → “Settings”. More information on how to obtain tokens can be found in the instructions.
Using the obtained token, register Agent in Platform by entering commands on the DBMS server. Example of the registration command:
# pmaagent register --access-token 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwbWEiLCJleHAiOjE3MTI5NTU1OTksImlhdCI6MTcwMzc1MTA0NSwic2NvcGUiOiJJTlNUQUxMIn0.Om6EK8vn4mSJeVyFQ7WqCBj9YtwWRQDJAHTgBDi8958' --host '10.128.0.121' --workspace-name '10.128.0.121' --endpoint 'tantor.domain.asdfa:4222' Agent successfully registered
After this, a new Agent will appear in the list of Agents in Platform interface (the “Agents” tab when navigating to the namespace).
Adding an instance to Platform
You can add instances of two types:
SERVER — a DBMS installation running directly on the server.
CONTAINER — a DBMS installation running in a docker container.
Register the instance in Platform.
Example of adding a standalone (not Patroni) SERVER type instance:
Add the following parameters to the DBMS configuration. Example:
echo "listen_addresses='*'" >/var/lib/pgsql/tantor-se-15/data/postgresql.auto.conf
Add the instance with the following command:
Note
In db-user and db-pass, specify the name and password of the database user that Agent will use to connect to the instance’s database.
When creating this user, a connection to the database will be used with the password and login specified in the db-admin-user and db-admin-pass keys.
Only the data specified in the db-user and db-pass keys will be saved in Agent’s configuration file. And only they will be used by Agent.
pmaagent instances add --name '10.128.0.121' --environment 'SERVER' --type 'AwideDB' --db-host '10.128.0.121' --db-port '5432' --db-user 'pma_user' --db-pass 'password' --db-admin-user 'test_conn' --db-admin-pass 'passwd' --confirm ########################################################################################## # PMA Agent. Version: 6.2.0. # # Add on-premise PostgreSQL instance # # Local date/time: Tuesday, 10-Sep-24 18:18:30 MSK # ########################################################################################## - Testing database connection using provided host [10.128.0.121]... [OK] - Checking if the PostgreSQL instance is in restore mode... [OK] - Checking if the [postgresql-contrib] packaged is installed...... [OK] - Checking if the [pg_stat_statements] extension is installed...... [OK] - Checking if the [pg_store_plans] extension is installed...... [WARN] - Could not detect availability of the extension [pg_store_plans]. Need to create the extension. - Creating the [pma_user] database user... [OK] - Checking the pg_hba configuration... [OK] - Updating the [/var/lib/pgsql/data/pg_hba.conf] file... [OK] - Reloading the PostgreSQL configuration... [OK] - Testing connection to database with provided parameters... [OK] Instance [6ee6317e-a103-4907-a697-b51c045d72c8] has been added successfully
Restart Platform Agent with the command:
# systemctl restart pmaagentExample of adding a standalone CONTAINER type instance (not Patroni):
pmaagent instances add --name 'demo-patroni1' --type 'PostgreSQL' --environment CONTAINER --container-target-id 64698910af9c --db-host '10.128.0.121' --db-port '5432' --db-user 'postgres' --db-pass 'postgres' --db-admin-user 'test_conn' --db-admin-pass 'passwd' --confirm ########################################################################################## # PMA Agent. Version: 6.2.0. # # Add PostgreSQL instance running in container # # Local date/time: Thursday, 21-Dec-23 16:54:14 MSK # ########################################################################################## - Parameters: + Type of instance : on-premise PostgreSQL + PostgreSQL default host : 10.128.0.121 + listener port : 5432 + Database name : postgres + PostgreSQL user (i.e. super user) : postgres + password : (* * * * * *) + PostgreSQL agent's user name : postgres (this database user will be created. Agent connects to the monitored PostgreSQL instance using this user name) + password : (will be prompted to input) - WARNING: During the process, the PostgreSQL instance will be reconfigured and reloaded. - Please make sure the instance of PostgreSQL that is listening the port [5432] - is properly configured, and its client authentication (pg_hba) is consistent. - Testing database connection using provided host [10.128.0.121]... [OK] - Checking if the PostgreSQL instance is in restore mode... [OK] - Checking if the [postgresql-contrib] packaged is installed...... [OK] - Checking if the [pg_stat_statements] extension is installed...... [OK] - Checking if the [pg_store_plans] extension is installed...... [OK] - Creating the [postgres] database user... [OK] - Testing connection to database with provided parameters... [OK] - Testing container connection using default parameters... [OK] Instance [48631c53-7d14-4d69-984f-3d87612650b9] has been added successfully
Example of adding a Patroni SERVER type instance:
pmaagent instances add --name '192.168.112.134' --environment 'SERVER' --type 'AwideDB' --db-host '192.168.112.134' --db-port '5432' --db-user 'pma_user' --db-pass 'Dota1234@' --db-admin-user 'superus' --db-admin-pass 'Dota1234@' --patroni-cluster-hosts '192.168.112.132,192.168.112.134,192.168.112.135' --patroni-user 'test_user' --patroni-password 'test_pass' --patroni-port '8008' --confirm ########################################################################################## # PMA Agent. Version: 6.2.0. # # Add PostgreSQL and Patroni instances # # Local date/time: Friday, 13-Sep-24 10:58:12 MSK # ########################################################################################## - Parameters: + Type of instance : on-premise PostgreSQL + PostgreSQL default host(empty: "unix socket") : 192.168.112.134 + listener port : 5432 + Database name : postgres + PostgreSQL user (i.e. super user) : superus + password : (* * * * * *) + PostgreSQL agent's user name : pma_user (this database user will be created. Agent connects to the monitored PostgreSQL instance using this user name) + password : (* * * * * *) + Path to client key : + Path to client certificate : + Path to root CA certificate : + Client key passphrase : (not provided) - WARNING: During the process, the PostgreSQL instance will be reconfigured and reloaded. - Please make sure the instance of PostgreSQL that is listening the port [5432] - is properly configured, and its client authentication (pg_hba) is consistent. - Testing database connection using provided host [192.168.112.134]... [OK] - Checking if the PostgreSQL instance is in restore mode... [OK] - Checking if the [postgresql-contrib] packaged is installed...... [OK] - Checking if the [pg_stat_statements] extension is installed...... [WARN] - Could not detect availability of the extension [pg_stat_statements]. Need to create the extension. - Checking if the [pg_store_plans] extension is installed...... [WARN] - Could not detect availability of the extension [pg_store_plans]. Need to create the extension. - Creating the [pma_user] database user... [OK] - Testing connection to database with provided parameters... [OK] - Testing Patroni connection using provided port [8008]... [OK] Instance [d32e74cc-f285-4f9a-8642-1d7e2d551995] has been added successfully
Note
If the section is missing in the dynamic Patroni configuration (DCS)
postgresql:
pg_hba: […]
or the pg_hba list is empty, Agent does not create its own access record in DCS when connecting the next PostgreSQL instance. Accordingly, Patroni will not regenerate cluster $PGDATA/pg_hba.conf, and the line with Agent’s host will not be included in the final file.
In this case, you need to manually add the record directly to the local pg_hba.conf of this node and the server shall be restarted (SELECT pg_reload_conf();).
Example of the record that needs to be added:
host all pma_user 10.200.44.57/32 scram-sha-256
You get this configuration only when the pg_hba.conf file is not centrally managed by Patroni, but is stored and maintained separately on each node (a typical case is geo-distributed clusters with different access policies at different sites).
Go to Platform interface and check that new instances have appeared in the list of instances. Metrics will appear within two minutes.
The list of instances can also be viewed in the CLI. Example ща views:
pmaagent instances list Environment Key Name DB Host DB Port DB Name SERVER 78cdbd4b-029b-40ea-972e-535f42b26855 10.128.0.121 10.128.0.121 5432 postgres
Removing an instance from Platform
Example of removing an instance:
pmaagent instances remove --key 78cdbd4b-029b-40ea-972e-535f42b26855 --confirm
Important
When removing the last instance, if it is of SERVER type, we will unregister Agent in Platform and the configuration will be deleted.
pmaagent instances list
Failed to load the configuration file. Сonfiguration file [/var/lib/pma/agent/agent.yml] not found.
You can use the following commands to view reference information:
“pmaagent register –help” — reference information on registering Agent. Example usage:
pmaagent register --help Registering the pmaagent Usage: pmaagent register [flags] Flags: --access-token string Access token. Used for authentication and authorization purposes --endpoint string Bus endpoint --help help about any command --host string IP address of host environment used to register Agent --workspace-name string Destination name of platform namespace. Value is case sensitive Global Flags: -c, --config-file string Path to the configuration file (default "/var/lib/pma/agent/agent.yml") -s, --stdout Send logging information to stdout. By default it is the file destination specified in the configuration file
“pmaagent instances add –help” — reference information on adding an instance. Example usage:
pmaagent instances add --help Add instance Usage: pmaagent instances add [flags] Flags: --aws-access-key-id string AWS Access Key ID (https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html). AWS RDS instance only. --aws-secret-access-key string AWS Secret Access Key. AWS RDS instance only. -y, --confirm Auto confirm all dialogs and command line interactions --container-host string Published container host (https://docs.docker.com/engine/reference/commandline/port) --container-port uint16 Published container port --container-target-id string Target managed/monitored container identifier (minimum 12 symbols) -w, --db-admin-pass string PostgreSQL database admin user password -u, --db-admin-user string Connect to the monitored PostgreSQL instance as specified admin database user. It should have privileged access credentials (default "postgres") --db-client-cert string PostgreSQL client cert path --db-client-key string PostgreSQL client key path --db-client-key-passphrase string PostgreSQL client's key passphrase --db-host string PostgreSQL instance server host or unix socket dir -d, --db-name string Monitored database name (default "postgres") -W, --db-pass string PostgreSQL database user password -p, --db-port uint16 PostgreSQL instance server port (default 5432) --db-root-ca string PostgreSQL root ca path -U, --db-user string Connect to the monitored PostgreSQL instance as specified database user. It should have privileged access credentials (default "pma_user") -e, --environment string Environment type. Possible values: ["CONTAINER" "SERVER" "RDS"] (default "SERVER") -h, --help help for add --name string Instance name --patroni-client-cert string Patroni client cert path --patroni-client-key string Patroni client key path --patroni-cluster-hosts strings The Patroni list includes the names of the cluster instance hosts or their IP addresses. --patroni-host string Patroni instance host name or IP address --patroni-passphrase string Patroni client's key passphrase --patroni-password string Patroni instance user password -P, --patroni-port uint16 Patroni instance port --patroni-root-ca string Patroni root ca path --patroni-ssl Use SSL to connect to the Patroni instance (default false) --patroni-user string Patroni instance user name -s, --stdout Send logging information to stdout. The default is the file destination specified in the configuration file --type string Instance type: ["PostgreSQL" "AwideDB" "RDS"] (default "PostgreSQL") Global Flags: -c, --config-file string Path to the configuration file (default "/var/lib/pma/agent/agent.yml")
“pmaagent instances remove –help” — reference information on removing an instance. Example usage:
pmaagent instances remove --help Remove instance Usage: pmaagent instances remove [flags] Flags: -y, --confirm Auto confirm all dialogs and command line interactions -h, --help help for remove --key string Key of the instance to remove --name string Name of the instance to remove Global Flags: -c, --config-file string Path to the configuration file (default "/var/lib/pma/agent/agent.yml") -s, --stdout Send logging information to stdout. By default it is the file destination specified in the configuration file