public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-24 20:18:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

cleaned up custom catalog content.

Browse Source
This commit is contained in:
Mark Bishop
2018-06-14 16:55:00 -07:00
committed by Mark Bishop
parent 14ed032cf0
commit 46e8732d37
2 changed files with 162 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/concepts/catalogs/_index.md
+103 -1
View File
@@ -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%/`
<table>
<tbody>
<tr>
<td>Sub-Directory </td>
<td>File</td>
<td>Description</td>
</tr>
<tr>
<td> </td>
<td> <code>add-readme</code></td>
<td> Rancher Specific: Text displayed within Rancher.</td>
</tr>
<tr>
<td><code>charts/</code></td>
<td></td>
<td>Directory containing dependency charts.</td>
</tr>
<tr>
<td> </td>
<td><code>Chart.yml</code></td>
<td>Required Helm chart information file.</td>
</tr>
<tr>
<td> </td>
<td><code>questions.yml</code></td>
<td>Rancher Specific: File containing questions displayed within Rancher.</td>
</tr>
<tr>
<td> </td>
<td><code>README.md</code></td>
<td>Optional: Helm Readme file displayed within Rancher.</td>
</tr>
<td></td>
<td><code>requirements.yml</code></td>
<td>Optional YAML file listing dependencies for the chart.</td>
</tr>
<tr>
<td><code>templates/</code></td>
<td></td>
<td>A directory of templates that, when combined with <code>values.yml</code>, generates Kubernetes YAML.</td>
</tr>
<tr>
<td> </td>
<td><code>values.yml</code></td>
<td>The default configuration values for the chart.</td>
</tr>
</tbody>
</table>
>**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:<br> - "ClusterIP" <br> - "NodePort" <br> - "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.
content/rancher/v2.x/en/tasks/global-configuration/catalog/_index.md
+59 -88
View File
@@ -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.
<br/>
<br/>
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 version>/
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.
<pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4">
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
</pre>
```
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:<br> - "ClusterIP" <br> - "NodePort" <br> - "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.