Merge "mariadb: add support for custom Galera notification script"

5 files changed, 144 insertions, 0 deletions

diff --git a/ansible/roles/mariadb/tasks/config.yml b/ansible/roles/mariadb/tasks/config.yml
index 1a8055110..65e563e18 100644
--- a/ansible/roles/mariadb/tasks/config.yml
+++ b/ansible/roles/mariadb/tasks/config.yml
@@ -36,6 +36,26 @@
     - enable_mariabackup | bool
     - inventory_hostname == mariadb_backup_host
 
+- name: Check if custom wsrep-notify.sh exists
+  ansible.builtin.stat:
+    path: "{{ node_custom_config }}/mariadb/wsrep-notify.sh"
+  register: wsrep_notify_stat
+  delegate_to: localhost
+  run_once: true
+
+- name: Copying over wsrep-notify.sh
+  vars:
+    service_name: "mariadb"
+    service: "{{ mariadb_services[service_name] }}"
+  ansible.builtin.template:
+    src: "{{ node_custom_config }}/mariadb/wsrep-notify.sh"
+    dest: "{{ node_config_directory }}/{{ service_name }}/wsrep-notify.sh"
+    mode: "0770"
+  become: true
+  when:
+    - wsrep_notify_stat.stat.exists
+    - service | service_enabled_and_mapped_to_host
+
 - name: Copying over config.json files for services
   ansible.builtin.template:
     src: "{{ item.key }}.json.j2"
diff --git a/ansible/roles/mariadb/templates/galera.cnf.j2 b/ansible/roles/mariadb/templates/galera.cnf.j2
index 90ad20522..eede80450 100644
--- a/ansible/roles/mariadb/templates/galera.cnf.j2
+++ b/ansible/roles/mariadb/templates/galera.cnf.j2
@@ -44,6 +44,9 @@ wsrep_sst_method={{ mariadb_wsrep_sst_method }}
 wsrep_sst_auth={{ database_user }}:{{ database_password }}
 wsrep_slave_threads=4
 wsrep_on = ON
+{% if wsrep_notify_stat.stat.exists %}
+wsrep_notify_cmd = /usr/local/bin/wsrep-notify.sh
+{% endif %}
 
 max_connections=10000
 
diff --git a/ansible/roles/mariadb/templates/mariadb.json.j2 b/ansible/roles/mariadb/templates/mariadb.json.j2
index 2ecc9fa5e..8711ce6f2 100644
--- a/ansible/roles/mariadb/templates/mariadb.json.j2
+++ b/ansible/roles/mariadb/templates/mariadb.json.j2
@@ -15,6 +15,13 @@
             "owner": "mysql",
             "perm": "0600"
         }{% endif %}
+        {% if wsrep_notify_stat.stat.exists %},
+        {
+            "source": "{{ container_config_directory }}/wsrep-notify.sh",
+            "dest": "/usr/local/bin/wsrep-notify.sh",
+            "owner": "mysql",
+            "perm": "0755"
+        }{% endif %}
         {% if database_enable_tls_backend | bool %},
         {
             "source": "{{ container_config_directory }}/ca-certificates/root.crt",
diff --git a/doc/source/reference/databases/mariadb-guide.rst b/doc/source/reference/databases/mariadb-guide.rst
index c4a40740e..b09ab11b6 100644
--- a/doc/source/reference/databases/mariadb-guide.rst
+++ b/doc/source/reference/databases/mariadb-guide.rst
@@ -69,3 +69,108 @@ Backup and restore is working only for default shard as kolla currently
 using HAProxy solution for MariaDB loadbalancer which is simple TCP and
 has configured only default shard hosts as backends, therefore backup
 script will reach only default shard on ``kolla_internal_vip_address``.
+
+.. _mariadb-notifications:
+
+Cluster Event Notifications
+---------------------------
+
+Kolla Ansible supports native MariaDB Galera cluster notifications. This allows
+operators to execute custom logic whenever a node status or cluster membership
+changes.
+
+To enable this feature, you must provide a custom script named
+``wsrep-notify.sh`` in the following directory on the control host:
+``/etc/kolla/config/mariadb/wsrep-notify.sh``.
+
+Kolla Ansible will automatically detect the presence of this file, copy it to
+the MariaDB nodes, and configure the ``wsrep_notify_cmd`` directive in the
+MariaDB configuration.
+
+Example 1: Integration with Prometheus Alertmanager
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use this feature to send alerts directly to Prometheus Alertmanager.
+Save the following content as ``/etc/kolla/config/mariadb/wsrep-notify.sh``:
+
+.. code-block:: bash
+
+    #!/bin/bash
+
+    # List of Alertmanager instances (direct IP addresses)
+    # Using kolla_address to bypass VIP for higher reliability
+    ALERTMANAGERS=(
+    {% for host in groups['prometheus-alertmanager'] %}
+      "{{ internal_protocol }}://{{ 'api' | kolla_address(host) |
+      put_address_in_context('url') }}:{{ hostvars[host]
+      ['prometheus_alertmanager_port'] }}/api/v2/alerts"
+    {% endfor %}
+    )
+
+    # Authentication credentials from Kolla configuration
+    AUTH="{{ prometheus_alertmanager_user }}:{{
+    prometheus_alertmanager_password }}"
+    HOSTNAME=$(hostname)
+
+    # Prepare the JSON payload for the Alertmanager API
+    PAYLOAD=$(cat <<EOF
+    [
+      {
+        "labels": {
+          "alertname": "GaleraEvent",
+          "severity": "warning",
+          "instance": "$HOSTNAME"
+        },
+        "annotations": {
+          "description": "Galera cluster event detected: $*",
+          "summary": "Galera Status Change on $HOSTNAME"
+        }
+      }
+    ]
+    EOF
+    )
+
+    # Iterate through instances until the first successful POST
+    for URL in "${ALERTMANAGERS[@]}"; do
+        echo "Attempting to send alert to: $URL"
+        if curl -X POST "$URL" \
+             -u "$AUTH" \
+             -H "Content-Type: application/json" \
+             -d "$PAYLOAD" \
+             --fail --silent --show-error; then
+            echo "Alert sent successfully."
+            exit 0
+        fi
+        echo "Failed to reach $URL, trying next instance..."
+    done
+
+    echo "Error: Could not send alert to any Alertmanager instance."
+    exit 1
+
+.. note::
+
+   When providing this script, ensure it has the correct permissions. Kolla
+   Ansible will attempt to set execution permissions (``0755``) automatically
+   during the deployment.
+
+Example 2: Logging Cluster Changes to a File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively, you can log all cluster events to a local file for later audit
+or simple monitoring. Save the following content as
+``/etc/kolla/config/mariadb/wsrep-notify.sh``:
+
+.. code-block:: bash
+
+   #!/bin/bash
+
+   LOG_FILE="/var/log/kolla/mariadb/galera_cluster_events.log"
+   TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
+
+   echo "[$TIMESTAMP] Host: $HOSTNAME | Event: $*" >> "$LOG_FILE"
+
+.. note::
+
+   When providing this script, ensure it has the correct permissions. Kolla
+   Ansible will attempt to set execution permissions (``0755``) automatically
+   during the deployment.
diff --git a/releasenotes/notes/mariadb-custom-notifications-aee3e90d5d0cb3dd.yaml b/releasenotes/notes/mariadb-custom-notifications-aee3e90d5d0cb3dd.yaml
new file mode 100644
index 000000000..4203bfabb
--- /dev/null
+++ b/releasenotes/notes/mariadb-custom-notifications-aee3e90d5d0cb3dd.yaml
@@ -0,0 +1,9 @@
+---
+features:
+  - |
+    Adds support for custom MariaDB Galera notification scripts.
+    Operators can provide a ``wsrep-notify.sh`` script in the custom
+    config directory (``/etc/kolla/config/mariadb/``). When detected,
+    Kolla Ansible configures MariaDB to execute it on cluster state
+    changes, enabling integration with Prometheus Alertmanager or
+    custom logging.