Update migration docs

2026-09-23 03:28:07 +00:00 · 2020-10-05 06:01:11 -07:00
parent a423a989d3
commit 5e63742480
11 changed files with 78 additions and 43 deletions
@@ -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
@@ -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
 ```
@@ -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
@@ -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
@@ -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]({{<baseurl>}}/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=<same hostname as first Rancher server> \
-  --set rancherImageTag=master-head
 ```
@@ -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