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:
| File | Description |
|---|---|
mysql-ca-cert.pem | CA certificate used to verify the MySQL server certificate |
mysql-client-cert.pem | Client certificate, used for mTLS |
mysql-client-key.pem | Client 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
- HAP Standalone Mode (Docker Compose)
- HAP Cluster Mode (Kubernetes)
-
Store the certificates on the server. For example, place them in
volume/mysql/ssl/alongsidedocker-compose.yaml. -
In
/data/mingdao/script/docker-compose.yaml, add the certificate mounts tovolumesunder the existingappservice:
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.
-
Follow Mount Configuration Files to mount each required certificate file into the container.
- One-way TLS: mount the CA certificate.
- mTLS: mount the CA certificate, client certificate, and private key.
Use a different environment variable beginning with
ENV_SERVICE_CONFIGfor each file. -
Ensure that the mount paths inside the container match the certificate paths in the connection configuration below.
Configure the Connection
Modify the configuration file for your deployment mode:
- HAP Standalone Mode (Docker Compose)
- HAP Cluster Mode (Kubernetes)
Configure the app service in /data/mingdao/script/docker-compose.yaml.
Configure the microservices in config.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.
- One-Way TLS
- mTLS Mutual Authentication
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_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;SslCert=/etc/mysql/ssl/mysql-client-cert.pem;SslKey=/etc/mysql/ssl/mysql-client-key.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;SslCert=/etc/mysql/ssl/mysql-client-cert.pem;SslKey=/etc/mysql/ssl/mysql-client-key.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;SslCert=/etc/mysql/ssl/mysql-client-cert.pem;SslKey=/etc/mysql/ssl/mysql-client-key.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;SslCert=/etc/mysql/ssl/mysql-client-cert.pem;SslKey=/etc/mysql/ssl/mysql-client-key.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;SslCert=/etc/mysql/ssl/mysql-client-cert.pem;SslKey=/etc/mysql/ssl/mysql-client-key.pem;'
ENV_RDB_URI_*takes precedence over the existingENV_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.