diff --git a/content/rancher/v2.x/en/concepts/catalogs/_index.md b/content/rancher/v2.x/en/concepts/catalogs/_index.md index f4aa0d4203b..ed62cb3b059 100644 --- a/content/rancher/v2.x/en/concepts/catalogs/_index.md +++ b/content/rancher/v2.x/en/concepts/catalogs/_index.md @@ -1,57 +1,77 @@ --- -title: Catalogs +title: Catalogs and Charts weight: 2250 --- -Rancher catalog builds on an enhanced version of Helm. All upstream Helm charts can work within Rancher, but Rancher adds several enhancements to improve the user experience. +_Catalogs_ are GitHub repositories filled with applications that are ready-made for deployment. -### Catalog Git Repositories +Applications are bundled in objects called _charts_, which are a packaging format popularized by [Helm](https://docs.helm.sh/). Think of them as templates for deployments. Per Helm, charts are: -Rancher stores Helm charts in git repositories to expedite the fetch and update of charts. In Rancher 2.0, only global catalogs are supported. Support for cluster-level and project-level charts will be added in the future. +>A collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on. -### Enhanced Revision Tracking +Rancher improves on Helm catalogs and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience. -While Helm supports versioned deployments, Rancher added capabilities to track and display what exactly changed between different revisions. +## Catalog Types -### Streamlined Application Launch +Within Rancher, you can access several different catalogs either by default or through customization. Enable or disable these catalogs by opening the **Global** view and then selecting **Catalogs** from the main menu. -Rancher supports simplified README files and questions files to streamline the application launch process. Users need not read through the entire list of Helm variables to understand how to launch an application. +- **Library** -### Application Resource Management + The Library Catalog includes charts curated by Rancher. Rancher stores charts in a git repository to expedite the fetch and update of charts. In Rancher 2.0, only global catalogs are supported. Support for cluster-level and project-level charts will be added in the future. + + This catalog features Rancher Charts, which include some [notable advantages](#chart-types) over native Helm charts. -Rancher tracks all the resources created by a specific application. Users can easily navigate to and troubleshoot on a page listing all the workload objects used to power an application. +- **Helm Stable** -### Custom Catalogs + This catalog includes native [Helm charts](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md), both of which are maintained by the Kubernetes community. This catalog features the largest pool of apps, but is also the most complex way to deploy charts within Rancher. -Creating a custom catalog for Rancher is straightforward. The catalogs are hosted in Git repositories and cloned into Rancher periodically. +- **Helm Incubator** -The charts themselves are standard [Helm templates](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md), with a few differences outlined below. + Similar in user experience to Helm Stable, but this catalog is filled with applications in BETA. -##### Rancher Chart Structure +- **Custom** -Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a standard chart. + Finally, you have the option of building your own catalogs. Custom catalogs are useful when you have a handful of apps that you deploy regularly in a specific configuration. + +### Custom Catalog Creation + +Creating a custom catalog for Rancher is straightforward. Create a Git Repo and then direct Rancher toward the repo. -Rancher charts differ slightly from native Helm charts in their directory structures. Rancher charts include two files that native Helm charts do not. +For step-by-step directions, see [placeholder](placeholder). -- `app-readme.md` - - A file that provides a high level overview, which displays within Rancher. +When you're done creating the catalog, populate it charts. See [Custom Chart Creation](#custom-chart-creation). - **Example: `app-readme.md` Rancher Output** +## Chart Types - ![app-readme.md]({{< baseurl >}}/img/rancher/app-readme.png) - -- `questions.yml` - - A file containing questions to prompt the user with. +Rancher supports two different types of charts: - **Example: `questions.yml` Rancher Output** +- **Helm Charts** - ![questions.yml]({{< baseurl >}}/img/rancher/questions.png) + Native Helm charts include an application along with other software required to run it. When deploying native Helm charts, you'll learn the chart's parameters and then configure them using **Answers**, which are sets of key value pairs. ->**Tip:** Though we recommend using Rancher charts, you can use native Helm repositories as well. + The Helm Stable and Helm Incubators are populated with native Helm charts. However, you can also use native Helm charts in Custom catalogs (although we recommend Rancher Charts). -The following table lists each file and sub-directory found in a Rancher chart directory: `charts/%application%/%app version%/` +- **Rancher Charts** + + Rancher charts mirror native helm charts, although they add two files that enhance user experience: `app-readme.md` and `questions.yaml`. Read more about them in [Rancher Chart Additional Files](#rancher-chart-additional-files) + + Advantages of Rancher charts include: + + - **Enhanced Revision Tracking** + + While Helm supports versioned deployments, Rancher adds tracking and revision history to display changes between different versions of the chart. + + - **Streamlined Application Launch** + + Rancher charts add simplified chart descriptions and configuration forms to make catalog application deployment easy. Rancher users need not read through the entire list of Helm variables to understand how to launch an application. + + - **Application Resource Management** + + Rancher tracks all the resources created by a specific application. Users can easily navigate to and troubleshoot on a page listing all the workload objects used to power an application. + +### Chart Directory Structure + +The following table demonstrates the directory structure for a chart, which can be found in a chart directory: `charts/%application%/%app version%/`. This information is helpful when customizing charts for a custom catalog. Files denoted with **Rancher Specific** are specific to Rancher charts, but are optional for chart customization. @@ -62,7 +82,7 @@ The following table lists each file and sub-directory found in a Rancher chart d - + @@ -78,7 +98,7 @@ The following table lists each file and sub-directory found in a Rancher chart d - + @@ -102,31 +122,30 @@ The following table lists each file and sub-directory found in a Rancher chart d
app-readme app-readme.md Rancher Specific: Text displayed within Rancher.
questions.ymlRancher Specific: File containing questions displayed within Rancher.Rancher Specific: File containing questions displayed within Rancher.
+### Rancher Chart Additional Files + +Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a native Helm chart. Rancher charts differ slightly from native Helm charts in their directory structures. Rancher charts include two files that native Helm charts do not. + +- `app-readme.md` + + A file that provides descriptive text in the chart's UI header. The following image displays the difference between a Rancher chart (which includes `app-readme.md`) and a native Helm chart (which does not). + + **Example: `app-readme.md` Rancher Output** + + ![app-readme.md]({{< baseurl >}}/img/rancher/app-readme.png) + +- `questions.yml` + + A file that containing questions for a form. These form questions simplify deployment of a chart. Without it, you must configure the deployment using key value pairs, which is more difficult. The following image displays the difference between a Rancher chart (which includes `questions.yml`) and a native Helm chart (which does not). + + + **Example: `questions.yml` Rancher Output** + + ![questions.yml]({{< baseurl >}}/img/rancher/questions.png) + + +### Custom Chart Creation + + You can fill your custom catalog with either Helm Charts or Rancher Charts, although we recommend Rancher Charts due to their enhanced user experience. + >**Note:** For a complete walk through of developing charts, see the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/). - - -#### Question Variable Reference - -This reference contains variables that you can use in `questions.yml`. - -| Variable | Type | Required | Description | -| ------------- | ------------- | --- |------------- | -| variable | string | true | define the variable name specified in the `values.yml` file, using `foo.bar` for nested object. | -| label | string | true | define the UI label. | -| description | string | false | specify the description of the variable.| -| type | string | false | default to `string` if not specified (current supported types are string, boolean, int, enum, password, storageclass and hostname).| -| required | bool | false | define if the variable is required or not (true \| false)| -| default | string | false | specify the default value. | -| group | string | false | group questions by input value. | -| min_length | int | false | min character length.| -| max_length | int | false | max character length.| -| min | int | false | min integer length. | -| max | int | false | max integer length. | -| options | []string | false | specify the options when the vriable type is `enum`, for example: options:
- "ClusterIP"
- "NodePort"
- "LoadBalancer"| -| valid_chars | string | false | regular expression for input chars validation. | -| invalid_chars | string | false | regular expression for invalid input chars validation.| -| subquestions | []subquestion | false| add an array of subquestions.| -| show_if | string | false | show current variable if conditional variable is true, for example `show_if: "serviceType=Nodeport"` | -| show\_subquestion_if | string | false | show subquestions if is true or equal to one of the options. for example `show_subquestion_if: "true"`| - ->**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. diff --git a/content/rancher/v2.x/en/tasks/global-configuration/catalog/_index.md b/content/rancher/v2.x/en/tasks/global-configuration/catalog/_index.md index bf4f7e8f38e..3d768a3db76 100644 --- a/content/rancher/v2.x/en/tasks/global-configuration/catalog/_index.md +++ b/content/rancher/v2.x/en/tasks/global-configuration/catalog/_index.md @@ -1,5 +1,5 @@ --- -title: Catalog +title: Catalogs and Charts weight: 3026 --- @@ -81,3 +81,29 @@ You can create custom catalogs of Helm charts for use in Rancher. Custom catalog 3. Complete the form and click **Create**. **Result**: Your catalog is added to Rancher. The catalog is available for deployment of your applications. + +#### Question Variable Reference + +This reference contains variables that you can use in `questions.yml`. + +| Variable | Type | Required | Description | +| ------------- | ------------- | --- |------------- | +| variable | string | true | define the variable name specified in the `values.yml` file, using `foo.bar` for nested object. | +| label | string | true | define the UI label. | +| description | string | false | specify the description of the variable.| +| type | string | false | default to `string` if not specified (current supported types are string, boolean, int, enum, password, storageclass and hostname).| +| required | bool | false | define if the variable is required or not (true \| false)| +| default | string | false | specify the default value. | +| group | string | false | group questions by input value. | +| min_length | int | false | min character length.| +| max_length | int | false | max character length.| +| min | int | false | min integer length. | +| max | int | false | max integer length. | +| options | []string | false | specify the options when the vriable type is `enum`, for example: options:
- "ClusterIP"
- "NodePort"
- "LoadBalancer"| +| valid_chars | string | false | regular expression for input chars validation. | +| invalid_chars | string | false | regular expression for invalid input chars validation.| +| subquestions | []subquestion | false| add an array of subquestions.| +| show_if | string | false | show current variable if conditional variable is true, for example `show_if: "serviceType=Nodeport"` | +| show\_subquestion_if | string | false | show subquestions if is true or equal to one of the options. for example `show_subquestion_if: "true"`| + +>**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported.