Skip to content

Latest commit

 

History

History
121 lines (82 loc) · 5.06 KB

hip-9999.md

File metadata and controls

121 lines (82 loc) · 5.06 KB
Raw
hip title authors created type status
9999
Add `warn` template function
Philipp Stehle <philipp.stehle@sap.com>
2022-12-09
feature
draft

Abstract

When authoring charts it can be useful to warn users, when they deviate from best practices. E.g. when using a deprecated value or using the latest tag for images.

There are already means to do this in Helm, for example by using the NOTES.txt feature, but they all come with drawbacks. Also, as long as there is no standard way to produce warnings, it is hard to build tools around this.

This HIP proposes the addition of a warn template function, that Chart authors can use to signal warnings to Helm. It also includes several proposals of how Helm could make this available to the Chart consumers.

Motivation

Some reasons why chart authors might want to produce warnings:

  • They have deprecated functionality, which they plan to remove later. E.g. we have recently renamed our timeout value to timeoutSeconds. Until the next major release we, will fallback to timeout if timeoutSeconds is not present. To ensure a smooth transition to the next major release, it would be helpful if we could warn our users ahead of time.
  • For backward compatibility, they allow that continue to allow setting they know are sub-optimal.
  • To ease non-productive (dev) setups, some settings that should not be used for productive environment might be allowed anyway, but produce a warning. E.g. using a replica count of 1, which of course can't be used, if high availability is a concern.

Some ways how users could want to consume warnings:

  • Via cli output
  • In automated PR validation (validation fails, if the PR introduces a new warning)

Specification

Creating Warnings

Add a new template function called warn, with one of the following semantics (looking for feedback, which one we should go for):

  1. warn takes a single string argument, describing the Warning.
  2. warn takes a two arguments: a category (depreaction, security, misc, etc.) and a description: The categories would be pre-defined by Helm
  3. warn takes 1 or more arguments and interprets the first argument as a printf style string.
  4. warn takes 2 or more arguments, combining alternative 2 and 3.

Consuming Warnings

There can be multiple ways to consume warnings for users, the most straight forward would be printing them to the console.

Other ways could be:

  • add a --fail-on-warning flag to template, install, upgrade and lint (causing helm to exit with non-zero on warnings)
  • add a --warning-output flag that would produce a machine readable (e.g. yaml or json) collection of warning on the filesystem for further processing.
  • Expose the warnings to SDK users as Go-structs

De-duplication: Helm could detect the same warning occuring multiple times and de-duplicate them, e.g. the following template:

{{ warn "my warning" }}
{{ warn "my warning" }}

Would produce the following output:

[WARNING]: my warning (occurred 2 times)

Also, in the long term we should consolidate all other sources of warnings, e.g.:

and provide them through a common interface (i.e. in machine readable form).

Backwards compatibility

Following HIP-0004

  • exported Go APIs will remain compatible: This might be of concern, we just need to keep it in mind while implementing. Should be possible to do this non-breaking.
  • CLI commands and flags: No existing flags will be changed.
  • CLI output: Will not change, unless the warn feature is used by a chart author and therefore actively opting into the feature.
  • File formats: No change required.
  • Charts: No change required.
  • Templates (commands, functions, syntax, and variables): Only adding new functionality

Security implications

As this allows for automatic scanning for (security) warnings, a malicious actor might be enabled to automatically scan for Helm Charts with flaws, putting users at risk. On the other hand, it also enables to users to do the same and therefore might even increase security.

How to teach this

For chart authors: Document the warn funcion with example use-cases. For chart consumers: Document how to consume warnings.

Reference implementation

PoC PR to helm/helm

Rejected ideas

  • Use NOTES.txt to produce warnings. This has several drawbacks:
    • Harder to consume for users, as there is no standardized way to transport warnings.
    • Harder to consume in automation (a CI job).
    • Notes of sub-chart are not rendered (at least not by default).
  • Call the template function warning: There is already the fail function, so warn seems to be more consistent.

Open issues

Let me know

References

A collection of URLs or materials used as references through the HIP.