From 6a192ca2882502f5dd9a9b23ec224e3fe5cea745 Mon Sep 17 00:00:00 2001 From: Steven Crespo Date: Fri, 25 Jun 2021 12:05:01 -0700 Subject: [PATCH] Update README --- README.md | 81 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 44 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index af21726d0..1bf40db01 100644 --- a/README.md +++ b/README.md @@ -9,16 +9,16 @@ files on top of it. * Chart must be Helm 3 compatible. - Helm 2 installed CRDs via an `helm.sh/hook: crd-install` annotation that installed - CRDs via a special hook. In Helm 3, this annotation was removed in favor of a `crds/` - directory where your CRDs should now reside. Templating and upgrading CRDs is also no - longer supported by default. Users who need to support templating / upgrading CRDs should - use a separate CRD chart that installs the CRDs via the `templates/` directory instead. - Leaving this hook in your chart will not cause it to break, but will cause the Helm logs - to emit the warning `manifest_sorter.go:175: info: skipping unknown hook: "crd-install"` - on an install or upgrade. + Helm 2 installed CRDs via an `helm.sh/hook: crd-install` annotation that installed + CRDs via a special hook. In Helm 3, this annotation was removed in favor of a `crds/` + directory where your CRDs should now reside. Templating and upgrading CRDs is also no + longer supported by default. Users who need to support templating / upgrading CRDs should + use a separate CRD chart that installs the CRDs via the `templates/` directory instead. + Leaving this hook in your chart will not cause it to break, but will cause the Helm logs + to emit the warning `manifest_sorter.go:175: info: skipping unknown hook: "crd-install"` + on an install or upgrade. - In addition, staritng [Helm 3.5.2](https://github.com/helm/helm/releases/tag/v3.5.2), Helm is stricter about parsing semver strings. Therefore, to ensure that your chart is deployable via Helm 3.5.2, your chart must have a semver-compliant version. + In addition, starting [Helm 3.5.2](https://github.com/helm/helm/releases/tag/v3.5.2), Helm is stricter about parsing semver strings. Therefore, to ensure that your chart is deployable via Helm 3.5.2, your chart must have a semver-compliant version. More information: * Supported Hooks: https://helm.sh/docs/topics/charts_hooks/ @@ -30,21 +30,21 @@ files on top of it. * Chart must have the following Rancher specific add-ons (More details on this below). * Rancher Labels & Annotations for Partners + * kubeVersion set in the chart's metadata * app-readme.md - * questions.yaml + * questions.yaml (Optional) ## Workflow ### 1. Fork the repository -After forking the repository, checkout the `main-source` branch and pull the latest changes. -Then create a new branch from it (e.g. `git checkout -b `) and execute +After forking the repository, checkout the `main-source` branch and pull the latest changes. +Then create a new branch off of `main-source` (e.g. `git checkout -b `) and execute `make` commands from next steps at the repository's root level. -### 2. Track a new upstream chart as a package (**SKIP if upgrading existing package**) +### 2. Set up your package to track an upstream chart (**SKIP if upgrading existing package**) -Create a package in the `packages` directory by following this structure (Replace `{CHART_NAME}` with -the name of the upstream chart). +Create a directory for your package in the `packages` directory and a `package.yaml` file inside (Replace `{CHART_NAME}` for your chart's name). ```text partner-charts # Repo root level @@ -53,21 +53,21 @@ partner-charts # Repo root level └── package.yaml # Metadata manifest containing upstream location version ``` -Track the upstream chart by setting these values in `package.yaml`: +Set up the following in your `package.yaml` to track your upstream chart: -- `url` - the URL that references you chart's tarball hosted in a Helm repository. +- `url` - the URL that references your chart's tarball hosted in a Helm repository. -- `packageVersion` - The version of the package. This is appended to your chart's version in the form `{CHART_NAME}-{VERSION}{packageVersion}.tgz` after repackaging. If omitted, the version contained in your chart will be used. +- `packageVersion` - The version of the package. This is appended to your upstream chart's version in the form `{CHART_NAME}-{VERSION}{packageVersion}.tgz` after a package is generated. If omitted, the version contained in your chart will be used. More information of what can be specified can be found in the [README.md](packages/README.md) within the `packages/` directory. #### Example `package.yaml` -This example is repackaged as `chart-v0.1.200.tgz` after modifications are applied. +This `package.yaml` will generate a `chart-v0.1.201.tgz` package. ```yaml url: https://example.com/helm-repo/chart-v0.1.2.tgz -packageVersion: 00 +packageVersion: 01 ``` ### 3. Prepare for changes @@ -82,14 +82,15 @@ make prepare ### 4. Make changes -Any modifications to your upstream chart like **adding the partner label** will be done in +Any modifications to your upstream chart like **adding the partner label** will be done in the auto-generated `charts` directory. -If this is a new chart, add the partner label and required annotations in `packages/{CHART_NAME}/charts/Chart.yaml`: +If this is a new chart, set the `kubeVersion` field and add the required annotations in `packages/{CHART_NAME}/charts/Chart.yaml`: ```yaml +kubeVersion: # A SemVer range of compatible Kubernetes versions. E.g 1.18 - 1.21, >= 1.19, etc annotations: - catalog.cattle.io/certified: partner + catalog.cattle.io/certified: partner # Enables the "partner" badge in the UI for easier identification catalog.cattle.io/release-name: chart-name-here # Your chart's name in kebab-case, this is used for deployment catalog.cattle.io/display-name: Fancy Chart Name Here # The chart's name you want displayed in the UI ``` @@ -99,15 +100,13 @@ You will also need to ensure that your chart has the following files in `package - `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.yaml` - Allows you to define a set of questions that user can provide answers to. -These questions will be displayed on the chart's installation page to make it easier for a user -to configure common use cases / set default values exposed by the chart's `values.yaml` so that -users can install the chart with little effort. +- `questions.yaml` - 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 ```yaml -questions: +questions: - variable: password default: "" required: true @@ -157,7 +156,7 @@ questions: | 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"`| -**subquestions**: `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. +**subquestions**: `subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. ### 5. Save your changes @@ -170,7 +169,7 @@ export PACKAGE={CHART_NAME} # Only need to run once make patch ``` -### 6. Update package to track new upstream (Maintenance) +### 6. Update package to track a new upstream (Maintenance) There are two ways you can update a package, one is to track a new updated upstream chart and the other is to do small modifications/fixes. @@ -180,21 +179,29 @@ and the other is to do small modifications/fixes. Update the `url` to reference the new upstream chart. If your chart uses `packageVersion`, reset it to `01` in `package.yaml`, in order for `PACKAGE={CHART_NAME} make prepare` to pull in the new upstream chart and apply the patch if one exists. You might need to run `PACKAGE={CHART_NAME} make patch` to ensure the patch can be applied on the new upstream. If applying the patch fails, there's currently no method for rebasing to a new upstream when the patch gets broken as a result. For example, an existing package tracking an upstream chart `url: https://example.com/helm-repo/chart-v0.1.2.tgz` -can be updated to track the new `url: https://example.com/helm-repo/chart-v0.1.3.tgz`, and a new package -`chart-v0.1.300.tgz` will be generated. +can be updated to track the new `url: https://example.com/helm-repo/chart-v0.1.3.tgz`, and a new package +`chart-v0.1.301.tgz` will be generated. ```yaml url: https://example.com/helm-repo/chart-v0.1.3.tgz -packageVersion: 00 +packageVersion: 01 ``` +Dependencies are not automatically updated when rebasing a chart, therefore the `url` of each dependency will +need to be manually updated as well. To update the dependencies go to your package's `generated-changes` directory and +update the `url` to reference the new dependency's upstream chart in `dependencies/{DEPENDENCY_CHART_NAME}/dependency.yaml`. + +Take for example, a chart `example-chart` with a postgresql 0.1.2 dependency that needs to be updated to 0.1.3. To update it +you would need to update the `url` in `example-chart/generated-changes/dependencies/postgresql/dependency.yaml` from +`https://example.com/helm-repo/postgresql-0.1.2.tgz` to `https://example.com/helm-repo/postgresql-0.1.3.tgz`. + #### Update existing package to introduce a small change If your chart uses `packageVersion`, increase the `packageVersion` in `package.yaml` without updating the `url`. This will create a new version of a package tracking the same upstream chart. For example, an existing package tracking an upstream chart `url: https://example.com/helm-repo/chart-v0.1.2.tgz` -generated a package `chart-v0.1.200.tgz`. Increasing the `packageVersion` without changing the `url` +generated a package `chart-v0.1.201.tgz`. Increasing the `packageVersion` without changing the `url` will generate a new package `chart-v0.1.201.tgz` based off of the same upstream chart. ### 7. Test your changes @@ -208,16 +215,16 @@ export PACKAGE={CHART_NAME} # Only need to run once make charts ``` -This will create the following two directories, and several files (e.g. `index.html`, `index.yaml`, etc.) +This will create the following two directories, and several files (e.g. `index.html`, `index.yaml`, etc.) to set up a Helm repo in your current branch. - `charts/{CHART_NAME}/{CHART_NAME}/{VERSION}` - Contains an unarchived version of your modified chart -- `assets/{CHART_NAME}/` - Contains an archived (tarball) version of your modified chart +- `assets/{CHART_NAME}/` - Contains an archived (tarball) version of your modified chart named `{CHART_NAME}-{VERSION}{packageVersion}.tgz` #### Test modified chart To test your changes, just push the generated files to your fork as a separate commit and add your -fork / branch as a Repository in the Dashboard UI. Your chart will then show up as an App in +fork / branch as a Repository in the Dashboard UI. Your chart will then show up as an App in `Apps & Marketplace` under the Repository that you configured.Make sure that you revert the generated files commit before submitting a PR! Alternatively, Python and Ngrok can be used if you rather avoid the push and revert commit approach. Use `python -m SimpleHTTPServer` to host the generated files locally, and expose them using Ngrok. Then add the Ngrok URL as a Repository in the Dashboard UI the same way you would add a fork / branch.