Skip to main content

CloudNative MySQL

CloudNative MySQL

CloudNative MySQL is a Kubernetes operator for Percona Server for MySQL that borrows design patterns from CloudNativePG, adapted for MySQL. Declare a Cluster resource and the operator provisions Pods, PVCs, credentials, TLS, and role-routed Services — then handles replication, failover, backups, and point-in-time recovery so you don't have to.

No affiliation

CloudNative MySQL is an independent project. It is not affiliated with, endorsed by, or associated with the CNCF or the CloudNativePG project and its maintainers.

Architecture at a Glance​

Declare your desired state via Kubernetes custom resources. The operator continuously reconciles:

  • Cluster — instances, storage, replication topology, TLS, Services
  • Backup — one-shot physical snapshots via XtraBackup to S3
  • ScheduledBackup — cron-driven backup schedules with retention
  • Database — declarative schemas with managed roles and owners

Key Features​

CategoryCapabilities
MySQL versionsPercona Server 8.0, 8.4, and 9.x
ReplicationGTID-based asynchronous and semi-synchronous replication, plus MySQL Group Replication with quorum-based consensus, planned switchover, and automatic failover
Traffic routingThree role-aware Services: read-write, read-only (replicas), and read (any ready)
BackupsPhysical backups via Percona XtraBackup to S3-compatible storage
PITRContinuous binlog archiving for point-in-time recovery to any timestamp
SecuritymTLS between operator and instances, MySQL TLS, per-instance ServiceAccount identity, admission webhook for status protection
Multi-tenancyCluster-per-tenant or schema-per-tenant via declarative Database and managed role resources
UpgradesRolling instance upgrades with primary switchover, plus in-place instance-manager binary swaps (no pod restart)
Self-healingPDBs, semi-sync reconciliation, primary-lease fencing, broken-replica detection and re-initialization
ObservabilityPrometheus metrics, PodMonitor support, kubectl cnmysql CLI plugin for ad-hoc inspection
Slim imagesCustom Debian-based instance images (~75% smaller than upstream Percona), rootless by default

API Resources​

ResourcePurpose
ClusterDefine a MySQL cluster: instances, storage, MySQL config, bootstrap, TLS
DatabaseDeclarative schema management with owners and privilege scoping
BackupOne-shot physical backup via XtraBackup to S3-compatible storage
ScheduledBackupCron-scheduled backups with deterministic naming and retention
ImageCatalogCluster-wide image resolution by MySQL major version
ClusterImageCatalogPer-cluster image override catalog

All resources live under the mysql.cloudnative-mysql.io/v1alpha1 API group. See the API Reference for every field.

Getting Started​

  1. Quickstart — build images, deploy the operator, create your first cluster, connect, scale, and take a backup.
  2. Cluster Lifecycle — understand how a Cluster CR becomes running MySQL instances.
  3. Instance Images — choose MySQL versions and understand the slim image layout.

Core Operations​

  1. Replication and Failover — GTID replication model, planned switchover, automatic failover, and rejoin.
  2. Group Replication — quorum-based consensus, automatic primary election, and event-driven observation.
  3. Security Model — mTLS, TLS, RBAC, per-instance identity, and the threat model.
  4. Multi-Tenancy — isolate tenants with Cluster-per-namespace or schema-per-tenant patterns.
  5. Operator Upgrades — rolling and in-place operator/instance-manager upgrades.

Backup and Recovery​

  1. Physical Backup and Recovery — one-shot XtraBackup archives and restore.
  2. Scheduled Backups — cron-driven backup schedules.
  3. Point-In-Time Recovery — continuous binlog archiving and timestamped recovery.
  4. Backup Retention and Deletion — cleanup semantics and planned GC.
  5. Object Store Configuration — S3-compatible providers, credentials, and TLS.

Day-2 Operations​

  1. Operations Runbooks — scaling, switchover, fencing, restart, reload, maintenance.
  2. Monitoring — Prometheus metrics, PodMonitor, kubectl plugin inspection.
  3. Troubleshooting — symptom-driven guide for common issues.

Reference​

  1. API Reference — complete field reference for every CRD.