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

Update catalog docs

Browse Source
This commit is contained in:
Catherine Luse
2020-04-01 21:06:29 -07:00
parent 37ecb8638f
commit 19f5499de7
10 changed files with 421 additions and 413 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/catalog/_index.md
+21 -95
View File
@@ -20,16 +20,11 @@ This section covers the following topics:
- [Prerequisites](#prerequisites)
- [Catalog scopes](#catalog-scopes)
- [Catalog Helm Deployment Versions](#catalog-helm-deployment-versions)
- [Enabling built-in global catalogs](#enabling-built-in-global-catalogs)
- [Adding custom global catalogs](#adding-custom-global-catalogs)
- [Add custom Git repositories](#add-custom-git-repositories)
- [Add custom Helm chart repositories](#add-custom-helm-chart-repositories)
- [Add private Git/Helm chart repositories](#add-private-git-helm-chart-repositories)
- [Launching catalog applications](#launching-catalog-applications)
- [Working with catalogs](#working-with-catalogs)
- [Apps](#apps)
- [Global DNS](#global-dns)
- [Chart compatibility with Rancher](#chart-compatibility-with-rancher)
- [Built-in global catalogs](#built-in-global-catalogs)
- [Custom catalogs](#custom-catalogs)
- [Creating and launching applications](#creating-and-launching-applications)
- [Chart compatibility with Rancher](#chart-compatibility-with-rancher)
- [Global DNS](#global-dns)
# Prerequisites
@@ -64,103 +59,34 @@ By default, catalogs are assumed to be deployed using Helm 2. If you run an app
Charts that are specific to Helm 2 should only be added to a Helm 2 catalog, and Helm 3 specific charts should only be added to a Helm 3 catalog.
# Enabling Built-in Global Catalogs
# Built-in Global Catalogs
Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator.
Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator. For details, refer to the section on managing [built-in global catalogs.]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in)
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
# Custom Catalogs
2. Toggle the default catalogs that you want use to a setting of **Enabled**.
There are two types of catalogs in Rancher: [Built-in global catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/) and [custom catalogs.]({{<baseurl>}}/rancher/v2.x/en/catalog/adding-catalogs/)
- **Library:** The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. This catalog features Rancher Charts, which include some [notable advantages]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts.
- **Helm Stable:** This catalog, which is maintained by the Kubernetes community, includes native [Helm charts](https://helm.sh/docs/chart_template_guide/). This catalog features the largest pool of apps.
- **Helm Incubator:** Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**.
Any user can create custom catalogs to add into Rancher. Custom catalogs can be added into Rancher at the global level, cluster level, or project level. For details, refer to the [section on adding custom catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/adding-catalogs) and the [catalog configuration reference.]({{<baseurl>}}/rancher/v2.x/en/catalog/catalog-config)
**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 **Apps** from the main navigation bar. In versions prior to v2.2.0, you can select **Catalog Apps** from the main navigation bar.
# Creating and Launching Applications
# Adding Custom Global Catalogs
Adding a catalog is as simple as adding a catalog name, a URL and a branch name.
**Prerequisite:** An [admin]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) of Rancher has the ability to add or remove catalogs globally in Rancher.
### 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 a catalog name and the URL address of the chart repository.
### Add Private Git/Helm Chart Repositories
_Available as of v2.2.0_
Private catalog repositories can be added using credentials like Username and Password. You may also want to use the OAuth token if your Git or Helm repository server supports that.
[Read More About Adding Private Git/Helm Catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#private-repositories)
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
2. Click **Add Catalog**.
3. Complete the form and click **Create**.
**Result:** Your catalog is added to Rancher.
# Launching Catalog Applications
After you've either enabled the built-in catalogs or added your own custom catalog, you can start launching any catalog application.>
1. From the **Global** view, open the project that you want to deploy to.
2. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the app that you want to launch, and then click **View Now**.
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.
5. Select a **Template Version**.
6. Complete the rest of the **Configuration Options**.
* 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**.
* When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of --set]https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm.
For example, when entering an answer that includes two values separated by a comma (i.e., `abc, bcd`), wrap the values with double quotes (i.e., `"abc, bcd"`).
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:
By creating a customized repository with added files, Rancher improves on Helm repositories and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience.
# Working with Catalogs
There are two types of catalogs in Rancher. Learn more about each type:
* [Built-in Global Catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/)
* [Custom Catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/)
### Apps
In Rancher, applications are deployed from the templates in a catalog. Rancher supports two types of applications:
In Rancher, applications are deployed from the templates in a catalog. This section covers the following topics:
* [Multi-cluster applications]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/)
* [Applications deployed in a specific Project]({{<baseurl>}}/rancher/v2.x/en/catalog/apps)
* [Creating catalog apps]({{<baseurl>}}/rancher/v2.x/en/catalog/creating-apps)
* [Launching catalog apps within a project]({{<baseurl>}}/rancher/v2.x/en/catalog/launching-apps)
* [Managing catalog apps]({{<baseurl>}}/rancher/v2.x/en/catalog/managing-apps)
* [Tutorial: Example custom chart creation]({{<baseurl>}}/rancher/v2.x/en/catalog/tutorial)
### Global DNS
# Chart Compatibility with Rancher
Charts now support the fields `rancher_min_version` and `rancher_max_version` in the [`questions.yml` file](https://github.com/rancher/integration-test-charts/blob/master/charts/chartmuseum/v1.6.0/questions.yml) to specify the versions of Rancher that the chart is compatible with. When using the UI, only app versions that are valid for the version of Rancher running will be shown. API validation is done to ensure apps that don't meet the Rancher requirements cannot be launched. An app that is already running will not be affected on a Rancher upgrade if the newer Rancher version does not meet the app's requirements.
# Global DNS
_Available as v2.2.0_
When creating applications that span multiple Kubernetes clusters, a Global DNS entry can be created to route traffic to the endpoints in all of the different clusters. An external DNS server will need be programmed to assign a fully qualified domain name (a.k.a FQDN) to your application. Rancher will use the FQDN you provide and the IP addresses where your application is running to program the DNS. Rancher will gather endpoints from all the Kubernetes clusters running your application and program the DNS.
For more information on how to use this feature, see [Global DNS]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/).
### Chart Compatibility with Rancher
Charts now support the fields `rancher_min_version` and `rancher_max_version` in the [`questions.yml` file](https://github.com/rancher/integration-test-charts/blob/master/charts/chartmuseum/v1.6.0/questions.yml) to specify the versions of Rancher that the chart is compatible with. When using the UI, only app versions that are valid for the version of Rancher running will be shown. API validation is done to ensure apps that don't meet the Rancher requirements cannot be launched. An app that is already running will not be affected on a Rancher upgrade if the newer Rancher version does not meet the app's requirements.
content/rancher/v2.x/en/catalog/custom/adding/_index.md → content/rancher/v2.x/en/catalog/adding-catalogs/_index.md
+51 -7
View File
@@ -1,13 +1,53 @@
---
title: Adding Custom Catalogs
weight: 4005
title: Creating Custom Catalogs
weight: 200
aliases:
- /rancher/v2.x/en/tasks/global-configuration/catalog/adding-custom-catalogs/
- /rancher/v2.x/en/catalog/custom/adding
---
[Custom catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/) can be added into Rancher at any [scope of Rancher]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-scope).
Custom catalogs can be added into Rancher at a global scope, cluster scope, or project scope.
## Adding Global Catalogs
- [Adding catalog repositories](#adding-catalog-repositories)
- [Add custom Git repositories](#add-custom-git-repositories)
- [Add custom Helm chart repositories](#add-custom-helm-chart-repositories)
- [Add private Git/Helm chart repositories](#add-private-git-helm-chart-repositories)
- [Adding global catalogs](#adding-global-catalogs)
- [Adding cluster level catalogs](#adding-cluster-level-catalogs)
- [Adding project level catalogs](#adding-project-level-catalogs)
- [Custom catalog configuration reference](#custom-catalog-configuration-reference)
# Adding Catalog Repositories
Adding a catalog is as simple as adding a catalog name, a URL and a branch name.
**Prerequisite:** An [admin]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) of Rancher has the ability to add or remove catalogs globally in Rancher.
### 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 a catalog name and the URL address of the chart repository.
### Add Private Git/Helm Chart Repositories
_Available as of v2.2.0_
Private catalog repositories can be added using credentials like Username and Password. You may also want to use the OAuth token if your Git or Helm repository server supports that.
For more information on private Git/Helm catalogs, refer to the [custom catalog configuration reference.]({{<baseurl>}}/rancher/v2.x/en/catalog/catalog-config)
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
2. Click **Add Catalog**.
3. Complete the form and click **Create**.
**Result:** Your catalog is added to Rancher.
# Adding Global Catalogs
>**Prerequisites:** In order to manage the [built-in catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/) or manage global catalogs, you need _one_ of the following permissions:
>
@@ -20,9 +60,9 @@ aliases:
{{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions)
4. Click **Create**.
**Result**: Your custom global catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [multi-cluster apps]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or [applications in any project]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/) from this catalog.
**Result**: Your custom global catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [multi-cluster apps]({{<baseurl>}}/rancher/v2.x/en/catalog/multi-cluster-apps/) or [applications in any project]({{<baseurl>}}/rancher/v2.x/en/catalog/launching-apps/) from this catalog.
## Adding Cluster Catalogs
# Adding Cluster Level Catalogs
_Available as of v2.2.0_
@@ -41,7 +81,7 @@ _Available as of v2.2.0_
**Result**: Your custom cluster catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [applications in any project in that cluster]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/) from this catalog.
## Adding Project Level Catalogs
# Adding Project Level Catalogs
_Available as of v2.2.0_
@@ -60,3 +100,7 @@ _Available as of v2.2.0_
5. Click **Create**.
**Result**: Your custom project catalog is added to Rancher. Once it is in `Active` state, it has completed synchronization and you will be able to start deploying [applications in that project]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/) from this catalog.
# Custom Catalog Configuration Reference
Refer to [this page]({{<baseurl>}}/rancher/v2.x/en/catalog/catalog-config) more information on configuring custom catalogs.
content/rancher/v2.x/en/catalog/apps/_index.md
-170
View File
@@ -1,170 +0,0 @@
---
title: Apps in a Project
weight: 5005
---
Within a project, when you want to deploy applications from catalogs, the applications available in your project will be based on the [scope of the catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-scope).
If your application is using ingresses, you can program the ingress hostname to an external DNS by setting up a [Global DNS entry]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/).
## Prerequisites
To create a multi-cluster app in Rancher, you must have at least one of the following permissions:
- A [project-member role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) in the target cluster, which gives you the ability to create, read, update, and delete the workloads
- A [cluster owner role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) for the cluster that include the target project
## Launching Catalog Applications
After you've either enabled the [built-in global catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in/) or [added your own custom catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding), you can start launching catalog applications.
1. From the **Global** view, navigate to your project that you want to start deploying applications.
2. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the application that you want to launch, and then click **View Details**.
4. (Optional) Review the detailed descriptions, which comes from the Helm chart's `README`.
5. 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 change the name of the namespace.
* 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**.
7. Complete the rest of the **Configuration Options**. Rancher handles how to [customize your configuration options](#configuration-options) depending on whether or not the custom catalog includes the `questions.yml` file.
8. Review the files in the **Preview** section. 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:
- **Workloads** view
- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
### Configuration Options
For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm.
> For example, when entering an answer that includes two values separated by a comma (i.e. `abc, bcd`), it is required to wrap the values with double quotes (i.e., ``"abc, bcd"``).
{{% tabs %}}
{{% tab "UI" %}}
#### Using a `questions.yml` file
If the Helm chart that you are deploying contains a `questions.yml` file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions.
#### Key Value Pairs for Native Helm Charts
For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.
{{% /tab %}}
{{% tab "Editing YAML Files" %}}
_Available as of v2.1.0_
If you do not want to input answers using the UI, you can choose the **Edit as YAML** option.
With this example YAML:
```YAML
outer:
inner: value
servers:
- port: 80
host: example
```
#### Kev Value Pairs
You can have a YAML file that translates these fields to match how to [format custom values so that it can be used with `--set`](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set).
These values would be translated to:
```
outer.inner=value
servers[0].port=80
servers[0].host=example
```
#### YAML files
_Available as of v2.2.0_
You can directly paste that YAML formatted structure into the YAML editor. By allowing custom values to be set using a YAML formatted structure, Rancher has the ability to easily customize for more complicated input values (e.g. multi-lines, array and JSON objects).
{{% /tab %}}
{{% /tabs %}}
## Application Management
After deploying an application, one of the benefits of using an application versus individual workloads/resources is the ease of being able to manage many workloads/resources applications. Apps can be cloned, upgraded or rolled back.
### Cloning Catalog Applications
After an application is deployed, you can easily clone it to use create another application with almost the same configuration. It saves you the work of manually filling in duplicate information.
### Upgrading Catalog Applications
After an application is deployed, you can easily upgrade to a different template version.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to upgrade.
1. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the application that you want to upgrade, and then click the Ellipsis to find **Upgrade**.
4. Select the **Template Version** that you want to deploy.
5. (Optional) Update your **Configuration Options**.
6. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for **Delete and recreate resources if needed during the upgrade**.
> In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the upgrade.
7. Review the files in the **Preview** section. When you're satisfied, click **Launch**.
**Result**: Your application is updated. You can view the application status from the project's:
- **Workloads** view
- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
### Rolling Back Catalog Applications
After an application has been upgraded, you can easily rollback to a different template version.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to upgrade.
1. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the application that you want to rollback, and then click the Ellipsis to find **Rollback**.
4. Select the **Revision** that you want to roll back to. By default, Rancher saves up to the last 10 revisions.
5. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for **Delete and recreate resources if needed during the upgrade**.
> In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the rollback.
7. Click **Rollback**.
**Result**: Your application is updated. You can view the application status from the project's:
- **Workloads** view
- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
### Deleting Catalog Application Deployments
As a safeguard to prevent you from unintentionally deleting other catalog applications that share a namespace, deleting catalog applications themselves does not delete the namespace they're assigned to.
Therefore, if you want to delete both an app and the namespace that contains the app, you should remove the app and the namespace separately:
1. Uninstall the app using the app's `uninstall` function.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to delete.
1. From the main menu, choose **Namespaces**.
1. Find the namespace running your catalog app. Select it and click **Delete**.
**Result:** The catalog application deployment and its namespace are deleted.
content/rancher/v2.x/en/catalog/built-in/_index.md
+10 -20
View File
@@ -1,35 +1,25 @@
---
title: Built-in Global Catalogs
weight: 4000
title: Enabling and Disabling Built-in Global Catalogs
weight: 100
aliases:
- /rancher/v2.x/en/tasks/global-configuration/catalog/enabling-default-catalogs/
---
There are default [global catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/#global-catalogs) packaged as part of Rancher.
There are default global catalogs packaged as part of Rancher.
## Managing Built-in Global Catalogs
Within Rancher, there are default catalogs packaged as part of Rancher. These can be enabled or disabled by an administrator.
>**Prerequisites:** In order to manage the built-in catalogs or [manage global catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/#adding-global-catalogs), you need _one_ of the following permissions:
>**Prerequisites:** In order to manage the built-in catalogs or manage global catalogs, you need _one_ of the following permissions:
>
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/)
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#global-permissions-reference) role assigned.
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/#custom-global-permissions-reference) role assigned.
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions prior to v2.2.0, you can select **Catalogs** directly in the navigation bar.
2. Toggle the default catalogs that you want use to a setting of **Enabled**.
2. Toggle the default catalogs that you want to be enabled or disabled:
- **Library**
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.x, 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]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#chart-types) over native Helm charts.
- **Helm Stable**
This catalog, , which is maintained by the Kubernetes community, includes native [Helm charts](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/getting_started.md). This catalog features the largest pool of apps.
- **Helm Incubator**
Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**.
- **Library:** The Library Catalog includes charts curated by Rancher. Rancher stores charts in a Git repository to expedite the fetch and update of charts. This catalog features Rancher Charts, which include some [notable advantages]({{<baseurl>}}/rancher/v2.x/en/catalog/creating-apps/#rancher-charts) over native Helm charts.
- **Helm Stable:** This catalog, which is maintained by the Kubernetes community, includes native [Helm charts](https://helm.sh/docs/chart_template_guide/). This catalog features the largest pool of apps.
- **Helm Incubator:** Similar in user experience to Helm Stable, but this catalog is filled with applications in **beta**.
**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 **Apps** from the main navigation bar. In versions prior to v2.2.0, within a project, you can select **Catalog Apps** from the main navigation bar.
content/rancher/v2.x/en/catalog/custom/_index.md → content/rancher/v2.x/en/catalog/catalog-config/_index.md
+20 -11
View File
@@ -1,24 +1,32 @@
---
title: Custom Catalogs
weight: 4020
title: Custom Catalog Configuration Reference
weight: 300
aliases:
- /rancher/v2.x/en/catalog/catalog-config
---
Any user can [create custom catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/creating/) to add into Rancher. Besides the content of the catalog, users must ensure their catalogs are able to be added into Rancher.
Any user can create custom catalogs to add into Rancher. Besides the content of the catalog, users must ensure their catalogs are able to be added into Rancher.
## Types of Repositories
- [Types of Repositories](#types-of-repositories)
- [Custom Git Repository](#custom-git-repository)
- [Custom Helm Chart Repository](#custom-helm-chart-repository)
- [Catalog Fields](#catalog-fields)
- [Private Repositories](#private-repositories)
- [Using Username and Password](#using-username-and-password)
- [Using an OAuth token](#using-an-oauth-token)
# Types of Repositories
Rancher supports adding in different types of repositories as a catalog:
* Custom Git Repository
* Custom Helm Chart Repository
### Custom Git Repository
# Custom Git 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`. The branch name must be a branch that is in your catalog URL. If no branch name is provided, it will default to use the `master` branch. Whenever you add a catalog to Rancher, it will be available almost immediately.
### Custom Helm Chart Repository
# Custom Helm Chart Repository
A Helm chart repository is an HTTP server that contains 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.
@@ -26,7 +34,7 @@ Helm comes with a built-in package server for developer testing (`helm serve`).
In Rancher, you can add the custom Helm chart repository with only a catalog name and the URL address of the chart repository.
## Catalog Fields
# Catalog Fields
When [adding your catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/) to Rancher, you'll provide the following information:
@@ -36,11 +44,12 @@ When [adding your catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/adding/)
| Name | Name for your custom catalog to distinguish the repositories in Rancher |
| Catalog URL | URL of your custom chart repository|
| Use Private Catalog | Selected if you are using a private repository that requires authentication |
| Username (Optional) | [Username](#using-username-and-password) or [OAuth Token](#using-an-oauth-token) |
| Password (Optional) | If you are authenticating using [username](#using-username-and-password), the associated password. If you are using an [OAuth Token](#using-an-oauth-token), use `x-oauth-basic`. |
| Username (Optional) | Username or OAuth Token |
| Password (Optional) | If you are authenticating using a username, enter the associated password. If you are using an OAuth token, use `x-oauth-basic`. |
| Branch | For a Git repository, the branch name. Default: `master`. For a Helm Chart repository, this field is ignored. |
| Helm version | The Helm version that will be used to deploy all of the charts in the catalog. This field cannot be changed later. For more information, refer to the [section on Helm versions.]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-helm-deployment-versions) |
## Private Repositories
# Private Repositories
_Available as of v2.2.0_
content/rancher/v2.x/en/catalog/custom/creating/_index.md → content/rancher/v2.x/en/catalog/creating-apps/_index.md
+31 -91
View File
@@ -1,41 +1,46 @@
---
title: Creating Custom Catalogs Apps
weight: 4000
title: Creating Catalog Apps
weight: 400
aliases:
- /rancher/v2.x/en/tasks/global-configuration/catalog/customizing-charts/
- /rancher/v2.x/en/catalog/custom/creating
---
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.
## Chart Types
> For a complete walkthrough of developing charts, see the [Chart Template Developer's Guide](https://helm.sh/docs/chart_template_guide/) in the official Helm documentation.
Rancher supports two different types of charts:
- [Chart types](#chart-types)
- [Helm charts](#helm-charts)
- [Rancher charts](#rancher-charts)
- [Chart directory structure](#chart-directory-structure)
- [Additional Files for Rancher Charts](#additional-files-for-rancher-charts)
- [questions.yml](#questions-yml)
- [Min/Max Rancher versions](#min-max-rancher-versions)
- [Question variable reference](#question-variable-reference)
- [Tutorial: Example Custom Chart Creation](#tutorial-example-custom-chart-creation)
- **Helm Charts**
# Chart Types
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.
Rancher supports two different types of charts: Helm charts and Rancher charts.
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).
### Helm Charts
- **Rancher Charts**
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.
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).
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).
Advantages of Rancher charts include:
### Rancher Charts
- **Enhanced Revision Tracking**
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 [Additional Files for Rancher Charts.](#additional-files-for-rancher-charts)
While Helm supports versioned deployments, Rancher adds tracking and revision history to display changes between different versions of the chart.
Advantages of Rancher charts include:
- **Streamlined Application Launch**
- **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.
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
# 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.
@@ -51,7 +56,7 @@ charts/<APPLICATION>/<APP_VERSION>/
|--values.yml # Default configuration values for the chart.
```
## Rancher Chart Additional Files
# Additional Files for Rancher Charts
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 Helm charts in their directory structures. Rancher charts include two files that Helm charts do not.
@@ -73,11 +78,11 @@ Before you create your own custom catalog, you should have a basic understanding
![questions.yml]({{<baseurl>}}/img/rancher/questions.png)
### Questions.yml
### questions.yml
Inside the `questions.yml`, most of the content will be around the questions to ask the end user, but there are some additional fields that can be set in this file.
#### Min/Max Rancher versions
### Min/Max Rancher versions
_Available as of v2.3.0_
@@ -90,7 +95,7 @@ rancher_min_version: 2.3.0
rancher_max_version: 2.3.99
```
#### Question Variable Reference
### Question Variable Reference
This reference contains variables that you can use in `questions.yml` nested under `questions:`.
@@ -116,71 +121,6 @@ This reference contains variables that you can use in `questions.yml` nested und
>**Note:** `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported.
# Tutorial: Example Custom Chart Creation
## Example Custom Chart Creation
You can fill your custom catalogs with either Helm Charts or Rancher Charts, although we recommend Rancher Charts due to their enhanced user experience.
>**Note:** For a complete walkthrough of developing charts, see the upstream Helm chart [developer reference](https://helm.sh/docs/chart_template_guide/).
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](#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 **must** 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.
For a tutorial on adding a custom Helm chart to a custom catalog, refer to [this page.]({{<baseurl>}}/rancher/v2.x/en/catalog/tutorial)
content/rancher/v2.x/en/catalog/launching-apps/_index.md
+102
View File
@@ -0,0 +1,102 @@
---
title: Launching Catalog Apps
weight: 700
aliases:
- /rancher/v2.x/en/catalog/launching-apps
---
Within a project, when you want to deploy applications from catalogs, the applications available in your project will be based on the [scope of the catalogs]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-scope).
If your application is using ingresses, you can program the ingress hostname to an external DNS by setting up a [Global DNS entry]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/).
- [Prerequisites](#prerequisites)
- [Launching a catalog app](#launching-a-catalog-app)
- [Configuration options](#configuration-options)
# Prerequisites
To launch an app from a catalog in Rancher, you must have at least one of the following permissions:
- A [project-member role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) in the target cluster, which gives you the ability to create, read, update, and delete the workloads
- A [cluster owner role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) for the cluster that include the target project
Before launching an app, you'll need to either [enable a built-in global catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/built-in) or [add your own custom catalog.]({{<baseurl>}}/rancher/v2.x/en/catalog/adding-catalogs)
# Launching a Catalog App
1. From the **Global** view, open the project that you want to deploy an app to.
2. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the app that you want to launch, and then click **View Now**.
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.
5. Select a **Template Version**.
6. Complete the rest of the **Configuration Options**.
* 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**.
* When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of --set](https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm. For example, when entering an answer that includes two values separated by a comma (i.e., `abc, bcd`), wrap the values with double quotes (i.e., `"abc, bcd"`).
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 **Workloads** view or **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
# Configuration Options
For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm.
> For example, when entering an answer that includes two values separated by a comma (i.e. `abc, bcd`), it is required to wrap the values with double quotes (i.e., ``"abc, bcd"``).
{{% tabs %}}
{{% tab "UI" %}}
### Using a questions.yml file
If the Helm chart that you are deploying contains a `questions.yml` file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions.
### Key Value Pairs for Native Helm Charts
For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.
{{% /tab %}}
{{% tab "Editing YAML Files" %}}
_Available as of v2.1.0_
If you do not want to input answers using the UI, you can choose the **Edit as YAML** option.
With this example YAML:
```YAML
outer:
inner: value
servers:
- port: 80
host: example
```
### Key Value Pairs
You can have a YAML file that translates these fields to match how to [format custom values so that it can be used with `--set`](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set).
These values would be translated to:
```
outer.inner=value
servers[0].port=80
servers[0].host=example
```
### YAML files
_Available as of v2.2.0_
You can directly paste that YAML formatted structure into the YAML editor. By allowing custom values to be set using a YAML formatted structure, Rancher has the ability to easily customize for more complicated input values (e.g. multi-lines, array and JSON objects).
{{% /tab %}}
{{% /tabs %}}
content/rancher/v2.x/en/catalog/managing-apps/_index.md
+80
View File
@@ -0,0 +1,80 @@
---
title: Managing Catalog Apps
weight: 500
---
After deploying an application, one of the benefits of using an application versus individual workloads/resources is the ease of being able to manage many workloads/resources applications. Apps can be cloned, upgraded or rolled back.
- [Cloning catalog applications](#cloning-catalog-applications)
- [Upgrading catalog applications](#upgrading-catalog-applications)
- [Rolling back catalog applications](#rolling-back-catalog-applications)
- [Deleting catalog application deployments](#deleting-catalog-application-deployments)
### Cloning Catalog Applications
After an application is deployed, you can easily clone it to use create another application with almost the same configuration. It saves you the work of manually filling in duplicate information.
### Upgrading Catalog Applications
After an application is deployed, you can easily upgrade to a different template version.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to upgrade.
1. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the application that you want to upgrade, and then click the Ellipsis to find **Upgrade**.
4. Select the **Template Version** that you want to deploy.
5. (Optional) Update your **Configuration Options**.
6. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for **Delete and recreate resources if needed during the upgrade**.
> In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the upgrade.
7. Review the files in the **Preview** section. When you're satisfied, click **Launch**.
**Result**: Your application is updated. You can view the application status from the project's:
- **Workloads** view
- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
### Rolling Back Catalog Applications
After an application has been upgraded, you can easily rollback to a different template version.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to upgrade.
1. From the main navigation bar, choose **Apps**. In versions prior to v2.2.0, choose **Catalog Apps** on the main navigation bar. Click **Launch**.
3. Find the application that you want to rollback, and then click the Ellipsis to find **Rollback**.
4. Select the **Revision** that you want to roll back to. By default, Rancher saves up to the last 10 revisions.
5. (Optional) Select whether or not you want to force the catalog application to be upgraded by checking the box for **Delete and recreate resources if needed during the upgrade**.
> In Kubernetes, some fields are designed to be immutable or cannot be updated directly. As of v2.2.0, you can now force your catalog application to be updated regardless of these fields. This will cause the catalog apps to be deleted and resources to be re-created if needed during the rollback.
7. Click **Rollback**.
**Result**: Your application is updated. You can view the application status from the project's:
- **Workloads** view
- **Apps** view. In versions prior to v2.2.0, this is the **Catalog Apps** view.
### Deleting Catalog Application Deployments
As a safeguard to prevent you from unintentionally deleting other catalog applications that share a namespace, deleting catalog applications themselves does not delete the namespace they're assigned to.
Therefore, if you want to delete both an app and the namespace that contains the app, you should remove the app and the namespace separately:
1. Uninstall the app using the app's `uninstall` function.
1. From the **Global** view, navigate to the project that contains the catalog application that you want to delete.
1. From the main menu, choose **Namespaces**.
1. Find the namespace running your catalog app. Select it and click **Delete**.
**Result:** The catalog application deployment and its namespace are deleted.
content/rancher/v2.x/en/catalog/multi-cluster-apps/_index.md
+34 -19
View File
@@ -1,15 +1,30 @@
---
title: Multi-Cluster Apps
weight: 5000
weight: 600
---
_Available as of v2.2.0_
Typically, most applications are deployed on a single Kubernetes cluster, but there will be times you might want to deploy multiple copies of the same application across different clusters and/or projects. In Rancher, a _multi-cluster application_, is an application deployed using a Helm chart across multiple clusters. With the ability to deploy the same application across multiple clusters, it avoids the repetition of the same action on each cluster, which could introduce user error during application configuration. With multi-cluster applications, you can customize to have the same configuration across all projects/clusters as well as have the ability to change the configuration based on your target project. Since multi-cluster application is considered a single application, it's easy to manage and maintain this application.
Any Helm charts from a [global catalog]({{<baseurl>}}/rancher/v2.x/en/catalog/#catalog-scope) can be used to deploy and manage multi-cluster applications.
Any Helm charts from a global catalog can be used to deploy and manage multi-cluster applications.
After creating a multi-cluster application, you can program a [Global DNS entry]({{<baseurl>}}/rancher/v2.x/en/catalog/globaldns/) to make it easier to access the application.
- [Prerequisites](#prerequisites)
- [Launching a multi-cluster app](#launching-a-multi-cluster-app)
- [Multi-cluster app configuration options](#multi-cluster-app-configuration-options)
- [Targets](#targets)
- [Upgrades](#upgrades)
- [Roles](#roles)
- [Application configuration options](#application-configuration-options)
- [Using a questions.yml file](#using-a-questions-yml-file)
- [Key value pairs for native Helm charts](key-value-pairs-for-native-helm-charts)
- [Members](#members)
- [Overriding application configuration options for specific projects](#overriding-application-configuration-options-for-specific-projects)
- [Upgrading multi-cluster app roles and projects](#upgrading-multi-cluster-app-roles-and-projects)
- [Multi-cluster application management](#multi-cluster-application-managements)
- [Deleting a multi-cluster application](#deleting-a-multi-cluster-application)
# Prerequisites
To create a multi-cluster app in Rancher, you must have at least one of the following permissions:
@@ -17,7 +32,7 @@ To create a multi-cluster app in Rancher, you must have at least one of the foll
- A [project-member role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#project-roles) in the target cluster(s), which gives you the ability to create, read, update, and delete the workloads
- A [cluster owner role]({{<baseurl>}}/rancher/v2.x/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) for the clusters(s) that include the target project(s)
## Launching a Multi-Cluster App
# Launching a Multi-Cluster App
1. From the **Global** view, choose **Apps** in the navigation bar. Click **Launch**.
@@ -29,7 +44,7 @@ To create a multi-cluster app in Rancher, you must have at least one of the foll
5. Select a **Template Version**.
6. Complete the [multi-cluster applications specific configuration options](#configuration-options-to-make-a-multi-cluster-app) as well as the [application configuration options](#application-configuration-options).
6. Complete the [multi-cluster applications specific configuration options](#multi-cluster-app-configuration-options) as well as the [application configuration options](#application-configuration-options).
7. Select the **Members** who can [interact with the multi-cluster application](#members).
@@ -39,15 +54,15 @@ To create a multi-cluster app in Rancher, you must have at least one of the foll
**Result**: Your application is deployed to your chosen namespace. You can view the application status from the project's:
### Configuration Options to Make a Multi-Cluster App
# Multi-cluster App Configuration Options
Rancher has divided the configuration option for the multi-cluster application into several sections.
#### Targets
### Targets
In the **Targets** section, select the [projects]({{<baseurl>}}/rancher/v2.x/en/k8s-in-rancher/projects-and-namespaces/#projects) that you want the application to be deployed in. The list of projects is based on what projects you have access to. For each project that you select, it will be added to the list, which shows the cluster name and project name that were selected. To remove a target project, click on **-**.
In the **Targets** section, select the projects that you want the application to be deployed in. The list of projects is based on what projects you have access to. For each project that you select, it will be added to the list, which shows the cluster name and project name that were selected. To remove a target project, click on **-**.
#### Upgrades
### Upgrades
In the **Upgrades** section, select the upgrade strategy to use, when you decide to upgrade your application.
@@ -55,9 +70,9 @@ In the **Upgrades** section, select the upgrade strategy to use, when you decide
* **Upgrade all apps simultaneously:** When selecting this upgrade strategy, all applications across all projects will be upgraded at the same time.
#### Roles
### Roles
In the **Roles** section, you define the role of the multi-cluster application. Typically, when a user [launches catalog applications]({{<baseurl>}}/rancher/v2.x/en/catalog/apps/#launching-catalog-applications), that specific user's permissions are used for creation of all workloads/resources that is required by the app.
In the **Roles** section, you define the role of the multi-cluster application. Typically, when a user [launches catalog applications]({{<baseurl>}}/rancher/v2.x/en/catalog/launching-apps), that specific user's permissions are used for creation of all workloads/resources that is required by the app.
For multi-cluster applications, the application is deployed by a _system user_ and is assigned as the creator of all underlying resources. A _system user_ is used instead of the actual user due to the fact that the actual user could be removed from one of the target projects. If the actual user was removed from one of the projects, then that user would no longer be able to manage the application for the other projects.
@@ -71,17 +86,17 @@ When launching the application, Rancher will confirm if you have these permissio
> **Note:** There are some applications like _Grafana_ or _Datadog_ that require access to specific cluster-scoped resources. These applications will require the _Cluster_ role. If you find out later that the application requires cluster roles, the multi-cluster application can be upgraded to update the roles.
### Application Configuration Options
# Application Configuration Options
For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://github.com/helm/helm/blob/master/docs/using_helm.md#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm.
For each Helm chart, there are a list of desired answers that must be entered in order to successfully deploy the chart. When entering answers, you must format them using the syntax rules found in [Using Helm: The format and limitations of –set](https://helm.sh/docs/intro/using_helm/#the-format-and-limitations-of---set), as Rancher passes them as `--set` flags to Helm.
> For example, when entering an answer that includes two values separated by a comma (i.e. `abc, bcd`), it is required to wrap the values with double quotes (i.e., ``"abc, bcd"``).
#### Using a `questions.yml` file
### Using a questions.yml file
If the Helm chart that you are deploying contains a `questions.yml` file, Rancher's UI will translate this file to display an easy to use UI to collect the answers for the questions.
#### Key Value Pairs for Native Helm Charts
### Key Value Pairs for Native Helm Charts
For native Helm charts (i.e., charts from the **Helm Stable** or **Helm Incubator** catalogs or a [custom Helm chart repository]({{<baseurl>}}/rancher/v2.x/en/catalog/custom/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.
@@ -93,7 +108,7 @@ By default, multi-cluster applications can only be managed by the user who creat
2. Select the **Access Type** for that member. There are three access types for a multi-cluster project, but due to how the permissions of a multi-cluster application are launched, please read carefully to understand what these access types mean.
- **Owner**: This access type can manage any configuration part of the multi-cluster application including the template version, the [multi-cluster applications specific configuration options](#configuration-options-to-make-a-multi-cluster-app), the [application specific configuration options](#application-configuration-options), the [members who can interact with the multi-cluster application](#members) and the [custom application configuration answers](#overriding-application-configuration-options-for-specific-projects). Since a multi-cluster application is created with a different set of permissions from the user, any _owner_ of the multi-cluster application can manage/remove applications in [target projects](#targets) without explicitly having access to these project(s). Only trusted users should be provided with this access type.
- **Owner**: This access type can manage any configuration part of the multi-cluster application including the template version, the [multi-cluster applications specific configuration options](#Multi-cluster App Configuration Options), the [application specific configuration options](#application-configuration-options), the members who can interact with the multi-cluster application and the [custom application configuration answers](#overriding-application-configuration-options-for-specific-projects). Since a multi-cluster application is created with a different set of permissions from the user, any _owner_ of the multi-cluster application can manage/remove applications in [target projects](#targets) without explicitly having access to these project(s). Only trusted users should be provided with this access type.
- **Member**: This access type can only modify the template version, the [application specific configuration options](#application-configuration-options) and the [custom application configuration answers](#overriding-application-configuration-options-for-specific-projects). Since a multi-cluster application is created with a different set of permissions from the user, any _member_ of the multi-cluster application can modify the application without explicitly having access to these project(s). Only trusted users should be provided with this access type.
@@ -115,7 +130,7 @@ The ability to use the same configuration to deploy the same application across
- **Answer**: Enter the answer that you want to be used instead.
## Upgrading Multi-Cluster App Roles and Projects
# Upgrading Multi-Cluster App Roles and Projects
- **Changing Roles on an existing Multi-Cluster app**
The creator and any users added with the access-type "owner" to a multi-cluster app, can upgrade its Roles. When adding a new Role, we check if the user has that exact role in all current target projects. These checks allow the same relaxations for global admins, cluster owners and project-owners as described in the installation section for the field `Roles`.
@@ -125,7 +140,7 @@ The creator and any users added with the access-type "owner" to a multi-cluster
2. We do not do these membership checks when removing target projects. This is because the caller's permissions could have with respect to the target project, or the project could have been deleted and hence the caller wants to remove it from targets list.
## Multi-Cluster Application Management
# Multi-Cluster Application Management
One of the benefits of using a multi-cluster application as opposed to multiple individual applications of the same type, is the ease of management. Multi-cluster applications can be cloned, upgraded or rolled back.
@@ -134,10 +149,10 @@ One of the benefits of using a multi-cluster application as opposed to multiple
2. Choose the multi-cluster application you want to take one of these actions on and click the **Vertical Ellipsis (...)**. Select one of the following options:
* **Clone**: Creates another multi-cluster application with the same configuration. By using this option, you can easily duplicate a multi-cluster application.
* **Upgrade**: Upgrade your multi-cluster application to change some part of the configuration. When performing an upgrade for multi-cluster application, the [upgrade strategy](#upgrade-strategy) can be modified if you have the correct [access type](#members).
* **Upgrade**: Upgrade your multi-cluster application to change some part of the configuration. When performing an upgrade for multi-cluster application, the [upgrade strategy](#upgrades) can be modified if you have the correct [access type](#members).
* **Rollback**: Rollback your application to a specific version. If after an upgrade, there are issues for your multi-cluster application for one or more of your [targets](#targets), Rancher has stored up to 10 versions of the multi-cluster application. Rolling back a multi-cluster application reverts the application for **all** target clusters and projects, not just the targets(s) affected by the upgrade issue.
## Deleting a Multi-Cluster Application
# Deleting a Multi-Cluster Application
1. From the **Global** view, choose **Apps** in the navigation bar.
content/rancher/v2.x/en/catalog/tutorial/_index.md
+72
View File
@@ -0,0 +1,72 @@
---
title: "Tutorial: Example Custom Chart Creation"
weight: 800
---
In this tutorial, you'll learn how to create a Helm chart and deploy it to a repository. The repository can then be used as a source for a custom catalog in Rancher.
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 a complete walkthrough of developing charts, see the upstream Helm chart [developer reference](https://helm.sh/docs/chart_template_guide/).
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](#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 **must** 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]({{<baseurl>}}/rancher/v2.x/en/catalog/creating-apps/#question-variable-reference).
```yaml
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
```
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.