diff --git a/assets/img/rancher/backup_restore/restore/default.png b/assets/img/rancher/backup_restore/restore/default.png new file mode 100644 index 00000000000..eabf5015ae3 Binary files /dev/null and b/assets/img/rancher/backup_restore/restore/default.png differ diff --git a/assets/img/rancher/backup_restore/restore/encryption.png b/assets/img/rancher/backup_restore/restore/encryption.png new file mode 100644 index 00000000000..4949e8d1f37 Binary files /dev/null and b/assets/img/rancher/backup_restore/restore/encryption.png differ diff --git a/assets/img/rancher/backup_restore/restore/existing.png b/assets/img/rancher/backup_restore/restore/existing.png new file mode 100644 index 00000000000..e9bd6db38d3 Binary files /dev/null and b/assets/img/rancher/backup_restore/restore/existing.png differ diff --git a/assets/img/rancher/backup_restore/restore/restore.png b/assets/img/rancher/backup_restore/restore/restore.png new file mode 100644 index 00000000000..dc6541b7810 Binary files /dev/null and b/assets/img/rancher/backup_restore/restore/restore.png differ diff --git a/assets/img/rancher/backup_restore/restore/s3store.png b/assets/img/rancher/backup_restore/restore/s3store.png new file mode 100644 index 00000000000..493364deaed Binary files /dev/null and b/assets/img/rancher/backup_restore/restore/s3store.png differ diff --git a/content/rancher/v2.x/en/backups/back-up-rancher/_index.md b/content/rancher/v2.x/en/backups/back-up-rancher/_index.md index 7f135ee9041..f1097411891 100644 --- a/content/rancher/v2.x/en/backups/back-up-rancher/_index.md +++ b/content/rancher/v2.x/en/backups/back-up-rancher/_index.md @@ -3,7 +3,11 @@ title: Backing up Rancher weight: 1 --- -In this section, you'll learn how to back up Rancher. +In this section, you'll learn how to back up Rancher running on any Kubernetes cluster. To backup Rancher installed with Docker, refer the instructions for [single node backups](../legacy/backup/single-node-backups/) + +### Prerequisites + +Rancher version must be v2.5.0 and up ### 1. Install the `rancher-backup` operator @@ -62,5 +66,5 @@ Rancher Backup & Restore is a cluster-admin only feature and available only for Which means only the rancher admins, and local cluster’s cluster-owner can: * Install the Chart -* See the navigation links for Backup and Restore CRDs (there is no overview page for this feature, after the chart is installed there’s a separate navigation link for its CRDs) +* See the navigation links for Backup and Restore CRDs * Perform a backup or restore by creating a Backup CR and Restore CR respectively, list backups/restores performed so far \ No newline at end of file diff --git a/content/rancher/v2.x/en/backups/configuration/backup-config/_index.md b/content/rancher/v2.x/en/backups/configuration/backup-config/_index.md index 796d69ab114..ee44cb76a1d 100644 --- a/content/rancher/v2.x/en/backups/configuration/backup-config/_index.md +++ b/content/rancher/v2.x/en/backups/configuration/backup-config/_index.md @@ -4,7 +4,7 @@ shortTitle: Backup weight: 1 --- -The Backup Create page lets you configure a schedule, encryption and storage location for your backups. +The Backup Create page lets you configure a schedule, enable encryption and specify the storage location for your backups. {{< img "/img/rancher/backup_restore/backup/backup.png" "">}} @@ -109,8 +109,8 @@ The S3 storage location contains the following configuration fields: s3: credentialSecretName: s3-creds credentialSecretNamespace: default - bucketName: rajashree-backup-test - folder: ecm1 + bucketName: rancher-backups + folder: rancher region: us-west-2 endpoint: s3.us-west-2.amazonaws.com ``` 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 ba007bc362c..91e17a171da 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 @@ -4,7 +4,9 @@ shortTitle: Restore weight: 2 --- -The Restore custom resource accepts the following fields: +The Restore Create page lets you provide details of the backup to restore from + +{{< img "/img/rancher/backup_restore/restore/restore.png" "">}} - [Backup Source](#backup-source) - [Getting the Backup Filename from S3](#getting-the-backup-filename-from-s3) @@ -16,17 +18,28 @@ The Restore custom resource accepts the following fields: ### 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 + +{{< img "/img/rancher/backup_restore/restore/existing.png" "">}} + * **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. +{{< img "/img/rancher/backup_restore/restore/default.png" "">}} + +* **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. + +{{< img "/img/rancher/backup_restore/restore/s3store.png" "">}} + * **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**. +{{< img "/img/rancher/backup_restore/restore/encryption.png" "">}} + 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 diff --git a/content/rancher/v2.x/en/backups/examples/_index.md b/content/rancher/v2.x/en/backups/examples/_index.md index c6fff372088..b73e0405afd 100644 --- a/content/rancher/v2.x/en/backups/examples/_index.md +++ b/content/rancher/v2.x/en/backups/examples/_index.md @@ -37,10 +37,10 @@ This section contains example Backup custom resources. apiVersion: resources.cattle.io/v1 kind: Backup metadata: - name: test-s3-def-backup + name: default-location-encrypted-backup spec: resourceSetName: rancher-resource-set - encryptionConfigSecretName: test-encryptionconfig + encryptionConfigSecretName: encryptionconfig ``` ### Recurring Backup in the Default Location @@ -49,11 +49,11 @@ spec: apiVersion: resources.cattle.io/v1 kind: Backup metadata: - name: test-default-location-recurring-backup + name: default-location-recurring-backup spec: resourceSetName: rancher-resource-set - schedule: "@every 2m" - retentionCount: 3 + schedule: "@every 1h" + retentionCount: 10 ``` ### Encrypted Recurring Backup in the Default Location @@ -62,11 +62,11 @@ spec: apiVersion: resources.cattle.io/v1 kind: Backup metadata: - name: test-s3-recurring-backup + name: default-enc-recurring-backup spec: - resourceSetName: ecm-resource-set - encryptionConfigSecretName: test-encryptionconfig - schedule: "@every 1m" + resourceSetName: rancher-resource-set + encryptionConfigSecretName: encryptionconfig + schedule: "@every 1h" retentionCount: 3 ``` @@ -76,7 +76,7 @@ spec: apiVersion: resources.cattle.io/v1 kind: Backup metadata: - name: minio-backup-demo + name: minio-backup spec: storageLocation: s3: @@ -86,7 +86,7 @@ spec: endpoint: minio.xip.io endpointCA: LS0tLS1CRUdJTi3VUFNQkl5UUT.....pbEpWaVzNkRS0tLS0t resourceSetName: rancher-resource-set - encryptionConfigSecretName: test-encryptionconfig + encryptionConfigSecretName: encryptionconfig ``` ### Backup in S3 Using AWS Credential Secret @@ -95,18 +95,18 @@ spec: apiVersion: resources.cattle.io/v1 kind: Backup metadata: - name: s3-backup-demo + name: s3-backup spec: storageLocation: s3: credentialSecretName: s3-creds credentialSecretNamespace: default - bucketName: rajashree-backup-test + bucketName: rancher-backups folder: ecm1 region: us-west-2 endpoint: s3.us-west-2.amazonaws.com resourceSetName: rancher-resource-set - encryptionConfigSecretName: test-encryptionconfig + encryptionConfigSecretName: encryptionconfig ``` ### Recurring Backup in S3 Using AWS Credential Secret @@ -115,20 +115,20 @@ spec: apiVersion: resources.cattle.io/v1 kind: Backup metadata: - name: test-s3-recurring-backup + name: s3-recurring-backup spec: storageLocation: s3: credentialSecretName: s3-creds credentialSecretNamespace: default - bucketName: rajashree-backup-test + bucketName: rancher-backups folder: ecm1 region: us-west-2 endpoint: s3.us-west-2.amazonaws.com resourceSetName: rancher-resource-set - encryptionConfigSecretName: test-encryptionconfig - schedule: "@every 2m" - retentionCount: 3 + encryptionConfigSecretName: encryptionconfig + schedule: "@every 1h" + retentionCount: 10 ``` ### Backup from EC2 Nodes with IAM Permission to Access S3 @@ -139,16 +139,16 @@ This example shows that the AWS credential secret does not have to be provided t apiVersion: resources.cattle.io/v1 kind: Backup metadata: - name: s3-backup-demo + name: s3-iam-backup spec: storageLocation: s3: - bucketName: rajashree-backup-test + bucketName: rancher-backups folder: ecm1 region: us-west-2 endpoint: s3.us-west-2.amazonaws.com resourceSetName: rancher-resource-set - encryptionConfigSecretName: test-encryptionconfig + encryptionConfigSecretName: encryptionconfig ``` # Restore @@ -161,9 +161,9 @@ This section contains example Restore custom resources. apiVersion: resources.cattle.io/v1 kind: Restore metadata: - name: restore-pvc-demo + name: restore-default spec: - backupFilename: test-default-location-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-29-54-07-00.tar.gz + backupFilename: default-location-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-29-54-07-00.tar.gz # encryptionConfigSecretName: test-encryptionconfig ``` @@ -174,13 +174,13 @@ kind: Restore metadata: name: restore-migration spec: - backupFilename: b-eks-2-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07#27#09Z.tar.gz + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz prune: false storageLocation: s3: credentialSecretName: s3-creds credentialSecretNamespace: default - bucketName: rajashree-backup-test + bucketName: rancher-backups folder: ecm1 region: us-west-2 endpoint: s3.us-west-2.amazonaws.com @@ -192,10 +192,10 @@ spec: apiVersion: resources.cattle.io/v1 kind: Restore metadata: - name: restore-s3-demo + name: restore-encrypted spec: - backupFilename: default-test-s3-def-backup-c583d8f2-6daf-4648-8ead-ed826c591471-2020-08-24T20#47#05Z.tar.gz - encryptionConfigSecretName: test-encryptionconfig + backupFilename: default-test-s3-def-backup-c583d8f2-6daf-4648-8ead-ed826c591471-2020-08-24T20-47-05Z.tar.gz + encryptionConfigSecretName: encryptionconfig ``` ### Restore an Encrypted Backup from Minio @@ -206,7 +206,7 @@ kind: Restore metadata: name: restore-minio spec: - backupFilename: default-minio-backup-demo-aa5c04b7-4dba-4c48-9ac4-ab7916812eaa-2020-08-30T13#18#17-07#00.tar.gz + backupFilename: default-minio-backup-demo-aa5c04b7-4dba-4c48-9ac4-ab7916812eaa-2020-08-30T13-18-17-07-00.tar.gz storageLocation: s3: credentialSecretName: minio-creds @@ -230,7 +230,7 @@ spec: s3: credentialSecretName: s3-creds credentialSecretNamespace: default - bucketName: rajashree-backup-test + bucketName: rancher-backups folder: ecm1 region: us-west-2 endpoint: s3.us-west-2.amazonaws.com diff --git a/content/rancher/v2.x/en/backups/migrating-rancher/_index.md b/content/rancher/v2.x/en/backups/migrating-rancher/_index.md index 191521059af..75534c6e914 100644 --- a/content/rancher/v2.x/en/backups/migrating-rancher/_index.md +++ b/content/rancher/v2.x/en/backups/migrating-rancher/_index.md @@ -8,6 +8,8 @@ If you are migrating Rancher to a new Kubernetes cluster, you don't need to inst ### Prerequisites These instructions assume you have [created a backup](../back-up-rancher) and you have already installed a new Kubernetes cluster where Rancher will be deployed. +It is necessary to use the same hostname that was set as the server URL in the first cluster. +Rancher version must be v2.5.0 and up Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes clusters such as Amazon EKS clusters. For help installing Kubernetes, refer to the documentation of the Kubernetes distribution. One of Rancher's Kubernetes distributions may also be used: @@ -35,8 +37,9 @@ kind: Restore metadata: name: restore-migration spec: - backupFilename: b-eks-2-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07#27#09Z.tar.gz + backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz prune: false + encryptionConfigSecretName: encryptionconfig storageLocation: s3: credentialSecretName: s3-creds @@ -47,6 +50,15 @@ spec: endpoint: s3.us-west-2.amazonaws.com ``` +> **Important:** The field `encryptionConfigSecretName` must be set only if your backup was created with encryption enabled. Provide the name of the Secret containing the encryption config file. If you only have the encryption config file, but don't have a secret created with it in this cluster, use the following steps to create the secret: +1. The encryption configuration file must be named `encryption-provider-config.yaml`, and the `--from-file` flag must be used to create this secret. So save your `EncryptionConfiguration` in a file called `encryption-provider-config.yaml` and run this command: + +``` +kubectl create secret generic encryptionconfig \ + --from-file=./encryption-provider-config.yaml \ + -n cattle-resources-system +``` + Then apply the resource: ``` @@ -59,10 +71,10 @@ Follow the steps to [install cert-manager]({{}}/rancher/v2.x/en/install ### 4. Bring up Rancher with Helm +Use the same version of Helm to install Rancher, that was used on the first cluster. + ``` -helm upgrade rancher rancher-alpha/rancher \ - --version 2.5.0-alpha1 \ +helm install rancher rancher-latest/rancher \ --namespace cattle-system \ --set hostname= \ - --set rancherImageTag=master-head ``` \ No newline at end of file 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 05a83055676..6c050fbedd9 100644 --- a/content/rancher/v2.x/en/backups/restoring-rancher/_index.md +++ b/content/rancher/v2.x/en/backups/restoring-rancher/_index.md @@ -38,7 +38,13 @@ A restore is performed by creating a Restore custom resource. 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: +**Result:** The rancher-operator scales down the rancher deployment during restore, and scales it back up once the restore completes. The resources are restored in this order: + +1. Custom Resource Definitions (CRDs) +2. Cluster-scoped resources +3. Namespaced resources + +To check how the restore is progressing, you can check the logs of the operator. Follow these steps to get the logs: ```yaml kubectl get pods -n cattle-resources-system