HIP: adding expose depoyed chart hip by mrlunchbox777 · Pull Request #421 · helm/community

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

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

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.

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

agreed, removed and referenced .Release.History and .Release.Revision checks instead. Also, when reviewing the hip and your comments, I think adding max makes sense because that's the terminology history uses.

hips/hip-0027.md

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 }}

see #421 (comment)

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 }}

see #421 (comment)

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).

see #421 (comment)

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`.

see #421 (comment)

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.

see #421 (comment)

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.

the logic is bad here, the intent was to be able to require a depth if a depth is available, but that achievable with what you already recommended, see #421 (comment)

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`

see #421 (comment)

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

see #421 (comment)

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).

I was being overly conservative. I think a better approach is to keep values out by default, for both attack surface and performance reasons, but still enable it's use/requirement from users/chart maintainers.

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.

see #421 (comment)

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

mrlunchbox777 · 2026-02-13T15:44:16Z

I accidentally messed up the history on my branch, so I ended up squashing it all into one commit to fix

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

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

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

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

mrlunchbox777 force-pushed the docs-adding-expose-previous-chart-hip branch 3 times, most recently from 8527341 to f1cfad4 Compare February 13, 2026 06:50

pull-request-size bot added size/XL and removed size/L labels Feb 13, 2026

docs: adding HIP-28 to expose release history during template rendering

cd01bdc

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

mrlunchbox777 force-pushed the docs-adding-expose-previous-chart-hip branch from f1cfad4 to cd01bdc Compare February 13, 2026 15:42

pull-request-size bot added size/L and removed size/XL labels Feb 13, 2026


		## 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).

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!

mrlunchbox777 Feb 13, 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!

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!

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!

mrlunchbox777 commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mrlunchbox777 Jan 15, 2026 •

edited

Loading

mrlunchbox777 Feb 13, 2026 •

edited

Loading