Configure TLS with MariaDB Agent Manager

Path

When running MariaDB Agent Manager, the path to the TLS parameters file can be specified using the -t option or by setting the REMOTE_AGENT_TLS_PARAMETERS environment variable.

Format

The MariaDB Agent Manager TLS configuration file uses the JSON format.

Sections

The MariaDB Agent Manager TLS configuration file consists of the following sections:

Authentication

When Prometheus and the exporters authenticate via TLS, Prometheus authenticates as the client, and the exporters authenticate as servers.

Multiple forms of authentication are supported using TLS:

• One-way TLS: The exporters authenticate themselves to Prometheus.

• Two-way TLS or mutual TLS: The exporters authenticate themselves to Prometheus, and the Prometheus authenticates itself to the exporters.

TLS and Exporters

TLS is enabled by server, rather than by exporter.

When TLS is enabled for a server, MariaDB Agent Manager enables TLS for all exporters used by the server, which can be:

• mariadb_exporter

• maxscale_exporter

• node_exporter

Each exporter uses the same set of certificate and key files.

Step 1: Generate Certificates and Keys

TLS uses asymmetric cryptography with a key pair consisting of a public key, and a private key. To use TLS with MariaDB Agent Manager, customers must obtain or create the certificates and keys.

Step 2: Enable TLS for Servers

TLS must be enabled for each server in the MariaDB Agent Manager Configuration File. These instructions assume the MariaDB Agent Manager configuration file is called configuration.json.

In the "datacenter.database_services[].servers[]" section, TLS is enabled for a server by setting the "tls" configuration attribute to "enabled".

The following example configuration file shows how to enable TLS:

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

Step 3: Configure TLS Parameters for Servers

The TLS parameters must be configured for each server in the TLS configuration file. These instructions assume the TLS configuration file is called tls_configuration.json.

In the "servers.tls_server_config.HOSTNAME" section, the TLS parameters can be configured for each server using the following configuration attributes:

The "servers.tls_server_config.default" section can be used to configure default TLS attributes for all servers.

For an example TLS configuration file, see "Example TLS Parameters File".

For additional information about how Prometheus uses these configuration attributes, see "Prometheus: HTTPS and Authentication".

Step 4: Configure TLS Parameters for Prometheus

The TLS parameters must be configured for Prometheus in the TLS configuration file. These instructions assume the TLS configuration file is called tls_configuration.json.

In the "prometheus.tls_configs.HOSTNAME" section, the TLS parameters can be configured for each server using the following configuration attributes:

The "prometheus.tls_configs.default" section can be used to configure default TLS attributes for all servers.

For an example TLS configuration file, see "Example TLS Parameters File".

For additional information about how Prometheus uses these configuration attributes, see "Prometheus: Configuration: tls_config".

Step 5: Copy Configuration Files to Every Host

Every host must have copies of the main configuration file and the TLS configuration file that were created or modified in the previous steps.

Copy the configuration file (configuration.json) and the TLS configuration file (tls_configuration.json) to every host.

Step 6: Stop MariaDB Agent Manager

On each Forwarding Host and Monitored Host, if MariaDB Agent Manager is already running, it must be stopped before continuing.

Execute the mariadb_agent_manager stop sub-command to stop MariaDB Agent Manager and the other Remote Monitoring components:

$ mariadb_agent_manager stop

Step 7: Start MariaDB Agent Manager

On each Forwarding Host and Monitored Host, MariaDB Agent Manager must be started with the new TLS parameters file.

Execute the mariadb_agent_manager start sub-command to start the services.

• On each Forwarding Host, MariaDB Agent Manager can be started with the following options:

  $ mariadb_agent_manager start -c ~/configuration.json -t ~/tls_configuration.json -f
  

  • The -c option specifies the path to the configuration file. Alternatively, the REMOTE_AGENT_CONFIG environment variable can be used.

  • The -t option specifies the path to a TLS parameters file. Alternatively, the REMOTE_AGENT_TLS_PARAMETERS environment variable can be used.

  • The -f option indicates that the node is a Forwarding Host. Alternatively, the FORWARDING_SERVER environment variable can be used.

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

  $ mariadb_agent_manager start -c ~/configuration.json -t ~/tls_configuration.json
  

  • The -c option specifies the path to the configuration file. Alternatively, the REMOTE_AGENT_CONFIG environment variable can be used.

  • The -t option specifies the path to a TLS parameters file. Alternatively, the REMOTE_AGENT_TLS_PARAMETERS environment variable can be used.

Example TLS Parameters File

The following example TLS parameters file shows how to configure the certificates and keys:

{
   "servers": {
      "tls_server_configs": {
         "default": {
            "cert_file": "/home/mariadbagent/certs/server.crt",
            "key_file": "/home/mariadbagent/certs/server.key",
            "client_auth_type": "NoClientCert",
            "client_ca_file": ""
         },
         "server2": {
            "cert_file": "/home/mariadbagent/certs/server2.crt",
            "key_file": "/home/mariadbagent/certs/server2.key"
         }
      }
   },
   "prometheus": {
      "tls_configs": {
         "default": {
            "cert_file": "/home/mariadbagent/certs/prometheus.crt",
            "key_file": "/home/mariadbagent/certs/prometheus.key"
         },
         "server2": {
            "ca_file": "/home/mariadbagent/certs/server2.crt"
         }
      }
   }
}