Skip to main content

CNMSQL - CloudNative for MySQL

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​

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 cnmsql 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.cnmsql.co/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.