Kubernetes/Upstream Helm charts policy

Problem Statement

The Kubernetes Special Interesting Group has identified the need to try and utilize upstream helm charts in order to avoid excessive divergence from upstream, avoid version locks and avoid waste of effort to redo what upstream has already achieved. Through discussion the following policy has been formulated.

Policy

On 2023-05-25, the Kubernetes Special Interest Group, after discussion regarding the re-use ofupstream helm charts, came up with the following policy. In the text below, terms MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, OPTIONAL, have the meaning defined in RFC2119.

If and only if the following requirements are met and on a case by case basis, we allow usage of an upstream helm chart

An evaluation MUST be done on the upstream helm chart by an (impromptu or planned) working group of at least 2 people. The first person SHOULD be the person asking for/proposing the usage of an upstream helm chart. The other person SHOULD be anyone generally agreed to have enough experience with helm chart writing. The 2 person rule is there to avoid self +2ing and merging. The 2 main people SHOULD NOT be members of the same team, so that they don't share incentives. Any other person MAY contribute to the evaluation, both at the request of one of the people mentioned above as well as out of their own initiative.

The evaluation and following decision MUST be documented on Wikitech, as a page under Helm/Upstream Charts, using Helm/Upstream Charts/Template as a template.

The list of things that need to be evaluated by the working group SHOULD contain, in no particular order

Overall quality of the chart.
If the above bullet point is failed, estimate the amount of work required to bring the upstream chart into the level of quality we strive for.
Estimate the amount of work it would take to rewrite from scratch internally, re-using all of our tooling.
Evaluation of the upstream charts authors receptiveness to changes to the chart, especially given the above bullet point. Authors SHOULD be receptive to pull/merge requests, offering some review at the very least.
Overall re-usability of the chart

The Kubernetes Special Interest Group, understands and acknowledges that:

This evaluation is effectively a judgement call by the 2+ people involved in the evaluation and that mistakes will be made in either direction.

An upstream chart can change over time. That means that charts that failed the evaluation in the past can pass in the future and charts that did pass the evaluation at some point may deteriorate and/or be abandoned over time.
Proceeding to the actions necessary (e.g. re-evaluation of an upstream Chart) to address situations resulting from the above SHOULD be done.
Helm chart writing is a new space, best practices are still being formulated and in some cases there might be push back and/or friction.
That while this is labeled a "policy", it is in effect, as of this writing (2023-06-28) a rough description of a playbook. Depending on this docs future, original naming might be wrong.

Best practices for adoption of upstream helm charts

In case of adopting an upstream helm chart and yet finding ourselves in the need to edit it, we should aim to upstream changes as much as possible. For patches that are lingering upstream or patches that are not suitable for upstream, here's a non exhaustive list of best practices to follow:

Commit the upstream source in one CR, then make changes in a second (to make reviews and rebasing easier)
Add the wmf/upstreamVersion annotation to the Chart.yaml pointing to the upstream version that was imported (makes rebasing easier as well):

annotations:
  # This chart is based on upstream version v1.10.1
  wmf/upstreamVersion: v1.10.1

Wherever possible, just add new template files rather than editing existing ones
If the above can't be followed and existing template need to be edited, editing existing templates, highlight them somehow (e.g. with comments)