From facdafd00e2a3a2129f820fa2c5dd43a2461c4d4 Mon Sep 17 00:00:00 2001 From: dkeightley Date: Tue, 27 Sep 2022 14:52:26 +1300 Subject: [PATCH 01/18] Update b64 example, add syntax highlighting, revise helm install steps --- .../migrate-rancher-to-new-cluster.md | 181 ++++++++++-------- .../backup-configuration.md | 17 +- 2 files changed, 118 insertions(+), 80 deletions(-) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index bb7af198240..f7fc4f82fd0 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -23,18 +23,34 @@ Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes - [K3s Kubernetes installation docs](https://rancher.com/docs/k3s/latest/en/installation/) ### 1. Install the rancher-backup Helm chart -Install version 2.x.x of the rancher-backup chart. The following assumes a connected environment with access to DockerHub: -``` -helm repo add rancher-charts https://charts.rancher.io -helm repo update -helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace --version $CHART_VERSION -helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system --version $CHART_VERSION -``` +Install the [rancher-backup chart](https://github.com/rancher/backup-restore-operator/tags), using a version in the 2.x.x major version range: -For an **air-gapped environment**, use the option below to pull the `backup-restore-operator` image from your private registry when installing the rancher-backup-crd helm chart. -``` ---set image.repository $REGISTRY/rancher/backup-restore-operator -``` + 1. Add the helm repository: + ```bash + helm repo add rancher-charts https://charts.rancher.io + helm repo update + ``` + 1. Select and set `CHART_VERSION` variable with a 2.x.x rancher-backup release version: + ```bash + helm search repo --versions rancher-charts/rancher-backup + CHART_VERSION=<2.x.x> + ``` + 2. Install the charts: + ```bash + helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace --version $CHART_VERSION + helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system --version $CHART_VERSION + ``` + + :::note + + The above assumes an environment with outbound connectivity to Docker Hub + + For an **air-gapped environment**, use the helm value below to pull the `backup-restore-operator` image from your private registry when installing the rancher-backup helm chart. + ```bash + --set image.repository $REGISTRY/rancher/backup-restore-operator + ``` + + ::: ### 2. Restore from backup using a Restore custom resource @@ -45,86 +61,80 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo 1. Update the default `resourceSet` to collect the CRDs with the apiVersion v1. 1. Update the default `resourceSet` and the client to use the new APIs internally, with `apiextensions.k8s.io/v1` as the replacement. -- Note that when making or restoring backups for v1.22, the Rancher version and the local cluster's Kubernetes version should be the same. The Kubernetes version should be considered when restoring a backup since the supported apiVersion in the cluster and in the backup file could be different. + :::note + + When making or restoring backups for v1.22, the Rancher version and the local cluster's Kubernetes version should be the same. The Kubernetes version should be considered when restoring a backup since the supported apiVersion in the cluster and in the backup file could be different. + + ::: ::: -If you are using an S3 store as the backup source and need to use your S3 credentials for restore, create a secret in this cluster using your S3 credentials. The Secret data must have two keys - `accessKey` and `secretKey` - that contain the S3 credentials. +1. When using S3 object storage that as the backup source for restore that requires credentials, create a `Secret` object in this cluster to add the S3 credentials. The secret data must have two keys - `accessKey`, and `secretKey`, that contain the S3 credentials. -:::caution + The secret can be created in any namespace, this example uses the default namespace. -The values `accessKey` and `secretKey` in the example below must be base64-encoded first when creating the object directly. If not encoded first, the pasted values will cause errors when you are attempting to backup or restore. + ```bash + kubectl create secret generic s3-creds \ + --from-literal=accessKey= \ + --from-literal=secretKey= + ``` -::: + :::note -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: s3-creds -type: Opaque -data: - accessKey: - secretKey: -``` + Add your access key and secret key as values for `accessKey` and `secretKey` in the command below. -This secret can be created in any namespace; with the above example, it will get created in the default namespace. + ::: -In the Restore custom resource, `prune` must be set to false. +1. Create a `Restore` object: -Create a Restore custom resource like the example below: + During a migration, `prune` must be set to `false`, the example below: -```yaml -# migrationResource.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 - prune: false - encryptionConfigSecretName: encryptionconfig - storageLocation: - s3: - credentialSecretName: s3-creds - credentialSecretNamespace: default - bucketName: backup-test - folder: ecm1 - region: us-west-2 - endpoint: s3.us-west-2.amazonaws.com -``` + ```yaml + # restore-migration.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 + prune: false + encryptionConfigSecretName: encryptionconfig + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + ``` -:::note Important: + :::note 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: + The field `encryptionConfigSecretName` must be set only if your backup was created with encryption enabled. Provide the name of the `Secret` object 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 -``` - -1. Apply the manifest, and watch for the Restore resources status: - - Apply the resource: -``` -kubectl apply -f migrationResource.yaml -``` - - Watch the Restore status: -``` -kubectl get restore -``` - - Watch the restoration logs: -``` -kubectl logs -n cattle-resources-system --tail 100 -f rancher-backup-xxx-xxx -``` - -Once the Restore resource has the status `Completed`, you can continue the Rancher installation. + 1. The [encryption configuration file](reference-guides/backup-restore-configuration/backup-configuration.md#encryption) 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: + ```bash + kubectl create secret generic encryptionconfig \ + --from-file=./encryption-provider-config.yaml \ + -n cattle-resources-system + ``` +1. Apply the manifest, and monitor the Restore status: + 1. Apply the `Restore` object resource: + ```bash + kubectl apply -f restore-migration.yaml + ``` + 1. Watch the Restore status: + ```bash + kubectl get restore + ``` + 1. Watch the restoration logs: + ```bash + kubectl logs -n cattle-resources-system --tail 100 -f -l app.kubernetes.io/instance=rancher-backup + ``` + 1. Once the Restore resource has the status `Completed`, you can continue the Rancher installation. ### 3. Install cert-manager @@ -134,8 +144,25 @@ Follow the steps to [install cert-manager](../../../pages-for-subheaders/install Use the same version of Helm to install Rancher, that was used on the first cluster. -``` +```bash helm install rancher rancher-latest/rancher \ --namespace cattle-system \ --set hostname= \ + --version x.y.z ``` + +:::note + +If the original Rancher environment is running, you can collect the current values with a kubeconfig for the original environment: + +```bash +helm get values rancher -n cattle-system -o yaml > rancher-values.yaml +``` + +These values can be reused using the `rancher-values.yaml` file: + +```bash +helm install rancher rancher-latest/rancher -n cattle-system -f rancher-values.yaml --version x.y.z +``` + +::: \ No newline at end of file diff --git a/docs/reference-guides/backup-restore-configuration/backup-configuration.md b/docs/reference-guides/backup-restore-configuration/backup-configuration.md index 9351a312631..5b3c3c45bba 100644 --- a/docs/reference-guides/backup-restore-configuration/backup-configuration.md +++ b/docs/reference-guides/backup-restore-configuration/backup-configuration.md @@ -42,7 +42,7 @@ To create the Secret, the encryption configuration file must be named `encryptio Save the `EncryptionConfiguration` in a file called `encryption-provider-config.yaml` and run this command: -``` +```bash kubectl create secret generic encryptionconfig \ --from-file=./encryption-provider-config.yaml \ -n cattle-resources-system @@ -121,10 +121,21 @@ metadata: name: creds type: Opaque data: - accessKey: - secretKey: + accessKey: + secretKey: ``` +:::note + +To avoid encoding issues, the credentialSecret can be created with the below command, updating the values for `accessKey` and `secretKey`. +```bash +kubectl create secret generic s3-creds \ + --from-literal=accessKey= \ + --from-literal=secretKey= +``` + +::: + ### IAM Permissions for EC2 Nodes to Access S3 There are two ways to set up the `rancher-backup` operator to use S3 as the backup storage location. From 6cf8f7d06f4fe1bb40759fc998f9bdc5ad51c529 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:27:16 +0000 Subject: [PATCH 02/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index f7fc4f82fd0..0b4113cde83 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -26,6 +26,7 @@ Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes Install the [rancher-backup chart](https://github.com/rancher/backup-restore-operator/tags), using a version in the 2.x.x major version range: 1. Add the helm repository: + ```bash helm repo add rancher-charts https://charts.rancher.io helm repo update From 56121338e6683bd2778f26934a2fb9c10188e4c6 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:27:32 +0000 Subject: [PATCH 03/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 0b4113cde83..c6e873f088b 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -31,6 +31,7 @@ Install the [rancher-backup chart](https://github.com/rancher/backup-restore-ope helm repo add rancher-charts https://charts.rancher.io helm repo update ``` + 1. Select and set `CHART_VERSION` variable with a 2.x.x rancher-backup release version: ```bash helm search repo --versions rancher-charts/rancher-backup From c833de211213ccc520f7b0e04d991ecaa765c22b Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:27:41 +0000 Subject: [PATCH 04/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index c6e873f088b..52bf2b42fcc 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -37,7 +37,8 @@ Install the [rancher-backup chart](https://github.com/rancher/backup-restore-ope helm search repo --versions rancher-charts/rancher-backup CHART_VERSION=<2.x.x> ``` - 2. Install the charts: + + 1. Install the charts: ```bash helm install rancher-backup-crd rancher-charts/rancher-backup-crd -n cattle-resources-system --create-namespace --version $CHART_VERSION helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system --version $CHART_VERSION From 57586ed6861e737f0904a25d49d6dd22844df855 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:27:59 +0000 Subject: [PATCH 05/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 52bf2b42fcc..46dde4b28a8 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -124,6 +124,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo --from-file=./encryption-provider-config.yaml \ -n cattle-resources-system ``` + 1. Apply the manifest, and monitor the Restore status: 1. Apply the `Restore` object resource: ```bash From c91f22c4743479fe05a984ff7dcc43c534101ba4 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:28:06 +0000 Subject: [PATCH 06/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 46dde4b28a8..97e3fc77c00 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -127,6 +127,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo 1. Apply the manifest, and monitor the Restore status: 1. Apply the `Restore` object resource: + ```bash kubectl apply -f restore-migration.yaml ``` From cdd2dbc52a2aebff77f2f1a7129025bce369d0a2 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:28:32 +0000 Subject: [PATCH 07/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 97e3fc77c00..2857d69bf14 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -131,6 +131,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo ```bash kubectl apply -f restore-migration.yaml ``` + 1. Watch the Restore status: ```bash kubectl get restore From 213e42e161faac162286a1c54171fb53563e589d Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:28:47 +0000 Subject: [PATCH 08/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 2857d69bf14..8320e890b32 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -136,6 +136,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo ```bash kubectl get restore ``` + 1. Watch the restoration logs: ```bash kubectl logs -n cattle-resources-system --tail 100 -f -l app.kubernetes.io/instance=rancher-backup From 594d7549a2f9c5fdc452a15bade99846ccff9034 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:29:09 +0000 Subject: [PATCH 09/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 8320e890b32..2bc319b1528 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -141,6 +141,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo ```bash kubectl logs -n cattle-resources-system --tail 100 -f -l app.kubernetes.io/instance=rancher-backup ``` + 1. Once the Restore resource has the status `Completed`, you can continue the Rancher installation. ### 3. Install cert-manager From 82734a0e36dafbdc283401a6d3ab764bd390b7e7 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:29:29 +0000 Subject: [PATCH 10/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 2bc319b1528..16a399322e1 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -48,7 +48,8 @@ Install the [rancher-backup chart](https://github.com/rancher/backup-restore-ope The above assumes an environment with outbound connectivity to Docker Hub - For an **air-gapped environment**, use the helm value below to pull the `backup-restore-operator` image from your private registry when installing the rancher-backup helm chart. + For an **air-gapped environment**, use the Helm value below to pull the `backup-restore-operator` image from your private registry when installing the rancher-backup Helm chart. + ```bash --set image.repository $REGISTRY/rancher/backup-restore-operator ``` From c9069aa624d0a8542cb7ece678303c32116dfea1 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:31:25 +0000 Subject: [PATCH 11/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 16a399322e1..2d209de5354 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -73,7 +73,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo ::: -1. When using S3 object storage that as the backup source for restore that requires credentials, create a `Secret` object in this cluster to add the S3 credentials. The secret data must have two keys - `accessKey`, and `secretKey`, that contain the S3 credentials. +1. When using S3 object storage as the backup source for a restore that requires credentials, create a `Secret` object in this cluster to add the S3 credentials. The secret data must have two keys - `accessKey`, and `secretKey`, that contain the S3 credentials. The secret can be created in any namespace, this example uses the default namespace. From efed50a63b116244ee241e87e4218989bd1741bc Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:31:36 +0000 Subject: [PATCH 12/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 2d209de5354..e09426c2733 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -91,7 +91,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo 1. Create a `Restore` object: - During a migration, `prune` must be set to `false`, the example below: + During a migration, `prune` must be set to `false`. See the example below: ```yaml # restore-migration.yaml From 75be9391f196adb0fbab8d8569b583de15139506 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:31:52 +0000 Subject: [PATCH 13/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index e09426c2733..9a8c25824b9 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -101,6 +101,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo name: restore-migration spec: backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz + // highlight-next-line prune: false encryptionConfigSecretName: encryptionconfig storageLocation: From 01f3cf79b8878cbf76019f41c7d0a29a794896fd Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:32:33 +0000 Subject: [PATCH 14/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 9a8c25824b9..22b295e67df 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -114,7 +114,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo endpoint: s3.us-west-2.amazonaws.com ``` - :::note Important: + :::note Important The field `encryptionConfigSecretName` must be set only if your backup was created with encryption enabled. Provide the name of the `Secret` object 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: From d8ba127a18b0d7b5a72fbb7c7192c23d1f1bdfb1 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:32:46 +0000 Subject: [PATCH 15/18] Update docs/reference-guides/backup-restore-configuration/backup-configuration.md Co-authored-by: Billy Tat --- .../backup-restore-configuration/backup-configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference-guides/backup-restore-configuration/backup-configuration.md b/docs/reference-guides/backup-restore-configuration/backup-configuration.md index 5b3c3c45bba..4f835c3c991 100644 --- a/docs/reference-guides/backup-restore-configuration/backup-configuration.md +++ b/docs/reference-guides/backup-restore-configuration/backup-configuration.md @@ -127,7 +127,8 @@ data: :::note -To avoid encoding issues, the credentialSecret can be created with the below command, updating the values for `accessKey` and `secretKey`. +To avoid encoding issues, the `credentialSecret` can be created with the below command, updating the values for `accessKey` and `secretKey`. + ```bash kubectl create secret generic s3-creds \ --from-literal=accessKey= \ From 8d282dd842f036c8fab74514b72165d9ecdd8804 Mon Sep 17 00:00:00 2001 From: dkeightley <20566450+dkeightley@users.noreply.github.com> Date: Thu, 29 Sep 2022 21:33:03 +0000 Subject: [PATCH 16/18] Update docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md Co-authored-by: Billy Tat --- .../migrate-rancher-to-new-cluster.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 22b295e67df..8181804ed0c 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -85,7 +85,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo :::note - Add your access key and secret key as values for `accessKey` and `secretKey` in the command below. + Add your access key and secret key as values for `accessKey` and `secretKey` in the command above. ::: From 03f5404e339df53b12fe17c071b73df9f053245a Mon Sep 17 00:00:00 2001 From: dkeightley Date: Fri, 30 Sep 2022 16:19:05 +1300 Subject: [PATCH 17/18] Adjust important block, small wording changes --- .../migrate-rancher-to-new-cluster.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md index 8181804ed0c..f855da4f270 100644 --- a/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md +++ b/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md @@ -103,6 +103,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz // highlight-next-line prune: false + // highlight-next-line encryptionConfigSecretName: encryptionconfig storageLocation: s3: @@ -116,17 +117,21 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo :::note Important - The field `encryptionConfigSecretName` must be set only if your backup was created with encryption enabled. Provide the name of the `Secret` object 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: + The field `encryptionConfigSecretName` should be used only if your backup was created with encryption enabled. - ::: + If this applies, provide the name of the `Secret` object containing the encryption config file. If you only have the encryption config file, but don't have the secret created in this cluster, use the following steps to create the secret: + + 1. Create an [encryption configuration file](reference-guides/backup-restore-configuration/backup-configuration.md#encryption) + 1. The command below uses a file named `encryption-provider-config.yaml`, with the `--from-file` flag. Run the below once the `EncryptionConfiguration` is saved in a file called `encryption-provider-config.yaml`: - 1. The [encryption configuration file](reference-guides/backup-restore-configuration/backup-configuration.md#encryption) 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: ```bash kubectl create secret generic encryptionconfig \ --from-file=./encryption-provider-config.yaml \ -n cattle-resources-system ``` + ::: + 1. Apply the manifest, and monitor the Restore status: 1. Apply the `Restore` object resource: @@ -144,7 +149,7 @@ Kubernetes v1.22, available as an experimental feature of v2.6.3, does not suppo kubectl logs -n cattle-resources-system --tail 100 -f -l app.kubernetes.io/instance=rancher-backup ``` - 1. Once the Restore resource has the status `Completed`, you can continue the Rancher installation. + 1. Once the Restore resource has the status `Completed`, you can continue the cert-manager and Rancher installation. ### 3. Install cert-manager @@ -169,7 +174,7 @@ If the original Rancher environment is running, you can collect the current valu helm get values rancher -n cattle-system -o yaml > rancher-values.yaml ``` -These values can be reused using the `rancher-values.yaml` file: +These values can be reused using the `rancher-values.yaml` file. Be sure to switch the kubeconfig to the new Rancher environment. ```bash helm install rancher rancher-latest/rancher -n cattle-system -f rancher-values.yaml --version x.y.z From f73bdc4a4a1c55b29afdfaaeab89ed3e68d645c2 Mon Sep 17 00:00:00 2001 From: dkeightley Date: Fri, 30 Sep 2022 16:19:23 +1300 Subject: [PATCH 18/18] Small wording changes for consistency --- .../backup-configuration.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/reference-guides/backup-restore-configuration/backup-configuration.md b/docs/reference-guides/backup-restore-configuration/backup-configuration.md index 4f835c3c991..9199cede367 100644 --- a/docs/reference-guides/backup-restore-configuration/backup-configuration.md +++ b/docs/reference-guides/backup-restore-configuration/backup-configuration.md @@ -23,22 +23,23 @@ Select the first option to perform a one-time backup, or select the second optio ## Encryption -The rancher-backup gathers resources by making calls to the kube-apiserver. Objects returned by apiserver are decrypted, so even if [encryption At rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) is enabled, even the encrypted objects gathered by the backup will be in plaintext. +The rancher-backup gathers resources by making calls to the kube-apiserver. Objects returned by apiserver are decrypted, so even if [encryption at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) is enabled, even the encrypted objects gathered by the backup will be in plaintext. -To avoid storing them in plaintext, you can use the same encryptionConfig file that was used for at-rest encryption, to encrypt certain resources in your backup. +To avoid storing them in plaintext, you can use the same `EncryptionConfiguration` file that was used for at rest encryption, to encrypt certain resources in your backup. :::note Important: -You must save the encryptionConfig file, because it won’t be saved by the rancher-backup operator. -The same encryptionFile needs to be used when performing a restore. +When encrypting objects in the backup you must save the `EncryptionConfiguration` file for future use, because it won’t be saved by the rancher-backup operator. + +For example, when [migrating Rancher to a new cluster](new-user-guides/backup-restore-and-disaster-recovery) the file is used to re-create the secret in the new cluster. ::: -The operator consumes this encryptionConfig as a Kubernetes Secret, and the Secret must be in the operator’s namespace. Rancher installs the `rancher-backup` operator in the `cattle-resources-system` namespace, so create this encryptionConfig secret in that namespace. +The operator consumes the `EncryptionConfiguration` as a Kubernetes Secret in the `cattle-resources-system` namespace under the key named `encryption-provider-config.yaml` in the secret data. For the `EncryptionConfiguration`, you can use the [sample file provided in the Kubernetes documentation.](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#understanding-the-encryption-at-rest-configuration) -To create the Secret, the encryption configuration file must be named `encryption-provider-config.yaml`, and the `--from-file` flag must be used to create this secret. +To ensure the correct key is used in the secret, the encryption configuration file must be named `encryption-provider-config.yaml`. The below command uses the `--from-file` flag to create the secret with the correct key name. Save the `EncryptionConfiguration` in a file called `encryption-provider-config.yaml` and run this command: @@ -50,7 +51,7 @@ kubectl create secret generic encryptionconfig \ This will ensure that the secret contains a key named `encryption-provider-config.yaml`, and the operator will use this key to get the encryption configuration. -The `Encryption Config Secret` dropdown will filter out and list only those Secrets that have this exact key +The `Encryption Config Secret` dropdown will filter out and list only those Secrets that have this exact key. ![](/img/backup_restore/backup/encryption.png)