diff --git a/content/rancher/v2.x/en/catalog/_index.md b/content/rancher/v2.x/en/catalog/_index.md index 48ecd6612fd..bc8595425bb 100644 --- a/content/rancher/v2.x/en/catalog/_index.md +++ b/content/rancher/v2.x/en/catalog/_index.md @@ -19,6 +19,8 @@ This section covers the following topics: - [Catalog scopes](#catalog-scopes) - [Catalog Helm Deployment Versions](#catalog-helm-deployment-versions) +- [When to use Helm 3](#when-to-use-helm-3) +- [Helm 3 Backwards Compatibility](#helm-3-backwards-compatibility) - [Built-in global catalogs](#built-in-global-catalogs) - [Custom catalogs](#custom-catalogs) - [Creating and launching applications](#creating-and-launching-applications) @@ -39,7 +41,7 @@ Project | This specific cluster can access the Helm charts in this catalog | v2 _Applicable as of v2.4.0_ -In November 2019, Helm 3 was released, and some features were deprecated or refactored. It is not fully backwards compatible with Helm 2. Therefore, catalogs in Rancher need to be separated, with each catalog only using one Helm version. +In November 2019, Helm 3 was released, and some features were deprecated or refactored. It is not fully [backwards compatible]({{}}/rancher/v2.x/en/catalog/helm-3-backwards-compatibility) with Helm 2. Therefore, catalogs in Rancher need to be separated, with each catalog only using one Helm version. This will help reduce app deployment issues as your Rancher users will not need to know which version of your chart is compatible with which Helm version - they can just select a catalog, select an app and deploy a version that has already be vetted for compatibility. When you create a custom catalog, you will have to configure the catalog to use either Helm 2 or Helm 3. This version cannot be changed later. If the catalog is added with the wrong Helm version, it will need to be deleted and re-added. @@ -49,6 +51,25 @@ By default, catalogs are assumed to be deployed using Helm 2. If you run an app Charts that are specific to Helm 2 should only be added to a Helm 2 catalog, and Helm 3 specific charts should only be added to a Helm 3 catalog. +# When to use Helm 3 + +_Applicable as of v2.4.0_ + +- If you want to ensure that the security permissions are being pulled from the kubeconfig file +- If you want to utilize apiVersion `v2` features such as creating a library chart to reduce code duplication or moving your requirements from the requirements.yaml into the Chart.yaml + +Overall Helm 3 is a movement towards a more standardized kubernetes feel. As the kubernetes community has evolved, standards and best practices have as well. Helm 3 is an attempt to adopt those practices and streamline how charts are maintained. + +# Helm 3 Backwards Compatibility + +_Applicable as of v2.4.0_ + +With the use of the OpenAPI schema to validate your rendered templates in Helm 3, you will find charts that worked in Helm 2 may not work in Helm 3. This will require you to update your chart templates to meet the new validation requirements. This is one of the main reasons support for Helm 2 and Helm 3 was provided starting in Rancher 2.4.x as not all charts can be deployed immediately in Helm 3. + +Helm 3 does not create a namespace for you, you have to provide an existing one. This can cause issues if you have integrated code with Helm 2, as you will need to make code changes to ensure a namespace is being created and passed in for Helm 3. Rancher will continue to manage namespaces for Helm to ensure this does not impact your app deployment. + +apiVersion `v2` is now reserved for Helm 3 charts. This apiVersion enforcement could cause issues as older versions of Helm 2 did not validate the apiVersion in the Chart.yaml file. In general your Helm 2 chart’s apiVersion should be set to `v1` and your Helm 3 chart’s apiVersion should be set to `v2`. You can install charts with apiVersion `v1` with Helm 3 but you cannot install `v2` charts into Helm 2. + # Built-in Global Catalogs Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator. For details, refer to the section on managing [built-in global catalogs.]({{}}/rancher/v2.x/en/catalog/built-in)