Skip to content

Commit

Permalink
improve docs for localConfig usage (#191)
Browse files Browse the repository at this point in the history
  • Loading branch information
Kutluhan Metin authored Apr 15, 2024
1 parent 62a554e commit c6522d6
Showing 1 changed file with 31 additions and 30 deletions.
61 changes: 31 additions & 30 deletions docs/modules/ROOT/pages/backup-restore.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -156,8 +156,6 @@ hot-backup Success

== Restoring from Local Backups

=== Restoring from Local Backups Created by Hot Backup Custom Resource

To restore a cluster from local backups, you can directly reapply the `Hazelcast` resource, which gives the cluster access to the PVCs that contain the persisted data. This will restore the Hazelcast cluster from existing `hot-restart` folders.

Or, to restore from local backups that you have taken using the `HotBackup` resource, give the `HotBackup` resource name in the restore configuration. For the restore to work correctly, make sure the status of the `HotBackup` resource is `Success`.
Expand All @@ -179,34 +177,6 @@ uses the latest agent version that is compatible with its version.

WARNING: You can use a local backup only once to restore a cluster. We recommend you backup externally if you need to persistently restore a backup across the clusters.

=== Restoring from Local Backups Created with other Methods

To restore from local backups that were not created by the HotBackup resource, configure `localConfig`.

[source,yaml,subs="attributes+"]
----
include::ROOT:example$/hazelcast-persistence-restore-local.yaml[]
----

<1> The name of the Hazelcast custom resource for both backup and restore must be the same. If the Hazelcast custom resource name is different, the restore fails.
<2> If you configured maps with persistence, you must create them while creating the Hazelcast CR. To create them while creating the Hazelcast CR, you must use xref:custom-config.adoc[Custom Config]. You cannot apply the Hazelcast CR and then the Map CRs.
<3> `pvcNamePrefix` is the prefix of the existing PVCs. It can be set to `persistence` or `hot-restart-persistence` depending on the installation method of the old cluster. In different versions of Hazelcast Helm Chart and Hazelcast Platform Operator, these values are used by default. Run the `kubect get pvc` command to decide which setting best suits your requirements.
<4> `baseDir` is the root directory for persistence.
<5> `backupDir` is the directory that contains a backupFolder for each available backup.
<6> `backupFolder` is the directory containing the specific backup for the restore.

TIP: To find the `backupFolder` value, you can run `kubectl exec -it <hazelcast-custom-resource-name> -c hazelcast -- /bin/bash` and list the contents of your in your existing installation. If you already deleted your installation, you can run a simple pod that lists the contents of the PVC and checks its logs. This lists the folder structure of the specified PVC. For example:

[source,yaml,subs="attributes+"]
----
include::ROOT:example$/pod-local-pvc-content.yaml[]
----
<1> Replace `/data/persistence` with the path to your PV, which is mounted inside the container.
<2> Replace `/data/persistence` with the correct mountPath specified in PV.
<3> Replace with the name of the one of the PVCs, which is mounted to the cluster from which the backup is taken.

NOTE: Agent copies the backup to be restored from `{baseDir}/{backupDir}/{backupFolder}` to `/data/persistence/base-dir`.

== Restoring from External Backups

To restore a cluster from external backups, you can either set up the bucket configuration or give the `HotBackup` resource name that you used to trigger the external backup. In either case, the backup is restored from the external bucket.
Expand Down Expand Up @@ -248,6 +218,37 @@ uses the latest agent version that is compatible with its version.
====

== Restoring from Persistent Volumes

To restore from local backups that are in an existing link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/[Persistent Volume], configure `localConfig`.

[source,yaml,subs="attributes+"]
----
include::ROOT:example$/hazelcast-persistence-restore-local.yaml[]
----

<1> To successfully attach existing PVCs to the newly created cluster:

- If the older cluster was created by the Hazelcast Platform Operator, the name of both the backup and restore Hazelcast custom resources must be the same.
- If the older cluster was created by the Hazelcast Helm Chart, the name of the new CR must be in the following format: `<name>-hazelcast-persistence`. For example, assuming that the older cluster was installed with `helm install hz hazelcast/hazelcast-enterprise` command, the new CR name must be `hz-hazelcast-enterprise`.
<2> If you configured maps with persistence, you must create them while creating the Hazelcast CR. To create them while creating the Hazelcast CR, you must use xref:custom-config.adoc[Custom Config]. You cannot apply the Hazelcast CR and then the Map CRs.
<3> `pvcNamePrefix` is the prefix of the existing PVCs. It can be set to `persistence` or `hot-restart-persistence` depending on the installation method of the old cluster. In different versions of Hazelcast Helm Chart and Hazelcast Platform Operator, these values are used by default. Run the `kubect get pvc` command to decide which setting best suits your requirements.
<4> `baseDir` is the root directory for persistence.
<5> `backupDir` is the directory that contains a backupFolder for each available backup.
<6> `backupFolder` is the directory containing the specific backup for the restore.

TIP: To find the `backupFolder` value, you can run `kubectl exec -it <hazelcast-custom-resource-name> -c hazelcast -- /bin/bash` and list the contents of your in your existing installation. If you already deleted your installation, you can run a simple pod that lists the contents of the PVC and checks its logs. This lists the folder structure of the specified PVC. For example:

[source,yaml,subs="attributes+"]
----
include::ROOT:example$/pod-local-pvc-content.yaml[]
----
<1> Replace `/data/persistence` with the path to your PV, which is mounted inside the container.
<2> Replace `/data/persistence` with the correct mountPath specified in PV.
<3> Replace with the name of the one of the PVCs, which is mounted to the cluster from which the backup is taken.

NOTE: Agent copies the backup to be restored from `{baseDir}/{backupDir}/{backupFolder}` to `/data/persistence/base-dir`.

== Configuring Persistence

=== Data Recovery Timeout
Expand Down

0 comments on commit c6522d6

Please sign in to comment.