Skip to content
Mariadb icon
v2.2.2App: v13.0.2Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

MariaDB Helm Chart

Helm chart for deploying MariaDB on Kubernetes using the official mariadb Docker image. Supports standalone and GTID-based replication architectures.

Breaking Change in 2.0.0

MariaDB now mounts /var/lib/mysql from the data volume subdirectory configured by persistence.subPath instead of the volume root. The default is mysql. This prevents ext4-backed PVCs from exposing the filesystem-created lost+found directory to MariaDB as a candidate database.

Existing installations whose data already lives at the volume root must set the legacy value during upgrade:

persistence:
  subPath: ""

Alternatively, migrate the existing volume-root data into the mysql subdirectory before upgrading.

Supported Architectures

Architecture Description
standalone Single MariaDB instance with persistent storage (default)
replication One fixed source with asynchronous GTID-based read replicas

Features

  • Official MariaDB image from Docker Hub
  • Standalone and replication modes with explicit configuration
  • GTID-based replication using MariaDB-native GTID (MASTER_USE_GTID=slave_pos)
  • Configuration presets small, medium, large, oltp, read-heavy, analytics
  • Resource presets small, medium, large for easy right-sizing
  • Init scripts support via ConfigMap or inline values
  • TLS server-side encryption with optional client enforcement
  • Prometheus metrics via mysqld-exporter sidecar and ServiceMonitor
  • S3-compatible backup CronJob with mariadb-dump and minio/mc upload
  • NetworkPolicy for ingress traffic control
  • PodDisruptionBudget for availability during maintenance
  • Datadir subPath isolation to keep ext4 lost+found out of MariaDB logs
  • Password management auto-generated or from existing Secret
  • Dual-stack networking — IPv4/IPv6 service support across all 6 Service objects
  • External Secrets Operator — ExternalSecret for Vault, AWS Secrets Manager, and more

Installation

HTTPS Repository

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install mariadb helmforge/mariadb

OCI Registry

helm install mariadb oci://ghcr.io/helmforgedev/helm/mariadb

Examples

The repository includes complete examples for standalone, replication, production replication, and legacy volume-root upgrades under examples/. The smallest architecture overrides are:

Architecture selection

# Standalone (default)
architecture: standalone

# Replication with 2 read replicas
architecture: replication
replication:
  readReplicas:
    replicaCount: 2
Official Schema

Values & Configuration Reference

All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.

View Values Schema

|-----|---------|-------------| | architecture | standalone | Deployment mode: standalone or replication | | image.repository | mariadb | MariaDB image | | image.tag | 13.0.2 | MariaDB version | | auth.rootPassword | "" | Root password (auto-generated if empty) | | auth.database | app | Application database | | auth.username | app | Application user | | auth.password | "" | Application password (auto-generated if empty) | | auth.replicationUsername | replicator | Replication user | | auth.existingSecret | "" | Existing secret with passwords | | config.preset | none | Configuration preset | | config.myCnf | "" | Extra my.cnf content | | persistence.subPath | mysql | Data volume subdirectory mounted as /var/lib/mysql; set "" for legacy volume-root installs | | persistence.prepareDataDir.enabled | false | Opt-in root initContainer for storage drivers that do not honor fsGroup; incompatible with Pod Security restricted | | standalone.resourcesPreset | small | Default standalone resource requests and limits | | standalone.persistence.size | 8Gi | Standalone PVC size | | replication.source.resourcesPreset | small | Default source resource requests and limits | | replication.source.persistence.size | 20Gi | Source PVC size | | replication.source.affinity | {} | Affinity for the source pod | | replication.source.tolerations | [] | Tolerations for the source pod | | replication.readReplicas.replicaCount | 2 | Number of read replicas | | replication.readReplicas.resourcesPreset | small | Default replica resource requests and limits | | replication.readReplicas.persistence.size | 20Gi | Replica PVC size | | replication.readReplicas.affinity | {} | Affinity for the replica pods | | replication.readReplicas.tolerations | [] | Tolerations for the replica pods | | replication.binlog.format | ROW | Binlog format | | service.type | ClusterIP | Service type | | service.port | 3306 | MariaDB port | | metrics.enabled | false | Enable mysqld-exporter | | tls.enabled | false | Enable server TLS | | backup.enabled | false | Enable S3 backup CronJob | | backup.schedule | "0 3 * * *" | Backup cron schedule | | networkPolicy.enabled | false | Enable NetworkPolicy | | pdb.enabled | false | Enable PodDisruptionBudget | | service.ipFamilyPolicy | ~ | IP family policy (SingleStack, PreferDualStack, RequireDualStack) | | service.ipFamilies | [] | IP families override (IPv4, IPv6) | | extraObjects | [] | Extra Kubernetes manifests rendered with the release | | externalSecrets.enabled | false | Render ExternalSecret resource | | externalSecrets.apiVersion | external-secrets.io/v1 | ExternalSecret API version | | externalSecrets.refreshInterval | 1h | Refresh interval | | externalSecrets.secretStoreRef.name | "" | SecretStore name (required when enabled) | | externalSecrets.secretStoreRef.kind | SecretStore | SecretStore kind | | externalSecrets.data | [] | Remote key mappings |

Dual-Stack Services

MariaDB 13.0.2 is the stable GA release of the 13.0 rolling line. It adds atomic CREATE OR REPLACE TABLE, single-table UPDATE ... RETURNING, InnoDB log archiving and new routine types. Back up databases and validate startup, replication, application compatibility and restore behavior before this major upgrade. mariadb-backup does not support the new log-archive format while innodb_log_archive=ON.

All 6 Service objects (client, metrics, source, source-metrics, replicas, replicas-metrics) carry the same ipFamilyPolicy and ipFamilies settings.

service:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv4
    - IPv6

Datadir SubPath and lost+found

Kubernetes storage classes often format PVCs as ext4. ext4 creates lost+found at the filesystem root, and MariaDB scans every datadir subdirectory as a database. Mounting the PVC root at /var/lib/mysql can therefore produce this non-fatal but noisy log line:

Invalid (old?) table or database name 'lost+found'

The chart avoids that on new installs by mounting the mysql subdirectory as the datadir:

persistence:
  subPath: mysql

For existing installations with data at the PVC root, keep the legacy behavior:

persistence:
  subPath: ""

See docs/datadir-subpath.md for upgrade guidance.

By default, the chart does not render a root initContainer for persistence.subPath. It relies on podSecurityContext.fsGroup and fsGroupChangePolicy: OnRootMismatch, which keeps the default path compatible with Pod Security restricted.

Only enable persistence.prepareDataDir.enabled=true for storage drivers that do not honor fsGroup for subPath directories. That opt-in path runs as root with CHOWN and FOWNER and requires a namespace-level Pod Security exception.

External Secrets Operator (ESO)

auth.existingSecret is required alongside externalSecrets.enabled=true to prevent credential drift between the chart-managed Secret and the ExternalSecret.

auth:
  existingSecret: mariadb-credentials

externalSecrets:
  enabled: true
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  data:
    - secretKey: mariadb-root-password
      remoteRef:
        key: mariadb/credentials
        property: root-password
    - secretKey: mariadb-user-password
      remoteRef:
        key: mariadb/credentials
        property: user-password

Differences from MySQL Chart

This chart uses MariaDB-native features:

  • GTID replication uses MASTER_USE_GTID=slave_pos (MariaDB GTID is always enabled, no gtid_mode toggle)
  • Commands use mariadb, mariadb-admin, mariadb-dump (not mysql, mysqladmin, mysqldump)
  • Environment variables use MARIADB_* prefix (not MYSQL_*)
  • Replication uses CHANGE MASTER TO with MariaDB-specific options
  • No mysqlx protocol (MySQL-specific)

CI Scenarios

File Description
standalone.yaml Basic standalone mode
replication.yaml Replication with 2 replicas
initdb.yaml Init scripts with example table
existing-secret.yaml External secret reference
metrics.yaml Metrics sidecar enabled
replication-metrics.yaml Replication with metrics
config-preset.yaml OLTP config preset
resources-preset.yaml Resource presets for replication
legacy-volume-root.yaml Legacy datadir mount for existing volume-root installs
tls.yaml TLS with existingSecret
tls-networkpolicy.yaml TLS + replication + NetworkPolicy
backup.yaml Backup with S3
dual-stack.yaml Dual-stack service policy
external-secrets.yaml External Secrets Operator integration

Troubleshooting

Inspect the StatefulSet, MariaDB logs, and recent namespace events before changing probes or credentials:

kubectl get statefulset,pod,pvc,service -l app.kubernetes.io/instance=<release>
kubectl logs -l app.kubernetes.io/instance=<release> --all-containers --tail=200 --prefix
kubectl get events --sort-by=.lastTimestamp
  • If MariaDB reports lost+found as a database, preserve an existing volume-root installation with persistence.subPath: ""; see docs/datadir-subpath.md.
  • If a replica stays unready, verify that the source is writable, the replication credentials are stable, and both replication threads are running before enabling requireRunningReplication.
  • If the metrics sidecar cannot connect, verify the password Secret and keep tls.client.enabled aligned with the server TLS configuration.
  • If a NetworkPolicy is enabled, allow application traffic on service.port. Metrics scraping requires both metrics.enabled: true and networkPolicy.metrics.enabled: true; configure networkPolicy.metrics.extraFrom with the permitted scraper sources.

More Information

Security Scan: mariadb

Framework Score
MITRE + NSA + SOC2 89.898994%

Security posture acceptable.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
  app[Application pods] --> svc[Client Service]
  svc --> db[MariaDB StatefulSet pod-0]
  db --> pvc[(PVC)]
  db --> cfg[Generated my.cnf]
  db --> secret[Password Secret]
  eso[External Secrets Operator optional] -. materializes .-> secret
Official Contractvalues.schema.json

Mariadb Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

173 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global settings shared by the chart.

Architecture(1)

ParameterTypeDefaultDescription
architecturestring-MariaDB deployment mode
Allowed:standalonereplication

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Override chart name

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Override full release name

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Labels added to all resources

Cluster Domain(1)

ParameterTypeDefaultDescription
clusterDomainstring-Kubernetes cluster domain

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Image pull secrets

Authentication(10)

ParameterTypeDefaultDescription
auth.rootPasswordstring-Chart configuration parameter
auth.databasestring-Chart configuration parameter
auth.usernamestring-Chart configuration parameter
auth.passwordstring-Chart configuration parameter
auth.replicationUsernamestring-Chart configuration parameter
auth.replicationPasswordstring-Chart configuration parameter
auth.existingSecretstring-Chart configuration parameter
auth.existingSecretRootPasswordKeystring-Chart configuration parameter
auth.existingSecretUserPasswordKeystring-Chart configuration parameter
auth.existingSecretReplicationPasswordKeystring-Chart configuration parameter

Configuration(2)

ParameterTypeDefaultDescription
config.presetstring-Chart configuration parameter
Allowed:nonesmallmediumlargeoltpread-heavyanalytics
config.myCnfstring-Chart configuration parameter

Initdb(2)

ParameterTypeDefaultDescription
initdb.scriptsobject-Chart configuration parameter
initdb.existingConfigMapstring-Chart configuration parameter

Persistence(2)

ParameterTypeDefaultDescription
persistence.subPathstring-Subdirectory of the data volume mounted as /var/lib/mysql. Empty string preserves legacy volume-root behavior.
persistence.prepareDataDir.enabledbooleanfalseEnable the root prepare-datadir-subpath initContainer. Incompatible with Pod Security restricted.

Standalone(7)

ParameterTypeDefaultDescription
standalone.serverIdinteger-Chart configuration parameter
standalone.resourcesPresetstring-Chart configuration parameter
Allowed:nonesmallmediumlarge
standalone.persistence.enabledboolean-Chart configuration parameter
standalone.persistence.storageClassstring-Chart configuration parameter
standalone.persistence.accessModesarray-Chart configuration parameter
standalone.persistence.sizestring-Chart configuration parameter
standalone.resourcesobject-Chart configuration parameter

Replication(33)

ParameterTypeDefaultDescription
replication.source.serverIdinteger-Chart configuration parameter
replication.source.resourcesPresetstring-Chart configuration parameter
Allowed:nonesmallmediumlarge
replication.source.persistence.enabledboolean-Chart configuration parameter
replication.source.persistence.storageClassstring-Chart configuration parameter
replication.source.persistence.accessModesarray-Chart configuration parameter
replication.source.persistence.sizestring-Chart configuration parameter
replication.source.resourcesobject-Chart configuration parameter
replication.source.probes.requireWritableboolean-Chart configuration parameter
replication.source.affinityobject-Chart configuration parameter
replication.source.tolerationsarray-Chart configuration parameter
replication.readReplicas.serverIdBaseinteger-Chart configuration parameter
replication.readReplicas.resourcesPresetstring-Chart configuration parameter
Allowed:nonesmallmediumlarge
replication.readReplicas.replicaCountinteger-Chart configuration parameter
replication.readReplicas.persistence.enabledboolean-Chart configuration parameter
replication.readReplicas.persistence.storageClassstring-Chart configuration parameter
replication.readReplicas.persistence.accessModesarray-Chart configuration parameter
replication.readReplicas.persistence.sizestring-Chart configuration parameter
replication.readReplicas.resourcesobject-Chart configuration parameter
replication.readReplicas.probes.requireReadOnlyboolean-Chart configuration parameter
replication.readReplicas.probes.requireRunningReplicationboolean-Chart configuration parameter
replication.readReplicas.affinityobject-Chart configuration parameter
replication.readReplicas.tolerationsarray-Chart configuration parameter
replication.binlog.formatstring-Chart configuration parameter
Allowed:ROWSTATEMENTMIXED
replication.binlog.retentionDaysinteger-Chart configuration parameter
replication.binlog.expireLogsSecondsinteger-Chart configuration parameter
replication.binlog.syncBinloginteger-Chart configuration parameter
replication.replicaTuning.parallelWorkersinteger-Chart configuration parameter
replication.pdb.enabledboolean-Chart configuration parameter
replication.pdb.minAvailableintegerstring-Chart configuration parameter
replication.pdb.maxUnavailableintegerstring-Chart configuration parameter
replication.scheduling.enableDefaultPodAntiAffinityboolean-Chart configuration parameter
replication.scheduling.enableDefaultTopologySpreadboolean-Chart configuration parameter
replication.scheduling.topologyKeystring-Chart configuration parameter

Service & Networking(8)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.metricsPortinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.sourceAnnotationsobject-Chart configuration parameter
service.replicasAnnotationsobject-Chart configuration parameter
service.ipFamilyPolicystringnull-Chart configuration parameter
Allowed:nullSingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Chart configuration parameter

Metrics & Observability(10)

ParameterTypeDefaultDescription
metrics.enabledboolean-Chart configuration parameter
metrics.resourcesPresetstring-Chart configuration parameter
Allowed:nonesmallmedium
metrics.service.annotationsobject-Chart configuration parameter
metrics.image.repositorystring-Chart configuration parameter
metrics.image.tagstring-Chart configuration parameter
metrics.image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
metrics.resourcesobject-Chart configuration parameter
metrics.serviceMonitor.enabledboolean-Chart configuration parameter
metrics.serviceMonitor.intervalstring-Chart configuration parameter
metrics.serviceMonitor.labelsobject-Chart configuration parameter

TLS(8)

ParameterTypeDefaultDescription
tls.enabledboolean-Chart configuration parameter
tls.existingSecretstring-Chart configuration parameter
tls.caFilenamestring-Chart configuration parameter
tls.certFilenamestring-Chart configuration parameter
tls.keyFilenamestring-Chart configuration parameter
tls.requireSecureTransportboolean-Chart configuration parameter
tls.client.enabledboolean-Chart configuration parameter
tls.client.sslboolean-Chart configuration parameter

Backup(25)

ParameterTypeDefaultDescription
backup.enabledboolean-Chart configuration parameter
backup.schedulestring-Chart configuration parameter
backup.suspendboolean-Chart configuration parameter
backup.concurrencyPolicystring-Chart configuration parameter
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger-Chart configuration parameter
backup.failedJobsHistoryLimitinteger-Chart configuration parameter
backup.backoffLimitinteger-Chart configuration parameter
backup.archivePrefixstring-Chart configuration parameter
backup.resourcesobject-Chart configuration parameter
backup.images.uploader.repositorystring-Chart configuration parameter
backup.images.uploader.tagstring-Chart configuration parameter
backup.images.uploader.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.images.mariadb.repositorystring-Chart configuration parameter
backup.images.mariadb.tagstring-Chart configuration parameter
backup.images.mariadb.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
backup.s3.endpointstring-Chart configuration parameter
backup.s3.bucketstring-Chart configuration parameter
backup.s3.prefixstring-Chart configuration parameter
backup.s3.createBucketIfNotExistsboolean-Chart configuration parameter
backup.s3.existingSecretstring-Chart configuration parameter
backup.s3.existingSecretAccessKeyKeystring-Chart configuration parameter
backup.s3.existingSecretSecretKeyKeystring-Chart configuration parameter
backup.s3.accessKeystring-Chart configuration parameter
backup.s3.secretKeystring-Chart configuration parameter
backup.database.mariadbdumpArgsstring-Chart configuration parameter

Network Policy(6)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.ingress.allowSameNamespaceboolean-Chart configuration parameter
networkPolicy.ingress.extraFromarray-Chart configuration parameter
networkPolicy.metrics.enabledboolean-Chart configuration parameter
networkPolicy.metrics.allowSameNamespaceboolean-Chart configuration parameter
networkPolicy.metrics.extraFromarray-Chart configuration parameter

Pdb(3)

ParameterTypeDefaultDescription
pdb.enabledboolean-Chart configuration parameter
pdb.minAvailableintegerstring-Chart configuration parameter
pdb.maxUnavailableintegerstring-Chart configuration parameter

Service Account(3)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter

Liveness Probe(5)

ParameterTypeDefaultDescription
livenessProbe.enabledboolean-Chart configuration parameter
livenessProbe.initialDelaySecondsinteger-Chart configuration parameter
livenessProbe.periodSecondsinteger-Chart configuration parameter
livenessProbe.timeoutSecondsinteger-Chart configuration parameter
livenessProbe.failureThresholdinteger-Chart configuration parameter

Readiness Probe(5)

ParameterTypeDefaultDescription
readinessProbe.enabledboolean-Chart configuration parameter
readinessProbe.initialDelaySecondsinteger-Chart configuration parameter
readinessProbe.periodSecondsinteger-Chart configuration parameter
readinessProbe.timeoutSecondsinteger-Chart configuration parameter
readinessProbe.failureThresholdinteger-Chart configuration parameter

Startup Probe(5)

ParameterTypeDefaultDescription
startupProbe.enabledboolean-Chart configuration parameter
startupProbe.initialDelaySecondsinteger-Chart configuration parameter
startupProbe.periodSecondsinteger-Chart configuration parameter
startupProbe.timeoutSecondsinteger-Chart configuration parameter
startupProbe.failureThresholdinteger-Chart configuration parameter

Pod Security(3)

ParameterTypeDefaultDescription
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicystring-Chart configuration parameter
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfile.typestring-Chart configuration parameter
Allowed:RuntimeDefaultLocalhostUnconfined

Container Security(6)

ParameterTypeDefaultDescription
securityContext.runAsUserinteger-Chart configuration parameter
securityContext.runAsGroupinteger-Chart configuration parameter
securityContext.runAsNonRootboolean-Chart configuration parameter
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Annotations(1)

ParameterTypeDefaultDescription
annotationsobject-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Extra Env(1)

ParameterTypeDefaultDescription
extraEnvarray-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Objects(1)

ParameterTypeDefaultDescription
extraObjectsarray[]Chart configuration parameter

External Secrets(7)

ParameterTypeDefaultDescription
externalSecrets.enabledbooleanfalseChart configuration parameter
externalSecrets.apiVersionstringexternal-secrets.io/v1Chart configuration parameter
externalSecrets.refreshIntervalstring1hChart configuration parameter
externalSecrets.secretStoreRef.namestring-Chart configuration parameter
externalSecrets.secretStoreRef.kindstringSecretStoreChart configuration parameter
Allowed:SecretStoreClusterSecretStore
externalSecrets.target.creationPolicystringOwnerChart configuration parameter
Allowed:OwnerMergeNoneOrphan
externalSecrets.dataarray-Chart configuration parameter