Skip to content

Commit 3bdeb02

Browse files
nastena1606nastena1606
authored
K8sPS-801 Fixed the restore to new cluster doc: (#223)
* K8SPS-801 Fixed the restore to new cluster doc: Update the yaml example to define storage settings under spec.backupSource.storage Added prefix to examples Updated PITR to remove non valid example with spec.storageName as this is not supported
1 parent 47b24ca commit 3bdeb02

1 file changed

Lines changed: 42 additions & 157 deletions

File tree

‎docs/backups-restore-to-new-cluster.md‎

Lines changed: 42 additions & 157 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,16 @@ This document focuses on the restore on a new cluster deployed in a different Ku
1111

1212
Select how you wish to restore:
1313

14-
- [Without point-in-time recovery](#restore-from-a-backup-without-point-in-time-recovery)
15-
- [Make a point-in-time recovery](#restore-with-point-in-time-recovery)
16-
- [Restore from an encrypted backup](#restore-from-an-encrypted-backup)
14+
- [Restore from a backup to a new Kubernetes-based environment](#restore-from-a-backup-to-a-new-kubernetes-based-environment)
15+
- [Restore scenarios](#restore-scenarios)
16+
- [Preconditions](#preconditions)
17+
- [Before you begin](#before-you-begin)
18+
- [Restore from a backup without point-in-time recovery](#restore-from-a-backup-without-point-in-time-recovery)
19+
- [Restore with point-in-time recovery](#restore-with-point-in-time-recovery)
20+
- [Restore from an encrypted backup](#restore-from-an-encrypted-backup)
21+
- [View restore details](#view-restore-details)
22+
- [Post-restore steps](#post-restore-steps)
23+
- [Troubleshooting](#troubleshooting)
1724

1825
To restore from a backup, you create a Restore object using a special restore configuration file. The example of such file is [deploy/backup/restore.yaml :octicons-link-external-16:](https://github.com/percona/percona-server-mysql-operator/blob/v{{release}}/deploy/backup/restore.yaml).
1926

@@ -123,6 +130,7 @@ Configure the `PerconaServerMySQLRestore` Custom Resource. Specify the following
123130
credentialsSecret: ps-cluster1-s3-credentials
124131
region: us-west-2
125132
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
133+
prefix: <PREFIX-WHERE-BACKUP-IS-STORED>
126134
...
127135
```
128136

@@ -141,6 +149,7 @@ Configure the `PerconaServerMySQLRestore` Custom Resource. Specify the following
141149
gcs:
142150
bucket: operator-testing
143151
credentialsSecret: ps-cluster1-gcp-credentials
152+
prefix: <PREFIX-WHERE-BACKUP-IS-STORED>
144153
type: gcs
145154
```
146155

@@ -165,16 +174,16 @@ When restoring to a new cluster, the Operator starts a temporary Binlog Server P
165174
166175
Binlog storage currently supports only AWS S3 and S3-compatible services, even when the base backup is stored elsewhere. Read more in the [Point-in-time recovery](backups-pitr.md) documentation.
167176
168-
### Approach 1. Define the storage configuration within the Restore object
177+
Edit the [deploy/backup/restore.yaml](https://github.com/percona/percona-server-mysql-operator/blob/v{{release}}/deploy/backup/restore.yaml) manifest.
169178
170179
1. Specify the following keys:
171180
172181
* Set `spec.clusterName` key to the name of the target cluster to restore the backup on
173182
* Configure the `spec.backupSource` subsection to point to the cloud storage where the backup is stored. This subsection should include:
174183
175184
* A destination key. Take it from the output of the `kubectl get ps-backup` command on the source cluster
176-
* The necessary [storage configuration keys](backups-storage.md#configure-storage-for-backups), just like in the `deploy/cr.yaml` file of the source cluster.
177-
185+
* The necessary [storage configuration keys](backups-storage.md#configure-storage-for-backups), just like in the `deploy/cr.yaml` file of the source cluster. Make sure to set the `prefix` in the restore object to the exact same value used for the backup, so the Operator can find the correct backup location.
186+
178187
* Configure the `pitr` subsection:
179188
180189
* `type` - specify one of the following:
@@ -199,12 +208,14 @@ Binlog storage currently supports only AWS S3 and S3-compatible services, even w
199208
clusterName: ps-cluster1
200209
backupSource:
201210
destination: s3://S3-BUCKET-NAME/BACKUP-NAME
202-
s3:
203-
bucket: S3-BUCKET-NAME
204-
credentialsSecret: ps-cluster1-s3-credentials
205-
region: us-west-2
206-
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
207-
...
211+
storage:
212+
s3:
213+
bucket: S3-BUCKET-NAME
214+
credentialsSecret: ps-cluster1-s3-credentials
215+
region: us-west-2
216+
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
217+
prefix: <PREFIX-WHERE-BACKUP-IS-STORED>
218+
...
208219
type: s3
209220
pitr:
210221
backupSource:
@@ -235,6 +246,7 @@ Binlog storage currently supports only AWS S3 and S3-compatible services, even w
235246
gcs:
236247
bucket: operator-testing
237248
credentialsSecret: ps-cluster1-gcp-credentials
249+
prefix: <PREFIX-WHERE-BACKUP-IS-STORED>
238250
type: gcs
239251
pitr:
240252
backupSource:
@@ -263,12 +275,14 @@ Binlog storage currently supports only AWS S3 and S3-compatible services, even w
263275
clusterName: ps-cluster1
264276
backupSource:
265277
destination: s3://S3-BUCKET-NAME/BACKUP-NAME
266-
s3:
267-
bucket: S3-BUCKET-NAME
268-
credentialsSecret: ps-cluster1-s3-credentials
269-
region: us-west-2
270-
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
271-
...
278+
storage:
279+
s3:
280+
bucket: S3-BUCKET-NAME
281+
credentialsSecret: ps-cluster1-s3-credentials
282+
region: us-west-2
283+
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
284+
prefix: <PREFIX-WHERE-BACKUP-IS-STORED>
285+
...
272286
type: s3
273287
pitr:
274288
backupSource:
@@ -299,6 +313,7 @@ Binlog storage currently supports only AWS S3 and S3-compatible services, even w
299313
gcs:
300314
bucket: operator-testing
301315
credentialsSecret: ps-cluster1-gcp-credentials
316+
prefix: <PREFIX-WHERE-BACKUP-IS-STORED>
302317
type: gcs
303318
pitr:
304319
backupSource:
@@ -321,145 +336,6 @@ Start the restore:
321336
kubectl apply -f deploy/backup/restore.yaml -n $NAMESPACE
322337
```
323338

324-
### Approach 2. The storage is defined on the target
325-
326-
Use this approach when the target cluster already has backup storage configured in its Custom Resource. The storage name must match the source environment and use the same bucket, prefix, and credentials.
327-
328-
However, you must provide the binlog storage configuration within the restore object using `spec.pitr.backupSource.binlogServer`. This ensures the Operator can locate and access the binlogs needed for point-in-time recovery.
329-
330-
1. Specify the following keys:
331-
332-
* Set `spec.clusterName` key to the name of the target cluster to restore the backup to
333-
* Set the `spec.storageName` to the storage name. It must match the name you defined in the target cluster's configuration.
334-
* Configure the `spec.backupSource` subsection with the backup destination. Take it from the output of the `kubectl get ps-backup` command on the source cluster.
335-
336-
* Configure the `pitr` subsection:
337-
338-
* `type` - specify one of the following:
339-
340-
* `date` - to restore up to a specific time
341-
* `gtid` - to restore up to a specific transaction
342-
343-
* For the `type=date` option, set the `date` key in the datetime format.
344-
* For the `type=gtid` option, set the `gtid` to the GTID set to restore the database to. It has the format `source_id:transaction_id`
345-
346-
* `pitr.backupSource.binlogServer` - configure access to the binlog storage on the source cluster. Use the same settings as in the source cluster's `spec.backup.pitr.binlogServer`, including the `prefix` for the binlog folder.
347-
348-
=== "Restore to a timestamp"
349-
350-
=== "S3-compatible storage"
351-
352-
```yaml
353-
apiVersion: ps.percona.com/v1
354-
kind: PerconaServerMySQLRestore
355-
metadata:
356-
name: restore-timestamp
357-
spec:
358-
clusterName: ps-cluster1
359-
storageName: s3-us-west
360-
backupSource:
361-
destination: s3://S3-BUCKET-NAME/BACKUP-NAME
362-
pitr:
363-
backupSource:
364-
binlogServer:
365-
storage:
366-
s3:
367-
bucket: S3-BINLOG-BUCKET-NAME
368-
credentialsSecret: ps-cluster1-s3-credentials
369-
region: us-west-2
370-
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE #Optional for AWS S3
371-
prefix: binlogs
372-
type: date
373-
date: "2026-03-20 09:15:00"
374-
375-
```
376-
377-
=== "Google Cloud Storage"
378-
379-
```yaml
380-
apiVersion: ps.percona.com/v1
381-
kind: PerconaServerMySQLRestore
382-
metadata:
383-
name: restore-timestamp
384-
spec:
385-
clusterName: ps-cluster1
386-
storageName: gcs
387-
backupSource:
388-
destination: gs://BUCKET-NAME/BACKUP-NAME
389-
pitr:
390-
backupSource:
391-
binlogServer:
392-
storage:
393-
s3:
394-
bucket: S3-BINLOG-BUCKET-NAME
395-
credentialsSecret: ps-cluster1-s3-credentials
396-
region: us-west-2
397-
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
398-
prefix: binlogs
399-
type: date
400-
date: "2026-03-20 09:15:00"
401-
```
402-
403-
=== "Restore to a transaction"
404-
405-
=== "S3-compatible storage"
406-
407-
```yaml
408-
apiVersion: ps.percona.com/v1
409-
kind: PerconaServerMySQLRestore
410-
metadata:
411-
name: restore-transaction
412-
spec:
413-
clusterName: ps-cluster1
414-
storageName: s3-us-west
415-
backupSource:
416-
destination: s3://S3-BUCKET-NAME/BACKUP-NAME
417-
pitr:
418-
backupSource:
419-
binlogServer:
420-
storage:
421-
s3:
422-
bucket: S3-BINLOG-BUCKET-NAME
423-
credentialsSecret: ps-cluster1-s3-credentials
424-
region: us-west-2
425-
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
426-
prefix: binlogs
427-
type: gtid
428-
gtid: "cc5e06e7-241e-11f1-a165-522d36bd0c5e:225"
429-
```
430-
431-
=== "Google Cloud Storage"
432-
433-
```yaml
434-
apiVersion: ps.percona.com/v1
435-
kind: PerconaServerMySQLRestore
436-
metadata:
437-
name: restore-transaction
438-
spec:
439-
clusterName: ps-cluster1
440-
storageName: gcs
441-
backupSource:
442-
destination: gs://BUCKET-NAME/BACKUP-NAME
443-
pitr:
444-
backupSource:
445-
binlogServer:
446-
storage:
447-
s3:
448-
bucket: S3-BINLOG-BUCKET-NAME
449-
credentialsSecret: ps-cluster1-s3-credentials
450-
region: us-west-2
451-
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
452-
prefix: binlogs
453-
type: gtid
454-
gtid: "cc5e06e7-241e-11f1-a165-522d36bd0c5e:225"
455-
```
456-
457-
Start the restore:
458-
459-
```bash
460-
kubectl apply -f deploy/backup/restore.yaml -n $NAMESPACE
461-
```
462-
463339
## Restore from an encrypted backup
464340

465341
Configure the `PerconaServerMySQLRestore` Custom Resource. Specify the following keys:
@@ -522,6 +398,15 @@ Configure the `PerconaServerMySQLRestore` Custom Resource. Specify the following
522398
credentialsSecret: ps-cluster1-s3-credentials
523399
region: us-west-2
524400
pitr:
401+
backupSource:
402+
binlogServer:
403+
storage:
404+
s3:
405+
bucket: S3-BINLOG-BUCKET-NAME
406+
credentialsSecret: ps-cluster1-s3-credentials
407+
region: us-west-2
408+
endpointUrl: https://URL-OF-THE-S3-COMPATIBLE-STORAGE
409+
prefix: binlogs
525410
type: date
526411
date: "{{year}}-05-01T15:30:00Z"
527412
```

0 commit comments

Comments
 (0)