updates per Will's feedback
Mark Bishop
Mark Bishop
@@ -35,11 +35,16 @@ Within Rancher, you can access several different catalogs either by default or t
|
||||
|
||||
### Custom Catalog Creation
|
||||
|
||||
Creating a custom catalog for Rancher is straightforward. Create a Git Repo and then direct Rancher toward the repo.
|
||||
Creating a custom catalog for Rancher is straightforward. Create a Git repo and then direct Rancher toward the repo.
|
||||
|
||||
For step-by-step directions, see [placeholder](placeholder).
|
||||
Custom catalog requirements include:
|
||||
|
||||
When you're done creating the catalog, populate it charts. See [Custom Chart Creation](#custom-chart-creation).
|
||||
- A unique name.
|
||||
- A URL that `git clone` can handle.
|
||||
|
||||
For step-by-step directions, see [Adding Custom Catalogs]({{< baseurl >}}rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs).
|
||||
|
||||
When you're done creating the catalog, populate it charts. Custom catalogs can support native Helm charts or Rancher charts. See [Custom Chart Creation](#custom-chart-creation).
|
||||
|
||||
## Chart Types
|
||||
|
||||
@@ -53,7 +58,7 @@ Rancher supports two different types of charts:
|
||||
|
||||
- **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)
|
||||
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:
|
||||
|
||||
@@ -130,7 +135,7 @@ Before you create your own custom catalog, you should have a basic understanding
|
||||
|
||||
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**
|
||||
<small>Rancher Chart with <code>app-readme.md</code> (left) vs. Helm Chart without (right)</small>
|
||||
|
||||
|
||||
|
||||
@@ -139,13 +144,15 @@ Before you create your own custom catalog, you should have a basic understanding
|
||||
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**
|
||||
<small>Rancher Chart with <code>question.yml</code> (left) vs. Helm Chart without (right)</small>
|
||||
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
You can fill your custom catalogs with either Helm Charts or Rancher Charts, although we recommend Rancher Charts due to their enhanced user experience.
|
||||
|
||||
For information on how to add and customize charts for a custom catalog, see [Customizing Charts]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/catalog/customizing-charts).
|
||||
|
||||
>**Note:** For a complete walk through of developing charts, see the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/).
|
||||
|
||||
@@ -3,107 +3,8 @@ title: Catalogs and Charts
|
||||
weight: 3026
|
||||
---
|
||||
|
||||
Within Rancher, you can use Helm Charts for quick deployment of applications from a central repository.
|
||||
This section includes step-by-step instruction on how to configure default and custom catalogs.
|
||||
|
||||
## Converting Native Helm Charts for Rancher
|
||||
|
||||
To convert a native Helm chart for use in Rancher, you must add two files for Rancher: `app-readme.md` and `questions.yml`.
|
||||
|
||||
>**Note:** Conversion of Helm charts for use in Rancher takes place outside of the Rancher UI.
|
||||
|
||||
1. Create an `app-readme.md` file.
|
||||
<br/>
|
||||
<br/>
|
||||
|
||||
**Example**:
|
||||
|
||||
```
|
||||
$ cat ./app-readme.md
|
||||
|
||||
# Wordpress ROCKS!
|
||||
```
|
||||
|
||||
[What's an `app-readme.md` file?]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#rancher-chart-structure)
|
||||
|
||||
2. Create a `questions.yml` file that prompts the user for parameters.
|
||||
|
||||
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.
|
||||
|
||||
The example also provides a list of categories for the chart. This metadata helps users find the chart when browsing the catalog UI.
|
||||
|
||||
<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>
|
||||
|
||||
[What's a `questions.yml` file?]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#rancher-chart-structure)
|
||||
|
||||
[What variables can I use in question.yml?]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#question-variable-reference)
|
||||
|
||||
## Adding Custom Catalogs
|
||||
|
||||
>**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.
|
||||
|
||||
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.
|
||||
|
||||
>**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).
|
||||
|
||||
1. From the **Global** view, choose **Catalogs** from the main menu.
|
||||
2. Click **Add 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:<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"`|
|
||||
|
||||
>**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported.
|
||||
- [Enabling Default Catalogs]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs)
|
||||
- [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs)
|
||||
- [Customizing Charts]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/catalog/customizing-charts)
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Adding Custom Catalogs
|
||||
weight: 50
|
||||
---
|
||||
|
||||
You can create custom catalogs of charts for use in Rancher. Custom catalogs are helpful for fast deployment of applications unique to your environment.
|
||||
|
||||
>**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.
|
||||
<br/>
|
||||
<br/>
|
||||
|
||||
>**Prerequisites:**
|
||||
>
|
||||
>- Recommended: Read [Catalogs and Charts]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs).
|
||||
>- Create a GitHub respository to serve as your custom catalog.
|
||||
|
||||
|
||||
1. From the **Global** view, choose **Catalogs** from the main menu.
|
||||
2. Click **Add Catalog**.
|
||||
3. Complete the form and click **Create**.
|
||||
|
||||
**Result**: Your catalog is added to Rancher.
|
||||
|
||||
## What's Next?
|
||||
|
||||
Add native Helm charts, Rancher charts, or both to your repository. For more information, see [Customizing Charts]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/catalogs).
|
||||
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: Customizing Charts
|
||||
weight: 75
|
||||
---
|
||||
|
||||
Before you can deploy customized catalog apps using Rancher, you must add charts to the GitHub repository serving as your custom catalog.
|
||||
|
||||
The custom catalog can contain native Helm charts, Rancher charts, or a combination of both (although we recommend using Rancher charts).
|
||||
|
||||
>**Prerequisites:**
|
||||
|
||||
>- Recommended: Read [Catalogs and Charts]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs).
|
||||
>- Create a GitHub repository to serve as your custom catalog.
|
||||
>- Complete [Adding Custom Catalogs]({{< baseurl >}}/Users/markbishop/Documents/GitHub/docs/content/rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs).
|
||||
|
||||
>**Note:** Customization of Helm charts takes place outside of the Rancher UI.
|
||||
|
||||
1. Within the GitHub repo that you're using as your custom catalog, create a directory structure that mirrors the structure listed in [Chart Directory Structure]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#chart-directory-structure).
|
||||
|
||||
Rancher requires this directory structure, although `app-readme.md` and `questions.yml` are optional.
|
||||
|
||||
>**Tip:**
|
||||
>
|
||||
>- To begin customizing a chart, copy one from either the [Rancher Library](https://github.com/rancher/charts) or the [Helm Stable](https://github.com/kubernetes/charts/tree/master/stable).
|
||||
>- For a complete walk through of developing charts, see the upstream Helm chart [developer reference](https://docs.helm.sh/developing_charts/).
|
||||
|
||||
2. **Recommended:** Create an `app-readme.md` file.
|
||||
|
||||
Use this file to create custom text for your chart's header in the Rancher UI. You can use this text to notify users that the chart is customized for your environment or provide special instruction on how to use it.
|
||||
<br/>
|
||||
<br/>
|
||||
**Example**:
|
||||
|
||||
```
|
||||
$ cat ./app-readme.md
|
||||
|
||||
# Wordpress ROCKS!
|
||||
```
|
||||
|
||||
3. **Recommended:** Create a `questions.yml` file.
|
||||
|
||||
This file creates a form for users to specify deployment parameters when they deploy the custom chart. Without this file, users will have to specify the parameters manually using key value pairs, which isn't user-friendly.
|
||||
<br/>
|
||||
<br/>
|
||||
The example below creates a form that prompts users for persistent volume size and a storage class.
|
||||
<br/>
|
||||
<br/>
|
||||
For a list of variables you can use when creating a `questions.yml` file, see [Question Variable Reference](#question-variable-reference).
|
||||
|
||||
<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>
|
||||
|
||||
4. Check the customized chart into your GitHub repo.
|
||||
|
||||
**Result:** Your custom chart is added to the repo. Your Rancher Server will replicate the chart within a few minutes.
|
||||
|
||||
## What's Next?
|
||||
|
||||
Launch your custom catalog app. For more information, see [Launching a Catalog App]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/launch-a-catalog-app).
|
||||
|
||||
## 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"`|
|
||||
|
||||
>**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Enabling Default Catalogs
|
||||
weight: 25
|
||||
---
|
||||
|
||||
Out-of-the-box, you can enable several different catalog repositories to simplify deployment of applications.
|
||||
|
||||
1. From the **Global** view, choose **Catalogs** from the main menu.
|
||||
2. Toggle the default catalogs that you want use to a setting of **Enabled**. The [default catalogs]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs/#catalog-types) are:
|
||||
|
||||
- **Library**
|
||||
- **Helm Stable**
|
||||
- **Helm Incubator**
|
||||
|
||||
>**Note:** If you want to use a custom catalog, see [Adding Custom Catalogs]({{< baseurl >}}/rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs) instead of this topic.
|
||||
|
||||
**Result:** The chosen catalogs are enabled. Wait a few minutes for Rancher to replicate the catalog charts. When replication completes, you'll be able to see them in any of your projects by selecting **Catalog Apps** from the main menu.
|
||||
|
||||
## What's Next?
|
||||
|
||||
Deploy catalog applications to your cluster nodes. For more information, see [Launching a Catalog App]({{< baseurl >}}/rancher/v2.x/en/tasks/projects/launch-a-catalog-app).
|
||||
@@ -3,28 +3,29 @@ title: Launching a Catalog App
|
||||
weight:
|
||||
draft: true
|
||||
---
|
||||
After you've enabled default catalogs or setup a custom catalog, you can launch apps using a catalog instead of a standard deployment.
|
||||
|
||||
>**Prerequiste:** Enable a catalog. For more information, see [Catalogs and Charts]({{< baseurl >}}/rancher/v2.x/en/concepts/catalogs)
|
||||
|
||||
1. From the **Global** view, open the project that you want to deploy to.
|
||||
|
||||
2. From the main menu, choose **Catalog Apps**. Then click **Launch**.
|
||||
|
||||
3. Click **Launch**.
|
||||
3. Find the app that you want to launch, and then click **View Now**.
|
||||
|
||||
4. Find the app that you want to launch, and then click **View Now**.
|
||||
|
||||
5. Under **Configuration Options** enter a **Name**. By default, this name is also used to create a Kubernetes namespace for the application.
|
||||
4. Under **Configuration Options** enter a **Name**. By default, this name is also used to create a Kubernetes namespace for the application.
|
||||
|
||||
* If you would like to change the **Namespace**, click **Customize** and enter a new name
|
||||
* If you want to use a different namespace that already exists, click **Customize**, and then click **Use an existing namespace**. Choose a namespace from the list.
|
||||
|
||||
6. Select a **Template Version**.
|
||||
5. Select a **Template Version**.
|
||||
|
||||
7. Optional: Add answers to the deployment. Click **Add Answers** to add key value pairs.
|
||||
6. Complete the rest of the **Configuration Options**.
|
||||
|
||||
* For native Helm charts, answers are provided as key value pairs in the **Answers** section.
|
||||
* Keys and values are available within the **Detailed Descriptions** accordion.
|
||||
* For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs), answers are provided as key value pairs in the **Answers** section.
|
||||
* Keys and values are available within **Detailed Descriptions**.
|
||||
|
||||
8. Review the files in **Preview**. When you're satisfied, click **Launch**
|
||||
7. Review the files in **Preview**. When you're satisfied, click **Launch**.
|
||||
|
||||
**Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's:
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 805 KiB After Width: | Height: | Size: 805 KiB |
|
Before Width: | Height: | Size: 309 KiB After Width: | Height: | Size: 309 KiB |
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 80 KiB After Width: | Height: | Size: 35 KiB |
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 8.7 KiB |
|
Before Width: | Height: | Size: 6.1 KiB After Width: | Height: | Size: 4.2 KiB |
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 14 KiB |
|
Before Width: | Height: | Size: 125 KiB After Width: | Height: | Size: 111 KiB |
|
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 5.7 KiB |
|
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 17 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 13 KiB |
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 14 KiB |
|
Before Width: | Height: | Size: 6.4 KiB After Width: | Height: | Size: 3.7 KiB |
|
Before Width: | Height: | Size: 7.9 KiB After Width: | Height: | Size: 3.1 KiB |
|
Before Width: | Height: | Size: 6.3 KiB After Width: | Height: | Size: 3.7 KiB |
|
Before Width: | Height: | Size: 54 KiB After Width: | Height: | Size: 34 KiB |
|
Before Width: | Height: | Size: 75 KiB After Width: | Height: | Size: 56 KiB |
|
Before Width: | Height: | Size: 8.9 KiB After Width: | Height: | Size: 5.9 KiB |
|
Before Width: | Height: | Size: 130 KiB After Width: | Height: | Size: 132 KiB |
|
Before Width: | Height: | Size: 130 KiB After Width: | Height: | Size: 79 KiB |
|
Before Width: | Height: | Size: 192 KiB After Width: | Height: | Size: 115 KiB |
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 6.9 KiB |
|
Before Width: | Height: | Size: 17 KiB After Width: | Height: | Size: 11 KiB |
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 6.7 KiB |
|
Before Width: | Height: | Size: 35 KiB After Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 7.0 KiB |