rancher-docs/assets/js/d503b0b0.6a2731fa.js

"use strict";(self.webpackChunkrancher_docs=self.webpackChunkrancher_docs||[]).push([[79458],{3905:(e,r,t)=>{t.d(r,{Zo:()=>u,kt:()=>d});var n=t(67294);function a(e,r,t){return r in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function o(e,r){var t=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);r&&(n=n.filter((function(r){return Object.getOwnPropertyDescriptor(e,r).enumerable}))),t.push.apply(t,n)}return t}function s(e){for(var r=1;r<arguments.length;r++){var t=null!=arguments[r]?arguments[r]:{};r%2?o(Object(t),!0).forEach((function(r){a(e,r,t[r])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(t)):o(Object(t)).forEach((function(r){Object.defineProperty(e,r,Object.getOwnPropertyDescriptor(t,r))}))}return e}function i(e,r){if(null==e)return{};var t,n,a=function(e,r){if(null==e)return{};var t,n,a={},o=Object.keys(e);for(n=0;n<o.length;n++)t=o[n],r.indexOf(t)>=0||(a[t]=e[t]);return a}(e,r);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n<o.length;n++)t=o[n],r.indexOf(t)>=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(a[t]=e[t])}return a}var l=n.createContext({}),c=function(e){var r=n.useContext(l),t=r;return e&&(t="function"==typeof e?e(r):s(s({},r),e)),t},u=function(e){var r=c(e.components);return n.createElement(l.Provider,{value:r},e.children)},p={inlineCode:"code",wrapper:function(e){var r=e.children;return n.createElement(n.Fragment,{},r)}},h=n.forwardRef((function(e,r){var t=e.components,a=e.mdxType,o=e.originalType,l=e.parentName,u=i(e,["components","mdxType","originalType","parentName"]),h=c(t),d=a,m=h["".concat(l,".").concat(d)]||h[d]||p[d]||o;return t?n.createElement(m,s(s({ref:r},u),{},{components:t})):n.createElement(m,s({ref:r},u))}));function d(e,r){var t=arguments,a=r&&r.mdxType;if("string"==typeof e||a){var o=t.length,s=new Array(o);s[0]=h;var i={};for(var l in r)hasOwnProperty.call(r,l)&&(i[l]=r[l]);i.originalType=e,i.mdxType="string"==typeof e?e:a,s[1]=i;for(var c=2;c<o;c++)s[c]=t[c];return n.createElement.apply(null,s)}return n.createElement.apply(null,t)}h.displayName="MDXCreateElement"},77746:(e,r,t)=>{t.r(r),t.d(r,{assets:()=>l,contentTitle:()=>s,default:()=>p,frontMatter:()=>o,metadata:()=>i,toc:()=>c});var n=t(87462),a=(t(67294),t(3905));const o={title:"Restoring Rancher"},s=void 0,i={unversionedId:"how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher",id:"how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher",title:"Restoring Rancher",description:"This page outlines how to perform a restore with Rancher.",source:"@site/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md",sourceDirName:"how-to-guides/new-user-guides/backup-restore-and-disaster-recovery",slug:"/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher",permalink:"/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher",draft:!1,editUrl:"https://github.com/rancher/rancher-docs/edit/main/docs/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md",tags:[],version:"current",lastUpdatedAt:1674854872,formattedLastUpdatedAt:"Jan 27, 2023",frontMatter:{title:"Restoring Rancher"},sidebar:"tutorialSidebar",previous:{title:"Backing up Rancher",permalink:"/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher"},next:{title:"Migrating Rancher to a New Cluster",permalink:"/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster"}},l={},c=[{value:"Additional Steps for Rollbacks with Rancher v2.6.4+",id:"additional-steps-for-rollbacks-with-rancher-v264",level:2},{value:"Rolling back from v2.6.4+ to lower versions of v2.6.x",id:"rolling-back-from-v264-to-lower-versions-of-v26x",level:3},{value:"Create the Restore Custom Resource",id:"create-the-restore-custom-resource",level:3},{value:"Logs",id:"logs",level:3},{value:"Cleanup",id:"cleanup",level:3},{value:"Known Issues",id:"known-issues",level:3}],u={toc:c};function p(e){let{components:r,...t}=e;return(0,a.kt)("wrapper",(0,n.Z)({},u,t,{components:r,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"This page outlines how to perform a restore with Rancher."),(0,a.kt)("admonition",{title:"Important:",type:"note"},(0,a.kt)("ul",{parentName:"admonition"},(0,a.kt)("li",{parentName:"ul"},"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 ",(0,a.kt)("a",{parentName:"li",href:"/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster"},"migrate rancher.")),(0,a.kt)("li",{parentName:"ul"},"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."),(0,a.kt)("li",{parentName:"ul"},"If you need to restore Rancher to a previous version after an upgrade, see the ",(0,a.kt)("a",{parentName:"li",href:"/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks"},"rollback documentation.")))),(0,a.kt)("h2",{id:"additional-steps-for-rollbacks-with-rancher-v264"},"Additional Steps for Rollbacks with Rancher v2.6.4+"),(0,a.kt)("p",null,"Rancher v2.6.4 upgrades the cluster-api module from v0.4.4 to v1.0.2. Version v1.0.2 of the cluster-api, in turn, upgrades the Cluster API's  Custom Resource Definitions (CRDs) from ",(0,a.kt)("inlineCode",{parentName:"p"},"cluster.x-k8s.io/v1alpha4")," to ",(0,a.kt)("inlineCode",{parentName:"p"},"cluster.x-k8s.io/v1beta1"),". The CRDs upgrade to v1beta1 causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. This is because CRDs that use the older apiVersion (v1alpha4) are incompatible with v1beta1."),(0,a.kt)("p",null,"To avoid rollback failure, the following Rancher scripts should be run ",(0,a.kt)("strong",{parentName:"p"},"before")," you attempt a restore operation or rollback: "),(0,a.kt)("ul",null,(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"verify.sh"),":  Checks for any Rancher-related resources in the cluster. "),(0,a.kt)("li",{parentName:"ul"},(0,a.kt)("inlineCode",{parentName:"li"},"cleanup.sh"),": Cleans up the cluster.")),(0,a.kt)("p",null,"See the ",(0,a.kt)("a",{parentName:"p",href:"https://github.com/rancher/rancher-cleanup"},"rancher/rancher-cleanup repo")," for more details and source code."),(0,a.kt)("admonition",{type:"caution"},(0,a.kt)("p",{parentName:"admonition"}," There will be downtime while ",(0,a.kt)("inlineCode",{parentName:"p"},"cleanup.sh")," runs, since the script deletes resources created by Rancher.")),(0,a.kt)("h3",{id:"rolling-back-from-v264-to-lower-versions-of-v26x"},"Rolling back from v2.6.4+ to lower versions of v2.6.x"),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},"Follow these ",(0,a.kt)("a",{parentName:"li",href:"https://github.com/rancher/rancher-cleanup/blob/main/README.md"},"instructions")," to run the scripts."),(0,a.kt)("li",{parentName:"ol"},"Follow these ",(0,a.kt)("a",{parentName:"li",href:"https://rancher.com/docs/rancher/v2.6/en/backups/migrating-rancher/"},"instructions")," to install the rancher-backup Helm chart on the existing cluster and restore the previous state.",(0,a.kt)("ol",{parentName:"li"},(0,a.kt)("li",{parentName:"ol"},"Omit Step 3."),(0,a.kt)("li",{parentName:"ol"},"When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to.")))),(0,a.kt)("h3",{id:"create-the-restore-custom-resource"},"Create the Restore Custom Resource"),(0,a.kt)("p",null,"A restore is performed by creating a Restore custom resource."),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("p",{parentName:"li"},"In the upper left corner, click ",(0,a.kt)("strong",{parentName:"p"},"\u2630 > Cluster Management"),".")),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("p",{parentName:"li"},"On the ",(0,a.kt)("strong",{parentName:"p"},"Clusters")," page, go to the ",(0,a.kt)("inlineCode",{parentName:"p"},"local")," cluster and click ",(0,a.kt)("strong",{parentName:"p"},"Explore"),". The ",(0,a.kt)("inlineCode",{parentName:"p"},"local")," cluster runs the Rancher server.")),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("p",{parentName:"li"},"In the left navigation bar, click ",(0,a.kt)("strong",{parentName:"p"},"Rancher Backups > Restores"),".")),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("p",{parentName:"li"},"Click ",(0,a.kt)("strong",{parentName:"p"},"Create"),".")),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("p",{parentName:"li"},"Create the Restore with the form, or with YAML.  For creating the Restore resource using form, refer to the ",(0,a.kt)("a",{parentName:"p",href:"/reference-guides/backup-restore-configuration/restore-configuration"},"configuration reference")," and to the ",(0,a.kt)("a",{parentName:"p",href:"/reference-guides/backup-restore-configuration/examples"},"examples."))),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("p",{parentName:"li"},"For using the YAML editor, we can click ",(0,a.kt)("strong",{parentName:"p"},"Create > Create from YAML"),". Enter the Restore YAML."),(0,a.kt)("pre",{parentName:"li"},(0,a.kt)("code",{parentName:"pre",className:"language-yaml"},"apiVersion: resources.cattle.io/v1\nkind: Restore\nmetadata:\n  name: restore-migration\nspec:\n  backupFilename: backup-b0450532-cee1-4aa1-a881-f5f48a007b1c-2020-09-15T07-27-09Z.tar.gz\n  encryptionConfigSecretName: encryptionconfig\n  storageLocation:\n    s3:\n      credentialSecretName: s3-creds\n      credentialSecretNamespace: default\n      bucketName: rancher-backups\n      folder: rancher\n      region: us-west-2\n      endpoint: s3.us-west-2.amazonaws.com\n")),(0,a.kt)("p",{parentName:"li"},"  For help configuring the Restore, refer to the ",(0,a.kt)("a",{parentName:"p",href:"/reference-guides/backup-restore-configuration/restore-configuration"},"configuration reference")," and to the ",(0,a.kt)("a",{parentName:"p",href:"/reference-guides/backup-restore-configuration/examples"},"examples."))),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("p",{parentName:"li"},"Click ",(0,a.kt)("strong",{parentName:"p"},"Create"),"."))),(0,a.kt)("p",null,(0,a.kt)("strong",{parentName:"p"},"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:"),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},"Custom Resource Definitions (CRDs)"),(0,a.kt)("li",{parentName:"ol"},"Cluster-scoped resources"),(0,a.kt)("li",{parentName:"ol"},"Namespaced resources")),(0,a.kt)("h3",{id:"logs"},"Logs"),(0,a.kt)("p",null,"To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f\n")),(0,a.kt)("h3",{id:"cleanup"},"Cleanup"),(0,a.kt)("p",null,"If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores."),(0,a.kt)("h3",{id:"known-issues"},"Known Issues"),(0,a.kt)("p",null,"In some cases, after restoring the backup, Rancher logs will show errors similar to the following:"),(0,a.kt)("pre",null,(0,a.kt)("code",{parentName:"pre"},"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\n")),(0,a.kt)("p",null,"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."),(0,a.kt)("p",null,"To eliminate the errors, we need to find and delete the resource that causes the error. See more information ",(0,a.kt)("a",{parentName:"p",href:"https://github.com/rancher/rancher/issues/35050#issuecomment-937968556"},"here")))}p.isMDXComponent=!0}}]);