API Reference

Field tables on this page are auto-generated from the CRD OpenAPI schemas via crd-ref-docs. Narrative sections with YAML examples, behavioral semantics, and constraints are hand-maintained.

The API group is:

mysql.cnmsql.co/v1alpha1

The API is still v1alpha1, so fields may change while the operator is under active development.

Packages

mysql.cnmsql.co/v1alpha1

mysql.cnmsql.co/v1alpha1

Package v1alpha1 contains API Schema definitions for the mysql v1alpha1 API group.

AffinityConfiguration

AffinityConfiguration contains the info we need to create the affinity rules for Pods.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`enablePodAntiAffinity` boolean	Activates anti-affinity for the pods. The operator will define pods anti-affinity unless this field is explicitly set to false		Optional: {}
`topologyKey` string	TopologyKey to use for anti-affinity configuration. See Kubernetes documentation for more information on how this works		Optional: {}
`nodeSelector` object (keys:string, values:string)	NodeSelector is map of key-value pairs used to define the nodes on which the pods can run. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/		Optional: {}
`nodeAffinity` NodeAffinity	NodeAffinity describes node affinity scheduling rules for the pod. More info: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity		Optional: {}
`tolerations` Toleration array	Tolerations is a list of Tolerations that should be set for all the pods, in order to allow them to run on tainted nodes. More info: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/		Optional: {}
`podAntiAffinityType` string	PodAntiAffinityType allows the user to decide whether pod anti-affinity between cluster instances should be considered a strong requirement ("required") during scheduling or not ("preferred", default).	preferred	Enum: [preferred required] Optional: {}
`additionalPodAntiAffinity` PodAntiAffinity	AdditionalPodAntiAffinity allows to specify pod anti-affinity terms to be added to the ones generated by the operator if EnablePodAntiAffinity is set to true (default) or to be used exclusively if set to false.		Optional: {}
`additionalPodAffinity` PodAffinity	AdditionalPodAffinity allows to specify pod affinity terms to be passed to all the cluster's pods.		Optional: {}

Backup

Backup is a namespaced one-shot physical backup request. Short name: mybackup

Example:

apiVersion: mysql.cnmsql.co/v1alpha1
kind: Backup
metadata:
  name: backup-sample
spec:
  cluster:
    name: cluster-sample
  method: xtrabackup
  target: prefer-standby
  online: true

Deleting a Backup object does not delete remote object-store data.

Backup is the Schema for the backups API.

Appears in:

BackupList

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`Backup`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` BackupSpec	spec defines the desired state of Backup	Required: {}
`status` BackupStatus	status defines the observed state of Backup	Optional: {}

BackupConfiguration

BackupConfiguration describes the continuous archiving target for the cluster.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`objectStore` S3ObjectStore	ObjectStore is the S3-compatible destination for backups and binlog archiving.		Optional: {}
`retentionPolicy` string	RetentionPolicy is a duration string (e.g. "30d", "8w") describing how long to keep backups.		Pattern: `^[1-9][0-9]*[dwm]$` Optional: {}
`target` BackupTarget	Target instance to take backups from, defaults to a standby if available.	prefer-standby	Enum: [primary prefer-standby] Optional: {}
`xtrabackupOptions` string array	XtrabackupOptions are extra flags passed to xtrabackup.		Optional: {}
`continuousArchiving` ContinuousArchivingConfiguration	ContinuousArchiving configures continuous binary-log archiving to the object store, the foundation for point-in-time recovery. Disabled by default.		Optional: {}

BackupList

BackupList contains a list of Backup.

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`BackupList`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` Backup array

BackupMethod

Underlying type: string

BackupMethod is the method used to take a physical backup. +kubebuilder:validation:Enum=xtrabackup;volumeSnapshot

Validation:

Enum: [xtrabackup volumeSnapshot]

Appears in:

BackupSpec
BackupStatus
ScheduledBackupSpec

Field	Description
`xtrabackup`	BackupMethodXtrabackup uses Percona XtraBackup to stream a physical backup to the object store.
`volumeSnapshot`	BackupMethodVolumeSnapshot uses CSI volume snapshots.

BackupPhase

Underlying type: string

BackupPhase is the current phase of a Backup.

Appears in:

BackupStatus

Field	Description
`pending`	BackupPhasePending means the backup has not started yet.
`running`	BackupPhaseRunning means the backup is in progress.
`completed`	BackupPhaseCompleted means the backup finished successfully.
`failed`	BackupPhaseFailed means the backup failed.

BackupSpec

BackupSpec defines the desired state of Backup.

Appears in:

Backup

Field	Description	Default	Validation
`cluster` LocalObjectReference	Cluster references the cluster to back up.		Required: {}
`objectStore` S3ObjectStore	ObjectStore overrides the destination configured on the referenced Cluster. When omitted, the Cluster's backup object store is used.		Optional: {}
`method` BackupMethod	Method is the backup method to use.	xtrabackup	Enum: [xtrabackup volumeSnapshot] Optional: {}
`target` BackupTarget	Target instance to take the backup from.	prefer-standby	Enum: [primary prefer-standby] Optional: {}
`online` boolean	Online, when true, performs a non-blocking (hot) backup. Defaults to true.	true	Optional: {}

BackupStatus

BackupStatus defines the observed state of Backup.

Appears in:

Backup

Field	Description	Validation
`phase` BackupPhase	Phase is the current phase of the backup.	Optional: {}
`instanceName` string	InstanceName is the instance the backup was taken from.	Optional: {}
`method` BackupMethod	Method is the method that was used.	Enum: [xtrabackup volumeSnapshot] Optional: {}
`backupId` string	BackupID is a unique identifier of the backup in the object store.	Optional: {}
`jobName` string	JobName is the Kubernetes Job running this backup.	Optional: {}
`destinationPath` string	DestinationPath is the full path of the backup in the object store.	Optional: {}
`sha256` string	SHA256 is the checksum of the uploaded backup artifact.	Optional: {}
`beginGTID` string	BeginGTID/EndGTID record the GTID range covered by the backup.	Optional: {}
`endGTID` string		Optional: {}
`beginBinlog` string	BeginBinlog/EndBinlog record the binary log coordinates.	Optional: {}
`endBinlog` string		Optional: {}
`startedAt` Time	StartedAt/StoppedAt record the backup timing.	Optional: {}
`stoppedAt` Time		Optional: {}
`error` string	Error holds the error message if the backup failed.	Optional: {}
`conditions` Condition array	Conditions represent the latest observations of the backup state.	Optional: {}

BackupTarget

Underlying type: string

BackupTarget describes which instance a backup is taken from. +kubebuilder:validation:Enum=primary;prefer-standby

Validation:

Enum: [primary prefer-standby]

Appears in:

BackupConfiguration
BackupSpec
ScheduledBackupSpec

Field	Description
`primary`	BackupTargetPrimary takes backups from the primary instance.
`prefer-standby`	BackupTargetPreferStandby prefers a standby instance, falling back to the primary if no standby is available.

BootstrapConfiguration

BootstrapConfiguration describes how the cluster is initialised.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`initdb` BootstrapInitDB	InitDB bootstraps a fresh, empty cluster.		Optional: {}
`recovery` BootstrapRecovery	Recovery bootstraps the cluster by restoring a physical backup.		Optional: {}

BootstrapInitDB

BootstrapInitDB configures a fresh cluster initialisation.

Appears in:

BootstrapConfiguration

Field	Description	Validation
`database` string	Database is the name of the application database to create.	Optional: {}
`owner` string	Owner is the name of the application user that owns the database.	Optional: {}
`secret` LocalObjectReference	Secret references the credentials for the application user. If empty, a secret is generated.	Optional: {}
`postInitSQL` string array	PostInitSQL is a list of SQL statements run as root after the database is created.	Optional: {}
`characterSet` string	Encoding/charset of the application database.	Optional: {}
`collation` string	Collation of the application database.	Optional: {}

BootstrapRecovery

BootstrapRecovery configures bootstrapping from a physical backup.

Appears in:

BootstrapConfiguration

Field	Description	Validation
`backup` LocalObjectReference	Backup references a Backup object to recover from.	Optional: {}
`source` string	Source is the name of an entry in ExternalClusters to recover from. Mutually exclusive with Backup. The entry's objectStore holds the backups and its name is the S3 key prefix to discover them under.	Optional: {}
`backupID` string	BackupID narrows recovery to a specific base backup within the object store. Only meaningful when Source is set; when empty, the latest completed backup is selected. Ignored when Backup is set.	Optional: {}
`recoveryTarget` RecoveryTarget	RecoveryTarget describes the point-in-time recovery target. When omitted, recovery proceeds to the latest available point.	Optional: {}

CatalogImage

CatalogImage maps a MySQL major version to a container image.

Appears in:

ImageCatalogSpec

Field	Description	Default	Validation
`major` integer	Major is the MySQL major version (e.g. 8 for 8.0/8.4 lines uses the full version where needed; values map to the image's server version).		Minimum: 5 Required: {}
`image` string	Image is the fully qualified Percona Server for MySQL image reference.		Required: {}

CertificatesConfiguration

CertificatesConfiguration contains the needed configurations to handle server and client certificates for TLS and mTLS communication.

Appears in:

CertificatesStatus
ClusterSpec

Field	Description	Validation
`serverCASecret` string	The secret containing the Server CA certificate. If not defined, a new secret will be created with a self-signed CA and will be used to generate the TLS certificate ServerTLSSecret.	Optional: {}
`serverTLSSecret` string	The secret of type kubernetes.io/tls containing the server TLS certificate and key that will be set as ssl-cert and ssl-key. Should be signed by the CA in ServerCASecret.	Optional: {}
`replicationTLSSecret` string	The secret of type kubernetes.io/tls containing the client certificate to authenticate as the replication user. Should be signed by the CA in ClientCASecret.	Optional: {}
`clientCASecret` string	The secret containing the Client CA certificate. If not defined, a new secret will be created with a self-signed CA and will be used to generate all the client certificates.	Optional: {}
`serverAltDNSNames` string array	The list of additional Subject Alternative Names (SANs) to be added to the server certificate generated by the operator.	Optional: {}

CertificatesStatus

CertificatesStatus contains configuration certificates and related expiration dates.

Appears in:

ClusterStatus

Field	Description	Validation
`serverCASecret` string	The secret containing the Server CA certificate. If not defined, a new secret will be created with a self-signed CA and will be used to generate the TLS certificate ServerTLSSecret.	Optional: {}
`serverTLSSecret` string	The secret of type kubernetes.io/tls containing the server TLS certificate and key that will be set as ssl-cert and ssl-key. Should be signed by the CA in ServerCASecret.	Optional: {}
`replicationTLSSecret` string	The secret of type kubernetes.io/tls containing the client certificate to authenticate as the replication user. Should be signed by the CA in ClientCASecret.	Optional: {}
`clientCASecret` string	The secret containing the Client CA certificate. If not defined, a new secret will be created with a self-signed CA and will be used to generate all the client certificates.	Optional: {}
`serverAltDNSNames` string array	The list of additional Subject Alternative Names (SANs) to be added to the server certificate generated by the operator.	Optional: {}
`expirations` object (keys:string, values:string)	Expiration dates for all certificates.	Optional: {}

Cluster

Cluster is the main namespaced resource. It describes a Percona Server for MySQL topology, bootstrap method, storage, image, backup configuration, and operational policy.

Short names: mysql, mysqlcluster

Minimal example

apiVersion: mysql.cnmsql.co/v1alpha1
kind: Cluster
metadata:
  name: cluster-sample
spec:
  instances: 3
  imageName: ghcr.io/cnmsql/cnmsql-instance:8.4
  storage:
    size: 10Gi
  mysql:
    binlogFormat: ROW
  bootstrap:
    initdb:
      database: app
      owner: app

Image selection

Use either imageName for a direct reference or imageCatalogRef to resolve via a catalog:

spec:
  imageName: ghcr.io/cnmsql/cnmsql-instance:8.4

spec:
  imageCatalogRef:
    apiGroup: mysql.cnmsql.co
    kind: ImageCatalog
    name: percona-images
    major: 8

MySQL configuration

spec:
  mysql:
    parameters:
      require_secure_transport: "ON"
      max_connections: "500"
    binlogFormat: ROW
    semiSync:
      enabled: true
      timeoutMillis: 1000
      dataDurability: preferred
    additionalConfigFiles:
      custom.cnf: |
        [mysqld]
        sort_buffer_size=4M

Denied and deprecated parameters: spec.mysql.parameters is validated before provisioning. Keys are compared case-insensitively with dashes and underscores treated as equivalent (log-bin equals log_bin).

Denied keys set the cluster phase: Blocked with a reason naming the offending key. These are keys the operator manages directly (replication identity, topology, TLS material, binlog durability) or keys that would relocate on-disk paths or expose the administrative interface: server_id, gtid_mode, read_only, log_bin, ssl_cert, sync_binlog, datadir, socket, tmpdir, plugin_dir, secure_file_priv, log_error, admin_address, admin_ssl_cert, tls_ciphersuites, skip_replica_start, auto_generate_certs. require_secure_transport is not denied — requiring TLS for client connections is the user's choice.

Deprecated keys are accepted but emit a DeprecatedParameter warning event pointing at the current spelling, e.g. slave_parallel_workers (use replica_parallel_workers), master_info_repository (removed on 8.0.23+).

Storage

spec:
  storage:
    storageClass: fast
    size: 100Gi
    resizeInUseVolumes: true

storage and binlogStorage share the same shape: storageClass, size, resizeInUseVolumes, and pvcTemplate for a full PVC template override.

Bootstrap

Fresh initialization:

spec:
  bootstrap:
    initdb:
      database: app
      owner: app
      secret:
        name: app-credentials
      postInitSQL:
        - CREATE TABLE app.ready (id int primary key)
      characterSet: utf8mb4
      collation: utf8mb4_0900_ai_ci

Recovery from a Backup:

spec:
  bootstrap:
    recovery:
      backup:
        name: backup-sample

Point-in-time recovery:

spec:
  bootstrap:
    recovery:
      backup:
        name: backup-sample
      recoveryTarget:
        targetGTID: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee:1-500"

Raw object-store recovery (no Backup CR) points bootstrap.recovery.source at an externalClusters entry. The entry carries its own objectStore and its name is the S3 key prefix:

spec:
  bootstrap:
    recovery:
      source: prod-cluster
      backupID: ""              # empty = latest completed
      recoveryTarget:
        targetGTID: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee:1-500"
  externalClusters:
    - name: prod-cluster
      objectStore:
        bucket: cnmsql-backups
        path: production
        endpoint: http://minio.minio.svc:9000
        credentials:
          accessKeyId:
            name: minio-creds
            key: accessKey
          secretAccessKey:
            name: minio-creds
            key: secretKey

recovery.backup and recovery.source are mutually exclusive. backupID is only meaningful with source — when empty, the operator selects the latest completed backup.

recoveryTarget accepts exactly one of targetTime (RFC3339 timestamp), targetGTID (inclusive GTID set), or targetImmediate (stop as soon as the base backup is consistent). An empty recoveryTarget: {} replays to the latest archived point. No recoveryTarget restores the base backup only.

Managed services

spec:
  managed:
    services:
      disabledDefaultServices:
        - ro
      template:
        metadata:
          labels:
            app.kubernetes.io/part-of: my-app
        spec:
          type: LoadBalancer
      additional:
        - name: mysql-lb
          selectorType: rw
          serviceTemplate:
            spec:
              type: LoadBalancer

disabledDefaultServices accepts ro and r. The rw service cannot be disabled. template is merged onto each default rw/ro/r service. additional services are rendered as `<cluster>-<name>`.

Managed roles

spec.managed.roles declares MySQL users the operator reconciles on the primary. When passwordSecret is omitted, the operator generates a password and stores it in a Secret named `<cluster>-<roleName>` (key password).

spec:
  managed:
    roles:
      - name: app
        host: "%"
        ensure: present
        passwordSecret:
          name: app-credentials
          key: password
        requireTLS: x509
        maxUserConnections: 50
        privileges:
          - privileges: [SELECT, INSERT, UPDATE, DELETE]
            "on": app.*
      - name: readonly
        ensure: present
        privileges:
          - privileges: [SELECT]
            "on": app.*
      - name: legacy
        ensure: absent

Quote the on key ("on": app.*). Unquoted, YAML parses on as boolean true and the API server rejects the manifest.

Users present in MySQL but not declared in spec.managed.roles are left untouched. To remove one, declare it with ensure: absent. Reconciliation runs after the cluster reaches Ready.

External clusters

externalClusters defines named external sources for replica or raw object-store recovery flows:

spec:
  externalClusters:
    - name: source-cluster
      connectionParameters:
        host: mysql.example.com
        port: "3306"
      password:
        name: source-creds
        key: password
      objectStore:
        bucket: source-backups
        path: production
        credentials:
          inheritFromIAMRole: true

Cluster

Cluster is the Schema for the clusters API.

Appears in:

ClusterList

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`Cluster`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` ClusterSpec	spec defines the desired state of Cluster	Required: {}
`status` ClusterStatus	status defines the observed state of Cluster	Optional: {}

ClusterImageCatalog

ClusterImageCatalog has the same spec.images shape as ImageCatalog, but is cluster-scoped and can be reused across namespaces. Short name: myclusterimagecatalog

Example:

apiVersion: mysql.cnmsql.co/v1alpha1
kind: ClusterImageCatalog
metadata:
  name: global-percona-images
spec:
  images:
    - major: 8
      image: ghcr.io/cnmsql/cnmsql-instance:8.4
    - major: 9
      image: ghcr.io/cnmsql/cnmsql-instance:9.x

Reference it from a Cluster with imageCatalogRef using kind: ClusterImageCatalog.

ClusterImageCatalog is the Schema for the clusterimagecatalogs API (cluster-scoped).

Appears in:

ClusterImageCatalogList

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`ClusterImageCatalog`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` ImageCatalogSpec	spec defines the desired state of ClusterImageCatalog	Required: {}

ClusterImageCatalogList

ClusterImageCatalogList contains a list of ClusterImageCatalog.

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`ClusterImageCatalogList`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` ClusterImageCatalog array

ClusterList

ClusterList contains a list of Cluster.

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`ClusterList`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` Cluster array

ClusterMonitoringTLSConfig

ClusterMonitoringTLSConfig configures TLS for cluster metrics scraping.

Appears in:

MonitoringConfiguration

Field	Description	Default	Validation
`enabled` boolean	Enabled serves metrics over TLS when true.	false	Optional: {}

ClusterSpec

ClusterSpec defines the desired state of Cluster.

Appears in:

Cluster

Field	Description	Default	Validation
`description` string	Description of this MySQL cluster.		Optional: {}
`inheritedMetadata` EmbeddedObjectMetadata	Metadata that will be inherited by all objects related to the Cluster.		Optional: {}
`imageName` string	ImageName is the name of the Percona Server for MySQL container image to use. Mutually exclusive with ImageCatalogRef.		Optional: {}
`imageCatalogRef` ImageCatalogRef	ImageCatalogRef resolves the image from an ImageCatalog or ClusterImageCatalog based on the MySQL major version. Mutually exclusive with ImageName.		Optional: {}
`imagePullPolicy` PullPolicy	ImagePullPolicy is the policy used to pull the container image.		Enum: [Always Never IfNotPresent] Optional: {}
`imagePullSecrets` LocalObjectReference array	ImagePullSecrets is the list of pull secrets used to pull the image.		Optional: {}
`instances` integer	Instances is the number of MySQL instances (one primary + replicas).	1	Minimum: 1 Optional: {}
`minSyncReplicas` integer	MinSyncReplicas is the minimum number of semi-synchronous replicas that must acknowledge a transaction before it is committed on the primary.		Minimum: 0 Optional: {}
`maxSyncReplicas` integer	MaxSyncReplicas is the maximum number of semi-synchronous replicas the primary will wait for. Must be lower than the number of instances.		Minimum: 0 Optional: {}
`mysql` MySQLConfiguration	MySQL holds the engine configuration (my.cnf parameters, replication options).		Optional: {}
`storage` StorageConfiguration	Storage configuration for the instance data directory.		Required: {}
`binlogStorage` StorageConfiguration	BinlogStorage, when set, places the binary logs on a separate volume from the data directory.		Optional: {}
`bootstrap` BootstrapConfiguration	Bootstrap describes how the cluster is initialised (fresh init or recovery from a backup).		Optional: {}
`rootPasswordSecret` LocalObjectReference	RootPasswordSecret references a secret containing the password for the MySQL root user. If not provided, a secret is generated.		Optional: {}
`enableSuperuserAccess` boolean	EnableSuperuserAccess, when true, makes the root user reachable through the generated/provided secret. Defaults to false.	false	Optional: {}
`certificates` CertificatesConfiguration	Certificates configures the TLS/mTLS material used by the cluster.		Optional: {}
`resources` ResourceRequirements	Resources describes the compute resource requirements of the instance pods.		Optional: {}
`affinity` AffinityConfiguration	Affinity/anti-affinity rules for the instance pods.		Optional: {}
`topologySpreadConstraints` TopologySpreadConstraint array	TopologySpreadConstraints describes how the instance pods should be spread across topology domains.		Optional: {}
`priorityClassName` string	PriorityClassName for the instance pods.		Optional: {}
`schedulerName` string	SchedulerName to use for the instance pods.		Optional: {}
`primaryUpdateStrategy` PrimaryUpdateStrategy	PrimaryUpdateStrategy controls whether the operator performs the primary update automatically (unsupervised) or waits for the user (supervised).	unsupervised	Enum: [unsupervised supervised] Optional: {}
`primaryUpdateMethod` PrimaryUpdateMethod	PrimaryUpdateMethod controls how the primary is updated: by switchover (promoting a replica first) or by in-place restart.	switchover	Enum: [switchover restart] Optional: {}
`inPlaceInstanceManagerUpdates` boolean	InPlaceInstanceManagerUpdates, when true, rolls an operator upgrade out to this cluster's instances by streaming the new instance-manager binary to each Pod, which re-execs in place — no Pod restart and no switchover. When false (the default) the operator instead deletes and recreates each Pod one at a time (replicas first, primary last via switchover).		Optional: {}
`maxStartDelay` integer	MaxStartDelay is the time in seconds allowed for an instance to start.	3600	Optional: {}
`maxStopDelay` integer	MaxStopDelay is the time in seconds allowed for an instance to gracefully shut down.	1800	Optional: {}
`smartShutdownTimeout` integer	SmartShutdownTimeout is the time in seconds reserved for a "smart" (graceful) shutdown attempt before falling back to a "fast" shutdown. Must be lower than maxStopDelay; the remaining time is used for the fast/immediate fallback. Defaults to 180.		Minimum: 0 Optional: {}
`maxSwitchoverDelay` integer	MaxSwitchoverDelay is the time in seconds allowed for a switchover to complete before being considered failed.	3600	Optional: {}
`failoverDelay` integer	FailoverDelay is the amount of time in seconds the operator waits before declaring an unreachable primary failed and triggering a failover.	0	Optional: {}
`enablePrimaryLease` boolean	EnablePrimaryLease, when true (default), makes the acting primary hold a per-cluster Lease before accepting writes.	true	Optional: {}
`backup` BackupConfiguration	Backup configures continuous archiving and the object store target.		Optional: {}
`replica` ReplicaClusterConfiguration	Replica turns this cluster into a replica cluster that follows a source defined in ExternalClusters.		Optional: {}
`externalClusters` ExternalCluster array	ExternalClusters is the list of external clusters that can be used as a replication source or a recovery origin.		Optional: {}
`managed` ManagedConfiguration	Managed describes the resources (roles, services) managed declaratively by the operator.		Optional: {}
`monitoring` MonitoringConfiguration	Monitoring configuration.		Optional: {}
`nodeMaintenanceWindow` NodeMaintenanceWindow	NodeMaintenanceWindow defines if the cluster is tolerant to node failures during maintenance (e.g. PVC may be reused).		Optional: {}
`enablePDB` boolean	EnablePDB, when true (default), makes the operator create a PodDisruptionBudget for the cluster.	true	Optional: {}
`serviceAccountTemplate` ServiceAccountTemplate	ServiceAccountTemplate to use for the generated service account.		Optional: {}
`env` EnvVar array	Env is a list of additional environment variables added to the instance containers.		Optional: {}
`envFrom` EnvFromSource array	EnvFrom is a list of sources to populate environment variables in the instance containers.		Optional: {}
`podSecurityContext` PodSecurityContext	PodSecurityContext applied to the instance pods.		Optional: {}
`securityContext` SecurityContext	SecurityContext applied to the instance containers.		Optional: {}
`logLevel` string	LogLevel sets the operator-side log level for this cluster.	info	Enum: [error warning info debug trace] Optional: {}

ClusterStatus

ClusterStatus defines the observed state of Cluster.

Appears in:

Cluster

Field	Description	Validation
`instances` integer	Instances is the total number of instances reported.	Optional: {}
`readyInstances` integer	ReadyInstances is the number of ready instances.	Optional: {}
`instanceNames` string array	InstanceNames is the list of instance (pod) names.	Optional: {}
`currentPrimary` string	CurrentPrimary is the name of the instance currently acting as primary.	Optional: {}
`targetPrimary` string	TargetPrimary is the name of the instance that should become primary (used during switchover/failover).	Optional: {}
`currentPrimaryTimestamp` string	CurrentPrimaryTimestamp is when the current primary was elected.	Optional: {}
`targetPrimaryTimestamp` string	TargetPrimaryTimestamp is when the current switchover request to TargetPrimary was started. It bounds the switchover by spec.maxSwitchoverDelay.	Optional: {}
`divergedInstances` string array	DivergedInstances are replicas whose executed GTID set is not contained in the primary's (errant transactions). They cannot safely rejoin; their in-Pod reconciler reads this list and refuses to self-configure as a replica, leaving them read-only for an operator to resolve.	Optional: {}
`fencedInstances` string array	FencedInstances are instances the operator has fenced because their Pod carries the fencing annotation. A fenced instance is pulled out of the routing Services, kept read-only by its in-Pod reconciler (so it stops archiving and refuses writes), and is excluded as a failover candidate. Clearing the annotation removes it from this list and restores it.	Optional: {}
`failedInstances` string array	FailedInstances are instances whose Pod shows positive evidence of being unable to run: a Failed Pod phase, or a container stuck in CrashLoopBackOff after repeated restarts. Unlike a not-yet-ready instance (which is expected during initial provisioning), a failed instance is a degradation regardless of whether the cluster ever finished provisioning, so it is surfaced independently of the phase. It is the cluster's "unhealthy" bucket.	Optional: {}
`replicationBrokenInstances` string array	ReplicationBrokenInstances are reachable replicas whose replication has aborted with a recorded error — a stopped IO or SQL thread, e.g. a duplicate-key conflict that halts replication. Unlike a diverged instance (detected by comparing GTID sets and listed in DivergedInstances), this is derived from the SQL-layer replication error the in-Pod reconciler reports, so a replica that is Running but cannot replicate is surfaced as a degradation rather than being mistaken for one still finishing provisioning.	Optional: {}
`primaryFailingSince` string	PrimaryFailingSince records when the current primary first became unreachable. It is used to enforce spec.failoverDelay before an automatic failover, and is cleared once the primary is healthy again.	Optional: {}
`latestGeneratedNode` integer	LatestGeneratedNode is the serial of the latest generated instance.	Optional: {}
`establishedAt` Time	EstablishedAt records the first time the cluster reached full readiness (every instance ready together), marking that it completed initial provisioning at least once. It is sticky: once set it is never cleared, so a later degradation cannot reset it. Its presence is what distinguishes a cluster that is still being provisioned (a drop below readiness is expected) from an established one (a drop below readiness is a degradation). It is deliberately independent of Phase, which intermediate reconcile steps re-stamp and which therefore cannot carry this fact reliably.	Optional: {}
`phase` string	Phase is a high-level human-readable cluster phase.	Optional: {}
`phaseReason` string	PhaseReason gives more detail about the current phase.	Optional: {}
`image` string	Image is the resolved image currently in use.	Optional: {}
`gtidExecutedByInstance` object (keys:string, values:string)	GTIDExecutedByInstance maps an instance name to its gtid_executed set.	Optional: {}
`gtidExecutedUpdatedAt` Time	GTIDExecutedUpdatedAt records when GTIDExecutedByInstance was last refreshed. Because gtid_executed advances on every write, the operator throttles how often it persists the map; this timestamp marks the last persisted snapshot.	Optional: {}
`executableHashByInstance` object (keys:string, values:string)	ExecutableHashByInstance maps an instance name to the SHA-256 hash of its running instance manager binary, as reported by the in-Pod control API. The operator uses it to detect stale instance managers when upgrading.	Optional: {}
`operatorExecutableHash` string	OperatorExecutableHash is the SHA-256 hash of the running operator binary. It is the target hash every instance manager should match after an upgrade.	Optional: {}
`certificates` CertificatesStatus	Certificates reports the status of the managed certificates.	Optional: {}
`continuousArchiving` ContinuousArchivingStatus	ContinuousArchiving reports the health of continuous binlog archiving when it is enabled.	Optional: {}
`lastRetentionRunTime` Time	LastRetentionRunTime is when the operator last ran a backup-retention GC pass against the object store. It throttles the periodic pass.	Optional: {}
`observedGeneration` integer	ObservedGeneration is the generation observed by the controller.	Optional: {}
`conditions` Condition array	Conditions represent the latest available observations of the cluster's state.	Optional: {}
`managedRolesStatus` ManagedRolesStatus	ManagedRolesStatus reports the reconciliation state of the declarative managed roles.	Optional: {}

ConfigMapKeySelector

ConfigMapKeySelector selects a key from a ConfigMap in the same namespace.

Appears in:

MonitoringConfiguration

Field	Description	Default	Validation
`name` string	Name of the ConfigMap		Required: {}
`key` string	Key within the ConfigMap to select		Required: {}

ContinuousArchivingConfiguration

ContinuousArchivingConfiguration configures continuous binary-log (binlog) archiving: the current primary's instance manager ships rotated binlog files to the object store so the cluster keeps a gapless, GTID-addressable change history.

Appears in:

BackupConfiguration

Field	Description	Default	Validation
`enabled` boolean	Enabled turns continuous binlog archiving on. Requires Backup.ObjectStore.	false	Optional: {}
`targetRPOSeconds` integer	TargetRPOSeconds bounds the recovery point objective: the primary forces a binary-log rotation at least this often so a low-write cluster still archives promptly. Defaults to 300 (5 minutes).	300	Minimum: 10 Optional: {}
`maxBinlogSizeMB` integer	MaxBinlogSizeMB caps the active binary log before mysqld rotates it, bounding the size-based RPO and per-object size. Defaults to 16 MiB.	16	Minimum: 1 Optional: {}
`binlogExpireSeconds` integer	BinlogExpireSeconds is the conservative backstop after which mysqld may expire a binary log, applied under the active purge gate. Defaults to 604800 (7 days).	604800	Minimum: 0 Optional: {}

ContinuousArchivingStatus

ContinuousArchivingStatus reports the health and frontier of continuous binary-log archiving.

Appears in:

ClusterStatus

Field	Description	Validation
`enabled` boolean	Enabled mirrors whether continuous archiving is configured on.	Optional: {}
`lastArchivedBinlog` string	LastArchivedBinlog is the most recent binary-log file shipped by the current primary.	Optional: {}
`lastArchivedGTID` string	LastArchivedGTID is the last GTID covered by the archive.	Optional: {}
`lastArchivedTime` string	LastArchivedTime is when the most recent file finished archiving.	Optional: {}
`pendingFiles` integer	PendingFiles is the number of rotated binary logs not yet archived (archive lag). A growing value means the archiver is falling behind.	Optional: {}
`lastFailureReason` string	LastFailureReason and LastFailureTime record the most recent archiving failure on the current primary, if any.	Optional: {}
`lastFailureTime` string		Optional: {}

Database

Database is a namespaced CRD (short name mydatabase) that declares a MySQL schema and the accounts scoped to it. It references a Cluster in the same namespace, which makes it the unit you delegate to tenant teams. The controller diffs the spec against the live server and issues the minimal SQL to converge; nothing is dropped unless you ask for it.

Example:

apiVersion: mysql.cnmsql.co/v1alpha1
kind: Database
metadata:
  name: tenant-a
  namespace: shared            # must match the Cluster's namespace
spec:
  cluster:
    name: shared
  name: tenant_a               # the MySQL schema; defaults to the resource name
  ensure: present
  characterSet: utf8mb4
  collation: utf8mb4_0900_ai_ci
  reclaimPolicy: retain
  users:
    - name: tenant_a_app
      host: "%"
      ensure: present
      passwordSecret:
        name: tenant-a-db
        key: password
      grants:
        - privileges: [SELECT, INSERT, UPDATE, DELETE]
          # `on` defaults to the managed schema (tenant_a.*)

Database is the Schema for the databases API.

Appears in:

DatabaseList

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`Database`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` DatabaseSpec	spec defines the desired state of Database	Required: {}
`status` DatabaseStatus	status defines the observed state of Database	Optional: {}

DatabaseGrant

DatabaseGrant describes a single MySQL GRANT statement.

Appears in:

DatabaseUser

Field	Description	Default	Validation
`privileges` string array	Privileges is the list of privileges (e.g. "SELECT", "INSERT", "ALL").		Required: {}
`on` string	On is the target of the grant (e.g. "mydb.*"). Defaults to the managed database.		Optional: {}

DatabaseList

DatabaseList contains a list of Database.

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`DatabaseList`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` Database array

DatabaseSpec

DatabaseSpec defines the desired state of Database.

Appears in:

Database

Field	Description	Default	Validation
`cluster` LocalObjectReference	Cluster references the MySQL cluster this database belongs to.		Required: {}
`name` string	Name is the name of the MySQL database (schema). Defaults to the resource name if empty.		Optional: {}
`ensure` EnsureOption	Ensure controls whether the database is created or dropped.	present	Enum: [present absent] Optional: {}
`characterSet` string	CharacterSet of the database (e.g. "utf8mb4").		Optional: {}
`collation` string	Collation of the database (e.g. "utf8mb4_0900_ai_ci").		Optional: {}
`users` DatabaseUser array	Users is the list of users managed for this database.		Optional: {}
`reclaimPolicy` string	ReclaimPolicy controls what happens to the MySQL database when the Database object is deleted.	retain	Enum: [delete retain] Optional: {}

DatabaseStatus

DatabaseStatus defines the observed state of Database.

Appears in:

Database

Field	Description	Validation
`applied` boolean	Applied is true once the desired state has been reconciled.	Optional: {}
`message` string	Message provides additional detail, typically an error.	Optional: {}
`observedGeneration` integer	ObservedGeneration is the generation observed by the controller.	Optional: {}
`passwordStatus` object (keys:string, values:string)	PasswordStatus records, per managed user ("name@host"), the source Secret resourceVersion last applied to MySQL. It lets the controller re-apply a password only when its Secret changes.	Optional: {}
`conditions` Condition array	Conditions represent the latest observations of the database state.	Optional: {}

DatabaseUser

DatabaseUser describes a MySQL user managed declaratively.

Appears in:

DatabaseSpec

Field	Description	Default	Validation
`name` string	Name of the user.		Required: {}
`host` string	Host the user connects from. Defaults to "%".	%	Optional: {}
`ensure` EnsureOption	Ensure controls whether the user is created or dropped.	present	Enum: [present absent] Optional: {}
`passwordSecret` SecretKeySelector	PasswordSecret references the secret key holding the user's password.		Optional: {}
`grants` DatabaseGrant array	Grants is the list of grants applied to the user.		Optional: {}

EmbeddedObjectMetadata

EmbeddedObjectMetadata contains metadata to be inherited by all resources related to a Cluster.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`labels` object (keys:string, values:string)			Optional: {}
`annotations` object (keys:string, values:string)			Optional: {}

EnsureOption

Underlying type: string

EnsureOption controls whether a declarative object must be present or absent. +kubebuilder:validation:Enum=present;absent

Validation:

Enum: [present absent]

Appears in:

DatabaseSpec
DatabaseUser
RoleConfiguration

Field	Description
`present`	EnsurePresent means the object must exist.
`absent`	EnsureAbsent means the object must not exist.

ExternalCluster

ExternalCluster describes a MySQL server external to this Cluster, used as a replication source or recovery origin.

Appears in:

ClusterSpec

Field	Description	Validation
`name` string	Name of the external cluster, referenced by Replica.Source and BootstrapRecovery.Source.	Required: {}
`connectionParameters` object (keys:string, values:string)	ConnectionParameters is a key/value map of connection settings (host, port, etc.).	Optional: {}
`password` SecretKeySelector	Password references a secret key holding the password for the connection.	Optional: {}
`sslCert` SecretKeySelector	SSLCert/SSLKey/SSLRootCert reference secret keys for mTLS to the source.	Optional: {}
`sslKey` SecretKeySelector		Optional: {}
`sslRootCert` SecretKeySelector		Optional: {}
`objectStore` S3ObjectStore	ObjectStore allows recovering from a backup stored in an object store.	Optional: {}

ImageCatalog

ImageCatalog is a namespaced mapping from MySQL major version to instance image. Short name: myimagecatalog

Example:

apiVersion: mysql.cnmsql.co/v1alpha1
kind: ImageCatalog
metadata:
  name: percona-images
spec:
  images:
    - major: 8
      image: ghcr.io/cnmsql/cnmsql-instance:8.4
    - major: 9
      image: ghcr.io/cnmsql/cnmsql-instance:9.x

Each major value can appear at most once in the images list (minimum one, maximum eight).

ImageCatalog is the Schema for the imagecatalogs API (namespaced).

Appears in:

ImageCatalogList

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`ImageCatalog`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` ImageCatalogSpec	spec defines the desired state of ImageCatalog	Required: {}

ImageCatalogList

ImageCatalogList contains a list of ImageCatalog.

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`ImageCatalogList`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` ImageCatalog array

ImageCatalogRef

ImageCatalogRef references an ImageCatalog or ClusterImageCatalog entry to resolve a container image for a given major version.

Appears in:

ClusterSpec

Field	Description	Validation
`apiGroup` string	APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be in the core API group. For any other third-party types, APIGroup is required.	Optional: {}
`kind` string	Kind is the type of resource being referenced
`name` string	Name is the name of resource being referenced
`major` integer	Major is the MySQL major version to resolve in the catalog.	Required: {}

ImageCatalogSpec

ImageCatalogSpec is the shared spec for ImageCatalog and ClusterImageCatalog.

Appears in:

ClusterImageCatalog
ImageCatalog

Field	Description	Default	Validation
`images` CatalogImage array	Images is the list of major version to container image mappings. Each major version must appear at most once.		MaxItems: 8 MinItems: 1

LocalObjectReference

LocalObjectReference contains the reference to a Kubernetes object in the same namespace, identified by name.

Appears in:

BackupSpec
BootstrapInitDB
BootstrapRecovery
ClusterSpec
DatabaseSpec
ScheduledBackupSpec

Field	Description	Default	Validation
`name` string	Name of the referent		Required: {}

ManagedConfiguration

ManagedConfiguration describes resources managed declaratively by the operator.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`services` ManagedServices	Services describes the services managed for the cluster.		Optional: {}
`roles` RoleConfiguration array	Roles is the list of MySQL users (roles) managed declaratively on the primary instance.		Optional: {}

ManagedRoleStatus

Underlying type: string

ManagedRoleStatus is the reconciliation state of a single managed role.

Appears in:

ManagedRolesStatus

Field	Description
`reconciled`	ManagedRoleReconciled means the role matches its desired state.
`not-managed`	ManagedRoleNotManaged means the MySQL user exists but is not managed.
`pending-reconciliation`	ManagedRolePendingReconciliation means the role still needs work.
`reserved`	ManagedRoleReserved means the role name is reserved by the operator.

ManagedRolesStatus

ManagedRolesStatus reports the reconciliation state of managed roles.

Appears in:

ClusterStatus

Field	Description	Validation
`byStatus` object (keys:ManagedRoleStatus, values:string array)	ByStatus groups managed role names by their reconciliation status.	Optional: {}
`cannotReconcile` object (keys:string, values:string array)	CannotReconcile maps a role name to the reasons it could not be reconciled.	Optional: {}
`passwordStatus` object (keys:string, values:RolePasswordState)	PasswordStatus tracks the applied password Secret version per role.	Optional: {}

ManagedService

ManagedService describes a user-defined managed service.

Appears in:

ManagedServices

Field	Description	Default	Validation
`selectorType` ServiceSelectorType	SelectorType specifies the type of selectors the service will have. Valid values are "rw", "r", and "ro".		Enum: [rw r ro] Required: {}
`name` string	Name is the name of the additional service. Must be unique among all managed services and must not collide with the default service names `<cluster>-rw`, `<cluster>-ro`, `<cluster>-r`).		Required: {}
`updateStrategy` ServiceUpdateStrategy	UpdateStrategy describes how the service template is reconciled with the operator defaults.	patch	Enum: [patch replace] Optional: {}
`serviceTemplate` ServiceTemplateSpec	ServiceTemplate is the template specification for the service. When UpdateStrategy is "patch", fields here are merged on top of the role-specific defaults. When "replace", they replace the defaults entirely (except for selector and owner reference).		Optional: {}

ManagedServices

ManagedServices controls the services generated for the cluster.

Appears in:

ManagedConfiguration

Field	Description	Validation
`disabledDefaultServices` ServiceSelectorType array	DisabledDefaultServices is the list of default services (rw, ro, r) to disable. The rw service cannot be disabled.	Enum: [rw ro r] Optional: {}
`template` ServiceTemplateSpec	Template applies to the three default services (rw, ro, r). Fields set here are merged into each default service. The operator still chooses the selector and port based on the service role.	Optional: {}
`additional` ManagedService array	Additional is a list of additional managed services specified by the user. Each entry declares a selectorType and an optional template to overlay on top of the role-specific defaults.	Optional: {}

Metadata

Metadata is a structure similar to the metav1.ObjectMeta, but still parseable by controller-gen to create a suitable CRD for the user. The comment of PodTemplateSpec has an explanation of why we are not using the core data types.

Appears in:

ServiceAccountTemplate

Field	Description	Validation
`name` string	The name of the resource. Only supported for certain types	Optional: {}
`labels` object (keys:string, values:string)	Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services. More info: http://kubernetes.io/docs/user-guide/labels	Optional: {}
`annotations` object (keys:string, values:string)	Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: http://kubernetes.io/docs/user-guide/annotations	Optional: {}

MonitoringConfiguration

MonitoringConfiguration configures cluster monitoring.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`enablePodMonitor` boolean	EnablePodMonitor creates a PodMonitor for the cluster pods.	false	Optional: {}
`customQueriesConfigMap` ConfigMapKeySelector array	CustomQueriesConfigMap references config maps holding custom monitoring queries.		Optional: {}
`customQueriesSecret` SecretKeySelector array	CustomQueriesSecret references secrets holding custom monitoring queries.		Optional: {}
`disableDefaultQueries` boolean	DisableDefaultQueries disables the built-in monitoring query set.		Optional: {}
`metricsQueriesTTL` Duration	MetricsQueriesTTL is the minimum interval between executions of the default and custom monitoring queries.		Optional: {}
`tls` ClusterMonitoringTLSConfig	TLS configures TLS for the instance metrics endpoint.		Optional: {}

MySQLConfiguration

MySQLConfiguration holds the MySQL engine configuration.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`parameters` object (keys:string, values:string)	Parameters is a key/value map of my.cnf settings applied under the [mysqld] section.		Optional: {}
`binlogFormat` string	BinlogFormat is the binary log format. ROW is required for safe replication and PITR and is the default.	ROW	Enum: [ROW STATEMENT MIXED] Optional: {}
`semiSync` SemiSyncConfiguration	SemiSync configures semi-synchronous replication.		Optional: {}
`additionalConfigFiles` object (keys:string, values:string)	AdditionalConfigFiles are extra files dropped into the MySQL configuration directory, keyed by file name.		Optional: {}

NodeMaintenanceWindow

NodeMaintenanceWindow contains information that the operator will use while upgrading the underlying nodes.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`reusePVC` boolean	ReusePVC, when true, reuses the existing PVC during a node maintenance (instead of provisioning a fresh one).	true	Optional: {}
`inProgress` boolean	InProgress signals that a node maintenance is in progress.	false	Optional: {}

ObjectMetaTemplate

ObjectMetaTemplate carries the user-configurable metadata fields.

Appears in:

ServiceTemplateSpec

Field	Description	Default	Validation
`labels` object (keys:string, values:string)	Labels added to the Service.		Optional: {}
`annotations` object (keys:string, values:string)	Annotations added to the Service.		Optional: {}

PrimaryUpdateMethod

Underlying type: string

PrimaryUpdateMethod contains the method to use when upgrading the primary server of the cluster as part of rolling updates. +kubebuilder:validation:Enum=switchover;restart

Validation:

Enum: [switchover restart]

Appears in:

ClusterSpec

Field	Description
`switchover`	PrimaryUpdateMethodSwitchover means the operator promotes a replica before updating the former primary.
`restart`	PrimaryUpdateMethodRestart means the operator restarts the primary in place.

PrimaryUpdateStrategy

Underlying type: string

PrimaryUpdateStrategy contains the strategy to follow when upgrading the primary server of the cluster as part of rolling updates. +kubebuilder:validation:Enum=unsupervised;supervised

Validation:

Enum: [unsupervised supervised]

Appears in:

ClusterSpec

Field	Description
`unsupervised`	PrimaryUpdateStrategyUnsupervised means that the operator performs the switchover/restart of the primary automatically.
`supervised`	PrimaryUpdateStrategySupervised means that the operator waits for the user to manually trigger the primary update.

RecoveryTarget

RecoveryTarget allows to specify a point in time to recover to.

Appears in:

BootstrapRecovery

Field	Description	Validation
`targetTime` string	TargetTime is an RFC3339 timestamp to recover to.	Optional: {}
`targetGTID` string	TargetGTID is the GTID set to recover up to.	Optional: {}
`targetImmediate` boolean	TargetImmediate stops recovery as soon as a consistent state is reached.	Optional: {}

ReplicaClusterConfiguration

ReplicaClusterConfiguration turns the cluster into a replica that follows an external source.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`enabled` boolean	Enabled controls whether the cluster runs in replica mode.	true	Optional: {}
`source` string	Source is the name of the entry in ExternalClusters to replicate from.		Required: {}

RoleConfiguration

RoleConfiguration describes a MySQL user managed declaratively against the primary instance.

Appears in:

ManagedConfiguration

Field	Description	Default	Validation
`name` string	Name is the MySQL user name.		MaxLength: 32 Required: {}
`host` string	Host is the MySQL host part. Defaults to "%".	%	Optional: {}
`ensure` EnsureOption	Ensure controls whether the user should exist or be absent.	present	Enum: [present absent] Optional: {}
`passwordSecret` SecretKeySelector	PasswordSecret references a Secret key holding the user's password. When unset, the operator generates a password and stores it in a Secret named `<cluster>-<name>` with key "password".		Optional: {}
`superuser` boolean	Superuser grants ALL PRIVILEGES on . WITH GRANT OPTION.	false	Optional: {}
`maxUserConnections` integer	MaxUserConnections resource limit. 0 = no limit.		Minimum: 0 Optional: {}
`maxQueriesPerHour` integer	MaxQueriesPerHour resource limit. 0 = no limit.		Minimum: 0 Optional: {}
`maxUpdatesPerHour` integer	MaxUpdatesPerHour resource limit. 0 = no limit.		Minimum: 0 Optional: {}
`maxConnectionsPerHour` integer	MaxConnectionsPerHour resource limit. 0 = no limit.		Minimum: 0 Optional: {}
`requireTLS` string	RequireTLS sets the connection TLS requirement: x509, ssl, or none.	none	Enum: [x509 ssl none] Optional: {}
`privileges` RolePrivilege array	Privileges are grants (global or per-database). Mutually exclusive with Superuser.		Optional: {}

RolePasswordState

RolePasswordState records the password Secret version last applied for a role.

Appears in:

ManagedRolesStatus

Field	Description	Default	Validation
`secretResourceVersion` string	SecretResourceVersion is the resourceVersion of the password Secret last applied.		Optional: {}
`lastApplied` Time	LastApplied is when the password was last applied.		Optional: {}

RolePrivilege

RolePrivilege is a grant of one or more privileges on a target.

Appears in:

RoleConfiguration

Field	Description	Default	Validation
`privileges` string array	Privileges is the grant list (SELECT, INSERT, ALL, etc.).		MinItems: 1
`on` string	On is the target (e.g. ".", "mydb."). Defaults to ".*".		Optional: {}

S3Credentials

S3Credentials holds the references to the secrets containing the credentials used to access an S3-compatible object store.

Appears in:

S3ObjectStore

Field	Description	Default	Validation
`accessKeyId` SecretKeySelector	The reference to the secret key containing the access key id.		Optional: {}
`secretAccessKey` SecretKeySelector	The reference to the secret key containing the secret access key.		Optional: {}
`sessionToken` SecretKeySelector	The reference to the secret key containing the session token, used for temporary credentials.		Optional: {}
`inheritFromIAMRole` boolean	InheritFromIAMRole, when true, makes the credentials be retrieved from the pod's environment (IRSA / instance profile) instead of from a secret.	false	Optional: {}

S3ObjectStore

S3ObjectStore describes an S3-compatible object store, designed to be compatible with as many providers as possible (AWS S3, MinIO, Ceph RGW, Wasabi, Backblaze B2, etc.).

Appears in:

BackupConfiguration
BackupSpec
ExternalCluster

Field	Description	Default	Validation
`endpoint` string	Endpoint is the URL of the S3-compatible service. Leave empty to target AWS S3 with the region's default endpoint.		Optional: {}
`region` string	Region is the bucket region. Required by most providers; for AWS it selects the regional endpoint.		Optional: {}
`bucket` string	Bucket is the destination bucket name.		Required: {}
`path` string	Path is the key prefix (folder) inside the bucket under which backups are stored.		Optional: {}
`forcePathStyle` boolean	ForcePathStyle uses path-style addressing (endpoint/bucket/key) instead of virtual-hosted style (bucket.endpoint/key). Required by MinIO, Ceph and most non-AWS providers; defaults to true for maximum compatibility.	true	Optional: {}
`signatureVersion` S3SignatureVersion	SignatureVersion selects the request signing scheme. Defaults to s3v4; set to s3v2 for legacy providers.	s3v4	Enum: [s3v4 s3v2] Optional: {}
`serverSideEncryption` string	ServerSideEncryption sets the SSE algorithm (e.g. "AES256" or "aws:kms").		Optional: {}
`storageClass` string	StorageClass sets the object storage class (e.g. "STANDARD_IA").		Optional: {}
`credentials` S3Credentials	Credentials to access the object store.		Required: {}
`tls` S3TLSConfig	TLS configuration for the endpoint connection.		Optional: {}

S3SignatureVersion

Underlying type: string

S3SignatureVersion is the AWS Signature version used to sign object-store requests. +kubebuilder:validation:Enum=s3v4;s3v2

Validation:

Enum: [s3v4 s3v2]

Appears in:

S3ObjectStore

Field	Description
`s3v4`	SignatureVersionV4 is the default AWS Signature V4.
`s3v2`	SignatureVersionV2 is the legacy AWS Signature V2, kept for older S3-compatible providers.

S3TLSConfig

S3TLSConfig configures TLS verification against the object-store endpoint.

Appears in:

S3ObjectStore

Field	Description	Default	Validation
`insecureSkipVerify` boolean	InsecureSkipVerify disables TLS certificate verification against the endpoint. Use only for testing.	false	Optional: {}
`caBundleSecret` SecretKeySelector	CABundleSecret references a secret key holding a PEM CA bundle used to verify the endpoint certificate (for private CAs / self-signed endpoints).		Optional: {}

ScheduledBackup

ScheduledBackup is a namespaced cron scheduler that creates Backup objects. Short name: myscheduledbackup

Example:

apiVersion: mysql.cnmsql.co/v1alpha1
kind: ScheduledBackup
metadata:
  name: cluster-sample-daily
spec:
  schedule: "0 0 2 * * *"
  cluster:
    name: cluster-sample
  immediate: true
  backupOwnerReference: self
  method: xtrabackup
  target: prefer-standby
  online: true

schedule uses six-field cron format: second minute hour day-of-month month day-of-week.

Generated Backups are labelled with mysql.cnmsql.co/scheduled-backup=<name> and immediate Backups also carry mysql.cnmsql.co/immediate-backup=true.

ScheduledBackup is the Schema for the scheduledbackups API.

Appears in:

ScheduledBackupList

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`ScheduledBackup`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ObjectMeta	Refer to Kubernetes API documentation for fields of `metadata`.	Optional: {}
`spec` ScheduledBackupSpec	spec defines the desired state of ScheduledBackup	Required: {}
`status` ScheduledBackupStatus	status defines the observed state of ScheduledBackup	Optional: {}

ScheduledBackupList

ScheduledBackupList contains a list of ScheduledBackup.

Field	Description	Validation
`apiVersion` string	`mysql.cnmsql.co/v1alpha1`
`kind` string	`ScheduledBackupList`
`kind` string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds	Optional: {}
`apiVersion` string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources	Optional: {}
`metadata` ListMeta	Refer to Kubernetes API documentation for fields of `metadata`.
`items` ScheduledBackup array

ScheduledBackupSpec

ScheduledBackupSpec defines the desired state of ScheduledBackup.

Appears in:

ScheduledBackup

Field	Description	Default	Validation
`schedule` string	Schedule is a cron expression (6 fields, including seconds) defining when backups are taken.		Required: {}
`cluster` LocalObjectReference	Cluster references the cluster to back up.		Required: {}
`suspend` boolean	Suspend, when true, pauses the schedule.	false	Optional: {}
`immediate` boolean	Immediate, when true, takes a backup as soon as the ScheduledBackup is created, in addition to the schedule.	false	Optional: {}
`backupOwnerReference` string	BackupOwnerReference controls the owner reference set on the generated Backup objects.	self	Enum: [none self cluster] Optional: {}
`method` BackupMethod	Method is the backup method used for the generated backups.	xtrabackup	Enum: [xtrabackup volumeSnapshot] Optional: {}
`target` BackupTarget	Target instance to take the generated backups from.	prefer-standby	Enum: [primary prefer-standby] Optional: {}
`online` boolean	Online, when true, performs non-blocking (hot) backups.	true	Optional: {}

ScheduledBackupStatus

ScheduledBackupStatus defines the observed state of ScheduledBackup.

Appears in:

ScheduledBackup

Field	Description	Validation
`lastCheckTime` Time	LastCheckTime is the last time the schedule was evaluated.	Optional: {}
`lastScheduleTime` Time	LastScheduleTime is the last time a backup was triggered.	Optional: {}
`nextScheduleTime` Time	NextScheduleTime is the next time a backup will be triggered.	Optional: {}

SecretKeySelector

SecretKeySelector selects a key from a Secret in the same namespace.

Appears in:

DatabaseUser
ExternalCluster
MonitoringConfiguration
RoleConfiguration
S3Credentials
S3TLSConfig

Field	Description	Default	Validation
`name` string	Name of the Secret		Required: {}
`key` string	Key within the Secret to select		Required: {}

SemiSyncConfiguration

SemiSyncConfiguration configures semi-synchronous replication.

Appears in:

MySQLConfiguration

Field	Description	Default	Validation
`enabled` boolean	Enabled turns on semi-synchronous replication.	false	Optional: {}
`timeoutMillis` integer	Timeout in milliseconds the primary waits for a replica acknowledgement before falling back to asynchronous replication.		Minimum: 0 Optional: {}
`dataDurability` string	DataDurability controls how strictly minSyncReplicas is enforced when replicas are unhealthy. "preferred" (the default) keeps the primary writable by self-healing the acknowledgement count down to the number of healthy replicas; "required" leaves it fixed so writes block until enough replicas acknowledge.	preferred	Enum: [preferred required] Optional: {}

ServiceAccountTemplate

ServiceAccountTemplate contains the template needed to generate the service accounts.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`metadata` Metadata	Refer to Kubernetes API documentation for fields of `metadata`.		Optional: {}

ServiceSelectorType

Underlying type: string

ServiceSelectorType is the type of a default service. +kubebuilder:validation:Enum=rw;ro;r

Validation:

Enum: [rw ro r]

Appears in:

ManagedService
ManagedServices

Field	Description
`rw`	ServiceSelectorTypeRW selects the read-write (primary) service.
`ro`	ServiceSelectorTypeRO selects the read-only (replicas) service.
`r`	ServiceSelectorTypeR selects the read (any instance) service.

ServiceTemplateServiceSpec

ServiceTemplateServiceSpec exposes the subset of corev1.ServiceSpec fields that users are allowed to customise. The operator retains control over the selector, ports, clusterIP, and owner reference.

Appears in:

ServiceTemplateSpec

Field	Description	Validation
`type` ServiceType	Type determines how the Service is exposed. Defaults to ClusterIP.	Enum: [ClusterIP NodePort LoadBalancer ExternalName] Optional: {}
`externalTrafficPolicy` ServiceExternalTrafficPolicy	ExternalTrafficPolicy describes how nodes distribute service traffic.	Optional: {}
`sessionAffinity` ServiceAffinity	SessionAffinity configures session affinity.	Optional: {}
`loadBalancerSourceRanges` string array	LoadBalancerSourceRanges restricts load balancer access.	Optional: {}
`externalName` string	ExternalName is the external reference for ExternalName services.	Optional: {}
`healthCheckNodePort` integer	HealthCheckNodePort specifies the health check node port.	Optional: {}

ServiceTemplateSpec

ServiceTemplateSpec describes the user-customisable parts of a managed Service.

Appears in:

ManagedService
ManagedServices

Field	Description	Default	Validation
`metadata` ObjectMetaTemplate	Refer to Kubernetes API documentation for fields of `metadata`.		Optional: {}
`spec` ServiceTemplateServiceSpec	Specification of the desired behavior of the Service. The selector field is operator-managed and cannot be overridden.		Optional: {}

ServiceUpdateStrategy

Underlying type: string

ServiceUpdateStrategy describes how the service template is reconciled. +kubebuilder:validation:Enum=patch;replace

Validation:

Enum: [patch replace]

Appears in:

ManagedService

Field	Description
`patch`	ServiceUpdateStrategyPatch merges user fields onto operator defaults.
`replace`	ServiceUpdateStrategyReplace replaces operator defaults with the user template.

StorageConfiguration

StorageConfiguration is the configuration used to create and reconcile PVCs, usable for the instance data directory or for separate binlog storage.

Appears in:

ClusterSpec

Field	Description	Default	Validation
`storageClass` string	StorageClass to use for PVCs. Applied after evaluating the PVC template, if available. If not specified, the generated PVCs will use the default storage class.		Optional: {}
`size` string	Size of the storage. Required if not already specified in the PVC template. Changes to this field are automatically reapplied to the created PVCs. Size cannot be decreased.		Optional: {}
`resizeInUseVolumes` boolean	Resize existing PVCs, defaults to true	true	Optional: {}
`pvcTemplate` PersistentVolumeClaimSpec	Template to be used to generate the Persistent Volume Claim		Optional: {}

Shared Types

S3ObjectStore

S3ObjectStore appears in Cluster.spec.backup.objectStore, Backup.spec.objectStore, and Cluster.spec.externalClusters[].objectStore. All fields are documented in the generated table above under S3ObjectStore.

Common Conditions

CNMSQL - CloudNative for MySQL resources use Kubernetes metav1.Condition entries. Common condition types:

Condition	Meaning
`Ready`	Resource is fully functional.
`Progressing`	Resource is being created, updated, backed up, restored, or changed.
`Degraded`	Resource failed to reach or maintain the desired state.

Packages​

mysql.cnmsql.co/v1alpha1​

Resource Types​

AffinityConfiguration​

Backup​

BackupConfiguration​

BackupList​

BackupMethod​

BackupPhase​

BackupSpec​

BackupStatus​

BackupTarget​

BootstrapConfiguration​

BootstrapInitDB​

BootstrapRecovery​

CatalogImage​

CertificatesConfiguration​

CertificatesStatus​

Cluster​

Minimal example​

Image selection​

MySQL configuration​

Storage​

Bootstrap​

Managed services​

Managed roles​

External clusters​

Cluster​

ClusterImageCatalog​

ClusterImageCatalogList​

ClusterList​

ClusterMonitoringTLSConfig​

ClusterSpec​

ClusterStatus​

ConfigMapKeySelector​

ContinuousArchivingConfiguration​

ContinuousArchivingStatus​

Database​

DatabaseGrant​

DatabaseList​

DatabaseSpec​

DatabaseStatus​

DatabaseUser​

EmbeddedObjectMetadata​

EnsureOption​

ExternalCluster​

ImageCatalog​

ImageCatalogList​

ImageCatalogRef​

ImageCatalogSpec​

LocalObjectReference​

ManagedConfiguration​

ManagedRoleStatus​

ManagedRolesStatus​

ManagedService​

ManagedServices​

Metadata​

MonitoringConfiguration​

MySQLConfiguration​

NodeMaintenanceWindow​

ObjectMetaTemplate​

PrimaryUpdateMethod​

PrimaryUpdateStrategy​

RecoveryTarget​

ReplicaClusterConfiguration​

RoleConfiguration​

RolePasswordState​

RolePrivilege​

S3Credentials​

S3ObjectStore​

S3SignatureVersion​

S3TLSConfig​

ScheduledBackup​

ScheduledBackupList​

ScheduledBackupSpec​

ScheduledBackupStatus​

SecretKeySelector​

SemiSyncConfiguration​

ServiceAccountTemplate​

ServiceSelectorType​

Packages

mysql.cnmsql.co/v1alpha1

Resource Types

AffinityConfiguration

Backup

BackupConfiguration

BackupList

BackupMethod

BackupPhase

BackupSpec

BackupStatus

BackupTarget

BootstrapConfiguration

BootstrapInitDB

BootstrapRecovery

CatalogImage

CertificatesConfiguration

CertificatesStatus

Cluster

Minimal example

Image selection

MySQL configuration

Storage

Bootstrap

Managed services

Managed roles

External clusters

Cluster

ClusterImageCatalog

ClusterImageCatalogList

ClusterList

ClusterMonitoringTLSConfig

ClusterSpec

ClusterStatus

ConfigMapKeySelector

ContinuousArchivingConfiguration

ContinuousArchivingStatus

Database

DatabaseGrant

DatabaseList

DatabaseSpec

DatabaseStatus

DatabaseUser

EmbeddedObjectMetadata

EnsureOption

ExternalCluster

ImageCatalog

ImageCatalogList

ImageCatalogRef

ImageCatalogSpec

LocalObjectReference

ManagedConfiguration

ManagedRoleStatus

ManagedRolesStatus

ManagedService

ManagedServices

Metadata

MonitoringConfiguration

MySQLConfiguration

NodeMaintenanceWindow

ObjectMetaTemplate

PrimaryUpdateMethod

PrimaryUpdateStrategy

RecoveryTarget

ReplicaClusterConfiguration

RoleConfiguration

RolePasswordState

RolePrivilege

S3Credentials

S3ObjectStore

S3SignatureVersion

S3TLSConfig

ScheduledBackup

ScheduledBackupList

ScheduledBackupSpec

ScheduledBackupStatus

SecretKeySelector

SemiSyncConfiguration

ServiceAccountTemplate

ServiceSelectorType