Skip to content

K8SPXC-1431 Fixed example configuration and finalizer description in the on-demand backup doc #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nastena1606 merged 4 commits into from
Dec 4, 2025
Merged

K8SPXC-1431 Fixed example configuration and finalizer description in the on-demand backup doc #274

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
75398ae
K8SPXC-1431 Fixed example comfiguration and finalizer description in …
nastena1606 Dec 1, 2025
efd7953
Extended finalizer description for PVC
nastena1606 Dec 1, 2025
e6afb04
Updated after the review
nastena1606 Dec 2, 2025
acd7302
Merge branch 'main' into K8SPXC-1431-Doc-backup-finalizer
nastena1606 Dec 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions docs/backup-cr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# PerconaXtraDBClusterBackup Custom Resource options

A Backup resource is a Kubernetes object that tells the Operator how
to backup your database. The [deploy/backup/backup.yaml :octicons-link-external-16:](https://github.com/percona/percona-xtradb-cluster-operator/blob/main/deploy/backup/backup.yaml) file is a template for creating backup resources.

It defines the `PerconaXtraDBClusterBackup` resource.

This document describes all available options that you can use to customize a backup.

## `apiVersion`

Specifies the API version of the Custom Resource.
`pxc.percona.com` indicates the group, and `v1` is the version of the API.

## `kind`

Defines the type of resource being created: `PerconaXtraDBClusterBackup`.

## `metadata`

The metadata part contains the following keys:

* <a name="backup-metadata-name"></a> `name` sets the name of your backup resource;
* `finalizers` subsection:

* `percona.com/delete-backup` if present, enables deletion of backup files from a backup storage when the backup object is removed (manually or by schedule). When used with the Persistent Volume as the backup storage, the finalizer deletes the PVC.

## `spec` section

The toplevel spec elements of the [deploy/backup/backup.yaml :octicons-link-external-16:](https://github.com/percona/percona-xtradb-cluster-operator/blob/main/deploy/backup/backup.yaml) are the following ones:

### `pxcCluster`

The name of the Percona XtraDB Cluster to back up.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `cluster1` |

### `storageName`

The name of the storage configuration defined in your `deploy/cr.yaml` file in the `spec.backup.storages` subsection.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `fs-pvc` |

### `activeDeadlineSeconds`

The timeout value in seconds, after which backup job will automatically fail.

| Value type | Example |
| ----------- | ---------- |
| :material-numeric-1-box: int | `3600` |

### `startingDeadlineSeconds`

The maximum time in seconds for a backup to reach the Starting state. The Operator compares the timestamp of the backup object against the current time. If the backup is not started within the set time, the Operator automatically marks it as "failed".

| Value type | Example |
| ----------- | ---------- |
| :material-numeric-1-box: int | `300` |

### `suspendedDeadlineSeconds`

The maximum time in seconds for a backup to remain in a suspended state. The Operator compares the timestamp when the backup job was suspended against the current time. After the defined suspension time expires, the backup is automatically marked as "failed".

| Value type | Example |
| ----------- | ---------- |
| :material-numeric-1-box: int | `1200` |

### `runningDeadlineSeconds`

The maximum time in seconds for a backup job to reach the Running state. The Operator compares the timestamp when the backup job started running against the current time. After the defined running time expires, the backup is automatically marked as "failed".

| Value type | Example |
| ----------- | ---------- |
| :material-numeric-1-box: int | `300` |

### `containerOptions.env`

The [environment variables set as key-value pairs :octicons-link-external-16:](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/) for the backup container.

| Value type | Example |
| ----------- | ---------- |
| :material-text-long: subdoc | <pre>- name: VERIFY_TLS<br> value: "false"</pre> |

### `containerOptions.args.xbcloud`

Custom [command line options :octicons-link-external-16:](https://docs.percona.com/percona-xtrabackup/8.0/xbcloud-options.html) for the `xbcloud` Percona XtraBackup tool.

| Value type | Example |
| ----------- | ---------- |
| :material-text-long: subdoc | <pre>- "--someflag=abc"</pre> |

### `containerOptions.args.xbstream`

Custom [command line options :octicons-link-external-16:](https://docs.percona.com/percona-xtrabackup/8.0/xbstream-options.html) for the `xbstream` Percona XtraBackup tool.

| Value type | Example |
| ----------- | ---------- |
| :material-text-long: subdoc | <pre>- "--someflag=abc"</pre> |

94 changes: 70 additions & 24 deletions docs/backups-ondemand.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,99 @@
# Make on-demand backup

1. To make an on-demand backup, you should first check your Custom Resource for
the necessary options and make changes, if needed, using the
`deploy/cr.yaml` configuration file. The `backup.storages` subsection should
contain at least one [configured storage](backups-storage.md).
## Before you begin

You can apply changes in the `deploy/cr.yaml` file with the usual
`kubectl apply -f deploy/cr.yaml` command.
1. Export the namespace as an environment variable. Replace the `<namespace>` placeholder with your value:

2. Now use *a special backup configuration YAML file* with the following
keys:
```bash
export NAMESPACE=<namespace>
```

2. Check the configuration of the `PerconaXtraDBCluster` Custom Resource. Verify that you have [configured backup storage](backups-storage.md) and specified its configuration in the `backup.storages` subsection of the Custom Resource.

* `metadata.name` key should be set to the **backup name**
(this name will be needed later to [restore the backup](backups-restore.md)),
## Backup steps

* `spec.pxcCluster` key should be set to the name of your cluster,
To make an on-demand backup, use
*a special backup configuration YAML file*. The example of such file is
[deploy/backup/backup.yaml :octicons-link-external-16:](https://github.com/percona/percona-xtradb-cluster-operator/blob/v{{release}}/deploy/backup/backup.yaml)

* `spec.storageName` key should be set to the name of your [already configured storage](backups-storage.md).
1. Specify the following keys

* optionally you can set the `metadata.finalizers.delete-s3-backup` key (it
triggers the actual deletion of backup files from the S3 bucket or azure
container when there is a manual or scheduled removal of the
corresponding backup object).
* Set the `metadata.name` key to assign a name to the backup. You will use it to make a [restore](backups-restore.md)
* Set the `spec.pxcCluster` key to the name of your cluster
* Set the `spec.storageName` key to a storage configuration defined in your `deploy/cr.yaml` file.
* Optionally, add the `percona.com/delete-backup` entry under `metadata.finalizers` to enable deletion of backup files from a backup storage when the backup object is removed (manually or by schedule).

You can find the example of such file in
[deploy/backup/backup.yaml :octicons-link-external-16:](https://github.com/percona/percona-xtradb-cluster-operator/blob/v{{release}}/deploy/backup/backup.yaml):
Here's the example configuration:

```yaml
apiVersion: pxc.percona.com/v1
kind: PerconaXtraDBClusterBackup
metadata:
finalizers:
- delete-s3-backup
- percona.com/delete-backup
name: backup1
spec:
pxcCluster: cluster1
storageName: fs-pvc
```

3. Run the actual backup command using this file:
2. Start the backup process:

```bash
kubectl apply -f deploy/backup/backup.yaml -n $NAMESPACE
```

3. Track the backup process by checking the status of the Backup object:

``` {.bash data-prompt="$" }
$ kubectl apply -f deploy/backup/backup.yaml
$ kubectl get pxc-backup -n $NAMESPACE -w
```

4. Track the backup process by checking the status of the Backup object:
The `-w` flag instructs the Operator to provide real-time updates about the backup progress. The `Succeeded` status indicates that a backup is completed.

??? example "Expected output"

```{.text .no-copy}
NAME CLUSTER STORAGE DESTINATION STATUS COMPLETED AGE
backup1 cluster1 fs-pvc pvc/xb-backup1-20251201102237-8f7b3390 Succeeded 3s 76s
```

4. View detailed information about the backup using the `kubectl describe` command:

``` {.bash data-prompt="$" }
$ kubectl get pxc-backup -w
$ kubectl describe pxc-backup -n $NAMESPACE
```

The `-w` flag instructs the Operator to provide real-time updates about the backup progress. The Succeeded status indicates that a backup is completed.
The `Status` section of the output provides useful details about the backup state, the error message in case of issues with the backup, and the storage details.

??? example "Sample output"

```{.text .no-copy}
Name: backup1
Namespace: <my-namespace>
Labels: <none>
Annotations: <none>
API Version: pxc.percona.com/v1
Kind: PerconaXtraDBClusterBackup
Metadata:
Creation Timestamp: 2025-12-01T10:22:37Z
Generation: 1
Resource Version: 1764584633525183013
UID: 8f7b3390-fa7a-4c37-85f2-9037c093589f
Spec:
Pxc Cluster: cluster1
Storage Name: fs-pvc
Status:
Completed: 2025-12-01T10:23:50Z
Destination: pvc/xb-backup1-20251201102237-8f7b3390
Image: perconalab/percona-xtradb-cluster-operator:main-pxc8.0-backup
Pvc:
Access Modes:
ReadWriteOnce
Resources:
Requests:
Storage: 6G
Storage Class Name: standard-rwo
Volume Mode: Filesystem
Volume Name: pvc-5238d6db-f40a-4608-8f8e-d0d74f328de9
```
78 changes: 3 additions & 75 deletions docs/operator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2674,15 +2674,15 @@ The custom CA certificate for TLS communication with S3 storage. See [Configure
| ----------- | ---------- |
| :material-code-string: string | `ca.crt` |

### `backup.storages.STORAGE-NAME.persistentVolumeClaim.type`
### `backup.storages.STORAGE-NAME.volume.persistentVolumeClaim.type`

The persistent volume claim storage type.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `filesystem` |

### `backup.storages.STORAGE-NAME.persistentVolumeClaim.storageClassName`
### `backup.storages.STORAGE-NAME.volume.persistentVolumeClaim.storageClassName`

Set the [Kubernetes Storage Class :octicons-link-external-16:](https://kubernetes.io/docs/concepts/storage/storage-classes/) to use with the Percona XtraDB Cluster backups [PersistentVolumeClaims :octicons-link-external-16:](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) for the `filesystem` storage type.

Expand Down Expand Up @@ -3021,77 +3021,5 @@ Specify the min password length for user passwords
| ----------- | ---------- |
| :material-numeric-1-box: int | `16` |

## <a name="operator-backupsource-section"></a> PerconaXtraDBClusterRestore Custom Resource options

[Percona XtraDB Cluster Restore](backups-restore.md) options are managed by the Operator via the
`PerconaXtraDBClusterRestore` [Custom Resource :octicons-link-external-16:](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and can be configured via the
[deploy/backup/restore.yaml :octicons-link-external-16:](https://github.com/percona/percona-xtradb-cluster-operator/blob/main/deploy/backup/restore.yaml)
configuration file. This Custom Resource contains the following options:

| Key | Value type | Description | Required |
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
| metadata.name | string | The name of the restore | true |
| spec.pxcCluster | string | Percona XtraDB Cluster name (the name of your running cluster) | true |
| spec.backupName | string | The name of the backup which should be restored| false |
| spec.resources | [subdoc](operator.md#operator-restore-resources-options-section)| Defines resources limits for the restore job | false |
| spec.backupSource| [subdoc](operator.md#operator-restore-backupsource-options-section)| Defines configuration for different restore sources | false |
| spec.pitr | [subdoc](operator.md#operator-restore-pitr-options-section) | Defines configuration for PITR restore | false |

### <a name="operator-restore-resources-options-section"></a>resources section

| Key | Value type | Description | Required |
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
| requests.memory | string | The [Kubernetes memory requests :octicons-link-external-16:](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) for the restore job (the specified value is used if memory limits are not set) | false |
| requests.cpu | string | [Kubernetes CPU requests :octicons-link-external-16:](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) for the restore job (the specified value is used if CPU limits are not set) | false |
| limits.memory | string | The [Kubernetes memory limits :octicons-link-external-16:](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) for the restore job (if set, the value will be used for memory requests as well) | false |
| limits.cpu | string | [Kubernetes CPU limits :octicons-link-external-16:](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container) for the restore job (if set, the value will be used for CPU requests as well) | false |

### <a name="operator-restore-backupsource-options-section"></a>backupSource section

| Key | Value type | Description | Required |
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
| destination | string | Path to the backup | false |
| storageName | string | The storage name from CR `spec.backup.storages`| false |
| verifyTLS | boolean | Enable or disable verification of the storage server TLS certificate. Disabling it may be useful e.g. to skip TLS verification for private S3-compatible storage with a self-issued certificate | true |
| s3 | [subdoc](operator.md#operator-restore-s3-options-section) | Define configuration for S3 compatible storages | false |
| azure | [subdoc](operator.md#operator-restore-azure-options-section) | Define configuration for azure blob storage | false |

### <a name="operator-restore-s3-options-section"></a>backupSource.s3 subsection

| Key | Value type | Description | Required |
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
| bucket | string | The bucket with a backup | true |
| credentialsSecret| string | The Secret name for the backup | true |
| endpointUrl | string | A valid endpoint URL | false |
| region | string | The region corresponding to the S3 bucket | false |
| caBundle | subdoc | Configuration for custom self-issued TLS certificates | false

#### backupSource.s3.caBundle subsection

| Key | Value type | Description | Required |
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
| name | string | The name of the Secret object that stores custom TLS certificates | true |
| key | string | The custom CA certificate file used to sign TLS certificates | true |

### <a name="operator-restore-azure-options-section"></a>backupSource.azure subsection

| Key | Value type | Description | Required |
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
| credentialsSecret| string | The Secret name for the azure blob storage | true |
| container | string | The container name of the azure blob storage | true |
| endpointUrl | string | A valid endpoint URL | false |
| storageClass | string | The storage class name of the azure blob storage | false |
| blockSize | integer | The size of a block of data to save and retrieve from the azure blob storage
| concurrency | integer | The number of writers to the same blob

### <a name="operator-restore-pitr-options-section"></a>pitr subsection

| Key | Value type | Description | Required |
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
| type | string | The type of PITR recover | true |
| date | string | The exact date of recovery | true |
| gtid | string | The exact GTID for PITR recover | true |
| spec.backupSource| [subdoc](operator.md#operator-restore-backupsource-options-section)| Percona XtraDB Cluster backups section | true |
| s3 | [subdoc](operator.md#operator-restore-s3-options-section) | Defines configuration for S3 compatible storages | false |
| azure | [subdoc](operator.md#operator-restore-azure-options-section) | Defines configuration for azure blob storage | false |


Loading