agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/mariadb-operator/SKILL.md

mariadb-operator

Skill4 starsChanged 5 months agoMITView on GitHub

Create and manage MariaDB operator CRDs — 12 CRDs under k8s.mariadb.com, Galera HA, MaxScale, backups, PITR, monitoring, and connection pooling.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create a database within a MariaDB instance.

    line 589
  2. Distinctive:

    Create a database user.

    line 625
  3. Distinctive:

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

    line 877

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

CRDShort NameScopeDescription
MariaDBmdbNamespacedGalera cluster
MaxScalemxsNamespacedMaxScale proxy
BackupbmdbNamespacedLogical backup
PhysicalBackuppbmdbNamespacedPhysical snapshot
RestorermdbNamespacedRestore from Backup
PointInTimeRecoverypitrNamespacedPITR to timestamp
DatabasedmdbNamespacedDatabase creation
UserumdbNamespacedUser management
GrantgmdbNamespacedPrivilege grants
ConnectioncmdbNamespacedConnection secret
SqlJobsmdbNamespacedSQL execution
ExternalMariaDBemdbNamespacedExternal DB connection

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

FieldTypeDefaultDescription
image.repositorystringmariadbMariaDB image repo
image.tagstring11.8.8MariaDB image tag
image.pullPolicystringIfNotPresentPull policy
galera.enabledboolfalseEnable Galera cluster
galera.primary.podIndexint0Primary pod index
galera.primary.automaticFailoverbooltrueAuto failover
galera.config.reuseStorageVolumeboolfalseReuse PVC on rejoin
galera.init.job.imageobject{}Init job image
storage.sizestring—PVC size
storage.storageClassNamestring—Storage class
storage.resizeInUseVolumesbooltrueResize PVC in use
storage.waitForVolume.enabledboolfalseWait for volume attach
replicasint3Replica count
service.typestringClusterIPService type
rootPasswordSecretKeyRefobject—Root password secret ref
rootPasswordSecretKeyRef.generateboolfalseAuto-generate password
usernamestring""Regular user
passwordSecretKeyRefobject—User password secret
databasestring""Database name
metrics.enabledboolfalseEnable exporter
metrics.exporter.imageobject—Exporter image
connectionPool.portint3306DB port
connectionPool.maxConnectionsint100Max connections
updateStrategy.typestringRollingUpdateUpdate strategy
updateStrategy.autoSwapPvc[]string[]Auto-swap PVCs
resourcesobject{}Container resources
tls.enabledboolfalseEnable TLS
tls.ssl.secretNamestring—TLS secret
myCnfstring—my.cnf config
podDisruptionBudget.enabledboolfalsePDB
podDisruptionBudget.maxUnavailableint1Max unavailable
progressDeadlineSecondsint600Progress deadline
maintenance.enabledboolfalseMaintenance mode
maintenance.requeueIntervalstring30sRequeue interval
ha.enablebooltrueEnable HA
ha.certobject—HA TLS cert config
replication.sourceobject—Replication source ref

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

FieldTypeDefaultDescription
imageobject—MaxScale image
replicasint1Replica count
mariaDbRefobject—Reference to MariaDB CR
mariaDbRef.waitForItbooltrueWait for MariaDB
configobject—Inline MaxScale config
auth.adminUsernamestringadminAdmin username
auth.adminPasswordSecretKeyRefobject—Admin password ref
auth.serverCredentials[]object—Server creds
metrics.enabledboolfalseEnable metrics
metrics.exporterobject—Exporter image
kubernetesService.typestringClusterIPK8s service type
services[]object—MaxScale internal services
tls.enabledboolfalseEnable TLS
resourcesobject{}Container resources
updateStrategyobject—Update strategy
podDisruptionBudgetobject—PDB config

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

FieldTypeDefaultDescription
mariaDbRef.namestring—MariaDB CR name
mariaDbRef.waitForItbooltrueWait for MariaDB
mariaDbRef.waitForItTimeoutstring—Wait timeout
schedule.cronstring—Cron expression
schedule.suspendboolfalseSuspend schedule
compressionstring—gzip or none
maxRetentionstring—Retention duration
storage.s3object—S3 storage config
storage.s3.bucketstring—Bucket name
storage.s3.prefixstring—Key prefix
storage.s3.endpointstring—S3 endpoint
storage.s3.regionstring—S3 region
storage.s3.accessKeyIdSecretKeyRefobject—Access key ref
storage.s3.secretAccessKeySecretKeyRefobject—Secret key ref
storage.s3.tlsobject—S3 TLS config
storage.azureobject—Azure Blob config
storage.volumesobject—PVC volume config
resourcesobject—Job resources
logLevelstringinfoLog level

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.

FieldTypeDescription
mariaDbRefobjectMariaDB reference
scheduleobjectCron schedule
compressionstringCompression method
maxRetentionstringRetention duration
storage.s3objectS3 storage (same as Backup)
storage.azureobjectAzure Blob
resourcesobjectJob resources

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

FieldTypeDescription
mariaDbRefobjectTarget MariaDB reference
backupRef.namestringBackup CR name (logical restore)
physicalBackupRef.namestringPhysicalBackup CR name
resourcesobjectJob resources

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

FieldTypeDescription
mariaDbRefobjectTarget MariaDB
backupRef.namestringBase Backup CR
targetRecoveryTimestringRFC3339 timestamp to recover to
resourcesobjectJob resources

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

FieldTypeDefaultDescription
mariaDbRefobject—MariaDB reference
namestring—Database name
characterSetstring—Character set
collatestring—Collation
cleanupPolicystringDeleteDelete or Skip
requeueIntervalstring—Reconciliation interval
retryIntervalstring5sRetry interval on error

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

FieldTypeDefaultDescription
mariaDbRefobject—MariaDB reference
namestring—Username
passwordSecretKeyRefobject—Password secret ref
passwordSecretKeyRef.generateboolfalseAuto-generate
passwordRotation.enabledboolfalseRotate password
passwordRotation.rotationIntervalstring—Rotation interval
maxUserConnectionsint—Connection limit
hoststring%Allowed host
cleanupPolicystringDeleteCleanup on CR delete
requeueIntervalstring—Reconcile interval
retryIntervalstring5sRetry interval

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

FieldTypeDescription
mariaDbRefobjectMariaDB reference
privileges[]stringList of privileges (ALL PRIVILEGES, SELECT, INSERT, etc.)
databasestringDatabase name
tablestringTable name (* for all)
usernamestringUsername
grantOptionboolAllow GRANT OPTION
hoststringHost pattern
cleanupPolicystringCleanup on CR delete
requeueIntervalstringReconcile interval
retryIntervalstringRetry interval

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

FieldTypeDescription
mariaDbRefobjectMariaDB reference
hoststringDatabase host
portintDatabase port
userNamestringUsername
passwordSecretKeyRefobjectPassword secret ref
databasestringDatabase name
secretNamestringOutput Secret name
templatestringGo template for DSN string
healthCheckobjectHealth check config

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

FieldTypeDescription
mariaDbRefobjectMariaDB reference
sqlstringInline SQL
sqlConfigMapKeyRefobjectSQL from ConfigMap
schedule.cronstringCron schedule (optional)
args[]stringSQL args
databasestringTarget database
usernamestringSQL user
passwordSecretKeyRefobjectPassword ref
logLevelstringLog level
resourcesobjectJob resources
retryIntervalstringRetry on error

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

FieldTypeDescription
hoststringExternal DB host
portintExternal DB port
usernamestringDB username
passwordSecretKeyRefobjectPassword secret ref
tls.enabledboolEnable TLS
tls.caSecretKeyRefobjectCA cert ref
connectionPool.portintLocal proxy port
connectionPool.maxConnectionsintMax connections

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.