diff --git a/content/rancher/v2.x/en/concepts/catalogs/_index.md b/content/rancher/v2.x/en/concepts/catalogs/_index.md index 570d3a001d7..2fa95c56b5f 100644 --- a/content/rancher/v2.x/en/concepts/catalogs/_index.md +++ b/content/rancher/v2.x/en/concepts/catalogs/_index.md @@ -3,7 +3,7 @@ title: Catalogs weight: 2250 --- -Rancher catalog builds on an enhanced version of Helm. All upstream Helm charts can work on Rancher, but Rancher adds several enhancements to make the user experience better. +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. ## Catalog Git Repositories @@ -20,3 +20,105 @@ Rancher supports simplified README files and questions files to streamline the a ## 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. + +## Custom Catalogs + +Creating a custom catalog for Rancher is straightforward. The catalogs are hosted in Git repositories and cloned into Rancher periodically. + +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. + +## Rancher Chart Structure + +Before you create your own custom catalog, you should have a basic understanding about how a Rancher chart differs from a standard 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 a high level overview, which displays within Rancher. + +- `questions.yml` + + A file containing questions to prompt the user with. + +>**Tip:** Though we recommend using Rancher charts, you can use native Helm repositories as well. + +The following table lists each file and sub-directory found in a Rancher chart directory: `charts/%application%/%app version%/` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Sub-Directory FileDescription
add-readme Rancher Specific: Text displayed within Rancher.
charts/Directory containing dependency charts.
Chart.ymlRequired Helm chart information file.
questions.ymlRancher Specific: File containing questions displayed within Rancher.
README.mdOptional: Helm Readme file displayed within Rancher.
requirements.ymlOptional YAML file listing dependencies for the chart.
templates/A directory of templates that, when combined with values.yml, generates Kubernetes YAML.
values.ymlThe default configuration values for the chart.
+ +>**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"`| + +**subquestions**: `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 0b68be7ce6a..363e596f988 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,113 +1,84 @@ --- -title: Catalog +title: Catalogs weight: 1000 draft: true --- -## Creating Custom Catalogs +Within Rancher, you can use Helm Charts for quick deployment of applications from a central repository. -Creating a custom catalog for Rancher is very straight forward. The catalogs are hosted in Git repositories and cloned into Rancher on a periodic basis. +## Converting Native Helm Charts for Rancher -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. +To convert a native Helm chart for use in Rancher, you must add two files for Rancher: `app-readme.md` and `questions.yml`. -### Rancher Chart Structure +>**Note:** Conversion of Helm charts for use in Rancher takes place outside of the Rancher UI. -A Rancher chart repository differs slightly in directory structure from upstream repos in that it includes an `app version` directory. Though Rancher can use native Helm repositories as well. +1. Create an `app-readme.md` file. +
+
-A Rancher chart also has two additional files an `app-readme.md` file that provides a high level overview display in the Rancher 2.x UI and a `questions.yml` file defining questions to prompt the user with. + **Example**: -``` + ``` + $ cat ./app-readme.md -charts/wordpress// - app-readme.md # Rancher Specific: Readme file for display in Rancher 2.0 UI - charts/ # Directory containing dependency charts - Chart.yaml # Required Helm chart information file - questions.yml # Rancher Specific: File containing questions for Rancher 2. UI - README.md # Optional: Helm Readme file (will be rendered in Rancher 2.0 UI as well) - requirements.yaml # Optional YAML file listing dependencies for the chart - templates/ # A directory of templates that, when combined with values.yml will generate K8s YAML - values.yaml # The default configuration values for this chart -``` + # Wordpress ROCKS! + ``` -*See the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/) for a complete walk through of developing charts.* + [What's an `app-readme.md` file?]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#rancher-chart-structure) -To convert an upstream chart to take advantage of Rancher's enhanced UX, first create an `app-readme.md` file in the root of your chart. +2. Create a `questions.yml` file that prompts the user for parameters. -``` -$ cat ./app-readme.md + The example below prompts the user to enable persistent storage with a radio button. If the user enables persistent storage, they are prompted for a storage class and volume size. -# Wordpress ROCKS! -``` + The example also provides a list of categories for the chart. This metadata helps users find the chart when browsing the catalog UI. -Then add a `questions.yml` file to prompt the user for something. + 
+        categories:
+        - Blog
+        - CMS
+        questions:
+        - variable: persistence.enabled
+        default: "false"
+        description: "Enable persistent volume for WordPress"
+        type: boolean
+        required: true
+        label: WordPress Persistent Volume Enabled
+        show_subquestion_if: true
+        group: "WordPress Settings"
+        subquestions:
+        - variable: persistence.size
+            default: "10Gi"
+            description: "WordPress Persistent Volume Size"
+            type: string
+            label: WordPress Volume Size
+        - variable: persistence.storageClass
+            default: ""
+            description: "If undefined or null, uses the default StorageClass. Default to null"
+            type: storageclass
+            label: Default StorageClass for WordPress
+
-``` -categories: -- Blog -- CMS -questions: -- variable: persistence.enabled - default: "false" - description: "Enable persistent volume for WordPress" - type: boolean - required: true - label: WordPress Persistent Volume Enabled - show_subquestion_if: true - group: "WordPress Settings" - subquestions: - - variable: persistence.size - default: "10Gi" - description: "WordPress Persistent Volume Size" - type: string - label: WordPress Volume Size - - variable: persistence.storageClass - default: "" - description: "If undefined or null, uses the default StorageClass. Default to null" - type: storageclass - label: Default StorageClass for WordPress -``` + [What's a `questions.yml` file?]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#rancher-chart-structure) -The above will prompt the user with a true / false radio button in the UI for enabling persistent storage. If the user choses to enable persistent storage they will be prompted for a storage class and volume size. + [What variables can I use in question.yml?]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#question-variable-reference) -The above file also provides a list of categories that this chart fits into. This helps users navigate and filtering when browsing the catalog UI. +## Adding Custom Catalogs -#### Question Variable Reference +>**Note:** +> +>- 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. -| Variable | Type | Required | Description | -| ------------- | ------------- | --- |------------- | -| variable | string | true | define the variable name specified in the `values.yaml`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"`| +You can create custom catalogs of Helm charts for use in Rancher. Custom catalogs are helpful for fast deployment of applications unique to your environment. -**subquestions**: `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. +>**Prerequisites:** +> +>- Create a custom catalog in GitHub. For more information, see [Catalogs]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs). +>- Convert the native Helm charts in your custom catalog for use in Rancher. For more information, see [Converting Native Helm Charts for Rancher](#converting-native-helm-charts-for-rancher). -## Adding Catalog of Helm Charts to Rancher +1. From the **Global** view, choose **Catalogs** from the main menu. +2. Click **Add Catalog**. +3. Complete the form and click **Create**. -Currently, catalogs can only be ad added to Rancher at a global level, which means any catalog added will be shared with all clusters and projects. - -At the global level in Rancher UI - -* Select `Catalogs` from the top level nav. -* Click `Add Catalog` button in upper left hand corner of UI. -* Give the catalog a name. This will be visible across all projects. -* Provide the Git URL of the catalog repository. -* Provide the Git branch you would like to use. -* Click `Create` - -In a few moments, the new catalog will refresh and be availble to launch applications from in projects. - -> **Note:** Currently, only unauthenticated catalogs are supported in Rancher. +**Result**: Your catalog is added to Rancher. The catalog is available for deployment of your applications.