mariadb-operator version >= v0.0.2
MariaDB running in KubernetesMariaDB with different topologyapiVersion: k8s.mariadb.com/v1alpha1
kind: MariaDB
metadata:
- name: mariadb-galera
+ name: mariadb
spec:
+ storage:
+ size: 1Gi
bootstrapFrom:
restoreJob:
args:
@@ -1513,6 +1526,64 @@ spec:
Galera is not compatible with the LOCK TABLES statement:
- https://mariadb.com/kb/en/lock-tables/#limitations
For this reason, the operator automatically adds the --skip-add-locks option to the Backup to overcome this limitation.
+Migrating an external MariaDB to a MariaDB running in Kubernetes
+You can leverage logical backups to bring your external MariaDB data into a new MariaDB instance running in Kubernetes. Follow this runbook for doing so:
+
+- Take a logical backup of your external MariaDB using one of the commands below:
+
+mariadb-dump --user=${MARIADB_USER} --password=${MARIADB_PASSWORD --host=${MARIADB_HOST} --single-transaction --events --routines --all-databases > backup.2024-08-26T12:24:34Z.sql
+
+
+[!IMPORTANT]
+If you are using Galera or planning to migrate to a Galera instance, make sure you understand the Galera backup limitations and use the following command instead:
+
+mariadb-dump --user=${MARIADB_USER} --password=${MARIADB_PASSWORD --host=${MARIADB_HOST} --single-transaction --events --routines --all-databases --skip-add-locks --ignore-table=mysql.global_priv > backup.2024-08-26T12:24:34Z.sql
+
+
+-
+
Ensure that your backup file is named in the following format: backup.2024-08-26T12:24:34Z.sql. If the file name does not follow this format, it will be ignored by the operator.
+
+-
+
Upload the backup file to one of the supported storage types. We recommend using S3.
+
+-
+
Create your MariaDB resource declaring that you want to bootstrap from the previous backup and providing a root password Secret that matches the backup:
+
+
+apiVersion: k8s.mariadb.com/v1alpha1
+kind: MariaDB
+metadata:
+ name: mariadb-galera
+spec:
+ rootPasswordSecretKeyRef:
+ name: mariadb
+ key: root-password
+ replicas: 3
+ galera:
+ enabled: true
+ storage:
+ size: 1Gi
+ bootstrapFrom:
+ s3:
+ bucket: backups
+ prefix: mariadb
+ endpoint: minio.minio.svc.cluster.local:9000
+ accessKeyIdSecretKeyRef:
+ name: minio
+ key: access-key-id
+ secretAccessKeySecretKeyRef:
+ name: minio
+ key: secret-access-key
+ tls:
+ enabled: true
+ caSecretKeyRef:
+ name: minio-ca
+ key: ca.crt
+ targetRecoveryTime: 2024-08-26T12:24:34Z
+
+
+- If you are using Galera in your new instance, migrate your previous users and grants to use the
User and Grant CRs.
+
Migrating to a MariaDB with different topology
Logical backups serve not just as a source of restoration, but also enable data mobility between MariaDB instances. These backups are called "logical" because they are independent from the MariaDB topology, as they only contain DDLs and INSERT statements to populate data.
Although backing up and restoring data from MariaDBs with different topologies is possible, there are a couple of technical details that you need to be aware of in the following scenarios:
@@ -1536,8 +1607,11 @@ kind: MariaDB
metadata:
name: mariadb-galera
spec:
+ replicas: 3
galera:
enabled: true
+ storage:
+ size: 1Gi
bootstrapFrom:
backupRef:
name: backup-standalone
diff --git a/main/search/search_index.json b/main/search/search_index.json
index 9a2ef670..bcc382a3 100644
--- a/main/search/search_index.json
+++ b/main/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83d\udea7\ud83d\udea7\ud83d\udea7 WIP \ud83d\udea7\ud83d\udea7\ud83d\udea7","text":"For full documentation visit mkdocs.org.
"},{"location":"#commands","title":"Commands","text":" mkdocs new [dir-name] - Create a new project.mkdocs serve - Start the live-reloading docs server.mkdocs build - Build the documentation site.mkdocs -h - Print help message and exit.
"},{"location":"#project-layout","title":"Project layout","text":"mkdocs.yml # The configuration file.\ndocs/\n index.md # The documentation homepage.\n ... # Other markdown pages, images and other files.\n
"},{"location":"API_REFERENCE/","title":"API Reference","text":""},{"location":"API_REFERENCE/#packages","title":"Packages","text":" - k8s.mariadb.com/v1alpha1
"},{"location":"API_REFERENCE/#k8smariadbcomv1alpha1","title":"k8s.mariadb.com/v1alpha1","text":"Package v1alpha1 contains API Schema definitions for the v1alpha1 API group
"},{"location":"API_REFERENCE/#resource-types","title":"Resource Types","text":" - Backup
- Connection
- Database
- Grant
- MariaDB
- MaxScale
- Restore
- SqlJob
- User
"},{"location":"API_REFERENCE/#affinityconfig","title":"AffinityConfig","text":"AffinityConfig defines policies to schedule Pods in Nodes.
Appears in: - BackupSpec - Exporter - Job - JobPodTemplate - MariaDBSpec - MaxScaleSpec - PodTemplate - RestoreSpec - SqlJobSpec
Field Description Default Validation antiAffinityEnabled boolean AntiAffinityEnabled configures PodAntiAffinity so each Pod is scheduled in a different Node, enabling HA.Make sure you have at least as many Nodes available as the replicas to not end up with unscheduled Pods."},{"location":"API_REFERENCE/#backup","title":"Backup","text":"Backup is the Schema for the backups API. It is used to define backup jobs and its storage.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Backup metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec BackupSpec"},{"location":"API_REFERENCE/#backupspec","title":"BackupSpec","text":"BackupSpec defines the desired state of Backup
Appears in: - Backup
Field Description Default Validation args string array Args to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. successfulJobsHistoryLimit integer Minimum: 0 failedJobsHistoryLimit integer Minimum: 0 timeZone string mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} storage BackupStorage Storage to be used in the Backup. Required: {} schedule Schedule Schedule defines when the Backup will be taken. maxRetention Duration MaxRetention defines the retention policy for backups. Old backups will be cleaned up by the Backup Job.It defaults to 30 days. databases string array Databases defines the logical databases to be backed up. If not provided, all databases are backed up. ignoreGlobalPriv boolean IgnoreGlobalPriv indicates to ignore the mysql.global_priv in backups.If not provided, it will default to true when the referred MariaDB instance has Galera enabled and otherwise to false.See: https://github.com/mariadb-operator/mariadb-operator/issues/556 logLevel string LogLevel to be used n the Backup Job. It defaults to 'info'. info backoffLimit integer BackoffLimit defines the maximum number of attempts to successfully take a Backup. restartPolicy RestartPolicy RestartPolicy to be added to the Backup Pod. OnFailure Enum: [Always OnFailure Never] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources."},{"location":"API_REFERENCE/#backupstorage","title":"BackupStorage","text":"BackupStorage defines the storage for a Backup.
Appears in: - BackupSpec
Field Description Default Validation s3 S3 S3 defines the configuration to store backups in a S3 compatible storage. persistentVolumeClaim PersistentVolumeClaimSpec PersistentVolumeClaim is a Kubernetes PVC specification. volume VolumeSource Volume is a Kubernetes volume specification."},{"location":"API_REFERENCE/#bootstrapfrom","title":"BootstrapFrom","text":"BootstrapFrom defines a source to bootstrap MariaDB from.
Appears in: - MariaDBSpec
Field Description Default Validation backupRef LocalObjectReference BackupRef is a reference to a Backup object. It has priority over S3 and Volume. s3 S3 S3 defines the configuration to restore backups from a S3 compatible storage. It has priority over Volume. volume VolumeSource Volume is a Kubernetes Volume object that contains a backup. targetRecoveryTime Time TargetRecoveryTime is a RFC3339 (1970-01-01T00:00:00Z) date and time that defines the point in time recovery objective.It is used to determine the closest restoration source in time. restoreJob Job RestoreJob defines additional properties for the Job used to perform the Restore."},{"location":"API_REFERENCE/#cleanuppolicy","title":"CleanupPolicy","text":"Underlying type: string
CleanupPolicy defines the behavior for cleaning up a resource.
Appears in: - DatabaseSpec - GrantSpec - SQLTemplate - UserSpec
Field Description Skip CleanupPolicySkip indicates that the resource will NOT be deleted from the database after the CR is deleted. Delete CleanupPolicyDelete indicates that the resource will be deleted from the database after the CR is deleted."},{"location":"API_REFERENCE/#connection","title":"Connection","text":"Connection is the Schema for the connections API. It is used to configure connection strings for the applications connecting to MariaDB.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Connection metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec ConnectionSpec"},{"location":"API_REFERENCE/#connectionspec","title":"ConnectionSpec","text":"ConnectionSpec defines the desired state of Connection
Appears in: - Connection
Field Description Default Validation secretName string SecretName to be used in the Connection. secretTemplate SecretTemplate SecretTemplate to be used in the Connection. healthCheck HealthCheck HealthCheck to be used in the Connection. params object (keys:string, values:string) Params to be used in the Connection. serviceName string ServiceName to be used in the Connection. port integer Port to connect to. If not provided, it defaults to the MariaDB port or to the first MaxScale listener. mariaDbRef MariaDBRef MariaDBRef is a reference to the MariaDB to connect to. Either MariaDBRef or MaxScaleRef must be provided. maxScaleRef ObjectReference MaxScaleRef is a reference to the MaxScale to connect to. Either MariaDBRef or MaxScaleRef must be provided. username string Username to use for configuring the Connection. Required: {} passwordSecretKeyRef SecretKeySelector PasswordSecretKeyRef is a reference to the password to use for configuring the Connection.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. Required: {} host string Host to connect to. If not provided, it defaults to the MariaDB host or to the MaxScale host. database string Database to use when configuring the Connection."},{"location":"API_REFERENCE/#connectiontemplate","title":"ConnectionTemplate","text":"ConnectionTemplate defines a template to customize Connection objects.
Appears in: - ConnectionSpec - MariaDBMaxScaleSpec - MariaDBSpec - MaxScaleSpec
Field Description Default Validation secretName string SecretName to be used in the Connection. secretTemplate SecretTemplate SecretTemplate to be used in the Connection. healthCheck HealthCheck HealthCheck to be used in the Connection. params object (keys:string, values:string) Params to be used in the Connection. serviceName string ServiceName to be used in the Connection. port integer Port to connect to. If not provided, it defaults to the MariaDB port or to the first MaxScale listener."},{"location":"API_REFERENCE/#container","title":"Container","text":"Container object definition.
Appears in: - Exporter - Galera - GaleraSpec - MariaDBSpec - MaxScaleSpec - PodTemplate
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. image string Image name to be used by the MariaDB instances. The supported format is <image>:<tag>. Required: {} imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent]"},{"location":"API_REFERENCE/#containertemplate","title":"ContainerTemplate","text":"ContainerTemplate defines a template to configure Container objects.
Appears in: - Container - Exporter - GaleraAgent - MariaDBSpec - MaxScaleSpec
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container."},{"location":"API_REFERENCE/#cooperativemonitoring","title":"CooperativeMonitoring","text":"Underlying type: string
CooperativeMonitoring enables coordination between multiple MaxScale instances running monitors. See: https://mariadb.com/docs/server/architecture/components/maxscale/monitors/mariadbmon/use-cooperative-locking-ha-maxscale-mariadb-monitor/
Appears in: - MaxScaleMonitor
Field Description majority_of_all CooperativeMonitoringMajorityOfAll requires a lock from the majority of the MariaDB servers, even the ones that are down. majority_of_running CooperativeMonitoringMajorityOfRunning requires a lock from the majority of the MariaDB servers."},{"location":"API_REFERENCE/#cronjobtemplate","title":"CronJobTemplate","text":"CronJobTemplate defines parameters for configuring CronJob objects.
Appears in: - BackupSpec - SqlJobSpec
Field Description Default Validation successfulJobsHistoryLimit integer Minimum: 0 failedJobsHistoryLimit integer Minimum: 0 timeZone string"},{"location":"API_REFERENCE/#database","title":"Database","text":"Database is the Schema for the databases API. It is used to define a logical database as if you were running a 'CREATE DATABASE' statement.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Database metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec DatabaseSpec"},{"location":"API_REFERENCE/#databasespec","title":"DatabaseSpec","text":"DatabaseSpec defines the desired state of Database
Appears in: - Database
Field Description Default Validation requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. retryInterval Duration RetryInterval is the interval used to perform retries. cleanupPolicy CleanupPolicy CleanupPolicy defines the behavior for cleaning up a SQL resource. Enum: [Skip Delete] mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} characterSet string CharacterSet to use in the Database. utf8 collate string Collate to use in the Database. utf8_general_ci name string Name overrides the default Database name provided by metadata.name. MaxLength: 80"},{"location":"API_REFERENCE/#exporter","title":"Exporter","text":"Exporter defines a metrics exporter container.
Appears in: - MariadbMetrics - MaxScaleMetrics
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. initContainers Container array InitContainers to be used in the Pod. sidecarContainers Container array SidecarContainers to be used in the Pod. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. volumes Volume array Volumes to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints to be used in the Pod. image string Image name to be used as metrics exporter. The supported format is <image>:<tag>.Only mysqld-exporter >= v0.15.0 is supported: https://github.com/prometheus/mysqld_exporter imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] port integer Port where the exporter will be listening for connections."},{"location":"API_REFERENCE/#galera","title":"Galera","text":"Galera allows you to enable multi-master HA via Galera in your MariaDB cluster.
Appears in: - MariaDBSpec
Field Description Default Validation primary PrimaryGalera Primary is the Galera configuration for the primary node. sst SST SST is the Snapshot State Transfer used when new Pods join the cluster.More info: https://galeracluster.com/library/documentation/sst.html. Enum: [rsync mariabackup mysqldump] availableWhenDonor boolean AvailableWhenDonor indicates whether a donor node should be responding to queries. It defaults to false. galeraLibPath string GaleraLibPath is a path inside the MariaDB image to the wsrep provider plugin. It is defaulted if not provided.More info: https://galeracluster.com/library/documentation/mysql-wsrep-options.html#wsrep-provider. replicaThreads integer ReplicaThreads is the number of replica threads used to apply Galera write sets in parallel.More info: https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_slave_threads. providerOptions object (keys:string, values:string) ProviderOptions is map of Galera configuration parameters.More info: https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_provider_options. agent GaleraAgent GaleraAgent is a sidecar agent that co-operates with mariadb-operator. recovery GaleraRecovery GaleraRecovery is the recovery process performed by the operator whenever the Galera cluster is not healthy.More info: https://galeracluster.com/library/documentation/crash-recovery.html. initContainer Container InitContainer is an init container that runs in the MariaDB Pod and co-operates with mariadb-operator. initJob Job InitJob defines a Job that co-operates with mariadb-operator by performing initialization tasks. config GaleraConfig GaleraConfig defines storage options for the Galera configuration files. enabled boolean Enabled is a flag to enable Galera."},{"location":"API_REFERENCE/#galeraagent","title":"GaleraAgent","text":"GaleraAgent is a sidecar agent that co-operates with mariadb-operator.
Appears in: - Galera - GaleraSpec
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. image string Image name to be used by the MariaDB instances. The supported format is <image>:<tag>. imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] port integer Port where the agent will be listening for connections. kubernetesAuth KubernetesAuth KubernetesAuth to be used by the agent container gracefulShutdownTimeout Duration GracefulShutdownTimeout is the time we give to the agent container in order to gracefully terminate in-flight requests."},{"location":"API_REFERENCE/#galeraconfig","title":"GaleraConfig","text":"GaleraConfig defines storage options for the Galera configuration files.
Appears in: - Galera - GaleraSpec
Field Description Default Validation reuseStorageVolume boolean ReuseStorageVolume indicates that storage volume used by MariaDB should be reused to store the Galera configuration files.It defaults to false, which implies that a dedicated volume for the Galera configuration files is provisioned. volumeClaimTemplate VolumeClaimTemplate VolumeClaimTemplate is a template for the PVC that will contain the Galera configuration files shared between the InitContainer, Agent and MariaDB."},{"location":"API_REFERENCE/#galerarecovery","title":"GaleraRecovery","text":"GaleraRecovery is the recovery process performed by the operator whenever the Galera cluster is not healthy. More info: https://galeracluster.com/library/documentation/crash-recovery.html.
Appears in: - Galera - GaleraSpec
Field Description Default Validation enabled boolean Enabled is a flag to enable GaleraRecovery. minClusterSize IntOrString MinClusterSize is the minimum number of replicas to consider the cluster healthy. It can be either a number of replicas (1) or a percentage (50%).If Galera consistently reports less replicas than this value for the given 'ClusterHealthyTimeout' interval, a cluster recovery is iniated.It defaults to '1' replica. clusterMonitorInterval Duration ClusterMonitorInterval represents the interval used to monitor the Galera cluster health. clusterHealthyTimeout Duration ClusterHealthyTimeout represents the duration at which a Galera cluster, that consistently failed health checks,is considered unhealthy, and consequently the Galera recovery process will be initiated by the operator. clusterBootstrapTimeout Duration ClusterBootstrapTimeout is the time limit for bootstrapping a cluster.Once this timeout is reached, the Galera recovery state is reset and a new cluster bootstrap will be attempted. podRecoveryTimeout Duration PodRecoveryTimeout is the time limit for recevorying the sequence of a Pod during the cluster recovery. podSyncTimeout Duration PodSyncTimeout is the time limit for a Pod to join the cluster after having performed a cluster bootstrap during the cluster recovery. forceClusterBootstrapInPod string ForceClusterBootstrapInPod allows you to manually initiate the bootstrap process in a specific Pod.IMPORTANT: Use this option only in exceptional circumstances. Not selecting the Pod with the highest sequence number may result in data loss.IMPORTANT: Ensure you unset this field after completing the bootstrap to allow the operator to choose the appropriate Pod to bootstrap from in an event of cluster recovery. job GaleraRecoveryJob Job defines a Job that co-operates with mariadb-operator by performing the Galera cluster recovery ."},{"location":"API_REFERENCE/#galerarecoveryjob","title":"GaleraRecoveryJob","text":"GaleraRecoveryJob defines a Job used to be used to recover the Galera cluster.
Appears in: - GaleraRecovery
Field Description Default Validation metadata Metadata Refer to Kubernetes API documentation for fields of metadata. resources ResourceRequirements Resouces describes the compute resource requirements."},{"location":"API_REFERENCE/#galeraspec","title":"GaleraSpec","text":"GaleraSpec is the Galera desired state specification.
Appears in: - Galera
Field Description Default Validation primary PrimaryGalera Primary is the Galera configuration for the primary node. sst SST SST is the Snapshot State Transfer used when new Pods join the cluster.More info: https://galeracluster.com/library/documentation/sst.html. Enum: [rsync mariabackup mysqldump] availableWhenDonor boolean AvailableWhenDonor indicates whether a donor node should be responding to queries. It defaults to false. galeraLibPath string GaleraLibPath is a path inside the MariaDB image to the wsrep provider plugin. It is defaulted if not provided.More info: https://galeracluster.com/library/documentation/mysql-wsrep-options.html#wsrep-provider. replicaThreads integer ReplicaThreads is the number of replica threads used to apply Galera write sets in parallel.More info: https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_slave_threads. providerOptions object (keys:string, values:string) ProviderOptions is map of Galera configuration parameters.More info: https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_provider_options. agent GaleraAgent GaleraAgent is a sidecar agent that co-operates with mariadb-operator. recovery GaleraRecovery GaleraRecovery is the recovery process performed by the operator whenever the Galera cluster is not healthy.More info: https://galeracluster.com/library/documentation/crash-recovery.html. initContainer Container InitContainer is an init container that runs in the MariaDB Pod and co-operates with mariadb-operator. initJob Job InitJob defines a Job that co-operates with mariadb-operator by performing initialization tasks. config GaleraConfig GaleraConfig defines storage options for the Galera configuration files."},{"location":"API_REFERENCE/#generatedsecretkeyref","title":"GeneratedSecretKeyRef","text":"GeneratedSecretKeyRef defines a reference to a Secret that can be automatically generated by mariadb-operator if needed.
Appears in: - MariaDBSpec - MariadbMetrics - MaxScaleAuth - ReplicaReplication
Field Description Default Validation generate boolean Generate indicates whether the Secret should be generated if the Secret referenced is not present. false"},{"location":"API_REFERENCE/#grant","title":"Grant","text":"Grant is the Schema for the grants API. It is used to define grants as if you were running a 'GRANT' statement.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Grant metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec GrantSpec"},{"location":"API_REFERENCE/#grantspec","title":"GrantSpec","text":"GrantSpec defines the desired state of Grant
Appears in: - Grant
Field Description Default Validation requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. retryInterval Duration RetryInterval is the interval used to perform retries. cleanupPolicy CleanupPolicy CleanupPolicy defines the behavior for cleaning up a SQL resource. Enum: [Skip Delete] mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} privileges string array Privileges to use in the Grant. MinItems: 1 Required: {} database string Database to use in the Grant. * table string Table to use in the Grant. * username string Username to use in the Grant. Required: {} host string Host to use in the Grant. It can be localhost, an IP or '%'. grantOption boolean GrantOption to use in the Grant. false"},{"location":"API_REFERENCE/#gtid","title":"Gtid","text":"Underlying type: string
Gtid indicates which Global Transaction ID should be used when connecting a replica to the master. See: https://mariadb.com/kb/en/gtid/#using-current_pos-vs-slave_pos.
Appears in: - ReplicaReplication
Field Description CurrentPos GtidCurrentPos indicates the union of gtid_binlog_pos and gtid_slave_pos will be used when replicating from master.This is the default Gtid mode. SlavePos GtidSlavePos indicates that gtid_slave_pos will be used when replicating from master."},{"location":"API_REFERENCE/#healthcheck","title":"HealthCheck","text":"HealthCheck defines intervals for performing health checks.
Appears in: - ConnectionSpec - ConnectionTemplate
Field Description Default Validation interval Duration Interval used to perform health checks. retryInterval Duration RetryInterval is the interval used to perform health check retries."},{"location":"API_REFERENCE/#job","title":"Job","text":"Job defines a Job used to be used with MariaDB.
Appears in: - BootstrapFrom - Galera - GaleraSpec
Field Description Default Validation metadata Metadata Refer to Kubernetes API documentation for fields of metadata. affinity AffinityConfig Affinity to be used in the Pod. resources ResourceRequirements Resouces describes the compute resource requirements. args string array Args to be used in the Container."},{"location":"API_REFERENCE/#jobcontainertemplate","title":"JobContainerTemplate","text":"JobContainerTemplate defines a template to configure Container objects that run in a Job.
Appears in: - BackupSpec - RestoreSpec - SqlJobSpec
Field Description Default Validation args string array Args to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container."},{"location":"API_REFERENCE/#jobpodtemplate","title":"JobPodTemplate","text":"JobPodTemplate defines a template to configure Container objects that run in a Job.
Appears in: - BackupSpec - RestoreSpec - SqlJobSpec
Field Description Default Validation podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod."},{"location":"API_REFERENCE/#kubernetesauth","title":"KubernetesAuth","text":"KubernetesAuth refers to the Kubernetes authentication mechanism utilized for establishing a connection from the operator to the agent. The agent validates the legitimacy of the service account token provided as an Authorization header by creating a TokenReview resource.
Appears in: - GaleraAgent
Field Description Default Validation enabled boolean Enabled is a flag to enable KubernetesAuth authDelegatorRoleName string AuthDelegatorRoleName is the name of the ClusterRoleBinding that is associated with the \"system:auth-delegator\" ClusterRole.It is necessary for creating TokenReview objects in order for the agent to validate the service account token."},{"location":"API_REFERENCE/#mariadb","title":"MariaDB","text":"MariaDB is the Schema for the mariadbs API. It is used to define MariaDB clusters.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string MariaDB metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec MariaDBSpec"},{"location":"API_REFERENCE/#mariadbmaxscalespec","title":"MariaDBMaxScaleSpec","text":"MariaDBMaxScaleSpec defines a reduced version of MaxScale to be used with the current MariaDB.
Appears in: - MariaDBSpec
Field Description Default Validation enabled boolean Enabled is a flag to enable a MaxScale instance to be used with the current MariaDB. image string Image name to be used by the MaxScale instances. The supported format is <image>:<tag>.Only MariaDB official images are supported. imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] services MaxScaleService array Services define how the traffic is forwarded to the MariaDB servers. monitor MaxScaleMonitor Monitor monitors MariaDB server instances. admin MaxScaleAdmin Admin configures the admin REST API and GUI. config MaxScaleConfig Config defines the MaxScale configuration. auth MaxScaleAuth Auth defines the credentials required for MaxScale to connect to MariaDB. metrics MaxScaleMetrics Metrics configures metrics and how to scrape them. connection ConnectionTemplate Connection provides a template to define the Connection for MaxScale. replicas integer Replicas indicates the number of desired instances. podDisruptionBudget PodDisruptionBudget PodDisruptionBudget defines the budget for replica availability. updateStrategy StatefulSetUpdateStrategy UpdateStrategy defines the update strategy for the StatefulSet object. kubernetesService ServiceTemplate KubernetesService defines a template for a Kubernetes Service object to connect to MaxScale. guiKubernetesService ServiceTemplate GuiKubernetesService define a template for a Kubernetes Service object to connect to MaxScale's GUI. requeueInterval Duration RequeueInterval is used to perform requeue reconciliations."},{"location":"API_REFERENCE/#mariadbref","title":"MariaDBRef","text":"MariaDBRef is a reference to a MariaDB object.
Appears in: - BackupSpec - ConnectionSpec - DatabaseSpec - GrantSpec - MaxScaleSpec - RestoreSpec - SqlJobSpec - UserSpec
Field Description Default Validation waitForIt boolean WaitForIt indicates whether the controller using this reference should wait for MariaDB to be ready. true"},{"location":"API_REFERENCE/#mariadbspec","title":"MariaDBSpec","text":"MariaDBSpec defines the desired state of MariaDB
Appears in: - MariaDB
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. initContainers Container array InitContainers to be used in the Pod. sidecarContainers Container array SidecarContainers to be used in the Pod. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. volumes Volume array Volumes to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints to be used in the Pod. suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false image string Image name to be used by the MariaDB instances. The supported format is <image>:<tag>.Only MariaDB official images are supported. imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources. rootPasswordSecretKeyRef GeneratedSecretKeyRef RootPasswordSecretKeyRef is a reference to a Secret key containing the root password. rootEmptyPassword boolean RootEmptyPassword indicates if the root password should be empty. Don't use this feature in production, it is only intended for development and test environments. database string Database is the name of the initial Database. username string Username is the initial username to be created by the operator once MariaDB is ready. It has all privileges on the initial database.The initial User will have ALL PRIVILEGES in the initial Database. passwordSecretKeyRef GeneratedSecretKeyRef PasswordSecretKeyRef is a reference to a Secret that contains the password to be used by the initial User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. passwordHashSecretKeyRef SecretKeySelector PasswordHashSecretKeyRef is a reference to the password hash to be used by the initial User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password hash. passwordPlugin PasswordPlugin PasswordPlugin is a reference to the password plugin and arguments to be used by the initial User. myCnf string MyCnf allows to specify the my.cnf file mounted by Mariadb.Updating this field will trigger an update to the Mariadb resource. myCnfConfigMapKeyRef ConfigMapKeySelector MyCnfConfigMapKeyRef is a reference to the my.cnf config file provided via a ConfigMap.If not provided, it will be defaulted with a reference to a ConfigMap containing the MyCnf field.If the referred ConfigMap is labeled with \"k8s.mariadb.com/watch\", an update to the Mariadb resource will be triggered when the ConfigMap is updated. timeZone string TimeZone sets the default timezone. If not provided, it defaults to SYSTEM and the timezone data is not loaded. bootstrapFrom BootstrapFrom BootstrapFrom defines a source to bootstrap from. storage Storage Storage defines the storage options to be used for provisioning the PVCs mounted by MariaDB. metrics MariadbMetrics Metrics configures metrics and how to scrape them. replication Replication Replication configures high availability via replication. This feature is still in alpha, use Galera if you are looking for a more production-ready HA. galera Galera Replication configures high availability via Galera. maxScaleRef ObjectReference MaxScaleRef is a reference to a MaxScale resource to be used with the current MariaDB.Providing this field implies delegating high availability tasks such as primary failover to MaxScale. maxScale MariaDBMaxScaleSpec MaxScale is the MaxScale specification that defines the MaxScale resource to be used with the current MariaDB.When enabling this field, MaxScaleRef is automatically set. replicas integer Replicas indicates the number of desired instances. 1 replicasAllowEvenNumber boolean disables the validation check for an odd number of replicas. false port integer Port where the instances will be listening for connections. 3306 podDisruptionBudget PodDisruptionBudget PodDisruptionBudget defines the budget for replica availability. updateStrategy UpdateStrategy UpdateStrategy defines how a MariaDB resource is updated. service ServiceTemplate Service defines a template to configure the general Service object.The network traffic of this Service will be routed to all Pods. connection ConnectionTemplate Connection defines a template to configure the general Connection object.This Connection provides the initial User access to the initial Database.It will make use of the Service to route network traffic to all Pods. primaryService ServiceTemplate PrimaryService defines a template to configure the primary Service object.The network traffic of this Service will be routed to the primary Pod. primaryConnection ConnectionTemplate PrimaryConnection defines a template to configure the primary Connection object.This Connection provides the initial User access to the initial Database.It will make use of the PrimaryService to route network traffic to the primary Pod. secondaryService ServiceTemplate SecondaryService defines a template to configure the secondary Service object.The network traffic of this Service will be routed to the secondary Pods. secondaryConnection ConnectionTemplate SecondaryConnection defines a template to configure the secondary Connection object.This Connection provides the initial User access to the initial Database.It will make use of the SecondaryService to route network traffic to the secondary Pods."},{"location":"API_REFERENCE/#mariadbmetrics","title":"MariadbMetrics","text":"MariadbMetrics defines the metrics for a MariaDB.
Appears in: - MariaDBSpec
Field Description Default Validation enabled boolean Enabled is a flag to enable Metrics exporter Exporter Exporter defines the metrics exporter container. serviceMonitor ServiceMonitor ServiceMonitor defines the ServiceMonior object. username string Username is the username of the monitoring user used by the exporter. passwordSecretKeyRef GeneratedSecretKeyRef PasswordSecretKeyRef is a reference to the password of the monitoring user used by the exporter.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password."},{"location":"API_REFERENCE/#maxscale","title":"MaxScale","text":"MaxScale is the Schema for the maxscales API. It is used to define MaxScale clusters.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string MaxScale metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec MaxScaleSpec"},{"location":"API_REFERENCE/#maxscaleadmin","title":"MaxScaleAdmin","text":"MaxScaleAdmin configures the admin REST API and GUI.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation port integer Port where the admin REST API and GUI will be exposed. guiEnabled boolean GuiEnabled indicates whether the admin GUI should be enabled."},{"location":"API_REFERENCE/#maxscaleauth","title":"MaxScaleAuth","text":"MaxScaleAuth defines the credentials required for MaxScale to connect to MariaDB.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation generate boolean Generate defies whether the operator should generate users and grants for MaxScale to work.It only supports MariaDBs specified via spec.mariaDbRef. adminUsername string AdminUsername is an admin username to call the admin REST API. It is defaulted if not provided. adminPasswordSecretKeyRef GeneratedSecretKeyRef AdminPasswordSecretKeyRef is Secret key reference to the admin password to call the admin REST API. It is defaulted if not provided. deleteDefaultAdmin boolean DeleteDefaultAdmin determines whether the default admin user should be deleted after the initial configuration. If not provided, it defaults to true. metricsUsername string MetricsUsername is an metrics username to call the REST API. It is defaulted if metrics are enabled. metricsPasswordSecretKeyRef GeneratedSecretKeyRef MetricsPasswordSecretKeyRef is Secret key reference to the metrics password to call the admib REST API. It is defaulted if metrics are enabled.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. clientUsername string ClientUsername is the user to connect to MaxScale. It is defaulted if not provided. clientPasswordSecretKeyRef GeneratedSecretKeyRef ClientPasswordSecretKeyRef is Secret key reference to the password to connect to MaxScale. It is defaulted if not provided.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. clientMaxConnections integer ClientMaxConnections defines the maximum number of connections that the client can establish.If HA is enabled, make sure to increase this value, as more MaxScale replicas implies more connections.It defaults to 30 times the number of MaxScale replicas. serverUsername string ServerUsername is the user used by MaxScale to connect to MariaDB server. It is defaulted if not provided. serverPasswordSecretKeyRef GeneratedSecretKeyRef ServerPasswordSecretKeyRef is Secret key reference to the password used by MaxScale to connect to MariaDB server. It is defaulted if not provided.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. serverMaxConnections integer ServerMaxConnections defines the maximum number of connections that the server can establish.If HA is enabled, make sure to increase this value, as more MaxScale replicas implies more connections.It defaults to 30 times the number of MaxScale replicas. monitorUsername string MonitorUsername is the user used by MaxScale monitor to connect to MariaDB server. It is defaulted if not provided. monitorPasswordSecretKeyRef GeneratedSecretKeyRef MonitorPasswordSecretKeyRef is Secret key reference to the password used by MaxScale monitor to connect to MariaDB server. It is defaulted if not provided.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. monitorMaxConnections integer MonitorMaxConnections defines the maximum number of connections that the monitor can establish.If HA is enabled, make sure to increase this value, as more MaxScale replicas implies more connections.It defaults to 30 times the number of MaxScale replicas. syncUsername string MonitoSyncUsernamerUsername is the user used by MaxScale config sync to connect to MariaDB server. It is defaulted when HA is enabled. syncPasswordSecretKeyRef GeneratedSecretKeyRef SyncPasswordSecretKeyRef is Secret key reference to the password used by MaxScale config to connect to MariaDB server. It is defaulted when HA is enabled.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. syncMaxConnections integer SyncMaxConnections defines the maximum number of connections that the sync can establish.If HA is enabled, make sure to increase this value, as more MaxScale replicas implies more connections.It defaults to 30 times the number of MaxScale replicas."},{"location":"API_REFERENCE/#maxscaleconfig","title":"MaxScaleConfig","text":"MaxScaleConfig defines the MaxScale configuration.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation params object (keys:string, values:string) Params is a key value pair of parameters to be used in the MaxScale static configuration file.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-maxscale-configuration-guide/#global-settings. volumeClaimTemplate VolumeClaimTemplate VolumeClaimTemplate provides a template to define the PVCs for storing MaxScale runtime configuration files. It is defaulted if not provided. sync MaxScaleConfigSync Sync defines how to replicate configuration across MaxScale replicas. It is defaulted when HA is enabled."},{"location":"API_REFERENCE/#maxscaleconfigsync","title":"MaxScaleConfigSync","text":"MaxScaleConfigSync defines how the config changes are replicated across replicas.
Appears in: - MaxScaleConfig
Field Description Default Validation database string Database is the MariaDB logical database where the 'maxscale_config' table will be created in order to persist and synchronize config changes. If not provided, it defaults to 'mysql'. interval Duration Interval defines the config synchronization interval. It is defaulted if not provided. timeout Duration Interval defines the config synchronization timeout. It is defaulted if not provided."},{"location":"API_REFERENCE/#maxscalelistener","title":"MaxScaleListener","text":"MaxScaleListener defines how the MaxScale server will listen for connections.
Appears in: - MaxScaleService
Field Description Default Validation suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false name string Name is the identifier of the listener. It is defaulted if not provided port integer Port is the network port where the MaxScale server will listen. Required: {} protocol string Protocol is the MaxScale protocol to use when communicating with the client. If not provided, it defaults to MariaDBProtocol. params object (keys:string, values:string) Params defines extra parameters to pass to the listener.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-maxscale-configuration-guide/#listener_1."},{"location":"API_REFERENCE/#maxscalemetrics","title":"MaxScaleMetrics","text":"MaxScaleMetrics defines the metrics for a Maxscale.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation enabled boolean Enabled is a flag to enable Metrics exporter Exporter Exporter defines the metrics exporter container. serviceMonitor ServiceMonitor ServiceMonitor defines the ServiceMonior object."},{"location":"API_REFERENCE/#maxscalemonitor","title":"MaxScaleMonitor","text":"MaxScaleMonitor monitors MariaDB server instances
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false name string Name is the identifier of the monitor. It is defaulted if not provided. module MonitorModule Module is the module to use to monitor MariaDB servers. It is mandatory when no MariaDB reference is provided. interval Duration Interval used to monitor MariaDB servers. It is defaulted if not provided. cooperativeMonitoring CooperativeMonitoring CooperativeMonitoring enables coordination between multiple MaxScale instances running monitors. It is defaulted when HA is enabled. Enum: [majority_of_all majority_of_running] params object (keys:string, values:string) Params defines extra parameters to pass to the monitor.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-common-monitor-parameters/.Monitor specific parameter are also suported:https://mariadb.com/kb/en/mariadb-maxscale-2308-galera-monitor/#galera-monitor-optional-parameters.https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-monitor/#configuration."},{"location":"API_REFERENCE/#maxscaleserver","title":"MaxScaleServer","text":"MaxScaleServer defines a MariaDB server to forward traffic to.
Appears in: - MaxScaleSpec
Field Description Default Validation name string Name is the identifier of the MariaDB server. Required: {} address string Address is the network address of the MariaDB server. Required: {} port integer Port is the network port of the MariaDB server. If not provided, it defaults to 3306. protocol string Protocol is the MaxScale protocol to use when communicating with this MariaDB server. If not provided, it defaults to MariaDBBackend. maintenance boolean Maintenance indicates whether the server is in maintenance mode. params object (keys:string, values:string) Params defines extra parameters to pass to the server.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-maxscale-configuration-guide/#server_1."},{"location":"API_REFERENCE/#maxscaleservice","title":"MaxScaleService","text":"Services define how the traffic is forwarded to the MariaDB servers.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false name string Name is the identifier of the MaxScale service. Required: {} router ServiceRouter Router is the type of router to use. Enum: [readwritesplit readconnroute] Required: {} listener MaxScaleListener MaxScaleListener defines how the MaxScale server will listen for connections. Required: {} params object (keys:string, values:string) Params defines extra parameters to pass to the service.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-maxscale-configuration-guide/#service_1.Router specific parameter are also suported:https://mariadb.com/kb/en/mariadb-maxscale-2308-readwritesplit/#configuration.https://mariadb.com/kb/en/mariadb-maxscale-2308-readconnroute/#configuration."},{"location":"API_REFERENCE/#maxscalespec","title":"MaxScaleSpec","text":"MaxScaleSpec defines the desired state of MaxScale.
Appears in: - MaxScale
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. initContainers Container array InitContainers to be used in the Pod. sidecarContainers Container array SidecarContainers to be used in the Pod. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. volumes Volume array Volumes to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints to be used in the Pod. suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false mariaDbRef MariaDBRef MariaDBRef is a reference to the MariaDB that MaxScale points to. It is used to initialize the servers field. servers MaxScaleServer array Servers are the MariaDB servers to forward traffic to. It is required if 'spec.mariaDbRef' is not provided. image string Image name to be used by the MaxScale instances. The supported format is <image>:<tag>.Only MaxScale official images are supported. imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources. services MaxScaleService array Services define how the traffic is forwarded to the MariaDB servers. It is defaulted if not provided. monitor MaxScaleMonitor Monitor monitors MariaDB server instances. It is required if 'spec.mariaDbRef' is not provided. admin MaxScaleAdmin Admin configures the admin REST API and GUI. config MaxScaleConfig Config defines the MaxScale configuration. auth MaxScaleAuth Auth defines the credentials required for MaxScale to connect to MariaDB. metrics MaxScaleMetrics Metrics configures metrics and how to scrape them. connection ConnectionTemplate Connection provides a template to define the Connection for MaxScale. replicas integer Replicas indicates the number of desired instances. 1 podDisruptionBudget PodDisruptionBudget PodDisruptionBudget defines the budget for replica availability. updateStrategy StatefulSetUpdateStrategy UpdateStrategy defines the update strategy for the StatefulSet object. kubernetesService ServiceTemplate KubernetesService defines a template for a Kubernetes Service object to connect to MaxScale. guiKubernetesService ServiceTemplate GuiKubernetesService defines a template for a Kubernetes Service object to connect to MaxScale's GUI. requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. If not defined, it defaults to 10s."},{"location":"API_REFERENCE/#metadata","title":"Metadata","text":"Metadata defines the metadata to added to resources.
Appears in: - BackupSpec - Exporter - GaleraRecoveryJob - Job - JobPodTemplate - MariaDBSpec - MaxScaleSpec - PodTemplate - RestoreSpec - SecretTemplate - ServiceTemplate - SqlJobSpec - VolumeClaimTemplate
Field Description Default Validation labels object (keys:string, values:string) Labels to be added to children resources. annotations object (keys:string, values:string) Annotations to be added to children resources."},{"location":"API_REFERENCE/#monitormodule","title":"MonitorModule","text":"Underlying type: string
MonitorModule defines the type of monitor module
Appears in: - MaxScaleMonitor
Field Description mariadbmon MonitorModuleMariadb is a monitor to be used with MariaDB servers. galeramon MonitorModuleGalera is a monitor to be used with Galera servers."},{"location":"API_REFERENCE/#passwordplugin","title":"PasswordPlugin","text":"PasswordPlugin defines the password plugin and its arguments.
Appears in: - MariaDBSpec - UserSpec
Field Description Default Validation pluginNameSecretKeyRef SecretKeySelector PluginNameSecretKeyRef is a reference to the authentication plugin to be used by the User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the authentication plugin. pluginArgSecretKeyRef SecretKeySelector PluginArgSecretKeyRef is a reference to the arguments to be provided to the authentication plugin for the User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the authentication plugin arguments."},{"location":"API_REFERENCE/#poddisruptionbudget","title":"PodDisruptionBudget","text":"PodDisruptionBudget is the Pod availability bundget for a MariaDB
Appears in: - MariaDBMaxScaleSpec - MariaDBSpec - MaxScaleSpec
Field Description Default Validation minAvailable IntOrString MinAvailable defines the number of minimum available Pods. maxUnavailable IntOrString MaxUnavailable defines the number of maximum unavailable Pods."},{"location":"API_REFERENCE/#podtemplate","title":"PodTemplate","text":"PodTemplate defines a template to configure Container objects.
Appears in: - Exporter - MariaDBSpec - MaxScaleSpec
Field Description Default Validation podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. initContainers Container array InitContainers to be used in the Pod. sidecarContainers Container array SidecarContainers to be used in the Pod. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. volumes Volume array Volumes to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints to be used in the Pod."},{"location":"API_REFERENCE/#primarygalera","title":"PrimaryGalera","text":"PrimaryGalera is the Galera configuration for the primary node.
Appears in: - Galera - GaleraSpec
Field Description Default Validation podIndex integer PodIndex is the StatefulSet index of the primary node. The user may change this field to perform a manual switchover. automaticFailover boolean AutomaticFailover indicates whether the operator should automatically update PodIndex to perform an automatic primary failover."},{"location":"API_REFERENCE/#primaryreplication","title":"PrimaryReplication","text":"PrimaryReplication is the replication configuration for the primary node.
Appears in: - Replication - ReplicationSpec
Field Description Default Validation podIndex integer PodIndex is the StatefulSet index of the primary node. The user may change this field to perform a manual switchover. automaticFailover boolean AutomaticFailover indicates whether the operator should automatically update PodIndex to perform an automatic primary failover."},{"location":"API_REFERENCE/#replicareplication","title":"ReplicaReplication","text":"ReplicaReplication is the replication configuration for the replica nodes.
Appears in: - Replication - ReplicationSpec
Field Description Default Validation waitPoint WaitPoint WaitPoint defines whether the transaction should wait for ACK before committing to the storage engine.More info: https://mariadb.com/kb/en/semisynchronous-replication/#rpl_semi_sync_master_wait_point. Enum: [AfterSync AfterCommit] gtid Gtid Gtid indicates which Global Transaction ID should be used when connecting a replica to the master.See: https://mariadb.com/kb/en/gtid/#using-current_pos-vs-slave_pos. Enum: [CurrentPos SlavePos] replPasswordSecretKeyRef GeneratedSecretKeyRef ReplPasswordSecretKeyRef provides a reference to the Secret to use as password for the replication user. connectionTimeout Duration ConnectionTimeout to be used when the replica connects to the primary. connectionRetries integer ConnectionRetries to be used when the replica connects to the primary. syncTimeout Duration SyncTimeout defines the timeout for a replica to be synced with the primary when performing a primary switchover.If the timeout is reached, the replica GTID will be reset and the switchover will continue."},{"location":"API_REFERENCE/#replication","title":"Replication","text":"Replication allows you to enable single-master HA via semi-synchronours replication in your MariaDB cluster.
Appears in: - MariaDBSpec
Field Description Default Validation primary PrimaryReplication Primary is the replication configuration for the primary node. replica ReplicaReplication ReplicaReplication is the replication configuration for the replica nodes. syncBinlog boolean SyncBinlog indicates whether the binary log should be synchronized to the disk after every event.It trades off performance for consistency.See: https://mariadb.com/kb/en/replication-and-binary-log-system-variables/#sync_binlog. probesEnabled boolean ProbesEnabled indicates to use replication specific liveness and readiness probes.This probes check that the primary can receive queries and that the replica has the replication thread running. enabled boolean Enabled is a flag to enable Replication."},{"location":"API_REFERENCE/#replicationspec","title":"ReplicationSpec","text":"ReplicationSpec is the Replication desired state specification.
Appears in: - Replication
Field Description Default Validation primary PrimaryReplication Primary is the replication configuration for the primary node. replica ReplicaReplication ReplicaReplication is the replication configuration for the replica nodes. syncBinlog boolean SyncBinlog indicates whether the binary log should be synchronized to the disk after every event.It trades off performance for consistency.See: https://mariadb.com/kb/en/replication-and-binary-log-system-variables/#sync_binlog. probesEnabled boolean ProbesEnabled indicates to use replication specific liveness and readiness probes.This probes check that the primary can receive queries and that the replica has the replication thread running."},{"location":"API_REFERENCE/#restore","title":"Restore","text":"Restore is the Schema for the restores API. It is used to define restore jobs and its restoration source.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Restore metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec RestoreSpec"},{"location":"API_REFERENCE/#restoresource","title":"RestoreSource","text":"RestoreSource defines a source for restoring a MariaDB.
Appears in: - BootstrapFrom - RestoreSpec
Field Description Default Validation backupRef LocalObjectReference BackupRef is a reference to a Backup object. It has priority over S3 and Volume. s3 S3 S3 defines the configuration to restore backups from a S3 compatible storage. It has priority over Volume. volume VolumeSource Volume is a Kubernetes Volume object that contains a backup. targetRecoveryTime Time TargetRecoveryTime is a RFC3339 (1970-01-01T00:00:00Z) date and time that defines the point in time recovery objective.It is used to determine the closest restoration source in time."},{"location":"API_REFERENCE/#restorespec","title":"RestoreSpec","text":"RestoreSpec defines the desired state of restore
Appears in: - Restore
Field Description Default Validation args string array Args to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. backupRef LocalObjectReference BackupRef is a reference to a Backup object. It has priority over S3 and Volume. s3 S3 S3 defines the configuration to restore backups from a S3 compatible storage. It has priority over Volume. volume VolumeSource Volume is a Kubernetes Volume object that contains a backup. targetRecoveryTime Time TargetRecoveryTime is a RFC3339 (1970-01-01T00:00:00Z) date and time that defines the point in time recovery objective.It is used to determine the closest restoration source in time. mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} database string Database defines the logical database to be restored. If not provided, all databases available in the backup are restored.IMPORTANT: The database must previously exist. logLevel string LogLevel to be used n the Backup Job. It defaults to 'info'. info backoffLimit integer BackoffLimit defines the maximum number of attempts to successfully perform a Backup. 5 restartPolicy RestartPolicy RestartPolicy to be added to the Backup Job. OnFailure Enum: [Always OnFailure Never] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources."},{"location":"API_REFERENCE/#s3","title":"S3","text":"Appears in: - BackupStorage - BootstrapFrom - RestoreSource - RestoreSpec
Field Description Default Validation bucket string Bucket is the name Name of the bucket to store backups. Required: {} endpoint string Endpoint is the S3 API endpoint without scheme. Required: {} region string Region is the S3 region name to use. prefix string Prefix indicates a folder/subfolder in the bucket. For example: mariadb/ or mariadb/backups. A trailing slash '/' is added if not provided. accessKeyIdSecretKeyRef SecretKeySelector AccessKeyIdSecretKeyRef is a reference to a Secret key containing the S3 access key id. Required: {} secretAccessKeySecretKeyRef SecretKeySelector AccessKeyIdSecretKeyRef is a reference to a Secret key containing the S3 secret key. Required: {} sessionTokenSecretKeyRef SecretKeySelector SessionTokenSecretKeyRef is a reference to a Secret key containing the S3 session token. tls TLS TLS provides the configuration required to establish TLS connections with S3."},{"location":"API_REFERENCE/#sqltemplate","title":"SQLTemplate","text":"SQLTemplate defines a template to customize SQL objects.
Appears in: - DatabaseSpec - GrantSpec - UserSpec
Field Description Default Validation requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. retryInterval Duration RetryInterval is the interval used to perform retries. cleanupPolicy CleanupPolicy CleanupPolicy defines the behavior for cleaning up a SQL resource. Enum: [Skip Delete]"},{"location":"API_REFERENCE/#sst","title":"SST","text":"Underlying type: string
SST is the Snapshot State Transfer used when new Pods join the cluster. More info: https://galeracluster.com/library/documentation/sst.html.
Appears in: - Galera - GaleraSpec
Field Description rsync SSTRsync is an SST based on rsync. mariabackup SSTMariaBackup is an SST based on mariabackup. It is the recommended SST. mysqldump SSTMysqldump is an SST based on mysqldump."},{"location":"API_REFERENCE/#schedule","title":"Schedule","text":"Schedule contains parameters to define a schedule
Appears in: - BackupSpec - SqlJobSpec
Field Description Default Validation cron string Cron is a cron expression that defines the schedule. Required: {} suspend boolean Suspend defines whether the schedule is active or not. false"},{"location":"API_REFERENCE/#secrettemplate","title":"SecretTemplate","text":"SecretTemplate defines a template to customize Secret objects.
Appears in: - ConnectionSpec - ConnectionTemplate
Field Description Default Validation metadata Metadata Refer to Kubernetes API documentation for fields of metadata. key string Key to be used in the Secret. format string Format to be used in the Secret. usernameKey string UsernameKey to be used in the Secret. passwordKey string PasswordKey to be used in the Secret. hostKey string HostKey to be used in the Secret. portKey string PortKey to be used in the Secret. databaseKey string DatabaseKey to be used in the Secret."},{"location":"API_REFERENCE/#servicemonitor","title":"ServiceMonitor","text":"ServiceMonitor defines a prometheus ServiceMonitor object.
Appears in: - MariadbMetrics - MaxScaleMetrics
Field Description Default Validation prometheusRelease string PrometheusRelease is the release label to add to the ServiceMonitor object. jobLabel string JobLabel to add to the ServiceMonitor object. interval string Interval for scraping metrics. scrapeTimeout string ScrapeTimeout defines the timeout for scraping metrics."},{"location":"API_REFERENCE/#servicerouter","title":"ServiceRouter","text":"Underlying type: string
ServiceRouter defines the type of service router.
Appears in: - MaxScaleService
Field Description readwritesplit ServiceRouterReadWriteSplit splits the load based on the queries. Write queries are performed on master and read queries on the replicas. readconnroute ServiceRouterReadConnRoute splits the load based on the connections. Each connection is assigned to a server."},{"location":"API_REFERENCE/#servicetemplate","title":"ServiceTemplate","text":"ServiceTemplate defines a template to customize Service objects.
Appears in: - MariaDBMaxScaleSpec - MariaDBSpec - MaxScaleSpec
Field Description Default Validation type ServiceType Type is the Service type. One of ClusterIP, NodePort or LoadBalancer. If not defined, it defaults to ClusterIP. ClusterIP Enum: [ClusterIP NodePort LoadBalancer] metadata Metadata Refer to Kubernetes API documentation for fields of metadata. loadBalancerIP string LoadBalancerIP Service field. loadBalancerSourceRanges string array LoadBalancerSourceRanges Service field. externalTrafficPolicy ServiceExternalTrafficPolicy ExternalTrafficPolicy Service field. sessionAffinity ServiceAffinity SessionAffinity Service field. allocateLoadBalancerNodePorts boolean AllocateLoadBalancerNodePorts Service field."},{"location":"API_REFERENCE/#sqljob","title":"SqlJob","text":"SqlJob is the Schema for the sqljobs API. It is used to run sql scripts as jobs.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string SqlJob metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec SqlJobSpec"},{"location":"API_REFERENCE/#sqljobspec","title":"SqlJobSpec","text":"SqlJobSpec defines the desired state of SqlJob
Appears in: - SqlJob
Field Description Default Validation args string array Args to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. successfulJobsHistoryLimit integer Minimum: 0 failedJobsHistoryLimit integer Minimum: 0 timeZone string mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} schedule Schedule Schedule defines when the SqlJob will be executed. username string Username to be impersonated when executing the SqlJob. Required: {} passwordSecretKeyRef SecretKeySelector UserPasswordSecretKeyRef is a reference to the impersonated user's password to be used when executing the SqlJob. Required: {} database string Username to be used when executing the SqlJob. dependsOn LocalObjectReference array DependsOn defines dependencies with other SqlJob objectecs. sql string Sql is the script to be executed by the SqlJob. sqlConfigMapKeyRef ConfigMapKeySelector SqlConfigMapKeyRef is a reference to a ConfigMap containing the Sql script.It is defaulted to a ConfigMap with the contents of the Sql field. backoffLimit integer BackoffLimit defines the maximum number of attempts to successfully execute a SqlJob. 5 restartPolicy RestartPolicy RestartPolicy to be added to the SqlJob Pod. OnFailure Enum: [Always OnFailure Never] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources."},{"location":"API_REFERENCE/#storage","title":"Storage","text":"Storage defines the storage options to be used for provisioning the PVCs mounted by MariaDB.
Appears in: - MariaDBSpec
Field Description Default Validation ephemeral boolean Ephemeral indicates whether to use ephemeral storage in the PVCs. It is only compatible with non HA MariaDBs. size Quantity Size of the PVCs to be mounted by MariaDB. Required if not provided in 'VolumeClaimTemplate'. It superseeds the storage size specified in 'VolumeClaimTemplate'. storageClassName string StorageClassName to be used to provision the PVCS. It superseeds the 'StorageClassName' specified in 'VolumeClaimTemplate'.If not provided, the default 'StorageClass' configured in the cluster is used. resizeInUseVolumes boolean ResizeInUseVolumes indicates whether the PVCs can be resized. The 'StorageClassName' used should have 'allowVolumeExpansion' set to 'true' to allow resizing.It defaults to true. waitForVolumeResize boolean WaitForVolumeResize indicates whether to wait for the PVCs to be resized before marking the MariaDB object as ready. This will block other operations such as cluster recovery while the resize is in progress.It defaults to true. volumeClaimTemplate VolumeClaimTemplate VolumeClaimTemplate provides a template to define the PVCs."},{"location":"API_REFERENCE/#suspendtemplate","title":"SuspendTemplate","text":"SuspendTemplate indicates whether the current resource should be suspended or not.
Appears in: - MariaDBSpec - MaxScaleListener - MaxScaleMonitor - MaxScaleService - MaxScaleSpec
Field Description Default Validation suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false"},{"location":"API_REFERENCE/#tls","title":"TLS","text":"Appears in: - S3
Field Description Default Validation enabled boolean Enabled is a flag to enable TLS. caSecretKeyRef SecretKeySelector CASecretKeyRef is a reference to a Secret key containing a CA bundle in PEM format used to establish TLS connections with S3.By default, the system trust chain will be used, but you can use this field to add more CAs to the bundle."},{"location":"API_REFERENCE/#updatestrategy","title":"UpdateStrategy","text":"UpdateStrategy defines how a MariaDB resource is updated.
Appears in: - MariaDBSpec
Field Description Default Validation type UpdateType Type defines the type of updates. One of ReplicasFirstPrimaryLast, RollingUpdate or OnDelete. If not defined, it defaults to ReplicasFirstPrimaryLast. ReplicasFirstPrimaryLast Enum: [ReplicasFirstPrimaryLast RollingUpdate OnDelete] rollingUpdate RollingUpdateStatefulSetStrategy RollingUpdate defines parameters for the RollingUpdate type."},{"location":"API_REFERENCE/#updatetype","title":"UpdateType","text":"Underlying type: string
UpdateType defines the type of update for a MariaDB resource.
Appears in: - UpdateStrategy
Field Description ReplicasFirstPrimaryLast ReplicasFirstPrimaryLast indicates that the update will be applied to all replica Pods first and later on to the primary Pod.The updates are applied one by one waiting until each Pod passes the readiness probei.e. the Pod gets synced and it is ready to receive traffic. RollingUpdate RollingUpdateUpdateType indicates that the update will be applied by the StatefulSet controller using the RollingUpdate strategy.This strategy is unaware of the roles that the Pod have (primary or replica) and it willperform the update following the StatefulSet ordinal, from higher to lower. OnDelete OnDeleteUpdateType indicates that the update will be applied by the StatefulSet controller using the OnDelete strategy.The update will be done when the Pods get manually deleted by the user."},{"location":"API_REFERENCE/#user","title":"User","text":"User is the Schema for the users API. It is used to define grants as if you were running a 'CREATE USER' statement.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string User metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec UserSpec"},{"location":"API_REFERENCE/#userspec","title":"UserSpec","text":"UserSpec defines the desired state of User
Appears in: - User
Field Description Default Validation requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. retryInterval Duration RetryInterval is the interval used to perform retries. cleanupPolicy CleanupPolicy CleanupPolicy defines the behavior for cleaning up a SQL resource. Enum: [Skip Delete] mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} passwordSecretKeyRef SecretKeySelector PasswordSecretKeyRef is a reference to the password to be used by the User.If not provided, the account will be locked and the password will expire.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. passwordHashSecretKeyRef SecretKeySelector PasswordHashSecretKeyRef is a reference to the password hash to be used by the User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password hash. passwordPlugin PasswordPlugin PasswordPlugin is a reference to the password plugin and arguments to be used by the User. maxUserConnections integer MaxUserConnections defines the maximum number of connections that the User can establish. 10 name string Name overrides the default name provided by metadata.name. MaxLength: 80 host string Host related to the User. MaxLength: 255"},{"location":"API_REFERENCE/#volumeclaimtemplate","title":"VolumeClaimTemplate","text":"VolumeClaimTemplate defines a template to customize PVC objects.
Appears in: - GaleraConfig - MaxScaleConfig - Storage
Field Description Default Validation metadata Metadata Refer to Kubernetes API documentation for fields of metadata."},{"location":"API_REFERENCE/#waitpoint","title":"WaitPoint","text":"Underlying type: string
WaitPoint defines whether the transaction should wait for ACK before committing to the storage engine. More info: https://mariadb.com/kb/en/semisynchronous-replication/#rpl_semi_sync_master_wait_point.
Appears in: - ReplicaReplication
Field Description AfterSync WaitPointAfterSync indicates that the primary waits for the replica ACK before committing the transaction to the storage engine.This is the default WaitPoint. It trades off performance for consistency. AfterCommit WaitPointAfterCommit indicates that the primary commits the transaction to the storage engine and waits for the replica ACK afterwards.It trades off consistency for performance."},{"location":"BACKUP/","title":"Backup and Restore","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.28
mariadb-operator allows you to declarativaly take backups by defining Backup resources and later on restore them by using their Restore counterpart. These resources get reconciled into Job/CronJob resources that automatically perform the backup/restore operations, so you don't need to manually script them.
"},{"location":"BACKUP/#table-of-contents","title":"Table of contents","text":" - Storage types
Backup CRRestore CR- Bootstrap new
MariaDB instances - Backup and restore specific databases
- Extra options
- Important considerations and limitations
- Migrating to a
MariaDB with different topology - Minio reference installation
- Reference
- Troubleshooting
"},{"location":"BACKUP/#storage-types","title":"Storage types","text":"Currently, the following storage types are supported: - S3 compatible storage: Store backups in a S3 compatible storage, such as AWS S3 or Minio. - PVCs: Use the available StorageClasses in your Kubernetes cluster to provision a PVC dedicated to store the backup files. - Kubernetes volumes: Use any of the volume types supported natively by Kubernetes.
Our recommendation is to store the backups externally in a S3 compatible storage. Minio makes this incredibly easy, take a look at our Minio reference installation to quickly spin up an instance.
"},{"location":"BACKUP/#backup-cr","title":"Backup CR","text":"You can take a one-time backup of your MariaDB instance by declaring the following resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n storage:\n persistentVolumeClaim:\n resources:\n requests:\n storage: 100Mi\n accessModes:\n - ReadWriteOnce\n
This will use the default StorageClass to provision a PVC that would hold the backup files, but ideally you should use a S3 compatible storage:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n storage:\n s3:\n bucket: backups\n prefix: mariadb\n endpoint: minio.minio.svc.cluster.local:9000\n region: us-east-1\n accessKeyIdSecretKeyRef:\n name: minio\n key: access-key-id\n secretAccessKeySecretKeyRef:\n name: minio\n key: secret-access-key\n tls:\n enabled: true\n caSecretKeyRef:\n name: minio-ca\n key: ca.crt\n
By providing the authentication details and the TLS configuration via references to Secret keys, this example will store the backups in a local Minio instance.
"},{"location":"BACKUP/#scheduling","title":"Scheduling","text":"To minimize the Recovery Point Objective (RPO) and mitigate the risk of data loss, it is recommended to perform backups regularly. You can do so by providing a spec.schedule in your Backup resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup-scheduled\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n schedule:\n cron: \"*/1 * * * *\"\n suspend: false\n
This resource gets reconciled into a CronJob that periodically takes the backups.
It is important to note that regularly scheduled Backups complement very well the target recovery time feature detailed below.
"},{"location":"BACKUP/#retention-policy","title":"Retention policy","text":"Given that the backups can consume a substantial amount of storage, it is crucial to define your retention policy by providing the spec.maxRetention field in your Backup resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup-scheduled\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n maxRetention: 720h # 30 days\n
By default, it will be set to 720h (30 days), indicating that backups older than 30 days will be automatically deleted.
"},{"location":"BACKUP/#restore-cr","title":"Restore CR","text":"You can easily restore a Backup in your MariaDB instance by creating the following resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n
This will trigger a Job that will mount the same storage as the Backup and apply the dump to your MariaDB database.
Nevertheless, the Restore resource doesn't necessarily need to specify a spec.backupRef, you can point to other storage source that contains backup files, for example a S3 bucket:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n s3:\n bucket: backups\n prefix: mariadb\n endpoint: minio.minio.svc.cluster.local:9000\n region: us-east-1\n accessKeyIdSecretKeyRef:\n name: minio\n key: access-key-id\n secretAccessKeySecretKeyRef:\n name: minio\n key: secret-access-key\n tls:\n enabled: true\n caSecretKeyRef:\n name: minio-ca\n key: ca.crt\n
"},{"location":"BACKUP/#target-recovery-time","title":"Target recovery time","text":"If you have multiple backups available, specially after configuring a scheduled Backup, the operator is able to infer which backup to restore based on the spec.targetRecoveryTime field.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n targetRecoveryTime: 2023-12-19T09:00:00Z\n
The operator will look for the closest backup available and utilize it to restore your MariaDB instance.
By default, spec.targetRecoveryTime will be set to the current time, which means that the latest available backup will be used.
"},{"location":"BACKUP/#bootstrap-new-mariadb-instances","title":"Bootstrap new MariaDB instances","text":"To minimize your Recovery Time Objective (RTO) and to switfly spin up new clusters from existing Backups, you can provide a Restore source directly in the MariaDB object via the spec.bootstrapFrom field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-from-backup\nspec:\n volumeClaimTemplate:\n resources:\n requests:\n storage: 1Gi\n accessModes:\n - ReadWriteOnce\n bootstrapFrom:\n backupRef:\n name: backup\n targetRecoveryTime: 2023-12-19T09:00:00Z\n
As in the Restore resource, you don't strictly need to specify a reference to a Backup, you can provide other storage types that contain backup files:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-from-backup\nspec:\n volumeClaimTemplate:\n resources:\n requests:\n storage: 1Gi\n accessModes:\n - ReadWriteOnce\n bootstrapFrom:\n s3:\n bucket: backups\n prefix: mariadb\n endpoint: minio.minio.svc.cluster.local:9000\n accessKeyIdSecretKeyRef:\n name: minio\n key: access-key-id\n secretAccessKeySecretKeyRef:\n name: minio\n key: secret-access-key\n tls:\n enabled: true\n caSecretKeyRef:\n name: minio-ca\n key: ca.crt\n targetRecoveryTime: 2023-12-19T09:00:00Z\n
Under the hood, the operator creates a Restore object just after the MariaDB resource becomes ready. The advantage of using spec.bootstrapFrom over a standalone Restore is that the MariaDB is bootstrap-aware and this will allow the operator to hold primary switchover/failover operations until the restoration is finished.
"},{"location":"BACKUP/#backup-and-restore-specific-databases","title":"Backup and restore specific databases","text":"By default, all the logical databases are backed up when a Backup is created, but you may also select specific databases by providing the databases field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n databases:\n - db1\n - db2\n - db3\n
When it comes to restore, all the databases available in the backup will be restored, but you may also choose a single database to be restored via the database field available in the Restore resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n databases: db1\n
There are a couple of points to consider here: - The referred database (db1 in the example) must previously exist for the Restore to succeed. - The mariadb CLI invoked by the operator under the hood only supports selecting a single database to restore via the --one-database option, restoration of multiple specific databases is not supported.
"},{"location":"BACKUP/#extra-options","title":"Extra options","text":"Not all the flags supported by mariadb-dump and mariadb have their counterpart field in the Backup and Restore CRs respectively, but you may pass extra options by using the args field. For example, setting the --verbose flag can be helpful to track the progress of backup and restore operations:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n args:\n - --verbose\n
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n args:\n - --verbose\n
Refer to the mariadb-dump and mariadb CLI options in the reference section.
"},{"location":"BACKUP/#important-considerations-and-limitations","title":"Important considerations and limitations","text":""},{"location":"BACKUP/#root-credentials","title":"Root credentials","text":"When restoring a backup, the root credentials specified through the spec.rootPasswordSecretKeyRef field in the MariaDB resource must match the ones in the backup. These credentials are utilized by the liveness and readiness probes, and if they are invalid, the probes will fail, causing your MariaDB Pods to restart after the backup restoration.
"},{"location":"BACKUP/#restore-job","title":"Restore job","text":"Restoring large backups can consume significant compute resources and may cause Restore Jobs to become stuck due to insufficient resources. To prevent this, you can define the compute resources allocated to the Job:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n bootstrapFrom:\n restoreJob:\n args:\n - --verbose\n resources:\n requests:\n cpu: 100m\n memory: 128Mi\n limits:\n memory: 1Gi\n
"},{"location":"BACKUP/#galera-backup-limitations","title":"Galera backup limitations","text":""},{"location":"BACKUP/#mysqlglobal_priv","title":"mysql.global_priv","text":"Galera only replicates the tables with InnoDB engine: - https://galeracluster.com/library/kb/user-changes.html
Something that does not include mysql.global_priv, the table used to store users and grants, which uses the MyISAM engine. This basically means that a Galera instance with mysql.global_priv populated will not replicate this data to an empty Galera instance. However, DDL statements (CREATE USER, ALTER USER ...) will be replicated.
Taking this into account, if we think now about a restore scenario where: - The backup file includes a DROP TABLE statement for the mysql.global_priv table. - The backup has some INSERT statements for the mysql.global_priv table. - The Galera cluster has 3 nodes: galera-0, galera-1 and galera-2. - The backup is restored in galera-0.
This is what will happen under the scenes while restoring the backup: - The DROP TABLE statement is a DDL so it will be executed in galera-0, galera-1 and galera-2. - The INSERT statements are not DDLs, so they will only be applied to galera-0. - This results in the galera-1 and galera-2 not having the mysql.global_priv table.
After the backup is fully restored, the liveness and readiness probes will kick in, they will succeed in galera-0, but they will fail in galera-1 and galera-2, as they rely in the root credentials available in mysql.global_priv, resulting in the galera-1 and galera-2 getting restarted.
To address this issue, when backing up MariaDB instances with Galera enabled, the mysql.global_priv table will be excluded from backups by using the --ignore-table option with mariadb-dump. This prevents the replication of the DROP TABLE statement for the mysql.global_priv table. You can opt-out from this feature by setting spec.ignoreGlobalPriv=false in the Backup resource.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n ignoreGlobalPriv: false\n
Also, to avoid situations where mysql.global_priv is unreplicated, all the entries in that table must be managed via DDLs. This is the recommended approach suggested in the Galera docs. There are a couple of ways that we can guarantee this: - Use the rootPasswordSecretKeyRef, username and passwordSecretKeyRef fields of the MariaDB CR to create the root and initial user respectively. This fields will be translated into DDLs by the image entrypoint. - Rely on the User and Grant CRs to create additional users and grants. They will be translated into DDL statements (CREATE USER, GRANT) by the operator.
"},{"location":"BACKUP/#lock-tables","title":"LOCK TABLES","text":"Galera is not compatible with the LOCK TABLES statement: - https://mariadb.com/kb/en/lock-tables/#limitations
For this reason, the operator automatically adds the --skip-add-locks option to the Backup to overcome this limitation.
"},{"location":"BACKUP/#migrating-to-a-mariadb-with-different-topology","title":"Migrating to a MariaDB with different topology","text":"Logical backups serve not just as a source of restoration, but also enable data mobility between MariaDB instances. These backups are called \"logical\" because they are independent from the MariaDB topology, as they only contain DDLs and INSERT statements to populate data.
Although backing up and restoring data from MariaDBs with different topologies is possible, there are a couple of technical details that you need to be aware of in the following scenarios:
"},{"location":"BACKUP/#migrating-between-standalone-and-replicated-mariadbs","title":"Migrating between standalone and replicated MariaDBs","text":"This should be fully compatible, no issues have been detected.
"},{"location":"BACKUP/#migrating-from-standalonereplicated-to-galera-mariadbs","title":"Migrating from standalone/replicated to Galera MariaDBs","text":"There are a couple of limitations regarding the backups in Galera, please make sure you read the Galera backup limitations section before proceeding.
To overcome this limitations, the Backup in the standalone/replicated instance needs to be taken with spec.ignoreGlobalPriv=true. In the following example, we are backing up a standalone MariaDB (single instance):
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup-standalone\nspec:\n mariaDbRef:\n name: mariadb-standalone\n ignoreGlobalPriv: true\n
Once the previous Backup is completed, we will be able bootstrap a new Galera instance from it:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n galera:\n enabled: true\n bootstrapFrom:\n backupRef:\n name: backup-standalone\n
"},{"location":"BACKUP/#minio-reference-installation","title":"Minio reference installation","text":"The easiest way to get a S3 compatible storage is Minio. You can install it by using their helm chart, or, if you are looking for a production-grade deployment, take a look at their operator.
In our case, we have have configured a Minio instance for development purposes, you can easily install it by running:
make cluster\nmake install-minio\nmake net # to access the console via a MetalLB LoadBalancer: https://minio-console:9001\n
As an alternative, you can also use play.min.io using these credentials.
"},{"location":"BACKUP/#reference","title":"Reference","text":" - API reference
- Example suite
mariadb-dump optionsmariadb options
"},{"location":"BACKUP/#troubleshooting","title":"Troubleshooting","text":""},{"location":"BACKUP/#galera-pods-restarting-after-bootstrapping-from-a-backup","title":"Galera Pods restarting after bootstrapping from a backup","text":"Please make sure you understand the Galera backup limitations.
After doing so, ensure that your backup does not contain a DROP TABLE mysql.global_priv; statement, as it will make your liveness and readiness probes to fail after the backup restoration.
"},{"location":"CONFIGURATION/","title":"Configuration","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.28
This documentation aims to provide guidance on various configuration aspects across many mariadb-operator CRs.
"},{"location":"CONFIGURATION/#table-of-contents","title":"Table of contents","text":" - my.cnf
- Passwords
- External resources
- Probes
"},{"location":"CONFIGURATION/#mycnf","title":"my.cnf","text":"An inline configuration file (my.cnf) can be provisioned in the MariaDB resource via the myCnf field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n myCnf: |\n [mariadb]\n bind-address=*\n default_storage_engine=InnoDB\n binlog_format=row\n innodb_autoinc_lock_mode=2\n innodb_buffer_pool_size=1024M\n max_allowed_packet=256M \n
In this field, you may provide any configuration option or system variable supported by MariaDB.
Under the hood, the operator automatically creates a ConfigMap with the contents of the myCnf field, which will be mounted in the MariaDB instance. Alternatively, you can manage your own configuration using a pre-existing ConfigMap by linking it via myCnfConfigMapKeyRef:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n myCnfConfigMapKeyRef:\n name: mariadb\n key: mycnf\n
To ensure your configuration changes take effect, the operator triggers a rolling update whenever the myCnf field or a ConfigMap is updated. For the operator to detect changes in a ConfigMap, it must be labeled with k8s.mariadb.com/watch. Refer to the external resources section for further detail.
"},{"location":"CONFIGURATION/#passwords","title":"Passwords","text":"Some CRs require passwords provided as Secret references to function properly. For instance, the root password for a MariaDB resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n rootPasswordSecretKeyRef:\n name: mariadb\n key: root-password\n
By default, fields like rootPasswordSecretKeyRef are optional and defaulted by the operator, resulting in random password generation if not provided:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n rootPasswordSecretKeyRef:\n name: mariadb\n key: root-password\n generate: true\n
You may choose to explicitly provide a Secret reference via rootPasswordSecretKeyRef and opt-out from random password generation by either not providing the generate field or setting it to false:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n rootPasswordSecretKeyRef:\n name: mariadb\n key: root-password\n generate: false\n
This way, we are telling the operator that we are expecting a Secret to be available eventually, enabling the use of GitOps tools to seed the password: - sealed-secrets: The Secret is reconciled from a SealedSecret, which is decrypted by the sealed-secrets controller. - external-secrets: The Secret is reconciled fom an ExternalSecret, which is read by the external-secrets controller from an external secrets source (Vault, AWS Secrets Manager ...).
"},{"location":"CONFIGURATION/#external-resources","title":"External resources","text":"Many CRs have a references to external resources (i.e. ConfigMap, Secret) not managed by the operator.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n myCnfConfigMapKeyRef:\n name: mariadb\n key: mycnf\n
These external resources should be labeled with k8s.mariadb.com/watch so the operator can watch them and perform reconciliations based on their changes. For example, see the my.cnf ConfigMap:
apiVersion: v1\nkind: ConfigMap\nmetadata:\n name: mariadb\n labels:\n k8s.mariadb.com/watch: \"\"\ndata:\n my.cnf: |\n [mariadb]\n bind-address=*\n default_storage_engine=InnoDB\n binlog_format=row\n innodb_autoinc_lock_mode=2\n innodb_buffer_pool_size=1024M\n max_allowed_packet=256M\n
"},{"location":"CONFIGURATION/#probes","title":"Probes","text":"Kubernetes probes serve as an inversion of control mechanism, enabling the application to communicate its health status to Kubernetes. This enables Kubernetes to take appropriate actions when the application is unhealthy, such as restarting or stop sending traffic to Pods.
[!IMPORTANT] Make sure you check the Kubernetes documentation if you are unfamiliar with Kubernetes probes.
Fine tunning of probes for databases running in Kubernetes is critical, you may do so by tweaking the following fields:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n livenessProbe:\n initialDelaySeconds: 20\n periodSeconds: 5\n timeoutSeconds: 5\n\n readinessProbe:\n initialDelaySeconds: 20\n periodSeconds: 5\n timeoutSeconds: 5\n
There isn't an universally correct default value for these thresholds, so we recommend determining your own based on factors like the compute resources, network, storage, and other aspects of the environment where your MariaDB and MaxScale instances are running.
"},{"location":"DEVELOPMENT/","title":"Development guide","text":"In this guide, we will be configuring a local environment to run mariadb-operator so you can develop and test features without hassle. The local mariadb-operator will be able to resolve DNS and connect to MariaDB as if it was running inside a Kubernetes cluster.
"},{"location":"DEVELOPMENT/#table-of-contents","title":"Table of contents","text":" - Flavours
- Getting started
- Cluster
- Network
- Dependencies
- Generate
- Install
- Build
- Run
- Test
"},{"location":"DEVELOPMENT/#flavours","title":"Flavours","text":""},{"location":"DEVELOPMENT/#devcontainer","title":"devcontainer","text":"Spin up a devcontainer with everything you need to develop. This can be used in conjunction with many tools, such as vscode, GitHub codespaces and DevPod, which will automatically detect the devcontainer.json.
The only dependency you need is docker in case that choose to run your devcontainer locally.
"},{"location":"DEVELOPMENT/#local","title":"local","text":"Run the operator locally in your machine using go run. It requires the following dependencies: - make - go - docker
This flavour uses KIND and MetalLB under the hood to provision Kubernetes clusters and assign local IPs to LoadBalancer Services. It has some limitations in Mac and Windows which will make the operator unable to connect to MariaDB via the LoadBalancer Service, leading to errors when reconciling SQL-related resources. Alternatively, use the devcontainer flavour.
"},{"location":"DEVELOPMENT/#getting-started","title":"Getting started","text":"After having decided which flavour to use and install the required dependencies, you will be able to use the Makefile targets we provide. For convenience, every development action has an associated Makefile target. You can list all of them by running make:
make\n\nUsage:\n make <target>\n\nGeneral\n help Display this help.\n\n...\n\nInstall\n install-crds Install CRDs.\n uninstall-crds Uninstall CRDs.\n install Install CRDs and dependencies for local development.\n install-samples Install sample configuration.\n serviceaccount Create long-lived ServiceAccount token for development.\n\nDev\n certs Generates development certificates.\n lint Lint.\n build Build binary.\n test Run tests.\n cover Run tests and generate coverage.\n release Test release locally.\n\nOperator\n run Run a controller from your host. \n\n...\n
"},{"location":"DEVELOPMENT/#cluster","title":"Cluster","text":"To start with, you will need a Kubernetes cluster for developing locally. You can provision a KIND cluster by using the following target:
make cluster\n
To decommission the cluster:
make cluster-delete\n
"},{"location":"DEVELOPMENT/#network","title":"Network","text":"You can configure the network connectivity so the operator is able to resolve DNS and address MariaDB as if it was running in-cluster:
make net\n
This connectivity leverages MetalLB to assign local IPs to the LoadBalancer Services for the operator to connect to MariaDB. For this to happen, these local IPs need to be within the docker CIDR, which can be queried using:
make cidr\n172.18.0.0/16\n
When deploying example manifests, take into account that LoadBalancer Services need to be within the docker CIDR to function properly, see: - examples/manifests/mariadb_v1alpha1_mariadb.yaml - examples/manifests/mariadb_v1alpha1_mariadb_replication.yaml - examples/manifests/mariadb_v1alpha1_mariadb_galera.yaml
"},{"location":"DEVELOPMENT/#dependencies","title":"Dependencies","text":"You might need the following third party dependencies to test certain features of mariadb-operator, to install them run:
make install-prometheus\nmake install-cert-manager\nmake install-minio\n
Some of this dependencies have ports mapped to the host (i.e. Grafana and Minio to expose the dashboard) so be sure to check the forwarded ports to access. This step requires running make net previously.
"},{"location":"DEVELOPMENT/#generate","title":"Generate","text":"This target generates code, CRDs and deployment manifests. Make sure to run this before pushing a commit, as it is required by the CI:
make gen\n
"},{"location":"DEVELOPMENT/#install","title":"Install","text":"Install CRDs and everything you need to run the operator locally:
make install\n
"},{"location":"DEVELOPMENT/#build","title":"Build","text":"Build the operator binary:
make build\n
Build the docker image and load it into KIND:
make docker-build\nmake docker-load\n
"},{"location":"DEVELOPMENT/#run","title":"Run","text":"make cluster\nmake install\nmake net\nmake run\n
"},{"location":"DEVELOPMENT/#unit-tests","title":"Unit tests","text":"make test\n
"},{"location":"DEVELOPMENT/#integration-tests","title":"Integration tests","text":"make cluster\nmake install\nmake install-minio\nmake net\nmake test-int\n
"},{"location":"DOCKER/","title":"Docker Images for MariaDB Operator","text":"The mariadb-operator uses a variety of docker images depending on how it\u2019s configured and what mix of open source or commercial software you\u2019d like to use. As only the latest version of MariaDB Community Server is supported, the community server version will increment frequently with only a best effort made to keep current with the latest release(s). Only MariaDB Enterprise Server offers support for older versions.
[!NOTE] Using Docker images other than the supported ones in this document is not recommended at this time.
Component Docker Registry Supported Tags CPU Pull Command MariaDB Community Server mariadb 11.4.3 (Used with Community Operator)11.4.3-ubi9 (Used with Enterprise Operator) amd64 arm64 ppc64le s390x docker pull docker-registry1.mariadb.com/library/mariadb:11.4.3docker pull docker-registry1.mariadb.com/library/mariadb:11.4.3-ubi9 MariaDB Enterprise Server docker.mariadb.comLogin required, click link for instructions 10.6.18-14 10.6.17-13 10.5.25-19 10.5.24-18 amd64 arm64 docker pull docker-registry.mariadb.com/enterprise-server:10.6.18-14 MariaDB MaxScale UBI mariadb/maxscale 23.08.6-ubi-1 24.02.2-ubi-1 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/maxscale:23.08.6-ubi-1 MariaDB MaxScale Rocky Linux mariadb/maxscale mariadb/maxscale:23.08.5 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/maxscale:23.08.5 MariaDB Prometheus Exporter mariadb/mariadb-prometheus-exporter v0.0.1 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/mariadb-prometheus-exporter-ubi:v0.0.1 MariaDB MaxScale prometheus exporter mariadb/maxscale-prometheus-exporter-ubi v0.0.1 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/maxscale-prometheus-exporter-ubi:v0.0.1 Community Operator ghcr.io/mariadb-operator/mariadb-operator v0.0.30 amd64 arm64 docker pull docker-registry3.mariadb.com/mariadb-operator/mariadb-operator:v0.0.30 Enterprise Operator mariadb/mariadb-operator-enterprise v0.0.30 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/mariadb-operator-enterprise:v0.0.30"},{"location":"GALERA/","title":"High availability via Galera","text":"The mariadb-operator provides cloud native support for provisioning and operating multi-master MariaDB clusters using Galera. This setup enables the ability to perform both read and write operations on all nodes, enhancing availability and allowing scalability across multiple nodes.
In certain circumstances, it could be the case that all the nodes of your cluster go down at the same time, something that Galera is not able to recover by itself, and it requires manual action to bring the cluster up again, as documented in the Galera documentation. Luckly enough, mariadb-operator has you covered and it encapsulates this operational expertise in the MariaDB CRD. You just need to declaratively specify spec.galera, as explained in more detail later in this guide.
To accomplish this, after the MariaDB cluster has been provisioned, mariadb-operator will regularly monitor the cluster's status to make sure it is healthy. If any issues are detected, the operator will initiate the recovery process to restore the cluster to a healthy state. During this process, the operator will set status conditions in the MariaDB and emit Events so you have a better understanding of the recovery progress and the underlying activities being performed. For example, you may want to know which Pods were out of sync to further investigate infrastructure-related issues (i.e. networking, storage...) on the nodes where these Pods were scheduled.
"},{"location":"GALERA/#table-of-contents","title":"Table of contents","text":" - Components
MariaDB configuration- Storage
- Wsrep provider
- IPv6 support
- Backup and restore
- Galera cluster recovery
- Bootstrap Galera cluster from existing PVCs
- Quickstart
- Troubleshooting
- Reference
"},{"location":"GALERA/#components","title":"Components","text":"To be able to effectively provision and recover MariaDB Galera clusters, the following components were introduced to co-operate with mariadb-operator: - init: Init container that dynamically provisions the Galera configuration file before the MariaDB container starts. Guarantees ordered deployment of Pods even if spec.podManagementPolicy = Parallel is set on the MariaDB StatefulSet, something crucial for performing the Galera recovery, as the operator needs to restart Pods independently. - agent: Sidecar agent that exposes the Galera state (grastate.dat) via HTTP and allows the operator to remotely bootstrap and recover the Galera cluster. For security reasons, it has authentication based on Kubernetes service accounts; this way only the operator is able to call the agent.
All these components are available in the ghcr.io/mariadb-operator mariadb-operator image. More preciselly, they are subcommands of the CLI shipped as binary inside the image.
"},{"location":"GALERA/#mariadb-configuration","title":"MariaDB configuration","text":"The easiest way to get a MariaDB Galera cluster up and running is setting spec.galera.enabled = true, like in this example:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n...\n replicas: 3\n\n galera:\n enabled: true\n
This relies on sensible defaults set by the operator, which may not be suitable for your Kubernetes cluster. This can be solved by overriding the defaults, as in this other example, so you have fine-grained control over the Galera configuration.
Refer to the reference section to better understand the purpose of each field.
"},{"location":"GALERA/#storage","title":"Storage","text":"By default, mariadb-operator provisions two PVCs for running Galera: - Storage PVC: Used to back the MariaDB data directory, mounted at /var/lib/mysql. - Config PVC: Where the Galera config files are located, mounted at /etc/mysql/conf.d.
However, you are also able to use just one PVC for keeping both the data and the config files:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n enabled: true\n config:\n reuseStorageVolume: true\n
"},{"location":"GALERA/#wsrep-provider","title":"Wsrep provider","text":"You are able to pass extra options to the Galera wsrep provider by using the galera.providerOptions field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n providerOptions:\n gcs.fc_limit: '64'\n
It is important to note that, the ist.recv_addr cannot be set by the user, as it is automatically configured to the Pod IP by the operator, something that an user won't be able to know beforehand.
A list of the available options can be found in the MariaDB documentation.
"},{"location":"GALERA/#ipv6-support","title":"IPv6 support","text":"If you have a Kubernetes cluster running with IPv6, the operator will automatically detect the IPv6 addresses of your Pods and it will configure several wsrep provider options to ensure that the Galera protocol runs smoothly with IPv6.
"},{"location":"GALERA/#backup-and-restore","title":"Backup and restore","text":"Please refer to the backup documentation to understand how to backup and restore Galera clusters. Specially, make sure you understand the Galera backup limitations.
"},{"location":"GALERA/#galera-cluster-recovery","title":"Galera cluster recovery","text":"mariadb-operator is able to monitor the Galera cluster and act accordinly to recover it if needed. This feature is enabled by default, but you may tune it as you need:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n enabled: true\n recovery:\n enabled: true\n minClusterSize: 1\n clusterMonitorInterval: 10s\n clusterHealthyTimeout: 30s\n clusterBootstrapTimeout: 10m\n podRecoveryTimeout: 5m\n podSyncTimeout: 5m\n
The minClusterSize field indicates the minimum cluster size (either absolut number of replicas or percentage) for the operator to consider the cluster healthy. If the cluster is unhealthy for more than the period defined in clusterHealthyTimeout (30s by default), a cluster recovery process is initiated by the operator. The process is explained in the Galera documentation and consists of the following steps:
- Recover the sequence number from the
grastate.dat on each node. - Trigger a recovery
Job to obtain the sequence numbers in case that the previous step didn't manage to. - Mark the node with highest sequence (bootstrap node) as safe to bootstrap.
- Bootstrap a new cluster in the bootstrap node.
- Restart and wait until the bootstrap node becomes ready.
- Restart the rest of the nodes one by one so they can join the new cluster.
The operator monitors the Galera cluster health periodically and performs the cluster recovery described above if needed. You are able to tune the monitoring interval via the clusterMonitorInterval field.
Refer to the reference section to better understand the purpose of each field.
"},{"location":"GALERA/#galera-recovery-job","title":"Galera recovery Job","text":"During the recovery process, a Job is triggered for each MariaDB Pod to obtain the sequence numbers. It's crucial for this Job to succeed; otherwise, the recovery process will fail. As a user, you are responsible for adjusting this Job to allocate sufficient resources and provide the necessary metadata to ensure its successful completion.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n enabled: true\n recovery:\n job:\n metadata:\n labels:\n sidecar.istio.io/inject: \"false\"\n resources:\n requests:\n cpu: 100m\n memory: 128Mi\n limits:\n memory: 256Mi\n
For example, if you're using a service mesh like Istio, it's important to add the sidecar.istio.io/inject=false label. Without this label, the Job will not complete, which would prevent the recovery process from finishing successfully.
"},{"location":"GALERA/#force-cluster-bootstrap","title":"Force cluster bootstrap","text":"[!CAUTION] Use this option only in exceptional circumstances. Not selecting the Pod with the highest sequence number may result in data loss.
[!WARNING] Ensure you unset forceClusterBootstrapInPod after completing the bootstrap to allow the operator to choose the appropriate Pod to bootstrap from in an event of cluster recovery.
You have the ability to manually select which Pod is used to bootstrap a new cluster during the recovery process by setting forceClusterBootstrapInPod:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n enabled: true\n recovery:\n enabled: true\n forceClusterBootstrapInPod: \"mariadb-galera-0\"\n
This should only be used in exceptional circumstances: - You are absolutely certain that the chosen Pod has the highest sequence number. - The operator has not yet selected a Pod to bootstrap from.
You can verify this with the following command:
kubectl get mariadb mariadb-galera -o jsonpath=\"{.status.galeraRecovery}\" | jq\n{\n \"recovered\": {\n \"mariadb-galera-0\": {\n \"seqno\": 350454,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\"\n },\n \"mariadb-galera-1\": {\n \"seqno\": 350450,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\"\n }\n },\n \"state\": {\n \"mariadb-galera-0\": {\n \"safeToBootstrap\": false,\n \"seqno\": -1,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\",\n \"version\": \"2.1\"\n },\n \"mariadb-galera-1\": {\n \"safeToBootstrap\": false,\n \"seqno\": -1,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\",\n \"version\": \"2.1\"\n },\n \"mariadb-galera-2\": {\n \"safeToBootstrap\": false,\n \"seqno\": -1,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\",\n \"version\": \"2.1\"\n }\n }\n}\n
In this case, assuming that mariadb-galera-2 sequence is lower than 350454, it should be safe to bootstrap from mariadb-galera-0.
Finally, after your cluster has been bootstrapped, remember to unset forceClusterBootstrapInPod to allow the operator to select the appropriate node for bootstrapping in the event of a cluster recovery.
"},{"location":"GALERA/#bootstrap-galera-cluster-from-existing-pvcs","title":"Bootstrap Galera cluster from existing PVCs","text":"mariadb-operator will never delete your MariaDB PVCs! Whenever you delete a MariaDB resource, the PVCs will remain intact so you could reuse them to re-provision a new cluster.
That said, Galera is unable to form a cluster from pre-existing state, it requires a cluster recovery process to identify which Pod has the highest sequence number to bootstrap a new cluster. That's exactly what the operator does: whenever a new MariaDB Galera cluster is created and previously created PVCs exist, a cluster recovery process is automatically triggered.
"},{"location":"GALERA/#quickstart","title":"Quickstart","text":"First of all, install the following configuration manifests that will be referenced by the CRDs further:
kubectl apply -f examples/manifests/config\n
Next, you can proceed with the installation of a MariaDB instance with Galera support:
kubectl apply -f examples/manifests/mariadb_galera.yaml\n
kubectl get mariadbs\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera True Running mariadb-galera-0 48m\n\nkubectl get events --field-selector involvedObject.name=mariadb-galera --sort-by='.lastTimestamp'\nLAST SEEN TYPE REASON OBJECT MESSAGE\n...\n45m Normal GaleraClusterHealthy mariadb/mariadb-galera Galera cluster is healthy\n\nkubectl get mariadb mariadb-galera -o jsonpath=\"{.status.conditions[?(@.type=='GaleraReady')]}\"\n{\"lastTransitionTime\":\"2023-07-13T18:22:31Z\",\"message\":\"Galera ready\",\"reason\":\"GaleraReady\",\"status\":\"True\",\"type\":\"GaleraReady\"}\n\nkubectl get mariadb mariadb-galera -o jsonpath=\"{.status.conditions[?(@.type=='GaleraConfigured')]}\"\n{\"lastTransitionTime\":\"2023-07-13T18:22:31Z\",\"message\":\"Galera configured\",\"reason\":\"GaleraConfigured\",\"status\":\"True\",\"type\":\"GaleraConfigured\"}\n\nkubectl get statefulsets -o wide\nNAME READY AGE CONTAINERS IMAGES\nmariadb-galera 3/3 58m mariadb,agent mariadb:11.0.3,ghcr.io/mariadb-operator/mariadb-operator:v0.0.26\n\nkubectl get pods -o wide\nNAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES\nmariadb-galera-0 2/2 Running 0 58m 10.244.2.4 mdb-worker3 <none> <none>\nmariadb-galera-1 2/2 Running 0 58m 10.244.1.9 mdb-worker2 <none> <none>\nmariadb-galera-2 2/2 Running 0 58m 10.244.5.4 mdb-worker4 <none> <none>\n
Up and running. Let's now proceed with simulating a Galera cluster failure by deleting all the Pods at the same time:
kubectl delete pods -l app.kubernetes.io/instance=mariadb-galera\npod \"mariadb-galera-0\" deleted\npod \"mariadb-galera-1\" deleted\npod \"mariadb-galera-2\" deleted\n
After some time, we will see the MariaDB entering a non Ready state:
kubectl get mariadb mariadb-galera\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera False Galera not ready mariadb-galera-0 67m\n\nkubectl get events --field-selector involvedObject.name=mariadb-galera --sort-by='.lastTimestamp'\nLAST SEEN TYPE REASON OBJECT MESSAGE\n...\n48s Warning GaleraClusterNotHealthy mariadb/mariadb-galera Galera cluster is not healthy\n\nkubectl get mariadb mariadb-galera -o jsonpath=\"{.status.conditions[?(@.type=='GaleraReady')]}\"\n{\"lastTransitionTime\":\"2023-07-13T19:25:17Z\",\"message\":\"Galera not ready\",\"reason\":\"GaleraNotReady\",\"status\":\"False\",\"type\":\"GaleraReady\"}\n
Eventually, the operator will kick in and recover the Galera cluster:
kubectl get events --field-selector involvedObject.name=mariadb-galera --sort-by='.lastTimestamp'\nLAST SEEN TYPE REASON OBJECT MESSAGE\n...\n16m Warning GaleraClusterNotHealthy mariadb/mariadb-galera Galera cluster is not healthy\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-2'\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-1'\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-0'\n16m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-1'\n16m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-2'\n17m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-0'\n17m Normal GaleraClusterBootstrap mariadb/mariadb-galera Bootstrapping Galera cluster in Pod 'mariadb-galera-2'\n20m Normal GaleraClusterHealthy mariadb/mariadb-galera Galera cluster is healthy\n\nkubectl get mariadb mariadb-galera -o jsonpath=\"{.status.galeraRecovery}\"\n{\"bootstrap\":{\"pod\":\"mariadb-galera-2\",\"time\":\"2023-07-13T19:25:28Z\"},\"recovered\":{\"mariadb-galera-0\":{\"seqno\":3,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\"},\"mariadb-galera-1\":{\"seqno\":3,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\"},\"mariadb-galera-2\":{\"seqno\":3,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\"}},\"state\":{\"mariadb-galera-0\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\",\"version\":\"2.1\"},\"mariadb-galera-1\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\",\"version\":\"2.1\"},\"mariadb-galera-2\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\",\"version\":\"2.1\"}}}\n
Finally, the MariaDB resource will become Ready and your Galera cluster will be operational again:
kubectl get mariadb mariadb-galera -o jsonpath=\"{.status.conditions[?(@.type=='GaleraReady')]}\"\n{\"lastTransitionTime\":\"2023-07-13T19:27:51Z\",\"message\":\"Galera ready\",\"reason\":\"GaleraReady\",\"status\":\"True\",\"type\":\"GaleraReady\"}\n\nkubectl get mariadb mariadb-galera\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera True Running mariadb-galera-0 82m\n
"},{"location":"GALERA/#troubleshooting","title":"Troubleshooting","text":"The aim of this section is showing you how to diagnose your Galera cluster when something goes wrong. In this situations, observability is a key factor to understand the problem, so we recommend following these steps before jumping into debugging the problem.
- Inspect
MariaDB status conditions.
kubectl get mariadb mariadb-galera -o jsonpath=\"{.status}\"\n{\"conditions\":[{\"lastTransitionTime\":\"2023-08-05T14:58:57Z\",\"message\":\"Galera not ready\",\"reason\":\"GaleraNotReady\",\"status\":\"False\",\"type\":\"Ready\"},{\"lastTransitionTime\":\"2023-08-05T14:58:57Z\",\"message\":\"Galera not ready\",\"reason\":\"GaleraNotReady\",\"status\":\"False\",\"type\":\"GaleraReady\"},{\"lastTransitionTime\":\"2023-08-03T19:21:16Z\",\"message\":\"Galera configured\",\"reason\":\"GaleraConfigured\",\"status\":\"True\",\"type\":\"GaleraConfigured\"}],\"currentPrimary\":\"All\",\"galeraRecovery\":{\"bootstrap\":{\"pod\":\"mariadb-galera-1\",\"time\":\"2023-08-05T14:59:18Z\"},\"recovered\":{\"mariadb-galera-0\":{\"seqno\":17,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\"},\"mariadb-galera-1\":{\"seqno\":17,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\"},\"mariadb-galera-2\":{\"seqno\":16,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\"}},\"state\":{\"mariadb-galera-0\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\",\"version\":\"2.1\"},\"mariadb-galera-1\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\",\"version\":\"2.1\"},\"mariadb-galera-2\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\",\"version\":\"2.1\"}}}}\n
- Make sure network connectivity is fine by checking that you have an
Endpoint per Pod in your Galera cluster.
kubectl get endpoints mariadb-galera-internal -o yaml\napiVersion: v1\nkind: Endpoints\nmetadata:\n name: mariadb-internal\nsubsets:\n- addresses:\n - hostname: mariadb-1\n ip: 10.255.140.181\n nodeName: k8s-worker-1\n targetRef:\n kind: Pod\n name: mariadb-1\n namespace: mariadb\n - hostname: mariadb-2\n ip: 10.255.20.156\n nodeName: k8s-worker-2\n targetRef:\n kind: Pod\n name: mariadb-2\n namespace: mariadb\n - hostname: mariadb-0\n ip: 10.255.214.164\n nodeName: k8s-worker-0\n targetRef:\n kind: Pod\n name: mariadb-0\n namespace: mariadb\n ports:\n - name: sst\n port: 4568\n protocol: TCP\n - name: ist\n port: 4567\n protocol: TCP\n - name: mariadb\n port: 3306\n protocol: TCP\n - name: agent\n port: 5555\n protocol: TCP\n - name: cluster\n port: 4444\n protocol: TCP\n\n
- Check the events associated with the
MariaDB object, as they provide significant insights for diagnosis, particularly within the context of cluster recovery.
kubectl get events --field-selector involvedObject.name=mariadb-galera --sort-by='.lastTimestamp'\nLAST SEEN TYPE REASON OBJECT MESSAGE\n...\n16m Warning GaleraClusterNotHealthy mariadb/mariadb-galera Galera cluster is not healthy\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-2'\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-1'\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-0'\n16m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-1'\n16m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-2'\n17m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-0'\n17m Normal GaleraClusterBootstrap mariadb/mariadb-galera Bootstrapping Galera cluster in Pod 'mariadb-galera-2'\n20m Normal GaleraClusterHealthy mariadb/mariadb-galera Galera cluster is healthy\n
- Enable
debug logs in mariadb-operator.
helm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --set logLevel=debug\nkubectl logs mariadb-operator-546c78f4f5-gq44k\n{\"level\":\"info\",\"ts\":1691090524.4911606,\"logger\":\"galera.health\",\"msg\":\"Checking Galera cluster health\",\"controller\":\"statefulset\",\"controllerGroup\":\"apps\",\"controllerKind\":\"StatefulSet\",\"statefulSet\":{\"name\":\"mariadb-galera\",\"namespace\":\"default\"},\"namespace\":\"default\",\"name\":\"mariadb-galera\",\"reconcileID\":\"098620db-4486-45cc-966a-9f3fec0d165e\"}\n{\"level\":\"debug\",\"ts\":1691090524.4911761,\"logger\":\"galera.health\",\"msg\":\"StatefulSet ready replicas\",\"controller\":\"statefulset\",\"controllerGroup\":\"apps\",\"controllerKind\":\"StatefulSet\",\"statefulSet\":{\"name\":\"mariadb-galera\",\"namespace\":\"default\"},\"namespace\":\"default\",\"name\":\"mariadb-galera\",\"reconcileID\":\"098620db-4486-45cc-966a-9f3fec0d165e\",\"replicas\":1}\n
- Get the logs of all the
MariaDB Pod containers, not only of the main mariadb container but also the agent and init ones.
kubectl logs mariadb-galera-0 -c init\n{\"level\":\"info\",\"ts\":1691090778.5239124,\"msg\":\"Starting init\"}\n{\"level\":\"info\",\"ts\":1691090778.5305626,\"msg\":\"Configuring Galera\"}\n{\"level\":\"info\",\"ts\":1691090778.5307593,\"msg\":\"Already initialized. Init done\"}\n\nkubectl logs mariadb-galera-0 -c agent\n{\"level\":\"info\",\"ts\":1691090779.3193653,\"logger\":\"server\",\"msg\":\"server listening\",\"addr\":\":5555\"}\n2023/08/03 19:26:28 \"POST http://mariadb-galera-0.mariadb-galera-internal.default.svc.cluster.local:5555/api/recovery HTTP/1.1\" from 10.244.4.2:39162 - 200 58B in 4.112086ms\n2023/08/03 19:26:28 \"DELETE http://mariadb-galera-0.mariadb-galera-internal.default.svc.cluster.local:5555/api/recovery HTTP/1.1\" from 10.244.4.2:39162 - 200 0B in 883.544\u00b5s\n\nkubectl logs mariadb-galera-0 -c mariadb\n2023-08-03 19:27:10 0 [Note] WSREP: Member 2.0 (mariadb-galera-0) synced with group.\n2023-08-03 19:27:10 0 [Note] WSREP: Processing event queue:...100.0% (1/1 events) complete.\n2023-08-03 19:27:10 0 [Note] WSREP: Shifting JOINED -> SYNCED (TO: 6)\n2023-08-03 19:27:10 2 [Note] WSREP: Server mariadb-galera-0 synced with group\n2023-08-03 19:27:10 2 [Note] WSREP: Server status change joined -> synced\n2023-08-03 19:27:10 2 [Note] WSREP: Synchronized with group, ready for connections\n
Once you are done with these steps, you will have the context required to jump ahead to the Common errors section to see if any of them matches your case. If they don't, feel free to open an issue or even a PR updating this document if you managed to resolve it.
"},{"location":"GALERA/#common-errors","title":"Common errors","text":""},{"location":"GALERA/#galera-cluster-recovery-not-progressing","title":"Galera cluster recovery not progressing","text":"If your MariaDB Galera cluster has been in GaleraNotReady state for a long time, the recovery process might not be progressing. You can diagnose this by checking: - The operator logs. - Galera recovery status:
kubectl get mariadb mariadb-galera -o jsonpath=\"{.status.galeraRecovery}\" | jq\n
- If you have
Pods named <mariadb-name>-<ordinal>-recovery-<suffix> running for a long time, check its logs to understand if something is wrong.
One of the reasons could be misconfigured Galera recovery Jobs, please make sure you read this section. If after checking all the points above, there are still no clear symptoms of what could be wrong, continue reading.
First af all, you could attempt to forcefully bootstrap a new cluster as it is described in this section. Please, refrain from doing so if the conditions described in the docs are not met.
Alternatively, if you can afford some downtime and your PVCs are in healthy state, you may follow this procedure: - Delete your existing MariaDB, this will leave your PVCs intact. - Create your MariaDB again, this will trigger a Galera recovery process as described in this section.
As a last resource, you can always delete the PVCs and bootstrap a new MariaDB from a backup as documented here.
"},{"location":"GALERA/#permission-denied-writing-galera-configuration","title":"Permission denied writing Galera configuration","text":"This error occurs when the user that runs the container does not have enough privileges to write in /etc/mysql/mariadb.conf.d:
Error writing Galera config: open /etc/mysql/mariadb.conf.d/0-galera.cnf: permission denied\n
To mitigate this, by default, the operator sets the following securityContext in the MariaDB's StatefulSet :
apiVersion: apps/v1\nkind: StatefulSet\nmetadata:\n name: mariadb-galera\nspec:\n securityContext:\n fsGroup: 999\n runAsGroup: 999\n runAsNonRoot: true\n runAsUser: 999\n
This enables the CSIDriver and the kubelet to recursively set the ownership ofr the /etc/mysql/mariadb.conf.d folder to the group 999, which is the one expected by MariaDB. It is important to note that not all the CSIDrivers implementations support this feature, see the CSIDriver documentation for further information.
"},{"location":"GALERA/#unauthorized-error-disabling-bootstrap","title":"Unauthorized error disabling bootstrap","text":"Error reconciling Galera: error disabling bootstrap in Pod 0: unauthorized\n
This situation occurs when the mariadb-operator credentials passed to the agent as authentication are either invalid or the agent is unable to verify them. To confirm this, ensure that both the mariadb-operator and the MariaDB ServiceAccounts are able to create TokenReview objects:
kubectl auth can-i --list --as=system:serviceaccount:default:mariadb-operator | grep tokenreview\ntokenreviews.authentication.k8s.io [] [] [create]\n\nkubectl auth can-i --list --as=system:serviceaccount:default:mariadb-galera | grep tokenreview\ntokenreviews.authentication.k8s.io [] [] [create]\n
If that's not the case, check that the following ClusterRole and ClusterRoleBindings are available in your cluster:
kubectl get clusterrole system:auth-delegator\nNAME CREATED AT\nsystem:auth-delegator 2023-08-03T19:12:37Z\n\nkubectl get clusterrolebinding | grep mariadb | grep auth-delegator\nmariadb-galera:auth-delegator ClusterRole/system:auth-delegator 108m\nmariadb-operator:auth-delegator ClusterRole/system:auth-delegator 112m\n
mariadb-operator:auth-delegator is the ClusterRoleBinding bound to the mariadb-operator ServiceAccount which is created by the helm chart, so you can re-install the helm release in order to recreate it:
helm upgrade --install mariadb-operator mariadb-operator/mariadb-operator\n
mariadb-galera:auth-delegator is the ClusterRoleBinding bound to the mariadb-galera ServiceAccount which is created on the flight by the operator as part of the reconciliation logic. You may check the mariadb-operator logs to see if there are any issues reconciling it.
Bear in mind that ClusterRoleBindings are cluster-wide resources that are not garbage collected when the MariaDB owner object is deleted, which means that creating and deleting MariaDBs could leave leftovers in your cluster. These leftovers can lead to RBAC misconfigurations, as the ClusterRoleBinding might not be pointing to the right ServiceAccount. To overcome this, you can override the ClusterRoleBinding name setting the spec.galera.agent.kubernetesAuth.authDelegatorRoleName field.
"},{"location":"GALERA/#timeout-waiting-for-pod-to-be-synced","title":"Timeout waiting for Pod to be Synced","text":"Timeout waiting for Pod 'mariadb-galera-2' to be Synced\n
This error appears in the mariadb-operator logs when a Pod is in non synced state for a duration exceeding the spec.galera.recovery.podRecoveryTimeout. Just after, the operator will restart the Pod.
Increase this timeout if you consider that your Pod may take longer to recover.
"},{"location":"GALERA/#galera-cluster-bootstrap-timed-out","title":"Galera cluster bootstrap timed out","text":"Galera cluster bootstrap timed out. Resetting recovery status\n
This is error is returned by the mariadb-operator after exceeding the spec.galera.recovery.clusterBootstrapTimeout when recovering the cluster. At this point, the operator will reset the recovered sequence numbers and start again from a clean state.
Increase this timeout if you consider that your Galera cluster may take longer to recover.
"},{"location":"GALERA/#github-issues","title":"GitHub Issues","text":"Here it is a list of Galera-related issues reported by mariadb-operator users which might shed some light in your investigation: - https://github.com/mariadb-operator/mariadb-operator/issues?q=label%3Agalera+
"},{"location":"GALERA/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"HA/","title":"High availability","text":"Our recommended HA setup for production is: - Galera with at least 3 nodes. Always an odd number of nodes. - Load balance requests using MaxScale as database proxy. - Use dedicated nodes to avoid noisy neighbours. - Define pod disruption budgets.
Refer to the following sections for further detail.
"},{"location":"HA/#table-of-contents","title":"Table of contents","text":" - Topologies
- Kubernetes Services
- MaxScale
- Pod Anti-Affinity
- Dedicated Nodes
- Pod Disruption Budgets
- Reference
"},{"location":"HA/#topologies","title":"Topologies","text":" - Multi master HA via Galera: All nodes support reads and writes. We have a designated primary where the writes are performed.
- Single master HA via SemiSync Replication: The primary node allows both reads and writes, while secondary nodes only allow reads.
"},{"location":"HA/#kubernetes-services","title":"Kubernetes Services","text":"In order to address nodes, mariadb-operator provides you with the following Kubernetes Services: - <mariadb-name>: To be used for read requests. It will point to all nodes. - <mariadb-name>-primary: To be used for write requests. It will point to a single node, the primary. - <mariadb-name>-secondary: To be used for read requests. It will point to all nodes, except the primary.
Whenever the primary changes, either by the user or by the operator, both the <mariadb-name>-primary and <mariadb-name>-secondary Services will be automatically updated by the operator to address the right nodes.
The primary may be manually changed by the user at any point by updating the spec.[replication|galera].primary.podIndex field. Alternatively, automatic primary failover can be enabled by setting spec.[replication|galera].primary.automaticFailover, which will make the operator to switch primary whenever the primary Pod goes down.
"},{"location":"HA/#maxscale","title":"MaxScale","text":"While Kubernetes Services can be utilized to dynamically address primary and secondary instances, the most robust high availability configuration we recommend relies on MaxScale. Please refer to MaxScale docs for further details.
"},{"location":"HA/#pod-anti-affinity","title":"Pod Anti-Affinity","text":"[!WARNING] Bear in mind that, when enabling this, you need to have at least as many Nodes available as the replicas specified. Otherwise your Pods will be unscheduled and the cluster won't bootstrap.
To achieve real high availability, we need to run each MariaDB Pod in different Kubernetes Nodes. This practice, known as anti-affinity, helps reducing the blast radius of Nodes being unavailable.
By default, anti-affinity is disabled, which means that multiple Pods may be scheduled in the same Node, something not desired in HA scenarios.
You can selectively enable anti-affinity in all the different Pods managed by the MariaDB resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n bootstrapFrom:\n restoreJob:\n affinity:\n antiAffinityEnabled: true\n ...\n galera:\n initJob:\n affinity:\n antiAffinityEnabled: true\n ...\n metrics:\n exporter:\n affinity:\n antiAffinityEnabled: true\n ...\n affinity:\n antiAffinityEnabled: true\n
Anti-affinity may also be enabled in the the resources that have a reference to MariaDB, resulting in their Pods being scheduled in Nodes where MariaDB is not running. For instance, the Backup and Restore processes can run in different Nodes:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb-galera\n ...\n affinity:\n antiAffinityEnabled: true\n
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb-galera\n ...\n affinity:\n antiAffinityEnabled: true\n
In the case of MaxScale, the Pods will also be placed in Nodes isolated in terms of compute, ensuring isolation not only among themselves but also from the MariaDB Pods. For example, if you run a MariaDB and MaxScale with 3 replicas each, you will need 6 Nodes in total:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n mariaDbRef:\n name: mariadb-galera\n ...\n metrics:\n exporter:\n affinity:\n antiAffinityEnabled: true\n ...\n affinity:\n antiAffinityEnabled: true\n
Default anti-affinity rules generated by the operator might not satisfy your needs, but you can always define your own rules. For example, if you want the MaxScale Pods to be in different Nodes, but you want them to share Nodes with MariaDB:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n mariaDbRef:\n name: mariadb-galera\n ...\n affinity:\n podAntiAffinity:\n requiredDuringSchedulingIgnoredDuringExecution:\n - labelSelector:\n matchExpressions:\n - key: app.kubernetes.io/instance\n operator: In\n values:\n - maxscale-galera\n # 'mariadb-galera' instance omitted (default anti-affinity rule)\n topologyKey: kubernetes.io/hostname\n
"},{"location":"HA/#dedicated-nodes","title":"Dedicated Nodes","text":"If you want to avoid noisy neighbours running in the same Kubernetes Nodes as your MariaDB, you may consider using dedicated Nodes. For achieving this, you will need: - Taint your Nodes and add the counterpart toleration in your Pods.
[!IMPORTANT] Tainting your Nodes is not covered by this operator, it is something you need to do by yourself beforehand. You may take a look at the Kubernetes documentation to understand how to achieve this. - Select the Nodes to schedule in via a nodeSelector in your Pods. [!NOTE] Although you can use the default Node labels, you may consider adding more significative labels to your Nodes, as you will have to refer to them in your Pod nodeSelector. Refer to the Kubernetes documentation.
- Add
podAntiAffinity to your Pods as described in the Pod Anti-Affinity section.
Once you have completed the previous steps, you can configure your MariaDB as follows:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n tolerations:\n - key: \"k8s.mariadb.com/ha\"\n operator: \"Exists\"\n effect: \"NoSchedule\"\n nodeSelector:\n \"k8s.mariadb.com/node\": \"ha\" \n affinity:\n antiAffinityEnabled: true\n
"},{"location":"HA/#pod-disruption-budgets","title":"Pod Disruption Budgets","text":"[!IMPORTANT] Take a look at the Kubernetes documentation if you are unfamiliar to PodDisruptionBudgets
By defining a PodDisruptionBudget, you are telling Kubernetes how many Pods your database tolerates to be down. This quite important for planned maintenance operations such as Node upgrades.
mariadb-operator creates a default PodDisruptionBudget if you are running in HA, but you are able to define your own by setting:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n podDisruptionBudget:\n maxUnavailable: 33%\n
"},{"location":"HA/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"MAXSCALE/","title":"MaxScale","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.25
[!IMPORTANT] MaxScale 23.08 is licensed under Business Source License. Make sure you understand the implications before using it!
MaxScale is a sophisticated database proxy, router, and load balancer designed specifically for and by MariaDB. It provides a range of features that ensure optimal high availability: - Query-based routing: Transparently route write queries to the primary nodes and read queries to the replica nodes. - Connection-based routing: Load balance connections between multiple servers. - Automatic primary failover based on MariaDB internals. - Replay pending transactions when a server goes down. - Support for Galera and Replication.
To better understand what MaxScale is capable of you may check the product page and the documentation.
"},{"location":"MAXSCALE/#table-of-contents","title":"Table of contents","text":" - MaxScale resources
MaxScale CRMariaDB CRMaxScale embedded in MariaDB- Defaults
- Server configuration
- Server maintenance
- Configuration
- Authentication
- Kubernetes
Services - Connection
- High availability
- Suspend resources
- MaxScale GUI
- MaxScale API
- Troubleshooting
- Reference
"},{"location":"MAXSCALE/#maxscale-resources","title":"MaxScale resources","text":"Prior to configuring MaxScale within Kubernetes, it's essential to have a basic understanding of the resources managed through its API.
"},{"location":"MAXSCALE/#servers","title":"Servers","text":"A server defines the backend database servers that MaxScale forwards traffic to. For more detailed information, please consult the server reference.
"},{"location":"MAXSCALE/#monitors","title":"Monitors","text":"A monitor is an agent that queries the state of the servers and makes it available to the services in order to route traffic based on it. For more detailed information, please consult the monitor reference.
Depending on which highly available configuration your servers have, you will need to choose betweeen the following modules: - Galera Monitor: Detects whether servers are part of the cluster, ensuring synchronization among them, and assigning primary and replica roles as needed. - MariaDB Monitor: Probes the state of the cluster, assigns roles to the servers, and executes failover, switchover, and rejoin operations as necessary.
"},{"location":"MAXSCALE/#services","title":"Services","text":"A service defines how the traffic is routed to the servers based on a routing algorithm that takes into account the state of the servers and its role. For more detailed information, please consult the service reference.
Depending on your requirements to route traffic, you may choose between the following routers: - Readwritesplit: Route write queries to the primary server and read queries to the replica servers. - Readconnroute: Load balance connections between multiple servers.
"},{"location":"MAXSCALE/#listeners","title":"Listeners","text":"A listener specifies a port where MaxScale listens for incoming connections. It is associated with a service that handles the requests received on that port. For more detailed information, please consult the listener reference.
"},{"location":"MAXSCALE/#maxscale-cr","title":"MaxScale CR","text":"The minimal spec you need to provision a MaxScale instance is just a reference to a MariaDB resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n mariaDbRef:\n name: mariadb-galera\n
This will provision a new StatefulSet for running MaxScale and configure the servers specified by the MariaDB resource. Refer to the Server configuration section if you want to manually configure the MariaDB servers.
The rest of the configuration uses reasonable defaults set automatically by the operator. If you need a more fine grained configuration, you can provide this values yourself:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n mariaDbRef:\n name: mariadb-galera\n\n services:\n - name: rw-router\n router: readwritesplit\n params:\n transaction_replay: \"true\"\n transaction_replay_attempts: \"10\"\n transaction_replay_timeout: \"5s\"\n max_slave_connections: \"255\"\n max_replication_lag: \"3s\"\n master_accept_reads: \"true\"\n listener:\n port: 3306\n protocol: MariaDBProtocol\n params:\n connection_metadata: \"tx_isolation=auto\"\n - name: rconn-master-router\n router: readconnroute\n params:\n router_options: \"master\"\n max_replication_lag: \"3s\"\n master_accept_reads: \"true\"\n listener:\n port: 3307\n - name: rconn-slave-router\n router: readconnroute\n params:\n router_options: \"slave\"\n max_replication_lag: \"3s\"\n listener:\n port: 3308\n\n monitor:\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n disable_master_failback: \"false\"\n available_when_donor: \"false\"\n disable_master_role_setting: \"false\"\n\n kubernetesService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.224\n
As you can see, the MaxScale resources we previously mentioned have a counterpart resource in the MaxScale CR.
The previous example configured a MaxScale for a Galera cluster, but you may also configure MaxScale with a MariaDB that uses replication. It is important to note that the monitor module is automatically inferred by the operator based on the MariaDB reference you provided, however, its parameters are specific to each monitor module:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-repl\nspec:\n...\n mariaDbRef:\n name: mariadb-repl\n\n services:\n - name: rw-router\n router: readwritesplit\n params:\n transaction_replay: \"true\"\n transaction_replay_attempts: \"10\"\n transaction_replay_timeout: \"5s\"\n max_slave_connections: \"255\"\n max_replication_lag: \"3s\"\n master_accept_reads: \"true\"\n listener:\n port: 3306\n protocol: MariaDBProtocol\n params:\n connection_metadata: \"tx_isolation=auto\"\n - name: rconn-master-router\n router: readconnroute\n params:\n router_options: \"master\"\n max_replication_lag: \"3s\"\n master_accept_reads: \"true\"\n listener:\n port: 3307\n - name: rconn-slave-router\n router: readconnroute\n params:\n router_options: \"slave\"\n max_replication_lag: \"3s\"\n listener:\n port: 3308\n\n monitor:\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n auto_failover: \"true\"\n auto_rejoin: \"true\"\n switchover_on_low_disk_space: \"true\"\n\n kubernetesService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.214\n
You also need to set a reference in the MariaDB resource to make it MaxScale-aware. This is explained in the MariaDB CR section.
Refer to the Reference section for further detail.
"},{"location":"MAXSCALE/#mariadb-cr","title":"MariaDB CR","text":"You can set a spec.maxScaleRef in your MariaDB resource to make it MaxScale-aware. By doing so, the primary server reported by MaxScale will be used in MariaDB and the high availability tasks such the primary failover will be delegated to MaxScale:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n...\n maxScaleRef:\n name: maxscale-galera\n\n galera:\n enabled: true\n
Refer to the Reference section for further detail.
"},{"location":"MAXSCALE/#maxscale-embedded-in-mariadb","title":"MaxScale embedded in MariaDB","text":"To streamline the setup outlined in the MaxScale CR and MariaDB CR sections, you can provision a MaxScale to be used with MariaDB in just one resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n...\n maxScale:\n enabled: true\n\n kubernetesService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.229\n\n galera:\n enabled: true\n
This will automatically set the references between MariaDB and MaxScale and default the rest of the fields.
It is important to note that, this is intended for simple use cases where no further modifications are done on the spec.maxscale field. If you need a more fine grained configuration and perform further updates to the MaxScale resource, please use a dedicated MaxScale as described in the MaxScale CR section.
Refer to the Reference section for further detail.
"},{"location":"MAXSCALE/#defaults","title":"Defaults","text":"mariadb-operator aims to provide highly configurable CRs, but at the same maximize its usability by providing reasonable defaults. In the case of MaxScale, the following defaulting logic is applied: - spec.servers are inferred from spec.mariaDbRef. - spec.monitor.module is inferred from the spec.mariaDbRef. - spec.monitor.cooperativeMonitoring is set if high availability is enabled. - If spec.services is not provided, the following are configured by default: - readwritesplit service on port 3306. - readconnroute service pointing to the primary node on port 3307. - readconnroute service pointing to the replica nodes on port 3308.
"},{"location":"MAXSCALE/#server-configuration","title":"Server configuration","text":"As an alternative to provide a reference to a MariaDB via spec.mariaDbRef, you can also specify the servers manually:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n servers:\n - name: mariadb-0\n address: mariadb-galera-0.mariadb-galera-internal.default.svc.cluster.local\n - name: mariadb-1\n address: mariadb-galera-1.mariadb-galera-internal.default.svc.cluster.local\n - name: mariadb-2\n address: mariadb-galera-2.mariadb-galera-internal.default.svc.cluster.local\n
As you could see, you can refer to in-cluser MariaDB servers by providing the DNS names of the MariaDB Pods as server addresses. In addition, you can also refer to external MariaDB instances running outside of the Kubernetes cluster where mariadb-operator was deployed:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n servers:\n - name: mariadb-0\n address: 172.18.0.140\n port: 3306\n - name: mariadb-1\n address: 172.18.0.141\n - name: mariadb-2\n address: 172.18.0.142\n\n monitor:\n name: mariadb-monitor\n module: galeramon\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n disable_master_failback: \"false\"\n available_when_donor: \"false\"\n disable_master_role_setting: \"false\"\n\n auth:\n adminUsername: mariadb-operator\n adminPasswordSecretKeyRef:\n name: maxscale\n key: password\n clientUsername: maxscale-client\n clientPasswordSecretKeyRef:\n name: maxscale\n key: password\n serverUsername: maxscale-server\n serverPasswordSecretKeyRef:\n name: maxscale\n key: password\n monitorUsername: maxscale-monitor\n monitorPasswordSecretKeyRef:\n name: maxscale\n key: password\n syncUsername: maxscale-sync\n syncPasswordSecretKeyRef:\n name: maxscale\n key: password\n
\u26a0\ufe0f Pointing to external MariaDBs has a some limitations \u26a0\ufe0f. Since the operator doesn't have a reference to a MariaDB resource (spec.mariaDbRef), it will be unable to perform the following actions: - Infer the monitor module (spec.monitor.module), so it will need to be provided by the user. - Autogenerate authentication credentials (spec.auth), so they will need to be provided by the user. See Authentication section.
"},{"location":"MAXSCALE/#server-maintenance","title":"Server maintenance","text":"You can put servers in maintenance mode by setting maintenance = true:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n servers:\n - name: mariadb-0\n address: mariadb-galera-0.mariadb-galera-internal.default.svc.cluster.local\n port: 3306\n protocol: MariaDBBackend\n maintenance: true\n
Maintenance mode prevents MaxScale from routing traffic to the server and also excludes it from being elected as the new primary during failover events.
"},{"location":"MAXSCALE/#configuration","title":"Configuration","text":"Similar to MariaDB, MaxScale allows you to provide global configuration parameters in a maxscale.conf file. You don't need to provide this config file directly, but instead you can use the spec.config.params to instruct the operator to create the maxscale.conf:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n config:\n params:\n log_info: \"true\"\n volumeClaimTemplate:\n resources:\n requests:\n storage: 100Mi\n accessModes:\n - ReadWriteOnce\n
Both this global configuration and the resources created by the operator using the MaxScale API are stored under a volume provisioned by the spec.config.volumeClaimTemplate. Refer to the troubleshooting if you are getting errors writing on this volume.
Refer to the MaxScale reference to provide global configuration.
"},{"location":"MAXSCALE/#authentication","title":"Authentication","text":"MaxScale requires authentication with differents levels of permissions for the following components/actors: - MaxScale API consumed by mariadb-operator. - Clients connecting to MaxScale. - MaxScale connecting to MariaDB servers. - MaxScale monitor connecting to MariaDB servers. - MaxScale configuration sync to connect to MariaDB servers. See high availability section.
By default, mariadb-operator autogenerates this credentials when spec.mariaDbRef is set and spec.auth.generate = true, but you are still able to provide your own:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n auth:\n generate: false\n adminUsername: mariadb-operator\n adminPasswordSecretKeyRef:\n name: maxscale\n key: password\n deleteDefaultAdmin: true\n clientUsername: maxscale-client\n clientPasswordSecretKeyRef:\n name: maxscale\n key: password\n clientMaxConnections: 90\n serverUsername: maxscale-server\n serverPasswordSecretKeyRef:\n name: maxscale\n key: password\n serverMaxConnections: 90 \n monitorUsername: maxscale-monitor\n monitorPasswordSecretKeyRef:\n name: maxscale\n key: password\n monitorMaxConnections: 90 \n syncUsername: maxscale-sync\n syncPasswordSecretKeyRef:\n name: maxscale\n key: password\n syncMaxConnections: 90\n
As you could see, you are also able to limit the number of connections for each component/actor. Bear in mind that, when running in high availability, you may need to increase this number, as more MaxScale instances implies more connections.
"},{"location":"MAXSCALE/#kubernetes-services","title":"Kubernetes Services","text":"To enable your applications to communicate with MaxScale, a Kubernetes Service is provisioned with all the ports specified in the MaxScale listeners. You have the flexibility to provide a template to customize this Service:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n kubernetesService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.224\n
This results in the reconciliation of the following Service:
apiVersion: v1\nkind: Service\nmetadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.229\n name: maxscale-galera\nspec:\n...\n ports:\n - name: admin\n port: 8989\n targetPort: 8989\n - name: rw-router-listener\n port: 3306\n targetPort: 3306\n - name: rconn-master-router-listener\n port: 3307\n targetPort: 3307\n - name: rconn-slave-router-listener\n port: 3308\n targetPort: 3308\n selector:\n app.kubernetes.io/instance: maxscale-galera\n app.kubernetes.io/name: maxscale\n type: LoadBalancer\n
There is also another Kubernetes Service to access the GUI, please refer to the MaxScale GUI section for further detail.
"},{"location":"MAXSCALE/#connection","title":"Connection","text":"You can leverage the Connection resource to automatically configure connection strings as Secret resources that your applications can mount:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Connection\nmetadata:\n name: connection-maxscale\nspec:\n maxScaleRef:\n name: maxscale-galera\n username: maxscale-galera-client\n passwordSecretKeyRef:\n name: maxscale-galera-client\n key: password\n secretName: conn-mxs\n port: 3306\n
Alternatively, you can also provide a connection template to your MaxScale resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n... \n connection:\n secretName: mxs-galera-conn\n port: 3306\n
Note that, the Connection uses the Service described in the Kubernetes Service section and you are able to specify which MaxScale service to connect to by providing the port (spec.port) of the corresponding MaxScale listener.
"},{"location":"MAXSCALE/#high-availability","title":"High availability","text":"To synchronize the configuration state across multiple replicas, MaxScale stores the configuration externally in a MariaDB table and conducts periodic polling across all replicas. By default, the table mysql.maxscale_config is used, but this can be configured by the user as well as the synchronization interval.
Another crucial aspect to consider regarding HA is that only one monitor can be running at any given time to avoid conflicts. This can be achieved via cooperative locking, which can be configured by the user. Refer to MaxScale docs for more information.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n replicas: 3\n\n monitor:\n name: mariadb-monitor\n module: galeramon\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n disable_master_failback: \"false\"\n available_when_donor: \"false\"\n disable_master_role_setting: \"false\" \n\n config:\n sync:\n database: mysql\n interval: 5s\n timeout: 10s\n
Multiple MaxScale replicas can be specified by providing the spec.replicas field. Note that, MaxScale exposes the scale subresource, so you can scale/downscale it by running the following command:
kubectl scale maxscale maxscale-galera --replicas 3\n
Or even configuring an HorizontalPodAutoscaler to do the job automatically.
"},{"location":"MAXSCALE/#suspend-resources","title":"Suspend resources","text":"In order to enable this feature, you must set the --feature-maxscale-suspend feature flag:
helm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --set extraArgs={--feature-maxscale-suspend}\n
Then you will be able to suspend any MaxScale resources, for instance, you can suspend a monitor:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n monitor:\n name: mariadb-monitor\n module: galeramon\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n disable_master_failback: \"false\"\n available_when_donor: \"false\"\n disable_master_role_setting: \"false\" \n suspend: true\n
"},{"location":"MAXSCALE/#maxscale-gui","title":"MaxScale GUI","text":"MaxScale offers a shiny user interface that provides very useful information about the MaxScale resources. You can enable it providing the following configuration:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n admin:\n port: 8989\n guiEnabled: true\n guiKubernetesService:\n type: LoadBalancer\n metadata:\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.231\n
The GUI is exposed via a dedicated Kubernetes Service in the same port as the MaxScale API. Once you access, you will need to enter the MaxScale API credentials configured by mariadb-operator in a Secret. See the Authentication section for more details.
"},{"location":"MAXSCALE/#maxscale-api","title":"MaxScale API","text":"mariadb-operator interacts with the MaxScale REST API to reconcile the specification provided by the user, considering both the MaxScale status retrieved from the API and the provided spec.
"},{"location":"MAXSCALE/#troubleshooting","title":"Troubleshooting","text":"mariadb-operator tracks both the MaxScale status in regards to Kubernetes resources as well as the status of the MaxScale API resources. This information is available on the status field of the MaxScale resource, it may be very useful for debugging purposes:
status:\n conditions:\n - lastTransitionTime: \"2024-02-08T17:29:01Z\"\n message: Running\n reason: MaxScaleReady\n status: \"True\"\n type: Ready\n configSync:\n databaseVersion: 20\n maxScaleVersion: 20\n listeners:\n - name: rconn-master-router-listener\n state: Running\n - name: rconn-slave-router-listener\n state: Running\n - name: rw-router-listener\n state: Running\n monitor:\n name: galeramon-monitor\n state: Running\n primaryServer: mariadb-galera-1\n replicas: 1\n servers:\n - name: mariadb-galera-0\n state: Slave, Synced, Running\n - name: mariadb-galera-1\n state: Master, Synced, Running\n - name: mariadb-galera-2\n state: Slave, Synced, Running\n services:\n - name: rconn-master-router\n state: Started\n - name: rconn-slave-router\n state: Started\n - name: rw-router\n state: Started\n
Kubernetes events emitted by mariadb-operator may also be very relevant for debugging. For instance, an event is emitted whenever the primary server changes:
kubectl get events --field-selector involvedObject.name=mariadb-repl-maxscale --sort-by='.lastTimestamp'\n\nLAST SEEN TYPE REASON OBJECT MESSAGE\n24s Normal MaxScalePrimaryServerChanged maxscale/mariadb-repl-maxscale MaxScale primary server changed from 'mariadb-repl-0' to 'mariadb-repl-1'\n
mariadb-operator logs can also be a good source of information for troubleshooting. You can increase its verbosity and enable MaxScale API request logs by running:
helm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --set logLevel=debug --set extraArgs={--log-maxscale}\n
"},{"location":"MAXSCALE/#common-errors","title":"Common errors","text":""},{"location":"MAXSCALE/#permission-denied-writing-varlibmaxscale","title":"Permission denied writing /var/lib/maxscale","text":"This error occurs when the user that runs the container does not have enough privileges to write in /var/lib/maxscale:
Failed to create directory '/var/lib/maxscale/maxscale.cnf.d': 13, Permission denied\n
To mitigate this, by default, the operator sets the following securityContext in the MaxScale's StatefulSet:
apiVersion: apps/v1\nkind: StatefulSet\nmetadata:\n name: maxscale-galera\nspec:\n securityContext:\n fsGroup: 996\n runAsGroup: 996\n runAsNonRoot: true\n runAsUser: 998\n
This enables the CSIDriver and the kubelet to recursively set the ownership ofr the /var/lib/maxscale folder to the group 996, which is the one expected by MaxScale. It is important to note that not all the CSIDrivers implementations support this feature, see the CSIDriver documentation for further information.
"},{"location":"MAXSCALE/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"METADATA/","title":"Metadata","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.28
This documentation shows how to configure metadata in the mariadb-operator CRs.
"},{"location":"METADATA/#table-of-contents","title":"Table of contents","text":" - Children object metadata
Pod metadataService metadataPVC metadata- Use cases
- Reference
"},{"location":"METADATA/#children-object-metadata","title":"Children object metadata","text":"MariaDB and MaxScale resources allow you to propagate metadata to all the children objects by specifying the inheritMetadata field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n inheritMetadata:\n labels:\n database.myorg.io: mariadb\n annotations:\n database.myorg.io: mariadb\n
This means that all the reconciled objects will inherit these labels and annotations. For instance, see the Services and Pods:
apiVersion: v1\nkind: Service\nmetadata:\n annotations:\n database.myorg.io: mariadb\n labels:\n database.myorg.io: mariadb\n name: mariadb-galera-primary\n namespace: default\n
apiVersion: v1\nkind: Pod\nmetadata:\n annotations:\n database.myorg.io: mariadb\n labels:\n database.myorg.io: mariadb\n name: mariadb-galera-0\n namespace: default\n
"},{"location":"METADATA/#pod-metadata","title":"Pod metadata","text":"You have the ability to provide dedicated metadata for Pods by specifying the podMetadata field in any CR that reconciles a Pod, for instance: MariaDB, MaxScale, Backup, Restore and SqlJobs:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n inheritMetadata:\n labels:\n sidecar.istio.io/inject: \"true\"\n annotations:\n database.myorg.io: mariadb\n podMetadata:\n labels:\n sidecar.istio.io/inject: \"false\"\n
It is important to note that the podMetadata field superseeds the inheritMetadata field, therefore the labels and annotations provided in the former will override the ones in the latter.
"},{"location":"METADATA/#service-metadata","title":"Service metadata","text":"Provision dedicated metadata for Services in the MariaDB resources can be done via the service, primaryService and secondaryService fields:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n service:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.150\n\n primaryService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.160\n\n secondaryService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.161\n
In the case of MaxScale, you can also do this via the kubernetesService field.
Refer to the HA documentation to know more about the Service fields and MaxScale.
"},{"location":"METADATA/#pvc-metadata","title":"PVC metadata","text":"Both MariaDB and MaxScale allow you to define a volumeClaimTemplate to be used by the underlying StatefulSet. You may also define metadata for it:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n storage:\n size: 1Gi\n volumeClaimTemplate:\n metadata:\n annotations:\n database.myorg.io: mariadb\n labels:\n database.myorg.io: mariadb\n accessModes:\n - ReadWriteOnce\n resources:\n requests:\n storage: 1Gi\n
"},{"location":"METADATA/#use-cases","title":"Use cases","text":"Being able to provide metadata allows you to integrate with other CNCF landscape projects:
"},{"location":"METADATA/#metallb","title":"Metallb","text":"If you run on bare metal and you use Metallb for managing the LoadBalancer objects, you can declare its IPs via annotations:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n service:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.150\n
"},{"location":"METADATA/#istio","title":"Istio","text":"Istio injects the data plane container to all Pods, but you might want to opt-out of this feature in some cases:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n podMetadata:\n labels:\n sidecar.istio.io/inject: \"false\"\n
For instance, you probably don't want to inject the Istio sidecar to Backup Pods, as it will prevent the Jobs from finishing and therefore your backup process will hang.
"},{"location":"METADATA/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"METRICS/","title":"Prometheus metrics","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.24
mariadb-operator is able to provision MariaDB instances and automatically configure Prometheus to scrape their metrics so they can be used later on to build Grafana dashboards or trigger Alertmanager alerts.
"},{"location":"METRICS/#table-of-contents","title":"Table of contents","text":" - Operator metrics
- Exporter
ServiceMonitor- Configuration
- Prometheus reference installation
- Grafana dashboards
- Reference
"},{"location":"METRICS/#operator-metrics","title":"Operator metrics","text":"In order to expose the operator internal metrics, please refer to the recommended installation flavour.
"},{"location":"METRICS/#exporter","title":"Exporter","text":"The operator configures a prometheus/mysqld-exporter exporter to query MariaDB and export the metrics in Prometheus format via an http endpoint.
It is important to note that, we run this exporter as an standalone Deployment and not as a sidecar alongside every MariaDB replica. This implies that the MariaDB lifecycle is not coupled to the exporter one, so we can upgrade them independently without affecting the availability of the other.
For being able to do this, we rely on the multi-target feature introduced in the v0.15.0 of prometheus/mysqld-exporter, so make sure to specify at least v0.15.0 in the exporter image.
"},{"location":"METRICS/#servicemonitor","title":"ServiceMonitor","text":"Once the exporter Deployment is ready, mariadb-operator creates a ServiceMonitor object that will be eventually reconciled by the Prometheus operator , resulting in the Prometheus instance being configured to scrape the exporter endpoint.
As you scale your MariaDB with more or less replicas, mariadb-operator will reconcile the ServiceMonitor to add/remove targets related to the MariaDB instances.
"},{"location":"METRICS/#configuration","title":"Configuration","text":"The easiest way to setup metrics in your MariaDB instance is just by setting spec.metrics.enabled = true, like in this example:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n...\n metrics:\n enabled: true\n
The rest of the fields are defaulted by the operator. If you need a more fine grained configuration, refer to the API reference and take a look at this example:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n...\n metrics:\n enabled: true\n exporter:\n image: prom/mysqld-exporter:v0.15.1\n resources:\n requests:\n cpu: 50m\n memory: 64Mi\n limits:\n cpu: 300m\n memory: 512Mi\n port: 9104\n serviceMonitor:\n prometheusRelease: kube-prometheus-stack\n jobLabel: mariadb-monitoring\n interval: 10s\n scrapeTimeout: 10s\n username: monitoring\n passwordSecretKeyRef:\n name: mariadb\n key: password\n
"},{"location":"METRICS/#prometheus-reference-installation","title":"Prometheus reference installation","text":"The easiest way to spin up a Prometheus observability stack in Kubernetes is by installing the kube-prometheus-stack helm chart.
We leverage this chart in our local development environment and we have configured it to ensure quality interactions between mariadb-operator and Prometheus. Feel free to install it by running:
make cluster\nmake install-prometheus\n
"},{"location":"METRICS/#grafana-dashboards","title":"Grafana dashboards","text":"To visualize MariaDB metrics, our Prometheus reference installation has some interesting Grafana dashboards configured that make use of the metrics configured by mariadb-operator. They are all available on grafana.com:
MySQL Overview
MySQL Exporter Quickstart and Dashboard
MySQL Replication
Galera/MariaDB - Overview
"},{"location":"METRICS/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"REGISTRY/","title":"Registry","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.27
This documentation aims to provide guidance on how to configure private registries in the mariadb-operator CRs.
"},{"location":"REGISTRY/#table-of-contents","title":"Table of contents","text":" - Credentials
MariaDBMaxScaleBackup, Restore and SqlJob
"},{"location":"REGISTRY/#credentials","title":"Credentials","text":"The first requirement to access a private registry is having credentials in the cluster that will be pulling the images. Kubernetes has a specific type of Secret kubernetes.io/dockerconfigjson designed specifically for this purpose. Please, refer to the Kubernetes documentation to see how it can be configured.
For convenience, this repo provides a make target that can be used to configure your existing credentials available in ~/.docker/config as a kubernetes.io/dockerconfigjson Secret:
REGISTRY_PULL_SECRET=registry DOCKER_CONFIG=~/.docker/config.json make registry-secret\n
"},{"location":"REGISTRY/#mariadb","title":"MariaDB","text":"In order to configure a private registry in your MariaDB resource, you can specify multiple imagePullSecrets:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n image: docker.mariadb.com/enterprise-server:10.6\n imagePullPolicy: IfNotPresent\n imagePullSecrets:\n - name: registry\n - name: another-registry\n
As a result, the Pods created as part of the reconciliation process will have the imagePullSecrets.
You can also configure credentials for the metrics exporter:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n metrics:\n enabled: true\n exporter:\n image: prom/mysqld-exporter:v0.15.1\n imagePullPolicy: IfNotPresent\n imagePullSecrets:\n - name: registry\n
By default, the metrics exporter Pod will inherit the credentials specified in the imagePullSecrets root field, but you can also specify dedicated credentials via metrics.exporter.imagePullSecrets.
"},{"location":"REGISTRY/#maxscale","title":"MaxScale","text":"Similarly to MariaDB, you are able to configure private registries in your MaxScale resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale\nspec:\n ...\n image: mariadb/maxscale:23.08\n imagePullPolicy: IfNotPresent\n imagePullSecrets:\n - name: registry\n
"},{"location":"REGISTRY/#backup-restore-and-sqljob","title":"Backup, Restore and SqlJob","text":"The batch Job resources will inherit the imagePullSecrets from the referred MariaDB, as they also make use of its image. However, you are also able to provide dedicated imagePullSecrets for these resources:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n image: docker.mariadb.com/enterprise-server:10.6\n imagePullPolicy: IfNotPresent\n imagePullSecrets:\n - name: registry\n
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n ...\n mariaDbRef:\n name: mariadb\n imagePullSecrets:\n - name: backup-registry\n
When the resources from the above examples are created, a Job with both registry and backup-registry imagePullSecrets will be reconciled.
"},{"location":"STORAGE/","title":"Storage","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.26
This operator gives you flexibility to define the storage that will back the /var/lib/mysql data directoty mounted by MariaDB.
"},{"location":"STORAGE/#table-of-contents","title":"Table of contents","text":" - Configuration
- Volume resize
- Ephemeral storage
- Reference
"},{"location":"STORAGE/#configuration","title":"Configuration","text":"The simplest way to configure storage for your MariaDB is:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n size: 1Gi\n
This will make use of the default StorageClass available in your cluster, but you can also provide a different one:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n size: 1Gi\n storageClassName: my-storage-class\n
Under the scenes, the operator is configuring the StatefulSet's volumeClaimTemplate property, which you are also able to provide yourself:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n size: 1Gi\n storageClassName: standard\n volumeClaimTemplate:\n accessModes:\n - ReadWriteOnce\n resources:\n requests:\n storage: 1Gi\n storageClassName: standard\n
"},{"location":"STORAGE/#volume-resize","title":"Volume resize","text":"[!WARNING] The StorageClass used for volume resizing must define allowVolumeExpansion = true.
It is possible to resize your storage after having provisioned a MariaDB. We need to distinguish between: - PVCs already in use. - StatefulSet storage size, which will be used when provisioning new replicas.
It is important to note that, for the first case, your StorageClass must support volume expansion by declaring the allowVolumeExpansion = true. In such case, it will be safe to expand the storage by increasing the size and setting resizeInUseVolumes = true:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n size: 2Gi\n resizeInUseVolumes: true\n waitForVolumeResize: true\n
Depending on your storage provider, this operation might take a while, and you can decide to wait for this operation before the MariaDB becomes ready by setting waitForVolumeResize = true. Operations such as cluster recovery and primary switchover will not be performed if the MariaDB resource is not ready.
"},{"location":"STORAGE/#ephemeral-storage","title":"Ephemeral storage","text":"Provisioning standalone MariaDB instances is also possible by setting ephemeral = true:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n ephemeral: true \n
This may be useful more multiple use cases, like provisioning ephemeral MariaDBs for the integration tests of your CI.
"},{"location":"STORAGE/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"UPDATES/","title":"Updates","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.29
This documentation aims to describe the supported strategies to perform updates of the MariaDB resource.
"},{"location":"UPDATES/#table-of-contents","title":"Table of contents","text":" - Update strategies
- Configuration
- Trigger updates
ReplicasFirstPrimaryLastRollingUpdateOnDelete
"},{"location":"UPDATES/#update-strategies","title":"Update strategies","text":"In order to provide you with flexibility for updating MariaDB reliably, this operator supports multiple update strategies:
ReplicasFirstPrimaryLast: Roll out replica Pods one by one, wait for each of them to become ready, and then proceed with the primary Pod.RollingUpdate: Utilize the rolling update strategy from Kubernetes. OnDelete: Updates are performed manually by deleting Pods.
"},{"location":"UPDATES/#configuration","title":"Configuration","text":"The update strategy can be configured in the updateStrategy field of the MariaDB resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n updateStrategy:\n type: ReplicasFirstPrimaryLast\n
It defaults to ReplicasFirstPrimaryLast if not provided.
"},{"location":"UPDATES/#trigger-updates","title":"Trigger updates","text":"Updates are not limited to updating the image field in the MariaDB resource, an update will be triggered whenever any field of the Pod template is changed. This translates into making changes to MariaDB fields that map directly or indirectly to the Pod template, for instance, the CPU and memory resources:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n- image: mariadb:10.11.7\n+ image: mariadb:10.11.8\n resources:\n requests:\n cpu: 200m\n memory: 128Mi\n limits:\n- memory: 1Gi\n+ memory: 2Gi\n
Once the update is triggered, the operator manages it differently based on the selected update strategy.
"},{"location":"UPDATES/#replicasfirstprimarylast","title":"ReplicasFirstPrimaryLast","text":"This role-aware update strategy consists in rolling out the replica Pods one by one first, waiting for each of them become ready (i.e. readiness probe passed), and then proceed with the primary Pod. This is the default update strategy, as it can potentially meet various reliability requirements and minimize the risks associated with updates:
- Write operations won't be affected until all the replica
Pods have been rolled out. If something goes wrong in the update, such as an update to an incompatible MariaDB version, this is detected early when the replicas are being rolled out and the update operation will be paused at that point. - Read operations impact is minimized by only rolling one replica
Pod at a time. - Waiting for every
Pod to be synced minimizes the impact in the clustering protocols and the network.
"},{"location":"UPDATES/#rollingupdate","title":"RollingUpdate","text":"This strategy leverages the rolling update strategy from the StatefulSet resource, which, unlike ReplicasFirstPrimaryLast, does not take into account the role of the Pods(primary or replica). Instead, it rolls out the Pods one by one, from the highest to the lowest StatefulSet index.
You are able to pass extra parameters to this strategy via the rollingUpdate object:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n updateStrategy:\n type: RollingUpdate\n rollingUpdate:\n maxUnavailable: 1\n
"},{"location":"UPDATES/#ondelete","title":"OnDelete","text":"This strategy aims to provide a method to update MariaDB resources manually by allowing users to restart the Pods individually.This way, the user has full control over the update process and can decide which Pods are rolled out at any given time.
Whenever an update is triggered, the MariaDB will be marked as pending to update:
kubectl get mariadbs\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera True Pending update mariadb-galera-0 5m17s\n
From this point, you are able to delete the Pods to trigger the update, which will result the MariaDB marked as updating:
kubectl get mariadbs\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera False Updating mariadb-galera-0 9m50s\n
Once all the Pods have been rolled out, the MariaDB resource will be back to a ready state:
kubectl get mariadbs\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera True Running mariadb-galera-1 12m\n
"},{"location":"UPGRADE_v0.0.20/","title":"Upgrade guide v0.0.20","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.20 from previous versions, as some breaking changes have been introduced. See: - https://github.com/mariadb-operator/mariadb-operator/pull/197 - https://github.com/mariadb-operator/mariadb-operator/pull/211
It's important to note that this migration process only applies if: - You have created a MariaDB resource using a mariadb-operator version < v0.0.20 and you are upgrading to >= v0.0.20. - Your MariaDB resource has spec.replication enabled.
If that's your case follow these steps for upgrading:
- Uninstall you current
mariadb-operator for preventing conflicts:
helm uninstall mariadb-operator\n
Alternatively, you may only downscale and delete the webhook configurations:
kubectl scale deployment mariadb-operator -n default --replicas=0\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=0\nkubectl delete validatingwebhookconfiguration mariadb-operator-webhook\nkubectl delete mutatingwebhookconfiguration mariadb-operator-webhook\n
- In case you are manually applying manifests, get a copy of your
MariaDB resources, as the CRD upgrade will wipe out fields that are no longer supported:
kubectl get mariadb mariadb-repl -n default -o yaml > mariadb-repl.yaml\n
- Upgrade CRDs to
v0.0.20: [!IMPORTANT] Helm does not handle CRD upgrades. See helm docs.
[!WARNING] This step will delete fields that are no longer supported in your resources.
kubectl replace -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.20.0/crds.yaml\n
- Perform migrations in your
MariaDB resouces: - Set
spec.replication.enabled = true. - If you had previously set
spec.replication.primary.service, move it to spec.primaryService. - Rename your resources to point to the new
<mariadb-name>-primary Service instead of primary-<mariadb-name>. - If you had previously set
spec.replication.primary.connection, move it to spec.primaryConnection. -
Rename your resources to point to the new <mariadb-name>-primary Connection instead of primary-<mariadb-name>.
-
Upgrade mariadb-operator to v0.0.20:
helm repo update mariadb-operator\nhelm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --version 0.20.0 \n
- If you previously decided to downscale the operator, make sure you upscale it back:
kubectl scale deployment mariadb-operator -n default --replicas=1\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=1\n
"},{"location":"UPGRADE_v0.0.21/","title":"Upgrade guide v0.0.21","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.21 from previous versions, as some breaking changes have been introduced. See: - https://github.com/mariadb-operator/mariadb-operator/pull/248
Follow these steps for upgrading:
- Uninstall you current
mariadb-operator for preventing conflicts:
helm uninstall mariadb-operator\n
Alternatively, you may only downscale and delete the webhook configurations:
kubectl scale deployment mariadb-operator -n default --replicas=0\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=0\nkubectl delete validatingwebhookconfiguration mariadb-operator-webhook\nkubectl delete mutatingwebhookconfiguration mariadb-operator-webhook\n
- In case you are manually applying manifests, get a copy of your
MariaDB resources, as the CRD upgrade will wipe out fields that are no longer supported:
kubectl get mariadb mariadb-repl -n default -o yaml > mariadb-repl.yaml\n
- Upgrade CRDs to
v0.0.21: [!IMPORTANT] Helm does not handle CRD upgrades. See helm docs.
[!WARNING] This step will delete fields that are no longer supported in your resources.
kubectl replace -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.21.0/crds.yaml\n
- Perform migrations in your
MariaDB resouces: MariaDB standalone migration ```diff- image:
- repository: mariadb
- tag: \"11.0.3\"
- pullPolicy: IfNotPresent
- image: mariadb:11.0.3
- imagePullPolicy: IfNotPresent ```
MariaDB galera migration ```diff- image:
- repository: mariadb
- tag: \"11.0.3\"
- pullPolicy: IfNotPresent
- image: mariadb:11.0.3
- imagePullPolicy: IfNotPresent galera: agent:
- image:
- repository: ghcr.io/mariadb-operator/mariadb-operator
- tag: \"v0.0.25\"
- pullPolicy: IfNotPresent
- image: ghcr.io/mariadb-operator/mariadb-operator:v0.0.26
- imagePullPolicy: IfNotPresent initContainer:
- image:
- repository: ghcr.io/mariadb-operator/init
- tag: \"v0.0.5\"
- pullPolicy: IfNotPresent
- image: ghcr.io/mariadb-operator/init:v0.0.6
-
imagePullPolicy: IfNotPresent ```
-
Upgrade mariadb-operator to v0.0.21:
helm repo update mariadb-operator\nhelm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --version 0.21.0 \n
- If you previously decided to downscale the operator, make sure you upscale it back:
kubectl scale deployment mariadb-operator -n default --replicas=1\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=1\n
"},{"location":"UPGRADE_v0.0.24/","title":"Upgrade guide v0.0.24","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.24 from previous versions, as some breaking changes have been introduced. See:
MariaDB - https://github.com/mariadb-operator/mariadb-operator/pull/248 - https://github.com/mariadb-operator/mariadb-operator/pull/312
Backup - https://github.com/mariadb-operator/mariadb-operator/pull/314
Restore - https://github.com/mariadb-operator/mariadb-operator/pull/308
Follow these steps for upgrading:
- Uninstall you current
mariadb-operator for preventing conflicts:
helm uninstall mariadb-operator\n
Alternatively, you may only downscale and delete the webhook configurations:
kubectl scale deployment mariadb-operator --replicas=0\nkubectl scale deployment mariadb-operator-webhook --replicas=0\nkubectl delete validatingwebhookconfiguration mariadb-operator-webhook\nkubectl delete mutatingwebhookconfiguration mariadb-operator-webhook\n
- In case you are manually applying manifests, get a copy of your
MariaDB, Backup and Restore resources, as the CRD upgrade will wipe out fields that are no longer supported:
kubectl get mariadb mariadb -o yaml > mariadb.yaml\nkubectl get backup backup -o yaml > backup.yaml\nkubectl get restore restore -o yaml > restore.yaml\n
- Upgrade CRDs to
v0.0.24: [!IMPORTANT] Helm does not handle CRD upgrades. See helm docs.
[!WARNING] This step will delete fields that are no longer supported in your resources.
kubectl replace -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.24.0/crds.yaml\n
- Perform migrations in your
MariaDB resouces:
metrics:\n+ enabled: true\n exporter:\n- image: prom/mysqld-exporter:v0.14.0\n+ image: prom/mysqld-exporter:v0.15.1\n
- Perform migrations in your
Backup resouces:
- maxRetentionDays: 30\n+ maxRetention: 720h\n
- Perform migrations in your
Restore resouces:
- fileName: backup.2023-12-19T09:00:00Z.sql\n+ targetRecoveryTime: 2023-12-19T09:00:00Z\n
- Upgrade
mariadb-operator to v0.0.24:
helm repo update mariadb-operator\nhelm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --version 0.24.0 \n
- If you previously decided to downscale the operator, make sure you upscale it back:
kubectl scale deployment mariadb-operator -n default --replicas=1\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=1\n
- If you have previously created
MariaDB instances with metrics enabled and a single replica, we also need to perform the following changes in order to create a new StatefulSet with spec.serviceName pointing to the internal Service(see https://github.com/mariadb-operator/mariadb-operator/issues/319 for context):
kubectl delete statefulset mariadb --cascade=orphan\nkubectl rollout restart statefulset mariadb\n
"},{"location":"UPGRADE_v0.0.26/","title":"Upgrade guide v0.0.26","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.26 from previous versions, as some breaking changes have been introduced in the MariaDB resource. See the changes grouped by field:
apiVersion https://github.com/mariadb-operator/mariadb-operator/pull/418
storage https://github.com/mariadb-operator/mariadb-operator/pull/407
serviceAccountName https://github.com/mariadb-operator/mariadb-operator/pull/416
galera https://github.com/mariadb-operator/mariadb-operator/pull/384 https://github.com/mariadb-operator/mariadb-operator/pull/394
Follow these steps for upgrading:
- In your current
mariadb-operator version, make sure the MariaDB to migrate is in ready state and get a copy of its manifest: [!IMPORTANT] MariaDB must be in ready state.
kubectl get mariadbs.mariadb.mmontes.io mariadb-galera -o yaml > mariadb-galera.yaml\n
- Download and setup the migration script:
wget -q \"https://raw.githubusercontent.com/mariadb-operator/mariadb-operator/main/hack/migrate_v0.0.26.sh\"\nchmod +x migrate_v0.0.26.sh\n
- Install
v0.0.26 CRDs: [!NOTE] Helm does not handle CRD upgrades. See helm docs.
kubectl apply --server-side=true --force-conflicts -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.26.0/crds.yaml\n
- Execute the migration script:
./migrate_v0.0.26.sh mariadb-galera.yaml\n
- Apply the
v0.0.26 specification:
kubectl apply -f migrated.mariadb-galera.yaml\n
- Patch the
v0.0.26 status:
kubectl patch mariadbs.k8s.mariadb.com mariadb-galera --subresource status --type merge -p \"$(cat status.mariadb-galera.yaml)\"\n
- Patch the
StatefulSet ownerReferences. All the remaining children resources will be instantly recreated by the v0.0.26 operator, but you might also patch them if you want: [!WARNING] Not changing the StatefulSet ownerReferences implies that it will be garbage collected when deleting the old CRDs.
MARIADB_UID=$(kubectl get mariadbs.k8s.mariadb.com mariadb-galera -o jsonpath=\"{.metadata.uid}\")\nkubectl patch statefulset mariadb-galera --type=json -p=\"[\n {\\\"op\\\": \\\"replace\\\", \\\"path\\\": \\\"/metadata/ownerReferences/0/apiVersion\\\", \\\"value\\\": \\\"k8s.mariadb.com/v1alpha1\\\"}, \n {\\\"op\\\": \\\"replace\\\", \\\"path\\\": \\\"/metadata/ownerReferences/0/uid\\\", \\\"value\\\": \\\"${MARIADB_UID}\\\"}\n]\"\n
- Uninstall you current
mariadb-operator:
helm uninstall mariadb-operator\n
- If your
MariaDB has Galera enabled, delete the mariadb-galera Role, as it will be specyfing the old CRDs:
kubectl delete role mariadb-galera\n
- Install the current
mariadb-operator version:
helm repo update mariadb-operator\nhelm install mariadb-operator mariadb-operator/mariadb-operator\n
- Cleanup old CRDs and migration script:
OLD_HELM_VERSION=0.25.0\nkubectl delete -f \"https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-${OLD_HELM_VERSION}/crds.yaml\"\n
rm migrate_v0.0.26.sh\n
"},{"location":"UPGRADE_v0.0.28/","title":"Upgrade guide v0.0.28","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.28 from previous versions, as some breaking changes have been introduced:
- Metadata: https://github.com/mariadb-operator/mariadb-operator/pull/537
- Affinity: https://github.com/mariadb-operator/mariadb-operator/pull/566 and https://github.com/mariadb-operator/mariadb-operator/pull/568
- Opt-in password generation: https://github.com/mariadb-operator/mariadb-operator/pull/598
Follow these steps for upgrading:
- Install
v0.0.28 CRDs: [!NOTE] Helm does not handle CRD upgrades. See helm docs.
kubectl apply --server-side=true --force-conflicts -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.28.0/crds.yaml\n
- Uninstall you current
mariadb-operator for preventing conflicts:
helm uninstall mariadb-operator\n
Alternatively, you may only downscale and delete the webhook configurations:
kubectl scale deployment mariadb-operator --replicas=0\nkubectl scale deployment mariadb-operator-webhook --replicas=0\nkubectl delete validatingwebhookconfiguration mariadb-operator-webhook\nkubectl delete mutatingwebhookconfiguration mariadb-operator-webhook\n
- In case you are manually applying manifests, get a copy of your resources, as the CRD upgrade will wipe out fields that are no longer supported:
kubectl get mariadb mariadb -o yaml > mariadb.yaml\nkubectl get maxscale maxscale -o yaml > maxscale.yaml\nkubectl get backup backup -o yaml > backup.yaml\nkubectl get restore restore -o yaml > restore.yaml\nkubectl get restore sqljob -o yaml > sqljob.yaml\n
- Upgrade CRDs to
v0.0.28: [!IMPORTANT] Helm does not handle CRD upgrades. See helm docs.
[!WARNING] This step will delete fields that are no longer supported in your resources.
kubectl replace -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.28.0/crds.yaml\n
- Perform
metadata related migrations in MariaDB, MaxScale and Connection resouces:
storage:\n volumeClaimTemplate:\n- labels:\n- k8s.mariadb.io/storage: \"fast\"\n- annotations:\n- k8s.mariadb.io/storage: \"fast\"\n+ metadata:\n+ labels:\n+ k8s.mariadb.io/storage: \"fast\"\n+ annotations:\n+ k8s.mariadb.io/storage: \"fast\"\n accessModes:\n - ReadWriteOnce\n resources:\n requests:\n storage: 1Gi\n storageClassName: standard\n\n service:\n type: LoadBalancer\n- labels:\n- k8s.mariadb.io/service: \"mysvc\"\n- annotations:\n- metallb.universe.tf/loadBalancerIPs: 172.18.0.150\n+ metadata:\n+ labels:\n+ k8s.mariadb.io/service: \"mysvc\"\n+ annotations:\n+ metallb.universe.tf/loadBalancerIPs: 172.18.0.150\n\n connection:\n secretName: mariadb-galera-conn\n secretTemplate:\n- labels:\n- k8s.mariadb.io/secret: \"supersecret\"\n- annotations:\n- k8s.mariadb.io/secret: \"supersecret\"\n+ metadata:\n+ labels:\n+ k8s.mariadb.io/secret: \"supersecret\"\n+ annotations:\n+ k8s.mariadb.io/secret: \"supersecret\"\n key: dsn\n\n galera:\n initJob:\n- labels:\n- sidecar.istio.io/inject: \"false\"\n- annotations\n- sidecar.istio.io/inject: \"false\"\n+ metadata:\n+ labels:\n+ sidecar.istio.io/inject: \"false\"\n+ annotations\n+ sidecar.istio.io/inject: \"false\"\n\n bootstrapFrom:\n restoreJob:\n- labels:\n- sidecar.istio.io/inject: \"false\"\n- annotations\n- sidecar.istio.io/inject: \"false\"\n+ metadata:\n+ labels:\n+ sidecar.istio.io/inject: \"false\"\n+ annotations\n+ sidecar.istio.io/inject: \"false\"\n
- Perform
affinity related migrations in MariaDB, MaxScale, Backup, Restore and SqlJob resources:
affinity:\n- enableAntiAffinity: true\n+ antiAffinityEnabled: true\n\n galera:\n initJob:\n affinity:\n- enableAntiAffinity: true\n+ antiAffinityEnabled: true\n\n bootstrapFrom:\n restoreJob:\n affinity:\n- enableAntiAffinity: true\n+ antiAffinityEnabled: true\n
- Perform password generation migrations in
MariaDB and MaxScale resources. This only applies if you are currently relying on Secrets generated by the operator:
- rootPasswordSecretKeyRef:\n- name: mariadb\n- key: root-password\n+ rootPasswordSecretKeyRef:\n+ name: mariadb\n+ key: root-password\n+ generate: true\n\n- passwordSecretKeyRef:\n- name: mariadb\n- key: root-password\n+ passwordSecretKeyRef:\n+ name: mariadb\n+ key: root-password\n+ generate: true\n
- Upgrade
mariadb-operator to v0.0.28:
helm repo update mariadb-operator\nhelm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --version 0.28.0 \n
- If you previously decided to downscale the operator, make sure you upscale it back:
kubectl scale deployment mariadb-operator -n default --replicas=1\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=1\n
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83d\udea7\ud83d\udea7\ud83d\udea7 WIP \ud83d\udea7\ud83d\udea7\ud83d\udea7","text":"For full documentation visit mkdocs.org.
"},{"location":"#commands","title":"Commands","text":" mkdocs new [dir-name] - Create a new project.mkdocs serve - Start the live-reloading docs server.mkdocs build - Build the documentation site.mkdocs -h - Print help message and exit.
"},{"location":"#project-layout","title":"Project layout","text":"mkdocs.yml # The configuration file.\ndocs/\n index.md # The documentation homepage.\n ... # Other markdown pages, images and other files.\n
"},{"location":"API_REFERENCE/","title":"API Reference","text":""},{"location":"API_REFERENCE/#packages","title":"Packages","text":" - k8s.mariadb.com/v1alpha1
"},{"location":"API_REFERENCE/#k8smariadbcomv1alpha1","title":"k8s.mariadb.com/v1alpha1","text":"Package v1alpha1 contains API Schema definitions for the v1alpha1 API group
"},{"location":"API_REFERENCE/#resource-types","title":"Resource Types","text":" - Backup
- Connection
- Database
- Grant
- MariaDB
- MaxScale
- Restore
- SqlJob
- User
"},{"location":"API_REFERENCE/#affinityconfig","title":"AffinityConfig","text":"AffinityConfig defines policies to schedule Pods in Nodes.
Appears in: - BackupSpec - Exporter - Job - JobPodTemplate - MariaDBSpec - MaxScaleSpec - PodTemplate - RestoreSpec - SqlJobSpec
Field Description Default Validation antiAffinityEnabled boolean AntiAffinityEnabled configures PodAntiAffinity so each Pod is scheduled in a different Node, enabling HA.Make sure you have at least as many Nodes available as the replicas to not end up with unscheduled Pods."},{"location":"API_REFERENCE/#backup","title":"Backup","text":"Backup is the Schema for the backups API. It is used to define backup jobs and its storage.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Backup metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec BackupSpec"},{"location":"API_REFERENCE/#backupspec","title":"BackupSpec","text":"BackupSpec defines the desired state of Backup
Appears in: - Backup
Field Description Default Validation args string array Args to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. successfulJobsHistoryLimit integer Minimum: 0 failedJobsHistoryLimit integer Minimum: 0 timeZone string mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} storage BackupStorage Storage to be used in the Backup. Required: {} schedule Schedule Schedule defines when the Backup will be taken. maxRetention Duration MaxRetention defines the retention policy for backups. Old backups will be cleaned up by the Backup Job.It defaults to 30 days. databases string array Databases defines the logical databases to be backed up. If not provided, all databases are backed up. ignoreGlobalPriv boolean IgnoreGlobalPriv indicates to ignore the mysql.global_priv in backups.If not provided, it will default to true when the referred MariaDB instance has Galera enabled and otherwise to false.See: https://github.com/mariadb-operator/mariadb-operator/issues/556 logLevel string LogLevel to be used n the Backup Job. It defaults to 'info'. info backoffLimit integer BackoffLimit defines the maximum number of attempts to successfully take a Backup. restartPolicy RestartPolicy RestartPolicy to be added to the Backup Pod. OnFailure Enum: [Always OnFailure Never] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources."},{"location":"API_REFERENCE/#backupstorage","title":"BackupStorage","text":"BackupStorage defines the storage for a Backup.
Appears in: - BackupSpec
Field Description Default Validation s3 S3 S3 defines the configuration to store backups in a S3 compatible storage. persistentVolumeClaim PersistentVolumeClaimSpec PersistentVolumeClaim is a Kubernetes PVC specification. volume VolumeSource Volume is a Kubernetes volume specification."},{"location":"API_REFERENCE/#bootstrapfrom","title":"BootstrapFrom","text":"BootstrapFrom defines a source to bootstrap MariaDB from.
Appears in: - MariaDBSpec
Field Description Default Validation backupRef LocalObjectReference BackupRef is a reference to a Backup object. It has priority over S3 and Volume. s3 S3 S3 defines the configuration to restore backups from a S3 compatible storage. It has priority over Volume. volume VolumeSource Volume is a Kubernetes Volume object that contains a backup. targetRecoveryTime Time TargetRecoveryTime is a RFC3339 (1970-01-01T00:00:00Z) date and time that defines the point in time recovery objective.It is used to determine the closest restoration source in time. restoreJob Job RestoreJob defines additional properties for the Job used to perform the Restore."},{"location":"API_REFERENCE/#cleanuppolicy","title":"CleanupPolicy","text":"Underlying type: string
CleanupPolicy defines the behavior for cleaning up a resource.
Appears in: - DatabaseSpec - GrantSpec - SQLTemplate - UserSpec
Field Description Skip CleanupPolicySkip indicates that the resource will NOT be deleted from the database after the CR is deleted. Delete CleanupPolicyDelete indicates that the resource will be deleted from the database after the CR is deleted."},{"location":"API_REFERENCE/#connection","title":"Connection","text":"Connection is the Schema for the connections API. It is used to configure connection strings for the applications connecting to MariaDB.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Connection metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec ConnectionSpec"},{"location":"API_REFERENCE/#connectionspec","title":"ConnectionSpec","text":"ConnectionSpec defines the desired state of Connection
Appears in: - Connection
Field Description Default Validation secretName string SecretName to be used in the Connection. secretTemplate SecretTemplate SecretTemplate to be used in the Connection. healthCheck HealthCheck HealthCheck to be used in the Connection. params object (keys:string, values:string) Params to be used in the Connection. serviceName string ServiceName to be used in the Connection. port integer Port to connect to. If not provided, it defaults to the MariaDB port or to the first MaxScale listener. mariaDbRef MariaDBRef MariaDBRef is a reference to the MariaDB to connect to. Either MariaDBRef or MaxScaleRef must be provided. maxScaleRef ObjectReference MaxScaleRef is a reference to the MaxScale to connect to. Either MariaDBRef or MaxScaleRef must be provided. username string Username to use for configuring the Connection. Required: {} passwordSecretKeyRef SecretKeySelector PasswordSecretKeyRef is a reference to the password to use for configuring the Connection.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. Required: {} host string Host to connect to. If not provided, it defaults to the MariaDB host or to the MaxScale host. database string Database to use when configuring the Connection."},{"location":"API_REFERENCE/#connectiontemplate","title":"ConnectionTemplate","text":"ConnectionTemplate defines a template to customize Connection objects.
Appears in: - ConnectionSpec - MariaDBMaxScaleSpec - MariaDBSpec - MaxScaleSpec
Field Description Default Validation secretName string SecretName to be used in the Connection. secretTemplate SecretTemplate SecretTemplate to be used in the Connection. healthCheck HealthCheck HealthCheck to be used in the Connection. params object (keys:string, values:string) Params to be used in the Connection. serviceName string ServiceName to be used in the Connection. port integer Port to connect to. If not provided, it defaults to the MariaDB port or to the first MaxScale listener."},{"location":"API_REFERENCE/#container","title":"Container","text":"Container object definition.
Appears in: - Exporter - Galera - GaleraSpec - MariaDBSpec - MaxScaleSpec - PodTemplate
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. image string Image name to be used by the MariaDB instances. The supported format is <image>:<tag>. Required: {} imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent]"},{"location":"API_REFERENCE/#containertemplate","title":"ContainerTemplate","text":"ContainerTemplate defines a template to configure Container objects.
Appears in: - Container - Exporter - GaleraAgent - MariaDBSpec - MaxScaleSpec
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container."},{"location":"API_REFERENCE/#cooperativemonitoring","title":"CooperativeMonitoring","text":"Underlying type: string
CooperativeMonitoring enables coordination between multiple MaxScale instances running monitors. See: https://mariadb.com/docs/server/architecture/components/maxscale/monitors/mariadbmon/use-cooperative-locking-ha-maxscale-mariadb-monitor/
Appears in: - MaxScaleMonitor
Field Description majority_of_all CooperativeMonitoringMajorityOfAll requires a lock from the majority of the MariaDB servers, even the ones that are down. majority_of_running CooperativeMonitoringMajorityOfRunning requires a lock from the majority of the MariaDB servers."},{"location":"API_REFERENCE/#cronjobtemplate","title":"CronJobTemplate","text":"CronJobTemplate defines parameters for configuring CronJob objects.
Appears in: - BackupSpec - SqlJobSpec
Field Description Default Validation successfulJobsHistoryLimit integer Minimum: 0 failedJobsHistoryLimit integer Minimum: 0 timeZone string"},{"location":"API_REFERENCE/#database","title":"Database","text":"Database is the Schema for the databases API. It is used to define a logical database as if you were running a 'CREATE DATABASE' statement.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Database metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec DatabaseSpec"},{"location":"API_REFERENCE/#databasespec","title":"DatabaseSpec","text":"DatabaseSpec defines the desired state of Database
Appears in: - Database
Field Description Default Validation requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. retryInterval Duration RetryInterval is the interval used to perform retries. cleanupPolicy CleanupPolicy CleanupPolicy defines the behavior for cleaning up a SQL resource. Enum: [Skip Delete] mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} characterSet string CharacterSet to use in the Database. utf8 collate string Collate to use in the Database. utf8_general_ci name string Name overrides the default Database name provided by metadata.name. MaxLength: 80"},{"location":"API_REFERENCE/#exporter","title":"Exporter","text":"Exporter defines a metrics exporter container.
Appears in: - MariadbMetrics - MaxScaleMetrics
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. initContainers Container array InitContainers to be used in the Pod. sidecarContainers Container array SidecarContainers to be used in the Pod. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. volumes Volume array Volumes to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints to be used in the Pod. image string Image name to be used as metrics exporter. The supported format is <image>:<tag>.Only mysqld-exporter >= v0.15.0 is supported: https://github.com/prometheus/mysqld_exporter imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] port integer Port where the exporter will be listening for connections."},{"location":"API_REFERENCE/#galera","title":"Galera","text":"Galera allows you to enable multi-master HA via Galera in your MariaDB cluster.
Appears in: - MariaDBSpec
Field Description Default Validation primary PrimaryGalera Primary is the Galera configuration for the primary node. sst SST SST is the Snapshot State Transfer used when new Pods join the cluster.More info: https://galeracluster.com/library/documentation/sst.html. Enum: [rsync mariabackup mysqldump] availableWhenDonor boolean AvailableWhenDonor indicates whether a donor node should be responding to queries. It defaults to false. galeraLibPath string GaleraLibPath is a path inside the MariaDB image to the wsrep provider plugin. It is defaulted if not provided.More info: https://galeracluster.com/library/documentation/mysql-wsrep-options.html#wsrep-provider. replicaThreads integer ReplicaThreads is the number of replica threads used to apply Galera write sets in parallel.More info: https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_slave_threads. providerOptions object (keys:string, values:string) ProviderOptions is map of Galera configuration parameters.More info: https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_provider_options. agent GaleraAgent GaleraAgent is a sidecar agent that co-operates with mariadb-operator. recovery GaleraRecovery GaleraRecovery is the recovery process performed by the operator whenever the Galera cluster is not healthy.More info: https://galeracluster.com/library/documentation/crash-recovery.html. initContainer Container InitContainer is an init container that runs in the MariaDB Pod and co-operates with mariadb-operator. initJob Job InitJob defines a Job that co-operates with mariadb-operator by performing initialization tasks. config GaleraConfig GaleraConfig defines storage options for the Galera configuration files. enabled boolean Enabled is a flag to enable Galera."},{"location":"API_REFERENCE/#galeraagent","title":"GaleraAgent","text":"GaleraAgent is a sidecar agent that co-operates with mariadb-operator.
Appears in: - Galera - GaleraSpec
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. image string Image name to be used by the MariaDB instances. The supported format is <image>:<tag>. imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] port integer Port where the agent will be listening for connections. kubernetesAuth KubernetesAuth KubernetesAuth to be used by the agent container gracefulShutdownTimeout Duration GracefulShutdownTimeout is the time we give to the agent container in order to gracefully terminate in-flight requests."},{"location":"API_REFERENCE/#galeraconfig","title":"GaleraConfig","text":"GaleraConfig defines storage options for the Galera configuration files.
Appears in: - Galera - GaleraSpec
Field Description Default Validation reuseStorageVolume boolean ReuseStorageVolume indicates that storage volume used by MariaDB should be reused to store the Galera configuration files.It defaults to false, which implies that a dedicated volume for the Galera configuration files is provisioned. volumeClaimTemplate VolumeClaimTemplate VolumeClaimTemplate is a template for the PVC that will contain the Galera configuration files shared between the InitContainer, Agent and MariaDB."},{"location":"API_REFERENCE/#galerarecovery","title":"GaleraRecovery","text":"GaleraRecovery is the recovery process performed by the operator whenever the Galera cluster is not healthy. More info: https://galeracluster.com/library/documentation/crash-recovery.html.
Appears in: - Galera - GaleraSpec
Field Description Default Validation enabled boolean Enabled is a flag to enable GaleraRecovery. minClusterSize IntOrString MinClusterSize is the minimum number of replicas to consider the cluster healthy. It can be either a number of replicas (1) or a percentage (50%).If Galera consistently reports less replicas than this value for the given 'ClusterHealthyTimeout' interval, a cluster recovery is iniated.It defaults to '1' replica. clusterMonitorInterval Duration ClusterMonitorInterval represents the interval used to monitor the Galera cluster health. clusterHealthyTimeout Duration ClusterHealthyTimeout represents the duration at which a Galera cluster, that consistently failed health checks,is considered unhealthy, and consequently the Galera recovery process will be initiated by the operator. clusterBootstrapTimeout Duration ClusterBootstrapTimeout is the time limit for bootstrapping a cluster.Once this timeout is reached, the Galera recovery state is reset and a new cluster bootstrap will be attempted. podRecoveryTimeout Duration PodRecoveryTimeout is the time limit for recevorying the sequence of a Pod during the cluster recovery. podSyncTimeout Duration PodSyncTimeout is the time limit for a Pod to join the cluster after having performed a cluster bootstrap during the cluster recovery. forceClusterBootstrapInPod string ForceClusterBootstrapInPod allows you to manually initiate the bootstrap process in a specific Pod.IMPORTANT: Use this option only in exceptional circumstances. Not selecting the Pod with the highest sequence number may result in data loss.IMPORTANT: Ensure you unset this field after completing the bootstrap to allow the operator to choose the appropriate Pod to bootstrap from in an event of cluster recovery. job GaleraRecoveryJob Job defines a Job that co-operates with mariadb-operator by performing the Galera cluster recovery ."},{"location":"API_REFERENCE/#galerarecoveryjob","title":"GaleraRecoveryJob","text":"GaleraRecoveryJob defines a Job used to be used to recover the Galera cluster.
Appears in: - GaleraRecovery
Field Description Default Validation metadata Metadata Refer to Kubernetes API documentation for fields of metadata. resources ResourceRequirements Resouces describes the compute resource requirements."},{"location":"API_REFERENCE/#galeraspec","title":"GaleraSpec","text":"GaleraSpec is the Galera desired state specification.
Appears in: - Galera
Field Description Default Validation primary PrimaryGalera Primary is the Galera configuration for the primary node. sst SST SST is the Snapshot State Transfer used when new Pods join the cluster.More info: https://galeracluster.com/library/documentation/sst.html. Enum: [rsync mariabackup mysqldump] availableWhenDonor boolean AvailableWhenDonor indicates whether a donor node should be responding to queries. It defaults to false. galeraLibPath string GaleraLibPath is a path inside the MariaDB image to the wsrep provider plugin. It is defaulted if not provided.More info: https://galeracluster.com/library/documentation/mysql-wsrep-options.html#wsrep-provider. replicaThreads integer ReplicaThreads is the number of replica threads used to apply Galera write sets in parallel.More info: https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_slave_threads. providerOptions object (keys:string, values:string) ProviderOptions is map of Galera configuration parameters.More info: https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_provider_options. agent GaleraAgent GaleraAgent is a sidecar agent that co-operates with mariadb-operator. recovery GaleraRecovery GaleraRecovery is the recovery process performed by the operator whenever the Galera cluster is not healthy.More info: https://galeracluster.com/library/documentation/crash-recovery.html. initContainer Container InitContainer is an init container that runs in the MariaDB Pod and co-operates with mariadb-operator. initJob Job InitJob defines a Job that co-operates with mariadb-operator by performing initialization tasks. config GaleraConfig GaleraConfig defines storage options for the Galera configuration files."},{"location":"API_REFERENCE/#generatedsecretkeyref","title":"GeneratedSecretKeyRef","text":"GeneratedSecretKeyRef defines a reference to a Secret that can be automatically generated by mariadb-operator if needed.
Appears in: - MariaDBSpec - MariadbMetrics - MaxScaleAuth - ReplicaReplication
Field Description Default Validation generate boolean Generate indicates whether the Secret should be generated if the Secret referenced is not present. false"},{"location":"API_REFERENCE/#grant","title":"Grant","text":"Grant is the Schema for the grants API. It is used to define grants as if you were running a 'GRANT' statement.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Grant metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec GrantSpec"},{"location":"API_REFERENCE/#grantspec","title":"GrantSpec","text":"GrantSpec defines the desired state of Grant
Appears in: - Grant
Field Description Default Validation requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. retryInterval Duration RetryInterval is the interval used to perform retries. cleanupPolicy CleanupPolicy CleanupPolicy defines the behavior for cleaning up a SQL resource. Enum: [Skip Delete] mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} privileges string array Privileges to use in the Grant. MinItems: 1 Required: {} database string Database to use in the Grant. * table string Table to use in the Grant. * username string Username to use in the Grant. Required: {} host string Host to use in the Grant. It can be localhost, an IP or '%'. grantOption boolean GrantOption to use in the Grant. false"},{"location":"API_REFERENCE/#gtid","title":"Gtid","text":"Underlying type: string
Gtid indicates which Global Transaction ID should be used when connecting a replica to the master. See: https://mariadb.com/kb/en/gtid/#using-current_pos-vs-slave_pos.
Appears in: - ReplicaReplication
Field Description CurrentPos GtidCurrentPos indicates the union of gtid_binlog_pos and gtid_slave_pos will be used when replicating from master.This is the default Gtid mode. SlavePos GtidSlavePos indicates that gtid_slave_pos will be used when replicating from master."},{"location":"API_REFERENCE/#healthcheck","title":"HealthCheck","text":"HealthCheck defines intervals for performing health checks.
Appears in: - ConnectionSpec - ConnectionTemplate
Field Description Default Validation interval Duration Interval used to perform health checks. retryInterval Duration RetryInterval is the interval used to perform health check retries."},{"location":"API_REFERENCE/#job","title":"Job","text":"Job defines a Job used to be used with MariaDB.
Appears in: - BootstrapFrom - Galera - GaleraSpec
Field Description Default Validation metadata Metadata Refer to Kubernetes API documentation for fields of metadata. affinity AffinityConfig Affinity to be used in the Pod. resources ResourceRequirements Resouces describes the compute resource requirements. args string array Args to be used in the Container."},{"location":"API_REFERENCE/#jobcontainertemplate","title":"JobContainerTemplate","text":"JobContainerTemplate defines a template to configure Container objects that run in a Job.
Appears in: - BackupSpec - RestoreSpec - SqlJobSpec
Field Description Default Validation args string array Args to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container."},{"location":"API_REFERENCE/#jobpodtemplate","title":"JobPodTemplate","text":"JobPodTemplate defines a template to configure Container objects that run in a Job.
Appears in: - BackupSpec - RestoreSpec - SqlJobSpec
Field Description Default Validation podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod."},{"location":"API_REFERENCE/#kubernetesauth","title":"KubernetesAuth","text":"KubernetesAuth refers to the Kubernetes authentication mechanism utilized for establishing a connection from the operator to the agent. The agent validates the legitimacy of the service account token provided as an Authorization header by creating a TokenReview resource.
Appears in: - GaleraAgent
Field Description Default Validation enabled boolean Enabled is a flag to enable KubernetesAuth authDelegatorRoleName string AuthDelegatorRoleName is the name of the ClusterRoleBinding that is associated with the \"system:auth-delegator\" ClusterRole.It is necessary for creating TokenReview objects in order for the agent to validate the service account token."},{"location":"API_REFERENCE/#mariadb","title":"MariaDB","text":"MariaDB is the Schema for the mariadbs API. It is used to define MariaDB clusters.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string MariaDB metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec MariaDBSpec"},{"location":"API_REFERENCE/#mariadbmaxscalespec","title":"MariaDBMaxScaleSpec","text":"MariaDBMaxScaleSpec defines a reduced version of MaxScale to be used with the current MariaDB.
Appears in: - MariaDBSpec
Field Description Default Validation enabled boolean Enabled is a flag to enable a MaxScale instance to be used with the current MariaDB. image string Image name to be used by the MaxScale instances. The supported format is <image>:<tag>.Only MariaDB official images are supported. imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] services MaxScaleService array Services define how the traffic is forwarded to the MariaDB servers. monitor MaxScaleMonitor Monitor monitors MariaDB server instances. admin MaxScaleAdmin Admin configures the admin REST API and GUI. config MaxScaleConfig Config defines the MaxScale configuration. auth MaxScaleAuth Auth defines the credentials required for MaxScale to connect to MariaDB. metrics MaxScaleMetrics Metrics configures metrics and how to scrape them. connection ConnectionTemplate Connection provides a template to define the Connection for MaxScale. replicas integer Replicas indicates the number of desired instances. podDisruptionBudget PodDisruptionBudget PodDisruptionBudget defines the budget for replica availability. updateStrategy StatefulSetUpdateStrategy UpdateStrategy defines the update strategy for the StatefulSet object. kubernetesService ServiceTemplate KubernetesService defines a template for a Kubernetes Service object to connect to MaxScale. guiKubernetesService ServiceTemplate GuiKubernetesService define a template for a Kubernetes Service object to connect to MaxScale's GUI. requeueInterval Duration RequeueInterval is used to perform requeue reconciliations."},{"location":"API_REFERENCE/#mariadbref","title":"MariaDBRef","text":"MariaDBRef is a reference to a MariaDB object.
Appears in: - BackupSpec - ConnectionSpec - DatabaseSpec - GrantSpec - MaxScaleSpec - RestoreSpec - SqlJobSpec - UserSpec
Field Description Default Validation waitForIt boolean WaitForIt indicates whether the controller using this reference should wait for MariaDB to be ready. true"},{"location":"API_REFERENCE/#mariadbspec","title":"MariaDBSpec","text":"MariaDBSpec defines the desired state of MariaDB
Appears in: - MariaDB
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. initContainers Container array InitContainers to be used in the Pod. sidecarContainers Container array SidecarContainers to be used in the Pod. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. volumes Volume array Volumes to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints to be used in the Pod. suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false image string Image name to be used by the MariaDB instances. The supported format is <image>:<tag>.Only MariaDB official images are supported. imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources. rootPasswordSecretKeyRef GeneratedSecretKeyRef RootPasswordSecretKeyRef is a reference to a Secret key containing the root password. rootEmptyPassword boolean RootEmptyPassword indicates if the root password should be empty. Don't use this feature in production, it is only intended for development and test environments. database string Database is the name of the initial Database. username string Username is the initial username to be created by the operator once MariaDB is ready. It has all privileges on the initial database.The initial User will have ALL PRIVILEGES in the initial Database. passwordSecretKeyRef GeneratedSecretKeyRef PasswordSecretKeyRef is a reference to a Secret that contains the password to be used by the initial User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. passwordHashSecretKeyRef SecretKeySelector PasswordHashSecretKeyRef is a reference to the password hash to be used by the initial User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password hash. passwordPlugin PasswordPlugin PasswordPlugin is a reference to the password plugin and arguments to be used by the initial User. myCnf string MyCnf allows to specify the my.cnf file mounted by Mariadb.Updating this field will trigger an update to the Mariadb resource. myCnfConfigMapKeyRef ConfigMapKeySelector MyCnfConfigMapKeyRef is a reference to the my.cnf config file provided via a ConfigMap.If not provided, it will be defaulted with a reference to a ConfigMap containing the MyCnf field.If the referred ConfigMap is labeled with \"k8s.mariadb.com/watch\", an update to the Mariadb resource will be triggered when the ConfigMap is updated. timeZone string TimeZone sets the default timezone. If not provided, it defaults to SYSTEM and the timezone data is not loaded. bootstrapFrom BootstrapFrom BootstrapFrom defines a source to bootstrap from. storage Storage Storage defines the storage options to be used for provisioning the PVCs mounted by MariaDB. metrics MariadbMetrics Metrics configures metrics and how to scrape them. replication Replication Replication configures high availability via replication. This feature is still in alpha, use Galera if you are looking for a more production-ready HA. galera Galera Replication configures high availability via Galera. maxScaleRef ObjectReference MaxScaleRef is a reference to a MaxScale resource to be used with the current MariaDB.Providing this field implies delegating high availability tasks such as primary failover to MaxScale. maxScale MariaDBMaxScaleSpec MaxScale is the MaxScale specification that defines the MaxScale resource to be used with the current MariaDB.When enabling this field, MaxScaleRef is automatically set. replicas integer Replicas indicates the number of desired instances. 1 replicasAllowEvenNumber boolean disables the validation check for an odd number of replicas. false port integer Port where the instances will be listening for connections. 3306 podDisruptionBudget PodDisruptionBudget PodDisruptionBudget defines the budget for replica availability. updateStrategy UpdateStrategy UpdateStrategy defines how a MariaDB resource is updated. service ServiceTemplate Service defines a template to configure the general Service object.The network traffic of this Service will be routed to all Pods. connection ConnectionTemplate Connection defines a template to configure the general Connection object.This Connection provides the initial User access to the initial Database.It will make use of the Service to route network traffic to all Pods. primaryService ServiceTemplate PrimaryService defines a template to configure the primary Service object.The network traffic of this Service will be routed to the primary Pod. primaryConnection ConnectionTemplate PrimaryConnection defines a template to configure the primary Connection object.This Connection provides the initial User access to the initial Database.It will make use of the PrimaryService to route network traffic to the primary Pod. secondaryService ServiceTemplate SecondaryService defines a template to configure the secondary Service object.The network traffic of this Service will be routed to the secondary Pods. secondaryConnection ConnectionTemplate SecondaryConnection defines a template to configure the secondary Connection object.This Connection provides the initial User access to the initial Database.It will make use of the SecondaryService to route network traffic to the secondary Pods."},{"location":"API_REFERENCE/#mariadbmetrics","title":"MariadbMetrics","text":"MariadbMetrics defines the metrics for a MariaDB.
Appears in: - MariaDBSpec
Field Description Default Validation enabled boolean Enabled is a flag to enable Metrics exporter Exporter Exporter defines the metrics exporter container. serviceMonitor ServiceMonitor ServiceMonitor defines the ServiceMonior object. username string Username is the username of the monitoring user used by the exporter. passwordSecretKeyRef GeneratedSecretKeyRef PasswordSecretKeyRef is a reference to the password of the monitoring user used by the exporter.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password."},{"location":"API_REFERENCE/#maxscale","title":"MaxScale","text":"MaxScale is the Schema for the maxscales API. It is used to define MaxScale clusters.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string MaxScale metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec MaxScaleSpec"},{"location":"API_REFERENCE/#maxscaleadmin","title":"MaxScaleAdmin","text":"MaxScaleAdmin configures the admin REST API and GUI.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation port integer Port where the admin REST API and GUI will be exposed. guiEnabled boolean GuiEnabled indicates whether the admin GUI should be enabled."},{"location":"API_REFERENCE/#maxscaleauth","title":"MaxScaleAuth","text":"MaxScaleAuth defines the credentials required for MaxScale to connect to MariaDB.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation generate boolean Generate defies whether the operator should generate users and grants for MaxScale to work.It only supports MariaDBs specified via spec.mariaDbRef. adminUsername string AdminUsername is an admin username to call the admin REST API. It is defaulted if not provided. adminPasswordSecretKeyRef GeneratedSecretKeyRef AdminPasswordSecretKeyRef is Secret key reference to the admin password to call the admin REST API. It is defaulted if not provided. deleteDefaultAdmin boolean DeleteDefaultAdmin determines whether the default admin user should be deleted after the initial configuration. If not provided, it defaults to true. metricsUsername string MetricsUsername is an metrics username to call the REST API. It is defaulted if metrics are enabled. metricsPasswordSecretKeyRef GeneratedSecretKeyRef MetricsPasswordSecretKeyRef is Secret key reference to the metrics password to call the admib REST API. It is defaulted if metrics are enabled.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. clientUsername string ClientUsername is the user to connect to MaxScale. It is defaulted if not provided. clientPasswordSecretKeyRef GeneratedSecretKeyRef ClientPasswordSecretKeyRef is Secret key reference to the password to connect to MaxScale. It is defaulted if not provided.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. clientMaxConnections integer ClientMaxConnections defines the maximum number of connections that the client can establish.If HA is enabled, make sure to increase this value, as more MaxScale replicas implies more connections.It defaults to 30 times the number of MaxScale replicas. serverUsername string ServerUsername is the user used by MaxScale to connect to MariaDB server. It is defaulted if not provided. serverPasswordSecretKeyRef GeneratedSecretKeyRef ServerPasswordSecretKeyRef is Secret key reference to the password used by MaxScale to connect to MariaDB server. It is defaulted if not provided.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. serverMaxConnections integer ServerMaxConnections defines the maximum number of connections that the server can establish.If HA is enabled, make sure to increase this value, as more MaxScale replicas implies more connections.It defaults to 30 times the number of MaxScale replicas. monitorUsername string MonitorUsername is the user used by MaxScale monitor to connect to MariaDB server. It is defaulted if not provided. monitorPasswordSecretKeyRef GeneratedSecretKeyRef MonitorPasswordSecretKeyRef is Secret key reference to the password used by MaxScale monitor to connect to MariaDB server. It is defaulted if not provided.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. monitorMaxConnections integer MonitorMaxConnections defines the maximum number of connections that the monitor can establish.If HA is enabled, make sure to increase this value, as more MaxScale replicas implies more connections.It defaults to 30 times the number of MaxScale replicas. syncUsername string MonitoSyncUsernamerUsername is the user used by MaxScale config sync to connect to MariaDB server. It is defaulted when HA is enabled. syncPasswordSecretKeyRef GeneratedSecretKeyRef SyncPasswordSecretKeyRef is Secret key reference to the password used by MaxScale config to connect to MariaDB server. It is defaulted when HA is enabled.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. syncMaxConnections integer SyncMaxConnections defines the maximum number of connections that the sync can establish.If HA is enabled, make sure to increase this value, as more MaxScale replicas implies more connections.It defaults to 30 times the number of MaxScale replicas."},{"location":"API_REFERENCE/#maxscaleconfig","title":"MaxScaleConfig","text":"MaxScaleConfig defines the MaxScale configuration.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation params object (keys:string, values:string) Params is a key value pair of parameters to be used in the MaxScale static configuration file.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-maxscale-configuration-guide/#global-settings. volumeClaimTemplate VolumeClaimTemplate VolumeClaimTemplate provides a template to define the PVCs for storing MaxScale runtime configuration files. It is defaulted if not provided. sync MaxScaleConfigSync Sync defines how to replicate configuration across MaxScale replicas. It is defaulted when HA is enabled."},{"location":"API_REFERENCE/#maxscaleconfigsync","title":"MaxScaleConfigSync","text":"MaxScaleConfigSync defines how the config changes are replicated across replicas.
Appears in: - MaxScaleConfig
Field Description Default Validation database string Database is the MariaDB logical database where the 'maxscale_config' table will be created in order to persist and synchronize config changes. If not provided, it defaults to 'mysql'. interval Duration Interval defines the config synchronization interval. It is defaulted if not provided. timeout Duration Interval defines the config synchronization timeout. It is defaulted if not provided."},{"location":"API_REFERENCE/#maxscalelistener","title":"MaxScaleListener","text":"MaxScaleListener defines how the MaxScale server will listen for connections.
Appears in: - MaxScaleService
Field Description Default Validation suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false name string Name is the identifier of the listener. It is defaulted if not provided port integer Port is the network port where the MaxScale server will listen. Required: {} protocol string Protocol is the MaxScale protocol to use when communicating with the client. If not provided, it defaults to MariaDBProtocol. params object (keys:string, values:string) Params defines extra parameters to pass to the listener.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-maxscale-configuration-guide/#listener_1."},{"location":"API_REFERENCE/#maxscalemetrics","title":"MaxScaleMetrics","text":"MaxScaleMetrics defines the metrics for a Maxscale.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation enabled boolean Enabled is a flag to enable Metrics exporter Exporter Exporter defines the metrics exporter container. serviceMonitor ServiceMonitor ServiceMonitor defines the ServiceMonior object."},{"location":"API_REFERENCE/#maxscalemonitor","title":"MaxScaleMonitor","text":"MaxScaleMonitor monitors MariaDB server instances
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false name string Name is the identifier of the monitor. It is defaulted if not provided. module MonitorModule Module is the module to use to monitor MariaDB servers. It is mandatory when no MariaDB reference is provided. interval Duration Interval used to monitor MariaDB servers. It is defaulted if not provided. cooperativeMonitoring CooperativeMonitoring CooperativeMonitoring enables coordination between multiple MaxScale instances running monitors. It is defaulted when HA is enabled. Enum: [majority_of_all majority_of_running] params object (keys:string, values:string) Params defines extra parameters to pass to the monitor.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-common-monitor-parameters/.Monitor specific parameter are also suported:https://mariadb.com/kb/en/mariadb-maxscale-2308-galera-monitor/#galera-monitor-optional-parameters.https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-monitor/#configuration."},{"location":"API_REFERENCE/#maxscaleserver","title":"MaxScaleServer","text":"MaxScaleServer defines a MariaDB server to forward traffic to.
Appears in: - MaxScaleSpec
Field Description Default Validation name string Name is the identifier of the MariaDB server. Required: {} address string Address is the network address of the MariaDB server. Required: {} port integer Port is the network port of the MariaDB server. If not provided, it defaults to 3306. protocol string Protocol is the MaxScale protocol to use when communicating with this MariaDB server. If not provided, it defaults to MariaDBBackend. maintenance boolean Maintenance indicates whether the server is in maintenance mode. params object (keys:string, values:string) Params defines extra parameters to pass to the server.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-maxscale-configuration-guide/#server_1."},{"location":"API_REFERENCE/#maxscaleservice","title":"MaxScaleService","text":"Services define how the traffic is forwarded to the MariaDB servers.
Appears in: - MariaDBMaxScaleSpec - MaxScaleSpec
Field Description Default Validation suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false name string Name is the identifier of the MaxScale service. Required: {} router ServiceRouter Router is the type of router to use. Enum: [readwritesplit readconnroute] Required: {} listener MaxScaleListener MaxScaleListener defines how the MaxScale server will listen for connections. Required: {} params object (keys:string, values:string) Params defines extra parameters to pass to the service.Any parameter supported by MaxScale may be specified here. See reference:https://mariadb.com/kb/en/mariadb-maxscale-2308-mariadb-maxscale-configuration-guide/#service_1.Router specific parameter are also suported:https://mariadb.com/kb/en/mariadb-maxscale-2308-readwritesplit/#configuration.https://mariadb.com/kb/en/mariadb-maxscale-2308-readconnroute/#configuration."},{"location":"API_REFERENCE/#maxscalespec","title":"MaxScaleSpec","text":"MaxScaleSpec defines the desired state of MaxScale.
Appears in: - MaxScale
Field Description Default Validation command string array Command to be used in the Container. args string array Args to be used in the Container. env EnvVar array Env represents the environment variables to be injected in a container. envFrom EnvFromSource array EnvFrom represents the references (via ConfigMap and Secrets) to environment variables to be injected in the container. volumeMounts VolumeMount array VolumeMounts to be used in the Container. livenessProbe Probe LivenessProbe to be used in the Container. readinessProbe Probe ReadinessProbe to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. initContainers Container array InitContainers to be used in the Pod. sidecarContainers Container array SidecarContainers to be used in the Pod. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. volumes Volume array Volumes to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints to be used in the Pod. suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false mariaDbRef MariaDBRef MariaDBRef is a reference to the MariaDB that MaxScale points to. It is used to initialize the servers field. servers MaxScaleServer array Servers are the MariaDB servers to forward traffic to. It is required if 'spec.mariaDbRef' is not provided. image string Image name to be used by the MaxScale instances. The supported format is <image>:<tag>.Only MaxScale official images are supported. imagePullPolicy PullPolicy ImagePullPolicy is the image pull policy. One of Always, Never or IfNotPresent. If not defined, it defaults to IfNotPresent. Enum: [Always Never IfNotPresent] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources. services MaxScaleService array Services define how the traffic is forwarded to the MariaDB servers. It is defaulted if not provided. monitor MaxScaleMonitor Monitor monitors MariaDB server instances. It is required if 'spec.mariaDbRef' is not provided. admin MaxScaleAdmin Admin configures the admin REST API and GUI. config MaxScaleConfig Config defines the MaxScale configuration. auth MaxScaleAuth Auth defines the credentials required for MaxScale to connect to MariaDB. metrics MaxScaleMetrics Metrics configures metrics and how to scrape them. connection ConnectionTemplate Connection provides a template to define the Connection for MaxScale. replicas integer Replicas indicates the number of desired instances. 1 podDisruptionBudget PodDisruptionBudget PodDisruptionBudget defines the budget for replica availability. updateStrategy StatefulSetUpdateStrategy UpdateStrategy defines the update strategy for the StatefulSet object. kubernetesService ServiceTemplate KubernetesService defines a template for a Kubernetes Service object to connect to MaxScale. guiKubernetesService ServiceTemplate GuiKubernetesService defines a template for a Kubernetes Service object to connect to MaxScale's GUI. requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. If not defined, it defaults to 10s."},{"location":"API_REFERENCE/#metadata","title":"Metadata","text":"Metadata defines the metadata to added to resources.
Appears in: - BackupSpec - Exporter - GaleraRecoveryJob - Job - JobPodTemplate - MariaDBSpec - MaxScaleSpec - PodTemplate - RestoreSpec - SecretTemplate - ServiceTemplate - SqlJobSpec - VolumeClaimTemplate
Field Description Default Validation labels object (keys:string, values:string) Labels to be added to children resources. annotations object (keys:string, values:string) Annotations to be added to children resources."},{"location":"API_REFERENCE/#monitormodule","title":"MonitorModule","text":"Underlying type: string
MonitorModule defines the type of monitor module
Appears in: - MaxScaleMonitor
Field Description mariadbmon MonitorModuleMariadb is a monitor to be used with MariaDB servers. galeramon MonitorModuleGalera is a monitor to be used with Galera servers."},{"location":"API_REFERENCE/#passwordplugin","title":"PasswordPlugin","text":"PasswordPlugin defines the password plugin and its arguments.
Appears in: - MariaDBSpec - UserSpec
Field Description Default Validation pluginNameSecretKeyRef SecretKeySelector PluginNameSecretKeyRef is a reference to the authentication plugin to be used by the User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the authentication plugin. pluginArgSecretKeyRef SecretKeySelector PluginArgSecretKeyRef is a reference to the arguments to be provided to the authentication plugin for the User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the authentication plugin arguments."},{"location":"API_REFERENCE/#poddisruptionbudget","title":"PodDisruptionBudget","text":"PodDisruptionBudget is the Pod availability bundget for a MariaDB
Appears in: - MariaDBMaxScaleSpec - MariaDBSpec - MaxScaleSpec
Field Description Default Validation minAvailable IntOrString MinAvailable defines the number of minimum available Pods. maxUnavailable IntOrString MaxUnavailable defines the number of maximum unavailable Pods."},{"location":"API_REFERENCE/#podtemplate","title":"PodTemplate","text":"PodTemplate defines a template to configure Container objects.
Appears in: - Exporter - MariaDBSpec - MaxScaleSpec
Field Description Default Validation podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. initContainers Container array InitContainers to be used in the Pod. sidecarContainers Container array SidecarContainers to be used in the Pod. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. volumes Volume array Volumes to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. topologySpreadConstraints TopologySpreadConstraint array TopologySpreadConstraints to be used in the Pod."},{"location":"API_REFERENCE/#primarygalera","title":"PrimaryGalera","text":"PrimaryGalera is the Galera configuration for the primary node.
Appears in: - Galera - GaleraSpec
Field Description Default Validation podIndex integer PodIndex is the StatefulSet index of the primary node. The user may change this field to perform a manual switchover. automaticFailover boolean AutomaticFailover indicates whether the operator should automatically update PodIndex to perform an automatic primary failover."},{"location":"API_REFERENCE/#primaryreplication","title":"PrimaryReplication","text":"PrimaryReplication is the replication configuration for the primary node.
Appears in: - Replication - ReplicationSpec
Field Description Default Validation podIndex integer PodIndex is the StatefulSet index of the primary node. The user may change this field to perform a manual switchover. automaticFailover boolean AutomaticFailover indicates whether the operator should automatically update PodIndex to perform an automatic primary failover."},{"location":"API_REFERENCE/#replicareplication","title":"ReplicaReplication","text":"ReplicaReplication is the replication configuration for the replica nodes.
Appears in: - Replication - ReplicationSpec
Field Description Default Validation waitPoint WaitPoint WaitPoint defines whether the transaction should wait for ACK before committing to the storage engine.More info: https://mariadb.com/kb/en/semisynchronous-replication/#rpl_semi_sync_master_wait_point. Enum: [AfterSync AfterCommit] gtid Gtid Gtid indicates which Global Transaction ID should be used when connecting a replica to the master.See: https://mariadb.com/kb/en/gtid/#using-current_pos-vs-slave_pos. Enum: [CurrentPos SlavePos] replPasswordSecretKeyRef GeneratedSecretKeyRef ReplPasswordSecretKeyRef provides a reference to the Secret to use as password for the replication user. connectionTimeout Duration ConnectionTimeout to be used when the replica connects to the primary. connectionRetries integer ConnectionRetries to be used when the replica connects to the primary. syncTimeout Duration SyncTimeout defines the timeout for a replica to be synced with the primary when performing a primary switchover.If the timeout is reached, the replica GTID will be reset and the switchover will continue."},{"location":"API_REFERENCE/#replication","title":"Replication","text":"Replication allows you to enable single-master HA via semi-synchronours replication in your MariaDB cluster.
Appears in: - MariaDBSpec
Field Description Default Validation primary PrimaryReplication Primary is the replication configuration for the primary node. replica ReplicaReplication ReplicaReplication is the replication configuration for the replica nodes. syncBinlog boolean SyncBinlog indicates whether the binary log should be synchronized to the disk after every event.It trades off performance for consistency.See: https://mariadb.com/kb/en/replication-and-binary-log-system-variables/#sync_binlog. probesEnabled boolean ProbesEnabled indicates to use replication specific liveness and readiness probes.This probes check that the primary can receive queries and that the replica has the replication thread running. enabled boolean Enabled is a flag to enable Replication."},{"location":"API_REFERENCE/#replicationspec","title":"ReplicationSpec","text":"ReplicationSpec is the Replication desired state specification.
Appears in: - Replication
Field Description Default Validation primary PrimaryReplication Primary is the replication configuration for the primary node. replica ReplicaReplication ReplicaReplication is the replication configuration for the replica nodes. syncBinlog boolean SyncBinlog indicates whether the binary log should be synchronized to the disk after every event.It trades off performance for consistency.See: https://mariadb.com/kb/en/replication-and-binary-log-system-variables/#sync_binlog. probesEnabled boolean ProbesEnabled indicates to use replication specific liveness and readiness probes.This probes check that the primary can receive queries and that the replica has the replication thread running."},{"location":"API_REFERENCE/#restore","title":"Restore","text":"Restore is the Schema for the restores API. It is used to define restore jobs and its restoration source.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string Restore metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec RestoreSpec"},{"location":"API_REFERENCE/#restoresource","title":"RestoreSource","text":"RestoreSource defines a source for restoring a MariaDB.
Appears in: - BootstrapFrom - RestoreSpec
Field Description Default Validation backupRef LocalObjectReference BackupRef is a reference to a Backup object. It has priority over S3 and Volume. s3 S3 S3 defines the configuration to restore backups from a S3 compatible storage. It has priority over Volume. volume VolumeSource Volume is a Kubernetes Volume object that contains a backup. targetRecoveryTime Time TargetRecoveryTime is a RFC3339 (1970-01-01T00:00:00Z) date and time that defines the point in time recovery objective.It is used to determine the closest restoration source in time."},{"location":"API_REFERENCE/#restorespec","title":"RestoreSpec","text":"RestoreSpec defines the desired state of restore
Appears in: - Restore
Field Description Default Validation args string array Args to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. backupRef LocalObjectReference BackupRef is a reference to a Backup object. It has priority over S3 and Volume. s3 S3 S3 defines the configuration to restore backups from a S3 compatible storage. It has priority over Volume. volume VolumeSource Volume is a Kubernetes Volume object that contains a backup. targetRecoveryTime Time TargetRecoveryTime is a RFC3339 (1970-01-01T00:00:00Z) date and time that defines the point in time recovery objective.It is used to determine the closest restoration source in time. mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} database string Database defines the logical database to be restored. If not provided, all databases available in the backup are restored.IMPORTANT: The database must previously exist. logLevel string LogLevel to be used n the Backup Job. It defaults to 'info'. info backoffLimit integer BackoffLimit defines the maximum number of attempts to successfully perform a Backup. 5 restartPolicy RestartPolicy RestartPolicy to be added to the Backup Job. OnFailure Enum: [Always OnFailure Never] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources."},{"location":"API_REFERENCE/#s3","title":"S3","text":"Appears in: - BackupStorage - BootstrapFrom - RestoreSource - RestoreSpec
Field Description Default Validation bucket string Bucket is the name Name of the bucket to store backups. Required: {} endpoint string Endpoint is the S3 API endpoint without scheme. Required: {} region string Region is the S3 region name to use. prefix string Prefix indicates a folder/subfolder in the bucket. For example: mariadb/ or mariadb/backups. A trailing slash '/' is added if not provided. accessKeyIdSecretKeyRef SecretKeySelector AccessKeyIdSecretKeyRef is a reference to a Secret key containing the S3 access key id. Required: {} secretAccessKeySecretKeyRef SecretKeySelector AccessKeyIdSecretKeyRef is a reference to a Secret key containing the S3 secret key. Required: {} sessionTokenSecretKeyRef SecretKeySelector SessionTokenSecretKeyRef is a reference to a Secret key containing the S3 session token. tls TLS TLS provides the configuration required to establish TLS connections with S3."},{"location":"API_REFERENCE/#sqltemplate","title":"SQLTemplate","text":"SQLTemplate defines a template to customize SQL objects.
Appears in: - DatabaseSpec - GrantSpec - UserSpec
Field Description Default Validation requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. retryInterval Duration RetryInterval is the interval used to perform retries. cleanupPolicy CleanupPolicy CleanupPolicy defines the behavior for cleaning up a SQL resource. Enum: [Skip Delete]"},{"location":"API_REFERENCE/#sst","title":"SST","text":"Underlying type: string
SST is the Snapshot State Transfer used when new Pods join the cluster. More info: https://galeracluster.com/library/documentation/sst.html.
Appears in: - Galera - GaleraSpec
Field Description rsync SSTRsync is an SST based on rsync. mariabackup SSTMariaBackup is an SST based on mariabackup. It is the recommended SST. mysqldump SSTMysqldump is an SST based on mysqldump."},{"location":"API_REFERENCE/#schedule","title":"Schedule","text":"Schedule contains parameters to define a schedule
Appears in: - BackupSpec - SqlJobSpec
Field Description Default Validation cron string Cron is a cron expression that defines the schedule. Required: {} suspend boolean Suspend defines whether the schedule is active or not. false"},{"location":"API_REFERENCE/#secrettemplate","title":"SecretTemplate","text":"SecretTemplate defines a template to customize Secret objects.
Appears in: - ConnectionSpec - ConnectionTemplate
Field Description Default Validation metadata Metadata Refer to Kubernetes API documentation for fields of metadata. key string Key to be used in the Secret. format string Format to be used in the Secret. usernameKey string UsernameKey to be used in the Secret. passwordKey string PasswordKey to be used in the Secret. hostKey string HostKey to be used in the Secret. portKey string PortKey to be used in the Secret. databaseKey string DatabaseKey to be used in the Secret."},{"location":"API_REFERENCE/#servicemonitor","title":"ServiceMonitor","text":"ServiceMonitor defines a prometheus ServiceMonitor object.
Appears in: - MariadbMetrics - MaxScaleMetrics
Field Description Default Validation prometheusRelease string PrometheusRelease is the release label to add to the ServiceMonitor object. jobLabel string JobLabel to add to the ServiceMonitor object. interval string Interval for scraping metrics. scrapeTimeout string ScrapeTimeout defines the timeout for scraping metrics."},{"location":"API_REFERENCE/#servicerouter","title":"ServiceRouter","text":"Underlying type: string
ServiceRouter defines the type of service router.
Appears in: - MaxScaleService
Field Description readwritesplit ServiceRouterReadWriteSplit splits the load based on the queries. Write queries are performed on master and read queries on the replicas. readconnroute ServiceRouterReadConnRoute splits the load based on the connections. Each connection is assigned to a server."},{"location":"API_REFERENCE/#servicetemplate","title":"ServiceTemplate","text":"ServiceTemplate defines a template to customize Service objects.
Appears in: - MariaDBMaxScaleSpec - MariaDBSpec - MaxScaleSpec
Field Description Default Validation type ServiceType Type is the Service type. One of ClusterIP, NodePort or LoadBalancer. If not defined, it defaults to ClusterIP. ClusterIP Enum: [ClusterIP NodePort LoadBalancer] metadata Metadata Refer to Kubernetes API documentation for fields of metadata. loadBalancerIP string LoadBalancerIP Service field. loadBalancerSourceRanges string array LoadBalancerSourceRanges Service field. externalTrafficPolicy ServiceExternalTrafficPolicy ExternalTrafficPolicy Service field. sessionAffinity ServiceAffinity SessionAffinity Service field. allocateLoadBalancerNodePorts boolean AllocateLoadBalancerNodePorts Service field."},{"location":"API_REFERENCE/#sqljob","title":"SqlJob","text":"SqlJob is the Schema for the sqljobs API. It is used to run sql scripts as jobs.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string SqlJob metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec SqlJobSpec"},{"location":"API_REFERENCE/#sqljobspec","title":"SqlJobSpec","text":"SqlJobSpec defines the desired state of SqlJob
Appears in: - SqlJob
Field Description Default Validation args string array Args to be used in the Container. resources ResourceRequirements Resouces describes the compute resource requirements. securityContext SecurityContext SecurityContext holds security configuration that will be applied to a container. podMetadata Metadata PodMetadata defines extra metadata for the Pod. imagePullSecrets LocalObjectReference array ImagePullSecrets is the list of pull Secrets to be used to pull the image. podSecurityContext PodSecurityContext SecurityContext holds pod-level security attributes and common container settings. serviceAccountName string ServiceAccountName is the name of the ServiceAccount to be used by the Pods. affinity AffinityConfig Affinity to be used in the Pod. nodeSelector object (keys:string, values:string) NodeSelector to be used in the Pod. tolerations Toleration array Tolerations to be used in the Pod. priorityClassName string PriorityClassName to be used in the Pod. successfulJobsHistoryLimit integer Minimum: 0 failedJobsHistoryLimit integer Minimum: 0 timeZone string mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} schedule Schedule Schedule defines when the SqlJob will be executed. username string Username to be impersonated when executing the SqlJob. Required: {} passwordSecretKeyRef SecretKeySelector UserPasswordSecretKeyRef is a reference to the impersonated user's password to be used when executing the SqlJob. Required: {} database string Username to be used when executing the SqlJob. dependsOn LocalObjectReference array DependsOn defines dependencies with other SqlJob objectecs. sql string Sql is the script to be executed by the SqlJob. sqlConfigMapKeyRef ConfigMapKeySelector SqlConfigMapKeyRef is a reference to a ConfigMap containing the Sql script.It is defaulted to a ConfigMap with the contents of the Sql field. backoffLimit integer BackoffLimit defines the maximum number of attempts to successfully execute a SqlJob. 5 restartPolicy RestartPolicy RestartPolicy to be added to the SqlJob Pod. OnFailure Enum: [Always OnFailure Never] inheritMetadata Metadata InheritMetadata defines the metadata to be inherited by children resources."},{"location":"API_REFERENCE/#storage","title":"Storage","text":"Storage defines the storage options to be used for provisioning the PVCs mounted by MariaDB.
Appears in: - MariaDBSpec
Field Description Default Validation ephemeral boolean Ephemeral indicates whether to use ephemeral storage in the PVCs. It is only compatible with non HA MariaDBs. size Quantity Size of the PVCs to be mounted by MariaDB. Required if not provided in 'VolumeClaimTemplate'. It superseeds the storage size specified in 'VolumeClaimTemplate'. storageClassName string StorageClassName to be used to provision the PVCS. It superseeds the 'StorageClassName' specified in 'VolumeClaimTemplate'.If not provided, the default 'StorageClass' configured in the cluster is used. resizeInUseVolumes boolean ResizeInUseVolumes indicates whether the PVCs can be resized. The 'StorageClassName' used should have 'allowVolumeExpansion' set to 'true' to allow resizing.It defaults to true. waitForVolumeResize boolean WaitForVolumeResize indicates whether to wait for the PVCs to be resized before marking the MariaDB object as ready. This will block other operations such as cluster recovery while the resize is in progress.It defaults to true. volumeClaimTemplate VolumeClaimTemplate VolumeClaimTemplate provides a template to define the PVCs."},{"location":"API_REFERENCE/#suspendtemplate","title":"SuspendTemplate","text":"SuspendTemplate indicates whether the current resource should be suspended or not.
Appears in: - MariaDBSpec - MaxScaleListener - MaxScaleMonitor - MaxScaleService - MaxScaleSpec
Field Description Default Validation suspend boolean Suspend indicates whether the current resource should be suspended or not.This can be useful for maintenance, as disabling the reconciliation prevents the operator from interfering with user operations during maintenance activities. false"},{"location":"API_REFERENCE/#tls","title":"TLS","text":"Appears in: - S3
Field Description Default Validation enabled boolean Enabled is a flag to enable TLS. caSecretKeyRef SecretKeySelector CASecretKeyRef is a reference to a Secret key containing a CA bundle in PEM format used to establish TLS connections with S3.By default, the system trust chain will be used, but you can use this field to add more CAs to the bundle."},{"location":"API_REFERENCE/#updatestrategy","title":"UpdateStrategy","text":"UpdateStrategy defines how a MariaDB resource is updated.
Appears in: - MariaDBSpec
Field Description Default Validation type UpdateType Type defines the type of updates. One of ReplicasFirstPrimaryLast, RollingUpdate or OnDelete. If not defined, it defaults to ReplicasFirstPrimaryLast. ReplicasFirstPrimaryLast Enum: [ReplicasFirstPrimaryLast RollingUpdate OnDelete] rollingUpdate RollingUpdateStatefulSetStrategy RollingUpdate defines parameters for the RollingUpdate type."},{"location":"API_REFERENCE/#updatetype","title":"UpdateType","text":"Underlying type: string
UpdateType defines the type of update for a MariaDB resource.
Appears in: - UpdateStrategy
Field Description ReplicasFirstPrimaryLast ReplicasFirstPrimaryLast indicates that the update will be applied to all replica Pods first and later on to the primary Pod.The updates are applied one by one waiting until each Pod passes the readiness probei.e. the Pod gets synced and it is ready to receive traffic. RollingUpdate RollingUpdateUpdateType indicates that the update will be applied by the StatefulSet controller using the RollingUpdate strategy.This strategy is unaware of the roles that the Pod have (primary or replica) and it willperform the update following the StatefulSet ordinal, from higher to lower. OnDelete OnDeleteUpdateType indicates that the update will be applied by the StatefulSet controller using the OnDelete strategy.The update will be done when the Pods get manually deleted by the user."},{"location":"API_REFERENCE/#user","title":"User","text":"User is the Schema for the users API. It is used to define grants as if you were running a 'CREATE USER' statement.
Field Description Default Validation apiVersion string k8s.mariadb.com/v1alpha1 kind string User metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. spec UserSpec"},{"location":"API_REFERENCE/#userspec","title":"UserSpec","text":"UserSpec defines the desired state of User
Appears in: - User
Field Description Default Validation requeueInterval Duration RequeueInterval is used to perform requeue reconciliations. retryInterval Duration RetryInterval is the interval used to perform retries. cleanupPolicy CleanupPolicy CleanupPolicy defines the behavior for cleaning up a SQL resource. Enum: [Skip Delete] mariaDbRef MariaDBRef MariaDBRef is a reference to a MariaDB object. Required: {} passwordSecretKeyRef SecretKeySelector PasswordSecretKeyRef is a reference to the password to be used by the User.If not provided, the account will be locked and the password will expire.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password. passwordHashSecretKeyRef SecretKeySelector PasswordHashSecretKeyRef is a reference to the password hash to be used by the User.If the referred Secret is labeled with \"k8s.mariadb.com/watch\", updates may be performed to the Secret in order to update the password hash. passwordPlugin PasswordPlugin PasswordPlugin is a reference to the password plugin and arguments to be used by the User. maxUserConnections integer MaxUserConnections defines the maximum number of connections that the User can establish. 10 name string Name overrides the default name provided by metadata.name. MaxLength: 80 host string Host related to the User. MaxLength: 255"},{"location":"API_REFERENCE/#volumeclaimtemplate","title":"VolumeClaimTemplate","text":"VolumeClaimTemplate defines a template to customize PVC objects.
Appears in: - GaleraConfig - MaxScaleConfig - Storage
Field Description Default Validation metadata Metadata Refer to Kubernetes API documentation for fields of metadata."},{"location":"API_REFERENCE/#waitpoint","title":"WaitPoint","text":"Underlying type: string
WaitPoint defines whether the transaction should wait for ACK before committing to the storage engine. More info: https://mariadb.com/kb/en/semisynchronous-replication/#rpl_semi_sync_master_wait_point.
Appears in: - ReplicaReplication
Field Description AfterSync WaitPointAfterSync indicates that the primary waits for the replica ACK before committing the transaction to the storage engine.This is the default WaitPoint. It trades off performance for consistency. AfterCommit WaitPointAfterCommit indicates that the primary commits the transaction to the storage engine and waits for the replica ACK afterwards.It trades off consistency for performance."},{"location":"BACKUP/","title":"Backup and Restore","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.28
mariadb-operator allows you to declarativaly take backups by defining Backup resources and later on restore them by using their Restore counterpart. These resources get reconciled into Job/CronJob resources that automatically perform the backup/restore operations, so you don't need to manually script them.
"},{"location":"BACKUP/#table-of-contents","title":"Table of contents","text":" - Storage types
Backup CRRestore CR- Bootstrap new
MariaDB instances - Backup and restore specific databases
- Extra options
- Important considerations and limitations
- Migrating an external MariaDB to a
MariaDB running in Kubernetes - Migrating to a
MariaDB with different topology - Minio reference installation
- Reference
- Troubleshooting
"},{"location":"BACKUP/#storage-types","title":"Storage types","text":"Currently, the following storage types are supported: - S3 compatible storage: Store backups in a S3 compatible storage, such as AWS S3 or Minio. - PVCs: Use the available StorageClasses in your Kubernetes cluster to provision a PVC dedicated to store the backup files. - Kubernetes volumes: Use any of the volume types supported natively by Kubernetes.
Our recommendation is to store the backups externally in a S3 compatible storage. Minio makes this incredibly easy, take a look at our Minio reference installation to quickly spin up an instance.
"},{"location":"BACKUP/#backup-cr","title":"Backup CR","text":"You can take a one-time backup of your MariaDB instance by declaring the following resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n storage:\n persistentVolumeClaim:\n resources:\n requests:\n storage: 100Mi\n accessModes:\n - ReadWriteOnce\n
This will use the default StorageClass to provision a PVC that would hold the backup files, but ideally you should use a S3 compatible storage:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n storage:\n s3:\n bucket: backups\n prefix: mariadb\n endpoint: minio.minio.svc.cluster.local:9000\n region: us-east-1\n accessKeyIdSecretKeyRef:\n name: minio\n key: access-key-id\n secretAccessKeySecretKeyRef:\n name: minio\n key: secret-access-key\n tls:\n enabled: true\n caSecretKeyRef:\n name: minio-ca\n key: ca.crt\n
By providing the authentication details and the TLS configuration via references to Secret keys, this example will store the backups in a local Minio instance.
"},{"location":"BACKUP/#scheduling","title":"Scheduling","text":"To minimize the Recovery Point Objective (RPO) and mitigate the risk of data loss, it is recommended to perform backups regularly. You can do so by providing a spec.schedule in your Backup resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup-scheduled\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n schedule:\n cron: \"*/1 * * * *\"\n suspend: false\n
This resource gets reconciled into a CronJob that periodically takes the backups.
It is important to note that regularly scheduled Backups complement very well the target recovery time feature detailed below.
"},{"location":"BACKUP/#retention-policy","title":"Retention policy","text":"Given that the backups can consume a substantial amount of storage, it is crucial to define your retention policy by providing the spec.maxRetention field in your Backup resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup-scheduled\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n maxRetention: 720h # 30 days\n
By default, it will be set to 720h (30 days), indicating that backups older than 30 days will be automatically deleted.
"},{"location":"BACKUP/#restore-cr","title":"Restore CR","text":"You can easily restore a Backup in your MariaDB instance by creating the following resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n
This will trigger a Job that will mount the same storage as the Backup and apply the dump to your MariaDB database.
Nevertheless, the Restore resource doesn't necessarily need to specify a spec.backupRef, you can point to other storage source that contains backup files, for example a S3 bucket:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n s3:\n bucket: backups\n prefix: mariadb\n endpoint: minio.minio.svc.cluster.local:9000\n region: us-east-1\n accessKeyIdSecretKeyRef:\n name: minio\n key: access-key-id\n secretAccessKeySecretKeyRef:\n name: minio\n key: secret-access-key\n tls:\n enabled: true\n caSecretKeyRef:\n name: minio-ca\n key: ca.crt\n
"},{"location":"BACKUP/#target-recovery-time","title":"Target recovery time","text":"If you have multiple backups available, specially after configuring a scheduled Backup, the operator is able to infer which backup to restore based on the spec.targetRecoveryTime field.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n targetRecoveryTime: 2023-12-19T09:00:00Z\n
The operator will look for the closest backup available and utilize it to restore your MariaDB instance.
By default, spec.targetRecoveryTime will be set to the current time, which means that the latest available backup will be used.
"},{"location":"BACKUP/#bootstrap-new-mariadb-instances","title":"Bootstrap new MariaDB instances","text":"To minimize your Recovery Time Objective (RTO) and to switfly spin up new clusters from existing Backups, you can provide a Restore source directly in the MariaDB object via the spec.bootstrapFrom field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-from-backup\nspec:\n storage:\n size: 1Gi\n bootstrapFrom:\n backupRef:\n name: backup\n targetRecoveryTime: 2023-12-19T09:00:00Z\n
As in the Restore resource, you don't strictly need to specify a reference to a Backup, you can provide other storage types that contain backup files:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-from-backup\nspec:\n storage:\n size: 1Gi\n bootstrapFrom:\n s3:\n bucket: backups\n prefix: mariadb\n endpoint: minio.minio.svc.cluster.local:9000\n accessKeyIdSecretKeyRef:\n name: minio\n key: access-key-id\n secretAccessKeySecretKeyRef:\n name: minio\n key: secret-access-key\n tls:\n enabled: true\n caSecretKeyRef:\n name: minio-ca\n key: ca.crt\n targetRecoveryTime: 2023-12-19T09:00:00Z\n
Under the hood, the operator creates a Restore object just after the MariaDB resource becomes ready. The advantage of using spec.bootstrapFrom over a standalone Restore is that the MariaDB is bootstrap-aware and this will allow the operator to hold primary switchover/failover operations until the restoration is finished.
"},{"location":"BACKUP/#backup-and-restore-specific-databases","title":"Backup and restore specific databases","text":"By default, all the logical databases are backed up when a Backup is created, but you may also select specific databases by providing the databases field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n databases:\n - db1\n - db2\n - db3\n
When it comes to restore, all the databases available in the backup will be restored, but you may also choose a single database to be restored via the database field available in the Restore resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n databases: db1\n
There are a couple of points to consider here: - The referred database (db1 in the example) must previously exist for the Restore to succeed. - The mariadb CLI invoked by the operator under the hood only supports selecting a single database to restore via the --one-database option, restoration of multiple specific databases is not supported.
"},{"location":"BACKUP/#extra-options","title":"Extra options","text":"Not all the flags supported by mariadb-dump and mariadb have their counterpart field in the Backup and Restore CRs respectively, but you may pass extra options by using the args field. For example, setting the --verbose flag can be helpful to track the progress of backup and restore operations:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n args:\n - --verbose\n
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb\n backupRef:\n name: backup\n args:\n - --verbose\n
Refer to the mariadb-dump and mariadb CLI options in the reference section.
"},{"location":"BACKUP/#important-considerations-and-limitations","title":"Important considerations and limitations","text":""},{"location":"BACKUP/#root-credentials","title":"Root credentials","text":"When restoring a backup, the root credentials specified through the spec.rootPasswordSecretKeyRef field in the MariaDB resource must match the ones in the backup. These credentials are utilized by the liveness and readiness probes, and if they are invalid, the probes will fail, causing your MariaDB Pods to restart after the backup restoration.
"},{"location":"BACKUP/#restore-job","title":"Restore job","text":"Restoring large backups can consume significant compute resources and may cause Restore Jobs to become stuck due to insufficient resources. To prevent this, you can define the compute resources allocated to the Job:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n storage:\n size: 1Gi\n bootstrapFrom:\n restoreJob:\n args:\n - --verbose\n resources:\n requests:\n cpu: 100m\n memory: 128Mi\n limits:\n memory: 1Gi\n
"},{"location":"BACKUP/#galera-backup-limitations","title":"Galera backup limitations","text":""},{"location":"BACKUP/#mysqlglobal_priv","title":"mysql.global_priv","text":"Galera only replicates the tables with InnoDB engine: - https://galeracluster.com/library/kb/user-changes.html
Something that does not include mysql.global_priv, the table used to store users and grants, which uses the MyISAM engine. This basically means that a Galera instance with mysql.global_priv populated will not replicate this data to an empty Galera instance. However, DDL statements (CREATE USER, ALTER USER ...) will be replicated.
Taking this into account, if we think now about a restore scenario where: - The backup file includes a DROP TABLE statement for the mysql.global_priv table. - The backup has some INSERT statements for the mysql.global_priv table. - The Galera cluster has 3 nodes: galera-0, galera-1 and galera-2. - The backup is restored in galera-0.
This is what will happen under the scenes while restoring the backup: - The DROP TABLE statement is a DDL so it will be executed in galera-0, galera-1 and galera-2. - The INSERT statements are not DDLs, so they will only be applied to galera-0. - This results in the galera-1 and galera-2 not having the mysql.global_priv table.
After the backup is fully restored, the liveness and readiness probes will kick in, they will succeed in galera-0, but they will fail in galera-1 and galera-2, as they rely in the root credentials available in mysql.global_priv, resulting in the galera-1 and galera-2 getting restarted.
To address this issue, when backing up MariaDB instances with Galera enabled, the mysql.global_priv table will be excluded from backups by using the --ignore-table option with mariadb-dump. This prevents the replication of the DROP TABLE statement for the mysql.global_priv table. You can opt-out from this feature by setting spec.ignoreGlobalPriv=false in the Backup resource.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb\n ignoreGlobalPriv: false\n
Also, to avoid situations where mysql.global_priv is unreplicated, all the entries in that table must be managed via DDLs. This is the recommended approach suggested in the Galera docs. There are a couple of ways that we can guarantee this: - Use the rootPasswordSecretKeyRef, username and passwordSecretKeyRef fields of the MariaDB CR to create the root and initial user respectively. This fields will be translated into DDLs by the image entrypoint. - Rely on the User and Grant CRs to create additional users and grants. They will be translated into DDL statements (CREATE USER, GRANT) by the operator.
"},{"location":"BACKUP/#lock-tables","title":"LOCK TABLES","text":"Galera is not compatible with the LOCK TABLES statement: - https://mariadb.com/kb/en/lock-tables/#limitations
For this reason, the operator automatically adds the --skip-add-locks option to the Backup to overcome this limitation.
"},{"location":"BACKUP/#migrating-an-external-mariadb-to-a-mariadb-running-in-kubernetes","title":"Migrating an external MariaDB to a MariaDB running in Kubernetes","text":"You can leverage logical backups to bring your external MariaDB data into a new MariaDB instance running in Kubernetes. Follow this runbook for doing so:
- Take a logical backup of your external MariaDB using one of the commands below:
mariadb-dump --user=${MARIADB_USER} --password=${MARIADB_PASSWORD --host=${MARIADB_HOST} --single-transaction --events --routines --all-databases > backup.2024-08-26T12:24:34Z.sql\n
[!IMPORTANT] If you are using Galera or planning to migrate to a Galera instance, make sure you understand the Galera backup limitations and use the following command instead:
mariadb-dump --user=${MARIADB_USER} --password=${MARIADB_PASSWORD --host=${MARIADB_HOST} --single-transaction --events --routines --all-databases --skip-add-locks --ignore-table=mysql.global_priv > backup.2024-08-26T12:24:34Z.sql\n
-
Ensure that your backup file is named in the following format: backup.2024-08-26T12:24:34Z.sql. If the file name does not follow this format, it will be ignored by the operator.
-
Upload the backup file to one of the supported storage types. We recommend using S3.
-
Create your MariaDB resource declaring that you want to bootstrap from the previous backup and providing a root password Secret that matches the backup:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n rootPasswordSecretKeyRef:\n name: mariadb\n key: root-password\n replicas: 3\n galera:\n enabled: true\n storage:\n size: 1Gi\n bootstrapFrom:\n s3:\n bucket: backups\n prefix: mariadb\n endpoint: minio.minio.svc.cluster.local:9000\n accessKeyIdSecretKeyRef:\n name: minio\n key: access-key-id\n secretAccessKeySecretKeyRef:\n name: minio\n key: secret-access-key\n tls:\n enabled: true\n caSecretKeyRef:\n name: minio-ca\n key: ca.crt\n targetRecoveryTime: 2024-08-26T12:24:34Z\n
- If you are using Galera in your new instance, migrate your previous users and grants to use the
User and Grant CRs.
"},{"location":"BACKUP/#migrating-to-a-mariadb-with-different-topology","title":"Migrating to a MariaDB with different topology","text":"Logical backups serve not just as a source of restoration, but also enable data mobility between MariaDB instances. These backups are called \"logical\" because they are independent from the MariaDB topology, as they only contain DDLs and INSERT statements to populate data.
Although backing up and restoring data from MariaDBs with different topologies is possible, there are a couple of technical details that you need to be aware of in the following scenarios:
"},{"location":"BACKUP/#migrating-between-standalone-and-replicated-mariadbs","title":"Migrating between standalone and replicated MariaDBs","text":"This should be fully compatible, no issues have been detected.
"},{"location":"BACKUP/#migrating-from-standalonereplicated-to-galera-mariadbs","title":"Migrating from standalone/replicated to Galera MariaDBs","text":"There are a couple of limitations regarding the backups in Galera, please make sure you read the Galera backup limitations section before proceeding.
To overcome this limitations, the Backup in the standalone/replicated instance needs to be taken with spec.ignoreGlobalPriv=true. In the following example, we are backing up a standalone MariaDB (single instance):
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup-standalone\nspec:\n mariaDbRef:\n name: mariadb-standalone\n ignoreGlobalPriv: true\n
Once the previous Backup is completed, we will be able bootstrap a new Galera instance from it:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n replicas: 3\n galera:\n enabled: true\n storage:\n size: 1Gi\n bootstrapFrom:\n backupRef:\n name: backup-standalone\n
"},{"location":"BACKUP/#minio-reference-installation","title":"Minio reference installation","text":"The easiest way to get a S3 compatible storage is Minio. You can install it by using their helm chart, or, if you are looking for a production-grade deployment, take a look at their operator.
In our case, we have have configured a Minio instance for development purposes, you can easily install it by running:
make cluster\nmake install-minio\nmake net # to access the console via a MetalLB LoadBalancer: https://minio-console:9001\n
As an alternative, you can also use play.min.io using these credentials.
"},{"location":"BACKUP/#reference","title":"Reference","text":" - API reference
- Example suite
mariadb-dump optionsmariadb options
"},{"location":"BACKUP/#troubleshooting","title":"Troubleshooting","text":""},{"location":"BACKUP/#galera-pods-restarting-after-bootstrapping-from-a-backup","title":"Galera Pods restarting after bootstrapping from a backup","text":"Please make sure you understand the Galera backup limitations.
After doing so, ensure that your backup does not contain a DROP TABLE mysql.global_priv; statement, as it will make your liveness and readiness probes to fail after the backup restoration.
"},{"location":"CONFIGURATION/","title":"Configuration","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.28
This documentation aims to provide guidance on various configuration aspects across many mariadb-operator CRs.
"},{"location":"CONFIGURATION/#table-of-contents","title":"Table of contents","text":" - my.cnf
- Passwords
- External resources
- Probes
"},{"location":"CONFIGURATION/#mycnf","title":"my.cnf","text":"An inline configuration file (my.cnf) can be provisioned in the MariaDB resource via the myCnf field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n myCnf: |\n [mariadb]\n bind-address=*\n default_storage_engine=InnoDB\n binlog_format=row\n innodb_autoinc_lock_mode=2\n innodb_buffer_pool_size=1024M\n max_allowed_packet=256M \n
In this field, you may provide any configuration option or system variable supported by MariaDB.
Under the hood, the operator automatically creates a ConfigMap with the contents of the myCnf field, which will be mounted in the MariaDB instance. Alternatively, you can manage your own configuration using a pre-existing ConfigMap by linking it via myCnfConfigMapKeyRef:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n myCnfConfigMapKeyRef:\n name: mariadb\n key: mycnf\n
To ensure your configuration changes take effect, the operator triggers a rolling update whenever the myCnf field or a ConfigMap is updated. For the operator to detect changes in a ConfigMap, it must be labeled with k8s.mariadb.com/watch. Refer to the external resources section for further detail.
"},{"location":"CONFIGURATION/#passwords","title":"Passwords","text":"Some CRs require passwords provided as Secret references to function properly. For instance, the root password for a MariaDB resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n rootPasswordSecretKeyRef:\n name: mariadb\n key: root-password\n
By default, fields like rootPasswordSecretKeyRef are optional and defaulted by the operator, resulting in random password generation if not provided:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n rootPasswordSecretKeyRef:\n name: mariadb\n key: root-password\n generate: true\n
You may choose to explicitly provide a Secret reference via rootPasswordSecretKeyRef and opt-out from random password generation by either not providing the generate field or setting it to false:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n rootPasswordSecretKeyRef:\n name: mariadb\n key: root-password\n generate: false\n
This way, we are telling the operator that we are expecting a Secret to be available eventually, enabling the use of GitOps tools to seed the password: - sealed-secrets: The Secret is reconciled from a SealedSecret, which is decrypted by the sealed-secrets controller. - external-secrets: The Secret is reconciled fom an ExternalSecret, which is read by the external-secrets controller from an external secrets source (Vault, AWS Secrets Manager ...).
"},{"location":"CONFIGURATION/#external-resources","title":"External resources","text":"Many CRs have a references to external resources (i.e. ConfigMap, Secret) not managed by the operator.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n myCnfConfigMapKeyRef:\n name: mariadb\n key: mycnf\n
These external resources should be labeled with k8s.mariadb.com/watch so the operator can watch them and perform reconciliations based on their changes. For example, see the my.cnf ConfigMap:
apiVersion: v1\nkind: ConfigMap\nmetadata:\n name: mariadb\n labels:\n k8s.mariadb.com/watch: \"\"\ndata:\n my.cnf: |\n [mariadb]\n bind-address=*\n default_storage_engine=InnoDB\n binlog_format=row\n innodb_autoinc_lock_mode=2\n innodb_buffer_pool_size=1024M\n max_allowed_packet=256M\n
"},{"location":"CONFIGURATION/#probes","title":"Probes","text":"Kubernetes probes serve as an inversion of control mechanism, enabling the application to communicate its health status to Kubernetes. This enables Kubernetes to take appropriate actions when the application is unhealthy, such as restarting or stop sending traffic to Pods.
[!IMPORTANT] Make sure you check the Kubernetes documentation if you are unfamiliar with Kubernetes probes.
Fine tunning of probes for databases running in Kubernetes is critical, you may do so by tweaking the following fields:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n livenessProbe:\n initialDelaySeconds: 20\n periodSeconds: 5\n timeoutSeconds: 5\n\n readinessProbe:\n initialDelaySeconds: 20\n periodSeconds: 5\n timeoutSeconds: 5\n
There isn't an universally correct default value for these thresholds, so we recommend determining your own based on factors like the compute resources, network, storage, and other aspects of the environment where your MariaDB and MaxScale instances are running.
"},{"location":"DEVELOPMENT/","title":"Development guide","text":"In this guide, we will be configuring a local environment to run mariadb-operator so you can develop and test features without hassle. The local mariadb-operator will be able to resolve DNS and connect to MariaDB as if it was running inside a Kubernetes cluster.
"},{"location":"DEVELOPMENT/#table-of-contents","title":"Table of contents","text":" - Flavours
- Getting started
- Cluster
- Network
- Dependencies
- Generate
- Install
- Build
- Run
- Test
"},{"location":"DEVELOPMENT/#flavours","title":"Flavours","text":""},{"location":"DEVELOPMENT/#devcontainer","title":"devcontainer","text":"Spin up a devcontainer with everything you need to develop. This can be used in conjunction with many tools, such as vscode, GitHub codespaces and DevPod, which will automatically detect the devcontainer.json.
The only dependency you need is docker in case that choose to run your devcontainer locally.
"},{"location":"DEVELOPMENT/#local","title":"local","text":"Run the operator locally in your machine using go run. It requires the following dependencies: - make - go - docker
This flavour uses KIND and MetalLB under the hood to provision Kubernetes clusters and assign local IPs to LoadBalancer Services. It has some limitations in Mac and Windows which will make the operator unable to connect to MariaDB via the LoadBalancer Service, leading to errors when reconciling SQL-related resources. Alternatively, use the devcontainer flavour.
"},{"location":"DEVELOPMENT/#getting-started","title":"Getting started","text":"After having decided which flavour to use and install the required dependencies, you will be able to use the Makefile targets we provide. For convenience, every development action has an associated Makefile target. You can list all of them by running make:
make\n\nUsage:\n make <target>\n\nGeneral\n help Display this help.\n\n...\n\nInstall\n install-crds Install CRDs.\n uninstall-crds Uninstall CRDs.\n install Install CRDs and dependencies for local development.\n install-samples Install sample configuration.\n serviceaccount Create long-lived ServiceAccount token for development.\n\nDev\n certs Generates development certificates.\n lint Lint.\n build Build binary.\n test Run tests.\n cover Run tests and generate coverage.\n release Test release locally.\n\nOperator\n run Run a controller from your host. \n\n...\n
"},{"location":"DEVELOPMENT/#cluster","title":"Cluster","text":"To start with, you will need a Kubernetes cluster for developing locally. You can provision a KIND cluster by using the following target:
make cluster\n
To decommission the cluster:
make cluster-delete\n
"},{"location":"DEVELOPMENT/#network","title":"Network","text":"You can configure the network connectivity so the operator is able to resolve DNS and address MariaDB as if it was running in-cluster:
make net\n
This connectivity leverages MetalLB to assign local IPs to the LoadBalancer Services for the operator to connect to MariaDB. For this to happen, these local IPs need to be within the docker CIDR, which can be queried using:
make cidr\n172.18.0.0/16\n
When deploying example manifests, take into account that LoadBalancer Services need to be within the docker CIDR to function properly, see: - examples/manifests/mariadb_v1alpha1_mariadb.yaml - examples/manifests/mariadb_v1alpha1_mariadb_replication.yaml - examples/manifests/mariadb_v1alpha1_mariadb_galera.yaml
"},{"location":"DEVELOPMENT/#dependencies","title":"Dependencies","text":"You might need the following third party dependencies to test certain features of mariadb-operator, to install them run:
make install-prometheus\nmake install-cert-manager\nmake install-minio\n
Some of this dependencies have ports mapped to the host (i.e. Grafana and Minio to expose the dashboard) so be sure to check the forwarded ports to access. This step requires running make net previously.
"},{"location":"DEVELOPMENT/#generate","title":"Generate","text":"This target generates code, CRDs and deployment manifests. Make sure to run this before pushing a commit, as it is required by the CI:
make gen\n
"},{"location":"DEVELOPMENT/#install","title":"Install","text":"Install CRDs and everything you need to run the operator locally:
make install\n
"},{"location":"DEVELOPMENT/#build","title":"Build","text":"Build the operator binary:
make build\n
Build the docker image and load it into KIND:
make docker-build\nmake docker-load\n
"},{"location":"DEVELOPMENT/#run","title":"Run","text":"make cluster\nmake install\nmake net\nmake run\n
"},{"location":"DEVELOPMENT/#unit-tests","title":"Unit tests","text":"make test\n
"},{"location":"DEVELOPMENT/#integration-tests","title":"Integration tests","text":"make cluster\nmake install\nmake install-minio\nmake net\nmake test-int\n
"},{"location":"DOCKER/","title":"Docker Images for MariaDB Operator","text":"The mariadb-operator uses a variety of docker images depending on how it\u2019s configured and what mix of open source or commercial software you\u2019d like to use. As only the latest version of MariaDB Community Server is supported, the community server version will increment frequently with only a best effort made to keep current with the latest release(s). Only MariaDB Enterprise Server offers support for older versions.
[!NOTE] Using Docker images other than the supported ones in this document is not recommended at this time.
Component Docker Registry Supported Tags CPU Pull Command MariaDB Community Server mariadb 11.4.3 (Used with Community Operator)11.4.3-ubi9 (Used with Enterprise Operator) amd64 arm64 ppc64le s390x docker pull docker-registry1.mariadb.com/library/mariadb:11.4.3docker pull docker-registry1.mariadb.com/library/mariadb:11.4.3-ubi9 MariaDB Enterprise Server docker.mariadb.comLogin required, click link for instructions 10.6.18-14 10.6.17-13 10.5.25-19 10.5.24-18 amd64 arm64 docker pull docker-registry.mariadb.com/enterprise-server:10.6.18-14 MariaDB MaxScale UBI mariadb/maxscale 23.08.6-ubi-1 24.02.2-ubi-1 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/maxscale:23.08.6-ubi-1 MariaDB MaxScale Rocky Linux mariadb/maxscale mariadb/maxscale:23.08.5 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/maxscale:23.08.5 MariaDB Prometheus Exporter mariadb/mariadb-prometheus-exporter v0.0.1 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/mariadb-prometheus-exporter-ubi:v0.0.1 MariaDB MaxScale prometheus exporter mariadb/maxscale-prometheus-exporter-ubi v0.0.1 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/maxscale-prometheus-exporter-ubi:v0.0.1 Community Operator ghcr.io/mariadb-operator/mariadb-operator v0.0.30 amd64 arm64 docker pull docker-registry3.mariadb.com/mariadb-operator/mariadb-operator:v0.0.30 Enterprise Operator mariadb/mariadb-operator-enterprise v0.0.30 amd64 arm64 docker pull docker-registry2.mariadb.com/mariadb/mariadb-operator-enterprise:v0.0.30"},{"location":"GALERA/","title":"High availability via Galera","text":"The mariadb-operator provides cloud native support for provisioning and operating multi-master MariaDB clusters using Galera. This setup enables the ability to perform both read and write operations on all nodes, enhancing availability and allowing scalability across multiple nodes.
In certain circumstances, it could be the case that all the nodes of your cluster go down at the same time, something that Galera is not able to recover by itself, and it requires manual action to bring the cluster up again, as documented in the Galera documentation. Luckly enough, mariadb-operator has you covered and it encapsulates this operational expertise in the MariaDB CRD. You just need to declaratively specify spec.galera, as explained in more detail later in this guide.
To accomplish this, after the MariaDB cluster has been provisioned, mariadb-operator will regularly monitor the cluster's status to make sure it is healthy. If any issues are detected, the operator will initiate the recovery process to restore the cluster to a healthy state. During this process, the operator will set status conditions in the MariaDB and emit Events so you have a better understanding of the recovery progress and the underlying activities being performed. For example, you may want to know which Pods were out of sync to further investigate infrastructure-related issues (i.e. networking, storage...) on the nodes where these Pods were scheduled.
"},{"location":"GALERA/#table-of-contents","title":"Table of contents","text":" - Components
MariaDB configuration- Storage
- Wsrep provider
- IPv6 support
- Backup and restore
- Galera cluster recovery
- Bootstrap Galera cluster from existing PVCs
- Quickstart
- Troubleshooting
- Reference
"},{"location":"GALERA/#components","title":"Components","text":"To be able to effectively provision and recover MariaDB Galera clusters, the following components were introduced to co-operate with mariadb-operator: - init: Init container that dynamically provisions the Galera configuration file before the MariaDB container starts. Guarantees ordered deployment of Pods even if spec.podManagementPolicy = Parallel is set on the MariaDB StatefulSet, something crucial for performing the Galera recovery, as the operator needs to restart Pods independently. - agent: Sidecar agent that exposes the Galera state (grastate.dat) via HTTP and allows the operator to remotely bootstrap and recover the Galera cluster. For security reasons, it has authentication based on Kubernetes service accounts; this way only the operator is able to call the agent.
All these components are available in the ghcr.io/mariadb-operator mariadb-operator image. More preciselly, they are subcommands of the CLI shipped as binary inside the image.
"},{"location":"GALERA/#mariadb-configuration","title":"MariaDB configuration","text":"The easiest way to get a MariaDB Galera cluster up and running is setting spec.galera.enabled = true, like in this example:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n...\n replicas: 3\n\n galera:\n enabled: true\n
This relies on sensible defaults set by the operator, which may not be suitable for your Kubernetes cluster. This can be solved by overriding the defaults, as in this other example, so you have fine-grained control over the Galera configuration.
Refer to the reference section to better understand the purpose of each field.
"},{"location":"GALERA/#storage","title":"Storage","text":"By default, mariadb-operator provisions two PVCs for running Galera: - Storage PVC: Used to back the MariaDB data directory, mounted at /var/lib/mysql. - Config PVC: Where the Galera config files are located, mounted at /etc/mysql/conf.d.
However, you are also able to use just one PVC for keeping both the data and the config files:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n enabled: true\n config:\n reuseStorageVolume: true\n
"},{"location":"GALERA/#wsrep-provider","title":"Wsrep provider","text":"You are able to pass extra options to the Galera wsrep provider by using the galera.providerOptions field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n providerOptions:\n gcs.fc_limit: '64'\n
It is important to note that, the ist.recv_addr cannot be set by the user, as it is automatically configured to the Pod IP by the operator, something that an user won't be able to know beforehand.
A list of the available options can be found in the MariaDB documentation.
"},{"location":"GALERA/#ipv6-support","title":"IPv6 support","text":"If you have a Kubernetes cluster running with IPv6, the operator will automatically detect the IPv6 addresses of your Pods and it will configure several wsrep provider options to ensure that the Galera protocol runs smoothly with IPv6.
"},{"location":"GALERA/#backup-and-restore","title":"Backup and restore","text":"Please refer to the backup documentation to understand how to backup and restore Galera clusters. Specially, make sure you understand the Galera backup limitations.
"},{"location":"GALERA/#galera-cluster-recovery","title":"Galera cluster recovery","text":"mariadb-operator is able to monitor the Galera cluster and act accordinly to recover it if needed. This feature is enabled by default, but you may tune it as you need:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n enabled: true\n recovery:\n enabled: true\n minClusterSize: 1\n clusterMonitorInterval: 10s\n clusterHealthyTimeout: 30s\n clusterBootstrapTimeout: 10m\n podRecoveryTimeout: 5m\n podSyncTimeout: 5m\n
The minClusterSize field indicates the minimum cluster size (either absolut number of replicas or percentage) for the operator to consider the cluster healthy. If the cluster is unhealthy for more than the period defined in clusterHealthyTimeout (30s by default), a cluster recovery process is initiated by the operator. The process is explained in the Galera documentation and consists of the following steps:
- Recover the sequence number from the
grastate.dat on each node. - Trigger a recovery
Job to obtain the sequence numbers in case that the previous step didn't manage to. - Mark the node with highest sequence (bootstrap node) as safe to bootstrap.
- Bootstrap a new cluster in the bootstrap node.
- Restart and wait until the bootstrap node becomes ready.
- Restart the rest of the nodes one by one so they can join the new cluster.
The operator monitors the Galera cluster health periodically and performs the cluster recovery described above if needed. You are able to tune the monitoring interval via the clusterMonitorInterval field.
Refer to the reference section to better understand the purpose of each field.
"},{"location":"GALERA/#galera-recovery-job","title":"Galera recovery Job","text":"During the recovery process, a Job is triggered for each MariaDB Pod to obtain the sequence numbers. It's crucial for this Job to succeed; otherwise, the recovery process will fail. As a user, you are responsible for adjusting this Job to allocate sufficient resources and provide the necessary metadata to ensure its successful completion.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n enabled: true\n recovery:\n job:\n metadata:\n labels:\n sidecar.istio.io/inject: \"false\"\n resources:\n requests:\n cpu: 100m\n memory: 128Mi\n limits:\n memory: 256Mi\n
For example, if you're using a service mesh like Istio, it's important to add the sidecar.istio.io/inject=false label. Without this label, the Job will not complete, which would prevent the recovery process from finishing successfully.
"},{"location":"GALERA/#force-cluster-bootstrap","title":"Force cluster bootstrap","text":"[!CAUTION] Use this option only in exceptional circumstances. Not selecting the Pod with the highest sequence number may result in data loss.
[!WARNING] Ensure you unset forceClusterBootstrapInPod after completing the bootstrap to allow the operator to choose the appropriate Pod to bootstrap from in an event of cluster recovery.
You have the ability to manually select which Pod is used to bootstrap a new cluster during the recovery process by setting forceClusterBootstrapInPod:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n galera:\n enabled: true\n recovery:\n enabled: true\n forceClusterBootstrapInPod: \"mariadb-galera-0\"\n
This should only be used in exceptional circumstances: - You are absolutely certain that the chosen Pod has the highest sequence number. - The operator has not yet selected a Pod to bootstrap from.
You can verify this with the following command:
kubectl get mariadb mariadb-galera -o jsonpath=\"{.status.galeraRecovery}\" | jq\n{\n \"recovered\": {\n \"mariadb-galera-0\": {\n \"seqno\": 350454,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\"\n },\n \"mariadb-galera-1\": {\n \"seqno\": 350450,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\"\n }\n },\n \"state\": {\n \"mariadb-galera-0\": {\n \"safeToBootstrap\": false,\n \"seqno\": -1,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\",\n \"version\": \"2.1\"\n },\n \"mariadb-galera-1\": {\n \"safeToBootstrap\": false,\n \"seqno\": -1,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\",\n \"version\": \"2.1\"\n },\n \"mariadb-galera-2\": {\n \"safeToBootstrap\": false,\n \"seqno\": -1,\n \"uuid\": \"67a44ea9-63a8-11ef-98a2-2b0c0aa0a627\",\n \"version\": \"2.1\"\n }\n }\n}\n
In this case, assuming that mariadb-galera-2 sequence is lower than 350454, it should be safe to bootstrap from mariadb-galera-0.
Finally, after your cluster has been bootstrapped, remember to unset forceClusterBootstrapInPod to allow the operator to select the appropriate node for bootstrapping in the event of a cluster recovery.
"},{"location":"GALERA/#bootstrap-galera-cluster-from-existing-pvcs","title":"Bootstrap Galera cluster from existing PVCs","text":"mariadb-operator will never delete your MariaDB PVCs! Whenever you delete a MariaDB resource, the PVCs will remain intact so you could reuse them to re-provision a new cluster.
That said, Galera is unable to form a cluster from pre-existing state, it requires a cluster recovery process to identify which Pod has the highest sequence number to bootstrap a new cluster. That's exactly what the operator does: whenever a new MariaDB Galera cluster is created and previously created PVCs exist, a cluster recovery process is automatically triggered.
"},{"location":"GALERA/#quickstart","title":"Quickstart","text":"First of all, install the following configuration manifests that will be referenced by the CRDs further:
kubectl apply -f examples/manifests/config\n
Next, you can proceed with the installation of a MariaDB instance with Galera support:
kubectl apply -f examples/manifests/mariadb_galera.yaml\n
kubectl get mariadbs\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera True Running mariadb-galera-0 48m\n\nkubectl get events --field-selector involvedObject.name=mariadb-galera --sort-by='.lastTimestamp'\nLAST SEEN TYPE REASON OBJECT MESSAGE\n...\n45m Normal GaleraClusterHealthy mariadb/mariadb-galera Galera cluster is healthy\n\nkubectl get mariadb mariadb-galera -o jsonpath=\"{.status.conditions[?(@.type=='GaleraReady')]}\"\n{\"lastTransitionTime\":\"2023-07-13T18:22:31Z\",\"message\":\"Galera ready\",\"reason\":\"GaleraReady\",\"status\":\"True\",\"type\":\"GaleraReady\"}\n\nkubectl get mariadb mariadb-galera -o jsonpath=\"{.status.conditions[?(@.type=='GaleraConfigured')]}\"\n{\"lastTransitionTime\":\"2023-07-13T18:22:31Z\",\"message\":\"Galera configured\",\"reason\":\"GaleraConfigured\",\"status\":\"True\",\"type\":\"GaleraConfigured\"}\n\nkubectl get statefulsets -o wide\nNAME READY AGE CONTAINERS IMAGES\nmariadb-galera 3/3 58m mariadb,agent mariadb:11.0.3,ghcr.io/mariadb-operator/mariadb-operator:v0.0.26\n\nkubectl get pods -o wide\nNAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES\nmariadb-galera-0 2/2 Running 0 58m 10.244.2.4 mdb-worker3 <none> <none>\nmariadb-galera-1 2/2 Running 0 58m 10.244.1.9 mdb-worker2 <none> <none>\nmariadb-galera-2 2/2 Running 0 58m 10.244.5.4 mdb-worker4 <none> <none>\n
Up and running. Let's now proceed with simulating a Galera cluster failure by deleting all the Pods at the same time:
kubectl delete pods -l app.kubernetes.io/instance=mariadb-galera\npod \"mariadb-galera-0\" deleted\npod \"mariadb-galera-1\" deleted\npod \"mariadb-galera-2\" deleted\n
After some time, we will see the MariaDB entering a non Ready state:
kubectl get mariadb mariadb-galera\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera False Galera not ready mariadb-galera-0 67m\n\nkubectl get events --field-selector involvedObject.name=mariadb-galera --sort-by='.lastTimestamp'\nLAST SEEN TYPE REASON OBJECT MESSAGE\n...\n48s Warning GaleraClusterNotHealthy mariadb/mariadb-galera Galera cluster is not healthy\n\nkubectl get mariadb mariadb-galera -o jsonpath=\"{.status.conditions[?(@.type=='GaleraReady')]}\"\n{\"lastTransitionTime\":\"2023-07-13T19:25:17Z\",\"message\":\"Galera not ready\",\"reason\":\"GaleraNotReady\",\"status\":\"False\",\"type\":\"GaleraReady\"}\n
Eventually, the operator will kick in and recover the Galera cluster:
kubectl get events --field-selector involvedObject.name=mariadb-galera --sort-by='.lastTimestamp'\nLAST SEEN TYPE REASON OBJECT MESSAGE\n...\n16m Warning GaleraClusterNotHealthy mariadb/mariadb-galera Galera cluster is not healthy\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-2'\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-1'\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-0'\n16m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-1'\n16m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-2'\n17m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-0'\n17m Normal GaleraClusterBootstrap mariadb/mariadb-galera Bootstrapping Galera cluster in Pod 'mariadb-galera-2'\n20m Normal GaleraClusterHealthy mariadb/mariadb-galera Galera cluster is healthy\n\nkubectl get mariadb mariadb-galera -o jsonpath=\"{.status.galeraRecovery}\"\n{\"bootstrap\":{\"pod\":\"mariadb-galera-2\",\"time\":\"2023-07-13T19:25:28Z\"},\"recovered\":{\"mariadb-galera-0\":{\"seqno\":3,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\"},\"mariadb-galera-1\":{\"seqno\":3,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\"},\"mariadb-galera-2\":{\"seqno\":3,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\"}},\"state\":{\"mariadb-galera-0\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\",\"version\":\"2.1\"},\"mariadb-galera-1\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\",\"version\":\"2.1\"},\"mariadb-galera-2\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"bf00b9c3-21a9-11ee-984f-9ba9ff0e9285\",\"version\":\"2.1\"}}}\n
Finally, the MariaDB resource will become Ready and your Galera cluster will be operational again:
kubectl get mariadb mariadb-galera -o jsonpath=\"{.status.conditions[?(@.type=='GaleraReady')]}\"\n{\"lastTransitionTime\":\"2023-07-13T19:27:51Z\",\"message\":\"Galera ready\",\"reason\":\"GaleraReady\",\"status\":\"True\",\"type\":\"GaleraReady\"}\n\nkubectl get mariadb mariadb-galera\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera True Running mariadb-galera-0 82m\n
"},{"location":"GALERA/#troubleshooting","title":"Troubleshooting","text":"The aim of this section is showing you how to diagnose your Galera cluster when something goes wrong. In this situations, observability is a key factor to understand the problem, so we recommend following these steps before jumping into debugging the problem.
- Inspect
MariaDB status conditions.
kubectl get mariadb mariadb-galera -o jsonpath=\"{.status}\"\n{\"conditions\":[{\"lastTransitionTime\":\"2023-08-05T14:58:57Z\",\"message\":\"Galera not ready\",\"reason\":\"GaleraNotReady\",\"status\":\"False\",\"type\":\"Ready\"},{\"lastTransitionTime\":\"2023-08-05T14:58:57Z\",\"message\":\"Galera not ready\",\"reason\":\"GaleraNotReady\",\"status\":\"False\",\"type\":\"GaleraReady\"},{\"lastTransitionTime\":\"2023-08-03T19:21:16Z\",\"message\":\"Galera configured\",\"reason\":\"GaleraConfigured\",\"status\":\"True\",\"type\":\"GaleraConfigured\"}],\"currentPrimary\":\"All\",\"galeraRecovery\":{\"bootstrap\":{\"pod\":\"mariadb-galera-1\",\"time\":\"2023-08-05T14:59:18Z\"},\"recovered\":{\"mariadb-galera-0\":{\"seqno\":17,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\"},\"mariadb-galera-1\":{\"seqno\":17,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\"},\"mariadb-galera-2\":{\"seqno\":16,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\"}},\"state\":{\"mariadb-galera-0\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\",\"version\":\"2.1\"},\"mariadb-galera-1\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\",\"version\":\"2.1\"},\"mariadb-galera-2\":{\"safeToBootstrap\":false,\"seqno\":-1,\"uuid\":\"6ea235ec-3232-11ee-8152-4af03d2c43a9\",\"version\":\"2.1\"}}}}\n
- Make sure network connectivity is fine by checking that you have an
Endpoint per Pod in your Galera cluster.
kubectl get endpoints mariadb-galera-internal -o yaml\napiVersion: v1\nkind: Endpoints\nmetadata:\n name: mariadb-internal\nsubsets:\n- addresses:\n - hostname: mariadb-1\n ip: 10.255.140.181\n nodeName: k8s-worker-1\n targetRef:\n kind: Pod\n name: mariadb-1\n namespace: mariadb\n - hostname: mariadb-2\n ip: 10.255.20.156\n nodeName: k8s-worker-2\n targetRef:\n kind: Pod\n name: mariadb-2\n namespace: mariadb\n - hostname: mariadb-0\n ip: 10.255.214.164\n nodeName: k8s-worker-0\n targetRef:\n kind: Pod\n name: mariadb-0\n namespace: mariadb\n ports:\n - name: sst\n port: 4568\n protocol: TCP\n - name: ist\n port: 4567\n protocol: TCP\n - name: mariadb\n port: 3306\n protocol: TCP\n - name: agent\n port: 5555\n protocol: TCP\n - name: cluster\n port: 4444\n protocol: TCP\n\n
- Check the events associated with the
MariaDB object, as they provide significant insights for diagnosis, particularly within the context of cluster recovery.
kubectl get events --field-selector involvedObject.name=mariadb-galera --sort-by='.lastTimestamp'\nLAST SEEN TYPE REASON OBJECT MESSAGE\n...\n16m Warning GaleraClusterNotHealthy mariadb/mariadb-galera Galera cluster is not healthy\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-2'\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-1'\n16m Normal GaleraPodStateFetched mariadb/mariadb-galera Galera state fetched in Pod 'mariadb-galera-0'\n16m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-1'\n16m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-2'\n17m Normal GaleraPodRecovered mariadb/mariadb-galera Recovered Galera sequence in Pod 'mariadb-galera-0'\n17m Normal GaleraClusterBootstrap mariadb/mariadb-galera Bootstrapping Galera cluster in Pod 'mariadb-galera-2'\n20m Normal GaleraClusterHealthy mariadb/mariadb-galera Galera cluster is healthy\n
- Enable
debug logs in mariadb-operator.
helm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --set logLevel=debug\nkubectl logs mariadb-operator-546c78f4f5-gq44k\n{\"level\":\"info\",\"ts\":1691090524.4911606,\"logger\":\"galera.health\",\"msg\":\"Checking Galera cluster health\",\"controller\":\"statefulset\",\"controllerGroup\":\"apps\",\"controllerKind\":\"StatefulSet\",\"statefulSet\":{\"name\":\"mariadb-galera\",\"namespace\":\"default\"},\"namespace\":\"default\",\"name\":\"mariadb-galera\",\"reconcileID\":\"098620db-4486-45cc-966a-9f3fec0d165e\"}\n{\"level\":\"debug\",\"ts\":1691090524.4911761,\"logger\":\"galera.health\",\"msg\":\"StatefulSet ready replicas\",\"controller\":\"statefulset\",\"controllerGroup\":\"apps\",\"controllerKind\":\"StatefulSet\",\"statefulSet\":{\"name\":\"mariadb-galera\",\"namespace\":\"default\"},\"namespace\":\"default\",\"name\":\"mariadb-galera\",\"reconcileID\":\"098620db-4486-45cc-966a-9f3fec0d165e\",\"replicas\":1}\n
- Get the logs of all the
MariaDB Pod containers, not only of the main mariadb container but also the agent and init ones.
kubectl logs mariadb-galera-0 -c init\n{\"level\":\"info\",\"ts\":1691090778.5239124,\"msg\":\"Starting init\"}\n{\"level\":\"info\",\"ts\":1691090778.5305626,\"msg\":\"Configuring Galera\"}\n{\"level\":\"info\",\"ts\":1691090778.5307593,\"msg\":\"Already initialized. Init done\"}\n\nkubectl logs mariadb-galera-0 -c agent\n{\"level\":\"info\",\"ts\":1691090779.3193653,\"logger\":\"server\",\"msg\":\"server listening\",\"addr\":\":5555\"}\n2023/08/03 19:26:28 \"POST http://mariadb-galera-0.mariadb-galera-internal.default.svc.cluster.local:5555/api/recovery HTTP/1.1\" from 10.244.4.2:39162 - 200 58B in 4.112086ms\n2023/08/03 19:26:28 \"DELETE http://mariadb-galera-0.mariadb-galera-internal.default.svc.cluster.local:5555/api/recovery HTTP/1.1\" from 10.244.4.2:39162 - 200 0B in 883.544\u00b5s\n\nkubectl logs mariadb-galera-0 -c mariadb\n2023-08-03 19:27:10 0 [Note] WSREP: Member 2.0 (mariadb-galera-0) synced with group.\n2023-08-03 19:27:10 0 [Note] WSREP: Processing event queue:...100.0% (1/1 events) complete.\n2023-08-03 19:27:10 0 [Note] WSREP: Shifting JOINED -> SYNCED (TO: 6)\n2023-08-03 19:27:10 2 [Note] WSREP: Server mariadb-galera-0 synced with group\n2023-08-03 19:27:10 2 [Note] WSREP: Server status change joined -> synced\n2023-08-03 19:27:10 2 [Note] WSREP: Synchronized with group, ready for connections\n
Once you are done with these steps, you will have the context required to jump ahead to the Common errors section to see if any of them matches your case. If they don't, feel free to open an issue or even a PR updating this document if you managed to resolve it.
"},{"location":"GALERA/#common-errors","title":"Common errors","text":""},{"location":"GALERA/#galera-cluster-recovery-not-progressing","title":"Galera cluster recovery not progressing","text":"If your MariaDB Galera cluster has been in GaleraNotReady state for a long time, the recovery process might not be progressing. You can diagnose this by checking: - The operator logs. - Galera recovery status:
kubectl get mariadb mariadb-galera -o jsonpath=\"{.status.galeraRecovery}\" | jq\n
- If you have
Pods named <mariadb-name>-<ordinal>-recovery-<suffix> running for a long time, check its logs to understand if something is wrong.
One of the reasons could be misconfigured Galera recovery Jobs, please make sure you read this section. If after checking all the points above, there are still no clear symptoms of what could be wrong, continue reading.
First af all, you could attempt to forcefully bootstrap a new cluster as it is described in this section. Please, refrain from doing so if the conditions described in the docs are not met.
Alternatively, if you can afford some downtime and your PVCs are in healthy state, you may follow this procedure: - Delete your existing MariaDB, this will leave your PVCs intact. - Create your MariaDB again, this will trigger a Galera recovery process as described in this section.
As a last resource, you can always delete the PVCs and bootstrap a new MariaDB from a backup as documented here.
"},{"location":"GALERA/#permission-denied-writing-galera-configuration","title":"Permission denied writing Galera configuration","text":"This error occurs when the user that runs the container does not have enough privileges to write in /etc/mysql/mariadb.conf.d:
Error writing Galera config: open /etc/mysql/mariadb.conf.d/0-galera.cnf: permission denied\n
To mitigate this, by default, the operator sets the following securityContext in the MariaDB's StatefulSet :
apiVersion: apps/v1\nkind: StatefulSet\nmetadata:\n name: mariadb-galera\nspec:\n securityContext:\n fsGroup: 999\n runAsGroup: 999\n runAsNonRoot: true\n runAsUser: 999\n
This enables the CSIDriver and the kubelet to recursively set the ownership ofr the /etc/mysql/mariadb.conf.d folder to the group 999, which is the one expected by MariaDB. It is important to note that not all the CSIDrivers implementations support this feature, see the CSIDriver documentation for further information.
"},{"location":"GALERA/#unauthorized-error-disabling-bootstrap","title":"Unauthorized error disabling bootstrap","text":"Error reconciling Galera: error disabling bootstrap in Pod 0: unauthorized\n
This situation occurs when the mariadb-operator credentials passed to the agent as authentication are either invalid or the agent is unable to verify them. To confirm this, ensure that both the mariadb-operator and the MariaDB ServiceAccounts are able to create TokenReview objects:
kubectl auth can-i --list --as=system:serviceaccount:default:mariadb-operator | grep tokenreview\ntokenreviews.authentication.k8s.io [] [] [create]\n\nkubectl auth can-i --list --as=system:serviceaccount:default:mariadb-galera | grep tokenreview\ntokenreviews.authentication.k8s.io [] [] [create]\n
If that's not the case, check that the following ClusterRole and ClusterRoleBindings are available in your cluster:
kubectl get clusterrole system:auth-delegator\nNAME CREATED AT\nsystem:auth-delegator 2023-08-03T19:12:37Z\n\nkubectl get clusterrolebinding | grep mariadb | grep auth-delegator\nmariadb-galera:auth-delegator ClusterRole/system:auth-delegator 108m\nmariadb-operator:auth-delegator ClusterRole/system:auth-delegator 112m\n
mariadb-operator:auth-delegator is the ClusterRoleBinding bound to the mariadb-operator ServiceAccount which is created by the helm chart, so you can re-install the helm release in order to recreate it:
helm upgrade --install mariadb-operator mariadb-operator/mariadb-operator\n
mariadb-galera:auth-delegator is the ClusterRoleBinding bound to the mariadb-galera ServiceAccount which is created on the flight by the operator as part of the reconciliation logic. You may check the mariadb-operator logs to see if there are any issues reconciling it.
Bear in mind that ClusterRoleBindings are cluster-wide resources that are not garbage collected when the MariaDB owner object is deleted, which means that creating and deleting MariaDBs could leave leftovers in your cluster. These leftovers can lead to RBAC misconfigurations, as the ClusterRoleBinding might not be pointing to the right ServiceAccount. To overcome this, you can override the ClusterRoleBinding name setting the spec.galera.agent.kubernetesAuth.authDelegatorRoleName field.
"},{"location":"GALERA/#timeout-waiting-for-pod-to-be-synced","title":"Timeout waiting for Pod to be Synced","text":"Timeout waiting for Pod 'mariadb-galera-2' to be Synced\n
This error appears in the mariadb-operator logs when a Pod is in non synced state for a duration exceeding the spec.galera.recovery.podRecoveryTimeout. Just after, the operator will restart the Pod.
Increase this timeout if you consider that your Pod may take longer to recover.
"},{"location":"GALERA/#galera-cluster-bootstrap-timed-out","title":"Galera cluster bootstrap timed out","text":"Galera cluster bootstrap timed out. Resetting recovery status\n
This is error is returned by the mariadb-operator after exceeding the spec.galera.recovery.clusterBootstrapTimeout when recovering the cluster. At this point, the operator will reset the recovered sequence numbers and start again from a clean state.
Increase this timeout if you consider that your Galera cluster may take longer to recover.
"},{"location":"GALERA/#github-issues","title":"GitHub Issues","text":"Here it is a list of Galera-related issues reported by mariadb-operator users which might shed some light in your investigation: - https://github.com/mariadb-operator/mariadb-operator/issues?q=label%3Agalera+
"},{"location":"GALERA/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"HA/","title":"High availability","text":"Our recommended HA setup for production is: - Galera with at least 3 nodes. Always an odd number of nodes. - Load balance requests using MaxScale as database proxy. - Use dedicated nodes to avoid noisy neighbours. - Define pod disruption budgets.
Refer to the following sections for further detail.
"},{"location":"HA/#table-of-contents","title":"Table of contents","text":" - Topologies
- Kubernetes Services
- MaxScale
- Pod Anti-Affinity
- Dedicated Nodes
- Pod Disruption Budgets
- Reference
"},{"location":"HA/#topologies","title":"Topologies","text":" - Multi master HA via Galera: All nodes support reads and writes. We have a designated primary where the writes are performed.
- Single master HA via SemiSync Replication: The primary node allows both reads and writes, while secondary nodes only allow reads.
"},{"location":"HA/#kubernetes-services","title":"Kubernetes Services","text":"In order to address nodes, mariadb-operator provides you with the following Kubernetes Services: - <mariadb-name>: To be used for read requests. It will point to all nodes. - <mariadb-name>-primary: To be used for write requests. It will point to a single node, the primary. - <mariadb-name>-secondary: To be used for read requests. It will point to all nodes, except the primary.
Whenever the primary changes, either by the user or by the operator, both the <mariadb-name>-primary and <mariadb-name>-secondary Services will be automatically updated by the operator to address the right nodes.
The primary may be manually changed by the user at any point by updating the spec.[replication|galera].primary.podIndex field. Alternatively, automatic primary failover can be enabled by setting spec.[replication|galera].primary.automaticFailover, which will make the operator to switch primary whenever the primary Pod goes down.
"},{"location":"HA/#maxscale","title":"MaxScale","text":"While Kubernetes Services can be utilized to dynamically address primary and secondary instances, the most robust high availability configuration we recommend relies on MaxScale. Please refer to MaxScale docs for further details.
"},{"location":"HA/#pod-anti-affinity","title":"Pod Anti-Affinity","text":"[!WARNING] Bear in mind that, when enabling this, you need to have at least as many Nodes available as the replicas specified. Otherwise your Pods will be unscheduled and the cluster won't bootstrap.
To achieve real high availability, we need to run each MariaDB Pod in different Kubernetes Nodes. This practice, known as anti-affinity, helps reducing the blast radius of Nodes being unavailable.
By default, anti-affinity is disabled, which means that multiple Pods may be scheduled in the same Node, something not desired in HA scenarios.
You can selectively enable anti-affinity in all the different Pods managed by the MariaDB resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n bootstrapFrom:\n restoreJob:\n affinity:\n antiAffinityEnabled: true\n ...\n galera:\n initJob:\n affinity:\n antiAffinityEnabled: true\n ...\n metrics:\n exporter:\n affinity:\n antiAffinityEnabled: true\n ...\n affinity:\n antiAffinityEnabled: true\n
Anti-affinity may also be enabled in the the resources that have a reference to MariaDB, resulting in their Pods being scheduled in Nodes where MariaDB is not running. For instance, the Backup and Restore processes can run in different Nodes:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n mariaDbRef:\n name: mariadb-galera\n ...\n affinity:\n antiAffinityEnabled: true\n
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Restore\nmetadata:\n name: restore\nspec:\n mariaDbRef:\n name: mariadb-galera\n ...\n affinity:\n antiAffinityEnabled: true\n
In the case of MaxScale, the Pods will also be placed in Nodes isolated in terms of compute, ensuring isolation not only among themselves but also from the MariaDB Pods. For example, if you run a MariaDB and MaxScale with 3 replicas each, you will need 6 Nodes in total:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n mariaDbRef:\n name: mariadb-galera\n ...\n metrics:\n exporter:\n affinity:\n antiAffinityEnabled: true\n ...\n affinity:\n antiAffinityEnabled: true\n
Default anti-affinity rules generated by the operator might not satisfy your needs, but you can always define your own rules. For example, if you want the MaxScale Pods to be in different Nodes, but you want them to share Nodes with MariaDB:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n mariaDbRef:\n name: mariadb-galera\n ...\n affinity:\n podAntiAffinity:\n requiredDuringSchedulingIgnoredDuringExecution:\n - labelSelector:\n matchExpressions:\n - key: app.kubernetes.io/instance\n operator: In\n values:\n - maxscale-galera\n # 'mariadb-galera' instance omitted (default anti-affinity rule)\n topologyKey: kubernetes.io/hostname\n
"},{"location":"HA/#dedicated-nodes","title":"Dedicated Nodes","text":"If you want to avoid noisy neighbours running in the same Kubernetes Nodes as your MariaDB, you may consider using dedicated Nodes. For achieving this, you will need: - Taint your Nodes and add the counterpart toleration in your Pods.
[!IMPORTANT] Tainting your Nodes is not covered by this operator, it is something you need to do by yourself beforehand. You may take a look at the Kubernetes documentation to understand how to achieve this. - Select the Nodes to schedule in via a nodeSelector in your Pods. [!NOTE] Although you can use the default Node labels, you may consider adding more significative labels to your Nodes, as you will have to refer to them in your Pod nodeSelector. Refer to the Kubernetes documentation.
- Add
podAntiAffinity to your Pods as described in the Pod Anti-Affinity section.
Once you have completed the previous steps, you can configure your MariaDB as follows:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n tolerations:\n - key: \"k8s.mariadb.com/ha\"\n operator: \"Exists\"\n effect: \"NoSchedule\"\n nodeSelector:\n \"k8s.mariadb.com/node\": \"ha\" \n affinity:\n antiAffinityEnabled: true\n
"},{"location":"HA/#pod-disruption-budgets","title":"Pod Disruption Budgets","text":"[!IMPORTANT] Take a look at the Kubernetes documentation if you are unfamiliar to PodDisruptionBudgets
By defining a PodDisruptionBudget, you are telling Kubernetes how many Pods your database tolerates to be down. This quite important for planned maintenance operations such as Node upgrades.
mariadb-operator creates a default PodDisruptionBudget if you are running in HA, but you are able to define your own by setting:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n podDisruptionBudget:\n maxUnavailable: 33%\n
"},{"location":"HA/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"MAXSCALE/","title":"MaxScale","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.25
[!IMPORTANT] MaxScale 23.08 is licensed under Business Source License. Make sure you understand the implications before using it!
MaxScale is a sophisticated database proxy, router, and load balancer designed specifically for and by MariaDB. It provides a range of features that ensure optimal high availability: - Query-based routing: Transparently route write queries to the primary nodes and read queries to the replica nodes. - Connection-based routing: Load balance connections between multiple servers. - Automatic primary failover based on MariaDB internals. - Replay pending transactions when a server goes down. - Support for Galera and Replication.
To better understand what MaxScale is capable of you may check the product page and the documentation.
"},{"location":"MAXSCALE/#table-of-contents","title":"Table of contents","text":" - MaxScale resources
MaxScale CRMariaDB CRMaxScale embedded in MariaDB- Defaults
- Server configuration
- Server maintenance
- Configuration
- Authentication
- Kubernetes
Services - Connection
- High availability
- Suspend resources
- MaxScale GUI
- MaxScale API
- Troubleshooting
- Reference
"},{"location":"MAXSCALE/#maxscale-resources","title":"MaxScale resources","text":"Prior to configuring MaxScale within Kubernetes, it's essential to have a basic understanding of the resources managed through its API.
"},{"location":"MAXSCALE/#servers","title":"Servers","text":"A server defines the backend database servers that MaxScale forwards traffic to. For more detailed information, please consult the server reference.
"},{"location":"MAXSCALE/#monitors","title":"Monitors","text":"A monitor is an agent that queries the state of the servers and makes it available to the services in order to route traffic based on it. For more detailed information, please consult the monitor reference.
Depending on which highly available configuration your servers have, you will need to choose betweeen the following modules: - Galera Monitor: Detects whether servers are part of the cluster, ensuring synchronization among them, and assigning primary and replica roles as needed. - MariaDB Monitor: Probes the state of the cluster, assigns roles to the servers, and executes failover, switchover, and rejoin operations as necessary.
"},{"location":"MAXSCALE/#services","title":"Services","text":"A service defines how the traffic is routed to the servers based on a routing algorithm that takes into account the state of the servers and its role. For more detailed information, please consult the service reference.
Depending on your requirements to route traffic, you may choose between the following routers: - Readwritesplit: Route write queries to the primary server and read queries to the replica servers. - Readconnroute: Load balance connections between multiple servers.
"},{"location":"MAXSCALE/#listeners","title":"Listeners","text":"A listener specifies a port where MaxScale listens for incoming connections. It is associated with a service that handles the requests received on that port. For more detailed information, please consult the listener reference.
"},{"location":"MAXSCALE/#maxscale-cr","title":"MaxScale CR","text":"The minimal spec you need to provision a MaxScale instance is just a reference to a MariaDB resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n mariaDbRef:\n name: mariadb-galera\n
This will provision a new StatefulSet for running MaxScale and configure the servers specified by the MariaDB resource. Refer to the Server configuration section if you want to manually configure the MariaDB servers.
The rest of the configuration uses reasonable defaults set automatically by the operator. If you need a more fine grained configuration, you can provide this values yourself:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n mariaDbRef:\n name: mariadb-galera\n\n services:\n - name: rw-router\n router: readwritesplit\n params:\n transaction_replay: \"true\"\n transaction_replay_attempts: \"10\"\n transaction_replay_timeout: \"5s\"\n max_slave_connections: \"255\"\n max_replication_lag: \"3s\"\n master_accept_reads: \"true\"\n listener:\n port: 3306\n protocol: MariaDBProtocol\n params:\n connection_metadata: \"tx_isolation=auto\"\n - name: rconn-master-router\n router: readconnroute\n params:\n router_options: \"master\"\n max_replication_lag: \"3s\"\n master_accept_reads: \"true\"\n listener:\n port: 3307\n - name: rconn-slave-router\n router: readconnroute\n params:\n router_options: \"slave\"\n max_replication_lag: \"3s\"\n listener:\n port: 3308\n\n monitor:\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n disable_master_failback: \"false\"\n available_when_donor: \"false\"\n disable_master_role_setting: \"false\"\n\n kubernetesService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.224\n
As you can see, the MaxScale resources we previously mentioned have a counterpart resource in the MaxScale CR.
The previous example configured a MaxScale for a Galera cluster, but you may also configure MaxScale with a MariaDB that uses replication. It is important to note that the monitor module is automatically inferred by the operator based on the MariaDB reference you provided, however, its parameters are specific to each monitor module:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-repl\nspec:\n...\n mariaDbRef:\n name: mariadb-repl\n\n services:\n - name: rw-router\n router: readwritesplit\n params:\n transaction_replay: \"true\"\n transaction_replay_attempts: \"10\"\n transaction_replay_timeout: \"5s\"\n max_slave_connections: \"255\"\n max_replication_lag: \"3s\"\n master_accept_reads: \"true\"\n listener:\n port: 3306\n protocol: MariaDBProtocol\n params:\n connection_metadata: \"tx_isolation=auto\"\n - name: rconn-master-router\n router: readconnroute\n params:\n router_options: \"master\"\n max_replication_lag: \"3s\"\n master_accept_reads: \"true\"\n listener:\n port: 3307\n - name: rconn-slave-router\n router: readconnroute\n params:\n router_options: \"slave\"\n max_replication_lag: \"3s\"\n listener:\n port: 3308\n\n monitor:\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n auto_failover: \"true\"\n auto_rejoin: \"true\"\n switchover_on_low_disk_space: \"true\"\n\n kubernetesService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.214\n
You also need to set a reference in the MariaDB resource to make it MaxScale-aware. This is explained in the MariaDB CR section.
Refer to the Reference section for further detail.
"},{"location":"MAXSCALE/#mariadb-cr","title":"MariaDB CR","text":"You can set a spec.maxScaleRef in your MariaDB resource to make it MaxScale-aware. By doing so, the primary server reported by MaxScale will be used in MariaDB and the high availability tasks such the primary failover will be delegated to MaxScale:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n...\n maxScaleRef:\n name: maxscale-galera\n\n galera:\n enabled: true\n
Refer to the Reference section for further detail.
"},{"location":"MAXSCALE/#maxscale-embedded-in-mariadb","title":"MaxScale embedded in MariaDB","text":"To streamline the setup outlined in the MaxScale CR and MariaDB CR sections, you can provision a MaxScale to be used with MariaDB in just one resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n...\n maxScale:\n enabled: true\n\n kubernetesService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.229\n\n galera:\n enabled: true\n
This will automatically set the references between MariaDB and MaxScale and default the rest of the fields.
It is important to note that, this is intended for simple use cases where no further modifications are done on the spec.maxscale field. If you need a more fine grained configuration and perform further updates to the MaxScale resource, please use a dedicated MaxScale as described in the MaxScale CR section.
Refer to the Reference section for further detail.
"},{"location":"MAXSCALE/#defaults","title":"Defaults","text":"mariadb-operator aims to provide highly configurable CRs, but at the same maximize its usability by providing reasonable defaults. In the case of MaxScale, the following defaulting logic is applied: - spec.servers are inferred from spec.mariaDbRef. - spec.monitor.module is inferred from the spec.mariaDbRef. - spec.monitor.cooperativeMonitoring is set if high availability is enabled. - If spec.services is not provided, the following are configured by default: - readwritesplit service on port 3306. - readconnroute service pointing to the primary node on port 3307. - readconnroute service pointing to the replica nodes on port 3308.
"},{"location":"MAXSCALE/#server-configuration","title":"Server configuration","text":"As an alternative to provide a reference to a MariaDB via spec.mariaDbRef, you can also specify the servers manually:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n servers:\n - name: mariadb-0\n address: mariadb-galera-0.mariadb-galera-internal.default.svc.cluster.local\n - name: mariadb-1\n address: mariadb-galera-1.mariadb-galera-internal.default.svc.cluster.local\n - name: mariadb-2\n address: mariadb-galera-2.mariadb-galera-internal.default.svc.cluster.local\n
As you could see, you can refer to in-cluser MariaDB servers by providing the DNS names of the MariaDB Pods as server addresses. In addition, you can also refer to external MariaDB instances running outside of the Kubernetes cluster where mariadb-operator was deployed:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n servers:\n - name: mariadb-0\n address: 172.18.0.140\n port: 3306\n - name: mariadb-1\n address: 172.18.0.141\n - name: mariadb-2\n address: 172.18.0.142\n\n monitor:\n name: mariadb-monitor\n module: galeramon\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n disable_master_failback: \"false\"\n available_when_donor: \"false\"\n disable_master_role_setting: \"false\"\n\n auth:\n adminUsername: mariadb-operator\n adminPasswordSecretKeyRef:\n name: maxscale\n key: password\n clientUsername: maxscale-client\n clientPasswordSecretKeyRef:\n name: maxscale\n key: password\n serverUsername: maxscale-server\n serverPasswordSecretKeyRef:\n name: maxscale\n key: password\n monitorUsername: maxscale-monitor\n monitorPasswordSecretKeyRef:\n name: maxscale\n key: password\n syncUsername: maxscale-sync\n syncPasswordSecretKeyRef:\n name: maxscale\n key: password\n
\u26a0\ufe0f Pointing to external MariaDBs has a some limitations \u26a0\ufe0f. Since the operator doesn't have a reference to a MariaDB resource (spec.mariaDbRef), it will be unable to perform the following actions: - Infer the monitor module (spec.monitor.module), so it will need to be provided by the user. - Autogenerate authentication credentials (spec.auth), so they will need to be provided by the user. See Authentication section.
"},{"location":"MAXSCALE/#server-maintenance","title":"Server maintenance","text":"You can put servers in maintenance mode by setting maintenance = true:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n servers:\n - name: mariadb-0\n address: mariadb-galera-0.mariadb-galera-internal.default.svc.cluster.local\n port: 3306\n protocol: MariaDBBackend\n maintenance: true\n
Maintenance mode prevents MaxScale from routing traffic to the server and also excludes it from being elected as the new primary during failover events.
"},{"location":"MAXSCALE/#configuration","title":"Configuration","text":"Similar to MariaDB, MaxScale allows you to provide global configuration parameters in a maxscale.conf file. You don't need to provide this config file directly, but instead you can use the spec.config.params to instruct the operator to create the maxscale.conf:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n config:\n params:\n log_info: \"true\"\n volumeClaimTemplate:\n resources:\n requests:\n storage: 100Mi\n accessModes:\n - ReadWriteOnce\n
Both this global configuration and the resources created by the operator using the MaxScale API are stored under a volume provisioned by the spec.config.volumeClaimTemplate. Refer to the troubleshooting if you are getting errors writing on this volume.
Refer to the MaxScale reference to provide global configuration.
"},{"location":"MAXSCALE/#authentication","title":"Authentication","text":"MaxScale requires authentication with differents levels of permissions for the following components/actors: - MaxScale API consumed by mariadb-operator. - Clients connecting to MaxScale. - MaxScale connecting to MariaDB servers. - MaxScale monitor connecting to MariaDB servers. - MaxScale configuration sync to connect to MariaDB servers. See high availability section.
By default, mariadb-operator autogenerates this credentials when spec.mariaDbRef is set and spec.auth.generate = true, but you are still able to provide your own:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n auth:\n generate: false\n adminUsername: mariadb-operator\n adminPasswordSecretKeyRef:\n name: maxscale\n key: password\n deleteDefaultAdmin: true\n clientUsername: maxscale-client\n clientPasswordSecretKeyRef:\n name: maxscale\n key: password\n clientMaxConnections: 90\n serverUsername: maxscale-server\n serverPasswordSecretKeyRef:\n name: maxscale\n key: password\n serverMaxConnections: 90 \n monitorUsername: maxscale-monitor\n monitorPasswordSecretKeyRef:\n name: maxscale\n key: password\n monitorMaxConnections: 90 \n syncUsername: maxscale-sync\n syncPasswordSecretKeyRef:\n name: maxscale\n key: password\n syncMaxConnections: 90\n
As you could see, you are also able to limit the number of connections for each component/actor. Bear in mind that, when running in high availability, you may need to increase this number, as more MaxScale instances implies more connections.
"},{"location":"MAXSCALE/#kubernetes-services","title":"Kubernetes Services","text":"To enable your applications to communicate with MaxScale, a Kubernetes Service is provisioned with all the ports specified in the MaxScale listeners. You have the flexibility to provide a template to customize this Service:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n kubernetesService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.224\n
This results in the reconciliation of the following Service:
apiVersion: v1\nkind: Service\nmetadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.229\n name: maxscale-galera\nspec:\n...\n ports:\n - name: admin\n port: 8989\n targetPort: 8989\n - name: rw-router-listener\n port: 3306\n targetPort: 3306\n - name: rconn-master-router-listener\n port: 3307\n targetPort: 3307\n - name: rconn-slave-router-listener\n port: 3308\n targetPort: 3308\n selector:\n app.kubernetes.io/instance: maxscale-galera\n app.kubernetes.io/name: maxscale\n type: LoadBalancer\n
There is also another Kubernetes Service to access the GUI, please refer to the MaxScale GUI section for further detail.
"},{"location":"MAXSCALE/#connection","title":"Connection","text":"You can leverage the Connection resource to automatically configure connection strings as Secret resources that your applications can mount:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Connection\nmetadata:\n name: connection-maxscale\nspec:\n maxScaleRef:\n name: maxscale-galera\n username: maxscale-galera-client\n passwordSecretKeyRef:\n name: maxscale-galera-client\n key: password\n secretName: conn-mxs\n port: 3306\n
Alternatively, you can also provide a connection template to your MaxScale resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n... \n connection:\n secretName: mxs-galera-conn\n port: 3306\n
Note that, the Connection uses the Service described in the Kubernetes Service section and you are able to specify which MaxScale service to connect to by providing the port (spec.port) of the corresponding MaxScale listener.
"},{"location":"MAXSCALE/#high-availability","title":"High availability","text":"To synchronize the configuration state across multiple replicas, MaxScale stores the configuration externally in a MariaDB table and conducts periodic polling across all replicas. By default, the table mysql.maxscale_config is used, but this can be configured by the user as well as the synchronization interval.
Another crucial aspect to consider regarding HA is that only one monitor can be running at any given time to avoid conflicts. This can be achieved via cooperative locking, which can be configured by the user. Refer to MaxScale docs for more information.
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n replicas: 3\n\n monitor:\n name: mariadb-monitor\n module: galeramon\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n disable_master_failback: \"false\"\n available_when_donor: \"false\"\n disable_master_role_setting: \"false\" \n\n config:\n sync:\n database: mysql\n interval: 5s\n timeout: 10s\n
Multiple MaxScale replicas can be specified by providing the spec.replicas field. Note that, MaxScale exposes the scale subresource, so you can scale/downscale it by running the following command:
kubectl scale maxscale maxscale-galera --replicas 3\n
Or even configuring an HorizontalPodAutoscaler to do the job automatically.
"},{"location":"MAXSCALE/#suspend-resources","title":"Suspend resources","text":"In order to enable this feature, you must set the --feature-maxscale-suspend feature flag:
helm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --set extraArgs={--feature-maxscale-suspend}\n
Then you will be able to suspend any MaxScale resources, for instance, you can suspend a monitor:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n monitor:\n name: mariadb-monitor\n module: galeramon\n interval: 2s\n cooperativeMonitoring: majority_of_all\n params:\n disable_master_failback: \"false\"\n available_when_donor: \"false\"\n disable_master_role_setting: \"false\" \n suspend: true\n
"},{"location":"MAXSCALE/#maxscale-gui","title":"MaxScale GUI","text":"MaxScale offers a shiny user interface that provides very useful information about the MaxScale resources. You can enable it providing the following configuration:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale-galera\nspec:\n...\n admin:\n port: 8989\n guiEnabled: true\n guiKubernetesService:\n type: LoadBalancer\n metadata:\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.231\n
The GUI is exposed via a dedicated Kubernetes Service in the same port as the MaxScale API. Once you access, you will need to enter the MaxScale API credentials configured by mariadb-operator in a Secret. See the Authentication section for more details.
"},{"location":"MAXSCALE/#maxscale-api","title":"MaxScale API","text":"mariadb-operator interacts with the MaxScale REST API to reconcile the specification provided by the user, considering both the MaxScale status retrieved from the API and the provided spec.
"},{"location":"MAXSCALE/#troubleshooting","title":"Troubleshooting","text":"mariadb-operator tracks both the MaxScale status in regards to Kubernetes resources as well as the status of the MaxScale API resources. This information is available on the status field of the MaxScale resource, it may be very useful for debugging purposes:
status:\n conditions:\n - lastTransitionTime: \"2024-02-08T17:29:01Z\"\n message: Running\n reason: MaxScaleReady\n status: \"True\"\n type: Ready\n configSync:\n databaseVersion: 20\n maxScaleVersion: 20\n listeners:\n - name: rconn-master-router-listener\n state: Running\n - name: rconn-slave-router-listener\n state: Running\n - name: rw-router-listener\n state: Running\n monitor:\n name: galeramon-monitor\n state: Running\n primaryServer: mariadb-galera-1\n replicas: 1\n servers:\n - name: mariadb-galera-0\n state: Slave, Synced, Running\n - name: mariadb-galera-1\n state: Master, Synced, Running\n - name: mariadb-galera-2\n state: Slave, Synced, Running\n services:\n - name: rconn-master-router\n state: Started\n - name: rconn-slave-router\n state: Started\n - name: rw-router\n state: Started\n
Kubernetes events emitted by mariadb-operator may also be very relevant for debugging. For instance, an event is emitted whenever the primary server changes:
kubectl get events --field-selector involvedObject.name=mariadb-repl-maxscale --sort-by='.lastTimestamp'\n\nLAST SEEN TYPE REASON OBJECT MESSAGE\n24s Normal MaxScalePrimaryServerChanged maxscale/mariadb-repl-maxscale MaxScale primary server changed from 'mariadb-repl-0' to 'mariadb-repl-1'\n
mariadb-operator logs can also be a good source of information for troubleshooting. You can increase its verbosity and enable MaxScale API request logs by running:
helm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --set logLevel=debug --set extraArgs={--log-maxscale}\n
"},{"location":"MAXSCALE/#common-errors","title":"Common errors","text":""},{"location":"MAXSCALE/#permission-denied-writing-varlibmaxscale","title":"Permission denied writing /var/lib/maxscale","text":"This error occurs when the user that runs the container does not have enough privileges to write in /var/lib/maxscale:
Failed to create directory '/var/lib/maxscale/maxscale.cnf.d': 13, Permission denied\n
To mitigate this, by default, the operator sets the following securityContext in the MaxScale's StatefulSet:
apiVersion: apps/v1\nkind: StatefulSet\nmetadata:\n name: maxscale-galera\nspec:\n securityContext:\n fsGroup: 996\n runAsGroup: 996\n runAsNonRoot: true\n runAsUser: 998\n
This enables the CSIDriver and the kubelet to recursively set the ownership ofr the /var/lib/maxscale folder to the group 996, which is the one expected by MaxScale. It is important to note that not all the CSIDrivers implementations support this feature, see the CSIDriver documentation for further information.
"},{"location":"MAXSCALE/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"METADATA/","title":"Metadata","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.28
This documentation shows how to configure metadata in the mariadb-operator CRs.
"},{"location":"METADATA/#table-of-contents","title":"Table of contents","text":" - Children object metadata
Pod metadataService metadataPVC metadata- Use cases
- Reference
"},{"location":"METADATA/#children-object-metadata","title":"Children object metadata","text":"MariaDB and MaxScale resources allow you to propagate metadata to all the children objects by specifying the inheritMetadata field:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n inheritMetadata:\n labels:\n database.myorg.io: mariadb\n annotations:\n database.myorg.io: mariadb\n
This means that all the reconciled objects will inherit these labels and annotations. For instance, see the Services and Pods:
apiVersion: v1\nkind: Service\nmetadata:\n annotations:\n database.myorg.io: mariadb\n labels:\n database.myorg.io: mariadb\n name: mariadb-galera-primary\n namespace: default\n
apiVersion: v1\nkind: Pod\nmetadata:\n annotations:\n database.myorg.io: mariadb\n labels:\n database.myorg.io: mariadb\n name: mariadb-galera-0\n namespace: default\n
"},{"location":"METADATA/#pod-metadata","title":"Pod metadata","text":"You have the ability to provide dedicated metadata for Pods by specifying the podMetadata field in any CR that reconciles a Pod, for instance: MariaDB, MaxScale, Backup, Restore and SqlJobs:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n inheritMetadata:\n labels:\n sidecar.istio.io/inject: \"true\"\n annotations:\n database.myorg.io: mariadb\n podMetadata:\n labels:\n sidecar.istio.io/inject: \"false\"\n
It is important to note that the podMetadata field superseeds the inheritMetadata field, therefore the labels and annotations provided in the former will override the ones in the latter.
"},{"location":"METADATA/#service-metadata","title":"Service metadata","text":"Provision dedicated metadata for Services in the MariaDB resources can be done via the service, primaryService and secondaryService fields:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n service:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.150\n\n primaryService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.160\n\n secondaryService:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.161\n
In the case of MaxScale, you can also do this via the kubernetesService field.
Refer to the HA documentation to know more about the Service fields and MaxScale.
"},{"location":"METADATA/#pvc-metadata","title":"PVC metadata","text":"Both MariaDB and MaxScale allow you to define a volumeClaimTemplate to be used by the underlying StatefulSet. You may also define metadata for it:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n storage:\n size: 1Gi\n volumeClaimTemplate:\n metadata:\n annotations:\n database.myorg.io: mariadb\n labels:\n database.myorg.io: mariadb\n accessModes:\n - ReadWriteOnce\n resources:\n requests:\n storage: 1Gi\n
"},{"location":"METADATA/#use-cases","title":"Use cases","text":"Being able to provide metadata allows you to integrate with other CNCF landscape projects:
"},{"location":"METADATA/#metallb","title":"Metallb","text":"If you run on bare metal and you use Metallb for managing the LoadBalancer objects, you can declare its IPs via annotations:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n service:\n type: LoadBalancer\n metadata:\n annotations:\n metallb.universe.tf/loadBalancerIPs: 172.18.0.150\n
"},{"location":"METADATA/#istio","title":"Istio","text":"Istio injects the data plane container to all Pods, but you might want to opt-out of this feature in some cases:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n podMetadata:\n labels:\n sidecar.istio.io/inject: \"false\"\n
For instance, you probably don't want to inject the Istio sidecar to Backup Pods, as it will prevent the Jobs from finishing and therefore your backup process will hang.
"},{"location":"METADATA/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"METRICS/","title":"Prometheus metrics","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.24
mariadb-operator is able to provision MariaDB instances and automatically configure Prometheus to scrape their metrics so they can be used later on to build Grafana dashboards or trigger Alertmanager alerts.
"},{"location":"METRICS/#table-of-contents","title":"Table of contents","text":" - Operator metrics
- Exporter
ServiceMonitor- Configuration
- Prometheus reference installation
- Grafana dashboards
- Reference
"},{"location":"METRICS/#operator-metrics","title":"Operator metrics","text":"In order to expose the operator internal metrics, please refer to the recommended installation flavour.
"},{"location":"METRICS/#exporter","title":"Exporter","text":"The operator configures a prometheus/mysqld-exporter exporter to query MariaDB and export the metrics in Prometheus format via an http endpoint.
It is important to note that, we run this exporter as an standalone Deployment and not as a sidecar alongside every MariaDB replica. This implies that the MariaDB lifecycle is not coupled to the exporter one, so we can upgrade them independently without affecting the availability of the other.
For being able to do this, we rely on the multi-target feature introduced in the v0.15.0 of prometheus/mysqld-exporter, so make sure to specify at least v0.15.0 in the exporter image.
"},{"location":"METRICS/#servicemonitor","title":"ServiceMonitor","text":"Once the exporter Deployment is ready, mariadb-operator creates a ServiceMonitor object that will be eventually reconciled by the Prometheus operator , resulting in the Prometheus instance being configured to scrape the exporter endpoint.
As you scale your MariaDB with more or less replicas, mariadb-operator will reconcile the ServiceMonitor to add/remove targets related to the MariaDB instances.
"},{"location":"METRICS/#configuration","title":"Configuration","text":"The easiest way to setup metrics in your MariaDB instance is just by setting spec.metrics.enabled = true, like in this example:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n...\n metrics:\n enabled: true\n
The rest of the fields are defaulted by the operator. If you need a more fine grained configuration, refer to the API reference and take a look at this example:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n...\n metrics:\n enabled: true\n exporter:\n image: prom/mysqld-exporter:v0.15.1\n resources:\n requests:\n cpu: 50m\n memory: 64Mi\n limits:\n cpu: 300m\n memory: 512Mi\n port: 9104\n serviceMonitor:\n prometheusRelease: kube-prometheus-stack\n jobLabel: mariadb-monitoring\n interval: 10s\n scrapeTimeout: 10s\n username: monitoring\n passwordSecretKeyRef:\n name: mariadb\n key: password\n
"},{"location":"METRICS/#prometheus-reference-installation","title":"Prometheus reference installation","text":"The easiest way to spin up a Prometheus observability stack in Kubernetes is by installing the kube-prometheus-stack helm chart.
We leverage this chart in our local development environment and we have configured it to ensure quality interactions between mariadb-operator and Prometheus. Feel free to install it by running:
make cluster\nmake install-prometheus\n
"},{"location":"METRICS/#grafana-dashboards","title":"Grafana dashboards","text":"To visualize MariaDB metrics, our Prometheus reference installation has some interesting Grafana dashboards configured that make use of the metrics configured by mariadb-operator. They are all available on grafana.com:
MySQL Overview
MySQL Exporter Quickstart and Dashboard
MySQL Replication
Galera/MariaDB - Overview
"},{"location":"METRICS/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"REGISTRY/","title":"Registry","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.27
This documentation aims to provide guidance on how to configure private registries in the mariadb-operator CRs.
"},{"location":"REGISTRY/#table-of-contents","title":"Table of contents","text":" - Credentials
MariaDBMaxScaleBackup, Restore and SqlJob
"},{"location":"REGISTRY/#credentials","title":"Credentials","text":"The first requirement to access a private registry is having credentials in the cluster that will be pulling the images. Kubernetes has a specific type of Secret kubernetes.io/dockerconfigjson designed specifically for this purpose. Please, refer to the Kubernetes documentation to see how it can be configured.
For convenience, this repo provides a make target that can be used to configure your existing credentials available in ~/.docker/config as a kubernetes.io/dockerconfigjson Secret:
REGISTRY_PULL_SECRET=registry DOCKER_CONFIG=~/.docker/config.json make registry-secret\n
"},{"location":"REGISTRY/#mariadb","title":"MariaDB","text":"In order to configure a private registry in your MariaDB resource, you can specify multiple imagePullSecrets:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n image: docker.mariadb.com/enterprise-server:10.6\n imagePullPolicy: IfNotPresent\n imagePullSecrets:\n - name: registry\n - name: another-registry\n
As a result, the Pods created as part of the reconciliation process will have the imagePullSecrets.
You can also configure credentials for the metrics exporter:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n metrics:\n enabled: true\n exporter:\n image: prom/mysqld-exporter:v0.15.1\n imagePullPolicy: IfNotPresent\n imagePullSecrets:\n - name: registry\n
By default, the metrics exporter Pod will inherit the credentials specified in the imagePullSecrets root field, but you can also specify dedicated credentials via metrics.exporter.imagePullSecrets.
"},{"location":"REGISTRY/#maxscale","title":"MaxScale","text":"Similarly to MariaDB, you are able to configure private registries in your MaxScale resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MaxScale\nmetadata:\n name: maxscale\nspec:\n ...\n image: mariadb/maxscale:23.08\n imagePullPolicy: IfNotPresent\n imagePullSecrets:\n - name: registry\n
"},{"location":"REGISTRY/#backup-restore-and-sqljob","title":"Backup, Restore and SqlJob","text":"The batch Job resources will inherit the imagePullSecrets from the referred MariaDB, as they also make use of its image. However, you are also able to provide dedicated imagePullSecrets for these resources:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n image: docker.mariadb.com/enterprise-server:10.6\n imagePullPolicy: IfNotPresent\n imagePullSecrets:\n - name: registry\n
apiVersion: k8s.mariadb.com/v1alpha1\nkind: Backup\nmetadata:\n name: backup\nspec:\n ...\n mariaDbRef:\n name: mariadb\n imagePullSecrets:\n - name: backup-registry\n
When the resources from the above examples are created, a Job with both registry and backup-registry imagePullSecrets will be reconciled.
"},{"location":"STORAGE/","title":"Storage","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.26
This operator gives you flexibility to define the storage that will back the /var/lib/mysql data directoty mounted by MariaDB.
"},{"location":"STORAGE/#table-of-contents","title":"Table of contents","text":" - Configuration
- Volume resize
- Ephemeral storage
- Reference
"},{"location":"STORAGE/#configuration","title":"Configuration","text":"The simplest way to configure storage for your MariaDB is:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n size: 1Gi\n
This will make use of the default StorageClass available in your cluster, but you can also provide a different one:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n size: 1Gi\n storageClassName: my-storage-class\n
Under the scenes, the operator is configuring the StatefulSet's volumeClaimTemplate property, which you are also able to provide yourself:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n size: 1Gi\n storageClassName: standard\n volumeClaimTemplate:\n accessModes:\n - ReadWriteOnce\n resources:\n requests:\n storage: 1Gi\n storageClassName: standard\n
"},{"location":"STORAGE/#volume-resize","title":"Volume resize","text":"[!WARNING] The StorageClass used for volume resizing must define allowVolumeExpansion = true.
It is possible to resize your storage after having provisioned a MariaDB. We need to distinguish between: - PVCs already in use. - StatefulSet storage size, which will be used when provisioning new replicas.
It is important to note that, for the first case, your StorageClass must support volume expansion by declaring the allowVolumeExpansion = true. In such case, it will be safe to expand the storage by increasing the size and setting resizeInUseVolumes = true:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n size: 2Gi\n resizeInUseVolumes: true\n waitForVolumeResize: true\n
Depending on your storage provider, this operation might take a while, and you can decide to wait for this operation before the MariaDB becomes ready by setting waitForVolumeResize = true. Operations such as cluster recovery and primary switchover will not be performed if the MariaDB resource is not ready.
"},{"location":"STORAGE/#ephemeral-storage","title":"Ephemeral storage","text":"Provisioning standalone MariaDB instances is also possible by setting ephemeral = true:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb-galera\nspec:\n ...\n storage:\n ephemeral: true \n
This may be useful more multiple use cases, like provisioning ephemeral MariaDBs for the integration tests of your CI.
"},{"location":"STORAGE/#reference","title":"Reference","text":" - API reference
- Example suite
"},{"location":"UPDATES/","title":"Updates","text":"[!NOTE] This documentation applies to mariadb-operator version >= v0.0.29
This documentation aims to describe the supported strategies to perform updates of the MariaDB resource.
"},{"location":"UPDATES/#table-of-contents","title":"Table of contents","text":" - Update strategies
- Configuration
- Trigger updates
ReplicasFirstPrimaryLastRollingUpdateOnDelete
"},{"location":"UPDATES/#update-strategies","title":"Update strategies","text":"In order to provide you with flexibility for updating MariaDB reliably, this operator supports multiple update strategies:
ReplicasFirstPrimaryLast: Roll out replica Pods one by one, wait for each of them to become ready, and then proceed with the primary Pod.RollingUpdate: Utilize the rolling update strategy from Kubernetes. OnDelete: Updates are performed manually by deleting Pods.
"},{"location":"UPDATES/#configuration","title":"Configuration","text":"The update strategy can be configured in the updateStrategy field of the MariaDB resource:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n updateStrategy:\n type: ReplicasFirstPrimaryLast\n
It defaults to ReplicasFirstPrimaryLast if not provided.
"},{"location":"UPDATES/#trigger-updates","title":"Trigger updates","text":"Updates are not limited to updating the image field in the MariaDB resource, an update will be triggered whenever any field of the Pod template is changed. This translates into making changes to MariaDB fields that map directly or indirectly to the Pod template, for instance, the CPU and memory resources:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n- image: mariadb:10.11.7\n+ image: mariadb:10.11.8\n resources:\n requests:\n cpu: 200m\n memory: 128Mi\n limits:\n- memory: 1Gi\n+ memory: 2Gi\n
Once the update is triggered, the operator manages it differently based on the selected update strategy.
"},{"location":"UPDATES/#replicasfirstprimarylast","title":"ReplicasFirstPrimaryLast","text":"This role-aware update strategy consists in rolling out the replica Pods one by one first, waiting for each of them become ready (i.e. readiness probe passed), and then proceed with the primary Pod. This is the default update strategy, as it can potentially meet various reliability requirements and minimize the risks associated with updates:
- Write operations won't be affected until all the replica
Pods have been rolled out. If something goes wrong in the update, such as an update to an incompatible MariaDB version, this is detected early when the replicas are being rolled out and the update operation will be paused at that point. - Read operations impact is minimized by only rolling one replica
Pod at a time. - Waiting for every
Pod to be synced minimizes the impact in the clustering protocols and the network.
"},{"location":"UPDATES/#rollingupdate","title":"RollingUpdate","text":"This strategy leverages the rolling update strategy from the StatefulSet resource, which, unlike ReplicasFirstPrimaryLast, does not take into account the role of the Pods(primary or replica). Instead, it rolls out the Pods one by one, from the highest to the lowest StatefulSet index.
You are able to pass extra parameters to this strategy via the rollingUpdate object:
apiVersion: k8s.mariadb.com/v1alpha1\nkind: MariaDB\nmetadata:\n name: mariadb\nspec:\n ...\n updateStrategy:\n type: RollingUpdate\n rollingUpdate:\n maxUnavailable: 1\n
"},{"location":"UPDATES/#ondelete","title":"OnDelete","text":"This strategy aims to provide a method to update MariaDB resources manually by allowing users to restart the Pods individually.This way, the user has full control over the update process and can decide which Pods are rolled out at any given time.
Whenever an update is triggered, the MariaDB will be marked as pending to update:
kubectl get mariadbs\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera True Pending update mariadb-galera-0 5m17s\n
From this point, you are able to delete the Pods to trigger the update, which will result the MariaDB marked as updating:
kubectl get mariadbs\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera False Updating mariadb-galera-0 9m50s\n
Once all the Pods have been rolled out, the MariaDB resource will be back to a ready state:
kubectl get mariadbs\nNAME READY STATUS PRIMARY POD AGE\nmariadb-galera True Running mariadb-galera-1 12m\n
"},{"location":"UPGRADE_v0.0.20/","title":"Upgrade guide v0.0.20","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.20 from previous versions, as some breaking changes have been introduced. See: - https://github.com/mariadb-operator/mariadb-operator/pull/197 - https://github.com/mariadb-operator/mariadb-operator/pull/211
It's important to note that this migration process only applies if: - You have created a MariaDB resource using a mariadb-operator version < v0.0.20 and you are upgrading to >= v0.0.20. - Your MariaDB resource has spec.replication enabled.
If that's your case follow these steps for upgrading:
- Uninstall you current
mariadb-operator for preventing conflicts:
helm uninstall mariadb-operator\n
Alternatively, you may only downscale and delete the webhook configurations:
kubectl scale deployment mariadb-operator -n default --replicas=0\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=0\nkubectl delete validatingwebhookconfiguration mariadb-operator-webhook\nkubectl delete mutatingwebhookconfiguration mariadb-operator-webhook\n
- In case you are manually applying manifests, get a copy of your
MariaDB resources, as the CRD upgrade will wipe out fields that are no longer supported:
kubectl get mariadb mariadb-repl -n default -o yaml > mariadb-repl.yaml\n
- Upgrade CRDs to
v0.0.20: [!IMPORTANT] Helm does not handle CRD upgrades. See helm docs.
[!WARNING] This step will delete fields that are no longer supported in your resources.
kubectl replace -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.20.0/crds.yaml\n
- Perform migrations in your
MariaDB resouces: - Set
spec.replication.enabled = true. - If you had previously set
spec.replication.primary.service, move it to spec.primaryService. - Rename your resources to point to the new
<mariadb-name>-primary Service instead of primary-<mariadb-name>. - If you had previously set
spec.replication.primary.connection, move it to spec.primaryConnection. -
Rename your resources to point to the new <mariadb-name>-primary Connection instead of primary-<mariadb-name>.
-
Upgrade mariadb-operator to v0.0.20:
helm repo update mariadb-operator\nhelm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --version 0.20.0 \n
- If you previously decided to downscale the operator, make sure you upscale it back:
kubectl scale deployment mariadb-operator -n default --replicas=1\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=1\n
"},{"location":"UPGRADE_v0.0.21/","title":"Upgrade guide v0.0.21","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.21 from previous versions, as some breaking changes have been introduced. See: - https://github.com/mariadb-operator/mariadb-operator/pull/248
Follow these steps for upgrading:
- Uninstall you current
mariadb-operator for preventing conflicts:
helm uninstall mariadb-operator\n
Alternatively, you may only downscale and delete the webhook configurations:
kubectl scale deployment mariadb-operator -n default --replicas=0\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=0\nkubectl delete validatingwebhookconfiguration mariadb-operator-webhook\nkubectl delete mutatingwebhookconfiguration mariadb-operator-webhook\n
- In case you are manually applying manifests, get a copy of your
MariaDB resources, as the CRD upgrade will wipe out fields that are no longer supported:
kubectl get mariadb mariadb-repl -n default -o yaml > mariadb-repl.yaml\n
- Upgrade CRDs to
v0.0.21: [!IMPORTANT] Helm does not handle CRD upgrades. See helm docs.
[!WARNING] This step will delete fields that are no longer supported in your resources.
kubectl replace -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.21.0/crds.yaml\n
- Perform migrations in your
MariaDB resouces: MariaDB standalone migration ```diff- image:
- repository: mariadb
- tag: \"11.0.3\"
- pullPolicy: IfNotPresent
- image: mariadb:11.0.3
- imagePullPolicy: IfNotPresent ```
MariaDB galera migration ```diff- image:
- repository: mariadb
- tag: \"11.0.3\"
- pullPolicy: IfNotPresent
- image: mariadb:11.0.3
- imagePullPolicy: IfNotPresent galera: agent:
- image:
- repository: ghcr.io/mariadb-operator/mariadb-operator
- tag: \"v0.0.25\"
- pullPolicy: IfNotPresent
- image: ghcr.io/mariadb-operator/mariadb-operator:v0.0.26
- imagePullPolicy: IfNotPresent initContainer:
- image:
- repository: ghcr.io/mariadb-operator/init
- tag: \"v0.0.5\"
- pullPolicy: IfNotPresent
- image: ghcr.io/mariadb-operator/init:v0.0.6
-
imagePullPolicy: IfNotPresent ```
-
Upgrade mariadb-operator to v0.0.21:
helm repo update mariadb-operator\nhelm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --version 0.21.0 \n
- If you previously decided to downscale the operator, make sure you upscale it back:
kubectl scale deployment mariadb-operator -n default --replicas=1\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=1\n
"},{"location":"UPGRADE_v0.0.24/","title":"Upgrade guide v0.0.24","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.24 from previous versions, as some breaking changes have been introduced. See:
MariaDB - https://github.com/mariadb-operator/mariadb-operator/pull/248 - https://github.com/mariadb-operator/mariadb-operator/pull/312
Backup - https://github.com/mariadb-operator/mariadb-operator/pull/314
Restore - https://github.com/mariadb-operator/mariadb-operator/pull/308
Follow these steps for upgrading:
- Uninstall you current
mariadb-operator for preventing conflicts:
helm uninstall mariadb-operator\n
Alternatively, you may only downscale and delete the webhook configurations:
kubectl scale deployment mariadb-operator --replicas=0\nkubectl scale deployment mariadb-operator-webhook --replicas=0\nkubectl delete validatingwebhookconfiguration mariadb-operator-webhook\nkubectl delete mutatingwebhookconfiguration mariadb-operator-webhook\n
- In case you are manually applying manifests, get a copy of your
MariaDB, Backup and Restore resources, as the CRD upgrade will wipe out fields that are no longer supported:
kubectl get mariadb mariadb -o yaml > mariadb.yaml\nkubectl get backup backup -o yaml > backup.yaml\nkubectl get restore restore -o yaml > restore.yaml\n
- Upgrade CRDs to
v0.0.24: [!IMPORTANT] Helm does not handle CRD upgrades. See helm docs.
[!WARNING] This step will delete fields that are no longer supported in your resources.
kubectl replace -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.24.0/crds.yaml\n
- Perform migrations in your
MariaDB resouces:
metrics:\n+ enabled: true\n exporter:\n- image: prom/mysqld-exporter:v0.14.0\n+ image: prom/mysqld-exporter:v0.15.1\n
- Perform migrations in your
Backup resouces:
- maxRetentionDays: 30\n+ maxRetention: 720h\n
- Perform migrations in your
Restore resouces:
- fileName: backup.2023-12-19T09:00:00Z.sql\n+ targetRecoveryTime: 2023-12-19T09:00:00Z\n
- Upgrade
mariadb-operator to v0.0.24:
helm repo update mariadb-operator\nhelm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --version 0.24.0 \n
- If you previously decided to downscale the operator, make sure you upscale it back:
kubectl scale deployment mariadb-operator -n default --replicas=1\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=1\n
- If you have previously created
MariaDB instances with metrics enabled and a single replica, we also need to perform the following changes in order to create a new StatefulSet with spec.serviceName pointing to the internal Service(see https://github.com/mariadb-operator/mariadb-operator/issues/319 for context):
kubectl delete statefulset mariadb --cascade=orphan\nkubectl rollout restart statefulset mariadb\n
"},{"location":"UPGRADE_v0.0.26/","title":"Upgrade guide v0.0.26","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.26 from previous versions, as some breaking changes have been introduced in the MariaDB resource. See the changes grouped by field:
apiVersion https://github.com/mariadb-operator/mariadb-operator/pull/418
storage https://github.com/mariadb-operator/mariadb-operator/pull/407
serviceAccountName https://github.com/mariadb-operator/mariadb-operator/pull/416
galera https://github.com/mariadb-operator/mariadb-operator/pull/384 https://github.com/mariadb-operator/mariadb-operator/pull/394
Follow these steps for upgrading:
- In your current
mariadb-operator version, make sure the MariaDB to migrate is in ready state and get a copy of its manifest: [!IMPORTANT] MariaDB must be in ready state.
kubectl get mariadbs.mariadb.mmontes.io mariadb-galera -o yaml > mariadb-galera.yaml\n
- Download and setup the migration script:
wget -q \"https://raw.githubusercontent.com/mariadb-operator/mariadb-operator/main/hack/migrate_v0.0.26.sh\"\nchmod +x migrate_v0.0.26.sh\n
- Install
v0.0.26 CRDs: [!NOTE] Helm does not handle CRD upgrades. See helm docs.
kubectl apply --server-side=true --force-conflicts -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.26.0/crds.yaml\n
- Execute the migration script:
./migrate_v0.0.26.sh mariadb-galera.yaml\n
- Apply the
v0.0.26 specification:
kubectl apply -f migrated.mariadb-galera.yaml\n
- Patch the
v0.0.26 status:
kubectl patch mariadbs.k8s.mariadb.com mariadb-galera --subresource status --type merge -p \"$(cat status.mariadb-galera.yaml)\"\n
- Patch the
StatefulSet ownerReferences. All the remaining children resources will be instantly recreated by the v0.0.26 operator, but you might also patch them if you want: [!WARNING] Not changing the StatefulSet ownerReferences implies that it will be garbage collected when deleting the old CRDs.
MARIADB_UID=$(kubectl get mariadbs.k8s.mariadb.com mariadb-galera -o jsonpath=\"{.metadata.uid}\")\nkubectl patch statefulset mariadb-galera --type=json -p=\"[\n {\\\"op\\\": \\\"replace\\\", \\\"path\\\": \\\"/metadata/ownerReferences/0/apiVersion\\\", \\\"value\\\": \\\"k8s.mariadb.com/v1alpha1\\\"}, \n {\\\"op\\\": \\\"replace\\\", \\\"path\\\": \\\"/metadata/ownerReferences/0/uid\\\", \\\"value\\\": \\\"${MARIADB_UID}\\\"}\n]\"\n
- Uninstall you current
mariadb-operator:
helm uninstall mariadb-operator\n
- If your
MariaDB has Galera enabled, delete the mariadb-galera Role, as it will be specyfing the old CRDs:
kubectl delete role mariadb-galera\n
- Install the current
mariadb-operator version:
helm repo update mariadb-operator\nhelm install mariadb-operator mariadb-operator/mariadb-operator\n
- Cleanup old CRDs and migration script:
OLD_HELM_VERSION=0.25.0\nkubectl delete -f \"https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-${OLD_HELM_VERSION}/crds.yaml\"\n
rm migrate_v0.0.26.sh\n
"},{"location":"UPGRADE_v0.0.28/","title":"Upgrade guide v0.0.28","text":"[!NOTE] APIs are currently in v1alpha1, which implies that non backward compatible changes might happen. See Kubernetes API versioning for more detail.
This guide illustrates, step by step, how to migrate to v0.0.28 from previous versions, as some breaking changes have been introduced:
- Metadata: https://github.com/mariadb-operator/mariadb-operator/pull/537
- Affinity: https://github.com/mariadb-operator/mariadb-operator/pull/566 and https://github.com/mariadb-operator/mariadb-operator/pull/568
- Opt-in password generation: https://github.com/mariadb-operator/mariadb-operator/pull/598
Follow these steps for upgrading:
- Install
v0.0.28 CRDs: [!NOTE] Helm does not handle CRD upgrades. See helm docs.
kubectl apply --server-side=true --force-conflicts -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.28.0/crds.yaml\n
- Uninstall you current
mariadb-operator for preventing conflicts:
helm uninstall mariadb-operator\n
Alternatively, you may only downscale and delete the webhook configurations:
kubectl scale deployment mariadb-operator --replicas=0\nkubectl scale deployment mariadb-operator-webhook --replicas=0\nkubectl delete validatingwebhookconfiguration mariadb-operator-webhook\nkubectl delete mutatingwebhookconfiguration mariadb-operator-webhook\n
- In case you are manually applying manifests, get a copy of your resources, as the CRD upgrade will wipe out fields that are no longer supported:
kubectl get mariadb mariadb -o yaml > mariadb.yaml\nkubectl get maxscale maxscale -o yaml > maxscale.yaml\nkubectl get backup backup -o yaml > backup.yaml\nkubectl get restore restore -o yaml > restore.yaml\nkubectl get restore sqljob -o yaml > sqljob.yaml\n
- Upgrade CRDs to
v0.0.28: [!IMPORTANT] Helm does not handle CRD upgrades. See helm docs.
[!WARNING] This step will delete fields that are no longer supported in your resources.
kubectl replace -f https://github.com/mariadb-operator/mariadb-operator/releases/download/helm-chart-0.28.0/crds.yaml\n
- Perform
metadata related migrations in MariaDB, MaxScale and Connection resouces:
storage:\n volumeClaimTemplate:\n- labels:\n- k8s.mariadb.io/storage: \"fast\"\n- annotations:\n- k8s.mariadb.io/storage: \"fast\"\n+ metadata:\n+ labels:\n+ k8s.mariadb.io/storage: \"fast\"\n+ annotations:\n+ k8s.mariadb.io/storage: \"fast\"\n accessModes:\n - ReadWriteOnce\n resources:\n requests:\n storage: 1Gi\n storageClassName: standard\n\n service:\n type: LoadBalancer\n- labels:\n- k8s.mariadb.io/service: \"mysvc\"\n- annotations:\n- metallb.universe.tf/loadBalancerIPs: 172.18.0.150\n+ metadata:\n+ labels:\n+ k8s.mariadb.io/service: \"mysvc\"\n+ annotations:\n+ metallb.universe.tf/loadBalancerIPs: 172.18.0.150\n\n connection:\n secretName: mariadb-galera-conn\n secretTemplate:\n- labels:\n- k8s.mariadb.io/secret: \"supersecret\"\n- annotations:\n- k8s.mariadb.io/secret: \"supersecret\"\n+ metadata:\n+ labels:\n+ k8s.mariadb.io/secret: \"supersecret\"\n+ annotations:\n+ k8s.mariadb.io/secret: \"supersecret\"\n key: dsn\n\n galera:\n initJob:\n- labels:\n- sidecar.istio.io/inject: \"false\"\n- annotations\n- sidecar.istio.io/inject: \"false\"\n+ metadata:\n+ labels:\n+ sidecar.istio.io/inject: \"false\"\n+ annotations\n+ sidecar.istio.io/inject: \"false\"\n\n bootstrapFrom:\n restoreJob:\n- labels:\n- sidecar.istio.io/inject: \"false\"\n- annotations\n- sidecar.istio.io/inject: \"false\"\n+ metadata:\n+ labels:\n+ sidecar.istio.io/inject: \"false\"\n+ annotations\n+ sidecar.istio.io/inject: \"false\"\n
- Perform
affinity related migrations in MariaDB, MaxScale, Backup, Restore and SqlJob resources:
affinity:\n- enableAntiAffinity: true\n+ antiAffinityEnabled: true\n\n galera:\n initJob:\n affinity:\n- enableAntiAffinity: true\n+ antiAffinityEnabled: true\n\n bootstrapFrom:\n restoreJob:\n affinity:\n- enableAntiAffinity: true\n+ antiAffinityEnabled: true\n
- Perform password generation migrations in
MariaDB and MaxScale resources. This only applies if you are currently relying on Secrets generated by the operator:
- rootPasswordSecretKeyRef:\n- name: mariadb\n- key: root-password\n+ rootPasswordSecretKeyRef:\n+ name: mariadb\n+ key: root-password\n+ generate: true\n\n- passwordSecretKeyRef:\n- name: mariadb\n- key: root-password\n+ passwordSecretKeyRef:\n+ name: mariadb\n+ key: root-password\n+ generate: true\n
- Upgrade
mariadb-operator to v0.0.28:
helm repo update mariadb-operator\nhelm upgrade --install mariadb-operator mariadb-operator/mariadb-operator --version 0.28.0 \n
- If you previously decided to downscale the operator, make sure you upscale it back:
kubectl scale deployment mariadb-operator -n default --replicas=1\nkubectl scale deployment mariadb-operator-webhook -n default --replicas=1\n
"}]}
\ No newline at end of file