Denise
GitHub
commit
324b99b2cf
99
README.md
99
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 <name-of-new-branch>`) 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 <name-of-new-branch>`) 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,22 +53,20 @@ 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 upstream 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 used along with your upstream chart's name and version to generate a filename with the format `{CHART_NAME}-{VERSION}{packageVersion}+up{VERSION}.tgz` for the package's tarball that gets generated.
|
||||
|
||||
More information of what can be specified can be found in the [README.md](packages/README.md) within the `packages/` directory.
|
||||
For example, an upstream chart `chart-0.1.2.tgz` and the `package.yaml` from below would generate a package with the name `chart-0.1.201+up0.1.2`.
|
||||
|
||||
#### Example `package.yaml`
|
||||
```yaml
|
||||
url: https://example.com/helm-repo/chart-0.1.2.tgz
|
||||
packageVersion: 01
|
||||
```
|
||||
|
||||
This example is repackaged as `chart-v0.1.200.tgz` after modifications are applied.
|
||||
|
||||
```yaml
|
||||
url: https://example.com/helm-repo/chart-v0.1.2.tgz
|
||||
packageVersion: 00
|
||||
```
|
||||
More information of what can be specified can be found in [packages/README.md](packages/README.md).
|
||||
|
||||
### 3. Prepare for changes
|
||||
|
||||
|
|
@ -82,14 +80,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 +98,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 +154,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 +167,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.
|
||||
|
|
@ -179,23 +176,31 @@ 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.
|
||||
For example, an existing package tracking an upstream chart `url: https://example.com/helm-repo/chart-0.1.2.tgz`
|
||||
can be updated to track the new `url: https://example.com/helm-repo/chart-0.1.3.tgz`, and a new package
|
||||
`chart-0.1.301+up0.1.3.tgz` will be generated.
|
||||
|
||||
```yaml
|
||||
url: https://example.com/helm-repo/chart-v0.1.3.tgz
|
||||
packageVersion: 00
|
||||
url: https://example.com/helm-repo/chart-0.1.3.tgz
|
||||
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`
|
||||
will generate a new package `chart-v0.1.201.tgz` based off of the same upstream chart.
|
||||
For example, an existing package tracking an upstream chart `url: https://example.com/helm-repo/chart-0.1.2.tgz`
|
||||
generated a package `chart-0.1.201+up0.1.2.tgz`. Increasing the `packageVersion` without changing the `url`
|
||||
will generate a new package `chart-0.1.202+up0.1.2.tgz` based off of the same upstream chart.
|
||||
|
||||
### 7. Test your changes
|
||||
|
||||
|
|
@ -208,16 +213,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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue