Skip to content

PXC-5333: ALTER INSTANCE RELOAD TLS for Galera - #2399

Open
jankowsk wants to merge 1 commit into
percona:8.4from
jankowsk:PXC-5333
Open

jankowsk wants to merge 1 commit into
percona:8.4from
jankowsk:PXC-5333

Conversation

@jankowsk

@jankowsk jankowsk commented Nov 10, 2026 •

Copy link
Copy Markdown

https://perconadev.atlassian.net/browse/PXC-5333

ALTER INSTANCE RELOAD TLS for Galera

Problem

The ALTER INSTANCE RELOAD TLS command reloads the MySQL SSL-related variables (ssl_ca, ssl_cert, ssl_key). The SET GLOBAL wsrep_provider_options='socket.ssl_reload=1' command reloads the Galera SSL parameters (socket.ssl_ca, socket.ssl_cert, socket.ssl_key).

We should have one command that reloads both, or the MySQL reload should cascade to Galera. The cascade could be turned on when pxc_encrypt_cluster_traffic is enabled.

We want to avoid modifying the parser.

Solution

The idea is to treat Galera connections as a TLS channel named wsrep, in the same way as the MySQL channels mysql_main and mysql_admin (see https://dev.mysql.com/doc/refman/9.7/en/alter-instance.html).

1. Channel wsrep

Galera SSL options are reloaded by:

ALTER INSTANCE RELOAD TLS FOR CHANNEL wsrep;

This does the same as SET GLOBAL wsrep_provider_options='socket.ssl_reload=1', with the same locking.

  • If no wsrep provider is configured or loaded, an error is returned.
  • If Galera SSL is disabled (socket.ssl=NO), Galera does nothing. The statement succeeds with a warning saying that Galera TLS is not enabled.

2. Channel mysql_main_and_wsrep

Galera SSL options are reloaded together with the MySQL ones for the main channel through an artificial channel that combines mysql_main and wsrep:

ALTER INSTANCE RELOAD TLS FOR CHANNEL mysql_main_and_wsrep;

This lets users reload both with a single command without changing the meaning of the existing commands.

3. Partial failure

Although it is a single command, reloading mysql_main_and_wsrep runs two separate operations: mysql_main first, then wsrep. The first one can succeed while the second one fails. In that case:

  • an error is returned;

  • the error text says that mysql_main has already been reloaded, so the user knows the statement was partially applied. For example:

    TLS for channel mysql_main was reloaded, but reloading TLS for channel wsrep failed: <reason>
    
  • after fixing the problem, the user only needs to repeat the Galera part (FOR CHANNEL wsrep).

If the mysql_main reload fails, wsrep is not attempted and the usual MySQL error is returned.

NO ROLLBACK ON ERROR applies only to the MySQL part. A wsrep failure is always an error.

The same rules apply to the cascade described in point 4.

4. Cascade when pxc_encrypt_cluster_traffic = ON

When pxc_encrypt_cluster_traffic = ON and a wsrep provider is configured, both plain ALTER INSTANCE RELOAD TLS and ALTER INSTANCE RELOAD TLS FOR CHANNEL mysql_main behave like FOR CHANNEL mysql_main_and_wsrep: MySQL TLS is reloaded first, then Galera TLS.

This changes the meaning of the existing command. It is the behavior users who set this flag are likely to expect, because Galera SSL is then configured from the MySQL ssl_* options.

When pxc_encrypt_cluster_traffic = OFF, Galera has its own SSL configuration and mysql_main reloads MySQL only, as in upstream MySQL.

4.1 Accepted limitation: mysql_main cannot be reloaded alone

The parser maps plain ALTER INSTANCE RELOAD TLS to the channel name mysql_main. So without a parser change, the plain form cannot be told apart from an explicit FOR CHANNEL mysql_main. As a result, with pxc_encrypt_cluster_traffic = ON:

  • there is no way to reload the mysql_main channel without also reloading Galera;
  • mysql_main and mysql_main_and_wsrep behave the same.

We accept this limitation to keep the parser unchanged.

4.2 Galera keeps its startup paths

With pxc_encrypt_cluster_traffic = ON, the Galera options socket.ssl_key, socket.ssl_ca and socket.ssl_cert are filled from the MySQL options ssl_key, ssl_ca and ssl_cert once, when the provider is loaded. Galera marks these options read-only, so they cannot be changed at runtime. socket.ssl_reload re-reads the files at the paths set at startup.

Only rotating certificates in place (new content, same file path) is supported for Galera. If the MySQL paths were changed at runtime, for example:

SET GLOBAL ssl_cert = '/new/server-cert.pem';
ALTER INSTANCE RELOAD TLS;

MySQL loads the new file, but Galera re-reads the old one. To make this visible instead of silent:

  • The server remembers the paths passed to Galera when the provider is loaded.
  • Whenever Galera TLS is reloaded with pxc_encrypt_cluster_traffic = ON (through the cascade, mysql_main_and_wsrep or wsrep), the current ssl_key, ssl_ca and ssl_cert values are compared with the remembered Galera paths.
  • If any of them differ, the reload still runs: MySQL loads the new paths and Galera re-reads its own paths. The statement succeeds with a warning naming the paths that differ and saying that a server restart is needed for Galera to use the new paths. The same message is written to the error log.

The check does not raise an error. An error would block MySQL TLS reloads (see 4.1) until the server is restarted.

Only ssl_key, ssl_ca and ssl_cert are passed to Galera. Changes to other MySQL TLS options (ssl_capath, ssl_crl, ssl_cipher, tls_version, ...) never affect Galera.

5. Privileges

ALTER INSTANCE RELOAD TLS needs CONNECTION_ADMIN. The existing Galera route (SET GLOBAL wsrep_provider_options) needs SYSTEM_VARIABLES_ADMIN. Through the new channels, a user with only CONNECTION_ADMIN can reload Galera TLS. We accept this.

6. Scope

  • Local node only. ALTER INSTANCE is not replicated (no TOI). The statement must be run on every node of the cluster.
  • New connections only. As with MySQL, existing Galera connections keep the certificate they were set up with. Only new connections use the reloaded one.
  • SST is not affected. SST runs as a separate process and reads its SSL configuration on its own.
  • No performance_schema row. performance_schema.tls_channel_status does not list the wsrep channel. This may be added later.

@it-percona-cla

it-percona-cla commented Nov 10, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@jankowsk jankowsk changed the title PXC-5333: ALTER INSTANCE RELOAD TLS for Galera https://perconadev.atl… PXC-5333: ALTER INSTANCE RELOAD TLS for Galera Nov 10, 2026
@jankowsk
jankowsk requested a balanced review from Copilot November 10, 2026 09:37

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The reconnect check still trusts the original certificate, so it can pass even if the reload leaves the old SSL context active and certificate rotation fails.

1 open issue
What changed in this PR

Extends ALTER INSTANCE RELOAD TLS to reload Galera TLS alongside MySQL TLS without changing the parser.

Changes:

  • Adds wsrep and mysql_main_and_wsrep channels, with automatic cascading when cluster traffic encryption is enabled.
  • Reports partial failures, disabled Galera TLS, and certificate-path differences.
  • Adds Galera tests for reloads, certificate rotation, failure handling, and provider availability.
File Description
sql/​wsrep_var.h Declares the Galera TLS settings structure and reload interface.
sql/​wsrep_var.cc Implements provider TLS reload and settings retrieval.
sql/​sql_admin.cc Adds channel routing, cascading, and reload diagnostics.
mysql-test/​suite/​galera/​t/​galera_ssl_reload_tls.test Tests explicit channels, failures, and certificate rotation.
mysql-test/​suite/​galera/​t/​galera_ssl_reload_tls.cnf Configures two nodes with Galera TLS enabled.
mysql-test/​suite/​galera/​t/​galera_ssl_reload_tls_no_ssl.test Tests warnings when Galera TLS is disabled.
mysql-test/​suite/​galera/​t/​galera_ssl_reload_tls_encrypt.test Tests cascading, path warnings, and missing-provider behavior.
mysql-test/​suite/​galera/​t/​galera_ssl_reload_tls_encrypt.cnf Enables cluster traffic encryption for cascade tests.
mysql-test/​suite/​galera/​r/​galera_ssl_reload_tls.result Records expected explicit-channel and rotation results.
mysql-test/​suite/​galera/​r/​galera_ssl_reload_tls_no_ssl.result Records expected disabled-TLS warnings.
mysql-test/​suite/​galera/​r/​galera_ssl_reload_tls_encrypt.result Records expected cascade results and diagnostics.

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Live Galera TLS reloads on the default encrypted-cluster path need human validation of multi-node certificate rotation and connection continuity because provider sources and runtime are unavailable in this snapshot.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

…assian.net/browse/PXC-5333

Problem:
ALTER INSTANCE RELOAD TLS reloads only the MySQL TLS context. Galera
TLS has to be reloaded separately with
SET GLOBAL wsrep_provider_options='socket.ssl_reload=1', even when
pxc_encrypt_cluster_traffic=ON and Galera uses the MySQL ssl_* files.

Resolution:
Treat Galera connections as TLS channels, without changing the parser:

* FOR CHANNEL wsrep reloads Galera TLS only, with the same locking as
  socket.ssl_reload. It fails if no provider is loaded, and succeeds
  with a warning if Galera TLS is disabled (socket.ssl=NO).
* FOR CHANNEL mysql_main_and_wsrep reloads mysql_main, then wsrep.
  If the wsrep part fails, the error says that mysql_main has already
  been reloaded. NO ROLLBACK ON ERROR applies to the MySQL part only.
* With pxc_encrypt_cluster_traffic=ON and a provider configured, plain
  ALTER INSTANCE RELOAD TLS and FOR CHANNEL mysql_main behave like
  mysql_main_and_wsrep.
* With pxc_encrypt_cluster_traffic=ON, Galera keeps the socket.ssl_*
  paths set at provider load and only re-reads those files. If ssl_ca,
  ssl_cert or ssl_key now point elsewhere, a warning is pushed and
  written to the error log saying a restart is needed.

The statement is local to the node (no TOI) and affects new
connections only.

Like socket.ssl_reload, the Galera reload replaces the certificate and
key but only adds to the CA trust store: a CA removed from the
socket.ssl_ca file stays trusted until restart.

Test:
galera.galera_ssl_reload_tls rotates node 1 to a certificate issued by
a new, unrelated CA (galera-reload-*.pem in std_data) and restarts
node 2 trusting only that CA. Node 2 can rejoin only if node 1 presents
the reloaded certificate, so the test fails if the reload is not
applied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants