HIP: adding expose depoyed chart hip #421

mrlunchbox777 · 2025-11-13T21:50:49Z

Adding a HIP to expose the currently deployed chart at render time.

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

mrlunchbox777 · 2025-11-24T17:22:46Z

@scottrigby @gjenkins8 here is the hip we talked about at contribfest

danilo-patrucco · 2025-11-24T17:54:15Z

+1

mrlunchbox777 · 2025-12-16T22:33:32Z

Some notes that were brought up to improve the proposal were to:

Consider the various states that .Deployed chart could be in (failed/rollback/etc), what to collect/show (size/speed implications), and how to control/represent the various options
Add notes for the existing flux use case

mrlunchbox777 · 2025-12-16T22:52:29Z

Some notes that were brought up to improve the proposal were to:

Consider the various states that .Deployed chart could be in (failed/rollback/etc), what to collect/show (size/speed implications), and how to control/represent the various options

Add notes for the existing flux use case

Here is an example of getting flux CRs to control if an upgrade job runs. It was part of this MR. It was used for a default name change on immutable resources by deleting them in a hook.

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

scottrigby · 2026-01-08T19:24:49Z

hips/hip-0027.md

+
+## Rejected Ideas
+
+- **Full Release Object:** Security/performance concerns; chart metadata sufficient


my main thought is, would you not also want to expose the values of helm history to check things like whether a previous release was successful?

Some thoughts about this: What about adding "History" key to the existing .Release built-in: .Release.History when a --release-history-depth flag is passed?

This could be a filtered version of the Release object that's currently stored in helm release secrets by default.

Agree that the full release object could cause performance issues. perhaps this could be mitigated by:

any history might be best to opt-into with a flag (default history level 0 rather than 1 as currently proposed)

including only a filtered subset of the release object, omitting potentially very large data like templates, manifest etc.

Not yet sure what security concerns adding the Release object would add that other built-ins don't already have (eg, .Values, .Files, etc). But good to consider here.

Thank you for the thoughtful suggestions! .Release.History feels natural and being part of an existing path makes it that much easier to find and use. Pulling the wider set of data is certainly more useful, it may be worth considering letting the user control the filter and default most things to discarded by default. This keeps with the opt-in nature of this proposal. I agree defaulting to 0 is better for similar reasons.

One suggestion I have on top of this would be to ensure that the user's decisions are available to the templates at the same time. This enables a "negotiation" between the user and author, i.e. a chart author may need a depth of 2 to render a chart properly and error out if not given it, but it doesn't force the condition on the user, they must accept first. It could also enable helpful error messages, extend testing, and branching logic based on available history.

Example use case:

{{- if lt .Release.HistoryDepth 3 }} {{- fail "This chart requires --release-history-depth=3 for safe upgrades from v2.x" }} {{- end }}

Proposed field: .Release.HistoryDepth (aligns with flag name)

This would be a simple integer value (0, 1, 2, etc.) always available in template context, similar to how .Release.Revision is currently available.

What do you think of that addition? Should we determine what things should be filtered by default as part of this?

Again, really appreciate the review. I'll update the HIP to use .Release.History and associated changes.

Release.HistoryDepth is redundant here, and equivalent to:

{{- if lt (len .Release.History) 3 }}

will reply with this and the rest inline

hips/hip-0027.md

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

scottrigby

getting closer. just a few more questions and suggestions.

scottrigby · 2026-01-29T20:48:37Z

hips/hip-0027.md

+
+This HIP proposes exposing release history metadata during template rendering. Currently, Helm templates have access to `.Chart` for the chart being installed but no equivalent access to deployed release history. This forces chart authors to use complex workarounds like post-renderers, pre-upgrade hooks, or manual values conventions to implement version-aware upgrade logic.
+
+The proposal introduces `.Release.History` (array of historical releases) available in template contexts, populated during `helm upgrade` and `helm rollback` operations. The `--release-history-depth` flag controls how many historical releases to retrieve (default: 0), requiring explicit opt-in. The `.Release.HistoryDepth` field exposes the requested depth value to enable chart authors to require minimum depth for safe upgrades.


I'd remove .Release.HistoryDepth, as it's functionally equivalent to len .Release.History in gotemplate. Eg,

{{- if lt (len .Release.History) 3 }}

scottrigby · 2026-01-29T20:50:17Z

hips/hip-0027.md

+{{- end }}
+
+# Require minimum depth for safe upgrades
+{{- if lt .Release.HistoryDepth 3 }}


see above

Suggested change

{{- if lt .Release.HistoryDepth 3 }}

{{- if lt (len .Release.History) 3 }}

scottrigby · 2026-01-29T20:52:08Z

hips/hip-0027.md

+
+### Exposing Requested Depth
+
+`.Release.HistoryDepth` exposes the value of `--release-history-depth` to chart templates, enabling a "negotiation" between user and chart author. Chart authors can require a minimum depth for safe migrations and provide helpful error messages, but this doesn't force the condition—users must explicitly opt in with the appropriate flag.
+
+**Example:**
+
+```yaml
+{{- if lt .Release.HistoryDepth 3 }}
+  {{- fail "This chart requires --release-history-depth=3 for safe upgrades from v2.x" }}
+{{- end }}
+```
+
+This field is always available (similar to `.Release.Revision`) and contains the integer value passed to `--release-history-depth` (0 by default).
+


see above

Suggested change

### Exposing Requested Depth

`.Release.HistoryDepth` exposes the value of `--release-history-depth` to chart templates, enabling a "negotiation" between user and chart author. Chart authors can require a minimum depth for safe migrations and provide helpful error messages, but this doesn't force the condition—users must explicitly opt in with the appropriate flag.

**Example:**

```yaml

{{- if lt .Release.HistoryDepth 3 }}

{{- fail "This chart requires --release-history-depth=3 for safe upgrades from v2.x" }}

{{- end }}

```

This field is always available (similar to `.Release.Revision`) and contains the integer value passed to `--release-history-depth` (0 by default).

scottrigby · 2026-01-29T20:52:49Z

hips/hip-0027.md

+
+### Always Available as Template Object
+
+`.Release.History` (empty array or populated) and `.Release.HistoryDepth` (integer) are always present to ensure consistent template behavior, prevent undefined variable errors, and enable testing with `helm template`.


see above

Suggested change

`.Release.History` (empty array or populated) and `.Release.HistoryDepth` (integer) are always present to ensure consistent template behavior, prevent undefined variable errors, and enable testing with `helm template`.

`.Release.History` (empty array or populated) is always present to ensure consistent template behavior, prevent undefined variable errors, and enable testing with `helm template`.

scottrigby · 2026-01-29T20:53:36Z

hips/hip-0027.md

+
+**`.Release.HistoryDepth`**: Integer value indicating the requested depth via `--release-history-depth` flag. Always available, defaults to 0.
+


see above

Suggested change

**`.Release.HistoryDepth`**: Integer value indicating the requested depth via `--release-history-depth` flag. Always available, defaults to 0.

scottrigby · 2026-01-29T21:01:07Z

hips/hip-0027.md

+{{- end }}
+
+# Enforce minimum depth requirement
+{{- if and (gt (len .Release.History) 0) (lt .Release.HistoryDepth 2) }}


I was going to suggest a change here but I don't actually understand how this use case differs from the above cases.

scottrigby · 2026-01-29T21:01:26Z

hips/hip-0027.md

+
+A future pull request will:
+
+1. Extend template rendering context to include `.Release.History` and `.Release.HistoryDepth`


Suggested change

1. Extend template rendering context to include `.Release.History` and `.Release.HistoryDepth`

1. Extend template rendering context to include `.Release.History`

scottrigby · 2026-01-29T21:01:50Z

hips/hip-0027.md

+5. Set `.Release.HistoryDepth` to the flag value in all contexts
+6. Include comprehensive unit and integration tests covering depth behavior, filtering, and edge cases


Suggested change

5. Set `.Release.HistoryDepth` to the flag value in all contexts

6. Include comprehensive unit and integration tests covering depth behavior, filtering, and edge cases

5. Include comprehensive unit and integration tests covering depth behavior, filtering, and edge cases

scottrigby · 2026-01-29T21:14:17Z

hips/hip-0027.md

+
+**Excluded by default:**
+
+- Values (may contain secrets)


I don't understand excluding this one. Templates already have access to .Values. And helm templating can already access previous secrets if needed via lookup() (it would be very cumbersome, but already accessible in templating).

scottrigby · 2026-01-29T21:15:55Z

hips/hip-0027.md

+
+## Security Implications
+
+**Not Exposed:** Previous values (may contain secrets) or previous manifests (may contain sensitive data). Only filtered release metadata is exposed (chart metadata, release status, timestamps, revision numbers).


unclear why this would increase exposure. see note about existing .Values and lookup() func above.

pull-request-size bot added the size/L label Nov 13, 2025

mrlunchbox777 added 6 commits November 13, 2025 16:52

docs: WIP adding significant changes, creating restore point

d263887

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

docs: WIP significant modifications, creating restore point

8867321

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

docs: WIP an improvement, but inconsistent

f613f22

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

docs: changing the object to always be available

78d4fe8

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

docs: minor corrections and adding linting and mutability considerations

f88e9b9

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

docs: making the hip shorter and more consumable

4c65745

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

mrlunchbox777 force-pushed the docs-adding-expose-previous-chart-hip branch from ef34886 to 4c65745 Compare November 13, 2025 21:52

docs: updated hip from notes during helm dev meeting

b48d8f5

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

mrlunchbox777 force-pushed the docs-adding-expose-previous-chart-hip branch from d819dc7 to b48d8f5 Compare December 16, 2025 23:08

scottrigby reviewed Jan 8, 2026

View reviewed changes

hips/hip-0027.md Outdated Show resolved Hide resolved

mrlunchbox777 added 2 commits January 14, 2026 21:42

fix: fixed the hip number and responded to reviews

33f290d

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

docs: linted hip

3238d65

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

scottrigby changed the title ~~docs: adding expose depoyed chart hip~~ HIP: adding expose depoyed chart hip Jan 29, 2026

scottrigby requested changes Jan 29, 2026

View reviewed changes


		## Rejected Ideas

		- Full Release Object: Security/performance concerns; chart metadata sufficient


		This HIP proposes exposing release history metadata during template rendering. Currently, Helm templates have access to `.Chart` for the chart being installed but no equivalent access to deployed release history. This forces chart authors to use complex workarounds like post-renderers, pre-upgrade hooks, or manual values conventions to implement version-aware upgrade logic.

		The proposal introduces `.Release.History` (array of historical releases) available in template contexts, populated during `helm upgrade` and `helm rollback` operations. The `--release-history-depth` flag controls how many historical releases to retrieve (default: 0), requiring explicit opt-in. The `.Release.HistoryDepth` field exposes the requested depth value to enable chart authors to require minimum depth for safe upgrades.

	{{- if lt .Release.HistoryDepth 3 }}
	{{- if lt (len .Release.History) 3 }}


		### Always Available as Template Object

		`.Release.History` (empty array or populated) and `.Release.HistoryDepth` (integer) are always present to ensure consistent template behavior, prevent undefined variable errors, and enable testing with `helm template`.


		`.Release.HistoryDepth`: Integer value indicating the requested depth via `--release-history-depth` flag. Always available, defaults to 0.


		A future pull request will:

		1. Extend template rendering context to include `.Release.History` and `.Release.HistoryDepth`

		5. Set `.Release.HistoryDepth` to the flag value in all contexts
		6. Include comprehensive unit and integration tests covering depth behavior, filtering, and edge cases

	5. Set `.Release.HistoryDepth` to the flag value in all contexts
	6. Include comprehensive unit and integration tests covering depth behavior, filtering, and edge cases
	5. Include comprehensive unit and integration tests covering depth behavior, filtering, and edge cases


		## Security Implications

		Not Exposed: Previous values (may contain secrets) or previous manifests (may contain sensitive data). Only filtered release metadata is exposed (chart metadata, release status, timestamps, revision numbers).

HIP: adding expose depoyed chart hip #421

Are you sure you want to change the base?

HIP: adding expose depoyed chart hip #421

Uh oh!

Conversation

mrlunchbox777 commented Nov 13, 2025

Uh oh!

mrlunchbox777 commented Nov 24, 2025

Uh oh!

danilo-patrucco commented Nov 24, 2025

Uh oh!

mrlunchbox777 commented Dec 16, 2025

Uh oh!

mrlunchbox777 commented Dec 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrlunchbox777 Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

scottrigby left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mrlunchbox777 Jan 15, 2026 •

edited

Loading