1 of 44

MariaDB Enterprise Kubernetes Operator

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

Introduction

General introduction to the Operator's capabilities, benefits for database operations, and its role in managing MariaDB within Kubernetes clusters.

MariaDB Enterprise Kubernetes Operator provides a seamless way to run and operate containerized versions of MariaDB Enterprise Server and MaxScale on Kubernetes, allowing you to leverage Kubernetes orchestration and automation capabilities. This document outlines the features and advantages of using Kubernetes and the MariaDB Enterprise Kubernetes Operator to streamline the deployment and management of MariaDB and MaxScale instances.

What is Kubernetes?

Kubernetes is more than just a container orchestrator; it is a comprehensive platform that provides APIs for managing both applications and the underlying infrastructure. It automates key aspects of container management, including deployment, scaling, and monitoring, while also handling essential infrastructure needs such as networking and storage. By unifying the management of applications and infrastructure, Kubernetes simplifies operations and improves efficiency in cloud-native environments.

Why Kubernetes?

Kubernetes brings several key benefits to the table when managing applications in a containerized environment:

Standardization: Kubernetes relies on standard APIs for managing applications and infrastructure, making it easier to ensure uniformity across various environments. It acts as a common denominator across cloud providers and on-premises.
Automation: Kubernetes APIs encapsulate operational best practises, minimizing the need for manual intervention and improving the efficiency of operations.
Cost Effectiveness: Having an standardized way to manage infrastructure across cloud providers and automation to streamline operations, Kubernetes helps reducing the infrastructure and operational costs.

What is a Kubernetes Operator?

Kubernetes has been designed with flexibility in mind, allowing developers to extend its capabilities through custom resources and operators.

In particular, MariaDB Enterprise Kubernetes Operator, watches the desired state defined by users via MariaDB and MaxScale resources, and takes actions to ensure that the actual state of the system matches the desired state. This includes managing compute, storage and network resources, as well as the full lifecycle of the MariaDB and MaxScale instances. Whenever the desired state changes or the underlying infrastructure is modified, the Operator takes the necessary actions to reconcile the actual state with the desired state.

Operational expertise is baked into the MariaDB and MaxScale APIs and seamlessly managed by the Operator. This includes automated backups, restores, upgrades, monitoring, and other critical lifecycle tasks, ensuring reliability in Day 2 operations.

MariaDB Enterprise Kubernetes Operator Features

Provision and Configure MariaDB and MaxScale Declaratively: Define MariaDB Enterprise Server and MaxScale clusters in YAML manifests and deploy them with ease in Kubernetes.
Multiple Topologies supported:

Customer access to docker.mariadb.com

Instructions for customers to authenticate and gain access to the private MariaDB Enterprise Docker registry to pull protected container images.

This documentation aims to provide guidance on how to configure access to docker.mariadb.com in your MariaDB Enterprise Kubernetes Operator resources.

Customer credentials

MariaDB Corporation requires customers to authenticate when logging in to the . A Customer Download Token must be provided as the password. Customer Download Tokens are available through the MariaDB Customer Portal. To retrieve the customer download token for your account:

Installation

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

Quickstart

A fast-track guide to deploying your first MariaDB Enterprise instance using the Operator, from initial configuration to a running database.

This guide aims to provide a quick way to get started with the MariaDB Enterprise Kubernetes Operator for Kubernetes. It will walk you through the process of deploying a MariaDB Enterprise Cluster and MaxScale via the MariaDB and MaxScale CRs (Custom Resources) respectively.

Before you begin, ensure you meet the following prerequisites:

Configure your customer access for docker.mariadb.com

The first step will be configuring a Secret with the credentials used by the MariaDB CR:

Next, we will deploy a MariaDB Enterprise Cluster (Galera) using the following CR:

Let's break it down:

rootPasswordSecretKeyRef: A reference to a Secret containing the root password.
imagePullSecrets: The name of the Secret containing the customer credentials to pull the MariaDB Enterprise Server image.

After applying the CR, we can observe the MariaDB Pods being created:

Now, let's deploy a MaxScale CR:

Again, let's break it down:

imagePullSecrets: The name of the Secret containing the customer credentials to pull the MaxScale image.
mariaDbRef: A reference to the MariaDB CR that we want to connect to.

After applying the CR, we can observe the MaxScale Pods being created, and that both the MariaDB and MaxScale CRs will become ready eventually:

To conclude, let's connect to the MariaDB Enterprise Cluster through MaxScale using the initial user and database we initially defined in the MariaDB CR:

You have successfully deployed a MariaDB Enterprise Cluster with MaxScale in Kubernetes using the MariaDB Enterprise Kubernetes Operator!

Refer to the , the and the for further detail.

Topologies

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

Standalone

This guide covers configuring standalone MariaDB Enterprise Server with minimal settings for development. Avoid using it in production due to risks like single point of failure and necessary downtime

This operator allows you to configure standalone MariaDB Enterprise Server instances. To achieve this, you can either omit the replicas field or set it to 1:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb
spec:
  rootPasswordSecretKeyRef:
    name: mariadb
    key: password

  replicas: 1

  port: 3306

  storage:
    size: 1Gi

  myCnf: |
    [mariadb]
    bind-address=*
    default_storage_engine=InnoDB
    binlog_format=row
    innodb_autoinc_lock_mode=2
    innodb_buffer_pool_size=800M
    max_allowed_packet=256M

  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      memory: 1Gi

  metrics:
    enabled: true

Whilst this can be useful for development and testing, it is not recommended for production use because of the following reasons:

Single point of failure
Upgrades require downtime
Only vertical scaling is possible

For achieving high availability, we recommend deploying a highly available topology as described in the .

Data Plane

In order to effectively manage the full lifecycle of both replication and Galera topologies, the operator relies on a set of components that run alonside the MariaDB instances and expose APIs for remote management. These components are collectively referred to as the "data-plane".

Components

The mariadb-enterprise-operator data-plane components are implemented as lightweight containers that run alongside the MariaDB instances within the same Pod. These components are available in the operator image. More preciselly, they are subcommands of the CLI shipped as binary inside the image.

Init container

The init container is responsible for dynamically generating the Pod-specifc configuration files before the MariaDB container starts. It also plays a crucial role in the MariaDB container startup, enabling replica recovery for the replication topolology and guaranteeing ordered deployment of Pods for the Galera topology.

Agent sidecar

The agent sidecar provides an HTTP API that enables the operator to remotely manage MariaDB instances. Through this API, the operator is able to remotely operate the data directory and handle the instance lifecycle, including operations such as replica recovery for replication and cluster recovery for the Galera topology. It supports methods to ensure that only the operator is able to call the agent API.

Since it has access to the data directory, it is also responsible for periodically archiving binary logs to be used for .

Agent auth methods

As previously mentioned, the agent exposes an API to remotely manage the replication and Galera clusters. The following authentication methods are supported to ensure that only the operator is able to call the agent:

`ServiceAccount` based authentication

The operator uses its ServiceAccount token as a mean of authentication for communicating with the agent, which subsequently verifies the token by creating a . This is the default authentication method and will be automatically applied by setting:

This Kubernetes-native authentication mechanism eliminates the need for the operator to manage credentials, as it relies entirely on Kubernetes for this purpose. However, the drawback is that the agent requires cluster-wide permissions to impersonate the ClusterRole and to create , which are cluster-scoped objects.

Basic authentication

As an alternative, the agent also supports basic authentication:

Unlike the , the operator needs to explicitly generate credentials to authenticate. The advantage of this approach is that it is entirely decoupled from Kubernetes and it does not require cluster-wide permissions on the Kubernetes API.

Updates

Please refer to the updates documentation for more information about .

Backup and Restore

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

CSI Specific Configuration

blob-csi-driver (Azure Blob Storage)

This section outlines a recommended StorageClass configuration for the that resolves common mounting and list operation issues encountered in Kubernetes environments.

The following is recommended when working with Azure Blob Storage (ABS).

Next, when defining your PhysicalBackup

Storage

This operator gives you flexibility to define the storage that will back the /var/lib/mysql data directory mounted by MariaDB.

Configuration

The simplest way to configure storage for your MariaDB is:

This will make use of the default StorageClass available in your cluster, but you can also provide a different one:

Under the scenes, the operator is configuring the StatefulSet's volumeClaimTemplate property, which you are also able to provide yourself:

Volume resize

The StorageClass used for volume resizing must define allowVolumeExpansion = true.

It is possible to resize your storage after having provisioned a MariaDB. We need to distinguish between:

PVCs already in use.
StatefulSet storage size, which will be used when provisioning new replicas.

It is important to note that, for the first case, your StorageClass must support volume expansion by declaring the allowVolumeExpansion = true. In such case, it will be safe to expand the storage by increasing the size and setting resizeInUseVolumes = true:

Depending on your storage provider, this operation might take a while, and you can decide to wait for this operation before the MariaDB becomes ready by setting waitForVolumeResize = true. Operations such as and will not be performed if the MariaDB resource is not ready.

Ephemeral storage

Provisioning standalone MariaDB instances with ephemeral storage can be done by setting ephemeral = true:

This may be useful for multiple use cases, like provisioning ephemeral MariaDBs for the integration tests of your CI.

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.

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:

helm uninstall mariadb-enterprise-operator

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

Upgrade mariadb-enterprise-operator-crds to 25.8.0:

The Galera data-plane must be updated to the 25.8.0 version.

If you want the operator to automatically update the data-plane (i.e. init and agent containers), you can set updateStrategy.autoUpdateDataPlane=true in your MariaDB resources:

Alternatively, you can also do this manually:

Upgrade mariadb-enterprise-operator to 25.8.0:

If you previously decided to downscale the operator, make sure you upscale it back:

If you previously set updateStratety.autoUpdateDataPlane=true, you may consider reverting the changes once the upgrades have finished:

25.10 LTS version update guide

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

The Galera data-plane must be updated to the 25.10.4 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:

Once set, you may proceed to update the operator. If you are using Helm:

Upgrade the mariadb-enterprise-operator-crds helm chart to 25.10.4:

Upgrade the mariadb-enterprise-operator helm chart to 25.10.4:

As part of the 25.10 LTS release, we have introduced support for LTS versions. Refer to the for sticking to LTS versions.

If you are on OpenShift:

If you are on the stable channel using installPlanApproval=Automatic in your Subscription object, then the operator will be automatically updated. If you use installPlanApproval=Manual, you should have a new InstallPlan which needs to be approved to update the operator:

As part of the 25.10 LTS release, we have introduced new . Consider switching to the stable-v25.10 if you are willing to stay in the 25.10.x version:

Consider reverting updateStrategy.autoUpdateDataPlane back to false in your MariaDB object to avoid unexpected updates:

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:

External MariaDB

Describes how the Operator can manage resources or connections for MariaDB instances that reside outside the local Kubernetes cluster.

MariaDB Enterprise Kubernetes Operator supports managing resources in external MariaDB instances i.e running outside of the Kubernetes cluster where the operator runs. This feature allows to manage users, privileges, databases, run SQL jobs declaratively and taking backups using the same CRs that you use to manage internal MariaDB instances.

`ExternalMariaDB` configuration

The ExternalMariaDB resource is similar to the internal MariaDB resource, but we need to provide a host, username and a reference to a Secret containing the user password. These will be the connection details that the operator will use to connect to the external MariaDB in order to manage resources, make sure that the specified user has enough privileges:

If you need to use TLS to connect to the external MariaDB, you can provide the server CA certificate and the client certificate Secrets via the tls field:

When using TLS, if you don't want to send the client certificate during the TLS handshake, please set tls.mutual=false:

As a result, you will be able to specify the ExternalMariaDB as a reference in , the same way you would do for a internal MariaDB resource.

As part of the ExternalMariaDB reconciliation, a Connection will be created whenever the connection template is specified. This could be handy to track the external connection status and declaratively create a connection string in a Secret to be consumed by applications to connect to the external MariaDB.

Supported objects

Currently, the ExternalMariaDB resource is supported by the following objects:

Connection
User
Grant

You can use it as an internal MariaDB resource, just by setting kind to ExternalMariaDB in the mariaDBRef field:

When the previous example gets reconciled, an user will be created in the referred external MariaDB instance.

Metadata

Details how to customize Kubernetes metadata, such as labels and annotations, for the resources generated and managed by the Operator.

This documentation shows how to configure metadata in the MariaDB Enterprise Kubernetes Operator CRs.

Children object metadata

MariaDB and MaxScale resources allow you to propagate metadata to all the children objects by specifying the inheritMetadata field:

This means that all the reconciled objects will inherit these labels and annotations. For instance, see the Services and Pods:

`Pod` metadata

You have the ability to provide dedicated metadata for Pods by specifying the podMetadata field in any CR that reconciles a Pod, for instance: MariaDB, MaxScale, Backup, Restore and SqlJobs:

It is important to note that the podMetadata field supersedes the inheritMetadata field, therefore the labels and annotations provided in the former will override the ones in the latter.

`Service` metadata

Provision dedicated metadata for Services in the MariaDB resources can be done via the service, primaryService and secondaryService fields:

In the case of MaxScale, you can also do this via the kubernetesService field.

Refer to the to know more about the Service fields and MaxScale.

`PVC` metadata

Both MariaDB and MaxScale allow you to define a volumeClaimTemplate to be used by the underlying StatefulSet. You may also define metadata for it:

Use cases

Being able to provide metadata allows you to integrate with other CNCF landscape projects:

Metallb

If you run on bare metal and you use for managing the LoadBalancer objects, you can declare its IPs via annotations:

Istio

injects the data-plane container to all Pods, but you might want to opt-out of this feature in some cases:

For instance, you probably don't want to inject the Istio sidecar to Backup Pods, as it will prevent the Jobs from finishing and therefore your backup process will hang.

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
Upgrades
Volume resize
Galera cluster recovery

More specifically, the reconciliation loop of the operator is omitted, anything part of it will not happen while the resource is suspended. This could be useful in maintenance scenarios, where manual operations need to be performed, as it helps prevent conflicts with the operator.

Suspend a resource

Currently, only MariaDB and MaxScale resources support suspension. You can enable it by setting suspend=true:

This results in the reconciliation loop being disabled and the status being marked as Suspended:

To re-enable it, simply remove the suspend setting or set it to suspend=false.

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:

apiVersion: enterprise.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb
spec:
  # ....
  myCnf: |
    [mariadb]
    plugin_load_add = auth_pam # Load auth plugin
  # ....

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

Component

Image

Supported Tags

CPU Architecture

Examples Catalog

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

The examples catalog 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 examples catalog:

Install the configuration shared by all the examples:

Start deploying examples:

Some examples rely on external dependencies for specific tasks, make sure to install them when it applies:

for metrics
for TLS certificates
for S3 object storage

It is recommended to complement the examples with the documentation to understand the full range of configuration options available.

If you are looking for production-grade examples, you can check the following manifests:

mariadb_replication_production.yaml and maxscale_replication_production.yaml for
mariadb_galera_production.yaml and maxscale_galera_production.yaml for

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.

Enabling TLS in existing instances

In this guide, we will be migrating existing MariaDB Galera and MaxScale instances to TLS without downtime.

1. Ensure that MariaDB has TLS enabled and not enforced. Set the following options if needed:

By setting these options, the operator will issue and configure certificates for MariaDB, but TLS will not be enforced in the connections i.e. both TLS and non-TLS connections will be accepted. TLS enforcement will be optionally configured at the end of the migration process.

This will trigger a rolling upgrade, make sure it finishes successfully before proceeding with the next step. Refer to the for further information about update strategies.

2. If you are currently using MaxScale, it is important to note that, unlike MariaDB, it does not support TLS and non-TLS connections simultaneously (see ). For this reason, you must temporarily point your applications to MariaDB during the migration process. You can achieve this by configuring your application to use the . At the end of the MariaDB migration process, the MaxScale instance will need to be recreated in order to use TLS, and then you will be able to point your application back to MaxScale. Ensure that all applications are pointing to MariaDB before moving on to the next step.

3. MariaDB is now accepting TLS connections. The next step is by pointing them to MariaDB securely. Ensure that all applications are connecting to MariaDB via TLS before proceeding to the next step.

4. If you are currently using MaxScale, and you are planning to connect via TLS through it, you should now delete your MaxScale instance. If needed, keep a copy of the MaxScale manifest, as we will need to recreate it with TLS enabled in further steps:

It is very important that you wait until your old MaxScale instance is fully terminated to make sure that the old configuration is cleaned up by the operator.

5. For enhanced security, it is recommended to enforce TLS in all MariaDB connections by setting the following options. This will trigger a rolling upgrade, make sure it finishes successfully before proceeding with the next step:

6. For improved security, you can optionally configure TLS for Galera SSTs by following the steps below:

Get the and grant execute permissions:

Run the migration script. Make sure you set <mariadb-name> with the name of the MariaDB resource:

Set the following option to enable TLS for Galera SSTs:

This will trigger a rolling upgrade, make sure it finishes successfully before proceeding with the next step

7. As mentioned in step 4, recreate your MaxScale instance with tls.enabled=true if needed:

8. MaxScale is now accepting TLS connections. Next, you need to by pointing them back to MaxScale securely. You have done this previously for MariaDB, you just need to update your application configuration to use the and its CA bundle.

Migrate Community operator to Enterprise operator

In this guide, we will be migrating from the to the without downtime. This guide assumes:

version of the MariaDB Community Operator is installed in the cluster.
MariaDB community resources will be migrated to its counterpart MariaDB enterprise resource. In this case, we will be using 11.4.4

Migrate external MariaDB into Kubernetes

In this guide, we will be migrating an external MariaDB into a new MariaDB instance running in Kubernetes and managed by MariaDB Enterprise Kubernetes Operator. We will be using for achieving this migration.

Ensure you understand the in the MariaDB Enterprise Kubernetes Operator.

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

If you are currently using or migrating to a Galera instance, use the following command instead:

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.

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.

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.

Asynchronous Replication

The operator supports provisioning and operating MariaDB clusters with replication as a highly availability topology. In the following sections we will be covering how to manage the full lifecycle of a replication cluster.

In a replication setup, one primary server handles all write operations while one or more replica servers replicate data from the primary, being able to handle read operations. More precisely, the primary has a binary log and the replicas asynchronously replicate the binary log events over the network.

Please refer to the MariaDB documentation for more details about replication.

Provisioning

In order to provision a replication cluster, you need to configure a number of replicas greater than 1 and set the replication.enabled=true in the MariaDB CR:

After applying the previous CR, the operator will provision a replication cluster with one primary and two replicas. The operator will take care of setting up replication, configuring the replication user and monitoring the replication status:

As you can see, the primary can be identified in the PRIMARY column of the kubectl get mariadb output. You may also inspect the current replication status by checking the MariaDB CR status:

The operator continuously monitors the replication status via , taking it into account for internal operations and updating the CR status accordingly.

Asynchronous vs semi-synchronous replication

By default, is configured, which requires an acknowledgement from at least one replica before committing the transaction back to the client. This trades off performance for better consistency and facilitates and operations.

If you are aiming for better performance, you can disable semi-synchronous replication, and go fully asynchronous, please refer to section for doing so.

Configuration

The replication settings can be customized under the replication section of the MariaDB CR. The following options are available:

gtidStrictMode: Enables GTID strict mode. It is recommended and enabled by default. See .
semiSyncEnabled: Determines whether semi-synchronous replication should be enabled. It is enabled by default. See .
semiSyncAckTimeout

These options are used by the operator to create a replication configuration file that is applied to all nodes in the cluster. When updating any of these options, an will be triggered in order to apply the new configuration.

For replica-specific configuration options, please refer to the section. Additional system variables may be configured via the myCnf configuration field. Refer to the for more details.

Replica configuration

The following options are replica-specific and can be configured under the replication.replica section of the MariaDB CR:

replPasswordSecretKeyRef: Reference to the Secret key containing the password for the replication user, used by the replicas to connect to the primary. By default, a Secret with a random password will be created.
gtid: GTID position mode to be used (CurrentPos and SlavePos

Probes

Kubernetes probes are resolved by the agent (see documentation) in the replication topology, taking into account both the MariaDB and replication status. Additionally, as described in the , probe thresholds may be tuned accordingly for a better reliability based on your environment.

In the following sub-sections we will be covering specifics about the replication topology.

Liveness probe

As part of the liveness probe, the agent checks that the MariaDB server is running and that the replication threads (Slave_IO_Running and Slave_SQL_Running) are both running on replicas. If any of these checks fail, the liveness probe will fail.

If such a behaviour is undesirable, it is possible to opt in for regular standalone startup/liveness probes (default SELECT 1 query). See standaloneProbes in the section.

Readiness probe

The readiness probe checks that the MariaDB server is running and that the Seconds_Behind_Master value is within the acceptable lag range defined by the spec.replication.replica.maxLagSeconds configuration option. If the lag exceeds this value, the readiness probe will fail and the replica will be marked as not ready.

Lagged replicas

A replica is considered to be lagging behind the primary when the Seconds_Behind_Master value reported by SHOW SLAVE STATUS exceeds the spec.replication.replica.maxLagSeconds configuration option. This results in the failing for that replica, and it has the following implications:

When using , queries will not be forwarded to lagged replicas. This doesn't affect MaxScale routing.
When taking a , lagged replicas will not be considered as a target for taking the backup.
During a managed by the operator, lagged replicas will block switchover operations, as all the replicas must be in sync before promoting the new primary. This doesn't affect MaxScale switchover operation.

Backing up and restoring

In order to back up and restore a replication cluster, all the concepts and procedures described in the documentation apply.

Additionally, for the replication topology, the operator tracks the GTID position at the time of taking the backup, and sets this position based on the gtid_current_pos system variable when restoring the backup, as described in the .

Depending on the PhysicalBackup strategy used, the operator will track the GTID position accordingly:

mariadb-backup: When using PhysicalBackup with the mariadb-backup strategy, the GTID will be restored to a mariadb-enterprise-operator.info file in the data directory, which the agent will expose to the operator via HTTP.
VolumeSnapshot: When using PhysicalBackup with the VolumeSnapshot strategy, the GTID position will be kept in a

When using PhysicalBackup with the mariadb-backup strategy, the GTID will be restored to a mariadb-enterprise-operator.info file in the data directory, which the agent will expose to the operator via HTTP.

It is important to note that, by default, physical backups are only taken in ready replicas when the MariaDB resource is in a ready state. If you are running with a single replica, it is recommended to set mariaDbRef.waitForIt=false and target=PreferReplica in the PhysicalBackup CR to allow taking backups from the primary when the replica is not ready. Please refer to the for configuring this behaviour.

`VolumeSnapshot`

When using PhysicalBackup with the VolumeSnapshot strategy, the GTID position will be kept in a enterprise.mariadb.com/gtid annotation in the VolumeSnapshot object, which later on the operator will read when restoring the backup.

Refrain from removing the enterprise.mariadb.com/gtid annotation in the VolumeSnapshot object, as it is required for configuring the replica when restoring the backup.

Primary switchover

Our recommendation for production environments is to rely on for the , as it provides .

You can declaratively trigger a primary switchover by updating the spec.replication.primary.podIndex field in the MariaDB CR to the index of the replica you want to promote as the new primary. For example, to promote the replica at index 1:

You can also do this imperatively using kubectl:

This will result in the MariaDB object reporting the following status:

The steps involved in the switchover operation are:

Lock the current primary using FLUSH TABLES WITH READ LOCK to ensure no new transactions are being processed.
Set the read_only system variable on the current primary to prevent any write operations.
Wait until all the replicas are in sync with the current primary. The timeout for this step can be configured via the spec.replication.replica.syncTimeout

If the switchover operation is stuck waiting for replicas to be in sync, you can check the MariaDB status to identify which replicas are causing the issue. Furthermore, if still in this step, you can cancel the switchover operation by setting back the spec.replication.primary.podIndex field back to the previous primary index.

Primary failover

Our recommendation for production environments is to rely on for the failover process, as it provides .

You can configure the operator to automatically perform a primary failover whenever the current primary becomes unavailable:

Optionally, you may also specify a autoFailoverDelay, which will add a delay before triggering the failover operation. By default, the failover is immediate, but introducing a delay may be useful to avoid failovers due to transient issues. But note that the delay should be lower than the readiness probe failure threshold (e.g. 20 seconds delay when readiness threshold is 30 seconds), otherwise all the replicas will be marked as not ready and the automatic failover will not be able to proceed.

Whenever the primary becomes unavailable, the following status will be reported in the MariaDB CR:

The criteria for choosing a new primary is:

The Pod should be in Ready state, therefore not considering unavailable or lagged replicas (see and sections).
Both the IO(Slave_IO_Running) and the SQL(Slave_SQL_Running) threads should be running.

Once the new primary is selected, the failover process will be performed, consisting of the following steps:

Wait for the new primary to apply all relay log events.
Promote the selected replica to be the new primary.
Connect replicas to the new primary.

Updates

When updating a replication cluster, all the considerations and procedures described in the documentation apply.

Furthermore, for the replication topology, the operator will trigger an additional once all the replicas have been updated, just before updating the primary. This ensures that the primary is always updated last, minimizing the impact on write operations.

The steps involved in updating a replication cluster are:

Update each replica one by one, waiting for each replica to be ready before proceeding to the next one (see section).
Once all replicas are up to date and synced, perform a to promote one of the replicas as the new primary. If MariaDB CR has a MaxScale configured using the spec.maxScaleRef field, the operator will trigger the instead.

Scaling out

Scaling out a replication cluster implies adding new replicas to the cluster i.e scaling horizontally. The process involves taking a physical backup from a ready replica to setup the new replica PVC, and upscaling the replication cluster afterwards.

The first step is to define the to be used for taking the backup. For doing so, we will be defining a PhysicalBackup CR, that will be used by the operator as template for creating the actual PhysicalBackup object during scaling out events. For instance, to use the mariadb-backup strategy, we can define the following PhysicalBackup:

It is important to note that, we set the spec.schedule.suspend=true to prevent scheduling this backup, as it will be only be used as a template.

Alternatively, you may also use a VolumeSnapshot strategy for taking the backup:

Once the PhysicalBackup template is created, you need to set a reference to it in the spec.replication.replica.bootstrapFrom, indicating that this will be the source for creating new replicas:

At this point, you can proceed to scale out the cluster by increasing the spec.replicas field in the MariaDB CR. For example, to scale out from 3 to 4 replicas:

You can also do this imperatively using kubectl:

This will trigger an scaling out operation, resulting in:

A PhysicalBackup based on the template being created.
Creating a new PVC for the new replica based on the PhysicalBackup.
Upscaling the StatefulSet, adding a

It is important to note that, if there are no ready replicas available at the time of the scaling out operation, the PhysicalBackup will not become ready, and the scaling out operation will be stuck until a replica becomes ready. You have the ability to cancel the scaling out operation by setting back the spec.replicas field to the previous value.

Considering that we set mariaDbRef.waitForIt=false and target=PreferReplica in the PhysicalBackup template, it is important to note that, if there are no ready replicas available at the time of the scaling out operation, the operator will take the backup from the primary instead. Please refer to the for configuring this behaviour.

You have the ability to cancel the scaling out operation by setting spec.replicas back to the previous value.

Replica recovery

The operator has the ability to automatically recover replicas that become unavailable and report a specific error code in the replication status. For doing so, the operator continuously monitors the replication status of each replica, and whenever a replica reports an error code listed in the table below, the operator will trigger an automated recovery process for that replica:

Error Code

Thread

Description

Documentation

To perform the recovery, the operator will take a physical backup from a ready replica, restore it to the failed replica PVC, and reconfigure the replica to connect to the primary from the GTID position stored in the backup.

Similarly to the operation, you need to define a PhysicalBackup template and set a reference to it in the spec.replication.replica.bootstrapFrom field of the MariaDB CR. Additionally, you need to explicitly enable the replica recovery, as it is disabled by default:

The errorDurationThreshold option defines the duration after which, a replica reporting an unknown error code will be considered for recovery. This is useful to avoid recovering replicas due to transient issues. It defaults to 5m.

We will be simulating a 1236 error in a replica to demonstrate how the recovery process works:

Do not perform the following steps in a production environment.

Purge the binary logs in the primary:

Delete the PVC and restart one of the replicas:

This will trigger a replica recovery operation, resulting in:

A PhysicalBackup based on the template being created.
Restoring the backup to the failed replica PVC.
Reconfigure the replica to connect to the primary from the GTID position stored in the backup.

Considering that we set mariaDbRef.waitForIt=false and target=PreferReplica in the PhysicalBackup template, it is important to note that, if there are no ready replicas available at the time of the replica recovery operation, the operator will take the backup from the primary instead. Please refer to the for configuring this behaviour.

You have the ability to cancel the recovery operation by setting spec.replication.replica.recovery.enabled=false.

Troubleshooting

The operator tracks the current replication status under the MariaDB status subresource. This status is updated every time the operator reconciles the MariaDB resource, and it is the first place to look for when troubleshooting replication issues:

Additionally, also under the status subresource, the operator sets status conditions whenever a specific state of the MariaDB lifecycle is reached:

The operator also emits Kubernetes events during failover/switchover operations. You may check them to see how these operations progress:

Common errors

Primary has purged binary logs, unable to configure replica

The primary may purge binary log events at some point, after then, if a replica requests events before that point, it will fail with the following error:

This is a something the operator is able to recover from, please refer to the .

Scaling out/recovery operation stuck

These operations rely on a PhysicalBackup for setting up the new replicas. If this PhysicalBackup does not become ready, the operation will not progress. In order to debug this please refer to the .

One of the reasons could be that you have no ready replicas for taking the backup and your PhysicalBackup CR does not allow taking the backup from the primary. You may set mariaDbRef.waitForIt=false and target=PreferReplica in the PhysicalBackup template to allow taking the backup from the primary when there are no ready replicas available. Please verify that this is the case by checking the status of your MariaDB resource and your Pods, and refer to the for configuring the backup behaviour.

MaxScale switchover stuck during update

When using MaxScale, after having updated all the replica Pods, it could happen that MaxScale refuses to perform the switchover, as it considers the Pod chosen by the operator to be unsafe:

For this case, you can manually update the primaryServer field in the MaxScale resource to a safe Pod, and restart the operator. If the new primary server is the right Pod, MaxScale will start the switchover and the update will continue after it completes.

Scale out/replica recovery job names too long

This error happens when the name of the physical backup Job created for the scaling out or replica recovery operation exceeds the Kubernetes hard limit of 63 characters. We have truncated the job names already to significantly mitigate this problem, but the problem might still happen if your MariaDB resource name is too long.

Point-In-Time-Recovery

Point-in-time recovery (PITR) is a feature that allows you to restore a MariaDB instance to a specific point in time. For achieving this, it combines a full base backup and the binary logs that record all changes made to the database after the backup. This is something fully automated by operator, covering archival and restoration up to a specific time, ensuring business continuity and reduced RTO and RPO.

Supported MariaDB versions and topologies

The operator uses mariadb-binlog to replay binary logs, in particular, it filters binlog events by passing a GTID to mariadb-binlog via the --start-position flag. This is only supported by MariaDB server 10.8 and later, so make sure you are using a compatible MariaDB version.

Regarding supported MariaB topologies, at the moment, binary log archiving and point-in-time recovery are only supported by the , which already relies on the binary logs for replication. Galera and standalone topologies will be supported in upcoming releases.

Storage types

Full base backups and binary logs can be stored in the following object storage types:

S3 compatible storage: Such as or .
.

For additional details on configuring storage, please refer to the section in the physical backup documentation, same settings are applicable to the PointInTimeRecovery object.

Configuration

To be able to perform a point-in-time restoration, a physical backup should be configured as full base backup. For example, you can configure a nightly backup:

Refer to the section for additional details on how to configure the full base backup.

Next step is configuring common aspects of both binary log archiving and point-in-time restoration by defining a PointInTimeRecovery object:

physicalBackupRef: It is a reference to the PhysicalBackup resource used as full base backup. See .
storage: Object storage configuration for binary logs. See .

With this configuration in place, you can enable binary log archival in a MariaDB instance by setting a reference to the PointInTimeRecovery object:

Once a full base backup has been completed and the binary logs have been archived, you can perform a point-in-time restoration. For example, you can create a new MariaDB instance with the following configuration:

Refer to the section for additional details.

Full base backup

To enable point-in-time recovery, a PhysicalBackup resource should be configured as full base backup. The backup should be a complete snapshot of the database at a specific point in time, and it will serve as the starting point for replaying the binary logs. Any of the supported can be used as full base backup, as all of them provide a consistent snapshot of the database and a starting GTID position.

It is very important to note that a full physical backups should be completed before a point-in-time restoration can be performed. This is something that the operator accounts for when computing the .

To further expand the , it is recommended to take physical backups after the primary Pod has changed. This can be automated by setting schedule.onPrimaryChange, as documented in the :

Alternatively, you can schedule an on-demand physical backup or rely on the cron scheduling for doing so:

The backup taken in the new primary will establish a baseline for a new , which will be expanded when new binary logs are archived.

Archival

The mariadb-enterprise-operator will periodically check for new binary logs and archive them to the configured object storage. The archival process is controlled by the archiveInterval and archiveTimeout settings in the PointInTimeRecovery configuration, which determine how often the archival process runs and how long it can take before it is considered failed.

The archival process is performed on the primary Pod in the asynchronous replication topology, you may check the logs of the agent sidecar container, Kubernetes events and status of the MariaDB objects to monitor the current status of the archival process:

There are a couple of important considerations regarding binary log archival:

The archival process should start from a clean state, which means that the object storage should be empty at the time of the first archival.
It is not recommended to set archiveInterval to a very low value (< 1m), as it can lead to increased load on the database Pod and the storage system.
If the archival process fails (e.g., due to network issues or storage unavailability), it will be retried in the next archive cycle.

Binary log size

The server has a default of 1GB, which means that a new binary log file will be created once the current one reaches that size. This is sensible default value for most cases, but it can be adjusted based on the data volume in order to enable a faster archival, and therefore a reduced RPO:

Environment

Recommended Size

Rationale

The smaller the binlog file size, the more frequently the files will be rotated and archived, which can lead to increased load on the database Pod and the storage system. On the other hand, setting a very high binlog file size can lead to longer archival times and increased RPO.

Refer to the documentation for instructions on how to set the max_binlog_size server variable in the MariaDB instance.

Compression

In order to reduce storage usage and save bandwidth during archival and restoration, the operator supports compressing the binary log files. Compression is enabled by setting the compression field in the PointInTimeRecovery configuration:

The supported compression algorithms 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.

Compression is disabled by default, and the are some important considerations before enabling it:

Compression is immutable, which means that once configured and binary logs have been archived with a specific algorithm, it cannot be changed. This also applies to restoration, the same compression algorithm should be configured as the one used for archival.
Although it saves storage space and bandwidth, the restoration process may take longer when compression is enabled, leading to an increased RTO. This can migrated by enabling .

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

When using S3-compatible storage, 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 binary logs. Ensure you have proper key management procedures in place.

When replaying SSE-C encrypted binary logs via bootstrapFrom, the same key must be provided in the S3 configuration.

Parallelization

Several tasks during both archival an restoration process can take a significant amount of time, specially when managing large data volumes. These tasks include compressing and uploading binary logs during archival, and downloading and decompressing binary logs during restoration. This can lead to longer archival and restoration times, which can impact the RTO.

To mitigate this, the operator supports parallelization of these tasks by using multiple workers. The maximum number of workers can be configured via the maxParallel field in the PointInTimeRecovery configuration:

This will create up to 4 workers, each of them responsible for the operations related to a single binary log, which means that up to 4 binary logs can be processed in parallel. This can significantly reduce the archival and restoration times, specially when is enabled.

Parallelization is disabled by default (maxParallel: 1), and there are some important considerations to be taken into account when enabling it:

During archival, the workers will be spawn in the container, sharing storage with the primary database Pod. Using an elevated number of workers can exhaust IOPS and/or CPU resources of the primary Pod, which can impact the performance of the database.
During both archival and restoration, using an elevated number of workers can saturate the network bandwidth when pulling/pushing multiple binary logs in parallel, something that can degrade the performance of the database.

Retention policy

Binary logs can grow significantly in size, especially in write-heavy environments, which can lead to increased storage costs. To mitigate this, the operator supports automatic purging of binary logs based on a retention policy defined by the maxRetention field in the PointInTimeRecovery configuration:

The binary logs that exceed the defined retention will be automatically deleted from the object storage after each archival cycle.

By default, binary logs are never purged from object storage, and there are few considerations regarding configuring a retention policy:

The date of the last event in the binary logs is used to determine its age, and therefore whether it should be purged or not.
The maxRetention field should not be set to a value lower than the archiveInterval, as it can lead to situations where binary logs are purged before they can be archived.

Binlog inventory

The operator maintains an inventory of the archived binary logs in an index.yaml file located at the root of the configured object storage. This file contains a list of all the archived binary logs per each server, along with their GTIDs and other metadata utilized internally. Here is an example of the index.yaml file:

This file is used internally by the operator to keep track of the archived binary logs, and it is updated after each successful archival. It should not be modified manually, as it can lead to inconsistencies between the actual archived binary logs and the inventory.

When it comes to point-in-time restoration, this file serves as a source of truth to compute the .

Binlog timeline and last recoverable time

Taking into account the last completed physical backup GTID and the archived binlogs in the , the operator computes a timeline of binary logs that can replayed and its corresponding last recoverable time. The last recoverable time is the latest timestamp that the MariaDB instance can be restored to. This information is crucial for understanding the RPO of the system and for making informed decisions during a recovery process.

You can easily check the by looking at the status of the PointInTimeRecovery object:

Then, you may provide exactly this timestamp, or an earlier one, as target recovery time when bootstrapping a new MariaDB instance, as described in the section.

Point-in-time restoration

In order to perform a point-in-time restoration, you can create a new MariaDB instance with a reference to the PointInTimeRecovery object in the bootstrapFrom field, along with the targetRecoveryTime field indicating the desired point-in-time to restore to.

For setting the targetRecoveryTime, it is recommended to check the last recoverable time first in the PointInTimeRecovery object:

pointInTimeRecoveryRef: Reference to the PointInTimeRecovery object that contains the configuration for the point-in-time recovery.
targetRecoveryTime: The desired point in time to restore to. It should be in RFC3339 format. If not provided, the current time will be used as target recovery time, which means restoring up to the .

The restoration process will match the closest physical backup before or at the targetRecoveryTime, and then it will replay the archived binary logs from the backup GTID position up until the targetRecoveryTime:

As you can see, the restoration process includes the following steps:

Perform a rolling restore of the , one Pod at a time.
Configure replication in the MariaDB instance.
Get the base backup GTID, to be used as the starting point for replaying the binary logs.

After having completed the restoration process, the following status conditions will be available for you to inspect the restoration process:

Strict mode

The strict mode controls whether the target recovery time provided during the bootstrap process should be strictly met or not. This is configured via the strictMode field in the PointInTimeRecovery configuration, and it is disabled by default:

When strict mode is enabled (recommended), if the target recovery time cannot be met, the initialization process will return an error early, and the MariaDB instance will not be created. This can happen, for example, if the target recovery time is later than the . Let's assume strict mode is enabled and the last recoverable time is:

If we attempt to provision the following MariaDB instance:

The following errors will be returned, as the target recovery time 2026-02-28T20:10:42Z is later than the last recoverable time 2026-02-27T20:10:42Z:

When strict mode is disabled (default), and the target recovery time cannot be met, the MariaDB provisioning will proceed and the last recoverable time will be used. This would mean that, the MariaDB instance will be provisioned with a recovery time of 2026-02-27T20:10:42Z, which is the last recoverable time:

After setting strictMode=false, if we attempt to create the same MariaDB instance as before, it will be successfully provisioned, but with a recovery time of 2026-02-27T20:10:42Z will be used instead of the requested 2026-02-28T20:10:42Z.

It is important to note that the last recoverable time is stored in the status field of the PointInTimeRecovery object, therefore if this object is deleted and recreated, the last recoverable time metadata will be lost, and it will not be available until recomputed. When it comes to restore, this implies that the error will be returned later in the process, when computing the binary log timeline, but the strict mode behaviour still applies. This is the error returned for that scenario:

Staging storage

The operator uses a staging area to temporarily store the binary logs during the restoration process. By default, the staging area is an attached to the restoration job, which means that the binary logs are kept in the node storage where the job has been scheduled. This may not be suitable for large binary logs, as it can lead to exhausting the node's storage, resulting the restoration process to fail and potentially impacting other workloads running in the same node.

You are able to configure an alternative staging area using the stagingStorage field under the bootstrapFrom section in the MariaDB resource:

This will provision a PVC and attach it to the restoration job to be used as staging area.

Limitations

A PointInTimeRecovery object can only be referred by a single MariaDB object via the pointInTimeRecoveryRef field.
A combination object storage bucket + prefix can only be utilizied by a single MariaDB instance to archive binary logs.

Troubleshooting

The operator tracks the current archival status under the MariaDB status subresource. This status is updated after each archival cycle, and it contains metadata about the binary logs that have been archived, along with other useful information for troubleshooting:

Additionally, also under the status subresource, the operator sets status conditions whenever a specific state of the binlog archival or point-in-time restoration process is reached:

The operator also emits Kubernetes events during both archival and restoration process, to either report an outstanding event or error:

Common errors

Unable to start archival process

The following error will be returned if the archival process is configured pointing to a non-empty object storage, as the operator expects to start from a clean state:

To solve this, you can update the PointInTimeRecovery configuration pointing to another object storage bucket or prefix that is empty:

After updating the PointInTimeRecovery configuration, the error will be cleared in the next archival cycle, and a new archival operation will be attempted.

Alternatively, you can also consider deleting the existing binary logs and , only after having double checked that they are not needed for recovery.

Target recovery time is after latest recoverable time

This error is returned in the MariaDB init process, when the targetRecoveryTime provided to bootstrap is later than the reported by the PointInTimeRecovery status.

For example, if you have configured the bootstrapFrom.targetRecoveryTime field with the value 2026-02-28T20:10:42Z, the following error will be returned:

There are two ways to solve this issue:

Update the targetRecoveryTime in the MariaDB resource to be earlier than or equal to the last recoverable time, which in this case is 2026-02-27T20:10:42Z.
Disable strictMode in the PointInTimeRecovery configuration, allowing to restore up until the latest recoverable time, in this case 2026-02-27T20:10:42Z

Invalid binary log timeline: error getting binlog timeline between GTID and target time: timeline did not reach target time

This error is returned when computing the binary log timeline during the restoration process, and it means that the operator could not build a timeline that reaches the targetRecoveryTime provided in the bootstrapFrom field of the MariaDB resource.

For example, if you have the following :

And your targetRecoveryTime is 2026-02-28T20:10:42Z, the following error will be returned:

There are two ways to solve this issue:

Update the targetRecoveryTime in the MariaDB resource to be earlier than or equal to the last recoverable time, which in this case is 2026-02-27T16:04:15Z.
Disable strictMode in the PointInTimeRecovery configuration, allowing to restore up until the latest recoverable time, in this case 2026-02-27T16:04:15Z

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

MariaDB Enterprise Kubernetes Operator

Introduction

hashtagWhat is Kubernetes?

hashtagWhy Kubernetes?

hashtagWhat is a Kubernetes Operator?

hashtagMariaDB Enterprise Kubernetes Operator Features

Customer access to docker.mariadb.com

hashtagCustomer credentials

Installation

Quickstart

Topologies

Standalone

Data Plane

hashtagComponents

hashtagInit container

hashtagAgent sidecar

hashtagAgent auth methods

hashtagServiceAccount based authentication

hashtagBasic authentication

hashtagUpdates

Backup and Restore

CSI Specific Configuration

hashtagblob-csi-driver (Azure Blob Storage)

Storage

hashtagConfiguration

hashtagVolume resize

hashtagEphemeral storage

Updates

hashtagUpdate strategies

hashtagConfiguration

hashtagTrigger updates

hashtagReplicasFirstPrimaryLast

hashtagRollingUpdate

hashtagOnDelete

hashtagNever

hashtagData-plane updates

25.08 version update guide

25.10 LTS version update guide

26.03 version update guide

External MariaDB

hashtagExternalMariaDB configuration

hashtagSupported objects

Metadata

hashtagChildren object metadata

hashtagPod metadata

hashtagService metadata

hashtagPVC metadata

hashtagUse cases

hashtagMetallb

hashtagIstio

Suspend Reconciliation

hashtagSuspended state

hashtagSuspend a resource

Plugins

Supported Docker Images

Examples Catalog

Migrations

Enabling TLS in existing instances

Migrate Community operator to Enterprise operator

Migrate external MariaDB into Kubernetes

Migrate Embedded MaxScale To MaxScale Resource

MariaDB Enterprise Kubernetes Operator

Introduction

hashtagWhat is Kubernetes?

hashtagWhy Kubernetes?

hashtagWhat is a Kubernetes Operator?

hashtagMariaDB Enterprise Kubernetes Operator Features

Migrations

Installation

Topologies

Plugins

Backup and Restore

Standalone

Supported Docker Images

Suspend Reconciliation

hashtagSuspended state

hashtagSuspend a resource

25.08 version update guide

Examples Catalog

CSI Specific Configuration

What is Kubernetes?

Why Kubernetes?

What is a Kubernetes Operator?

MariaDB Enterprise Kubernetes Operator Features

Customer credentials

Components

Init container

Agent sidecar

Agent auth methods

`ServiceAccount` based authentication

Basic authentication

Updates

blob-csi-driver (Azure Blob Storage)

Configuration

Volume resize

Ephemeral storage

Update strategies

Configuration

Trigger updates

`ReplicasFirstPrimaryLast`

`RollingUpdate`

`OnDelete`

`Never`

Data-plane updates

`ExternalMariaDB` configuration

Supported objects

Children object metadata

`Pod` metadata

`Service` metadata

`PVC` metadata

Use cases

Metallb

Istio

Suspended state

Suspend a resource

What is Kubernetes?

Why Kubernetes?

What is a Kubernetes Operator?

MariaDB Enterprise Kubernetes Operator Features

Suspended state

Suspend a resource

blob-csi-driver (Azure Blob Storage)

Issue 1: Access for Non-Root Containers (`-o allow_other`)

Issue 2: Immediate List Operations and Backup Deletion (`--cancel-list-on-mount-seconds=0`)

Components

Init container

Agent sidecar

Agent auth methods

`ServiceAccount` based authentication

Basic authentication

Updates

Customer credentials

Openshift

`MariaDB`

`MaxScale`

`Backup`, `Restore` and `SqlJob`

Update strategies

Configuration

Trigger updates

`ReplicasFirstPrimaryLast`

`RollingUpdate`

`OnDelete`

`Never`

Data-plane updates

Children object metadata

`Pod` metadata

`Service` metadata

`PVC` metadata

Use cases

Metallb

Istio

`ExternalMariaDB` configuration

Supported objects

Configuration

Volume resize

Ephemeral storage

`User` CR

Custom name

`Grant` CR

`Database` CR