Skip to content

Commit

Permalink
Update readme (#1089)
Browse files Browse the repository at this point in the history
  • Loading branch information
@adamkpickering
adamkpickering authored Nov 26, 2024
1 parent 03f7368 commit 0c337e8
Showing 1 changed file with 48 additions and 302 deletions.
350 changes: 48 additions & 302 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,23 @@
# partner-charts
# Rancher Partner Charts Repository

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.
The Rancher Partner Charts Repository is a collection of helm charts from
SUSE partners that are certified to run on Rancher-supported Kubernetes
distributions. Users can deploy these charts directly from the Apps view in
Rancher Manager. Minor Rancher-specific modifications are added to these charts
in order to provide the best possible experience using them from within Rancher.

Rancher-specific modifications are applied to these charts, and overlay files
may be added as well.
[`partner-charts-ci`](https://github.com/rancher/partner-charts-ci) is used to
automate many aspects of this repository. For the technical details of this
repository, please consult the `partner-charts-ci` documentation.

## 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/).
### What are the requirements for adding a project to this repository?

Start this process with a [Partner Application](https://partner.suse.com/s/apply).
Before submitting a chart to this repository, you must become a
[SUSE "Ready" Verified partner](https://www.suse.com/product-certification/ready/certify-your-applications/).
You can start this process with a [Partner Application](https://partner.suse.com/s/apply).

To certify your software, you need to attest that the software:
To certify your software as SUSE "Ready", you need to attest that the software:

* has been tested on RKE2 or K3s and publishes documentation showing supported
versions, including
Expand All @@ -24,316 +26,60 @@ To certify your software, you need to attest that the software:
* 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
* 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 public [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, download `partner-charts-ci`
using `scripts/pull-scripts`. The `update` function can be used to download and
integrate your chart.

#### 1. Download `partner-charts-ci`
```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 `update` subcommand
The `update` subcommand will go through the CI process. Append the `--commit`
flag if you want it to create a git commit when it completes.
```bash
bin/partner-charts-ci update --commit
```
#### 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 update # 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.
Once your software is certified as SUSE "Ready", there are a few more requirements
for inclusion in this repository. Your software's helm chart must:

#### 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
```
* be helm 3 compatible
* be available from a public [helm repository](https://helm.sh/docs/topics/chart_repository/)
(recommended) or a public git repository
* have `kubeVersion` set in the chart's metadata
* contain an `app-readme.md` file (refer to the [`partner-charts-ci` documentation](https://github.com/rancher/partner-charts-ci) for more details)
* be deployable from the current version of Rancher with the default values

## Configuration File
Meeting these requirements ensures that Rancher users can easily deploy your
software.

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. Do not set this field directly; instead, use `partner-charts-ci deprecate`.
| 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. Do not set this field directly unless the package is new; instead, use `partner-charts-ci hide`.
| 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
| Vendor | | Sets the vendor name providing the chart
> [!NOTE]
> This repository is not intended for certain kinds of software. For example:
>
> * slightly modified software or helm charts that meet the needs of only a
> few people
> * software maintained by an open source community without any backing
> organization with which SUSE can have a partnership
## 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
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
```
### How do I add my project to this repository?

### 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
```
In order to add a helm chart to this repository:

### 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 this repository.
2. Follow the process for adding a package as described in the
[`partner-charts-ci` documentation](https://github.com/rancher/partner-charts-ci).
`partner-charts-ci` can be obtained by running `scripts/pull-scripts`, which
downloads the right version for your machine to `bin/partner-charts-ci`.
3. Create a pull request for your changes targeting the `main-source` branch in this repository.

#### 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
### Who is responsible for maintaining the helm charts in this repository?

#### 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`.
Each SUSE partner organzation is responsible for maintaining the versions
of their helm charts in this repository. However, SUSE also monitors this
repository and may make changes if necessary.

#### 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 update
```
#### 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
### When and how are helm charts removed from this repository?

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
* 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
Expand Down

0 comments on commit 0c337e8

Please sign in to comment.