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

Remove unneeded intermediate folders

Browse Source
This commit is contained in:
Billy Tat
2022-08-17 10:23:03 -07:00
parent 506e174643
commit 07355d1446
1146 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
versioned_docs/version-2.6/helm-charts/creating-apps/creating-apps.md
+128
View File
@@ -0,0 +1,128 @@
---
title: Creating Apps
weight: 400
---
Rancher's App Marketplace is based on Helm Repositories and Helm Charts. You can add HTTP based standard Helm Repositories as well as any Git Repository which contains charts.
> 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' can provide the chart's parameter values in a YAML editor.
### Rancher Charts
Rancher charts are native helm charts with 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)
Rancher charts add simplified chart descriptions and configuration forms to make the application deployment easy. Rancher users do not need to read through the entire list of Helm variables to understand how to launch an application.
# Chart Directory Structure
You can provide Helm Charts in a standard, HTTP based Helm Repository. For more information see the [Chart Repository Guide](https://helm.sh/docs/topics/chart_repository) in the official Helm documentation.
Alternatively you can organize your charts in a Git Repository and directly add this to the App Marketplace.
The following table demonstrates the directory structure for a Git repository. The `charts` directory is the top level directory under the repository base. Adding the repository to Rancher will expose all charts contained within it. 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.
- `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 a values YAML config, 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> (top) vs. Helm Chart without (bottom)</figcaption>
![questions.yml]({{<baseurl>}}/img/rancher/rancher-app-2.6.png)
![values.yaml]({{<baseurl>}}/img/rancher/helm-app-2.6.png)
### Chart.yaml annotations
Rancher supports additional annotations that you can add to the `Chart.yaml` file. These annotations allow you to define application dependencies or configure additional UI defaults:
| Annotation | Description | Example |
| --------------------------------- | ----------- | ------- |
| catalog.cattle.io/auto-install | If set, will install the specified chart in the specified version before installing this chart | other-chart-name=1.0.0 |
| catalog.cattle.io/display-name | A display name that should be displayed in the App Marketplace instead of the chart name | Display Name of Chart |
| catalog.cattle.io/namespace | A fixed namespace where the chart should be deployed in. If set, this can't be changed by the user | fixed-namespace |
| catalog.cattle.io/release-name | A fixed release name for the Helm installation. If set, this can't be changed by the user | fixed-release-name |
| catalog.cattle.io/requests-cpu | Total amount of CPU that should be unreserverd in the cluster. If less CPU is available, a warning will be shown | 2000m |
| catalog.cattle.io/requests-memory | Total amount of memory that should be unreserverd in the cluster. If less memory is available, a warning will be shown | 2Gi |
| catalog.cattle.io/os | Restricts the OS where this chart can be installed. Possible values: `linux`, `windows`. Default: no restriction | linux |
### 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
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.
versioned_docs/version-2.6/helm-charts/helm-charts.md
+137
View File
@@ -0,0 +1,137 @@
---
title: Helm Charts in Rancher
weight: 11
---
In this section, you'll learn how to manage Helm chart repositories and applications in Rancher. Helm chart repositories are managed using **Apps & Marketplace**. It uses a catalog-like system to import bundles of charts from repositories and then uses those charts to either deploy custom Helm applications or Rancher's tools such as Monitoring or Istio. Rancher tools come as pre-loaded repositories which deploy as standalone Helm charts. Any additional repositories are only added to the current cluster.
### Changes in Rancher v2.6
Starting in Rancher v2.6.0, a new versioning scheme for Rancher feature charts was implemented. The changes are centered around the major version of the charts and the +up annotation for upstream charts, where applicable.
**Major Version:** The major version of the charts is tied to Rancher minor versions. When you upgrade to a new Rancher minor version, you should ensure that all of your **Apps & Marketplace** charts are also upgraded to the correct release line for the chart.
>**Note:** Any major versions that are less than the ones mentioned in the table below are meant for 2.5 and below only. For example, you are advised to not use <100.x.x versions of Monitoring in 2.6.x+.
**Feature Charts:**
| **Name** | **Supported Minimum Version** | **Supported Maximum Version** |
| ---------------- | ------------ | ------------ |
| external-ip-webhook | 100.0.0+up1.0.0 | 100.0.1+up1.0.1 |
| harvester-cloud-provider | 100.0.2+up0.1.12 | 100.0.2+up0.1.12 |
| harvester-csi-driver | 100.0.2+up0.1.11 | 100.0.2+up0.1.11 |
| rancher-alerting-drivers | 100.0.0 | 100.0.2 |
| rancher-backup | 2.0.1 | 2.1.2 |
| rancher-cis-benchmark | 2.0.1 | 2.0.4 |
| rancher-gatekeeper | 100.0.0+up3.6.0 | 100.1.0+up3.7.1 |
| rancher-istio | 100.0.0+up1.10.4 | 100.2.0+up1.12.6 |
| rancher-logging | 100.0.0+up3.12.0 | 100.1.2+up3.17.4 |
| rancher-longhorn | 100.0.0+up1.1.2 | 100.1.1+up1.2.3 |
| rancher-monitoring | 100.0.0+up16.6.0 | 100.1.0+up19.0.3
| rancher-sriov (experimental) | 100.0.0+up0.1.0 | 100.0.3+up0.1.0 |
| rancher-vsphere-cpi | 100.3.0+up1.2.1 | 100.3.0+up1.2.1 |
| rancher-vsphere-csi | 100.3.0+up2.5.1-rancher1 | 100.3.0+up2.5.1-rancher1 |
| rancher-wins-upgrader | 0.0.100 | 100.0.0+up0.0.1 |
| neuvector | 100.0.0+up2.2.0 | 100.0.0+up2.2.0 |
</br>
**Charts based on upstream:** For charts that are based on upstreams, the +up annotation should inform you of what upstream version the Rancher chart is tracking. Check the upstream version compatibility with Rancher during upgrades also.
- As an example, `100.x.x+up16.6.0` for Monitoring tracks upstream kube-prometheus-stack `16.6.0` with some Rancher patches added to it.
- On upgrades, ensure that you are not downgrading the version of the chart that you are using. For example, if you are using a version of Monitoring > `16.6.0` in Rancher 2.5, you should not upgrade to `100.x.x+up16.6.0`. Instead, you should upgrade to the appropriate version in the next release.
### Charts
From the top-left menu select _"Apps & Marketplace"_ and you will be taken to the Charts page.
The charts page contains all Rancher, Partner, and Custom Charts.
* Rancher tools such as Logging or Monitoring are included under the Rancher label
* Partner charts reside under the Partners label
* Custom charts will show up under the name of the repository
All three types are deployed and managed in the same way.
> Apps managed by the Cluster Manager (the global view in the legacy Rancher UI) should continue to be managed only by the Cluster Manager, and apps managed with <b>Apps & Marketplace</b> in the new UI must be managed only by <b>Apps & Marketplace</b>.
### Repositories
From the left sidebar select _"Repositories"_.
These items represent helm repositories, and can be either traditional helm endpoints which have an index.yaml, or git repositories which will be cloned and can point to a specific branch. In order to use custom charts, simply add your repository here and they will become available in the Charts tab under the name of the repository.
To add a private CA for Helm Chart repositories:
- **HTTP-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:</br>
```
[...]
spec:
caBundle:
MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT
...
nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4=
[...]
```
- **Git-based chart repositories**: You must add a base64 encoded copy of the CA certificate in DER format to the spec.caBundle field of the chart repo, such as `openssl x509 -outform der -in ca.pem | base64 -w0`. Click **Edit YAML** for the chart repo and set, as in the following example:</br>
```
[...]
spec:
caBundle:
MIIFXzCCA0egAwIBAgIUWNy8WrvSkgNzV0zdWRP79j9cVcEwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRQwEgYDVQQKDAtNeU9yZywgSW5jLjENMAsGA1UEAwwEcm9vdDAeFw0yMTEyMTQwODMyMTdaFw0yNDEwMDMwODMyMT
...
nDxZ/tNXt/WPJr/PgEB3hQdInDWYMg7vGO0Oz00G5kWg0sJ0ZTSoA10ZwdjIdGEeKlj1NlPyAqpQ+uDnmx6DW+zqfYtLnc/g6GuLLVPamraqN+gyU8CHwAWPNjZonFN9Vpg0PIk1I2zuOc4EHifoTAXSpnjfzfyAxCaZsnTptimlPFJJqAMj+FfDArGmr4=
[...]
```
> **Note:** Helm chart repositories with authentication
>
> As of Rancher v2.6.3, a new value `disableSameOriginCheck` has been added to the Repo.Spec. This allows users to bypass the same origin checks, sending the repository Authentication information as a Basic Auth Header with all API calls. This is not recommended but can be used as a temporary solution in cases of non-standard Helm chart repositories such as those that have redirects to a different origin URL.
>
> To use this feature for an existing Helm chart repository, click <b>⋮ > Edit YAML</b>. On the `spec` portion of the YAML file, add `disableSameOriginCheck` and set it to `true`.
>
> ```yaml
[...]
spec:
disableSameOriginCheck: true
[...]
```
### Helm Compatibility
Only Helm 3 compatible charts are supported.
### Deployment and Upgrades
From the _"Charts"_ tab select a Chart to install. Rancher and Partner charts may have extra configurations available through custom pages or questions.yaml files, but all chart installations can modify the values.yaml and other basic settings. Once you click install, a Helm operation job is deployed, and the console for the job is displayed.
To view all recent changes, go to the _"Recent Operations"_ tab. From there you can view the call that was made, conditions, events, and logs.
After installing a chart, you can find it in the _"Installed Apps"_ tab. In this section you can upgrade or delete the installation, and see further details. When choosing to upgrade, the form and values presented will be the same as installation.
Most Rancher tools have additional pages located in the toolbar below the _"Apps & Marketplace"_ section to help manage and use the features. These pages include links to dashboards, forms to easily add Custom Resources, and additional information.
> If you are upgrading your chart using _"Customize Helm options before upgrade"_ , please be aware that using the _"--force"_ option may result in errors if your chart has immutable fields. This is because some objects in Kubernetes cannot be changed once they are created. To ensure you do not get this error you can:
>
> * use the default upgrade option ( i.e do not use _"--force"_ option )
> * uninstall the existing chart and install the upgraded chart
> * delete the resources with immutable fields from the cluster before performing the _"--force"_ upgrade
#### Changes in Rancher v2.6.3
The upgrade button has been removed for legacy apps from the **Apps & Marketplace > Installed Apps** page.
If you have a legacy app installed and want to upgrade it:
- The legacy [feature flag]({{<baseurl>}}/rancher/v2.6/en/installation/resources/feature-flags/) must be turned on (if it's not turned on automatically because of having a legacy app before upgrading)
- You can upgrade the app from cluster explorer, from the left nav section **Legacy > Project > Apps**
- For multi-cluster apps, you can go to **≡ > Multi-cluster Apps** and upgrade the app from there
### Limitations
[Dashboard apps or Rancher feature charts](../helm-charts/) **cannot** be installed using the Rancher CLI.