CNMSQL - CloudNative for MySQL
CNMSQL - CloudNative for 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
CNMSQL - CloudNative for MySQL is an independent project. It is not affiliated with, endorsed by, or associated with Oracle, MySQL, 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​
| Category | Capabilities |
|---|---|
| Engines | Percona Server for MySQL or MariaDB, selected per cluster with spec.flavor |
| MySQL versions | Percona Server 8.0, 8.4, and 9.x |
| MariaDB versions | MariaDB 10.11, 11.4, and 12.3 |
| Replication | GTID-based asynchronous and semi-synchronous replication, plus MySQL Group Replication with quorum-based consensus, planned switchover, and automatic failover |
| Traffic routing | Three role-aware Services: read-write, read-only (replicas), and read (any ready) |
| Backups | Physical backups via Percona XtraBackup to S3-compatible storage |
| PITR | Continuous binlog archiving for point-in-time recovery to any timestamp |
| Security | mTLS between operator and instances, MySQL TLS, per-instance ServiceAccount identity, admission webhook for status protection |
| Multi-tenancy | Cluster-per-tenant or schema-per-tenant via declarative Database and managed role resources |
| Upgrades | Rolling instance upgrades with primary switchover, plus in-place instance-manager binary swaps (no pod restart) |
| Self-healing | PDBs, semi-sync reconciliation, primary-lease fencing, broken-replica detection and re-initialization |
| Observability | Prometheus metrics, PodMonitor support, kubectl cnmsql CLI plugin for ad-hoc inspection |
| Slim images | Custom Debian-based instance images (~75% smaller than upstream Percona), rootless by default |
API Resources​
| Resource | Purpose |
|---|---|
Cluster | Define a MySQL cluster: instances, storage, MySQL config, bootstrap, TLS |
Database | Declarative schema management with owners and privilege scoping |
Backup | One-shot physical backup via XtraBackup to S3-compatible storage |
ScheduledBackup | Cron-scheduled backups with deterministic naming and retention |
ImageCatalog | Cluster-wide image resolution by MySQL series |
ClusterImageCatalog | Per-cluster image override catalog |
All resources live under the mysql.cnmsql.co/v1alpha1 API group. See the API Reference for every field.
Getting Started​
- Quickstart: install the operator via Helm, pull pre-built images, create your first cluster, connect, scale, and take a backup.
- Cluster Lifecycle: understand how a
ClusterCR becomes running MySQL instances. - Instance Images: choose MySQL versions and understand the slim image layout.
- MariaDB Flavor: run a cluster on MariaDB instead of MySQL, and the behavior that differs.
Core Operations​
- Replication and Failover: GTID replication model, planned switchover, automatic failover, and rejoin.
- Group Replication: quorum-based consensus, automatic primary election, and event-driven observation.
- Security Model: mTLS, TLS, RBAC, per-instance identity, and the threat model.
- Multi-Tenancy: isolate tenants with Cluster-per-namespace or schema-per-tenant patterns.
- Operator Upgrades: rolling and in-place operator/instance-manager upgrades.
Backup and Recovery​
- Physical Backup and Recovery: one-shot XtraBackup archives and restore.
- Scheduled Backups: cron-driven backup schedules.
- Point-In-Time Recovery: continuous binlog archiving and timestamped recovery.
- Backup Retention and Deletion: cleanup semantics and planned GC.
- Object Store Configuration: S3-compatible providers, credentials, and TLS.
Day-2 Operations​
- Operations Runbooks: scaling, switchover, fencing, restart, reload, maintenance.
- Monitoring: Prometheus metrics, PodMonitor, kubectl plugin inspection.
- Troubleshooting: symptom-driven guide for common issues.
Reference​
- API Reference: complete field reference for every CRD.