Skip to content

Commit 8b77d22

Browse files
nastena1606nastena1606
authored
K8SPXC-1431 Fixed example configuration and finalizer description in the on-demand backup doc (#274)
K8SPXC-1431 Fixed example configuration and finalizer description in the on-demand backup doc Added PXC Backup and Restore Custom Resource options reference doc to align this doc set with the rest of the Operators
1 parent d2ef0e9 commit 8b77d22

File tree

5 files changed

+450
-99
lines changed

5 files changed

+450
-99
lines changed

‎docs/backup-cr.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# PerconaXtraDBClusterBackup Custom Resource options
2+
3+
A Backup resource is a Kubernetes object that tells the Operator how
4+
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.
5+
6+
It defines the `PerconaXtraDBClusterBackup` resource.
7+
8+
This document describes all available options that you can use to customize a backup.
9+
10+
## `apiVersion`
11+
12+
Specifies the API version of the Custom Resource.
13+
`pxc.percona.com` indicates the group, and `v1` is the version of the API.
14+
15+
## `kind`
16+
17+
Defines the type of resource being created: `PerconaXtraDBClusterBackup`.
18+
19+
## `metadata`
20+
21+
The metadata part contains the following keys:
22+
23+
* <a name="backup-metadata-name"></a> `name` sets the name of your backup resource;
24+
* `finalizers` subsection:
25+
26+
* `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.
27+
28+
## `spec` section
29+
30+
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:
31+
32+
### `pxcCluster`
33+
34+
The name of the Percona XtraDB Cluster to back up.
35+
36+
| Value type | Example |
37+
| ----------- | ---------- |
38+
| :material-code-string: string | `cluster1` |
39+
40+
### `storageName`
41+
42+
The name of the storage configuration defined in your `deploy/cr.yaml` file in the `spec.backup.storages` subsection.
43+
44+
| Value type | Example |
45+
| ----------- | ---------- |
46+
| :material-code-string: string | `fs-pvc` |
47+
48+
### `activeDeadlineSeconds`
49+
50+
The timeout value in seconds, after which backup job will automatically fail.
51+
52+
| Value type | Example |
53+
| ----------- | ---------- |
54+
| :material-numeric-1-box: int | `3600` |
55+
56+
### `startingDeadlineSeconds`
57+
58+
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".
59+
60+
| Value type | Example |
61+
| ----------- | ---------- |
62+
| :material-numeric-1-box: int | `300` |
63+
64+
### `suspendedDeadlineSeconds`
65+
66+
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".
67+
68+
| Value type | Example |
69+
| ----------- | ---------- |
70+
| :material-numeric-1-box: int | `1200` |
71+
72+
### `runningDeadlineSeconds`
73+
74+
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".
75+
76+
| Value type | Example |
77+
| ----------- | ---------- |
78+
| :material-numeric-1-box: int | `300` |
79+
80+
### `containerOptions.env`
81+
82+
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.
83+
84+
| Value type | Example |
85+
| ----------- | ---------- |
86+
| :material-text-long: subdoc | <pre>- name: VERIFY_TLS<br> value: "false"</pre> |
87+
88+
### `containerOptions.args.xbcloud`
89+
90+
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.
91+
92+
| Value type | Example |
93+
| ----------- | ---------- |
94+
| :material-text-long: subdoc | <pre>- "--someflag=abc"</pre> |
95+
96+
### `containerOptions.args.xbstream`
97+
98+
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.
99+
100+
| Value type | Example |
101+
| ----------- | ---------- |
102+
| :material-text-long: subdoc | <pre>- "--someflag=abc"</pre> |
103+

‎docs/backups-ondemand.md‎

Lines changed: 70 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,99 @@
11
# Make on-demand backup
22

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

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

11-
2. Now use *a special backup configuration YAML file* with the following
12-
keys:
7+
```bash
8+
export NAMESPACE=<namespace>
9+
```
10+
11+
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.
1312

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

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

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

21-
* optionally you can set the `metadata.finalizers.delete-s3-backup` key (it
22-
triggers the actual deletion of backup files from the S3 bucket or azure
23-
container when there is a manual or scheduled removal of the
24-
corresponding backup object).
21+
* Set the `metadata.name` key to assign a name to the backup. You will use it to make a [restore](backups-restore.md)
22+
* Set the `spec.pxcCluster` key to the name of your cluster
23+
* Set the `spec.storageName` key to a storage configuration defined in your `deploy/cr.yaml` file.
24+
* 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).
2525

26-
You can find the example of such file in
27-
[deploy/backup/backup.yaml :octicons-link-external-16:](https://github.com/percona/percona-xtradb-cluster-operator/blob/v{{release}}/deploy/backup/backup.yaml):
26+
Here's the example configuration:
2827
2928
```yaml
3029
apiVersion: pxc.percona.com/v1
3130
kind: PerconaXtraDBClusterBackup
3231
metadata:
3332
finalizers:
34-
- delete-s3-backup
33+
- percona.com/delete-backup
3534
name: backup1
3635
spec:
3736
pxcCluster: cluster1
3837
storageName: fs-pvc
3938
```
4039
41-
3. Run the actual backup command using this file:
40+
2. Start the backup process:
41+
42+
```bash
43+
kubectl apply -f deploy/backup/backup.yaml -n $NAMESPACE
44+
```
45+
46+
3. Track the backup process by checking the status of the Backup object:
4247
4348
``` {.bash data-prompt="$" }
44-
$ kubectl apply -f deploy/backup/backup.yaml
49+
$ kubectl get pxc-backup -n $NAMESPACE -w
4550
```
4651
47-
4. Track the backup process by checking the status of the Backup object:
52+
The `-w` flag instructs the Operator to provide real-time updates about the backup progress. The `Succeeded` status indicates that a backup is completed.
4853
54+
??? example "Expected output"
55+
56+
```{.text .no-copy}
57+
NAME CLUSTER STORAGE DESTINATION STATUS COMPLETED AGE
58+
backup1 cluster1 fs-pvc pvc/xb-backup1-20251201102237-8f7b3390 Succeeded 3s 76s
59+
```
60+
61+
4. View detailed information about the backup using the `kubectl describe` command:
62+
4963
``` {.bash data-prompt="$" }
50-
$ kubectl get pxc-backup -w
64+
$ kubectl describe pxc-backup -n $NAMESPACE
5165
```
5266
53-
The `-w` flag instructs the Operator to provide real-time updates about the backup progress. The Succeeded status indicates that a backup is completed.
67+
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.
68+
69+
??? example "Sample output"
70+
71+
```{.text .no-copy}
72+
Name: backup1
73+
Namespace: <my-namespace>
74+
Labels: <none>
75+
Annotations: <none>
76+
API Version: pxc.percona.com/v1
77+
Kind: PerconaXtraDBClusterBackup
78+
Metadata:
79+
Creation Timestamp: 2025-12-01T10:22:37Z
80+
Generation: 1
81+
Resource Version: 1764584633525183013
82+
UID: 8f7b3390-fa7a-4c37-85f2-9037c093589f
83+
Spec:
84+
Pxc Cluster: cluster1
85+
Storage Name: fs-pvc
86+
Status:
87+
Completed: 2025-12-01T10:23:50Z
88+
Destination: pvc/xb-backup1-20251201102237-8f7b3390
89+
Image: perconalab/percona-xtradb-cluster-operator:main-pxc8.0-backup
90+
Pvc:
91+
Access Modes:
92+
ReadWriteOnce
93+
Resources:
94+
Requests:
95+
Storage: 6G
96+
Storage Class Name: standard-rwo
97+
Volume Mode: Filesystem
98+
Volume Name: pvc-5238d6db-f40a-4608-8f8e-d0d74f328de9
99+
```

‎docs/operator.md‎

Lines changed: 3 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -2674,15 +2674,15 @@ The custom CA certificate for TLS communication with S3 storage. See [Configure
26742674
| ----------- | ---------- |
26752675
| :material-code-string: string | `ca.crt` |
26762676

2677-
### `backup.storages.STORAGE-NAME.persistentVolumeClaim.type`
2677+
### `backup.storages.STORAGE-NAME.volume.persistentVolumeClaim.type`
26782678

26792679
The persistent volume claim storage type.
26802680

26812681
| Value type | Example |
26822682
| ----------- | ---------- |
26832683
| :material-code-string: string | `filesystem` |
26842684

2685-
### `backup.storages.STORAGE-NAME.persistentVolumeClaim.storageClassName`
2685+
### `backup.storages.STORAGE-NAME.volume.persistentVolumeClaim.storageClassName`
26862686

26872687
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.
26882688

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

3024-
## <a name="operator-backupsource-section"></a> PerconaXtraDBClusterRestore Custom Resource options
3025-
3026-
[Percona XtraDB Cluster Restore](backups-restore.md) options are managed by the Operator via the
3027-
`PerconaXtraDBClusterRestore` [Custom Resource :octicons-link-external-16:](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and can be configured via the
3028-
[deploy/backup/restore.yaml :octicons-link-external-16:](https://github.com/percona/percona-xtradb-cluster-operator/blob/main/deploy/backup/restore.yaml)
3029-
configuration file. This Custom Resource contains the following options:
3030-
3031-
| Key | Value type | Description | Required |
3032-
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
3033-
| metadata.name | string | The name of the restore | true |
3034-
| spec.pxcCluster | string | Percona XtraDB Cluster name (the name of your running cluster) | true |
3035-
| spec.backupName | string | The name of the backup which should be restored| false |
3036-
| spec.resources | [subdoc](operator.md#operator-restore-resources-options-section)| Defines resources limits for the restore job | false |
3037-
| spec.backupSource| [subdoc](operator.md#operator-restore-backupsource-options-section)| Defines configuration for different restore sources | false |
3038-
| spec.pitr | [subdoc](operator.md#operator-restore-pitr-options-section) | Defines configuration for PITR restore | false |
3039-
3040-
### <a name="operator-restore-resources-options-section"></a>resources section
3041-
3042-
| Key | Value type | Description | Required |
3043-
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
3044-
| 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 |
3045-
| 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 |
3046-
| 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 |
3047-
| 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 |
3048-
3049-
### <a name="operator-restore-backupsource-options-section"></a>backupSource section
3050-
3051-
| Key | Value type | Description | Required |
3052-
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
3053-
| destination | string | Path to the backup | false |
3054-
| storageName | string | The storage name from CR `spec.backup.storages`| false |
3055-
| 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 |
3056-
| s3 | [subdoc](operator.md#operator-restore-s3-options-section) | Define configuration for S3 compatible storages | false |
3057-
| azure | [subdoc](operator.md#operator-restore-azure-options-section) | Define configuration for azure blob storage | false |
3058-
3059-
### <a name="operator-restore-s3-options-section"></a>backupSource.s3 subsection
3060-
3061-
| Key | Value type | Description | Required |
3062-
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
3063-
| bucket | string | The bucket with a backup | true |
3064-
| credentialsSecret| string | The Secret name for the backup | true |
3065-
| endpointUrl | string | A valid endpoint URL | false |
3066-
| region | string | The region corresponding to the S3 bucket | false |
3067-
| caBundle | subdoc | Configuration for custom self-issued TLS certificates | false
3068-
3069-
#### backupSource.s3.caBundle subsection
3070-
3071-
| Key | Value type | Description | Required |
3072-
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
3073-
| name | string | The name of the Secret object that stores custom TLS certificates | true |
3074-
| key | string | The custom CA certificate file used to sign TLS certificates | true |
3075-
3076-
### <a name="operator-restore-azure-options-section"></a>backupSource.azure subsection
3077-
3078-
| Key | Value type | Description | Required |
3079-
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
3080-
| credentialsSecret| string | The Secret name for the azure blob storage | true |
3081-
| container | string | The container name of the azure blob storage | true |
3082-
| endpointUrl | string | A valid endpoint URL | false |
3083-
| storageClass | string | The storage class name of the azure blob storage | false |
3084-
| blockSize | integer | The size of a block of data to save and retrieve from the azure blob storage
3085-
| concurrency | integer | The number of writers to the same blob
3086-
3087-
### <a name="operator-restore-pitr-options-section"></a>pitr subsection
3088-
3089-
| Key | Value type | Description | Required |
3090-
| ---------------- | ----------------- | ---------------------------------------------- | -------- |
3091-
| type | string | The type of PITR recover | true |
3092-
| date | string | The exact date of recovery | true |
3093-
| gtid | string | The exact GTID for PITR recover | true |
3094-
| spec.backupSource| [subdoc](operator.md#operator-restore-backupsource-options-section)| Percona XtraDB Cluster backups section | true |
3095-
| s3 | [subdoc](operator.md#operator-restore-s3-options-section) | Defines configuration for S3 compatible storages | false |
3096-
| azure | [subdoc](operator.md#operator-restore-azure-options-section) | Defines configuration for azure blob storage | false |
3024+
30973025

0 commit comments

Comments
 (0)