Skip to content

Latest commit

 

History

History
343 lines (302 loc) · 15.1 KB

README.md

File metadata and controls

343 lines (302 loc) · 15.1 KB
Raw

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.

Start this process with a Partner Application.

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 public Helm (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 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>

cd partner-charts
mkdir -p packages/suse/kubewarden-controller

3. Create your upstream.yaml 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.

Important: In GKE clusters, a Helm Chart will NOT display in Rancher Apps unless kubeVersion includes -0 suffix in Chart.yaml For example:

kubeVersion: '>= 1.19.0-0'

Some example upstream.yaml are provided below

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

Create any add-on files such as an app-readme.md and questions.yml in an overlay subdirectory (Optional)

mkdir packages/suse/kubewarden-controller/overlay
echo "Example app-readme.md" > packages/suse/kubewarden-controller/overlay/app-readme.md

5. Commit your packages directory

git add packages/suse/kubewarden-controller
git commit -m "Submitting suse/kubewarden-controller"

6. Test your configuration

7. Push your commit

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

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.

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.

bin/partner-charts-ci update --commit

4. Validate your changes

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:
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
  1. In your local partner-charts directory start a python3 http server:
#python3 -m http.server 8000
  1. From a second terminal expose your local http server via ngrok ( https://ngrok.com/download )
#./ngrok http 8000

  1. 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.

  2. 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

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
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.
- latest will pull only the latest chart version default
- newer will pull all newer versions than currently stored
- 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

Examples

Helm Repo

Minimal Requirements

HelmRepo: https://charts.kubewarden.io
HelmChart: kubewarden-controller
Vendor: SUSE
DisplayName: Kubewarden Controller

Multiple Release Streams

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

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

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

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.

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.

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.

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:

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)

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)

git mv assets/<chart>/* assets/<vendor>/

8. Update the index.yaml to reflect the new assets path for existing entries

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.

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

git add assets charts packages index.yaml
git commit -m "Migrating <vendor> <chart> chart"

10. Push your commit

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) if one is available.