1 of 100

Tools

This space includes documentation for clients, utilities, and applications, including AI-focused ones, designed to help you manage, monitor, back up, and interact with your MariaDB Server deployment.

MariaDB Enterprise Manager

MariaDB Enterprise Manager is a comprehensive observability and management solution designed for your entire database fleet. It provides advanced, topology-aware monitoring and a powerful suite of visual tools for query development and schema management, all from a single, centralized interface.

MariaDB Enterprise Manager

Overview of MariaDB Enterprise Manager, a centralized observability and management solution offering topology-aware monitoring, visual schema management, and query editing via an integrated workspace.

At its core, Enterprise Manager uses lightweight agents to collect deep telemetry from your standalone databases, replicated topologies, and MaxScale clusters via the OpenTelemetry standard. This foundation powers the integrated Grafana dashboards, which come pre-packaged with production-ready visualizations and alerts. Beyond monitoring, the Workspace provides a shared environment for developers and DBAs with an advanced Query Editor and a visual ERD Designer. The entire system is secured with role-based access control, audit logging, and can integrate with your corporate identity provider (OIDC) for single sign-on.

Key Capabilities at a Glance

Advanced Monitoring

Leverage the power of a built-in Grafana instance, complete with pre-packaged dashboards and production-ready alerts. The platform provides the flexibility to create custom , define , and route notifications to a wide range of destinations.

Integration with Other Observability Solutions

Built on open standards, Enterprise Manager uses OpenTelemetry for metrics collection. Its integrated Prometheus time-series database exposes a query API, allowing you to seamlessly export metrics and integrate with your existing observability stack.

Centralized Management

Gain a topology-based, centralized view of your entire database fleet. Enterprise Manager discovers and visualizes your replication and clustering setups, providing the ability to drill down into a specific through a seamless single sign-on (SSO) experience.

Workspace

The Workspace provides a powerful suite of tools for developers and DBAs. It features a rich for running and debugging SQL and a visual for schema management and modeling across multiple database connections.

Enterprise Security

Secure your management layer with robust security features. Authenticate users with your corporate , enforce granular permissions with , and maintain compliance with a comprehensive audit log for all administrative actions.

Architecture Overview

Explains the client/server architecture, central components (Supermax, Grafana, Prometheus), and local agents (OpenTelemetry, exporters).

MariaDB Enterprise Manager is a client/server application for monitoring and managing MariaDB deployments. It provides topology-aware monitoring, visual schema management, and query editing across multiple database connections.

The architecture consists of two primary components: a central Enterprise Manager Server that aggregates data and hosts the user interface, and an Enterprise Manager Agent that is deployed on each monitored host.

Enterprise Manager Server

The Enterprise Manager Server runs on a dedicated host and acts as the central command center. It is delivered as a suite of Docker containers managed by Docker Compose.

The core components are the following:

Component

Description

Enterprise Manager Agent

The Enterprise Manager Agent is installed on each MariaDB Server and MaxScale host that you want to monitor. Its job is to collect data and forward it to the central server.

These components are installed via the mema-agent package (RPM or DEB) and include:

Prometheus Exporters: These are the primary data gatherers.
- Node Exporter: Collects system-level metrics (CPU, RAM, disk usage).
- Mysqld Exporter: Collects detailed metrics from the MariaDB database itself.

Networking Requirements

For the system to function correctly, the following firewall ports must be open on the Enterprise Manager Server host:

8090 (HTTP/S): The main entry point for the web UI. Nginx listens on this port and proxies requests to Supermax and Grafana.
4318 (HTTP/S): Agents on monitored nodes push telemetry data to this port.

Administration

Hub page covering deployment, user management, backup and restore, hostname changes, and security in Enterprise Manager.

Deployment

Guidelines and instructions for deploying MariaDB Enterprise Manager, including network and firewall requirements for successful installation.

This section provides an overview of the deployment process for MariaDB Enterprise Manager, covering installation and upgrades for both the central server and the monitoring agents.

MariaDB Enterprise Manager is designed for a streamlined deployment experience. You can launch the main server with a single-line command for a quick start, and a UI-integrated helper tool simplifies the process of installing and registering agents on your monitored databases.

Installing the Enterprise Manager Server

Installing MariaDB Enterprise Manager

Step-by-step instructions for deploying the Docker-based Enterprise Manager Server, including standard online setups and air-gapped installation procedures.

Prerequisites

Prepare a machine for Enterprise Manager installation that complies with Hardware and System Requirements
Make sure that you have required network ports opened:
Obtain MariaDB Customer Download Token
- Navigate to the
- Log in using your
Set up MariaDB Enterprise Repository - MariaDB Enterprise Tools for each monitored MariaDB Server and MaxScale
- https://mariadb.com/docs/server/server-management/install-and-upgrade-mariadb/installing-mariadb/binary-packages/mariadb-package-repository-setup-and-usage

Standard Installation

Log in to Docker registry

Download the installation script

Insert your Customer Download Token into the download URL and download the installation script:

The installer generates a self-signed TLS certificate for Enterprise Manager. To change the certificate, follow instructions at .

To modify metrics retention time, see .

Enterprise Manager Server Air-Gapped Installation

Installing Enterprise Manager to a machine without an Internet connection is possible by manually copying the Docker images and related settings from an Internet-connected machine to the final target machine.

Follow these steps:

Install on an Internet-connected machine

First, install Enterprise Manager on an Internet-connected machine as explained in the normal installation section. When the installation script asks for the address and port that Enterprise Manager should listen at for incoming connections, enter the values for the final target machine.

Save images and settings

Once installation is complete, save all related Docker images and settings by running the following commands from the directory that contains the

Agent Installation

Instructions for installing the mema-agent application using native OS package managers, including prerequisite steps for creating a local monitor user in MariaDB.

To install mema-agent, you need to set up .

The mema-agent is a small application that must be installed on every server you wish to monitor with MariaDB Enterprise Manager, including MariaDB Server nodes and MaxScale nodes.

This guide covers the recommended installation method using a package manager.

Add Multiple MaxScale Monitors

Explains how to monitor multiple logical databases or clusters managed by a single MaxScale deployment by adding or changing specific MaxScale monitors in the UI.

MariaDB Enterprise Manager allows you to monitor multiple logical databases or clusters that are managed by the same set of high-availability MaxScale instances. After adding your first MaxScale instance, you can easily add more monitors to track different services without re-entering the connection details.

Default Monitor Behavior

If you add a database from a MaxScale setup that has multiple monitors and do not explicitly select one, Enterprise Manager will automatically assign the first available monitor by default. To ensure you are tracking the correct service, it's best to specify the monitor manually.

Adding an Additional Monitor

Follow these steps to add another logical database that is monitored by the same MaxScale deployment.

Add a new monitored logical database

Navigate to your main database inventory page.

Changing the Monitor for an Existing Database

If you need to change which MaxScale monitor an existing logical database is tracking, follow these steps.

Navigate to your main database inventory page and locate the logical database you wish to edit.

SSO to MaxScale (Single Sign-On)

Instructions for configuring Single Sign-On (SSO) integration to seamlessly access the MaxScale GUI directly from MariaDB Enterprise Manager.

For topologies managed by MaxScale, you can seamlessly access the MaxScale GUI directly from Enterprise Manager using Single Sign-On.SSO to MaxScale requires MaxScale 25.10.0 or higher.1

Accessing the MaxScale GUI

Network and Firewall Requirements

Outlines the necessary network ports and firewall configurations (such as ports 8090 and 4318) required for UI access and agent telemetry data collection.

It's recommended to run MariaDB Enterprise Manager on an internal, secured network. Direct public exposure is not recommended.

Before installing MariaDB Enterprise Manager, ensure that your firewall and network rules allow traffic on all required ports. Proper connectivity is essential for the system to function correctly.

The following table details the necessary ports and their purposes.

Backup & Restore of Enterprise Manager

Procedures for backing up the Enterprise Manager configurations and metrics data, as well as steps for restoring the system in case of failure.

Note: This is about backing up the data, configuration and collected metrics of the Enterprise Manager (EM), not the databases.

Backing up Enterprise Manager Server

Stop the Enterprise Manager

Go to the Enterprise Manager installation directory
Run docker compose stop to stop the Enterprise Manager

Create a directory for backups

Take a backup of all the volumes

The backups directory now contains the data from the Enterprise Manager.

Start the Enterprise Manager

Go to the Enterprise Manager installation directory
Run docker compose up -d to start the Enterprise Manager

Restoring Enterprise Manager Server

Stop the Enterprise Manager

Go to the Enterprise Manager installation directory
Run docker compose stop to stop the Enterprise Manager

Change Hostname or IP Address

Steps for safely modifying the hostname or IP address of the Enterprise Manager server and ensuring all monitored agents remain connected.

To set the hostname or IP address for an existing MariaDB Enterprise Management instance, follow these instructions. Changing the hostname or IP address is useful if your server's IP changed or if you need to switch from an IP address to a public DNS name.

Connect to your server

SSH into the server where your Enterprise Manager is running:

Navigate to the directory

Change into the enterprise-manager directory, where your Docker Compose files are located:

Edit the `.env` file

Open the environment file with a text editor (for example nano):

Find the line that begins with MEMA_HOSTNAME=

Save the file

Save the file and exit the editor.

Restart the services

Restart the MEM services so the new environment variable takes effect. The --force-recreate flag ensures the containers are rebuilt using the updated environment variables:

After the restart, your Enterprise Manager will be accessible at the new hostname or IP address.

Usage

Hub page detailing how to use Enterprise Manager's core features, specifically Monitoring and the Workspace.

Monitoring

Covers the monitoring capabilities including the built-in Grafana dashboards, metrics tracking, and predefined alert rules for the database fleet.

Dashboards

Hub page for MariaDB Enterprise Manager's pre-packaged Grafana dashboards, which provide deep visibility into server health, database topologies, and system performance.

Alerts and Notifications

Overview of the integrated Grafana-based alerting engine used to detect critical conditions and dispatch notifications to various destinations.

MariaDB Enterprise Manager provides a powerful and flexible alerting system, built on the capabilities of the integrated Grafana Alerting engine. It allows you to proactively monitor your entire database fleet, define custom rules for potential issues, and receive notifications through various channels to ensure you can respond quickly.

How It Works: The Alerting Flow

The alerting process in MariaDB Enterprise Manager follows a clear, four-step flow from detection to notification.

SMTP Server Configuration

Instructions for configuring SMTP credentials and server details in the environment file to enable email alerts from the integrated alerting engine.

This page explains how to configure email alerting for MariaDB Enterprise Manager using Grafana's integrated alerting engine. Configure SMTP credentials and server details in the main environment file so Enterprise Manager can send alert notifications via email.

This is an advanced draft.

MariaDB Enterprise Kubernetes Operator

MariaDB Enterprise Kubernetes Operator automates provisioning, scaling, backups, and high availability, making cloud-native database operations efficient and reliable.

Installation

Detailed guide on installing the MariaDB Enterprise Kubernetes Operator using Helm charts or manual manifests within a Kubernetes environment.

Topologies

Explains supported deployment patterns such as standalone instances, Primary/Replica replication, and Galera Cluster configurations for high availability.

Backup and Restore

Procedures for configuring automated and on-demand backups using MariaDB Enterprise Backup, including restoration steps to recover data.

25.08 version update guide

This guide illustrates, step by step, how to update to 25.8.0 from previous versions.

Uninstall you current mariadb-enterprise-operator for preventing conflicts:

Alternatively, you may only downscale and delete the webhook configurations:

26.03 version update guide

This guide illustrates, step by step, how to update to 26.3.1 from previous versions. This guide only applies if you are updating from a version prior to 26.3.x, otherwise you may upgrade directly (see and docs)

The must be updated to the 26.3.1 version. You must set updateStrategy.autoUpdateDataPlane=true in your MariaDB resources before updating the operator. Then, once updated, the operator will also be updating the data-plane based on its version:

Suspend Reconciliation

Instructions on how to temporarily pause the Operator's automated management of a specific resource for maintenance or troubleshooting.

Suspended state

When a resource is suspended, all operations performed by the operator are disabled, including but not limited to:

Provisioning

Plugins

Overview of available plugins and extensions that can be used to enhance the functionality of the MariaDB Enterprise Kubernetes Operator.

Supported Docker Images

The following is a list of images that have plugins installed and available to use.

Even though these images have plugins installed, that doesn't necessarily mean that they are enabled by default. You may need to install them. The recommended operator native way to do so is to use:

Each supported plugin will have a section on how to install it.

Component

Image

Examples Catalog

A collection of YAML manifests and configuration examples for various common deployment scenarios and resource management tasks.

The contains a number of sample manifests that aim to show the operator functionality in a practical way. Follow these instructions for getting started:

Download the :

Install the configuration shared by all the examples:

Migrations

Learn about migrations with MariaDB Enterprise Kubernetes Operator. This section covers strategies and procedures for smoothly migrating your MariaDB databases within Kubernetes environments.

Specific guidance on migrating database instances into the multi-tenancy Catalog structure within a Kubernetes environment.

Migrate Embedded MaxScale To MaxScale Resource

In this guide, we will be migrating a MaxScale embedded in a MariaDB resource to it's own resource.

Note that if you've been using the embedded maxScale property, the operator will already have created a MaxScale resource to go along with it.

MariaDB Enterprise MCP Server

Overview

"Model Context Protocol" (MCP) is a standard or interface designed to bridge the gap between AI development tools (like copilots in your code editor) and your project's specific environment.

In simple terms, it's a way for an AI to understand the context of what you're working on.

The MariaDB Enterprise MCP (Model Context Protocol) Server is a secure, enterprise-grade application designed to act as the primary interface between AI assistants and MariaDB data ecosystems. This product solves a key challenge: how to allow powerful AI agents to safely and efficiently leverage an organization's most valuable asset—its data.

Token Management

Token management is a critical part of the system's security, handled primarily by the RAG API.

Token Generation

The process involves two main steps:

Example

Usage Examples

Standard SQL Query

{ "tool": "execute_sql", "parameters": { "database_name": "test_db", "sql_query": "SELECT * FROM users WHERE id = %s", "parameters": [123] } }

Create Vector Store

Insert Documents into Vector Store

Semantic Search

RAG Generation

Service Management

MariaDB AI RAG runs as a web service using Uvicorn/FastAPI. You can manage the service using standard system commands.

Starting the Service

# Start the service using the executable directly
./databridge

Viewing Logs

Logs are stored in the logs directory within the installation path:

Updates

Best practices and procedures for performing rolling updates and version upgrades for MariaDB Enterprise Server and MaxScale without downtime.

By leveraging the automation provided by MariaDB Enterprise Kubernetes Operator, you can declaratively manage large fleets of databases using CRs. This also covers day two operations, such as upgrades, which can be risky when rolling out updates to thousands of instances simultaneously.

To mitigate this, and to give you full control on the upgrade process, you are able to choose between multiple update strategies described in the following sections.

Update strategies

In order to provide you with flexibility for updating MariaDB reliably, this operator supports multiple update strategies:

: Roll out replica Pods one by one, wait for each of them to become ready, and then proceed with the primary Pod.
: Utilize the rolling update strategy from Kubernetes.
: Updates are performed manually by deleting Pods

Configuration

The update strategy can be configured in the updateStrategy field of the MariaDB resource:

It defaults to ReplicasFirstPrimaryLast if not provided.

Trigger updates

Updates are not limited to updating the image field in the MariaDB resource, an update will be triggered whenever any field of the Pod template is changed. This translates into making changes to MariaDB fields that map directly or indirectly to the Pod template, for instance, the CPU and memory resources:

Once the update is triggered, the operator manages it differently based on the selected update strategy.

`ReplicasFirstPrimaryLast`

This role-aware update strategy consists in rolling out the replica Pods one by one first, waiting for each of them become ready (i.e. readiness probe passed), and then proceed with the primary Pod. This is the default update strategy, as it can potentially meet various reliability requirements and minimize the risks associated with updates:

Write operations won't be affected until all the replica Pods have been rolled out. If something goes wrong in the update, such as an update to an incompatible MariaDB version, this is detected early when the replicas are being rolled out and the update operation will be paused at that point.
Read operations impact is minimized by only rolling one replica Pod at a time.
Waiting for every

`RollingUpdate`

This strategy leverages the rolling update strategy from the , which, unlike , does not take into account the role of the Pods(primary or replica). Instead, it rolls out the Pods one by one, from the highest to the lowest StatefulSet index.

You are able to pass extra parameters to this strategy via the rollingUpdate object:

`OnDelete`

This strategy aims to provide a method to update MariaDB resources manually by allowing the user to restart the Pods individually. This way, the user has full control over the update process and can decide which Pods are rolled out at any given time.

Whenever an , the MariaDB will be marked as pending to update:

From this point, you are able to delete the Pods to trigger the update, which will result the MariaDB marked as updating:

Once all the Pods have been rolled out, the MariaDB resource will be back to a ready state:

`Never`

The operator will not perform updates on the StatefulSet whenever this update strategy is configured. This could be useful in multiple scenarios:

Progressive fleet upgrades: If you're managing large fleets of databases, you likely prefer to roll out updates progressively rather than simultaneously across all instances.
Operator upgrades: When upgrading the operator, changes to the StatefulSet or the Pod template may occur from one version to another, which could trigger a rolling update of your MariaDB instances.

Data-plane updates

Highly available topologies rely on that run alongside MariaDB to enable the remote management of the database instances. These containers use the mariadb-enterprise-operator image, which can be automatically updated by the operator based on its image version:

By default, updateStrategy.autoUpdateDataPlane is false, which means that no automatic upgrades will be performed, but you can opt-in/opt-out from this feature at any point in time by updating this field. For instance, you may want to selectively enable updateStrategy.autoUpdateDataPlane in a subset of your MariaDB instances after the operator has been upgraded to a newer version, and then disable it once the upgrades are completed.

It is important to note that this feature is fully compatible with the strategy: no upgrades will happen when updateStrategy.autoUpdateDataPlane=true and updateStrategy.type=Never.

High Availability

This section provides guidance on how to configure high availability in MariaDB and MaxScale instances. If you are looking for an HA setup for the operator, please refer to the Helm documentation.

Our recommended setup for production is:

Use a highly available topology for MariaDB:
- with a primary node and at least 2 replicas.
- Synchronous multi-master with at least 3 nodes. Always an odd number of nodes, as it is quorum-based.
Leverage as database proxy to load balance requests and perform failover/switchover operations. Configure 2 replicas to enable MaxScale upgrades without downtime.
Use to avoid noisy neighbours.
Define .

Highly Available Topologies

: The primary node allows both reads and writes, while secondary nodes only serve reads. The primary has a binary log and the replicas asynchronously replicate the binary log events.
: All nodes support reads and writes, but writes are only sent to one node to avoid contention. The fact that is synchronous and that all nodes are equally configured makes the primary failover/switchover operation seamless and usually instantaneous.

Kubernetes Services

In order to address nodes, MariaDB Enterprise Kubernetes Operator provides you with the following Kubernetes Services:

<mariadb-name>: This is the default Service, only intended for the .
<mariadb-name>-primary: To be used for write requests. It will point to the primary node.

Whenever the primary changes, either by the user or by the operator, both the <mariadb-name>-primary and <mariadb-name>-secondary Services will be automatically updated by the operator to address the right nodes.

The primary may be manually changed by the user at any point by updating the spec.[replication|galera].primary.podIndex field. Alternatively, automatic primary failover can be enabled by setting spec.[replication|galera].primary.autoFailover, which will make the operator to switch primary whenever the primary Pod goes down.

MaxScale

While Kubernetes Services can be used for addressing primary and secondary instances, we recommend utilizing as database proxy for doing so, as it comes with additional advantages:

Enhanced failover/switchover operations for both replication and Galera
Single entrypoint for both reads and writes
Multiple router modules available to define how to route requests

The full lifecyle of the MaxScale proxy is covered by this operator. Please refer to for further detail.

Pod Anti-Affinity

Bear in mind that, when enabling this, you need to have at least as many Nodes available as the replicas specified. Otherwise your Pods will be unscheduled and the cluster won't bootstrap.

To achieve real high availability, we need to run each MariaDB Pod in different Kubernetes Nodes. This practice, known as anti-affinity, helps reducing the blast radius of Nodes being unavailable.

By default, anti-affinity is disabled, which means that multiple Pods may be scheduled in the same Node, something not desired in HA scenarios.

You can selectively enable anti-affinity in all the different Pods managed by the MariaDB resource:

Anti-affinity may also be enabled in the resources that have a reference to MariaDB, resulting in their Pods being scheduled in Nodes where MariaDB is not running. For instance, the Backup and Restore processes can run in different Nodes:

In the case of MaxScale, the Pods will also be placed in Nodes isolated in terms of compute, ensuring isolation not only among themselves but also from the MariaDB Pods. For example, if you run a MariaDB and MaxScale with 3 replicas each, you will need 6 Nodes in total:

Default anti-affinity rules generated by the operator might not satisfy your needs, but you can always define your own rules. For example, if you want the MaxScale Pods to be in different Nodes, but you want them to share Nodes with MariaDB:

Dedicated Nodes

If you want to avoid noisy neighbours running in the same Kubernetes Nodes as your MariaDB, you may consider using dedicated Nodes. For achieving this, you will need:

Taint your Nodes and add the counterpart toleration in your Pods.

Tainting your Nodes is not covered by this operator, it is something you need to do by yourself beforehand. You may take a look at the to understand how to achieve this.

Select the Nodes where Pods will be scheduled in via a nodeSelector.

Although you can use the default Node labels, you may consider adding more significative labels to your Nodes, as you will have to set to them in your Pod nodeSelector. Refer to the .

Add podAntiAffinity to your Pods as described in the section.

The previous steps can be achieved by setting these fields in the MariaDB resource:

Pod Disruption Budgets

Take a look at the if you are unfamiliar to PodDisruptionBudgets

By defining a PodDisruptionBudget, you are telling Kubernetes how many Pods your database tolerates to be down. This quite important for planned maintenance operations such as Node upgrades.

MariaDB Enterprise Kubernetes Operator creates a default PodDisruptionBudget if you are running in HA, but you are able to define your own by setting:

Connections

Explains how application clients connect to databases managed by the Operator, including the use of Kubernetes Services and MaxScale proxies.

MariaDB Enterprise Kubernetes Operator provides the Connection resource to configure connection strings for applications connecting to MariaDB. This resource creates and maintains a Kubernetes Secret containing the credentials and connection details needed by your applications.

`Connection` CR

A Connection resource declares an intent to create a connection string for applications to connect to a MariaDB instance. When reconciled, it creates a Secret containing the DSN and optionally, individual connection parameters:

The operator creates a Secret named connection containing a DSN and individual fields like username, password, host, port, and database. Applications can mount this Secret to obtain the connection details.

Service selection

By default, the host in the generated Secret points to the Service named after the referenced MariaDB or MaxScale resource (the same as metadata.name). For HA MariaDB, the Service <mariadb-name>-primary is used instead, so only the primary Pod will be used as target:

Alternatively, you may override the default behaviour by setting serviceName and connect to another Service.

Please refer to the to identify which Services are available.

Credential generation

The operator can automatically generate credentials for users via the GeneratedSecretKeyRef type with the generate: true field. This feature is available in the MariaDB, MaxScale, and User resources.

For example, when creating a MariaDB resource with an initial user:

The operator will automatically generate a random password and store it in a Secret named app-password. You can then reference this Secret in your Connection resource:

If you prefer to provide your own password, you can opt-out from random password generation by either not providing the generate field or setting it to false. This enables the use of GitOps tools like or to seed the password.

Secret template

The secretTemplate field allows you to customize the output Secret, allowing you to include individual connection parameters:

The resulting Secret will contain:

dsn: The full connection string
username: The database username
password: The database password

Custom DSN format

You can customize the DSN format using Go templates via the format field:

Available template variables:

{{ .Username }}: The database username
{{ .Password }}: The database password
{{ .Host }}: The database host

Refer to the for additional details about the template syntax.

TLS authentication

Connection supports TLS client certificate authentication as an alternative to password authentication:

When using TLS authentication, provide tlsClientCertSecretRef instead of passwordSecretKeyRef. The referenced Secret must be a Kubernetes TLS Secret containing the client certificate and key.

Cross-namespace connections

Connection resources can reference MariaDB instances in different namespaces:

This creates a Connection in the app namespace that references a MariaDB in the mariadb namespace.

MaxScale connections

Connection resources can reference MaxScale instances using maxScaleRef:

When referencing a MaxScale, the operator uses the MaxScale Service and its listener port. The health check will consume connections from the MaxScale connection pool.

External MariaDB connections

Connection resources can reference ExternalMariaDB instances by specifying kind: ExternalMariaDB in the mariaDbRef:

This is useful for generating connection strings to external MariaDB instances running outside of Kubernetes.

Health checking

The healthCheck field configures periodic health checks to verify database connectivity:

interval: How often to perform health checks (default: 30s)
retryInterval: How often to retry after a failed health check (default: 3s)

The Connection status reflects the health check results, allowing you to monitor connectivity issues through Kubernetes.

PAM

The MariaDB pam plugin facilitates user authentication by interfacing with the Pluggable Authentication Modules (PAM) framework, enabling diverse and centralized authentication schemes.

Currently the enterprise operator utilizes this plugin to provide support for:

LDAP based authentication

LDAP

This guide outlines the process of configuring MariaDB to authenticate users against an LDAP or Active Directory service. The integration is achieved by using MariaDB's Pluggable Authentication Module (PAM) plugin, which delegates authentication requests to the underlying Linux PAM framework.

How Does It Work?

To enable LDAP authentication for MariaDB through PAM, several components work in tandem:

PAM (Pluggable Authentication Modules): A framework used by Linux and other UNIX-like systems to consolidate authentication tasks. Applications like MariaDB can use PAM to authenticate users without needing to understand the underlying authentication mechanism. Operations such as system login, screen unlocking, and sudo access commonly use PAM.
nss-pam-ldapd: This is the software package that provides the necessary bridge between PAM and an LDAP server. It includes the core components required for authentication.
pam_ldap.so: A specific PAM module, provided by the nss-pam-ldapd package. This module is the "plug-in" that the PAM framework loads to handle authentication requests destined for an LDAP server.

The nslcd daemon is ran as a sidecar container and communication happens through the shared unix socket, following container best practices of keeping a single process per container.

What is needed for LDAP Auth?

nslcd is configured with 2 files. nslcd.conf which tells the daemon about the LDAP server and nsswitch.conf, determine the sources from which to obtain name-service information.

nslcd can be configured to run as a specific user based on the uid and gid props specified in the config file, however that user should have sufficient permissions to read/write to /var/run/nslcd, should own both nslcd.conf and nsswitch.conf and they should not be too open (0600).

Both of these configuration files will be attached later on in the example given.

nslcd.conf

The /etc/nslcd.conf is the configuration file for LDAP nameservice daemon.

In a production environment it is recommended to use LDAPS (LDAP secure), which uses traditional TLS encryption to secure data in transit. To do so, you need to add the following to your nslcd.conf file:

nsswitch.conf

The Name Service Switch (NSS) configuration file, located at /etc/nsswitch.conf. It is used by the GNU C Library and certain other applications to determine the sources from which to obtain name-service information in a range of categories, and in what order. Each category of information is identified by a database name.

Installing The PAM Plugin

The pam plugin is not enabled by default (even though it is installed). To enable it, you should add the following lines to your MariaDB Custom Resource:

See below for a complete example.

Combining It All Together

Fistly, we need to create our ConfigMaps and Secrets, that will store the nsswitch.conf, nslcd.conf and the mariadb pam module.

Make sure to adapt the nslcd-conf as per your ldap server configuration.

mariadb-nss-config.yaml:

kubectl apply -f mariadb-nss-config.yaml

Now that our configuration is done, we need to create the MariaDB custom resource along with needed configurations.

mariadb.yaml:

kubectl apply -f mariadb.yaml

And in the end we need to create our user in the database, which must have the same name as a user in ldap server. In the example below that's ldap-user. We also create mariadb-ldap secret, which holds the name of the plugin we are using as well as the module we need to load.

mariadb-user.yaml:

kubectl apply -f mariadb-user.yaml

After a few seconds, the user should have been created by the operator. To verify that all is working as expected, modify the <password> field below and run:

You should see something along the lines of:

LDAPS

If you followed the instructions for setting up a basic MariaDB instance with ldap, you need to fetch the public certificate that your LDAP server is set up with and add it to a called mariadb-ldap-tls.

If you have the certificate locally in a file called tls.crt you can run:

With MaxScale

To put MaxScale in front of your PAM-enabled MariaDB cluster, configure MaxScale so that it skips checking if passwords of incoming clients are correct, but rather assumes they are. The failure still occurs, but at the time when MaxScale tries to authenticate to the backend servers.

maxscale-ldap.yaml:

kubectl apply -f maxscale-ldap.yaml

Ref:

Known Issues

Slow Start On KIND

This may be a problem with the maximum number of file-handles a process can allocate. Some systems have this value set to really high, which causes an issue. To remedy this, you need to delete your kind cluster and run:

At this point, the problem should be fixed.

For more information, check .

Deployment Overview

What You Have

One Package: ai-nexus.deb

What's Inside the Package:

RAG API application
MCP Server application
Both applications bundled together

What You Need to Deploy

1. The Application Package (ai-nexus.deb)

This contains your RAG API and MCP Server applications.

2. A Database (MariaDB)

The applications need a database to store documents and vector embeddings.

3. Configuration (Secret Management Mode)

You need to choose HOW to provide secrets (API keys, passwords) to the applications.

Two Deployment Options

Option A: Deploy on Ubuntu (Native) ✅ SIMPLER

What happens: Install the .deb package directly on Ubuntu

Steps:

Install MariaDB on Ubuntu
Install ai-nexus.deb on Ubuntu
Configure secrets (choose a mode)
Start services

Guide: UBUNTU_DEPLOYMENT_GUIDE.md

Option B: Deploy with Docker (on Windows) 🐳

What happens: Package everything in Docker containers

Steps:

Build Docker image (wraps the .deb package)
Start containers with docker-compose
Configure secrets (choose a mode)

Guide: DOCKER_DEPLOYMENT_GUIDE.md

Secret Management Modes (Works with BOTH Options)

After you deploy the application (Ubuntu or Docker), you choose ONE mode:

Mode 1: Standalone (Simplest) ⭐

How it works: Secrets stored in a plain text config file

Config File Location:

Ubuntu: /opt/rag-in-a-box/config/config.env.template
Docker: config.env.secure.local

Example:

How to generate secure keys:

When to use: Development, testing, single developer

Mode 2: Local Vault (Production-Like) 🔐

How it works: Secrets stored in HashiCorp Vault (running locally)

Architecture:

Config File Location:

Ubuntu: /opt/rag-in-a-box/config/config.env.template
Docker: config.env.vault.local

Example:

When to use: Team development, production-like testing

Mode 3: 1Password (Enterprise) 🔑

How it works: Secrets stored in 1Password vault

Architecture:

Config File:

When to use: Enterprise with 1Password subscription

Mode 4: HCP Vault (Production Cloud) ☁️

How it works: Secrets stored in HashiCorp Cloud Platform

Architecture:

When to use: Production cloud deployments

Complete Deployment Flow

Scenario 1: Ubuntu Native + Standalone Mode

Scenario 2: Ubuntu Native + Vault Mode

Scenario 3: Docker + Standalone Mode

Scenario 4: Docker + Vault Mode

Key Points to Understand

1. The Package is the Same

The ai-nexus.deb package is identical regardless of:

Where you deploy it (Ubuntu or Docker)
Which secret mode you use (Standalone, Vault, 1Password, HCP)

2. Deployment Location is Independent of Secret Mode

You can use ANY secret mode with ANY deployment location:

Ubuntu + Standalone ✅
Ubuntu + Vault ✅
Ubuntu + 1Password ✅
Docker + Standalone ✅

3. The Application Decides at Startup

When RAG API and MCP Server start, they:

Read the config file
Check which mode is configured
Fetch secrets accordingly:

Which Guide to Use?

I want to deploy on Ubuntu (no Docker)

→ Use: UBUNTU_DEPLOYMENT_GUIDE.md

Then choose secret mode:

Standalone: Edit /opt/rag-in-a-box/config/config.env.template with actual secrets
Vault: Install Vault, store secrets, configure Vault connection in config
1Password: Install 1Password CLI, configure 1Password references in config

I want to deploy with Docker (on Windows)

→ Use: DOCKER_DEPLOYMENT_GUIDE.md

Then choose secret mode:

Standalone: Edit config.env.secure.local with actual secrets
Vault: Run Vault container, store secrets, use config.env.vault.local
1Password: Install 1Password CLI, use config.env.1password.employee

Quick Decision Tree

Example: Complete Ubuntu Deployment (Standalone)

Example: Complete Ubuntu Deployment (Vault)

Summary

One Package (ai-nexus.deb) contains RAG API + MCP Server

Two Deployment Options:

Ubuntu Native (install .deb directly)
Docker (wrap .deb in container)

Four Secret Modes (choose one):

Standalone (secrets in config file)
Local Vault (secrets in local Vault)
1Password (secrets in 1Password)
HCP Vault (secrets in cloud Vault)

The application is the same - only the deployment location and secret source change.

Which Documentation to Read?

Your Situation

Read This

Is this clearer now? The key insight is:

Same package everywhere
Choose where to deploy (Ubuntu or Docker)
Choose how to manage secrets (Standalone/Vault/1Password/HCP)

Synchronous Multi-Master With Galera

MariaDB Enterprise Kubernetes Operator provides cloud native support for provisioning and operating multi-master MariaDB clusters using Galera. This setup enables the ability to perform writes on a single node and reads in all nodes, enhancing availability and allowing scalability across multiple nodes.

In certain circumstances, it could be the case that all the nodes of your cluster go down at the same time, something that Galera is not able to recover by itself, and it requires manual action to bring the cluster up again, as documented in the Galera documentation. The MariaDB Enterprise Kubernetes Operator encapsulates this operational expertise in the MariaDB CR. You just need to declaratively specify spec.galera, as explained in more detail later in this guide.

To accomplish this, after the MariaDB cluster has been provisioned, the operator will regularly monitor the cluster's status to make sure it is healthy. If any issues are detected, the operator will initiate the recovery process to restore the cluster to a healthy state. During this process, the operator will set status conditions in the MariaDB and emit Events so you have a better understanding of the recovery progress and the underlying activities being performed. For example, you may want to know which Pods were out of sync to further investigate infrastructure-related issues (i.e. networking, storage...) on the nodes where these Pods were scheduled.

`MariaDB` configuration

The easiest way to get a MariaDB Galera cluster up and running is setting spec.galera.enabled = true:

This relies on sensible defaults set by the operator, which may not be suitable for your Kubernetes cluster. This can be solved by overriding the defaults, so you have fine-grained control over the Galera configuration.

Refer to the to better understand the purpose of each field.

Storage

By default, the operator provisions two PVCs for running Galera:

Storage PVC: Used to back the MariaDB data directory, mounted at /var/lib/mysql.
Config PVC: Where the Galera config files are located, mounted at /etc/mysql/conf.d.

However, you are also able to use just one PVC for keeping both the data and the config files:

Wsrep provider

You are able to pass extra options to the Galera wsrep provider by using the galera.providerOptions field:

It is important to note that, the ist.recv_addr cannot be set by the user, as it is automatically configured to the Pod IP by the operator, something that an user won't be able to know beforehand.

A list of the available options can be found in the .

IPv6 support

If you have a Kubernetes cluster running with IPv6, the operator will automatically detect the IPv6 addresses of your Pods and it will configure several options to ensure that the Galera protocol runs smoothly with IPv6.

Galera cluster recovery

MariaDB Enterprise Kubernetes Operator monitors the Galera cluster and acts accordinly to recover it if needed. This feature is enabled by default, but you may tune it as you need:

The minClusterSize field indicates the minimum cluster size (either absolut number of replicas or percentage) for the operator to consider the cluster healthy. If the cluster is unhealthy for more than the period defined in clusterHealthyTimeout (30s by default), a cluster recovery process is initiated by the operator. The process is explained in the and consists of the following steps:

Recover the sequence number from the grastate.dat on each node.
Trigger a to obtain the sequence numbers in case that the previous step didn't manage to.
Mark the node with highest sequence (bootstrap node) as safe to bootstrap.

The operator monitors the Galera cluster health periodically and performs the cluster recovery described above if needed. You are able to tune the monitoring interval via the clusterMonitorInterval field.

Refer to the to better understand the purpose of each field.

Galera recovery `Job`

During the recovery process, a Job is triggered for each MariaDB Pod to obtain the sequence numbers. It's crucial for this Job to succeed; otherwise, the recovery process will fail. As a user, you are responsible for adjusting this Job to allocate sufficient resources and provide the necessary metadata to ensure its successful completion.

For example, if you're using a service mesh like Istio, it's important to add the sidecar.istio.io/inject=false label. Without this label, the Job will not complete, which would prevent the recovery process from finishing successfully.

Force cluster bootstrap

Use this option only in exceptional circumstances. Not selecting the Pod with the highest sequence number may result in data loss.

Ensure you unset forceClusterBootstrapInPod after completing the bootstrap to allow the operator to choose the appropriate Pod to bootstrap from in an event of cluster recovery.

You have the ability to manually select which Pod is used to bootstrap a new cluster during the recovery process by setting forceClusterBootstrapInPod:

This should only be used in exceptional circumstances:

You are absolutely certain that the chosen Pod has the highest sequence number.
The operator has not yet selected a Pod to bootstrap from.

You can verify this with the following command:

In this case, assuming that mariadb-galera-2 sequence is lower than 350454, it should be safe to bootstrap from mariadb-galera-0.

Finally, after your cluster has been bootstrapped, remember to unset forceClusterBootstrapInPod to allow the operator to select the appropriate node for bootstrapping in the event of a cluster recovery.

Bootstrap Galera cluster from existing PVCs

MariaDB Enterprise Kubernetes Operator will never delete your MariaDB PVCs. Whenever you delete a MariaDB resource, the PVCs will remain intact so you could reuse them to re-provision a new cluster.

That said, Galera is unable to form a cluster from pre-existing state, it requires a process to identify which Pod has the highest sequence number to bootstrap a new cluster. That's exactly what the operator does: whenever a new MariaDB Galera cluster is created and previously created PVCs exist, a cluster recovery process is automatically triggered.

Quickstart

Apply the following manifests to get started with Galera in Kubernetes:

Next, check the MariaDB status and the resources created by the operator:

Let's now proceed with simulating a Galera cluster failure by deleting all the Pods at the same time:

After some time, we will see the MariaDB entering a non Ready state:

Eventually, the operator will kick in and recover the Galera cluster:

Finally, the MariaDB resource will become Ready and your Galera cluster will be operational again:

Troubleshooting

The aim of this section is showing you how to diagnose your Galera cluster when something goes wrong. In this situations, observability is a key factor to understand the problem, so we recommend following these steps before jumping into debugging the problem.

Inspect MariaDB status conditions.

Make sure network connectivity is fine by checking that you have an Endpoint per Pod in your Galera cluster.

Check the events associated with the MariaDB object, as they provide significant insights for diagnosis, particularly within the context of cluster recovery.

Enable debug logs in mariadb-enterprise-operator.

Get the logs of all the MariaDB Pod containers, not only of the main mariadb container but also the agent and init ones.

Once you are done with these steps, you will have the context required to jump ahead to the section to see if any of them matches your case.

Common errors

Galera cluster recovery not progressing

If your MariaDB Galera cluster has been in GaleraNotReady state for a long time, the recovery process might not be progressing. You can diagnose this by checking:

Operator logs.
Galera recovery status:

MariaDB events:

If you have Pods named <mariadb-name>-<ordinal>-recovery-<suffix> running for a long time, check its logs to understand if something is wrong.

One of the reasons could be misconfigured Galera recovery Jobs, please make sure you read . If after checking all the points above, there are still no clear symptoms of what could be wrong, continue reading.

First af all, you could attempt to forcefully bootstrap a new cluster as it is described in . Please, refrain from doing so if the conditions described in the docs are not met.

Alternatively, if you can afford some downtime and your PVCs are in healthy state, you may follow this procedure:

Delete your existing MariaDB, this will leave your PVCs intact.
Create your MariaDB again, this will trigger a Galera recovery process as described in .

As a last resource, you can always delete the PVCs and bootstrap a new MariaDB from a backup as documented .

Permission denied writing Galera configuration

This error occurs when the user that runs the container does not have enough privileges to write in /etc/mysql/mariadb.conf.d:

To mitigate this, by default, the operator sets the following securityContext in the MariaDB's StatefulSet :

This enables the CSIDriver and the kubelet to recursively set the ownership ofr the /etc/mysql/mariadb.conf.d folder to the group 999, which is the one expected by MariaDB. It is important to note that not all the CSIDrivers implementations support this feature, see the for further information.

Unauthorized error disabling bootstrap

This situation occurs when the mariadb-enterprise-operator credentials passed to the agent as authentication are either invalid or the agent is unable to verify them. To confirm this, ensure that both the mariadb-enterprise-operator and the MariaDB ServiceAccounts are able to create TokenReview objects:

If that's not the case, check that the following ClusterRole and ClusterRoleBindings are available in your cluster:

mariadb-enterprise-operator:auth-delegator is the ClusterRoleBinding bound to the mariadb-enterprise-operator ServiceAccount which is created by the helm chart, so you can re-install the helm release in order to recreate it:

mariadb-galera:auth-delegator is the ClusterRoleBinding bound to the mariadb-galera ServiceAccount which is created on the flight by the operator as part of the reconciliation logic. You may check the mariadb-enterprise-operator logs to see if there are any issues reconciling it.

Bear in mind that ClusterRoleBindings are cluster-wide resources that are not garbage collected when the MariaDB owner object is deleted, which means that creating and deleting MariaDBs could leave leftovers in your cluster. These leftovers can lead to RBAC misconfigurations, as the ClusterRoleBinding might not be pointing to the right ServiceAccount. To overcome this, you can override the ClusterRoleBinding name setting the spec.galera.agent.kubernetesAuth.authDelegatorRoleName field.

Timeout waiting for Pod to be Synced

This error appears in the mariadb-enterprise-operator logs when a Pod is in non synced state for a duration exceeding the spec.galera.recovery.podRecoveryTimeout. Just after, the operator will restart the Pod.

Increase this timeout if you consider that your Pod may take longer to recover.

Galera cluster bootstrap timed out

This is error is returned by the mariadb-enterprise-operator after exceeding the spec.galera.recovery.clusterBootstrapTimeout when recovering the cluster. At this point, the operator will reset the recovered sequence numbers and start again from a clean state.

Increase this timeout if you consider that your Galera cluster may take longer to recover.

Logical backups

What is a logical backup?

A logical backup is a backup that contains the logical structure of the database, such as tables, indexes, and data, rather than the physical storage format. It is created using mariadb-dump, which generates SQL statements that can be used to recreate the database schema and populate it with data.

Logical backups serve not just as a source of restoration, but also enable data mobility between MariaDB instances. These backups are called "logical" because they are independent from the MariaDB topology, as they only contain DDLs and INSERT statements to populate data.

Although logical backups are a great fit for data mobility and migrations, they are not as efficient as for large databases. For this reason, physical backups are the recommended method for backing up MariaDB databases, especially in production environments.

Storage types

Currently, the following storage types are supported:

S3 compatible storage: Store backups in a S3 compatible storage, such as or .
PVCs: Use the available in your Kubernetes cluster to provision a PVC dedicated to store the backup files.
Kubernetes volumes: Use any of the supported natively by Kubernetes.

Our recommendation is to store the backups externally in a S3 compatible storage.

`Backup` CR

You can take a one-time backup of your MariaDB instance by declaring the following resource:

This will use the default StorageClass to provision a PVC that would hold the backup files, but ideally you should use a S3 compatible storage:

By providing the authentication details and the TLS configuration via references to Secret keys, this example will store the backups in a local Minio instance.

Alternatively you can use dynamic credentials from an EKS Service Account using EKS Pod Identity or IRSA:

By leaving out the accessKeyIdSecretKeyRef and secretAccessKeySecretKeyRef credentials and pointing to the correct serviceAccountName, the backup Job will use the dynamic credentials from EKS.

Scheduling

To minimize the Recovery Point Objective (RPO) and mitigate the risk of data loss, it is recommended to perform backups regularly. You can do so by providing a spec.schedule in your Backup resource:

This resource gets reconciled into a CronJob that periodically takes the backups.

It is important to note that regularly scheduled Backups complement very well the feature detailed below.

Retention policy

Given that the backups can consume a substantial amount of storage, it is crucial to define your retention policy by providing the spec.maxRetention field in your Backup resource:

Compression

You are able to compress backups by providing the compression algorithm you want to use in the spec.compression field:

Currently the following compression algorithms are supported:

bzip2: Good compression ratio, but slower compression/decompression speed compared to gzip.
gzip: Good compression/decompression speed, but worse compression ratio compared to bzip2.
none: No compression.

compression is defaulted to none by the operator.

Server-Side Encryption with Customer-Provided Keys (SSE-C)

You can enable server-side encryption using your own encryption key (SSE-C) by providing a reference to a Secret containing a 32-byte (256-bit) key encoded in base64:

When using SSE-C, you are responsible for managing and securely storing the encryption key. If you lose the key, you will not be able to decrypt your backups. Ensure you have proper key management procedures in place.

When restoring from SSE-C encrypted backups, the same key must be provided in the Restore CR or bootstrapFrom configuration.

`Restore` CR

You can easily restore a Backup in your MariaDB instance by creating the following resource:

This will trigger a Job that will mount the same storage as the Backup and apply the dump to your MariaDB database.

Nevertheless, the Restore resource doesn't necessarily need to specify a spec.backupRef, you can point to other storage source that contains backup files, for example a S3 bucket:

Target recovery time

If you have multiple backups available, specially after configuring a , the operator is able to infer which backup to restore based on the spec.targetRecoveryTime field.

The operator will look for the closest backup available and utilize it to restore your MariaDB instance. Only backups strictly before or at targetRecoveryTime will be matched.

By default, spec.targetRecoveryTime will be set to the current time, which means that the latest available backup will be used.

Bootstrap new `MariaDB` instances

To minimize your Recovery Time Objective (RTO) and to switfly spin up new clusters from existing Backups, you can provide a Restore source directly in the MariaDB object via the spec.bootstrapFrom field:

As in the Restore resource, you don't strictly need to specify a reference to a Backup, you can provide other storage types that contain backup files:

Under the hood, the operator creates a Restore object just after the MariaDB resource becomes ready. The advantage of using spec.bootstrapFrom over a standalone Restore is that the MariaDB is bootstrap-aware and this will allow the operator to hold primary switchover/failover operations until the restoration is finished.

Backup and restore specific databases

By default, all the logical databases are backed up when a Backup is created, but you may also select specific databases by providing the databases field:

When it comes to restore, all the databases available in the backup will be restored, but you may also choose a single database to be restored via the database field available in the Restore resource:

There are a couple of points to consider here:

The referred database (db1 in the example) must previously exist for the Restore to succeed.
The mariadb CLI invoked by the operator under the hood only supports selecting a single database to restore via the option, restoration of multiple specific databases is not supported.

Extra options

Not all the flags supported by mariadb-dump and mariadb have their counterpart field in the Backup and Restore CRs respectively, but you may pass extra options by using the args field. For example, setting the --verbose flag can be helpful to track the progress of backup and restore operations:

Refer to the mariadb-dump and mariadb CLI options in the section.

Staging area

S3 is the only storage type that supports a staging area.

When using S3 storage for backups, a staging area is used for keeping the external backups while they are being processed. By default, this staging area is an emptyDir volume, which means that the backups are temporarily stored in the node's local storage where the Backup/Restore Job is scheduled. In production environments, large backups may lead to issues if the node doesn't have sufficient space, potentially causing the backup/restore process to fail.

To overcome this limitation, you are able to define your own staging area by setting the stagingStorage field to both the Backup and Restore CRs:

In the examples above, a PVC with the default StorageClass will be used as staging area. Refer to the for more configuration options.

Similarly, you may also use a custom staging area when :

Important considerations and limitations

Root credentials

When restoring a backup, the root credentials specified through the spec.rootPasswordSecretKeyRef field in the MariaDB resource must match the ones in the backup. These credentials are utilized by the liveness and readiness probes, and if they are invalid, the probes will fail, causing your MariaDB Pods to restart after the backup restoration.

Restore job

Restoring large backups can consume significant compute resources and may cause Restore Jobs to become stuck due to insufficient resources. To prevent this, you can define the compute resources allocated to the Job:

Galera backup limitations

`mysql.global_priv`

Galera only replicates the tables with InnoDB engine, see the .

Something that does not include mysql.global_priv, the table used to store users and grants, which uses the MyISAM engine. This basically means that a Galera instance with mysql.global_priv populated will not replicate this data to an empty Galera instance. However, DDL statements (CREATE USER, ALTER USER ...) will be replicated.

Taking this into account, if we think now about a restore scenario where:

The backup file includes a DROP TABLE statement for the mysql.global_priv table.
The backup has some INSERT statements for the mysql.global_priv table.

This is what will happen under the scenes while restoring the backup:

The DROP TABLE statement is a DDL so it will be executed in galera-0, galera-1 and galera-2.
The INSERT statements are not DDLs, so they will only be applied to galera-0.

After the backup is fully restored, the liveness and readiness probes will kick in, they will succeed in galera-0, but they will fail in galera-1 and galera-2, as they rely in the root credentials available in mysql.global_priv, resulting in the galera-1 and galera-2 getting restarted.

To address this issue, when backing up MariaDB instances with Galera enabled, the mysql.global_priv table will be excluded from backups by using the --ignore-table option with mariadb-dump. This prevents the replication of the DROP TABLE statement for the mysql.global_priv table. You can opt-out from this feature by setting spec.ignoreGlobalPriv=false in the Backup resource.

Also, to avoid situations where mysql.global_priv is unreplicated, all the entries in that table must be managed via DDLs. This is the recommended approach suggested in the . There are a couple of ways that we can guarantee this:

Use the rootPasswordSecretKeyRef, username and passwordSecretKeyRef fields of the MariaDB CR to create the root and initial user respectively. This fields will be translated into DDLs by the image entrypoint.
Rely on the and CRs to create additional users and grants. Refer to the for further detail.

`LOCK TABLES`

Galera is not compatible with the LOCK TABLES statement:

For this reason, the operator automatically adds the --skip-add-locks option to the Backup to overcome this limitation.

Migrations using logical backups

Migrating an external MariaDB to a `MariaDB` running in Kubernetes

You can leverage logical backups to bring your external MariaDB data into a new MariaDB instance running in Kubernetes. Follow this runbook for doing so:

Take a logical backup of your external MariaDB using one of the commands below:

If you are using Galera or planning to migrate to a Galera instance, make sure you understand the and use the following command instead:

Ensure that your backup file is named in the following format: backup.2024-08-26T12:24:34Z.sql. If the file name does not follow this format, it will be ignored by the operator.
Upload the backup file to one of the supported . We recommend using S3.
Create your MariaDB resource declaring that you want to and providing a

If you are using Galera in your new instance, migrate your previous users and grants to use the User and Grant CRs. Refer to the for further detail.

Migrating to a `MariaDB` with different topology

Database mobility between MariaDB instances with different topologies is possible with logical backups. However, there are a couple of technical details that you need to be aware of in the following scenarios:

Migrating between standalone and replicated `MariaDBs`

This should be fully compatible, no issues have been detected.

Migrating from standalone/replicated to Galera `MariaDBs`

There are a couple of limitations regarding the backups in Galera, please make sure you read the section before proceeding.

To overcome this limitations, the Backup in the standalone/replicated instance needs to be taken with spec.ignoreGlobalPriv=true. In the following example, we are backing up a standalone MariaDB (single instance):

Once the previous Backup is completed, we will be able bootstrap a new Galera instance from it:

Reference

Troubleshooting

Galera `Pods` restarting after bootstrapping from a backup

Please make sure you understand the .

After doing so, ensure that your backup does not contain a DROP TABLE mysql.global_priv; statement, as it will make your liveness and readiness probes to fail after the backup restoration.

Physical backups

What is a physical backup?

A physical backup is a snapshot of the entire data directory (/var/lib/mysql), including all data files. This type of backup captures the exact state of the database at a specific point in time, allowing for quick restoration in case of data loss or corruption.

Physical backups are the recommended method for backing up MariaDB databases, especially in production environments, as they are faster and more efficient than logical backups.

Backup strategies

Multiple strategies are available for performing physical backups, including:

mariadb-backup: Taken using the enterprise version of , specifically , which is available in the MariaDB enterprise images. The operator supports scheduling Jobs to perform backups using this utility.
Kubernetes VolumeSnapshot: Leverage to create snapshots of the persistent volumes used by the MariaDB Pods. This method relies on a compatible CSI (Container Storage Interface) driver that supports volume snapshots. See the

In order to use VolumeSnapshots, you will need to provide a VolumeSnapshotClass that is compatible with your storage provider. The operator will use this class to create snapshots of the persistent volumes:

For the rest of compatible , the mariadb-backup CLI will be used to perform the backup. For instance, to use S3 as backup storage:

Storage types

Multiple storage types are supported for storing physical backups, including:

S3 compatible storage: Store backups in a S3 compatible storage, such as or .
Azure Blob Storage: Store backups in an .
Persistent Volume Claims (PVC): Use any of the available in your Kubernetes cluster to create a PersistentVolumeClaim (PVC) for storing backups.

Scheduling

Physical backup schedule can be optionally configured using the spec.schedule field in the PhysicalBackup resource. When empty, a single backup job is scheduled:

cron: to define the backup schedule.
suspend: Setting it to true, it prevents new backups from being scheduled.
immediate

It is very important to note that, by default, backups are only scheduled if the referred MariaDB resource is in ready state. You can override this behavior by setting mariaDbRef.waitForIt=false which allows backups to be scheduled even if the MariaDB resource is not ready.

Compression

When using physical backups based on mariadb-backup, you are able to choose the compression algorithm used to compress the backup files. The available options are:

bzip2: Good compression ratio, but slower compression/decompression speed compared to gzip.
gzip: Good compression/decompression speed, but worse compression ratio compared to bzip2.
none: No compression.

To specify the compression algorithm, you can use the compression field in the PhysicalBackup resource:

compression is defaulted to none by the operator.

Server-Side Encryption with Customer-Provided Keys (SSE-C) For S3

You can enable server-side encryption using your own encryption key (SSE-C) by providing a reference to a Secret containing a 32-byte (256-bit) key encoded in base64:

When restoring from SSE-C encrypted backups via bootstrapFrom, the same key must be provided in the S3 configuration.

Retention policy

You can define a retention policy both for backups based on mariadb-backup and for VolumeSnapshots. The retention policy allows you to specify how long backups should be retained before they are automatically deleted. This can be defined via the maxRetention field in the PhysicalBackup resource:

When using physical backups based on mariadb-backup, the operator will automatically delete backups files in the specified storage older than the retention period. The cleanup process will be performed after each successful backup.

When using VolumeSnapshots, the operator will automatically delete the VolumeSnapshot resources older than the retention period using the Kubernetes API. The cleanup process will be performed after a VolumeSnapshot is successfully created.

Target policy

You can define a target policy both for backups based on mariadb-backup and for VolumeSnapshots. The target policy allows you to specify in which Pod the backup should be taken. This can be defined via the target field in the PhysicalBackup resource:

The following target policies are available:

Replica: The backup will be taken in a ready replica. If no ready replicas are available, the backup will not be scheduled.
PreferReplica: The backup will be taken in a ready replica if available, otherwise it will be taken in the primary Pod.

When using the PreferReplica target policy, you may be willing to schedule the backups even if the MariaDB resource is not ready. In this case, you can set mariaDbRef.waitForIt=false to allow scheduling the backup even if no replicas are available.

Restoration

Physical backups can only be restored in brand new MariaDB instances without any existing data. This means that you cannot restore a physical backup into an existing MariaDB instance that already has data.

To perform a restoration, you can specify a PhysicalBackup as restoration source under the spec.bootstrapFrom field in the MariaDB resource:

This will take into account the backup strategy and storage type used in the PhysicalBackup, and it will perform the restoration accordingly.

As an alternative, you can also provide a reference to an S3 bucket that was previously used to store the physical backup files:

It is important to note that the backupContentType field must be set to Physical when restoring from a physical backup. This ensures that the operator uses the correct restoration method.

To restore a VolumeSnapshot, you can provide a reference to a specific VolumeSnapshot resource in the spec.bootstrapFrom field:

Target recovery time

By default, the operator will match the closest backup available to the current time. You can specify a different target recovery time by using the targetRecoveryTime field in the PhysicalBackup resource. This lets you define the exact point in time you want to restore to:

Only backups strictly before or at targetRecoveryTime will be matched.

Timeout

By default, both backups based on mariadb-backup and VolumeSnapshots will have a timeout of 1 hour. You can change this timeout by using the timeout field in the PhysicalBackup resource:

When timed out, the operator will delete the Jobs or VolumeSnapshots resources associated with the PhysicalBackup resource. The operator will create new Jobs or VolumeSnapshots to retry the backup operation if the PhysicalBackup resource is still scheduled.

Log level

When taking backups based on mariadb-backup, you can specify the log level to be used by the mariadb-enterprise-operator container using the logLevel field in the PhysicalBackup resource:

Extra options

When taking backups based on mariadb-backup, you can specify extra options to be passed to the mariadb-backup command using the args field in the PhysicalBackup resource:

Refer to the for a list of available options.

Azure Blob Storage Credentials

Credentials for accessing Azure Blob Storage can be provided via the azureBlob key in the storage field of the PhysicalBackup resource. The credentials are provided as a reference to a Kubernetes Secret:

Alternatively, you may choose to omit the storageAccountKey and storageAccountName if you are using

S3 credentials

Credentials for accessing an S3 compatible storage can be provided via the s3 key in the storage field of the PhysicalBackup resource. The credentials can be provided as a reference to a Kubernetes Secret:

Alternatively, if you are running in EKS, you can use dynamic credentials from an EKS Service Account using EKS Pod Identity or IRSA:

By leaving out the accessKeyIdSecretKeyRef and secretAccessKeySecretKeyRef credentials and pointing to the correct serviceAccountName, the backup Job will use the dynamic credentials from EKS.

Staging area

S3 backups based on mariadb-backup are the only scenario that requires a staging area.

When using S3 storage for backups, a staging area is used for keeping the external backups while they are being processed. By default, this staging area is an emptyDir volume, which means that the backups are temporarily stored in the node's local storage where the PhysicalBackup Job is scheduled. In production environments, large backups may lead to issues if the node doesn't have sufficient space, potentially causing the backup/restore process to fail.

Additionally, when restoring these backups, the operator will pull the backup files from S3, uncompress them if needded, and restore them to each of the MariaDB Pods in the cluster individually. To save network bandwidth and compute resources, a staging area is used to keep the uncompressed backup files after they have been restored to the first MariaDB Pod. This allows the operator to restore the same backup to the rest of MariaDB Pods seamlessly, without needing to pull and uncompress the backup again.

To configure the staging area, you can use the stagingStorage field in the PhysicalBackup resource:

Similarly, you may also use a staging area when , in the MariaDB resource:

In the examples above, a PVC with the default StorageClass will be provisioned to be used as staging area.

`VolumeSnapshots`

Before using this feature, ensure that you meet the following prerequisites :

and its CRs are installed in the cluster.

The operator is capable of creating of the PVCs used by the MariaDB Pods. This allows you to create point-in-time snapshots of your data in a Kubernetes-native way, leveraging the capabilities of your storage provider.

Most of the fields described in this documentation apply to VolumeSnapshots, including scheduling, retention policy, and compression. The main difference with the mariadb-backup based backups is that the operator will not create a Job to perform the backup, but instead it will create a VolumeSnapshot resource directly.

In order to create consistent, point-in-time snapshots of the MariaDB data, the operator will perform the following steps:

Execute a BACKUP STAGE START statement followed by BACKUP STAGE BLOCK_COMMIT in one of the secondary Pods.
Create a VolumeSnapshot resource of the data PVC mounted by the MariaDB secondary Pod.

This backup process is described in the and is designed to be .

Non-blocking physical backups

Both for mariadb-backup and VolumeSnapshot , the enterprise operator performs non-blocking physical backups by leveraging the . This implies that the backups are taken without long read locks, enabling consistent, production-grade backups with minimal impact on running workloads, ideal for high-availability and performance-sensitive environments.

Important considerations and limitations

Root credentials

Restore `Job`

When using backups based on mariadb-backup, restoring and uncompressing large backups can consume significant compute resources and may cause restoration Jobs to become stuck due to insufficient resources. To prevent this, you can define the compute resources allocated to the Job:

`ReadWriteOncePod` access mode partially supported

When using backups based on mariadb-backup, the data PVC used by the MariaDB Pod cannot use the access mode, as it needs to be mounted at the same time by both the MariaDB Pod and the PhysicalBackup Job. In this case, please use either the ReadWriteOnce or ReadWriteMany access modes instead.

Alternatively, if you want to keep using the ReadWriteOncePod access mode, you must use backups based on VolumeSnapshots, which do not require creating a Job to perform the backup and therefore avoid the volume sharing limitation.

`PhysicalBackup` `Jobs` scheduling

PhysicalBackup Jobs must mount the data PVC used by one of the secondary MariaDB Pods. To avoid scheduling issues caused by the commonly used ReadWriteOnce access mode, the operator schedules backup Jobs on the same node as MariaDB by default.

If you prefer to disable this behavior and allow Jobs to run on any node, you can set podAffinity=false:

This configuration may be suitable when using the ReadWriteMany access mode, which allows multiple Pods across different nodes to mount the volume simultaneously.

Troubleshooting

Custom columns are used to display the status of the PhysicalBackup resource:

To get a higher level of detail, you can also check the status field directly:

You may also check the related events for the PhysicalBackup resource to see if there are any issues:

Common errors

`mariadb-backup` log copy incomplete: consider increasing `innodb_log_file_size`

In some situations, when using the mariadb-backup strategy, you may encounter the following error in the backup Job logs:

This can be addressed by increasing the innodb_log_file_size in the MariaDB configuration. You can do this by adding the following to your MariaDB resource:

Refer to for further details on this issue.

`mariadb-backup` `Job` fails to start because the `Pod` cannot mount `MariaDB` PVC created with `StorageClass` provider

Without explicitly enabled the ReadWriteOnce access mode is treated as ReadWriteOncePod.

Refer to for further details on this issue.

Helm

Official Helm install MariaDB Enterprise Operator: mariadb-enterprise-operator-crds chart, values.yaml imagePullSecrets, --version, helm upgrade/uninstall.

Helm is the preferred way to install MariaDB Enterprise Kubernetes Operator in Kubernetes clusters. This documentation aims to provide guidance on how to manage the installation and upgrades of both the CRDs and the operator via Helm charts.

Prerequisites

Configure your customer credentials as described in the documentation to be able to pull images.

Charts

MariaDB Enterprise Kubernetes Operator is split into two different helm charts for better convenience:

mariadb-enterprise-operator-crds: Bundles the required by the operator.
mariadb-enterprise-operator: Contains all the template manifests required to install the operator. Refer to the section for detailed information about the supported values.

Control-plane

The operator extends the Kubernetes control plane and consists of the following components deployed via Helm:

operator: The mariadb-enterprise-operator itself that performs the CRD reconciliation.
webhook: The Kubernetes control-plane delegates CRD validations to this HTTP server. Kubernetes requires TLS to communicate with the webhook server.

Installing CRDs

Helm has certain . To address this, we are providing the CRDs in a separate chart, . This allows us to manage the installation and updates of the CRDs independently from the operator. For example, you can uninstall the operator without impacting your existing MariaDB CRDs.

CRDs can be installed in your cluster by running the following commands

Installing the operator

The first step is to prepare a values.yaml file to specify your previously configured :

Then, you can proceed to install the operator:

If you have the and already installed in your cluster, it is recommended to leverage them to scrape the operator metrics and provision the webhook certificate respectively:

Refer to the section for detailed information about the supported values.

Long-Term Support Versions

MariaDB Enterprise Kubernetes Operator provides stable Long-Term Support (LTS) versions.

Version

Supported Kubernetes Versions

Description

If you instead wish to install a specific LTS release, you can do:

Where: --version "25.10.*" installs the most recent available release within the 25.10 series.

Deployment modes

The following deployment modes are supported:

Cluster-wide

The operator watches CRDs in all namespaces and requires cluster-wide RBAC permissions to operate. This is the default deployment mode, enabled through the default configuration values:

Single namespace

By setting currentNamespaceOnly=true, the operator will only watch CRDs within the namespace it is deployed in, and the RBAC permissions will be restricted to that namespace as well:

Updates

Make sure you read and understand the before proceeding to update the operator.

To install a version instead, replace <new-version> with your desired LTS release. For example: --version "25.10.*" will automatically install the latest available patch within that LTS series.

The first step is upgrading the CRDs that the operator depends on:

Once updated, you may proceed to upgrade the operator:

Whenever a new version of the operator is released, an upgrade guide is linked in the if additional upgrade steps are required. Be sure to review the and follow the version-specific upgrade guides accordingly.

Operator high availability

The operator can run in high availability mode to prevent downtime during updates and ensure continuous reconciliation of your CRs, even if the node where the operator runs goes down. To achieve this, you need:

Multiple replicas
Configure Pod anti-affinity
Configure PodDisruptionBudgets

You can achieve this by providing the following values to the helm chart:

You may similarly configure the webhook and cert-controller components to run in high availability mode by providing the same values to their respective sections. Refer to the for detailed information.

Uninstalling

Uninstalling the mariadb-enterprise-operator-crds Helm chart will remove the CRDs and their associated resources, resulting in downtime.

First, uninstall the mariadb-enterprise-operator Helm chart. This action will not delete your CRDs, so your operands (i.e. MariaDB and MaxScale) will continue to run without the operator's reconciliation.

At this point, if you also want to delete CRDs and the operands running in your cluster, you may proceed to uninstall the mariadb-enterprise-operator-crds Helm chart:

Operator helm values

Key

Type

Default

Description

TLS

Guide to securing database traffic with TLS/SSL certificates, covering internal communication between nodes and external client connections.

MariaDB Enterprise Kubernetes Operator supports issuing, configuring and rotating TLS certificates for both your MariaDB and MaxScale resources. It aims to be secure by default; for this reason, TLS certificates are issued and configured by the operator as a default behaviour.

`MariaDB` configuration

This section covers TLS configuration in new instances. If you are looking to migrate an existing instance to use TLS, please refer to instead.

TLS can be configured in MariaDB resources by setting tls.enabled=true:

As a result, the operator will generate a Certificate Authority (CA) and use it to issue the leaf certificates mounted by the instance. It is important to note that the TLS connections are not enforced in this case i.e. both TLS and non-TLS connections will be accepted. This is the default behaviour when no tls field is specified.

If you want to enforce TLS connections, you can set tls.required=true:

This approach ensures that any unencrypted connection will fail, effectively enforcing security best practices.

If you want to fully opt-out from TLS, you can set tls.enabled=false:

This will disable certificate issuance, resulting in all connections being unencrypted.

Refer to further sections for a more advanced TLS configuration.

`MaxScale` configuration

This section covers TLS configuration in new instances. If you are looking to migrate an existing instance to use TLS, please refer to instead.

TLS will be automatically enabled in MaxScale when the referred MariaDB (via mariaDbRef) has TLS enabled and enforced. Alternatively, you can explicitly enable TLS by setting tls.enabled=true:

As a result, the operator will generate a Certificate Authority (CA) and use it to issue the leaf certificates mounted by the instance. It is important to note that, unlike MariaDB, MaxScale does not support TLS and non-TLS connections simultaneously (see ). Therefore, TLS connections will be enforced in this case i.e. unencrypted connections will fail, ensuring security best practises.

If you want to fully opt-out from TLS, you can set tls.enabled=false. This should only be done when MariaDB TLS is not enforced or disabled:

This will disable certificate issuance, resulting in all connections being unencrypted.

Refer to further sections for a more advanced TLS configuration.

`MariaDB` certificate specification

The MariaDB TLS setup consists of the following certificates:

Certificate Authority (CA) keypair to issue the server certificate.
Server leaf certificate used to encrypt server connections.
Certificate Authority (CA) keypair to issue the client certificate.

As a default behaviour, the operator generates a single CA to be used for issuing both the server and client certificates, but the user can decide to use dedicated CAs for each case. Root CAs, and in some cases, are supported, see for further detail.

The server certificate contains the following Subject Alternative Names (SANs):

<mariadb-name>.<namespace>.svc.<cluster-name>
<mariadb-name>.<namespace>.svc
<mariadb-name>.<namespace>

Whereas the client certificate is only valid for the <mariadb-name>-client SAN.

`MaxScale` certificate specification

The MaxScale TLS setup consists of the following certificates:

Certificate Authority (CA) keypair to issue the admin certificate.
Admin leaf certificate used to encrypt the administrative REST API and GUI.
Certificate Authority (CA) keypair to issue the listener certificate.

As a default behaviour, the operator generates a single CA to be used for issuing both the admin and the listener certificates, but the user can decide to use dedicated CAs for each case. Client certificate and CA bundle configured in the referred MariaDB are used as server certificates by default, but the user is able to provide its own certificates. Root CAs, and in some cases, are supported, see for further detail.

Both the admin and listener certificates contain the following Subject Alternative Names (SANs):

<maxscale-name>.<namespace>.svc.<clusername>
<maxscale-name>.<namespace>.svc
<maxscale-name>.<namespace>

For details about the server certificate, see .

CA bundle

As you could appreciate in and , the TLS setup involves multiple CAs. In order to establish trust in a more convenient way, the operator groups the CAs together in a CA bundle that will need to be specified when . Every MariaDB and MaxScale resources have a dedicated bundle of its own available in a Secret named <instance-name>-ca-bundle.

These trust bundles contain non expired CAs needed to connect to the instances. New CAs are automatically added to the bundle after , whilst old CAs are removed after they expire. It is important to note that both the new and old CAs remain in the bundle for a while to ensure a smooth update when the new certificates are issued by the new CA.

Issue certificates with the operator

By setting tls.enabled=true, the operator will generate a root CA for each instance, which will be used to issue the certificates described in the and sections:

To establish trust with the instances, the CA's public key will be added to the . If you need a different trust chain, please refer to the section.

The advantage of this approach is that the operator fully manages the Secrets that contain the certificates without depending on any third party dependency. Also, since the operator fully controls the renewal process, it is able to pause a leaf certificate renewal if the CA is being updated at that moment, as described in the section.

Issue certificates with cert-manager

must be previously installed in the cluster in order to use this feature.

cert-manager is the de-facto standard for managing certificates in Kubernetes. It is a Kubernetes native certificate management controller that allows you to automatically provision, manage and renew certificates. It supports multiple (in-cluster, Hashicorp Vault...) which are configured as Issuer or ClusterIssuer resources.

As an example, we are going to setup an in-cluster root CA ClusterIssuer:

Then, you can reference the ClusterIssuer in the MariaDB and MaxScale resources:

The operator will create cert-manager's for each certificate, and will mount the resulting in the instances. These Secrets containing the certificates will be managed by cert-manager as well as its renewal process.

To establish trust with the instances, the in the Secret will be added to the . If you need a different trust chain, please refer to the section.

The advantage of this approach is that you can use any of the , such as the in-cluster CA or HashiCorp Vault, and potentially reuse the same Issuer/ClusterIssuer with multiple instances.

Provide your own certificates

Providing your own certificates is as simple as creating the Secrets with the appropriate structure and referencing them in the MariaDB and MaxScale resources. The certificates must be compliant with the and .

The CA certificate must be provided as a Secret with the following structure:

The ca.key field is only required if you want to the operator to automatically re-issue certificates with this CA, see for further detail. In other words, if only ca.crt is provided, the operator will trust this CA by adding it to the , but no certificates will be issued with it, the user will responsible for upating the certificate Secret manually with renewed certificates.

The enterprise.mariadb.com/watch label is required only if you want the operator to automatically trigger an update when the CA is renewed, see for more detail.

The leaf certificate must match the previous CA's public key, and it should provided as a with the following structure:

The enterprise.mariadb.com/watch label is required only if you want the operator to automatically trigger an update when the certificate is renewed, see for more detail.

Once the certificate Secrets are available in the cluster, you can create the MariaDB and MaxScale resources referencing them:

Bring your own CA

If you already have a CA setup outside of Kubernetes, you can use it with the operator by providing the CA certificate as a Secret with the following structure:

Just by providing a reference to this Secret, the operator will use it to issue leaf certificates instead of generating a new CA:

Intermediate CAs

Intermediate CAs are supported by the operator with . Leaf certificates issued by the intermediate CAs are slightly different, and include the intermediate CA public key as part of the certificate, in the following order: Leaf certificate -> Intermediate CA. This is a common practise to easily establish trust in complex PKI setups, where multiple CA are involved.

Many applications support this Leaf certificate -> Intermediate CA structure as a valid leaf certificate, and are able to establish trust with the intermediate CA. Normally, the intermediate CA will not be directly trusted, but used as a path to the root CA, which should be trusted by the application. If not trusted already, you can add the root CA to the by using a .

Custom trust

You are able to provide a set of CA public keys to be added to the by creating a Secret with the following structure:

And referencing it in the MariaDB and MaxScale resources, for instance:

This is specially useful when issuing certificates with an intermediate CA, see section for further detail.

Distributing trust

Distributing the to your application namespace is out of the scope of this operator, the bundles will remain in the same namespace as the MariaDB and MaxScale instances.

If your application is in a different namespace, you can copy the CA bundle to the application namespace. Projects like can help you to automate this process and continously reconcile bundle changes.

TLS version configuration

You may configure the supported TLS versions in MariaDB by setting:

If not specified, the MariaDB's default TLS versions will be used. See .

Regarding MaxScale, you can also configure the supported TLS versions, both for the Admin REST API and MariaDB servers:

If not specified, the MaxScale's default TLS versions will be used. See MaxScale docs:

Certificate lifetime configuration

By default, CA certificates are valid for 3 years, while leaf certificates have a validity of 3 months. This lifetime can be customized in both MariaDB and MaxScale resources through the certificate configuration fields. For example:

When issuing certificates with cert-manager, you can specify the certificate configuration field alongside the issuer reference:

Private key configuration

By default, private keys are generated with the ECDSA algorithm and a size of 256. You can customize the private key configuration in both MariaDB and MaxScale resources through the certificate configuration fields. For example:

When issuing certificates with cert-manager, you can specify the private key configuration field alongside the issuer reference:

The following set of algorithms and sizes are supported:

Algorithm

Key Sizes

CA renewal

Depending on the setup, CAs can be managed and renewed by either MariaDB Enterprise Kubernetes Operator or cert-manager.

When managed by the operator, CAs have a lifetime of 3 years by default, and are marked for renewal after 66% of its lifetime has passed i.e. ~2 years. After being renewed, the operator will trigger an update of the instances to include the new CA in the bundle.

When managed by cert-manager, the renewal process is fully controlled by cert-manager, but the operator will also update the CA bundle after the CA is renewed.

You may choose any of the available to control the instance update process.

Certificate renewal

Depending on the setup, certificates can be managed and renewed by the operator or cert-manager. In either case, certificates have a lifetime of 90 days by default, and marked for renewal after 66% of its lifetime has passed i.e. ~60 days.

When the , the operator is able to pause a leaf certificate renewal if the CA is being updated at that same moment. This approach ensures a smooth update by avoiding the simultaneous rollout of the new CA and its associated certificates. Rolling them out together could be problematic, as all Pods need to trust the new CA before its issued certificates can be utilized.

When the , the renewal process is fully managed by cert-manager, and the operator will not interfere with it. The operator will only update the instances whenever the CA or the certificates get renewed.

You may choose any of the available to control the instance update process.

Certificate status

To have a high level picture of the certificates status, you can check the status.tls field of the MariaDB and MaxScale resources:

TLS requirements for `Users`

You are able to declaratively manage access to your MariaDB instances by creating . In particular, when TLS is enabled, you can provide additional requirements for the user when connecting over TLS.

For instance, if you want to require a valid x509 certificate for the user to be able o connect:

In order to restrict which subject the user certificate should have and/or require a particular issuer, you may set:

When any of these TLS requirements are not met, the user will not be able to connect to the instance.

See and the for further detail.

Galera Enterprise SSL modes

MariaDB Enterprise Cluster (Galera) supports multiple SSL modes to secure the communication between the nodes. For configuring the SSL enforcement level on the server i.e. WSREP, you can set:

The following values are supported: SERVER_X509, SERVER and PROVIDER. Refer to the for further detail about these modes.

You may also configure the SSL enforcement level used during Snapshot State Transfers(SST) by setting:

The following values are supported: VERIFY_IDENTITY, VERIFY, REQUIRED and DISABLED. Refer to the for further detail about these modes.

If you are willing to increase the enforcement level in an existing instance, make sure you follow the migration guide provided in the section.

Secure application connections with TLS

In this guide, we will configure TLS for an application running in the app namespace to connect with MariaDB and MaxScale instances deployed in the default namespace. We assume that the following resources are already present in the default namespace with TLS enabled:

The first step is to create a User resource and grant the necessary permissions:

The app user will be able to connect to the MariaDB instance from the app namespace by providing a certificate with subject mariadb-galera-client and issued by the mariadb-galera-ca CA.

With the permissions in place, the next step is to prepare the certificates required for the application to connect:

CA Bundle: The trust bundle for MariaDB and MaxScale is available as a Secret named <instance-name>-ca-bundle in the default namespace. For more details, refer to the sections on and .
Client Certificate: MariaDB

In this example, we assume that the following Secrets are available in the app namespace:

mariadb-bundle: CA bundle for the MariaDB and MaxScale instances.
mariadb-galera-client-cert: Client certificate required to connect to the MariaDB instance.

With these Secrets in place, we can proceed to define our application:

The application will connect to the MariaDB instance using the app user, and will execute a simple query to check the connection status. The --ssl-ca, --ssl-cert, --ssl-key and --ssl-verify-server-cert flags are used to provide the CA bundle, client certificate and key, and to verify the server certificate respectively.

If the connection is successful, the output should be:

You can also point the application to the MaxScale instance by updating the host to maxscale-galera.default.svc.cluster.local:

If successful, the expected output is:

Test TLS certificates with `Connections`

In order to validate your TLS setup, and to ensure that you TLS certificates are correctly issued and configured, you can use the Connection resource to test the connection to both your MariaDB and MaxScale instances:

If successful, the Connection resource will be in a Ready state, which means that your TLS setup is correctly configured:

This could be specially useful when and issuing certificates for your applications.

Limitations

Galera and intermediate CAs

Leaf certificates issued by are not supported by Galera, see . This implies that a root CA must be used to issue the MariaDB certificates.

This doesn't affect MaxScale, as it is able to establish trust with intermediate CAs, and therefore you can still issue your application facing certificates (MaxScale listeners) with an intermediate CA, giving you more flexibility in your PKI setup.

MaxScale

Unlike MariaDB, TLS and non-TLS connections on the same port are not supported simultaneously.
TLS encryption must be enabled for listeners when they are created. For servers, the TLS can be enabled after creation but it cannot be disabled or altered.

Refer to the for further details.

API Reference

Technical documentation of the Custom Resource Definitions (CRDs) and API fields used to configure the MariaDB Enterprise Kubernetes Operator.

Packages

enterprise.mariadb.com/v1alpha1

enterprise.mariadb.com/v1alpha1

Underlying type: string

CleanupPolicy defines the behavior for cleaning up a resource.

Appears in:

Field

Description

Underlying type: string

CooperativeMonitoring enables coordination between multiple MaxScale instances running monitors. See: https://mariadb.com/docs/server/architecture/components/maxscale/monitors/mariadbmon/use-cooperative-locking-ha-maxscale-mariadb-monitor/

Appears in:

Field

Description

CronJobTemplate

CronJobTemplate defines parameters for configuring CronJob objects.

Appears in:

Field

Description

Default

Validation

Grant is the Schema for the grants API. It is used to define grants as if you were running a 'GRANT' statement.

Field

Description

Default

Validation

GrantSpec

GrantSpec defines the desired state of Grant

Appears in:

Field

Description

Default

Validation

MariaDB is the Schema for the mariadbs API. It is used to define MariaDB clusters.

Field

Description

Default

Validation

MariaDBRef

MariaDBRef is a reference to a MariaDB object.

Appears in:

Field

Description

Default

Validation

MariaDBSpec

MariaDBSpec defines the desired state of MariaDB

Appears in:

Field

Description

Default

Validation

MariadbMetrics

MariadbMetrics defines the metrics for a MariaDB.

Appears in:

Field

Description

Default

Validation

Appears in:

Field

Description

Default

Validation

Appears in:

Field

Description

Default

Validation

Refer to the Kubernetes docs: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#resourcerequirements-v1-core.

Appears in:

Appears in:

Field

Description

Default

Validation

SQLTemplate

SQLTemplate defines a template to customize SQL objects.

Appears in:

Field

Description

Default

Validation

SSECConfig

SSECConfig defines the configuration for SSE-C (Server-Side Encryption with Customer-Provided Keys).

Appears in:

Field

Description

Default

Validation

Underlying type: string

ServiceRouter defines the type of service router.

Appears in:

Field

Description

ServiceTemplate

ServiceTemplate defines a template to customize Service objects.

Appears in:

Field

Description

Default

Validation

Appears in:

Field

Description

Default

Validation

TLSRequirements

TLSRequirements specifies TLS requirements for the user to connect. See: https://mariadb.com/kb/en/securing-connections-for-client-and-server/#requiring-tls.

Appears in:

Field

Description

Default

Validation

TopologySpreadConstraint

Refer to the Kubernetes docs: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#topologyspreadconstraint-v1-core.

Appears in:

Field

Description

Default

Validation

TypedLocalObjectReference

TypedLocalObjectReference is a reference to a specific object type.

Appears in:

Field

Description

Default

Validation

UpdateStrategy

UpdateStrategy defines how a MariaDB resource is updated.

Appears in:

Field

Description

Default

Validation

UpdateType

Underlying type: string

UpdateType defines the type of update for a MariaDB resource.

Appears in:

Field

Description

Underlying type: string

WaitPoint defines whether the transaction should wait for ACK before committing to the storage engine. More info: https://mariadb.com/kb/en/semisynchronous-replication/#rpl_semi_sync_master_wait_point.

Appears in:

Field

Description

WeightedPodAffinityTerm

Refer to the Kubernetes docs: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#weightedpodaffinityterm-v1-core.

Appears in:

Field

Description

Default

Validation

Tools

Tools

hashtagMariaDB Enterprise Manager

MariaDB Enterprise Manager

hashtagKey Capabilities at a Glance

hashtagAdvanced Monitoring

hashtagIntegration with Other Observability Solutions

hashtagCentralized Management

hashtagWorkspace

hashtagEnterprise Security

Architecture Overview

hashtagEnterprise Manager Server

hashtagEnterprise Manager Agent

hashtagNetworking Requirements

Administration

Deployment

hashtagInstalling the Enterprise Manager Server

Installing MariaDB Enterprise Manager

hashtagStandard Installation

hashtagEnterprise Manager Server Air-Gapped Installation

Agent Installation

Add Multiple MaxScale Monitors

hashtagAdding an Additional Monitor

hashtagAdd a new monitored logical database

hashtagChanging the Monitor for an Existing Database

hashtagOpen the database edit menu

SSO to MaxScale (Single Sign-On)

hashtagAccessing the MaxScale GUI

Network and Firewall Requirements

Backup & Restore of Enterprise Manager

hashtagBacking up Enterprise Manager Server

hashtagRestoring Enterprise Manager Server

Change Hostname or IP Address

hashtagConnect to your server

hashtagNavigate to the directory

hashtagEdit the .env file

hashtagSave the file

hashtagRestart the services

Usage

Monitoring

Dashboards

Alerts and Notifications

hashtagHow It Works: The Alerting Flow

SMTP Server Configuration

hashtag

MariaDB Enterprise Kubernetes Operator

Installation

Topologies

Backup and Restore

25.08 version update guide

26.03 version update guide

Suspend Reconciliation

hashtagSuspended state

Plugins

Supported Docker Images

Examples Catalog

Migrations

Migrate Embedded MaxScale To MaxScale Resource

MariaDB Enterprise MCP Server

Overview

Token Management

hashtagToken Generation

Example

hashtag

Usage Examples

hashtagStandard SQL Query

hashtagCreate Vector Store

hashtagInsert Documents into Vector Store

hashtagSemantic Search

hashtagRAG Generation

Service Management

hashtagStarting the Service

hashtagViewing Logs

Administration

Usage

Dashboards

Monitoring

Architecture Overview

hashtagEnterprise Manager Server

hashtagEnterprise Manager Agent

MariaDB Enterprise Manager

Key Capabilities at a Glance

Advanced Monitoring

Integration with Other Observability Solutions

Centralized Management

Workspace

Enterprise Security

Enterprise Manager Server

Enterprise Manager Agent

Networking Requirements

Installing the Enterprise Manager Server

Standard Installation

Enterprise Manager Server Air-Gapped Installation

Adding an Additional Monitor

Add a new monitored logical database

Changing the Monitor for an Existing Database

Open the database edit menu

Accessing the MaxScale GUI

Backing up Enterprise Manager Server

Restoring Enterprise Manager Server

Connect to your server

Navigate to the directory

Edit the `.env` file

Save the file

Restart the services

How It Works: The Alerting Flow

Suspended state

Token Generation

Standard SQL Query

Create Vector Store

Insert Documents into Vector Store

Semantic Search

RAG Generation

Starting the Service

Viewing Logs

Enterprise Manager Server

Enterprise Manager Agent

Networking Requirements

Installing the Enterprise Manager Server

Accessing the MaxScale GUI

MariaDB Enterprise Manager

MariaDB Enterprise Operator

MariaDB Enterprise MCP Server

MariaDB AI RAG

Installing Enterprise Manager Agents

Quick start

Configuring SSO in `maxscale.cnf`

Adding an Additional Monitor

Add a new monitored logical database

Changing the Monitor for an Existing Database

Open the database edit menu

Standard Installation

Enterprise Manager Server Air-Gapped Installation

Connect to your server

Navigate to the directory

Edit the `.env` file

Save the file

Restart the services

Backing up Enterprise Manager Server

Restoring Enterprise Manager Server

Starting the Service

Viewing Logs

Standard SQL Query

Create Vector Store

Insert Documents into Vector Store

Semantic Search

RAG Generation

Key Capabilities at a Glance

Advanced Monitoring

Integration with Other Observability Solutions

Centralized Management

Workspace

Enterprise Security

How It Works: The Alerting Flow

Suspended state

Token Generation