Files
rancher-docs/v2.0-v2.4/pages-for-subheaders/upgrades.html
T

27 lines
64 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-2.0-2.4 plugin-docs plugin-id-default docs-doc-id-pages-for-subheaders/upgrades">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v2.3.1">
<title data-rh="true">Upgrades | Rancher</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://ranchermanager.docs.rancher.com/v2.0-v2.4/pages-for-subheaders/upgrades"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="2.0-2.4"><meta data-rh="true" name="docusaurus_tag" content="docs-default-2.0-2.4"><meta data-rh="true" name="docsearch:version" content="2.0-2.4"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-2.0-2.4"><meta data-rh="true" property="og:title" content="Upgrades | Rancher"><meta data-rh="true" name="description" content="The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm."><meta data-rh="true" property="og:description" content="The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm."><link data-rh="true" rel="icon" href="/img/favicon.png"><link data-rh="true" rel="alternate" href="https://ranchermanager.docs.rancher.com/v2.0-v2.4/pages-for-subheaders/upgrades" hreflang="en"><link data-rh="true" rel="alternate" href="https://ranchermanager.docs.rancher.com/zh/v2.0-v2.4/pages-for-subheaders/upgrades" hreflang="zh"><link data-rh="true" rel="alternate" href="https://ranchermanager.docs.rancher.com/v2.0-v2.4/pages-for-subheaders/upgrades" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://30NEY6C9UY-dsn.algolia.net" crossorigin="anonymous"><link data-rh="true" rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades"><link rel="preconnect" href="https://www.googletagmanager.com">
<script>window.dataLayer=window.dataLayer||[]</script>
<script>!function(e,t,a,n,g){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var m=t.getElementsByTagName(a)[0],r=t.createElement(a);r.async=!0,r.src="https://www.googletagmanager.com/gtm.js?id=GTM-57KS2MW",m.parentNode.insertBefore(r,m)}(window,document,"script","dataLayer")</script>
<link rel="search" type="application/opensearchdescription+xml" title="Rancher" href="/opensearch.xml">
<script src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" charset="UTF-8" data-domain-script="0f98beb0-fc4c-417d-a42e-564e2cae42d2" async></script>
<script src="/scripts/optanonwrapper.js" async></script><link rel="stylesheet" href="/assets/css/styles.efd70281.css">
<link rel="preload" href="/assets/js/runtime~main.5e8050ed.js" as="script">
<link rel="preload" href="/assets/js/main.7c8ccb50.js" as="script">
</head>
<body class="navigation-with-keyboard">
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-57KS2MW" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus">
<div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/rancher-logo-horiz-color.svg" alt="logo" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/rancher-logo-horiz-color.svg" alt="logo" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate"></b></a><div class="navbar__item dropdown dropdown--hoverable"><a aria-current="page" class="navbar__link active" aria-haspopup="true" aria-expanded="false" role="button" href="/v2.0-v2.4">v2.0-v2.4</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/">Latest</a></li><li><a class="dropdown__link" href="/v2.7">v2.7</a></li><li><a class="dropdown__link" href="/v2.6">v2.6</a></li><li><a class="dropdown__link" href="/v2.5">v2.5</a></li><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/v2.0-v2.4/pages-for-subheaders/upgrades">v2.0-v2.4</a></li><li><a class="dropdown__link" href="/versions">All versions</a></li></ul></div></div><div class="navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link"><svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" class="iconLanguage_nlXk"><path fill="currentColor" d="M12.87 15.07l-2.54-2.51.03-.03c1.74-1.94 2.98-4.17 3.71-6.53H17V4h-7V2H8v2H1v1.99h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"></path></svg>English</a><ul class="dropdown__menu"><li><a href="/v2.0-v2.4/pages-for-subheaders/upgrades" target="_self" rel="noopener noreferrer" class="dropdown__link dropdown__link--active" lang="en">English</a></li><li><a href="/zh/v2.0-v2.4/pages-for-subheaders/upgrades" target="_self" rel="noopener noreferrer" class="dropdown__link" lang="zh">简体中文</a></li></ul></div><a href="https://github.com/rancher/rancher-docs" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link navbar__github">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><a href="https://www.rancher.com" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Rancher Home<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="searchBox_ZlJk"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebarViewport_Xe31"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/v2.0-v2.4">Rancher 2.0-2.4</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--active" aria-expanded="true" href="/v2.0-v2.4/getting-started">Getting Started</a><button aria-label="Toggle the collapsible sidebar category &#x27;Getting Started&#x27;" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/introduction">Introduction</a><button aria-label="Toggle the collapsible sidebar category &#x27;Introduction&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/quick-start-guides">Quick Start Guides</a><button aria-label="Toggle the collapsible sidebar category &#x27;Quick Start Guides&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--active" aria-expanded="true" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/installation-and-upgrade">Installation and Upgrade</a><button aria-label="Toggle the collapsible sidebar category &#x27;Installation and Upgrade&#x27;" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-3 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/installation-requirements">Installation Requirements</a><button aria-label="Toggle the collapsible sidebar category &#x27;Installation Requirements&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-3 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--active" aria-expanded="true" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster">Install/Upgrade on a Kubernetes Cluster</a><button aria-label="Toggle the collapsible sidebar category &#x27;Install/Upgrade on a Kubernetes Cluster&#x27;" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-4 menu__list-item"><a class="menu__link" tabindex="0" href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks">Rollbacks</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-4 menu__list-item"><a class="menu__link" tabindex="0" href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting">Troubleshooting the Rancher Server Kubernetes Cluster</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-4 menu__list-item"><div class="menu__list-item-collapsible menu__list-item-collapsible--active"><a class="menu__link menu__link--sublist menu__link--active" aria-current="page" aria-expanded="true" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/upgrades">Upgrades</a><button aria-label="Toggle the collapsible sidebar category &#x27;Upgrades&#x27;" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-5 menu__list-item"><a class="menu__link" tabindex="0" href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on">Migrating from a Kubernetes Install with an RKE Add-on</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-5 menu__list-item"><a class="menu__link" tabindex="0" href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration">Upgrading to v2.0.7+ — Namespace Migration</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-5 menu__list-item"><a class="menu__link" tabindex="0" href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2">Upgrading Rancher Installed on Kubernetes with Helm 2</a></li></ul></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-3 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/other-installation-methods">Other Installation Methods</a><button aria-label="Toggle the collapsible sidebar category &#x27;Other Installation Methods&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-3 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/resources">Resources</a><button aria-label="Toggle the collapsible sidebar category &#x27;Resources&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-and-roll-back-kubernetes">Upgrading and Rolling Back Kubernetes</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link" tabindex="0" href="/v2.0-v2.4/getting-started/installation-and-upgrade/upgrade-kubernetes-without-upgrading-rancher">Upgrading Kubernetes without Upgrading Rancher</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-3 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" tabindex="0" href="/v2.0-v2.4/pages-for-subheaders/advanced-options">Advanced Options</a><button aria-label="Toggle the collapsible sidebar category &#x27;Advanced Options&#x27;" type="button" class="clean-btn menu__caret"></button></div></li></ul></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/v2.0-v2.4/how-to-guides">How-to Guides</a><button aria-label="Toggle the collapsible sidebar category &#x27;How-to Guides&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/v2.0-v2.4/reference-guides">Reference Guides</a><button aria-label="Toggle the collapsible sidebar category &#x27;Reference Guides&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/v2.0-v2.4/explanations">Explanations</a><button aria-label="Toggle the collapsible sidebar category &#x27;Explanations&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/v2.0-v2.4/faq">FAQ</a><button aria-label="Toggle the collapsible sidebar category &#x27;FAQ&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/v2.0-v2.4/troubleshooting">Troubleshooting</a><button aria-label="Toggle the collapsible sidebar category &#x27;Troubleshooting&#x27;" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/v2.0-v2.4/contribute-to-rancher">Contributing to Rancher</a></li></ul></nav></div></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="theme-doc-version-banner alert alert--warning margin-bottom--md" role="alert"><div>This is documentation for <!-- -->Rancher<!-- --> <b>v2.0-v2.4</b>, which is no longer actively maintained.</div><div class="margin-top--md">For up-to-date documentation, see the <b><a href="/">latest version</a></b> (<!-- -->Latest<!-- -->).</div></div><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item"><a class="breadcrumbs__link" itemprop="item" href="/v2.0-v2.4/getting-started"><span itemprop="name">Getting Started</span></a><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item"><a class="breadcrumbs__link" itemprop="item" href="/v2.0-v2.4/pages-for-subheaders/installation-and-upgrade"><span itemprop="name">Installation and Upgrade</span></a><meta itemprop="position" content="2"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item"><a class="breadcrumbs__link" itemprop="item" href="/v2.0-v2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster"><span itemprop="name">Install/Upgrade on a Kubernetes Cluster</span></a><meta itemprop="position" content="3"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Upgrades</span><meta itemprop="position" content="4"></li></ul></nav><span class="theme-doc-version-badge badge badge--secondary">Version: v2.0-v2.4</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Upgrades</h1></header><p>The following instructions will guide you through upgrading a Rancher server that was installed on a Kubernetes cluster with Helm. These steps also apply to air gap installs with Helm.</p><p>For the instructions to upgrade Rancher installed with Docker, refer to <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher">this page.</a></p><p>To upgrade the components in your Kubernetes cluster, or the definition of the <a href="https://rancher.com/docs/rke/latest/en/config-options/services/" target="_blank" rel="noopener noreferrer">Kubernetes services</a> or <a href="https://rancher.com/docs/rke/latest/en/config-options/add-ons/" target="_blank" rel="noopener noreferrer">add-ons</a>, refer to the <a href="https://rancher.com/docs/rke/latest/en/upgrades/" target="_blank" rel="noopener noreferrer">upgrade documentation for RKE</a>, the Rancher Kubernetes Engine.</p><p>If you installed Rancher using the RKE Add-on yaml, follow the directions to <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on">migrate or upgrade</a>.</p><ul><li><a href="#prerequisites">Prerequisites</a></li><li><a href="#upgrade-outline">Upgrade Outline</a></li><li><a href="#known-upgrade-issues">Known Upgrade Issues</a></li><li><a href="#rke-add-on-installs">RKE Add-on Installs</a></li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="prerequisites">Prerequisites<a href="#prerequisites" class="hash-link" aria-label="Direct link to Prerequisites" title="Direct link to Prerequisites">​</a></h2><h3 class="anchor anchorWithStickyNavbar_LWe7" id="access-to-kubeconfig">Access to kubeconfig<a href="#access-to-kubeconfig" class="hash-link" aria-label="Direct link to Access to kubeconfig" title="Direct link to Access to kubeconfig">​</a></h3><p>Helm should be run from the same location as your kubeconfig file, or the same location where you run your kubectl commands from.</p><p>If you installed Kubernetes with RKE, the config will have been created in the directory you ran <code>rke up</code> in.</p><p>The kubeconfig can also be manually targeted for the intended cluster with the <code>--kubeconfig</code> tag (see: <a href="https://helm.sh/docs/helm/helm/" target="_blank" rel="noopener noreferrer">https://helm.sh/docs/helm/helm/</a>)</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="review-known-issues">Review Known Issues<a href="#review-known-issues" class="hash-link" aria-label="Direct link to Review Known Issues" title="Direct link to Review Known Issues">​</a></h3><p>Review the <a href="#known-upgrade-issues">known upgrade issues</a> in the Rancher documentation for the most noteworthy issues to consider when upgrading Rancher.</p><p>A more complete list of known issues for each Rancher version can be found in the release notes on <a href="https://github.com/rancher/rancher/releases" target="_blank" rel="noopener noreferrer">GitHub</a> and on the <a href="https://forums.rancher.com/c/announcements/12" target="_blank" rel="noopener noreferrer">Rancher forums.</a></p><p>Note that upgrades <em>to</em> or <em>from</em> any chart in the <a href="/v2.0-v2.4/reference-guides/installation-references/helm-chart-options#helm-chart-repositories/">rancher-alpha repository</a> aren&#x27;t supported.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="helm-version">Helm Version<a href="#helm-version" class="hash-link" aria-label="Direct link to Helm Version" title="Direct link to Helm Version">​</a></h3><p>The upgrade instructions assume you are using Helm 3.</p><p>For migration of installs started with Helm 2, refer to the official <a href="https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/" target="_blank" rel="noopener noreferrer">Helm 2 to 3 migration docs.</a> The <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2">Helm 2 upgrade page here</a>provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="for-air-gap-installs-populate-private-registry">For air gap installs: Populate private registry<a href="#for-air-gap-installs-populate-private-registry" class="hash-link" aria-label="Direct link to For air gap installs: Populate private registry" title="Direct link to For air gap installs: Populate private registry">​</a></h3><p>-For <a href="/v2.0-v2.4/pages-for-subheaders/air-gapped-helm-cli-install">air gap installs only,</a> collect and populate images for the new Rancher server version. Follow the guide to <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images">populate your private registry</a> with the images for the Rancher version that you want to upgrade to.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="for-upgrades-from-v20-v22-with-external-tls-termination">For upgrades from v2.0-v2.2 with external TLS termination<a href="#for-upgrades-from-v20-v22-with-external-tls-termination" class="hash-link" aria-label="Direct link to For upgrades from v2.0-v2.2 with external TLS termination" title="Direct link to For upgrades from v2.0-v2.2 with external TLS termination">​</a></h3><p>If you are upgrading Rancher from v2.x to v2.3+, and you are using external TLS termination, you will need to edit the cluster.yml to <a href="/v2.0-v2.4/reference-guides/installation-references/helm-chart-options#configuring-ingress-for-external-tls-when-using-nginx-v0-25">enable using forwarded host headers.</a></p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="for-upgrades-with-cert-manager-older-than-080">For upgrades with cert-manager older than 0.8.0<a href="#for-upgrades-with-cert-manager-older-than-080" class="hash-link" aria-label="Direct link to For upgrades with cert-manager older than 0.8.0" title="Direct link to For upgrades with cert-manager older than 0.8.0">​</a></h3><p><a href="https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753" target="_blank" rel="noopener noreferrer">Let&#x27;s Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.</a> Upgrade cert-manager to the latest version by following <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager">these instructions.</a></p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="upgrade-outline">Upgrade Outline<a href="#upgrade-outline" class="hash-link" aria-label="Direct link to Upgrade Outline" title="Direct link to Upgrade Outline">​</a></h2><p>Follow the steps to upgrade Rancher server:</p><ul><li><a href="#1-back-up-your-kubernetes-cluster-that-is-running-rancher-server">1. Back up your Kubernetes cluster that is running Rancher server</a></li><li><a href="#2-update-the-helm-chart-repository">2. Update the Helm chart repository</a></li><li><a href="#3-upgrade-rancher">3. Upgrade Rancher</a></li><li><a href="#4-verify-the-upgrade">4. Verify the Upgrade</a></li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="1-back-up-your-kubernetes-cluster-that-is-running-rancher-server">1. Back up Your Kubernetes Cluster that is Running Rancher Server<a href="#1-back-up-your-kubernetes-cluster-that-is-running-rancher-server" class="hash-link" aria-label="Direct link to 1. Back up Your Kubernetes Cluster that is Running Rancher Server" title="Direct link to 1. Back up Your Kubernetes Cluster that is Running Rancher Server">​</a></h2><p><a href="/v2.0-v2.4/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/back-up-rancher-launched-kubernetes-clusters#option-b-one-time-snapshots">Take a one-time snapshot</a>
of your Kubernetes cluster running Rancher server.</p><p>You&#x27;ll use the backup as a restoration point if something goes wrong during upgrade.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="2-update-the-helm-chart-repository">2. Update the Helm chart repository<a href="#2-update-the-helm-chart-repository" class="hash-link" aria-label="Direct link to 2. Update the Helm chart repository" title="Direct link to 2. Update the Helm chart repository">​</a></h2><ol><li><p>Update your local helm repo cache.</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm repo update</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li><p>Get the repository name that you used to install Rancher.</p><p>For information about the repos and their differences, see <a href="/v2.0-v2.4/reference-guides/installation-references/helm-chart-options#helm-chart-repositories">Helm Chart Repositories</a>.</p><ul><li>Latest: Recommended for trying out the newest features<div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm repo add rancher-latest https://releases.rancher.com/server-charts/latest</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li>Stable: Recommended for production environments<div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm repo add rancher-stable https://releases.rancher.com/server-charts/stable</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li>Alpha: Experimental preview of upcoming releases.<div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm repo add rancher-stable https://releases.rancher.com/server-charts/stable</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> Note: Upgrades are not supported to, from, or between Alphas.</li></ul><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm repo list</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">NAME URL</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">stable https://charts.helm.sh/stable</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">rancher-&lt;CHART_REPO&gt; https://releases.rancher.com/server-charts/&lt;CHART_REPO&gt;</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><blockquote><p><strong>Note:</strong> If you want to switch to a different Helm chart repository, please follow the <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/resources/choose-a-rancher-version#switching-to-a-different-helm-chart-repository">steps on how to switch repositories</a>. If you switch repositories, make sure to list the repositories again before continuing onto Step 3 to ensure you have the correct one added.</p></blockquote></li></ol><ol><li><p>Fetch the latest chart to install Rancher from the Helm chart repository.</p><p>This command will pull down the latest charts and save it in the current directory as a <code>.tgz</code> file.</p><div class="language-plain codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-plain codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm fetch rancher-&lt;CHART_REPO&gt;/rancher</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>You can fetch the chart for the specific version you are upgrading to by adding in the <code>--version=</code> tag. For example:</p><div class="language-plain codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-plain codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm fetch rancher-&lt;CHART_REPO&gt;/rancher --version=v2.4.11</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li></ol><h2 class="anchor anchorWithStickyNavbar_LWe7" id="3-upgrade-rancher">3. Upgrade Rancher<a href="#3-upgrade-rancher" class="hash-link" aria-label="Direct link to 3. Upgrade Rancher" title="Direct link to 3. Upgrade Rancher">​</a></h2><p>This section describes how to upgrade normal (Internet-connected) or air gap installations of Rancher with Helm.</p><div class="tabs-container tabList__CuJ"><ul role="tablist" aria-orientation="horizontal" class="tabs"><li role="tab" tabindex="0" aria-selected="true" class="tabs__item tabItem_LNqP tabs__item--active">Kubernetes Upgrade</li><li role="tab" tabindex="-1" aria-selected="false" class="tabs__item tabItem_LNqP">Kubernetes Air Gap Upgrade</li></ul><div class="margin-top--md"><div role="tabpanel" class="tabItem_Ymn6"><p>Get the values, which were passed with <code>--set</code>, from the current Rancher Helm chart that is installed.</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm get values rancher -n cattle-system</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">hostname: rancher.my.org</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><blockquote><p><strong>Note:</strong> There will be more values that are listed with this command. This is just an example of one of the values.</p></blockquote><p>If you are also upgrading cert-manager to the latest version from a version older than 0.11.0, follow <a href="#option-b-reinstalling-rancher-and-cert-manager">Option B: Reinstalling Rancher and cert-manager.</a></p><p>Otherwise, follow <a href="#option-a-upgrading-rancher">Option A: Upgrading Rancher.</a></p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="option-a-upgrading-rancher">Option A: Upgrading Rancher<a href="#option-a-upgrading-rancher" class="hash-link" aria-label="Direct link to Option A: Upgrading Rancher" title="Direct link to Option A: Upgrading Rancher">​</a></h3><p>Upgrade Rancher to the latest version with all your settings.</p><p>Take all the values from the previous step and append them to the command using <code>--set key=value</code>:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm upgrade rancher rancher-&lt;CHART_REPO&gt;/rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --namespace cattle-system \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --set hostname=rancher.my.org</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><blockquote><p><strong>Note:</strong> The above is an example, there may be more values from the previous step that need to be appended.</p></blockquote><p>Alternatively, it&#x27;s possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm get values rancher -n cattle-system -o yaml &gt; values.yaml</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm upgrade rancher rancher-&lt;CHART_REPO&gt;/rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --namespace cattle-system \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> -f values.yaml \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> --version=2.4.5</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="option-b-reinstalling-rancher-and-cert-manager">Option B: Reinstalling Rancher and cert-manager<a href="#option-b-reinstalling-rancher-and-cert-manager" class="hash-link" aria-label="Direct link to Option B: Reinstalling Rancher and cert-manager" title="Direct link to Option B: Reinstalling Rancher and cert-manager">​</a></h3><p>If you are currently running the cert-manager whose version is older than v0.11, and want to upgrade both Rancher and cert-manager to a newer version, then you need to reinstall both Rancher and cert-manager due to the API change in cert-manager v0.11.</p><ol><li><p>Uninstall Rancher</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm delete rancher -n cattle-system</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li><li><p>Uninstall and reinstall <code>cert-manager</code> according to the instructions on the <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/resources/upgrade-cert-manager-helm-2">Upgrading Cert-Manager</a> page.</p></li><li><p>Reinstall Rancher to the latest version with all your settings. Take all the values from the step 1 and append them to the command using <code>--set key=value</code>. Note: There will be many more options from the step 1 that need to be appended.</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm install rancher rancher-&lt;CHART_REPO&gt;/rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--namespace cattle-system \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set hostname=rancher.my.org</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></li></ol></div><div role="tabpanel" class="tabItem_Ymn6" hidden=""><p>Render the Rancher template using the same chosen options that were used when installing Rancher. Use the reference table below to replace each placeholder. Rancher needs to be configured to use the private registry in order to provision any Rancher launched Kubernetes clusters or Rancher tools.</p><p>Based on the choice you made during installation, complete one of the procedures below.</p><table><thead><tr><th>Placeholder</th><th>Description</th></tr></thead><tbody><tr><td><code>&lt;VERSION&gt;</code></td><td>The version number of the output tarball.</td></tr><tr><td><code>&lt;RANCHER.YOURDOMAIN.COM&gt;</code></td><td>The DNS name you pointed at your load balancer.</td></tr><tr><td><code>&lt;REGISTRY.YOURDOMAIN.COM:PORT&gt;</code></td><td>The DNS name for your private registry.</td></tr><tr><td><code>&lt;CERTMANAGER_VERSION&gt;</code></td><td>Cert-manager version running on k8s cluster.</td></tr></tbody></table><h3 class="anchor anchorWithStickyNavbar_LWe7" id="option-a-default-self-signed-certificate">Option A: Default Self-signed Certificate<a href="#option-a-default-self-signed-certificate" class="hash-link" aria-label="Direct link to Option A: Default Self-signed Certificate" title="Direct link to Option A: Default Self-signed Certificate">​</a></h3><div class="language-plain codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-plain codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm template ./rancher-&lt;VERSION&gt;.tgz --output-dir . \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--name rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--namespace cattle-system \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set hostname=&lt;RANCHER.YOURDOMAIN.COM&gt; \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set certmanager.version=&lt;CERTMANAGER_VERSION&gt; \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set rancherImage=&lt;REGISTRY.YOURDOMAIN.COM:PORT&gt;/rancher/rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set systemDefaultRegistry=&lt;REGISTRY.YOURDOMAIN.COM:PORT&gt; \ # Available as of v2.2.0, set a default private registry to be used in Rancher</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="option-b-certificates-from-files-using-kubernetes-secrets">Option B: Certificates from Files using Kubernetes Secrets<a href="#option-b-certificates-from-files-using-kubernetes-secrets" class="hash-link" aria-label="Direct link to Option B: Certificates from Files using Kubernetes Secrets" title="Direct link to Option B: Certificates from Files using Kubernetes Secrets">​</a></h3><div class="language-plain codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-plain codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm template ./rancher-&lt;VERSION&gt;.tgz --output-dir . \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--name rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--namespace cattle-system \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set hostname=&lt;RANCHER.YOURDOMAIN.COM&gt; \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set rancherImage=&lt;REGISTRY.YOURDOMAIN.COM:PORT&gt;/rancher/rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set ingress.tls.source=secret \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set systemDefaultRegistry=&lt;REGISTRY.YOURDOMAIN.COM:PORT&gt; \ # Available as of v2.2.0, set a default private registry to be used in Rancher</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>If you are using a Private CA signed cert, add <code>--set privateCA=true</code> following <code>--set ingress.tls.source=secret</code>:</p><div class="language-plain codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-plain codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm template ./rancher-&lt;VERSION&gt;.tgz --output-dir . \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--name rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--namespace cattle-system \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set hostname=&lt;RANCHER.YOURDOMAIN.COM&gt; \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set rancherImage=&lt;REGISTRY.YOURDOMAIN.COM:PORT&gt;/rancher/rancher \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set ingress.tls.source=secret \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set privateCA=true \</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set systemDefaultRegistry=&lt;REGISTRY.YOURDOMAIN.COM:PORT&gt; \ # Available as of v2.2.0, set a default private registry to be used in Rancher</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">--set useBundledSystemChart=true # Available as of v2.3.0, use the packaged Rancher system charts</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="apply-the-rendered-templates">Apply the Rendered Templates<a href="#apply-the-rendered-templates" class="hash-link" aria-label="Direct link to Apply the Rendered Templates" title="Direct link to Apply the Rendered Templates">​</a></h3><p>Copy the rendered manifest directories to a system with access to the Rancher server cluster and apply the rendered templates.</p><p>Use <code>kubectl</code> to apply the rendered manifests.</p><div class="language-plain codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-plain codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">kubectl -n cattle-system apply -R -f ./rancher</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="4-verify-the-upgrade">4. Verify the Upgrade<a href="#4-verify-the-upgrade" class="hash-link" aria-label="Direct link to 4. Verify the Upgrade" title="Direct link to 4. Verify the Upgrade">​</a></h2><p>Log into Rancher to confirm that the upgrade succeeded.</p><blockquote><p><strong>Having network issues following upgrade?</strong></p><p>See <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration#restoring-cluster-networking">Restoring Cluster Networking</a>.</p></blockquote><h2 class="anchor anchorWithStickyNavbar_LWe7" id="known-upgrade-issues">Known Upgrade Issues<a href="#known-upgrade-issues" class="hash-link" aria-label="Direct link to Known Upgrade Issues" title="Direct link to Known Upgrade Issues">​</a></h2><p>The following table lists some of the most noteworthy issues to be considered when upgrading Rancher. A more complete list of known issues for each Rancher version can be found in the release notes on <a href="https://github.com/rancher/rancher/releases" target="_blank" rel="noopener noreferrer">GitHub</a> and on the <a href="https://forums.rancher.com/c/announcements/12" target="_blank" rel="noopener noreferrer">Rancher forums.</a></p><table><thead><tr><th>Upgrade Scenario</th><th>Issue</th></tr></thead><tbody><tr><td>Upgrading to v2.4.6 or v2.4.7</td><td>These Rancher versions had an issue where the <code>kms:ListKeys</code> permission was required to create, edit, or clone Amazon EC2 node templates. This requirement was removed in v2.4.8.</td></tr><tr><td>Upgrading to v2.3.0+</td><td>Any user provisioned cluster will be automatically updated upon any edit as tolerations were added to the images used for Kubernetes provisioning.</td></tr><tr><td>Upgrading to v2.2.0-v2.2.x</td><td>Rancher introduced the <a href="https://github.com/rancher/system-charts" target="_blank" rel="noopener noreferrer">system charts</a> repository which contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. To be able to use these features in an air gap install, you will need to mirror the <code>system-charts</code> repository locally and configure Rancher to use that repository. Please follow the instructions to <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/resources/local-system-charts">configure Rancher system charts</a>.</td></tr><tr><td>Upgrading from v2.0.13 or earlier</td><td>If your cluster&#x27;s certificates have expired, you will need to perform <a href="/v2.0-v2.4/how-to-guides/advanced-user-guides/manage-clusters/rotate-certificates#rotating-expired-certificates-after-upgrading-older-rancher-versions">additional steps</a> to rotate the certificates.</td></tr><tr><td>Upgrading from v2.0.7 or earlier</td><td>Rancher introduced the <code>system</code> project, which is a project that&#x27;s automatically created to store important namespaces that Kubernetes needs to operate. During upgrade to v2.0.7+, Rancher expects these namespaces to be unassigned from all projects. Before beginning upgrade, check your system namespaces to make sure that they&#x27;re unassigned to <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration">prevent cluster networking issues.</a></td></tr></tbody></table><h2 class="anchor anchorWithStickyNavbar_LWe7" id="rke-add-on-installs">RKE Add-on Installs<a href="#rke-add-on-installs" class="hash-link" aria-label="Direct link to RKE Add-on Installs" title="Direct link to RKE Add-on Installs">​</a></h2><p><strong>Important: RKE add-on install is only supported up to Rancher v2.0.8</strong></p><p>Please use the Rancher helm chart to install Rancher on a Kubernetes cluster. For details, see the <a href="/v2.0-v2.4/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster">Kubernetes Install</a>.</p><p>If you are currently using the RKE add-on install method, see <a href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on">Migrating from a RKE add-on install</a> for details on how to move to using the helm chart.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/rancher/rancher-docs/edit/main/versioned_docs/version-2.0-2.4/pages-for-subheaders/upgrades.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"><span class="theme-last-updated">Last updated<!-- --> on <b><time datetime="2023-05-26T18:18:59.000Z">May 26, 2023</time></b></span></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><a class="pagination-nav__link pagination-nav__link--prev" href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/troubleshooting"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Troubleshooting the Rancher Server Kubernetes Cluster</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/v2.0-v2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/migrating-from-rke-add-on"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Migrating from a Kubernetes Install with an RKE Add-on</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#prerequisites" class="table-of-contents__link toc-highlight">Prerequisites</a><ul><li><a href="#access-to-kubeconfig" class="table-of-contents__link toc-highlight">Access to kubeconfig</a></li><li><a href="#review-known-issues" class="table-of-contents__link toc-highlight">Review Known Issues</a></li><li><a href="#helm-version" class="table-of-contents__link toc-highlight">Helm Version</a></li><li><a href="#for-air-gap-installs-populate-private-registry" class="table-of-contents__link toc-highlight">For air gap installs: Populate private registry</a></li><li><a href="#for-upgrades-from-v20-v22-with-external-tls-termination" class="table-of-contents__link toc-highlight">For upgrades from v2.0-v2.2 with external TLS termination</a></li><li><a href="#for-upgrades-with-cert-manager-older-than-080" class="table-of-contents__link toc-highlight">For upgrades with cert-manager older than 0.8.0</a></li></ul></li><li><a href="#upgrade-outline" class="table-of-contents__link toc-highlight">Upgrade Outline</a></li><li><a href="#1-back-up-your-kubernetes-cluster-that-is-running-rancher-server" class="table-of-contents__link toc-highlight">1. Back up Your Kubernetes Cluster that is Running Rancher Server</a></li><li><a href="#2-update-the-helm-chart-repository" class="table-of-contents__link toc-highlight">2. Update the Helm chart repository</a></li><li><a href="#3-upgrade-rancher" class="table-of-contents__link toc-highlight">3. Upgrade Rancher</a><ul><li><a href="#option-a-upgrading-rancher" class="table-of-contents__link toc-highlight">Option A: Upgrading Rancher</a></li><li><a href="#option-b-reinstalling-rancher-and-cert-manager" class="table-of-contents__link toc-highlight">Option B: Reinstalling Rancher and cert-manager</a></li><li><a href="#option-a-default-self-signed-certificate" class="table-of-contents__link toc-highlight">Option A: Default Self-signed Certificate</a></li><li><a href="#option-b-certificates-from-files-using-kubernetes-secrets" class="table-of-contents__link toc-highlight">Option B: Certificates from Files using Kubernetes Secrets</a></li><li><a href="#apply-the-rendered-templates" class="table-of-contents__link toc-highlight">Apply the Rendered Templates</a></li></ul></li><li><a href="#4-verify-the-upgrade" class="table-of-contents__link toc-highlight">4. Verify the Upgrade</a></li><li><a href="#known-upgrade-issues" class="table-of-contents__link toc-highlight">Known Upgrade Issues</a></li><li><a href="#rke-add-on-installs" class="table-of-contents__link toc-highlight">RKE Add-on Installs</a></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2023 SUSE Rancher. All Rights Reserved.</div></div></div></footer></div>
<script src="/assets/js/runtime~main.5e8050ed.js"></script>
<script src="/assets/js/main.7c8ccb50.js"></script>
</body>
</html>