Skip to main content

MySQL TLS Connection Configuration

This guide describes how to configure HAP to connect to MySQL using one-way TLS or mTLS.

Before configuring the connection, ensure that TLS is enabled on MySQL. An account using one-way TLS must not require a client certificate; for example, it must not have REQUIRE X509 set.

For mTLS, MySQL must trust the CA that issued the client certificate. To require a client certificate for an account, set REQUIRE X509.

Prepare Certificates​

Prepare the following files and ensure that the services inside the container can read them:

FileDescription
mysql-ca-cert.pemCA certificate used to verify the MySQL server certificate
mysql-client-cert.pemClient certificate, used for mTLS
mysql-client-key.pemClient private key, used for mTLS

One-way TLS requires only the CA certificate; mTLS also requires a client certificate and private key.

The following example mounts the certificates in /etc/mysql/ssl/ inside the container. You can use a different path, but it must match the path in the connection configuration. The connection address must match the name in the MySQL server certificate.

Mount Certificates​

  1. Store the certificates on the server. For example, place them in volume/mysql/ssl/ alongside docker-compose.yaml.

  2. In /data/mingdao/script/docker-compose.yaml, add the certificate mounts to volumes under the existing app service:

services:
app:
volumes:
- ./volume/mysql/ssl/mysql-ca-cert.pem:/etc/mysql/ssl/mysql-ca-cert.pem:ro
- ./volume/mysql/ssl/mysql-client-cert.pem:/etc/mysql/ssl/mysql-client-cert.pem:ro
- ./volume/mysql/ssl/mysql-client-key.pem:/etc/mysql/ssl/mysql-client-key.pem:ro

For one-way TLS, mount only the CA certificate; for mTLS, mount all three files above.

Configure the Connection​

Modify the configuration file for your deployment mode:

Configure the app service in /data/mingdao/script/docker-compose.yaml.

Add the following environment variables for your authentication method, and update the address, port, username, password, and certificate paths. Certificate paths are paths inside the container.

ENV_RDB_TYPE: '10'
ENV_RDB_URI_MDPROJECT: 'Server=192.0.2.10;Port=3306;Database=MDProject;uid=hap;password=YOUR_PASSWORD;SslMode=VerifyFull;SslCa=/etc/mysql/ssl/mysql-ca-cert.pem;'
ENV_RDB_URI_MDLOG: 'Server=192.0.2.10;Port=3306;Database=MDLog;uid=hap;password=YOUR_PASSWORD;SslMode=VerifyFull;SslCa=/etc/mysql/ssl/mysql-ca-cert.pem;'
ENV_RDB_URI_MDSTRUCTURE: 'Server=192.0.2.10;Port=3306;Database=MDStructure;uid=hap;password=YOUR_PASSWORD;SslMode=VerifyFull;SslCa=/etc/mysql/ssl/mysql-ca-cert.pem;'
ENV_RDB_URI_MDCALENDAR: 'Server=192.0.2.10;Port=3306;Database=MDCalendar;uid=hap;password=YOUR_PASSWORD;SslMode=VerifyFull;SslCa=/etc/mysql/ssl/mysql-ca-cert.pem;'
ENV_RDB_URI_MDAPPLICATION: 'Server=192.0.2.10;Port=3306;Database=MDApplication;uid=hap;password=YOUR_PASSWORD;SslMode=VerifyFull;SslCa=/etc/mysql/ssl/mysql-ca-cert.pem;'

ENV_RDB_URI_* takes precedence over the existing ENV_MYSQL_* connection settings. After confirming that no other services or maintenance scripts depend on them, you can remove the existing address, port, username, and password variables.

When connecting to MGR through MySQL Router, set Server to the Router addresses, separated by commas, and set Port to the Router read-write port.

The connection address must match the server certificate verified by TLS. When using an IP address, the certificate must include that IP address.

After configuring, run the following command from the installation manager directory in standalone mode to recreate the app container and apply the Compose configuration:

docker compose -f docker-compose.yaml up -d --no-deps --force-recreate app

Then restart the HAP microservices. In cluster mode, apply the configuration and restart the HAP microservices.