346 lines
15 KiB
Markdown
346 lines
15 KiB
Markdown
# partner-charts
|
|
|
|
Rancher Partner Charts is a collection of Helm charts from SUSE partners that
|
|
are certified to run on Rancher-supported Kubernetes distributions. These charts
|
|
are served from this repository so that users can deploy these charts directly
|
|
from the Apps view in Rancher Manager.
|
|
|
|
Rancher-specific modifications are applied to these charts, and overlay files
|
|
may be added as well.
|
|
|
|
## SUSE Ready Partnership
|
|
|
|
Before submitting a contribution to this repository, you must be a
|
|
[SUSE "Ready" Verified partner](https://www.suse.com/product-certification/ready/certify-your-applications/).
|
|
|
|
Start this process with a [Partner Application](https://partner.suse.com/s/apply).
|
|
|
|
To certify your software, you need to attest that the software:
|
|
|
|
* has been tested on RKE2 or K3s and publishes documentation showing supported
|
|
versions, including
|
|
* version of Rancher (e.g. 2.8)
|
|
* Rancher-supported distribution of Kubernetes (RKE2, K3s, EKS, etc.)
|
|
* version of Kubernetes (e.g. 1.27)
|
|
* is supported by your organization on the declared Rancher versions and configurations
|
|
* is actively maintained and proactively updated
|
|
* Critical vulnerabilities are patched in a timely way
|
|
* release notes disclose serious bugs and vulnerabilities
|
|
* has a license and/or terms and conditions for use available in public
|
|
documentation or via the chart itself
|
|
* does not compete commercially with Rancher Prime
|
|
|
|
## Requirements
|
|
|
|
Once your software is certified SUSE "Ready", there are a few more requirements
|
|
for inclusion in Rancher Partner charts. The Helm chart must:
|
|
|
|
* be Helm 3 compatible
|
|
* be in a hosted [Helm](https://helm.sh/docs/topics/chart_repository/)
|
|
(recommended) or Git repository that we can reference
|
|
* have the following Rancher specific add-ons (More details on this below)
|
|
* kubeVersion set in the chart's metadata
|
|
* app-readme.md
|
|
* questions.yml (Optional)
|
|
* be deployable from the current version of Rancher with the default Values
|
|
|
|
Testing these requirements will ensure that Rancher users can deploy your
|
|
software correctly and easily.
|
|
|
|
## Workflow
|
|
|
|
#### 1. Fork the [Rancher Partner Charts](https://github.com/rancher/partner-charts/) repository, clone your fork, checkout the **main-source** branch and pull the latest changes.
|
|
Then create a new branch off of main-source
|
|
|
|
#### 2. Create subdirectories in **packages** in the form of `<vendor>/<chart>`
|
|
```bash
|
|
cd partner-charts
|
|
mkdir -p packages/suse/kubewarden-controller
|
|
|
|
```
|
|
#### 3. Create your [upstream.yaml](#configuration-file) in `packages/<vendor>/<chart>`
|
|
|
|
The tool reads a configuration yaml, `upstream.yaml`, to know where to fetch the upstream chart. This file is also able to define any alterations for valid variables in the Chart.yaml as described by [Helm](https://helm.sh/docs/topics/charts/#the-chartyaml-file).
|
|
|
|
**Important:** In GKE clusters, a Helm Chart will NOT display in Rancher Apps unless `kubeVersion` includes `-0` suffix in `Chart.yaml` For example:
|
|
```bash
|
|
kubeVersion: '>= 1.19.0-0'
|
|
```
|
|
Some [example upstream.yaml](#examples) are provided below
|
|
```bash
|
|
cat <<EOF > packages/suse/kubewarden-controller/upstream.yaml
|
|
HelmRepo: https://charts.kubewarden.io
|
|
HelmChart: kubewarden-controller
|
|
Vendor: SUSE
|
|
DisplayName: Kubewarden Controller
|
|
ChartMetadata:
|
|
icon: https://www.kubewarden.io/images/icon-kubewarden.svg
|
|
EOF
|
|
```
|
|
#### 4. [Create 'overlay' files](#overlay)
|
|
Create any add-on files such as an `app-readme.md` and `questions.yml` in an `overlay` subdirectory (Optional)
|
|
```bash
|
|
mkdir packages/suse/kubewarden-controller/overlay
|
|
echo "Example app-readme.md" > packages/suse/kubewarden-controller/overlay/app-readme.md
|
|
```
|
|
#### 5. Commit your packages directory
|
|
```bash
|
|
git add packages/suse/kubewarden-controller
|
|
git commit -m "Submitting suse/kubewarden-controller"
|
|
```
|
|
#### 6. [Test your configuration](#testing-your-configuration)
|
|
#### 7. Push your commit
|
|
```bash
|
|
git push origin <your_branch>
|
|
```
|
|
#### 8. Open a pull request to **main-source** branch
|
|
|
|
|
|
## Testing your configuration
|
|
If you would like to test your configuration using the CI tool, simply run the provided script in `scripts/pull-scripts` to download the binary. The 'auto' function is what will be run to download and store your chart.
|
|
|
|
#### 1. Download the binary
|
|
```bash
|
|
scripts/pull-scripts
|
|
```
|
|
#### 2. Set the **PACKAGE** environment variable to your chart
|
|
You can confirm the package entry with `bin/partner-charts-ci list` which will list all detected charts with a configuration file.
|
|
```bash
|
|
export PACKAGE=<vendor>/<chart>
|
|
```
|
|
#### 3. Run the 'auto' or 'stage' function
|
|
The 'auto' subcommand will run the complete CI process.
|
|
The 'stage' subcommand will do the same process but will not create a git commit when it completes.
|
|
```bash
|
|
bin/partner-charts-ci auto
|
|
```
|
|
#### 4. Validate your changes
|
|
```bash
|
|
bin/partner-charts-ci validate
|
|
```
|
|
#### Testing new chart on Rancher Apps UI
|
|
1. If you haven't done so yet, pull down your new chart files into your local `partner-charts` repository:
|
|
```bash
|
|
a) Get scripts: scripts/pull-scripts
|
|
b) List and find your company name/chart: bin/partner-charts-ci list | grep <vendor>
|
|
c) set PACKAGE variable to your company/chart: export PACKAGE=<vendor>/<chart-name> or export PACKAGE=<vendor>
|
|
d) Run bin/partner-charts-ci stage or auto # the new charts should be downloaded
|
|
```
|
|
2. In your local `partner-charts` directory start a python3 http server:
|
|
```bash
|
|
#python3 -m http.server 8000
|
|
```
|
|
3. From a second terminal expose your local http server via ngrok ( https://ngrok.com/download )
|
|
```bash
|
|
#./ngrok http 8000
|
|
```
|
|
4. In Rancher UI create a test repository that points to your local `partner-charts` repo by selecting an appropriate cluster and going to Apps > Repositories and clicking "Create". Enter a Name, copy ngrok forwarding url and paste it into Target http(s) "Index URL" and click "Create" again.
|
|
|
|
5. Once the new repository is "Active" go to Apps > Charts , find your new chart, review Readme is correct, etc. and install it. It should be successfully deployed.
|
|
|
|
## Overlay
|
|
|
|
Any files placed in the `packages/<vendor>/<chart>/overlay` directory will be overlayed onto the chart. This allows for adding or overwriting files within the chart as needed. The primary intended purpose is for adding the optional app-readme.md and questions.yml files but it may be used for adding or replacing any chart files.
|
|
|
|
- `app-readme.md` - Write a brief description of the app and how to use it. It's recommended to keep
|
|
it short as the longer `README.md` in your chart will be displayed in the UI as detailed description.
|
|
|
|
- `questions.yml` - Defines a set of questions to display in the chart's installation page in order for users to
|
|
answer them and configure the chart using the UI instead of modifying the chart's values file directly.
|
|
|
|
#### Questions example
|
|
[Variable Reference](https://docs.ranchermanager.rancher.io/how-to-guides/new-user-guides/helm-charts-in-rancher/create-apps#question-variable-reference)
|
|
```yaml
|
|
questions:
|
|
- variable: password
|
|
default: ""
|
|
required: true
|
|
type: password
|
|
label: Admin Password
|
|
group: "Global Settings"
|
|
- variable: service.type
|
|
default: "ClusterIP"
|
|
type: enum
|
|
group: "Service Settings"
|
|
options:
|
|
- "ClusterIP"
|
|
- "NodePort"
|
|
- "LoadBalancer"
|
|
required: true
|
|
label: Service Type
|
|
show_subquestion_if: "NodePort"
|
|
subquestions:
|
|
- variable: service.nodePort
|
|
default: ""
|
|
description: "NodePort port number (to set explicitly, choose port between 30000-32767)"
|
|
type: int
|
|
min: 30000
|
|
max: 32767
|
|
label: Service NodePort
|
|
```
|
|
|
|
## Configuration File
|
|
|
|
Options for `upstream.yaml`
|
|
| Variable | Requires | Description |
|
|
| ------------- | ------------- |------------- |
|
|
| ArtifactHubPackage | ArtifactHubRepo | Defines the package to pull from the defined ArtifactHubRepo
|
|
| ArtifactHubRepo | ArtifactHubPackage | Defines the repo to access on Artifact Hub
|
|
| AutoInstall | | Allows setting a required additional chart to deploy prior to current chart, such as a dedicated CRDs chart
|
|
| ChartMetadata | | Allows setting/overriding the value of any valid [Chart.yaml variable](https://helm.sh/docs/topics/charts/#the-chartyaml-file)
|
|
| Deprecated | | Whether the package is deprecated. Deprecated packages will not integrate any new chart versions from upstream
|
|
| DisplayName | | Sets the name the chart will be listed under in the Rancher UI
|
|
| Experimental | | Adds the 'experimental' annotation which adds a flag on the UI entry
|
|
| Fetch | HelmChart, HelmRepo | Selects set of charts to pull from upstream.<br />- **latest** will pull only the latest chart version *default*<br />- **newer** will pull all newer versions than currently stored<br />- **all** will pull all versions
|
|
| GitBranch | GitRepo | Defines which branch to pull from the upstream GitRepo
|
|
| GitHubRelease | GitRepo | If true, will pull latest GitHub release from repo. Requires GitHub URL
|
|
| GitRepo | | Defines the git repo to pull from
|
|
| GitSubdirectory | GitRepo | Allows selection of a subdirectory of the upstream git repo to pull the chart from
|
|
| HelmChart | HelmRepo | Defines which chart to pull from the upstream Helm repo
|
|
| HelmRepo | HelmChart | Defines the upstream Helm repo to pull from
|
|
| Hidden | | Adds the 'hidden' annotation which hides the chart from the Rancher UI
|
|
| Namespace | | Addes the 'namespace' annotation which hard-codes a deployment namespace for the chart
|
|
| PackageVersion | | Used to generate new patch version of chart
|
|
| ReleaseName | | Sets the value of the release-name Rancher annotation. Defaults to the chart name
|
|
| TrackVersions | HelmChart, HelmRepo | Allows selection of multiple *Major.Minor* versions to track from upstream independently.
|
|
| Vendor | | Sets the vendor name providing the chart
|
|
|
|
## Examples
|
|
### Helm Repo
|
|
#### Minimal Requirements
|
|
```yaml
|
|
HelmRepo: https://charts.kubewarden.io
|
|
HelmChart: kubewarden-controller
|
|
Vendor: SUSE
|
|
DisplayName: Kubewarden Controller
|
|
```
|
|
#### Multiple Release Streams
|
|
```yaml
|
|
HelmRepo: https://charts.kubewarden.io
|
|
HelmChart: kubewarden-controller
|
|
Vendor: SUSE
|
|
DisplayName: Kubewarden Controller
|
|
Fetch: newer
|
|
TrackVersions:
|
|
- 0.4
|
|
- 1.0
|
|
- 1.1
|
|
ChartMetadata:
|
|
kubeVersion: '>=1.21-0'
|
|
icon: https://www.kubewarden.io/images/icon-kubewarden.svg
|
|
```
|
|
|
|
### Artifact Hub
|
|
```yaml
|
|
ArtifactHubRepo: kubewarden
|
|
ArtifactHubPackage: kubewarden-controller
|
|
Vendor: SUSE
|
|
DisplayName: Kubewarden Controller
|
|
ChartMetadata:
|
|
kubeVersion: '>=1.21-0'
|
|
icon: https://www.kubewarden.io/images/icon-kubewarden.svg
|
|
```
|
|
|
|
### Git Repo
|
|
```yaml
|
|
GitRepo: https://github.com/kubewarden/helm-charts.git
|
|
GitBranch: main
|
|
GitSubdirectory: charts/kubewarden-controller
|
|
Vendor: SUSE
|
|
DisplayName: Kubewarden Controller
|
|
ChartMetadata:
|
|
kubeVersion: '>=1.21-0'
|
|
icon: https://www.kubewarden.io/images/icon-kubewarden.svg
|
|
```
|
|
|
|
### GitHub Release
|
|
```yaml
|
|
GitRepo: https://github.com/kubewarden/helm-charts.git
|
|
GitHubRelease: true
|
|
GitSubdirectory: charts/kubewarden-controller
|
|
Vendor: SUSE
|
|
DisplayName: Kubewarden Controller
|
|
ChartMetadata:
|
|
kubeVersion: '>=1.21-0'
|
|
icon: https://www.kubewarden.io/images/icon-kubewarden.svg
|
|
```
|
|
## Migrate existing chart to automated updates
|
|
These steps are for charts still using `package.yaml` to track upstream chart. These charts should be migrated to receive automatic updates via an `upstream.yaml` by following the steps below. After chart is migrated, it should get updated from your helm/github repo automatically.
|
|
|
|
#### 1. Fork partner-charts repository, clone your fork, checkout the main-source branch and pull the latest changes. Then create a new branch off of main-source
|
|
|
|
#### 2. Create directory structure for your company and chart in `packages/<vendor>/<chart>` e.g.
|
|
```bash
|
|
mkdir -p partner-charts/packages/suse/kubewarden-controller
|
|
```
|
|
#### 3. Create an `upstream.yaml` in `packages/<vendor>/<chart>`
|
|
If your existing chart is using a high patch version like 5.5.100 due to old method of taking version 5.5.1 and modifying it with the PackageVersion, add `PackageVersion` to the `upstream.yaml` (set it to 01 , 00 is not valid). Ideally, when the the next minor version is released e.g. 5.6.X you can then remove `PackageVersion` from the `upstream.yaml` since 5.6.X > 5.5.XXX. E.g.
|
|
```yaml
|
|
cat <<EOF > packages/suse/kubewarden-controller/upstream.yaml
|
|
HelmRepo: https://charts.kubewarden.io
|
|
HelmChart: kubewarden-controller
|
|
Vendor: SUSE
|
|
DisplayName: Kubewarden Controller
|
|
PackageVersion: 01 # add if existing chart is using high patch version
|
|
ChartMetadata:
|
|
kubeVersion: '>=1.21-0'
|
|
icon: https://www.kubewarden.io/images/icon-kubewarden.svg
|
|
EOF
|
|
```
|
|
#### 4. If there is an `overlay` dir in `partner-charts/packages/<chart>/generated-changes/` move it to `packages/<vendor>/<chart>/` and ensure only necessary files are present in overlay dir e.g.
|
|
```bash
|
|
mv partner-charts/packages/kubewarden-controller/generated-changes/overlay partner-charts/packages/suse/kubewarden-controller/
|
|
```
|
|
Check the old generated-changes/patch directory for any requisite other changes. If there is an edit in `Chart.yaml.patch` that needs to be replicated, it can be handled in the `upstream.yaml` `ChartMetadata` (see https://github.com/rancher/partner-charts#configuration-file). If it is a change for any other file in the chart it can be done via an overlay file. See https://github.com/rancher/partner-charts#overlay
|
|
|
|
#### 5. Clean up old packages and charts directories:
|
|
```bash
|
|
git rm -r packages/<chart>
|
|
git rm -r charts/<chart>
|
|
```
|
|
* Note: If a chart is using a logo file in partner-charts repo, make sure the `icon:` variable is set correctly in the `upstream.yaml ChartMetadata`.
|
|
|
|
#### 6. Stage your changes (To make sure the config works, and to setup the new charts and assets directories)
|
|
```bash
|
|
export PACKAGE=<vendor>/<chart>
|
|
bin/partner-charts-ci stage
|
|
```
|
|
#### 7. Move the old assets files to the new directory (Sometimes this is unchanged but most times it does change)
|
|
```bash
|
|
git mv assets/<chart>/* assets/<vendor>/
|
|
```
|
|
#### 8. Update the `index.yaml` to reflect the new assets path for existing entries
|
|
```bash
|
|
sed -i 's%assets/<chart>%assets/<vendor>%' index.yaml
|
|
```
|
|
After doing this, run this loop to validate that every assets file referenced in the index actually exists, it makes sure your paths aren't edited incorrectly.
|
|
```bash
|
|
for charts in $(yq '.entries[][] | .urls[0]' index.yaml); do stat ${charts} > /dev/null; if [[ ! $? -eq 0 ]]; then echo ${charts}; fi; done
|
|
```
|
|
The command should return quickly with no output. If it outputs anything it means some referenced assets files don't exist which is a problem.
|
|
#### 9. Add/Commit your changes
|
|
```bash
|
|
git add assets charts packages index.yaml
|
|
git commit -m "Migrating <vendor> <chart> chart"
|
|
```
|
|
#### 10. Push your commit
|
|
```bash
|
|
git push origin <your branch>
|
|
```
|
|
#### 11. Open a pull request to the `main-source` branch for review
|
|
|
|
## Deprecation and Removal Policy
|
|
|
|
Charts may be removed from this repository for a number of reasons:
|
|
|
|
- Technical requirements are not met
|
|
- A serious security problem is discovered
|
|
- The vendor's SUSE "Ready" partnership is no longer active
|
|
|
|
In these cases, the chart will first be deprecated. While a chart is deprecated,
|
|
no new versions of the chart will be added to this repository. The chart will
|
|
be left in the deprecated state for a minimum of 3 months, and then it will be
|
|
removed. The pull requests that deprecate and remove the chart will indicate an
|
|
alternative source (e.g. the corresponding upstream project or [Rancher Prime
|
|
Application Collection](https://apps.rancher.io)) if one is available.
|