diff --git a/tools/mariadb-enterprise-operator/api-reference.md b/tools/mariadb-enterprise-operator/api-reference.md index 4f50772da7..77b157a22e 100644 --- a/tools/mariadb-enterprise-operator/api-reference.md +++ b/tools/mariadb-enterprise-operator/api-reference.md @@ -173,7 +173,7 @@ _Appears in:_ | `maxRetention` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#duration-v1-meta)_ | 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. | | | -| `logLevel` _string_ | LogLevel to be used n the Backup Job. It defaults to 'info'. | info | | +| `logLevel` _string_ | LogLevel to be used in the Backup Job. It defaults to 'info'. | info | Enum: [debug info warn error dpanic panic fatal]
| | `backoffLimit` _integer_ | BackoffLimit defines the maximum number of attempts to successfully take a Backup. | | | | `restartPolicy` _[RestartPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#restartpolicy-v1-core)_ | RestartPolicy to be added to the Backup Pod. | OnFailure | Enum: [Always OnFailure Never]
| | `inheritMetadata` _[Metadata](#metadata)_ | InheritMetadata defines the metadata to be inherited by children resources. | | | @@ -1316,8 +1316,8 @@ _Appears in:_ | `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.
The initial User will have ALL PRIVILEGES in the initial Database. | | | | `passwordSecretKeyRef` _[GeneratedSecretKeyRef](#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 "enterprise.mariadb.com/watch", updates may be performed to the Secret in order to update the password. | | | -| `passwordHashSecretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | PasswordHashSecretKeyRef is a reference to the password hash to be used by the initial User.
If the referred Secret is labeled with "enterprise.mariadb.com/watch", updates may be performed to the Secret in order to update the password hash.
It requires the 'skip-strict-password-validation' option to be set. See: https://mariadb.com/docs/server/ref/mdb/cli/mariadbd/strict-password-validation/. | | | -| `passwordPlugin` _[PasswordPlugin](#passwordplugin)_ | PasswordPlugin is a reference to the password plugin and arguments to be used by the initial User.
It requires the 'skip-strict-password-validation' option to be set. See: https://mariadb.com/docs/server/ref/mdb/cli/mariadbd/strict-password-validation/. | | | +| `passwordHashSecretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | PasswordHashSecretKeyRef is a reference to the password hash to be used by the initial User.
If the referred Secret is labeled with "enterprise.mariadb.com/watch", updates may be performed to the Secret in order to update the password hash.
It requires the 'strict-password-validation=false' option to be set. See: https://mariadb.com/docs/server/server-management/variables-and-modes/server-system-variables#strict_password_validation. | | | +| `passwordPlugin` _[PasswordPlugin](#passwordplugin)_ | PasswordPlugin is a reference to the password plugin and arguments to be used by the initial User.
It requires the 'strict-password-validation=false' option to be set. See: https://mariadb.com/docs/server/server-management/variables-and-modes/server-system-variables#strict_password_validation. | | | | `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](#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 "enterprise.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. | | | @@ -2001,6 +2001,7 @@ _Appears in:_ | `tolerations` _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#toleration-v1-core) array_ | Tolerations to be used in the Pod. | | | | `priorityClassName` _string_ | PriorityClassName to be used in the Pod. | | | | `mariaDbRef` _[MariaDBRef](#mariadbref)_ | MariaDBRef is a reference to a MariaDB object. | | Required: \{\}
| +| `target` _[PhysicalBackupTarget](#physicalbackuptarget)_ | Target defines in which Pod the physical backups will be taken. It defaults to "Replica", meaning that the physical backups will only be taken in ready replicas. | | Enum: [Replica PreferReplica]
| | `compression` _[CompressAlgorithm](#compressalgorithm)_ | Compression algorithm to be used in the Backup. | | Enum: [none bzip2 gzip]
| | `stagingStorage` _[BackupStagingStorage](#backupstagingstorage)_ | StagingStorage defines the temporary storage used to keep external backups (i.e. S3) while they are being processed.
It defaults to an emptyDir volume, meaning that the backups will be temporarily stored in the node where the PhysicalBackup Job is scheduled.
The staging area gets cleaned up after each backup is completed, consider this for sizing it appropriately. | | | | `storage` _[PhysicalBackupStorage](#physicalbackupstorage)_ | Storage defines the final storage for backups. | | Required: \{\}
| @@ -2012,6 +2013,7 @@ _Appears in:_ | `restartPolicy` _[RestartPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#restartpolicy-v1-core)_ | RestartPolicy to be added to the PhysicalBackup Pod. | OnFailure | Enum: [Always OnFailure Never]
| | `inheritMetadata` _[Metadata](#metadata)_ | InheritMetadata defines the metadata to be inherited by children resources. | | | | `successfulJobsHistoryLimit` _integer_ | SuccessfulJobsHistoryLimit defines the maximum number of successful Jobs to be displayed. It defaults to 5. | | Minimum: 0
| +| `logLevel` _string_ | LogLevel to be used in the PhysicalBackup Job. It defaults to 'info'. | info | Enum: [debug info warn error dpanic panic fatal]
| #### PhysicalBackupStorage @@ -2033,6 +2035,23 @@ _Appears in:_ | `volumeSnapshot` _[PhysicalBackupVolumeSnapshot](#physicalbackupvolumesnapshot)_ | VolumeSnapshot is a Kubernetes VolumeSnapshot specification. | | | +#### PhysicalBackupTarget + +_Underlying type:_ _string_ + +PhysicalBackupTarget defines in which Pod the physical backups will be taken. + + + +_Appears in:_ +- [PhysicalBackupSpec](#physicalbackupspec) + +| Field | Description | +| --- | --- | +| `Replica` | PhysicalBackupTargetReplica indicates that the physical backup will be taken in a ready replica.
| +| `PreferReplica` | PhysicalBackupTargetReplica indicates that the physical backup will preferably be taken in a ready replica.
If no ready replicas are available, physical backups will be taken in the primary.
| + + #### PhysicalBackupVolumeSnapshot @@ -2473,7 +2492,7 @@ _Appears in:_ | `stagingStorage` _[BackupStagingStorage](#backupstagingstorage)_ | StagingStorage defines the temporary storage used to keep external backups (i.e. S3) while they are being processed.
It defaults to an emptyDir volume, meaning that the backups will be temporarily stored in the node where the Restore Job is scheduled. | | | | `mariaDbRef` _[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 | | +| `logLevel` _string_ | LogLevel to be used n the Backup Job. It defaults to 'info'. | info | Enum: [debug info warn error dpanic panic fatal]
| | `backoffLimit` _integer_ | BackoffLimit defines the maximum number of attempts to successfully perform a Backup. | 5 | | | `restartPolicy` _[RestartPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#restartpolicy-v1-core)_ | RestartPolicy to be added to the Backup Job. | OnFailure | Enum: [Always OnFailure Never]
| | `inheritMetadata` _[Metadata](#metadata)_ | InheritMetadata defines the metadata to be inherited by children resources. | | | @@ -3092,8 +3111,8 @@ _Appears in:_ | `cleanupPolicy` _[CleanupPolicy](#cleanuppolicy)_ | CleanupPolicy defines the behavior for cleaning up a SQL resource. | | Enum: [Skip Delete]
| | `mariaDbRef` _[MariaDBRef](#mariadbref)_ | MariaDBRef is a reference to a MariaDB object. | | Required: \{\}
| | `passwordSecretKeyRef` _[SecretKeySelector](#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 "enterprise.mariadb.com/watch", updates may be performed to the Secret in order to update the password. | | | -| `passwordHashSecretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | PasswordHashSecretKeyRef is a reference to the password hash to be used by the User.
If the referred Secret is labeled with "enterprise.mariadb.com/watch", updates may be performed to the Secret in order to update the password hash.
It requires the 'skip-strict-password-validation' option to be set. See: https://mariadb.com/docs/server/ref/mdb/cli/mariadbd/strict-password-validation/. | | | -| `passwordPlugin` _[PasswordPlugin](#passwordplugin)_ | PasswordPlugin is a reference to the password plugin and arguments to be used by the User.
It requires the 'skip-strict-password-validation' option to be set. See: https://mariadb.com/docs/server/ref/mdb/cli/mariadbd/strict-password-validation/. | | | +| `passwordHashSecretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | PasswordHashSecretKeyRef is a reference to the password hash to be used by the User.
If the referred Secret is labeled with "enterprise.mariadb.com/watch", updates may be performed to the Secret in order to update the password hash.
It requires the 'strict-password-validation=false' option to be set. See: https://mariadb.com/docs/server/server-management/variables-and-modes/server-system-variables#strict_password_validation. | | | +| `passwordPlugin` _[PasswordPlugin](#passwordplugin)_ | PasswordPlugin is a reference to the password plugin and arguments to be used by the User.
It requires the 'strict-password-validation=false' option to be set. See: https://mariadb.com/docs/server/server-management/variables-and-modes/server-system-variables#strict_password_validation. | | | | `require` _[TLSRequirements](#tlsrequirements)_ | Require specifies TLS requirements for the user to connect. See: https://mariadb.com/kb/en/securing-connections-for-client-and-server/#requiring-tls. | | | | `maxUserConnections` _integer_ | MaxUserConnections defines the maximum number of simultaneous connections that the User can establish. | 10 | | | `name` _string_ | Name overrides the default name provided by metadata.name. | | MaxLength: 80
| diff --git a/tools/mariadb-enterprise-operator/backup-and-restore/physical_backup.md b/tools/mariadb-enterprise-operator/backup-and-restore/physical_backup.md index 19f9968265..6572802244 100644 --- a/tools/mariadb-enterprise-operator/backup-and-restore/physical_backup.md +++ b/tools/mariadb-enterprise-operator/backup-and-restore/physical_backup.md @@ -75,16 +75,19 @@ metadata: spec: mariaDbRef: name: mariadb + waitForIt: true schedule: cron: "*/1 * * * *" suspend: false immediate: true ``` -If you want to immediatly trigger a backup after creating the `PhysicalBackup` resource, you can set the `immediate` field to `true`. This will create a backup immediately, regardless of the schedule. +If you want to immediately trigger a backup after creating the `PhysicalBackup` resource, you can set the `immediate` field to `true`. This will create a backup immediately, regardless of the schedule. If you want to suspend the schedule, you can set the `suspend` field to `true`. This will prevent any new backups from being created until the `PhysicalBackup` is resumed. +It is very important to note that, by default, backups will only be scheduled if the referred `MariaDB` resource is in ready state. You can override this behavior by setting `mariaDbRef.waitForIt=false` which will allow backups to be scheduled even if the `MariaDB` resource is not ready. + ## Compression When using physical backups based on `mariadb-backup`, you are able to choose the compression algorithm used to compress the backup files. The available options are: @@ -122,9 +125,30 @@ spec: maxRetention: 720h # 30 days ``` -When using physical backups based on `mariadb-backup`, the operator will automatically delete backups files in the specified storage older than the retention period. +When using physical backups based on `mariadb-backup`, the operator will automatically delete backups files in the specified storage older than the retention period. The cleanup process will be performed after each successful backup. + +When using `VolumeSnapshots`, the operator will automatically delete the `VolumeSnapshot` resources older than the retention period using the Kubernetes API. The cleanup process will be performed after a `VolumeSnapshot` is successfully created. + +## Target policy + +You can define a target policy both for backups based on `mariadb-backup` and for `VolumeSnapshots`. The target policy allows you to specify in which `Pod` the backup should be taken. This can be defined via the `target` field in the `PhysicalBackup` resource: + +```yaml +apiVersion: enterprise.mariadb.com/v1alpha1 +kind: PhysicalBackup +metadata: + name: physicalbackup +spec: + mariaDbRef: + name: mariadb + target: Replica +``` -When using `VolumeSnapshots`, the operator will automatically delete the `VolumeSnapshot` resources older than the retention period using the Kubernetes API. +The following target policies are available: +- `Replica`: The backup will be taken in a ready replica. If no ready replicas are available, the backup will not be scheduled. +- `PreferReplica`: The backup will be taken in a ready replica if available, otherwise it will be taken in the primary `Pod`. + +When using the `PreferReplica` target policy, you may be willing to schedule the backups even if the `MariaDB` resource is not ready. In this case, you can set `mariaDbRef.waitForIt=false` to allow scheduling the backup even if no replicas are available. ## Restoration @@ -217,7 +241,22 @@ spec: timeout: 2h ``` -When timed out, the operator will delete the `Jobs` or `VolumeSnapshots` resources associated wit the `PhysicalBackup` resource. The operator will create new `Jobs` or `VolumeSnapshots` to retry the backup operation if the `PhysicalBackup` resource is still scheduled. +When timed out, the operator will delete the `Jobs` or `VolumeSnapshots` resources associated with the `PhysicalBackup` resource. The operator will create new `Jobs` or `VolumeSnapshots` to retry the backup operation if the `PhysicalBackup` resource is still scheduled. + +## Log level + +When taking backups based on `mariadb-backup`, you can specify the log level to be used by the `mariadb-operator` container using the `logLevel` field in the `PhysicalBackup` resource: + +```yaml +apiVersion: enterprise.mariadb.com/v1alpha1 +kind: PhysicalBackup +metadata: + name: physicalbackup +spec: + mariaDbRef: + name: mariadb + logLevel: debug +``` ## Extra options diff --git a/tools/mariadb-enterprise-operator/docker-images.md b/tools/mariadb-enterprise-operator/docker-images.md index 1b81eb9f56..9b563eda58 100644 --- a/tools/mariadb-enterprise-operator/docker-images.md +++ b/tools/mariadb-enterprise-operator/docker-images.md @@ -18,9 +18,9 @@ All the Docker images used by this operator are based on [Red Hat UBI](https://c MariaDB Enterprise Kubernetes Operator is compatible with the following Docker images: | Component | Image | Supported Tags | CPU Architecture | |-----------|-------|----------------|------------------| -| MariaDB Enterprise Kubernetes Operator (ppc64le support) | docker.mariadb.com/mariadb-enterprise-operator | 25.10.2
25.10.1
25.10.0
25.8.0
| amd64
arm64
ppc64le
| +| MariaDB Enterprise Kubernetes Operator (ppc64le support) | docker.mariadb.com/mariadb-enterprise-operator | 25.10.3
25.10.2
25.10.1
25.10.0
25.8.0
| amd64
arm64
ppc64le
| | MariaDB Enterprise Kubernetes Operator | docker.mariadb.com/mariadb-enterprise-operator | 1.0.0
| amd64
arm64
| -| MariaDB Enterprise Server (ppc64le support) | docker.mariadb.com/enterprise-server | 11.8.3-1
11.4.8-5
11.4.7-4.3
11.4.7-4.2
11.4.7-4.1
11.4
10.6.23-19
10.6.22-18.1
10.6
| amd64
arm64
ppc64le
| +| MariaDB Enterprise Server (ppc64le support) | docker.mariadb.com/enterprise-server | 11.8.5-2
11.8.3-1
11.4.8-5
11.4.7-4.3
11.4.7-4.2
11.4.7-4.1
11.4
10.6.23-19
10.6.22-18.1
10.6
| amd64
arm64
ppc64le
| | MariaDB Enterprise Server | docker.mariadb.com/enterprise-server | 11.4.5-3
11.4.4-2
10.6.21-17
10.6.20-16.1
10.6.19-15.1
10.6.18-14.2
10.6.17-13.2
| amd64
arm64
| | MaxScale Enterprise (ppc64le support) | docker.mariadb.com/maxscale | 25.10.0
25.01.4
25.01.3-1
25.01
| amd64
arm64
ppc64le
| | MaxScale Enterprise | docker.mariadb.com/maxscale-enterprise | 25.01.2
25.01.1
| amd64
arm64
| diff --git a/tools/mariadb-enterprise-operator/installation/helm.md b/tools/mariadb-enterprise-operator/installation/helm.md index 1e4f76ce78..0d1a797790 100644 --- a/tools/mariadb-enterprise-operator/installation/helm.md +++ b/tools/mariadb-enterprise-operator/installation/helm.md @@ -8,7 +8,7 @@ Configure your [customer credentials as described in the documentation](../custo ## Charts -MariaDB Enterprise Kubernetes Operator is splitted into two different helm charts for better convenience: +MariaDB Enterprise Kubernetes Operator is split into two different helm charts for better convenience: * `mariadb-enterprise-operator-crds`: Bundles the [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) required by the operator. * `mariadb-enterprise-operator`: Contains all the template manifests required to install the operator. Refer to the [operator helm values](helm.md#operator-helm-values) section for detailed information about the supported values. @@ -246,7 +246,7 @@ helm uninstall mariadb-enterprise-operator-crds | config.exporterMaxscaleImage | string | `"mariadb/maxscale-prometheus-exporter-ubi:1.1.0"` | Default MaxScale exporter image | | config.galeraLibPath | string | `"/usr/lib64/galera/libgalera_enterprise_smm.so"` | Galera Enterprise library path to be used with Galera | | config.mariadbDefaultVersion | string | `"11.8"` | Default MariaDB Enterprise version to be used when unable to infer it via image tag | -| config.mariadbImage | string | `"docker.mariadb.com/enterprise-server:11.8.3-1"` | Default MariaDB Enterprise image | +| config.mariadbImage | string | `"docker.mariadb.com/enterprise-server:11.8.5-2"` | Default MariaDB Enterprise image | | config.mariadbImageName | string | `"docker.mariadb.com/enterprise-server"` | Default MariaDB Enterprise image name | | config.maxscaleImage | string | `"docker.mariadb.com/maxscale:25.10.0"` | Default MaxScale Enterprise image | | crds | object | `{"enabled":false}` | CRDs | @@ -281,7 +281,7 @@ helm uninstall mariadb-enterprise-operator-crds | pprof.enabled | bool | `false` | Enable the pprof HTTP server. | | pprof.port | int | `6060` | The port where the pprof HTTP server listens. | | priorityClassName | string | `""` | priorityClassName to add to controller Pod | -| rbac.aggregation.enabled | bool | `true` | Specifies whether the cluster roles aggrate to view and edit predefinied roles | +| rbac.aggregation.enabled | bool | `true` | Specifies whether the cluster roles aggregate to view and edit predefinied roles | | rbac.enabled | bool | `true` | Specifies whether RBAC resources should be created | | resources | object | `{}` | Resources to add to controller container | | securityContext | object | `{}` | Security context to add to controller container | diff --git a/tools/mariadb-enterprise-operator/plugins/supported-docker-images.md b/tools/mariadb-enterprise-operator/plugins/supported-docker-images.md index db421d2173..b974d8b9ca 100644 --- a/tools/mariadb-enterprise-operator/plugins/supported-docker-images.md +++ b/tools/mariadb-enterprise-operator/plugins/supported-docker-images.md @@ -23,7 +23,7 @@ Each supported plugin will have a section on how to install it. | Component | Image | Supported Tags | CPU Architecture | |-----------|-------|----------------|------------------| -| MariaDB Enterprise Server (ppc64le support) | docker.mariadb.com/enterprise-server | 11.8.3-1
11.4.8-5
11.4.7-4.3
11.4.7-4.2
11.4.7-4.1
11.4
10.6.23-19
10.6.22-18.1
10.6
| amd64
arm64
ppc64le
| +| MariaDB Enterprise Server (ppc64le support) | docker.mariadb.com/enterprise-server | 11.8.5-2
11.8.3-1
11.4.8-5
11.4.7-4.3
11.4.7-4.2
11.4.7-4.1
11.4
10.6.23-19
10.6.22-18.1
10.6
| amd64
arm64
ppc64le
| {% include "https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yV/~/reusable/pNHZQXPP5OEz2TgvhFva/" %} diff --git a/tools/mariadb-enterprise-operator/topologies/replication.md b/tools/mariadb-enterprise-operator/topologies/replication.md index cf9854b6d2..546e17330a 100644 --- a/tools/mariadb-enterprise-operator/topologies/replication.md +++ b/tools/mariadb-enterprise-operator/topologies/replication.md @@ -75,7 +75,7 @@ kubectl get mariadb mariadb-repl -o jsonpath="{.status.replication}" | jq } ``` -The operator continiously monitors the replication status via [`SHOW SLAVE STATUS`](https://mariadb.com/docs/server/reference/sql-statements/administrative-sql-statements/show/show-replica-status), taking it into account for internal operations and updating the CR status accordingly. +The operator continuously monitors the replication status via [`SHOW SLAVE STATUS`](https://mariadb.com/docs/server/reference/sql-statements/administrative-sql-statements/show/show-replica-status), taking it into account for internal operations and updating the CR status accordingly. ## Asynchronous vs semi-syncrhonous replication @@ -174,17 +174,14 @@ A replica is considered to be lagging behind the primary when the `Seconds_Behin In order to back up and restore a replication cluster, all the concepts and procedures described in the [physical backup](../backup-and-restore/physical_backup.md) documentation apply. -Additionally, for the replication topology, the operator tracks the GTID position at the time of taking the backup, and sets this position in the `gtid_slave_pos` system variable when restoring the backup, as described in the [MariaDB documentation](https://mariadb.com/docs/server/server-usage/backup-and-restore/mariadb-backup/setting-up-a-replica-with-mariadb-backup). +Additionally, for the replication topology, the operator tracks the GTID position at the time of taking the backup, and sets this position based on the `gtid_current_pos` system variable when restoring the backup, as described in the [MariaDB documentation](https://mariadb.com/docs/server/server-usage/backup-and-restore/mariadb-backup/setting-up-a-replica-with-mariadb-backup). Depending on the `PhysicalBackup` strategy used, the operator will track the GTID position accordingly: -#### mariadb-backup +- __mariadb-backup__: When using `PhysicalBackup` with the `mariadb-backup` strategy, the GTID will be restored to a `mariadb-enterprise-operator.info` file in the data directory, which the agent will expose to the operator via HTTP. +- __VolumeSnapshot__: When using `PhysicalBackup` with the `VolumeSnapshot` strategy, the GTID position will be kept in a `enterprise.mariadb.com/gtid` annotation in the `VolumeSnapshot` object, which later on the operator will read when restoring the backup. -When using `PhysicalBackup` with the `mariadb-backup` strategy, the GTID will be restored to a `mariadb-enterprise-operator.info` file in the data directory, which the agent will expose to the operator via HTTP. - -#### `VolumeSnapshot` - -When using `PhysicalBackup` with the `VolumeSnapshot` strategy, the GTID position will be kept in a `enterprise.mariadb.com/gtid` annotation in the `VolumeSnapshot` object, which later on the operator will read when restoring the backup. +It is important to note that, by default, physical backups are only taken in ready replicas when the `MariaDB` resource is in a ready state. If you are running with a single replica, it is recommended to set `mariaDbRef.waitForIt=false` and `target=PreferReplica` in the `PhysicalBackup` CR to allow taking backups from the primary when the replica is not ready. Please refer to the [physical backup documentation](../backup-and-restore/physical_backup.md) for configuring this behaviour. {% hint style="warning" %} Refrain from removing the `enterprise.mariadb.com/gtid` annotation in the `VolumeSnapshot` object, as it is required for configuring the replica when restoring the backup. @@ -315,8 +312,10 @@ metadata: spec: mariaDbRef: name: mariadb-repl + waitForIt: false schedule: suspend: true + target: PreferReplica storage: s3: bucket: scaleout @@ -350,14 +349,16 @@ metadata: spec: mariaDbRef: name: mariadb-repl + waitForIt: false schedule: suspend: true + target: PreferReplica storage: volumeSnapshot: volumeSnapshotClassName: csi-hostpath-snapclass ``` -Once the `PhysicalBackup` template is created, you neeed to set a reference to it in the `spec.replication.replica.bootstrapFrom`, indicating that this will be the source for creating new replicas: +Once the `PhysicalBackup` template is created, you need to set a reference to it in the `spec.replication.replica.bootstrapFrom`, indicating that this will be the source for creating new replicas: ```yaml apiVersion: enterprise.mariadb.com/v1alpha1 @@ -411,9 +412,9 @@ NAME READY STATUS PRIMARY UPDATES mariadb-repl False Scaling out mariadb-repl-1 ReplicasFirstPrimaryLast 3d5h kubectl get physicalbackups -NAME COMPLETE STATUS MARIADB LAST SCHEDULED AGE -mariadb-repl-physicalbackup-scale-out True Success mariadb-repl 14s 14s -physicalbackup-tpl False Suspended mariadb-repl 3d8h +NAME COMPLETE STATUS MARIADB LAST SCHEDULED AGE +mariadb-repl-pb-scaleout True Success mariadb-repl 14s 14s +physicalbackup-tpl False Suspended mariadb-repl 3d8h kubectl get pods NAME READY STATUS RESTARTS AGE @@ -428,11 +429,17 @@ NAME READY STATUS PRIMARY UPDATES AGE mariadb-repl True Running mariadb-repl-1 ReplicasFirstPrimaryLast 3d5h ``` -It is important to note that, if there are no ready replicas available at the time of the scaling out operation, the `PhysicalBackup` will not become ready, and the scaling out operation will be stuck until a replica becomes ready. You have the ability to cancel the scaling out operation by setting back the `spec.replicas` field to the previous value. +{% hint style="warning" %} +Considering that we set `mariaDbRef.waitForIt=false` and `target=PreferReplica` in the `PhysicalBackup` template, it is important to note that, if there are no ready replicas available at the time of the scaling out operation, the operator will take the backup from the primary instead. Please refer to the [physical backup documentation](../backup-and-restore/physical_backup.md) for configuring this behaviour. +{% endhint %} + +{% hint style="info" %} +You have the ability to cancel the scaling out operation by setting `spec.replicas` back to the previous value. +{% endhint %} ## Replica recovery -The operator has the ability to automatically recover replicas that become unavailable and report a specific error code in the replication status. For doing so, the operator continiously monitors the replication status of each replica, and whenever a replica reports an error code listed in the table below, the operator will trigger an automated recovery process for that replica: +The operator has the ability to automatically recover replicas that become unavailable and report a specific error code in the replication status. For doing so, the operator continuously monitors the replication status of each replica, and whenever a replica reports an error code listed in the table below, the operator will trigger an automated recovery process for that replica: | Error Code | Thread | Description | Documentation | |------------|--------|-------------|---------------| @@ -461,7 +468,7 @@ spec: The `errorDurationThreshold` option defines the duration after which, a replica reporting an unknown error code will be considered for recovery. This is useful to avoid recovering replicas due to transient issues. It defaults to `5m`. -We will be simulating a `1236` error in a replica to demostrate how the recovery process works: +We will be simulating a `1236` error in a replica to demonstrate how the recovery process works: {% hint style="danger" %} Do not perform the following steps in a production environment. @@ -495,25 +502,31 @@ NAME READY STATUS PRIMARY UPDATES mariadb-repl False Recovering replicas mariadb-repl-1 ReplicasFirstPrimaryLast 3d6h kubectl get physicalbackups -NAME COMPLETE STATUS MARIADB LAST SCHEDULED AGE -mariadb-repl-physicalbackup-replica-recovery True Success mariadb-repl 31s 31s -physicalbackup-tpl False Suspended mariadb-repl 3d9h +NAME COMPLETE STATUS MARIADB LAST SCHEDULED AGE +mariadb-repl-pb-recovery True Success mariadb-repl 31s 31s +physicalbackup-tpl False Suspended mariadb-repl 3d9h kubectl get pods -NAME READY STATUS RESTARTS AGE -mariadb-repl-0 0/2 PodInitializing 0 22s -mariadb-repl-0-physicalbackup-init-qn79f 0/1 Completed 0 8s -mariadb-repl-1 2/2 Running 0 3d6h -mariadb-repl-2 2/2 Running 0 3d6h -mariadb-repl-metrics-56865fff65-t72kc 1/1 Running 0 3d6h -mariadb-repl-physicalbackup-replica-recovery-2025102020270r98zr 0/1 Completed 0 31s +NAME READY STATUS RESTARTS AGE +mariadb-repl-0 0/2 PodInitializing 0 22s +mariadb-repl-0-pb-init-qn79f 0/1 Completed 0 8s +mariadb-repl-1 2/2 Running 0 3d6h +mariadb-repl-2 2/2 Running 0 3d6h +mariadb-repl-metrics-56865fff65-t72kc 1/1 Running 0 3d6h +mariadb-repl-pb-recovery-2025102020270r98zr 0/1 Completed 0 31s kubectl get mariadb NAME READY STATUS PRIMARY UPDATES AGE mariadb-repl True Running mariadb-repl-1 ReplicasFirstPrimaryLast 3d6h ``` -It is important to note that, if there are no ready replicas available at the time of the recovery operation, the `PhysicalBackup` will not become ready, and the recovery operation will be stuck until a replica becomes ready. You have the ability to cancel the recovery operation by setting `spec.replication.replica.recovery.enabled=false`. +{% hint style="warning" %} +Considering that we set `mariaDbRef.waitForIt=false` and `target=PreferReplica` in the `PhysicalBackup` template, it is important to note that, if there are no ready replicas available at the time of the replica recovery operation, the operator will take the backup from the primary instead. Please refer to the [physical backup documentation](../backup-and-restore/physical_backup.md) for configuring this behaviour. +{% endhint %} + +{% hint style="info" %} +You have the ability to cancel the recovery operation by setting `spec.replication.replica.recovery.enabled=false`. +{% endhint %} ## Troubleshooting @@ -634,13 +647,13 @@ Error 1236: Got fatal error from master when reading data from binary log. This is a something the operator is able to recover from, please refer to the [replica recovery section](#replica-recovery). -##### Scaling out/recovery operation stucked +##### Scaling out/recovery operation stuck -These operations rely on a `PhysicalBackup` for setting up the new replicas. If this `PhysicalBackup` does not become ready, the operation will not progress. In order to debug this please refer to the [`PhysicalBackup` troubleshooting section](../backup-and-restore/physical_backup.md#troubleshooting). +These operations rely on a `PhysicalBackup` for setting up the new replicas. If this `PhysicalBackup` does not become ready, the operation will not progress. In order to debug this please refer to the [`PhysicalBackup` troubleshooting section](../backup-and-restore/physical_backup.md#troubleshooting). -One of the reasons could be that there are not replicas in ready state at the time of creating the `PhysicalBackup`, for instance, all the replicas are lagging behind the primary. Please verify that this is the case by checking the status of your `MariaDB` resource and your `Pods`. +One of the reasons could be that you have no ready replicas for taking the backup and your `PhysicalBackup` CR does not allow taking the backup from the primary. You may set `mariaDbRef.waitForIt=false` and `target=PreferReplica` in the `PhysicalBackup` template to allow taking the backup from the primary when there are no ready replicas available. Please verify that this is the case by checking the status of your `MariaDB` resource and your `Pods`, and refer to the [physical backup documentation](../backup-and-restore/physical_backup.md) for configuring the backup behaviour. -##### MaxScale switchover stucked during update +##### MaxScale switchover stuck during update When using MaxScale, after having updated all the replica Pods, it could happen that MaxScale refuses to perform the switchover, as it considers the Pod chosen by the operator to be unsafe: @@ -650,6 +663,17 @@ When using MaxScale, after having updated all the replica Pods, it could happen For this case, you can manually update the `primaryServer` field in the `MaxScale` resource to a safe Pod, and restart the operator. If the new primary server is the right Pod, MaxScale will start the switchover and the update will continue after it completes. +##### Scale out/replica recovery job names too long + +```bash +error creating Job: Job.batch \"mariadb-repl-operator-test-new-physicalbackup-scale-out-20251208221943\" +is invalid: spec.template.labels: +Invalid value: \"mariadb-repl-operator-test-new-physicalbackup-scale-out-20251208221943\": +must be no more than 63 characters +``` + +This error happens when the name of the physical backup `Job` created for the scaling out or replica recovery operation exceeds the Kubernetes hard limit of 63 characters. We have truncated the job names already to significantly mitigate this problem, but the problem might still happen if your `MariaDB` resource name is too long. + {% include "https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yV/~/reusable/pNHZQXPP5OEz2TgvhFva/" %} {% @marketo/form formId="4316" %} diff --git a/tools/mariadb-enterprise-operator/updates/update-25.10.md b/tools/mariadb-enterprise-operator/updates/update-25.10.md index 6d85a36f52..4f67b0955a 100644 --- a/tools/mariadb-enterprise-operator/updates/update-25.10.md +++ b/tools/mariadb-enterprise-operator/updates/update-25.10.md @@ -1,8 +1,8 @@ # 25.10 LTS update guide -This guide illustrates, step by step, how to update to `25.10.2` from previous versions. +This guide illustrates, step by step, how to update to `25.10.3` from previous versions. This guide only applies if you are updating from a version prior to `25.10.x`, otherwise you may upgrade directly (see [Helm](https://mariadb.com/docs/tools/mariadb-enterprise-operator/installation/helm#updates) and [OpenShift](https://mariadb.com/docs/tools/mariadb-enterprise-operator/installation/openshift#updates) docs) -- The Galera data-plane must be updated to the `25.10.2` version. You must set `updateStrategy.autoUpdateDataPlane=true` in your `MariaDB` resources before updating the operator. Then, once updated, the operator will also be updating the data-plane based on its version: +- The Galera data-plane must be updated to the `25.10.3` version. You must set `updateStrategy.autoUpdateDataPlane=true` in your `MariaDB` resources before updating the operator. Then, once updated, the operator will also be updating the data-plane based on its version: ```diff apiVersion: enterprise.mariadb.com/v1alpha1 kind: MariaDB @@ -15,16 +15,16 @@ spec: - Once set, you may proceed to update the operator. If you are using __Helm__: -Upgrade the `mariadb-enterprise-operator-crds` helm chart to `25.10.2`: +Upgrade the `mariadb-enterprise-operator-crds` helm chart to `25.10.3`: ```bash helm repo update mariadb-enterprise-operator -helm upgrade --install mariadb-enterprise-operator-crds mariadb-enterprise-operator/mariadb-enterprise-operator-crds --version 25.10.2 +helm upgrade --install mariadb-enterprise-operator-crds mariadb-enterprise-operator/mariadb-enterprise-operator-crds --version 25.10.3 ``` -Upgrade the `mariadb-enterprise-operator` helm chart to `25.10.2`: +Upgrade the `mariadb-enterprise-operator` helm chart to `25.10.3`: ```bash helm repo update mariadb-enterprise-operator -helm upgrade --install mariadb-enterprise-operator mariadb-enterprise-operator/mariadb-enterprise-operator --version 25.10.2 +helm upgrade --install mariadb-enterprise-operator mariadb-enterprise-operator/mariadb-enterprise-operator --version 25.10.3 ``` As part of the 25.10 LTS release, we have introduced support for LTS versions. Refer to the [Helm docs](https://mariadb.com/docs/tools/mariadb-enterprise-operator/installation/helm#long-term-support-versions) for sticking to LTS versions. @@ -36,7 +36,7 @@ If you are on the `stable` channel using `installPlanApproval=Automatic` in your ```bash oc get installplan NAME CSV APPROVAL APPROVED -install-sjgcs mariadb-enterprise-operator.v25.10.2 Manual false +install-sjgcs mariadb-enterprise-operator.v25.10.3 Manual false oc patch installplan install-sjgcs --type merge -p '{"spec":{"approved":true}}'