Skip to content

Latest commit

 

History

History
559 lines (415 loc) · 24.3 KB

README.md

File metadata and controls

559 lines (415 loc) · 24.3 KB

OpenShift Helm Charts Repository

OpenShift Helm Charts Repository is the canonical source of all the certified Helm charts from partners. Once your chart is ready for submission, you can submit a pull request. The pull request can include the chart and/or a report generated by the chart-verifier tool. Based on the content, the chart will be certified, and the chart-verifier will be run if a report is not provided.

After merging your pull request, the CI/CD pipeline will publish the chart in the GitHub releases and add it to the Helm charts repository index. If you are submitting the report without a chart, the report must contain a URL pointing to the downloadable location of the chart. In this case, the Helm charts repository index will include the download URL and other chart metadata available in the report. If you want the chart published through GitHub but do not want the CI/CD pipeline running chart-verifier against your chart, you can submit a chart and the report together.

Table of Contents:

Submitting Chart Related Changes

In a nutshell, these are the actions that are performed when you submit a chart. The pull request is checked for non-chart-related changes and fails the job if found. A check confirms the chart is added to a correct directory path. If a report is provided, confirm the report has not been modified after generation, all mandatory checks are present and have passed. If a chart is provided, check the digest in the report to match the digest calculated for the submitted chart. If a report is not provided, run the chart-verifier and confirm all mandatory checks pass.

Additionally, for signed charts, if a pgp public key is included in the OWNERS file a check will be made to ensure the key can be used to verify the chart.

You can submit chart related changes in three methods:

  1. Submit a chart without Chart Verification Report

    • Chart as a tarball
      • For signed chart also include the providence file.
    • Chart in a directory

  2. Submit a Chart Verification Report without the Chart

  3. Submit a Chart Verification Report with the Chart

The following sections explains about the process for submission.

Preparation

To submit a pull request, you need to fork the Git repository and clone it to your local system. If you had followed the partner connect documentation, you should see an OWNERS file under your chart directory within your organization directory.

You should see the OWNERS file at:

charts/partners/acme/awesome/OWNERS

For example, if the organization name is acme and the chart name is awesome. The content of the OWNERS file is going to be something like this:

chart:
  name: awesome
  shortDescription: A Helm chart for Awesomeness
publicPgpKey: null
providerDelivery: False
users:
  - githubUsername: <username-one>
  - githubUsername: <username-two>
vendor:
  label: acme
  name: ACME Inc.

The name of the chart that you are submitting must match the value in the OWNERS file. The following section explains how to submit a chart source. And the section followed describes how to submit a chart verification report—finally submitting a chart and the report together.

Before submitting chart source or chart verification report, create a directory with the version number as the name. For example, if you are publishing the 0.1.0 version of the awesome chart, create a directory like this:

charts/partners/acme/awesome/0.1.0/

For Community charts only (partners should follow process above), submit the OWNERS file PR towards main branch under your charts/community directory within your orgranization directory. This PR should be sent prior to sending any charts to the repo. For example, for a community chart named awesome for an organization named acme, send it here:

charts/community/acme/awesome/OWNERS

Alternatively, for charts that represent a product supported by Red Hat, submit the OWNERS file PR towards main branch under the charts/redhat directory within your orgranization directory. For example, for a Red Hat chart named awesome, send it here:

charts/redhat/redhat/awesome/OWNERS

Notice that in this case your organization will also be redhat.

Submitting a Chart without Chart Verification Report

The chart could be a tarball created using the helm package command or a directory with the chart source. If it is a tarball, it is placed directly under the 0.1.0 directory, further if the chart is signed, the providence file is added to the same directory.

charts/partners/acme/awesome/0.1.0/awesome-0.1.0.tgz
charts/partners/acme/awesome/0.1.0/awesome-0.1.0.tgz.prov

For a signed chart the OWNERS file can include a base64 encoded public key for the chart. If this is present the key will be decoded and specified when the chart-verifier is used to create a report for the chart. If the public key does not match the chart the verifier report will include a check failure and, the PR will end with an error. If the public key does match the chart, and there are no other failures, a release will be created which will include the tarball, the providence file, the public key file, and the generated report.

awesome-0.1.0.tgz
awesome-0.1.0.tgz.prov
awesome-0.1.0.tgz.key
report.yaml

If the OWNERS file does not include the public key the chart verifier check is skipped and will not affect the pull request outcome. Further the public key file will not be included in the release.

If the chart is a directory with the chart source, create an src directory to place the chart source.

Here is an example path:

charts/partners/acme/awesome/0.1.0/src/

The file structure looks like this:

.
└── src
    ├── Chart.yaml
    ├── README.md
    ├── templates
    │   ├── deployment.yaml
    │   ├── _helpers.tpl
    │   ├── hpa.yaml
    │   ├── ingress.yaml
    │   ├── NOTES.txt
    │   ├── serviceaccount.yaml
    │   ├── service.yaml
    │   └── tests
    │       └── test-connection.yaml
    ├── values.schema.json
    └── values.yaml

Submitting a Chart Verification Report without the Chart

Generate the report and save it under 0.1.0 with a given file name as report.yaml.

Signed Report

When you follow the partner connect documentation, you could see details about adding a PGP public key. Adding PGP public key is optional. But if you have added that, you should see your public key in the OWNERS file under your chart directory within your organization directory. The PGP public key is available in the publicPgpKey attribute. The value of that attribute must be conforming to ASCII armor format.

When submitting a chart verification report without the chart, you can sign your report and save the signature in ASCII armor format.

gpg --sign --armor --detach-sign --output report.yaml.asc report.yaml

There will be [WARNING] message in the console if the signature verification fails.

Report for a Signed chart

For a signed chart, if a pgp public key was provided to the chart verifier when generating the report, a digest of the key is included in the report. If a base64 encoded pgp public key is then included in the OWNERS file a check is made to confirm the digest of the decoded key in the OWNERS file matches the key digest in the report, and if the match fails the PR will fail. However, if the key digests match, and there are no other errors when processing the PR, a release is generated containing the public key and the report:

awesome-0.1.0.tgz.key
report.yaml

Note: A release is not generated if provider control delivery is enabled.

Submitting a Chart Verification Report with the Chart

You can also submit a chart and the report together. As mentioned in the "Submitting a Chart without Chart Verification Report" section, place the source or tarball under the version numbered directory. Similarly, as mentioned in the "Submitting a Chart Verification Report without the Chart" section, place report.yaml also under the save under the version numbered directory.

Signed Report

As mentioned in the previous section, optionally, you can sign the report. There will be [WARNING] message in the console if the signature verification fails.

Signed Chart

For a signed chart the submission must include a tarball and a providence file in addition to the report file. In this case, for checking purpose the PR is treated similarly to a report only submission.

Post Submission Manual Review

After submitting the pull request, it will take a few minutes to run all the checks and merge the PR automatically. These are the manual review steps you can perform after creating the pull request.

  1. Watch the newly opened pull request for any messages.
  2. If there is a message with errors, you can go to the next section, Troubleshooting Pull Request Failures, to get more details. Once you identify the problem, you can update the pull request with the necessary changes.
  3. If there is a success message that indicates the chart repository index has been updated successfully. You can verify it by checking the latest commit in the gh-pages branch. The commit message will be in this format: <partner-label>-<chart-name>-<version-number> index.yaml (#<PR-number>) (e.g, acme-psql-service-0.1.1 index.yaml (#7)). Your chart-related changes must be reflected in the index.yaml file.
  4. If you have submitted a chart source, a GitHub release with the chart and corresponding report will be made available in the GitHub releases page. The release tag will be in this format: <partner-label>-<chart-name>-<version-number> (e.g., acme-psql-service-0.1.1).
  5. The chart must be available through the official repository URL: https://charts.openshift.io . You can follow the instruction given there to install it in your OpenShift cluster.

Troubleshooting Pull Request Failures

After submitting the pull request, you can keep the pull request page open to observe the results. If there is no issue with the pull request, it is going go be merged automatically.

If there is an issue, a comment with details will appear in the pull request. At the bottom of the page, you will also see a box with a heading like this: "Some checks were not successful" or "All checks have failed". And below that, checks are marked with the "required" label to merge the PR automatically:

CI / Chart Certification (pull_request_target) Details

The first part of Chart Certification (PR Content Check) fails if the pull request contains changes not related to any chart. This check performs using the script already part of the upstream repository. That way, it will ensure the pull request author is not modifying the verification scripts themselves. PR Content check also ensures the chart version submitted is not already released and if provider control delivery settings are consistant. The job will fail if any of the checks fail.

The second part of Chart Certification (Verify PR) performs all the necessary checks to merge the pull request. The following sections explain various errors produced by the Verify PR.

The third part of Chart Certification makes the chart release and update index.yaml in the repository.

Error when submitting files not part of any chart

If you try to submit changes that are not related to any particular chart, you will receive an error like this:

[ERROR] One or more files included in the pull request are not part of the chart

Please ensure you are making changes inside the chart version directory. For example, if you are partner the location is going to be here:

charts/partners/<organization-name>/<chart-name>/<version-number>

Here is an example directory:

charts/partners/acme/awesome/0.1.0

In the above example, the name of the partner is acme, the chart name is awesome, and version number is 0.1.0.

Missing OWNERS file in the chart directory

The OWNERS file is created through the Red Hat partner connect program and is a prerequisite for submitting a chart. If it does not exist for a submitted chart you will see an error:

[ERROR] .../OWNERS file does not exist.

You can follow the partner connect documentation to create the OWNERS file.

Pull request author is not part of OWNERS file

Every chart directory has an OWNERS file. The process to create that file is explained in the chart submissoion preparation section. Before submitting the pull request, you need to ensure your GitHub username is part of that file. If that is not the case, you will get an error like this.

[ERROR] {usernmae} is not allowed to submit the chart on behalf of {organization}

You can follow the partner connect documentation to update the OWNERS file.

Vendor label mismatch with the directory structure

The directory structure and the value of vendor label in the OWNERS file must match. Otherwise you will see an error like this:

[ERROR] vendor/label in OWNERS file ({vendor_label}) doesn't match the directory structure (charts/{category}/{organization}/{chart})

If the vendor label in the OWNERS file is wrong, you can follow the partner connect documentation to update the OWNERS file.

If the directory structure (organization name) is wrong, please reach out to Partner Acceleration Desk.

Chart name mismatch with the directory structure

The directory structure and the value of chart name in the OWNERS file must match. Otherwise you will see an error like this:

[ERROR] chart/name in OWNERS file ({chart_name}) doesn't match the directory structure (charts/{category}/{organization}/{chart})

If the chart name in the OWNERS file is wrong, you can follow the partner connect documentation to update the OWNERS file.

If the directory structure (chart name) is wrong, please reach out to Partner Acceleration Desk.

Error when submitting both chart source and tarball

When submitting a chart, it should be either a tarball or the chart source dirctory. Otherwise, you will see an error like this:

[ERROR] Both chart source directory and tarball should not exist

As a fix, you can either remove the tarball or the chart source directory.

Error when submitting files not related to any chart

Earlier there was an error when submitting files not part of any chart. But that check was checking files outside the chart version directory. If you make a change within chart directory but not making any chart related changes, you will see and error like this:

[ERROR] One of these must be modifed: report, chart source, or tarball

Please ensure the file names are as described in the documentation above.

Error when digest in the report is not matching with the chart digest

You will see an error like this when digest in the report is not matching with the chart digest:

[ERROR] Digest is not matching: {submitted_digest}, {generated_digest}

Please ensure you have not modified the chart after generating report. If you see the above error, run the chart-verifier once again and update your pull request.

Error with the chart URL when submitting report

When you submit a chart verification report without the chart, the report must have a valid URL.

These are the possible errors when there is an issue with the URL:

Invalid schema: {chart_url}
Invalid URL: {chart_url}
Missing schema in URL: {chart_url}

Please ensure the report is generated by running the chart-verifier against the URL.

Chart name and version mismatch errors

The chart name and version number in the report.yaml, Chart.yaml, directory path names should be consistent. Otherwise you will see these kind of error messages:

[ERROR] Chart name ({submitted_report_chart_name}) doesn't match the directory structure (charts/{category}/{organization}/{chart}/{version})
[ERROR] Chart version ({submitted_report_chart_version}) doesn't match the directory structure (charts/{category}/{organization}/{chart}/{version})
[ERROR] Chart name in the chart is not matching against the value in the report: {submitted_report_chart_name} vs {report_chart_name}
[ERROR] Chart version in the chart is not matching against the value in the report: {submitted_report_chart_version} vs. {report_chart_version}
[ERROR] Chart name ({report_chart_name}) doesn't match the directory structure (charts/{category}/{organization}/{chart}/{version})
[ERROR] Chart version ({report_chart_version}) doesn't match the directory structure (charts/{category}/{organization}/{chart}/{version})
[ERROR] Chart Version '{report_version}' doesn't match the version in the directory path: '{version}'

Report failures

If you see an errors like this, please ensure you are using the latest version of chart-verifier tool.

[ERROR] YAML error: ...
[ERROR] Unexpected error: ...
[ERROR] Error analysing the report: ...
[ERROR] Missing annotation in chart/report: {annotation}

If the error is still persisting after upgrading to latest chart-verifier, please contact Partner Acceleration Desk.

If the report has some failure, it will be displayed like this:

[ERROR] Report has failed.
Number of checks passed:
Number of checks failed:
Error message: ..

To fix the above failure, you need to modify the chart as per the failure messages.

Signed chart failures

Signed chart failures can occur when a base64 encoded pgp public key is included in the OWNERS file.

If the pull request includes a chart verifier report you may see a failure for example:

PGP key in OWNERS file does not match with key digest in report.

This can be caused by:

  • the PGP key in the OWNERS file is not base64 encoded.
  • the PGP key in the OWNERS file does not match to the PGP public key specified to the chart verifier when the report was generated.

If the pull request includes a chart tarball and providence file, but no chart verifier report, you may see a failure for example:

[ERROR] Chart verifier report includes failures:

Number of checks passed: 12
Number of checks failed: 1
Error message(s):
Chart is signed : Signature verification failed : openpgp: signature made by unknown entity

This is because the key generated from the PGP key in the OWNERS file does not correspond to the secret key used to sign the chart.

Web catalog only delivery

Whenever there is a mismatch between provider delivery in the OWNERS file and the report, the following errors will show:

[ERROR] Report indicates web catalog only but the distribution method set for the chart is not web catalog only.
[ERROR] The web catalog distribution method is set for the chart but is not set in the report.
[ERROR] The web catalog distribution method requires the pull request to be report only.

The distribution method of web catalog only requires providerDelivery to be set to true within the OWNERS file.

There are three methods of distribution for certified helm charts.

  • Publish your chart in the Red Hat Helm Chart repository
    • Submissions should include either a chart or chart and report.
  • Publish you chart in your own Helm Chart repository
    • Submissions should be report only using a publicly available chart URL.
  • Web catalog only
    • This submission should be report only using a private chart URL.

For more information on the different Helm Chart Distribution methods, see: Creating a Helm Chart Certification Project

Frequently Asked Questions

Can I test the pull request in my fork before submitting?

Yes, you can do it. See Pull Reqest: Testing in a Fork for more information

Can I use any command-line interface to create pull request?

Yes, you can use the GitHub CLI to create pull request.

How to update OWNERS file?

Partners can refer to the partner documentation for Submitting your Helm chart for certification.

For Red Hat and Community charts, submit a PR towards main branch with an OWNERS file under your chart directory within your orgranization directory.

Support

You can use the issue tracker in this repository to report bugs. If you are a partner, please refer to the Partner Acceleration Desk documentation.

^Top