Update catalog docs with rancher v2.2.0 new features

2026-09-09 10:45:48 +00:00 · 2019-03-22 10:07:37 -07:00
parent a35a12812b
commit 0dc6bc9e9d
12 changed files with 130 additions and 4 deletions
@@ -11,7 +11,7 @@ aliases:

 Rancher provides a catalog of charts that make it easy to repeatedly deploy any applications.

-_Catalogs_ are GitHub repositories filled with applications that are ready-made for deployment. Applications are bundled in objects called _charts_.
+_Catalogs_ are GitHub repositories or Helm Chart Repository filled with applications that are ready-made for deployment. Applications are bundled in objects called _charts_.

 _Charts_ are a packaging format popularized by [Helm](https://docs.helm.sh/). Think of them as templates for deployments. Per Helm, charts are:

@@ -44,13 +44,35 @@ Within Rancher, there are default catalogs packaged as part of Rancher. These ca

 ## Adding Custom Catalogs

-Adding a catalog is as simple as adding a catalog name, a URL and a branch name. The URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will use the `master` branch by default. Whenever you add a catalog to Rancher, it will be available immediately.
+Adding a catalog is as simple as adding a catalog name, a URL and a branch name. 
+
+
+#### Add Custom Git Repositories
+The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will use the `master` branch by default. Whenever you add a catalog to Rancher, it will be available immediately.
+
+
+#### Add Custom Helm Chart Repositories
+
+A Helm chart repository is an HTTP server that houses one or more packaged charts. Any HTTP server that can serve YAML files and tar files and can answer GET requests can be used as a repository server.
+
+Helm comes with built-in package server for developer testing (helm serve). The Helm team has tested other servers, including Google Cloud Storage with website mode enabled, S3 with website mode enabled or hosting custom chart repository server using open-source projects like [ChartMuseum](https://github.com/helm/chartmuseum).
+
+In Rancher, You can add the custom Helm chart repository with only specify a catalog name and the URL address of the chart repository.
+
+#### Add Private Git/Helm Chart Repositories
+_Available as of v2.2.0_
+
+From Rancher v2.2.0, you can now select to add private catalog repositories using credentials like Username and Password, you may also want to use the 
+OAuth token if your Git or Helm repository server support that.
+
+[Read More About Adding Private Git/Helm Catalogs]({{< baseurl >}}/rancher/v2.x/en/catalog/private/)
+

 >**Notes:**
 >
 >- Currently, you can only add custom catalogs to Rancher at the global level. Therefore, any catalog that you add is shared with all clusters and projects.
 >
->- Currently, only unauthenticated catalogs are supported.
+>- Currently, authenticated catalogs repositories are only supported from Rancher v2.0.0.
 <br/>
 <br/>

@@ -0,0 +1,37 @@
+---
+title: Custom values.yaml for Catalog Apps
+weight: 4035
+aliases:
+  - /rancher/v2.x/en/tasks/global-configuration/catalog/custom-values-for-apps/
+---
+
+For both Rancher or custom catalog apps, the user can override the default values in the `Answers` section.
+
+For example, setting custom values of the default values.yaml
+
+```YAML
+outer:
+  inner: value
+servers:
+- port: 80
+  host: example
+```
+
+need to be translated into `outer.inner=value`, `servers[0].port=80` and `servers[0].host=example` respectively in the Answers section
+(Read more about [Format of Custom Values Using `--Set`](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set)).
+
+![dot-custom-values-form.png]({{< baseurl >}}/img/rancher/catalog/dot-custom-values-form.png)
+or through `Edit as YAML` view:
+![dot-custom-values.png]({{< baseurl >}}/img/rancher/catalog/dot-custom-values.png)
+<hr>
+
+### Supports Real Custom `values.yaml` for Catalog Apps
+_Available as of v2.2.0_
+
+From Rancher v2.2.0, you can now set custom values using a YAML formatted structure through `Edit as YAML`.
+
+![custom-values-yaml.png]({{< baseurl >}}/img/rancher/catalog/custom-values-yaml.png)
+
+It allows the user to customize more complicated input values like multi-lines, array, and JSON object in a user-friendly format compared with `dot-structure`.
+
+![custom-values-yaml-long.png]({{< baseurl >}}/img/rancher/catalog/custom-values-yaml-long.png)
@@ -5,7 +5,7 @@ aliases:
  - /rancher/v2.x/en/tasks/global-configuration/catalog/customizing-charts/
 ---

-Rancher's catalog service requires any custom catalogs to be structured in a specific format for the catalog service to be able to leverage it in Rancher. Any custom catalog must be a public Git repository. The URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`.
+Rancher's catalog service requires any custom catalogs to be structured in a specific format for the catalog service to be able to leverage it in Rancher. Any custom catalog must be a Git or Helm chart repository. The Git URL needs to be one that `git clone` [can handle](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) and must end in `.git`.

 ## Chart Types

@@ -0,0 +1,31 @@
+---
+title: Force Upgrade Catalog Apps
+weight: 4040
+aliases:
+  - /rancher/v2.x/en/tasks/global-configuration/catalog/force-upgrade-catalog-apps/
+---
+
+_Available as of v2.2.0_
+
+Using `force-upgrade` will force Rancher catalog apps to delete and recreate resources if needed during the upgrade.
+
+
+### How to Force-upgrade Catalog Apps
+
+For both upgrade and rollback, the user can select the `Delete and recreate resources if needed during the upgrade` checkbox at the bottom of the catalog app details page to force-upgrade the app.
+
+![force-upgrade.png]({{< baseurl >}}/img/rancher/catalog/force-upgrade.png)
+
+
+### When to Use The Force-upgrade and Cautions
+
+In Kubernetes, some fields are designed to be immutable or cannot be updated directly, e.g. changing Service type from NodePort to ClusterIP will result in:
+```
+Error: UPGRADE FAILED: Service "docker-registry" is invalid: spec.ports[0].nodePort: Forbidden: may not be used when `type` is 'ClusterIP'
+```
+and `force-upgrade` will be recreating resources for immutable fields when force is applied.
+
+>**Cautions:**
+>
+>- Don't force-upgrade resources that contain persistent data, e.g. Statefulset or Deployment with Bounded PVC.
+
@@ -0,0 +1,36 @@
+---
+title: Add Private Catalogs
+weight: 4030
+aliases:
+  - /rancher/v2.x/en/tasks/global-configuration/catalog/add-private-catalogs/
+---
+
+### Add Private Git/Helm Chart Repositories
+_Available as of v2.2.0_
+
+From Rancher v2.2.0, you can now select to add private catalog repositories using credentials like Username and Password, you may also want to use the 
+OAuth token if your Git or Helm repository server support that.
+
+![add-private-catalog.png]({{< baseurl >}}/img/rancher/catalog/add-private-catalog.png)
+
+As an example, if you want to add a private Github repository as your custom catalog using OAuth token:
+
+1. Firstly, you will need to create an [OAuth token](https://github.com/settings/tokens) 
+with `repo` permission selected, and click **Generate token**.
+
+    ![add-git-token.png]({{< baseurl >}}/img/rancher/catalog/add-git-token.png)
+
+
+2. From the `Global -> Catalogs` page, you can now click **Add Catalog** to add your custom private chart repository:
+
+    | Variable              |  Description  |
+    | --------------------  | ------------- |
+    | 	Name                | Custom catalog name. |
+    | 	Catalog URL         | Enter the URL of your custom chart repository, e.g, `https://github.com/username/myrepo.git`. |
+    | 	Use Private Catalog | Select if this is private chart repository server. |
+    | 	Username            | Enter your Github username or Git generated OAuth token. |
+    | 	Password            | Enter your Github password or `x-oauth-basic` if OAuth token is provided above, read [using Git over HTTPS and OAuth](https://github.blog/2012-09-21-easier-builds-and-deployments-using-git-over-https-and-oauth/) for more details. |
+    | 	Branch              | Enter your Github branch name, default to master. |
+    
+
+**Result**: Your custom catalog is added to the Rancher with `Active` state once it completes synchronization.