bitnamicharts/mariadb-galera repository overview

⁠Bitnami Secure Images Helm chart for MariaDB Galera

MariaDB Galera is a multi-primary database cluster solution for synchronous replication and high availability.

Overview of MariaDB Galera⁠

Trademarks: This software listing is packaged by Bitnami. The respective trademarks mentioned in the offering are owned by the respective companies, and use of them does not imply any affiliation or endorsement.

⁠ TL;DR

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/mariadb-galera

⁠ Introduction

This chart bootstraps a MariaDB Galera⁠ cluster on Kubernetes⁠ using the Helm⁠ package manager.

⁠ Differences between the the Bitnami MariaDB Galera and Bitnami MariaDB Helm charts

There are two different ways to deploy a MariaDB cluster, using the MariaDB Helm chart or the MariaDB Galera Helm chart. Both solutions provide a simply and reliable way to run MariaDB in a production environment. Keep reading to discover the differences between them and check which one better suits your needs.

• The MariaDB Galera Helm chart configures a cluster with three nodes by default, all of them acting as master nodes with writing / reading permissions. The MariaDB Helm chart deploys one node that you can use as a single-node application database.
• The MariaDB Galera Helm chart provides a cluster with both read and write scalability since all nodes acts as master nodes (multi-master topology) while a cluster comprised of several MariaDB nodes will establish the master-slave topology.
• The MariaDB Galera Helm chart deploys a cluster with synchronous replication, avoiding data loss if any node fails.
• The MariaDB Galera Helm chart cluster ensures high-availability thanks to automatic membership control, failed nodes are drop from the cluster.

The following diagram shows you the options you have for using Bitnami's MariaDB solutions in your deployments: either as a single-node database (MariaDB) or as a multi-master cluster (MariaDB Galera).

⁠ Before you begin

• Kubernetes 1.23+
• Helm 3.8.0+
• PV provisioner support in the underlying infrastructure

⁠ Installing the Chart

To install the chart with the release name my-release:

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/mariadb-galera

The command deploys MariaDB Galera on the Kubernetes cluster in the default configuration. The Parameters⁠ section lists the parameters that can be configured during installation.

⁠ Uninstalling the Chart

For a graceful termination, set the replica count of the Pods in the mariadb-galera StatefulSet to 0:

kubectl scale sts my-release-mariadb-galera --replicas=0

To uninstall/delete the my-release release:

helm delete --purge my-release

The command removes all the Kubernetes components associated with the chart and deletes the release.

⁠ Configuration and installation details

This section describes credentials, configuration, and other installation options.

⁠ Resource requests and limits

Bitnami charts allow setting resource requests and limits for all containers inside the chart deployment. These are inside the resources value (check parameter table). Setting requests is essential for production workloads and these should be adapted to your specific use case.

To make this process easier, the chart contains the resourcesPreset values, which automatically sets the resources section according to different presets. Check these presets in the bitnami/common chart⁠. However, in production workloads using resourcesPreset is discouraged as it may not fully adapt to your specific needs. Find more information on container resource management in the official Kubernetes documentation⁠.

⁠ Update credentials

Bitnami charts configure credentials at first boot. Any further change in the secrets or credentials require manual intervention. Follow these instructions:

• Update the user password following the upstream documentation⁠
• Update the password secret with the new values (replace the SECRET_NAME, PASSWORD, ROOT_PASSWORD and BACKUP_PASSWORD placeholders)

kubectl create secret generic SECRET_NAME --from-literal=mariadb-root-password=ROOT_PASSWORD --from-literal=mariadb-password=PASSWORD --from-literal=mariadb-galera-mariabackup-password=BACKUP_PASSWORD --dry-run -o yaml | kubectl apply -f -

⁠ Prometheus metrics

This chart can be integrated with Prometheus by setting metrics.enabled to true. This will deploy a sidecar container with mysqld_exporter⁠ in all pods and will expose it via a metrics service configurable under the metrics.service section. This service will have the necessary annotations to be automatically scraped by Prometheus.

⁠Prometheus requirements

It is necessary to have a working installation of Prometheus or Prometheus Operator for the integration to work. Install the Bitnami Prometheus helm chart⁠ or the Bitnami Kube Prometheus helm chart⁠ to easily have a working Prometheus in your cluster.

⁠Integration with Prometheus Operator

The chart can deploy ServiceMonitor objects for integration with Prometheus Operator installations. To do so, set the value metrics.serviceMonitor.enabled=true. Ensure that the Prometheus Operator CustomResourceDefinitions are installed in the cluster or it will fail with the following error:

no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

Install the Bitnami Kube Prometheus helm chart⁠ for having the necessary CRDs and the Prometheus Operator.

⁠ Rolling VS Immutable tags⁠

It is strongly recommended to use immutable tags in a production environment. This ensures your deployment does not change automatically if the same tag is updated with a different image.

Bitnami will release a new chart updating its containers if a new version of the main container, significant changes, or critical vulnerabilities exist.

⁠ Change MariaDB version

To modify the MariaDB version used in this chart you can specify a valid image tag⁠ using the image.tag parameter. For example, image.tag=X.Y.Z. This approach is also applicable to other images like exporters.

⁠ LDAP

LDAP support can be enabled in the chart by specifying the ldap. parameters while creating a release. The following parameters should be configured to properly enable the LDAP support in the chart.

• ldap.enabled: Enable LDAP support. Defaults to false.
• ldap.uri: LDAP URL beginning in the form ldap[s]://<hostname>:<port>. No defaults.
• ldap.base: LDAP base DN. No defaults.
• ldap.binddn: LDAP bind DN. No defaults.
• ldap.bindpw: LDAP bind password. No defaults.
• ldap.bslookup: LDAP base lookup. No defaults.
• ldap.nss_initgroups_ignoreusers: LDAP ignored users. root,nslcd.
• ldap.scope: LDAP search scope. No defaults.
• ldap.filter: LDAP custom search filter. No defaults.
• ldap.map: LDAP custom map to use. No defaults.
• ldap.tls_reqcert: LDAP TLS check on server certificates. No defaults.

For example:

ldap.enabled="true"
ldap.uri="ldap://my_ldap_server"
ldap.base="dc=example,dc=org"
ldap.binddn="cn=admin,dc=example,dc=org"
ldap.bindpw="admin"
ldap.bslookup="ou=group-ok,dc=example,dc=org"
ldap.nss_initgroups_ignoreusers="root,nslcd"
ldap.scope="sub"
ldap.filter="AccountName"
ldap.map="number"
ldap.tls_reqcert="demand"

Next, login to the MariaDB server using the mysql client and add the PAM authenticated LDAP users.

For example,

CREATE USER 'bitnami'@'localhost' IDENTIFIED VIA pam USING 'mariadb';

With the above example, when the bitnami user attempts to login to the MariaDB server, he/she will be authenticated against the LDAP server.

⁠ Securing traffic using TLS

TLS support can be enabled in the chart by specifying the tls. parameters while creating a release. The following parameters should be configured to properly enable the TLS support in the chart:

• tls.enabled: Enable TLS support. Defaults to false
• tls.certificatesSecret: Name of the secret that contains the certificates. No defaults.
• tls.certFilename: Certificate filename. No defaults.
• tls.certKeyFilename: Certificate key filename. No defaults.
• tls.certCAFilename: CA Certificate filename. No defaults.

For example:

First, create the secret with the cetificates files:

kubectl create secret generic certificates-tls-secret --from-file=./cert.pem --from-file=./cert.key --from-file=./ca.pem

Then, use the following parameters:

tls.enabled="true"
tls.certificatesSecret="certificates-tls-secret"
tls.certFilename="cert.pem"
tls.certKeyFilename="cert.key"
tls.certCAFilename="ca.pem"

⁠ Initialize a fresh instance

The Bitnami MariaDB Galera⁠ image allows you to use your custom scripts to initialize a fresh instance. In order to execute the scripts, they must be located inside the chart folder files/docker-entrypoint-initdb.d so they can be consumed as a ConfigMap.

Alternatively, you can specify custom scripts using the initdbScripts parameter as dict.

In addition to these options, you can also set an external ConfigMap with all the initialization scripts. This is done by setting the initdbScriptsConfigMap parameter. Note that this will override the two previous options.

The allowed extensions are .sh, .sql and .sql.gz.

Take into account those scripts are treated differently depending on the extension. While the .sh scripts are executed in all the nodes; the .sql and .sql.gz scripts are only executed in the bootstrap node. The reason behind this differentiation is that the .sh scripts allow adding conditions to determine what is the node running the script, while these conditions can't be set using .sql nor sql.gz files. This way it is possible to cover different use cases depending on their needs.

If using a .sh script you want to do a "one-time" action like creating a database, you need to add a condition in your .sh script to be executed only in one of the nodes, such as

initdbScripts:
  my_init_script.sh: |
     #!/bin/sh
     if [[ $(hostname) == *-0  ]]; then
       echo "First node"
       mysql -P 3306 -uroot -prandompassword -e "create database new_database";
     else
       echo "No first node"
     fi

⁠ Extra Init Containers

The feature allows for specifying a template string for a initContainer in the pod. Usecases include situations when you need some pre-run setup. For example, in IKS (IBM Cloud Kubernetes Service), non-root users do not have write permission on the volume mount path for NFS-powered file storage. So, you could use a initcontainer to chown the mount. See a example below, where we add an initContainer on the pod that reports to an external resource that the db is going to starting. values.yaml

extraInitContainers:
- name: initcontainer
  image: bitnami/minideb
  command: ["/bin/sh", "-c"]
  args:
    - install_packages curl && curl http://api-service.local/db/starting;

⁠ Sidecar Containers

The feature allows for specifying additional containers in the pod. Use cases include situations when you need to run some sidecar containers. For example, you can observe if mysql in pod is running and report to some service discovery software like eureka. Example: values.yaml

sidecars:
- name: '{{ .Chart.Name }}-eureka-sidecar'
  image: 'image:tag'
  env:
  - name: SERVICE_NAME
    value: '{{ template "common.names.fullname" . }}'
  - name: EUREKA_APP_NAME
    value: '{{ template "common.names.name" . }}'
  - name: MARIADB_USER
    value: '{{ .Values.db.user }}'
  - name: MARIADB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: '{{ template "common.names.fullname" . }}'
        key: mariadb-password
  resources:
    limits:
      cpu: 100m
      memory: 20Mi
    requests:
      cpu: 50m
      memory: 10Mi

⁠ Bootstrapping a node other than 0

To restart the cluster you need to check the state in which it is after being stopped, also you will need the previous password for the rootUser and mariabackup, and the deployment name. The value of safe_to_bootstrap in /bitnami/mariadb/data/grastate.dat, will indicate if it is safe to bootstrap form that node. In the case it is other than node 0, it is needed to choose one and force the bootstrapping from it. You will notice that in these cases it is needed to start the nodes in Parallel by setting podManagementPolicy.

⁠Checking safe_to_boostrap

First you need to get the name of the persistent volume claims (pvc), for example:

$ kubectl get pvc
NAME                              STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
data-my-galera-mariadb-galera-0   Bound    pvc-a496aded-f604-4a2d-b934-174907c4d235   8Gi        RWO            gp2            25h
data-my-galera-mariadb-galera-1   Bound    pvc-00ba6121-9042-4760-af14-3b8a40de936c   8Gi        RWO            gp2            25h
data-my-galera-mariadb-galera-2   Bound    pvc-61644bc9-2d7d-4e84-bf32-35e59d909b05   8Gi        RWO            gp2            25h

The following command will print the content of grastate.dat for the persistent volume claim data-my-galera-mariadb-galera-2. This needs to be run for each of the pvc. You will need to change this name accordingly with yours for each PVC.

$ kubectl run -i --rm --tty volpod --overrides='
{
    "apiVersion": "v1",
    "kind": "Pod",
    "metadata": {
        "name": "volpod"
    },
    "spec": {
        "containers": [{
            "command": [
                "cat",
                "/mnt/data/grastate.dat"
            ],
            "image": "bitnami/minideb",
            "name": "mycontainer",
            "volumeMounts": [{
                "mountPath": "/mnt",
                "name": "galeradata"
            }]
        }],
        "restartPolicy": "Never",
        "volumes": [{
            "name": "galeradata",
            "persistentVolumeClaim": {
                "claimName": "data-my-galera-mariadb-galera-2"
            }
        }]
    }
}' --image="bitnami/minideb"

The output should be similar to this:

# GALERA saved state
version: 2.1
uuid:    6f2cbfcd-951b-11ea-a116-5f407049e57d
seqno:   25
safe_to_bootstrap: 1

There are two possible scenarios:

⁠Only one node with safe_to_bootstrap: 1

In this case you will need the node number N and run:

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/mariadb-galera \
--set rootUser.password=XXXX \
--set galera.mariabackup.password=YYYY \
--set galera.bootstrap.forceBootstrap=true \
--set galera.bootstrap.bootstrapFromNode=N \
--set podManagementPolicy=Parallel

⁠All the nodes with safe_to_bootstrap: 0

In this case the cluster was not stopped cleanly and you need to pick one to force the bootstrap from. The one to be chosen in the one with the highest seqno in /bitnami/mariadb/data/grastate.dat. The following example shows how to force bootstrap from node 3.

helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/mariadb-galera \
--set rootUser.password=XXXX \
--set galera.mariabackup.password=YYYY \
--set galera.bootstrap.forceBootstrap=true \
--set galera.bootstrap.bootstrapFromNode=3 \
--set galera.bootstrap.forceSafeToBootstrap=true \
--set podManagementPolicy=Parallel

⁠Remove the forced boostraping

After you have started the cluster by forcing the bootstrapping on one of the nodes, you will need to remove the forcing so the node can restart with normality.

helm upgrade my-release oci://REGISTRY_NAME/REPOSITORY_NAME/mariadb-galera \
--set rootUser.password=XXXX \
--set galera.mariabackup.password=YYYY \
--set podManagementPolicy=Parallel

⁠ Backup and restore

Two different approaches are available to back up and restore Bitnami MariaDB Galera Helm chart deployments on Kubernetes:

• Back up the data from the source deployment and restore it in a new deployment using MariaDB Galera built-in backup/restore tools.
• Back up the persistent volumes from the source deployment and attach them to a new deployment using Velero, a Kubernetes backup/restore tool.

⁠Method 1: Backup and restore data using MariaDB Galera built-in tools

This method involves the following steps:

• Use the mysqldump tool to create a snapshot of the data in the source cluster.
• Create a new MariaDB Galera Cluster deployment and forward the MariaDB Galera Cluster service port for the new deployment.
• Create and start a MariaDB Galera container image to mount a directory containing the backup file as a volume.
• Restore the data using the mysql client tool to import the backup to the new cluster.

⁠Method 2: Back up and restore persistent data volumes

This method involves copying the persistent data volumes for the MariaDB Galera nodes and reusing them in a new deployment with Velero⁠, an open source Kubernetes backup/restore tool. This method is only suitable when:

• The Kubernetes provider is supported by Velero⁠.
• Both clusters are on the same Kubernetes provider, as this is a requirement of Velero's native support for migrating persistent volumes⁠.
• The restored deployment on the destination cluster will have the same name, namespace, topology and credentials as the original deployment on the source cluster.

This method involves the following steps:

• Install Velero on the source and destination clusters.
• Use Velero to back up the PersistentVolumes (PVs) used by the deployment on the source cluster.
• Use Velero to restore the backed-up PVs on the destination cluster.
• Create a new deployment on the destination cluster with the same chart, deployment name, credentials and other parameters as the original. This new deployment will use the restored PVs and hence the original data.

Refer to our detailed tutorial on backing up and restoring MariaDB Galera chart deployments on Kubernetes⁠, which covers both these approaches, for more information.

⁠ Setting Pod's affinity

This chart allows you to set your custom affinity using the affinity parameter. Find more information about Pod's affinity in the kubernetes documentation⁠.

As an alternative, you can use of the preset configurations for pod affinity, pod anti-affinity, and node affinity available at the bitnami/common⁠ chart. To do so, set the podAffinityPreset, podAntiAffinityPreset, or nodeAffinityPreset parameters.

⁠ FIPS parameters

The FIPS parameters only have effect if you are using images from the Bitnami Secure Images catalog⁠.

For more information on this new support, please refer to the FIPS Compliance section⁠.

⁠ Persistence

The Bitnami MariaDB Galera⁠ image stores the MariaDB data and configurations at the /bitnami/mariadb path of the container.

The chart mounts a Persistent Volume⁠ volume at this location. The volume is created using dynamic volume provisioning, by default. An existing PersistentVolumeClaim can be defined.

⁠ Parameters

The following subsections list global, common, and component-specific parameters.

⁠ Global parameters

Note: the README for this chart is longer than the DockerHub length limit of 25000, so it has been trimmed. The full README can be found at https://techdocs.broadcom.com/us/en/vmware-tanzu/bitnami-secure-images/bitnami-secure-images/services/bsi-app-doc/apps-charts-mariadb-galera-index.html⁠