mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-29 06:29:34 +00:00
Remove unneeded intermediate folders
This commit is contained in:
Billy Tat
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Creating Custom Catalogs
|
||||
weight: 200
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/catalog/adding-custom-catalogs/
|
||||
- /rancher/v2.0-v2.4/en/catalog/custom/adding
|
||||
- /rancher/v2.0-v2.4/en/catalog/adding-catalogs
|
||||
- /rancher/v2.0-v2.4/en/catalog/custom/
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/adding-catalogs
|
||||
---
|
||||
|
||||
Custom catalogs can be added into Rancher at a global scope, cluster scope, or project scope.
|
||||
|
||||
- [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.0-v2.4/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.0-v2.4/en/catalog/catalog-config)
|
||||
|
||||
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions before 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.0-v2.4/en/catalog/built-in/) or manage global catalogs, you need _one_ of the following permissions:
|
||||
>
|
||||
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/)
|
||||
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/) role assigned.
|
||||
|
||||
1. From the **Global** view, choose **Tools > Catalogs** in the navigation bar. In versions before v2.2.0, you can select **Catalogs** directly in the navigation bar.
|
||||
2. Click **Add Catalog**.
|
||||
3. Complete the form. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
|
||||
{{<baseurl>}}/rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/#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.0-v2.4/en/catalog/multi-cluster-apps/) or [applications in any project]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/launching-apps/) from this catalog.
|
||||
|
||||
# Adding Cluster Level Catalogs
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
>**Prerequisites:** In order to manage cluster scoped catalogs, you need _one_ of the following permissions:
|
||||
>
|
||||
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/)
|
||||
>- [Cluster Owner Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/cluster-project-roles/#cluster-roles)
|
||||
>- [Custom Cluster Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Cluster Catalogs]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/cluster-project-roles/#cluster-role-reference) role assigned.
|
||||
|
||||
1. From the **Global** view, navigate to your cluster that you want to start adding custom catalogs.
|
||||
2. Choose the **Tools > Catalogs** in the navigation bar.
|
||||
2. Click **Add Catalog**.
|
||||
3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Cluster** scope, it is defaulted to `Cluster`. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
|
||||
{{<baseurl>}}/rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/#catalog-helm-deployment-versions)
|
||||
5. Click **Create**.
|
||||
|
||||
**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.0-v2.4/en/catalog/apps/) from this catalog.
|
||||
|
||||
# Adding Project Level Catalogs
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
>**Prerequisites:** In order to manage project scoped catalogs, you need _one_ of the following permissions:
|
||||
>
|
||||
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/)
|
||||
>- [Cluster Owner Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/cluster-project-roles/#cluster-roles)
|
||||
>- [Project Owner Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/cluster-project-roles/#project-roles)
|
||||
>- [Custom Project Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/cluster-project-roles/#cluster-roles) with the [Manage Project Catalogs]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/cluster-project-roles/#project-role-reference) role assigned.
|
||||
|
||||
1. From the **Global** view, navigate to your project that you want to start adding custom catalogs.
|
||||
2. Choose the **Tools > Catalogs** in the navigation bar.
|
||||
2. Click **Add Catalog**.
|
||||
3. Complete the form. By default, the form will provide the ability to select `Scope` of the catalog. When you have added a catalog from the **Project** scope, it is defaulted to `Cluster`. Select the Helm version that will be used to launch all of the apps in the catalog. For more information about the Helm version, refer to [this section.](
|
||||
{{<baseurl>}}/rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/#catalog-helm-deployment-versions)
|
||||
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.0-v2.4/en/catalog/apps/) from this catalog.
|
||||
|
||||
# Custom Catalog Configuration Reference
|
||||
|
||||
Refer to [this page]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/catalog-config) more information on configuring custom catalogs.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Enabling and Disabling Built-in Global Catalogs
|
||||
weight: 100
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/catalog/enabling-default-catalogs/
|
||||
- /rancher/v2.0-v2.4/en/catalog/built-in
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/built-in
|
||||
---
|
||||
|
||||
There are default global catalogs packaged as part of Rancher.
|
||||
|
||||
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, you need _one_ of the following permissions:
|
||||
>
|
||||
>- [Administrator Global Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/)
|
||||
>- [Custom Global Permissions]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/#custom-global-permissions) with the [Manage Catalogs]({{<baseurl>}}/rancher/v2.0-v2.4/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 before v2.2.0, you can select **Catalogs** directly in the navigation bar.
|
||||
|
||||
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. This catalog features Rancher Charts, which include some [notable advantages]({{<baseurl>}}/rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/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 before v2.2.0, within a project, you can select **Catalog Apps** from the main navigation bar.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: Custom Catalog Configuration Reference
|
||||
weight: 300
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/catalog/catalog-config
|
||||
- /rancher/v2.0-v2.4/en/catalog/catalog-config
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/catalog-config
|
||||
---
|
||||
|
||||
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)
|
||||
- [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
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
Helm comes with a 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.
|
||||
|
||||
# Catalog Fields
|
||||
|
||||
When [adding your catalog]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/custom/adding/) to Rancher, you'll provide the following information:
|
||||
|
||||
|
||||
| Variable | Description |
|
||||
| -------------------- | ------------- |
|
||||
| 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 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.0-v2.4/en/helm-charts/legacy-catalogs/#catalog-helm-deployment-versions) |
|
||||
|
||||
# Private Repositories
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Private Git or Helm chart repositories can be added into Rancher using either credentials, i.e. `Username` and `Password`. Private Git repositories also support authentication using OAuth tokens.
|
||||
|
||||
### Using Username and Password
|
||||
|
||||
1. When [adding the catalog]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/custom/adding/), select the **Use private catalog** checkbox.
|
||||
|
||||
2. Provide the `Username` and `Password` for your Git or Helm repository.
|
||||
|
||||
### Using an OAuth token
|
||||
|
||||
Read [using Git over HTTPS and OAuth](https://github.blog/2012-09-21-easier-builds-and-deployments-using-git-over-https-and-oauth/) for more details on how OAuth authentication works.
|
||||
|
||||
1. Create an [OAuth token](https://github.com/settings/tokens)
|
||||
with `repo` permission selected, and click **Generate token**.
|
||||
|
||||
2. When [adding the catalog]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/custom/adding/), select the **Use private catalog** checkbox.
|
||||
|
||||
3. For `Username`, provide the Git generated OAuth token. For `Password`, enter `x-oauth-basic`.
|
||||
@@ -0,0 +1,131 @@
|
||||
---
|
||||
title: Creating Catalog Apps
|
||||
weight: 400
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/catalog/customizing-charts/
|
||||
- /rancher/v2.0-v2.4/en/catalog/custom/creating
|
||||
- /rancher/v2.0-v2.4/en/catalog/custom
|
||||
- /rancher/v2.0-v2.4/en/catalog/creating-apps
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/creating-apps
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
> 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.
|
||||
|
||||
- [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)
|
||||
|
||||
# Chart Types
|
||||
|
||||
Rancher supports two different types of charts: Helm charts and Rancher charts.
|
||||
|
||||
### Helm 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.
|
||||
|
||||
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).
|
||||
|
||||
### 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 [Additional Files for Rancher Charts.](#additional-files-for-rancher-charts)
|
||||
|
||||
Advantages of Rancher charts include:
|
||||
|
||||
- **Enhanced revision tracking:** While Helm supports versioned deployments, Rancher adds tracking and revision history to display changes between different versions of the chart.
|
||||
- **Streamlined application launch:** Rancher charts add simplified chart descriptions and configuration forms to make catalog application deployment easy. Rancher users need not read through the entire list of Helm variables to understand how to launch an application.
|
||||
- **Application resource management:** Rancher tracks all the resources created by a specific application. Users can easily navigate to and troubleshoot on a page listing all the workload objects used to power an application.
|
||||
|
||||
# Chart Directory Structure
|
||||
|
||||
The following table demonstrates the directory structure for a Rancher Chart. The `charts` directory is the top level directory under the repository base. Adding the repository to Rancher will expose all charts contained within it. This information is helpful when customizing charts for a custom catalog. The `questions.yaml`, `README.md`, and `requirements.yml` files are specific to Rancher charts, but are optional for chart customization.
|
||||
|
||||
```
|
||||
<Repository-Base>/
|
||||
│
|
||||
├── charts/
|
||||
│ ├── <Application Name>/ # This directory name will be surfaced in the Rancher UI as the chart name
|
||||
│ │ ├── <App Version>/ # Each directory at this level provides different app versions that will be selectable within the chart in the Rancher UI
|
||||
│ │ │ ├── Chart.yaml # Required Helm chart information file.
|
||||
│ │ │ ├── questions.yaml # Form questions displayed within the Rancher UI. Questions display in Configuration Options.*
|
||||
│ │ │ ├── README.md # Optional: Helm Readme file displayed within Rancher UI. This text displays in Detailed Descriptions.
|
||||
│ │ │ ├── requirements.yml # Optional: YAML file listing dependencies for the chart.
|
||||
│ │ │ ├── values.yml # Default configuration values for the chart.
|
||||
│ │ │ ├── templates/ # Directory containing templates that, when combined with values.yml, generates Kubernetes YAML.
|
||||
```
|
||||
|
||||
# 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.
|
||||
|
||||
- `app-readme.md`
|
||||
|
||||
A file that provides descriptive text in the chart's UI header. The following image displays the difference between a Rancher chart (which includes `app-readme.md`) and a native Helm chart (which does not).
|
||||
|
||||
<figcaption>Rancher Chart with <code>app-readme.md</code> (left) vs. Helm Chart without (right)</figcaption>
|
||||
|
||||
|
||||
|
||||
- `questions.yml`
|
||||
|
||||
A file that contains 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).
|
||||
|
||||
|
||||
<figcaption>Rancher Chart with <code>questions.yml</code> (left) vs. Helm Chart without (right)</figcaption>
|
||||
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
_Available as of v2.3.0_
|
||||
|
||||
For each chart, you can add the minimum and/or maximum Rancher version, which determines whether or not this chart is available to be deployed from Rancher.
|
||||
|
||||
> **Note:** Even though Rancher release versions are prefixed with a `v`, there is *no* prefix for the release version when using this option.
|
||||
|
||||
```
|
||||
rancher_min_version: 2.3.0
|
||||
rancher_max_version: 2.3.99
|
||||
```
|
||||
|
||||
### Question Variable Reference
|
||||
|
||||
This reference contains variables that you can use in `questions.yml` nested under `questions:`.
|
||||
|
||||
| Variable | Type | Required | Description |
|
||||
| ------------- | ------------- | --- |------------- |
|
||||
| variable | string | true | Define the variable name specified in the `values.yml` file, using `foo.bar` for nested objects. |
|
||||
| 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, multiline, boolean, int, enum, password, storageclass, hostname, pvc, and secret).|
|
||||
| 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 variable 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.
|
||||
|
||||
# Tutorial: Example Custom Chart Creation
|
||||
|
||||
For a tutorial on adding a custom Helm chart to a custom catalog, refer to [this page.]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/tutorial)
|
||||
@@ -0,0 +1,161 @@
|
||||
---
|
||||
title: Global DNS
|
||||
weight: 5010
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/catalog/globaldns
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/globaldns
|
||||
---
|
||||
|
||||
_Available as of v2.2.0_
|
||||
|
||||
Rancher's Global DNS feature provides a way to program an external DNS provider to route traffic to your Kubernetes applications. Since the DNS programming supports spanning applications across different Kubernetes clusters, Global DNS is configured at a global level. An application can become highly available as it allows you to have one application run on different Kubernetes clusters. If one of your Kubernetes clusters goes down, the application would still be accessible.
|
||||
|
||||
> **Note:** Global DNS is only available in [Kubernetes installations]({{<baseurl>}}/rancher/v2.0-v2.4/en/installation/install-rancher-on-k8s/) with the `local` cluster enabled.
|
||||
|
||||
- [Global DNS Providers](#global-dns-providers)
|
||||
- [Global-DNS-Entries](#global-dns-entries)
|
||||
- [Permissions for Global DNS Providers and Entries](#permissions-for-global-dns-providers-and-entries)
|
||||
- [Setting up Global DNS for Applications](#setting-up-global-dns-for-applications)
|
||||
- [Adding a Global DNS Entry](#adding-a-global-dns-entry)
|
||||
- [Editing a Global DNS Provider](#editing-a-global-dns-provider)
|
||||
- [Global DNS Entry Configuration](#global-dns-entry-configuration)
|
||||
- [DNS Provider Configuration](#dns-provider-configuration)
|
||||
- [Route53](#route53)
|
||||
- [CloudFlare](#cloudflare)
|
||||
- [AliDNS](#alidns)
|
||||
- [Adding Annotations to Ingresses to program the External DNS](#adding-annotations-to-ingresses-to-program-the-external-dns)
|
||||
|
||||
# Global DNS Providers
|
||||
|
||||
Before adding in Global DNS entries, you will need to configure access to an external provider.
|
||||
|
||||
The following table lists the first version of Rancher each provider debuted.
|
||||
|
||||
| DNS Provider | Available as of |
|
||||
| --- | --- |
|
||||
| [AWS Route53](https://aws.amazon.com/route53/) | v2.2.0 |
|
||||
| [CloudFlare](https://www.cloudflare.com/dns/) | v2.2.0 |
|
||||
| [AliDNS](https://www.alibabacloud.com/product/dns) | v2.2.0 |
|
||||
|
||||
# Global DNS Entries
|
||||
|
||||
For each application that you want to route traffic to, you will need to create a Global DNS Entry. This entry will use a fully qualified domain name (a.k.a FQDN) from a global DNS provider to target applications. The applications can either resolve to a single [multi-cluster application]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/multi-cluster-apps/) or to specific projects. You must [add specific annotation labels](#adding-annotations-to-ingresses-to-program-the-external-dns) to the ingresses in order for traffic to be routed correctly to the applications. Without this annotation, the programming for the DNS entry will not work.
|
||||
|
||||
# Permissions for Global DNS Providers and Entries
|
||||
|
||||
By default, only [global administrators]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/) and the creator of the Global DNS provider or Global DNS entry have access to use, edit and delete them. When creating the provider or entry, the creator can add additional users in order for those users to access and manage them. By default, these members will get `Owner` role to manage them.
|
||||
|
||||
# Setting up Global DNS for Applications
|
||||
|
||||
1. From the **Global View**, select **Tools > Global DNS Providers**.
|
||||
1. To add a provider, choose from the available provider options and configure the Global DNS Provider with necessary credentials and an optional domain. For help, see [DNS Provider Configuration.](#dns-provider-configuration)
|
||||
1. (Optional) Add additional users so they could use the provider when creating Global DNS entries as well as manage the Global DNS provider.
|
||||
1. (Optional) Pass any custom values in the Additional Options section.
|
||||
|
||||
# Adding a Global DNS Entry
|
||||
|
||||
1. From the **Global View**, select **Tools > Global DNS Entries**.
|
||||
1. Click on **Add DNS Entry**.
|
||||
1. Fill out the form. For help, refer to [Global DNS Entry Configuration.](#global-dns-entry-configuration)
|
||||
1. Click **Create.**
|
||||
|
||||
# Editing a Global DNS Provider
|
||||
|
||||
The [global administrators]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/), creator of the Global DNS provider and any users added as `members` to a Global DNS provider, have _owner_ access to that provider. Any members can edit the following fields:
|
||||
|
||||
- Root Domain
|
||||
- Access Key & Secret Key
|
||||
- Members
|
||||
- Custom values
|
||||
|
||||
1. From the **Global View**, select **Tools > Global DNS Providers**.
|
||||
|
||||
1. For the Global DNS provider that you want to edit, click the **⋮ > Edit**.
|
||||
|
||||
# Editing a Global DNS Entry
|
||||
|
||||
The [global administrators]({{<baseurl>}}/rancher/v2.0-v2.4/en/admin-settings/rbac/global-permissions/), creator of the Global DNS entry and any users added as `members` to a Global DNS entry, have _owner_ access to that DNS entry. Any members can edit the following fields:
|
||||
|
||||
- FQDN
|
||||
- Global DNS Provider
|
||||
- Target Projects or Multi-Cluster App
|
||||
- DNS TTL
|
||||
- Members
|
||||
|
||||
Any users who can access the Global DNS entry can **only** add target projects that they have access to. However, users can remove **any** target project as there is no check to confirm if that user has access to the target project.
|
||||
|
||||
Permission checks are relaxed for removing target projects in order to support situations where the user's permissions might have changed before they were able to delete the target project. Another use case could be that the target project was removed from the cluster before being removed from a target project of the Global DNS entry.
|
||||
|
||||
1. From the **Global View**, select **Tools > Global DNS Entries**.
|
||||
|
||||
1. For the Global DNS entry that you want to edit, click the **⋮ > Edit**.
|
||||
|
||||
|
||||
# Global DNS Entry Configuration
|
||||
|
||||
| Field | Description |
|
||||
|----------|--------------------|
|
||||
| FQDN | Enter the **FQDN** you wish to program on the external DNS. |
|
||||
| Provider | Select a Global DNS **Provider** from the list. |
|
||||
| Resolves To | Select if this DNS entry will be for a [multi-cluster application]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/multi-cluster-apps/) or for workloads in different [projects]({{<baseurl>}}/rancher/v2.0-v2.4/en/k8s-in-rancher/projects-and-namespaces/). |
|
||||
| Multi-Cluster App Target | The target for the global DNS entry. You will need to ensure that [annotations are added to any ingresses](#adding-annotations-to-ingresses-to-program-the-external-dns) for the applications that you want to target. |
|
||||
| DNS TTL | Configure the DNS time to live value in seconds. By default, it will be 300 seconds. |
|
||||
| Member Access | Search for any users that you want to have the ability to manage this Global DNS entry. |
|
||||
|
||||
# DNS Provider Configuration
|
||||
|
||||
### Route53
|
||||
|
||||
| Field | Explanation |
|
||||
|---------|---------------------|
|
||||
| Name | Enter a **Name** for the provider. |
|
||||
| Root Domain | (Optional) Enter the **Root Domain** of the hosted zone on AWS Route53. If this is not provided, Rancher's Global DNS Provider will work with all hosted zones that the AWS keys can access. |
|
||||
| Credential Path | The [AWS credential path.](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-where) |
|
||||
| Role ARN | An [Amazon Resource Name.](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) |
|
||||
| Region | An [AWS region.](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html#Concepts.RegionsAndAvailabilityZones.Regions) |
|
||||
| Zone | An [AWS zone.](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html#Concepts.RegionsAndAvailabilityZones.AvailabilityZones) |
|
||||
| Access Key | Enter the AWS **Access Key**. |
|
||||
| Secret Key | Enter the AWS **Secret Key**. |
|
||||
| Member Access | Under **Member Access**, search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry. |
|
||||
|
||||
|
||||
### CloudFlare
|
||||
|
||||
| Field | Explanation |
|
||||
|---------|---------------------|
|
||||
| Name | Enter a **Name** for the provider. |
|
||||
| Root Domain | Optional: Enter the **Root Domain**. In case this is not provided, Rancher's Global DNS Provider will work with all domains that the keys can access. |
|
||||
| Proxy Setting | When set to yes, the global DNS entry that gets created for the provider has proxy settings on. |
|
||||
| API Email | Enter the CloudFlare **API Email**. |
|
||||
| API Key | Enter the CloudFlare **API Key**. |
|
||||
| Member Access | Search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry. |
|
||||
|
||||
### AliDNS
|
||||
|
||||
>**Notes:**
|
||||
>
|
||||
>- Alibaba Cloud SDK uses TZ data. It needs to be present on `/usr/share/zoneinfo` path of the nodes running `local` cluster, and it is mounted to the external DNS pods. If it is not available on the nodes, please follow the [instruction](https://www.ietf.org/timezones/tzdb-2018f/tz-link.html) to prepare it.
|
||||
>- Different versions of AliDNS have different allowable TTL range, where the default TTL for a global DNS entry may not be valid. Please see the [reference](https://www.alibabacloud.com/help/doc-detail/34338.htm) before adding an AliDNS entry.
|
||||
|
||||
| Field | Explanation |
|
||||
|---------|---------------------|
|
||||
| Name | Enter a **Name** for the provider. |
|
||||
| Root Domain | Optional: Enter the **Root Domain**. In case this is not provided, Rancher's Global DNS Provider will work with all domains that the keys can access. |
|
||||
| Access Key | Enter the **Access Key**. |
|
||||
| Secret Key | Enter the **Secret Key**. |
|
||||
| Member Access | Search for any users that you want to have the ability to use this provider. By adding this user, they will also be able to manage the Global DNS Provider entry. |
|
||||
|
||||
# Adding Annotations to Ingresses to program the External DNS
|
||||
|
||||
In order for Global DNS entries to be programmed, you will need to add a specific annotation on an ingress in your application or target project.
|
||||
|
||||
For any application that you want targeted for your Global DNS entry, find an ingress associated with the application.
|
||||
|
||||
This ingress needs to use a specific `hostname` and an annotation that should match the FQDN of the Global DNS entry.
|
||||
|
||||
In order for the DNS to be programmed, the following requirements must be met:
|
||||
|
||||
* The ingress routing rule must be set to use a `hostname` that matches the FQDN of the Global DNS entry.
|
||||
* The ingress must have an annotation (`rancher.io/globalDNS.hostname`) and the value of this annotation should match the FQDN of the Global DNS entry.
|
||||
|
||||
Once the ingress in your [multi-cluster application]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/multi-cluster-apps/) or in your target projects is in an `active` state, the FQDN will be programmed on the external DNS against the Ingress IP addresses.
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: Helm Charts in Rancher
|
||||
weight: 12
|
||||
description: Rancher enables the use of catalogs to repeatedly deploy applications easily. Catalogs are GitHub or Helm Chart repositories filled with deployment-ready apps.
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/concepts/global-configuration/catalog/
|
||||
- /rancher/v2.0-v2.4/en/concepts/catalogs/
|
||||
- /rancher/v2.0-v2.4/en/tasks/global-configuration/catalog/
|
||||
- /rancher/v2.0-v2.4/en/catalog
|
||||
- /rancher/v2.0-v2.4/en/catalog/apps
|
||||
---
|
||||
|
||||
Rancher provides the ability to use a catalog of Helm charts that make it easy to repeatedly deploy applications.
|
||||
|
||||
- **Catalogs** are GitHub repositories or Helm Chart repositories filled with applications that are ready-made for deployment. Applications are bundled in objects called _Helm charts_.
|
||||
- **Helm charts** are a collection of files that describe a related set of Kubernetes resources. A single chart might be used to deploy something simple, like a memcached pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on.
|
||||
|
||||
Rancher improves on Helm catalogs and charts. All native Helm charts can work within Rancher, but Rancher adds several enhancements to improve their user experience.
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
- [Catalog scopes](#catalog-scopes)
|
||||
- [Catalog Helm Deployment Versions](#catalog-helm-deployment-versions)
|
||||
- [When to use Helm 3](#when-to-use-helm-3)
|
||||
- [Helm 3 Backwards Compatibility](#helm-3-backwards-compatibility)
|
||||
- [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)
|
||||
|
||||
# Catalog Scopes
|
||||
|
||||
Within Rancher, you can manage catalogs at three different scopes. Global catalogs are shared across all clusters and project. There are some use cases where you might not want to share catalogs between different clusters or even projects in the same cluster. By leveraging cluster and project scoped catalogs, you will be able to provide applications for specific teams without needing to share them with all clusters and/or projects.
|
||||
|
||||
Scope | Description | Available As of |
|
||||
--- | --- | --- |
|
||||
Global | All clusters and all projects can access the Helm charts in this catalog | v2.0.0 |
|
||||
Cluster | All projects in the specific cluster can access the Helm charts in this catalog | v2.2.0 |
|
||||
Project | This specific cluster can access the Helm charts in this catalog | v2.2.0 |
|
||||
|
||||
# Catalog Helm Deployment Versions
|
||||
|
||||
_Applicable as of v2.4.0_
|
||||
|
||||
In November 2019, Helm 3 was released, and some features were deprecated or refactored. It is not fully [backwards compatible]({{<baseurl>}}/rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/#helm-3-backwards-compatibility) with Helm 2. Therefore, catalogs in Rancher need to be separated, with each catalog only using one Helm version. This will help reduce app deployment issues as your Rancher users will not need to know which version of your chart is compatible with which Helm version - they can just select a catalog, select an app and deploy a version that has already been vetted for compatibility.
|
||||
|
||||
When you create a custom catalog, you will have to configure the catalog to use either Helm 2 or Helm 3. This version cannot be changed later. If the catalog is added with the wrong Helm version, it will need to be deleted and re-added.
|
||||
|
||||
When you launch a new app from a catalog, the app will be managed by the catalog's Helm version. A Helm 2 catalog will use Helm 2 to manage all of the apps, and a Helm 3 catalog will use Helm 3 to manage all apps.
|
||||
|
||||
By default, catalogs are assumed to be deployed using Helm 2. If you run an app in Rancher before v2.4.0, then upgrade to Rancher v2.4.0+, the app will still be managed by Helm 2. If the app was already using a Helm 3 Chart (API version 2) it will no longer work in v2.4.0+. You must either downgrade the chart's API version or recreate the catalog to use Helm 3.
|
||||
|
||||
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.
|
||||
|
||||
# When to use Helm 3
|
||||
|
||||
_Applicable as of v2.4.0_
|
||||
|
||||
- If you want to ensure that the security permissions are being pulled from the kubeconfig file
|
||||
- If you want to utilize apiVersion `v2` features such as creating a library chart to reduce code duplication, or moving your requirements from the `requirements.yaml` into the `Chart.yaml`
|
||||
|
||||
Overall Helm 3 is a movement towards a more standardized Kubernetes feel. As the Kubernetes community has evolved, standards and best practices have as well. Helm 3 is an attempt to adopt those practices and streamline how charts are maintained.
|
||||
|
||||
# Helm 3 Backwards Compatibility
|
||||
|
||||
_Applicable as of v2.4.0_
|
||||
|
||||
With the use of the OpenAPI schema to validate your rendered templates in Helm 3, you will find charts that worked in Helm 2 may not work in Helm 3. This will require you to update your chart templates to meet the new validation requirements. This is one of the main reasons support for Helm 2 and Helm 3 was provided starting in Rancher 2.4.x, as not all charts can be deployed immediately in Helm 3.
|
||||
|
||||
Helm 3 does not create a namespace for you, so you will have to provide an existing one. This can cause issues if you have integrated code with Helm 2, as you will need to make code changes to ensure a namespace is being created and passed in for Helm 3. Rancher will continue to manage namespaces for Helm to ensure this does not impact your app deployment.
|
||||
|
||||
apiVersion `v2` is now reserved for Helm 3 charts. This apiVersion enforcement could cause issues as older versions of Helm 2 did not validate the apiVersion in the `Chart.yaml` file. In general, your Helm 2 chart’s apiVersion should be set to `v1` and your Helm 3 chart’s apiVersion should be set to `v2`. You can install charts with apiVersion `v1` with Helm 3, but you cannot install `v2` charts into Helm 2.
|
||||
|
||||
# Built-in Global Catalogs
|
||||
|
||||
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.0-v2.4/en/catalog/built-in)
|
||||
|
||||
# Custom Catalogs
|
||||
|
||||
There are two types of catalogs in Rancher: [Built-in global catalogs]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/built-in/) and [custom catalogs.]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/adding-catalogs/)
|
||||
|
||||
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.0-v2.4/en/catalog/adding-catalogs) and the [catalog configuration reference.]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/catalog-config)
|
||||
|
||||
# Creating and Launching Applications
|
||||
|
||||
In Rancher, applications are deployed from the templates in a catalog. This section covers the following topics:
|
||||
|
||||
* [Multi-cluster applications]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/multi-cluster-apps/)
|
||||
* [Creating catalog apps]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/creating-apps)
|
||||
* [Launching catalog apps within a project]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/launching-apps)
|
||||
* [Managing catalog apps]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/managing-apps)
|
||||
* [Tutorial: Example custom chart creation]({{<baseurl>}}/rancher/v2.0-v2.4/en/catalog/tutorial)
|
||||
|
||||
# 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.0-v2.4/en/helm-charts/globaldns/).
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Launching Catalog Apps
|
||||
weight: 700
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/catalog/launching-apps
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/launching-apps
|
||||
---
|
||||
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
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.0-v2.4/en/helm-charts/legacy-catalogs/#catalog-scopes).
|
||||
|
||||
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.0-v2.4/en/helm-charts/globaldns/).
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Launching a catalog app](#launching-a-catalog-app)
|
||||
- [Configuration options](#configuration-options)
|
||||
|
||||
# Prerequisites
|
||||
|
||||
When Rancher deploys a catalog app, it launches an ephemeral instance of a Helm service account that has the permissions of the user deploying the catalog app. Therefore, a user cannot gain more access to the cluster through Helm or a catalog application than they otherwise would have.
|
||||
|
||||
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.0-v2.4/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.0-v2.4/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.0-v2.4/en/catalog/built-in) or [add your own custom catalog.]({{<baseurl>}}/rancher/v2.0-v2.4/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 before 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 before 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>
|
||||
<TabItem value="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.0-v2.4/en/helm-charts/legacy-catalogs/catalog-config/#custom-helm-chart-repository)), answers are provided as key value pairs in the **Answers** section. These answers are used to override the default values.
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="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).
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Managing Catalog Apps
|
||||
weight: 500
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/catalog/managing-apps
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/managing-apps
|
||||
---
|
||||
|
||||
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 before 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 ⋮ 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 before 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 before 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 ⋮ 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 before 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.
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Multi-Cluster Apps
|
||||
weight: 600
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/catalog/multi-cluster-apps
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/multi-cluster-apps
|
||||
---
|
||||
_Available as of v2.2.0_
|
||||
|
||||
The documentation about multi-cluster apps has moved [here.]({{<baseurl>}}/rancher/v2.0-v2.4/en/deploy-across-clusters/multi-cluster-apps)
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: "Tutorial: Example Custom Chart Creation"
|
||||
weight: 800
|
||||
aliases:
|
||||
- /rancher/v2.0-v2.4/en/catalog/tutorial
|
||||
- /rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/tutorial
|
||||
---
|
||||
|
||||
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 the [Chart Directory Structure]({{<baseurl>}}/rancher/v2.0-v2.4/en/helm-charts/legacy-catalogs/creating-apps/#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.0-v2.4/en/helm-charts/legacy-catalogs/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.
|
||||
Reference in New Issue
Block a user