Configure TLS with MariaDB Agent Manager

Overview

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

With MariaDB Agent Manager, communication between Prometheus and some metrics exporters can be encrypted using TLS 1.2.

Prometheus's support for TLS encryption is experimental and might change in the future. For additional information, see "Prometheus: HTTPS and Authentication".

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:

Section

Description

"servers"

The set of hosts in your data center and the corresponding TLS parameters that MariaDB Agent Manager should use for each.

"prometheus"

Prometheus-related TLS settings.

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:

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:

Example Configuration File

{
  "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:

Attribute Key Name

Description

Type

Recommended Value

"cert_file"

  • Specify the absolute path to the server's certificate file

String

See description

"key_file"

  • Specify the absolute path to the server's private key file

String

See description

"client_auth_type"

  • Specify a server policy for client authentication

  • This attribute is optional

String

"NoClientCert"

"client_ca_file"

  • Specify the absolute path to the Certificate Authority (CA) chain file

  • This attribute is optional

String

See description

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:

Attribute Key Name

Description

Type

Recommended Value

"ca_file"

  • Specify the absolute path to the Certificate Authority (CA) chain file

String

See description

"cert_file"

  • Specify the absolute path to the certificate file

  • This attribute is optional

String

See description

"key_file"

  • Specify the absolute path to the private key file

  • This attribute is optional

String

See description

"server_name"

  • Set this to the desired hostname when the Server Name Indication (SNI) extension for TLS is used

  • This attribute is optional

String

See description

"insecure_skip_verify"

  • Set to true to disable validation of the server certificate

  • This attribute is optional

boolean

false

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"
         }
      }
   }
}