diff --git a/content/rancher/v2.x/en/backups/configuration/restore-config/_index.md b/content/rancher/v2.x/en/backups/configuration/restore-config/_index.md index fe0054e693e..ba007bc362c 100644 --- a/content/rancher/v2.x/en/backups/configuration/restore-config/_index.md +++ b/content/rancher/v2.x/en/backups/configuration/restore-config/_index.md @@ -6,36 +6,60 @@ weight: 2 The Restore custom resource accepts the following fields: -- [BackupFilename](#backupfilename) -- [EncryptionConfigName](#encryptionconfigname) +- [Backup Source](#backup-source) + - [Getting the Backup Filename from S3](#getting-the-backup-filename-from-s3) +- [Encryption](#encryption) - [StorageLocation](#storagelocation) +- [Prune during restore](#prune-during-restore) -### BackupFilename + +### Backup Source +Provide details of the backup file and its storage location, which the operator will then use to perform the restore. Select from the following options to provide these details + +* **An existing backup config**: Selecting this option will populate the **Target Backup** dropdown with the Backups available in this cluster. Select the Backup from the dropdown, and that will fill out the **Backup Filename** field for you, and will also pass the backup source information from the selected Backup to the operator. + +If the Backup custom resource does not exist in the cluster, you need to get the exact filename and provide the backup source details with either of the following options: + +* **The default storage target**: Select this option if you are restoring from a backup file that exists in the default storage location configured at the operator-level. The operator-level configuration is the storage location that was configured when the `rancher-backup` operator was installed or upgraded. Provide the exact filename in the **Backup Filename** field. +* **An S3-compatible object store**: Select this option if no default storage location is configured at the operator-level, OR if the backup file exists in a different S3 bucket than the one configured as the default storage location. Provide the exact filename in the **Backup Filename** field. Refer [this section](#getting-the-backup-filename-from-s3) for exact steps on getting the backup filename from s3. Fill in all the details for the S3 compatible object store. Its fields are exactly same as ones for the `backup.StorageLocation` configuration in the [Backup custom resource.](../../configuration/backup-config/#storagelocation) + +### Encryption + +If the backup was created with encryption enabled, its file will have `.enc` suffix. Choosing such a Backup, or providing a backup filename with `.enc` suffix will display another dropdown named **Encryption Config Secret**. + +The Secret selected from this dropdown must have the same contents as the one used for the Backup custom resource while performing the backup. If the encryption configuration doesn't match, the restore will fail + +The `Encryption Config Secret` dropdown will filter out and list only those Secrets that have this exact key + +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `encryptionConfigSecretName` | Provide the name of the Secret from `cattle-resources-system` namespace, that contains the encryption config file. | + +> **Important** +This field should only be set if the backup was created with encryption enabled. Providing the incorrect encryption config will cause the restore to fail. + +### Prune during restore + +* **Prune**: In order to fully restore Rancher from a backup, and to go back to the exact state it was at when the backup was performed, we need to delete any additional resources that were created by Rancher after the backup was taken. The operator does so if the **Prune** flag is enabled. Prune is enabled by default and it is recommended to keep it enabled. +* **Delete Timeout**: This is the amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again. + +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `prune` | Delete the resources managed by Rancher that are not present in the backup (Recommended). | +| `deleteTimeoutSeconds` | Amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again. | + +### Getting the Backup Filename from S3 This is the name of the backup file that the `rancher-backup` operator will use to perform the restore. -This field is required. - To obtain this file name from S3, go to your S3 bucket (and folder if it was specified while performing backup). -Copy the filename and store it in your Restore custom resource. So for instance, +Copy the filename and store it in your Restore custom resource. So assuming the name of your backup file is `backupfile`, -- If your bucket name is `s3bucket` and no folder was specified, the `backupFilename` to use will be the `Key` value from S3. -- If your bucket name is `s3bucket` and the base folder is`s3folder`, the `Key` will be `s3Folder/backupfile`, so the `backupFilename` to use is only `backupfile` . -- If there is a subfolder inside `s3Folder` called `s3sub`, and that has your backup file named `backupfileSub`, then the `backupFilename` to use is `s3sub/backupfileSub`. +- If your bucket name is `s3bucket` and no folder was specified, then the `backupFilename` to use will be `backupfile`. +- If your bucket name is `s3bucket` and the base folder is`s3folder`, the `backupFilename` to use is only `backupfile` . +- If there is a subfolder inside `s3Folder` called `s3sub`, and that has your backup file, then the `backupFilename` to use is `s3sub/backupfile`. -### EncryptionConfigName - -This is encryption configuration secret. It must be the same secret as the one used for the Backup custom resource while performing the backup. If the encryption configuration doesn't match, the restore will fail. - -This field is optional. - -### StorageLocation - -This field is optional. - -Its fields are exactly same as ones for the `backup.StorageLocation` configuration in the [Backup custom resource.](../../configuration/backup-config/#storagelocation) - -If the StorageLocation is specified, the operator will retrieve the backup location from that particular S3 bucket. If not specified, operator will try to find this file in the operator-level S3 store, and in the operator-level PVC store. - -The operator-level configuration is the storage location that was configured when the `rancher-backup` operator was installed or upgraded. \ No newline at end of file +| YAML Directive Name | Description | +| ---------------- | ---------------- | +| `backupFilename` | This is the name of the backup file that the `rancher-backup` operator will use to perform the restore. | diff --git a/content/rancher/v2.x/en/backups/restoring-rancher/_index.md b/content/rancher/v2.x/en/backups/restoring-rancher/_index.md index 13ba992265f..05a83055676 100644 --- a/content/rancher/v2.x/en/backups/restoring-rancher/_index.md +++ b/content/rancher/v2.x/en/backups/restoring-rancher/_index.md @@ -3,56 +3,44 @@ title: Restoring Rancher weight: 2 --- -A restore is performed by creating a Restore custom resource. +A restore is performed by creating a Restore custom resource. + +> **Important** +* Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.](../migrating-rancher) +* While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore. ### 1. Create the Restore Custom Resource 1. In the **Cluster Explorer,** go to the dropdown menu in the upper left corner and click **Rancher Backups.** 1. Click **Restore.** -1. Create the Restore with the form, or with YAML. For this example, we can use **Create > Create from YAML.** +1. Create the Restore with the form, or with YAML. For creating the Restore resource using form, refer to the [configuration reference](../configuration/restore-config) and to the [examples.](../examples/#restore) +1. For using the YAML editor, we can click **Create > Create from YAML.** Enter the Restore YAML. -Create a Restore custom resource such as the following. + ```yaml + apiVersion: resources.cattle.io/v1 + kind: Restore + metadata: + name: restore-migration + spec: + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + encryptionConfigSecretName: encryptionconfig + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rancher-backups + folder: rancher + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + ``` -The `prune` directive needs to be set to false so that the secret associated with the operator's service account will not get deleted. + For help configuring the Restore, refer to the [configuration reference](../configuration/restore-config) and to the [examples.](../examples/#restore) -Replace the `backupFilename` and `storageLocation` with your own information. +1. Click **Create.** + +**Result:** The rancher-operator scales down the rancher deployment during restore. Once the restore completes, the operator scales back up the rancher deployment. So rancher will be unavailable for the duration of restore. To check how the restore is progressing, you can check the logs of the operator. Follow these steps to get the logs: ```yaml -apiVersion: resources.cattle.io/v1 -kind: Restore -metadata: - name: restore-migration -spec: - backupFilename: b-eks-2-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07#27#09Z.tar.gz - prune: false - storageLocation: - s3: - credentialSecretName: s3-creds - credentialSecretNamespace: default - bucketName: backup-test - folder: ecm1 - region: us-west-2 - endpoint: s3.us-west-2.amazonaws.com -``` - -**Result:** Helm 3 stores the chart release as a Kubernetes [Secret.](https://kubernetes.io/docs/concepts/configuration/secret/) When the restore is performed, the Rancher chart release in the backup is created in the cluster where the restore is performed. Now Rancher does not need to be reinstalled. It just needs to be upgraded. - -### 2. Install cert-manager - -Follow the steps to [install cert-manager]({{}}/rancher/v2.x/en/installation/install-rancher-on-k8s/install/#5-install-cert-manager) in the documentation about installing cert-manager on Kubernetes. - -### 3. Upgrade the Rancher Release - -If Rancher was scaled down when the backup was created, you can set the size of the deployment through the `helm upgrade` command. - -``` -helm upgrade rancher rancher-alpha/rancher \ - --version 2.5.0-alpha1 \ - --namespace cattle-system \ - -set hostname= \ - --set rancherImageTag=master-head -``` - -For more information about Rancher image tags, see [this page.]({{}}/rancher/v2.x/en/installation/resources/choosing-version/) - -**Result:** Rancher is restored. \ No newline at end of file +kubectl get pods -n cattle-resources-system +kubectl logs -n cattle-resources-system -f +``` \ No newline at end of file