mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 20:48:11 +00:00
2.5: Apply Divio and update links
This commit is contained in:
Billy Tat
@@ -1,73 +0,0 @@
|
||||
---
|
||||
title: Backing up Rancher
|
||||
weight: 1
|
||||
aliases:
|
||||
- /rancher/v2.5/en/backups/v2.5/back-up-rancher
|
||||
- /rancher/v2.x/en/backups/
|
||||
- /rancher/v2.x/en/backups/v2.5/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 to the instructions for [single node backups]({{<baseurl>}}/rancher/v2.5/en/backups/v2.5/docker-installs/docker-backups).
|
||||
|
||||
The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster.
|
||||
|
||||
Note that the rancher-backup operator version 1.x.x is for Rancher v2.5.x.
|
||||
|
||||
> When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made. The Kubernetes version should also be considered when restoring a backup, since the supported apiVersion in the cluster and in the backup file could be different.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Rancher version must be v2.5.0 and up
|
||||
|
||||
### 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** view for the local cluster.
|
||||
1. Click **Apps.**
|
||||
1. Click **Rancher Backups.**
|
||||
1. Configure the default storage location. For help, refer to the [storage configuration section.](../configuration/storage-config)
|
||||
|
||||
>**NOTE:** There are two known issues in Fleet that occur after performing a restoration using the backup-restore-operator: Fleet agents are inoperable and clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here]({{<baseurl>}}/rancher/v2.5/en/deploy-across-clusters/fleet/#troubleshooting) for workarounds.
|
||||
|
||||
### 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 the YAML editor.
|
||||
1. For configuring the Backup details using the form, click **Create** and refer to the [configuration reference](../configuration/backup-config) and to the [examples.](../examples/#backup)
|
||||
1. For using the YAML editor, we can click **Create > Create from YAML.** Enter the Backup YAML. This example Backup custom resource would create encrypted recurring backups in S3. The app uses the `credentialSecretNamespace` value to determine where to look for the S3 backup secret:
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: s3-recurring-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: rancher
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
schedule: "@every 1h"
|
||||
retentionCount: 10
|
||||
```
|
||||
|
||||
> **Note:** When creating the Backup resource using YAML editor, the `resourceSetName` must be set to `rancher-resource-set`
|
||||
|
||||
For help configuring the Backup, refer to the [configuration reference](../configuration/backup-config) and to the [examples.](../examples/#backup)
|
||||
|
||||
> **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.
|
||||
|
||||
@@ -1,122 +0,0 @@
|
||||
---
|
||||
title: Backups and Disaster Recovery
|
||||
weight: 5
|
||||
aliases:
|
||||
- /rancher/v2.5/en/backups/v2.5
|
||||
- /rancher/v2.x/en/backups/v2.5/
|
||||
---
|
||||
|
||||
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 Kubernetes cluster.
|
||||
|
||||
As of Rancher v2.5, the `rancher-backup` operator is used to backup and restore Rancher. The `rancher-backup` Helm chart is [here.](https://github.com/rancher/charts/tree/release-v2.5/charts/rancher-backup)
|
||||
|
||||
The backup-restore operator needs to be installed in the local cluster, and only backs up the Rancher app. The backup and restore operations are performed only in the local Kubernetes cluster.
|
||||
|
||||
> When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made.
|
||||
|
||||
- [Changes in Rancher v2.5](#changes-in-rancher-v2-5)
|
||||
- [Backup and Restore for Rancher v2.5 installed with Docker](#backup-and-restore-for-rancher-v2-5-installed-with-docker)
|
||||
- [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)
|
||||
- [RBAC](#rbac)
|
||||
- [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 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 v2.5 installed with Docker
|
||||
|
||||
For Rancher installed with Docker, refer to the same steps used up till 2.5 for [backups](./docker-installs/docker-backups) and [restores.](./docker-installs/docker-restores)
|
||||
|
||||
# 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. This ResourceSet should not be modified.
|
||||
|
||||
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. It is a cluster-admin only feature and available only for the **local** cluster. (*If you do not see `rancher-backup` in the Rancher UI, you may have selected the wrong cluster.*)
|
||||
|
||||
>**NOTE:** There are two known issues in Fleet that occur after performing a restoration using the backup-restore-operator: Fleet agents are inoperable and clientSecretName and helmSecretName are not included in Fleet gitrepos. Refer [here]({{<baseurl>}}rancher/v2.5/en/deploy-across-clusters/fleet/#troubleshooting) for workarounds.
|
||||
|
||||
### Installing rancher-backup with the Rancher UI
|
||||
|
||||
1. In the Rancher UI's Cluster Manager, choose the cluster named **local**
|
||||
1. On the upper-right click on 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 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
|
||||
helm install rancher-backup rancher-charts/rancher-backup -n cattle-resources-system
|
||||
```
|
||||
|
||||
### RBAC
|
||||
|
||||
Only the rancher admins and the local cluster’s cluster-owner can:
|
||||
|
||||
* Install the Chart
|
||||
* 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
|
||||
|
||||
# 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.]({{<baseurl>}}/rancher/v2.5/en/backups/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.](./configuration/storage-config)
|
||||
|
||||
### Example values.yaml for the rancher-backup Helm Chart
|
||||
|
||||
The example [values.yaml file](./configuration/storage-config/#example-values-yaml-for-the-rancher-backup-helm-chart) can be used to configure the `rancher-backup` operator when the Helm CLI is used to install it.
|
||||
@@ -1,186 +0,0 @@
|
||||
---
|
||||
title: Backup Configuration
|
||||
shortTitle: Backup
|
||||
weight: 1
|
||||
aliases:
|
||||
- /rancher/v2.5/en/backups/v2.5/configuration/backup-config
|
||||
- /rancher/v2.x/en/backups/v2.5/configuration/backup-config/
|
||||
---
|
||||
|
||||
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" "">}}
|
||||
|
||||
- [Schedule](#schedule)
|
||||
- [Encryption](#encryption)
|
||||
- [Storage Location](#storage-location)
|
||||
- [S3](#s3)
|
||||
- [Example S3 Storage Configuration](#example-s3-storage-configuration)
|
||||
- [Example MinIO Configuration](#example-minio-configuration)
|
||||
- [Example credentialSecret](#example-credentialsecret)
|
||||
- [IAM Permissions for EC2 Nodes to Access S3](#iam-permissions-for-ec2-nodes-to-access-s3)
|
||||
- [Examples](#examples)
|
||||
|
||||
|
||||
# Schedule
|
||||
|
||||
Select the first option to perform a one-time backup, or select the second option to schedule recurring backups. Selecting **Recurring Backups** lets you configure following two fields:
|
||||
|
||||
- **Schedule**: This field accepts
|
||||
- Standard [cron expressions](https://en.wikipedia.org/wiki/Cron), such as `"0 * * * *"`
|
||||
- Descriptors, such as `"@midnight"` or `"@every 1h30m"`
|
||||
- **Retention Count**: This value specifies how many backup files must be retained. If files exceed the given retentionCount, the oldest files will be deleted. The default value is 10.
|
||||
|
||||
{{< img "/img/rancher/backup_restore/backup/schedule.png" "">}}
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `schedule` | Provide the cron string for scheduling recurring backups. |
|
||||
| `retentionCount` | Provide the number of backup files to be retained. |
|
||||
|
||||
# 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.
|
||||
|
||||
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 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.
|
||||
|
||||
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 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.
|
||||
|
||||
The `Encryption Config Secret` dropdown will filter out and list only those Secrets that have this exact key
|
||||
|
||||
{{< img "/img/rancher/backup_restore/backup/encryption.png" "">}}
|
||||
|
||||
In the example command above, the name `encryptionconfig` can be changed to anything.
|
||||
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `encryptionConfigSecretName` | Provide the name of the Secret from `cattle-resources-system` namespace, that contains the encryption config file. |
|
||||
|
||||
# Storage Location
|
||||
|
||||
{{< img "/img/rancher/backup_restore/backup/storageLocation.png" "">}}
|
||||
|
||||
If the StorageLocation is specified in the Backup, the operator will retrieve the backup location from that particular S3 bucket. If not specified, the operator will try to find this file in the default operator-level S3 store, and in the operator-level PVC store. The default storage location is configured during the deployment of the `rancher-backup` operator.
|
||||
|
||||
Selecting the first option stores this backup in the storage location configured while installing the rancher-backup chart. The second option lets you configure a different S3 compatible storage provider for storing the backup.
|
||||
|
||||
### S3
|
||||
|
||||
The S3 storage location contains the following configuration fields:
|
||||
|
||||
1. **Credential Secret** (optional): 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. 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) The Credential Secret dropdown lists the secrets in all namespaces.
|
||||
1. **Bucket Name**: The name of the S3 bucket where backup files will be stored.
|
||||
1. **Region** (optional): The AWS [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) where the S3 bucket is located. This field isn't needed for configuring MinIO.
|
||||
1. **Folder** (optional): The name of the folder in the S3 bucket where backup files will be stored. Nested folders (e.g., `rancher/cluster1`) are not supported.
|
||||
1. **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.
|
||||
1. **Endpoint CA** (optional): This should be the Base64 encoded CA cert. For an example, refer to the [example S3 compatible configuration.](#example-s3-storage-configuration)
|
||||
1. **Skip TLS Verifications** (optional): Set to true if you are not using TLS.
|
||||
|
||||
|
||||
| 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. Nested folders (e.g., `rancher/cluster1`) are not supported. | |
|
||||
| `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 Storage Configuration
|
||||
|
||||
```yaml
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: rancher
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
```
|
||||
|
||||
### Example MinIO Configuration
|
||||
|
||||
```yaml
|
||||
s3:
|
||||
credentialSecretName: minio-creds
|
||||
bucketName: rancherbackups
|
||||
endpoint: minio.35.202.130.254.sslip.io
|
||||
endpointCA: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURHakNDQWdLZ0F3SUJBZ0lKQUtpWFZpNEpBb0J5TUEwR0NTcUdTSWIzRFFFQkN3VUFNQkl4RURBT0JnTlYKQkFNTUIzUmxjM1F0WTJFd0hoY05NakF3T0RNd01UZ3lOVFE1V2hjTk1qQXhNREk1TVRneU5UUTVXakFTTVJBdwpEZ1lEVlFRRERBZDBaWE4wTFdOaE1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBCjA4dnV3Q2Y0SEhtR2Q2azVNTmozRW5NOG00T2RpS3czSGszd1NlOUlXQkwyVzY5WDZxenBhN2I2M3U2L05mMnkKSnZWNDVqeXplRFB6bFJycjlpbEpWaVZ1NFNqWlFjdG9jWmFCaVNsL0xDbEFDdkFaUlYvKzN0TFVTZSs1ZDY0QQpWcUhDQlZObU5xM3E3aVY0TE1aSVpRc3N6K0FxaU1Sd0pOMVVKQTZ6V0tUc2Yzc3ByQ0J2dWxJWmZsVXVETVAyCnRCTCt6cXZEc0pDdWlhNEEvU2JNT29tVmM2WnNtTGkwMjdub3dGRld3MnRpSkM5d0xMRE14NnJoVHQ4a3VvVHYKQXJpUjB4WktiRU45L1Uzb011eUVKbHZyck9YS2ZuUDUwbk8ycGNaQnZCb3pUTStYZnRvQ1d5UnhKUmI5cFNTRApKQjlmUEFtLzNZcFpMMGRKY2sxR1h3SURBUUFCbzNNd2NUQWRCZ05WSFE0RUZnUVU5NHU4WXlMdmE2MTJnT1pyCm44QnlFQ2NucVFjd1FnWURWUjBqQkRzd09ZQVU5NHU4WXlMdmE2MTJnT1pybjhCeUVDY25xUWVoRnFRVU1CSXgKRURBT0JnTlZCQU1NQjNSbGMzUXRZMkdDQ1FDb2wxWXVDUUtBY2pBTUJnTlZIUk1FQlRBREFRSC9NQTBHQ1NxRwpTSWIzRFFFQkN3VUFBNElCQVFER1JRZ1RtdzdVNXRQRHA5Q2psOXlLRW9Vd2pYWWM2UlAwdm1GSHpubXJ3dUVLCjFrTkVJNzhBTUw1MEpuS29CY0ljVDNEeGQ3TGdIbTNCRE5mVVh2anArNnZqaXhJYXR2UWhsSFNVaWIyZjJsSTkKVEMxNzVyNCtROFkzelc1RlFXSDdLK08vY3pJTGh5ei93aHRDUlFkQ29lS1dXZkFiby8wd0VSejZzNkhkVFJzNwpHcWlGNWZtWGp6S0lOcTBjMHRyZ0xtalNKd1hwSnU0ZnNGOEcyZUh4b2pOKzdJQ1FuSkg5cGRIRVpUQUtOL2ppCnIvem04RlZtd1kvdTBndEZneWVQY1ZWbXBqRm03Y0ZOSkc4Y2ZYd0QzcEFwVjhVOGNocTZGeFBHTkVvWFZnclMKY1VRMklaU0RJd1FFY3FvSzFKSGdCUWw2RXBaUVpWMW1DRklrdFBwSQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t
|
||||
```
|
||||
### Example credentialSecret
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: creds
|
||||
type: Opaque
|
||||
data:
|
||||
accessKey: <Enter your base64-encoded access key>
|
||||
secretKey: <Enter your base64-encoded secret key>
|
||||
```
|
||||
|
||||
### 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:::rancher-backups"
|
||||
]
|
||||
},
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"s3:PutObject",
|
||||
"s3:GetObject",
|
||||
"s3:DeleteObject",
|
||||
"s3:PutObjectAcl"
|
||||
],
|
||||
"Resource": [
|
||||
"arn:aws:s3:::rancher-backups/*"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
# Examples
|
||||
|
||||
For example Backup custom resources, refer to [this page.](../../examples/#backup)
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
title: Rancher Backup Configuration Reference
|
||||
shortTitle: Configuration
|
||||
weight: 4
|
||||
aliases:
|
||||
- /rancher/v2.5/en/backups/v2.5/configuration
|
||||
- /rancher/v2.x/en/backups/v2.5/configuration/
|
||||
---
|
||||
|
||||
- [Backup configuration](./backup-config)
|
||||
- [Restore configuration](./restore-config)
|
||||
- [Storage location configuration](./storage-config)
|
||||
- [Example Backup and Restore Custom Resources](../examples)
|
||||
@@ -1,90 +0,0 @@
|
||||
---
|
||||
title: Restore Configuration
|
||||
shortTitle: Restore
|
||||
weight: 2
|
||||
aliases:
|
||||
- /rancher/v2.5/en/backups/v2.5/configuration/restore-config
|
||||
- /rancher/v2.x/en/backups/v2.5/configuration/restore-config/
|
||||
---
|
||||
|
||||
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)
|
||||
- [An Existing Backup Config](#an-existing-backup-config)
|
||||
- [The default storage target](#the-default-storage-target)
|
||||
- [An S3-compatible object store](#an-s3-compatible-object-store)
|
||||
- [Encryption](#encryption)
|
||||
- [Prune during restore](#prune-during-restore)
|
||||
- [Getting the Backup Filename from S3](#getting-the-backup-filename-from-s3)
|
||||
|
||||
# Backup Source
|
||||
Provide details of the backup file and its storage location, which the operator will then use to perform the restore. Select from the following options to provide these details
|
||||
|
||||
|
||||
|
||||
|
||||
### An existing backup config
|
||||
|
||||
Selecting this option will populate the **Target Backup** dropdown with the Backups available in this cluster. Select the Backup from the dropdown, and that will fill out the **Backup Filename** field for you, and will also pass the backup source information from the selected Backup to the operator.
|
||||
|
||||
{{< img "/img/rancher/backup_restore/restore/existing.png" "">}}
|
||||
|
||||
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 the default storage target or an S3-compatible object store.
|
||||
|
||||
|
||||
### 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" "">}}
|
||||
|
||||
### 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 to [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/#storage-location)
|
||||
|
||||
{{< img "/img/rancher/backup_restore/restore/s3store.png" "">}}
|
||||
|
||||
# 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
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `encryptionConfigSecretName` | Provide the name of the Secret from `cattle-resources-system` namespace, that contains the encryption config file. |
|
||||
|
||||
> **Important**
|
||||
This field should only be set if the backup was created with encryption enabled. Providing the incorrect encryption config will cause the restore to fail.
|
||||
|
||||
# Prune During Restore
|
||||
|
||||
* **Prune**: In order to fully restore Rancher from a backup, and to go back to the exact state it was at when the backup was performed, we need to delete any additional resources that were created by Rancher after the backup was taken. The operator does so if the **Prune** flag is enabled. Prune is enabled by default and it is recommended to keep it enabled.
|
||||
* **Delete Timeout**: This is the amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again.
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `prune` | Delete the resources managed by Rancher that are not present in the backup (Recommended). |
|
||||
| `deleteTimeoutSeconds` | Amount of time the operator will wait while deleting a resource before editing the resource to remove finalizers and attempt deletion again. |
|
||||
|
||||
# Getting the Backup Filename from S3
|
||||
|
||||
This is the name of the backup file that the `rancher-backup` operator will use to perform the restore.
|
||||
|
||||
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 assuming the name of your backup file is `backupfile`,
|
||||
|
||||
- If your bucket name is `s3bucket` and no folder was specified, then the `backupFilename` to use will be `backupfile`.
|
||||
- If your bucket name is `s3bucket` and the base folder is`s3folder`, the `backupFilename` to use is only `backupfile` .
|
||||
- If there is a subfolder inside `s3Folder` called `s3sub`, and that has your backup file, then the `backupFilename` to use is `s3sub/backupfile`.
|
||||
|
||||
| YAML Directive Name | Description |
|
||||
| ---------------- | ---------------- |
|
||||
| `backupFilename` | This is the name of the backup file that the `rancher-backup` operator will use to perform the restore. |
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
title: Backup Storage Location Configuration
|
||||
shortTitle: Storage
|
||||
weight: 3
|
||||
aliases:
|
||||
- /rancher/v2.5/en/backups/v2.5/configuration/storage-config
|
||||
- /rancher/v2.x/en/backups/v2.5/configuration/storage-config/
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
Only one storage location can be configured at the operator level.
|
||||
|
||||
- [Storage Location Configuration](#storage-location-configuration)
|
||||
- [No Default Storage Location](#no-default-storage-location)
|
||||
- [S3-compatible Object Store](#s3-compatible-object-store)
|
||||
- [Use an existing StorageClass](#existing-storageclass)
|
||||
- [Use an existing PersistentVolume](#existing-persistent-volume)
|
||||
- [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
|
||||
|
||||
You can choose to not have any operator-level storage location configured. If you select this option, you must configure an S3-compatible object store as the storage location for each individual backup.
|
||||
|
||||
### S3-compatible Object Store
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------- | -------------- |
|
||||
| Credential Secret | Choose the credentials for S3 from your secrets in Rancher. [Example]({{<baseurl>}}/rancher/v2.5/en/backups/v2.5/examples/#example-credential-secret-for-storing-backups-in-s3). |
|
||||
| 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 |
|
||||
| insecureTLSSkipVerify | Set to true if you are not using TLS. |
|
||||
|
||||
### Existing StorageClass
|
||||
|
||||
Installing the `rancher-backup` chart by selecting the StorageClass option will create a Persistent Volume Claim (PVC), and Kubernetes will in turn dynamically provision a Persistent Volume (PV) where all the backups will be saved by default.
|
||||
|
||||
For information about creating storage classes refer to [this section.]({{<baseurl>}}/rancher/v2.5/en/cluster-admin/volumes-and-storage/provisioning-new-storage/)
|
||||
|
||||
> **Important**
|
||||
It is highly recommended to use a StorageClass with a reclaim policy of "Retain". Otherwise if the PVC created by the `rancher-backup` chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted.
|
||||
If no such StorageClass is available, after the PV is provisioned, make sure to edit its reclaim policy and set it to "Retain" before storing backups in it.
|
||||
|
||||
### Existing Persistent Volume
|
||||
|
||||
Select an existing Persistent Volume (PV) that will be used to store your backups. For information about creating PersistentVolumes in Rancher, refer to [this section.]({{<baseurl>}}/rancher/v2.5/en/cluster-admin/volumes-and-storage/attaching-existing-storage/#2-add-a-persistent-volume-that-refers-to-the-persistent-storage)
|
||||
|
||||
> **Important**
|
||||
It is highly recommended to use a Persistent Volume with a reclaim policy of "Retain". Otherwise if the PVC created by the `rancher-backup` chart gets deleted (either during app upgrade, or accidentally), the PV will get deleted too, which means all backups saved in it will get deleted.
|
||||
|
||||
|
||||
# Example values.yaml for the rancher-backup Helm Chart
|
||||
|
||||
The documented `values.yaml` file that can be used to configure `rancher-backup` operator when the Helm CLI is used can be found in the [backup-restore-operator repository.](https://github.com/rancher/backup-restore-operator/blob/release/v1.0/charts/rancher-backup/values.yaml)
|
||||
|
||||
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)
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
title: Backing up Rancher Installed with Docker
|
||||
shortTitle: Backups
|
||||
weight: 3
|
||||
aliases:
|
||||
- /rancher/v2.5/en/installation/after-installation/single-node-backup-and-restoration/
|
||||
- /rancher/v2.5/en/installation/after-installation/single-node-backup-and-restoration/
|
||||
- /rancher/v2.5/en/backups/backups/single-node-backups/
|
||||
- /rancher/v2.5/en/backups/legacy/backup/single-node-backups/
|
||||
- /rancher/v2.5/en/backups/v2.5/docker-installs/docker-backups/
|
||||
- /rancher/v2.x/en/backups/v2.5/docker-installs/docker-backups/
|
||||
---
|
||||
|
||||
|
||||
After completing your Docker installation of Rancher, we recommend creating backups of it on a regular basis. Having a recent backup will let you recover quickly from an unexpected disaster.
|
||||
|
||||
## Before You Start
|
||||
|
||||
During the creation of your backup, you'll enter a series of commands, replacing placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data-<DATE> -v $PWD:/backup busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
```
|
||||
|
||||
In this command, `<DATE>` is a placeholder for the date that the data container and backup were created. `9-27-18` for example.
|
||||
|
||||
Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the [procedure below](#creating-a-backup).
|
||||
|
||||
<sup>Terminal <code>docker ps</code> Command, Displaying Where to Find <code><RANCHER_CONTAINER_TAG></code> and <code><RANCHER_CONTAINER_NAME></code></sup>
|
||||
|
||||
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
| -------------------------- | -------------------------- | --------------------------------------------------------- |
|
||||
| `<RANCHER_CONTAINER_TAG>` | `v2.0.5` | The rancher/rancher image you pulled for initial install. |
|
||||
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
|
||||
| `<RANCHER_VERSION>` | `v2.0.5` | The version of Rancher that you're creating a backup for. |
|
||||
| `<DATE>` | `9-27-18` | The date that the data container or backup was created. |
|
||||
<br/>
|
||||
|
||||
You can obtain `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>` by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped with `docker ps -a`. Use these commands for help anytime while creating backups.
|
||||
|
||||
## Creating a Backup
|
||||
|
||||
This procedure creates a backup that you can restore if Rancher encounters a disaster scenario.
|
||||
|
||||
|
||||
1. Using a remote Terminal connection, log into the node running your Rancher Server.
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container.
|
||||
|
||||
```
|
||||
docker stop <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
1. <a id="backup"></a>Use the command below, replacing each placeholder, to create a data container from the Rancher container that you just stopped.
|
||||
|
||||
```
|
||||
docker create --volumes-from <RANCHER_CONTAINER_NAME> --name rancher-data-<DATE> rancher/rancher:<RANCHER_CONTAINER_TAG>
|
||||
```
|
||||
|
||||
1. <a id="tarball"></a>From the data container that you just created (<code>rancher-data-<DATE></code>), create a backup tarball (<code>rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz</code>). Use the following command, replacing each placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from rancher-data-<DATE> -v $PWD:/backup:z busybox tar pzcvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz /var/lib/rancher
|
||||
```
|
||||
|
||||
**Step Result:** A stream of commands runs on the screen.
|
||||
|
||||
1. Enter the `ls` command to confirm that the backup tarball was created. It will have a name similar to `rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`.
|
||||
|
||||
1. Move your backup tarball to a safe location external to your Rancher Server. Then delete the `rancher-data-<DATE>` container from your Rancher Server.
|
||||
|
||||
1. Restart Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container:
|
||||
|
||||
```
|
||||
docker start <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
|
||||
**Result:** A backup tarball of your Rancher Server data is created. See [Restoring Backups: Docker Installs]({{<baseurl>}}/rancher/v2.5/en/backups/restorations/single-node-restoration) if you need to restore backup data.
|
||||
@@ -8,5 +8,5 @@ aliases:
|
||||
- /rancher/v2.x/en/backups/v2.5/docker-installs/
|
||||
---
|
||||
|
||||
- [Backups](./docker-backups)
|
||||
- [Restores](./docker-restores)
|
||||
- [Backups](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-docker-installed-rancher.md)
|
||||
- [Restores](../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-docker-installed-rancher.md)
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
title: Restoring Backups—Docker Installs
|
||||
shortTitle: Restores
|
||||
weight: 3
|
||||
aliases:
|
||||
- /rancher/v2.5/en/installation/after-installation/single-node-backup-and-restoration/
|
||||
- /rancher/v2.5/en/backups/restorations/single-node-restoration
|
||||
- /rancher/v2.5/en/backups/v2.5/docker-installs/docker-restores
|
||||
- /rancher/v2.x/en/backups/v2.5/docker-installs/docker-restores/
|
||||
---
|
||||
|
||||
If you encounter a disaster scenario, you can restore your Rancher Server to your most recent backup.
|
||||
|
||||
## Before You Start
|
||||
|
||||
During restore of your backup, you'll enter a series of commands, filling placeholders with data from your environment. These placeholders are denoted with angled brackets and all capital letters (`<EXAMPLE>`). Here's an example of a command with a placeholder:
|
||||
|
||||
```
|
||||
docker run --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
|
||||
busybox sh -c "rm /var/lib/rancher/* -rf && \
|
||||
tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>"
|
||||
```
|
||||
|
||||
In this command, `<RANCHER_CONTAINER_NAME>` and `<RANCHER_VERSION>-<DATE>` are environment variables for your Rancher deployment.
|
||||
|
||||
Cross reference the image and reference table below to learn how to obtain this placeholder data. Write down or copy this information before starting the procedure below.
|
||||
|
||||
<sup>Terminal <code>docker ps</code> Command, Displaying Where to Find <code><RANCHER_CONTAINER_TAG></code> and <code><RANCHER_CONTAINER_NAME></code></sup>
|
||||
|
||||
|
||||
|
||||
| Placeholder | Example | Description |
|
||||
| -------------------------- | -------------------------- | --------------------------------------------------------- |
|
||||
| `<RANCHER_CONTAINER_TAG>` | `v2.0.5` | The rancher/rancher image you pulled for initial install. |
|
||||
| `<RANCHER_CONTAINER_NAME>` | `festive_mestorf` | The name of your Rancher container. |
|
||||
| `<RANCHER_VERSION>` | `v2.0.5` | The version number for your Rancher backup. |
|
||||
| `<DATE>` | `9-27-18` | The date that the data container or backup was created. |
|
||||
<br/>
|
||||
|
||||
You can obtain `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>` by logging into your Rancher Server by remote connection and entering the command to view the containers that are running: `docker ps`. You can also view containers that are stopped using a different command: `docker ps -a`. Use these commands for help anytime during while creating backups.
|
||||
|
||||
## Restoring Backups
|
||||
|
||||
Using a [backup]({{<baseurl>}}/rancher/v2.5/en/backups/docker-installs/docker-backups/) that you created earlier, restore Rancher to its last known healthy state.
|
||||
|
||||
1. Using a remote Terminal connection, log into the node running your Rancher Server.
|
||||
|
||||
1. Stop the container currently running Rancher Server. Replace `<RANCHER_CONTAINER_NAME>` with the name of your Rancher container:
|
||||
|
||||
```
|
||||
docker stop <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
1. Move the backup tarball that you created during completion of [Creating Backups—Docker Installs]({{<baseurl>}}/rancher/v2.5/en/backups/docker-installs/docker-backups/) onto your Rancher Server. Change to the directory that you moved it to. Enter `dir` to confirm that it's there.
|
||||
|
||||
If you followed the naming convention we suggested in [Creating Backups—Docker Installs]({{<baseurl>}}/rancher/v2.5/en/backups/docker-installs/docker-backups/), it will have a name similar to `rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz`.
|
||||
|
||||
1. Enter the following command to delete your current state data and replace it with your backup data, replacing the placeholders. Don't forget to close the quotes.
|
||||
|
||||
>**Warning!** This command deletes all current state data from your Rancher Server container. Any changes saved after your backup tarball was created will be lost.
|
||||
|
||||
```
|
||||
docker run --volumes-from <RANCHER_CONTAINER_NAME> -v $PWD:/backup \
|
||||
busybox sh -c "rm /var/lib/rancher/* -rf && \
|
||||
tar pzxvf /backup/rancher-data-backup-<RANCHER_VERSION>-<DATE>.tar.gz"
|
||||
```
|
||||
|
||||
**Step Result:** A series of commands should run.
|
||||
|
||||
1. Restart your Rancher Server container, replacing the placeholder. It will restart using your backup data.
|
||||
|
||||
```
|
||||
docker start <RANCHER_CONTAINER_NAME>
|
||||
```
|
||||
|
||||
1. Wait a few moments and then open Rancher in a web browser. Confirm that the restore succeeded and that your data is restored.
|
||||
@@ -1,301 +0,0 @@
|
||||
---
|
||||
title: Examples
|
||||
weight: 5
|
||||
aliases:
|
||||
- /rancher/v2.5/en/backups/v2.5/examples
|
||||
- /rancher/v2.x/en/backups/v2.5/examples/
|
||||
---
|
||||
|
||||
This section contains examples of Backup and Restore custom resources.
|
||||
|
||||
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
|
||||
|
||||
This section contains example Backup custom resources.
|
||||
|
||||
### Backup in the Default Location with Encryption
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: default-location-encrypted-backup
|
||||
spec:
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
### Recurring Backup in the Default Location
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: default-location-recurring-backup
|
||||
spec:
|
||||
resourceSetName: rancher-resource-set
|
||||
schedule: "@every 1h"
|
||||
retentionCount: 10
|
||||
```
|
||||
|
||||
### Encrypted Recurring Backup in the Default Location
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: default-enc-recurring-backup
|
||||
spec:
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
schedule: "@every 1h"
|
||||
retentionCount: 3
|
||||
```
|
||||
|
||||
### Encrypted Backup in Minio
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: minio-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: minio-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancherbackups
|
||||
endpoint: minio.sslip.io
|
||||
endpointCA: LS0tLS1CRUdJTi3VUFNQkl5UUT.....pbEpWaVzNkRS0tLS0t
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
### Backup in S3 Using AWS Credential Secret
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: s3-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
### Recurring Backup in S3 Using AWS Credential Secret
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Backup
|
||||
metadata:
|
||||
name: s3-recurring-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
schedule: "@every 1h"
|
||||
retentionCount: 10
|
||||
```
|
||||
|
||||
### 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-iam-backup
|
||||
spec:
|
||||
storageLocation:
|
||||
s3:
|
||||
bucketName: rancher-backups
|
||||
folder: ecm1
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
resourceSetName: rancher-resource-set
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
```
|
||||
|
||||
# Restore
|
||||
|
||||
This section contains example Restore custom resources.
|
||||
|
||||
### Restore Using the Default Backup File Location
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-default
|
||||
spec:
|
||||
backupFilename: 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: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
|
||||
prune: false
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
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-encrypted
|
||||
spec:
|
||||
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
|
||||
|
||||
```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.sslip.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: rancher-backups
|
||||
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: <Enter your base64-encoded access key>
|
||||
secretKey: <Enter your base64-encoded secret key>
|
||||
```
|
||||
|
||||
# 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=
|
||||
```
|
||||
@@ -1,105 +0,0 @@
|
||||
---
|
||||
title: Migrating Rancher to a New Cluster
|
||||
weight: 3
|
||||
aliases:
|
||||
- /rancher/v2.x/en/backups/v2.5/migrating-rancher/
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
### 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 required 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:
|
||||
|
||||
- [RKE Kubernetes installation docs]({{<baseurl>}}/rke/latest/en/installation/)
|
||||
- [K3s Kubernetes installation docs]({{<baseurl>}}/k3s/latest/en/installation/)
|
||||
|
||||
### 1. Install the rancher-backup Helm chart
|
||||
Install version 1.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
|
||||
```
|
||||
<br/>
|
||||
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
|
||||
```
|
||||
|
||||
### 2. Restore from backup using a Restore custom resource
|
||||
|
||||
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` containing the s3 credentials like this:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Secret
|
||||
metadata:
|
||||
name: s3-creds
|
||||
type: Opaque
|
||||
stringData:
|
||||
accessKey: <Enter your base64-encoded access key>
|
||||
secretKey: <Enter your base64-encoded secret key>
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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: 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
|
||||
```
|
||||
|
||||
>**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
|
||||
```
|
||||
|
||||
1. Then apply the resource:
|
||||
```
|
||||
kubectl apply -f migrationResource.yaml
|
||||
```
|
||||
|
||||
### 3. Install cert-manager
|
||||
|
||||
Follow the steps to [install cert-manager]({{<baseurl>}}/rancher/v2.5/en/installation/install-rancher-on-k8s/#5-install-cert-manager) in the documentation about installing cert-manager on Kubernetes.
|
||||
|
||||
### 4. Bring up Rancher with Helm
|
||||
|
||||
Use the same version of Helm to install Rancher, that was used on the first cluster.
|
||||
|
||||
```
|
||||
helm install rancher rancher-latest/rancher \
|
||||
--namespace cattle-system \
|
||||
--set hostname=<same hostname as the server URL from the first Rancher server> \
|
||||
```
|
||||
@@ -1,72 +0,0 @@
|
||||
---
|
||||
title: Restoring Rancher
|
||||
weight: 2
|
||||
aliases:
|
||||
- /rancher/v2.x/en/installation/backups/restores
|
||||
- /rancher/v2.x/en/backups/restoring-rancher
|
||||
- /rancher/v2.x/en/backups/v2.5/restoring-rancher/
|
||||
---
|
||||
|
||||
A restore is performed by creating a Restore custom resource.
|
||||
|
||||
> **Important**
|
||||
>
|
||||
> * Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.]({{<baseurl>}}/rancher/v2.5/en/backups/migrating-rancher)
|
||||
> * While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore.
|
||||
> * When restoring a backup into a new Rancher setup, the version of the new setup should be the same as the one where the backup is made.
|
||||
|
||||
### 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 creating the Restore resource using form, refer to the [configuration reference]({{<baseurl>}}/rancher/v2.5/en/backups/configuration/restore-config) and to the [examples.]({{<baseurl>}}/rancher/v2.5/en/backups/examples)
|
||||
1. For using the YAML editor, we can click **Create > Create from YAML.** Enter the Restore YAML.
|
||||
|
||||
```yaml
|
||||
apiVersion: resources.cattle.io/v1
|
||||
kind: Restore
|
||||
metadata:
|
||||
name: restore-migration
|
||||
spec:
|
||||
backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz
|
||||
encryptionConfigSecretName: encryptionconfig
|
||||
storageLocation:
|
||||
s3:
|
||||
credentialSecretName: s3-creds
|
||||
credentialSecretNamespace: default
|
||||
bucketName: rancher-backups
|
||||
folder: rancher
|
||||
region: us-west-2
|
||||
endpoint: s3.us-west-2.amazonaws.com
|
||||
```
|
||||
|
||||
For help configuring the Restore, refer to the [configuration reference]({{<baseurl>}}/rancher/v2.5/en/backups/configuration/restore-config) and to the [examples.]({{<baseurl>}}/rancher/v2.5/en/backups/examples)
|
||||
|
||||
1. Click **Create.**
|
||||
|
||||
**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
|
||||
|
||||
### Logs
|
||||
|
||||
To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs:
|
||||
|
||||
```
|
||||
kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
|
||||
If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores.
|
||||
|
||||
### Known Issues
|
||||
In some cases, after restoring the backup, Rancher logs will show errors similar to the following:
|
||||
```
|
||||
2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing
|
||||
```
|
||||
This happens because one of the resources that was just restored has finalizers but the related resources have been deleted so the handler cannot find it.
|
||||
|
||||
To eliminate the errors, we need to find and delete the resource that causes the error. See more information [here](https://github.com/rancher/rancher/issues/35050#issuecomment-937968556)
|
||||
Reference in New Issue
Block a user