Mariadb Operator

MariaDB Operator CRDs

Repository: github.com/mariadb-operator/mariadb-operator
Latest release: v26.6.0 (Jun 5, 2026)
API version: k8s.mariadb.com/v1alpha1
CRDs: 12
Kubernetes: >=1.26
Go: 1.26, controller-runtime 0.23.3

Overview

MariaDB CR ──► StatefulSet with Galera HA
MaxScale CR ──► MaxScale proxy Deployment (read/write splitting)
  │
Database CR ──► Database creation
User CR ──► User creation + password rotation
Grant CR ──► Privilege assignment
  │
Backup CR ──► Scheduled backups (S3/Azure/Volume)
PhysicalBackup CR ──► Physical snapshot backups
Restore CR ──► Restore from backup
PointInTimeRecovery CR ──► PITR to specific timestamp
  │
Connection CR ──► Connection string in Secret
SqlJob CR ──► Scheduled SQL execution
  │
ExternalMariaDB CR ──► Connect to external MariaDB instances

CRDs

MariaDB

The primary CRD defining a MariaDB Galera cluster.

apiVersion: k8s.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-cluster
spec:
  # Image (v26.3.0+: image.repo + image.tag split)
  image:
    repository: mariadb
    tag: 11.8.8

  # Galera HA
  galera:
    enabled: true
    primary:
      podIndex: 0
      automaticFailover: true
    config:
      reuseStorageVolume: false
      # Additional galera config
    init:
      job:
        image:
          repository: mariadb
          tag: 11.8.8
      resources: {}

  # Volume claim
  storage:
    size: 10Gi
    storageClassName: standard
    # accessModes:
    #   - ReadWriteOnce
    #   - ReadWriteMany
    #   - ReadOnlyMany
    #   - ReadWriteOncePod
    resizeInUseVolumes: true
    waitForVolume:
      enabled: false

  # Replicas
  replicas: 3

  # Service
  service:
    type: ClusterIP
    # Additional service template

  # Connection
  rootPasswordSecretKeyRef:
    name: mariadb-root
    key: password
    # generate: true  # auto-generate
  username: ""
  passwordSecretKeyRef: {}
  database: ""

  # Metrics
  metrics:
    enabled: true
    exporter:
      image:
        repository: prom/mysqld-exporter
        tag: v0.15.1
      resources: {}

  # Connection pool
  connectionPool:
    port: 3306
    maxConnections: 100
    minPoolSize: 1

  # Update strategy
  updateStrategy:
    type: RollingUpdate
    autoSwapPvc:
      - statefulset-1

  # Pod spec
  podAnnotations: {}
  imagePullSecrets: []
  priorityClassName: ""
  affinity: {}
  tolerations: []
  nodeSelector: {}
  topologySpreadConstraints: []

  # Resource limits
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi

  # TLS
  tls:
    enabled: false
    # ssl:
    #   secretName: mariadb-tls
    #   caSecretName: mariadb-ca
    # clientCertSecretName: mariadb-client

  # MaxScale reference
  maxScaleRef: {}

  # Replication
  replication:
    # Source connection ref for replica
    source: {}

  # Maintenance
  maintenance:
    enabled: false
    # Requeue interval during maintenance
    requeueInterval: 30s

  # HA
  ha:
    enable: true
    cert: {}
  #   cert:
  #     certManager:
  #       enabled: true
  #       duration: 2160h

  # Default configuration
  myCnf: |
    [mysqld]
    character-set-server=utf8mb4
    collation-server=utf8mb4_unicode_ci
    max_connections=100

  # PodDisruptionBudget
  podDisruptionBudget:
    enabled: true
    maxUnavailable: 1

  # Progress deadlines
  progressDeadlineSeconds: 600

Spec Fields

MaxScale

MariaDB MaxScale proxy for read/write splitting and connection routing.

apiVersion: k8s.mariadb.com/v1alpha1
kind: MaxScale
metadata:
  name: maxscale
spec:
  image:
    repository: mariadb/maxscale
    tag: 23.08.5

  replicas: 2

  # MariaDB reference
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  # Configuration
  config:
    maxscale:
      # global MaxScale config
      admin_host: 0.0.0.0
      admin_port: 8989
    servers:
      - address: mariadb-cluster
        port: 3306
        protocol: MariaDBBackend
    monitors:
      - module: galeramon
        servers:
          - mariadb-cluster
        user: maxscale
        password: maxscale
    services:
      - router: readwritesplit
        servers:
          - mariadb-cluster
        user: maxscale
        password: maxscale
    listeners:
      - protocol: MariaDBClient
        service: readwritesplit
        port: 3306
      - protocol: HTTP
        service: restapi
        port: 8989

  # Authentication
  auth:
    adminUsername: admin
    adminPasswordSecretKeyRef:
      name: maxscale-admin
      key: password
    # serverCredentials:
    #   - user: maxscale
    #     passwordSecretKeyRef:
    #       name: maxscale
    #       key: password

  # Metrics
  metrics:
    enabled: true
    exporter:
      image:
        repository: mariadb/maxscale-prometheus-exporter-ubi
        tag: v0.0.1
      resources: {}

  # Kubernetes Service
  kubernetesService:
    type: LoadBalancer
    annotations: {}
    metadata: {}

  # Services (non-K8s, MaxScale internal services)
  services:
    - name: restapi
      router: restapi
      port: 8989

  # TLS
  tls:
    enabled: false

  # Resources
  resources:
    requests:
      cpu: 200m
      memory: 256Mi

  # Pod spec
  affinity: {}
  tolerations: []
  nodeSelector: {}
  priorityClassName: ""
  podAnnotations: {}
  updateStrategy: {}

  # MaxScale configuration without full override
  # Use config overrides vs full config

Spec Fields

Backup

Scheduled logical backups.

apiVersion: k8s.mariadb.com/v1alpha1
kind: Backup
metadata:
  name: backup-s3
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true
    waitForItTimeout: 30s

  schedule:
    cron: "0 */6 * * *"
    suspend: false
    # immediate: true

  compression: gzip
  maxRetention: 720h  # 30 days

  storage:
    s3:
      bucket: mariadb-backups
      prefix: prod
      endpoint: s3.eu-west-1.amazonaws.com
      region: eu-west-1
      accessKeyIdSecretKeyRef:
        name: s3-credentials
        key: access-key-id
      secretAccessKeySecretKeyRef:
        name: s3-credentials
        key: secret-access-key
      tls:
        enabled: true
        caSecretKeyRef:
          name: s3-ca
          key: ca.crt

  # Also supports Azure Blob:
  # storage:
  #   azure:
  #     containerName: backups
  #     storageAccount: myaccount
  #     accessKeySecretKeyRef:
  #       name: azure-credentials
  #       key: access-key

  # Or emptyDir volume:
  # storage:
  #   volumes:
  #     persistentVolumeClaim:
  #       claimName: backup-pvc

  # Backup job resources
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi

  # Log level
  logLevel: info

Spec Fields

PhysicalBackup

Physical snapshot backup (filesystem-level, faster restore).

apiVersion: k8s.mariadb.com/v1alpha1
kind: PhysicalBackup
metadata:
  name: physical-backup-s3
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  schedule:
    cron: "0 0 * * *"
    suspend: false
    immediate: false

  compression: gzip
  maxRetention: 720h  # 30 days

  storage:
    s3:
      bucket: mariadb-physical-backups
      prefix: prod
      endpoint: s3.eu-west-1.amazonaws.com
      region: eu-west-1
      accessKeyIdSecretKeyRef:
        name: s3-credentials
        key: access-key-id
      secretAccessKeySecretKeyRef:
        name: s3-credentials
        key: secret-access-key

  resources:
    requests:
      cpu: 200m
      memory: 256Mi

Spec Fields

Same as Backup but for physical snapshots. Uses mariadb-backup tool internally. Faster to restore than logical Backup.

Restore

Restore a MariaDB from a Backup.

apiVersion: k8s.mariadb.com/v1alpha1
kind: Restore
metadata:
  name: restore-from-backup
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  backupRef:
    name: backup-s3

  # OR restore from PhysicalBackup:
  # physicalBackupRef:
  #   name: physical-backup-s3

  resources:
    requests:
      cpu: 200m
      memory: 256Mi

Spec Fields

PointInTimeRecovery

Recover to a specific timestamp.

apiVersion: k8s.mariadb.com/v1alpha1
kind: PointInTimeRecovery
metadata:
  name: pitr-recovery
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  backupRef:
    name: backup-s3

  targetRecoveryTime: "2026-06-10T14:30:00Z"

  resources:
    requests:
      cpu: 200m
      memory: 256Mi

Spec Fields

Database

Create a database within a MariaDB instance.

apiVersion: k8s.mariadb.com/v1alpha1
kind: Database
metadata:
  name: app-db
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  name: myapp
  characterSet: utf8mb4
  collate: utf8mb4_unicode_ci

  cleanupPolicy: Delete  # Delete | Skip

  requeueInterval: 30s
  retryInterval: 5s

Spec Fields

User

Create a database user.

apiVersion: k8s.mariadb.com/v1alpha1
kind: User
metadata:
  name: app-user
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  name: myapp
  passwordSecretKeyRef:
    name: app-password
    key: password
  # generate: true   # auto-generate password
  # passwordRotation:  # v26.6.0+
  #   enabled: true
  #   rotationInterval: 720h

  maxUserConnections: 30
  host: "%"

  cleanupPolicy: Delete
  requeueInterval: 30s
  retryInterval: 5s

Spec Fields

Grant

Assign privileges to a user on a database.

apiVersion: k8s.mariadb.com/v1alpha1
kind: Grant
metadata:
  name: app-grant
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  privileges:
    - "ALL PRIVILEGES"
  database: "myapp"
  table: "*"
  username: myapp
  grantOption: true
  host: "%"

  cleanupPolicy: Delete
  requeueInterval: 30s
  retryInterval: 5s

Spec Fields

Connection

Expose a connection string as a Kubernetes Secret.

apiVersion: k8s.mariadb.com/v1alpha1
kind: Connection
metadata:
  name: app-connection
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  host: mariadb-cluster
  port: 3306
  userName: myapp
  passwordSecretKeyRef:
    name: app-password
    key: password
  database: myapp

  # Template for the connection string
  # template: "mysql://{{ .userName }}:{{ .password }}@{{ .host }}:{{ .port }}/{{ .database }}"

  # Secret name to output
  secretName: app-dsn

  # Health check
  healthCheck:
    interval: 30s
    retryInterval: 5s

Spec Fields

SqlJob

Execute SQL statements, optionally on a schedule.

apiVersion: k8s.mariadb.com/v1alpha1
kind: SqlJob
metadata:
  name: migrate-schema
spec:
  mariaDbRef:
    name: mariadb-cluster
    waitForIt: true

  # One-time execution
  sql: |
    CREATE TABLE IF NOT EXISTS migrations (
      id INT AUTO_INCREMENT PRIMARY KEY,
      name VARCHAR(255) NOT NULL,
      applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    );

  # OR from a ConfigMap:
  # sqlConfigMapKeyRef:
  #   name: migration-sql
  #   key: migrate.sql

  # OR on a schedule:
  # schedule:
  #   cron: "0 0 * * 0"

  # Arguments:
  args: []

  # Database and user context
  database: myapp
  username: myapp
  passwordSecretKeyRef:
    name: app-password
    key: password

  # Log level
  logLevel: info

  resources:
    requests:
      cpu: 100m
      memory: 64Mi

  # Retry
  retryInterval: 5s

Spec Fields

ExternalMariaDB

Connect to an external (out-of-cluster) MariaDB instance.

apiVersion: k8s.mariadb.com/v1alpha1
kind: ExternalMariaDB
metadata:
  name: external-db
spec:
  # Connection parameters
  host: db.example.com
  port: 3306
  username: admin
  passwordSecretKeyRef:
    name: external-db-creds
    key: password

  # TLS
  tls:
    enabled: true
    caSecretKeyRef:
      name: external-db-ca
      key: ca.crt

  # Connection pool
  connectionPool:
    port: 3307
    maxConnections: 50

  # Used by MaxScale, Backup, SqlJob as a valid mariaDbRef target

Spec Fields

V26.3.0 Config Format Change

Before v26.3.0, MariaDB image was specified as a single string:

# OLD (pre-v26.3.0)
spec:
  image: mariadb:11.8.8

From v26.3.0+, image is split:

# NEW (v26.3.0+)
spec:
  image:
    repository: mariadb
    tag: 11.8.8

Common Patterns

MariaDB with MaxScale

# MariaDB
apiVersion: k8s.mariadb.com/v1alpha1
kind: MariaDB
metadata:
  name: mariadb-cluster
spec:
  image:
    repository: mariadb
    tag: 11.8.8
  galera:
    enabled: true
  replicas: 3
  storage:
    size: 10Gi
  metrics:
    enabled: true
---
# MaxScale
apiVersion: k8s.mariadb.com/v1alpha1
kind: MaxScale
metadata:
  name: maxscale
spec:
  mariaDbRef:
    name: mariadb-cluster
  replicas: 2
  config:
    maxscale:
      admin_host: 0.0.0.0
      admin_port: 8989
  auth:
    adminUsername: admin
    adminPasswordSecretKeyRef:
      name: maxscale-admin
      key: password
  kubernetesService:
    type: LoadBalancer
---
# Database
apiVersion: k8s.mariadb.com/v1alpha1
kind: Database
metadata:
  name: myapp
spec:
  mariaDbRef:
    name: mariadb-cluster
  name: myapp
  characterSet: utf8mb4
---
# User
apiVersion: k8s.mariadb.com/v1alpha1
kind: User
metadata:
  name: myapp-user
spec:
  mariaDbRef:
    name: mariadb-cluster
  name: myapp
  passwordSecretKeyRef:
    name: myapp-password
    key: password
  maxUserConnections: 30
---
# Grant
apiVersion: k8s.mariadb.com/v1alpha1
kind: Grant
metadata:
  name: myapp-grant
spec:
  mariaDbRef:
    name: mariadb-cluster
  privileges:
    - "ALL PRIVILEGES"
  database: "myapp"
  table: "*"
  username: myapp
  grantOption: true

Scheduled S3 Backup

apiVersion: k8s.mariadb.com/v1alpha1
kind: Backup
metadata:
  name: hourly-backup
spec:
  mariaDbRef:
    name: mariadb-cluster
  schedule:
    cron: "0 * * * *"
  compression: gzip
  maxRetention: 168h  # 7 days
  storage:
    s3:
      bucket: mariadb-backups
      prefix: cluster-hourly
      endpoint: s3.eu-west-1.amazonaws.com
      region: eu-west-1
      accessKeyIdSecretKeyRef:
        name: s3-creds
        key: access-key-id
      secretAccessKeySecretKeyRef:
        name: s3-creds
        key: secret-access-key

Point-in-Time Recovery

apiVersion: k8s.mariadb.com/v1alpha1
kind: PointInTimeRecovery
metadata:
  name: pitr-recovery
spec:
  mariaDbRef:
    name: mariadb-cluster
  backupRef:
    name: hourly-backup
  targetRecoveryTime: "2026-06-10T14:30:00Z"

SqlJob for Schema Migrations

apiVersion: k8s.mariadb.com/v1alpha1
kind: SqlJob
metadata:
  name: schema-migrate
spec:
  mariaDbRef:
    name: mariadb-cluster
  database: myapp
  username: myapp
  passwordSecretKeyRef:
    name: myapp-password
    key: password
  sql: |
    CREATE TABLE IF NOT EXISTS users (
      id BIGINT AUTO_INCREMENT PRIMARY KEY,
      email VARCHAR(255) UNIQUE NOT NULL,
      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    );
    CREATE INDEX idx_users_email ON users(email);

Password Rotation (v26.6.0)

apiVersion: k8s.mariadb.com/v1alpha1
kind: User
metadata:
  name: app-user
spec:
  mariaDbRef:
    name: mariadb-cluster
  name: app
  passwordRotation:
    enabled: true
    rotationInterval: 720h  # 30 days
  host: "%"

Connection Secret

apiVersion: k8s.mariadb.com/v1alpha1
kind: Connection
metadata:
  name: app-connection
spec:
  mariaDbRef:
    name: mariadb-cluster
  host: maxscale
  port: 3306
  userName: myapp
  passwordSecretKeyRef:
    name: myapp-password
    key: password
  database: myapp
  secretName: app-dsn

External MariaDB

apiVersion: k8s.mariadb.com/v1alpha1
kind: ExternalMariaDB
metadata:
  name: legacy-db
spec:
  host: db.legacy.example.com
  port: 3306
  username: readonly
  passwordSecretKeyRef:
    name: legacy-creds
    key: password
  tls:
    enabled: true
    caSecretKeyRef:
      name: legacy-ca
      key: ca.crt

Common Mistakes

• Image format change in v26.3.0 — Pre-v26.3.0 used image: mariadb:11.8. v26.3.0+ uses image.repository + image.tag. Check your operator version.
• Galera requires 3+ replicas — Galera cluster needs at least 3 replicas. 2 replicas causes split-brain.
• Galera reuseStorageVolume — When re-joining a Galera node, the PVC must be empty. Set reuseStorageVolume: true to wipe and reuse.
• Root password auto-generate — rootPasswordSecretKeyRef.generate: true auto-generates but the password is only available in the Secret. Extract before losing it.
• MaxScale config complexity — MaxScale CR uses inline config, not external files. The config structure mirrors MaxScale's native config format.
• Backup retention precision — maxRetention is a Go duration (720h = 30 days). Old backups are cleaned based on this, not just scheduling.
• S3 TLS for MinIO — When using MinIO with self-signed certs, use storage.s3.tls.caSecretKeyRef to provide the CA.
• PhysicalBackup speed — PhysicalBackup is faster than Backup for large databases but requires filesystem-level access. Use for databases > 50GB.
• SqlJob idempotency — SqlJob doesn't track which SQL has been applied. Use IF NOT EXISTS / IF EXISTS patterns.
• Password rotation impact — passwordRotation changes the password in both the Secret and MariaDB. Applications using the old password will lose connection.
• WaitForIt timeout — Large MariaDB clusters can take minutes to bootstrap. Set mariaDbRef.waitForItTimeout appropriately.
• Connection secret update — The Connection CR creates a Secret with the DSN. Deleting the Connection CR deletes the Secret.
• Multi-cluster topology — v26.6.0 supports replication.source for cross-cluster replication between MariaDB CRs.
• Maintenance mode — Set maintenance.enabled: true to pause reconciliation during manual operations.