diff --git a/docs/modules/ROOT/examples/hazelcast-persistence-restore-local.yaml b/docs/modules/ROOT/examples/hazelcast-persistence-restore-local.yaml new file mode 100644 index 00000000..660eee59 --- /dev/null +++ b/docs/modules/ROOT/examples/hazelcast-persistence-restore-local.yaml @@ -0,0 +1,19 @@ +apiVersion: hazelcast.com/v1alpha1 +kind: Hazelcast +metadata: + name: hazelcast <1> +spec: + clusterSize: 3 + repository: 'docker.io/hazelcast/hazelcast-enterprise' + licenseKeySecretName: hazelcast-license-key + customConfigCmName: mapCustomConfig <2> + persistence: + pvc: + accessModes: ["ReadWriteOnce"] + requestStorage: 20Gi + restore: + localConfig: + pvcNamePrefix: "hot-restart-persistence" <3> + baseDir: "base" <4> + backupDir: "backup" <5> + backupFolder: "backup-1709045128548" <6> diff --git a/docs/modules/ROOT/examples/pod-local-pvc-content.yaml b/docs/modules/ROOT/examples/pod-local-pvc-content.yaml new file mode 100644 index 00000000..e6836c4e --- /dev/null +++ b/docs/modules/ROOT/examples/pod-local-pvc-content.yaml @@ -0,0 +1,16 @@ +apiVersion: v1 +kind: Pod +metadata: + name: list-content-pod +spec: + containers: + - name: list-content-container + image: busybox + command: ["/bin/sh", "-c", "tree /data/persistence"] <1> + volumeMounts: + - name: pv-storage + mountPath: /data/persistence <2> + volumes: + - name: pv-storage + persistentVolumeClaim: + claimName: hot-restart-persistence-hazelcast-0 <3> \ No newline at end of file diff --git a/docs/modules/ROOT/pages/backup-restore.adoc b/docs/modules/ROOT/pages/backup-restore.adoc index 88579d0c..673e7874 100644 --- a/docs/modules/ROOT/pages/backup-restore.adoc +++ b/docs/modules/ROOT/pages/backup-restore.adoc @@ -6,7 +6,10 @@ This topic assumes that you know about Persistence in Hazelcast. To learn about Persistence, see the xref:hazelcast:storage:persistence.adoc[Platform documentation]. -There are two options for a backup: local and external. Local backups are kept in volume and never moved anywhere whereas external backups are moved into buckets provided by the user. +Backups can be either of the following: + +- Local: Local backups are kept in volume and never moved anywhere. +- External: External backups are moved into buckets provided by the user. TIP: For a working example, see link:https://docs.hazelcast.com/tutorials/hazelcast-platform-operator-external-backup-restore[this tutorial]. @@ -23,8 +26,8 @@ include::ROOT:example$/hazelcast-persistence.yaml[] <1> <>. <2> Size of the PersistentVolumeClaim (PVC) where Hazelcast data is persisted. <3> Agent responsible for moving data from the local storage to external buckets. - The agent configuration is optional. If you enable `persistence` and do not pass the agent configuration, Hazelcast Platform Operator - uses the latest agent version that is compatible with its version. +The agent configuration is optional. If you enable `persistence` and do not pass the agent configuration, Hazelcast Platform Operator +uses the latest agent version that is compatible with its version. NOTE: Make sure to calculate the total disk space that you will use. The total used disk space may be larger than the size of in-memory data, depending on how many <> you take. @@ -153,9 +156,11 @@ 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`. +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`. When this restore mechanism is used, the Restore Agent container is deployed with the Hazelcast container in the same Pod. The agent starts as an initContainer before the Hazelcast container. @@ -168,8 +173,36 @@ include::ROOT:example$/hazelcast-persistence-restore-cr-name.yaml[] <1> `HotBackup` resource name used for restore. The backup folder name will be taken from the `HotBackup` resource. <2> Agent responsible for restoring data from the local storage. - The agent configuration is optional. If you give `restore` under `persistence` and do not pass the agent configuration, Hazelcast Platform Operator - uses the latest agent version that is compatible with its version. +The agent configuration is optional. If you give `restore` under `persistence` and do not pass the agent configuration, Hazelcast Platform Operator +uses the latest agent version that is compatible with its version. + +=== 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 -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`. Note: You can only use a local backup once to restore a cluster. It is recommended to backup externally if you need to persistently restore a backup across clusters. @@ -194,8 +227,8 @@ include::ROOT:example$/hazelcast-persistence-restore-external.yaml[] <1> Bucket URI where backup data will be restored from. <2> Name of the secret with credentials for accessing the given bucket URI. <3> Agent which is responsible for restoring data from the external storage. - The agent configuration is optional. If you provide `restore` under `persistence` and do not pass the agent configuration, Hazelcast Platform Operator - uses the latest agent version that is compatible with its version. +The agent configuration is optional. If you provide `restore` under `persistence` and do not pass the agent configuration, Hazelcast Platform Operator +uses the latest agent version that is compatible with its version. -- HotBackup resource name:: @@ -208,8 +241,8 @@ include::ROOT:example$/hazelcast-persistence-restore-cr-name.yaml[] <1> `HotBackup` resource name used for the restore. The bucket URI and secret are taken from the `HotBackup` resource. <2> Agent responsible for restoring data from external storage. - The agent configuration is optional. If you provide `restore` under `persistence` and do not pass the agent configuration, Hazelcast Platform Operator - uses the latest agent version that is compatible with its version. +The agent configuration is optional. If you provide `restore` under `persistence` and do not pass the agent configuration, Hazelcast Platform Operator +uses the latest agent version that is compatible with its version. -- ====