diff --git a/content/rancher/v2.x/en/backups/_index.md b/content/rancher/v2.x/en/backups/_index.md index e73e5d6e32f..8f9b990ec18 100644 --- a/content/rancher/v2.x/en/backups/_index.md +++ b/content/rancher/v2.x/en/backups/_index.md @@ -3,4 +3,102 @@ title: Backups and Disaster Recovery weight: 5 --- -> This section is under construction. \ No newline at end of file +In this section, you'll learn how to create backups of Rancher, how to restore Rancher from backup, and how to migrate Rancher to a new server. + +- [Changes in Rancher v2.5](#changes-in-rancher-v2-5) +- [Backup and Restore for Rancher Prior to v2.5](#backup-and-restore-for-rancher-prior-to-v2-5) +- [How Backups and Restores Work](#how-backups-and-restores-work) +- [Installing the rancher-backup Operator](#installing-the-rancher-backup-operator) + - [Installing rancher-backup with the Rancher UI](#installing-rancher-backup-with-the-rancher-ui) + - [Installing rancher-backup with the Helm CLI](#installing-rancher-backup-with-the-helm-cli) +- [Backing up Rancher](#backing-up-rancher) +- [Restoring Rancher](#restoring-rancher) +- [Migrating Rancher to a New Cluster](#migrating-rancher-to-a-new-cluster) +- [Default Storage Location Configuration](#default-storage-location-configuration) + - [Example values.yaml for the rancher-backup Helm Chart](#example-values-yaml-for-the-rancher-backup-helm-chart) + +### Changes in Rancher v2.5 + +The new `rancher-backup` operator allows Rancher to be backed up and restored on any Kubernetes cluster. This application is a Helm chart, and it can be deployed through the Rancher **Apps & Marketplace** page, or by using the Helm CLI. + +Previously, the way that cluster data was backed up depended on the type of Kubernetes cluster that was used. + +In Rancher v2.4, it was only supported to install Rancher on two types of Kubernetes clusters: an RKE cluster, or a K3s cluster with an external database. If Rancher was installed on an RKE cluster, [RKE would be used]({{}}/rancher/v2.x/en/backups/legacy/backup/k8s-backups/ha-backups/) to take a snapshot of the etcd database and restore the cluster. If Rancher was installed on a K3s cluster with an external database, the database would need to be backed up and restored using the upstream documentation for the database. + +In Rancher v2.5, it is now supported to install Rancher hosted Kubernetes clusters, such as Amazon EKS clusters, which do not expose etcd to a degree that would allow snapshots to be created by an external tool. etcd doesn't need to be exposed for `rancher-backup` to work, because the operator gathers resources by making calls to `kube-apiserver`. + +### Backup and Restore for Rancher Prior to v2.5 + +For Rancher prior to v2.5, the way that Rancher is backed up and restored differs based on the way that Rancher was installed. Our legacy backup and restore documentation is here: + +- For Rancher installed on an RKE Kubernetes cluster, refer to the legacy [backup]({{}}/rancher/v2.x/en/backups/legacy/backup/k8s-backups/ha-backups/) and [restore]({{}}/rancher/v2.x/en/backups/legacy/restore/k8s-restore/rke-restore/) documentation. +- For Rancher installed on a K3s Kubernetes cluster, refer to the legacy [backup]({{}}/rancher/v2.x/en/backups/legacy/backup/k8s-backups/k3s-backups/) and [restore]({{}}/rancher/v2.x/en/backups/legacy/restore/k8s-restore/k3s-restore/) documentation. +- For Rancher installed with Docker, refer to the legacy [backup]({{}}/rancher/v2.x/en/backups/legacy/backup/single-node-backups/) and [restore]({{}}/rancher/v2.x/en/backups/legacy/restore/single-node-restoration/) documentation. + +### How Backups and Restores Work + +The `rancher-backup` operator introduces three custom resources: Backups, Restores, and ResourceSets. The following cluster-scoped custom resource definitions are added to the cluster: + +- `backups.resources.cattle.io` +- `resourcesets.resources.cattle.io` +- `restores.resources.cattle.io` + +The ResourceSet defines which Kubernetes resources need to be backed up. The ResourceSet is not available to be configured in the Rancher UI because the values required to back up Rancher are predefined. + +When a Backup custom resource is created, the `rancher-backup` operator calls the `kube-apiserver` to get the resources in the ResourceSet (specifically, the predefined `rancher-resource-set`) that the Backup custom resource refers to. + +The operator then creates the backup file in the .tar.gz format and stores it in the location configured in the Backup resource. + +When a Restore custom resource is created, the operator accesses the backup .tar.gz file specified by the Restore, and restores the application from that file. + +The Backup and Restore custom resources can be created in the Rancher UI, or by using `kubectl apply`. + +# Installing the rancher-backup Operator + +The `rancher-backup` operator can be installed from the Rancher UI, or with the Helm CLI. In both cases, the `rancher-backup` Helm chart is installed on the Kubernetes cluster running the Rancher server. + +### Installing rancher-backup with the Rancher UI + +1. In the Rancher UI, go to the **Cluster Explorer.** +1. Click **Apps.** +1. Click the `rancher-backup` operator. +1. Optional: Configure the default storage location. For help, refer to the [configuration section.](./configuration/storage-config) + +**Result:** The `rancher-backup` operator is installed. + +From the **Cluster Explorer,** you can see the `rancher-backup` operator listed under **Deployments.** + +To configure the backup app in Rancher, click **Cluster Explorer** in the upper left corner and click **Rancher Backups.** + +### Installing rancher-backup with the Helm CLI + +Install the backup app as a Helm chart: + +``` +helm repo add rancherchart https://charts.rancher.io +helm repo update +helm install rancher-backup-crd rancherchart/rancher-backup-crd -n cattle-resources-system --create-namespace +helm install rancher-backup rancherchart/rancher-backup -n cattle-resources-system +``` + +# Backing up Rancher + +A backup is performed by creating a Backup custom resource. For a tutorial, refer to [this page.](../back-up-rancher) + +# Restoring Rancher + +A restore is performed by creating a Restore custom resource. For a tutorial, refer to [this page.](../restoring-rancher) + +# Migrating Rancher to a New Cluster + +A migration is performed by following [these steps.](../migrating-rancher) + +# Default Storage Location Configuration + +Configure a storage location where all backups are saved by default. You will have the option to override this with each backup, but will be limited to using an S3-compatible or Minio object store. + +For information on configuring these options, refer to [this page.](../storage-config) + +### Example values.yaml for the rancher-backup Helm Chart + +The example [values.yaml file](../example-values) can be used to configure the `rancher-backup` operator when the Helm CLI is used to install it. 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 new file mode 100644 index 00000000000..d142f7ccffc --- /dev/null +++ b/content/rancher/v2.x/en/backups/back-up-rancher/_index.md @@ -0,0 +1,58 @@ +--- +title: Backing up Rancher +weight: 1 +--- + +In this section, you'll learn how to back up Rancher. + +### 1. Install the `rancher-backup` operator + +The backup storage location is an operator-level setting, so it needs to be configured when `rancher-backup` is installed or upgraded. + +Backups are created as .tar.gz files. These files can be pushed to S3 or Minio, or they can be stored in a persistent volume. + +1. In the Rancher UI, go to the **Cluster Explorer.** +1. Click **Apps.** +1. Click `rancher-backup`. +1. Configure the default storage location. For help, refer to the [storage configuration section.](#configuring-the-storage-location) + +### 2. Perform a Backup + +To perform a backup, a custom resource of type Backup must be created. + +1. In the **Cluster Explorer,** go to the dropdown menu in the upper left corner and click **Rancher Backups.** +1. Click **Backup.** +1. Create the Backup with the form, or with YAML. For this example, we can click **Create > Create from YAML.** Enter the Backup YAML. This example Backup custom resource would create encrypted recurring backups in S3: + + ```yaml + apiVersion: resources.cattle.io/v1 + kind: Backup + metadata: + name: test-s3-recurring-backup + spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rajashree-backup-test + 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 + ``` + + + + + + For help configuring the Backup, refer to the [configuration reference](../../configuration/backup-config) and to the [examples.](../../examples/backups) + + Recurring backups are scheduled by editing the `Schedule` and `RetentionCount` fields. For more information, refer to the [Backup configuration reference.](../../backup-config/#schedule) + + > **Important:** The `rancher-backup` operator doesn't save the EncryptionConfiguration file. The contents of the EncryptionConfiguration file must be saved when an encrypted backup is created, and the same file must be used when restoring from this backup. +1. Click **Create.** + +**Result:** The backup file is created in the storage location configured in the Backup custom resource. The name of this file is used when performing a restore. \ No newline at end of file diff --git a/content/rancher/v2.x/en/backups/configuration/_index.md b/content/rancher/v2.x/en/backups/configuration/_index.md new file mode 100644 index 00000000000..d83cc04b29f --- /dev/null +++ b/content/rancher/v2.x/en/backups/configuration/_index.md @@ -0,0 +1,10 @@ +--- +title: Rancher Backup Configuration Reference +shortTitle: Configuration +weight: 4 +--- + +- [Backup configuration](./backup-config) +- [Restore configuration](./restore-config) +- [Storage location configuration](./storage-config) +- [Example Backup and Restore Custom Resources](../examples) \ 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 new file mode 100644 index 00000000000..aace0aaee59 --- /dev/null +++ b/content/rancher/v2.x/en/backups/configuration/backup-config/_index.md @@ -0,0 +1,150 @@ +--- +title: Backup Configuration +shortTitle: Backup +weight: 1 +--- + +The OpenAPI schema for the Backup custom resource definition is [here.](https://github.com/rancher/rancher-backup/blob/master/crds/backup.yaml#L14) + +The Backup custom resource accepts the following fields: + +- [EncryptionConfigName](#encryptionconfigname) +- [StorageLocation](#storagelocation) + - [S3](#s3) + - [Example S3 Compatible Storage Configuration](#example-s3-compatible-storage-configuration) + - [Example credentialSecret](#example-credentialsecret) + - [IAM Permissions for EC2 Nodes to Access S3](#iam-permissions-for-ec2-nodes-to-access-s3) +- [Schedule](#schedule) +- [RetentionCount](#retentioncount) +- [Examples](#examples) + +# EncryptionConfigName + +This field is optional. + +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. + +> **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. + +The operator consumes this encryptionConfig as a 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. + +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. + +Save the `EncryptionConfiguration` in a file called `encryption-provider-config.yaml` and run this command: + +``` +kubectl create secret generic test-encryptionconfig \ + --from-file=./encryption-provider-config.yaml \ + -n cattle-resources-system +``` + +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. + +In the example command above, the name `test-encryptionconfig` can be changed to anything. + +# StorageLocation + +[Optional]. It can be set if you want to provide a specific S3 bucket details for the current backup CR. To set that, you must set the `StorageLocation.s3` field. + +### S3 + +The S3 storage location contains the following configuration fields: + +| YAML Directive Name | Description | Required | +| ---------------- | ---------------- | ------------ | +| `credentialSecretName` | If you need to use the AWS Access keys Secret keys to access s3 bucket, create a secret with your credentials with keys and the directives `accessKey` and `secretKey`. It can be in any namespace as long as you provide that namespace in `credentialSecretNamespace`. An example secret is [here.](#example-credentialsecret) This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in [this section.](#iam-permissions-for-ec2-nodes-to-access-s3) | | +| `credentialSecretNamespace` | The namespace of the secret containing the credentials to access S3. This directive is unnecessary if the nodes running your operator are in EC2 and set up with IAM permissions that allow them to access S3, as described in [this section.](#iam-permissions-for-ec2-nodes-to-access-s3) | | +| `bucketName` | The name of the S3 bucket where backup files will be stored. | ✓ | +| `folder` | The name of the folder in the S3 bucket where backup files will be stored. | | +| `region` | The AWS [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. | ✓ | +| `endpoint` | The [endpoint](https://docs.aws.amazon.com/general/latest/gr/s3.html) that is used to access S3 in the region of your bucket. | ✓ | +| `endpointCA` | This should be the Base64 encoded CA cert. For an example, refer to the [example S3 compatible configuration.](#example-s3-storage-configuration) | | +| `insecureTLSSkipVerify` | Set to true if you are not using TLS. | | + +### Example S3 Compatible Storage Configuration + +```yaml +s3: + credentialSecretName: minio-creds + bucketName: rancherbackups + endpoint: minio.35.202.130.254.xip.io + endpointCA: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQUtpWFZpNEpBb0J5TUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NakF3T0RNd01UZ3lOVFE1V2hjTk1qQXhNREk1TVRneU5UUTVXakFTTVJBdwpEZ1lEVlFRRERBZDBaWE4wTFdOaE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBCjA4dnV3Q2Y0SEhtR2Q2azVNTmozRW5NOG00T2RpS3czSGszd1NlOUlXQkwyVzY5WDZxenBhN2I2M3U2L05mMnkKSnZWNDVqeXplRFB6bFJycjlpbEpWaVZ1NFNqWlFjdG9jWmFCaVNsL0xDbEFDdkFaUlYvKzN0TFVTZSs1ZDY0QQpWcUhDQlZObU5xM3E3aVY0TE1aSVpRc3N6K0FxaU1Sd0pOMVVKQTZ6V0tUc2Yzc3ByQ0J2dWxJWmZsVXVETVAyCnRCTCt6cXZEc0pDdWlhNEEvU2JNT29tVmM2WnNtTGkwMjdub3dGRld3MnRpSkM5d0xMRE14NnJoVHQ4a3VvVHYKQXJpUjB4WktiRU45L1Uzb011eUVKbHZyck9YS2ZuUDUwbk8ycGNaQnZCb3pUTStYZnRvQ1d5UnhKUmI5cFNTRApKQjlmUEFtLzNZcFpMMGRKY2sxR1h3SURBUUFCbzNNd2NUQWRCZ05WSFE0RUZnUVU5NHU4WXlMdmE2MTJnT1pyCm44QnlFQ2NucVFjd1FnWURWUjBqQkRzd09ZQVU5NHU4WXlMdmE2MTJnT1pybjhCeUVDY25xUWVoRnFRVU1CSXgKRURBT0JnTlZCQU1NQjNSbGMzUXRZMkdDQ1FDb2wxWXVDUUtBY2pBTUJnTlZIUk1FQlRBREFRSC9NQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFER1JRZ1RtdzdVNXRQRHA5Q2psOXlLRW9Vd2pYWWM2UlAwdm1GSHpubXJ3dUVLCjFrTkVJNzhBTUw1MEpuS29CY0ljVDNEeGQ3TGdIbTNCRE5mVVh2anArNnZqaXhJYXR2UWhsSFNVaWIyZjJsSTkKVEMxNzVyNCtROFkzelc1RlFXSDdLK08vY3pJTGh5ei93aHRDUlFkQ29lS1dXZkFiby8wd0VSejZzNkhkVFJzNwpHcWlGNWZtWGp6S0lOcTBjMHRyZ0xtalNKd1hwSnU0ZnNGOEcyZUh4b2pOKzdJQ1FuSkg5cGRIRVpUQUtOL2ppCnIvem04RlZtd1kvdTBndEZneWVQY1ZWbXBqRm03Y0ZOSkc4Y2ZYd0QzcEFwVjhVOGNocTZGeFBHTkVvWFZnclMKY1VRMklaU0RJd1FFY3FvSzFKSGdCUWw2RXBaUVpWMW1DRklrdFBwSQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t +``` +### Example credentialSecret + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: creds +type: Opaque +data: + accessKey: + 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. + +One way is to configure the `credentialSecretName` in the Backup custom resource, which refers to AWS credentials that have access to S3. + +If the cluster nodes are in Amazon EC2, the S3 access can also be set up by assigning IAM permissions to the EC2 nodes so that they can access S3. + +To allow a node to access S3, follow the instructions in the [AWS documentation](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-instance-access-s3-bucket/) to create an IAM role for EC2. When you add a custom policy to the role, add the following permissions, and replace the `Resource` with your bucket name: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket" + ], + "Resource": [ + "arn:aws:s3:::backup-test" + ] + }, + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:PutObjectAcl" + ], + "Resource": [ + "arn:aws:s3:::backup-test/*" + ] + } + ] +} +``` + +After the role is created, and you have attached the corresponding instance profile to your EC2 instance(s), the `credentialSecretName` directive can be left empty in the Backup custom resource. + +# Schedule + +This field is optional. + +Recurring backups can be enabled by setting this field. It accepts: + +- Standard [cron expressions](https://en.wikipedia.org/wiki/Cron) +- Descriptors, such as "@midnight" or "@every 1h30m" + +# RetentionCount + +This field is optional and applicable only for recurring backups. The default is 10. + +This value specifies how many backup files for a particular app must be retained. If files exceed the given retentionCount, the oldest files will be deleted. + +# Examples + +For example Backup custom resources, refer to [this page.](../../examples/#backup) \ No newline at end of file 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 new file mode 100644 index 00000000000..5175e2ec76c --- /dev/null +++ b/content/rancher/v2.x/en/backups/configuration/restore-config/_index.md @@ -0,0 +1,42 @@ +--- +title: Restore Configuration +shortTitle: Restore +weight: 2 +--- + +The OpenAPI schema for the Restore custom resource definition is [here.](https://github.com/rancher/rancher-backup/blob/master/crds/restore.yaml) + +The Restore custom resource accepts the following fields: + +- [BackupFilename] +- [EncryptionConfigName] + +### BackupFilename + +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, + +- 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`. + +### 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.](../../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 diff --git a/content/rancher/v2.x/en/backups/configuration/storage-config/_index.md b/content/rancher/v2.x/en/backups/configuration/storage-config/_index.md new file mode 100644 index 00000000000..4c2f8b23b0c --- /dev/null +++ b/content/rancher/v2.x/en/backups/configuration/storage-config/_index.md @@ -0,0 +1,122 @@ +--- +title: Backup Storage Location Configuration +shortTitle: Storage +weight: 3 +--- + +Configure a storage location where all backups are saved by default. You will have the option to override this with each backup, but will be limited to using an S3-compatible object store. + +The storage location is configured at the operator level. Therefore, it must be configured when the `rancher-backup` operator is installed or upgraded. + +Only one storage location can be configured for each backup. + +- [Storage Location Configuration](#storage-location-configuration) + - [No Default Storage Location](#no-default-storage-location) + - [Use the Default Storage Class (gp2)](#use-the-default-storage-class-gp2) + - [S3-compatible Object Store](#s3-compatible-object-store) + - [Existing StorageClass](#existing-storageclass) + - [Existing PersistentVolume](#existing-persistentvolume) +- [Encryption](#encryption) +- [Example values.yaml for the rancher-backup Helm Chart](#example-values-yaml-for-the-rancher-backup-helm-chart) + +# Storage Location Configuration + +### No Default Storage Location + +This option is the default. + +### Use the Default Storage Class (gp2) + +If this option is selected, the cluster's [default StorageClass](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) will be used to store the backups. + +### S3-compatible Object Store + +| Parameter | Description | +| -------------- | -------------- | +| Credential Secret | Choose the credentials for S3 from your secrets in Rancher. | +| Bucket Name | Enter the name of the [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html) where the backups will be stored. Default: `rancherbackups`. | +| Region | The [AWS region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. | +| Folder | The [folder in the S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/using-folders.html) where the backups will be stored. | +| Endpoint | The [S3 endpoint](https://docs.aws.amazon.com/general/latest/gr/s3.html) For example, `s3.us-west-2.amazonaws.com`. | +| Endpoint CA | The CA cert used to for the S3 endpoint. Default: base64 encoded CA cert | + +### Existing StorageClass + +Configure an existing storage class that will be used to store your backups. For information about creating storage classes in refer to [this section.]({{}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/provisioning-new-storage/#1-add-a-storage-class-and-configure-it-to-use-your-storage-provider) + +If a StorageClass is selected, a new PersistentVolumeClaim will be created on the same host on which the `rancher-backup` operator pod is running. This will in turn create a new PersistentVolume due to dynamic provisioning. + +### Existing PersistentVolume + +Configure an existing PersistentVolume that will be used to store your backups. For information about creating PersistentVolumes in Rancher, refer to [this section.]({{}}/rancher/v2.x/en/cluster-admin/volumes-and-storage/attaching-existing-storage/#2-add-a-persistent-volume-that-refers-to-the-persistent-storage) + +# Encryption + +Resources can be encrypted before they are saved in a backup file. + +The `rancher-backup` operator uses the same process to encrypt the backups as is described in the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) for encrypting data at rest.Encryption details are provided in an EncryptionConfiguration YAML file. + +You can use any EncryptionConfiguration YAML, including one that is already used in your Kubernetes cluster. + +In order for `rancher-backup` operator to use the EncryptionConfiguration, the file must be named `encryption-provider-config.yaml`. + +> **Important:** The `rancher-backup` operator doesn't save the EncryptionConfiguration file. The contents of the EncryptionConfiguration file must be saved when a backup is created, and the same file must be used when restoring from this backup. + +# Example values.yaml for the rancher-backup Helm Chart + + +This values.yaml file can be used to configure `rancher-backup` operator when the Helm CLI is used to install it. + +For more information about `values.yaml` files and configuring Helm charts during installation, refer to the [Helm documentation.](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing) + +```yaml +image: + repository: rancher/rancher-backup + tag: v0.0.1-rc10 + +## Default s3 bucket for storing all backup files created by the rancher-backup operator +s3: + enabled: false + ## credentialSecretName if set, should be the name of the Secret containing AWS credentials. + ## To use IAM Role, don't set this field + credentialSecretName: creds + credentialSecretNamespace: "" + region: us-west-2 + bucketName: rancherbackups + folder: base folder + endpoint: s3.us-west-2.amazonaws.com + endpointCA: base64 encoded CA cert + # insecureTLSSkipVerify: optional + +## ref: http://kubernetes.io/docs/user-guide/persistent-volumes/ +## If persistence is enabled, operator will create a PVC with mountPath /var/lib/backups +persistence: + enabled: false + + ## If defined, storageClassName: + ## If set to "-", storageClassName: "", which disables dynamic provisioning + ## If undefined (the default) or set to null, no storageClassName spec is + ## set, choosing the default provisioner. (gp2 on AWS, standard on + ## GKE, AWS & OpenStack). + ## Refer to https://kubernetes.io/docs/concepts/storage/persistent-volumes/#class-1 + ## + storageClass: "-" + + ## If you want to disable dynamic provisioning by setting storageClass to "-" above, + ## and want to target a particular PV, provide name of the target volume + volumeName: "" + + ## Only certain StorageClasses allow resizing PVs; Refer to https://kubernetes.io/blog/2018/07/12/resizing-persistent-volumes-using-kubernetes/ + size: 2Gi + + +global: + cattle: + systemDefaultRegistry: "" + +nodeSelector: {} + +tolerations: [] + +affinity: {} +``` \ No newline at end of file diff --git a/content/rancher/v2.x/en/backups/examples/_index.md b/content/rancher/v2.x/en/backups/examples/_index.md new file mode 100644 index 00000000000..273712df63d --- /dev/null +++ b/content/rancher/v2.x/en/backups/examples/_index.md @@ -0,0 +1,297 @@ +--- +title: Examples +weight: 5 +--- + +This section contains examples of Backup and Restore custom resources. The original source is [here.](https://github.com/rancher/rancher-backup/tree/master/examples) + +The default backup storage location is configured when the `rancher-backup` operator is installed or upgraded. + +Encrypted backups can only be restored if the Restore custom resource uses the same encryption configuration secret that was used to create the backup. + +- [Backup](#backup) + - [Backup in the default location with encryption](#backup-in-the-default-location-with-encryption) + - [Recurring backup in the default location](#recurring-backup-in-the-default-location) + - [Encrypted recurring backup in the default location](#encrypted-recurring-backup-in-the-default-location) + - [Encrypted backup in Minio](#encrypted-backup-in-minio) + - [Backup in S3 using AWS credential secret](#backup-in-s3-using-aws-credential-secret) + - [Recurring backup in S3 using AWS credential secret](#recurring-backup-in-s3-using-aws-credential-secret) + - [Backup from EC2 nodes with IAM permission to access S3](#backup-from-ec2-nodes-with-iam-permission-to-access-s3) +- [Restore](#restore) + - [Restore using the default backup file location](#restore-using-the-default-backup-file-location) + - [Restore for Rancher migration](#restore-for-rancher-migration) + - [Restore from encrypted backup](#restore-from-encrypted-backup) + - [Restore an encrypted backup from Minio](#restore-an-encrypted-backup-from-minio) + - [Restore from backup using an AWS credential secret to access S3](#restore-from-backup-using-an-aws-credential-secret-to-access-s3) + - [Restore from EC2 nodes with IAM permissions to access S3](#restore-from-ec2-nodes-with-iam-permissions-to-access-s3) +- [Example Credential Secret for Storing Backups in S3](#example-credential-secret-for-storing-backups-in-s3) +- [Example EncryptionConfiguration](#example-encryptionconfiguration) + +# Backup + +### Backup in the Default Location with Encryption + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: test-s3-def-backup +spec: + resourceSetName: rancher-resource-set + encryptionConfigSecretName: test-encryptionconfig +``` + +### Recurring Backup in the Default Location + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: test-default-location-recurring-backup +spec: + resourceSetName: rancher-resource-set + schedule: "@every 2m" + retentionCount: 3 +``` + +### Encrypted Recurring Backup in the Default Location + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: test-s3-recurring-backup +spec: + resourceSetName: ecm-resource-set + encryptionConfigSecretName: test-encryptionconfig + schedule: "@every 1m" + retentionCount: 3 +``` + +### Encrypted Backup in Minio + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: minio-backup-demo +spec: + storageLocation: + s3: + credentialSecretName: minio-creds + credentialSecretNamespace: default + bucketName: rancherbackups + endpoint: minio.xip.io + endpointCA: LS0tLS1CRUdJTi3VUFNQkl5UUT.....pbEpWaVzNkRS0tLS0t + resourceSetName: rancher-resource-set + encryptionConfigSecretName: test-encryptionconfig +``` + +### Backup in S3 Using AWS Credential Secret + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: s3-backup-demo +spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rajashree-backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set + encryptionConfigSecretName: test-encryptionconfig +``` + +### Recurring Backup in S3 Using AWS Credential Secret + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: test-s3-recurring-backup +spec: + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rajashree-backup-test + 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 +``` + +### Backup from EC2 Nodes with IAM Permission to Access S3 + +This example shows that the AWS credential secret does not have to be provided to create a backup if the nodes running `rancher-backup` have [these permissions for access to S3.](../../configuration/backup-config/#iam-permissions-for-eC2-nodes-to-access-s3) + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Backup +metadata: + name: s3-backup-demo +spec: + storageLocation: + s3: + bucketName: rajashree-backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + resourceSetName: rancher-resource-set + encryptionConfigSecretName: test-encryptionconfig +``` + +# Restore + +### Restore Using the Default Backup File Location + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-pvc-demo +spec: + backupFilename: test-default-location-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-29-54-07-00.tar.gz +# encryptionConfigSecretName: test-encryptionconfig +``` + +### Restore for Rancher Migration +```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: rajashree-backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com +``` + +### Restore from Encrypted Backup + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-s3-demo +spec: + backupFilename: default-test-s3-def-backup-c583d8f2-6daf-4648-8ead-ed826c591471-2020-08-24T20#47#05Z.tar.gz + encryptionConfigSecretName: test-encryptionconfig +``` + +### Restore an Encrypted Backup from Minio + +```yaml +apiVersion: resources.cattle.io/v1 +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 + storageLocation: + s3: + credentialSecretName: minio-creds + credentialSecretNamespace: default + bucketName: rancherbackups + endpoint: minio.xip.io + endpointCA: LS0tLS1CRUdJTi3VUFNQkl5UUT.....pbEpWaVzNkRS0tLS0t + encryptionConfigSecretName: test-encryptionconfig +``` + +### Restore from Backup Using an AWS Credential Secret to Access S3 + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-s3-demo +spec: + backupFilename: test-s3-recurring-backup-752ecd87-d958-4d20-8350-072f8d090045-2020-09-26T12-49-34-07-00.tar.gz.enc + storageLocation: + s3: + credentialSecretName: s3-creds + credentialSecretNamespace: default + bucketName: rajashree-backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + encryptionConfigSecretName: test-encryptionconfig +``` + +### Restore from EC2 Nodes with IAM Permissions to Access S3 + +This example shows that the AWS credential secret does not have to be provided to restore from backup if the nodes running `rancher-backup` have [these permissions for access to S3.](../../configuration/backup-config/#iam-permissions-for-eC2-nodes-to-access-s3) + +```yaml +apiVersion: resources.cattle.io/v1 +kind: Restore +metadata: + name: restore-s3-demo +spec: + backupFilename: default-test-s3-recurring-backup-84bf8dd8-0ef3-4240-8ad1-fc7ec308e216-2020-08-24T10#52#44-07#00.tar.gz + storageLocation: + s3: + bucketName: rajashree-backup-test + folder: ecm1 + region: us-west-2 + endpoint: s3.us-west-2.amazonaws.com + encryptionConfigSecretName: test-encryptionconfig +``` + +# Example Credential Secret for Storing Backups in S3 + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: creds +type: Opaque +data: + accessKey: + secretKey: +``` + +# Example EncryptionConfiguration + +```yaml +apiVersion: apiserver.config.k8s.io/v1 +kind: EncryptionConfiguration +resources: + - resources: + - secrets + providers: + - aesgcm: + keys: + - name: key1 + secret: c2VjcmV0IGlzIHNlY3VyZQ== + - name: key2 + secret: dGhpcyBpcyBwYXNzd29yZA== + - aescbc: + keys: + - name: key1 + secret: c2VjcmV0IGlzIHNlY3VyZQ== + - name: key2 + secret: dGhpcyBpcyBwYXNzd29yZA== + - secretbox: + keys: + - name: key1 + secret: YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY= +``` + + + diff --git a/content/rancher/v2.x/en/backups/legacy/_index.md b/content/rancher/v2.x/en/backups/legacy/_index.md index 2315b1a7b8c..3b35e376401 100644 --- a/content/rancher/v2.x/en/backups/legacy/_index.md +++ b/content/rancher/v2.x/en/backups/legacy/_index.md @@ -1,6 +1,6 @@ --- title: Legacy Backup and Restore Documentation -weight: 1 +weight: 6 --- > This section is under construction. diff --git a/content/rancher/v2.x/en/backups/migrating-rancher/_index.md b/content/rancher/v2.x/en/backups/migrating-rancher/_index.md new file mode 100644 index 00000000000..36563a5ef63 --- /dev/null +++ b/content/rancher/v2.x/en/backups/migrating-rancher/_index.md @@ -0,0 +1,68 @@ +--- +title: Migrating Rancher to a New Cluster +weight: 3 +--- + +If you are migrating Rancher to a new Kubernetes cluster, you don't need to install Rancher on the new cluster first. If Rancher is restored to a new cluster with Rancher already installed, it can cause problems with [permissions](https://github.com/rancher/rancher-backup/issues/24) and [namespaces.](https://github.com/rancher/rancher-backup/issues/6) + +### 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. + +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: + +- [RKE Kubernetes installation docs]({{}}/rke/latest/en/installation/) +- [K3s Kubernetes installation docs]({{}}/k3s/latest/en/installation/) + +### 1. Install the rancher-backup Helm chart +``` +helm repo add rancherchart https://charts.rancher.io +helm repo update +helm install rancher-backup-crd rancherchart/rancher-backup-crd -n cattle-resources-system --create-namespace +helm install rancher-backup rancherchart/rancher-backup -n cattle-resources-system +``` + +### 2. Restore from backup using a Restore custom resource + +In the Restore custom resource, `prune` must be set to false. + +Create a Restore custom resource like the example below: + +```yaml +# migrationResource.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 +``` + +Then apply the resource: + +``` +kubectl apply -f migrationResource.yaml +``` + +### 3. 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. + +### 4. Bring up Rancher with Helm + +``` +helm upgrade rancher rancher-alpha/rancher \ + --version 2.5.0-alpha1 \ + --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 new file mode 100644 index 00000000000..13ba992265f --- /dev/null +++ b/content/rancher/v2.x/en/backups/restoring-rancher/_index.md @@ -0,0 +1,58 @@ +--- +title: Restoring Rancher +weight: 2 +--- + +A restore is performed by creating a Restore custom resource. + +### 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.** + +Create a Restore custom resource such as the following. + +The `prune` directive needs to be set to false so that the secret associated with the operator's service account will not get deleted. + +Replace the `backupFilename` and `storageLocation` with your own information. + +```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